アクセスエントリを管理する - Amazon EKS

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

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

アクセスエントリを管理する

前提条件
  • Amazon EKS クラスターのクラスターアクセスオプションに関する知識。詳細については、「Kubernetes API へのアクセスを許可する 」を参照してください。

  • 既存の Amazon EKS クラスター。デプロイするには、「Amazon EKS の使用開始」を参照してください。アクセスエントリを使用してクラスターの認証モードを変更するには、クラスターのプラットフォームバージョンが、次の表に記載されているバージョンと同じかそれ以降、または表に記載されているバージョンよりも Kubernetes のバージョンが新しい必要があります。

    Kubernetes バージョン プラットフォームバージョン
    1.30 eks.2
    1.29 eks.1
    1.28 eks.6
    1.27 eks.10
    1.26 eks.11
    1.25 eks.12
    1.24 eks.15
    1.23 eks.17

    現在の Kubernetes バージョンとプラットフォームバージョンを確認するには、次のコマンドの my-cluster をクラスターの名前に置き換えて、変更したコマンドを実行します: aws eks describe-cluster --name my-cluster --query 'cluster.{"Kubernetes Version": version, "Platform Version": platformVersion}'

    重要

    Amazon EKS は、クラスターを表に記載されているプラットフォームバージョンに更新したあと、クラスターを最初に作成した IAM プリンシパルに対し、クラスターへの管理者権限を持つアクセスエントリを作成します。その IAM プリンシパルにクラスターへの管理者権限を与えたくない場合は、Amazon EKS が作成したアクセスエントリを削除します。

    前の表に記載されているものより前のプラットフォームバージョンのクラスターの場合、クラスター作成者が常にクラスター管理者になります。クラスターを作成した IAM ユーザーまたはロールからは、クラスター管理者権限を削除することはできません。

  • クラスターに対し CreateAccessEntryListAccessEntriesDescribeAccessEntryDeleteAccessEntryUpdateAccessEntry のアクセス許可を持つ IAM プリンシパル。Amazon EKS アクセス許可の詳細については、サービス認証リファレンスの「Amazon Elastic Kubernetes Service で定義されるアクション」を参照してください。

  • アクセスエントリを作成する既存の IAM プリンシパル、または更新または削除する既存のアクセスエントリ。

アクセスエントリの設定

アクセスエントリを使い始めるには、クラスターの認証モードを API_AND_CONFIG_MAP または API モードに変更する必要があります。これにより、アクセスエントリ用の API が追加されます。

