Cross-account image pull using the password-free component - Container Registry

Selection strategy

Choose the network connection and account authorization methods that best suit your business needs. Then, select a credential-free component that supports the chosen authorization method.

For detailed steps, see Configure network connectivity and Configure account authorization and the credential-free component. Then, verify cross-account image pulling.

Note

In this topic, "cross-account" means across different Alibaba Cloud accounts (primary accounts), not RAM users (sub-accounts).

Prerequisites

The RAM role for the passwordless component has the required permissions.
An ACK cluster that supports the passwordless component is available.
- aliyun-acr-credential-helper (managed)
  
  ACK managed clusters, ACK serverless clusters, and ACK Edge clusters that run Kubernetes 1.22 or later
- aliyun-acr-credential-helper (self-managed)
  
  ACK managed clusters and ACK dedicated clusters that run Kubernetes 1.20 or later
An ACR Enterprise Edition instance is available.
Important
- The passwordless component supports only ACR Enterprise Edition instances and 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 connectivity

When you pull images across accounts, the ACK cluster that pulls the images and the ACR Enterprise Edition instance that stores them are in different VPCs under separate Alibaba Cloud accounts, and may also be in different regions. Before you pull an image, you must establish network connectivity and ensure that the required domain names are resolvable. 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 then transferred over the public network. However, this method is less secure and incurs costs for the Elastic IP Address and network 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 service is free if the VPCs are in the same region but incurs charges if they are in different regions. However, the CIDR blocks of the two VPCs cannot overlap. If the CIDR blocks of the VPCs have significant overlaps, you must modify your existing network architecture.
Cloud Enterprise Network connection: A Cloud Enterprise Network instance can contain one or more transit routers. You can use an inter-region connection to connect multiple transit routers to enable inter-region and cross-account VPC communication.

For a comparison between vpc peering connections and Cloud Enterprise Network, see What is the difference between Cloud Enterprise Network and VPC Peering Connection?

Item	Public connection	VPC peering connection	Cloud Enterprise Network
Network type	Public network	Private network	Private network
Billing	Fees are incurred based on the billing of Elastic IP Address.	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 for outbound traffic.	Fees are incurred based on the billing rules of Cloud Enterprise Network.
Key features	You do not need to modify 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. The CIDR blocks of the two VPCs must not overlap. If there are significant overlaps, you must modify your existing network architecture.	Images are transferred over a private network for higher security. Cloud Enterprise Network is designed for enterprise production environments with high security requirements.
Configuration procedure	Configure a public endpoint for an 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 an ACK cluster Configure the ACK cluster to access external public resources and pull images from the ACR Enterprise Edition instance.	Enable private domain name resolution for an ACR instance After you connect the ACR Enterprise Edition instance to a VPC, you can access the instance from within the VPC by using a private domain name. After the configuration, obtain the VPC ID and the private IP address of the ACR Enterprise Edition instance. Obtain the domain names and IP addresses related to the ACR instance Obtain the domain name and IP address of the authentication service and the associated OSS bucket that are used to access the ACR Enterprise Edition instance. Create a vpc peering connection and configure a route table You need to add routes that point to the peer VPC at both ends of the vpc peering connection to enable private communication between the VPC of the ACK cluster and the VPC of the ACR Enterprise Edition instance. On the ACK cluster side of the peering connection, you must also configure routes to the IP address of the authentication service and the IP address of the associated OSS bucket. Configure DNS resolution for the ACR instance domain name in the ACK cluster Use methods such as adding a private DNS record or using a custom data script for a node pool to batch modify the `/etc/hosts` file. This resolves the ACR instance domain name to its private IP address for the ACK cluster. Traffic is then forwarded to the VPC of the ACR instance through the routes of the vpc peering connection.	Enable private domain name resolution for an ACR instance After you connect the ACR Enterprise Edition instance to a VPC, you can access the instance from within the VPC by using a private domain name. After the configuration, obtain the VPC ID and the private IP address of the ACR Enterprise Edition instance. Obtain the domain names and IP addresses related to the ACR instance Obtain the domain name and IP address of the authentication service and the associated OSS bucket that are used to access the ACR Enterprise Edition instance. 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 an inter-region connection to connect the two transit routers. Configure route tables for the VPC and transit router You must also configure routes to the IP address of the authentication service and the IP address of the associated OSS bucket for the VPC and transit router of the ACK cluster. Configure DNS resolution for the ACR instance domain name in the ACK cluster Use methods such as adding a private DNS record or using a custom data script for a node pool to batch modify the `/etc/hosts` file. This resolves the ACR instance domain name to its private IP address for the ACK cluster. Traffic is then forwarded to the VPC of the ACR instance through the CEN routes.

Step 2: Configure authorization and the credential-free component

The following three authorization methods enable credential-free image pulling across accounts. Choose the method that best suits your requirements.

