容器计算服务 ACS：通过 CredentialProvider 配置使用 RAM 角色 STS 临时凭据

功能介绍

在 AI Agent 场景下，Agent 常需以阿里云身份访问云服务（如对象存储 OSS、日志、云监控等）。若将长期 AccessKey（AK/SK）直接写入应用代码、镜像或环境变量，所有实例共享同一组密钥、权限无法收敛到实例维度，且存在长期密钥泄露与难以轮转的风险。

CredentialProvider 是 ack-agent-identity 提供的凭据来源自定义资源（CRD）。当类型为 RAM 且来源为 RRSA 时，ack-agent-identity 组件通过 RRSA（RAM Roles for Service Accounts）调用 STS 服务的 AssumeRoleWithOIDC 接口扮演指定 RAM 角色，签发一组短期 STS 临时凭据（AccessKeyId、AccessKeySecret、SecurityToken），并具备以下能力：

• 应用侧不持有任何长期 AK/SK，实际下发的是有效期受限的 STS 临时凭据，由平台按需签发与自动轮转。

• 通过 AgentRole / AgentRoleBinding 授权机制，精细控制每个 Agent 身份可获取哪些 CredentialProvider 的凭据。

• 通过 policy（会话策略）将 STS 凭据的权限收缩为 RAM 角色权限的子集，并支持模板变量按 Agent 身份、Sandbox 实例等上下文动态调整权限，实现实例级的最小权限授权。

CredentialProvider 除 RAM 外还支持 APIKey 等类型。本文仅介绍 type: RAM + RRSA 来源（签发阿里云 STS 临时凭据），其余类型与来源请参见对应文档。

涉及的资源对象

配置一次可用的 STS 凭据下发，通常涉及以下 CR，下文配置 STS 凭据章节将按顺序创建：

前提条件

• 集群版本 >= 1.28。

• 通过集群组件管理页面，确认 ack-agent-identity 组件版本 >= 0.4.0。

• 已通过目标集群集群信息页的基本信息页签开启RRSA OIDC，并记录提供商URL和提供商 ARN，用于后续 RAM 角色信任策略配置。

• 已配置可访问目标 ACS 集群的 kubeconfig，具体操作请参见通过kubectl快速使用ACS。

• 本模式依赖 ack-agent-identity 组件访问 STS 服务的 AssumeRoleWithOIDC 接口获取临时凭据。请根据实际业务的 Sandbox 实例规模，前往配额中心申请 AssumeRoleWithOIDC 接口的访问配额，避免因配额不足导致凭据获取失败。评估方法请参见如何预估 AssumeRoleWithOIDC接口的峰值 QPS？。

  跨账号场景另需：如需通过 targetRoleArn 实现跨账号扮演，还需满足 ack-agent-identity 组件版本 >= 0.5.0，并按实例规模额外申请 STS AssumeRole 接口的访问配额。详细配置请参见RRSA 跨账号访问。

配置 STS 凭据

以下集群内资源（AgentIdentity、CredentialProvider、AgentRole、AgentRoleBinding）需创建于同一命名空间。

步骤 1：创建 RAM 角色并配置信任策略

在 RAM 控制台创建 RAM 角色（如 ack-agent-identity-sample-role），并配置信任策略，授权 ack-agent-identity 组件通过 RRSA 扮演此角色。将以下模板中的 <oidc_issuer_url> 和 <oidc_provider_arn> 替换为集群的 RRSA OIDC 信息（可通过集群基本信息页的RRSA OIDC部分获取）。

{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "oidc:aud": "sts.aliyuncs.com",
          "oidc:iss": "<oidc_issuer_url>",
          "oidc:sub": [
            "system:serviceaccount:ack-agent-identity:credential-provider"
          ]
        }
      },
      "Effect": "Allow",
      "Principal": {
        "Federated": [
          "<oidc_provider_arn>"
        ]
      }
    }
  ],
  "Version": "1"
}

步骤 2：为该 RAM 角色授予自定义权限策略

为上一步创建的 RAM 角色授予自定义权限策略（建议按最小权限精细化授权，避免直接绑定 AliyunOSSReadOnlyAccess 等范围过大的系统策略）。此处授予的角色权限是最大权限边界，每个实例最终获得的权限还会被下一步 CredentialProvider 的 policy 进一步收缩。以下示例授予对 my-bucket 的只读权限（将 my-bucket 替换为实际 Bucket 名称）：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject",
        "oss:ListObjects"
      ],
      "Resource": [
        "acs:oss:*:*:my-bucket",
        "acs:oss:*:*:my-bucket/*"
      ]
    }
  ]
}

