Container Registry:Load container images on demand

Limitations

• If your container runtime is containerd, accelerated image repositories can use custom domain names. Due to Docker limitations, this is not supported if you use the Docker runtime. For more information, see Use a custom domain name to access a Container Registry Enterprise Edition instance.

• The index-only mode cannot be used in Function Compute (FC) or Serverless App Engine (SAE) scenarios.

• You must manually convert existing images to accelerated images.

Region availability

The on-demand loading feature is not available in Alibaba Finance Cloud and Alibaba Gov Cloud regions.

Convert to an accelerated image

1. Log on to the Container Registry console.

2. In the top navigation bar, select a region.

3. In the navigation pane on the left, click Instances.

4. On the Instances page, click the Enterprise Edition instance that you want to manage.

5. On the instance details page, in the navigation pane on the left, choose Repository > Repositories.

6. On the Repositories page, click the name of the target repository or click Manage in the Actions column. In the upper-left corner of the Basic Information page, click Edit.

7. In the Modify Settings dialog box, enable Accelerated Image, select a mode, and then click Confirm.

   • Full Mode: Provides significant acceleration for container startup. The size of the generated accelerated image is approximately 130% of the original image size. It takes about 25 seconds to generate an accelerated image from a 1 GB original image. Existing image layers are not regenerated.

   • index-only mode: Provides about 70% of the acceleration effect of the full mode. The size of the accelerated image is about 3% of the original image size. It takes about 3 seconds to generate an accelerated image from a 1 GB original image. Image layers for which an index has been created are not re-indexed.

     Important

     The index-only mode is in public preview. We recommend that you test it in a non-production environment before you use it in a production environment.

     Note

     • The index-only mode applies only to images compressed with tar or tgz. The mode does not apply to images compressed with other methods, such as zstd.

     • The index-only mode must be used with the original image, and the original image cannot be deleted. In full mode, the accelerated image can be used independently.

     • The index-only mode is not supported by the Docker runtime.

   After you configure image acceleration, pushed images automatically trigger conversion tasks. If you want to receive notifications when image conversion is complete, you can configure event notifications. For example, set the expression to _accelerated$. For more information, see Configure event notifications.

8. (Optional) Specify a Prefetch File List. Files in this list are prefetched when the accelerated image starts. We recommend that you use this feature when large files need to be read at container startup.

   Note

   Each line must contain an absolute path to a file. For a directory, the path must end with a forward slash (/).

Install the image acceleration component

To start accelerated containers, you must install the storage plugin for on-demand loading on your worker nodes.

1. To use accelerated images, you can enable Container Image Acceleration for a new or existing node pool in the ACK console.

   ACK managed and dedicated clusters

   Enable for a new node pool

   1. Log on to the ACK console and click Clusters in the left navigation pane.

   2. Click the cluster name. In the left navigation pane, choose Nodes > Node Pools.

   3. When creating a node pool, expand Advanced Options and enable Container Image Acceleration.

   Enable for an existing node pool

   Important

   Changes to Container Image Acceleration take effect only on nodes added to the pool after the change. Existing nodes are not affected — to apply the feature to existing nodes, remove them and re-add them. See Remove a node and Add existing nodes.

   1. Log on to the ACK console and click Clusters in the left navigation pane.

   2. Click the cluster name. In the left navigation pane, choose Nodes > Node Pools.

   3. Find the node pool and click Edit in the Actions column. In the Advanced Options section, enable Container Image Acceleration and follow the on-screen instructions to update the node pool ConfigMap. The Status column shows Updating while the update is in progress, and Active when complete.

   Other cluster types

   You need to add the alibabacloud.com/image-accelerate-enabled: true image acceleration label to the nodes. This action automatically enables the image acceleration feature and installs the image storage plugin during node initialization.

   The method for adding a label varies by cluster type:

   Cluster type	Configuration guide
   ACK Serverless cluster	Create a node pool Modify the configurations of a node pool
   ACK Edge cluster	For cloud-side node pools, see Create and manage a node pool. For edge node pools, see Create an edge node pool.
   ACK Lingjun cluster	Lingjun node pools
   Alibaba Cloud Container Compute Service (ACS)	Manage node labels and taints

