All Products
Search
Document Center

Container Registry:Use the aliyun-acr-credential-helper component to pull images without using a secret

Last Updated:Sep 29, 2024

You can configure the aliyun-acr-credential-helper component for Container Service for Kubernetes (ACK) clusters to automatically obtain the secret when you pull private images from Container Registry Enterprise Edition instances for the ACK clusters. This eliminates the need to manually provide usernames and secrets.

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 secret that is generated by the component to pull images. This eliminates the need to use other secrets when you pull images.

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. For more information, see the "FAQ" section of this topic.

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

Item

Usage note

Mirroring

  • 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 use the component to pull private images from Container Registry Enterprise Edition instances.

Cluster type and version

  • Supported cluster types:

    • ACK dedicated clusters of v1.11.2 or later. If the version of your cluster is earlier than v1.11.2, you must update the cluster version. For more information, see Manually update ACK clusters.

    • ACK managed clusters of all versions.

  • You can pull images without using a secret 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 the "Scenario 2: Pull images across regions" section of this topic.

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 then apply the configuration. This ensures that the format of the ConfigMap is valid.

Step 1: Install the aliyun-acr-credential-helper component

If you installed the aliyun-acr-credential-helper component, make sure that the component is of the latest version. Otherwise, update the component. Updating the component does not affect your business. 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.

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

  2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Operations > Add-ons.

  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

    Automatically determines whether to use the managedRole mode, which is the default value. The system uses the managedRole mode for new clusters and the workerRole mode for old clusters.

    managedRole

    Uses the managedRole mode.

    workerRole

    Uses the workerRole mode.

Step 2: Modify configurations

Perform the following operations to modify configurations for a Container Registry Enterprise Edition instance. For information about how to modify configurations for a Container Registry Personal Edition instance, see the "How do I pull private images from a Container Registry Personal Edition instance?" section of this topic.

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

    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. In the left-side navigation pane of the page that appears, choose Configurations > ConfigMaps.

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

      If the acr-configuration ConfigMap does not exist, create a ConfigMap named acr-configuration. For more information, see the "Create a ConfigMap" section of the Manage ConfigMaps topic. 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

    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.

    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 the aliyun-acr-credential-helper component 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

    Parameters for specifying an instance:

    • instanceId: the ID of the Container Registry instance. This field is required for 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.

Step 3: Pull images in different scenarios

The permissions that are required to pull private images vary based on the scenario.

Scenario

Description

Scenario 1: Pull images within the same account

You want to pull images within the same account. By default, the aliyun-acr-credential-helper component pulls private images within the same account.

Scenario 2: Pull images across regions

You want to pull images across regions.

Scenario 3: Pull images across accounts

Configure RAM Roles for Service Accounts (RRSA) to pull images across accounts

You want to pull images across accounts.

Assume a RAM role to pull images across accounts

  • Clusters rely on the worker role based on the value of the tokenMode parameter.

  • You want to pull images across accounts.

Use the AccessKey ID and AccessKey secret of a RAM user to pull images across accounts

You want to pull images across accounts.

If you pull images by using the AccessKey ID and AccessKey secret of a RAM user, you must specify the AccessKey pair in the acr-configuration ConfigMap. In this case, the AccessKey pair may be leaked. To ensure data security, make sure that the RAM role to which the AccessKey pair belongs is granted only the permissions to pull images. We recommend that you use the other two methods to pull images across accounts.

Configure the required permissions based on the following scenarios.

Scenario 1: Pull images within the same account

  1. Create a custom policy and add the following content to the policy. For more information, see the "Step 1: Create a custom policy" section of the [Product Changes] Permissions of the worker RAM role of ACK managed clusters are revoked topic.

    {
        "Version": "1",
        "Statement": [
            {
                "Action": [
                    "cr:GetAuthorizationToken",
                    "cr:ListInstanceEndpoint",
                    "cr:PullRepository"
                ],
                "Resource": "*",
                "Effect": "Allow"
            }
        ]
    }
  2. Attach the custom policy to the worker RAM role of the cluster. For more information, see the "Step 2: Attach the custom policy to the worker RAM role" section of the [Product Changes] Permissions of the worker RAM role of ACK managed clusters are revoked topic.

  3. Modify the acr-configuration ConfigMap based on the following sample code to pull private images from a Container Registry Enterprise Edition instance.

    data:
        service-account: "default"
        watch-namespace: "all"
        expiring-threshold: "15m"
        notify-email:"c*@aliyuncs.com"
        acr-registry-info:|
          - instanceId: "cri-instanceId"
            regionId: "cn-hangzhou"
            domains: "instance.default.domain.com,instance.custom.domain.com"

