Helm / أساسي: أسس الحزمة والتصيير / الدرس 4

التعبيرات والسلاسل وحدود YAML

ركب تعبيرات قوالب صغيرة مع حفظ نوع حقل YAML المستقبِل وفهم أن Helm يصيّر نصا قبل قراءة Kubernetes للكائنات.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى 2026-10-28

في هذه الصفحة

أهداف الدرس

قراءة استدعاءات الدوال وترتيب الوسيط في السلسلة.
اقتباس المخرج النصي مع إبقاء الأعداد المطلوبة رقمية.
شرح مساعدات الإزاحة وحدود المخرج حسب السياق.

عامل التصيير كإنتاج نص

لا يبني قالب Helm كائن Kubernetes ذي أنواع مباشرة، بل ينتج نصا يجب أن يُحلل لاحقا بوصفه YAML ويطابق مخطط API الهدف. لذلك قد يظهر تعبير صحيح داخل manifest غير صالح. قد تغير النقطتان أو السطر الجديد أو القيمة غير المقتبسة طريقة قراءة الناتج. اجعل التعبيرات صغيرة ليتمكن المراجع من توقع النص المحيط بها. ضع قيود المدخلات المعقدة في مخطط القيم وواجهات موثقة بدلا من إخفاء تطبيق صغير داخل قالب، واقرأ الوثيقة الناتجة بعناية المصدر نفسها.

اقرأ الوسيط الأخير في السلسلة

يبدأ استدعاء الدالة باسمها ثم وسائطها. ترسل السلسلة نتيجة الخطوة السابقة كوسيط أخير للدالة التالية. وهكذا تتحول القيمة المارة عبر upper ثم quote أولا ثم تُمثل كنص مقتبس. هذه ليست أنبوبا للصدفة ولا تنفذ أمرا. يفترض المقطع الأول أن .Values.region هو النص west، فيكون الناتج المتوقع "WEST". قد يغير ترتيب الدوال معنى الناتج، لذا اشرح كل تحويل حسب ترتيب تقييمه.

gotemplate حقلان بعقدي نوع مختلفين

region: {{ .Values.region | upper | quote }}
port: {{ .Values.service.port }}

الناتج المتوقع

region: "WEST"
port: 8080

بافتراض region يساوي west والمنفذ عدد صحيح 8080، يكون المخرج المقصود نصا مقتبسا وعددا غير مقتبس. لم يصير هذا المقطع بواسطة Helm.

احفظ نوع الحقل المستقبِل

يحمي اقتباس النص قيمة ConfigMap.data من تفسيرها كعدد أو قيمة منطقية. لكن اقتباس containerPort قد يحول العدد الصحيح إلى نص في موضع تطلب فيه API رقما. القاعدة سياقية: اتبع مخطط الحقل المستقبل ولا تتبع قاعدة اقتباس كل شيء. قد تكون القيمة رقمية في values.yaml ثم تتحول عمدا إلى نص تحت ConfigMap.data لأن التطبيق سيحللها لاحقا. اشرح هذا التحويل صراحة. تحقق من العدد قبل تنسيقه كيلا يتحول نص غير صالح إلى قيمة تبدو مقبولة في الناتج.

ضمن المخرج المركب عمدا

تسلسل toYaml قيمة إلى YAML، بينما تضيف nindent سطرا جديدا وإزاحة لكل سطر. يشيع الجمع بينهما حين تتحول خريطة قيم إلى فرع داخل manifest. يحدد عمق الوجهة عدد المسافات. في المقطع الثاني تقع labels تحت metadata، لذلك تحتاج العناصر المسلسلة إلى أربع مسافات من جذر الوثيقة. تمرير نص بدلا من خريطة ينتج نصا أيضا لكنه لا يحقق عقد labels. اعتبر التسلسل تنسيقا لا تحققا؛ ويجب أن يثبت مخطط القيم البنية المسموحة أولا.

gotemplate مقطع ملصقات مركبة

metadata:
  name: catalog-config
  labels:
    {{- toYaml .Values.extraLabels | nindent 4 }}

إذا كانت extraLabels تساوي {team: learning}، فالعنصر المقصود team: learning بإزاحة أربع مسافات. حُذف باقي ConfigMap عمدا.

أبق التحويلات قابلة للتفسير

استخدم التحويل عندما يكون معناه جزءا من عقد المدخلات العام. قد يخفي تحويل معرّف حساس لحالة الأحرف إلى حروف صغيرة مدخلا خاطئا بدلا من إصلاحه. ويصعب التوليد العشوائي والوقت الحالي واستعلامات العنقود إعادة إنتاج التصيير، فلا تدخلها دون تعليل دورة الحياة. في حزمة كتالوج ثابتة يسهل مقارنة التعبيرات الحتمية عبر المراجعات. ينبغي أن يبدأ المراجع بملف قيم صغير ويتتبع التحويلات ويفسر كل حقل ناتج دون افتراض أن نجاح التصيير يثبت توافق النشر.

الأخطاء الشائعة وإصلاحها

تحول حقل API عددي إلى نص مقتبس

لماذا يحدث؟: استُخدم مساعد الاقتباس نفسه لكل الحقول المستقبلة.
كيف تصلحه؟: احفظ مخطط الوجهة وتحقق من العدد الصحيح المدخل قبل تصييره.
كيف تتجنب تكراره؟: صنف مخرجات الأمثلة حسب نوع الحقل المستقبِل.

تصيير خريطة labels عند جذر الوثيقة

لماذا يحدث؟: استُخدم التسلسل دون إزاحة تناسب الوجهة.
كيف تصلحه؟: استخدم nindent بالعمق المطلوب تحت metadata.labels.
كيف تتجنب تكراره؟: راجع الفرع الناتج كاملا بما في ذلك سطره الأول.

تغيير معرّف بصمت داخل القالب

لماذا يحدث؟: أُضيف التطبيع دون تحديد دلالة المعرّف في التطبيق.
كيف تصلحه؟: ارفض المدخل غير الصالح أو وثق التحويل المقصود بأمثلة.
كيف تتجنب تكراره؟: افصل التحقق عن التحويلات التجميلية.

اختبر فهمك

1. يخزن ConfigMap قيمة retryCount من المدخل العددي 3. هل تُقتبس القيمة؟

اعرض الحل المشروح

نعم، فقيم ConfigMap.data نصوص، ولذلك ينبغي أن تكون القيمة الناتجة "3" وإن كان مدخل القيم العام عددا صحيحا. تحقق منه رقميا ثم نسقه للوجهة. وثق أن التطبيق يحلل النص؛ فلا يثبت الاقتباس أو تحليل YAML قبول التطبيق للنطاق المختار.

2. ماذا يفعل .Values.region | upper | quote للقيمة west، ولماذا لا يمثل فحص تفويض؟