容器服务 tcr-assistant-oidc 简介

二、组件介绍

与原有 tcr-assistant 插件相比，tcr-assistant-oidc 具备以下增强能力：

三、部署在集群内的 Kubernetes 对象

四、组件资源用量

六、免密拉取镜像

Kubernetes 集群拉取私有镜像需要创建访问凭证 Secret 资源，并配置资源 YAML 中的 ImagePullSecret 属性，显式指定已创建的 Secret。整体配置流程较为繁琐，且会因未配置 ImagePullSecret 或指定错误 Secret 而造成镜像拉取失败。

为解决以上问题，可在集群中安装 tcr-assistant-oidc 组件，组件基于 OIDC 身份动态生成指定 TCR 企业版实例的临时访问凭证，并按配置下发至 TKE 集群指定命名空间内，同时自动关联到目标 ServiceAccount 的 imagePullSecrets 字段。在使用 YAML 创建或更新资源时，无需显式配置 ImagePullSecret，集群将会自动使用已下发的动态凭证拉取镜像。

七、跨账号拉取镜像

集群管理员可通过配置 CAM OIDC 身份提供商与角色信任策略，允许 B 账号（TKE 集群所在账号）扮演 A 账号（TCR 实例所在账号）的 CAM 角色，从而免密拉取 A 账号 TCR 企业版实例中的镜像，无需在两个账号间同步长期凭证。同账号也可以使用该组件进行凭证动态更新。

八、自定义域名拉取镜像

若 TCR 企业版实例绑定了自定义域名（如 docker.mycompany.com），组件支持将自定义域名同步写入生成的 dockerconfigjson，工作负载可直接通过自定义域名拉取镜像。

九、动态凭证轮转

组件基于 STS AssumeRoleWithWebIdentity 换取的临时密钥（有效期固定为 2 小时）访问 TCR，Controller 内部按 tokenExpiration 周期性触发凭证轮转，避免长期凭证泄露风险。

十、限制条件

基础环境要求：

·仅支持 Kubernetes 1.20 及以上版本的 TKE 集群（Kubernetes 1.20 将 ServiceAccountIssuerDiscovery 特性升级为正式可用）。

·目标 TKE 集群需已开启 OIDC 功能，且 pod-identity-webhook 组件安装成功。

·已开通 容器镜像服务 TCR 并完成服务授权，且已创建企业版实例（状态为“运行中”）。

针对免密拉取镜像使用场景：

·用户需在 CAM 中配置相应的自定义策略（含 tcr:DescribeInstances、tcr:PullRepository 等），并授予对应角色。建议由具有 TCR 管理员及 CAM 管理员权限的用户完成组件初始化配置。

·组件安装并生效后，请避免在资源 YAML 中重复指定 ImagePullSecret，以免节点使用错误的镜像拉取访问凭证导致镜像拉取失败。

·namespaces 与 serviceAccounts 匹配规则不支持通配符表达式，需明确填写资源名称或使用 * 表示全部。

·Secret 轮转间隔 tokenExpiration 建议在 3600~5400 秒 之间，避免临时密钥（有效期 7200 秒）过期后未及时轮转。

针对跨账号拉取场景：

·B 账号 TKE 集群 VPC 与 A 账号 TCR 实例 VPC 需通过对等连接/云联网互通，且已完成 TCR 实例 Private DNS 解析配置。

·A 账号需在 CAM OIDC 身份提供商中登记 B 账号 TKE 集群的 OIDC Issuer 与 JWKS。

十一、组件权限说明

注意：说明：

注意：权限场景章节仅列举组件核心功能涉及的相关权限，完整权限列表请参见权限定义章节。

十二、权限说明

该组件权限是当前功能实现的最小权限依赖。

十三、权限场景

十四、权限定义

