Helm وتغليف Kubernetes

تشريح الـ Chart

18 دقيقة الدرس 3 من 28

تشريح الـ Chart

كل Helm chart عبارة عن مجلد يتبع هيكلًا محددًا وثابتًا. تعلّم هذا الهيكل مرة واحدة وستستطيع قراءة أي chart وتشخيصه وكتابته من الصفر — سواء كان chart Redis الرسمي من Bitnami، أو chart داخلي في شركتك، أو chart تكتبه أنت بنفسك. هذا الدرس يستعرض كل ملف ومجلد بالتفصيل، يشرح سبب وجوده، ويعرض الأنماط الإنتاجية التي تميز charts قابلة للصيانة عن أخرى هشة.

شجرة المجلدات القياسية

تشغيل الأمر helm create myapp ينشئ هذا الهيكل تلقائيًا. ليس اعتباطيًا — فمحرك القوالب في Helm ومحلل التبعيات وأوامر الحزم تتوقع جميعها هذا الهيكل بالضبط.

myapp/
├── Chart.yaml            # بيانات Chart الوصفية (إلزامي)
├── values.yaml           # قيم الضبط الافتراضية (إلزامي)
├── values.schema.json    # مخطط JSON للتحقق من القيم (اختياري، موصى به بشدة)
├── charts/               # sub-charts المعتمد عليها (.tgz)
├── crds/                 # تعريفات الموارد المخصصة CRD (تُثبَّت قبل القوالب)
├── templates/            # قوالب مانيفيست Kubernetes (إلزامي)
│   ├── NOTES.txt         # تعليمات الاستخدام تُطبع بعد التثبيت
│   ├── _helpers.tpl      # قوالب مسماة ودوال مساعدة (لا تُعرض كمانيفيست)
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── serviceaccount.yaml
│   ├── hpa.yaml
│   └── tests/
│       └── test-connection.yaml   # Pod اختباري (helm test <release>)
└── .helmignore           # ملفات مستثناة من الحزمة .tgz

هيكل مجلدات Helm chart — لكل ملف دور محدد في عقد التحزيم.

Chart.yaml — وثيقة الهوية

ملف Chart.yaml إلزامي. يقرأه Helm قبل أي شيء آخر. مثال إنتاجي:

# Chart.yaml
apiVersion: v2                   # v2 = Helm 3 (لا تستخدم v1 في المشاريع الجديدة)
name: myapp
description: A production-ready web application chart
type: application                # "application" قابل للنشر / "library" قوالب فقط
version: 1.4.2                   # إصدار الـ CHART (SemVer) — يتغير عند تعديل المنطق
appVersion: "2.7.0"              # إصدار التطبيق — للتوضيح فقط، Helm لا يستخدمه

maintainers:
  - name: Platform Engineering
    email: platform@acme.com
dependencies:
  - name: postgresql
    version: "15.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled

version مقابل appVersion: هذان الحقلان يُربكان معظم المهندسين في البداية. version هو إصدار الـ chart — يتغير عند إصلاح خطأ في قالب أو إضافة ميزة Helm. appVersion هو إصدار التطبيق — معلوماتي فقط؛ لا يستخدمه Helm لسحب الصور. يقرأ deployment.yaml تاغ الصورة من values.yaml وليس من appVersion.

values.yaml — المصدر الوحيد للحقيقة في الضبط

يُعرّف values.yaml الضبط الافتراضي الذي تستطيع كل قالب في templates/ الرجوع إليه. إنه الواجهة البرمجية العامة للـ chart. كل من يُثبّت الـ chart سيتجاوز أجزاء من هذا الملف عبر --set أو ملف values.yaml خاص به. صمّمه بعناية — تغيير أسماء المفاتيح تغيير جذري للمستخدمين.

# values.yaml — مثال إنتاجي
replicaCount: 3

image:
  repository: gcr.io/acme/myapp
  tag: ""          # فارغ عمدًا — يُعيّنه CI عبر --set image.tag=$SHA
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp
    existingSecret: "myapp-db-secret"

أفضل الممارسات الإنتاجية — لا تضع الأسرار في values.yaml. استخدم نمط existingSecret (كما هو موضح) أو External Secrets Operator أو Vault Agent. ملف values.yaml يُحفظ في git وكثيرًا ما يظهر في سجلات CI. الاعتمادات فيه ستُسرَّب حتمًا.

مجلد templates/ — مكان ولادة المانيفيست

