فشل إنشاء السحابة بسبب الخطأ SUBSTITUTIONVARIABLENOT_DEFINED لقوالب CI والبرنامج النصي للتحقق من صحة الاستبدال الذي يتم تشغيل خط الأنابيب الثابت

لقد أصبح Cloud Build أداة محورية في التكامل المستمر وسير عمل النشر للعديد من المطورين والمؤسسات. إن تكامله الوثيق مع منتجات Google Cloud Platform (GCP) الأخرى وسير العمل القابل للبرمجة النصية يجعله مفضلاً للفرق التي ترغب في خطوط أنابيب CI/CD قابلة للتخصيص وقابلة للتطوير. ومع ذلك، كما هو الحال مع العديد من الأدوات القوية، فإن Cloud Build لا يخلو من المراوغات - خاصة عندما يتعلق الأمر بالمتغيرات والمعلمات. إحدى المشكلات المحبطة التي واجهها العديد من المطورين مؤخرًا هي الخطأSUBSTITUTION_VARIABLE_NOT_DEFINED. يمكن لهذه المشكلة بعيدة المنال أن تؤدي إلى توقف خط أنابيب بأكمله، مما يؤثر على سرعة التطوير وزيادة وقت استكشاف الأخطاء وإصلاحها.

ليرة تركية؛ د

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

فهم خطأ SUBSTITUTION_VARIABLE_NOT_DEFINED

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

على سبيل المثال، قد يتضمن قالب Cloud Build الشائع خطوات إنشاء مثل ما يلي:

خطوات:
- الاسم: "gcr.io/cloud-builders/docker"
  الوسائط: ['build', '-t', '${_IMAGE_NAME}', '.']

هنا، ${_IMAGE_NAME} هو متغير بديل محدد من قبل المستخدم. إذا لم يتم توفير هذا المتغير في وقت تشغيل الإنشاء، ربما عبر تكوين المشغل أو سطر الأوامر، فسوف يفشل Cloud Build على الفور مع ظهور خطأSUBSTITUTION_VARIABLE_NOT_DEFINED.

الأسباب الجذرية في تطبيقات قالب CI

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

الحالات التي من المحتمل أن يظهر فيها هذا الخطأ:

• عندما يتم نسيان القيمة الافتراضية في إعدادات المشغل
• عند إضافة قالب جديد ولكن لا يتم توثيق أو فرض جميع المتغيرات المطلوبة
• عندما يقوم المطورون باستنساخ القوالب عبر البيئات (على سبيل المثال، التدريج والإنتاج) ولكن مع حذف تعريفات متغيرة محددة

إصلاح عملي: البرنامج النصي للتحقق من صحة الاستبدال

لحل هذه المشكلة ومنع الاضطرابات المستقبلية، قدمت عدة فرق آلية التحقق المسبق - وهوبرنامج نصي للتحققمضمن يتم تشغيله في بداية المسار للتحقق من متغيرات الاستبدال المطلوبة قبل تنفيذ أي خطوات مهمة.

يقوم البرنامج النصي بفحص البيئة الحالية ويحاول تأكيد وجود (وأحيانًا النوع أو النمط) جميع المتغيرات المهمة. في حالة فقدان أي منها، فإنه يتوقف عن التنفيذ مبكرًا ويوفر قائمة يمكن قراءتها بواسطة الإنسان بالمتغيرات التي كانت غائبة.

فيما يلي مثال مبسط لمثل هذا البرنامج النصي المكتوب بلغة bash:

#!/بن/باش
مجموعة -ه

REQUIRED_VARS=(
  "_IMAGE_NAME"
  "_SERVICE_NAME"
)

لـ VAR في "${REQUIRED_VARS[@]}"
يفعل
  إذا [[ -z "${!VAR}" ]]; ثم
    صدى "خطأ: لم يتم تعريف متغير الاستبدال المطلوب ${VAR}."
    خروج 1
  فاي
منتهي

صدى "جميع متغيرات الاستبدال المطلوبة موجودة."

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

التكامل في سير عمل Cloud Build

في سير العمل العملي، يمكن تضمين البرنامج النصي للتحقق من الصحة إما كأمر مضمن أو استيراده من ملف برنامج نصي مشترك في موقع آمن، مثل مجموعة GCS ذات الإصدار. عادةً ما تكون هذه هي الخطوة الأولى في ملف cloudbuild.yaml:

