Configure password-free image pulling from ACR for an ACS cluster - Container Compute Service

How it works

When you install and configure aliyun-acr-credential-helper, the add-on reads your ACR instance settings and generates a short-lived credential. It creates a Kubernetes secret in the cluster and associates the secret with the service account you specify. All pods using that service account automatically use the generated secret to pull images — no manual secret management required.

The add-on renews credentials automatically before they expire. The default renewal threshold is 15 minutes before expiry (expiringThreshold: 15m).

Prerequisites

Before you begin, make sure you have:

An ACS cluster. See Create an ACS cluster
An ACR instance with image repositories configured:
- Personal Edition: Use a Personal Edition instance to push and pull images
- Enterprise Edition: Use an Enterprise Edition instance to push and pull images
(Enterprise Edition only) Network access configured for the ACR instance. By default, a new Enterprise Edition instance is not connected to any network. Configure one of the following:
- Public network access: Allows access over the internet using a public endpoint, including across regions. See Configure access over the internet
- VPC access: Allows access within a Virtual Private Cloud (VPC). See Configure access over a VPC

Install and configure the add-on

Log on to the ACS console. In the left navigation pane, click Clusters.
Click the name of the target cluster. In the left navigation pane, click 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 one or more ACR instances. Configure AcrInstanceInfo based on your ACR edition: Full parameter reference for AcrInstanceInfo:

ACR edition	Required parameters	Notes
Personal Edition	Use default values for all AcrInstanceInfo parameters	Leave `instanceId` blank
Enterprise Edition	Set `instanceId`; use defaults for other parameters	Find the instance ID on the Overview page of the Container Registry console. It starts with `cri-`

Parameter	Description	Default
`instanceId`	The ID of the ACR instance. For Enterprise Edition, find the Instance ID on the Overview page of the Container Registry console (starts with `cri-`). Leave blank for Personal Edition.	Empty (configures Personal Edition in the current region)
`regionId`	The region where the ACR instance resides. For example, `cn-hangzhou` for the China (Hangzhou) region. Leave blank if the ACR instance and ACS cluster are in the same region.	Region of the ACS cluster
`domains`	The domain names used to access the ACR instance. Separate multiple domain names with commas.	All domain names for the instance: public endpoint (`registry.`), VPC endpoint (`registry-vpc.`), and internal same-region endpoint (`registry-internal.*`)
`assumeRoleARN`	(Optional) The ARN of the image repository owner's RAM role, used for cross-account image pulling. Leave blank if not pulling across accounts. Example: `acs:ram::123456789012****:test-rrsa-acr`	Empty
`expireDuration`	(Optional) The validity period of temporary credentials in a cross-account scenario, in seconds. Must be less than or equal to the Max Session Duration of the image repository owner's RAM role. Leave blank if not pulling across accounts.	`3600` (range: 3600–43200)
`rrsaRoleARN`	(Optional) The ARN of the ACS cluster's RAM role, used when RAM Roles for Service Accounts (RRSA) is enabled. Leave blank if not using RRSA. Example: `acs:ram::987654321012****:demo-role-for-rrsa`	Empty
`rrsaOIDCProviderRoleARN`	(Optional) The RRSA OpenID Connect (OIDC) Provider ARN of the ACS cluster. Leave blank if not using RRSA. Example: `acs:ram::987654321012:oidc-provider/ack-rrsa-abcd1234`	Empty

Configure other parameters:

Parameter	Description	Default
Specifies whether to enable RRSA	Select this checkbox to enable RRSA. Required for cross-account image pulling.	Not selected
`watchNamespace`	The namespace where password-free pulling applies. Set to `all` to apply to all namespaces, or specify multiple namespaces separated by commas. Specify only your business namespaces — avoid `all` or system namespaces to prevent image pulling failures for system components.	`default`
`serviceAccount`	The service account to apply the add-on to. Separate multiple service accounts with commas. Set to `*` to apply to all service accounts in the specified namespace.	`default`
`expiringThreshold`	The expiration threshold for locally cached credentials. Credentials are renewed when the remaining validity drops below this value. Use `15m`.	`15m`
`notifyEmail`	The email tag in the secret generated by the add-on.	`xxx@aliyun.com`

Click OK.

Configure cross-account image pulling

RRSA (RAM Roles for Service Accounts) enables aliyun-acr-credential-helper to pull ACR images across Alibaba Cloud accounts. RRSA provides pod-level permission isolation within an ACS cluster.

Important

RRSA is supported only for ACR Enterprise Edition (Basic, Standard, and Premium).
After enabling RRSA, the add-on cannot pull private images from Personal Edition instances. Other authentication methods described in this topic are also not supported.
Enable RRSA for the cluster before configuring RRSA settings for the add-on. If you configure them in the wrong order, delete the add-on's pod after completing the configuration to make RRSA take effect.

