Use the aliyun-acr-credential-helper component to pull images without using a password - Container Service for Kubernetes

You can use the aliyun-acr-credential-helper component to pull private images without using a password from instances of Container Registry Personal Edition and Enterprise Edition to a self-managed Kubernetes cluster. This topic describes how to use aliyun-acr-credential-helper to pull a private image without using a password in two scenarios.

Prerequisites

A registered cluster is created and an external Kubernetes cluster is connected to the registered cluster. For more information, see Create a registered cluster in the ACK console and Use onectl to create a registered cluster.
A kubectl client is connected to the registered cluster. For more information, see Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster.

Usage notes

The aliyun-acr-credential-helper component reads the configuration from the acr-configuration ConfigMap in the kube-system namespace of an ACK cluster and then pulls private images. After you configure the aliyun-acr-credential-helper component, the component generates a Secret in your cluster and associates the Secret with the service account that you specified in the acr-configuration ConfigMap. By default, all pods that use this service account use the generated Secret to pull images without using a password.

Important

If you create a service account to deploy applications, such as Helm charts, the service account requires a period of time to be associated with the Secret that is generated by aliyun-acr-credential-helper. We recommend that you use the webhook feature to inject the Secret into the service account before you pull images.

The following table describes the limits on using the aliyun-acr-credential-helper component to pull private images without using a password.

Parameter	Description
Mirroring	You can pull private images from the Container Registry instances that belong to the current RAM user. You can also pull private images across accounts through authorization or by using the AccessKey pair of another RAM user. You can pull private images in scenarios in which you need to pull images from instances of Container Registry Enterprise Edition and Container Registry Personal Edition.
Cluster and Kubernetes version	The Kubernetes version of the cluster must be 1.11.2 or later. Otherwise, you must upgrade the Kubernetes version of the cluster. For more information, see Update an ACK cluster. You can pull images without using a password from multiple namespaces of a cluster.

Precautions

Item	Precaution
imagePullSecrets	If you specify imagePullSecret in the template of a Kubernetes resource, such as a Deployment, the aliyun-acr-credential-helper component becomes invalid. To use the component, do not specify imagePullSecret. By default, the configuration of the aliyun-acr-credential-helper component overwrites the imagePullSecrets parameter of the default service accounts in all namespaces. These service accounts are automatically modified when the service-account parameter of the acr-configuration ConfigMap in the kube-system namespace is modified.
ServiceAccount	If a Kubernetes resource, such as a Deployment, uses a custom service account, you must modify the service-account parameter in the configuration file of the aliyun-acr-credential-helper component. This way, the component is authorized to pull images by using the custom service account. After you create a service account in a cluster, check whether the value of the imagePullSecrets parameter contains a secret that starts with acr-credential. If yes, the service account is associated with the secret, and applications that use the service account can pull images by using the secret. Applications that use the service account may fail to pull images immediately after the service account is created due to authentication failures.
Region	Check whether the private images that you want to pull reside in the region of your ACK cluster. By default, you can pull private images only from Container Registry instances that reside in the region of your ACK cluster. If you want to pull images across regions, see Scenario 2: Pull images across regions.
YAML format	When you modify the acr-configuration ConfigMap in the kube-system namespace, make sure that you use the same indentation as the example in this topic. We recommend that you paste the YAML content provided in this topic to the editor, replace the corresponding values, and apply the configuration. This ensures that the format of the ConfigMap is valid.

Configure the aliyun-acr-credential-helper component in the self-managed cluster

Step 1: Grant RAM permissions to aliyun-acr-credential-helper

Use onectl

Install onectl on your on-premises machine. For more information, see Use onectl to manage registered clusters.

Run the following command to grant RAM permissions to aliyun-acr-credential-helper:

onectl ram-user grant --addon aliyun-acr-credential-helper

Expected output:

Ram policy ack-one-registered-cluster-policy-aliyun-acr-credential-helper granted to ram user ack-one-user-ce313528c3 successfully.

Use the Function Compute console

Before you can install the component in an external cluster, you must set the AccessKey pair to grant the external cluster the permissions to access Alibaba Cloud resources. Before you set the AccessKey pair, create a RAM user and grant the RAM user the permissions to access Alibaba Cloud resources.

Create a RAM user. For more information, see Create a RAM user.

Create a custom policy. For more information, see Create a custom policy.

Example:

{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "cr:GetAuthorizationToken",
                "cr:ListInstanceEndpoint",
                "cr:PullRepository"
            ],
            "Resource": [
                "*"
            ],
            "Effect": "Allow"
        }
    ]
}