Item	RRSA	Worker RAM role	RAM user AccessKey
Supported cluster types	Supports ACK Basic managed clusters, ACK Pro managed clusters, ACK Edge clusters, and ACK Serverless Pro clusters running Kubernetes 1.22 or later.	Supports ACK Basic managed clusters, ACK Pro managed clusters, and ACK dedicated clusters running Kubernetes 1.20 or later.	Supports ACK Basic managed clusters, ACK Pro managed clusters, and ACK dedicated clusters running Kubernetes 1.20 or later.
Supported components	aliyun-acr-credential-helper (Managed) add-on aliyun-acr-credential-helper component You must upgrade the component to v23.02.06.1-74e2172-aliyun or later. For more information about the differences between these components, see Comparison of credential-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. Provides fine-grained permission control and isolation. It uses temporary credentials from Security Token Service (STS) without hard-coded AccessKey ID and AccessKey Secret pairs.	Medium. All pods share the same permissions, which may pose a risk of excessive permissions.	Low. High risk of AccessKey leakage.
Use cases	Suitable for security-sensitive services and production environments that require strict permission control.	Suitable for scenarios that require unified permissions and for development and testing environments that require a moderate level of permission control.	Suitable for rapid deployment or demo environments.

RRSA

In the ACK cluster of Account A, configure a specific ServiceAccount to assume a RAM role of Account B with permissions for credential-free image pulling. This allows the ACK cluster to access and pull private images from Account B.

Note

To enable the RRSA feature for the credential-free component, you must first enable RRSA for the cluster and then configure RRSA for the credential-free component. If you perform these steps in the wrong order, you must delete the pods of the component to activate the RRSA feature.

In Account A, enable the RRSA feature for your ACK cluster and create a RAM role that has permission to assume a role.
1. Enable the RRSA feature for your 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, find the Security and Auditing section, and next to RRSA OIDC, click Enable.
  4. In the Enable RRSA dialog box, click OK.
    
    In the Basic Information section, wait for the cluster status to change from Updating to Running. When the status changes to Running, RRSA is enabled.
  5. After RRSA is enabled for a cluster, go to the Basic Information tab. In the Security and Auditing section, hover over Enabled to the right of RRSA OIDC to view the URL and ARN of the OIDC provider.
2. Use the following JSON to edit the trust policy and create a RAM role for an OIDC provider.
  - Replace <oidc_issuer_url> with the OIDC provider URL of your cluster that you obtained in the preceding step.
  - Replace <oidc_provider_arn> with the OIDC provider ARN of your cluster that you obtained in the preceding 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 policy to the RAM role to grant it permissions to assume other roles, and then record the ARN of the RAM role. For more information, see Grant permissions to a RAM role.
  1. On the details page of the RAM role, click the Authorization tab and then click Authorize.
  2. In the Authorize panel, in the Policies section, find and select the AliyunSTSAssumeRoleAccess policy, and then click OK.
  3. On the details page of the RAM role, go to the Basic Information section to view and record the ARN of the RAM role. For more information, see View the ARN of a RAM role.
In Account B, create a RAM role, grant it permissions to pull private images, and configure its trust policy to allow the RAM role from Account A to assume it.
1. Create a RAM role for a trusted Alibaba Cloud account and use the following JSON to edit the trust policy. This allows the RAM role in Account A to assume this role.
```
{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "<ARN of the RAM role created in Account A>"
        ]
      }
    }
  ],
  "Version": "1"
}
```
2. Create a custom policy with the following content and attach the policy to the RAM role to grant it permissions to obtain 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 value is 3,600 seconds.
  
  We recommend that you set this value to be the same as the expireDuration parameter in the component configuration described later. The value of expireDuration cannot exceed the maximum session duration.
4. On the details page of the RAM role, go to the Basic Information section to view and record the ARN of the RAM role.

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

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

Managed add-on

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 Parameters dialog box, select Enable RRSA, click Add, enter the following parameters, and then click Confirm.

791184c653f445f62c3387d88ad8bdcf

Associated ACR Enterprise Edition instance configuration:

Parameter	Description	Example
instanceId	The ID of the ACR Enterprise Edition instance. To specify multiple IDs, separate them with commas (,).	cri-XXXXX
regionId	The region ID of the ACR Enterprise Edition instance.	cn-hangzhou
domains	The access domain names (public and VPC) for the ACR instance. Separate multiple domain names with commas (,).	XXXXX-registry.cn-hangzhou.cr.aliyuncs.com
assumeRoleARN	The ARN of the RAM role that belongs to the owner of the ACR instance. Enter 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 in Account B.	3600
rrsaRoleARN	The ARN of the RAM role that belongs to the owner of the ACK cluster. Enter the ARN of the RAM role that you created in Account A.	acs:ram::128XXXXXXXXXX09011:role/XXXX
rrsaOIDCProviderRoleARN	The ARN of the OIDC provider for the ACK cluster. Enter the OIDC provider ARN of the RRSA feature for the ACK cluster in Account A.	acs:ram::128XXXXXXXXXX09011:oidc-provider/ack-rrsa-c8864XXXXXXXXXXXXXXXXXX99356a636

