How to use the aliyun-acr-credential-helper component to pull images without using a secret - Container Service for Kubernetes

You can configure an 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 passwords as secrets.

Note

For information about how to push images to Container Registry Personal Edition instances and pull images from the instances, see Use a Container Registry Personal Edition instance to push and pull images.

Prerequisites
Usage notes
Precautions
Step 1: Install the aliyun-acr-credential-helper component
Step 2: Pull images in different scenarios
Other features
References

Prerequisites

An ACK managed cluster is created. For more information, see Create an ACK managed cluster.
The kubeconfig file of the cluster is obtained, and the cluster is connected by using kubectl. For more information, see Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster.

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 pull private images in compatible scenarios in which you need to pull private images from instances of Enterprise Edition and Personal Edition.
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 password 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.

Log on to the ACK console. In the left-side navigation pane, click Clusters.
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.
On the Add-ons page, click the Security tab, find aliyun-acr-credential-helper, and then click Install.

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.

Use the ACK console

Log on to the ACK console and click Clusters in the left-side navigation pane.
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.
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

Run the following command to go to the editing page of the acr-configuration ConfigMap:
```
kubectl edit cm acr-configuration -n kube-system
```
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 (,).	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 secret. Leave the parameter empty when you need to pull images in compatible scenarios in which 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 secret.	Default value: default. If the value is set to all, images can be pulled from all namespaces without using a secret. 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	Scenarios in which you want to pull images across accounts.
	Assume a RAM role to pull images across accounts	Scenarios in which clusters rely on the worker role. Scenarios in which you want to pull images across accounts.
	Use the AccessKey ID and AccessKey secret of a RAM user to pull images across accounts	Scenarios in which 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

Create a custom policy. For more information, see Step 1: Create a custom policy.

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

Attach the custom policy to the worker RAM role. For more information, see Step 2: Attach the custom policy to the worker RAM role.

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.
After you enable the RRSA feature, the Secrets that are generated by aliyun-acr-credential-helper cannot be used to pull private images of Container Registry Personal Edition instances. After you enable the RRSA feature, you cannot use other authentication methods that are described in this topic, such as the AccessKey pair method.
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.

Enable the RRSA feature for the cluster. For more information, see Enable the RRSA feature.
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 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 when you configure the acr-configuration ConfigMap. 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.

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

Expand to view the details

Note

Configuration rules:

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

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

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

Expand to view the details

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

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.

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

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.

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

Table of contents

Prerequisites

Usage notes

Precautions

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

Use the ACK console

Use kubectl

Step 2: Pull images in different scenarios

Scenario 1: Pull images within the same account

Scenario 2: Pull images across regions

Scenario 3: Pull images across accounts

Other features

Pull private images from a Container Registry Personal Edition instance

Use the webhook feature

References