Container Registry:Load resources of a container image on demand

Prerequisites

Before you begin, make sure you have:

• A Container Registry Enterprise Edition instance. See Create a Container Registry Enterprise Edition instance

• The Virtual Private Cloud (VPC) of the cluster added to the access control list (ACL) of the Container Registry Enterprise Edition instance. Accelerated images run in VPCs only. See Configure a VPC ACL

• An ACK cluster running a supported version and operating system (see the compatibility table below)

Compatibility

Choose an acceleration mode

Select a mode based on your speed requirements, storage constraints, and runtime environment.

Limitations

• On-demand image loading is not supported in Alibaba Finance Cloud or Alibaba Gov Cloud regions.

• Existing images require manual conversion to the accelerated format; only newly pushed images convert automatically after you enable acceleration on a repository.

• Docker runtime does not support custom domain names for accelerated image repositories. If your container runtime is containerd, you can set custom domain names. See Use a custom domain name to access a Container Registry Enterprise Edition instance.

Convert a base image to an accelerated image

Enable image acceleration on a repository. After that, every image pushed to the repository converts automatically. The base image is not modified — the accelerated image is stored under a new tag.

Accelerated image tag format:

• Index-only mode: <base-tag>_accelerated

  • Requires containerd runtime

  • The base image tag cannot be deleted while the accelerated image is in use

• Full mode: <base-tag>_accelerated (Docker and containerd) or <base-tag>_containerd_accelerated (containerd only)

  • The _containerd_accelerated image and its base image cannot be deleted while in use

The namespace and repository name of the accelerated image are identical to those of the base 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 you want to manage.

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

6. Find the repository for which you want to enable image acceleration. Click the repository name or click Manage in the Actions column, then click Edit in the upper-left corner.

7. In the Modify Settings dialog box, go to the Accelerated Image section, select Enabled, choose an acceleration mode, and click Confirm. After you enable acceleration, every image pushed to the repository converts automatically. To receive a notification each time a conversion completes, configure an event notification with an expression-based trigger set to _accelerated$. See Event notification.

   • Full Mode: Significantly accelerates container startup. The accelerated image is ~130% the size of the base image. Conversion takes ~25 seconds per 1 GB. Previously converted layers are not re-converted.

   • Index-only Mode: Provides ~70% the acceleration effect of full mode. The accelerated image is ~3% the size of the base image. Conversion takes ~3 seconds per 1 GB. Previously indexed layers are not re-indexed.

8. (Optional) Specify a Prefetch File List. Files in this list are prefetched when an accelerated container starts, reducing runtime latency for large files that must be read at startup. Enter one absolute file path per line. For directories, append a trailing slash (/).

   If a large file (for example, a machine learning model or a static asset bundle) is always read during container initialization, add it to the Prefetch File List. This eliminates the on-demand fetch penalty for that file.

Install the aliyun-acr-acceleration-suite component

The aliyun-acr-acceleration-suite component must run on each worker node that starts containers using accelerated images.

Enable on-demand loading for workloads

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 <deployment-name> -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 for this workload
        k8s.aliyun.com/image-accelerate-mode: on-demand
    spec:
      containers:
        - 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

What's next

• Event notification — Monitor image conversion events

• Attach a custom policy to a RAM user — Set least-privilege permissions for image pulling

• Use the aliyun-acr-credential-helper component to pull images without using a secret — Simplify credential management