Container Registry:Pull images from an ACR Enterprise Edition instance in the same account using the credential-free add-on

Step 1: Install the add-on

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 add-on 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 add-on. The other options are add-on settings. If you do not need to change the namespaces or ServiceAccounts that the add-on monitors, you can keep the default settings.

   After the add-on 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 credential-free add-on 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

   Add-on 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 credential-free 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 credential-free add-on applies. The default value is Default. A value of Default applies the add-on to the default ServiceAccount in the specified namespaces. If you set the value to *, the add-on applies to all ServiceAccounts in the specified namespaces. To specify multiple ServiceAccounts, separate them with a comma (,).
   expiringThreshold	The expiration threshold for credentials in the add-on. The default value is15m.
   notifyEmail	No configuration is required.

Step 2: Pull an image

After you install and configure the credential-free add-on, specify a ServiceAccount associated with the add-on when you create a workload. This enables credential-free 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 credential-free add-on.
      containers:
      - name: nginx
        image: "******.cn-hangzhou.cr.aliyuncs.com/nginx/nginx:latest" # Specify the ACR image address.
        ports:
        - containerPort: 80

Step 1: Install the add-on

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 add-on is installed, you need to configure it before you can pull images. For more information, see Step 2: Update the add-on configuration (add an ACR instance).

   tokenMode	Description
   auto	(Recommended) The add-on 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 add-on depends on. For more information, see [Product Change] Announcement on changing the permissions required by the aliyun-acr-credential-helper add-on.
   managedRole	The add-on uses the AliyunCSManagedAcrRole role authorized in Prerequisites to obtain permissions.
   workerRole	The add-on uses the cluster worker RAM role to obtain permissions. You need to grant specific permissions to the worker RAM role. Select workerRole as the add-on mode If you select workerRole as the add-on 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 add-on configuration

After the credential-free add-on 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 credential-free add-on, specify a ServiceAccount associated with the add-on when you create a workload. This enables credential-free 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 credential-free add-on.
      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 credential-free add-on configuration, for example:

• The instance information configured in the credential-free add-on does not match the ACR instance.

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

Follow the steps in this topic to troubleshoot the issue.

If the add-on 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 credential-free add-on. 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 credential-free add-on. 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.