All Products
Search
Document Center

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

Last Updated:Aug 14, 2023

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

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.

Item

Description

Image

  • You can pull private images from the Container Registry instances that belong to the current Resource Access Management (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 from instances of Container Registry Enterprise Edition and Container Registry Personal Edition.

Cluster and Kubernetes version

  • The cluster must run Kubernetes 1.11.2 or later. 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 set 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 set 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 with 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

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

  2. 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.

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

  2. 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"
            }
        ]
    }
  3. Attach the custom policy to the RAM user. For more information, see Create a RAM user and grant permissions to the RAM user.

  4. Create an AccessKey pair for the RAM user. For more information, see Obtain an AccessKey pair.

  5. 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 updated to 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 impact of changing the RAM role on which the component relies, see [Product Changes] Revoke the permissions on which aliyun-acr-credential-helper relies.

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 impact of changing the RAM role on which the component relies, see [Product Changes] Revoke the permissions on which aliyun-acr-credential-helper relies.

  1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

  2. 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.

  3. On the Add-ons page, click the Security tab, find aliyun-acr-credential-helper, and then click Install.

  4. 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. 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 (,). Enter an asterisk (*) to specify 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 (,).

    This parameter is left empty by default. This specifies that images are pulled from a Container Registry Personal Edition instance in the same region as the cluster without using a password. Leave the parameter empty when you need to pull images from instances of Personal Edition and Enterprise Edition.

    Sample configurations 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 password.

    Default value: default. If the value is set to all, images can be pulled from all namespaces without using a password. 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 kubectl

  1. Run the following command to go to the editing page of the acr-configuration ConfigMap:

    kubectl edit cm acr-configuration -n kube-system
  2. Configure the parameters of the acr-configuration ConfigMap based on your requirements.

Use the ACK console

  1. Log on to the ACK console and click Clusters in the left-side navigation pane.

  2. 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.

  3. In the upper part of the ConfigMap page, select kube-system from the Namespace drop-down list. Then, find acr-configuration and configure the parameters.

    If the acr-configuration ConfigMap does not exist, 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.

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 kubectl

  1. Run the following command to go to the editing page of the acr-configuration ConfigMap:

    kubectl edit cm acr-configuration -n kube-system
  2. Configure the parameters of the acr-configuration ConfigMap based on your requirements.

Use the ACK console

  1. Log on to the ACK console and click Clusters in the left-side navigation pane.

  2. 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.

  3. In the upper part of the ConfigMap page, select kube-system from the Namespace drop-down list. Then, find acr-configuration and configure the parameters.

    If the acr-configuration ConfigMap does not exist, 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.