tencent cloud

Tencent Kubernetes Engine

DokumentasiTencent Kubernetes EngineApplication ConfigurationComponent and Application Management Add-On Managementtcr-assistant-oidc Descriptiontcr-assistant-oidc Introduction

tcr-assistant-oidc Introduction

Download
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-08-14 15:18:29
Diterjemahkan oleh AI

Introduction

Component Description

The tcr-assistant-oidc plugin (TCR dynamic password-free image pull plugin) is an official component for dynamic password-free container image pulling based on OIDC authentication released by TCR. After you install this component in a TKE cluster, the cluster can automatically and dynamically generate and rotate temporary access credentials for TCR Enterprise Edition instances. This allows workloads to pull images from TCR Enterprise Edition instances under your own or other accounts without explicitly configuring ImagePullSecrets in cluster resource YAML files. The plugin also supports configuring custom domains.
Compared to the original tcr-assistant plugin, tcr-assistant-oidc offers the following enhanced capabilities:
Capability
tcr-assistant
tcr-assistant-oidc
Credential type
Static long-term credentials (username + password)
Dynamic temporary keys, automatically rotated
Cross-account pull
Only supports pulling from the same account.
Supports pulling from the same account and across accounts
Security
Long-term key exposure risk
Temporary keys are rotated periodically and automatically expire.

Kubernetes Objects Deployed in a Cluster

Term
Type
Resource Capacity
Namespace
tcr-assistant-system
Namespace
1
-
tcr-assistant-oidc-manager-role
ClusterRole
1
-
tcr-assistant-oidc-manager-rolebinding
ClusterRoleBinding
1
-
tcr-assistant-oidc-leader-election-role
Role
1
tcr-assistant-system
tcr-assistant-oidc-leader-election-rolebinding
RoleBinding
1
tcr-assistant-system
tcr-assistant-oidc-controller-manager
ServiceAccount
1
tcr-assistant-system
tcr-assistant-oidc-webhook-server-cert
Secret
1
tcr-assistant-system
tcr-assistant-oidc-webhook-service
Service
1
tcr-assistant-system
tcr-assistant-oidc-mutating-webhook-configuration
MutatingWebhookConfiguration
1
-
oidcimagepullsecrets.tcr.tencentcloudcr.com
CustomResourceDefinition
1
-
tcr-oidc-*
OIDCImagePullSecret CRD
(1-N)
tcr-assistant-system
tcr.ips.*
Secret
(1-N)*{Namespace No.}
Target Namespace
tcr-assistant-oidc-controller-manager
Deployment
1
tcr-assistant-system

Component Resource Usage

Component
Resource Usage
Number of instances
tcr-assistant-oidc-controller-manager
CPU:600m
memory:512Mi
2 (multi-replica high availability)

Scenarios

Pulling Images Without a Password

To pull private images, a Kubernetes cluster requires you to create a Secret resource for access credentials, configure the ImagePullSecret property in the resource YAML, and explicitly specify the created Secret. This overall configuration process is cumbersome and can lead to image pull failures if ImagePullSecret is not configured or an incorrect Secret is specified.
To address the issues above, you can install the tcr-assistant-oidc component in your cluster. Based on OIDC authentication, the component dynamically generates temporary access credentials for specified TCR Enterprise Edition instances. It then delivers these credentials to a specified namespace in the TKE cluster according to your configuration and automatically associates them with the imagePullSecrets field of the target ServiceAccount. When you create or update resources using YAML, you do not need to explicitly configure ImagePullSecret. The cluster will automatically use the delivered dynamic credentials to pull images.

Cross-Account Image Pulling

A cluster administrator can configure the CAM OIDC identity provider and role trust policy to allow Account B (the account where the TKE cluster resides) to assume the CAM role of Account A (the account where the TCR instance resides). This enables password-free pulling of images from the TCR Enterprise Edition instance in Account A without the need to synchronize long-term credentials between the two accounts. The same account can also use this component for dynamic credential updates.

Pulling Images Using a Custom Domain

If a custom domain (for example, docker.mycompany.com) is bound to a TCR Enterprise Edition instance, the component can write the custom domain into the generated dockerconfigjson. This allows workloads to pull images directly via the custom domain.

Dynamic Credential Rotation

The component accesses TCR using temporary credentials (with a fixed validity period of 2 hours) obtained via the STS AssumeRoleWithWebIdentity API. Internally, the Controller periodically triggers credential rotation based on tokenExpiration to mitigate the risk of long-term credential exposure.

