Container Registry:Load resources of a container image on demand

Usage limits

• If your container runtime is Containerd, you can set custom domain names for repositories of accelerated images. If your container runtime is Docker, you cannot set custom domain names for repositories of accelerated images due to the limits of Docker. 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 or Serverless App Engine (SAE) scenarios.

Region limits

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

Convert a base image to an accelerated image

1. Log on to the Container Registry console.

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

3. In the left-side navigation pane, click Instances.

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

5. In the left-side navigation pane of the management page of the Container Registry Enterprise Edition instance, choose Repository > Repositories.

6. On the Repositories page, find the repository for which you want to enable image acceleration. Click the name of the repository or click Manage in the Actions column. On the page that appears, click Edit in the upper-left corner.

7. In the Modify Settings dialog box, select Enabled in the Accelerated Image section, select an acceleration mode, and then click Confirm.

   • Full Mode: This mode significantly accelerates container startup. The size of an accelerated image is approximately 130% the size of the base image. The system requires approximately 25 seconds to generate an accelerated image for a 1 GB-sized image. If an accelerated image layer has been generated for an image layer, the system does not re-generate an accelerated image layer for the image layer.

   • Index-only Mode: This mode provides an acceleration effect that is approximately 70% the effect of full mode on container startup. The size of an accelerated image is approximately 3% the size of the base image. The system requires approximately 3 seconds to generate an accelerated image for a 1 GB-sized image. The system does not re-generate indexes for image layers that already have indexes.

     Important

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

     Note

     • The index-only mode can be used only for images that are compressed by tar and tgz. The mode cannot be used for images that are compressed by other compression methods, such as zstd.

     • When you use the index-only mode to accelerate an image, you must use the accelerated image together with the base image. You cannot delete the base image. If you use the full mode, you can separately use the accelerated image.

     • The index-only mode does not support the Docker runtime.

   After you enable image acceleration for a repository, each image that the system pushes to the repository is automatically converted into an accelerated image. If you want to be notified each time an image is converted into an accelerated image, you can configure event notifications. For example, specify an expression-based trigger and set the expression to _accelerated$. For more information, see Event Notification.

8. (Optional) Specify Prefetch File List. The files in this list are preferentially prefetched when accelerated images are started. We recommend that you use the file prefetch feature when large files must be read for container startup.

   Note

   Enter the absolute path of a file in a line. If the absolute path is a directory, add the forward slash (/) to the end of the line.

Install the aliyun-acr-acceleration-suite image acceleration component

To start a container by using an accelerated image, you must install the aliyun-acr-acceleration-suite component on the worker node in the ACK cluster.

1. To support DADI-accelerated images, you can enable Container Image Acceleration in the ACK console to enable image acceleration for new or existing node pools.

   ACK managed clusters

   Enable image acceleration when you create a node pool

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

   2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side navigation pane, choose Nodes > Node Pools.

   3. On the Node Pools page, enable Container Registry Acceleration in the Advanced Options section. For more information, see Create and manage a node pool.

   Enable image acceleration for an existing node pool

   If you turn on or off Container Image Acceleration, this operation takes effect only for new nodes. If you want this operation to take effect on existing nodes, you must remove the nodes from the node pool and re-add the nodes to the node pool. For more information, see Remove a node and Add existing ECS instances to an ACK cluster.

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

   2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side navigation pane, choose Nodes > Node Pools.

   3. On the Node Pools page, find the node pool that you want to modify and click Edit in the Actions column. In the Advanced Options section, enable Container Registry Acceleration and follow the instructions to update the ConfigMap of the node pool.

      On the Node Pools page, if the Status column of the node pool displays Updating, the node pool is being modified. If the status of the node pool changes to Active, the modification is complete.

   Other clusters

   When you create the worker node pool, you can set the alibabacloud.com/image-accelerate-enabled: true label for the nodes to enable image acceleration when the nodes are initialized. After the image acceleration label is set, the aliyun-acr-acceleration-suite component is automatically installed when the nodes are initialized.

   Enable image acceleration when you create a node pool

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

   2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side navigation pane, choose Nodes > Node Pools.

   3. On the Node Pools page, click Create Node Pool. On the Create Node Pool page, follow the instructions in the Create and manage a node pool topic to configure the node pool. Unfold Advanced Options and then set the alibabacloud.com/image-accelerate-enabled: true label for the nodes in the Node Labels section.

   Enable image acceleration for an existing node pool

   If you turn on or off Container Image Acceleration, this operation takes effect only for new nodes. If you want this operation to take effect on existing nodes, you must remove the nodes from the node pool and re-add the nodes to the node pool. For more information, see Remove a node and Add existing ECS instances to an ACK cluster.

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

   2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side navigation pane, choose Nodes > Node Pools.

   3. On the Node Pools page, find the node pool for which you want to enable image acceleration and click Edit in the Actions column. Unfold Advanced Options and then set the alibabacloud.com/image-accelerate-enabled: true label for the nodes in the Node Labels section.

