خطای ۴۰۱ توی EKS که ربطی به اعتبارنامه نداشت

kubernetes eks aws devops platform-engineering troubleshooting

اولین دیپلوی پروداکشن با پایپ‌لاین جدیدمون توی همه‌ی مراحل سبز شد جز آخری. چک هویت، کشیدن چارت، update-kubeconfig؛ همه موفق بودن. بعد helm upgrade با یه خط شکست خورد:

Error: Kubernetes cluster unreachable: the server has asked for the client to provide credentials

اولین کاری که همه سراغش می‌رن اینه که «کلید دسترسی AWS رو عوض کن». این غریزه اشتباهه. خطا از AWS نیست. توکن صادر شده بود، امضا شده بود و به kube-apiserver ارائه شده بود؛ سرور API ردش کرد. کلاستر برای پرینسیپالی که درخواست می‌داد هیچ ورودی دسترسی نداشت، پس نمی‌تونست توکن رو به هیچ هویتی که می‌شناسه وصل کنه.

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

چرا این غریزه اشتباهه

کلمه‌ی «credentials» توی اون پیام گمراه‌کننده‌ست. پیام از client-go، کتابخونه‌ی کلاینت Kubernetes، میاد، نه از AWS STS. خطاهای اعتبارنامه‌ی AWS خیلی زودتر و با یه پیام دیگه ظاهر می‌شن، معمولاً چیزی شبیه exec: ... could not get token، و توی مرحله‌ی aws eks get-token شکست می‌خورن، نه توی helm upgrade.

توی ردیابی ما، همه‌چیزِ قبل از مرحله‌ی helm کار کرد:

  • نقش IRSA رانر با AssumeRoleWithWebIdentity نقش دیپلوی بین‌اکانتی رو به دست آورد.
  • نقش دیپلوی چارت رو از ECR اکانت عملیات کشید.
  • دستور update-kubeconfig یه kubeconfig معتبر نوشت که به کلاستر پروداکشن اشاره می‌کرد.
  • دستور aws eks get-token یه توکن برگردوند.

توکن ساخته می‌شد. توکن ارائه می‌شد. بعد کلاستر ردش کرد. این یعنی خطای ۴۰۱، و ۴۰۱ یعنی احراز هویت شکست خورده، اون هم توی کلاستر، نه توی AWS: توکن معتبره، ولی کلاستر نمی‌تونه اونو به هویتی که می‌شناسه وصل کنه. اگه مشکل مجوزدهی بود، یعنی RBAC اجازه نمی‌داد، جواب ۴۰۳ می‌گرفتیم.

مدل ذهنی سه‌لایه

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

لایهچی کار می‌کنهپیام خطااولین چک
AWS STSبرای رانر یا نقش دیپلوی سشن صادر می‌کنهcould not get token، ExpiredToken، AccessDeniedaws sts get-caller-identity --profile <profile>
کنترل دسترسی EKSپرینسیپال IAM رو به یه هویت Kubernetes نگاشت می‌کنهserver has asked for the client to provide credentials (با توکن معتبر)aws eks list-access-entries --cluster-name <c>
RBAC در Kubernetesبه هویت نگاشت‌شده اجازه‌ی انجام کاری رو می‌دهForbidden، cannot ...kubectl auth can-i --list

خطای ۴۰۱ از سرور API وسط این جدول می‌شینه. خطای ۴۰۳ پایینش. رد شدن اتصال (connection refused) یا تایم‌اوت، مشکل شبکه یا kubeconfig هستن و اصلاً توی این جدول جایی ندارن. وقتی بدونی روی کدوم لایه‌ای، بقیه‌ی عیب‌یابی مکانیکیه.

دو تأیید که سی ثانیه طول می‌کشن

قبل از این‌که دنبال هر راه‌حلی بری، مطمئن شو سمت AWS سالمه، که آخرش کلیدی رو عوض نکنی که هیچ‌وقت مشکل نبوده:

# Side A: the AWS identity your deploy role assumes
aws sts get-caller-identity --profile <spoke-account>

# Side B: the cluster itself can issue a token for that identity
aws eks get-token --cluster-name <cluster> --region <region> --profile <spoke-account>