Limits

Basic Environment Requirements:
Only TKE clusters with Kubernetes version 1.20 or later are supported. (Kubernetes 1.20 upgraded the ServiceAccountIssuerDiscovery feature to General Availability.)
The target TKE cluster must have the OIDC feature enabled, and the pod-identity-webhook component must be installed successfully.
You have activated TCR and completed service authorization, and have created an Enterprise Edition instance (in the "Running" state).
For Password-Free Image Pull Scenarios:
Users need to configure corresponding custom policies (including tcr:DescribeInstances, tcr:PullRepository, and so on) in CAM and grant them to the appropriate roles. It is recommended that users with TCR administrator and CAM administrator permissions complete the component initialization configuration.
After the component is installed and becomes effective, avoid repeatedly specifying ImagePullSecret in your resource YAML. This prevents image pull failures caused by nodes using incorrect image pull access credentials.
The matching rules for namespaces and serviceAccounts do not support wildcard expressions. You must explicitly specify the resource names or use * to indicate all.
It is recommended to set the Secret rotation interval tokenExpiration between 3600 and 5400 seconds. This prevents the temporary credentials (with a validity period of 7200 seconds) from expiring before they are rotated in a timely manner.
For Cross-Account Image Pull Scenarios:
The VPC of the TKE cluster in Account B and the VPC of the TCR instance in Account A must be interconnected via Peering Connection/CCN. Additionally, the Private DNS resolution for the TCR instance must be configured.
Account A must be registered in the CAM OIDC identity provider with the OIDC Issuer and JWKS of the TKE cluster in Account B.

Component Permission Description

Note:
The Permission Scenarios section only lists the permissions related to the component's core features. For the complete permission list, see the Permission Definitions section.

Permission Description

The permissions for this component represent the minimum set of permissions required for the current feature implementation.

Permission Scenarios

Function
Object Involved
Operation Permission Involved
Requires the feature of password-free image pulling, which proactively manages image pull credentials (secret) for customers.
Secret
watch,create,update,patch,delete
Performs leader election by creating and updating ConfigMaps/Leases to ensure high availability of components.
ConfigMap,Lease
get,list,watch,create,update,patch,delete
Monitors the creation and update of namespaces and automatically injects image pull credentials when needed.
Namespace
get,list,watch
Query and update service accounts.
ServiceAccount
get,list,watch,patch,update
Manages custom resources (CRD) to achieve dynamic orchestration of credentials.
OIDCImagePullSecret
get,list,watch,create,update,patch,delete
Admission fallback during Pod creation, checking and injecting ImagePullSecrets.
Pod (Admission)
Intercept CREATE events with MutatingWebhook

Permission Definition

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: tcr-assistant-oidc-leader-election-role
  namespace: tcr-assistant-system
rules:
  - 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/v1
kind: ClusterRole
metadata:
  name: tcr-assistant-oidc-manager-role
rules:
  - 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"]

Principles

Overview

tcr-assistant-oidc helps users automatically and dynamically deploy Kubernetes imagePullSecrets to any Namespace based on OIDC identity and associate them with the ServiceAccount in that namespace. When a user-created workload does not explicitly specify an imagePullSecret or a serviceAccount, Kubernetes attempts to find and match a suitable imagePullSecret from the ServiceAccount resource named default in the current namespace.
Unlike traditional solutions, the Secret content in this component is dynamically generated by STS temporary credentials and periodically rotated based on tokenExpiration. This approach mitigates the risk of long-term credential exposure.

Glossary

Name
Alias
Description
OIDCImagePullSecret
oips
A CRD defined by tcr-assistant-oidc, which declares credential sources (roleArn / registries) and distribution rules (namespaces / serviceAccounts / customDomains).
OIDC Token
-
A JWT injected into the Controller Pod by pod-identity-webhook, issued by the TKE cluster API Server, and used as a credential for cross-account identity trust.
STS AssumeRoleWithWebIdentity
-
A Tencent Cloud STS API that exchanges an OIDC Token for temporary SecretId / SecretKey / Token of a specified role.
Account A / Account B
-
Account A: the account where the TCR instance resides (image provider); Account B: the account where the TKE cluster resides (image consumer). In a same-account scenario, A = B.

How It Works