2. Install the aliyun-acr-acceleration-suite component.

   1. Log on to the ACK console.

   2. In the left-side navigation pane of the ACK console, click Clusters.

   3. On the Clusters page, click the name of the cluster for which you want to install the aliyun-acr-acceleration-suite component and choose Operations > Add-ons in the left-side navigation pane.

   4. In the Others section of the Add-ons page, find aliyun-acr-acceleration-suite and click Install.

   5. In the Install aliyun-acr-acceleration-suite message, click OK.

      • In the left-side navigation pane of the Cluster Management page, choose Workloads > DaemonSets. On the DaemonSets page, view the installation details of the daemons of the component.

      • In the left-side navigation pane of the Cluster Management page, choose Workloads > Deployments. On the Deployments page, view the installation details of the deployments of the component.

      If all pods of the component are started, the installation of the component is complete.

Enable the accelerated image

1. Configure access credential for the repository where the accelerated image resides.

   Warning

   Make sure that the principle of least privilege is followed when you configure the secret that is used to pull images and only the required permissions are granted. For more information, see Attach a custom policy to a RAM user.

   • Use the aliyun-acr-credential-helper component that allows you to pull images from an image repository without using secrets.

     • If the aliyun-acr-credential-helper component has been configured for the cluster and the specified information about the Container Registry Enterprise Edition instance is correct, you can skip this step.

     • If the aliyun-acr-credential-helper component has not been configured for the cluster, you can configure the component for the cluster. For more information, see Use the aliyun-acr-credential-helper component to pull images without using a secret.

   • Specify a label for the secret that is used to pull images.

     Note

     Only the aliyun-acr-acceleration-suite component of V0.2.6 or later supports this method.

     Run the following commands to create a secret whose type is kubernetes.io/dockerconfigjson and whose label is images.alibabacloud.com/accelerated: true:

     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. Attach the image acceleration label.

   You can attach the image acceleration label to workloads such as pods and Deployments. You can also attach an image acceleration label to a namespace of the ACK cluster or ACK Serverless cluster. The on-demand image loading feature is applied to all workloads in the namespace that meet acceleration conditions. This way, you do not need to edit the YAML file for each workload. You can use one of the following methods to attach the image acceleration label to a specific workload or all workloads in a namespace:

   Note

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

   • Attach the image acceleration label to a workload.

     The following example shows how to attach the image acceleration label to pods. Run the following command to attach the image acceleration label to the pods that are managed by a Deployment:

     kubectl edit deployment <Name of the Deployment> -n <Namespace in which the Deployment resides>

     Add the k8s.aliyun.com/image-accelerate-mode: on-demand label to the YAML file of the Deployment.

     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"]

   • Attach the image acceleration label to a namespace.

     • Attach the image acceleration label in the ACK console.

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

       2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side navigation pane, click Namespaces and Quotas.

       3. On the Namespace page, find the namespace that you want to configure and click Edit in the Actions column.

       4. In the Label section of the Edit Namespace dialog box, set Variable Key to k8s.aliyun.com/image-accelerate-mode and Variable Value to on-demand, and click OK.

     • Attach the image acceleration label on the CLI.

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

   If you have attached an image acceleration label to a namespace and converted based images into accelerated images, when you create or update a pod in the namespace, the aliyun-acr-acceleration-suite component automatically uses the URL of the accelerated image of the pod to replace the URL of the base image of the pod, adds a nodeSelector, and then schedules the pod to the accelerated node.