پک (Pack) چیست؟

پک (Pack) یک منبع سفارشی کوبرنتیز برای نصب و مدیریت چارت هلم (Helm Chart) است. شما چارت، نسخه و مقادیر دلخواه را در مانیفست پک تعریف می‌کنید و پک اپراتور وضعیت واقعی کلاستر را با این تعریف هماهنگ نگه می‌دارد.

اگر با مفاهیم هلم آشنا نیستید، ابتدا هلم و چارت هلم در کوبرنتیز را بخوانید.

بیشتر کاربران پک‌ها را از بخش کوبچی > پک‌ها در پنل کوبیت نصب و مدیریت می‌کنند. این صفحه مرجع فنی همان منبع است و برای کار با فایل YAML، kubectl، گیت‌آپس یا kubit-cli کاربرد دارد. برای نصب از پنل، نصب پک در کوبچی را ببینید.

چارت هلم قالب‌ها و مقادیر پیش‌فرض یک اپلیکیشن را در خود دارد. پک مشخص می‌کند کدام چارت با چه نسخه و تنظیماتی در یک فضای نام نصب شود. پک اپراتور این تعریف را می‌خواند، خروجی هلم را اعتبارسنجی و اعمال می‌کند و نتیجه را در وضعیت پک می‌نویسد.

هر پک به یک Helm Release در همان فضای نام مربوط است. تغییر spec پک می‌تواند باعث ارتقای همان انتشار شود؛ بنابراین پیش از اعمال تغییر در محیط عملیاتی، خروجی را با kubit helm-diff بررسی کنید.

برای کار مستقیم با مانیفست پک به این موارد نیاز دارید:

• دسترسی به یک کلاستر دارای پک اپراتور؛
• مجوز خواندن یا تغییر Pack در فضای نام مقصد؛
• یک ClusterPackRepository قابل دسترس که چارت مورد نظر را ارائه کند؛
• مجوز خواندن منابع وابسته‌ای که در مقادیر چارت به آن‌ها ارجاع می‌دهید.

اگر فقط از پنل کوبچی استفاده می‌کنید، کوبیت بخش زیادی از این پیش‌نیازها را برای پروژه آماده می‌کند.

نمونه زیر چارت Redis را از مخزن سراسری kubit-paas در فضای نام my-project نصب می‌کند. نسخه و ساختار values را با مستندات همان چارت تطبیق دهید.

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 تلقی می‌شود؛ در هر دو حالت پک توسط پک اپراتور مدیریت خواهد شد. فقط مقدار صریح spec.managed: false مدیریت اپراتور را متوقف می‌کند. در نمونهٔ بالا، managed: true برای شفاف‌بودن این رفتار نوشته شده است.

فیلدهای اصلی مانیفست عبارت‌اند از:

PackRepository در یک فضای نام تعریف می‌شود و پک همان فضای نام می‌تواند از آن استفاده کند. این نوع برای مخزنی مناسب است که فقط یک پروژه یا محیط باید به آن دسترسی داشته باشد.

ClusterPackRepository در سطح کلاستر تعریف می‌شود و با داشتن مجوز مناسب، پک‌های فضاهای نام مختلف می‌توانند از آن استفاده کنند. سراسری‌بودن دامنه منبع به معنی عمومی‌بودن اطلاعات ورود مخزن نیست؛ نام کاربری و رمز مخزن باید همچنان با دسترسی محدود نگهداری شوند.

فیلد spec.chart.version می‌تواند یک نسخهٔ دقیق یا محدودیت نسخه باشد. پک اپراتور فهرست نسخه‌های چارت را با این محدودیت فیلتر می‌کند و بالاترین نسخهٔ منطبق را انتخاب می‌کند. مقدار نسخه را داخل کوتیشن بنویسید تا YAML آن را رشته در نظر بگیرد.

عملگرهای پرکاربرد شامل ‎==‎، ‎!=‎، ‎~=‎، ‎<‎، ‎<=‎، ‎>‎ و ‎>=‎ هستند. شرط‌هایی که با ویرگول جدا می‌شوند هم‌زمان باید برقرار باشند. از نحوهایی مانند ‎^1.2.3‎ یا 1.x || 2.x استفاده نکنید؛ این نحوها متعلق به مدیرهای بستهٔ دیگر هستند.