As a typical Kubernetes Operator, tcr-assistant-oidc creates a CRD object in the target Kubernetes cluster upon deployment: oidcimagepullsecrets.tcr.tencentcloudcr.com. This CRD has a kind of OIDCImagePullSecret, a version of tcr.tencentcloudcr.com/v1, and an abbreviation of oips.
tcr-assistant-oidc continuously watches the Namespace and ServiceAccount resources in the Kubernetes cluster. When these resources change, it checks whether the changes match the rules defined in OIDCImagePullSecret to automatically deploy the Secret resources required for pulling images from private image repositories. The program is deployed within the Kubernetes cluster and accesses the Kubernetes master API using the in-cluster mode. It also relies on the TKE official pod-identity-webhook to inject OIDC Tokens into the Controller Pod and obtains dynamic temporary credentials through Tencent Cloud STS.

Creating a CRD Resource

You must complete the following CAM configuration in the account where the TCR instance resides:
1. Create an OIDC identity provider in the CAM Console - Identity Provider and register the OIDC Issuer and JWKS of the TKE cluster.
2. Create a custom policy in the CAM Console - Policies to grant the minimum permissions, such as tcr:DescribeInstances and tcr:PullRepository.
3. Create a role in the CAM Console - Roles, bind the trust policy to the OIDC identity provider, associate the aforementioned custom policy, and record the role ARN.
Note:
roleArn: The CAM role ARN for Account A obtained from the console, in the format qcs::cam::uin/{UIN}:roleName/{ROLE_NAME}. The Controller uses it to call STS and obtain temporary credentials.
registries: The TCR instance name (excluding the domain suffix). The component automatically assembles the public network, VPC, and custom domain endpoints based on it.
Domain (server): Dynamically generated, it includes {registry}.tencentcloudcr.com, {registry}-vpc.tencentcloudcr.com, and the user-configured customDomains.
After the component is deployed, the corresponding OIDCImagePullSecret resource is automatically created. You can also create it manually using kubectl or Client Go:
# Create an OIDCImagePullSecret resource
$ kubectl create -f oidcimagepullsecret-sample.yaml

oidcimagepullsecret.tcr.tencentcloudcr.com/tcr-oidc-sample created
OIDCImagePullSecret resource sample file:
apiVersion: tcr.tencentcloudcr.com/v1
kind: OIDCImagePullSecret
metadata:
  name: tcr-oidc-sample
spec:
  namespaces: "*"
  serviceAccounts: "*"
  roleArn: "qcs::cam::uin/100001113387:roleName/tcr-cross-account-role"
  registries:
    - "your-tcr-registry"
  customDomains:
    - "docker.mycompany.com"
  tokenExpiration: 3600
The OIDCImagePullSecret spec fields are explained in the following table:
Field
Function
Annotation
namespaces
Namespace matching rule
* or an empty string indicates matching any Namespace. Separate multiple namespaces with ,.Note: Expressions are not supported. Specify the exact resource name.
serviceAccounts
ServiceAccount matching rule
* or an empty string indicates matching any ServiceAccount. Separate multiple ServiceAccounts with ,.Note: Expressions are not supported. Specify the exact resource name.
roleArn
CAM role ARN for Account A
Used for STS AssumeRoleWithWebIdentity. Format: qcs::cam::uin/{UIN}:roleName/{ROLE_NAME}.
registries
List of TCR instance names
Enter only the instance name, without the domain suffix. The component automatically combines the public network/VPC domain.
customDomains
List of custom domain names for TCR instances
Optional. Used for custom domain pull scenarios. It is additionally written into the auths of dockerconfigjson.
tokenExpiration
Secret rotation interval (seconds)
Recommended range: 3600~5400. Default: 3600. Must not exceed the validity period of STS temporary credentials (7200s).
After creation is complete, you can observe the execution results of tcr-assistant-oidc using the following commands:
# List OIDCImagePullSecret information
$ kubectl get oips
NAME               NAMESPACES   SERVICE-ACCOUNTS   REGISTRIES              CREDENTIAL-STATUS
tcr-oidc-sample    *            *                  [your-tcr-registry]     Ready

# View detailed information
$ kubectl describe oips tcr-oidc-sample
Name:         tcr-oidc-sample
Namespace:
API Version:  tcr.tencentcloudcr.com/v1
Kind:         OIDCImagePullSecret
Spec:
  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:  3600
Status:
  Credential Status:   Ready
  Last Refresh Time:   2026-08-05T10:00:00Z
  Next Refresh Time:   2026-08-05T11:00:00Z
  Secrets Desired:     10
  Secrets Success:     10
