Use managed-aliyun-acr-credential-helper to pull images in an ACK Serverless cluster without using a secret - Container Registry

In Container Service for Kubernetes (ACK) Pro clusters, ACK Serverless clusters, and ACK Edge clusters, you can use the managed-aliyun-acr-credential-helper component to pull images from Container Registry Enterprise Edition instances and Container Registry Personal Edition instances. This topic describes how to use managed-aliyun-acr-credential-helper to pull private images in common scenarios.

Prerequisites

An ACK Pro cluster, ACK Serverless cluster, or ACK Edge cluster that runs Kubernetes 1.22 or later is created. For more information, see Create an ACK Serverless cluster.
A Container Registry Enterprise Edition instance is created. For more information, see Create a Container Registry Enterprise Edition instance.
Container Registry is granted permissions that are required to access relevant Alibaba Cloud services. For more information, visit Cloud Resource Access Authorization.
No user-side version of managed-aliyun-acr-credential-helper exists in the cluster.

Note

If you want to use managed-aliyun-acr-credential-helper to pull images across Alibaba Cloud accounts, the cluster must be an ACK Serverless cluster or ACK Pro cluster that runs Kubernetes 1.22 or later, and the images must be stored in Container Registry Enterprise Edition instances.

Usage description

The managed-aliyun-acr-credential-helper component reads your configurations in the Container Registry console and then pulls private images. After you configure the managed-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 configurations. 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.

Install the managed-aliyun-acr-credential-helper component

If you have installed the managed-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 your business. For more information, see Manage components.

For more information about the aliyun-acr-credential-helper component, see aliyun-acr-credential-helper.

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 the aliyun-acr-credential-helper (Managed) card, and then click Install in the lower-right corner of the card.

On the Install aliyun-acr-credential-helper page, click + Add next to AcrInstanceInfo to add multiple Container Registry instances.

The following table describes the parameters that specify the ACR instances.

Parameter	Description	Value
InstanceId	The ID of the Container Registry instance. You can obtain the instance ID in the Container Registry console.	For Container Registry Enterprise Edition instances, the value of this parameter starts with `cri-`. For Container Registry Personal Edition instances, leave the parameter empty.
regionId	The region ID of the Container Registry instance. You can obtain the region ID in the Container Registry console. You must specify this parameter if the cluster is not in the same region as the Container Registry instance. You can leave this parameter empty if the cluster is in the same region as the Container Registry instance.	For example, the region ID of the China (Hangzhou) region is `cn-hangzhou`.
domains	By default, all domain names of the Container Registry Enterprise Edition instance are displayed. You can specify specific domain names. Separate multiple domain names with commas (,).	`example1.com,example2.com`
assumeRoleARN	The Alibaba Cloud resource name (ARN) of the RAM role assumed by the Alibaba Cloud account that owns the Container Registry instance.	`acs:ram::aaa`
expireDuration	The validity period of the secret that is used to pull images across Alibaba Cloud accounts.	Default value: 3600. Valid values: 3600 to 43200. Unit: seconds. Set MaxSessionDuration of the RAM role of Account B to 43200.
rrsaRoleARN	The ARN of the RAM role assumed by the Alibaba Cloud account that owns the cluster.	`acs:ram::bbb`
rrsaOIDCProviderRoleARN	The ARN of the OpenID Connect (OIDC) provider that is used by the cluster.	`acs:ram::ccc`
service-account	The service account that is associated with the secret generated by the managed-aliyun-acr-credential-helper component.	Default value: default. Note You can specify multiple service accounts. Separate multiple service accounts with commas (,). A value of an asterisk (*) indicates all service accounts in the specified namespace.

After you configure the parameters of the Container Registry instances, you must configure parameters of the cluster. The following table describes the parameters of the cluster.

