Helm / متوسط: عقود التأليف ودورة الحياة / الدرس 8
مخططات القيم والتحقق من العقد
استخدم JSON Schema وفحوص قوالب مركزة لرفض بنى المدخلات غير المدعومة مع تمييز تحقق البنية عن ضمانات التطبيق والسياسة.
في هذه الصفحة
أهداف الدرس
- تحديد الخصائص المطلوبة والأنواع والنطاقات والكائنات المتداخلة.
- شرح القيم الافتراضية في المخطط وقرارات الخصائص غير المعروفة.
- اختيار قيود تعبر عن واجهة القيم العامة.
تحقق من الواجهة العامة
يحدد مخطط القيم المدخل المقبول قبل وصول الكائنات الناتجة إلى Kubernetes. يمكنه رفض نص في موضع عدد النسخ الصحيح أو حقل مطلوب غائب أو نمط خدمة غير مدعوم. يوجد المخطط في values.schema.json ويخص عقد القيم لا manifest الناتج كله. يكشف ذلك الأخطاء قرب أسبابها ويسهل تفسير الرسائل. لكنه لا يثبت وجود صورة أو انفتاح منفذ فعلي أو سماح سياسة المؤسسة بالكائن. أبق هذه الادعاءات البيئية خارج نطاقه.
عبّر عن الأنواع والنطاقات
يستخدم المقطع الأول مصطلحات المسودة السابعة من JSON Schema لمدخل افتراضي صغير. تسمي required الحقول الواجبة، وتصف properties قيودها. يسمح minimum صفر بتعليق التطبيق عمدا، بينما maximum عشرة عقد منتج توضيحي لا توصية سعة عامة. إذا لم يناسب الصفر التطبيق فاختر عقدا آخر واشرحه. لا تجعل required النص غير فارغ وحدها؛ أضف minLength حين يُمنع الفراغ. وتحتاج الكائنات المتداخلة قوائم required خاصة لأن شروط المستوى الأعلى لا تتكرر تلقائيا.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["replicaCount", "service"],
"properties": {
"replicaCount": {"type": "integer", "minimum": 0, "maximum": 10},
"service": {
"type": "object",
"required": ["port"],
"properties": {"port": {"type": "integer", "minimum": 1, "maximum": 65535}}
}
}
}المخطط JSON كامل لكنه إعداد غير قابل للتشغيل. حُلل نحوه محليا ولم يقيّمه محرك مخططات Helm.
حدد سياسة المفاتيح غير المعروفة
قد يُتجاهل الخطأ الإملائي replicaCout بصمت ما لم يرفض المخطط الخصائص غير المعروفة. تستطيع additionalProperties false كشفه، لكن استخدمها بحكمة؛ فقد تقبل الحزمة خرائط توسعة أو قيما عامة من الأب بصورة مشروعة. يمكن لتقييد الجذر بشدة رفض تكامل اعتماد صحيح. حدد كائنات صارمة للواجهات المملوكة وخرائط مفتوحة مقصودة للبيانات الوصفية المناسبة. وثق هل تقبل annotations المخصصة مفاتيح نصية حرة. وللنقطة القابلة للتوسعة عقد نوع خاص؛ فالانفتاح لا يتطلب قبول قوائم وكائنات وأعداد في كل مكان.
افصل القيم الافتراضية عن التحقق
default في JSON Schema وصف وليس أمرا لحقن قيمة داخل Values في Helm. ضع الافتراضيات التشغيلية في values.yaml واستخدم المخطط للتحقق منها. كما تعد required في القالب القيم الفارغة غائبة، فقد ترفض false أو الصفر مع سماح المخطط بهما. يناسب المقطع الثاني نص مستودع يجب ألا يفرغ ولا يناسب راية enabled المنطقية. يمكن التعبير عن قيود الحقول المتعددة ببدائل المخطط أو شرط fail واضح، لكن تجنب رسائل متعارضة موزعة على طبقات كثيرة.
{{- $repository := required "image.repository must be a nonempty string" .Values.image.repository -}}
image: {{ printf "%s:%s" $repository .Values.image.tag | quote }}افترض أن image خريطة موجودة وأن tag تحقق منه سابقا. لا يتحقق المقطع من توفر السجل أو نحو البصمة.
أنشئ حالات قبول ورفض
اختبر الافتراضيات وتجاوزا صالحا وقيمة خاطئة لكل قيد مهم. اجعل أسباب الرفض محددة؛ فلا ينبغي لحالة نوع العدد أن تفشل أولا لغياب service. أدرج حقولا متداخلة مفقودة وأنواعا خاطئة والصفر المسموح وقيمة enum غير مدعومة. راجع تطور المخطط كتغيير واجهة؛ فقد يرفض تضييق النطاق تثبيتات قائمة كانت ملفاتها السابقة تعمل. قدم مسار انتقال واذكر المدخل القديم المقبول. يفيد تحقق نحو JSON وحده لكنه لا يثبت سلوك المخطط الفعلي، فسم الفحص المحلي بدقة عند غياب محرك تحقق.
الأخطاء الشائعة وإصلاحها
توقع ملء Values من default في المخطط
- لماذا يحدث؟
- فُسر وصف في المخطط كحقن للقيمة.
- كيف تصلحه؟
- صرح بالافتراضيات في values.yaml وتحقق من صورتها المدمجة.
- كيف تتجنب تكراره؟
- راجع تحديد الافتراضيات والتحقق كآليتين مختلفتين.
فشل راية false مقصودة عند required
- لماذا يحدث؟
- يعد مساعد القالب false فارغة.
- كيف تصلحه؟
- استخدم فحص الوجود والنوع المنطقي بدلا من منطق النص غير الفارغ.
- كيف تتجنب تكراره؟
- أدرج false والصفر ضمن حالات العقد.
رفض جذر صارم لخريطة global صحيحة
- لماذا يحدث؟
- تجاهل رفض الخصائص غير المعروفة عقد التكامل مع الأب.
- كيف تصلحه؟
- حدد واجهات global والاعتماديات المسموحة عمدا.
- كيف تتجنب تكراره؟
- اختبر الحزمة منفردة وضمن سياق الأب.
اختبر فهمك
1. كيف يطلب المخطط وسم صورة نصيا غير فارغ؟
اعرض الحل المشروح
أدرج tag في required للكائن image، وحدد نوعه string وminLength واحدا. واطلب image في الأب المناسب إذا كان واجبا. يثبت ذلك الوجود وعدم الفراغ لا وجود الصورة فعلا أو صحة سياسة السجل. يجب أن تطابق قيود التنسيق الإضافية واجهة الوسم أو البصمة الموثقة للحزمة.
2. يرفض حد أقصى جديد replicaCount 12 الذي قُبل سابقا. هل هذا تنظيف توثيق فقط؟
اعرض الحل المشروح
لا. يغير واجهة القيم المقبولة وقد يمنع عمليات لاحقة على تثبيت قائم. اشرح السبب وحدد القيم المتأثرة وقدم انتقالا متوافقا أو سياسة إصدار كاسر مقصودة. لا تبرر الرقم كضبط عام؛ فالسعة والتوفر وسلوك التطبيق تحتاج أدلتها الخاصة.
أهم ما تعلمته
- تقيد المخططات واجهة القيم ولا تثبت ضمانات التشغيل أو التفويض.
- الافتراضية والوجود والنوع وعدم الفراغ قرارات مختلفة.