步骤 3：创建 CredentialProvider

将以下内容保存为 credential-provider-sts.yaml 并执行 kubectl apply -f credential-provider-sts.yaml 命令，创建 CredentialProvider 引用上述 RAM 角色。policy 字段定义最终颁发的 STS Token 的权限范围（必须是角色权限的子集）。

apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: CredentialProvider
metadata:
  name: aliyun-oss-readonly
  namespace: <YOUR_NAMESPACE>
spec:
  type: RAM
  ram:
    source:
      provider: RRSA
      rrsa:
        # 步骤 1 创建的 RAM 角色名称
        roleName: ack-agent-identity-sample-role
        policy: |
          {
            "Version": "1",
            "Statement": [
              {
                "Effect": "Allow",
                "Action": ["oss:GetObject"],
                "Resource": ["acs:oss:*:*:my-bucket/agent-data/*"]
              },
              {
                "Effect": "Allow",
                "Action": ["oss:ListObjects"],
                "Resource": ["acs:oss:*:*:my-bucket"],
                "Condition": {
                  "StringLike": { "oss:Prefix": ["agent-data/*"] }
                }
              }
            ]
          }
        tokenValidity: 3600s  # STS 凭据有效期，默认 1h，最短 15m

policy 支持通过模板变量按 Agent 身份等上下文动态收缩权限，实现实例级的权限最小化，详见policy 权限收缩与模板变量。

步骤 4：创建 AgentIdentity

将以下内容保存为 agent-identity.yaml 并执行 kubectl apply -f agent-identity.yaml 命令，创建 AgentIdentity 定义 Agent 身份标识。

apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: AgentIdentity
metadata:
  name: my-agent          # Agent 身份名称，后续授权中引用
  namespace: <YOUR_NAMESPACE>
spec:
  description: "示例 AI Agent 身份"

步骤 5：创建 AgentRole 与 AgentRoleBinding

将以下内容保存为 agent-role-sts.yaml 并执行 kubectl apply -f agent-role-sts.yaml 命令，创建 AgentRole 和 AgentRoleBinding，授权 Agent 身份获取该 CredentialProvider 的凭据。

apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: AgentRole
metadata:
  name: get-aliyun-sts
  namespace: <YOUR_NAMESPACE>
spec:
  rules:
  - effect: Allow
    action: "GetResourceCredential"
    # 与步骤 3 创建的 CredentialProvider 名称保存一致
    resource: "CredentialProvider/aliyun-oss-readonly"
---
apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: AgentRoleBinding
metadata:
  name: my-agent-get-aliyun-sts
  namespace: <YOUR_NAMESPACE>
spec:
  agentRoleRef:
    apiGroup: agentidentity.alibabacloud.com
    kind: AgentRole
    name: get-aliyun-sts
  subjects:
  - authorizationType: "Agent"
    agentAuthorizationConfiguration:
      # 与步骤 4 创建的 AgentIdentity name 保持一致
      agentName: my-agent 

步骤 6：确认 CredentialProvider 已就绪

确认 CredentialProvider 已就绪（Available 列为 True）。

kubectl get credentialprovider aliyun-oss-readonly -n <YOUR_NAMESPACE>

预期输出：

NAME                  AVAILABLE   AGE
aliyun-oss-readonly   True        30s

RRSA 来源的 CredentialProvider 通过校验后即标记为 Available，此时仅表示配置合法，并不代表已成功扮演 RAM 角色。角色不存在、信任策略配置错误、权限不足等问题会在实际获取 STS 凭据时才暴露，详见状态与排查。

步骤 7：验证 RAM 角色扮演可用性

由于 Available=True 仅代表配置合法，建议在进入生产前触发一次实际的凭据签发以验证 RAM 角色能被成功扮演。可通过消费凭据章节任一场景发起一次真实请求，观察是否成功签发凭据；若签发失败，按状态与排查章节的现象与排查方向定位。

消费凭据

创建并授权好的 STS 凭据，通常由以下几类场景消费，均无需应用侧持有长期 AK/SK：

• Agent Sandbox 出口流量凭据注入：为 SecurityProfile 的 tokenTransformation 规则引用本 CredentialProvider，Sandbox 应用使用伪造的 AK/SK 通过标准阿里云 SDK 发起请求，出口网关在转发时透明替换为真实 STS 三元组并重新计算请求签名。完整端到端配置请参见为Agent Sandbox出口流量注入凭据。

