All Products
Search
Document Center

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

Last Updated:Mar 15, 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.

Important

Table of contents

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 Other features.

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

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 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 Update an ACK cluster.

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

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

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.

  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.

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

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

Step 2: Pull images in different scenarios

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

Configuration method

Scenario

Scenario 1: 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

Scenarios in which 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.

  • 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 Step 1: Create a custom policy.

    {
        "Version": "1",
        "Statement": [
            {
                "Action": [
                    "cr:GetAuthorizationToken",
                    "cr:ListInstanceEndpoint",
                    "cr:PullRepository"
                ],
                "Resource": "*",
                "Effect": "Allow"
            }
        ]
    }
  2. Attach the custom policy to the worker RAM role. For more information, see Step 2: Attach the custom policy to the worker RAM role.

  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 Enable the RRSA feature.

  2. Grant the RAM permissions that are required 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 of 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 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 ARN (Alibaba Cloud Resource Name) 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, add the ARN of the RAM role of Account A to the Principal field of the trust policy. Associate the following policy with the RAM role in Account B. The policy grants the RAM role in Account B the permissions to obtain information of Container Registry instances and pull images from the instances.

      {
          "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 in the following "Modify parameters of aliyun-acr-credential-helper" section. We recommend that you specify the same value for MaxSessionDuration and expireDuration. The value of expireDuration can be smaller 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 the 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. This rule requires you to 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. Define the permissions in the policy that is associated with the RAM role of Account B. Make sure that the RAM role is granted the permissions that are required to pull private images from Container Registry instances of Account B.

      For more information, see Modify the document and description of a custom policy.

      Important

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

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

      The following figure shows where the content is added.RAM有CR的相关权限

  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 more information about how to obtain the ARN of a RAM role, see How do I view the ARN of a RAM role?

    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 Management 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 more information about how to obtain the ARN of a RAM role, see How do I view the ARN of a RAM role? 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 the details

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

  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 more information about how to view the AccessKey pair of a RAM user, see View the AccessKey pair 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.

Other features

Use 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

FAQ

I installed the aliyun-acr-credential-helper component in my cluster. The cluster still fails to pull private images from a Container Registry Personal Edition instance. What do I do?

  • We recommend that you use a Container Registry Enterprise Edition instance if you want to pull images by using the aliyun-acr-credential-helper component. For more information about how to pull images from a Container Registry Personal Edition instance, see Push images to and pull images from a Container Registry Personal instance.

  • If you have configured the acr-configuration ConfigMap, delete # from the #-instanceId value and modify the value of the acr-configuration ConfigMap. This way, the cluster can pull private images from Container Registry Personal Edition instances by using the aliyun-acr-credential-helper component.

    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"