适用于 Kubernetes 的 AWS IAM 认证器

一个使用 AWS IAM 凭证向 Kubernetes 集群进行身份认证的工具。 该工具的初始工作由 Heptio 推动。该项目获得了众多社区工程师的贡献，目前由 Heptio 和 Amazon EKS OSS 工程师维护。

目录

• 我为什么需要它？
• 我如何使用它？
• Kops 用法
• 它是如何工作的？
• 什么是集群 ID？
• 指定凭证与使用 AWS 配置文件
• 从集群外部进行 API 授权
• 故障排查
• 完整配置格式
• 开发
• 社区、讨论、贡献与支持

我为什么需要它？

如果你是在 AWS 上运行 Kubernetes 集群的管理员，你本来就需要管理 AWS IAM 凭证来配置和更新集群。 通过使用适用于 Kubernetes 的 AWS IAM 认证器，你可以避免为 Kubernetes 访问单独管理一套凭证。 AWS IAM 还提供了许多出色的特性，例如带外审计跟踪（通过 CloudTrail）以及 2FA/MFA 强制实施。

如果你正在 AWS 上构建 Kubernetes 安装程序，适用于 Kubernetes 的 AWS IAM 认证器可以简化你的引导过程。 你无需设法将初始管理员凭证安全地从新安装的集群中偷运出来。 相反，你可以在集群配置时创建一个专用的 KubernetesAdmin 角色，并设置认证器以允许集群管理员登录。

我如何使用它？

假设你有一个在 AWS 中运行的集群，并且想要添加适用于 Kubernetes 的 AWS IAM 认证器支持，你需要：

1. 创建一个用于识别用户的 IAM 角色。
2. 以 DaemonSet 方式运行认证器服务器。
3. 配置你的 API 服务器与认证器通信。
4. 设置 kubectl 以使用认证器令牌。

1. 创建 IAM 角色

首先，你必须创建一个或多个 IAM 角色，这些角色将映射到 Kubernetes 集群内的用户/组。 最简单的方法是通过 AWS 控制台：

• 选择“跨账户访问的角色”/“在你拥有的 AWS 账户之间提供访问”选项。
• 粘贴你的 AWS 账户 ID 号（可在控制台右上角找到）。
• 你的角色不需要附加任何额外策略。

这将创建一个没有任何权限的 IAM 角色，该角色可由你账户中已授权的用户/角色代入。 记下你的角色的 Amazon Resource Name（ARN），你将在下文用到它。

你也可以使用 AWS CLI 而不是 AWS 控制台，通过单步完成此操作：

# get your account ID
ACCOUNT_ID=$(aws sts get-caller-identity --output text --query 'Account')

# define a role trust policy that opens the role to users in your account (limited by IAM policy)
POLICY=$(echo -n '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::'; echo -n "$ACCOUNT_ID"; echo -n ':root"},"Action":"sts:AssumeRole","Condition":{}}]}')

# create a role named KubernetesAdmin (will print the new role's ARN)
aws iam create-role \
  --role-name KubernetesAdmin \
  --description "Kubernetes administrator role (for AWS IAM Authenticator for Kubernetes)." \
  --assume-role-policy-document "$POLICY" \
  --output text \
  --query 'Role.Arn'

你也可以跳过此步骤，改用：

• 一个现有角色（例如跨账户访问角色）。
• 一个 IAM 用户（参见下方的 mapUsers）。
• 一个 EC2 实例或一个联合角色（参见下方的 mapRoles）。

2. 运行服务器

该服务器旨在以 DaemonSet 形式运行在你的每个主节点上，并使用主机网络，以便它可以暴露一个 localhost 端口。

有关示例 ConfigMap 和 DaemonSet 配置，请参见 deploy/example.yaml。 在应用它之前，请为你的集群更新以下值：

• 替换 config.yaml 中的占位符 IAM ARN（arn:aws:iam::000000000000:...）。
• 将 clusterID 设置为你的集群的唯一值。
• 验证 DaemonSet 的调度规则与你的控制平面节点标签/污点相匹配。

然后部署它：

kubectl apply -f deploy/example.yaml
kubectl -n kube-system rollout status daemonset/aws-iam-authenticator
kubectl -n kube-system get pods -l k8s-app=aws-iam-authenticator

一旦 Pod 在控制平面节点上运行，aws-iam-authenticator server 将在主机上的 /etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml（或通过 --generate-kubeconfig 配置的路径）创建 webhook kubeconfig。

（可选）预生成证书、密钥和 kubeconfig

如果你正在构建自动化安装程序，也可以使用 aws-iam-authenticator init 轻松预生成证书、密钥和 webhook kubeconfig 文件。 该命令将生成文件并将它们放入配置的输出目录中。

你可以在启动 API 服务器之前在每个主节点上运行此命令。 你也可以在配置主节点之前生成它们，并将它们安装到适当的主机路径中。

如果你不预生成文件，aws-iam-authenticator server 将按需生成它们。 这可以正常工作，但需要在安装后重启 Kubernetes API 服务器。

3. 配置你的 API 服务器以与服务器通信

Kubernetes API 通过 token authentication webhook 与 AWS IAM Authenticator for Kubernetes 集成。 当你运行 aws-iam-authenticator server 时，它将生成一个 webhook 配置文件并将其保存到主机文件系统中。 你需要向 API 服务器配置中添加一个额外的标志：

--authentication-token-webhook-config-file=/etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml

在许多集群上，API 服务器以静态 Pod 的形式运行。 你可以将该标志添加到 /etc/kubernetes/manifests/kube-apiserver.yaml 中。 确保主机目录 /etc/kubernetes/aws-iam-authenticator/ 已挂载到你的 API 服务器 Pod 中。 你可能还需要重启主节点上的 kubelet 守护进程，以加载更新后的静态 Pod 定义：

