Container Service for Kubernetes:Use the aliyun-acr-credential-helper component to pull images without secrets

Implementation mechanism

Limits

The aliyun-acr-credential-helper component allows you to pull the following images in the following clusters:

• Images
  • You can pull private images from the Container Registry instances that are in the same account as the current cluster account. You can also pull private images from the Container Registry instances that are in an account different from the current cluster account by granting permissions or by using an accessKey pair of a sub account.
  • You can pull private images in scenarios in which you need to pull images from instances of Container Registry Enterprise Edition and Container Registry Personal Edition.
• Clusters
  • You can pull images without secrets from multiple namespaces of a cluster in a batch.
  • Supported cluster types:
    • ACK dedicated clusters
    • ACK managed clusters
  • Supported cluster versions:
    • ACK dedicated clusters: By default, clusters of v1.11.2 or later support image pulling without using a password. If the cluster version is earlier than v1.11.2, you must update the cluster version. For more information, see Update the Kubernetes version of an ACK cluster.
    • Managed Kubernetes clusters: All versions.

Precautions

Ensure that aliyun-acr-credential-helper can take effect

• Do not use the imagePullSecret parameter to configure a secret that is used to pull images in the template of a Kubernetes resource, such as a Deployment.
• If a Kubernetes resource, such as a Deployment, uses a custom service account, you must modify the service-account parameter in the configuration file of the aliyun-acr-credential-helper component. This way, the component is authorized to pull images by using the custom service accounts.
• Check whether the private image that you want to pull resides in the same region as your ACK cluster. By default, you can pull private images only from Container Registry instances that reside in the same region as your ACK cluster. If you want to pull images from Container Registry instances that reside in different regions from your ACK cluster, see Scenario 2 in this topic.
• After you create a service account in a cluster, the service account requires a period of time to be associated with the secret that is generated by aliyun-acr-credential-helper. When the service account is associated with the secret, applications that are in the service account can pull images based on the secret. If you use an application in the service account to pull images immediately after you create a service account, images may fail to be pulled because the service account is not associated with the secret that is generated by aliyun-acr-credential-helper.
• By default, the value of the service-account parameter in the acr-configuration ConfigMap in aliyun-acr-credential-helper overwrites the value of the imagePullSecrets parameter of service accounts in all namespaces in the ACK cluster.
• When you modify the acr-configuration ConfigMap in the kube-system namespace, make sure that you use the same indentation as the example that is provided in this topic. We recommend that you paste the YAML code that is provided in this topic to the editor, replace the corresponding values, and apply the configuration. This ensures that the format of the ConfigMap is valid.

Prevent the AccessKey pair of the RAM role from being leaked

If you pull images by using the AccessKey ID and AccessKey secret of a RAM role, you must specify the AccessKey pair in the acr-configuration ConfigMap. This may disclose the AccessKey pair. To ensure the security of the AccessKey pair, make sure that the RAM role is granted only the permissions that are required to pull images. We do not recommend that you use the AccessKey pair method to pull images.

Update and configure aliyun-acr-credential-helper

Before you use aliyun-acr-credential-helper to pull images, you may need to update and configure the component. Perform the following steps:

1. Update aliyun-acr-credential-helper.
   For more information about aliyun-acr-credential-helper, see aliyun-acr-credential-helper. Updating the component does not negatively impact workloads.
   1. Log on to the ACK console and click Clusters in the left-side navigation pane.
   2. On the Clusters page, click the name of a cluster and choose Operations > Add-ons in the left-side navigation pane.
   3. On the Add-ons page, click the Security tab, find aliyun-acr-credential-helper, and then click Upgrade.
