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

> پایپ‌لاین CI ما یه توکن معتبر EKS می‌ساخت، درست و تمیز ارائه‌ش می‌داد، و رد می‌شد. مشکل از اعتبارنامه‌های AWS نبود. مشکل کنترل دسترسی خودِ EKS بود، و خطا جلوی چشم همه بود: کلاستر برای نقشی که درخواست می‌داد هیچ ورودی دسترسی نداشت.

- URL: https://ashkmb.com/fa/blog/eks-401-not-credentials/
- Author: Ashkan Kamyab (https://ashkmb.com)
- Published: 2026-07-30
- Language: fa

اولین دیپلوی پروداکشن با پایپ‌لاین جدیدمون توی همه‌ی مراحل سبز شد جز آخری. چک هویت، کشیدن چارت، `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`، `AccessDenied` | `aws 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 سالمه، که آخرش کلیدی رو عوض نکنی که هیچ‌وقت مشکل نبوده:

```bash
# 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 هم یکی می‌بینه. مشکل توکن نیست.

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

```bash
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 هر دو کار می‌کردن، چون ورودی‌هاشون خیلی قبل از این شکاف اپلای شده بودن. پروداکشن اولین دیپلوی با پایپ‌لاین جدید بود، پس شکاف فقط اون‌جا خودش رو نشون داد. محیط‌های قبلی آسیبی ندیدن.

## راه‌حل

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

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

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

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

```bash
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 که روی محیط قبلی کار می‌کرد و روی محیط جدید دیگه کار نمی‌کنه، همون شکافه با یه تاریخچه‌ی اپلای دیگه. توکن سالمه. کلاستر سالمه. ورودی وجود نداره.
