قابلیت‌های Pack در چارت هلم

نویسندهٔ چارت هلم می‌تواند با دو فایل اختیاری، چارت را برای استفاده با Pack غنی‌تر کند. pack-metadata.yaml خروجی‌های قابل استفادهٔ Pack را تعریف می‌کند و pack-migrations.yaml تغییر مانیفست Pack هنگام ارتقای چارت را مدیریت می‌کند.

این دو فایل در ریشهٔ چارت و کنار Chart.yaml و values.yaml قرار می‌گیرند. نبودن آن‌ها مانع نصب چارت با Pack نمی‌شود؛ فقط قابلیت مرتبط در دسترس نخواهد بود.

برای ساختار استاندارد چارت، هلم و چارت هلم در کوبرنتیز را ببینید. این صفحه فقط قراردادهایی را توضیح می‌دهد که Pack Operator و kubit-cli مستقیماً مصرف می‌کنند.

بخش exports در pack-metadata.yaml اطلاعاتی را تعریف می‌کند که کاربر یا ابزارهای کوبیت می‌توانند از یک Pack بخوانند. نسخهٔ اپلیکیشن، image نهایی، نشانی سرویس و مقدارهای عملیاتی نمونه‌های رایج هستند.

exports:
  image_repository: '{{ values.image.repository }}'
  image_tag: '{{ values.image.tag }}'
  image: '{{ exports.image_repository }}:{{ exports.image_tag }}'

  app_version:
    value: '{{ exports.image_tag }}'
    metric: true
    status: true

  endpoint:
    value: '{{ metadata.name }}.{{ metadata.namespace }}:{{ values.service.port }}'
    status: true

هر export می‌تواند یک مقدار ساده باشد یا با فیلد value و گزینه‌های تکمیلی تعریف شود. exportها به‌صورت بازگشتی رندر می‌شوند؛ بنابراین یک export می‌تواند مانند image در نمونهٔ بالا به exportهای دیگر ارجاع دهد.

Templateهای pack-metadata.yaml از همان نحو Jinja مورد استفاده در Pack استفاده می‌کنند. زمینه‌های در دسترس عبارت‌اند از:

وقتی کل value یک عبارت template باشد، نوع مقدار حفظ می‌شود. اگر template بخشی از یک رشتهٔ بزرگ‌تر باشد، نتیجه رشته خواهد بود. ارجاع حلقه‌ای میان exportها یا ارجاع به مسیر تعریف‌نشده می‌تواند خطای رندر ایجاد کند.

هر export باید مقدار خود را از یکی از این منابع بگیرد:

exports:
  redis_password:
    secretKeyRef:
      name: '{{ metadata.name }}'
      key: redis-password
    sensitive: true
    optional: false

  config_mode:
    configMapKeyRef:
      name: '{{ metadata.name }}-config'
      key: mode

  service_cluster_ip:
    genericRef:
      apiVersion: v1
      kind: Service
      name: '{{ metadata.name }}'
      valueFrom: spec.clusterIP

در genericRef، فیلد valueFrom مسیر مقدار داخل منبع را مشخص می‌کند. نام منبع و مسیر می‌توانند ثابت یا templateشده باشند. هویت اجراکننده باید مجوز خواندن منبع مقصد را داشته باشد.

اگر optional: false باشد، پیدا نشدن منبع یا کلید باعث شکست رندر metadata می‌شود. در حالت پیش‌فرض، kubit pack exports خطاهای exportها را در خروجی ‎__errors__‎ گزارش می‌کند.

علامت sensitive مقدار را رمزنگاری یا پنهان نمی‌کند. قالب‌های dict و list در kubit-cli این علامت را همراه خروجی برمی‌گردانند، اما کنترل دسترسی به Pack، Secret و خروجی فرمان همچنان ضروری است. مقدار حساس را در log، pipeline یا مخزن گیت ثبت نکنید.

kubit pack exports -f redis.pack.yaml \
  --local-chartpath ./redis \
  --output dict

برای جزئیات قالب‌های خروجی، خواندن خروجی‌های Pack با kubit-cli را ببینید.

فایل اختیاری pack-migrations.yaml تغییرهای لازم در مانیفست Pack را هنگام ارتقای نسخهٔ چارت تعریف می‌کند. هر migration با نام repository، نام چارت و نسخهٔ مبدأ انتخاب می‌شود، spec.chart.version را به نسخهٔ مقصد می‌رساند و در صورت نیاز vars یا values را تبدیل می‌کند.

Pack Operator این فایل را از چارت مقصد می‌خواند. به همین دلیل، چارت مقصد باید زنجیرهٔ کامل migration از همهٔ نسخه‌های قدیمی پشتیبانی‌شده را همراه داشته باشد. نبود این فایل مانع نصب چارت نمی‌شود، اما تغییر ناسازگار ساختار مقادیر می‌تواند انتخاب‌های پک‌های قدیمی را نامعتبر کند.

برای ساخت فایل، انتخاب بازه‌های نسخه، استفاده از stepها و tagها و آزمون migration، راهنمای مهاجرت Pack بین نسخه‌های چارت را بخوانید.

گزینهٔ ‎--local-chartpath‎ اجازه می‌دهد چارت محلی را بدون تغییر repository معرفی‌شده در Pack آزمایش کنید. برای این آزمون به یک مانیفست Pack نیاز دارید تا metadata، vars و values زمینهٔ واقعی رندر را بسازند.

kubit helm-template -f redis.pack.yaml \
  --local-chartpath ./redis

kubit helm-diff -f redis.pack.yaml \
  --local-chartpath ./redis

kubit pack exports -f redis.pack.yaml \
  --local-chartpath ./redis \
  --output dict

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

1. با helm-template معتبر بودن خروجی هلم را بررسی کنید.
2. با helm-diff تغییر منابع نسبت به Helm Release موجود را ببینید.
3. با pack exports همهٔ exportها، خطاها و علامت حساس‌بودن را بررسی کنید.
4. با pack migrate هر مسیر ارتقای پشتیبانی‌شده را روی نمونهٔ نسخهٔ قدیمی اجرا کنید.

فرمان helm-upgrade نیز چارت محلی را می‌پذیرد، اما Helm Release را مستقیماً تغییر می‌دهد. آن را بخشی از آزمون اولیه در نظر نگیرید و پیش از استفاده، هشدار اجرای مستقیم Helm upgrade را بخوانید.

1. خروجی helm-template را برای Packهای نمونه بررسی کنید.
2. تغییر منابع را با helm-diff بازبینی کنید.
3. exportهای ساده، بازگشتی، اختیاری و حساس را با pack exports آزمایش کنید.
4. دسترسی لازم برای secretKeyRef، configMapKeyRef و genericRef را محدود نگه دارید.
5. تغییر ساختار values را فقط همراه migration سازگار و پس از اجرای چک‌لیست آزمون migration منتشر کنید.

• مرجع Pack و مانیفست آن
• مفاهیم هلم و ساختار چارت
• مرجع فرمان‌های kubit-cli
• چرخهٔ ارتقای خودکار در Pack Operator