Amazon EKS クラスターにおける、アクセスエントリに関する問題をトラブルシューティングする方法を教えてください。

解決策

前提条件: Amazon EKS クラスターを Kubernetes バージョン 1.23 以降で実行中であること。

注: AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI で発生したエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

認証モードに関するエラー

クラスターの認証モードを変更する際、次のエラーメッセージが表示されます。

• "An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Unsupported authentication mode update from API_AND_CONFIG_MAP to CONFIG_MAP." (認証モード変更がサポートされていない)
• "An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Unsupported authentication mode update from API to CONFIG_MAP." (認証モード変更がサポートされていない)
• "An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Unsupported authentication mode update from API to API_AND_CONFIG_MAP." (認証モード変更がサポートされていない)

認証モードを設定する際の操作は不可逆です。たとえば、モードを API に変更した後、CONFIG_MAP または API_AND_CONFIG_MAP に戻すことはできません。詳細については、「簡素化された Amazon EKS アクセス管理制御に関する詳細」を参照してください。

認証モードに関連するエラーを防ぐには、aws-auth ConfigMap ではなく、アクセスエントリを使用します。

AccessDeniedException エラー

AWS Identity and Access Management (IAM) プリンシパルにはアクセスエントリの使用に十分な権限が欠けている場合、エラーメッセージが表示されます。エラーメッセージは、次の例に類似した形式です。

"An error occurred (AccessDeniedException) when calling the CreateAccessEntry operation: User: [principalARN] is not authorized to perform: eks:CreateAccessEntry on resource: arn:aws:eks:us-east-1:000000000:cluster/your-eks-cluster." (操作の呼び出し権限が不足している)

この問題を解決するには、リクエストを行う IAM プリンシパルの IAM ポリシーに次の権限を追加します。

• CreateAccessEntry
• ListAccessEntries
• DescribeAccessEntry
• DeleteAccessEntry
• UpdateAccessEntry

CONFIG_MAP から API_AND_CONFIG_MAP への移行または更新に関する問題

アクセスエントリを CONFIG_MAP から API_AND_CONFIG_MAP に移行または更新する際、次の通知が表示去ります。

"The mapping of the node IAM role defined in the existing ConfigMap/AWS-Auth was automatically added as an access entry.However, in aws-auth, this role is defined as two system:nodes/system:bootstrappers group, but at the access entry side it only has system:nodes/." (既存の ConfigMap/AWS-Auth で定義されたノード IAM ロールのマッピングは、アクセスエントリとして自動で追加されました。ただし、aws-auth においては、このロールは 2 つの system:nodes/system:bootstrappers グループとして定義されます。アクセスエントリ側には、system:nodes/ のみが含まれます)

移行プロセスでは、デフォルト動作として、ノードの IAM ロールが system:nodes グループにマッピングされるため、トラブルシューティングを要するエラーは発生しません。

アクセスエントリの移行後は、aws-auth ConfigMap および、system:bootstrappers グループによって付与される IAM アクセスエントリ構成は必要ありません。ノードは、すべての操作を system:nodes グループが付与する権限を用いて実行できます。system:nodes は、CONFIG_MAP から API_AND_CONFIG_MAP への移行により、アクセスエントリから不要なグループが削除されたことを示しています。

種類に関するエラー

アクセスエントリの宛先 IAM プリンシパルとして IAM ロールを設定しなかった場合、次のエラーが発生します。

"AccessEntry principalArn must be IAM role when using types [EC2_LINUX, EC2_WINDOWS, FARGATE_LINUX]." (このタイプを指定する場合、アクセスエントリは IAM ロールである必要がある)

この問題を解決するには、アクセスエントリに次のいずれかの種類を指定します。

• EC2_LINUX
• EC2_WINDOWS
• FARGATE_LINUX

アクセスエントリの種類に関する詳細については、「アクセスエントリを作成する」を参照してください。

ユーザー名に関するエラー

アクセスエントリの作成時に入力したユーザー名が適切でない場合、次のエラーメッセージが表示されます。

"The username must not begin with [eks:, aws:, system:, amazon:, iam:]." (特定のプレフィックスは、ユーザー名の先頭に配置できない)

独自のユーザー名を指定する場合、ユーザー名の先頭には、次のプレフィックスを付与できません。

• eks:
• aws:
• system:
• amazon:
• iam:

この問題を解決するには、ユーザー名がアクセスエントリのユーザー名要件を満たしていることを確認します。ユーザー名に関する詳細については、「アクセスエントリを作成する」を参照してください。

注: 潜在的なエラーを防ぐには、Amazon EKS で自動的にユーザー名を生成することをおすすめします。

権限に関するエラー

Amazon EKS は、クラスター上の Kubernetes ロールベースアクセス制御 (RBAC) オブジェクトには指定したグループ名が含まれることを確認しないことが原因で、権限エラーが発生します。Amazon EKS は、指定したグループ名がクラスターの紐付けに含まれるかどうかを確認しません。

この問題を解決するには、次の手順を実行します。

• aws-auth ConfigMap または IAM アクセスエントリにより、Kubernetes の RoleBinding または ClusterRoleBinding でサブジェクトとして指定したグループが正常に作成されたことを確認します。
• アクセスエントリにおいて、Kubernetes グループへの参照で綴りと形式を適切に記述したことを確認します。

サービスリンクロールに関するエラー

アクセスエントリの作成時にサービスリンクロールを指定した場合、次のエラーメッセージが表示されます。

"The caller is not allowed to modify access entries with a principalArn value of a Service Linked Role." (呼び出し元には、サービスリンクロールの principalArn 値を含むアクセスエントリを変更する権限が欠けている)

アクセスエントリでは、サービスリンクロールはサポートされません。したがって、プリンシパルの Amazon リソースネーム (ARN) がサービスリンクロールである場合、アクセスエントリを作成できません。ARN を参照すると、サービスリンクロールを識別できます。たとえば、arn:aws:iam::*:role/aws-service-role/* という ARN は、サービスリンクロールです。

サービスリンクロールにクラスターへのアクセスを付与するには、CONFIG_MAP または API_AND_CONFIG_MAP の認証モードを使用し、aws-auth ConfigMap でそのサービスリンクロールを指定します。

関連情報

ConfigMap を用いて IAM ユーザー に Kubernetes へのアクセスを付与する