Pull images across accounts with the password-free component - Container Registry

Decision guide

First, select a network connection method and an account authorization method. Then, select a credential-free component that supports the chosen methods.

For detailed steps, follow the steps in Configure network connections and Configure account authorization and the credential-free component, and then Verify cross-account image pulling.

Note

In this topic, cross-account access refers to access between different Alibaba Cloud accounts (root accounts), not between RAM users (sub-accounts).

Prerequisites

The RAM role used by the passwordless component has been granted the required permissions.
Your ACK cluster must support the passwordless component.
- aliyun-acr-credential-helper (managed)
  
  Version 1.22 or later of ACK managed clusters, ACK serverless clusters, or ACK Edge clusters
- aliyun-acr-credential-helper (self-managed)
  
  Version 1.20 or later ACK managed clusters or ACK dedicated clusters
The Container Registry (ACR) instance must be an Enterprise Edition instance.
Important
- The passwordless component supports only ACR Enterprise Edition instances and ACR Personal Edition instances created on or before September 8, 2024. If you cannot use the passwordless component, see How do I use imagePullSecrets?.

Procedure

Step 1: Configure network connections

When pulling an image across accounts, the ACK cluster pulling the image and the ACR Enterprise Edition instance hosting the image are in different VPCs that belong to different accounts and may also be in different regions. Before you pull the image, you must establish network connectivity and ensure that the relevant domain names can be resolved. You can use one of the following methods:

Public connection: Configure a public endpoint for the ACR Enterprise Edition instance and enable public network access for the ACK cluster. The image is transferred over the public internet. This method is less secure and incurs costs for both the elastic IP address and outbound traffic.
VPC peering connection: Use a VPC peering connection to connect the two VPCs, which allows the ACK cluster to access the ACR Enterprise Edition instance. This feature is free if the VPCs are in the same region but is charged if they are in different regions. This method requires the two VPCs to have non-overlapping CIDR blocks. If there is a significant overlap in the CIDR blocks already in use, you may need to redesign your existing network architecture.
Cloud Enterprise Network (CEN) connection: A CEN instance can contain one or more transit routers. Multiple transit routers can be interconnected through cross-region connections to enable VPC communication across different regions and accounts.

For a comparison of VPC peering connections and CEN, see What are the differences between Cloud Enterprise Network and VPC Peering Connection?