Scenario 2: Pull images across regions

If you want to pull images from Container Registry instances that reside in different regions from your ACK cluster, you must modify the acr-configuration ConfigMap.

Important

After you enable cross-region image pulling, the aliyun-acr-credential-helper component sends API requests to the destination region over the Internet. You must enable Internet access for the cluster.

For example, if you want to pull images from Container Registry instances that reside in the China (Beijing) and China (Hangzhou) regions, modify the acr-configuration ConfigMap based on the following sample code.

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

Scenario 3: Pull images across accounts

You can use one of the following methods to pull images across accounts.

  • Pull images across accounts by configuring RRSA: Account A assumes the RAM role of Account B to pull private images from the Container Registry instances of Account B.

  • Pull images across accounts by assuming a RAM role: Account A assumes the RAM role of Account B to pull private images from the Container Registry instances of Account B.

  • Pull images across accounts by using the AccessKey pair of a RAM user: Account A uses the AccessKey pair of Account B to pull private images from the Container Registry instances of Account B.

Pull images across accounts by configuring RRSA

The RRSA feature can be used to perform access control on pods in a cluster.

You can configure RRSA to pull images from Container Registry Enterprise Edition instances (including Basic Edition and Advanced Edition instances) only in clusters of v1.22 and later. Clusters of v1.22 and later include ACK Basic clusters, ACK Pro clusters, ACK Serverless Basic clusters, and ACK Serverless Pro clusters.