apiVersion: rbac.authorization.k8s.io/v1kind: Rolemetadata: name: tcr-assistant-oidc-leader-election-role namespace: tcr-assistant-systemrules: – apiGroups: [""] resources: ["configmaps"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] – apiGroups: ["coordination.k8s.io"] resources: ["leases"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] – apiGroups: [""] resources: ["events"] verbs: ["create", "patch"]—apiVersion: rbac.authorization.k8s.io/v1kind: ClusterRolemetadata: name: tcr-assistant-oidc-manager-rolerules: – apiGroups: [""] resources: ["secrets"] verbs: ["create", "delete", "get", "list", "patch", "update", "watch"] – apiGroups: [""] resources: ["namespaces"] verbs: ["get", "list", "watch"] – apiGroups: [""] resources: ["serviceaccounts"] verbs: ["get", "list", "patch", "update", "watch"] – apiGroups: [""] resources: ["serviceaccounts/status"] verbs: ["get", "patch", "update"] – apiGroups: ["admissionregistration.k8s.io"] resources: ["mutatingwebhookconfigurations"] verbs: ["create", "get", "patch", "update"] – apiGroups: ["tcr.tencentcloudcr.com"] resources: ["oidcimagepullsecrets"] verbs: ["create", "delete", "get", "list", "patch", "update", "watch"] – apiGroups: ["tcr.tencentcloudcr.com"] resources: ["oidcimagepullsecrets/status"] verbs: ["get", "patch", "update"]

十六、概述

tcr-assistant-oidc 用于帮助用户基于 OIDC 身份自动、动态地部署 Kubernetes imagePullSecret 到任意 Namespace，并关联到该空间下的 ServiceAccount。在用户创建的工作负载当中没有明确指定 imagePullSecret 和 serviceAccount 的情况下，Kubernetes 会尝试从当前命名空间下名为 default 的 ServiceAccount 资源中查找、匹配合适的 imagePullSecret。

与传统方案不同，本组件的 Secret 内容由 STS 临时凭证动态生成，并按 tokenExpiration 周期性轮转，避免了长期凭证泄露的风险。

十七、术语表

十八、实现原理

tcr-assistant-oidc 作为典型的 Kubernetes Operator，在部署时会在目标 Kubernetes 集群中创建 CRD 对象：oidcimagepullsecrets.tcr.tencentcloudcr.com。该 CRD 的 kind 为 OIDCImagePullSecret，版本是 tcr.tencentcloudcr.com/v1，缩写为 oips。

tcr-assistant-oidc 通过持续观察（watch） Kubernetes 集群的 Namespace 和 ServiceAccount 资源，并在这些资源发生变更的时候，检查资源变化是否匹配 OIDCImagePullSecret 中设定的规则来自动为用户部署拉取私有镜像仓库所需要的 Secret 资源。程序部署在 Kubernetes 集群内，使用 in cluster 模式访问 Kubernetes master API；同时依赖 TKE pod-identity-webhook 为 Controller Pod 注入 OIDC Token，通过腾讯云 STS 获取动态临时凭证。

十九、创建 CRD 资源

你需要在 TCR 实例所在账号完成如下 CAM 配置：

1. 在 CAM 控制台-身份提供商 中创建 OIDC 身份提供商，登记 TKE 集群的 OIDC Issuer 与 JWKS。

2. 在 CAM 控制台-策略 中创建自定义策略，授予 tcr:DescribeInstances、tcr:PullRepository 等最小权限。

3. 在 CAM 控制台-角色 中创建角色，信任策略绑定 OIDC 身份提供商，并关联上述自定义策略，记录角色 ARN。

注意：说明：

组件部署完成后，会自动创建对应的 OIDCImagePullSecret 资源。也可通过 kubectl 或 Client Go 手工创建：

# 新建 OIDCImagePullSecret 资源$ kubectl create -f oidcimagepullsecret-sample.yamloidcimagepullsecret.tcr.tencentcloudcr.com/tcr-oidc-sample created

OIDCImagePullSecret 资源示例文件：

apiVersion: tcr.tencentcloudcr.com/v1kind: OIDCImagePullSecretmetadata: name: tcr-oidc-samplespec: namespaces: "*" serviceAccounts: "*" roleArn: "qcs::cam::uin/100001113387:roleName/tcr-cross-account-role" registries: – "your-tcr-registry" customDomains: – "docker.mycompany.com" tokenExpiration: 3600

OIDCImagePullSecret spec 字段解释如下表：

创建完成后，可以通过以下命令观察 tcr-assistant-oidc 执行结果：

