اتصال پایپ‌لاین ساخت و استقرار به کوبچی

بخش CI/CD هر پک یک نشانی و توکن اختصاصی برای پایپ‌لاین می‌سازد. پایپ‌لاین پس از ساخت و انتشار ایمیج، تگ تازه را به این نشانی می‌فرستد. کوبچی مقدار DOCKER_TAG را در پک تغییر می‌دهد، پیکربندی را اعتبارسنجی می‌کند و نتیجه را در اختیار پک اپراتور می‌گذارد.

کوبچی کد برنامه را دریافت نمی‌کند و ایمیج را نمی‌سازد. ساخت و push ایمیج بر عهده GitHub Actions یا GitLab CI/CD است؛ کوبچی فقط تگ یا متغیر مجاز پک را به‌روز می‌کند.

1. یک کامیت، پایپ‌لاین مخزن برنامه را اجرا می‌کند.
2. پایپ‌لاین ایمیج را می‌سازد و با یک تگ یکتا در رجیستری قرار می‌دهد.
3. مرحله استقرار، همان تگ را با درخواست POST و توکن اختصاصی پک به کوبچی می‌فرستد.
4. کوبچی متغیر پک را تغییر می‌دهد، مانیفست را اعتبارسنجی می‌کند و در صورت اتصال GitOps تغییر را در گیت نیز کامیت می‌کند.
5. پک اپراتور انتشار هلم را با پیکربندی تازه هماهنگ می‌کند. نحوه جایگزینی پادها به تنظیمات چارت و ورک‌لود بستگی دارد.

• یک پک نصب‌شده داشته باشید که تگ ایمیج را از متغیری مانند DOCKER_TAG بخواند.
• مخزن برنامه روی GitHub یا GitLab و یک Runner فعال برای اجرای پایپ‌لاین آماده باشد.
• مقصد رجیستری و اطلاعات ورود لازم برای push ایمیج را داشته باشید.
• مجوز مشاهده صفحه CI/CD پک و ساخت اعتبارنامه آن را داشته باشید. اگر گزینه‌ها در دسترس نیستند، از مدیر سازمان بخواهید نقش پروژه را بررسی کند.

توکن CI/CD برای تغییر متغیرهای مجاز همان پک استفاده می‌شود. آن را مانند رمز عبور نگه دارید و در فایل مخزن، خروجی پایپ‌لاین، تیکت یا تصویر قرار ندهید.

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

spec:
  vars:
    DOCKER_TAG: main-initial
  values:
    image:
      tag: '{{ vars.DOCKER_TAG }}'

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

پک مورد نظر را باز کنید و در سایدبار داخل صفحه پک، CI/CD را انتخاب کنید. همین راهنما از کارت CI/CD در نمای کلی پک نیز در دسترس است.

در مرحله انتخاب بستر CI/CD، یکی از گزینه‌های GitHub Actions یا GitLab CI/CD را انتخاب کنید. با زدن گام بعد، اگر پک هنوز اعتبارنامه CI/CD نداشته باشد، کوبچی یک توکن اختصاصی می‌سازد.

مرحله تنظیم متغیرهای محیطی پنج نام را نشان می‌دهد:

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

در مخزن GitHub از Settings > Secrets and variables > Actions وارد تب Secrets شوید. برای هر مقدار روی New repository secret بزنید و نام را دقیقاً مطابق جدول وارد کنید. دست‌کم KUBIT_WEBHOOK_TOKEN و اطلاعات ورود رجیستری باید Secret باشند.

قالب فعلی GitHub هر پنج مقدار را از secrets می‌خواند. اگر URL یا نام کاربری را در بخش Variables ذخیره می‌کنید، باید ارجاع متناظر در فایل workflow را نیز از secrets به vars تغییر دهید.

در پروژه GitLab از Settings > CI/CD بخش Variables را باز و متغیرها را یکی‌یکی اضافه کنید. برای توکن وب‌هوک و رمز رجیستری، حالت Masked and hidden را در صورت پشتیبانی نسخه GitLab انتخاب کنید. اگر پایپ‌لاین فقط روی شاخه یا تگ محافظت‌شده اجرا می‌شود، گزینه Protect variable را نیز فعال کنید.

قالب GitLab برای نام مسیر ایمیج از متغیر IMAGE_ADDRESS استفاده می‌کند، اما این مقدار در جدول کوبچی نمایش داده نمی‌شود. آن را نیز متناسب با مسیر رجیستری خود تعریف کنید؛ برای نمونه team/my-app.

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

• GitHub Actions: فایل .github/workflows/main.yaml
• GitLab CI/CD: فایل .gitlab-ci.yml

پیش از کامیت، قالب را با پروژه خود هماهنگ کنید. نام شاخه، Dockerfile، مسیر ایمیج، Runner، رجیستری و قواعد اجرای استقرار ممکن است با نمونه فرق داشته باشند. قالب GitHub با push روی شاخه main اجرا می‌شود و پس از build، مرحله استقرار را خودکار اجرا می‌کند. در قالب فعلی GitLab، job استقرار manual است و باید پس از موفقیت build آن را تأیید کنید.

