ما Pack؟

Pack هو مورد Kubernetes مخصص لتثبيت Helm Chart وإدارته. تحدد Chart والإصدار والقيم في ملف Pack، ويحافظ Pack Operator على توافق الحالة الفعلية في cluster مع هذا التعريف.

إذا لم تكن مفاهيم Helm مألوفة لك، اقرأ Helm وHelm Chart في Kubernetes أولا.

يثبت معظم المستخدمين Packs ويديرونها من Kubchi > Packs في لوحة Kubit. هذه الصفحة مرجع المورد نفسه عند العمل باستخدام YAML أو kubectl أو GitOps أو kubit-cli. للتثبيت من اللوحة، راجع تثبيت Pack في Kubchi.

يحتوي Helm Chart على templates التطبيق وقيمه الافتراضية. يحدد Pack ملف Chart وإصداره وإعداداته في namespace. يقرأ Pack Operator هذا التعريف ويتحقق من مخرجات Helm ويطبقها ويسجل النتيجة في حالة Pack.

يرتبط كل Pack بـ Helm Release في namespace نفسه. وقد يؤدي تغيير spec إلى ترقية Release. افحص المخرجات قبل تغيير production باستخدام kubit helm-diff.

للعمل مباشرة مع ملف Pack تحتاج إلى:

• الوصول إلى cluster يحتوي على Pack Operator.
• صلاحية قراءة Pack أو تغييره في namespace الهدف.
• مورد ClusterPackRepository متاحا ويوفر Chart المطلوب.
• صلاحية قراءة الموارد المشار إليها في قيم Chart.

عند استخدام Kubchi فقط، تجهز Kubit كثيرا من هذه المتطلبات للمشروع.

يثبت المثال التالي Redis Chart من المستودع العام kubit-paas في namespace باسم my-project. طابق الإصدار وبنية values مع توثيق Chart.

apiVersion: k8s.kubit.ir/v1alpha1
kind: Pack
metadata:
  name: redis
  namespace: my-project
spec:
  managed: true
  chart:
    repository:
      kind: ClusterPackRepository
      name: kubit-paas
    name: redis
    version: '0.1.6'
    autoUpgrade: false
  vars: {}
  values: {}

الحقل spec.managed اختياري. غيابه يعادل spec.managed: true، وفي الحالتين يدير Pack Operator المورد. توقف القيمة الصريحة spec.managed: false الإدارة. يذكر المثال managed: true بوضوح.

الحقول الرئيسية هي:

يُعرّف PackRepository داخل namespace ولا تستخدمه إلا Packs في namespace نفسه. استخدمه عندما يكون المستودع مخصصا لمشروع أو بيئة واحدة.

يُعرّف ClusterPackRepository على مستوى cluster، ويمكن لـ Packs في namespaces مختلفة استخدامه مع الصلاحية المطلوبة. لا يعني النطاق العام أن بيانات الدخول عامة؛ قيّد الوصول إلى اسم المستخدم وكلمة المرور.

يقبل spec.chart.version إصدارا دقيقا أو قيدا. يرشح Pack Operator إصدارات المستودع ويختار أعلى إصدار مطابق. ضع القيمة بين علامتي اقتباس حتى يعاملها YAML كنص.

تشمل المعاملات ‎==‎ و‎!=‎ و‎~=‎ و‎<‎ و‎<=‎ و‎>‎ و‎>=‎. يجب أن تتحقق كل الشروط المفصولة بفاصلة. لا تستخدم صيغا مثل ‎^1.2.3‎ أو 1.x || 2.x لأنها تخص مديري حزم آخرين.

إذا غاب version، يستخدم أعلى إصدار متاح. لا يفعّل القيد وحده الترقية التلقائية؛ يلزم أيضا autoUpgrade: true وautoUpgradeDelay صالح وإصدار غير دقيق. لا يدخل إصدار ثابت مثل ‎'0.1.6'‎ قائمة الترقية.

يحفظ spec.values القيم التي تتجاوز افتراضيات Chart. يجب أن يطابق اسم كل key ونوعه ملف values.yaml أو توثيق Chart.

spec:
  values:
    replicaCount: 2
    service:
      port: 6379

يعالج Pack Operator templates داخل spec.values ثم يرسل القيم النهائية إلى Helm. لا تنسخ بنية values كاملة لتغيير خيار واحد؛ اكتب القيم المختلفة عن افتراضيات Chart فقط لتسهيل مراجعة التغيير والترقية.

يمكن للنصوص داخل spec.values استخدام Jinja. تنتج تعبيرات ‎{{ ... }}‎ قيما، وتوفر كتل ‎{% ... %}‎ منطق القالب. السياقات الرئيسية هي:

