Container Registry:Use the passwordless component to pull images from an ACR Enterprise Edition instance within the same account

Step 1: Install the component

1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

2. On the Clusters page, click the name of the target cluster. In the left-side 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. On the Install aliyun-acr-credential-helper page, review the AcrInstanceInfo configuration and other options. AcrInstanceInfo holds the configuration for each ACR instance associated with the component. If you do not need to change the monitored namespaces or service accounts, keep the default settings.

   After installation, update the configuration at any time by clicking Configuration on the aliyun-acr-credential-helper (Managed) card on the Add-ons page.

   AcrInstanceInfo parameters:

   Parameter	Description
   InstanceId	The ACR instance ID, available in the Container Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry console. Leave blank for a Personal Edition instance; required for an Enterprise Edition instance.
   regionId	The region ID of the ACR instance, available in the Container Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry consoleContainer Registry console. Required for cross-region image pulls.
   domains	The domain names the component uses to access the ACR instance. Defaults to all domain names (public and VPC) of the specified instance. Separate multiple values with commas (,).
   assumeRoleARN	For cross-account pulls only. Leave blank for same-account pulls. See Pull images across accounts.
   expireDuration	Cross-account configuration. Leave blank for same-account pulls.
   rrsaRoleARN	Cross-account configuration. Leave blank for same-account pulls.
   rrsaOIDCProviderRoleARN	Cross-account configuration. Leave blank for same-account pulls.

   Component settings:

   Setting	Default	Description
   Enable RRSA	Off	Enable to support cross-account image pulls. Not required for same-account pulls.
   watchNamespace	default	The namespaces to monitor for passwordless image pulls. Use all for all namespaces, or specify multiple namespaces separated by commas (,). Avoid all or system component namespaces to prevent issues with system image pulls.
   serviceAccount	Default	The service accounts the component applies to. Default targets the default service account in all specified namespaces; * targets all service accounts. Separate multiple values with commas (,).
   expiringThreshold	15m	How early before credential expiration the component refreshes them.
   notifyEmail	—	No configuration required.

   

Step 2: Pull an image

After installing the component, specify a service account associated with it when creating a workload. The component automatically injects the credentials—no imagePullSecrets field needed.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      serviceAccountName: my-service-account # Specify a service account associated with the passwordless component.
      containers:
      - name: nginx
        image: "******.cn-hangzhou.cr.aliyuncs.com/nginx/nginx:latest" # Specify the ACR image address.
        ports:
        - containerPort: 80

To verify the component is working, run the following command and confirm that the imagePullSecrets field on the service account is populated:

kubectl describe serviceaccount <your-service-account> -n <your-namespace>

Step 1: Install the component

1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

2. On the Clusters page, click the name of the target cluster. In the left-side navigation pane, click Add-ons.

3. On the Add-ons page, click the Security tab. Find aliyun-acr-credential-helper and click Install.

4. On the Parameter Settings page, select a permission mode from the tokenMode drop-down list and click OK. After installation, configure the component before pulling images. See Step 2: Add an ACR instance to the component. When using workerRole, grant the following permissions to the worker RAM role. See Grant permissions to a RAM role for instructions.

   tokenMode	Description
   auto (recommended)	Detects the cluster creation date and picks the permission mode automatically. Clusters created before April 3, 2023 use workerRole; clusters created on or after that date use managedRole.
   managedRole	Uses the AliyunCSManagedAcrRole role granted in the Prerequisites section.
   workerRole	Uses the cluster's worker RAM role. Grant the required permissions to the worker RAM role before using this mode. Select this mode for cross-account image pulls via role assumption.

   Select workerRole as the component mode

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

Step 2: Add an ACR instance to the component

After installing the component, configure the acr-configuration ConfigMap to add an ACR instance. Use the console or kubectl.

Step 3: Pull an image

After configuring the component, specify a service account associated with it when creating a workload.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      serviceAccountName: my-service-account # Specify a service account associated with the passwordless component.
      containers:
      - name: nginx
        image: "******.cn-hangzhou.cr.aliyuncs.com/nginx/nginx:latest" # Specify the ACR image address.
        ports:
        - containerPort: 80

To verify the component is working, run the following command and confirm that imagePullSecrets is populated on the service account:

kubectl describe serviceaccount <your-service-account> -n <your-namespace>

How do I enable immediate Secret injection for newly created service accounts?

When enabled, the passwordless component uses a webhook to detect new service accounts and inject the Secret the moment they are created. This is useful when a Helm Chart creates a service account and a Deployment simultaneously—without immediate injection, the Deployment may start before credentials are available.

Because the webhook adds overhead to every service account creation, only enable this feature if your workflow requires it.

data:
  webhook-configuration: |
    enable: true
    failure-policy: Ignore
    timeout-seconds: 10

Why does the image pull still fail after configuring the passwordless component?

The most common cause is a configuration mismatch. Check the following:

• The instance information in the component (instance ID, region, domains) matches the ACR instance.

• The image address used in the workload matches a domain name configured in the component.

If the configuration looks correct, check whether the workload YAML has an imagePullSecrets field set manually. The passwordless component cannot coexist with a manually specified imagePullSecrets. Delete the imagePullSecrets field from the workload, then delete and recreate the Pod.

How do I use imagePullSecrets?

ACR Personal Edition instances created on or after September 9, 2024 do not support the passwordless component. For these instances, store the registry credentials in a Secret and reference it in imagePullSecrets.

kubectl create secret docker-registry image-secret-1 \
  --docker-server=<registry-server> \
  --docker-username=<name> \
  --docker-password=<password> \
  --docker-email=<email>

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-test
  namespace: default
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      imagePullSecrets:
      - name: image-secret-1  # Use the Secret created in the previous step.
      containers:
      - name: nginx
        image: <acrID>.cr.aliyuncs.com/<repo>/nginx:latest  # Replace with the ACR image address.