systemctl restart kubelet.service

4. 创建 IAM 角色/用户到 Kubernetes 用户/组的映射

服务器的默认行为是仅从其配置文件的 mapUsers 和 mapRoles 字段获取映射。详情请参阅下方的完整配置格式。

使用 --backend-mode 标志，你可以配置服务器从两个额外的后端获取映射：EKS 风格的 ConfigMap（--backend-mode=EKSConfigMap）或 IAMIdentityMapping 自定义资源（--backend-mode=CRD）。默认后端，即由服务器 Pod 挂载的服务器配置文件，对应于 --backend-mode=MountedFile。

你可以传入这些后端的逗号分隔列表，让服务器按顺序搜索它们。例如，使用 --backend-mode=EKSConfigMap,MountedFile 时，服务器将先在 EKS 风格的 ConfigMap 中搜索映射，如果未找到给定 IAM 角色/用户的映射，则再搜索服务器配置文件。如果同一 IAM 角色/用户的映射存在于多个后端中，服务器将使用逗号分隔列表中排在最前面的后端中的映射。在此示例中，如果在 EKS ConfigMap 中找到映射，则无论服务器配置文件中是否存在重复或冲突的映射，都将使用该映射。

请注意，当设置单个后端时，服务器将仅从该后端获取映射，而忽略其他后端，即使它们存在。例如，使用 --backend-mode=CRD 时，服务器将仅从 IAMIdentityMappings 获取映射，而忽略挂载的文件和 EKS ConfigMap。

MountedFile

这是默认的映射后端，对大多数用户来说已经足够。详情请参阅下方的完整配置格式。

CRD（alpha）

此后端将每个 IAM 映射建模为一个 IAMIdentityMapping Kubernetes 自定义资源。这种方法使你能够使用 kubectl 或 API 以 Kubernetes 原生方式维护映射。此外，语法错误（如 YAML 未对齐）可以更容易地被捕获，并且不会影响所有映射。

要设置 IAMIdentityMapping CRD，你首先需要 apply CRD 清单：

kubectl apply -f deploy/iamidentitymapping.yaml

部署 CRD 后，你就可以创建用于建模 IAM 身份的自定义资源。参见 ./deploy/example-iamidentitymapping.yaml：

---
apiVersion: iamauthenticator.k8s.aws/v1alpha1
kind: IAMIdentityMapping
metadata:
  name: kubernetes-admin
spec:
  # Arn of the User or Role to be allowed to authenticate
  arn: arn:aws:iam::XXXXXXXXXXXX:user/KubernetesAdmin
  # Username that Kubernetes will see the user as, this is useful for setting
  # up allowed specific permissions for different users
  username: kubernetes-admin
  # Groups to be attached to your users/roles. For example `system:masters` to
  # create cluster admin, or `system:nodes`, `system:bootstrappers` for nodes to
  # access the API server.
  groups:
  - system:masters

EKSConfigMap

EKS 风格的 kube-system/aws-auth ConfigMap 用作后端。该 ConfigMap 的格式应与 EKS 集群中的格式完全一致： https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html。如果你正从 EKS 迁移或迁移到 EKS 并希望保留映射，或者你在运行 EKS 的同时还运行其他 AWS 集群并希望在每个集群中使用相同的映射，这会很有用。

DynamicFile

由 cfg.dynamicfilepath 指定的本地文件可用作后端。该文件内容的格式应与 EKSConfigMap 完全一致。每当该文件内容发生变化时，authenticator 会自动重新加载它。这为管理 ARN 映射提供了更大的灵活性。

关于如何配置 DynamicFile 模式，请查看 https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml。

运行 make e2e RUNNER=kind 来体验启用了 DynamicFile 模式的 kind 集群。

5. 如何为 Kubernetes 用户名配置 reservedPrefixConfig

aws-iam-authenticator 可以支持 k8s 用户名的保留前缀。如果设置了保留前缀，那么带有该保留前缀的用户名将无法通过身份验证，并会报错 "username must not begin with with the following prefixes:"。

关于如何配置保留前缀，请查看 https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml。

6. 设置 kubectl 以使用 AWS IAM Authenticator for Kubernetes 提供的身份验证令牌

最后，服务器设置完成后，你需要进行身份验证。 你仍然需要一个包含集群公共数据（集群 CA 证书、端点地址）的 kubeconfig。 不过，配置中的 users 部分应包含一个 exec 部分（参阅 kubectl 凭据插件文档）：

# [...]
users:
- name: kubernetes-admin
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: aws-iam-authenticator
      args:
        - "token"
        - "-i"
        - "REPLACE_ME_WITH_YOUR_CLUSTER_ID"
        - "-r"
        - "REPLACE_ME_WITH_YOUR_ROLE_ARN"
  # no client certificate/key needed here!

这意味着 kubeconfig 完全是公开数据，可以在所有 Authenticator 用户之间共享。 将其上传到受信任的公共位置（例如 AWS S3）可能是合理的做法。

请确保已安装 aws-iam-authenticator 二进制文件。 你可以使用 go install sigs.k8s.io/aws-iam-authenticator/cmd/aws-iam-authenticator@latest 进行安装。

要进行身份验证，请运行 kubectl --kubeconfig /path/to/kubeconfig" [...]。 kubectl 会使用你 kubeconfig 中提供的参数 exec 执行 aws-iam-authenticator 二进制文件，该程序会生成一个令牌并将其传递给 apiserver。 该令牌有效期为 15 分钟（AWS 允许的最短值），并且可以多次重复使用。