spec:
  vars:
    IMAGE_TAG: '7.4'
  values:
    replicaCount: 2
    metrics:
      enabled: true
    image:
      tag: '{{ vars.IMAGE_TAG }}'
    instanceName: '{{ metadata.name }}'
    service:
      port: 6379
      targetPort: '{{ values.service.port }}'
    redisUrl: 'redis://{{ metadata.name }}:{{ values.service.port }}'

تأتي image.tag من vars.IMAGE_TAG، بينما تقرأ service.targetPort وجزء من redisUrl قيمة values.service.port. يمكن لـ templates الرجوع إلى قيم أخرى بالإضافة إلى vars.

إذا كانت القيمة كلها تعبير template واحدا، يبقى نوع النتيجة محفوظا؛ فيبقى replicaCount رقما وmetrics.enabled قيمة boolean. وإذا كان التعبير جزءا من نص أكبر، تكون النتيجة نصا.

المعالجة تكرارية، ولذلك يمكن لقيمة الرجوع إلى أخرى ولا يهم ترتيب keys. يؤدي متغير غير معرّف أو دورة مثل a -> b -> a إلى خطأ validation.

من filters المفيدة:

• to_bool وto_str لتحويل النوع.
• split لتحويل النص إلى list.
• to_base64 وfrom_base64.
• to_json وfrom_json وto_yaml وfrom_yaml.
• ternary لاختيار قيمة حسب شرط.
• to_scalar لتحويل كمية Kubernetes مثل CPU أو memory إلى رقم.

يمكن مثلا تحويل النص ‎"true"‎ إلى boolean باستخدام ‎'{{ vars.ENABLED | to_bool }}'‎.

يفصل spec.vars مدخلات template عن بنية Chart. لا يغيّر تعريف var وحده مخرجات Helm؛ استخدمه في spec.values بتعبير مثل ‎{{ vars.IMAGE_TAG }}‎.

spec:
  vars:
    IMAGE_TAG: '7.4'
  values:
    image:
      tag: '{{ vars.IMAGE_TAG }}'

يدمج Pack Operator المتغيرات من organization وproject وPack. ترتيب الأولوية من الأدنى إلى الأعلى:

1. متغيرات organization.
2. متغيرات project.
3. spec.vars في Pack.

إذا تكرر الاسم، تحل القيمة الأقرب إلى Pack محل السابقة. الأسماء حساسة لحالة الحروف. استخدم مستوى organization أو project للقيم المشتركة وspec.vars للاستثناءات الخاصة بالتثبيت.

يشفّر Vault النص الحساس قبل وضعه في الملف. أثناء المعالجة، يفك Pack Operator القيم المشفرة في vars أو values باستخدام Vault key في namespace نفسه.

printf '%s' "$VAULT_PASSWORD" | kubit -n my-project vault create \
  --vault-id app-vault \
  --vault-password-stdin

printf '%s' "$REDIS_PASSWORD" | kubit -n my-project vault encrypt \
  --vault-id app-vault

ضع مخرجات الأمر الثاني كاملة في var واستخدمها في values. يوضح المثال شكل البيانات فقط، ويجب استبدال ENCRYPTED_PAYLOAD بالمخرجات الحقيقية:

spec:
  vars:
    REDIS_PASSWORD: |
      $KUBIT_VAULT;1.2;AES256;app-vault
      ENCRYPTED_PAYLOAD
  values:
    auth:
      password: '{{ vars.REDIS_PASSWORD }}'

يجب أن يوجد Vault key في namespace نفسه، وأن تملك هوية التنفيذ أو Pack Operator صلاحية قراءته. لا تسجل النص بعد فكّه في الملف أو Git أو CI logs أو تذاكر الدعم. وقيّد أيضا الوصول إلى Secrets الخاصة بـ Helm Release والموارد التي ينشئها Chart.

استخدم أوامر Vault في kubit-cli للإنشاء والعرض والتشفير. وللعمل من اللوحة، راجع إدارة Vault في Kubchi (بالإنجليزية).

عند غياب spec.managed، يعامله Pack Operator كقيمة true. لإيقاف reconciliation مؤقتا، اكتب false بوضوح:

spec:
  managed: false

يتوقف المشغّل عن validation والتطبيق والترقية التلقائية، وتصبح المرحلة Unmanaged. لا تتوقف workloads الحالية ولا يُحذف Helm Release. تعيد القيمة true توفيق الحالة مع spec.

هذا الخيار يوقف الإدارة مؤقتا ولا يصلح الأخطاء. قد تبتعد التغييرات اليدوية عن الملف وتُستبدل بعد إعادة التفعيل. يختلف سلوك الحذف أيضا؛ اقرأ حذف Pack أولا.

يمكن لمؤلف Chart تعريف مخرجات Pack في pack-metadata.yaml. توجد البنية الكاملة في تعريف Pack exports. ليست هذه المخرجات جزءا من spec، وقد تعرض إصدار التطبيق أو عنوان الخدمة أو image أو استهلاك الموارد أو قيمة مولدة. ويمكن أيضا قراءة القيمة من Secret أو ConfigMap أو مورد آخر في namespace نفسه.