اگه هر دو موفق بودن، با مشکل اعتبارنامه طرف نیستی. با مشکل ورودی دسترسی طرفی. توکنی که توی Side B می‌گیری دقیقاً همون توکنیه که سرور API می‌بینه؛ اگه Side B توکن برگردونه، kube-apiserver هم یکی می‌بینه. مشکل توکن نیست.

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

aws eks list-access-entries \
  --cluster-name <cluster> \
  --region <region> \
  --profile <admin-profile>

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

ورودی‌های دسترسی EKS واقعاً چی‌ان

ورودی‌های دسترسی EKS (access entries) جایگزینِ کانفیگ‌مپ مربوط به aws-auth در سطح API هستن. وقتی AWS الگوی aws-auth رو منسوخ کرد، معرفی شدن؛ الگویی که توش نقش‌های IAM رو با ویرایش دستی یه فایل YAML توی kube-system به کاربرهای Kubernetes نگاشت می‌کردی. این مهاجرت سال‌هاست که در جریانه؛ خیلی از کلاسترها هنوز با authenticationMode: CONFIG_MAP کار می‌کنن و به aws-auth تکیه دارن، بعضی‌ها توی دوره‌ی گذار با API_AND_CONFIG_MAP اجرا می‌شن، و جدیدترها فقط API هستن.

توی هر حالتی که API رو شامل بشه، زنجیره این شکلیه:

  1. پرینسیپال IAM (نقش تو) یه توکن EKS از پیش امضاشده ارائه می‌ده.
  2. سرور API توکن رو با STS اعتبارسنجی می‌کنه.
  3. سرور API پرینسیپال رو توی جدول ورودی‌های دسترسی جست‌وجو می‌کنه.
  4. اگه پرینسیپال پیدا بشه، پالیسی‌های دسترسیِ مربوط بهش به گروه‌ها یا کاربرهای Kubernetes نگاشت می‌شن.
  5. بعد این گروه‌ها و کاربرها تابع RBAC معمولی Kubernetes هستن.

خطای ۴۰۱ توی قدم ۳ یعنی جست‌وجو هیچی برنگردونده. پرینسیپال از سمت AWS معتبره و توکن از سمت STS معتبره؛ فقط کلاستر هیچ ردیفی براش نداره. توکن ارائه می‌شه، جست‌وجو شکست می‌خوره، سرور API اعتبارنامه می‌خواد (چون چیزی نداره که پرینسیپال رو بهش نگاشت کنه)، و client-go این رو به کاربر این‌طوری گزارش می‌ده: «server has asked for the client to provide credentials».

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

شکاف توی مورد ما از کجا اومد

ماژول EKS ما یه مپ به اسم access_entries می‌گیره. هر ورودی به شکل { principal_arn = "..." } هست، و ماژول aws_eks_access_entry رو می‌سازه، به‌اضافه‌ی یه اتصال پیش‌فرض به AmazonEKSClusterAdminPolicy در سطح کلاستر. اضافه کردن یه کلید به اون مپ تنها کاریه که توی کد باید بکنی تا به یه نقش دیپلوی دسترسی کامل به کلاستر بدی.

ورودی نقش دیپلوی CI موقع راه‌اندازی EKS پروداکشن به مپ اضافه شد. ورودی هم‌جوارش، dashboard-admin، توی همون بلوک از قبل روی کلاستر بود، که ثابت می‌کرد بلوک دست‌کم یه بار اپلای شده. ورودی دیپلوی بعد از اون آخرین اپلای اضافه شده بود. با Terragrunt، ویرایش بدون اپلای یکی از راحت‌ترین اشتباه‌هاست، چون خروجی پلن برای یه ورودی جدید کوچیک و تمیزه، و هزینه‌ی رد شدن از اپلای «فقط همین یه بار» تا وقتی که اولین دیپلوی بهش نیاز پیدا کنه دیده نمی‌شه.

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

راه‌حل

terragrunt apply --all --target <env>/eks

این اپلای فقط وقتی واقعاً صرفاً چیزی اضافه می‌کنه که هیچ‌کدوم از پرینسیپال‌های تعریف‌شده‌ی دیگه از قبل با کلیک توی کنسول ساخته نشده باشن. توی مورد ما ورودی‌های هم‌جوار dashboard-admin و viewer-role از قبل روی کلاستر فعال بودن، پس اگه بی‌مقدمه اجراش می‌کردیم، اپلای با ResourceInUseException شکست می‌خورد. اولین کار اینه که وضعیت زنده‌ی کلاستر رو بررسی کنی:

