容器服务集群支持启用 IRSA (IAM Role for Service Account) 能力。基于 IRSA 功能，您可以在集群内实现 Pod 维度的 OpenAPI 权限隔离，从而实现云资源访问权限的细粒度隔离，降低安全风险。本文介绍如何在集群中使用 IRSA。 ## 使用限制 * 目前仅托管版且已创建好的集群支持开启 IRSA 能力，创建集群时不支持开启。 * 集群中开启 IRSA 能力后不支持关闭。建议您先在测试集群中进行充分测试验证，再使用到生产集群中。 * 启用 IRSA 会导致 kube\-apiserver 的短暂重启，请在业务低峰期操作。 * 仅支持在 Kubernetes v1.24 及以上版本集群中使用 IRSA 能力。 * 若需要为 VKE 集群中的 Pod 自动注入 IRSA 相关配置，则依赖 VKE 提供的 pod\-identity\-webhook 组件。 ## 前提条件请确保目标集群处于 **运行中** 状态。 ## 操作步骤 ### 步骤一：集群开启 IRSA 能力 1. 登录 [容器服务控制台](https://console.volcengine.com/vke)。 2. 在左侧导航栏中选择 **集群**，单击目标集群名称，进入集群管理页面。 3. 在集群的 **总览** 页面 **概览** 页签，开启 IRSA OIDC。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_aefad8c94647f99a81fc02b7f3595042.png) 4. 在系统弹出的提示框中确认信息，然后单击 **确定**。集群开启 IRSA 能力后，控制台上显示 **提供商 URL** 和 **提供商 TRN**。请确认 **提供商 TRN** 信息中的身份提供商名称。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_74195c42c98f267d57db25d4dbcd1166.png) ### 步骤二：（可选）安装 pod\-identity\-webhook 组件需要为 Pod 自动注入 IRSA 配置时，安装 pod\-identity\-webhook 组件。 1. 在目标集群的管理页面左侧导航栏单击 **组件管理**。 2. 在 **组件管理** 页面的安全页签，找到 pod\-identity\-webhook 组件并在组件右上角选择 `...` \> **安装**。 ### 步骤三：新建 OIDC 身份提供商类型的 IAM 角色集群开启 IRSA 能力后，您需要自行在 IAM 控制台配置信任身份为 OIDC 类型的身份提供商的 IAM 角色。 1. 登录 [IAM 控制台](https://console.volcengine.com/iam)。 2. 在左侧导航栏选择 **角色管理**，然后单击 **新建角色**。 3. 在 **新建角色** 页面按如下参数说明，配置参数。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_7ade07e8fc83983533087da85ffce3aa.png) * **选择信任身份** |参数 |说明 | |---|---| |选择信任身份类型 |选择 **身份提供商**。 | |身份提供商类型 |选择 **OIDC**。 | |身份提供商 |选择 **步骤一** 中获取的 **提供商 TRN** 信息中身份提供商名称。 | * **配置角色信息** 参考 IAM 文档：[角色管理](https://www.volcengine.com/docs/6257/64979) 中的说明，结合您的实际情况自主配置。 * **添加权限** 参考 IAM 文档：[角色管理](https://www.volcengine.com/docs/6257/64979) 中的说明，结合您的实际情况自主配置。 ### 步骤四：编辑角色信任关系授权 VKE 集群（已开启 IRSA 的集群）内指定命名空间（NameSpace）下的服务账号（Service Account），允许扮演上述创建的 IAM 角色。 1. 在 [IAM 控制台](https://console.volcengine.com/iam) 的 **角色管理** 页面，搜索 **步骤三** 中创建的角色名称。 2. 单击角色名称，进入角色详情页面。 3. 在 **信任关系** 页签，单击 **编辑信任策略**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6a7145022ba2e3485ba5799c0261a796.png) 在`Statement`字段下添加如下代码块： ```json "Condition": { "StringLike": { "oidc:aud": "sts.volcengine.com", // 固定值，OIDC 中的 Audience 值。 "oidc:iss": "https://oidc-vke-cn-beijing.tos-cn-beijing.volces.com/ccog93v********", // 配置为您的集群开启 IRSA 能力后控制台中显示的“供应商 URL”信息。 "oidc:sub": "system:serviceaccount:oidc-ns-1:oidc-sa-1" // 需要满足格式：system:serviceaccount:{namespace}:{serviceaccount} ，其中{namespace}和{serviceaccount}是 Kubernetes 集群内目标 NameSpace 和 Service Account。 } }, ``` 完整代码块示例如下： ```json { "Statement": [ { "Effect": "Allow", "Action": [ "sts:AssumeRoleWithOIDC" ], "Condition": { "StringLike": { "oidc:aud": "sts.volcengine.com", // 固定值，OIDC 中的 Audience 值。 "oidc:iss": "https://oidc-vke-cn-beijing.tos-cn-beijing.volces.com/ccog93vv********", // 配置为您的集群开启 IRSA 能力后控制台中显示的“供应商 URL”信息。 "oidc:sub": "system:serviceaccount:oidc-ns-1:oidc-sa-1" // 需要满足格式：system:serviceaccount:{namespace}:{serviceaccount} ，其中{namespace}和{serviceaccount}是 Kubernetes 集群内目标 NameSpace 和 Service Account。 } }, "Principal": { "Federated": [ "trn:iam::2100******:oidc-provider/vke-irsa-********" ] } } ] } ```