Parameter	Description	Value
watchNamespace	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. You can configure multiple namespaces. Separate multiple namespaces with commas (,). We recommend that you configure your business namespaces for the parameter. If possible, do not set the parameter to `all` or the namespaces in which system components of clusters are stored. Otherwise, system component images may fail to be pulled.
serviceAccount	The service account that is associated with the secret generated by the managed-aliyun-acr-credential-helper component.	Default value: `default`. You can specify multiple service accounts. Separate multiple service accounts with commas (,). A value of an asterisk (`*`) indicates all service accounts in the specified namespace.
expiringThreshold	The period of time after which the cached secret expires.	Default value: `15m`. We recommended that you use the default value. The default value specifies that the secret is updated 15 minutes before the cached secret expires.
Specifies whether to enable RRSA	If you select the check box and configure the RAM Roles for Service Accounts (RRSA) feature for the cluster and the managed-aliyun-acr-credential-helper component, this feature is enabled.	By default, this check box is not selected. After you configure RRSA and select this check box, you can pull images from Container Registry instances across Alibaba Cloud accounts.

The following table describes the scenarios of pulling private images.

Configuration method	Scenario
Scenario 1: Pull images within the same account	By default, the managed-aliyun-acr-credential-helper component uses this method to pull private images. This method is applicable if the cluster and the Container Registry instance belong to the same Alibaba Cloud account.
Scenario 2: Pull images across regions	This method is applicable if the cluster and the Container Registry instance reside in different regions.
Scenario 3: Pull images across accounts	This method is applicable if you want to pull images across Alibaba Cloud accounts by configuring RRSA.

Scenario 1: Pull images within the same account

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 click Cluster Information in the left-side navigation pane.
In the left-side navigation pane, choose Operations > Add-ons.
On the Add-ons page, click the Security tab, find the aliyun-acr-credential-helper (Managed) card, and then click Configuration in the lower-right corner of the card.
In the aliyun-acr-credential-helper Parameters dialog box, click Add. In the instanceId field, enter the ID of the Container Registry Enterprise Edition instance. Click OK.

Scenario 2: Pull images across regions

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 click Cluster Information in the left-side navigation pane.
In the left-side navigation pane, choose Operations > Add-ons.
On the Add-ons page, click the Security tab, find the aliyun-acr-credential-helper (Managed) card, and then click Configuration in the lower-right corner of the card.
In the aliyun-acr-credential-helper Parameters dialog box, click Add. In the instanceId field, enter the ID of the Container Registry Enterprise Edition instance. In the regionId field, enter the region ID of the Container Registry Enterprise Edition instance. Click OK.

Scenario 3: Pull images across accounts

Pull images across accounts by configuring RRSA

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

Only in ACK Pro or ACK Serverless clusters that run Kubernetes 1.22 or later, the RRSA feature can be used to pull images from Container Registry Enterprise Edition (including Basic Edition, Standard Edition, and Advanced Edition) instances.

Important

After you enable the RRSA feature, the secret that is generated by managed-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 managed-aliyun-acr-credential-helper, you must enable RRSA by clicking Enable RRSA in the "Cluster Information" section on the Basic Information tab of the Cluster Information page in the ACK console and then configure RRSA for managed-aliyun-acr-credential-helper. If you configure RRSA for managed-aliyun-acr-credential-helper and then enable RRSA for the cluster in the ACK console, you must delete the pod corresponding to managed-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 RRSA.
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 operations to enable RRSA for managed-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 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. 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 "aliyun-acr-credential-helper Parameters" dialog box. 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.
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 click Cluster Information in the left-side navigation pane.
In the left-side navigation pane, choose Operations > Add-ons.
On the Add-ons page, click the Security tab, find the aliyun-acr-credential-helper (Managed) card, and then click Configuration in the lower-right corner of the card.
In the aliyun-acr-credential-helper Parameters dialog box, click Add and then specify values for the assumeRoleARN, expireDuration, rrsaRoleARN, and rrsaOIDCProviderRoleARN parameters. Click OK.