Pull images from an ACR instance without using a secret - Container Compute Service

Container Compute Service (ACS) lets you pull images from Container Registry (ACR) without using a secret. This improves efficiency and security. This topic describes how to pull images from an ACR instance in an ACS cluster without using a secret.

Background information

Container Registry (ACR) provides secure hosting and efficient distribution for standard cloud native artifacts. ACR is available in different editions, such as Personal Edition and Enterprise Edition. For more information, see What is Container Registry?. ACS provides a unified method to configure password-free image pulling for different ACR editions.

When you configure the password-free service for an ACS cluster, ACS automatically provides authentication credentials to pull images from ACR. This simplifies the pod creation process, prevents password leaks, and enhances security.

Note

Password-free image pulling is not supported for images from repositories other than ACR, such as Docker Hub or self-managed repositories.

Prerequisites

Before you configure password-free image pulling from ACR for an ACS cluster, complete the following tasks:

Create an ACS cluster. For more information, see Create an ACS cluster.
Create an ACR instance and configure its image repositories and images.
- For information about how to configure an ACR Personal Edition instance, see Use a Personal Edition instance to push and pull images.
- For information about how to configure an ACR Enterprise Edition instance, see Use an Enterprise Edition instance to push and pull images.
If you use an ACR Enterprise Edition instance, configure its access method.
By default, a new ACR Enterprise Edition instance is not connected to any network. You must configure an Access Control List (ACL) to allow access to the instance over the internet or a virtual private cloud (VPC).
- Public network access: After you enable public network access, you can access images in the Enterprise Edition instance over the internet using a public endpoint. You can access images across regions. For more information, see Configure access over the Internet.
- VPC access: To access an ACR Enterprise Edition instance over a VPC, you must grant the required permissions. For more information, see Configure access over a VPC.

How it works

The password-free component reads your configurations from the console to pull private images. After you configure the component, it automatically creates a secret in the cluster. The component then associates the secret with the service account that you specified in the configuration. By default, any pod that uses this service account uses the generated secret to pull images. This lets you pull images without a password.

Install and configure the password-free component

Log on to the ACS console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its ID. In the left-side navigation pane of the cluster details page, choose Operations > Add-ons.
On the Add-ons page, click the Security tab. Find aliyun-acr-credential-helper and click Install.

In the Parameters dialog box, click Add to the right of AcrInstanceInfo to add information about one or more ACR instances. Configure the parameters as described in the following examples and click Confirm.

Add AcrInstanceInfo.

Note

The configuration for default scenarios is as follows:

To synchronize with an ACR Personal Edition instance, use the default configurations for AcrInstanceInfo.
To synchronize with an ACR Enterprise Edition instance, specify the instanceID and use the default configurations for the other AcrInstanceInfo items.

Key	Description	Value
instanceID	The ID of the ACR instance.	Find the created instance in the Container Registry console. Enterprise Edition: On the Instance Information page, you can find the Instance ID. The value is a string that starts with `cri-`. Personal Edition: To configure password-free pulling for a Personal Edition instance, leave this parameter empty. The default value is empty. This configures the Personal Edition instance in the current region.
regionID	The region ID of the ACR instance.	The ID of the region where the ACR instance resides. For example, the region ID for an instance in the China (Hangzhou) region is `cn-hangzhou`. The default value is the region of the ACS cluster. If the ACR instance is in the same region as the ACS cluster, leave this parameter empty.
domains	The domain names used to access the ACR instance.	The domain names used to access the image. Separate multiple domain names with a comma (,). The default value includes all domain names that correspond to the instanceID of the ACR instance. This includes the public endpoint (registry.), VPC endpoint (registry-vpc.), and internal same-region endpoint (registry-internal.*).
assumeRoleARN	(Optional) The ARN of the RAM role of the image repository owner, which you can obtain in Step 4 of Configure pulling images across accounts. Leave this parameter empty if you do not pull images across accounts.	Example: acs:ram::123456789012****:test-rrsa-acr The default value is empty.
expireDuration	(Optional) The validity period of the temporary credentials in a cross-account scenario. Leave this parameter empty if you are not pulling images across accounts. Important The value of expireDuration must be less than or equal to the Maximum Session Duration of the image repository owner's role that you set in Step 4 of Configure cross-account image pulling.	The default value is `3600`.
rrsaRoleARN	(Optional) The ARN of the ACS cluster RAM role, which you can obtain in Step 3 of Configure pulling images across accounts. Leave this parameter empty if you do not pull images across accounts.	Example: acs:ram::987654321012****:demo-role-for-rrsa The default value is empty.
rrsaOIDCProviderRoleARN	(Optional) The RRSA OpenID Connect (OIDC) Provider ARN of the ACS cluster, which you can obtain in Step 2 of Configure pulling images across accounts. Leave this parameter empty if you do not pull images across accounts.	Example: acs:ram::987654321012**:oidc-provider/ack-rrsa-abcd1234** The default value is empty.

