EKSの「Unauthorized」エラーの修正：KubeconfigとIAMのトラブルシューティング

エラーメッセージ

ポッドの確認やサービスのデプロイを行おうとして作業の真っ最中、ターミナルから予期せぬエラーが返ってくることがあります。標準的な kubectl コマンドを実行した際、次のようなエラーに遭遇することがあります。

error: You must be logged in to the server (Unauthorized)

なぜこのエラーが発生するのか？

「Unauthorized（未認証）」エラーは、詳細な情報がほとんど示されないことで知られています。Amazon EKS の世界では、このエラーが権限不足を意味することは稀です。多くの場合、クラスターが「あなたが誰であるか」を認識できていないことを意味します。これには通常、次の4つの理由が考えられます。

AWS 認証情報の期限切れ: SSO セッションがタイムアウトしたか、一時的な IAM トークンが期限切れになっています。SSO セッションのデフォルト制限は通常 8 時間または 12 時間です。
プロファイルの不一致: AWS CLI が「staging」プロファイルを向いている一方で、kubeconfig が「production」を探している状態です。
IAM ロールのマッピング不足: IAM ID がクラスター内部の「ゲストリスト」に追加されていません。これは aws-auth ConfigMap または EKS アクセスエントリ（Access Entries）で管理されます。
古い Kubeconfig: ~/.kube/config が、EKS でサポートされなくなった古い認証 API を使用しようとしています。

ステップ 1: AWS ID の確認

最初のステップは、実は Kubernetes のコマンドではありません。AWS の視点から見て、自分が誰として認識されているかを正確に確認する必要があります。次のコマンドを実行してください。

aws sts get-caller-identity

出力された Arn をよく確認してください。クラスターへのアクセス権を持つ IAM ロールまたはユーザーと一致していますか？AWS SSO を使用している場合、セッションがいつの間にか切れている可能性があります。念のため aws sso login を実行してください。

複数の環境を管理していますか？現在のターミナルセッションで正しいプロファイルがエクスポートされていることを確認してください。

export AWS_PROFILE=my-eks-profile
aws sts get-caller-identity

ステップ 2: Kubeconfig の更新

Kubeconfig ファイルは古くなることがあります。これは、クラスターが最近更新された場合や、ローカルの AWS 設定を変更した場合によく起こります。一度リセットしてファイルを再生成するのが、通常は最も早い解決策です。

リージョンとクラスター名を置き換えて、次のコマンドを実行します。

aws eks update-kubeconfig --region us-east-1 --name my-cluster-name

特定のプロファイルを使用している場合は、コマンドの末尾に追加して、設定が正しい認証情報を使用するようにします。

aws eks update-kubeconfig --region us-east-1 --name my-cluster-name --profile my-eks-profile

このコマンドにより ~/.kube/config が更新されます。これにより、aws eks get-token コマンドが認証を自動的に処理するように設定されます。

ステップ 3: EKS での IAM マッピングの確認

有効な AWS 認証情報を持っていても、クラスターから拒否されることがあります。デフォルトでは、EKS はクラスターを最初に作成した特定の IAM エンティティにのみアクセスを許可します。

方法 A: EKS アクセスエントリ（EKS 1.23+ 推奨）

モダンなクラスターではアクセスエントリ（Access Entries）を使用します。AWS コンソールの EKS > クラスター > [対象のクラスター] > アクセス を確認してください。自分の IAM ロールまたはユーザーがリストされていることを確認します。AmazonEKSClusterAdminPolicy のようなポリシーがアタッチされている必要があります。

方法 B: aws-auth ConfigMap

古いクラスターは aws-auth ConfigMap に依存しています。現在は「Unauthorized（未認証）」の状態であるため、自分自身でこれを確認することはできません。クラスター作成者または管理者に次のコマンドを実行してもらう必要があります。

kubectl get configmap aws-auth -n kube-system -o yaml

出力結果の mapRoles セクションに、あなたのロール ARN が含まれている必要があります。

mapRoles: |
  - groups:
    - system:masters
    rolearn: arn:aws:iam::123456789012:role/my-admin-role
    username: my-admin-role

このリストにロールが含まれていない場合、AWS の権限に関係なく「Unauthorized」のままとなります。

ステップ 4: Exec プラグインのデバッグ

~/.kube/config を開き、users: セクションを探します。次のようになっているはずです。

users:
- name: my-cluster-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: aws
      args: ["eks", "get-token", "--cluster-name", "my-cluster"]

コマンドとして aws-iam-authenticator が指定されている場合は、aws に切り替えてください。AWS CLI v2 はネイティブで EKS トークンをサポートしています。古い認証ツールよりも大幅に高速で安定しています。

動作確認

認証情報と設定を更新したら、簡単な権限チェックで接続をテストします。

kubectl auth can-i '*' '*'

yes と返ってくれば、完全に認証されています。no と返ってくる場合は、「Unauthorized」エラーは解消されていますが、IAM ロールにクラスター内部の必要な RBAC 権限が不足しています。

最後に、すべてのポッドをリストして正常に動作しているか確認します。

kubectl get pods -A

クイックヒント

時刻のズレ: システムクロックが 300 秒（5 分）以上ずれていると、AWS へのリクエストは失敗します。NTP で時刻を同期してください。
環境変数による上書き: AWS_ACCESS_KEY_ID などの環境変数は ~/.aws/credentials ファイルの設定を上書きします。競合が疑われる場合は、これらの変数をアンセットしてください。
バージョンの互換性: AWS CLI がバージョン 2.10 以上であることを確認してください。また、kubectl のバージョンはクラスターのマイナーバージョンとの差が 1 以内である必要があります（例: 1.30 クラスターには 1.29 を使用）。