• OSS 存储挂载：为 Sandbox 声明 authType: agent-identity 的存储卷，挂载时通过 credentialProviderName 引用本 CredentialProvider，容器存储接口（CSI，Container Storage Interface）使用签发的 STS 凭据按需挂载 OSS 目录。完整端到端配置请参见为Agent Sandbox挂载OSS存储。

• AgenticFS 存储挂载：为 Sandbox 声明 authType: agent-identity 的存储卷，挂载时通过 credentialProviderName 引用本 CredentialProvider，容器存储接口使用签发的 STS 凭据按需挂载 AgenticFS 目录。完整端到端配置请参见为 Agent Sandbox 挂载 AgenticFS。

policy 权限收缩与模板变量

每个实例最终获得的 STS 凭据权限，为RAM 角色权限与CredentialProviderpolicy 的交集。policy 只能在角色权限范围内进一步收缩，无法放大超出角色的权限。合理配置 policy 是实现实例级最小权限的关键。

policy 的内容为标准的 RAM 权限策略 JSON，共有三种写法：静态 policy 直接声明固定权限，模板变量按当前请求身份上下文替换资源路径，内置函数按 Sandbox 实例的挂载配置自动填充。以下按顺序介绍。

policy: |
  {
    "Statement": [
      {
        "Action": ["oss:GetObject", "oss:PutObject"],
        "Effect": "Allow",
        "Resource": [
          "acs:oss:*:*:my-bucket/${ack:agent-identity/metadata/tenant-id}/*"
        ]
      }
    ],
    "Version": "1"
  }

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxClaim
metadata:
  name: my-claim
  namespace: <YOUR_NAMESPACE>
spec:
  templateName: my-sandbox-set
  replicas: 1
  annotations:
    # 以下 annotation 去掉前缀后可通过模板中的 ${ack:agent-identity/metadata/tenant-id} 引用
    security.agents.kruise.io/tenant-id: acme
    security.agents.kruise.io/agent-name: my-agent

[
  "acs:oss:*:*:bucket-abc/sub-path/foo",
  "acs:oss:*:*:bucket-abc/sub-path/foo/*",
  "acs:oss:*:*:bucket-abc/sub-path/bar",
  "acs:oss:*:*:bucket-abc/sub-path/bar/*"
]

[
  "acs:oss:*:*:bucket-abc"
]

[
  "sub-path/foo/*",
  "sub-path/bar/*"
]

[
  "acs:kms:cn-hangzhou:123456789:key",
  "acs:kms:cn-hangzhou:123456789:alias",
  "acs:kms:cn-hangzhou:123456789:key/key-1",
  "acs:kms:cn-hangzhou:123456789:key/key-2",
  "acs:kms:cn-hangzhou:123456789:alias/key-1",
  "acs:kms:cn-hangzhou:123456789:alias/key-2"
]

[
  "acs:kms:cn-hangzhou:123456789:key",
  "acs:kms:cn-hangzhou:123456789:key/*",
  "acs:kms:cn-hangzhou:123456789:alias",
  "acs:kms:cn-hangzhou:123456789:alias/*"
]

[
  "acs:oss:*:*:sbx-1799-cn-hangzhou-bs-apsr/sub-path/foo",
  "acs:oss:*:*:sbx-1799-cn-hangzhou-bs-apsr/sub-path/foo/*",
  "acs:oss:*:*:sbx-1799-cn-hangzhou-bs-apsr/sub-path/bar",
  "acs:oss:*:*:sbx-1799-cn-hangzhou-bs-apsr/sub-path/bar/*"
]

[
  "acs:oss:*:*:sbx-1799-cn-hangzhou-bs-apsr"
]

[
  "acs:nas:cn-hangzhou:123456:filesystem/*"
]

[
  "acs:nas:cn-hangzhou:123456:accesspoint/ap-foo",
  "acs:nas:cn-hangzhou:123456:accesspoint/ap-bar"
]

RRSA 跨账号访问（targetRoleArn）

默认情况下 RRSA 只能扮演本账号的 RAM 角色。若 Agent 需访问另一个阿里云账号下的资源，可通过 targetRoleArn 开启跨账号扮演：ack-agent-identity 先用 RRSA 扮演本账号的 roleName 获取一个中间 STS 凭据，再用该中间凭据 AssumeRole 到 targetRoleArn 指向的目标账号角色，最终签发目标账号的 STS 凭据。此时 policy、tokenValidity 均作用于第二跳（即最终扮演目标角色）。

整个过程由 ack-agent-identity 组件向 STS 服务发起两次请求：

1. AssumeRoleWithOIDC（扮演源账号角色 roleName）→ 获得中间 STS 凭据（源账号角色身份）

