migration لـ Pack بين إصدارات Helm Chart

تحوّل Pack Migration ملفات Pack الحالية عند تغيير بنية values أو vars أو إصدار Chart، وتحافظ على اختيارات المستخدم من دون إعادة كتابة كل ملف يدويا.

هذه الصفحة مرجع إنشاء pack-migrations.yaml واختباره. راجع إمكانات Pack في Helm Chart للملفات والميزات الأخرى.

يحدد pack-migrations.yaml تحويل ملف Pack عند تغير البنية أو الإصدار. يجب أن يوجد بهذا الاسم في جذر Chart بجانب Chart.yaml.

يقرأ Pack Operator الملف من Chart الهدف. يجب أن يحتوي كل إصدار منشور على سلسلة كاملة من جميع الإصدارات القديمة المدعومة إلى الهدف، حتى لا يضطر المستخدم الذي يتجاوز عدة إصدارات إلى تثبيت الإصدارات الوسطية.

migrations:
  - repo: kubit-paas
    chart: redis
    from_version: '>=0.1.0, <0.2.0'
    to_version: '~=0.2.0'
    context:
      metrics_default: true
    steps:
      - set:
          values: !var pack.spec.values
          values.metrics.enabled: !default-var metrics_default

      - if: values.password
        set:
          values.auth.password: !pop values.password

      - reorder:
          values:
            - auth
            - metrics

repo هو اسم مورد المستودع وليس URL. تتطابق قيمتا repo وchart بدقة ولا تقبلان wildcard. لا يطابق ملف Pack الذي لا يحتوي على spec.chart.version أي migration.

يدعم from_version مقارنات semantic version:

ضع التعبير بين علامتي اقتباس، خصوصا إذا بدأ بـ ‎<‎ أو ‎>‎. يجب أن تتحقق كل الشروط المفصولة بفاصلة.

قبل كل migration، يضبط المشغّل spec.chart.version إلى to_version. ثم يفحص migrations اللاحقة بالإصدار الجديد، ولذلك يمكن لعدة entries تكوين سلسلة:

migrations:
  - repo: kubit-paas
    chart: redis
    from_version: '<0.3.0'
    to_version: '~=0.3.0'
    steps: []

  - repo: kubit-paas
    chart: redis
    from_version: '>=0.3.0, <0.5.0'
    to_version: '~=0.5.0'
    steps: []

ينتقل Pack بإصدار 0.2.0 إلى فرع 0.3 ثم 0.5. يجب ألا يطابق to_version قيمة from_version في entry نفسها حتى لا تتكرر لاحقا.

ترتيب entries في الملف ليس ترتيب التنفيذ النهائي. يرتبها المشغّل حسب المستودع واسم Chart وصيغة from_version المنظفة. اختبر الترتيب الفعلي في سلاسل مثل 1.9 و1.10.

تُفصل المسارات بنقطة، مثل pack.spec.values.service.port. لكل entry سياق مستقل يحتوي على:

اختصر المسارات بإنشاء aliases في بداية migration:

- set:
    chart: !var pack.spec.chart
    values: !var pack.spec.values
    chart.autoUpgrade: !default-var true

تشير mapping أو list المقروءة عبر ‎!var‎ إلى البيانات الأصلية، ولذلك يبقى تغيير values.service.port داخل pack.spec.values. لا يكتب متغير مؤقت مثل old_port في المخرجات ولا ينتقل بين entries.

تعيد قراءة مسار غائب null. وينشئ المسار المكتوب mappings الوسطية الغائبة، لكن تُتجاهل كتابة null.

إذا احتوى key على نقطة فعلية، استخدم ‎\.‎ وضع المسار كله بين علامتي اقتباس مفردتين:

- set:
    copied: !var 'values.annotations.example\.com/key'
    'values.annotations.example\.com/key': enabled

الجزء الرقمي من المسار ليس index في list. استخدم item_in_list لقراءة عنصر list أو تغييره.

كل عنصر في steps هو step. تنفذ العمليات دائما بهذا الترتيب:

1. شرط if أو فرع else.
2. البحث عبر item_in_list.
3. التعيين عبر set.
4. تنفيذ steps المتداخلة.
5. الترتيب عبر reorder.

اجعل كل step صغيرا. اجمع عدة عمليات في step واحدة فقط إذا كان ترتيب تنفيذها الثابت مطلوبا، مثل العثور على عنصر list قبل تغييره عبر set.

تستبدل القيمة من دون tag الهدف. للحفاظ على اختيار المستخدم، اقرأ key القديم بـ ‎!pop‎ واضبط القيمة الافتراضية للهدف بـ ‎!default-var‎. استخدم ‎!default‎ لقيمة جديدة لا يجب أن تستبدل قيمة موجودة، حتى إذا كانت false أو صفرا أو فارغة.