aws eks list-access-entries \
  --cluster-name <cluster> \
  --region <region> \
  --profile <admin-profile>

اگه ورودی‌هایی که ماژول می‌خواد مدیریتشون کنه از قبل روی کلاستر هستن، قبل از اپلای ایمپورتشون کن:

terragrunt import 'aws_eks_access_entry.this["dashboard-admin"]' \
  '<cluster>:<dashboard-admin-role-arn>'

وقتی ایمپورت تموم شد، یه apply روی همون ماژول برای ورودی جدید یه ساختِ تمیزه و به ورودی‌های موجود دست نمی‌زنه. اثبات نهایی، اجرای بعدی دیپلویه. اگه اپلای موفق بود و دیپلوی هنوز شکست می‌خوره، ورودی در عمل به یه پالیسی دسترسیِ قابل‌استفاده وصل نشده، و قدم بعدی اجرای list-associated-access-policies هست.

نمودار مسیر

کل پایپ‌لاین، با نقطه‌ی شکستی که مشخص شده:

  ┌───────────────┐     ┌────────────────────┐     ┌───────────────┐
  │  runner IRSA  │ ──▶ │  cross-account     │ ──▶ │  aws eks      │
  │  role         │     │  deploy role       │     │  get-token    │
  └───────────────┘     └────────────────────┘     └───────────────┘
                                                          │
                                                          ▼
  ┌───────────────┐     ┌────────────────────┐     ┌───────────────┐
  │  Kubernetes   │ ◀── │  access entry      │ ◀── │  kube-        │
  │  RBAC         │     │  lookup  ❌  no row │     │  apiserver    │
  └───────────────┘     └────────────────────┘     └───────────────┘

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

الگوی کلی‌تر

توی یه پایپ‌لاین دیپلوی EKS، «اعتبارنامه» کلمه‌ایه که سه لایه‌ی مختلف رو پوشش می‌ده: اعتبارنامه‌های AWS (پرینسیپال معتبر داری؟)، کنترل دسترسی EKS (کلاستر اون پرینسیپال رو می‌شناسه؟)، و RBAC در Kubernetes (اون پرینسیپال اجازه داره کاری رو که می‌خواد انجام بده؟). فقط دومی پیام بالا رو تولید می‌کنه. عوض کردن کلیدهای AWS به دومی کمکی نمی‌کنه. آپدیت کردن kubeconfig هم به دومی کمکی نمی‌کنه. تنها چیزی که به دومی کمک می‌کنه، یه aws_eks_access_entry برای همون پرینسیپالیه که درخواست می‌ده.

وقتی پیام می‌گه «credentials»، قبل از این‌که هر کدوم از اعتبارنامه‌ها رو عوض کنی، چک کن واقعاً درباره‌ی کدومشون حرف می‌زنه. خودِ پیام خطا بدترین بخش عیب‌یابیه؛ توی هر سه لایه سر جاش می‌مونه و توی دو مورد از سه مورد به لایه‌ی اشتباه اشاره می‌کنه. زنجیره‌ی سه‌قدمیِ aws sts get-caller-identity، بعد aws eks get-token و بعد aws eks list-access-entries این ابهام رو توی کمتر از یه دقیقه برطرف می‌کنه و بهت می‌گه کدوم لایه رو باید درست کنی.

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

$ cat KUBERNETES .md
· 7 دقیقه مطالعه

کلاستر جدید روی هر نود ۱۱۰ پاد اجرا می‌کرد. پروداکشن روی ۵۸ گیر کرده بود.

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

kubernetes aws eks terraform devops
$ cat AIAGENTS .md
· 12 دقیقه مطالعه

اجرای Hermes Agent روی EKS: از docker-compose تا Helm

ایجنت هوش مصنوعی خودبهبودِ Nous Research، روی یه محیط EKS در حد پروداکشن. رجیستری خصوصی ECR، نقش‌های IRSA، کلیدهای API به‌شکل سکرت، و یه چارت Helm اختصاصی که از صفر ساختیمش.

ai-agents aws eks kubernetes llm helm devops
$ cat KUBERNETES .md
· 7 دقیقه مطالعه

کلاستر ۱۶۰ میلی‌کور مصرف می‌کرد. ریکوئست‌هاش شش تا نود لازم داشتن.

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

kubernetes eks finops devops mechanism