Events:                <none>
Attention:
To update the Secret resource deployed by tcr-assistant-oidc, you do not need to delete and recreate the OIDCImagePullSecret resource. After the fields such as spec.roleArn, spec.registries, and spec.customDomains are modified, the Controller automatically reconciles, and the Secret content is refreshed in the next rotation cycle.

Namespace Changes

After observing the creation of a new Kubernetes Namespace resource, tcr-assistant-oidc first checks whether its name matches the namespaces field in the OIDCImagePullSecret resource. If the resource name does not match, it skips the subsequent steps. If the resource name matches, it calls STS to obtain temporary credentials, renders the dockerconfigjson, calls the Kubernetes API to create a Secret resource, and adds the Secret resource name to the imagePullSecrets field of the ServiceAccount resource in that namespace. An example is provided below:
# View the automatically deployed Secret in the newns namespace
$ kubectl get secrets -n newns
NAME                     TYPE                             DATA   AGE
tcr.ips.tcr-oidc-sample  kubernetes.io/dockerconfigjson   1      7m2s

# View the container registry domains contained in the 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"
]

# View the Secret that is automatically associated with the default ServiceAccount resource in the newns namespace
$ kubectl get serviceaccounts default -o yaml -n newns
apiVersion: v1
imagePullSecrets:
- name: tcr.ips.tcr-oidc-sample
kind: ServiceAccount
metadata:
  name: default
  namespace: newns

ServiceAccount Changes

After observing the creation of a new Kubernetes ServiceAccount resource, tcr-assistant-oidc first checks whether its name matches the serviceAccounts field in the OIDCImagePullSecret resource. If the resource name does not match, it skips the subsequent steps. If the resource name matches, it calls the Kubernetes API to create or update a Secret resource and adds the Secret resource name to the imagePullSecrets field of the ServiceAccount resource. An example is provided below:
# Create a ServiceAccount resource in the newns namespace
$ kubectl create sa kung -n newns
serviceaccount/kung created

# View the Secret that is automatically associated with the newly created ServiceAccount resource named kung in the newns namespace
$ kubectl get serviceaccounts kung -o yaml -n newns
apiVersion: v1
imagePullSecrets:
- name: tcr.ips.tcr-oidc-sample
kind: ServiceAccount
metadata:
  name: kung
  namespace: newns

Credential Rotation

The Reconciler inside the Controller is triggered periodically based on tokenExpiration. During each rotation, it re-invokes the STS AssumeRoleWithWebIdentity API to obtain new temporary credentials and updates the content of the distributed Secret. Running Pods do not require a restart and will use the new credentials during the next image pull. When the Controller version is upgraded, existing Secrets remain uninterrupted, and the Controller automatically resumes reconciliation after restarting.

Pod Creation Admission Fallback

When a new Namespace / Pod is created, the Controller might not have completed the creation of the Secret and its injection into the ServiceAccount. The component intercepts Pod Create requests via the Pod Mutating Webhook: it checks whether the target ServiceAccount has the ImagePullSecret mounted. If it is not ready, the component actively waits and retries according to CheckIntervalMs to prevent Pods from failing to pull images due to timing issues.

Use Cases and Operation Guide

The tcr-assistant-oidc plugin supports two password-free image pull scenarios: within the same account and across accounts. The CAM configuration processes for these two scenarios differ significantly. For specific installation steps, including enabling TKE OIDC, creating CAM OIDC identity providers / policies / roles, establishing VPC network connectivity, installing the plugin via the console / TencentCloud API / Terraform, and verification and troubleshooting, see the hands-on documentation for the corresponding scenario:
Scenario
Prerequisite
Operation Document
Passwordless Pull Within the Same Account
The TKE cluster and the TCR Enterprise Edition instance belong to the same Tencent Cloud account.
Passwordless Pull Across Accounts
The TKE cluster and the TCR Enterprise Edition instance belong to different Tencent Cloud accounts.
Note:
The component parameters used in both scenarios (roleArn / registries / namespaces / serviceAccounts / customDomains / tokenExpiration) are completely identical. The only difference lies in the party responsible for configuring the OIDC identity provider and the role trust policy on the CAM side.
If you need to automate the installation of the tcr-assistant-oidc component via Terraform / TencentCloud API, Terraform examples and API invocation examples are included in the two operation documents mentioned above.

Topik sebelumnya: TCR DescriptionTopik selanjutnya: Configuring tcr-assistant-oidc for Same-Account Dynamic Password-Free Image Pull

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan