Container Registry:Pull images from an ACR Enterprise Edition instance within the same account by using the secret-free component

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-side pane, choose Operations > 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 the configurations for each ACR instance associated with the component. The other options are component configurations. If you do not need to modify the namespaces or service accounts that the component monitors, you can keep the default settings.

   After the component is installed, you can change its 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 secret-free plugin 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 secret. 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 secret-free 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. We recommend using 15 minutes. The component automatically renews the credentials 15 minutes before they expire.
   notifyEmail	No configuration is required.

Step 2: Pull an image

After you install and configure the secret-free component, specify a service account that is associated with the component when you create a workload. This lets you pull images without a secret.

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 secret-free 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-side pane, choose Operations > 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 for the component from the tokenMode drop-down list, and then click OK. After the component is installed, configure it before you pull 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 the secret-free component is installed, you must configure the acr-configuration ConfigMap to add an ACR instance before you can pull an image. You can do this in the console or using kubectl.

Step 3: Pull an image

After you install and configure the secret-free component, specify a service account that is associated with the component when you create a workload. This lets you pull images without a secret.

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

Image pull still fails after the secret-free component is configured

The image pull may fail due to an incorrect configuration of the secret-free component. For example:

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

• The image address used for pulling the image 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 failure might be due to a conflict between the imagePullSecrets field that is manually entered in the workload YAML and the secret-free component. To resolve this issue, manually delete the imagePullSecrets field, and then delete and recreate the pod.

How to use imagePullSecrets

ACR Personal Edition instances created on or after September 9, 2024 do not support the secret-free component. For new ACR Personal Edition instances, we recommend that you save the username and logon password in a Secret and use it in the imagePullSecrets field.

kubectl create secret generic 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