Pull ACR images without a password - Container Compute Service

Container Compute Service (ACS) supports pulling images from Container Registry (ACR) without a password to improve efficiency and security. This topic describes how to pull ACR images without a password in an ACS cluster.

Background information

Container Registry (ACR) provides secure hosting and efficient distribution of cloud native artifacts across multiple editions, including ACR Personal Edition and ACR Enterprise Edition. For more information, see Introduction to Container Registry (ACR). ACS provides a unified configuration method for pulling ACR images without a password across all ACR editions.

By configuring passwordless access for an ACS cluster, ACS automatically injects authentication information for ACR images when creating instances. This simplifies the instance creation process and reduces the risk of password exposure, enhancing security.

Note

Docker images, self-hosted repositories, and other non-ACR images do not support passwordless pulling.

Prerequisites

Before you configure passwordless pulling of ACR images in an ACS cluster, complete the following tasks:

Create an ACS cluster. For more information, see Create an ACS cluster.
You have created an ACR instance and configured the image repository and images.
- To configure an ACR Personal Edition instance, see Push and pull images using a Personal Edition instance.
- To configure an ACR Enterprise Edition instance, see Push and pull images using an Enterprise Edition instance.
If you use an ACR Enterprise Edition instance, configure its access method.

Newly created ACR Enterprise Edition instances are disconnected by default. You must configure appropriate ACL policies before accessing the instance over the Internet or a virtual private cloud (VPC).
- Internet access: After enabling public network access, you can directly access ACR Enterprise Edition instance images using the public domain name (cross-domain supported). For more information, see Configure public network access control.
- VPC access: To access an ACR Enterprise Edition instance through a VPC, enable the required authorization. For more information, see Configure VPC access control.

How it works

The passwordless component pulls private images by reading your console configuration. After you configure the passwordless component, it automatically creates a Secret in the cluster and associates it with the ServiceAccount specified in the configuration. Any pod that uses this ServiceAccount automatically uses the Secret generated by the passwordless component to pull images, achieving passwordless image pulling.

Install and configure the passwordless component

Log on to the ACS console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the target cluster. In the left navigation pane, click Add-ons.
On the Add-ons page, select the Security tab. Find aliyun-acr-credential-helper and click Install.

In the Parameters dialog box, click Add next to AcrInstanceInfo to add multiple ACR instance entries. Use the following example for configuration, then click OK.

Add AcrInstanceInfo.

Note

The default scenario is configured as follows:

To sync an ACR Personal Edition instance, use the default AcrInstanceInfo configuration.
To sync an ACR Enterprise Edition instance, enter the instanceID and keep other fields at their default values.

Parameter key	Configuration Item Key Description	Value
instanceID	ACR instance ID.	Find your instance in Container Registry. Enterprise Edition: In Instance , find the Instance ID. The value is a string starting with `cri-`. Personal Edition: Leave this field empty to enable passwordless pulling for Personal Edition. Default value: empty (configures the Personal Edition instance in the current region).
regionID	Region ID of the ACR instance.	The region ID where your ACR instance resides. For example, the region ID for Hangzhou is `cn-hangzhou`. Default value: the region of your ACS cluster. Leave empty if the ACR instance is in the same region.
domains	Domain names used to access the ACR instance.	Domain names for pulling images. Separate multiple domains with commas (,). Default value: all domains associated with the ACR instance specified by instanceID (public domain registry., VPC domain registry-vpc., internal domain registry-internal.*).
assumeRoleARN	(Optional) The ARN of the image repository owner's RAM role obtained in step 4 of Configure cross-account image pulling. Leave empty if not pulling across accounts.	Example: acs:ram::123456789012****:test-rrsa-acr Default value: empty.
expireDuration	(Optional) Validity period of temporary credentials in cross-account scenarios. Leave empty if not pulling across accounts. Important The value of expireDuration must be less than or equal to the Max Session Duration set for the image repository owner's role in step 4 of Configure cross-account image pulling.	Default value: `3600`.
rrsaRoleARN	(Optional) The ARN of the ACS cluster RAM role obtained in step 3 of Configure cross-account image pulling. Leave empty if not pulling across accounts.	Example: acs:ram::987654321012****:demo-role-for-rrsa Default value: empty.
rrsaOIDCProviderRoleARN	(Optional) The ARN of the ACS cluster RRSA OIDC provider obtained in step 2 of Configure cross-account image pulling. Leave empty if not pulling across accounts.	Example: acs:ram::987654321012:oidc-provider/ack-rrsa-abcd1234 Default value: empty.

Configure other parameters.

Parameter key	Configuration Item Key Description	Configuration Item Value
Enable RRSA	Select to enable RRSA (requires completing RRSA-related configurations).	Not selected by default. After configuring RRSA parameters and selecting this option, you can pull images across accounts.
watchNamespace	Namespaces where passwordless image pulling is enabled.	The default value is `default`. When the value is set to all, it indicates that all Namespaces should support passwordless image pulls. To configure multiple Namespaces, separate them with commas (,). Note We recommend specifying only your application namespaces. Avoid setting this to all or system component namespaces to prevent failures in pulling system component images.
serviceAccount	Apply the passwordless component to the specified service account.	Default value: `default`. Note To specify multiple ServiceAccounts, separate them with commas (,). Use * to apply to all ServiceAccounts in the specified namespace(s).
expiringThreshold	Expiration threshold for locally cached credentials.	Default value: `15m`. Note We recommend using 15m, which updates credentials 15 minutes before they expire.
notifyEmail	Email label in the Secret generated by the passwordless component.	Default value: `xxx@aliyun.com`.

