文档中心

容器服务

IRSA 机制

集群中使用 IRSA 能力

容器服务集群支持启用 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 能力

登录容器服务控制台。

在左侧导航栏中选择集群，单击目标集群名称，进入集群管理页面。

在集群的总览页面概览页签，开启 IRSA OIDC。

在系统弹出的提示框中确认信息，然后单击确定。

集群开启 IRSA 能力后，控制台上显示提供商 URL 和提供商 TRN。请确认提供商 TRN 信息中的身份提供商名称。

步骤二：（可选）安装 pod-identity-webhook 组件

需要为 Pod 自动注入 IRSA 配置时，安装 pod-identity-webhook 组件。

在目标集群的管理页面左侧导航栏单击组件管理。

在组件管理页面的安全页签，找到 pod-identity-webhook 组件并在组件右上角选择 ... > 安装。

步骤三：新建 OIDC 身份提供商类型的 IAM 角色

集群开启 IRSA 能力后，您需要自行在 IAM 控制台配置信任身份为 OIDC 类型的身份提供商的 IAM 角色。

在左侧导航栏选择角色管理，然后单击新建角色。

在新建角色页面按如下参数说明，配置参数。

选择信任身份

参数	说明
选择信任身份类型	选择身份提供商。
身份提供商类型	选择 OIDC。
身份提供商	选择步骤一中获取的提供商 TRN 信息中身份提供商名称。

配置角色信息

参考 IAM 文档：角色管理中的说明，结合您的实际情况自主配置。

添加权限

参考 IAM 文档：角色管理中的说明，结合您的实际情况自主配置。

步骤四：编辑角色信任关系

授权 VKE 集群（已开启 IRSA 的集群）内指定命名空间（NameSpace）下的服务账号（Service Account），允许扮演上述创建的 IAM 角色。

在 IAM 控制台的角色管理页面，搜索步骤三中创建的角色名称。

单击角色名称，进入角色详情页面。

在信任关系页签，单击编辑信任策略。

在Statement字段下添加如下代码块：

"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。
}
},

完整代码块示例如下：

{
"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。

编辑完成后，保存策略。

步骤五：创建工作负载

在集群中创建工作负载，并在工作负载 Pod 中实现 OIDC Token 文件访问 STS 服务的 AssumeRoleWithOIDC 接口所需的环境变量。

本文以创建 Pod 的同时创建步骤四中配置的 NameSpace、Service Account 为例。

通过 kubectl 连接已开启了 IRSA 的集群。详细操作，请参见连接集群。

创建对应的 NameSpace 和 Service Account 的 YAML 文件，示例文件demo-1.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 将不会被自动注入配置。

执行如下命令，创建 NameSpace 和 Service Account。

kubectl apply -f demo-1.yaml

创建工作负载（以 Pod 为例）的 YAML 文件，示例文件demo-2.yaml的内容如下：

已安装 pod-identity-webhook 组件，为 Pod 自动注入 IRSA 配置时：

说明

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

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

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 配置时：

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: <role_trn>
- 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 挂载地址。

执行如下命令，创建工作负载。

kubectl apply -f demo-2.yaml

结果验证

完成工作负载创建后，可在 Pod 内调用安全令牌服务（Security Token Service，STS）的 AssumeRoleWithOIDC 接口，验证 Pod 是否能够使用注入的 OIDC Token 扮演指定的 IAM 角色并获取临时安全凭证。脚本示例如下：

预期结果如下，当返回结果中包含Result.Credentials字段（含AccessKeyId、SecretAccessKey、SessionToken）时，表示 Pod 已成功扮演 IAM 角色并获取临时安全凭证，IRSA 配置验证成功。

最近更新时间：2026.10.19 11:26:26

这个页面对您有帮助吗？

有用

无用