Comparison item	Public connection	VPC peering connection	Cloud Enterprise Network (CEN)
Network type	Public	Private	Private
Billing	Fees are incurred based on the billing methods of elastic IP addresses.	No fees are incurred if the VPCs of the ACK cluster and the ACR Enterprise Edition instance are in the same region. If the VPCs are in different regions, Cloud Data Transfer (CDT) charges a fee for outbound traffic.	Fees are incurred based on the CEN billing rules.
Key features	Requires no changes to your existing network architecture. For security, you must configure inbound and outbound rules and access control policies.	Images are transferred over a private network for higher security. No fees are incurred if the VPCs are in the same region. This method requires that the two VPCs have non-overlapping CIDR blocks. If there is a significant overlap in the CIDR blocks already in use, you may need to redesign your existing network architecture.	Images are transferred over a private network for higher security. CEN is designed for enterprise production environments with high security requirements.
Configuration procedure	Configure a public endpoint for the ACR instance Configure a public access control policy to remotely and securely manage and access the ACR Enterprise Edition instance. Enable public network access for the ACK cluster Configure public network access for the ACK cluster to pull images from the ACR Enterprise Edition instance.	Enable private domain name resolution for the ACR instance After you connect the ACR Enterprise Edition instance to the VPC, you can access the instance within the VPC by using its private domain name. After the configuration, obtain the VPC ID and the private IP address of the ACR Enterprise Edition instance. Obtain the domain name and IP address of the ACR instance Obtain the domain name and IP address of the authentication service used to access the ACR Enterprise Edition instance, and the domain name and IP address of the associated OSS bucket. Create a VPC peering connection and configure a route table You must add route entries that point to the peer VPC at both ends of the VPC peering connection to enable private communication between the VPCs for the ACK cluster and the ACR Enterprise Edition instance. At the ACK cluster's end of the VPC peering connection, you must also configure route entries for the IP address of the authentication service and the IP address of the associated OSS bucket. Resolve the ACR instance domain name for the ACK cluster Use methods such as adding a private DNS record or using a node pool custom data script to batch modify the `/etc/hosts` file. This resolves the ACR instance's domain name to its private IP address, allowing the ACK cluster to forward traffic to the ACR instance's VPC through the configured route entries.	Enable private domain name resolution for the ACR instance After you connect the ACR Enterprise Edition instance to the VPC, you can access the instance within the VPC by using its private domain name. After the configuration, obtain the VPC ID and the private IP address of the ACR Enterprise Edition instance. Obtain the domain name and IP address of the ACR instance Obtain the domain name and IP address of the authentication service used to access the ACR Enterprise Edition instance, and the domain name and IP address of the associated OSS bucket. Configure cross-account VPC communication by using CEN Connect the VPC of the ACR Enterprise Edition instance to the transit router in its region. Connect the VPC of the ACK cluster to the transit router in its region. Then, use a cross-region connection to enable communication between the two transit routers. Configure VPC and transit router route tables In the route tables for the ACK cluster's VPC and transit router, you must also configure route entries for the IP address of the authentication service and the IP address of the associated OSS bucket. Resolve the ACR instance domain name for the ACK cluster Use methods such as adding a private DNS record or using a node pool custom data script to batch modify the `/etc/hosts` file. This step resolves the ACR instance domain name to its private IP address for the ACK cluster, allowing traffic to be forwarded to the ACR instance's VPC through the CEN route entries.

Step 2: Configure authorization and password-free component

The following three authorization methods allow you to pull images across accounts without using static credentials. Choose the method that best fits your requirements.

Comparison item	RRSA	Worker RAM role	RAM user AccessKey
Cluster type	Supports ACK Basic clusters, ACK Pro clusters, ACK Edge clusters, and ACK Serverless Pro clusters of v1.22 and later.	Supports ACK Basic clusters, ACK Pro clusters, and ACK dedicated clusters of v1.20 and later.	Supports ACK Basic clusters, ACK Pro clusters, and ACK dedicated clusters of v1.20 and later.
Supported components	aliyun-acr-credential-helper managed component aliyun-acr-credential-helper component Must be upgraded to v23.02.06.1-74e2172-aliyun or later. For more information about the differences between these components, see Comparison of password-free components.	aliyun-acr-credential-helper component	aliyun-acr-credential-helper component
Permission granularity	Pod-level (fine-grained)	Cluster-level (medium-grained)	Account-level (coarse-grained)
Security	High. This method provides fine-grained permission control and isolation. It uses temporary credentials from STS (Security Token Service) and avoids hard-coding AccessKey pairs.	Medium. All Pods share the same permissions, which can lead to excessive privileges.	Low. High risk of AccessKey pair leakage.
Applicable scenarios	Suitable for security-sensitive services and production environments that require strict permission control.	Suitable for scenarios with uniform permission requirements, such as development and test environments that need moderate permission control.	Suitable for quick deployments or demo environments.

RRSA

In the ACK cluster under Account A, you configure a specific ServiceAccount to assume a RAM role from Account B. This RAM role is granted the necessary permissions, allowing the ACK cluster to pull private images from the ACR instance in Account B without using static credentials.

Note

To enable the RRSA (RAM Roles for Service Accounts) feature for the password-free component, you must first enable RRSA for the cluster and then configure RRSA for the component. If you perform these steps in the wrong order, you must delete the Pod of the password-free component to activate the RRSA feature.