2. Configure the acr-configuration ConfigMap.
   Mode 1: Configure the acr-configuration ConfigMap in the ACK console
   1. Log on to the ACK console and click Clusters in the left-side navigation pane.
   2. On the Clusters page, click the name of a cluster and choose Configurations > ConfigMaps in the left-side navigation pane.
   3. In the upper part of the ConfigMap page, select kube-system from the Namespace drop-down list and find the acr-configuration ConfigMap. Then, modify the ConfigMap by using one of the following methods:
      • Method 1: Click Edit in the Actions column, modify the keys, and change the values of the ConfigMap.

        If no acr-configuration ConfigMap is created for your cluster, create an acr-configuration ConfigMap. For more information, see Create a ConfigMap. For information about how to update ConfigMaps, see Manage ConfigMaps.

      • Method 2: Click Edit YAML in the Actions column, modify the keys, and change the values of the ConfigMap.
   Mode 2: Configure the acr-configuration ConfigMap by using kubectl
   1. Run the following command to go to the edit page of the acr-configuration ConfigMap:

      kubectl edit cm acr-configuration -n kube-system

   2. Configure the parameters of the acr-configuration ConfigMap based on your requirements.
   The following table describes the keys and values of the acr-configuration ConfigMap.

   Key	Description	Value
   service-account	The service accounts that are used by the aliyun-acr-credential-helper component to pull images.	Default value: default. Note Separate multiple service accounts with commas (,). Enter an asterisk (*) to specify all service accounts in all namespaces.
   acr-registry-info	The information about Container Registry instances. Each instance can be specified by three parameters of the string type in a YAML file. Note Configure the parameters based on the following descriptions: instanceId: the ID of the Container Registry instance. You must configure this parameter if you pull images from Container Registry Enterprise Edition instances. regionId: the ID of the region where the Container Registry instance resides. This parameter is optional. The default value is the region where your ACK cluster resides. domains: the domain names of the Container Registry instance. This parameter is optional. By default, all domain names of the instance are specified. Separate multiple domain names with commas (,).	This parameter is left empty by default. This indicates that images are pulled from a Container Registry Personal Edition instance in the same region as the cluster without using a password. Leave the parameter empty when you need to pull images from instances of Personal Edition and Enterprise Edition. Sample configurations for a Container Registry Enterprise Edition instance: - instanceId: "cri-instanceId" regionId: "cn-hangzhou" domains: "xxx.com,yyy.com"
   watch-namespace	The namespaces from which you want to pull images without secrets.	Default value: default. Note If the value is set to all, images can be pulled from all namespaces in the cluster without using a password. Separate multiple namespaces with commas (,).
   expiring-threshold	The period of time after which the cached secret expires.	Default value: 15m. Note We recommended that you use the default value. The default value specifies to update the secret 15 minutes before the cached secret expires.

Scenario 1: Pull images by using the same account as the cluster

Before you pull images by using the same account as the cluster, make sure that the account is granted the permissions that are required to pull images from Container Registry instances.

1. Log on to the ACK console and click Clusters in the left-side navigation pane.
2. On the Clusters page, find the cluster. Click the name of the cluster in the Cluster Name/ID column, or click Details in the Actions column corresponding to the cluster.
3. On the Cluster Information page, click the Cluster Resources tab, and then click the hyperlink next to Worker RAM Role.
4. On the Roles page, click the Permissions tab and click the policy name in the Policy column.
5. Check whether the policy document contains the following content. If the policy document does not contain the following content, click Modify Policy Document. Add the following content to the policy document and then click OK.

   {
     "Action": [
        "cr:GetAuthorizationToken",
        "cr:ListInstanceEndpoint",
        "cr:PullRepository"
     ],
     "Resource": "*",
     "Effect": "Allow"
   }

   Modify the acr-configuration ConfigMap based on the following sample code to pull private images of the Container Registry Enterprise Edition instance. For information about how to configure acr-configuration, see 2.

   data:
       service-account: "default"
       watch-namespace: "all"
       expiring-threshold: "15m"
       notify-email: "cs@aliyuncs.com"
       acr-registry-info:|
         - instanceId: "cri-instanceId"
           regionId: "cn-hangzhou"
           domains: "instance.default.domain.com,instance.custom.domain.com"

Scenario 2: Pull images that are in a region different from the cluster

If the images that you want to pull reside in regions different from your ACK cluster, you must modify the acr-configuration ConfigMap.

data:
    service-account: "default"
    watch-namespace: "all"
    expiring-threshold: "15m"
    notify-email: "cs@aliyuncs.com"
    acr-registry-info: |
      - instanceId: "cri-instanceId"
        regionId: "cn-beijing"
      - instanceId: "cri-instanceId"
        regionId: "cn-hangzhou"            

Scenario 3: Pull images that are in an account different from your cluster account

Configure RRSA to pull images that are in an account different from the cluster account

The RRSA feature can be used to perform access control on pods in a cluster.

Prerequisites

Enable the RRSA feature for the cluster