2. AssumeRole（凭中间凭据扮演目标账号角色 targetRoleArn）→ 获得最终 STS 凭据（目标账号角色身份）

   跨账号涉及两个 RAM 角色：源账号角色（第一跳，即 CredentialProvider 中 roleName 指向的角色，位于集群所在账号）与目标账号角色（第二跳，targetRoleArn 指向的角色，位于被访问账号）。按以下步骤配置：

步骤 1：为源账号角色授予扮演目标角色的权限

在源账号为源账号角色授予扮演目标角色的权限。源账号角色于跨账号场景下仅作跳板，无需任何资源访问权限，只需授予sts:AssumeRole权限；其信任策略仍为信任集群 RRSA OIDC，与配置 STS 凭据步骤 1 一致。为该角色附加如下自定义权限策略（将 Resource 替换为实际目标角色 ARN）：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": ["acs:ram::123456789012:role/cross-oss-role"]
    }
  ]
}

步骤 2：在目标账号创建目标账号角色并配置信任策略

在目标账号创建目标账号角色（如 cross-oss-role），其信任策略仅信任源账号角色（而非整个源账号），只允许该角色扮演。将 <源账号 UID> 替换为源账号的账号 ID，ack-agent-identity-sample-role 替换为实际的源账号角色名：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Principal": {
        "RAM": ["acs:ram::<源账号 UID>:role/ack-agent-identity-sample-role"]
      }
    }
  ]
}

随后为目标账号角色授予其在目标账号内实际要访问的资源权限（此为最大权限边界，建议按最小权限精细化授权，写法同配置 STS 凭据步骤 2 的自定义策略）。该权限还会被下一步 CredentialProvider 的 policy 进一步收缩。

跨账号角色的创建与信任配置详见通过RAM角色跨阿里云账号授权。

步骤 3：创建引用 targetRoleArn 的 CredentialProvider

创建引用 targetRoleArn 的 CredentialProvider（policy、tokenValidity 作用于第二跳，即于目标角色权限内进一步收缩）：

apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: CredentialProvider
metadata:
  name: cross-account-oss
  namespace: <YOUR_NAMESPACE>
spec:
  type: RAM
  ram:
    source:
      provider: RRSA
      rrsa:
        # 源账号角色（第一跳）
        roleName: ack-agent-identity-sample-role   
        # 目标账号角色（第二跳）                 
        targetRoleArn: "acs:ram::123456789012:role/cross-oss-role"  
        policy: |
          {
            "Version": "1",
            "Statement": [
              {
                "Effect": "Allow",
                "Action": ["oss:GetObject"],
                "Resource": ["acs:oss:*:*:cross-bucket/*"]
              }
            ]
          }

targetRoleArn 须为合法的 RAM 角色 ARN，格式为 acs:ram::<目标账号 UID>:role/<角色名>，可通过目标账号的 RAM 角色详情页查看。

字段说明

type: RAM + RRSA 来源的 spec 结构如下：

spec:
  type: RAM                          # 必填，凭据类型；创建后不可变更
  ram:
    source:
      provider: RRSA                 # 必填，凭据来源
      rrsa:
        roleName: <role-name>        # 必填，要扮演的本账号 RAM 角色名称
        policy: <policy-json>        # 必填，会话策略，须为角色权限的子集
        tokenValidity: 1h            # 可选，STS 凭据有效期，默认 1h
        targetRoleArn: <role-arn>    # 可选，跨账号扮演的目标角色 ARN

关键字段说明如下：

状态与排查

CredentialProvider 的运行状态记录于 status.conditions，可通过以下命令查看：

kubectl describe credentialprovider <name> -n <YOUR_NAMESPACE>

RRSA 来源的 CredentialProvider 只要通过配置校验就会立即标记为 Available=True（Reason 为 ReconcileSucceeded），协调阶段不会校验 RAM 角色是否存在、信任策略是否正确、权限是否足够。因此，与 RAM 角色相关的错误不会体现在 CredentialProvider 的状态上，而是在实际签发 STS 凭据（调用 AssumeRoleWithOIDC）时才暴露。常见运行时错误及排查方向如下：

出口注入与 OSS 挂载场景的完整分层排查手段，请分别参见为Agent Sandbox出口流量注入凭据与为Agent Sandbox挂载OSS存储。

使用限制

以下为本功能的硬性约束一览，细节描述保留于对应章节：

常见问题

相关文档

• 为Agent Sandbox出口流量注入凭据

• 为Agent Sandbox挂载OSS存储

• 通过RAM角色跨阿里云账号授权

• 设置RAM角色最大会话时间

• 通过RRSA配置ServiceAccount的RAM权限