tencent cloud

容器服务

文档容器服务实践教程安全TKE Authenticator 组件实践指南

TKE Authenticator 组件实践指南

下载
聚焦模式
字号
最后更新时间： 2026-09-29 16:24:17
本文档已由 AI 辅助审校

组件介绍

TkeAuthenticator 是一个 Kubernetes Authentication Webhook 和 Authorization Webhook 服务，为 TKE 集群提供基于腾讯云 CAM 的身份认证（CAM Identity Authentication）和访问控制能力。
该组件允许用户通过 腾讯云 CAM（Cloud Access Management）身份访问 Kubernetes 集群，无需在本地存储任何静态集群凭证（如 x509 客户端证书或静态令牌）。同时，它支持将 Kubernetes RBAC 权限管理机制对接腾讯云 CAM 用户组，便于对子账号进行细粒度的访问权限控制。

使用场景

能力
说明
对应 Kubernetes 阶段
CAM 身份认证（CAM Identity Authentication）
通过 CAM 身份验证用户，将 CAM 用户/角色映射为 Kubernetes RBAC 用户和用户组。配合 tke-cam-tool 使用，构建 CAM 身份到 Kubernetes RBAC 用户/组的桥梁。
CAM 用户组鉴权（CAM User Group Authorization）
基于 CAM 用户组进行 Kubernetes RBAC 鉴权，支持按用户组维度批量管理集群权限。CAM 用户组 是多个相同职能的用户（子账号）的集合，适用于为职能相同的子账号快速设置相同的 Kubernetes 对象访问权限。

组件说明

说明：
UserGroupAccessControl（CAM 用户组鉴权）原为独立组件，现已合并至 TkeAuthenticator 统一部署。
认证和鉴权是完全独立的两个功能模块，分别对应 Kubernetes 请求处理流程中的 Authentication 和 Authorization 阶段，彼此之间没有功能依赖关系。
安装 TkeAuthenticator 后，两个功能默认开启，无需额外配置，也可单独使用其中任一功能。

限制条件

1. TKE 托管集群，Kubernetes 版本 ≥ 1.20。
2. TkeAuthenticator 组件版本 ≥ 1.0.0。

安装组件

1. 登录 容器服务控制台，选择左侧导航栏中的集群。
2. 在集群管理页面，单击目标集群 ID，进入集群详情页。
3. 选择左侧导航中的组件管理，在组件管理页面中单击新建。
4. 在新建组件页面，选择认证授权模块，勾选 TkeAuthenticator 组件。如下图所示：

5. 单击服务授权。为使容器服务能够读取您账号下的用户组信息，需要在组件安装时完成角色 TKE_QCSRole 关联预设策略 QcloudAccessForTKERoleInGroupsForUser 的授权。如下图所示：

在服务授权页面中，确认角色名称和授权策略，单击同意授权。

6. 返回新建组件页面，单击完成。安装完成后，可在组件管理页面查看组件状态和详情。

CAM 身份认证（CAM Identity Authentication）

TkeAuthenticator 的 CAM 身份认证功能通过 Authentication Webhook 实现，将腾讯云 CAM 身份映射为 Kubernetes RBAC 用户和用户组。配合 tke-cam-tool 一起使用，TkeAuthenticator 可构建 CAM 身份到 Kubernetes RBAC 用户/组的桥梁，从而避免在本地存储任何静态集群凭证（如 x509 客户端证书或静态令牌）。
该“桥梁”由一个自定义资源定义（Custom Resource Definition，CRD）CAMIdentityMapping 实现，它定义了如何将 CAM 身份映射到 Kubernetes 用户/组。

工作原理

TkeAuthenticator 认证流程如下图所示：