خطوات:
- الاسم: "gcr.io/cloud-builders/bash"
  نقطة الدخول: "باش"
  الوسائط: ['-c'، './validate_vars.sh']

وهذا يمنح الفرق القدرة على:

• إصدار منطق التحقق من صحة CI الخاص بهم
• الحفاظ على مصدر واحد للحقيقة للمتغيرات المتوقعة
• تقليل دورات تصحيح الأخطاء المزعجة التي تتضمن تحرير مشغلات التجربة والخطأ

تجربة المطور المحسنة

كان لإدخال نص التحقق هذا تأثيرات فورية:

• عدد أقل من حالات فشل خطوط الأنابيببسبب المتغيرات المفقودة غير الملحوظة.
• رسائل خطأ أكثر وضوحًاتشير مباشرة إلى المشكلة بدلاً من السجلات الغامضة.
• تأهيل أسرعللمطورين الجدد الذين أعادوا استخدام مسارات عمل CI الحالية دون الحاجة إلى معرفة قبلية كاملة بالمتغيرات المتوقعة.

بمرور الوقت، قامت بعض الفرق بتوسيع أداة التحقق من الصحة للسماح بالمتغيراتالاختياريةوتعيين الإجراءات الاحتياطية، مما يوفر المزيد من المرونة للقوالب المشتركة. قام آخرون بإقرانه مع التحقق من صحة مخطط YAML لفحص خط أنابيب cloudbuild.yaml بالكامل في وقت التشغيل.

منع الخطأ في المشاريع الجديدة

للحفاظ على المشاريع المستقبلية خالية من هذه المشكلة، يوصى باتباع أفضل الممارسات التالية:

• قم بتوثيق جميع متغيرات الاستبدال المطلوبةفي دليل README أو CI الخاص بمستودع الريبو.
• استخدم برنامجًا نصيًا للتحققفي كل قالب جديد يضاف إلى سير عمل CI/CD الخاص بك.
• حدد اصطلاحات تسمية واضحة(على سبيل المثال، تتضمن المتغيرات التي تبدأ بـ _ بدائل مخصصة مطلوبة).
• قم بتعيين القيم الافتراضيةفي الإصدارات حيثما كان ذلك مناسبًا أو قم بتوفير منطق متغير اختياري من خلال البرمجة النصية.

الأفكار النهائية

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

الأسئلة المتداولة: متغيرات استبدال Cloud Build والتحقق من صحتها

• س: ما هو المتغير البديل في Cloud Build؟
  المتغير البديل هو عنصر نائب في ملف cloudbuild.yaml الخاص بك والذي يتم استبداله بالقيم الفعلية عند تشغيل الإصدار. تُستخدم هذه المتغيرات لتخصيص الإصدارات لبيئات أو تكوينات مختلفة.
• س: لماذا أرى أخطاء SUBSTITUTION_VARIABLE_NOT_DEFINED؟
  يحدث هذا الخطأ عادةً عندما لا يتم تمرير المتغير المشار إليه في ملف YAML عبر مشغل الإنشاء أو البيئة، مما يجعله غير محدد في وقت التشغيل.
• س: كيف يمكنني توفير متغيرات الاستبدال عند تشغيل البناء؟
  يمكنك تمرير متغيرات الاستبدال من خلال Google Cloud Console عند إعداد المشغل، أو عبر gcloud CLI باستخدام علامة --substitutions .
• س: هل يمكنني تعيين القيم الافتراضية للمتغيرات البديلة؟
  لا يدعم Cloud Build القيم الافتراضية مباشرة في YAML، ولكن يمكنك برمجة المنطق للتعامل مع المتغيرات غير المحددة وتعيين بدائل برمجيًا في البرامج النصية bash أو Python.
• س: ما هي أفضل طريقة لفرض التواجد المتغير عبر مشاريع متعددة؟
  استخدم برنامجًا نصيًا مشتركًا للتحقق من الصحة في بداية جميع قوالب cloudbuild.yaml لفرض الاتساق والتحقق من صحة المدخلات قبل متابعة مهمة الإنشاء.