AWS Management Console
アクセスエントリを作成するには
  1. Amazon EKS コンソール (https://console.aws.amazon.com/eks/home#/clusters) を開きます。

  2. アクセスエントリを作成するクラスターの名前を選択します。

  3. [リモートアクセス] タブを選択します。

  4. 認証モードには、クラスターの現在の認証モードが表示されます。モードが EKS API と表示されている場合は、すでにアクセスエントリを追加でき、残りの手順は省略できます。

  5. [アクセスの管理] を選択します。

  6. クラスター認証モードの場合は、EKS API でモードを選択します。認証モードを、EKS API およびアクセスエントリを削除するモードに戻すことはできないことに注意してください。

  7. [Save changes] (変更の保存) をクリックします。Amazon EKS がクラスターの更新を開始し、クラスターのステータスが Updating に変わり、変更が [更新履歴] タブに記録されます。

  8. クラスターのステータスが Active に戻るまで待ちます。クラスターが Active になったら、アクセスエントリの作成 の手順に従って IAM プリンシパルのクラスターへのアクセスを追加できます。

AWS CLI
前提条件

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

  1. 以下のコマンドを実行します。my-cluster の部分は、自分のクラスター名に置き換えます。ConfigMap メソッドを完全に無効にする場合は、API_AND_CONFIG_MAPAPI に置き換えてください。

    Amazon EKS がクラスターの更新を開始し、クラスターのステータスが UPDATING に変わり、変更が aws eks list-updates に記録されます。

    aws eks update-cluster-config --name my-cluster --access-config authenticationMode=API_AND_CONFIG_MAP
  2. クラスターのステータスが Active に戻るまで待ちます。クラスターが Active になったら、アクセスエントリの作成 の手順に従って IAM プリンシパルのクラスターへのアクセスを追加できます。

アクセスエントリの作成

考慮事項

アクセスエントリを作成する前に、次の点を考慮してください。

  • アクセスエントリには、1 つだけの既存の IAM プリンシパルの Amazon リソースネーム (ARN) が含まれます。IAM プリンシパルは複数のアクセスエントリに含めることはできません。指定する ARN に関するその他の考慮事項

    • IAM のベストプラクティスでは、長期認証情報を持つ IAM ユーザーではなく、短期認証情報を持つ IAM ロールを使用してクラスターにアクセスすることを推奨しています。詳細は、IAM ユーザーガイドの「人間のユーザーが一時的な認証情報を使用して AWS にアクセスするには、ID プロバイダーとのフェデレーションの使用が必要です」を参照してください。

    • ARN が IAM ロール用の場合は、パスを含めることができます。aws-auth ConfigMap エントリの ARN にはパスを含めることはできません。例えば、ARN は arn:aws:iam::111122223333:role/development/apps/my-role または arn:aws:iam::111122223333:role/my-role にすることができます。

    • アクセスエントリのタイプが STANDARD 以外の場合 (タイプに関する次の考慮事項を参照)、ARN はクラスターと同じ AWS アカウント である必要があります。タイプが STANDARD の場合、ARN はクラスターが属するアカウントと同じ、または異なる AWS アカウント でもかまいません。

    • アクセスエントリの作成後に IAM プリンシパルを変更することはできません。

    • この ARN を含む IAM プリンシパルを削除しても、アクセスエントリは自動的に削除されません。削除する IAM プリンシパルの ARN を含むアクセスエントリを削除することをお勧めします。アクセスエントリを削除せず、IAM プリンシパルを再作成すると、同じ ARN があっても、アクセスエントリは機能しません。これは、再作成された IAM プリンシパルの ARN は同じですが、再作成された IAM プリンシパルの roleID または userID (aws sts get-caller-identity AWS CLI コマンドで確認できます) は、元の IAM プリンシパルの ARN とは異なるためです。アクセスエントリの IAM プリンシパルの roleID または userID が表示されない場合でも、Amazon EKS はそれをアクセスエントリとともに保存します。

  • 各アクセスエントリにはタイプがあります。EC2 Linux (Linux または Bottlerocket のセルフマネージド型ノードで使用される IAM ロールの場合)、EC2 Windows (Windows のセルフマネージド型ノードで使用される IAM ロールの場合)、FARGATE_LINUX (AWS Fargate (Fargate) で使用される IAM ロールの場合)、またはSTANDARD をタイプとして指定できます。タイプを指定しない場合、Amazon EKS は自動的にタイプを STANDARD に設定します。マネージド型ノードグループや Fargate プロファイルに使用される IAM ロールのアクセスエントリを作成する必要はありません。Amazon EKS は、クラスターのプラットフォームバージョンに関係なくこれらのロールのエントリを aws-auth ConfigMap に追加するためです。

    アクセスエントリの作成後にタイプを変更することはできません。

  • アクセスエントリのタイプが STANDARD の場合、アクセスエントリのユーザー名を指定できます。ユーザー名の値を指定しない場合、Amazon EKS はアクセスエントリのタイプと、指定した IAM プリンシパルが IAM ロールか IAM ユーザーかに応じて、以下のいずれかの値を設定します。独自のユーザー名を指定する特別な理由がない限り、ユーザー名を指定せず、Amazon EKS に自動生成させることをお勧めします。独自のユーザー名を指定する場合:

    • system:eks:aws:amazon:、または iam: で始めることはできません。

    • ユーザー名が IAM ロール用の場合は、ユーザー名の末尾に {{SessionName}} を追加することをお勧めします。ユーザー名に {{SessionName}} を追加する場合、ユーザー名の {{SessionName}} の前にコロンを含める必要があります。このロールを引き受けると、ロールを引き受けるときに指定されたセッションの名前が自動的にクラスターに渡され、CloudTrail ログに表示されます。例えば、john{{SessionName}} というユーザー名にはできません。ユーザー名は :john{{SessionName}} または jo:hn{{SessionName}} でなければなりません。コロンは {{SessionName}} の前になければいけません。次の表の Amazon EKS によって生成されたユーザー名には ARN が含まれています。ARN にはコロンが含まれているため、この要件を満たしています。ユーザー名に {{SessionName}} を含めなければ、コロンは不要です。

    IAM プリンシパルタイプ タイプ Amazon EKS が自動的に設定するユーザー名の値
    ユーザー STANDARD

    ユーザーの ARN。例:arn:aws:iam::111122223333:user/my-user

    ロール STANDARD

    想定されるロールの STS ARN。Amazon EKS では、{{SessionName}} がロールに追加されます。

    例:arn:aws:sts::111122223333:assumed-role/my-role/{{SessionName}}

    指定したロールの ARN にパスが含まれている場合、Amazon EKS は生成されたユーザー名からそのパスを削除します。

    ロール EC2 Linux、または EC2 Windows

    system:node:{{EC2PrivateDNSName}}

    ロール FARGATE_LINUX

    system:node:{{SessionName}}

    アクセスエントリの作成後にユーザー名を変更することができます。

  • アクセスエントリのタイプが STANDARD で、Kubernetes RBAC 認証を使用する場合は、アクセスエントリに 1 つ以上のグループ名を追加できます。アクセスエントリを作成したら、グループ名を追加および削除できます。IAM プリンシパルがクラスター上の Kubernetes オブジェクトにアクセスできるようにするには、Kubernetes ロールベース認証 (RBAC) オブジェクトを作成して管理する必要があります。クラスター上に Kubernetes RoleBinding または ClusterRoleBinding を作成し、グループ名を kind: Groupsubject として指定します。Kubernetes は、バインディングの roleRef でも指定した Kubernetes Role または ClusterRole オブジェクトで指定したすべてのクラスターオブジェクトにアクセスすることを IAM プリンシパルに許可します。グループ名を指定する場合は、Kubernetes ロールベース認証 (RBAC) オブジェクトについて理解しておくことをお勧めします。詳細については、「Kubernetes ドキュメント」の「RBAC 認証の使用」を参照してください。

    重要

    Amazon EKS は、クラスターに存在する Kubernetes RBAC オブジェクトに、指定したグループ名が含まれていることを確認しません。

    クラスター上の Kubernetes オブジェクトに IAM プリンシパルがアクセスするのを許可する Kubernetes の代わりに、またはそれに加えて、Amazon EKS アクセスポリシーをアクセスエントリに関連付けることができます。Amazon EKS は、IAM プリンシパルがアクセスポリシーのアクセス許可を使用してクラスター上の Kubernetes オブジェクトにアクセスすることを許可します。アクセスポリシーのアクセス許可の範囲は、指定した Kubernetes 名前空間に限定できます。アクセスポリシーを使用する場合、Kubernetes RBAC オブジェクトを管理する必要はありません。詳細については、「アクセスポリシーとアクセスエントリとの関連付けおよび関連付け解除」を参照してください。

  • タイプが EC2 Linux または EC2 Windows のアクセスエントリを作成する場合、アクセスエントリを作成する IAM プリンシパルには iam:PassRole アクセス許可が必要です。詳細については、IAM ユーザーガイドの「AWS のサービス にロールを渡すアクセス許可をユーザーに付与する」を参照してください。

  • 標準的な IAM 動作と同様に、アクセスエントリの作成と更新は最終的には一貫性があり、最初の API コールが正常に戻ってから有効になるまでに数秒かかる場合があります。発生する可能性のあるこれらの遅延を考慮して、アプリケーションを設計する必要があります。アプリケーションの重要で高可用性のコードパスには、アクセスエントリの作成や更新を含めないことをお勧めします。代わりに、実行頻度が低い別の初期化またはセットアップルーチンに の変更を加えます。また、本番稼働ワークフローが依存する前に、変更が伝達済みであることを確認します。

  • アクセスエントリは、サービスリンクロールをサポートしていません。プリンシパル ARN がサービスリンクロールである場合、アクセスエントリを作成することはできません。サービスリンクロールは、arn:aws:iam::*:role/aws-service-role/* 形式の ARN によって識別できます。

AWS Management Console または AWS CLI を使用してアクセスエントリを作成できます。

AWS Management Console
アクセスエントリを作成するには
  1. Amazon EKS コンソール (https://console.aws.amazon.com/eks/home#/clusters) を開きます。

  2. アクセスエントリを作成するクラスターの名前を選択します。

  3. [リモートアクセス] タブを選択します。

  4. [アクセスエントリの作成] を選択します。

  5. IAM プリンシパルには、既存の IAM ロールまたはユーザーを選択します。IAM のベストプラクティスでは、長期認証情報を持つ IAM ユーザーではなく、短期認証情報を持つ IAM ロールを使用してクラスターにアクセスすることを推奨しています。詳細は、IAM ユーザーガイドの「人間のユーザーが一時的な認証情報を使用して AWS にアクセスするには、ID プロバイダーとのフェデレーションの使用が必要です」を参照してください。

  6. [タイプ] で、アクセスエントリがセルフマネージド型の Amazon EC2 ノードに使用されるノードロール用のものである場合は、[EC2 Linux] または [EC2 Windows] を選択します。それ以外の場合は、デフォルト (標準) をそのまま使用します。

  7. 選択した タイプ標準で、ユーザー名を指定する場合は、ユーザー名を入力します。

  8. 選択した タイプ標準で、IAM プリンシパルに Kubernetes RBAC 認証を使用したい場合は、グループに 1 つ以上の名前を指定します。グループ名を指定せず、Amazon EKS 認証を使用する場合は、後のステップで、またはアクセスエントリの作成後にアクセスポリシーを関連付けることができます。

  9. (オプション) [タグ] では、アクセスエントリにラベルを割り当てます。例えば、同じタグを持つすべてのリソースを検索しやすくするためです。

  10. [Next] を選択します。

  11. [アクセスポリシーの追加] ページで、選択したタイプが標準で、Amazon EKS が IAM プリンシパルにクラスター上の Kubernetes オブジェクトへのアクセス許可を与えることを許可する場合は、次の手順を実行します。それ以外の場合は、次へ を選択します。

    1. [ポリシー名] には、アクセスポリシーを選択します。アクセスポリシーのアクセス許可は表示できませんが、Kubernetes ユーザー向け ClusterRole オブジェクトと同様のアクセス許可が含まれています。詳細については、Kubernetes ドキュメントの「ユーザー向けロール」を参照してください。

    2. 以下のオプションのいずれかを選択します。

      • クラスター — Amazon EKS が IAM プリンシパルに、クラスター上のすべての Kubernetes オブジェクトのアクセスポリシー内のアクセス許可があるように承認する場合は、このオプションを選択します。

      • Kubernetes 名前空間 — Amazon EKS が IAM プリンシパルに、クラスター上の特定の Kubernetes 名前空間のすべての Kubernetes オブジェクトのアクセスポリシー内のアクセス許可があるように承認する場合は、このオプションを選択します。[名前空間]には、クラスター上の Kubernetes 名前空間の名前を入力します。名前空間をさらに追加する場合は、[新しい名前空間を追加する] を選択し、名前空間名を入力します。

    3. ポリシーを追加するには、[ポリシーを追加] を選択します。ポリシーごとに異なる範囲を設定できますが、各ポリシーは 1 回しか追加できません。

    4. [Next] を選択します。

  12. アクセスエントリの設定を確認してください。何かが正しくないと思われる場合は、[戻る] を選択して手順に戻り、エラーを修正します。設定が正しければ、[作成] を選択します。

AWS CLI
前提条件

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

アクセスエントリを作成するには

アクセスエントリを作成するには、以下のいずれかの例を使用できます。

  • セルフマネージド型 Amazon EC2 Linux ノードグループのアクセスエントリを作成します。my-cluster はクラスターの名前、111122223333 は自分の AWS アカウント ID に、eks-my-Cluster-Self-Managed-NG-1ノード IAM ロールの名前に置き換えます。ノードグループが Windows ノードグループの場合は、EC2_LinuxEC2_Windows に置き換えてください。

    aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/EKS-my-cluster-self-managed-ng-1 --type EC2_Linux

    STANDARD 以外のタイプを指定する場合、--kubernetes-groups オプションは使用できません。タイプが STANDARD 以外の値であるため、このアクセスエントリにアクセスポリシーを関連付けることはできません。

  • Amazon EC2 セルフマネージド型ノードグループには使用されていない IAM ロールを許可するアクセスエントリを作成し、Kubernetes にクラスターへのアクセスを許可してもらいます。my-cluster をクラスターの名前に、111122223333 を AWS アカウント ID に、my-role を IAM ロールの名前に置き換えます。Viewer は、クラスター上の Kubernetes RoleBinding または ClusterRoleBinding オブジェクトで指定したグループの名前に置き換えます。

    aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/my-role --type STANDARD --user Viewers --kubernetes-groups Viewers
  • IAM ユーザーがクラスターに対して認証できるようにするアクセスエントリを作成します。これも可能であるためこの例が示されていますが、IAM のベストプラクティスでは、長期認証情報を持つ IAM ユーザーではなく、短期認証情報を持つ IAM ロールを使用してクラスターにアクセスすることを推奨しています。詳細は、IAM ユーザーガイドの「人間のユーザーが一時的な認証情報を使用して AWS にアクセスするには、ID プロバイダーとのフェデレーションの使用が必要です」を参照してください。

    aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:user/my-user --type STANDARD --username my-user

    このユーザーに Kubernetes API ディスカバリーロールのアクセス許可よりも多くのクラスターへのアクセスを許可したい場合は、--kubernetes-groups オプションが使用されていないため、アクセスエントリにアクセスポリシーを関連付ける必要があります。詳細については、「アクセスポリシーとアクセスエントリとの関連付けおよび関連付け解除」と Kubernetes ドキュメントの「API ディスカバリーロール」を参照してください。

アクセスエントリの更新

AWS Management Console または AWS CLI を使用してアクセスエントリを更新できます。

AWS Management Console
アクセスエントリを更新するには
  1. Amazon EKS コンソール (https://console.aws.amazon.com/eks/home#/clusters) を開きます。

  2. アクセスエントリを作成するクラスターの名前を選択します。

  3. [リモートアクセス] タブを選択します。

  4. 更新するアクセスエントリを選択します。

  5. [編集] を選択します。

  6. [ユーザー名] では、既存の値を変更できます。

  7. [グループ]では、既存のグループ名を削除したり、新しいグループ名を追加したりできます。system: nodes または system: bootstrappers というグループ名が存在する場合は、削除しないでください。これらのグループを削除すると、クラスターが正しく機能しなくなる可能性があります。グループ名を指定せず、Amazon EKS 認証を使用する場合は、後のステップで、アクセスポリシーを関連付けてください。

  8. [タグ] では、アクセスエントリにラベルを割り当てます。例えば、同じタグを持つすべてのリソースを検索しやすくするためです。また、既存のタグを削除することもできます。

  9. [変更の保存] をクリックします。

  10. アクセスポリシーをエントリに関連付ける場合は、アクセスポリシーとアクセスエントリとの関連付けおよび関連付け解除 を参照してください。

AWS CLI
前提条件

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

アクセスエントリを更新するには

my-cluster はクラスターの名前、111122223333 は AWS アカウント ID に、EKS-my-cluster-my-namespace-Viewers は IAM ロールの名前に置き換えます。

aws eks update-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/EKS-my-cluster-my-namespace-Viewers --kubernetes-groups Viewers

アクセスエントリのタイプが STANDARD 以外の値の場合、--kubernetes-groups オプションは使用できません。また、アクセスポリシーを STANDARD 以外のタイプのアクセスエントリに関連付けることもできません。

アクセスエントリの削除

アクセスエントリを誤って削除したことが判明した場合は、いつでも再作成できます。削除するアクセスエントリがアクセスポリシーに関連付けられている場合、その関連付けは自動的に削除されます。アクセスエントリを削除する前に、アクセスポリシーとアクセスエントリの関連付けを解除する必要はありません。

AWS Management Console または AWS CLI を使用してアクセスエントリを削除できます。

AWS Management Console
アクセスエントリを削除するには
  1. Amazon EKS コンソール (https://console.aws.amazon.com/eks/home#/clusters) を開きます。

  2. アクセスエントリを削除するクラスターの名前を選択します。

  3. [リモートアクセス] タブを選択します。

  4. [アクセスエントリ] リストで、削除するアクセスエントリを選択します。

  5. [Delete] を選択します。

  6. 確認ダイアログボックスで、[削除] を選択します。

AWS CLI
前提条件

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

アクセスエントリを削除するには

my-cluster をクラスターの名前、111122223333 を AWS アカウント ID に、my-role をクラスターにアクセスさせたくない IAM ロールの名前に置き換えます。

aws eks delete-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/my-role