流程说明：
1. 用户请求：用户通过 kubectl 携带 token 发送请求至 Kubernetes API Server。
2. Webhook 认证：API Server 将 token 封装为 TokenReview 请求，转发至 TkeAuthenticator。
3. 身份验证：TkeAuthenticator 将 token 中的请求发送至腾讯云安全令牌服务（Security Token Service，STS），调用 GetCallerIdentity 获取用户的 CAM 身份信息（ARN）。
4. 映射查找：TkeAuthenticator 在所有 CAMIdentityMapping 中查找与该 ARN 匹配的映射规则，返回对应的 Kubernetes RBAC 用户名和用户组给 API Server。
5. RBAC 鉴权：API Server 使用返回的用户名和用户组执行标准的 RBAC 鉴权（检查 RoleBinding / ClusterRoleBinding）。
6. 处理请求：鉴权通过后，API Server 处理用户请求并返回结果。
说明：
如果 ARN 在所有 CAMIdentityMapping 中均未找到匹配，TkeAuthenticator 将返回 "Not Authenticated" 决策，用户会看到 "Unauthorized" 错误。

Token 机制

用户需要一个由腾讯云凭证签名的特殊 token 来向 Kubernetes API Server 进行身份认证。
该 token 本质上是一个序列化的 GetCallerIdentity 请求，后续由 TkeAuthenticator 发送至 STS 服务以获取用户的 CAM 身份。用于签名请求的腾讯云凭证（生成 Authorization header 中的签名）代表了用户希望被认证为的 CAM 身份。例如，使用某个子账号的 Secret ID 和 Secret Key 签名 token，则该 token 将被认证为该子账号。
Token 格式：
Token 由固定前缀 k8s-tke-v1. 加上 base64 编码的 JSON 组成：
k8s-tke-v1.<base64 编码的 JSON>
解码后的 JSON 结构如下：
{
  "clusterId": "cls-*****",
  "header": {
    "Authorization": [
      "TC3-HMAC-SHA256 Credential=AKID*****/2024-09-03/sts/tc3_request, SignedHeaders=content-type;host;x-tc-action;x-tc-tke-clusterid, Signature=*****"
    ],
    "Content-Type": ["application/json; charset=utf-8"],
    "Host": ["sts.internal.tencentcloudapi.com"],
    "X-TC-Action": ["GetCallerIdentity"],
    "X-TC-TKE-ClusterID": ["cls-*****"],
    "X-TC-Timestamp": ["1725332268"],
    "X-TC-Token": ["*****"],
    "X-TC-Version": ["2018-08-13"]
  }
}
必须存在的 Header 字段：
字段
说明
Authorization
身份认证签名。详情请参见 签名方法 v3。
Content-Type
请求内容类型。
Host
STS 服务端点地址。
X-TC-Action
固定为 GetCallerIdentity。
X-TC-TKE-ClusterID
token 可访问的集群 ID。
必须签名的 Header 字段（必须出现在 Authorization 的 SignedHeaders 中）：
content-type
host
x-tc-action
x-tc-tke-clusterid（确保 token 只能用于访问指定集群）
说明：
token 有效期为 5 分钟（由 Authorization header 中的签名有效期决定）。详情请参见 腾讯云请求公共参数文档。

客户端工具（tke-cam-tool）

tke-cam-tool 是一个 CLI 工具，帮助用户生成访问 Kubernetes API Server 所需的 kubeconfig 文件和 token。
tke-cam-tool 使用流程如下图所示：

