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

بنية الحزمة وعقود النسخ

اقرأ حزمة تطبيق صغيرة وحافظ على اتساق بيانات التغليف ومعرّفات التطبيق وافتراضات المنصة المدعومة.

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

في هذه الصفحة

أهداف الدرس

شرح أدوار Chart.yaml وvalues.yaml ومجلدي templates وcharts.
اختيار حقول متسقة لنسخة الحزمة والتطبيق.
مراجعة محتويات الحزمة دون اعتبار التغليف نشرا.

ارسم عقد المجلد

يتعرف Helm على بنية مقصودة للحزمة. يعلن Chart.yaml البيانات الوصفية، ويوفر values.yaml القيم الافتراضية، ويحتوي templates النصوص التي تصبح manifests، بينما يضم charts الاعتماديات المغلفة أو المفكوكة. ويقيد values.schema.json الاختياري القيم، وللمجلد crds دورة حياة خاصة سندرسها لاحقا. يمكن أن تكون الملفات المجاورة أصول إعداد للتطبيق إذا أدرجتها الحزمة عمدا. ليست شجرة المصدر حزمة نظيفة تلقائيا. راجع الأمثلة والتقارير المؤقتة والمواد الخاصة قبل التغليف، واجعل اسم المجلد مطابقا لاسم الحزمة ليتفق القارئ والأتمتة على الأصل محل المراجعة.

text بنية مصدر صغيرة خاضعة للمراجعة

catalog/
  Chart.yaml
  values.yaml
  values.schema.json
  templates/
    configmap.yaml
    _helpers.tpl

الشجرة توضيحية. لا يُخرج ملف المساعد ككائن manifest، وملف المخطط اختياري لكنه مفيد.

اقرأ البيانات الوصفية كعقد

في حزم التطبيقات الخاصة بـHelm 3 يصف apiVersion v2 صيغة الحزمة لا واجهة مورد Kubernetes. يعرّف version أصل الحزمة ويتبع النسخ الدلالية. أما appVersion فبيان وصفي للتطبيق لا يلزم أن يتبع النسخ الدلالية؛ ضعه بين علامات اقتباس لحفظ نوعه النصي. يفصل المثال تغيير التغليف عن بناء التطبيق 2.7.1. قد يتطلب تعديل منفذ افتراضي أو مساعد تغيير نسخة الحزمة مع ثبات الصورة. وبالمقابل لا يعني تحديث التطبيق تغير بقية سلوك الحزمة. اشرح أثر التوافق في ملاحظات الإصدار.

yaml مقطع بيانات Chart.yaml

apiVersion: v2
name: catalog
description: Synthetic catalog application chart
type: application
version: 0.4.0
appVersion: "2.7.1"

هذا الملف بيانات حزمة وليس كائن Kubernetes. الأرقام اختيارات تعليمية ولا تمثل ادعاء بالدعم.

افصل أبعاد التوافق

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

راجع حدود الحزمة

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

وثق الملكية والتغيير

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

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

استخدام apps/v1 في apiVersion لملف Chart.yaml

لماذا يحدث؟: نُقلت بيانات مورد Kubernetes إلى بيانات التغليف.
كيف تصلحه؟: استخدم v2 لصيغة حزمة Helm 3 وضع واجهات الموارد داخل القوالب.
كيف تتجنب تكراره؟: راجع مخطط بيانات الحزمة ومخطط الكائن الناتج منفصلين.

تعديل appVersion لا يغير الصورة

لماذا يحدث؟: يستخدم القالب image.tag بدلا من Chart.AppVersion.
كيف تصلحه؟: افحص تعبير الصورة واضبط مدخله الموثق عمدا.
كيف تتجنب تكراره؟: وضح هل بيانات التطبيق وصفية أم قيمة افتراضية للصورة.

احتواء الأرشيف على تصدير محلي خاص

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

اختبر فهمك

1. غيّر مساعد الملصقات مع ثبات التطبيق 2.7.1. أي نسخة تستحق المراجعة؟

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

تتغير نسخة الحزمة لأن السلوك المغلف تغير، ويمكن أن يبقى appVersion مساويا 2.7.1. راجع هل الملصقات وصفية أم تدخل في محددات غير قابلة للتغيير؛ فتعديل يبدو تجميليا قد يؤثر في الملكية والتوجيه. اختر الزيادة حسب سياسة توافق الحزمة واشرح التغيير الفعلي دون اعتبار كل تعديل ملصق تنسيقا غير مؤثر.

2. أين يوضع ملف إعداد تطبيق افتراضي ثابت، وكيف يراجع؟