For information about other parameters, see Component configuration.

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 component, and then click Install. In the dialog box that appears, set tokenMode to auto and click OK.

Modify the ConfigMap of the credential-free component.

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

On the ConfigMaps page, select kube-system from the Namespace drop-down list at the top. Then, find acr-configuration and click Edit YAML in the Actions column. Modify 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"                                   # ID of the ACR Enterprise Edition instance.
      regionId: "cn-hangzhou"                                 # Region ID of the ACR Enterprise Edition instance.
      domains: "xxxxx-registry.cn-hangzhou.cr.aliyuncs.com"   # Access domain name of the ACR Enterprise Edition instance.
      rrsaRoleARN: "<ARN of the RAM role created in Account A>"
      rrsaOIDCProviderRoleARN: "<OIDC provider ARN from the Basic Information page of the cluster in the ACK console for Account A>"
      assumeRoleARN: "<ARN of the RAM role created in Account B>"
      expireDuration: 3600                                    # Maximum session duration for the RAM role in Account B. The default value is 3600.
  rrsa: |
    enable: true                                              # Enable the RRSA feature for the credential-free component.

Worker RAM role

In the ACK cluster of Account A, configure the default worker RAM role of the cluster to assume a RAM role of Account B with permissions for credential-free image pulling. This allows the ACK cluster to access and pull private images from Account B.

In Account A, view the worker RAM role of the cluster and grant it permissions to assume another role.
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 policy to the RAM role to grant it permissions to assume other roles, and then record the ARN of the RAM role. For more information, see Grant permissions to a RAM role.
  1. On the details page of the RAM role, click the Authorization tab and then click Authorize.
  2. In the Authorize panel, in the Policies section, find and select the AliyunSTSAssumeRoleAccess policy, and then click OK.
  3. On the details page of the RAM role, go to the Basic Information section to view and record the ARN of the RAM role. For more information, see View the ARN of a RAM role.
In Account B, create a RAM role, grant it permissions to pull private images, and configure its trust policy to allow the worker RAM role of the ACK cluster in Account A to assume it.
1. Create a RAM role for a trusted Alibaba Cloud account.
2. Create a custom policy with the following content and attach the policy to the RAM role to grant it permissions to obtain instance information and pull images.
```
{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "cr:GetAuthorizationToken",
                "cr:ListInstanceEndpoint",
                "cr:PullRepository"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}
```
3. On the details page of the RAM role, 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 in Account A>"
        ]
      }
    }
  ],
  "Version": "1"
}
```
4. On the details page of the RAM role, go to the Basic Information section to view and record the ARN of the RAM role. For more information, see View the ARN of a RAM role.
In Account A, install the credential-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 then click Install. In the dialog box that appears, set tokenMode to workerRole and click Confirm.
4. Modify the ConfigMap of the credential-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 at the top. Then, find acr-configuration and click Edit YAML in the Actions column. Modify 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"                                    # ID of the ACR Enterprise Edition instance.
        regionId: "cn-hangzhou"                                  # Region ID of the ACR Enterprise Edition instance.
        domains: "xxxxx-registry.cn-hangzhou.cr.aliyuncs.com"    # Access domain name of the ACR Enterprise Edition instance.
        assumeRoleARN: "<ARN of the RAM role created in Account B>"
        expireDuration: 3600                                     # Maximum session duration for the RAM role in Account B. The default value is 3600.
```

RAM user AccessKey

In the ACK cluster of Account A, the credential-free component stores the AccessKey ID and AccessKey Secret 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, which can lead to credential leakage.

In Account B, create a RAM user and ensure that the user has the required cr.* permissions.
1. Create a RAM user.
2. Create a custom policy with the following content and attach the policy to the RAM user to grant it permissions to obtain 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.
In Account A, install the credential-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 then click Install. In the dialog box that appears, set tokenMode to auto and click OK.
5. Modify the ConfigMap of the credential-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 at the top. Then, find acr-configuration and click Edit YAML in the Actions column. Modify the configuration based on the following example.

Step 3: Verify cross-account image pulling

Note

The verification procedure is for demonstration purposes only. For detailed instructions, see Build an image and Create a workload.

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

In the ACK cluster of Account A, choose Workloads > Deployments and use the container image to create a workload.

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 address of the ACR image in Account B.
        ports:
        - containerPort: 80

If the pod events for the workload contain a message similar to Successfully pulled image "XXX" in XXXs (XXXs including waiting). Image size: XXX bytes., it indicates that the credential-free component successfully pulled the image across accounts.

FAQ

IP conflicts in the 100.0.0.0/8 CIDR block

The IP addresses for the authentication and OSS domains resolve to the 100.0.0.0/8 CIDR block. If your internal network also uses this range, IP address conflicts will occur.

Authentication domain name conflict

You can resolve the authentication domain conflict by enabling the instance to take over the authentication domain. This allows you to access the service by 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 use the instance takeover feature for the authentication domain, 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

You can access OSS resources over a private network by using PrivateLink, and then point the OSS domain name to the PrivateLink domain name by using a CNAME record.