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, find the cluster you want and click its name. In the left navigation pane, click Add-ons.

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

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

   After installation, you can update the component configuration. On the Add-ons page, click Configuration on the aliyun-acr-credential-helper (Managed) card.

   

   Configuration of associated ACR instances:

   AcrInstanceInfo		Description
   InstanceId		The ID of the ACR instance. You can obtain the ID in the Container Registry console. Important Leave this parameter empty for a Personal Edition ACR instance. This parameter is required for an Enterprise Edition ACR instance.
   regionId		The region ID of the ACR instance. You can obtain the region ID in the Container Registry console. Important This parameter is required when you pull images across regions.
   domains		The domain names that the passwordless plug-in uses to access the ACR instance. By default, all domain names (public and VPC) of the specified ACR instance are used. To specify individual domain names, separate them with commas (,).
   Configuration for pulling images across accounts This applies to scenarios where you pull images across accounts. If you do not have this requirement, leave the fields empty.	assumeRoleARN	Not required for pulling images within the same account. To pull images across accounts, see Pull images across accounts.
   	expireDuration
   	rrsaRoleARN
   	rrsaOIDCProviderRoleARN

   Component configuration

   Configuration item	Description
   Enable RRSA	Select this to enable RRSA. This is not required for pulling images within the same account. To pull images across accounts, see Pull images across accounts.
   watchNamespace	The namespaces from which you want to pull images without a password. The default value is default. A value of all means all namespaces. To specify multiple namespaces, separate them with commas (,). We recommend that you configure your business namespaces. Avoid configuring all or namespaces related to system components to prevent issues with pulling system component images.
   serviceAccount	The service accounts that the managed passwordless component applies to. The default value is Default. A value of Default applies to the default service account in all specified namespaces. An asterisk (*) applies to all service accounts in the specified namespaces. To configure multiple service accounts, separate them with commas (,).
   expiringThreshold	The expiration threshold for the component's credentials. The default value is 15m.
   notifyEmail	No configuration is required.

Step 2: Pull an image

After installing and configuring the passwordless component, specify a service account associated with the component when creating a workload to pull images without a password.

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

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, find the cluster you want and click its 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.

4. On the Parameter Settings page, select a permission mode for the component from the tokenMode drop-down list, then click OK. After installation, configure the component before pulling an image. For more information, see Step 2: Change the component configuration (add an ACR instance).

   tokenMode	Description
   auto	(Recommended) The component detects the cluster creation time and automatically determines the permission mode. For clusters created before April 3, 2023, the workerRole mode is used. For clusters created on or after April 3, 2023, the managedRole mode is used. Important Versions of aliyun-acr-credential-helper released after April 3, 2023 provide configuration items to customize the RAM role that the component depends on. For more information, see [Product Change] Announcement on changing the permissions that aliyun-acr-credential-helper depends on.
   managedRole	The component uses the AliyunCSManagedAcrRole role, which is granted permissions in the Prerequisites section, to obtain permissions.
   workerRole	The component uses the cluster's worker RAM role to obtain permissions. You must grant specific permissions to the worker RAM role. Select workerRole as the component mode When you select workerRole as the permission mode, the cluster's worker RAM role must have the following permissions. For more information about how to grant permissions, see Grant permissions to a RAM role. { "Version": "1", "Statement": [ { "Action": [ "cr:GetAuthorizationToken", "cr:ListInstanceEndpoint", "cr:PullRepository" ], "Resource": "*", "Effect": "Allow" } ] } Important Select this mode to pull images across accounts using role assumption.

Step 2: Change the component configuration (add an ACR instance)

After installing the passwordless component, you must configure the acr-configuration ConfigMap to add an ACR instance before pulling an image. You can do this in the console or using kubectl.

Step 3: Pull an image

After installing and configuring the passwordless component, specify a service account associated with the component when creating a workload to pull images without a password.

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

Why does the image pull still fail after the passwordless component is configured?

A possible cause is an incorrect configuration of the passwordless component, such as:

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

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

Follow the steps in this topic to troubleshoot the issue.

If the component is configured correctly but the pull still fails, the issue might stem from a conflict between the manually specified imagePullSecrets field in the workload YAML and the passwordless component. To resolve this, delete the imagePullSecrets field manually, 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 new ACR Personal Edition instances, we recommend saving the 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 the ACR link.