说明

IAM 信任策略支持添加多个Statement。

4. 编辑完成后，保存策略。 ### 步骤五：创建工作负载在集群中创建工作负载，并在工作负载 Pod 中实现 OIDC Token 文件访问 STS 服务的 [AssumeRoleWithOIDC](https://www.volcengine.com/docs/6257/1494877) 接口所需的环境变量。本文以创建 Pod 的同时创建 **步骤四** 中配置的 NameSpace、Service Account 为例。 1. 通过 kubectl 连接已开启了 IRSA 的集群。详细操作，请参见 [连接集群](https://www.volcengine.com/docs/6460/100942)。 2. 创建对应的 NameSpace 和 Service Account 的 YAML 文件，示例文件`demo-1.yaml`的内容如下： ```yaml --- apiVersion: v1 kind: Namespace metadata: name: oidc-ns-1 # NameSpace 名称。与“步骤三”中配置的 NameSpace 名称保持一致。 labels: vke.volcengine.com/pod-identity-injection-enabled: "true" # 为当前 NameSpace 下的 Pod 开启 IRSA 配置自动化注入能力。 --- apiVersion: v1 kind: ServiceAccount metadata: name: oidc-sa-1 namespace: oidc-ns-1 # Service Account 名称。与“步骤三”中配置的 Service Account 名称保持一致。 annotations: vke.volcengine.com/role-trn: trn:iam::2100******:role/podrole1234 # 该 Service Account 关联的 IAM 角色 TRN（在访问控制的角色详情页面获取角色 TRN）。如果未配置该 Annotation 或配置的值不是一个合法的 IAM 角色 TRN，则使用该 Service Account 的 Pod 将不会被自动注入配置。 ``` 3. 执行如下命令，创建 NameSpace 和 Service Account。 ```bash kubectl apply -f demo-1.yaml ``` 4. 创建工作负载（以 Pod 为例）的 YAML 文件，示例文件`demo-2.yaml`的内容如下： * 已安装 pod\-identity\-webhook 组件，为 Pod 自动注入 IRSA 配置时：

说明

您提交的业务 Pod 无需做任何调整，即可使用 IRSA 能力，由 pod\-identity\-webhook 组件自动为 Pod 注入相应配置。

若您有其他环境变量需要配置，可开启扩展环境变量能力。详细操作，请参见 pod\-identity\-webhook。

