IAM ロールを引き受けるように Kubernetes サービスアカウントを設定する - Amazon EKS

このページの改善にご協力ください

本ユーザーガイドの改善にご協力いただけませんか? このページの下部までスクロールし、[GitHub でこのページの編集] を選択します。皆さまにご協力いただくことで、あらゆる人々に使いやすいユーザーガイドになります。

IAM ロールを引き受けるように Kubernetes サービスアカウントを設定する

このトピックでは、AWS Identity and Access Management (IAM) ロールを引き受けるように Kubernetes サービスアカウントを設定する方法について説明します。任意の Pods はサービスアカウントを使用するように設定すると、ロールにアクセス許可がある AWS のサービス すべてにアクセスできます。

前提条件

  • 既存のクラスター。まだ所有していない場合は、Amazon EKS の使用開始 でのガイドのいずれかに従って作成します。

  • クラスター用の既存 IAM OpenID Connect (OIDC) プロバイダー。既に所有中かどうかの確認、または作成方法については「クラスターの IAM OIDC プロバイダーを作成する」を参照してください。

  • ご使用のデバイスまたは AWS CloudShell で、バージョン 2.12.3 以降、または AWS Command Line Interface (AWS CLI) のバージョン 1.27.160 以降がインストールおよび設定されていること。現在のバージョンを確認するには、「aws --version | cut -d / -f2 | cut -d ' ' -f1」を参照してください。macOS の yum、apt-get、または Homebrew などのパッケージマネージャは、AWS CLI の最新バージョンより数バージョン遅れることがあります。最新バージョンをインストールするには、「AWS Command Line Interface ユーザーガイド」の「AWS CLI のインストール、更新、およびアンインストール」と「aws configure でのクイック設定」を参照してください。AWS CloudShell にインストールされている AWS CLI バージョンは、最新バージョンより数バージョン遅れている可能性もあります。更新するには、「AWS CloudShell ユーザーガイド」の「ホームディレクトリへの AWS CLI のインストール」を参照してください。

  • デバイスまたは AWS CloudShell に、kubectl コマンドラインツールがインストールされていること。バージョンは、ご使用のクラスターの Kubernetes バージョンと同じか、1 つ前のマイナーバージョン以前、あるいはそれより新しいバージョンが使用できます。例えば、クラスターのバージョンが 1.29 である場合、kubectl のバージョン 1.28、1.29、または 1.30 が使用できます。kubectl をインストールまたはアップグレードする方法については、「kubectl のインストールまたは更新」を参照してください。

  • クラスター構成を含む既存の kubectl config ファイル。kubectl config ファイルの作成については、「Amazon EKS クラスターの kubeconfig ファイルを作成または更新する」を参照してください。

IAM ロールを Kubernetes サービスアカウントに関連付けるには

  1. 既存の IAM ポリシーを IAM ロールに関連付ける場合は、次のステップにスキップします。

    IAM ポリシーを作成します。ポリシーを自作することも、必要となるアクセス権限のいくつかが既に付与されている AWS 管理ポリシーをコピーし、特定の要件に応じてカスタマイズすることもできます。詳細については、『IAM ユーザーガイド』の「IAM ポリシーの作成」を参照してください。

    1. Pods にアクセスさせる AWS のサービス の権限を含むファイルを作成します。すべての AWS のサービス に対するアクションの全リストについては、「サービス認証リファレンス」を参照してください。

      次のコマンドを実行して、Amazon S3 バケットへの読み取り専用アクセスを許可するサンプルポリシーファイルを作成できます。必要に応じて、このバケットに設定情報またはブートストラップスクリプトを格納すると、Pod 内のコンテナがバケットからファイルを読み取り、アプリケーションにロードできます。このサンプルポリシーを作成する場合は、次のコンテンツをデバイスにコピーします。my-pod-secrets-bucket をバケット名に置き換え、コマンドを実行します。

      cat >my-policy.json <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::my-pod-secrets-bucket"
        }
    ]
}
EOF

    2. IAM ポリシーを作成します。

      aws iam create-policy --policy-name my-policy --policy-document file://my-policy.json

  2. IAM ロールを作成し、Kubernetes サービスアカウントに関連付けます。eksctl または AWS CLI を使用できます。

    eksctl
    前提条件

    デバイスまたは AWS CloudShell にインストールされている eksctl コマンドラインツールのバージョン 0.183.0 以降。eksctl をインストールまたはアップグレードするには、eksctl ドキュメントの「インストール」を参照してください。

    my-service-account を、eksctl で作成する Kubernetes サービスアカウントの名前に置き換え、IAM ロールに関連付けます。default は、eksctl でサービスアカウントを作成する名前空間に置き換えます。my-cluster の部分は、自分のクラスター名に置き換えます。my-role は、サービスアカウントを関連付けるロールの名前に置き換えます。まだ存在しない場合は、eksctl によって作成されます。111122223333 をアカウント ID に置き換え、my-policy を既存のポリシー名に置き換えます。

    eksctl create iamserviceaccount --name my-service-account --namespace default --cluster my-cluster --role-name my-role \
    --attach-policy-arn arn:aws:iam::111122223333:policy/my-policy --approve
    重要

    ロールまたはサービスアカウントが既に存在する場合、前のコマンドは失敗する可能性があります。eksctl には、そのような状況で使用できるさまざまなオプションがあります。詳細については、eksctl create iamserviceaccount --help を実行してください。

    AWS CLI

    1. IAM ロールを引き受ける既存の Kubernetes サービスアカウントがある場合は、この手順を省略できます。

      Kubernetes サービスアカウントを作成します。次のコンテンツをデバイスにコピーします。my-service-account を目的の名前に置き換え、必要に応じて default を別の名前空間に置き換えます。default を変更する場合、名前空間は既に存在している必要があります。

      cat >my-service-account.yaml <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-service-account
  namespace: default