# 列出 OIDCImagePullSecret 信息$ kubectl get oipsNAME NAMESPACES SERVICE-ACCOUNTS REGISTRIES CREDENTIAL-STATUStcr-oidc-sample * * [your-tcr-registry] Ready# 查看详细信息$ kubectl describe oips tcr-oidc-sampleName: tcr-oidc-sampleNamespace:API Version: tcr.tencentcloudcr.com/v1Kind: OIDCImagePullSecretSpec: Namespaces: * Service Accounts: * Role Arn: qcs::cam::uin/100001113387:roleName/tcr-cross-account-role Registries: [your-tcr-registry] Custom Domains: [docker.mycompany.com] Token Expiration: 3600Status: Credential Status: Ready Last Refresh Time: 2026-08-05T10:00:00Z Next Refresh Time: 2026-08-05T11:00:00Z Secrets Desired: 10 Secrets Success: 10Events: <none>

注意：如需更新 tcr-assistant-oidc 部署的 Secret 资源，无需删除重建 OIDCImagePullSecret 资源。修改 spec.roleArn、spec.registries、spec.customDomains 等字段后 Controller 会自动 reconcile，Secret 内容将在下一个轮转周期刷新。

20、Namespace 变更

tcr-assistant-oidc 在观察到有新的 Kubernetes Namespace 资源创建后，会首先校验名称是否与 OIDCImagePullSecret 资源中的 namespaces 字段匹配。如果资源名称不匹配，跳过后续流程；若资源名称匹配，则会调用 STS 换取临时凭证、渲染 dockerconfigjson，调用 Kubernetes API 创建 Secret 资源，并添加 Secret 资源名称到该命名空间下 ServiceAccount 资源的 imagePullSecrets 字段中。示例如下：

# 查看 newns 下自动部署的 Secret$ kubectl get secrets -n newnsNAME TYPE DATA AGEtcr.ips.tcr-oidc-sample kubernetes.io/dockerconfigjson 1 7m2s# 查看 dockerconfigjson 中包含的镜像仓库域名$ kubectl get secret tcr.ips.tcr-oidc-sample -n newns \\ -o jsonpath='{.data.\\.dockerconfigjson}' | base64 -d | jq '.auths | keys'[ "your-tcr-registry.tencentcloudcr.com", "your-tcr-registry-vpc.tencentcloudcr.com", "docker.mycompany.com"]# 查看 newns 下自动关联到 ServiceAccount 资源 default 中的 Secret$ kubectl get serviceaccounts default -o yaml -n newnsapiVersion: v1imagePullSecrets:- name: tcr.ips.tcr-oidc-samplekind: ServiceAccountmetadata: name: default namespace: newns

21、ServiceAccount 变更

tcr-assistant-oidc 在观察到有新的 Kubernetes ServiceAccount 资源创建后，会首先校验名称是否与 OIDCImagePullSecret 资源中的 serviceAccounts 字段匹配。如果资源名称不匹配，跳过后续流程；若资源名称匹配，则会调用 Kubernetes API 创建或更新 Secret 资源，并添加 Secret 资源名称到 ServiceAccount 资源的 imagePullSecrets 字段当中。示例如下：

# 在 newns 新建 ServiceAccount 资源$ kubectl create sa kung -n newnsserviceaccount/kung created# 查看 newns 下自动关联到新建 ServiceAccount 资源 kung 中的 Secret$ kubectl get serviceaccounts kung -o yaml -n newnsapiVersion: v1imagePullSecrets:- name: tcr.ips.tcr-oidc-samplekind: ServiceAccountmetadata: name: kung namespace: newns

22、凭证轮转

Controller 内部 Reconciler 按 tokenExpiration 周期性触发。每次轮转会重新调用 STS AssumeRoleWithWebIdentity 获取新的临时凭证，并更新已分发的 Secret 内容。已运行的 Pod 无需重启，下一次镜像拉取即使用新凭证；升级 Controller 版本时，已生成的 Secret 不会中断，Controller 重启后自动恢复 reconcile。

23、Pod 创建准入兜底

新建 Namespace / Pod 时，Controller 可能尚未完成 Secret 创建与 SA 注入。组件通过 Pod Mutating Webhook 拦截 Pod Create 请求：检查目标 SA 是否已挂载 ImagePullSecret，未就绪时按 CheckIntervalMs 主动等待重试，避免 Pod 因时序问题拉取失败。

24、使用场景与操作指引

tcr-assistant-oidc 支持同账号与跨账号两种免密拉取场景，两种场景的 CAM 配置流程差异较大。具体安装步骤（包括开启 TKE OIDC、创建 CAM OIDC 身份提供商 / 策略 / 角色、打通 VPC 网络、通过控制台 / 云 API / Terraform 安装插件、验证与故障排查等）请参考对应场景的实操文档：

注意：说明：