生成 Token
tke-cam-tool 使用用户提供的腾讯云凭证生成 token：
tke-cam-tool exec-cred token --cluster-id <CLUSTER_ID> [FLAGS...]
生成的 token 被封装在 ExecCredential 对象中，输出到标准输出供 kubectl 捕获和解析：
{
  "kind": "ExecCredential",
  "apiVersion": "client.authentication.k8s.io/v1beta1",
  "spec": { "interactive": false },
  "status": {
    "expirationTimestamp": "2024-10-12T09:18:05Z",
    "token": "k8s-tke-v1.<base64 编码内容>"
  }
}
缓存机制：
ExecCredential 中的 expirationTimestamp 为 token 的过期时间，tke-cam-tool 会复用未过期的缓存 token。
生成的 ExecCredential 有效期为 4 分钟（比实际 token 的 5 分钟有效期少 1 分钟，预留网络传输时间）。
使用 --no-cache 标志可禁用缓存，强制每次生成新 token。
使用 --role 扮演角色时，缓存的 token 必须使用相同的 role ARN、external ID 和 session name 才会被复用。
生成 Kubeconfig
生成可直接用于访问集群的 kubeconfig 文件：
tke-cam-tool exec-cred kubeconfig --cluster-id <CLUSTER_ID> --region <REGION> [FLAGS...]
该命令通过调用 DescribeClusterEndpoints 接口获取集群的 API Server 地址和 CA 证书，然后组装 kubeconfig 文件。
生成的 kubeconfig 利用 k8s.io/client-go 的 ExecCredential 插件 能力，在每次 kubectl 请求时动态运行 tke-cam-tool exec-cred token 命令生成 token。示例：
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: BASE64_PEM_ENCODED_CA_CERTIFICATE
    server: API_SERVER_ADDRESS
  name: <CLUSTER_ID>                   # 自动生成，值为集群 ID
contexts:
- context:
    cluster: <CLUSTER_ID>
    user: <CLUSTER_ID>-exec-cred-plugin
  name: <CLUSTER_ID>-exec-cred-plugin-context  # 自动生成
current-context: <CLUSTER_ID>-exec-cred-plugin-context
kind: Config
preferences: {}
users:
- name: <CLUSTER_ID>-exec-cred-plugin  # 自动生成
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      args:
      - exec-cred
      - token
      - --cluster-id
      - <CLUSTER_ID>
      - --profile
      - default
      command: tke-cam-tool
      env: null
      interactiveMode: Never
      provideClusterInfo: false

映射规则（CAMIdentityMapping）

上述工作原理的第 4 步中，TkeAuthenticator 需要通过映射规则将 CAM 身份转换为 Kubernetes 用户。该映射规则即 CAMIdentityMapping——一个 Kubernetes CRD（Custom Resource），用于定义从 CAM 身份的 ARN 到 Kubernetes RBAC 用户和用户组的映射关系。
当用户通过 TkeAuthenticator 认证时，组件会从所有 CAMIdentityMapping 中查找与用户 ARN 匹配的规则，并返回对应的 Kubernetes 用户名和用户组给 API Server。
基本结构
apiVersion: authenticator.tke.cloud.tencent.com/v1
kind: CAMIdentityMapping
metadata:
  name: <MAPPING_NAME>              # 自定义资源名称，例如：my-sub-account-mapping
spec:
  arn: <CAM_IDENTITY_ARN>        # CAM 身份 ARN，例如：qcs::cam::uin/100000000001:uin/100000000002
  username: <K8S_USERNAME>         # 自定义 Kubernetes 用户名，例如：my-user
  groups:                             # 映射后的 Kubernetes 用户组（可选）
    - <GROUP_1>                     # 自定义用户组名称，例如：dev-team
    - <GROUP_2>                    # 自定义用户组名称，例如：read-only
字段说明：
字段
必填
说明
metadata.name
是
资源名称，自定义即可，在集群内唯一。
spec.arn
是
CAM 身份的 ARN，用于匹配认证用户。支持精确匹配和通配符。
spec.username
是
认证成功后返回给 API Server 的 Kubernetes 用户名。
spec.groups
否
认证成功后返回给 API Server 的 Kubernetes 用户组列表。
完整示例
将子账号映射为 Kubernetes 用户，并加入自定义用户组以及该子账号所属的所有 CAM 用户组：
apiVersion: authenticator.tke.cloud.tencent.com/v1
kind: CAMIdentityMapping
metadata:
  name: <MAPPING_NAME>              # 自定义资源名称，例如：my-sub-account-mapping
