**帮助改进此页面** 

要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。

# Amazon EKS 功能 IAM 角色
<a name="capability-role"></a>

EKS 功能需要配置功能 IAM 角色（或功能角色）。EKS 功能使用此角色对 AWS 服务执行操作，并通过自动创建的访问条目访问集群中的 Kubernetes 资源。

在功能创建期间指定功能角色之前，您必须创建具有相应信任策略和相应功能类型的权限的 IAM 角色。创建此 IAM 角色后，可以将其重用于任意数量的功能资源。

## 功能角色要求
<a name="_capability_role_requirements"></a>

功能角色必须满足以下要求：
+ 该角色必须与集群和功能资源位于同一 AWS 账户中
+ 该角色必须拥有信任策略，以允许 EKS 功能服务代入该角色
+ 该角色必须拥有与功能类型和使用案例要求相适应的权限（请参阅[按功能类型划分的权限](#capability-permissions)）

## 功能角色的信任策略
<a name="capability-trust-policy"></a>

所有功能角色必须包含以下信任策略：

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "capabilities.eks.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ]
    }
  ]
}
```

此信任策略允许 EKS 执行以下操作：
+ 担任该角色，以执行 AWS API 操作
+ 标记会话以进行审计和跟踪

## 按功能类型划分的权限
<a name="capability-permissions"></a>

所需的 IAM 权限取决于您使用的功能和部署模式。

**注意**  
对于搭配使用 IAM 角色选择器与 ACK 的生产部署，或者在没有 AWS 服务集成的情况下使用 kro 或 Argo CD 时，功能角色可能不需要信任策略之外的任何 IAM 权限。

 **kro（Kube Resource Orchestrator）**   
不需要 IAM 权限。您可以创建没有附加策略的功能角色。kro 只需要 Kubernetes RBAC 权限即可创建和管理 Kubernetes 资源。

 ** AWS Controllers for Kubernetes（ACK）**   
ACK 支持两种权限模型：  
+  **简单设置（开发/测试）**：直接向功能角色添加 AWS 服务权限。这非常适合入门级的单账户部署或所有用户都需要相同权限的情况。
+  **生产最佳实践**：使用 IAM 角色选择器，实施最低权限访问。使用这种方法，功能角色只需要获得 `sts:AssumeRole` 权限即可代入服务特定角色。您无需向功能角色本身添加 AWS 服务权限（如 S3 或 RDS），系统会将这些权限授予映射到特定命名空间的各个 IAM 角色。

  IAM 角色选择器可启用以下功能：
  + 命名空间级别权限隔离
  + 跨账户资源管理
  + 团队特定 IAM 角色
  + 最低权限安全模型

    IAM 角色选择器方法的功能角色策略示例：

    ```
    {
      "Version": "2012-10-17",		 	 	 
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "sts:AssumeRole",
          "Resource": [
            "arn:aws:iam::111122223333:role/ACK-S3-Role",
            "arn:aws:iam::111122223333:role/ACK-RDS-Role",
            "arn:aws:iam::444455556666:role/ACKCrossAccountRole"
          ]
        }
      ]
    }
    ```

    有关包括 IAM 角色选择器在内的 ACK 权限配置的详细信息，请参阅[配置 ACK 权限](ack-permissions.md)。

 **Argo CD**   
默认情况下，不需要 IAM 权限。以下功能可能需要可选权限：  
+  ** AWS Secrets Manager**：如果使用 Secrets Manager 来存储 Git 存储库凭证
+  ** AWS CodeConnections**：如果使用 CodeConnections 进行 Git 存储库身份验证

  Secrets Manager 和 CodeConnections 策略示例：

  ```
  {
    "Version": "2012-10-17",		 	 	 
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "secretsmanager:GetSecretValue",
          "secretsmanager:DescribeSecret"
        ],
        "Resource": "arn:aws:secretsmanager:region:account-id:secret:argocd/*"
      },
      {
        "Effect": "Allow",
        "Action": [
          "codeconnections:UseConnection",
          "codeconnections:GetConnection"
        ],
        "Resource": "arn:aws:codeconnections:region:account-id:connection/*"
      }
    ]
  }
  ```

  有关 Argo CD 权限要求的详细信息，请参阅 [Argo CD 注意事项](argocd-considerations.md)。

## 检查现有功能角色
<a name="check-capability-role"></a>

您可使用以下过程来检查账户是否已具有适合您使用案例的功能 IAM 角色。

1. 通过 https://console.aws.amazon.com/iam/ 打开 IAM 控制台。

1. 在左侧导航窗格中，选择 **角色**。

1. 在角色列表中搜索功能角色名称（例如，`ACKCapabilityRole` 或 `ArgoCDCapabilityRole`）。

1. 如果存在角色，请选择该角色，查看附加策略和信任关系。

1. 选择 **Trust relationships**（信任关系），然后选择 **Edit trust policy**（编辑信任策略）。

1. 验证信任关系是否与[功能信任策略](#capability-trust-policy)相匹配。如果不匹配，请更新信任策略。

1. 选择**权限**并验证该角色是否具有适用于您的功能类型和使用案例的权限。

## 创建功能 IAM 角色
<a name="create-capability-role"></a>

要创建功能角色，您可以使用 AWS 管理控制台 或 AWS CLI。

 ** AWS 管理控制台 **   

1. 通过 https://console.aws.amazon.com/iam/ 打开 IAM 控制台。

1. 选择 **Roles**，然后选择 **Create role**。

1. 对于**可信实体类型**，选择**自定义信任策略**。

1. 将[功能信任策略](#capability-trust-policy)复制并粘贴到信任策略编辑器中。

1. 选择**下一步**。

1. 在**添加权限**选项卡上，选择或创建适合您的功能类型的策略（请参阅[按功能类型划分的权限](#capability-permissions)）。对于 kro，您可以跳过此步骤。

1. 选择**下一步**。

1. 对于**角色名称**，请为角色输入唯一名称，例如 `ACKCapabilityRole`、`ArgoCDCapabilityRole` 或 `kroCapabilityRole`。

1. 对于 **Description**（说明），请输入描述性文本，例如 `Amazon EKS - ACK capability role`。

1. 选择**创建角色**。

 **AWS CLI**   

1. 将[功能信任策略](#capability-trust-policy)复制到名为 `capability-trust-policy.json` 的文件中。

1. 创建角色。将 `ACKCapabilityRole` 替换为您所需的角色名称。

   ```
   aws iam create-role \
     --role-name ACKCapabilityRole \
     --assume-role-policy-document file://capability-trust-policy.json
   ```

1. 将所需的 IAM 策略附加到角色。对于 ACK，请为要管理的 AWS 服务附加策略。对于 Argo CD，请根据需要为 Secrets Manager 或 CodeConnections 附加策略。对于 kro，您可以跳过此步骤。

   具有 S3 权限的 ACK 示例：

   ```
   aws iam put-role-policy \
     --role-name ACKCapabilityRole \
     --policy-name S3Management \
     --policy-document file://s3-policy.json
   ```

## 对功能角色问题进行问题排查
<a name="troubleshooting-capability-role"></a>

 **功能创建失败，并显示“IAM 角色无效”**   
验证：  
+ 该角色与集群位于同一账户中
+ 信任策略与[功能信任策略](#capability-trust-policy)相匹配 
+ 您拥有该角色的 `iam:PassRole` 权限

 **功能显示权限错误**   
验证：  
+ 该角色具有此功能类型所需的 IAM 权限
+ 该角色的访问条目存在于集群上
+ 如有需要，还可配置其他 Kubernetes 权限（请参阅[其他 Kubernetes 权限](capabilities-security.md#additional-kubernetes-permissions)）

 **ACK 资源失败并出现“权限被拒绝”错误**   
验证：  
+ 此角色具有您的使用案例所需的 IAM 权限
+ 对于引用密钥的 ACK 控制器，请确保已将范围限定为相应命名空间的 `AmazonEKSSecretReaderPolicy` 访问条目策略进行了关联。

有关更多问题排查指导，请参阅[EKS 功能的安全注意事项](capabilities-security.md)。