EOF
kubectl apply -f my-service-account.yaml

    2. 次のコマンドを使用して、AWS アカウント ID を環境変数に設定します。

      account_id=$(aws sts get-caller-identity --query "Account" --output text)

    3. 次のコマンドを使用して、クラスターの OIDC ID プロバイダーを環境変数に設定します。my-cluster を自分のクラスター名に置き換えます。

      oidc_provider=$(aws eks describe-cluster --name my-cluster --region $AWS_REGION --query "cluster.identity.oidc.issuer" --output text | sed -e "s/^https:\/\///")

    4. サービスアカウントの名前空間と名前の変数を設定します。my-service-account を、ロールを引き受けさせる Kubernetes サービスアカウントに置き換えます。default は、サービスアカウントの名前空間に置き換えます。

      export namespace=default
export service_account=my-service-account

    5. IAM ロール用の信頼ポリシーファイルを作成するには、次のコマンドを実行します。名前空間内のすべてのサービスアカウントにロールの使用を許可する場合は、次の内容をデバイスにコピーします。StringEquals を StringLike に置き換え、$service_account を * に置き換えます。以下の StringEquals または StringLike 条件に複数のエントリを追加して、複数のサービスアカウントまたは名前空間がロールを引き受けられるようにできます。クラスターが属するアカウントとは異なる AWS アカウントのロールがロールを引き受けられるようにする方法については、「クロスアカウントの IAM アクセス許可」を参照してください。

      cat >trust-relationship.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::$account_id:oidc-provider/$oidc_provider"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "$oidc_provider:aud": "sts.amazonaws.com",
          "$oidc_provider:sub": "system:serviceaccount:$namespace:$service_account"
        }
      }
    }
  ]
}
EOF

    6. ロールを作成します。my-role を IAM ロールの名前に、my-role-description をユーザーロールの表記に置き換えます。

      aws iam create-role --role-name my-role --assume-role-policy-document file://trust-relationship.json --description "my-role-description"

    7. IAM ポリシーをロールにアタッチします。my-role を IAM ロールの名前に置き換え、作成した既存のポリシーの名前に my-policy を置き換えます。

      aws iam attach-role-policy --role-name my-role --policy-arn=arn:aws:iam::$account_id:policy/my-policy

    8. サービスアカウントに、サービスアカウントで引き受ける IAM ロールの Amazon リソースネーム (ARN) の注釈を付けます。my-role を既存の IAM ロールの名前に置き換えます。前の手順で、クラスターが属するアカウントとは異なる AWS アカウントのロールに、ロールの引き受けを許可したと仮定します。その場合、AWS アカウントおよび他のアカウントからのロールを必ず指定してください。詳細については、「クロスアカウントの IAM アクセス許可」を参照してください。

      kubectl annotate serviceaccount -n $namespace $service_account eks.amazonaws.com/role-arn=arn:aws:iam::$account_id:role/my-role

  3. ロールとサービスアカウントが正しく設定されていることを確認します。

    1. IAM ロールの信頼ポリシーが正しく設定されていることを確認します。

      aws iam get-role --role-name my-role --query Role.AssumeRolePolicyDocument

      出力例は次のとおりです。

      {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::111122223333:oidc-provider/oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:default:my-service-account",
                    "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

    2. 前の手順でロールにアタッチしたポリシーが、そのロールにアタッチされていることを確認します。

      aws iam list-attached-role-policies --role-name my-role --query AttachedPolicies[].PolicyArn --output text

      出力例は次のとおりです。

      arn:aws:iam::111122223333:policy/my-policy

    3. 使用するポリシーの Amazon リソースネーム (ARN) を保存する変数を設定します。my-policy を、アクセス許可を確認するポリシーの名前に置き換えます。

      export policy_arn=arn:aws:iam::111122223333:policy/my-policy

    4. ポリシーのデフォルトバージョンを確認します。

      aws iam get-policy --policy-arn $policy_arn

      出力例は次のとおりです。

      {
    "Policy": {
        "PolicyName": "my-policy",
        "PolicyId": "EXAMPLEBIOWGLDEXAMPLE",
        "Arn": "arn:aws:iam::111122223333:policy/my-policy",
        "Path": "/",
        "DefaultVersionId": "v1",
        [...]
    }
}

    5. ポリシーの内容を表示して、Pod で必要な権限がすべて含まれていることを確認します。必要であれば、次のコマンドの 1 を、前の出力で返されたバージョンに置き換えます。

      aws iam get-policy-version --policy-arn $policy_arn --version-id v1

      出力例は次のとおりです。

      {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::my-pod-secrets-bucket"
        }
    ]
}

      前の手順でサンプルポリシーを作成した場合、出力は同じになります。別のポリシーを作成した場合、サンプルの内容は異なります。

    6. Kubernetes サービスアカウントにロールが注釈されていることを確認します。

      kubectl describe serviceaccount my-service-account -n default

      出力例は次のとおりです。

      Name:                my-service-account
Namespace:           default
Annotations:         eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/my-role
Image pull secrets:  <none>
Mountable secrets:   my-service-account-token-qqjfl
Tokens:              my-service-account-token-qqjfl
[...]

  4. (オプション) サービスアカウントの AWS Security Token Service エンドポイントを設定する。AWS では、グローバルエンドポイントの代わりに地域の AWS STS エンドポイントを使用することを推奨しています。これにより、レイテンシーが減少し、組み込みの冗長性が提供され、セッショントークンの有効性が向上します。

次のステップ

Kubernetes サービスアカウントを使用するように Pods を設定するには