# اپ داشت متغیر REDIS_PORT رو می‌خوند، ولی Kubernetes از قبل یه چیز دیگه روی مقدارش نوشته بود.

> همه‌ی ویوهایی که به کش دست می‌زدن خطای ۵۰۰ می‌دادن، در حالی که هلث‌چک سبز مونده بود. مقصر یه سرویس به اسم redis بود و تنظیم enableServiceLinks، یه پیش‌فرض Kubernetes از دوران Docker که متغیرهای محیطی‌ای رو تزریق می‌کنه که هیچ‌وقت نخواسته بودی.

- URL: https://ashkmb.com/fa/blog/kubernetes-enableservicelinks-env-collision/
- Author: Ashkan Kamyab (https://ashkmb.com)
- Published: 2026-07-08
- Language: fa

داشتم یه اپ Django رو روی [کلاستر هوم‌لبم](https://ashkmb.com/fa/blog/vibe-coded-proxmox-dashboard/) دیپلوی می‌کردم. هیچ چیز عجیب و غریبی هم نبود: خود اپ، یه Postgres و یه Redis، هر کدوم پشت سرویس خودش. پادها سبز بالا اومدن، فیکسچرها لود شدن، `/health` هم ۲۰۰ برگردوند. بعد خواستم لاگین کنم و یه HTTP 500 لخت تحویل گرفتم، با بدنه‌ی کاملاً خالی.

فقط هم لاگین نبود. اندپوینت اسکیمای API هم ۵۰۰ می‌داد. اندپوینت هلث همچنان کار می‌کرد، فایل‌های استاتیک هم همین‌طور. چند تا درخواست طول کشید تا الگو رو ببینم: هر ویویی که به کش دست می‌زد خراب می‌شد، و هر چیزی که دست نمی‌زد سالم بود.

## بیرون کشیدن تریس‌بک از پادی که توی حالت پروداکشن اجرا می‌شه

توی ایمیج، `DEBUG` به‌صورت هاردکد روی `False` بود. برای همین بدنه‌ی پاسخ خالی بود و لاگ‌ها فقط خود ۵۰۰ رو نشون می‌دادن، نه استثنایی که پشتش بود. به‌جای این‌که ایمیج رو با دیباگ روشن دوباره بیلد کنم، کلاینت تست Django رو داخل خود پاد اجرا کردم:

```python
# kubectl exec -it <pod> -- python manage.py shell
from django.test import Client

c = Client(raise_request_exception=True)
c.post("/backend/token/", {"username": "admin", "password": "..."})
```

تیکه‌ی به‌دردبخورش `raise_request_exception=True` هست. کلاینت تست به‌جای این‌که صفحه‌ی ۵۰۰ رو رندر کنه، همون استثنای اصلی رو مستقیم توی شِلت دوباره پرتاب می‌کنه. نه تغییری توی کد، نه دیپلوی دوباره، نه حالت دیباگ توی یه کلاستر در حال اجرا. تریس‌بک بلافاصله برگشت:

```
ValueError: Port could not be cast to integer value as 'tcp:'
```

پورتی که با `tcp:` شروع می‌شه. رشته‌ی اتصال Redis که اپ سرهم کرده بود این شکلی بود:

```
redis://redis:tcp://10.233.61.42:6379/1
```

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

```python
REDIS_HOST = os.environ.get("REDIS_HOST", "redis")
REDIS_PORT = os.environ.get("REDIS_PORT", "6379")
CACHE_URL = f"redis://{REDIS_HOST}:{REDIS_PORT}/1"
```

`REDIS_PORT` توی محیط پاد مقدار داشت. نه مانیفست‌های من ستش کرده بودن، نه چارت، نه هیچ کانفیگ‌مپی. مقدارش `tcp://10.233.61.42:6379` بود، که پورت نیست. یه URL هست.

## کی مقدار REDIS_PORT رو یه URL می‌ذاره؟

این کارِ kubelet هست. وقتی یه پاد بالا میاد، Kubernetes برای هر سرویسی که توی اون نیم‌اسپیس وجود داره یه دسته متغیر محیطی تزریق می‌کنه. برای سرویسی به اسم `redis` روی پورت ۶۳۷۹، همه‌ی پادهای اون نیم‌اسپیس این‌ها رو می‌گیرن:

```
REDIS_SERVICE_HOST=10.233.61.42
REDIS_SERVICE_PORT=6379
REDIS_PORT=tcp://10.233.61.42:6379
REDIS_PORT_6379_TCP=tcp://10.233.61.42:6379
REDIS_PORT_6379_TCP_PROTO=tcp
REDIS_PORT_6379_TCP_PORT=6379
REDIS_PORT_6379_TCP_ADDR=10.233.61.42
```

این یه لایه‌ی سازگاری برای قابلیت Docker links هست، سازوکاری که Docker قبل از رواج DNS برای وصل‌کردن کانتینرها به هم داشت. Kubernetes از همون اولین نسخه‌ش دقیقاً همین قالب متغیرها رو برداشت تا کانتینرهایی که برای Docker links نوشته شده بودن همچنان کار کنن. این ماجرا مال بیش از ده سال پیشه. کشف سرویس از طریق DNS برنده شد و دیگه هیچ‌کس اپش رو بر اساس `*_PORT_6379_TCP_ADDR` نمی‌نویسه، ولی این تزریق هنوز به‌طور پیش‌فرض روشنه. فیلدی از پاد که کنترلش می‌کنه `enableServiceLinks` هست و مقدار پیش‌فرضش هم `true` هست.

این تداخل به یه دلیل مشخص موذیانه‌ست: `<SERVICE_NAME>_PORT` دقیقاً همون اسمیه که یه اپ دوازده‌عاملی خودش هم برای متغیرش انتخاب می‌کرد. سرویست رو `redis` اسم بذار و توی اپت `REDIS_PORT` رو بخون، اون‌وقت یه تداخل حتمی داری که برنده‌ش Kubernetes هست، چون محیطِ تزریق‌شده قبل از اجرای کدت سر جاشه. مقدارش حتی عدد هم نیست، چون Docker links اون رو به شکل یه URL همراه با اسم پروتکل قالب‌بندی می‌کرد.

سرویس Postgres من کاملاً اتفاقی از همین بلا قسر در رفت. اون‌جا هم Kubernetes متغیر `POSTGRES_PORT=tcp://...` رو تزریق کرده بود، ولی اپ `DB_HOST` و `DB_PORT` رو می‌خونه، پس متغیرهای تزریق‌شده همون‌جا بی‌استفاده موندن. اعصاب‌خردکن‌ترین بخش این نوع خرابی همینه: این‌که گیرت بندازه یا نه، به یه تصادف نامرئی توی اسم‌گذاری بستگی داره، بین اسم سرویس‌هات و قراردادی که اپت برای کانفیگ داره.

## راه‌حل

سه تا گزینه هست، به همون ترتیبی که من سراغشون می‌رم.

تزریق رو توی اسپک پاد خاموش کن:

```yaml
spec:
  enableServiceLinks: false
```

راه‌حل تمیز همینه. کشف سرویس از طریق DNS دست‌نخورده می‌مونه و `redis.namespace.svc` همچنان ریزالو می‌شه. تنها چیزی که حذف می‌شه همون دسته‌ی متغیرهای قدیمیه، و اگه اپت روی هر کلاستری اجرا می‌شه که توی ده سال اخیر ساخته شده، هیچ‌چیزی اون‌ها رو نمی‌خونده.

اگه نمی‌تونی به اسپک پاد دست بزنی، متغیری رو که تداخل داره صریحاً ست کن:

```yaml
env:
  - name: REDIS_PORT
    value: "6379"
```

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

گزینه‌ی سوم انضباط توی اسم‌گذاریه: هیچ‌وقت سرویسی رو جوری اسم نذار که `<NAME>_PORT` با چیزی که اپت می‌خونه یکی بشه. من به این یکی اعتماد ندارم. شرطش اینه که هر هم‌تیمی‌ای که بعداً میاد، موقع اسم‌گذاری یه سرویس، از یه قاعده‌ی تزریق مال دوران Docker خبر داشته باشه، و این دقیقاً همون جور دانشیه که کم‌کم دود می‌شه و می‌ره هوا.

یه ویژگی دیگه هم هست که بهتره بدونی: متغیرها موقع شروع پاد تزریق می‌شن، اون هم فقط برای سرویس‌هایی که همون لحظه وجود دارن. پاد رو قبل از ساختن سرویس بالا بیار، متغیر وجود نداره؛ همون پاد رو یه هفته بعد ری‌استارت کن، یهو پیداش می‌شه. دیپلویی که کار می‌کرد می‌تونه دفعه‌ی بعد که پاد دوباره زمان‌بندی می‌شه بشکنه، بدون این‌که هیچ مانیفستی عوض شده باشه. این همون جنس خرابیه که [آپدیت کانفیگ‌مپی که هیچ‌وقت به پادِ در حال اجرا نمی‌رسه](https://ashkmb.com/fa/blog/helm-configmap-reload-cross-release/) هم داره: پایپ‌لاین دیپلوی سبزه و خرابی فقط موقع اجرا وجود داره.

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

خود Kubernetes هنوز رفتارهایی برای سازگاری با گذشته با خودش میاره که از بیشتر کلاسترهایی که روش اجرا می‌شن قدیمی‌ترن، و این رفتارها تا وقتی سر از متغیرهای محیطیت درنیارن به چشم نمیان. مثل [فاینالایزرها](https://ashkmb.com/fa/blog/kubernetes-finalizers-explained/)، `enableServiceLinks` هم سازوکاریه که بیشتر آدم‌ها روزی باهاش آشنا می‌شن که راهشون رو می‌بنده.

دو تا عادت هست که ارزش داره داشته باشی. وقتی یه اپ توی پاد بدرفتاری می‌کنه ولی همه‌جای دیگه درست کار می‌کنه، قبل از این‌که یه خط دیگه کد بخونی، محیط واقعی پاد رو چاپ کن (`kubectl exec <pod> -- env | sort`)؛ گاهی جواب سؤال «کی اینو ست کرده؟» خود پلتفرمه. و برای چارت‌هایی که دست خودته، به این فکر کن که `enableServiceLinks: false` رو پیش‌فرض بذاری برای هر ورک‌لودی که صریحاً به متغیرهای Docker links نیاز نداره، که این روزها یعنی تقریباً همه‌شون.