Important
  • To enable the RRSA feature, you must update the aliyun-acr-credential-helper component to v23.02.06.1-74e2172-aliyun or later.

  • To enable the RRSA feature for aliyun-acr-credential-helper, you must enable RRSA on the Basic Information tab of the Cluster Information page in the ACK console and then configure RRSA for aliyun-acr-credential-helper. If you configure RRSA for aliyun-acr-credential-helper and then enable RRSA on the Basic Information tab of the Cluster Information page in the ACK console, you must delete the pod corresponding to aliyun-acr-credential-helper after you configure RRSA. This allows RRSA to take effect.

  1. Enable the RRSA feature for the cluster. For more information, see the "Enable RRSA" section of the Use RRSA to authorize different pods to access different cloud services topic.

  2. Grant the required permissions to access Container Registry resources across accounts.

    After the RRSA feature is enabled for the cluster, you must perform the following steps to enable RRSA for aliyun-acr-credential-helper. For example, the current cluster is in Account A and the Container Registry instance is in Account B. If you want to pull images from the Container Registry instance, you must grant the cluster in Account A the permissions to access Container Registry resources of Account B.

    1. Configure a RAM role for Account A

      Create a RAM role in Account A and associate the AliyunSTSAssumeRoleAccess policy with the RAM role. This policy grants the RAM role the permission to assume the role of Account A. Modify the trust policy of the RAM role.

      • Replace <oidc_issuer_url> in the example with the URL of the OpenID Connect (OIDC) provider of the cluster. You can obtain the URL on the Basic Information tab of the Cluster Information page in the ACK console.

      • Replace <oidc_provider_arn> in the example with the Alibaba Cloud Resource Name (ARN) of the OIDC provider of the cluster. You can obtain the ARN on the Basic Information tab of the Cluster Information page in the ACK console.

      {
        "Statement": [
          {
            "Action": "sts:AssumeRole",
            "Condition": {
              "StringEquals": {
                "oidc:aud": "sts.aliyuncs.com",
                "oidc:iss": "<oidc_issuer_url>",
                "oidc:sub": "system:serviceaccount:kube-system:aliyun-acr-credential-helper"
              }
            },
            "Effect": "Allow",
            "Principal": {
              "Federated": [
                "<oidc_provider_arn>"
              ]
            }
          }
        ],
        "Version": "1"
      }
    2. Configure a RAM role for Account B

      Create a RAM role that has Container Registry-related permissions in Account B. On the Trust Policy Management tab, enter the ARN of the RAM role of Account A in the Principal field of the trust policy.

      {
        "Statement": [
          {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
              "RAM": [
                <ARN of the RAM role that you created for Account A>
              ]
            }
          }
        ],
        "Version": "1"
      }

      Attach a policy that allows users to obtain information of Container Registry instances and pull images from the instances to the RAM role in Account B.

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

      You can configure the MaxSessionDuration parameter for the RAM role. Valid values of this parameter range from 3600 to 43200 seconds. You must configure the expireDuration parameter when you configure the acr-configuration ConfigMap in Step 3. We recommend that you specify the same value for MaxSessionDuration and expireDuration. The value of expireDuration can be less than or equal to the value of MaxSessionDuration.

  3. Configure the acr-configuration ConfigMap

    Modify the acr-configuration ConfigMap based on the following information:

    data:
      rrsa: |
        enable: true
      acr-registry-info: |
        - instanceId: cri-xxx
          regionId: cn-hangzhou
          rrsaRoleARN: aUserRoleARN
          rrsaOIDCProviderRoleARN: aUserClusterOIDCProviderRoleARN
          assumeRoleARN: bUserRoleARN
          expireDuration: 3600

    Key

    Description

    Value

    rrsaRoleARN

    The ARN of the RAM role that you created for Account A.

    acs:ram::aaa

    rrsaOIDCProviderRoleARN

    The ARN of the OIDC provider that you obtained on the Basic Information tab of the Cluster Information page in the ACK console.

    acs:ram::bbb

    assumeRoleARN

    The ARN of the RAM role that you created for Account B.

    acs:ram::ccc

    expireDuration

    The session period of the RAM role that you created for Account B. The session period is equal to the validity period of the secret that is generated by aliyun-acr-credential-helper.

    Important

    The expireDuration value cannot be greater than the MaxSessionDuration value of the RAM role of Account B.

    Default value: 3600. Valid values: 3600 to 43200. Unit: seconds.

    Set MaxSessionDuration of the RAM role of Account B to 43200.

Pull images across accounts by assuming a RAM role

Unfold to view details

Note

Configuration rules:

  1. The RAM role of Account B is authorized to pull private images from a specified private repository. This rule requires you to grant the cr.* permissions to the RAM role of Account B.

  2. Account B allows the worker role of the ACK cluster of 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 ACK cluster created by Account A has the permissions to assume the RAM role of Account B. This rule requires you to associate the AliyunAssumeRoleAccess policy with the worker role of Account A.

  4. Set the worker role of Account A to assume the RAM role of Account B. In this case, you must specify the assumeRoleARN parameter in the acr-configuration ConfigMap.

  1. Create a RAM role for Account B. Specify Alibaba Cloud Account as the trusted entity of the RAM role. Make sure that the RAM role is granted the permissions that are required to pull private images from Container Registry instances of Account B.

    1. Create a RAM role for Account B. For more information, see Create a RAM role for a trusted Alibaba Cloud account.

    2. Create a custom policy on the JSON tab. For more information, see Create custom policies.

      Important

      Make sure that the RAM role is granted the permissions of cr.*.

      ```
      {
      "Action": [
      "cr:GetAuthorizationToken",
      "cr:ListInstanceEndpoint",
      "cr:PullRepository"
      ],
      "Resource": [
      "*"
      ],
      "Effect": "Allow"
      }
      
      ```
    3. Attach the custom policy to the RAM role. For more information, see Grant permissions to a RAM role.

  2. Modify the trust policy of the RAM role of Account B. This way, the RAM role of Account B allows the worker role of the ACK cluster in Account A to assume the RAM role of Account B.

    Obtain the ARN of the worker role of the ACK cluster created by Account A.

    1. For information about how to obtain the ARN of a RAM role, see the "How do I view the ARN of a RAM role?" section of the FAQ about RAM roles and STS tokens topic.

    2. Modify the trust policy of the RAM role of Account B.

      1. Log on to the RAM console. In the left-side navigation pane, click Roles. On the Roles page, find the RAM role of Account B and click the role name.

      2. On the details page of the RAM role, click the Trust Policy tab, and add the ARN of the worker role of Account A to the Principal field of the trust policy.RamRoleARN

  3. Check whether the worker role of the ACK cluster in Account A is granted the AssumeRole permission. For more information, see View the basic information about a policy.AssumeRule权限

  4. Add the assumeRoleARN parameter to the acr-configuration ConfigMap.

    Set the value of the assumeRoleARN parameter to the ARN of the RAM role of Account B. For information about how to obtain the ARN of a RAM role, see the "How do I view the ARN of a RAM role?" section of the FAQ about RAM roles and STS tokens topic. The following YAML file shows the sample configuration:

    data:
        service-account: "default"
        watch-namespace: "all"
        expiring-threshold: "15m"
        notify-email:"c*@aliyuncs.com"
        acr-registry-info: |
          - instanceId: ""
            regionId: "cn-beijing"
            domains: "registry.cn-beijing.aliyuncs.com"
            assumeRoleARN: "acs:ram::.*:role/kubernetesworkerrole-test"
            expireDuration: 3600

