Container Registry provides the aliyun-acr-credential-helper component for you to pull private images without a password from Container Registry Enterprise Edition or Personal Edition. This component is automatically installed in Container Service for Kubernetes (ACK) clusters. This topic describes how to use the aliyun-acr-credential-helper component to pull a private image without a password in different scenarios.
Background information
- Assume the worker role of an ACK cluster to pull images from Container Registry instances that are created within your account. This is the default method.
- Use the AccessKey ID and AccessKey secret of a custom RAM user to pull private images.
- Assume the RAM role of another account to pull images from Container Registry instances of that account.
Implementation mechanism
After you configure the aliyun-acr-credential-helper component, the component creates a secret in your cluster and associates it with the service account that you specified in the acr-configuration ConfigMap. For more information about how to configure the aliyun-acr-credential-helper component, see Upgrade and configure the aliyun-acr-credential-helper component.By default, any pods that use this service account use the created secret to pull images without a password.Limits
The aliyun-acr-credential-helper component supports the following images and clusters:
- Supported images
- You can use the aliyun-acr-credential-helper component to pull private images from Container Registry Enterprise Edition and Container Registry Personal Edition instances.
- You can use the aliyun-acr-credential-helper component to pull private images from Container Registry instances within your own account. You can also pull private images from Container Registry instances of other accounts after authorization or by using the AccessKey ID and AccessKey secret.
- You can use the aliyun-acr-credential-helper component to pull private images from Container Registry instances that reside in different regions from your ACK cluster.
- Supported clusters
- You can use the aliyun-acr-credential-helper component to pull images without a password from clusters that contain multiple namespaces.
- Supported cluster types:
- Dedicated Kubernetes clusters
- Managed Kubernetes clusters
- Supported cluster versions:
- Dedicated Kubernetes clusters: The Kubernetes version must be V1.11.2 or later. If the Kubernetes version is earlier than V1.11.2, you must manually update the Kubernetes version to V1.11.2 or later. For more information, see Upgrade the Kubernetes version of an ACK cluster.
- Managed Kubernetes clusters: All versions.
Usage notes
- If you want to use the aliyun-acr-credential-helper component, do not specify the imagePullSecret parameter. If the imagePullSecret parameter is specified in the template of a Kubernetes resource, such as a Deployment, the component becomes invalid.
- If a Kubernetes resource, such as a Deployment, uses custom service accounts, 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 3 in this topic.
- If you want to use a RAM user to pull private images, you must specify the AccessKey ID and AccessKey secret of the RAM user in the acr-configuration ConfigMap. However, this may disclose the AccessKey pair information. To ensure data security, make sure that the RAM role is granted only the permissions to pull images.
- After you create a service account in a cluster, it takes some time for the aliyun-acr-credential-helper component to renew the token of the service account. The new token for pulling private images is generated based on the default permissions of your ACK cluster. Applications with the service account can use the token to pull images only after the token is renewed. If you create an application immediately after you create a service account, the application will fail to pull images because it is unauthorized.
- By default, the configuration of the aliyun-acr-credential-helper component overwrites the imagePullSecret parameter of default service accounts in all namespaces. These service accounts are automatically modified when the service-account parameter of the acr-configuration ConfigMap in the kube-system namespace is changed.
- When you modify the acr-configuration ConfigMap in the kube-system namespace, make sure that you use the same indentation as the example in this topic. We recommend that you paste the YAML code 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.
Upgrade and configure the aliyun-acr-credential-helper component
Before you use the aliyun-acr-credential-helper component to pull images, you must update and configure the component by performing the following steps:
Scenario 1: Pull private images from Container Registry Enterprise Edition and Container Registry Personal Edition instances
- Pull private images from Container Registry Enterprise Edition instances.
data: service-account: "default" watch-namespace: "all" expiring-threshold: "15m" notify-email: "cs@aliyuncs.com" acr-registry-info: | - instanceId: "cri-xxx" regionId: "cn-hangzhou" domains: "xxx.com,yyy.com"
- Pull private images from Container Registry Personal Edition instances.
data: service-account: "default" watch-namespace: "all" expiring-threshold: "15m" notify-email: "cs@aliyuncs.com" acr-registry-info: | - instanceId: "" regionId: "cn-hangzhou" domains: "xxx.com,yyy.com"
- Pull private images from both Container Registry Enterprise Edition and Personal Edition
instances.
data: service-account: "default" watch-namespace: "all" expiring-threshold: "15m" notify-email: "cs@aliyuncs.com" acr-registry-info: | - instanceId: "" - instanceId: "cri-xxxx"
Scenario 2: Pull images with the current account
If you want to pull images with the current account, you must check whether the current account has the permissions to pull images from Container Registry instances.
- If the images exist in the Container Registry repository but cannot be found on the Container Registry instances that belong to the current account, you must pull the images across accounts. For more information, see Scenario 4: Pull images across accounts.
- If the images exist in the Container Registry repository and is found on the Container Registry instances that belong to the current account, Submit a ticket.
- If the images are not found in the Container Registry repository, you need to check whether the images can be found on Container Registry. If the images are not found on Container Registry, you must replicate the external images to Container Registry or change the image status so that the images can be pulled over the Internet.
Scenario 3: Pull images across regions
If you want to pull images from Container Registry instances that reside in different regions from your ACK cluster, you must modify the acr-configuration ConfigMap.
For example, if you want to pull images from Container Registry instances that reside in the China (Beijing) and China (Hangzhou) regions at a time, modify the acr-configuration ConfigMap, as shown in the following sample code. For more information, see Update and configure the aliyun-acr-credential-helper component.
data:
service-account: "default"
watch-namespace: "all"
expiring-threshold: "15m"
notify-email: "cs@aliyuncs.com"
acr-registry-info: |
- instanceId: ""
regionId: "cn-beijing"
- instanceId: ""
regionId: "cn-hangzhou"
Scenario 4: Pull images across accounts
- Pull images across accounts by assuming a RAM role: Account A assumes the RAM role of Account B to pull private images from the Container Registry instances of Account B.
- Pull images across accounts by using the AccessKey pair of a RAM user: The RAM user must have the permissions to pull specified images.
Pull images across accounts by assuming a RAM role
- The RAM role of Account B is authorized to pull private images from a specified private repository. This rule requires you to grant permissions related to Container Registry.
- Account B allows the worker role of the ACK cluster of Account A to assume the RAM role of Account B. This rule requires you to modify the trust policy of the RAM role of Account B.
- The worker role of the ACK cluster created by Account A has the permissions to assume the RAM role of Account B. This rule requires you to attach the AliyunAssumeRoleAccess policy to the worker role of Account A.
- Set the worker role of Account A to assume the RAM role of Account B. This rule requires you to specify the assumeRoleARN parameter in the acr-configuration ConfigMap.
Pull images across accounts by using the AccessKey pair of a RAM user