Attach the custom policy to the RAM user. For more information, see Create a RAM user and grant permissions to the RAM user.
Create an AccessKey pair for the RAM user. For more information, see Obtain an AccessKey pair.
Use the AccessKey pair to create a Secret named alibaba-addon-secret in the registered cluster.
The system automatically uses the AccessKey pair to access cloud resources when you install the aliyun-acr-credential-helper component.
```
kubectl -n kube-system create secret generic alibaba-addon-secret --from-literal='access-key-id=<your access key id>' --from-literal='access-key-secret=<your access key secret>'
```
Note
Replace <your access key id> and <your access key secret> with the AccessKey pair that you obtained in the previous step.

Step 2: Update and configure aliyun-acr-credential-helper

You must install and configure aliyun-acr-credential-helper before you can use it to pull images without using a password.

Use onectl

Run the following command to install aliyun-acr-credential-helper:

onectl addon install aliyun-acr-credential-helper

Expected output:

Addon aliyun-acr-credential-helper, version **** installed.

If aliyun-acr-credential-helper is already installed, make sure that aliyun-acr-credential-helper is of the latest version. You can run the following command to update aliyun-acr-credential-helper to the latest version:

onectl addon upgrade aliyun-acr-credential-helper

Expected output:

Addon aliyun-acr-credential-helper upgraded to version ****.

Use the console

If you installed the aliyun-acr-credential-helper component, make sure that the component is the latest version. Otherwise, update the component. Updating the component does not negatively impact workloads. For more information, see Manage components. For more information about the aliyun-acr-credential-helper component, see aliyun-acr-credential-helper.

Important

After the aliyun-acr-credential-helper component is updated to the latest version, the RAM role on which the component relies is changed. The component provides the tokenMode parameter to allow you to specify the RAM role on which the component relies. For more information about the impacts of changing the RAM role on which the component relies, see [Product Changes] Revoke the permissions on which aliyun-acr-credential-helper relies.

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the name of the cluster that you want to manage and choose Operations > Add-ons in the left-side navigation pane.
On the Add-ons page, click the Security tab, find aliyun-acr-credential-helper, and then click Install.

On the Parameters page, use the default value auto for the tokenMode parameter and click OK.

After you update an ACK managed cluster to the latest version, the aliyun-acr-credential-helper component provides the tokenMode parameter. You can modify the parameter after the component is installed. After the component is modified, the system recreates the pod for the component. Old clusters described in the table refer to clusters that are created before April 3, 2023, and new clusters refer to clusters that are created on or after April 3, 2023. The following table describes the valid values of the tokenMode parameter.

tokenMode	Description
auto	The default value. The value specifies that the system automatically determines whether the cluster is a new or old cluster. New clusters use the managedRole mode. Old clusters use the workerRole mode.
managedRole	Use the managedRole mode.
workerRole	Use the workerRole mode.

After the aliyun-acr-credential-helper component is installed, you must configure the acr-configuration ConfigMap before you can pull images.

Use the ACK console

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the name of the cluster that you want to manage and choose Configurations > ConfigMaps in the left-side navigation pane.
In the upper part of the ConfigMap page, select kube-system from the Namespace drop-down list. Then, find the acr-configuration ConfigMap and configure the parameters.
If the acr-configuration ConfigMap does not exist, create a ConfigMap. For more information, see Create a ConfigMap. For information about how to update ConfigMaps, see Manage ConfigMaps.
- Click Edit in the Actions column to configure keys and values for the ConfigMap.
- Click Edit YAML in the Actions column to configure keys and values for the ConfigMap.

Use kubectl

Run the following command to go to the editing page of the acr-configuration ConfigMap:
```
kubectl edit cm acr-configuration -n kube-system
```
Configure the parameters of the acr-configuration ConfigMap based on your requirements.

The following table describes the keys and values of the acr-configuration ConfigMap.

