Use the passwordless component to pull an image from an ACR Enterprise Edition instance in the same account

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 then click Install.

4. On the Install component aliyun-acr-credential-helper page, view the AcrInstanceInfo settings and other options. AcrInstanceInfo contains the settings for each ACR instance that is associated with the component. The other options are component settings. If you do not need to change the namespaces or ServiceAccounts that the component monitors, you can keep the default settings.

   After the component is installed, you can change its settings by clicking Configurations on the aliyun-acr-credential-helper (managed) card on the Add-ons page.

   ACR instance association settings:

   AcrInstanceInfo		Description
   InstanceId		The ID of the ACR instance. You can obtain the ID from the Container Registry console. Important Leave this field blank for ACR Personal Edition instances. This field is required for ACR Enterprise Edition instances.
   regionId		The ID of the region where the ACR instance is deployed. You can obtain the ID from the Container Registry console. Important This parameter is required for cross-region image pulls.
   domains		The domain names used by the passwordless component to access the ACR instance. By default, this includes all domain names (internet and VPC) of the specified ACR instance. To specify multiple domain names, separate them with commas (,).
   Settings for cross-account image pulls These settings apply to cross-account image pulls. If you do not need this feature, leave the fields blank.	assumeRoleARN	No configuration is required for same-account pulls. For cross-account pulls, see Pull images across accounts.
   	expireDuration
   	rrsaRoleARN
   	rrsaOIDCProviderRoleARN

   Component settings

   Parameter	Description
   Enable RRSA	Select this checkbox to enable RRSA. No configuration is required for same-account pulls. For cross-account pulls, see Pull images across accounts.
   watchNamespace	The namespaces where you want to enable passwordless image pulls. The default value isdefault. Set the value toall to enable this feature for all namespaces. To specify multiple namespaces, separate them with commas (,). We recommend that you specify only your business namespaces and avoid usingall or namespaces for cluster system components to prevent disruptions to system image pulls.
   serviceAccount	Specifies the ServiceAccount to which the managed passwordless component applies. The default value is Default. A value of Default applies the component to the default ServiceAccount in the specified namespaces. If you set the value to *, the component applies to all ServiceAccounts in the specified namespace. To specify multiple ServiceAccounts, separate them with a comma (,).
   expiringThreshold	The expiration threshold for credentials in the component. The default value is15m.
   notifyEmail	No configuration is required.

Step 2: Pull an image

After you install and configure the passwordless component, specify a ServiceAccount associated with the component when you create a workload. This enables passwordless image pulling.

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 that is 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

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 card, and then click Install.

4. On the Parameters page, select a permission mode from the tokenMode drop-down list and click OK. After the component is installed, you need to configure it before you can pull images. For more information, see Step 2: Update the component configuration (add an ACR instance).

   tokenMode	Description
   auto	(Recommended) The component detects the cluster creation time and automatically chooses a permission mode. Clusters created before April 3, 2023 use the workerRole mode. Clusters created on or after April 3, 2023 use the managedRole mode. Important Versions of aliyun-acr-credential-helper released on or after April 3, 2023 provide a parameter that allows you to customize the RAM role that the component depends on. For more information, see [Product Change] Announcement on changing the permissions required by the aliyun-acr-credential-helper component.
   managedRole	The component uses the AliyunCSManagedAcrRole role authorized in Prerequisites to obtain permissions.
   workerRole	The component uses the cluster worker RAM role to obtain permissions. You need to grant specific permissions to the worker RAM role. Select workerRole as the component mode If you select workerRole as the component permission mode, the cluster worker RAM role must have the following permissions. For information about how to grant permissions, see Manage RAM role permissions. { "Version": "1", "Statement": [ { "Action": [ "cr:GetAuthorizationToken", "cr:ListInstanceEndpoint", "cr:PullRepository" ], "Resource": "*", "Effect": "Allow" } ] } Important Select this mode if you need to pull images across accounts by assuming a role.

Step 2: Update the component configuration

After the passwordless component is installed, you need to configure theacr-configuration ConfigMap to add an ACR instance before you can pull images. You can do this by using the console or kubectl.

Step 3: Pull an image

After you install and configure the passwordless component, specify a ServiceAccount associated with the component when you create a workload. This enables passwordless image pulling.

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 that is 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

Troubleshoot image pull failures

One possible cause is an incorrect passwordless component configuration, for example:

• The instance information configured in the passwordless component does not match the ACR instance.

• The image address used for pulling does not match the domain name specified in the component's instance information.

Follow the steps in this topic to troubleshoot the issue.

If the component is configured correctly but image pulling still fails, it may be due to a conflict between a manually specifiedimagePullSecrets field in the workload YAML and the passwordless component. To resolve this, manually remove theimagePullSecrets field 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, we recommend that you store the username and password in a Secret and reference it in theimagePullSecrets 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 the ACR image address.