لا تُحفظ في status.exports إلا المخرجات المعلمة للحالة. استخدم kubit pack exports لرؤية كل المخرجات. صيغة simple للعرض السريع، وdict وlist للبيانات المنظمة.

قد تكون بعض المخرجات حساسة. تعرّف العلامة الأداة المستهلكة بحساسية المخرجات لكنها لا تستبدل التحكم في الوصول. لا تحفظ المخرجات الحساسة في logs أو pipeline أو ticket أو Git.

تتوفر metadata.name وmetadata.namespace وlabels وannotations داخل template لبناء أسماء أو إعدادات مرتبطة بالبيئة. حافظ على ثبات الأسماء وannotations التشغيلية ووثّقها لتجنب السلوك غير المقصود.

إذا اعتمد Pack على Secret أو ConfigMap، صرّح بالتبعية عبر annotation إعادة التشغيل. للعمليات اليدوية استخدم force-upgrade وrollout-restart، ولا تعدل annotations الداخلية للمشغّل مباشرة.

kubectl apply -f redis.pack.yaml

ثم افحص الحالة والأحداث:

kubectl -n my-project get pack redis
kubectl -n my-project describe pack redis

تستخدم النتيجة الناجحة مرحلة Applied. المراحل الرئيسية:

• Applied: طُبقت الحالة المطلوبة.
• Failed: فشل validation أو التطبيق.
• Unmanaged: spec.managed معطل ولا يغير المشغّل Pack.

حقول الحالة الرئيسية:

بقاء status.desired مع Failed يوضح الإصدار والإعدادات التي حاول المشغّل الوصول إليها. قارنه مع status.current. كل حقول status مخرجات للمشغّل ولا تُعدّل يدويا.

يمكن أن يوفر Chart قواعد migration في pack-migrations.yaml. راجع migration بين إصدارات Chart لإنشاء الملف. تُختار migration حسب المستودع واسم Chart وإصداري المصدر والهدف، ويمكنها تحويل الإصدار أو vars أو values.

قبل الترقية اليدوية، اعرض النتيجة باستخدام kubit pack migrate وراجع diff وسجل التغيير في الملف الأصلي أو Git فقط. يغير الخيار ‎--inline‎ ملف الإدخال، ولذلك استخدمه على ملف ذي version control أو نسخة قابلة للاستعادة.

في الترقية التلقائية، يفحص المشغّل migration المطابقة أولا. إذا لم توجد أو فشلت، تستمر الترقية العادية. اختبر migration قبل نشر Chart ولا تعتمد على فشلها لإيقاف الترقية.

عدّل spec.vars أو spec.values ثم طبق الملف مرة أخرى. يتحقق Pack Operator من التغيير ثم يحدّث Helm Release.

لتسجيل تغييرات production في Git، احفظ الملف في مستودع واستخدم Kubchi GitOps (بالإنجليزية). هذه الميزة اختيارية. توجد قواعد عرض تحويل الإصدار في migration بين إصدارات Chart.

تعمل الترقية التلقائية فقط إذا فُعّلت في المشغّل وكانت autoUpgrade تساوي true وكانت autoUpgradeDelay صالحة ولم يكن إصدار Chart دقيقا. بعد نشر إصدار متوافق وانقضاء المدة، يفحص المشغّل migrations وينفذ الترقية.

عندما تكون spec.managed بقيمة true، يبدأ حذف Pack إزالة Helm Release وموارده:

kubectl -n my-project delete pack redis

افحص البيانات الدائمة وسياسة الاحتفاظ بالvolumes قبل الحذف. عندما تكون spec.managed بقيمة false، لا يزيل حذف Pack موارد Helm Release. للحذف المُدار، أعد managed إلى true وانتظر مرحلة Applied ثم احذف المورد. لا تحذف Pack غير المُدار مباشرة إلا إذا كنت ستدير Release المتبقي خارج Pack.

لا تزل finalizer يدويا لفرض الحذف، فقد تبقى موارد Helm بلا مالك. إذا لم يكتمل الحذف، افحص الأحداث وstatus.error ثم تواصل مع دعم Kubit.

• Helm وHelm Chart
• إضافة إمكانات Pack إلى Chart
• إنشاء Pack migration واختبارها
• تثبيت Pack وإدارته في Kubchi
• تعديل إعداد Pack في Kubchi (بالإنجليزية)
• إدارة تغييرات Pack باستخدام GitOps (بالإنجليزية)
• تشفير البيانات باستخدام Vault (بالإنجليزية)
• سلوك Pack Operator
• إعادة تشغيل Pack بعد تغيير Secret أو ConfigMap
• قراءة Pack exports باستخدام kubit-cli
• استخدام Pack عبر kubit-cli