Configure other parameters.

Key	Description	Value
Enable RRSA	Select this check box to enable RAM Roles for Service Accounts (RRSA). You must complete the RRSA-related configurations.	This option is not selected by default. After you configure the RRSA-related parameters and select this check box, you can pull images across accounts.
watchNamespace	The namespace where you want to pull images without a password.	The default value is `default`. If you set the value to all, you can pull images without a password from all namespaces. To specify multiple namespaces, separate them with a comma (,). Note Specify your business namespaces. Do not specify all or system component namespaces to prevent image pulling failures for system components.
serviceAccount	The service account that the password-free component applies to.	The default value is `default`. Note To specify multiple service accounts, separate them with a comma (,). If you set this parameter to an asterisk (*), all service accounts in the specified namespace are supported.
expiringThreshold	The expiration threshold for the locally cached credentials.	The default value is `15m`. Note We recommend that you use 15m. This means the credentials are renewed 15 minutes before they expire.
notifyEmail	The email tag in the secret that is generated by the password-free component.	The default value is `xxx@aliyun.com`.

Configure cross-account image pulling

Use RRSA to pull images across accounts

The RAM Roles for Service Accounts (RRSA) feature provides pod-level permission isolation within an ACS cluster. By enabling the RRSA feature for an ACS cluster and distributing the ARN of an authorized role to different image repository owners, the password-free component can pull ACR images across accounts.

The RRSA feature is supported only for pulling images from ACR Enterprise Edition (Basic, Standard, and Premium) instances.

Important

After you enable RRSA, the credentials that the component generates do not support pulling private images from Personal Edition instances. Other authentication methods described in this topic are also not supported.
You must enable RRSA for the cluster before you configure the RRSA settings for the password-free add-on. If you perform these steps in the wrong order, you must delete the add-on's pod after the configuration is complete to ensure that the RRSA feature takes effect.

Enable the RRSA feature for the ACS cluster. For more information, see Enable the RRSA feature.
ACS automatically creates an RRSA OpenID Connect (OIDC) provider for the cluster. On the cluster details page in the ACS console, choose Basic Information > Security And Auditing > RRSA OIDC to view the Provider URL and Provider ARN.

The cluster owner uses the OIDC provider to configure a RAM role and grant permissions to assume the role.

Create a RAM role using an OIDC provider or associate an OIDC provider with an existing RAM role. This allows the password-free component to use the permissions of the role to access OpenAPI.

Create a RAM role using an OIDC provider

Log on to the Resource Access Management (RAM) console using an Alibaba Cloud account.
In the navigation pane on the left, choose Identity Management > Roles. On the Roles page, click Create Role.
On the Create Role page, click Switch To Editor. Set Principal to Identity Provider. Configure the role information as described in the following table and click Confirm.

This example uses the following configurations.

