# دیپلوی Helm موفق بود. کانفیگ هیچ‌وقت اعمال نشد.

> پایپ‌لاین CI سبز در حالی که گیت‌وی لایو ۴۰۴ برمی‌گردونه، شکست تست نیست. یه شکاف بی‌صدا توی ری‌لود شدنه. این‌جا الگوی چک‌سام بین‌ریلیزی رو می‌گم که این شکاف رو توی helmfile می‌بنده.

- URL: https://ashkmb.com/fa/blog/helm-configmap-reload-cross-release/
- Author: Ashkan Kamyab (https://ashkmb.com)
- Published: 2026-06-21
- Language: fa

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

مسیر جدید ۴۰۴ برگردوند.

یه پورت‌فوروارد و یه curl تأییدش کرد: تعریف مسیر جدید روی گیت‌وی لایو نبود. پاد داشت با کانفیگ آخرین ری‌استارت کار می‌کرد، نه کانفیگی که تازه دیپلوی کرده بودیم. ما یه کانفیگ‌مپ رو آپدیت کرده بودیم. پاد روحش هم خبر نداشت.

چیزی که پیدا کردنش رو سخت‌تر می‌کرد: قبلاً کار کرده بود. دو ماه قبل، یه تغییر کانفیگ مشابه بدون هیچ دردسری رفته بود روی لایو. چیزی که اون موقع نمی‌دونستیم این بود که اون تغییر از قضا به `mountPath` یه والیوم هم دست زده بود، و همین به‌عنوان اثر جانبی باعث شده بود Kubernetes پاد رو دوباره رول‌اوت کنه. به نظر می‌رسید آپدیت کانفیگ علت بوده. تصادف بود.

## چرا کانفیگ‌مپ باعث ری‌استارت نمی‌شه

سیستم Kubernetes وقتی یه پاد رو رول‌اوت می‌کنه که *pod template spec* اون تغییر کنه. هر کانفیگ‌مپ یه آبجکت جدا توی API خود Kubernetes هست. آپدیت کردنش pod template رو تغییر نمی‌ده. پاد با هر چیزی که آخرین بار موقع شروع مانت شده بود به کارش ادامه می‌ده.

این عمدیه. این‌جا Kubernetes آگاهانه «داده عوض شد» رو از «مصرف‌کننده باید ری‌استارت بشه» جدا می‌کنه. برای اپ‌هایی که داخل خود پروسه فایل‌ها رو زیر نظر دارن، این رفتار درستیه: می‌تونن بدون ری‌استارت پاد کانفیگ رو دوباره بارگذاری کنن. برای اپ‌هایی که فایل‌های کانفیگ رو موقع شروع می‌خونن و توی حافظه نگه می‌دارن، یه تله‌ست.

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

## فیکس استاندارد: انوتیشن چک‌سام

راه‌حل استاندارد اینه که یه انوتیشن `checksum/config` به pod template مربوط به دیپلویمنت اضافه کنی که از محتوای کانفیگ‌مپ ساخته می‌شه:

```yaml
# templates/deployment.yaml — standard single-chart pattern
spec:
  template:
    metadata:
      annotations:
        checksum/config: {{ include "gateway.configmap" . | sha256sum | quote }}
```

وقتی محتوای کانفیگ‌مپ عوض بشه، مقدار انوتیشن هم عوض می‌شه. انوتیشن داخل `spec.template.metadata` قرار داره، که جزو pod spec حساب می‌شه. اون‌وقت Kubernetes می‌بینه pod template عوض شده و یه ری‌استارت تدریجی راه می‌اندازه. مقدار انوتیشن به‌عنوان متادیتا هیچ معنایی نداره؛ تنها کارش اینه که سیگنال تغییر رو به pod spec برسونه.

این الگو توی مستندات Helm و بیشتر نوشته‌هایی که درباره‌ی ری‌استارت اجباری پاد بعد از تغییر کانفیگ‌مپ هستن اومده. توی یه چارت Helm واحد، جایی که `include "gateway.configmap"` به تمپلیت نام‌دار دسترسی داره، خوب کار می‌کنه.

## چرا بین ریلیزها خراب می‌شه

ساختار ما دو تا ریلیز Helm جدا داره: یکی که دیپلویمنت گیت‌وی مال اونه، و یکی که آبجکت‌های کانفیگ‌مپ مربوط به تعریف‌های API رو از روی فایل‌های تعریف جداگانه می‌سازه.

دامنه‌ی `include` به چارت فعلی محدوده. نمی‌تونی از تمپلیت دیپلویمنت، `include "other-release.configmap"` رو صدا بزنی؛ اون تمپلیت نام‌دار توی کانتکست رندر اون چارت وجود نداره. محتوای کانفیگ‌مپ موقع رندر در دسترس چارت دیپلویمنت نیست.

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

## راه‌حل helmfile

فایل‌های values توی helmfile از تمپلیت‌نویسی Go با یه سری تابع فراتر از Helm استاندارد پشتیبانی می‌کنن. دو تاشون مستقیم همین مشکل رو حل می‌کنن.

تابع `readFile` محتوای خام یه فایل رو می‌خونه و به شکل رشته برمی‌گردونه. تابع `readDirEntries` ورودی‌های یه دایرکتوری رو برمی‌گردونه. هر دو مسیرها رو نسبت به دایرکتوری خود فایل values حساب می‌کنن، نه ریشه‌ی ریپو. این جزئیات آخر مهمه.

توی فایل values ریلیز گیت‌وی، همه‌ی فایل‌های منبعی رو که محتوای کانفیگ‌مپ از اون‌ها میاد می‌خونیم، محتوا رو پشت هم می‌چسبونیم، هشش می‌کنیم و نتیجه رو به شکل یه کلید values در اختیار می‌ذاریم:

```yaml
# helmfile-values/gateway/values.yaml.gotmpl
{{- $apiDir := "./apis" -}}
{{- $content := "" -}}
{{- range readDirEntries $apiDir -}}
{{-   $content = cat $content (readFile (printf "%s/%s" $apiDir .Name)) -}}
{{- end -}}
configChecksum: {{ $content | sha256sum | quote }}
```

مسیر `./apis` نسبت به محل فایل values حساب می‌شه. اگه `values.yaml.gotmpl` توی `helmfile-values/gateway/values.yaml.gotmpl` باشه، `./apis` روی دیسک باید `helmfile-values/gateway/apis/` باشه. اگه این رو اشتباه بگیری، `readDirEntries` یه فهرست خالی برمی‌گردونه، `$content` خالی می‌مونه و هش ثابت می‌شه. انوتیشن رندر می‌شه ولی هر چی توی فایل‌های منبع بذاری، هیچ‌وقت عوض نمی‌شه.

بعد تمپلیت دیپلویمنت هشِ از قبل محاسبه‌شده رو از values می‌خونه:

```yaml
# gateway chart — templates/deployment.yaml
spec:
  template:
    metadata:
      annotations:
        checksum/config: {{ .Values.configChecksum }}
```

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

## راستی‌آزمایی این‌که کار می‌کنه

دستور `helmfile template` فایل YAML مربوط به دیپلویمنت رو با انوتیشن مقداردهی‌شده رندر می‌کنه. هر فایلی توی دایرکتوری تعریف‌های API رو ویرایش کن، دوباره `helmfile template` رو اجرا کن و مطمئن شو هش توی انوتیشن عوض می‌شه. اگه عوض نشد، مسیر اشتباهه. عبارت `{{ $content | len }}` رو به تمپلیت values اضافه کن تا مطمئن شی اصلاً محتوایی خونده می‌شه.

دستور `helmfile diff` آپدیت انوتیشن رو به شکل یه تغییر تمیز توی pod template نشون می‌ده: فقط مقدار انوتیشن، نه چیز دیگه. بعد از اپلای، یه پورت‌فوروارد و یه curl روی مسیر جدید تأیید می‌کنه که کانفیگ روی لایو اعمال شده.

## چیزی که باید از این ماجرا برداشت

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

توابع `readFile` و `readDirEntries` در helmfile راه فرار درستن، چون توی لایه‌ی values کار می‌کنن، قبل از این‌که هر کانتکست تمپلیتی در دامنه‌ی چارت اجرا بشه. همین باعث می‌شه برای هر ریلیزی که لازم داره محتوای فایل‌های منبع یه ریلیز دیگه رو هش کنه در دسترس باشن.

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

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