All Products
Search

This Product

    Container Registry:Pull images across accounts

    Document Center

    Container Registry:Pull images across accounts

    Last Updated:Mar 26, 2026

    When an ACK cluster and an ACR Enterprise Edition instance belong to different Alibaba Cloud accounts, the cluster must establish network connectivity to the instance and obtain the required permissions before it can pull images. This topic describes how to use the aliyun-acr-credential-helper passwordless component to pull container images across accounts without storing credentials in pod specs.

    In this topic, *cross-account* refers to different Alibaba Cloud accounts, not RAM users.

    Prerequisites

    Before you begin, ensure that you have:

    • Granted the required permissions to the RAM role used by the passwordless component

    • An ACK cluster that supports the passwordless component:

      • aliyun-acr-credential-helper (managed): ACK managed clusters, ACK serverless clusters, and ACK Edge clusters running Kubernetes 1.22 or later

      • aliyun-acr-credential-helper (self-managed): ACK managed clusters and ACK dedicated clusters running Kubernetes 1.20 or later

    • An ACR 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 the passwordless component is not available for your setup, see How do I use imagePullSecrets?.

    How it works

    The setup involves three steps:

    1. Configure network connectivity — connect the ACK cluster's VPC to the ACR instance's VPC

    2. Configure account authorization and the passwordless component — grant the cluster permission to pull images from the other account

    3. Verify cross-account image pulling — deploy a test workload to confirm everything works

    The diagram below shows the available network connectivity options and authorization methods, and how to select the right combination for your setup.

    image

    Step 1: Configure network connectivity

    The ACK cluster and ACR instance are in separate VPCs and separate accounts. Before pulling images, establish network connectivity and ensure domain name resolution works. Three options are available:

    Public networkVPC peeringCloud Enterprise Network (CEN)
    Network typePublicPrivatePrivate
    CostEIP fees + data transfer fees (billing details)Free (same region); CDT data transfer fees (cross-region)CEN billing rules
    Key constraintNo architecture changes needed; configure access control for securityVPCs must have non-overlapping CIDR blocksDesigned for enterprise environments with high security requirements

    For a detailed comparison of VPC peering and CEN, see What are the differences between CEN and VPC peering connections?

    Public network

    Configure a public endpoint for the ACR instance and enable public network access for the ACK cluster. Images transfer over the public internet, so apply access control policies to restrict exposure.

    1. Configure a public endpoint for the ACR instance

    2. Enable public network access for the ACK cluster

    VPC peering

    Connect the ACK cluster's VPC to the ACR instance's VPC through a VPC peering connection. This routes image traffic over a private network. The two VPCs must have non-overlapping CIDR blocks.

    1. Attach a VPC to the ACR instance for internal same-region endpoint resolution — after attaching, record the VPC ID and internal IP address of the ACR instance

    2. Obtain the domain names and IP addresses related to the ACR instance — record the authentication service domain name and IP address, and the associated OSS bucket domain name and IP address

    3. Create a VPC peering connection and configure a route table — add routes pointing to the peer VPC at each end; at the ACK cluster end, also add routes for the authentication service IP and OSS bucket IP

    4. Resolve the ACR instance domain name for the ACK cluster — add an internal DNS resolution record or use a node pool custom data script to update /etc/hosts in bulk, mapping the ACR instance domain name to its internal IP address

    Cloud Enterprise Network

    Use CEN transit routers to connect the two VPCs across accounts and regions. This is the recommended option for production environments with strict security requirements.

    1. Attach the ACR instance's VPC to a transit router in the ACR account's region — record the VPC ID and internal IP address of the ACR instance

    2. Obtain the domain names and IP addresses related to the ACR instance — record the authentication service domain name and IP address, and the associated OSS bucket domain name and IP address

    3. Configure a cross-account VPC-to-VPC connection using CEN — connect each account's VPC to a transit router in its region, then link the two transit routers with an inter-region connection

    4. Configure the route tables of the VPC and transit router — at the ACK cluster end, add routes for the authentication service IP and OSS bucket IP

    5. Resolve the ACR instance domain name for the ACK cluster — add an internal DNS resolution record or use a node pool custom data script to update /etc/hosts in bulk, mapping the ACR instance domain name to its internal IP address

    Step 2: Configure account authorization and the passwordless component

    Three authorization methods are available. Choose based on your security requirements and cluster type.

    RRSAWorker RAM role assumptionAccessKey pair
    Permission granularityPod-level (fine-grained)Cluster-levelAccount-level (coarse-grained)
    SecurityHigh — uses STS temporary credentials with no hard-coded AccessKey pairsMedium — all pods share permissionsLow — AccessKey ID and secret stored in plaintext
    Best forProduction environments requiring strict permission controlDev and staging environments requiring unified permissionsQuick demos and non-production deployments
    Supported clustersACK managed (Basic/Pro), ACK Edge, ACK serverless Pro — Kubernetes 1.22+ACK managed (Basic/Pro), ACK dedicated — Kubernetes 1.20+ACK managed (Basic/Pro), ACK dedicated — Kubernetes 1.20+
    Supported componentsaliyun-acr-credential-helper (managed) or aliyun-acr-credential-helper v23.02.06.1-74e2172-aliyun+aliyun-acr-credential-helperaliyun-acr-credential-helper

    For details on component differences, see Passwordless component comparison.

    Use RRSA

    RAM Roles for Service Accounts (RRSA) lets a specific ServiceAccount in the ACK cluster (Account A) assume a RAM role in Account B to pull private images. This is the highest-security option — it uses STS temporary credentials scoped to the individual pod.

    Enable RRSA in the cluster before configuring RRSA for the passwordless component. If you configure the component first, delete the passwordless plug-in pod to activate RRSA.
    image

    Step 2.1 — In Account A: Enable RRSA and create a RAM role with assume-role permissions

    1. Log on to the ACK console and click Clusters in the left navigation pane.

    2. Click the target cluster name. In the left navigation pane, click Cluster Information.

    3. On the Basic Information tab, find the Security and Auditing section, and click Enable next to RRSA OIDC.

      image

    4. In the Enable RRSA dialog box, click Confirm. Wait until the cluster status changes from Updating to Running.

    5. On the Basic Information tab, hover over Enabled next to RRSA OIDC to view the OIDC provider URL and ARN (Alibaba Cloud Resource Name). Record both values — you will need them in the next step.

      image

    6. Use the script editor to edit the trust policy and create a RAM role for an OIDC IdP. Replace the placeholders with the OIDC provider URL and ARN from the previous step. Trust policy for the RAM role in Account A

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

    7. Attach the AliyunSTSAssumeRoleAccess policy to the role. See Grant permissions to a RAM role.

      1. On the role details page, click the Permissions tab, then click Grant Permission.

      2. In the Grant Permission panel, select the AliyunSTSAssumeRoleAccess access policy and click OK.

    8. On the role details page, record the ARN from the Basic Information section. See How do I view the ARN of a RAM role?

    Step 2.2 — In Account B: Create a RAM role and grant Account A permission to assume it

    1. Use the script editor to edit the trust policy and create a RAM role for a trusted Alibaba Cloud account. This allows Account A to assume the role. Trust policy for the RAM role in Account B

      {
  "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 grant it to the RAM role. This grants permission to get instance information and pull images. Custom policy for the RAM role in Account B

      {
    "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 (default: 3,600). Record this value — the expireDuration parameter you configure later must not exceed it.

    4. On the role details page, record the ARN from the Basic Information section.

    Step 2.3 — In Account A: Install the passwordless component and apply the configuration

    For component differences, see Passwordless component comparison.

    aliyun-acr-credential-helper (managed)

    1. Log on to the ACK console and click Clusters in the left navigation pane.

    2. Click the target cluster name. In the left navigation pane, click Add-ons.

    3. On the Add-ons page, click the Security tab, find the aliyun-acr-credential-helper (Managed) card, and click Install.

    4. In the Aliyun-acr-credential-helper Parameter Settings dialog box, select the Is RRSA Enabled checkbox, click Add, enter the following parameters, and click OK. For other parameters, see Component configuration.

      ParameterDescriptionExample
      instanceIdACR instance ID. Separate multiple IDs with commas.cri-XXXXX
      regionIdRegion of the ACR instance.cn-hangzhou
      domainsAll endpoints (public and VPC) of the ACR instance. Separate multiple domain names with commas.XXXXX-registry.cn-hangzhou.cr.aliyuncs.com
      assumeRoleARNARN of the RAM role created in Account B (Step 2.2).acs:ram::100XXXXXXXX9630:role/XXXX
      expireDurationValidity period of the temporary credentials, in seconds. Must not exceed the maximum session duration of the RAM role in Account B.3600
      rrsaRoleARNARN of the RAM role created in Account A (Step 2.1).acs:ram::128XXXXXXXXXX09011:role/XXXX
      rrsaOIDCProviderRoleARNARN of the OIDC IdP for the ACK cluster in Account A (Step 2.1).acs:ram::128XXXXXXXXXX09011:oidc-provider/ack-rrsa-c8864XXXXXXXXXXXXXXXXXX99356a636

      791184c653f445f62c3387d88ad8bdcf

    aliyun-acr-credential-helper

    1. Log on to the ACK console and click Clusters in the left navigation pane.

    2. Click the target cluster name. In the left navigation pane, click Add-ons.

    3. On the Add-ons page, click the Security tab, find aliyun-acr-credential-helper, and click Install. In the dialog box, set tokenMode to auto and click OK.

      04479cf3d9857845bf530ea2f0850a60

    4. Update the ConfigMap for the passwordless component.

      1. In the left navigation pane, choose Configuration > ConfigMaps.

      2. At the top of the ConfigMaps page, select kube-system from the Namespace drop-down list.

      3. In the acr-configuration row, click Edit YAML and apply the following configuration.

      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"                                 # Region of the ACR instance
      domains: "xxxxx-registry.cn-hangzhou.cr.aliyuncs.com"   # Endpoint of the ACR instance
      rrsaRoleARN: "<ARN of the RAM role created in Account A>"
      rrsaOIDCProviderRoleARN: "<OIDC IdP ARN of the ACK cluster in Account A>"
      assumeRoleARN: "<ARN of the RAM role created in Account B>"
      expireDuration: 3600   # Must not exceed the maximum session duration of the RAM role in Account B
  rrsa: |
    enable: true             # Enable RRSA for the passwordless component

    Use Worker RAM role assumption

    The Worker RAM role of the ACK cluster in Account A assumes a RAM role in Account B to pull private images. All pods in the cluster share the same cross-account permissions.

    image

    Step 2.1 — In Account A: Grant the Worker RAM role permission to assume roles

    1. Log on to the ACK console and click Clusters in the left navigation pane.

    2. Click the target cluster name. In the left navigation pane, click Cluster Information.

    3. On the Basic Information tab, find the Cluster Resources section and click the link next to Worker RAM Role.

    4. Attach the AliyunSTSAssumeRoleAccess policy to the role and record its ARN. See Grant permissions to a RAM role.

      1. On the role details page, click the Permissions tab, then click Grant Permission.

      2. In the Grant Permission panel, select the AliyunSTSAssumeRoleAccess access policy and click OK.

      3. On the role details page, record the ARN from the Basic Information section. See How do I view the ARN of a RAM role?

    Step 2.2 — In Account B: Create a RAM role and allow Account A's Worker RAM role to assume it

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

    2. Create a custom policy with the following content and grant it to the RAM role. Custom policy for the RAM role in Account B

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

    3. Update the trust policy to allow Account A's Worker RAM role to assume this role. Trust policy for the RAM role in Account B On the role details page, click the Trust Policy tab, click Edit Trust Policy, and apply the following:

      {
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "<ARN of the Worker RAM role in Account A>"
        ]
      }
    }
  ],
  "Version": "1"
}

    4. On the role details page, record the ARN from the Basic Information section. See How do I view the ARN of a RAM role?

    Step 2.3 — In Account A: Install the passwordless component and apply the configuration

    1. Log on to the ACK console and click Clusters in the left navigation pane.

    2. Click the target cluster name. In the left navigation pane, click Add-ons.

    3. On the Add-ons page, click the Security tab, find aliyun-acr-credential-helper, and click Install. In the dialog box, set tokenMode to workerRole and click OK.

      100f8cde3395436575996fbbd290dc56

    4. Update the ConfigMap for the passwordless component.

      1. In the left navigation pane, choose Configuration > ConfigMaps.

      2. At the top of the ConfigMaps page, select kube-system from the Namespace drop-down list.

      3. In the acr-configuration row, click Edit YAML and apply the following configuration.

      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"                                   # Region of the ACR instance
      domains: "xxxxx-registry.cn-hangzhou.cr.aliyuncs.com"    # Endpoint of the ACR instance
      assumeRoleARN: "<ARN of the RAM role created in Account B>"
      expireDuration: 3600   # Must not exceed the maximum session duration of the RAM role in Account B

    Use an AccessKey pair

    The passwordless component in Account A uses the AccessKey ID and AccessKey secret of a RAM user from Account B to pull private images. This is the simplest method to configure but stores credentials in plaintext — use it only for demos or non-production environments.

    Step 2.1 — In Account B: Create a RAM user and get an AccessKey pair

    1. Create a RAM user.

    2. Create a custom policy with the following content and grant it to the RAM user. Custom policy for the RAM user in Account B

      {
    "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.

    Step 2.2 — In Account A: Install the passwordless component and apply the configuration

    1. Log on to the ACK console and click Clusters in the left navigation pane.

    2. Click the target cluster name. In the left navigation pane, click Add-ons.

    3. On the Add-ons page, click the Security tab, find aliyun-acr-credential-helper, and click Install. In the dialog box, set tokenMode to auto and click OK.

      04479cf3d9857845bf530ea2f0850a60

    4. Update the ConfigMap for the passwordless component.

      1. In the left navigation pane, choose Configuration > ConfigMaps.

      2. At the top of the ConfigMaps page, select kube-system from the Namespace drop-down list.

      3. In the acr-configuration row, click Edit YAML and apply the following configuration.

      data:
  service-account: "default"
  watch-namespace: "all"
  expiring-threshold: "15m"
  notify-email: "c*@example.com"
  acr-registry-info: |
    - instanceId: ""                        # ACR Enterprise Edition instance ID
      regionId: "cn-hangzhou"               # Region of the ACR instance
      customAccessKey: "xxxxx"              # AccessKey ID of the RAM user in Account B
      customAccessKeySecret: "xxxxxx"       # AccessKey secret of the RAM user in Account B

    Step 3: Verify cross-account image pulling

    The following procedure is for verification purposes. For production workloads, see Build images and Create a workload.

    1. In the ACR Enterprise Edition instance of Account B, copy the Public Endpoint or VPC address of the container image.

      image

    2. In the ACK cluster of Account A, create a Deployment that references the image from Account B.

      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   # ACR image address from Account B
        ports:
        - containerPort: 80

    3. Check the pod events. If the following message appears, the image was pulled successfully.

      Successfully pulled image "XXX" in XXXs (XXXs including waiting). Image size: XXX bytes.

      ecb56ef14d98a537ebe64f6bd9fd883d

    FAQ

    How do I resolve IP address conflicts in the 100.0.0.0/8 CIDR block?

    When you configure routing rules, the authentication domain name and OSS domain name resolve to IP addresses in the 100.0.0.0/8 CIDR block. If your internal network uses addresses from this range, conflicts may prevent access to the ACR Enterprise Edition instance. The resolution depends on which domain name is affected.

    Authentication domain name conflict

    Enable the instance to take over the authentication domain name. Once enabled, the cluster only needs to reach the instance domain name, which avoids the 100.0.0.0/8 range entirely.

    1. Log on to the Container Registry console.

    2. Log on to the Container Registry console and select a region in the top navigation bar.

    3. On the Instances page, click the Enterprise Edition instance.

    4. In the navigation pane, choose Repository Management > Domain Names.

    5. On the Domain Names page, turn on the Instance Takeover of Authentication Domain Name switch.

      Important

      To use this feature, submit a ticket to add the Enterprise Edition instance to the allowlist first.

    6. In the Confirm Enable Instance Takeover Authentication Domain Name dialog box, click OK.

    OSS domain name conflict

    Access OSS resources over a private network using PrivateLink, then point the CNAME record of the original OSS domain name to the PrivateLink endpoint.