در نمونه GitLab، خط set -ex را پیش از استفاده عملی به set -e تغییر دهید. گزینه -x فرمان‌های اجراشده را در لاگ job چاپ می‌کند و ممکن است هدر دارای توکن وب‌هوک را آشکار کند. همچنین مطمئن شوید متغیرهای حساس در تنظیمات GitLab مخفی شده‌اند.

درخواست اصلی مرحله استقرار معادل این نمونه است:

curl --fail --silent --show-error \
  --request POST \
  --form "DOCKER_TAG=${IMAGE_TAG}" \
  --header "Authorization: Bearer ${KUBIT_WEBHOOK_TOKEN}" \
  "${KUBIT_WEBHOOK_URL}"

IMAGE_TAG باید همان تگی باشد که مرحله build در رجیستری push کرده است. از تگ ثابت latest استفاده نکنید؛ با شناسه کامیت یا شماره نسخه می‌توان هر استقرار را به ایمیج مشخصی نسبت داد.

وب‌هوک پیش‌فرض نام‌های دیگری را نیز می‌پذیرد، به شرطی که با DOCKER_TAG شروع شوند؛ مانند DOCKER_TAG_API و DOCKER_TAG_WORKER. هر نام باید در spec.vars وجود داشته باشد و در بخش درست values مصرف شود.

برای ارسال چند مقدار، آن‌ها را با قالب variables[NAME] به درخواست اضافه کنید:

curl --fail --silent --show-error \
  --request POST \
  --form "variables[DOCKER_TAG_API]=${API_TAG}" \
  --form "variables[DOCKER_TAG_WORKER]=${WORKER_TAG}" \
  --header "Authorization: Bearer ${KUBIT_WEBHOOK_TOKEN}" \
  "${KUBIT_WEBHOOK_URL}"

نامی که با DOCKER_TAG شروع نشود در این اتصال پذیرفته نمی‌شود. برای مقدارهای عمومی پروژه از متغیرهای کوبیتی استفاده کنید؛ وب‌هوک CI/CD برای تغییر کنترل‌شده تگ‌های استقرار است.

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

اگر پایپ‌لاین شما قواعد دیگری برای اجرا دارد، همچنان مسیر فایل GitOps را از triggerهای build و deploy کنار بگذارید. پس از نخستین اجرا، لاگ کامیت‌های GitOps را بررسی کنید و مطمئن شوید تغییر تگ فقط یک اجرای مورد انتظار ایجاد کرده است.

1. فایل workflow یا pipeline و تغییرهای لازم پروژه را کامیت کنید.
2. اجرای build را باز کنید و مطمئن شوید ایمیج با تگ مورد انتظار در رجیستری push شده است.
3. در GitLab، job دستی استقرار را پس از بررسی build اجرا کنید. در GitHub، اجرای مرحله deploy را دنبال کنید.
4. پاسخ درخواست کوبچی باید موفق باشد و job به‌دلیل گزینه --fail روی پاسخ خطا متوقف شود.
5. در پیکربندی پک، مقدار تازه DOCKER_TAG را بررسی کنید. سپس وضعیت ورک‌لودها و پادها و رویدادهای پک را ببینید.

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

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

توکن و URL نمایش‌داده‌شده را دوباره در تنظیمات GitHub یا GitLab جایگزین کنید و فقط پس از آن پایپ‌لاین را اجرا کنید. ساخت دوباره بدون به‌روزرسانی Secretهای مخزن باعث خطای احراز هویت در اجرای بعدی می‌شود.

مقدار KUBIT_WEBHOOK_TOKEN را با توکن فعلی پنل مقایسه کنید. فاصله اضافی، استفاده از توکن قبلی پس از ساخت دوباره و ثبت مقدار به‌عنوان Variable معمولی از علت‌های رایج‌اند. توکن را در لاگ چاپ نکنید؛ مقدار Secret را مستقیم جایگزین کنید.

نام فیلد باید DOCKER_TAG باشد یا با همین عبارت شروع شود. در درخواست چندمتغیره نیز از قالب دقیق variables[DOCKER_TAG_NAME] استفاده کنید. نام‌ها به بزرگی و کوچکی حروف حساس‌اند.

مطمئن شوید همان تگ ابتدا در رجیستری push و سپس برای کوبچی ارسال شده است. در پک نیز بررسی کنید متغیر داخل spec.vars وجود دارد و فیلد تگ واقعی چارت به {{ vars.DOCKER_TAG }} یا نام متناظر ارجاع می‌دهد.

نشانی رجیستری، مسیر ایمیج و وجود تگ را بررسی کنید. اعتبارنامه push پایپ‌لاین با اعتبارنامه pull کلاستر یکسان نیست. برای مخزن خصوصی، رمز مخزن داکر را نیز در کوبچی ثبت و برای پروژه فعال کنید.

اگر پک به GitOps متصل است، قواعد اجرای پایپ‌لاین را طوری تنظیم کنید که کامیت دارای [skip ci] و تغییر صرفاً در مسیر مانیفست پک، build تازه‌ای آغاز نکند. سپس تاریخچه پایپ‌لاین و کامیت‌های GitOps را برای پیدا کردن trigger تکراری بررسی کنید.