使用容器组身份将 IAM 角色附加到 Amazon EKS 附加组件

某些 Amazon EKS 附加组件需要 IAM 角色权限才能调用 AWS API。例如，Amazon VPC CNI 附加组件会调用某些 AWS API 来配置您账户中的网络资源。需要使用 AWS IAM 对这些附加组件授予权限。更具体地说，运行附加组件的容器组（Pod）的服务账户需要与具有充分 IAM 策略的 IAM 角色相关联。

向集群工作负载授予 AWS 权限的建议方法是使用 Amazon EKS 功能容器组身份。您可以使用容器组身份关联将附加组件的服务账户映射到 IAM 角色。如果某个容器组使用具有关联的服务账户，Amazon EKS 会在容器组的容器中设置环境变量。环境变量配置 AWS SDK（包括 AWS CLI）使用 EKS 容器组身份凭证。了解有关 EKS 容器组身份的更多信息。

Amazon EKS 附加组件可以帮助管理与该附加组件对应的容器组身份关联的生命周期。例如，您可以在单个 API 调用中创建或更新 Amazon EKS 附加组件和必要的容器组身份关联。Amazon EKS 还提供用于检索建议 IAM 策略的 API。

建议的用量：

1. 确认已在您的集群上设置 Amazon EKS 容器组身份代理。

2. 使用 describe-addon-versions AWS CLI 操作确定要安装的附加组件是否需要 IAM 权限。如果 requiresIamPermissions 标志是 true，则应使用 describe-addon-configurations 操作来确定附加组件所需的权限。响应中将包含建议的托管 IAM 策略列表。

3. 使用 CLI describe-addon-configuration 操作检索 Kubernetes 服务账户的名称和建议的 IAM 策略。根据您的安全要求评估建议策略的范围。

4. 使用建议的权限策略和容器组身份所需的信任策略创建 IAM 角色。有关更多信息，请参阅 创建 EKS 容器组身份关联。

5. 使用该 CLI 创建或更新 Amazon EKS 附加组件。指定至少一个容器组身份关联。容器组身份关联是（1）Kubernetes 服务账户的名称，以及（2）IAM 角色的 ARN。

注意事项：

• 使用附加组件 API 创建的容器组身份关联归相应的附加组件所有。如果您删除该附加组件，则容器组身份关联也会被删除。在使用 AWS CLI 或 API 删除附加组件时，您可以通过使用 preserve 选项来防止这种级联删除。如有必要，您也可以直接更新或删除容器组身份关联。附加组件不能取得现有容器组身份关联的所有权。您必须删除现有关联，然后使用附加组件创建或更新操作重新创建该关联。

• Amazon EKS 建议使用容器组身份关联来管理附加组件的 IAM 权限。仍然支持之前的方法（服务账户的 IAM 角色（IRSA））。您可以为附加组件同时指定 IRSA serviceAccountRoleArn 和容器组身份关联。如果在集群上安装了 EKS 容器组身份代理，则 serviceAccountRoleArn 将被忽略，并且 EKS 将使用提供的容器组身份关联。如果未启用容器组身份，则将使用 serviceAccountRoleArn。

• 如果您更新现有附加组件的容器组身份关联，Amazon EKS 会启动附加组件容器组（Pod）的滚动重新启动。

检索有关附加组件的 IAM 信息

您可以使用 AWS CLI 来确定（1）某个附加组件是否需要 IAM 权限，以及（2）该附加组件的建议 IAM 策略。

检索有关 Amazon EKS 附加组件（AWS CLI）的 IAM 信息

1. 确定要安装的附加组件的名称以及集群的 Kubernetes 版本。了解可用 Amazon EKS 附加组件的详情。

