پک اپراتور چیست؟

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

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

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

پک اپراتور می‌تواند قابلیت‌های دیگری مانند همگام‌سازی Secretها را نیز در کلاستر فعال کند. این صفحه فقط رفتارهای مرتبط با منبع Pack را پوشش می‌دهد.

با ساخت یا تغییر یک پک، اپراتور این جریان را اجرا می‌کند:

1. ساختار پک، مخزن، چارت، نسخه و مقادیر قابل رندر را بررسی می‌کند.
2. وضعیت مورد انتظار هلم را با انتشار موجود در کلاستر مقایسه می‌کند.
3. در صورت وجود تغییر، نصب یا ارتقای هلم را اجرا می‌کند.
4. نسخه دقیق چارت، شماره بازبینی هلم، نتیجه و خطا را در status پک می‌نویسد.
5. رویدادی مانند SuccessfulApply، AppliedWithErrors یا ApplyFailed روی منبع ثبت می‌کند.

اگر وضعیت واقعی و مورد انتظار یکسان باشند، اپراتور اجرای اضافه انجام نمی‌دهد و پک را در فاز Applied نگه می‌دارد. این رفتار باعث می‌شود اعمال دوباره همان مانیفست، انتشار تازه و غیرضروری نسازد.

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

فاز Failed یعنی اعتبارسنجی یا اعمال تغییر کامل نشده است. جزئیات خطا در status.error و رویدادهای منبع قرار می‌گیرند. در این وضعیت، status.desired می‌تواند نتیجه‌ای را نشان دهد که اپراتور قصد اعمال آن را داشته است.

فاز Unmanaged زمانی ثبت می‌شود که spec.managed: false باشد. اپراتور در این حالت پک را اعتبارسنجی، نصب یا ارتقا نمی‌دهد. این گزینه را فقط زمانی استفاده کنید که ابزار دیگری مالک انتشار هلم است و مسئولیت جلوگیری از اختلاف وضعیت را پذیرفته‌اید.

پک اپراتور پیش از پذیرش تغییر spec، خروجی هلم و دسترسی‌های لازم را بررسی می‌کند. اگر چارت پیدا نشود، نسخه با محدودیت تعیین‌شده سازگار نباشد، مقدار والت قابل رمزگشایی نباشد یا خروجی هلم معتبر نباشد، تغییر می‌تواند پیش از اعمال رد شود.

برای مشاهده اثر تغییر بدون نصب، از kubit helm-template استفاده کنید. برای مقایسه با انتشار موجود نیز kubit helm-diff مناسب است.

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

spec:
  chart:
    version: '~=1.4'
    autoUpgrade: true
    autoUpgradeDelay: 1h

اپراتور با تازه‌شدن فهرست مخزن، نسخه سازگار جدید را پیدا می‌کند. نسخه‌های ثابت وارد صف ارتقای خودکار نمی‌شوند. مقدار تأخیر می‌تواند از ترکیب روز، ساعت، دقیقه و ثانیه ساخته شود؛ مانند 1d2h30m.

اگر چارت فایل pack-migrations.yaml داشته باشد، اپراتور مهاجرت‌های منطبق را پیش از مسیر عادی ارتقا روی تعریف پک اعمال می‌کند. اگر مهاجرت خودکار خطا بدهد، خطا در لاگ ثبت می‌شود و مسیر عادی ارتقا ادامه پیدا می‌کند؛ بنابراین تغییر نسخه حساس را ابتدا با kubit pack migrate بررسی کنید. برای طراحی زنجیره و تبدیل مقادیر، راهنمای مهاجرت Pack را بخوانید.

برای اعمال دوباره انتشار هلم بدون تغییر مانیفست، از دستور زیر استفاده کنید:

kubit -n my-project pack force-upgrade my-app

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

kubit -n my-project pack rollout-restart my-app

این دو عملیات یکسان نیستند. force-upgrade مسیر ارتقای هلم را دوباره اجرا می‌کند، اما rollout-restart ورک‌لودهای پک را دوباره راه‌اندازی می‌کند. پیش از استفاده در محیط عملیاتی، اثر قطعی کوتاه‌مدت یا شروع هم‌زمان پادها را در نظر بگیرید.

اگر قابلیت بازراه‌اندازی وابسته در کلاستر فعال باشد، annotation زیر باعث می‌شود تغییر منابع نام‌برده، پک و ورک‌لودهای Deployment یا StatefulSet متعلق به آن را دوباره راه‌اندازی کند:

metadata:
  annotations:
    pack-operator.k8s.kubit.ir/watch-to-redeploy: configmap/app-config, secret/app-secret

فقط configmap/NAME و secret/NAME پذیرفته می‌شوند و منبع باید در همان فضای نام پک باشد. چند منبع را با فاصله، ویرگول یا نقطه‌ویرگول جدا کنید. تغییر منبع پس از یک تأخیر کوتاه پردازش می‌شود تا تغییرهای نزدیک به هم باعث راه‌اندازی‌های پیاپی نشوند.

ابتدا منبع و رویدادهای آن را بخوانید:

kubectl -n my-project get pack my-app -o yaml
kubectl -n my-project describe pack my-app

سپس این موارد را به‌ترتیب بررسی کنید:

1. مقدار status.phase و متن status.error؛
2. وجود مخزن معرفی‌شده و دسترسی پک به آن؛
3. وجود نسخه سازگار چارت در مخزن؛
4. صحت متغیرها، مقادیر والت و ساختار values؛
5. خروجی kubit helm-template و kubit helm-diff؛
6. رویدادها و وضعیت ورک‌لودهایی که هلم ساخته است.

status، resourceVersion، uid و finalizer را برای رفع خطا داخل فایل اصلی پک کپی نکنید. این فیلدها را کوبرنتیز و اپراتور مدیریت می‌کنند. اگر خطا از دسترسی یا پیکربندی سراسری اپراتور است، اطلاعات status.error، نام کلاستر، فضای نام و نام پک را برای پشتیبانی کوبیت ارسال کنید؛ مقدار رمز، توکن یا متن رمزگشایی‌شده والت را ارسال نکنید.