Key	Description	Value
service-account	The service accounts that are used by aliyun-acr-credential-helper to pull images.	Default value: default. Note Separate multiple service accounts with commas (,). An asterisk (`*`) specifies all service accounts in all namespaces.
acr-registry-info	The information about Container Registry instances. Each instance can be specified by three parameters of the string type in a YAML file. Note Configure the parameters based on the following descriptions: instanceId: the ID of the Container Registry instance. You must configure this parameter if you pull images from Container Registry Enterprise Edition instances. regionId: the ID of the region where the Container Registry instance resides. This parameter is optional. The default value is the region where your ACK cluster resides. domains: the domain names of the Container Registry instance. This parameter is optional. By default, all domain names of the instance are specified. Separate multiple domain names with commas (,).	Sample configuration for a Container Registry Enterprise Edition instance: `- instanceId: <cri-instanceId> regionId: "cn-hangzhou" domains: "xxx.com,yyy.com"`
watch-namespace	The namespaces from which you want to pull images without using a secret.	Default value: default. A value of all specifies all namespaces in the Container Registry instance. Separate multiple namespaces with commas (,). Note We recommend that you set the values to your production namespaces. If you set the value to all or namespaces of the system components of the cluster, images in the namespaces may fail to be pulled.
expiring-threshold	The period of time after which the cached secret expires.	Default value: 15m. Note We recommended that you use the default value. The default value specifies that the secret is updated 15 minutes before the cached secret expires.

Scenario 1: Pull private images from Container Registry Enterprise Edition and Container Registry Personal Edition instances

ACK allows you to pull private images from Container Registry Enterprise Edition and Personal Edition at the same time, from Container Registry Enterprise Edition separately, or from Container Registry Personal Edition separately. Modify the acr-configuration ConfigMap based on your business requirements. For more information, see Configure a component. Example:

Enterprise Edition

apiVersion:v1
data:
acr-api-version:"2018-12-01"
acr-registry-info:|-
-instanceId:"cri-xxx"
 regionId:"cn-hangzhou"
expiring-threshold:15m
service-account:default
watch-namespace:all
kind:ConfigMap
metadata:
name:acr-configuration
  namespace:kube-system
selfLink:/api/v1/namespaces/kube-system/configmaps/acr-configuration

Personal Edition

apiVersion:v1
data:
acr-api-version:"2018-12-01"
acr-registry-info:|-
-instanceId:""
 regionId:"cn-hangzhou"
expiring-threshold:15m
service-account:default
watch-namespace:all
kind:ConfigMap
metadata:
name:acr-configuration
namespace:kube-system
selfLink:/api/v1/namespaces/kube-system/configmaps/acr-configuration

You can configure the acr-configuration ConfigMap by using one of the following methods:

Use the ACK console

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the name of the cluster that you want to manage and choose Configurations > ConfigMaps in the left-side navigation pane.
In the upper part of the ConfigMap page, select kube-system from the Namespace drop-down list. Then, find the acr-configuration ConfigMap and configure the parameters.
If the acr-configuration ConfigMap does not exist, create a ConfigMap. For more information, see Create a ConfigMap. For information about how to update ConfigMaps, see Manage ConfigMaps.
- Click Edit in the Actions column to configure keys and values for the ConfigMap.
- Click Edit YAML in the Actions column to configure keys and values for the ConfigMap.

Use kubectl

Run the following command to go to the editing page of the acr-configuration ConfigMap:
```
kubectl edit cm acr-configuration -n kube-system
```
Configure the parameters of the acr-configuration ConfigMap based on your requirements.

Scenario 2: Pull images across regions

If you want to pull images from Container Registry instances to a registered cluster and the Container Registry instances and the registered cluster are deployed in different regions, you must modify the acr-configuration ConfigMap.

For example, if you want to pull images from Container Registry instances that are deployed in the China (Beijing) and China (Hangzhou) regions at the same time, modify the acr-configuration ConfigMap based on the following code block. For more information, see Configure the component.

data:
    service-account: "default"
    watch-namespace: "all"
    expiring-threshold: "15m"
    notify-email: "cs@aliyuncs.com"
    acr-registry-info: |
      - instanceId: ""
        regionId: cn-beijing
      - instanceId: ""
        regionId: cn-hangzhou

You can configure the acr-configuration ConfigMap by using one of the following methods:

Use the ACK console

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the name of the cluster that you want to manage and choose Configurations > ConfigMaps in the left-side navigation pane.
In the upper part of the ConfigMap page, select kube-system from the Namespace drop-down list. Then, find the acr-configuration ConfigMap and configure the parameters.
If the acr-configuration ConfigMap does not exist, create a ConfigMap. For more information, see Create a ConfigMap. For information about how to update ConfigMaps, see Manage ConfigMaps.
- Click Edit in the Actions column to configure keys and values for the ConfigMap.
- Click Edit YAML in the Actions column to configure keys and values for the ConfigMap.

Use kubectl

Run the following command to go to the editing page of the acr-configuration ConfigMap:
```
kubectl edit cm acr-configuration -n kube-system
```
Configure the parameters of the acr-configuration ConfigMap based on your requirements.