2. 使用 AWS CLI 确定该附加组件是否需要 IAM 权限。

   aws eks describe-addon-versions \
   --addon-name <addon-name> \
   --kubernetes-version <kubernetes-version>

   例如：

   aws eks describe-addon-versions \
   --addon-name aws-ebs-csi-driver \
   --kubernetes-version 1.30

   审查以下示例输出。请注意，requiresIamPermissions 的值为 true，即默认的附加组件版本。在检索建议的 IAM 策略时，您需要指定附加组件版本。

   {
       "addons": [
           {
               "addonName": "aws-ebs-csi-driver",
               "type": "storage",
               "addonVersions": [
                   {
                       "addonVersion": "v1.31.0-eksbuild.1",
                       "architecture": [
                           "amd64",
                           "arm64"
                       ],
                       "compatibilities": [
                           {
                               "clusterVersion": "1.30",
                               "platformVersions": [
                                   "*"
                               ],
                               "defaultVersion": true
                           }
                       ],
                       "requiresConfiguration": false,
                       "requiresIamPermissions": true
                   },
   [...]

3. 如果附加组件需要 IAM 权限，请使用 AWS CLI 检索建议的 IAM 策略。

   aws eks describe-addon-configuration \
   --query podIdentityConfiguration \
   --addon-name <addon-name> \
   --addon-version <addon-version>

   例如：

   aws eks describe-addon-configuration \
   --query podIdentityConfiguration \
   --addon-name aws-ebs-csi-driver \
   --addon-version v1.31.0-eksbuild.1

   审查以下输出。记下 recommendedManagedPolicies。

   [
       {
           "serviceAccount": "ebs-csi-controller-sa",
           "recommendedManagedPolicies": [
               "arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy"
           ]
       }
   ]

4. 创建 IAM 角色并附加托管策略。或者，审查托管策略并根据需要缩小权限范围。审查创建用于 EKS 容器组身份的 IAM 角色的说明。

使用 IAM 角色更新附加组件

更新 Amazon EKS 附加组件以使用容器组身份关联（AWS CLI）

1. 确定：

   • cluster-name – 要在其上安装附加组件的 EKS 集群的名称。

   • addon-name – 要安装的 Amazon EKS 附加组件的名称。

   • service-account-name – 该附加组件使用的 Kubernetes 服务账户的名称。

   • iam-role-arn – 对附加组件拥有足够权限的 IAM 角色的 ARN。IAM 角色必须具有 EKS 容器组身份所需的信任策略。

2. 使用 AWS CLI 更新附加组件。您还可以在创建附加组件时使用相同的 --pod-identity-assocations 语法指定容器组身份关联。请注意，如果您在更新附加组件时指定容器组身份关联，则所有之前的容器组身份关联都将被覆盖。

   aws eks update-addon --cluster-name <cluster-name> \
   --addon-name <addon-name> \
   --pod-identity-associations 'serviceAccount=<service-account-name>,roleArn=<role-arn>'

   例如：

   aws eks update-addon --cluster-name mycluster \
   --addon-name aws-ebs-csi-driver \
   --pod-identity-associations 'serviceAccount=ebs-csi-controller-sa,roleArn=arn:aws:iam::123456789012:role/StorageDriver' 

3. 验证是否已创建容器组身份关联：

   aws eks list-pod-identity-associations --cluster-name <cluster-name> 

   如果成功，您应看到与以下内容类似的输出。记下 EKS 附加组件的 OwnerARN。

   {
       "associations": [
           {
               "clusterName": "mycluster",
               "namespace": "kube-system",
               "serviceAccount": "ebs-csi-controller-sa",
               "associationArn": "arn:aws:eks:us-west-2:123456789012:podidentityassociation/mycluster/a-4wvljrezsukshq1bv",
               "associationId": "a-4wvljrezsukshq1bv",
               "ownerArn": "arn:aws:eks:us-west-2:123456789012:addon/mycluster/aws-ebs-csi-driver/9cc7ce8c-2e15-b0a7-f311-426691cd8546"
           }
       ]
   }

从附加组件中移除关联

从 Amazon EKS 附加组件（AWS CLI）中移除所有容器组身份关联

1. 确定：

   • cluster-name – 要在其上安装附加组件的 EKS 集群的名称。

   • addon-name – 要安装的 Amazon EKS 附加组件的名称。

2. 更新附加组件以指定容器组身份关联的空数组。

   aws eks update-addon --cluster-name <cluster-name> \
   --addon-name <addon-name> \
   --pod-identity-associations "[]"

对 EKS 附加组件的容器组身份进行故障排除

如果您的附加组件在尝试 AWS API、SDK 或 CLI 操作时遇到错误，请确认以下内容：

• 容器组身份代理已安装在您的集群中。

  • 审查如何设置容器组身份代理。

• 该附加组件具有有效的容器组身份关联。

  • 使用 AWS CLI 检索附加组件使用的服务账户名称的关联。

    aws eks list-pod-identity-associations --cluster-name <cluster-name>

• 预期的 IAM 角色具有 EKS 容器组身份所需的信任策略。

  • 使用 AWS CLI 检索附加组件的信任策略。

    aws iam get-role --role-name <role-name> --query Role.AssumeRolePolicyDocument

• 预期的 IAM 角色具有该附加组件的必要权限。

  • 使用 AWS CloudTrail 审查 AccessDenied 或 UnauthorizedOperation 事件。

• 容器组身份关联中的服务账户名称与附加组件使用的服务账户名称相匹配。

  • 审查附加组件的文档以确定服务账户名称。