Parameter	Description
Identity Provider Type	OIDC.
Select Identity Provider	acs-rrsa-<cluster_id>. <cluster_id> is your cluster ID.
Condition	oidc:iss: Keep the default value. oidc:aud: Keep the default value. oidc:sub: Set the condition operator to StringEquals. Set the value in the system:serviceaccount:<namespace>:<serviceAccountName> format. <namespace>: The namespace where the application resides. <serviceAccountName>: The name of the service account. As required by the password-free add-on, you must enter `system:serviceaccount:kube-system:aliyun-acr-credential-helper`.

In the Create Role dialog box, set Role Name to demo-role-for-rrsa. Click Confirm.

Associate an OIDC provider with an existing RAM role

Log on to the RAM console using an Alibaba Cloud account.
In the navigation pane on the left, choose Identity Management > Roles and click the name of the target RAM role.
On the Trust Policy tab, click Edit Trust Policy. For more information, see Modify the trust policy of a RAM role.

Add the following content to the Statement list in the trust policy.

{
    "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>"
        ]
    }
}

Important

Replace <oidc_issuer_url> and <oidc_provider_arn> with the Provider URL and Provider ARN that you obtained in Step 2.

Grant the AliyunSTSAssumeRoleAccess policy to the RAM role. This allows the password-free component to assume the role. For more information, see Grant permissions to a RAM role.
On the role details page, choose Basic Information > ARN to view the ARN of the RAM role.

Configure a RAM role for the image repository owner that trusts the RAM role of the cluster owner and grants image pulling permissions.
1. Create a RAM role. For more information, see Create a RAM role for a trusted Alibaba Cloud account.
2. Trust the RAM role of the ACS cluster and allow it to assume the role of the repository owner. For more information, see Modify the trust policy of a RAM role. The following code shows a sample policy document:
```
{
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "<acs_role_arn>"
                ]
            }
        }
    ],
    "Version": "1"
}
```
  Important
  Replace <acs_role_arn> with the ARN of the ACS cluster's RAM role that you obtained in Step 3.
3. Grant image pulling permissions to the RAM role.
  1. Create a custom policy in script edit mode using the following policy document. We recommend that you set the policy Name to AliyunACRBasicAccess. For more information, see Create a custom policy.
```
{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "cr:GetAuthorizationToken",
                "cr:ListInstanceEndpoint",
                "cr:PullRepository"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}
```
  2. Grant the AliyunACRBasicAccess permission to the RAM role. For more information, see Grant permissions to a RAM role.
4. [Optional] Set the Maximum Session Duration for the RAM role. The value can range from 3600 to 43200 seconds. If you set the Maximum Session Duration, you must also set the expireDuration parameter when you configure AcrInstanceInfo in Step 5.
5. On the role details page, choose Basic Information > ARN to view the ARN of the RAM role.

In the configuration of the password-free component, select Enable RRSA and configure AcrInstanceInfo.

Modify the parameters in the AcrInstanceInfo section as described in the following table.

Key	Description	Value
Enable RRSA	Select this check box to enable RRSA. You must complete the RRSA-related configurations.	Selected
rrsaRoleARN	The ARN of the ACS cluster's RAM role that you obtained in Step 3.	`<acs_role_arn>`
rrsaOIDCProviderRoleARN	The Provider ARN of the RRSA OIDC provider for the ACS cluster that you obtained in Step 2.	`oidc_provider_arn`
assumeRoleARN	The ARN of the image repository owner's RAM role that you obtained in Step 4.	`<acr_role_arn>`
expireDuration	The validity period of the temporary credentials generated by the password-free component. Important The value of expireDuration must be less than or equal to the Maximum Session Duration of the image repository owner's RAM role that you set in Step 4.	The default value is 3600. The value must be in the range of [3600, 43200]. Unit: seconds.

Container Compute Service:Pull images from an ACR instance without using a secret