اگر version حذف شود، بالاترین نسخهٔ قابل انتخاب از مخزن استفاده می‌شود. محدودیت نسخه نیز به‌تنهایی ارتقای خودکار را فعال نمی‌کند. برای ارتقای خودکار باید autoUpgrade: true، یک autoUpgradeDelay معتبر و یک محدودیت غیردقیق داشته باشید. نسخهٔ ثابت مانند ‎'0.1.6'‎ وارد صف ارتقای خودکار نمی‌شود.

فیلد spec.values مقادیری را نگه می‌دارد که روی مقادیر پیش‌فرض چارت اعمال می‌شوند. نام و نوع هر کلید باید با values.yaml یا راهنمای همان چارت سازگار باشد.

در نمونهٔ زیر دو مقدار تو در تو برای چارت تنظیم شده‌اند:

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

پک اپراتور ابتدا templateهای داخل spec.values را رندر می‌کند و سپس مقادیر نهایی را به هلم می‌دهد. کل ساختار values را فقط برای تغییر یک گزینه کپی نکنید؛ مقدارهایی را بنویسید که واقعاً باید با پیش‌فرض چارت متفاوت باشند. این کار بازبینی تغییر و ارتقای چارت را ساده‌تر می‌کند.

رشته‌های داخل 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 را می‌خوانند. بنابراین templateها می‌توانند علاوه بر vars به مقدارهای دیگر همان values نیز ارجاع دهند.

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

رندر بازگشتی است؛ بنابراین یک مقدار می‌تواند به مقدار دیگری ارجاع دهد و ترتیب کلیدها در فایل مهم نیست. ارجاع به متغیر تعریف‌نشده یا ساختن چرخه‌ای مانند a -> b -> a باعث خطای اعتبارسنجی می‌شود.

چند فیلتر کاربردی عبارت‌اند از:

• to_bool و to_str برای تبدیل نوع؛
• split برای تبدیل یک رشته به فهرست؛
• to_base64 و from_base64؛
• to_json، from_json، to_yaml و from_yaml؛
• ternary برای انتخاب مقدار بر اساس یک شرط؛
• to_scalar برای تبدیل کمیت کوبرنتیز، مانند CPU یا حافظه، به مقدار عددی.

برای نمونه، رشتهٔ ‎"true"‎ را می‌توان با ‎'{{ vars.ENABLED | to_bool }}'‎ به مقدار boolean تبدیل کرد.

فیلد spec.vars ورودی‌های قابل استفاده در template را از جزئیات ساختار چارت جدا می‌کند. تعریف یک var به‌تنهایی چیزی را در هلم تغییر نمی‌دهد؛ باید آن را در spec.values با عبارتی مانند ‎{{ vars.IMAGE_TAG }}‎ مصرف کنید.

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

پک اپراتور متغیرهای تعریف‌شده در سطح سازمان، پروژه و پک را ترکیب می‌کند. ترتیب تقدم از کم به زیاد چنین است:

1. متغیر سازمان؛
2. متغیر پروژه؛
3. spec.vars همان پک.

اگر یک نام در چند سطح تکرار شود، مقدار نزدیک‌تر به پک جای مقدار قبلی را می‌گیرد. نام متغیرها به بزرگی و کوچکی حروف حساس است. برای متغیرهای مشترک محیط از سطح سازمان یا پروژه و برای استثناهای همان نصب از spec.vars استفاده کنید.

Vault متن حساس را پیش از قرارگرفتن در مانیفست رمزنگاری می‌کند. پک اپراتور هنگام رندر، مقدارهای رمزنگاری‌شده در vars یا values را با کلید Vault همان فضای نام رمزگشایی می‌کند.

ابتدا Vault را در فضای نام پک بسازید و مقدار حساس را رمزنگاری کنید:

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 باید در همان فضای نام پک وجود داشته باشد و هویت اجراکننده یا پک اپراتور مجوز خواندن آن را داشته باشد. متن رمزگشایی‌شده را در مانیفست، گیت، لاگ CI یا تیکت پشتیبانی ثبت نکنید. پس از رندر، مقدار برای نصب هلم استفاده می‌شود؛ بنابراین دسترسی به Secretهای انتشار هلم و منابع ساخته‌شده توسط چارت را نیز محدود نگه دارید.