```yaml apiVersion: v1 kind: Pod metadata: name: demo # Pod 名称。 namespace: oidc-ns-1 # 与上方设置的 NameSpace 名称保持一致。 spec: serviceAccountName: oidc-sa-1 # 与上方设置的 Service Account 名称保持一致。 containers: - image: cr-cn-beijing.volces.com/******:latest # 容器镜像地址和 Tag，请配置为您自己的镜像地址。 imagePullPolicy: "Always" args: - irsa - demo name: demo # 容器名称。 restartPolicy: OnFailure ``` * 未安装 pod\-identity\-webhook 组件，手动为 Pod 注入 IRSA 配置时： ```yaml apiVersion: v1 kind: Pod metadata: name: pod-1 # Pod 名称。 namespace: oidc-ns-1 # 与上方设置的 NameSpace 名称保持一致。 spec: serviceAccountName: oidc-sa-1 # 与上方设置的 Service Account 名称保持一致。 volumes: # 为 Pod 设置服务账号令牌卷投影。更多信息，请见 Kubernetes 文档：https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection 。 - name: irsa-oidc-token # 卷名称，与下方 volumeMounts 下的挂载卷名称保持一致。 projected: defaultMode: 420 sources: - serviceAccountToken: audience: sts.volcengine.com # 固定值，表示指定的 Audience 值。 expirationSeconds: 3600 # OIDC Token 有效期，单位为：秒。 path: token containers: env: # Pod 中实现请求 AssumeRoleWithOIDC 所需的环境变量。 - name: VOLCENGINE_OIDC_ROLE_TRN value: - name: VOLCENGINE_OIDC_TOKEN_FILE value: /var/run/secrets/vke.volcengine.com/irsa-tokens/token # OIDC Token 挂载地址，与下方 volumeMounts 下的挂载地址保持一致。 image: cr-cn-beijing.volces.com/******:latest # 容器镜像地址和 Tag，请配置为您自己的镜像地址。 imagePullPolicy: IfNotPresent name: c-test # 容器名称。 volumeMounts: - name: irsa-oidc-token # 挂载卷名称，与上方 volumes 下的卷名称保持一致。 readOnly: true mountPath: /var/run/secrets/vke.volcengine.com/irsa-tokens/token # OIDC Token 挂载地址。 ``` 5. 执行如下命令，创建工作负载。 ```bash kubectl apply -f demo-2.yaml ``` ## 结果验证完成工作负载创建后，可在 Pod 内调用安全令牌服务（Security Token Service，STS）的 AssumeRoleWithOIDC 接口，验证 Pod 是否能够使用注入的 OIDC Token 扮演指定的 IAM 角色并获取临时安全凭证。脚本示例如下： ```Bash #!/usr/bin/env bash set -euo pipefail # 必须存在的环境变量 : "${VOLCENGINE_OIDC_TOKEN_FILE:?need VOLCENGINE_OIDC_TOKEN_FILE}" : "${VOLCENGINE_OIDC_ROLE_TRN:?need VOLCENGINE_OIDC_ROLE_TRN}" STS_HOST="sts.cn-beijing.volcengineapi.com" # STS 服务接入域名 ACTION="AssumeRoleWithOIDC" # API 接口动作：使用 OIDC 令牌扮演角色 VERSION="2018-01-01" # STS 接口版本号 DURATION="3600" # 获取 STS 临时凭证有效期，单位秒，最大可根据角色配置调整 SESSION_NAME="irsa-$(hostname)-$(date +%s)" # 会话名称：主机名+时间戳 OIDC_TOKEN=$(cat "${VOLCENGINE_OIDC_TOKEN_FILE}") # 读取 OIDC 令牌文件内容，获取 JWT 令牌 POLICY='{"Statement":[{"Effect":"Allow","Action":["*"],"Resource":["*"]}]}' # 内联授权策略，临时会话权限；示例为全部权限，生产环境建议缩小 Action/Resource 范围 curl -s -X POST "https://${STS_HOST}/?Action=${ACTION}&Version=${VERSION}" \ -H "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "RoleTrn=${VOLCENGINE_OIDC_ROLE_TRN}" \ --data-urlencode "OIDCToken=${OIDC_TOKEN}" \ --data-urlencode "Policy=${POLICY}" \ --data-urlencode "DurationSeconds=${DURATION}" \ --data-urlencode "RoleSessionName=${SESSION_NAME}" ``` 预期结果如下，当返回结果中包含`Result.Credentials`字段（含`AccessKeyId`、`SecretAccessKey`、`SessionToken`）时，表示 Pod 已成功扮演 IAM 角色并获取临时安全凭证，IRSA 配置验证成功。 ```JSON { "ResponseMetadata": { "RequestId": "202****", "Action": "AssumeRoleWithOIDC", "Version": "2018-01-01", "Service": "sts", "Region": "cn-beijing" }, "Result": { "Credentials": { "CurrentTime": "2021-04-12T10:57:09+08:00\n\n", "Expiration": "2021-04-12T11:57:09+08:00\n\n", "AccessKeyId": "AKTPOD****", "SecretAccessKey": "TVRN****", "SessionToken": "STSeyW****" }, "OIDCTokenInfo": { "Subject": "Kryrk****", "Issuer": "https://dev-xxxxxx.****.com", "ClientIds": [ "49627****" ], "ExpirationTime": "2021-10-20T04:27:09Z", "IssuanceTime": "2021-10-20T03:27:09Z" }, "AssumedRoleUser": { "AssumedRoleId": "5DokU****", "Trn": "vJ****" } } } ```