Alibaba Cloud Container Registry (ACR) provides the aliyun-acr-credential-helper component for you to pull private images without a password from instances of Container Registry Enterprise Edition and default instances. This component is automatically installed in Alibaba Cloud Container Service for Kubernetes (ACK) clusters. This topic describes how to use the aliyun-acr-credential-helper component to pull a private image in different scenarios.

Prerequisites

Create a managed ACK cluster
Notice
  • If you want to use the aliyun-acr-credential-helper 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.
  • Check whether the private image that you want to pull is in the region where the target ACK cluster is deployed. By default, you can pull private images from only ACR instances that are deployed in the region where the target cluster is deployed. If you need to pull images from ACR instances that are deployed in different regions, refer to Scenario 3 in this topic.
  • If you want to assume a custom Resource Access Management (RAM) role to pull private images, you must specify the AccessKey ID and AccessKey secret of the RAM role in the acr-configuration ConfigMap. However, this may disclose the AccessKey information. To ensure data security, make sure that the RAM role is granted only the permissions to pull images.

Background information

aliyun-acr-credential-helper reads the required information from the acr-configuration ConfigMap created in the kube-system namespace and then pulls private images. You can pull private images in the following ways:
  • Assume the worker role of an ACK cluster to pull images from ACR instances that are created under your account.
  • Use the AccessKey ID and AccessKey secret of a custom RAM role to pull private images from ACR instances that are created under your account.
  • Use AssumeRole to assume the RAM role of another account to pull images from that account.

aliyun-acr-credential-helper supports the following images and clusters:

  • 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 pull private images from other accounts after authorization or by using the AccessKey ID and AccessKey secret.
    • 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 without a password from clusters that contain multiple namespaces.
    • Supported cluster types:
      • Dedicated 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.

Before you use the aliyun-acr-credential-helper component to pull images, you must perform the following steps.

  1. Upgrade the component.
    1. Log on to the .
    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 the ConfigMap is not found in the list, Create a ConfigMap. To update configuration items, see Modify a Config Map.

      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 Set the three fields based on the following descriptions:
      • 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 is the region where the target cluster is deployed.
      • domains: the domain names of the ACR instance. This field is optional. By default, all domain names of the instances are specified. Separate multiple domain names 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 The namespaces to which the images to be pulled belong. The default value is default.
      Note If the value is set to all, images are pulled from all namespaces without a password. Separate multiple namespaces with commas (,).
      expiring-threshold The validity period of the local cache token. The default value is 15m (15 minutes). We recommend that you use the default value.

Scenario 1: Pull images across accounts

In this scenario, you can pull images across accounts in the following ways:
  • Pull images across accounts by role assuming: Account A assumes the RAM role of Account B to pull private images from Account B
  • Pull images across accounts by using the AccessKey information of other accounts: The RAM role of the used account must have the permissions to pull images.

Pull images across accounts by RAM role assuming

Note
Follow these 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 permissions to assume the RAM role of Account B. This rule requires you to attach the AliyunAssumeRoleAccess permission 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 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 permissions to pull private images from Account B.
    1. Create a RAM role.
    2. Customize the permissions of the created RAM role and make sure that the created RAM role has the permissions to pull private images from Account B
      For more information, see Modify a custom policy.
      Notice Make sure that you have granted all ACR-related permissions to the RAM role of Account B.
      ```
      
      {
      "Action": [
       "cr:GetAuthorizationToken",
       "cr:ListInstanceEndpoint"
       "cr:PullRepository"
      ],
      "Resource": [
      "*"
      ],
      "Effect": "Allow"
      }
      
      ```
      The following figure shows where the content is added.The RAM role is granted the ACR-related permissions
  2. Modify the trust policy of the RAM role of Account B. This way, Account B allows the worker role of the target ACK cluster created by Account A to assume the RAM role of Account B. This requires you to enter the Alibaba Cloud Resource Name (ARN) of the worker role into the Principal field of the trust policy.
    1. Obtain the ARN of the worker role of the target ACK cluster created by Account A.
      For more information, see How do I find the ARN of a RAM role?.
    2. Modify the trust policy of the RAM role of Account B.
      1. Go to the RAM console. In the left-side navigation pane, choose RAM Roles. On the RAM roles page, find and click the target RAM role.
      2. On the details page of the target RAM role, click the Trust Policy Management tab, and enter the ARN of the worker role into the Principal field of the trust policy.RamRoleARN
  3. Check whether the worker role of Account A has the AssumeRole permission.AssumeRole permission
    For more information, see View the basic information about a policy.
  4. Add the assumeRoleARN field to the configuration file of the aliyun-acr-credential-helper component.

    Set the value of the assumeRoleARN field to the ARN of the RAM role of Account B. For more information about how to obtain the ARN information, see How do I find the ARN of a RAM role?. The following YAML file is an example. For more information about how to configure the component, see the preceding Configure the component section.

    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

Pull images across accounts by using the AccessKey information of other accounts

  1. Create a RAM role for your account. Specify Alibaba Cloud Account as the trusted entity of the RAM role. Make sure that the created RAM role has the permissions to pull private images.
    For more information, see Step 1 in the Pull images across accounts by role assuming section.
  2. Configure the acr-configuration ConfigMap in the kube-system namespace. Specify the AccessKey ID and AccessKey secret of the created RAM role.
    This way, the acr-configuration component can use the RAM role to pull private images. For more information about how to obtain the AccessKey information, see View the basic information about AccessKey pairs.

    The following code block provides a configuration example: For more information about how to configure the component, see the preceding Configure the component section.

    data:   
        service-account: "default"
        watch-namespace: "all"
        expiring-threshold: "15m"
        notify-email: "cs@aliyuncs.com"
        acr-registry-info: |
        - instanceId: ""
          customAccessKey: "xxxxx" // Enter the AccessKey ID of the created RAM role.
          customAccessKeySecret: "xxxxxx" // Enter the AccessKey secret of the created RAM role.

Scenario 2: Pull images under the current account

If you want to pull images under the current account, you must check whether the current account has the permissions to pull images from ACR instances.

  1. Log on to the ACK console. In the left-side navigation pane, choose Clusters > Clusters. On the Clusters page, find and click the target cluster.
  2. On the Cluster Resources tab, click the worker role on the right side of Worker RAM Role.
  3. On the page that appears, click the Permissions tab, and then find and click the target policy in the Policy column.
  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"
    }
    The following figure shows where the content is added.The RAM role is granted the ACR-related permissions
Note If you fail to pull images without a password under the current account, you 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, Submit a ticket
  • 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 the acr-configurationConfigMap.

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: For more information, see the Configure the component section.

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
            

Scenario 4: Pull private images from default instances and instances of Container Registry Enterprise Edition

If you need to pull private images from both the default instances and instances of Container Registry Enterprise Edition at the same time, modify the acr-configurationConfigMap as shown in the following example. For more information, see the Configure the component section.
data:   
    service-account: "default"
    watch-namespace: "all"
    expiring-threshold: "15m"
    notify-email: "cs@aliyuncs.com"
    acr-registry-info: |
    - instanceId: ""
    - instanceId: "cri-xxxx"