Pull images across accounts by using the AccessKey pair of a RAM user

Unfold to view details

  1. Create a RAM user and grant the RAM user the permissions to pull images from Container Registry instances. For information about how to grant the permissions to pull images from Container Registry instances, see the "Scenario 3: Pull images across accounts" section of this topic.

  2. Configure the acr-configuration ConfigMap in the kube-system namespace. Enter the AccessKey ID and AccessKey secret of the RAM user that you created.

    This way, the aliyun-acr-credential-helper component can use the RAM user to pull private images. For information about how to view the AccessKey pair of a RAM user, see View the information about AccessKey pairs of a RAM user.

    The following YAML file shows the sample configuration:

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

FAQ

How do I pull private images from a Container Registry Personal Edition instance?

When you migrate images from a Container Registry Personal Edition instance to an Enterprise Edition instance, you may want to pull private images from the Enterprise Edition instance and the Personal Edition instance. In this case, you must modify the acr-configuration ConfigMap based on the following sample configuration. For information about how to push images to and pull images from a Container Registry Personal instance, see Push images to and pull images from a Container Registry Personal instance.

Important

Before you modify the acr-configuration ConfigMap, remove # from #-instanceId.

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

How do I enable the webhook feature?

After you enable the webhook feature, Secrets are immediately injected into newly created service accounts. The feature applies to scenarios in which you want to inject Secrets to service accounts without a delay, such as the scenario in which you create a service account together with a Deployment by using Helm charts. We recommend that you disable the feature in other scenarios.

Important

To enable the webhook feature, you must update the aliyun-acr-credential-helper component to v23.02.06.1-74e2172-aliyun or later.

After you update the component to the latest version, you must modify the acr-configuration ConfigMap based on the following information:

data:
  webhook-configuration: |
    enable: true
    failure-policy: Ignore
    timeout-seconds: 10

Table 1. Keys and values

Key

Description

Value

enable

Specifies whether to enable the webhook feature.

Valid values: true and false. Default value: false.

failure-policy

The failure handling policy when the webhook feature does not work as expected.

Valid values: Ignore and Fail.

  • If you set this parameter to Ignore, the service account is created even if an exception occurs during the creation process. A secret may not be associated with the service account.

  • If you set this parameter to Fail, the creation process of the service account is interrupted when an exception occurs. We recommend that you do not set this parameter to Fail because this setting may cause workload deployment failures.

Due to the limits of cluster API servers, when timeout-seconds is set to 15, failure-policy is set to Fail, and 10 service accounts are created per second for a period of time, service accounts may fail to be created due to timeout errors.

timeout-seconds

The timeout period of requests to create service accounts. The failure-policy is applied when a request to create a service account times out.

Default value: 10. Unit: seconds. You do not need to specify the unit.

References