spec:
  arn: qcs::cam::uin/<ROOT_ACCOUNT_ID>:uin/<SUB_ACCOUNT_ID>
  username: <K8S_USERNAME>           # 自定义 Kubernetes 用户名，例如：my-user
  groups:
    - read-group                  # 自定义用户组名称
    - write-group                  # 自定义用户组名称
    - {{CAMUserGroupIDs}}
支持的 ARN 类型
ARN（Access Resource Name）是全局唯一的 CAM 身份标识符，格式为 qcs::SERVICE:(REGION:)ACCOUNT:RESOURCE。
类型
ARN 格式
示例
主账号
qcs::cam::uin/<ROOT_ACCOUNT_ID>:root
qcs::cam::uin/100000000001:root
子账号
qcs::cam::uin/<ROOT_ACCOUNT_ID>:uin/<SUB_ACCOUNT_ID>
qcs::cam::uin/100000000001:uin/100000000002
CAM 角色
qcs::cam::uin/<ROOT_ACCOUNT_ID>:role/<ROLE_ID>
qcs::cam::uin/100000000001:role/4611686018427000001
联合账号
qcs::sts::uin/<ROOT_ACCOUNT_ID>:federated-user/<UIN>
qcs::sts::uin/100000000001:federated-user/100000000002
通配符
qcs::cam::uin/<ROOT_ACCOUNT_ID>:uin/*
匹配该主账号下所有子账号
说明：
UIN 是用户 ID，可在腾讯云控制台右上角头像处查看。
占位符
您可以在 username 和 groups 中使用占位符，它们会在认证成功后被自动替换为实际值。所有占位符都用双花括号 {{}} 包围。
通用占位符（username 和 groups 均可使用）：
占位符
说明
{{AccountID}}
CAM 身份所属的主账号 ID
{{SessionName}}
CAM 身份的会话名称（仅 CAM 角色有效）
{{SecretID}}
Token 签名所使用的腾讯云 Secret ID
示例——使用 {{AccountID}} 作为用户名：
apiVersion: authenticator.tke.cloud.tencent.com/v1
kind: CAMIdentityMapping
metadata:
  name: <MAPPING_NAME>              # 自定义资源名称，例如：account-id-mapping
spec:
  arn: qcs::cam::uin/<ROOT_ACCOUNT_ID>:uin/<SUB_ACCOUNT_ID>
  username: {{AccountID}}
仅 groups 可使用的占位符：
占位符
说明
{{CAMUserGroupIDs}}
子账号所属的所有 CAM 用户组 ID（仅子账号有效）
{{CAMUserGroupIDs}} 会在认证时自动展开为该子账号所属的所有 CAM 用户组 ID。您可以在占位符前后添加自定义前缀/后缀来控制返回的用户组格式。
示例——使用 {{CAMUserGroupIDs}} 关联用户组：
apiVersion: authenticator.tke.cloud.tencent.com/v1
kind: CAMIdentityMapping
metadata:
  name: <MAPPING_NAME>              # 自定义资源名称，例如：cam-group-mapping
spec:
  arn: qcs::cam::uin/<ROOT_ACCOUNT_ID>:uin/<SUB_ACCOUNT_ID>
  username: <K8S_USERNAME>           # 自定义 Kubernetes 用户名，例如：my-user
  groups:
    - cam-group-{{CAMUserGroupIDs}}
假设子账号属于 CAM 用户组 56789 和 67890，则认证后返回的用户组为：
cam-group-56789
cam-group-67890
注意：
如果子账号不属于任何 CAM 用户组，则该占位符不会产生任何用户组。
{{CAMUserGroupIDs}} 仅当 CAM 身份是子账号时有效。如果 CAM 身份是角色或联合账号，该占位符不会产生任何用户组。

快速开始

以下步骤演示如何以 CAM 身份访问 Kubernetes 集群并读取 Pod 资源。
开始前，请确认：
1. 本地已安装 kubectl。
2. 集群已开启公网访问。
注意：
开启集群外网访问后，需要配置 自定义公网域名解析。

步骤一：安装 tke-cam-tool

根据您的客户端架构选择对应的二进制工具进行下载。工具下载地址：https://mirrors.tencent.com/install/tke-cam-tool/v0.0.9/

步骤二：获取腾讯云凭证

根据您的凭证类型，选择以下任一方式：
方式
适用场景
凭证类型
已有子账号 Secret ID / Secret Key
永久密钥
通过企业 SSO 或腾讯云账号 OAuth 登录
临时密钥
方式一：使用腾讯云密钥
适用于已有腾讯云子账号密钥的场景。
export TENCENTCLOUD_SECRET_ID=<YOUR_SECRET_ID>
export TENCENTCLOUD_SECRET_KEY=<YOUR_SECRET_KEY>
说明：
如果您还没有腾讯云密钥，请登录子账号腾讯云控制台，在 访问管理 页面左侧单击访问密钥获取。
请确认使用的是子账号密钥而非主账号密钥，因为密钥代表着访问集群的 CAM 身份。
请参见 子账号创建密钥 了解如何为子账号创建密钥。
方式二：使用 SSO 登录
适用于通过企业 SSO 或腾讯云账号 OAuth 登录的场景，无需手动管理密钥。选择以下任一方式完成登录：
企业 SSO 登录（通过企业统一身份认证 IdP 登录）：
# 配置 SSO 登录地址
# 替换 <YOUR_SSO_ID> 为企业 SSO 配置 ID（从企业 IdP 管理员处获取）
tccli sso configure --url https://tencentcloudsso.com/<YOUR_SSO_ID>/login

# 执行登录
tccli sso login
腾讯云账号 OAuth 登录（直接使用腾讯云账号登录）：
tccli auth login
根据提示在浏览器中完成登录，登录成功后凭证会自动写入 ~/.tccli/default.credential。

步骤三：部署 CAMIdentityMapping

创建 CAMIdentityMapping，将 CAM 身份映射到 Kubernetes 用户。根据步骤二选择的方式，arn 字段的填写方式不同：
说明：
鼠标悬停在腾讯云控制台右上角头像处，可查看主账号 ID 和子账号 ID。
方式一（密钥）对应的配置
使用子账号密钥时，arn 填写子账号的 CAM 用户 ARN：
apiVersion: authenticator.tke.cloud.tencent.com/v1
kind: CAMIdentityMapping
metadata:
  name: <MAPPING_NAME>               # 自定义资源名称，例如：my-cam-mapping
spec:
  arn: qcs::cam::uin/<ROOT_ACCOUNT_ID>:uin/<SUB_ACCOUNT_ID>
  username: <K8S_USERNAME>            # 自定义 Kubernetes 用户名，例如：my-user，后续 RBAC 绑定需与此一致
方式二（SSO）对应的配置
使用 SSO 登录时，凭证为临时密钥，需通过 --role 扮演 CAM 角色，arn 填写该角色的 ARN：
apiVersion: authenticator.tke.cloud.tencent.com/v1
kind: CAMIdentityMapping
metadata:
  name: <MAPPING_NAME>               # 自定义资源名称，例如：my-cam-mapping
spec:
  arn: qcs::cam::uin/<ROOT_ACCOUNT_ID>:role/<ROLE_ID>
  username: <K8S_USERNAME>            # 自定义 Kubernetes 用户名，例如：my-user，后续 RBAC 绑定需与此一致
说明：
支持的 ARN 格式请参见 支持的 ARN 类型。

步骤四：创建 RBAC 权限规则

为映射的用户授予读取 Pod 的权限（<K8S_USERNAME> 需与上面 CAMIdentityMapping 中的 username 保持一致）：
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: <CLUSTER_ROLE_NAME>           # 自定义 ClusterRole 名称，例如：pod-reader
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: <BINDING_NAME>               # 自定义 ClusterRoleBinding 名称，例如：my-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: <CLUSTER_ROLE_NAME>           # 引用上面创建的 ClusterRole 名称
subjects:
  - kind: User
    apiGroup: rbac.authorization.k8s.io
    name: <K8S_USERNAME>              # 与 CAMIdentityMapping 中的 username 保持一致，例如：my-user

步骤五：生成 kubeconfig

确认已开启集群的公网访问，设置集群 ID 和地域：
export CLUSTER_ID=<YOUR_CLUSTER_ID>    # 例如：cls-xxxxxxxx
export REGION=<YOUR_REGION>            # 例如：ap-guangzhou
说明：
集群 ID 可在腾讯云控制台的集群列表页面中查看。
根据步骤二选择的方式，执行对应命令：
方式一（密钥）生成 kubeconfig
tke-cam-tool exec-cred kubeconfig \\
  --cluster-id ${CLUSTER_ID} \\
  --region ${REGION} \\
  -o ${CLUSTER_ID}.kubeconfig
方式二（SSO）生成 kubeconfig
SSO 临时密钥不能直接签名 token，需通过 --role 扮演 CAM 角色：
tke-cam-tool exec-cred kubeconfig \\
  --cluster-id ${CLUSTER_ID} \\
  --region ${REGION} \\
  --profile default \\
  --token-profile default \\
  --role qcs::cam::uin/<ROOT_ACCOUNT_ID>:roleName/<ROLE_NAME> \\  # 替换为实际的主账号 ID 和角色名称
  -o ${CLUSTER_ID}.kubeconfig
参数说明：
参数
说明
--profile default
使用 SSO 登录写入的凭证调用 TKE 接口获取集群信息
--token-profile default
kubeconfig 中 kubectl 调用 tke-cam-tool 时使用的凭证
--role
扮演 CAM 角色获取新的临时密钥，格式为 qcs::cam::uin/<ROOT_ACCOUNT_ID>:roleName/<ROLE_NAME>。替换 <ROOT_ACCOUNT_ID> 为主账号 ID（例如：100000000001），<ROLE_NAME> 为 CAM 角色名称（例如：TKE_QCSRole）

步骤六：验证访问

# 可以读取 pods（已授权）
kubectl --kubeconfig ${CLUSTER_ID}.kubeconfig get pod

# 无法读取 deployments（未授权）
kubectl --kubeconfig ${CLUSTER_ID}.kubeconfig get deployment
# Error from server (Forbidden): deployments.apps is forbidden: User "<K8S_USERNAME>" cannot list resource "deployments" in API group "apps" in the namespace "default"

CAM 用户组鉴权（CAM User Group Authorization）

TkeAuthenticator 内置了基于 CAM 用户组的鉴权功能（即 Authorization Webhook），支持将 Kubernetes RBAC 权限管理机制对接腾讯云 CAM 用户组，便于对子账号进行细粒度的访问权限控制。安装组件后，该功能默认开启。

使用场景

CAM 用户组 是多个相同职能的用户（子账号）的集合，可以实现批量的授权、设置订阅消息等功能。本功能适用于需要在 TKE 集群中为职能相同的子账号快速设置相同的 Kubernetes 对象访问权限的场景。
例如：
开发团队的所有成员需要对某些命名空间拥有读写权限
运维团队需要集群级别的管理权限
测试团队仅需要对特定命名空间的只读权限
通过将子账号加入对应的 CAM 用户组，并为用户组绑定 Kubernetes RBAC 规则，即可实现批量权限管理，无需为每个用户单独配置 RBAC 规则。

工作原理

鉴权流程如下：
1. 用户请求：用户通过 kubectl 发送请求至 API Server（此时已通过认证阶段）。
2. 转发鉴权：API Server 将请求封装为 SubjectAccessReview，转发至 TkeAuthenticator 的 /authorize 端点。
3. 查询用户组：TkeAuthenticator 从请求中提取用户标识（UIN），查询缓存或调用腾讯云 CAM ListGroupsForUser API 获取该用户所属的所有用户组。
4. RBAC 评估：TkeAuthenticator 将用户组 ID 附加到用户的 groups 中，在本地评估 RBAC 规则（ClusterRole/Role + ClusterRoleBinding/RoleBinding），做出鉴权决策。
5. 返回结果：TkeAuthenticator 返回鉴权决策（Allow / Deny / NoOpinion）给 API Server。
说明：
当用户不属于任何 CAM 用户组，或 RBAC 规则中没有匹配的授权时，返回 NoOpinion，API Server 会继续使用其他 authorizer（如内置 RBAC）进行鉴权。

快速开始

步骤一：新建用户组

您需要在访问管理 CAM 服务中完成用户组创建，操作详情请参见 新建用户组。若您已有用户组，可跳过此步骤。

步骤二：创建基于用户组的 RBAC 规则

您可以通过以下两种方式为用户组创建 RBAC 规则：
方式
适用场景
通过可视化界面操作，适合不熟悉 YAML 的用户
通过 YAML 文件创建，适合熟悉 Kubernetes 的用户
方式一：通过 TKE 控制台
1. 选择左侧导航栏中的授权管理 > ClusterRole，在 ClusterRole 页面单击 RBAC 策略生成器。
2. 在新建 ClusterRole 中，账号类型选择用户组，并勾选用户组。如下图所示：

3. 单击下一步。在集群 RBAC 设置中，为指定用户组设置 Kubernetes 对象资源权限。
4. 单击完成。
查看角色绑定策略：
选择左侧导航栏中的授权管理 > ClusterRoleBinding，在 ClusterRoleBinding 中查看以用户组 ID 命名开头的权限策略信息。
说明：
若您需要变更腾讯云资源的操作权限，如组内子账号迁移、增加/删除云产品的操作权限，您仅需在 CAM 侧的用户组进行修改，权限变更的结果会在您创建的角色绑定策略中即时生效。操作详情请参见 为用户组添加/移除用户。
方式二：通过 kubectl 命令行
假设 CAM 用户组 ID 为 <CAM_USER_GROUP_ID>（例如 12345），创建以下 RBAC 规则，允许该用户组的成员读取所有 Pod：
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: <CLUSTER_ROLE_NAME>           # 自定义 ClusterRole 名称，例如：pod-reader
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: <BINDING_NAME>               # 自定义 ClusterRoleBinding 名称，例如：cam-group-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: <CLUSTER_ROLE_NAME>           # 引用上面创建的 ClusterRole 名称
subjects:
  - kind: Group
    apiGroup: rbac.authorization.k8s.io
    name: <CAM_USER_GROUP_ID>       # 替换为 CAM 用户组 ID，例如：12345

步骤三：验证访问

获取集群的 kubeconfig 文件（可通过 TKE 控制台 下载，或使用 tke-cam-tool 生成），然后使用该 CAM 用户的凭证验证访问：
# ${KUBECONFIG_PATH} 替换为实际的 kubeconfig 文件路径
# 验证可以读取 pods（用户组已授权）
kubectl --kubeconfig ${KUBECONFIG_PATH} get pods

# 验证无法执行未授权操作
kubectl --kubeconfig ${KUBECONFIG_PATH} delete pod some-pod
# 预期：返回 Forbidden 错误

使用场景：按团队划分权限

为不同团队创建 CAM 用户组，然后在集群中为每个用户组配置不同的 RBAC 权限：
# 开发团队 - 可以读写 dev 命名空间
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: <BINDING_NAME>               # 自定义 RoleBinding 名称，例如：dev-team-binding
  namespace: dev
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: edit                          # Kubernetes 内置的 ClusterRole
subjects:
  - kind: Group
    apiGroup: rbac.authorization.k8s.io
    name: <DEV_GROUP_ID>            # 替换为开发团队 CAM 用户组 ID，例如：56789
---
# 运维团队 - 集群管理员权限
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: <BINDING_NAME>               # 自定义 ClusterRoleBinding 名称，例如：ops-team-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin                 # Kubernetes 内置的 ClusterRole
subjects:
  - kind: Group
    apiGroup: rbac.authorization.k8s.io
    name: <OPS_GROUP_ID>            # 替换为运维团队 CAM 用户组 ID，例如：67890

缓存管理

TkeAuthenticator 的鉴权模块内置了用户组缓存机制，以减少对 CAM API 的调用频率。

缓存行为

缓存 TTL：默认 10 分钟。
缓存键：以用户 UIN 为键。
缓存更新：TTL 过期后，下次鉴权请求会重新查询 CAM API。

从 UserGroupAccessControl 组件迁移

如果您之前使用的是独立的 UserGroupAccessControl 组件，请按以下步骤迁移：
1. 卸载旧组件：在组件管理页面卸载独立的 UserGroupAccessControl 组件。
2. 安装/升级 TkeAuthenticator：确保集群中安装的 TkeAuthenticator 版本 >= 1.0.0。
3. 保留现有 RBAC 规则：之前为 CAM 用户组创建的 ClusterRole/Role 和 ClusterRoleBinding/RoleBinding 无需修改，可以直接复用。
4. 验证功能正常：使用 CAM 用户凭证访问集群，确认基于用户组的权限控制正常工作。

常见问题

安装 TkeAuthenticator 后需要手动开启 CAM 用户组鉴权吗？

不需要。TkeAuthenticator 安装后，所有功能（认证 + 鉴权）默认开启，无需额外配置。

用户组变更后多久生效？

默认情况下，用户组信息会被缓存 10 分钟。缓存过期后，下次鉴权请求会重新查询 CAM API 获取最新的用户组信息。

如果用户不属于任何 CAM 用户组会怎样？

如果用户不属于任何 CAM 用户组，authorization webhook 将返回 NoOpinion（不做决定），此时 API Server 会继续使用其他 authorizer（如内置 RBAC）进行鉴权。

Authentication Webhook 和 Authorization Webhook 的关系是什么？

两者都由 TkeAuthenticator 提供，但它们是完全独立的两个功能模块，彼此之间没有功能依赖关系：
Authentication Webhook（/authenticate）：负责 CAM 身份认证，验证用户的 CAM 身份并映射到 Kubernetes 用户/组。
Authorization Webhook（/authorize）：负责鉴权，基于 CAM 用户组和 RBAC 规则判断用户是否有权执行某操作。
在 Kubernetes 中，请求处理按照先认证后鉴权的顺序进行，这是 Kubernetes 自身的标准流程。在 TkeAuthenticator 组件内部，认证和鉴权是独立实现的，只是合并部署在同一个服务中。您可以单独使用其中任一功能，也可以同时使用两者。

是否支持 Namespace 级别的权限控制？

A: 是的。Authorization Webhook 支持评估 ClusterRole/ClusterRoleBinding（集群级别）和 Role/RoleBinding（Namespace 级别）的 RBAC 规则。您可以为不同的 CAM 用户组在不同的 Namespace 中配置不同的权限。

{{CAMUserGroupIDs}} 占位符对非子账号身份有效吗？

无效。{{CAMUserGroupIDs}} 仅当 CAM 身份是子账号时有效。如果 CAM 身份是角色或联合账号，该占位符不会产生任何用户组。


上一篇: 使用 ExternalSecretOperator 导入腾讯云 SSM 凭据下一篇: 概述

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈

搜索
    请输入关键词搜索文档