برای ساخت، فهرست‌کردن و رمزنگاری از دستورهای Vault در kubit-cli استفاده کنید. اگر با پنل کار می‌کنید، مدیریت Vault در کوبچی را ببینید.

اگر spec.managed در مانیفست وجود نداشته باشد، پک اپراتور آن را معادل true در نظر می‌گیرد و پک را مدیریت می‌کند. برای توقف موقت reconciliation باید مقدار false را به‌صورت صریح بنویسید:

spec:
  managed: false

در این حالت اپراتور اعتبارسنجی، اعمال تغییر و ارتقای خودکار را متوقف می‌کند و فاز پک Unmanaged می‌شود. این تغییر workloadهای در حال اجرا را متوقف نمی‌کند و Helm Release موجود را نیز حذف نمی‌کند. با برگرداندن مقدار به true، اپراتور وضعیت پک را دوباره با spec هماهنگ می‌کند.

از این گزینه برای توقف آگاهانه و موقت مدیریت استفاده کنید، نه برای رفع خطا. هنگام غیرفعال‌بودن مدیریت، تغییرهای دستی بیرون از پک ممکن است با مانیفست فاصله بگیرند و پس از فعال‌سازی دوباره بازنویسی شوند. رفتار حذف پک در این وضعیت نیز متفاوت است؛ پیش از حذف، بخش حذف پک را بخوانید.

نویسندهٔ چارت می‌تواند خروجی‌های قابل استفادهٔ پک را در فایل pack-metadata.yaml تعریف کند. ساختار کامل این فایل در تعریف خروجی‌های Pack در چارت آمده است. این خروجی‌ها بخشی از spec پک نیستند و ممکن است اطلاعاتی مانند نسخهٔ اپلیکیشن، آدرس سرویس، نام image، مصرف منابع یا یک مقدار تولیدشده را نمایش دهند. تعریف چارت همچنین می‌تواند مقدار خروجی را از یک Secret، ConfigMap یا منبع دیگر در همان فضای نام بخواند.

فقط خروجی‌هایی که در metadata چارت برای نمایش در وضعیت علامت‌گذاری شده‌اند، در status.exports قرار می‌گیرند. برای دیدن همهٔ خروجی‌های تعریف‌شده از kubit pack exports استفاده کنید. قالب simple برای مشاهدهٔ سریع و قالب‌های dict و list برای پردازش ساخت‌یافته مناسب‌اند.

برخی خروجی‌ها حساس هستند. علامت حساس‌بودن به ابزارها کمک می‌کند نمایش یا پردازش مناسب‌تری داشته باشند، اما جایگزین کنترل دسترسی نیست؛ خروجی حساس را در لاگ، pipeline، تیکت یا فایل گیت ثبت نکنید.

metadata.name، metadata.namespace، labelها و annotationهای پک در زمینهٔ template در دسترس‌اند و می‌توانند برای ساخت نام یا تنظیمات وابسته به محیط استفاده شوند. نام‌ها و annotationهای عملیاتی را ثابت و مستند نگه دارید تا تغییر آن‌ها رفتار ناخواسته ایجاد نکند.

اگر پک به Secret یا ConfigMap وابسته است، می‌توانید با annotation بازاستقرار هنگام تغییر منبع این وابستگی را صریح کنید تا اپراتور پس از تغییر منبع، rollout یا restart لازم را انجام دهد. برای اجرای دستی عملیات نیز از دستورهای force-upgrade و rollout-restart استفاده کنید و annotationهای داخلی اپراتور را مستقیماً تغییر ندهید.

مانیفست را با kubectl اعمال کنید:

kubectl apply -f redis.pack.yaml

سپس وضعیت و رویدادهای پک را بررسی کنید:

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

نتیجه موفق با فاز Applied ثبت می‌شود. فازهای اصلی عبارت‌اند از:

• Applied: وضعیت مورد انتظار پک اعمال شده است؛
• Failed: اعتبارسنجی یا اعمال پک با خطا روبه‌رو شده است؛
• Unmanaged: مقدار spec.managed غیرفعال است و اپراتور پک را تغییر نمی‌دهد.