Under Account A, enable the RRSA feature for the ACK cluster and create a RAM role with role assumption permissions.
1. Enable the RRSA feature for the ACK cluster.
  1. Log on to the ACK console. In the left navigation pane, click Clusters.
  2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Cluster Information.
  3. On the Basic Information tab, in the Security and Auditing section, click Enable next to RRSA OIDC.
  4. In the Enable RRSA dialog box, click Confirm. Wait for the cluster status to change from Updating to Running. RRSA is now enabled.
  5. After RRSA is enabled, hover over the Enabled label next to RRSA OIDC in the Security and Auditing section. The URL and Alibaba Cloud Resource Name (ARN) of the OIDC provider are displayed.
2. Create a RAM role for an OIDC identity provider and update its trust policy with the following content.
  - Replace <oidc_issuer_url> with the OIDC provider URL that you obtained in the previous step.
  - Replace <oidc_provider_arn> with the OIDC provider ARN that you obtained in the previous step.
```
{
  "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"
}
```
3. Attach the AliyunSTSAssumeRoleAccess permission policy to the role to grant role assumption permissions, and then record its ARN. For more information, see Manage permissions for a RAM role.
  1. On the role details page, on the Authorization tab, click Authorize.
  2. In the Authorize panel, under Policies, find and select the AliyunSTSAssumeRoleAccess policy, and then click OK.
  3. On the role details page, in the Basic Information section, view and record the RAM role's ARN. For detailed instructions, see How do I view the ARN of a RAM role?
Under Account B, create a RAM role with permissions to pull private images, and configure it to be assumable by the RAM role from Account A.
1. Create a RAM role for a trusted Alibaba Cloud account. Edit the trust policy with the following script to allow role assumption by the role from Account A.
```
{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "<ARN of the role created in Account A>"
        ]
      }
    }
  ],
  "Version": "1"
}
```
2. Create a custom permission policy with the following content and attach it to the RAM role to grant permissions to get instance information and pull images.
```
{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "cr:GetAuthorizationToken",
                "cr:ListInstanceEndpoint",
                "cr:PullRepository"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}
```
3. Set the maximum session duration for the RAM role to a value between 3,600 and 43,200 seconds. The default is 3,600 seconds.
  
  Ensure this value matches the expireDuration parameter in the component configuration described later. The value of expireDuration cannot exceed the maximum session duration.
4. On the role details page, in the Basic Information section, view and record the RAM role's ARN.

Under Account A, install the password-free component for the ACK cluster and modify its configuration.

For more information about the differences between the following components, see Comparison of password-free components.

Managed component

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click Add-ons .
On the Add-ons page, click the Security tab, find the aliyun-acr-credential-helper (managed) card, and then click Install.

In the aliyun-acr-credential-helper Parameter Configuration dialog box, select Enable RRSA. Then, click Add, enter the following parameters, and click Confirm.

ACR Enterprise Edition instance configuration:

Parameter	Description	Example
instanceId	The ID of the ACR instance. To specify multiple IDs, separate them with commas (,).	cri-XXXXX
regionId	The region ID of the ACR instance.	cn-hangzhou
domains	The domain names used to access the ACR instance. Enter all access domain names (public and VPC) for the ACR instance. To specify specific domain names, separate them with commas (,).	XXXXX-registry.cn-hangzhou.cr.aliyuncs.com
assumeRoleARN	The ARN of the RAM role that you created in Account B.	acs:ram::100XXXXXXXX9630:role/XXXX
expireDuration	The validity period of the temporary credentials for cross-account access. Enter the maximum session duration of the RAM role that you created under Account B.	3600
rrsaRoleARN	The ARN of the RAM role that you created in Account A.	acs:ram::128XXXXXXXXXX09011:role/XXXX
rrsaOIDCProviderRoleARN	The provider ARN of the ACK cluster. Enter the provider ARN of the RRSA OIDC identity provider for the ACK cluster under Account A.	acs:ram::128XXXXXXXXXX09011:oidc-provider/ack-rrsa-c8864XXXXXXXXXXXXXXXXXX99356a636

For information about other parameters, see Component configuration.