كل ملف .yaml في templates/ تعالجه محرك قوالب Go في Helm ويُحوَّل إلى مانيفيست Kubernetes عادي. الملفات التي تبدأ بـ _ (مثل _helpers.tpl) لا تُعرض كمانيفيست أبدًا — وجودها فقط لتعريف قوالب مسماة قابلة لإعادة الاستخدام.

الكائنات الرئيسية التي تعمل معها داخل القالب:

.Values — كل شيء من values.yaml مدمجًا مع أي تجاوزات --set
.Release — بيانات الإصدار الحالي: .Release.Name, .Release.Namespace, .Release.IsInstall
.Chart — حقول Chart.yaml: .Chart.Name, .Chart.Version, .Chart.AppVersion
.Capabilities — معلومات الكلستر: .Capabilities.KubeVersion.Major
.Files — الوصول لملفات مضمّنة في الـ chart (مثل ملفات الضبط)

_helpers.tpl — المكتبة القياسية للـ Chart

في _helpers.tpl تُعرّف القوالب المسماة (الماكرو) التي تستدعيها قوالب المانيفيست. كل chart ينشئه helm create يأتي بمجموعة قياسية من هذه المساعدات:

{{/*
_helpers.tpl — المساعدات القياسية
*/}}

{{/* اسم الـ chart مقطوعًا إلى 63 حرفًا — حد تسمية K8s */}}
{{- define "myapp.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/* الاسم الكامل: Release.Name + اسم الـ chart */}}
{{- define "myapp.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{/* تسميات الـ selector — يجب أن تكون ثابتة عبر الترقيات */}}
{{- define "myapp.selectorLabels" -}}
app.kubernetes.io/name: {{ include "myapp.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{/* التسميات الكاملة — تشمل إصدار الـ chart */}}
{{- define "myapp.labels" -}}
helm.sh/chart: {{ include "myapp.chart" . }}
{{ include "myapp.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

فخ إنتاجي — تسميات selector غير ثابتة. الحقل spec.selector في Deployment غير قابل للتعديل بعد الإنشاء. إذا أضفت إصدار الـ chart أو تاغ الصورة في تسميات الـ selector ثم حاولت الترقية، سيرفض Kubernetes التحديث بخطأ field is immutable. المساعد selectorLabels يتضمن فقط app.kubernetes.io/name وapp.kubernetes.io/instance — قيم لا تتغير أبدًا عبر الإصدارات.

استخدام المساعدات في القوالب الفعلية

ملف deployment.yaml الحقيقي يستدعي هذه المساعدات بـ include مع تمرير سياق الجذر .:

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "myapp.fullname" . }}
  labels:
    {{- include "myapp.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "myapp.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "myapp.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

nindent مقابل indent: nindent N يضيف سطرًا جديدًا قبل المسافة البادئة — ضروري عند توصيل كتلة متعددة الأسطر بمفتاح YAML. بدونه يقع السطر الأول على نفس سطر المفتاح ويكسر تحليل YAML. هذا أكثر أخطاء التنسيق شيوعًا في قوالب المبتدئين.

values.schema.json — التحقق عند التثبيت

مع نمو الـ chart، سيقع المستخدمون في أخطاء كتابة — مثل وضع replicas بدلًا من replicaCount، أو تمرير نص مكان رقم. أضف ملف JSON Schema وسيتحقق Helm من كل helm install أو helm upgrade قبل لمس الكلستر. على نطاق big-tech هذا يمنع فئة كاملة من حوادث سوء الضبط.

مع هذا المخطط، helm install myapp . --set replicaCount=abc يفشل فورًا برسالة خطأ واضحة، بدلًا من نشر Deployment معطوب يرفضه Kubernetes بصمت بعد دقائق.

الصورة الكاملة

عند تشغيل helm install myrelease ./myapp -f prod-values.yaml، ينفذ Helm هذا التسلسل: تحميل Chart.yaml (الهوية + قائمة التبعيات) ← حل sub-charts في charts/ ← دمج values.yaml مع ملف التجاوز ← التحقق عبر values.schema.json ← عرض كل templates/*.yaml عبر محرك قوالب Go ← تطبيق CRDs من crds/ أولًا ← ثم تطبيق جميع المانيفيست المُعرضة على الكلستر بترتيب التبعية. فهم هذا التسلسل هو الفارق بين التخمين عند فشل chart والمعرفة الدقيقة بمكان البحث.