فیلدهای اصلی وضعیت عبارت‌اند از:

باقی‌ماندن status.desired در کنار فاز Failed نشان می‌دهد اپراتور به کدام نسخه و تنظیمات می‌خواسته برسد. برای تشخیص اختلاف، آن را با status.current مقایسه کنید. همهٔ فیلدهای status خروجی اپراتور هستند و نباید دستی ویرایش شوند.

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

پیش از ارتقای دستی، نتیجه را با kubit pack migrate پیش‌نمایش کنید، diff را بازبینی کنید و فقط پس از اطمینان تغییر را در مانیفست اصلی یا مخزن گیت ثبت کنید. گزینهٔ ‎--inline‎ فایل ورودی را تغییر می‌دهد؛ بنابراین آن را روی فایل دارای نسخه یا یک کپی قابل بازیابی اجرا کنید.

در ارتقای خودکار، اپراتور ابتدا migration منطبق را بررسی می‌کند. اگر migration منطبق نباشد یا اجرای آن خطا بدهد، مسیر عادی ارتقای خودکار ادامه پیدا می‌کند؛ بنابراین migration را پیش از انتشار چارت آزمایش کنید و به شکست آن برای متوقف‌کردن ارتقا تکیه نکنید.

برای تغییر پیکربندی، spec.vars یا spec.values را ویرایش و مانیفست را دوباره اعمال کنید. پک اپراتور ابتدا تغییر را اعتبارسنجی می‌کند و سپس انتشار هلم را به‌روز می‌کند.

برای تغییرهای محیط عملیاتی، مانیفست را در مخزن گیت نگه دارید و از مسیر گیت‌آپس کوبچی استفاده کنید تا منبع تغییر مشخص بماند. قواعد و روش پیش‌نمایش تبدیل نسخه‌ها در بخش مهاجرت بین نسخه‌های chart توضیح داده شده است.

ارتقای خودکار فقط زمانی انجام می‌شود که قابلیت مربوط در اپراتور فعال باشد، autoUpgrade مقدار true داشته باشد، autoUpgradeDelay معتبر باشد و نسخه چارت به یک نسخه ثابت محدود نشده باشد. در این حالت اپراتور پس از انتشار نسخه تازه و سپری‌شدن تأخیر، مهاجرت‌های مرتبط را بررسی و سپس ارتقا را اجرا می‌کند.

وقتی spec.managed مقدار true دارد، حذف منبع پک، حذف انتشار هلم و منابع مدیریت‌شدهٔ آن را آغاز می‌کند:

kubectl -n my-project delete pack redis

پیش از حذف، وضعیت داده‌های پایدار و سیاست نگهداری ولوم‌های چارت را بررسی کنید. اگر spec.managed مقدار false داشته باشد، اپراتور هنگام حذف پک، Helm Release و منابع آن را uninstall نمی‌کند. برای حذف مدیریت‌شده، ابتدا managed را دوباره true کنید، تا رسیدن پک به فاز Applied صبر کنید و سپس منبع را حذف کنید. فقط زمانی پک unmanaged را مستقیماً حذف کنید که عمداً می‌خواهید مدیریت انتشار باقی‌مانده را خارج از پک ادامه دهید.

برای پایان‌دادن اجباری به حذف، finalizer پک را دستی پاک نکنید؛ این کار می‌تواند منابع هلم را بدون مالک باقی بگذارد. اگر حذف کامل نمی‌شود، رویدادها و status.error را بررسی و با پشتیبانی کوبیت تماس بگیرید.

• آشنایی با هلم و چارت هلم در کوبرنتیز
• افزودن قابلیت‌های Pack به چارت هلم
• ساخت و آزمون migration برای Pack
• نصب و مدیریت پک از پنل کوبچی
• ویرایش پیکربندی پک در کوبچی
• مدیریت تغییرات پک با گیت‌آپس
• رمزنگاری داده حساس با والت
• نقش و رفتار پک اپراتور
• بازاستقرار پک پس از تغییر Secret یا ConfigMap
• خواندن خروجی‌های Pack با kubit-cli
• کار با پک از طریق kubit-cli