2. Install the image acceleration component.

   1. Log on to the ACK console. In the left navigation pane, click Clusters.

   2. On the Clusters page, click the name of the target cluster. In the navigation pane on the left, click Add-ons.

   3. On the Add-ons page, find aliyun-acr-acceleration-suite in the More section and click Install.

   4. In the Tips dialog box, click OK.

      • In the navigation pane on the left, choose Workloads > DaemonSets. On the DaemonSets page, view the installation details of the component's DaemonSet.

      • In the navigation pane on the left, choose Workloads > Deployments. On the Deployments page, view the installation details of the component's Deployment.

      The component installation is complete when all its pods are running.

Enable accelerated images

1. Configure repository access credentials.

   Warning

   Configure your image pull secret according to the principle of least privilege. Grant only the permissions required to pull the service images used by the cluster. For more information, see Grant a custom policy to a RAM user.

   • Option 1: Use the aliyun-acr-credential-helper component.

     • If you have installed the aliyun-acr-credential-helper component and correctly configured it for your Container Registry Enterprise Edition instance, no further action is necessary.

     • If you have not installed the component, you can install it now. For more information, see Use the aliyun-acr-credential-helper component to pull container images without a secret.

   • Option 2: Add a label to an image pull secret.

     Note

     This method is supported only by the aliyun-acr-acceleration-suite component of version 0.2.6 or later.

     Create a Secret of the kubernetes.io/dockerconfigjson type and add the images.alibabacloud.com/accelerated: true label to the Secret.

     kubectl create secret docker-registry <SecretName> --docker-server=<RegistryVpcDomain> --docker-username=<UserName> --docker-password=<Password>

     kubectl label secrets <SecretName>  images.alibabacloud.com/accelerated="true"

2. Add an image acceleration label.

   You can add an image acceleration label to a workload, such as a pod or Deployment, or to an entire namespace in your ACK or ACK Serverless cluster. When you label a namespace, on-demand loading is enabled for all eligible workloads within that namespace, eliminating the need to modify the YAML file for each workload. Choose the method that best suits your requirements.

   Note

   The label key is k8s.aliyun.com/image-accelerate-mode and the value is on-demand.

   • Add an image acceleration label to a workload.

     The following example shows how to add a label to a pod managed by a Deployment. Run the following command to edit the Deployment:

     kubectl edit deployment <DeploymentName> -n <DeploymentNamespace>

     In the Deployment's YAML file, add the k8s.aliyun.com/image-accelerate-mode: on-demand label.

     apiVersion: apps/v1
     kind: Deployment
     metadata:
       name: nginx-deployment
       labels:
         app: nginx
     spec:
       replicas: 1
       selector:
         matchLabels:
           app: nginx
       template:
         metadata:
           labels:
             app: nginx
             # enable on-demand mode
             k8s.aliyun.com/image-accelerate-mode: on-demand
         spec:
           containers:
            # your ACR instacne image
            - image: test-registry-vpc.cn-hangzhou.cr.aliyuncs.com/test/nginx:latest
              name: test
              command: ["sleep", "3600"]

   • Add an image acceleration label to a namespace.

     • Add an image acceleration label in the console.

       1. Log on to the ACK console, and in the left navigation bar, select Clusters.

       2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Namespaces and Quotas.

       3. On the Namespace page, find the target namespace and click Edit in the Actions column.

       4. In the Edit the namespace dialog box, set the Variable Key of the Tag to k8s.aliyun.com/image-accelerate-mode and the Variable Value of the Tag to on-demand, and then click Confirm.

     • Add an image acceleration label by using the command line.

   kubectl label namespaces <YOUR-NAMESPACE> k8s.aliyun.com/image-accelerate-mode=on-demand

   After you add the acceleration label and convert an original image to an accelerated image, the acceleration component automatically replaces the original image address with the accelerated image address and adds a nodeSelector to schedule pods to accelerated nodes during pod creation or updates within the namespace.