This topic describes how to use the aliyun-acr-credential-helper component provided by Alibaba Cloud Container Registry (ACR) to pull images without a password.

Prerequisites

Create an ACK cluster

Notice
  • If you want to use the component, do not manually specify the imagePullSecret parameter. If the imagePullSecret parameter is specified in the template of a Kubernetes resource (such as a Deployment), the component becomes invalid.
  • If a Kubernetes resource (such as a deployment) uses custom service accounts, you must modify the service-account field in the configuration file of the component. Then, the component is authorized to pull images with the custom service accounts.

Background information

  • Supported images
    • You can use the component to pull private images from instances of Container Registry Enterprise Edition and default instances.
    • You can use the component to pull private images from your ACR instances or private images from other Resource Access Management (RAM) users after authorization.
    • You can use the component to pull private images from ACR instances deployed in different regions.
  • Supported clusters
    • You can use the component to pull images from clusters that contain multiple namespaces without a password.
    • Supported cluster types
      • Dedicated Alibaba Cloud Container Service for Kubernetes (ACK) clusters.
      • Managed ACK clusters.
      • Serverless Kubernetes (ASK) clusters.
    • Supported cluster versions
      • Dedicated ACK clusters: The Kubernetes version must be V1.11.2 or later. If your Kubernetes version is earlier than V1.11.2, you must manually upgrade to V1.11.2 or later. For more information, see Upgrade a cluster.
      • Managed ACK clusters: All versions.
      • ASK clusters: All versions.

Upgrade and configure the component.

  1. Upgrade the component.
    1. Log on to the Container Service console.
    2. In the left-side navigation pane, choose Clusters > Clusters. Find the target cluster, and choose More > Manage System Components in the Actions column.
    3. In the System Components section, find the aliyun-acr-credential-helper component and click Upgrade.
  2. Configure the component.
    1. In the left-side navigation pane, choose Configuration > ConfigMaps.
    2. Select the target cluster, and select kube-system from the Namespace drop-down list. In the ConfigMap list, find and click acr-configuration. If this ConfigMap is not found in the list, you must create one.The acr-configuration ConfigMap

      The following example shows how to configure acr-configuration.

      • Instances of Container Registry Enterprise Edition:
        acr-registry-info: |
             - instanceId: cri-xxx
               regionId: cn-hangzhou
               domains: xxx.com,yyy.com
           watch-namespace: "all"
           service-account: "default"
           expiring-threshold: "15m"
      • Default instances:
        acr-registry-info: 
           watch-namespace: "all"
           service-account: "default"
           expiring-threshold: "15m"
      Parameter Description Default value
      service-account This parameter specifies the service accounts that are used by the component to pull images. The default value is default.
      Note Separate multiple service accounts with commas (,). Enter an asterisk (*) to specify all service accounts in the specified namespace.
      acr-registry-info This parameter specifies the information about ACR instances. Each instance can be specified by three string type fields in a YAML file.
      Note The string type fields are as follows:
      • instanceId: the ID of the ACR instance. This field is required for instances of Container Registry Enterprise Edition.
      • regionId: the ID of the region where the ACR instance is deployed. This field is optional. The default value is the region where the target cluster is deployed.
      • domains: the domains of the ACR instance. This field is optional. By default, all domains of the instances are specified. Separate multiple domains with commas (,).
      By default, this parameter is not specified. This means that images are pulled from the default repository of the ACR instance deployed in the region where the target cluster is deployed.
      watch-namespace This parameter specifies the namespaces from which the images are pulled. The default value is default.
      Note Set the value to all to pull images from all namespaces without a password. Separate multiple namespaces with commas (,).
      expiring-threshold The validity period of the local cache token. The default is 15 minutes. We recommend that you use the default value.

Scenario 1: Pull images across accounts

In this scenario, an ACK cluster of Account A is used to pull private images from Account B.

Note
Follow the rules when you pull images across accounts:
  1. The RAM role of Account B is authorized to pull private images from a specified private repository. This rule requires you to grant all ACR-related permissions to the RAM role of Account B.
  2. Account B allows the worker role of the target ACK cluster created by Account A to assume the RAM role of Account B. This rule requires you to modify the trust policy of the RAM role of Account B
  3. The worker role of the target ACK cluster created by Account A has the permission to assume the RAM role of Account B. This rule requires you to attach the AliyunAssumeRoleAccess policy to the worker role of Account A.
  4. Set the worker role of Account A to assume the RAM role of Account B. This rule requires you to add and specify the assumeRoleARN field in the acr-configuration ConfigMap.
  1. Create a RAM role of Account B. Specify Alibaba Cloud Account as the trusted entity of the RAM role. Make sure that the created RAM role has the permission to pull private images from Account B. In the RAM console, click RAM Roles, and then click Create RAM Role.
    Note This RAM is granted the ACR-related permissions.The RAM role is granted the ACR-related permissions
  2. Enter the Alibaba Cloud Resource Name (ARN) of the worker role into the Principal field of the trust policy. This allows the worker role of Account A to assume the RAM role of Account B.RamRoleARN
  3. Check whether the worker role of Account A has the AssumeRole permission.AssumeRole permission
  4. Add the assumeRoleARN field to the configuration file of the component and set the value to the ARN of the RAM role of Account B. Example:
    data:   
        service-account: "default"
        watch-namespace: "all"
        expiring-threshold: "15m"
        notify-email: "cs@aliyuncs.com"
        acr-registry-info: |
        - instanceId: ""
           regionId: cn-beijing
           domains: registry.cn-beijing.aliyuncs.com
           assumeRoleARN: acs:ram::.*:role/kubernetesworkerrole-test

Scenario 2: Fail to pull images without a password

If this error occurs, you must check whether the current account has the permission to pull images from ACR instances.

  1. Log on to the ACK console. In the left-side navigation pane, choose Clusters > Clusters. Find the target cluster and click the cluster name.
  2. In the Cluster Resources section, click the RAM role on the right side of Worker RAM Role.WorkRam
  3. You are then redirected to the RAM console. On the RAM page, click the policy name in the Policy column.Click the policy name
  4. Click Modify Policy Document.
  5. On the Policy Document tab, add the following content and click OK.
    {
      "Action": [
        "cr:Get*",
        "cr:List*",
        "cr:PullRepository"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  6. The following figure shows where the content is added.
    Example
Note You also need to check whether the image specified in the pod exists in the ACR repository.
  • If the image exists in the ACR repository but is not found on the ACR instances created by the current account, you need to pull the image across accounts. This is similar to scenario 1.
  • If the image is not found on the ACR instances created by the current account, .
  • If the image is not found in the ACR repository, you need to check whether the image can be found on Alibaba Cloud Container Registry. If the image is found on Alibaba Cloud Container Registry, you need to synchronize the external image to Alibaba Cloud Container Registry, or change the image status so that the image can be pulled over the Internet.

Scenario 3: Pull images across regions

If you want to pull images from ACR instances that are deployed in different regions, you must modify acr-configuration.

For example, if you want to pull images from ACR instances deployed in the China (Beijing) and China (Hangzhou) regions at the same time, modify acr-configuration as follows:

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