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

In Container Service for Kubernetes (ACK) Pro, ACK Serverless Pro, and ACK Edge clusters, you can use the managed-aliyun-acr-credential-helper component to pull images from Container Registry Enterprise Edition 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, ACK Serverless Pro, ACK Edge, or Container Compute Service (ACS) cluster that runs Kubernetes 1.22 or later is created.
A Container Registry Enterprise Edition instance is created. For more information, see Create a Container Registry Enterprise Edition instance.
Container Registry has 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 is installed 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 Pro, ACK Pro, or ACS cluster that runs Kubernetes 1.22 or later, and the images that you want to pull must be stored on Container Registry Enterprise Edition instances.

Usage notes

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 of 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, find the cluster that you want to manage and click its name. In the left-side pane, choose Operations > Add-ons.
On the Add-ons page, click the Security tab, find the aliyun-acr-credential-helper (Managed) card in the Security section, 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 one or more ACR instances from which you want to pull images without using a secret. If you want to pull images from a Container Registry Personal Edition instance, you also need to click + Add next to AcrInstanceInfo. However, you do not need to set the instanceId parameter.

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 the MaxSessionDuration parameter 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`

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`. Note You can specify multiple service accounts. Separate the service accounts with commas (,). A value of an asterisk (*) specifies all service accounts in the specified namespace.
expiringThreshold	The period of time after which the cached secret expires.	Default value: `15 minutes`. We recommend that you use the default value. The default value specifies that the cached secret is automatically updated 15 minutes before expiry.
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 option 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. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, click Cluster Information.
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 in the Security section, 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. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, click Cluster Information.
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 in the Security section, 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 Basic clusters, ACK Pro clusters, and ACK Serverless Pro clusters that run Kubernetes 1.22 or later, you can configure RRSA to pull images from Container Registry Enterprise Edition instances (including Basic 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 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 RRSA.
Grant the required RAM 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 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 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 attach the AliyunSTSAssumeRoleAccess policy to 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. Click the name of the RAM role. On the Trust Policy tab, enter the ARN of the RAM role of Account A in the Principal field of the trust policy. Attach the following policy to 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 step 7 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 smaller than or equal to the value of MaxSessionDuration.
Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, click Cluster Information.
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 in the Security section, 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.