Step 1: Enable RRSA for the ACS cluster

Enable the RRSA feature for your ACS cluster. See Enable the RRSA feature.

Step 2: Get the OIDC provider details

After enabling RRSA, ACS automatically creates an OIDC provider for the cluster. On the cluster details page, go to Basic Information > Security and Auditing > RRSA OIDC to view the Provider URL and Provider ARN.

Step 3: Create a RAM role for the cluster owner

The cluster owner needs a RAM role that the add-on can use to call OpenAPI. Use one of the following options:

Option A: Create a new RAM role using the OIDC provider

Log on to the Resource Access Management (RAM) console with an Alibaba Cloud account.
In the left navigation pane, choose Identities > Roles. Click Create Role.

Click Switch to Policy Editor. Set Principal to Identity Provider and configure the following:

Parameter	Value
Identity Provider Type	OIDC
Identity Provider	`acs-rrsa-<cluster_id>`, where `<cluster_id>` is your cluster ID
oidc:iss	Keep the default value
oidc:aud	Keep the default value
oidc:sub	Set the condition operator to StringEquals. Set the value to `system:serviceaccount:kube-system:aliyun-acr-credential-helper`

Set Role Name to demo-role-for-rrsa and click OK.
Grant the AliyunSTSAssumeRoleAccess policy to this RAM role. See Grant permissions to a RAM role.
On the role details page, go to Basic Information > ARN to view and copy the ARN of this RAM role.

Option B: Associate the OIDC provider with an existing RAM role

Log on to the RAM console with an Alibaba Cloud account.
In the left navigation pane, choose Identities > Roles and click the target RAM role.
On the Trust Policy tab, click Edit Trust Policy. See Modify the trust policy of a RAM role.

Add the following entry to the Statement list:

Important

Replace <oidc_issuer_url> and <oidc_provider_arn> with the Provider URL and Provider ARN from Step 2.

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

Grant the AliyunSTSAssumeRoleAccess policy to this RAM role. See Grant permissions to a RAM role.
On the role details page, go to Basic Information > ARN to view and copy the ARN of this RAM role.

Step 4: Configure a RAM role for the image repository owner

The image repository owner needs a RAM role that trusts the cluster owner's RAM role and has image pulling permissions.

Create a RAM role. See Create a RAM role for a trusted Alibaba Cloud account.

Allow the ACS cluster's RAM role to assume this role. Edit the trust policy with the following content. See Modify the trust policy of a RAM role.

Important

Replace <acs_role_arn> with the ARN of the ACS cluster's RAM role from Step 3.

{
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "<acs_role_arn>"
                ]
            }
        }
    ],
    "Version": "1"
}

Grant image pulling permissions to this RAM role:

Create a custom policy in script edit mode using the following policy document. Set Policy Name to AliyunACRBasicAccess. See Create a custom policy. ``

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

Grant the AliyunACRBasicAccess policy to the RAM role. See Grant permissions to a RAM role.

(Optional) Set the Max Session Duration for this RAM role. The value must be between 3600 and 43200 seconds. If you set this, also set expireDuration in the AcrInstanceInfo configuration to a value less than or equal to the max session duration.
On the role details page, go to Basic Information > ARN to view and copy the ARN of this RAM role.

Step 5: Update the add-on configuration

In the aliyun-acr-credential-helper configuration, enable RRSA and set the following parameters in AcrInstanceInfo:

Parameter	Description	Value
Specifies whether to enable RRSA	Enable RRSA for cross-account pulling.	Selected
`rrsaRoleARN`	The ARN of the ACS cluster's RAM role from Step 3.	`<acs_role_arn>`
`rrsaOIDCProviderRoleARN`	The Provider ARN of the RRSA OIDC provider from Step 2.	`<oidc_provider_arn>`
`assumeRoleARN`	The ARN of the image repository owner's RAM role from Step 4.	`<acr_role_arn>`
`expireDuration`	The validity period of temporary credentials, in seconds. Must be less than or equal to the Max Session Duration set in Step 4.	Default: `3600` (range: 3600–43200)

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

How it works

Prerequisites

Install and configure the add-on

Configure cross-account image pulling

Step 1: Enable RRSA for the ACS cluster

Step 2: Get the OIDC provider details

Step 3: Create a RAM role for the cluster owner

Option A: Create a new RAM role using the OIDC provider

Option B: Associate the OIDC provider with an existing RAM role

Step 4: Configure a RAM role for the image repository owner

Step 5: Update the add-on configuration

What's next