# قید برقرار بود. با این حال زون خالی موند.

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

- URL: https://ashkmb.com/fa/blog/topology-spread-satisfied-but-wrong/
- Author: Ashkan Kamyab (https://ashkmb.com)
- Published: 2026-09-18
- Language: fa

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

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

## قید واقعاً چه قولی می‌ده

یه `topologySpreadConstraint` فقط یه بار ارزیابی می‌شه، موقعی که پاد زمان‌بندی می‌شه، و دیگه هیچ‌وقت. Kubernetes دوباره توازن برقرار نمی‌کنه. وقتی یه پاد بالا میاد، اسکجولر برای هر مقدار از کلید توپولوژی، پادهایی رو که با `labelSelector` قید جور درمیان می‌شمره، اسکیو رو در برابر `maxSkew` حساب می‌کنه، و بر همین اساس جاش می‌ده. بعد از اون لحظه هیچ‌چیز دوباره ارزیابی نمی‌شه؛ پاد همون‌جایی که فرود اومده می‌مونه تا وقتی که یه چیزی حذفش کنه.

پس «برقرار» هم‌زمان ادعایی درباره‌ی دو چیزه: یه شمارش، و جمعیتی که شمارش روش انجام شده. تو مورد من شمارش درست بود. جمعیت نه.

وسوسه‌انگیزه که بری سراغ `whenUnsatisfiable: DoNotSchedule` و بگی قید سخت‌گیرتر شد. مشکل این نیست، و مشکل من هم این نبود. سخت‌گیری هیچ‌وقت ورودی ماجرا نبود. جمعیت بود.

## ایراد اول: رول‌اوت پادها رو روی هم می‌چینه

اولین راهی که جمعیت دروغ می‌گه از مسیر زمان می‌گذره.

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

راه‌حل یه خطه:

```yaml
matchLabelKeys:
- pod-template-hash
```

اسکجولر قبل از شمردن، `pod-template-hash` خود پاد رو به سلکتور اضافه می‌کنه، و این جمعیت رو به ReplicaSet خود پاد محدود می‌کنه. پادهای هم‌خانواده‌ای که دارن می‌میرن دیگه شمرده نمی‌شن و رول‌اوت به‌طور عادی پخش می‌شه. این قابلیت از Kubernetes 1.30 به نسخه‌ی پایدار (GA) رسیده، و اون‌قدر کم‌هزینه‌ست که جاش روی هر قید پخشیه که سلکتورش هیچ هویت مختص هر ورک‌لودی نداره.

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

دومین راهی که جمعیت دروغ می‌گه از پهلو می‌گذره، و این یکی جدیه.

یه اپراتور سه تا دیپلویمنت کالکتور رو تو این نیم‌اسپیس مدیریت می‌کنه، با سه، دو و دو رپلیکا. روی همه‌شون `app.kubernetes.io/component: opentelemetry-collector` رو می‌ذاره، چون معنای این لیبل همینه: یه چیز چیه، نه این‌که کدوم چیزه.

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

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

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

راه‌حل، هویت مختص هر ورک‌لود توی سلکتوره. اپراتور برای هر دیپلویمنت یه لیبل instance می‌ذاره، پس قید این‌طوری می‌شه:

```yaml
topologySpreadConstraints:
- maxSkew: 1
  topologyKey: topology.kubernetes.io/zone
  whenUnsatisfiable: DoNotSchedule
  labelSelector:
    matchLabels:
      app.kubernetes.io/component: opentelemetry-collector
      app.kubernetes.io/instance: <the deployment's own instance>   # scoped
  matchLabelKeys:
  - pod-template-hash                                               # added
```

لیبل instance رو از روی یه پاد زنده بخون، نه این‌که کلیدش رو فرض کنی. اپراتورها بر اساس نوع لیبل می‌زنن، و لیبلی که یه نوع رو مشخص می‌کنه دقیقاً کلید غلطیه برای پخش کردن.

## ترمیمی که به جواب غلط می‌رسه

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

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

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

یه تله‌ی دیگه از همین خانواده هم بگم، چون دقیقاً وسط همین جور بررسی‌ها گاز می‌گیره: دستور apply تو Helm قبل از تموم شدن رول‌اوتی که راه انداخته برمی‌گرده، چون `maxUnavailable: 1` باعث می‌شه دو از سه در دسترس حساب بشه. دستور apply گفت تموم شد، در حالی که یه پاد هنوز Pending بود. رول‌اوت‌ها رو خودت چک کن؛ خوش‌بینی دستور apply رو به ارث نبر.

## راه‌حل، با تأیید همون موردی که شکست خورده بود

هر دو خط اضافه شدن: لیبل مختص instance توی `matchLabels`، و `pod-template-hash` توی `matchLabelKeys`. بعدش دیپلویمنتی رو که پادهاش روی هم چیده شده بودن دستی ترمیم نکردم، و این عمدی بود.

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

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

## کجاها این قاعده عمومیت داره

سلکتور یه اعلام جمعیته، نه یه اسم. هر وقت یکی می‌نویسی، سؤال این نیست که «ورک‌لود من رو انتخاب می‌کنه یا نه»، اینه که «مجموعه‌ی کامل چیزهایی که انتخاب می‌کنه چیه»، و این دو جواب به شکل‌هایی از هم فاصله می‌گیرن که هیچ‌وقت توی آبجکتی که داری ویرایشش می‌کنی دیده نمی‌شه.

نسخه‌ی ملایم این دروغ، سایدکاره: پاد متریک تک‌رپلیکای یه چارت معمولاً همون لیبل `name` چیزی رو داره که منظورت بود، پس شمارش اون رو هم حساب می‌کنه، و یه پخش نامتوازن `maxSkew: 1` رو برقرار نگه می‌داره در حالی که یه زون واقعاً خالی مونده. اگه پادهایی که می‌خوای هیچ لیبل متمایزکننده‌ای از خودشون ندارن، کنار گذاشتن بقیه باید صریحاً بیان بشه، نه ضمنی:

```yaml
labelSelector:
  matchLabels:
    app.kubernetes.io/name: <the chart>
  matchExpressions:
  - key: app.kubernetes.io/component
    operator: DoesNotExist
```

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

عادت تشخیصی‌ای که هر دو رو می‌گیره: قبل از این‌که به یه قید پخش اعتماد کنی، فهرست چیزهایی رو که اسکجولر واقعاً می‌شمره دربیار، و از روی پادهای زنده دربیار، با `kubectl get pods --show-labels`، نه از روی اسپکی که نوشتی. اسپک بهت می‌گه منظورت چی بود. پادها بهت می‌گن چی گیرت اومد، و این‌ها تنها دو تا واقعیت توی سیستمن، و فقط وقتی با هم جور درمیان که سلکتور درست باشه.

یه قید برقرار فقط یه شمارش رو ثابت می‌کنه. فقط نیت تعیین می‌کنه که اون شمارش روی همون چیزی بوده که منظورت بود یا نه.