Configure cross-account image pulling

Use RRSA for cross-account pulling

RAM Roles for Service Accounts (RRSA) enables pod-level permission isolation in ACS clusters. By enabling RRSA for your ACS cluster and sharing the authorized role ARN with image repository owners, the passwordless component can pull ACR images across accounts.

RRSA currently supports pulling images only from ACR Enterprise Edition instances (Basic, Standard, and Pro).

Important

After enabling RRSA, credentials generated by the component cannot pull private images from Personal Edition or use other authentication methods described in this topic.
To enable RRSA for the passwordless plug-in, first enable RRSA, then configure RRSA-related parameters for the plug-in. If you reverse this order, delete the passwordless plug-in pod after configuration for RRSA to take effect.

Enable RRSA for your ACS cluster. For more information, see Enable RRSA.
ACS automatically creates an RRSA OIDC provider for the cluster. In the cluster console, go to Basic Information > Security and Audit > RRSA > OIDC to view the Provider URL and Provider ARN.

The cluster owner configures a RAM role using the OIDC provider and grants role assumption permissions.

Create a RAM role using the OIDC provider or associate an existing RAM role with the OIDC provider so the passwordless component can use the role to access OpenAPI.

Create a RAM role using the OIDC provider

Log on to the Resource Access Management (RAM) console with your Alibaba Cloud account.
In the navigation pane on the left, choose Identities > Roles. On the Roles page, click Create Role.
On the Create Role page, click Switch to Policy Editor. Set Principal to Identity Provider. Configure the role as follows, then click OK.

Use the following example configuration.

configuration item	Description
IdP Type	OIDC.
Select IdP	acs-rrsa-<cluster_id>. Replace <cluster_id> with your cluster ID.
Condition	oidc:iss: Keep the default value. oidc:aud: Keep the default value. oidc:sub: Set the condition operator to StringEquals. Use the format system:serviceaccount:<namespace>:<serviceAccountName>. <namespace>: Namespace of your application. <serviceAccountName>: Name of the service account. For the passwordless plug-in, you must use `system:serviceaccount:kube-system:aliyun-acr-credential-helper`.

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

Associate an existing RAM role with the OIDC provider

Log on to the Resource Access Management (RAM) console with your Alibaba Cloud account.
In the navigation pane on the left, choose Identities > Roles. Click the name of your 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 example entry 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 obtained in step 2.

Attach the AliyunSTSAssumeRoleAccess permission policy to the RAM role so the passwordless component can assume the role. For more information, see Manage permissions of a RAM role.
On the Basic Information > ARN page, view the ARN of the RAM role.

Configure a RAM role for the image repository owner, trust the cluster owner's RAM role, and grant image-pulling permissions.
1. Create a RAM role. For more information, see Create a RAM role with Alibaba Cloud account as the trusted entity.
2. Trust the ACS cluster RAM role to allow it to assume the repository owner's role. For more information, see Modify the trust policy of a RAM role. Use the following example policy document:
```
{
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "<acs_role_arn>"
                ]
            }
        }
    ],
    "Version": "1"
}
```
  Important
  Replace <acs_role_arn> with the ACS cluster RAM role ARN obtained in step 3.
3. Grant image-pulling permissions to the RAM role.
  1. Create a custom policy in script edit mode. The policy document content is as follows. We recommend that you name the policy Name AliyunACRBasicAccess. For more information, see Creating 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 Manage permissions of a RAM role.
4. [Optional] Set the Max Session Duration for the RAM role. Valid values range from 3600 to 43200 seconds. If you set the Max Session Duration, also set the expireDuration parameter when configuring AcrInstanceInfo in step 5.
5. On the Basic Information > ARN page, view the ARN of the RAM role.

In the passwordless component configuration, select Enable RRSA and configure AcrInstanceInfo.

Modify AcrInstanceInfo as follows.

Parameter key	Description	configuration item value
Enable RRSA	Select to enable RRSA (requires completing RRSA-related configurations).	Selected
rrsaRoleARN	ACS cluster RAM role ARN obtained in step 3.	`<acs_role_arn>`
rrsaOIDCProviderRoleARN	ACS cluster RRSA OIDC provider ARN obtained in step 2.	`oidc_provider_arn`
assumeRoleARN	Image repository owner RAM role ARN obtained in step 4.	`<acr_role_arn>`
expireDuration	Validity period of temporary credentials generated by the passwordless component. Important The value of expireDuration must be less than or equal to the Max Session Duration set for the image repository owner's role in step 4.	Default: 3600. Valid range: [3600, 43200]. Unit: seconds.

Container Compute Service:Pull ACR images without a password