aliyun-acr-credential-helper

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click Add-ons .
On the Add-ons page, click the Security tab, find the aliyun-acr-credential-helper component, and click Install. In the dialog box that appears, set the tokenMode option to auto, and then click OK.

Modify the ConfigMap of the password-free component.

In the left-side navigation pane, choose Configurations > ConfigMaps.

On the ConfigMaps page, select kube-system from the Namespace drop-down list. Then, find acr-configuration and click Edit YAML in the **Actions** column. Update the configuration based on the following example.

data:
  service-account: "default"
  watch-namespace: "all"
  expiring-threshold: "15m"
  notify-email: "c*@example.com"
  acr-registry-info: |
    - instanceId: "cri-xxx"                                   # ACR instance ID.
      regionId: "cn-hangzhou"                                 # ACR instance region ID.
      domains: "xxxxx-registry.cn-hangzhou.cr.aliyuncs.com"   # ACR instance access domain name.
      rrsaRoleARN: "<ARN of the role created under Account A>"
      rrsaOIDCProviderRoleARN: "<OIDC Provider ARN from the cluster's Basic Information page in the ACK console under Account A>"
      assumeRoleARN: "<ARN of the role created under Account B>"
      expireDuration: 3600                                    # Maximum session duration for the RAM role under Account B. Default: 3600.             
  rrsa: |
    enable: true                                              # Enable the RRSA feature for the password-free component.

Worker RAM role

In the ACK cluster under Account A, configure the cluster's default Worker RAM role to assume a RAM role from Account B that has permissions to pull images. This allows the ACK cluster to access and pull private images from Account B.

Under Account A, view the cluster's Worker RAM role and grant it role assumption permissions.
1. Log on to the ACK console. In the left navigation pane, click Clusters.
2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Cluster Information.
3. On the Cluster Information page, click the Basic Information tab. In the Cluster Resources section, click the link to the right of Worker RAM Role.
4. Attach the AliyunSTSAssumeRoleAccess permission policy to the role to grant role assumption permissions, and then record its ARN. For more information, see Manage permissions for a RAM role.
  1. On the role details page, on the Authorization tab, click Authorize.
  2. In the Authorize panel, under Policies, find and select the AliyunSTSAssumeRoleAccess policy, and then click OK.
  3. On the role details page, in the Basic Information section, view and record the RAM role's ARN. For detailed instructions, see How do I view the ARN of a RAM role?
Under Account B, create a RAM role with permissions to pull private images, and configure it to be assumable by the Worker RAM role of the ACK cluster in Account A.
1. Create a RAM role for a trusted Alibaba Cloud account.
2. Create a custom permission policy with the following content and attach it to the RAM role to grant permissions to get instance information and pull images.
```
{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "cr:GetAuthorizationToken",
                "cr:ListInstanceEndpoint",
                "cr:PullRepository"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}
```
3. On the RAM role's details page, click the Trust Policy tab and Edit Trust Policy with the following content. This allows the Worker RAM role of the ACK cluster in Account A to assume the RAM role in Account B.
```
{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "<ARN of the role created under Account A>"
        ]
      }
    }
  ],
  "Version": "1"
}
```
4. On the role details page, in the Basic Information section, view and record the RAM role's ARN. For detailed instructions, see How do I view the ARN of a RAM role?
Under Account A, install the password-free component for the ACK cluster and modify its configuration.
1. Log on to the ACK console. In the left navigation pane, click Clusters.
2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Add-ons .
3. On the Add-ons page, click the Security tab, find the aliyun-acr-credential-helper component, and click Install. In the dialog box that appears, set the tokenMode option to workerRole, and then click Confirm.
4. Modify the ConfigMap of the password-free component.
  1. In the left-side navigation pane, choose Configurations > ConfigMaps.
  2. On the ConfigMaps page, select kube-system from the Namespace drop-down list. Then, find acr-configuration and click Edit YAML in the **Actions** column. Update the configuration based on the following example.