• Method 1: Enable RRSA in the ACK console
  1. Log on to the ACK console and click Clusters in the left-side navigation pane.
  2. On the Clusters page, find the cluster. Click the name of the cluster in the Cluster Name/ID column, or click Details in the Actions column.
  3. On the Cluster Information page, click the Basic Information tab and click Enable RRSA next to RRSA OIDC.
  4. In the Enable RRSA message, click Confirm.

     After the cluster status changes from Updating to Running, the RRSA feature is enabled for the cluster and the OIDC (OpenID Connect) provider URL is displayed next to RRSA OIDC.

• Method 2: Enable RRSA by using ack-ram-tool
  To enable RRSA by using the ack-ram-tool command line interface (CLI), run the following command. Replace <cluster_id> in the command with the ID of the cluster that you want to manage.

  ack-ram-tool rrsa enable -c <cluster_id>

Enable the RRSA feature for aliyun-acr-credential-helper

After the RRSA feature is enabled for the cluster, you must perform the following steps to enable RRSA for aliyun-acr-credential-helper. For example, the current cluster is in Account A and the Container Registry instance is in Account B. If you want to pull images of the Container Registry instance, you must authorize Account A to access the Container Registry resources of Account B.

1. Configure a RAM role for Account A
   Create a RAM role in Account A and modify the trust policy of the RAM role.

   • Replace <oidc_issuer_url> in the example with the OIDC provider URL of the cluster. You can obtain the OIDC provider URL on the Basic Information tab of the Cluster Information page in the ACK console.
   • Replace <oidc_provider_arn> in the example with the OIDC provider ARN (Alibaba Cloud Resource Name) of the cluster. You can obtain the OIDC provider ARN on the Basic Information tab of the Cluster Information page in the ACK console.

   {
     "Statement": [
       {
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "oidc:aud": "sts.aliyuncs.com",
             "oidc:iss": "<oidc_issuer_url>",
             "oidc:sub": "system:serviceaccount:kube-system:aliyun-acr-credential-helper"
           }
         },
         "Effect": "Allow",
         "Principal": {
           "Federated": [
             "<oidc_provider_arn>"
           ]
         }
       }
     ],
     "Version": "1"
   }

2. Configure a RAM role for Account B
   Create a RAM role for Account B. Associate the following policy with the RAM role to grant the role the permissions that are required to obtain the information about Container Registry instances and pull images from the instances.

   {
       "Version": "1",
       "Statement": [
           {
               "Action": [
                   "cr:GetAuthorizationToken",
                   "cr:ListInstanceEndpoint",
                   "cr:PullRepository"
               ],
               "Resource": "*",
               "Effect": "Allow"
           }
       ]
   }

   You can configure the MaxSessionDuration parameter for the RAM role. Valid values of this parameter range from 3600 to 43200 seconds. You must configure the expireDuration parameter when you modify parameters of aliyun-acr-credential-helper. We recommend that you specify the same value for MaxSessionDuration and expireDuration. The value of expireDuration can be less than or equal to the value of MaxSessionDuration.

3. Authorize Account A to assume the role of Account B

   In the RAM role of Account B that is granted permissions on Container Registry instances, click the Trust Policy Management tab and add the ARN of the RAM role of Account A.

   Associate the AliyunSTSAssumeRoleAccess policy with the RAM role of Account A to grant the RAM role the permissions that are required to assume the role of Account B.

Modify parameters of aliyun-acr-credential-helper

data:
  rrsa: |
    enable: true
  acr-registry-info: |
    - instanceId: cri-xxx
      regionId: cn-hangzhou
      rrsaRoleARN: aUserRoleARN
      rrsaOIDCProviderRoleARN: aUserClusterOIDCProviderRoleARN
      assumeRoleARN: bUserRoleARN
      expireDuration: 3600

Assume a role of the account to pull images that are in an account different from the cluster account

Use the accessKey pair of a sub account to pull images that are in an account different from the cluster account

Other features

Pull private images from a Container Registry Personal Edition instance

data:
    service-account: "default"
    watch-namespace: "all"
    expiring-threshold: "15m"
    notify-email: "cs@aliyuncs.com"
    acr-registry-info: |
      - instanceId: ""
      - instanceId: "cri-xxxx"

Instant use of service accounts

Configuration method

data:
  webhook-configuration: |
    enable: true
    failure-policy: Ignore
    timeout-seconds: 10

References

• aliyun-acr-credential-helper
• Use RRSA to authorize pods to access different cloud services