الوحدة 4 من مسار Monaco Managed: يحوّل نشر Monaco Managed مجلدًا من ملفات YAML وJSON إلى إعدادات فعّالة في عنقودك، بعد تحقق تجريبي لا يغيّر شيئًا.
المسار: Monaco Managed · الوحدة 4/5 · المدة: نحو 45 دقيقة · المستوى: متوسط
الأهداف:
- تنظيم مشروع Monaco: المجلدات و
config.yamlوقالب JSON - ضبط قالب بالمتغيرات والمراجع بين الإعدادات
- تجاوز قيمة لكل بيئة
- التحقق بالأمر
deploy --dry-runثم النشر
المتطلبات المسبقة: واجهة سطر الأوامر monaco مثبّتة وملف بيان (الوحدة 2)، ومشروع مُصدَّر بالأمر monaco download (الوحدة 3)، وبيئة Managed للاختبار.
أعدّت الوحدات السابقة الأداة واستعادت إعدادات موجودة. تعالج هذه الوحدة الخطوة المحورية: نشر Monaco Managed. أي كتابة الملفات أو تعديلها، والتأكد من اتساقها، ثم إرسالها إلى البيئة المستهدفة. يحلّ هذا التسلسل محلّ النقر في الواجهة، ويجعل كل تغيير قابلًا للمراجعة في Git.
المحتوى صالح لـ Dynatrace Managed فقط: رمز API وواجهات الإعدادات الكلاسيكية وSettings 2.0. النقاط المتحقَّق منها مأخوذة من صفحات Managed في الوثائق الرسمية ومن شيفرة المستودع Dynatrace/dynatrace-configuration-as-code.
نشر Monaco Managed: بنية المشروع
بحسب الوثائق، المشروع مجلد. يحتوي على مجلدات فرعية تحمل أسماء واجهات API، وتحتوي هذه بدورها على ملفات كل إعداد. يتألف الإعداد من عنصرين: ملف YAML (المعاملات والاعتماديات والاسم والقالب) وقالب JSON، أي الحمولة المرسلة إلى واجهة Dynatrace.

يحدد ملف البيان المشاريع المراد نشرها والبيئات المستهدفة. مفاتيحه العليا هي manifestVersion وprojects وenvironmentGroups. تنتمي كل بيئة إلى مجموعة واحدة بالضبط. أسماء مجلدات API (مثل management-zone وalerting-profile وdashboard) مذكورة في صفحة «Configuration types and access permissions»؛ وتسرد هذه الصفحة أيضًا مخططات Settings 2.0.
| العنصر | الدور |
|---|---|
manifest.yaml |
أي المشاريع، وإلى أي البيئات، وبأي رمز (اسم المتغير) |
| مجلد المشروع | يجمع الإعدادات منطقيًا (فريق، خدمة) |
config.yaml |
قائمة الإعدادات: id وtype وconfig |
| قالب JSON | جسم الكائن، مع متغيرات {{ .nom }} |
يوجد نوعان من المشاريع في ملف البيان: simple (الافتراضي، مع name وpath اختياريًا) وgrouping، الذي يحمّل كل مجلد فرعي بوصفه مشروعًا مستقلًا، يسبقه اسم المشروع ونقطة (مثل general.zones).
ملف config.yaml
يبدأ الملف بالمفتاح configs، وهو قائمة. يتطلب كل عنصر ثلاثة حقول: id وtype وconfig. الحقل id موجود لـ Monaco وحده: يجب أن يكون فريدًا لكل نوع ولكل مشروع، ويُستخدم أساسًا في المراجع. يشير type إلى واجهة API (api: dashboard، أو الصيغة المختصرة type: dashboard) أو إلى مخطط Settings 2.0 (settings مع schema وscope).
تحتوي الكتلة config على name وtemplate، واختياريًا skip وparameters. في واجهة API كلاسيكية يحدد name هوية الكائن في البيئة: به يُقرَّر بين الإنشاء والتحديث. لذلك يجب أن يستخدمه القالب كما هو، دون أي حرف زائد، بالصيغة "{{ .name }}". مسافة زائدة واحدة تفسّر الكائنات المكررة التي تُلاحَظ أحيانًا بعد النشر.
قوالب JSON والمتغيرات
يُكتب القالب بصيغة JSON مع قواعد Go templates. توصي الوثائق بالبساطة: يكفي في أغلب الحالات الإشارة إلى معامل بالصيغة {{ .NOM_DU_PARAMETRE }}. تُهرَّب قيم YAML قبل إدراجها، مما يضمن JSON صالحًا حتى مع علامات الاقتباس أو أسطر جديدة.
فخ شائع: بعض الحمولات تحتوي أصلًا على أقواس مزدوجة، وعندئذ يجب تهريبها ({{`{{`}} للفتح و{{`}}`}} للإغلاق). يفعل Monaco ذلك تلقائيًا للملفات الناتجة عن monaco download.
للمعاملات أنواع عدة: القيمة (الصيغة المختصرة: seuil: 15)، وenvironment (يقرأ متغير بيئة، مع default اختياري)، وreference وcompound وlist وfile. لا يُقيَّم المعامل إلا إذا أشار إليه إعداد منشور. إذا غاب متغير بيئة ولم يُحدَّد default، يفشل النشر. تعود الوحدة 5 إلى موضوع الأسرار.
الاعتماديات بين الإعدادات
يقرأ المعامل reference خاصية من إعداد آخر، وغالبًا معرّفه الفعلي id في Dynatrace. يستنتج Monaco من ذلك الترتيب: يُنشر الإعداد المشار إليه أولًا. وتؤدي حلقة اعتماديات إلى فشل النشر. الصيغة المختصرة هي [project, type, configId, property]؛ ويمكن حذف المستويات الأولى إذا طابقت مستويات الإعداد الحالي.

في المثال، يحلّ zoneId معرّف management zone المسماة zone-prod، المعرَّفة في المجلد management-zone من المشروع نفسه. يطابق الحقل mzId في القالب الحقل المقابل في واجهة ملفات التنبيه؛ ونوعه سلسلة نصية. ولأن القيمة تُدرج بين علامتي اقتباس، تبقى النتيجة JSON صالحًا.
يغيّر القسم environmentOverrides قيمًا لبيئة واحدة (هنا الاسم)، ويفعل groupOverrides ذلك لمجموعة كاملة. مع skip: true في تجاوز ما، لا يُنشر الإعداد في تلك المجموعة.
التحقق بالأمر deploy –dry-run
الأمر الأساسي هو monaco deploy manifest.yaml. يتحقق الخيار --dry-run (اختصاره -d) من بنية ملف البيان والمشاريع والإعدادات: يحلّ المعاملات وينتج قوالب JSON. توضح الوثائق أن التشغيل التجريبي لا يتصل بـ Dynatrace ولا يستطيع التحقق من محتوى الحمولات. لذلك قد يفشل النشر مع خطأ HTTP 400 إن كان القالب غير صحيح.
تساعد خيارات أخرى في حصر النشر:
--environment(-e): بيئة أو أكثر من ملف البيان؛--group(-g): مجموعة بيئات، ولا يجتمع مع--environment؛--project(-p): مشروع واحد مع اعتمادياته؛--continue-on-error(-c): المتابعة رغم الأخطاء، مع خطر أخطاء متتالية في الإعدادات التابعة.
بالنسبة إلى فريق SRE، التشغيل التجريبي فحص منخفض الكلفة يوضع عند كل طلب دمج: يلتقط المراجع المكسورة والمتغيرات الناقصة وملفات JSON المشوهة قبل أن تصل إلى أي بيئة. لكنه لا يغني عن نشر في بيئة اختبار.
ممارسات جيدة
- الانطلاق من كائن مُصدَّر بـ
monaco downloadبدل كتابة JSON من الذاكرة. - إبقاء القوالب بسيطة ونقل المنطق إلى المعاملات.
- النشر أولًا في بيئة الاختبار (
-e) ثم في مجموعة الإنتاج. - عدم كتابة أي رمز في ملف البيان: يظهر فيه اسم المتغير فقط.
تمرين عملي
لم تُنفَّذ الأوامر التالية عند كتابة هذه الوحدة: تستند النتيجة المتوقعة إلى الوثائق وإلى شيفرة CLI. استخدم بيئة Managed للاختبار.
الخطوة 1 — تحضير المشروع
أنشئ المجلد monaco-demo مع ملف البيان الموضَّح في الصورة ومشروع alerting. صدّر كائنين موجودين (management zone وملف تنبيه) بالأمر monaco download (الوحدة 3) لاستخدامهما قالبين. النتيجة المتوقعة: مجلد لكل نوع API، في كل منها config.yaml وملف JSON.
الخطوة 2 — ضبط القالب
في JSON الخاص بملف التنبيه، استبدل الاسم بـ "{{ .name }}" واستبدل معرّف المنطقة بمتغير يغذّيه مرجع إلى management zone، كما في المثال. النتيجة المتوقعة: لا تبقى أي قيمة خاصة ببيئة مكتوبة مباشرة، عدا قيم المعاملات.
الخطوة 3 — التحقق التجريبي
export DT_PREPROD_URL="<URL de votre environnement Managed de recette>"
export DT_PREPROD_TOKEN="<jeton d'API de test>"
monaco deploy manifest.yaml --dry-run
النتيجة المتوقعة: تسجّل شيفرة CLI المصدرية العبارة «Validation finished without errors» عندما يكون كل شيء متسقًا (الصيغة غير مؤكدة في كل الإصدارات).
الخطوة 4 — إحداث خطأ متعمد
استبدل configId في المرجع بمعرّف غير موجود، وأعد تشغيل --dry-run، ثم أعده كما كان. النتيجة المتوقعة: خطأ عند التحميل أو التحقق، دون أي نداء إلى البيئة.
الخطوة 5 — النشر
monaco deploy manifest.yaml -e preprod-managed
النتيجة المتوقعة: تُنشأ management zone قبل ملف التنبيه المرتبط بها. أعد تشغيل الأمر: يُحدَّث الكائن ولا يُكرَّر، لأن name متطابق.
اختبار
- ما الحقول الثلاثة الإلزامية في عنصر من
configs؟ a) name, template, skip b) id, type, config c) id, name, scope d) project, type, parameters - ماذا يتحقق منه
--dry-run؟ a) أن واجهة Dynatrace تقبل حمولة JSON b) بنية الملفات ونتيجة القوالب، دون اتصال c) صلاحيات رمز API d) لا شيء، فهو ينشر بوضع القراءة فقط - يُستخدم معامل من نوع
referenceمن أجل: a) قراءة متغير بيئة b) قراءة خاصية من إعداد آخر وفرض ترتيب النشر c) استيراد ملف d) تعطيل إعداد - كيف يُنشر إلى بيئة محددة فقط؟ a)
--groupb)--projectc)--environmentd)--continue-on-error
الإجابات
- b) يتطلب كل إعداد
idوtypeوconfig. - b) لا يتصل التشغيل التجريبي بـ Dynatrace: لا يُتحقق من محتوى الحمولات.
- b) ينشئ المرجع اعتمادية: يُنشر الإعداد المقصود أولًا.
- c) يستهدف
-eبيئة أو أكثر من ملف البيان.
للمزيد
- Dynatrace Monaco: درس الإعدادات بوصفها شيفرة
- Monaco أم Terraform: كيف تختار
- مسار Dynatrace Managed: الأتمتة وواجهات API
- الوثائق الرسمية: Monaco YAML Configuration (Managed)
← الوحدة 3: تصدير Monaco Managed · فهرس المسار · الوحدة 5: أسرار Monaco Managed →
الأسئلة الشائعة
هل يضمن التشغيل التجريبي نجاح النشر؟
لا. يتحقق من البنية ونتيجة القوالب دون الاتصال بـ Dynatrace. وقد تسبب حمولة JSON غير صالحة للواجهة خطأ HTTP 400 عند النشر الفعلي.
لماذا يُنشأ كائن مكرر بدل تحديثه؟
في واجهة API كلاسيكية، يحدد name هوية الكائن. إذا اختلف اسم القالب عن اسم YAML (مسافة أو حرف زائد)، لا يجد Monaco الكائن الموجود. تحقق من أن القالب يستخدم "{{ .name }}" دون أي شيء حوله.
هل يمكن فرض ترتيب النشر؟
نعم، عبر الاعتماديات: يفرض المعامل reference أن يمرّ الإعداد المشار إليه أولًا. أما ترتيب بعض كائنات Settings 2.0، فتصف الوثائق أيضًا معاملًا اسمه insertAfter (CLI الإصدار 2.14.0 أو أحدث).
صرت تعرف كيف تنظّم مشروعًا وتربط الإعدادات وتتحقق تجريبيًا وتنشر إلى بيئة محددة. تتناول الوحدة التالية الأسرار والبيئات المتعددة والأمر delete.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. لا يغني هذا المسار عن تدريبات وشهادات Dynatrace University الرسمية. تحقق دائمًا من الميزات في الوثائق الرسمية الخاصة بإصدارك.