```
data:
    service-account: "default"
    watch-namespace: "all"
    expiring-threshold: "15m"
    notify-email: "c*@example.com"
    acr-registry-info: |
      - instanceId: "cri-xxx"                                    # ACR Enterprise Edition instance ID.
        regionId: "cn-hangzhou"                                  # ACR Enterprise Edition region ID.
        domains: "xxxxx-registry.cn-hangzhou.cr.aliyuncs.com"    # ACR Enterprise Edition access domain name.
        assumeRoleARN: "<ARN of the role created under Account B>"
        expireDuration: 3600                                     # Maximum session duration for the RAM role under Account B. Default: 3600.
```

RAM user AccessKey

In the ACK cluster under Account A, the password-free component stores the AccessKey ID (AK) and AccessKey Secret (SK) of a RAM user from Account B to pull private images from Account B. Although this method is simple to configure, it poses a security risk because the AccessKey pair is stored in plaintext.

Under Account B, create a RAM user and ensure it has the necessary cr.* permissions.
1. Create a RAM user.
2. Create a custom permission policy with the following content and attach it to the RAM user to grant permissions to get instance information and pull images.
```
{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "cr:GetAuthorizationToken",
                "cr:ListInstanceEndpoint",
                "cr:PullRepository"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}
```
3. Create an AccessKey pair and record the AccessKey ID and AccessKey Secret.
Under Account A, install the password-free component for the ACK cluster and modify its configuration.
1. Log on to the ACK console. In the left navigation pane, click Clusters.
2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Cluster Information.
3. On the Clusters page, click the name of your cluster. In the left navigation pane, click Add-ons .
4. On the Add-ons page, click the Security tab, find the aliyun-acr-credential-helper component, and click Install. In the dialog box that appears, set the tokenMode option to auto, and then click OK.
5. Modify the ConfigMap of the password-free component.
  1. In the left-side navigation pane, choose Configurations > ConfigMaps.
  2. On the ConfigMaps page, select kube-system from the Namespace drop-down list. Then, find acr-configuration and click Edit YAML in the **Actions** column. Update the configuration based on the following example.

Step 3: Verify cross-account image pulling

Note

This verification process is for demonstration only. For detailed instructions, see Build an image and Create a workload.

In the ACR Enterprise Edition instance under Account B, obtain the Public endpoint or VPC address of the container image as needed.

Navigate to the Basic Information page of the target image repository. The endpoint addresses are available on the right side of the page.

In the ACK cluster under Account A, navigate to Workloads > Deployments and create a workload by using the container image.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment-basic
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: ******.cn-hangzhou.cr.aliyuncs.com/instance/instancetest:v1 # Specify the ACR image address from Account B 
        ports:
        - containerPort: 80

A Pod event with the message Successfully pulled image "XXX" in XXXs (XXXs including waiting). Image size: XXX bytes. indicates that the password-free component successfully pulled the image across accounts.

On the workload's details page, on the Pods tab, confirm that the Pod status is **Running** and the **Image** column displays the cross-account image repository address, such as test332-registry.cn-hangzhou.cr.aliyuncs.com/instance/test:v1.

FAQ

Resolve IP conflicts in the 100.0.0.0/8 CIDR block

The authentication and OSS domain IPs resolve to the 100.0.0.0/8 CIDR block. If your internal network uses this range, IP conflicts will occur.

Authentication domain name conflict

Resolve this conflict by enabling the instance to take over the authentication domain. This lets you access the service using only the instance domain name.

Log on to the Container Registry console.
In the top navigation bar, select a region.
On the Instances page, click the Enterprise Edition instance that you want to manage.
In the navigation pane on the left of the instance management page, choose Repository > Domain. On the Domain page, turn on the Instance Taking over Authentication Domain Name switch.
Important
To enable authentication domain takeover, you must submit a ticket to add your Enterprise Edition instance to the allowlist.
In the Confirm to Enable Instance Taking over Authentication Domain Name dialog box, click Confirm.

OSS domain name conflict

To resolve this conflict, access OSS resources over a private network by using PrivateLink, then point the OSS domain name to the PrivateLink domain name with a CNAME record.