لا تستخدم ‎!pop-empty‎ لنقل البيانات. فهي تحذف قيمة falsey فقط، وتكتب false في الهدف عندما لا يُحذف شيء. استخدم أسماء مؤقتة ونظف من المسار الأعمق إلى الأب:

- set:
    _: !pop values.deprecatedOption
    _1: !pop-empty values.legacy.child
    _2: !pop-empty values.legacy

مع ‎!merge‎ يجب أن يكون المصدر والهدف mappings. أنشئ الهدف أولا بـ ‎!default‎ إذا كان قد لا يوجد.

يمكن لـ ‎!jinja‎ إنتاج boolean أو رقم أو list أو mapping. استخدم filter باسم default أو d للمسار الاختياري؛ الوصول المباشر إلى متغير غير معرّف يوقف migration بخطأ.

يحوّل الشرط البسيط قيمة المسار إلى boolean. يعكس ‎!not‎ النتيجة، ويستخدم ‎!jinja‎ للمقارنة أو الشرط المركب:

- if: values.ingress.enabled
  set:
    values.ingress.className: !default nginx

- if: !not values.persistence.enabled
  set:
    _: !pop values.persistence

- if: !jinja '{{ values.mode | d("standard") == "legacy" }}'
  steps:
    - set:
        values.mode: standard
  else:
    - set:
        values.mode: !default standard

يجب أن يكون else بجانب if ويحتوي على قائمة steps. إذا لم يتحقق الشرط، تنفذ steps في else فقط وتُتجاهل العمليات الأخرى في step الخارجية.

يجد item_in_list mapping داخل list عبر key وvalue أو عبر index، ويحفظ العنصر في المتغير المؤقت var:

- set:
    values.service.ports: !default []

- item_in_list:
    list: values.service.ports
    key: name
    value: http
    create: true
    var: http_port
  set:
    http_port.port: !default 6379
    http_port.protocol: !default TCP

أنشئ list أولا عبر ‎!default []‎، وإلا فقد يُضاف العنصر إلى list مؤقتة غير مرتبطة بـ Pack.

لا يمكن استخدام key وindex معا. يسبب index خارج النطاق خطأ. من دون create: true، لا يأخذ var قيمة إذا لم يوجد عنصر؛ احم steps اللاحقة بـ if. تقبل value قيمة ثابتة أو ‎!var‎ أو ‎!pop‎ فقط.

ينقل reorder المفاتيح المحددة إلى بداية mapping موجودة حسب الترتيب المطلوب. تبقى المفاتيح الأخرى بعدها. يغير ذلك قراءة YAML فقط ولا يغير سلوك Helm.

- reorder:
    pack.spec.values:
      - global
      - service
      - ingress
    pack.spec.values.service:
      - enabled
      - type
      - ports

kubit pack migrate -f redis.pack.yaml \
  --local-chartpath ./redis

يعرض الأمر الملف الناتج في stdout. قارنه بالإدخال وتأكد من تغير الإصدار والمسارات المطلوبة فقط. تُطبّع المخرجات وقد يُحذف spec.managed: true؛ غياب spec.managed يعادل true.

اختبر لكل مسار:

1. أقدم إصدار مدعوم وحدي البداية والنهاية لكل from_version.
2. Pack قبل كل migration وسطية وPack يمر بالسلسلة كاملة.
3. قيم المستخدم المخصصة وfalse والصفر والقيمة الفارغة والحقل الاختياري الغائب.
4. عنصر list موجود وغائب وindex غير صالح.
5. التشغيل مرة ثانية، ويجب ألا ينشئ تغييرا جديدا خاصا بـ migration.
6. معالجة Chart الهدف أو diff باستخدام الملف الناتج.

راجع التغيير الدلالي في values بالإضافة إلى diff النصي. قد يظهر ترتيب الحقول وتنظيف metadata حتى إذا لم تعرفه steps مباشرة.

kubit pack migrate -f redis.pack.yaml \
  --local-chartpath ./redis \
  --inline

يغير ‎--inline‎ ملف الإدخال. احتفظ بالإصدار السابق في Git وتحقق من المسار. راجع مرجع pack migrate لاختيار الهدف أو تشغيله على Pack في cluster.

في الترقية التلقائية، يفحص Pack Operator migration المطابقة. إذا أنتجت تغييرا صالحا، يُستبدل ملف Pack بالنتيجة. إذا لم توجد أو فشلت، تستمر الترقية العادية؛ لا يضمن خطأ migration توقف الترقية.

• إمكانات Pack في Helm Chart
• مرجع pack migrate في kubit-cli
• الترقية التلقائية في Pack Operator
• تحديد إصدار Chart في Pack