Container Service for Kubernetes:Load resources of a container image on demand

Prerequisites

Before you begin, ensure that you have:

• A supported cluster type and version: Supported operating systems when you create the cluster:

  • Alibaba Cloud Linux 2.1903

  • Alibaba Cloud Linux 3.2104

  • Alibaba Cloud Linux 3.2104 LTS 64-bit ARM edition

  • Alibaba Cloud Linux UEFI 2.1903

  • CentOS 7.9

  Cluster type	Minimum version
  ACK managed and dedicated clusters	v1.16.9
  ACK Edge clusters	v1.26.3
  ACK Serverless clusters	v1.26.3
  ACK Lingjun clusters	v1.26.3
  Alibaba Cloud Container Compute Service (ACS)	v1.26.3

• A Container Registry Enterprise Edition instance. See Create a Container Registry Enterprise Edition instance. The CR Enterprise Edition editions that support image acceleration depend on the acceleration mode:

  • Full mode: Standard Edition and Advanced Edition

  • Index-only mode: Basic Edition, Standard Edition, and Advanced Edition

• The virtual private cloud (VPC) of your ACK or ACK Serverless cluster added to the access control list (ACL) of the Container Registry Enterprise Edition instance. Accelerated images run only inside VPCs. See Configure a VPC ACL.

Choose an acceleration mode

Select an acceleration mode before enabling image acceleration on a repository.

Additional constraints for index-only mode:

• Works only with images compressed by tar or tgz. Images compressed with zstd are not supported, because the index-only approach maps byte ranges within the original compressed stream and zstd does not expose a seekable structure.

• Does not support the Docker runtime, because the index-only snapshotter relies on containerd's plugin API, which Docker does not expose.

• Cannot be used in Function Compute or Serverless App Engine (SAE) scenarios.

Limitations

• Custom domain names: containerd supports custom domain names for accelerated image repositories. Docker does not, due to Docker's own restrictions. See Use a custom domain name to access a Container Registry Enterprise Edition instance.

• Existing images: Images already in a repository are not automatically converted when you enable acceleration. Trigger conversion manually.

• Region availability: This feature is not available in Alibaba Finance Cloud and Alibaba Gov Cloud regions.

Convert a base image to an accelerated image

Enable image acceleration on a repository so that every image pushed to that repository is automatically converted to an accelerated image. Conversion runs in the background and does not affect the base image.

About accelerated image tags:

The namespace and repository name of an accelerated image are the same as the base image. The tag format depends on the acceleration mode:

• Index-only mode: base tag + _accelerated suffix (containerd runtime only). Do not delete the base image tag while the accelerated image is in use.

• Full mode: two tag formats are generated:

  • Base tag + _accelerated suffix — supports Docker and containerd runtimes.

  • Base tag + _containerd_accelerated suffix — supports containerd runtime only. Do not delete this image or its base image while either is in use.

Steps:

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 you want to manage.

5. In the left-side navigation pane, choose Repository > Repositories.

6. On the Repositories page, find the repository and click its name, or click Manage in the Actions column. On the repository page, click Edit in the upper-left corner.

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

8. (Optional) In Prefetch File List, enter the absolute paths of files to prefetch at container startup. Use this when large files must be read at startup.

   Enter one absolute path per line. For directories, add a trailing slash (/).

After you enable acceleration, each image pushed to the repository is automatically converted. To receive a notification when conversion completes, configure an event notification with an expression-based trigger and set the expression to _accelerated$. See Event Notification.

Install the aliyun-acr-acceleration-suite add-on

The aliyun-acr-acceleration-suite add-on must be installed on worker nodes before you can start containers using accelerated images. Installation has two steps: enable image acceleration on the node pool, then install the add-on in the ACK console.

Enable on-demand image loading

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

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

kubectl edit deployment <DeploymentName> -n <Namespace>

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 image loading
        k8s.aliyun.com/image-accelerate-mode: on-demand
    spec:
      containers:
        # Use the VPC endpoint of your Container Registry Enterprise Edition instance
        - image: test-registry-vpc.cn-hangzhou.cr.aliyuncs.com/test/nginx:latest
          name: test
          command: ["sleep", "3600"]

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