TCR Addon is a plug-in provided by the Tencent Container Registry (TCR) service for private-network and Secret-free pulling of container images. After this plug-in is installed in a TKE cluster, cluster nodes can pull container images from Enterprise Edition instances over the private network, without the need for explicit configuration of ImagePullSecret in the cluster resource YAML file. This plug-in can accelerate image pulling in TKE clusters and simplify image configuration.
Note
The TKE cluster version must be v1.10.x or later. We recommend that you use this add-on in TKE v1.12.x or later.
The startup parameters of the Kubernetes controller manager component must contain authentication-kubeconfig and authorization-kubeconfig (enabled by default in TKE v.12.x).
Kubernetes objects deployed within a cluster
Name
Local Disk Types
Resource Amount
Namespace
tcr-assistant-system
Namespace
1
-
tcr-assistant-manager-role
ClusterRole
1
-
tcr-assistant-manager-rolebinding
ClusterRoleBinding
1
-
tcr-assistant-leader-election-role
Role
1
tcr-assistant-system
tcr-assistant-leader-election-rolebinding
RoleBinding
1
tcr-assistant-system
tcr-assistant-webhook-server-cert
Secret
1
tcr-assistant-system
tcr-assistant-webhook-service
Service
1
tcr-assistant-system
tcr-assistant-validating-webhook-configuration
ValidatingWebhookConfiguration
1
tcr-assistant-system
imagepullsecrets.tcr.tencentcloudcr.com
CustomResourceDefinition
1
tcr-assistant-system
tcr.ips*
ImagePullSecret CRD
(2-3)
tcr-assistant-system
tcr.ips*
Secret
(2-3)*{Namespace No.}
tcr-assistant-system
tcr-assistant-controller-manager
Deployment
1
tcr-assistant-system
updater-config
ConfigMap
1
tcr-assistant-system
hosts-updater
DaemonSet
{Node No.}
tcr-assistant-system
Component resource usage
Component
Resource Usage
Number of instances
tcr-assistant-controller-manager
CPU：100m memory：30Mi
1
hosts-updater
CPU：100m memory：100Mi
Number of worker nodes
Use Cases
Pulling images without a Secret
Pulling private images in a Kubernetes cluster requires creating an access credential Secret resource and configuring the ImagePullSecret attribute in the resource YAML file, explicitly specifying the created Secret. The overall configuration process can be cumbersome and may cause image pulling failures due to incorrect or missing ImagePullSecret configurations.
To address these issues, you can install the TCR add-on in the cluster. The add-on will automatically obtain the access credentials for the specified TCR Enterprise Edition instance and distribute them to the designated namespace within the TKE cluster. When creating or updating resources using YAML, there is no need to configure ImagePullSecret, as the cluster will automatically use the distributed access credentials to pull images from the TCR Enterprise Edition instance.
Pulling images over the private network
The component will automatically create a DaemonSet workload called host-updater, which updates the Host configuration of cluster nodes and resolves the associated instance domain name to the dedicated private IP of the established private network access link. Please note that this configuration is intended for testing scenarios only. It is recommended to use the automatic private network link resolution provided by TCR, or configure private domain resolution using the PrivateDNS product, or manage resolution using a self-built DNS service.
Limits
For use cases of secret-free image pulling:
Users must have the permission to obtain the access credential of the specified TCR Enterprise Edition instance, that is, the permission to call the CreateInstanceToken API. We recommend that users with TCR admin permissions configure this add-on.
After the add-on is installed and takes effect, do not repeatedly specify ImagePullSecret in the resource YAML file. Otherwise, nodes may use the incorrect image pull access credential, leading to pull failures.
How to Use
1. Select an associated instance: select an existing TCR Enterprise Edition instance under the current logged-in account and confirm that the current logged-in user has the permission to create a long-term access credential for the instance. If you need to create a new Enterprise Edition instance, create it in the region where the current cluster is located.
2. Configure Secret-free Pulling (enabled by default): You can choose to automatically distribute the current user's access credentials or specify a username and password. You can also optionally configure the namespaces and ServiceAccounts for which Secret-free Pulling is enabled. We recommend using the default settings to avoid issues with this feature when new namespaces are created.
3. Configure Private Network Parsing (Advanced Feature): Ensure that the cluster and associated TCR instance have established a private network access link and enabled the private network parsing function. Please note that this configuration is for testing scenarios only. It is recommended to use the automatic private network link parsing provided by TCR, or directly use the PrivateDNS product for private domain parsing configuration, or manage parsing using a self-built DNS service.
4. After the TCR add-on is created, if you need to modify its configuration, delete the add-on and reconfigure and reinstall it.
Note
Deleting the add-on will not automatically delete the dedicated access credentials created. You can manually disable or delete them in the Tencent Container Registry console.
How It Works
Overview
TCR Assistant is designed to help users automatically deploy k8s imagePullSecret to any Namespace and associate it with the ServiceAccount in that namespace. When a user-created workload does not explicitly specify an imagePullSecret and a serviceAccount, k8s will attempt to find and match the appropriate imagePullSecret from the ServiceAccount resource named default in the current namespace.
Glossary
Name
Alias
Description
ImagePullSecret
ips, ipss
The CRD defined by TCR Assistant. It’s used to store the username and password of the image repository, and issue the target Namespace and ServiceAccount.
How to Implement
TCR Assistant is a typical Kubernetes Operator. When deploying TCR Assistant, we create a Custom Resource Definition (CRD) object in the target Kubernetes cluster: imagepullsecrets.tcr.tencentcloudcr.com. The kind of this CRD is ImagePullSecret, the version is tcr.tencentcloudcr.com/v1, and the abbreviation is ips or ipss.
TCR Assistant continuously observes (watches) the k8s cluster's Namespace and ServiceAccount resources. When these resources change, it checks whether the resource changes match the rules set in ImagePullSecret to automatically deploy the Secret resources needed to pull private image repositories. The program is typically deployed within the k8s cluster and accesses the k8s master API using the in-cluster mode.
Creating CRD resources
When TCR Assistant is deployed, the Secret used to pull TCR image is not deployed in the target K8s cluster. You need to create ImagePullSecret using kubectl or Client Go.
The explanation of the ImagePullSecret spec fields is as follows:
Parameter
Effect
Remarks
namespaces
NameSpace matching rule
* or an empty character represents a match for any value; to match multiple NameSpaces, use , to separate resource names. Note: Expressions are not supported; you must explicitly specify the resource names.
serviceAccounts
serviceAccounts matching rule
* or an empty character represents a match for any value. To match multiple ServiceAccounts, use a , to separate resource names. Note: Expressions are not supported; you must explicitly specify the resource names.
docker.server
Image repository domain name
Please enter only the repository domain name
docker.username
Image repository username
Make sure the user has all the required permissions
docker.password
Password of the image repository username
-
After the creation, you can run the following command to check execution result of TCR Assistant:
# List ImagePullSecret information
$ kubectl get ipss
NAME NAMESPACES SERVICE-ACCOUNTS SECRETS-DESIRED SECRETS-SUCCESS
To update the Secret resource deployed by TCR Assistant, there is no need to delete and recreate the ImagePullSecret resource. Simply edit the docker.username and docker.password fields to take effect. For example:
$ kubectl edit ipss imagepullsecret-sample
Namespace updates
Upon detecting the creation of a new k8s Namespace resource, the TCR Assistant will first check if the name matches the ImagePullSecret resource's namespaces field. If the resource name does not match, the subsequent process is skipped. If the resource name matches, the k8s API will be called to create a Secret resource and add the Secret resource name to the ServiceAccount resource's imagePullSecrets field. An example is shown below:
# View the automatically deployed Secret in the newns namespace
# View the Secret automatically associated with the ServiceAccount resource "default" in the "newns" namespace
$ kubectl get serviceaccounts default -o yaml -n newns
apiVersion: v1
imagePullSecrets:
- name: tcr.ipsimagepullsecret-sample
kind: ServiceAccount
metadata:
creationTimestamp: "2021-12-01T07:09:56Z"
name: default
namespace: newns
resourceVersion: "30392461"
uid: 7bc67144-3685-4666-ba41-b1447bbbaa38
secrets:
- name: default-token-nb5vw
ServiceAccount updates
Upon detecting the creation of a new k8s ServiceAccount resource, the TCR Assistant will first check if the name matches the ImagePullSecret resource's serviceAccounts field. If the resource name does not match, the subsequent process is skipped. If the resource name matches, the TCR Assistant will call the k8s API to create or update the Secret resource and add the Secret resource name to the ServiceAccount resource's imagePullSecrets field. An example is shown below:
# Create a ServiceAccount resource in the newns namespace
$ kubectl create sa kung -n newns
serviceaccount/kung created
# View the Secret automatically associated with the newly created ServiceAccount resource named "kung" in the "newns" namespace.
$ kubectl get serviceaccounts kung -o yaml -n newns
