投稿

EKS の IRSA から Pod Identity への移行手順と判断ポイント

EKS の IRSA を Pod Identity に移行すべきかを整理し、Agent の導入、IAM ロールの信頼ポリシー、関連付けの作成、Pod での確認まで説明します。

投稿日
投稿者
13 分で読めます
EKS の IRSA から Pod Identity への移行手順と判断ポイント

EKS の IRSA を Pod Identity に移行する必要はあるのでしょうか。必須ではありません。 現在の IRSA が安定しており、クラスターごとの OIDC プロバイダーや IAM ロールの信頼ポリシーの管理が負担になっていなければ、新しい方式という理由だけで切り替える必要はありません。複数クラスターでの設定を簡素化し、ServiceAccount と IAM ロールの対応を EKS 側で管理したい場合には、Pod Identity が選択肢になります。AWS の Pod Identity 設定ガイド

IRSA は OIDC identity federation と STS の Web Identity を利用します。仕組みとしては、セルフマネージド Kubernetes やオンプレミス環境で認証を AWS IAM と連携する構成に近いものの、IRSA 自体は EKS の機能です。一方、Pod Identity は EKS 専用の AWS による統合で、EKS の関連付け、EKS Auth、ノード上の Agent を使って認証情報を提供します。設定を EKS に集約できる反面、EKS 固有の仕組みへの依存は増えます。AWS の EKS における IAM ベストプラクティス

移行する場合は、EKS Pod Identity Agent の導入、pods.eks.amazonaws.com を信頼する IAM ロールの設定、既存の namespace と ServiceAccount に対する関連付けの作成、IRSA annotation の削除、Pod の再作成という順序で進めます。S3 や Secrets Manager などへのアクセスを許可する既存の IAM 権限ポリシーは、通常そのまま利用できます。

以下では、EKS の EC2 ノードで動く database-backup/database-backup-sa を例にします。IRSA の設定については、既存の記事も参照してください。

IRSA と Pod Identity の違い

項目IRSAEKS Pod Identity
IAM ロールの信頼先クラスターの IAM OIDC プロバイダーpods.eks.amazonaws.com
ServiceAccount の設定eks.amazonaws.com/role-arn annotationnamespace、ServiceAccount、ロールを結ぶ EKS の関連付け
認証情報の取得Web Identity token と STSPod Identity Agent と EKS Auth
ノード側の構成Pod Identity Agent は不要通常の EC2 ノードでは Agent が必要。EKS Auto Mode には組み込み済み

Pod Identity のロールは特定クラスターの OIDC プロバイダーに紐づかないため、別のクラスターの関連付けでも再利用できます。ただし、関連付けを作成するだけでは、既存の Pod は IRSA から切り替わりません。IRSA 用の環境変数が残っていると、AWS SDK のデフォルト認証情報チェーンが IRSA を先に選ぶ場合があります。AWS SDK の対応状況と認証情報チェーン

移行前に確認すること

クラスター名、リージョン、namespace、ServiceAccount、現在のロール ARN を控えます。また、アプリケーションが Pod Identity に対応する AWS SDK とデフォルト認証情報チェーンを使っていることを確認してください。固定のアクセスキーや独自の credential provider は、関連付けだけでは切り替わりません。以下は通常の EKS EC2 ノードを対象とします。Fargate や特殊なノード環境では、事前に Agent の要件を確認してください。

コマンドは Bash の例です。値を環境に合わせて変更します。

1
2
3
4
5
6
7
8
9
10

CLUSTER_NAME=my-cluster
AWS_REGION=ap-northeast-1
NAMESPACE=database-backup
SERVICE_ACCOUNT=database-backup-sa
ROLE_NAME=DatabaseBackupRole
ACCOUNT_ID=111122223333
ROLE_ARN="arn:aws:iam::${ACCOUNT_ID}:role/${ROLE_NAME}"

kubectl get serviceaccount "$SERVICE_ACCOUNT" -n "$NAMESPACE" -o yaml
aws iam get-role --role-name "$ROLE_NAME" --query 'Role.AssumeRolePolicyDocument'

1. Pod Identity Agent を導入する

まず aws eks describe-addon --cluster-name "$CLUSTER_NAME" --addon-name eks-pod-identity-agent --region "$AWS_REGION" で導入済みか確認します。通常の EC2 ノードで未導入の場合は、次を実行します。

1
2
3
4
5
6

aws eks create-addon \
  --cluster-name "$CLUSTER_NAME" \
  --addon-name eks-pod-identity-agent \
  --region "$AWS_REGION"

kubectl get daemonset -n kube-system eks-pod-identity-agent

ワークロードが稼働するノードで Agent が動いていることを確認してから、切り替えを進めます。Agent はノードの IAM ロールの権限を使用し、Agent 自身の IRSA ロールは使いません。EKS Auto Mode には Pod Identity が組み込まれているため、この add-on の追加は不要です。Agent の導入ガイド、EKS add-on 一覧

2. IAM ロールの信頼ポリシーを更新する

IRSA のロールはクラスターの OIDC プロバイダーを信頼し、sts:AssumeRoleWithWebIdentity を許可します。Pod Identity を使うには、既存の信頼ポリシーの Statement 配列に次のステートメントを追加します。

1
2
3
4
5
6
7
8
9
10

{
  "Effect": "Allow",
  "Principal": {
    "Service": "pods.eks.amazonaws.com"
  },
  "Action": [
    "sts:AssumeRole",
    "sts:TagSession"
  ]
}

移行中は従来の OIDC ステートメントを残し、旧 Pod が IRSA を使えるようにします。S3 や Secrets Manager への権限ポリシーは、認証情報の取得方式を変えるだけなら修正不要です。CLI を使う場合は信頼ポリシー全体を取得して編集し、aws iam update-assume-role-policy --role-name "$ROLE_NAME" --policy-document file://trust-policy.json で更新します。上のステートメントだけで既存のポリシーを上書きしないでください。AWS の信頼ポリシー例

3. Pod Identity の関連付けを作成する

1
2
3
4
5
6
7
8
9
10
11
12

aws eks create-pod-identity-association \
  --cluster-name "$CLUSTER_NAME" \
  --namespace "$NAMESPACE" \
  --service-account "$SERVICE_ACCOUNT" \
  --role-arn "$ROLE_ARN" \
  --region "$AWS_REGION"

aws eks list-pod-identity-associations \
  --cluster-name "$CLUSTER_NAME" \
  --namespace "$NAMESPACE" \
  --service-account "$SERVICE_ACCOUNT" \
  --region "$AWS_REGION"

関連付けは EKS が管理するため、ServiceAccount に新しい annotation を付ける必要はありません。設定の反映には短い遅延が生じる場合があります。関連付けを確認してからワークロードを切り替えてください。AWS CLI リファレンス

4. IRSA annotation を削除し、Pod を再作成する

まず Helm chart、Kustomize、GitOps の ServiceAccount 定義から eks.amazonaws.com/role-arn を削除します。そうしないと、次のデプロイで元に戻る可能性があります。続いてクラスター上の ServiceAccount を更新します。

1
2
3

kubectl annotate serviceaccount "$SERVICE_ACCOUNT" \
  -n "$NAMESPACE" \
  eks.amazonaws.com/role-arn-

既存 Pod の環境変数やマウントは ServiceAccount の更新だけでは変わりません。Deployment の場合は Pod を再作成します。

1
2

kubectl rollout restart deployment/database-backup -n "$NAMESPACE"
kubectl rollout status deployment/database-backup -n "$NAMESPACE"

CronJob の場合は次の Job を待つか、確認用の Job を作成します。上の Deployment 用コマンドは CronJob には使用しません。

5. Pod が実際に使用する IAM ロールを確認する

新しく作成された Pod の環境変数を確認します。

1
2

kubectl exec -n "$NAMESPACE" <new-pod-name> -- \
  env | grep -E '^AWS_(CONTAINER_CREDENTIALS_FULL_URI|CONTAINER_AUTHORIZATION_TOKEN_FILE|ROLE_ARN|WEB_IDENTITY_TOKEN_FILE)='

AWS_CONTAINER_CREDENTIALS_FULL_URI と AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE が表示され、IRSA 用の AWS_ROLE_ARN と AWS_WEB_IDENTITY_TOKEN_FILE がないことを確認します。さらに、同じアプリケーションコンテナ内で aws sts get-caller-identity を実行し、想定した assumed-role ARN が返るか確認します。AWS CLI が入っていない場合は、アプリケーションと同じ AWS SDK から STS を呼び出してください。最後に、必要な S3 や Secrets Manager の操作も試し、権限まで確認します。Pod Identity の仕組み

そのロールを共有するすべてのワークロードの移行が終わってから、古い OIDC の信頼ステートメントを削除します。他の ServiceAccount が IRSA を使っている可能性があり、クラスターの IAM OIDC プロバイダーにも別の用途があるかもしれません。

よくある質問

関連付けを作成したのに、Pod が IRSA を使い続けるのはなぜですか？

annotation の削除、Pod の再作成、アプリケーションで別の認証情報を指定していないかを確認してください。関連付けだけでは、AWS SDK の認証情報チェーンで先に見つかった認証情報は上書きされません。

既存の IAM ロールは使えますか？

使えます。権限ポリシーは残し、信頼ポリシーに pods.eks.amazonaws.com を追加します。複数の ServiceAccount で同じロールを使う場合は、同じ権限を与えてよいか確認してください。AWS の IAM ベストプラクティス

IRSA に戻すにはどうすればよいですか？

古い OIDC の信頼ステートメントを残していれば、デプロイ設定に eks.amazonaws.com/role-arn annotation を戻し、Pod を再作成します。get-caller-identity と必要な AWS 操作を確認したうえで、関連付けを削除するか判断してください。

eksctl で管理しているクラスターでは、eksctl utils migrate-to-pod-identity --cluster my-cluster で移行計画を確認し、--approve を付けて適用する方法もあります。対象の ServiceAccount、add-on、信頼ポリシーの変更内容を事前に確認してください。eksctl の移行ガイド

AWS, EKS
AWS EKS IAM Kubernetes
この投稿は投稿者によって CC BY 4.0 の下でライセンスされています。

トレンドのタグ

AWS IAM EC2 S3 Database EKS K8S SSM AI RDS