Pull images from ACR Enterprise instances in the same account using the password-free component

Step 1: Install the component

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 (managed) card and click Install.

4. On the Install aliyun-acr-credential-helper page, you will see the AcrInstanceInfo configuration and other options. AcrInstanceInfo defines settings for each ACR instance associated with the component. Other options are general component settings. If you do not need to change the namespaces or ServiceAccounts the component monitors, keep the default values.

   After installation, go to the Add-ons page and click Configurations on the aliyun-acr-credential-helper (managed) card to update the component settings.

   

   ACR instance association settings:

   AcrInstanceInfo		Description
   InstanceId		The ACR instance ID. You can find it in the Container Registry console. Important Leave blank for ACR Personal instances. Required for ACR Enterprise instances.
   regionId		The region ID of your ACR instance. You can find it in the Container Registry console. Important Required for cross-region image pulls.
   domains		The domain names the password-free plug-in uses to access your ACR instance. By default, all domains (public and VPC) of the ACR instance specified above are included. To specify particular domains, separate them with commas (,).
   Cross-account image pull settings Use these settings only for cross-account image pulls. Leave blank if not needed.	assumeRoleARN	No configuration is needed for same-account pulls. For cross-account pulls, see Pull images across accounts.
   	expireDuration
   	rrsaRoleARN
   	rrsaOIDCProviderRoleARN

   Component settings

   Setting	Description
   Enable RRSA	Select this option to enable RRSA. No configuration is needed for same-account pulls. For cross-account pulls, see Pull images across accounts.
   watchNamespace	The namespaces where you want password-free image pulls. Default: default. Use all to enable password-free pulls in all namespaces. To specify multiple namespaces, separate them with commas (,). We recommend configuring only your business namespaces and avoiding all or system namespaces to prevent interference with system component image pulls.
   serviceAccount	Specify the service accounts that are associated with managed aliyun-acr-credential-helper. Default value is Default. When the value is set to Default, it applies to the default service account in each specified namespace. If set to (*), it supports all service accounts in the specified namespace. To configure multiple service accounts, separate them with commas (,).
   expiringThreshold	The credential expiration threshold inside the component. Default: 15m.
   notifyEmail	No configuration needed.

Step 2: Pull images

After installing and configuring the password-free component, specify a ServiceAccount already associated with the component when creating your workload to enable password-free image pulls.

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 ServiceAccount already associated with the password-free component
      containers:
      - name: nginx
        image: "******.cn-hangzhou.cr.aliyuncs.com/nginx/nginx:latest" # Specify the ACR image address
        ports:
        - containerPort: 80

Step 1: Install the component

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 aliyun-acr-credential-helper and click Install.

4. On the Parameters page, select a permission mode using tokenMode, then click OK. After installation, complete the component configuration as described in Step 2: Update component configuration (add ACR instances) before pulling images.

   tokenMode	Description
   auto	(Recommended) The component detects your cluster creation date and automatically selects a permission mode. Clusters created before April 3, 2023, use workerRole mode. Clusters created on or after April 3, 2023, use managedRole mode. Important Starting April 3, 2023, the aliyun-acr-credential-helper component includes a setting to customize the RAM role it depends on. For details, see [Product update] Announcement on changing permissions required by aliyun-acr-credential-helper.
   managedRole	The component uses the AliyunCSManagedAcrRole granted in the Prerequisites section.
   workerRole	The component uses the Worker RAM role of your cluster. You must grant specific permissions to this role. Select workerRole mode If you choose workerRole mode, your cluster's Worker RAM role must have the following permissions. For instructions, see Manage permissions for RAM roles. { "Version": "1", "Statement": [ { "Action": [ "cr:GetAuthorizationToken", "cr:ListInstanceEndpoint", "cr:PullRepository" ], "Resource": "*", "Effect": "Allow" } ] } Important Choose this mode to pull images across accounts using role assumption.

Step 2: Update component configuration (add ACR instances)

After installing the password-free component, configure the acr-configuration ConfigMap via the console or kubectl to add your ACR instances before pulling images.

Step 3: Pull images

After installing and configuring the password-free component, specify a ServiceAccount already associated with the component when creating your workload to enable password-free image pulls.

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 ServiceAccount already associated with the password-free component
      containers:
      - name: nginx
        image: "******.cn-hangzhou.cr.aliyuncs.com/nginx/nginx:latest" # Specify the ACR image address
        ports:
        - containerPort: 80

Why do image pulls still fail after configuring the password-free component?

A possible cause is incorrect component configuration, such as:

• The instance information in the password-free component does not match your ACR instance.

• The image address used for pulling does not match the domain name in the component’s instance configuration.

Follow the steps in this topic to troubleshoot.

If the component configuration is correct but pulls still fail, your workload YAML might contain a manually specified imagePullSecrets field that conflicts with the password-free component. Delete the imagePullSecrets field and recreate the pod to resolve the issue.

How do I use imagePullSecrets?

ACR Personal instances created on or after September 9, 2024, do not support the password-free component. For these instances, we recommend storing your username and logon password in a Secret and referencing it in the imagePullSecrets field.

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 your ACR URL