Accelerate ACS pod startup with ImageCache

How it works

Before running a container, an ACS pod must pull the specified container image. However, factors such as network conditions and container image size often make image pulling the longest step in pod startup. To accelerate instance startup, ACS provides the ImageCache feature. By pre-creating an ImageCache from a container image, you can create ACS pods that use the cache. This avoids or reduces image layer downloads and shortens startup time.

The actual speed improvement depends on factors such as the size of the container image used by the ACS pod and the network connectivity to the image repository.

Each ImageCache can contain one image. An ImageCache with the In Progress status is being built. Once its status changes to Completed, it is ready for use.

The time required to create an ImageCache depends on the container image size and the configured network bandwidth. Creation may time out and fail due to issues such as network connectivity problems, authentication failure, or a non-existent repository or tag.

Billing

Considerations

• Permissions: Creating an ImageCache creates a Service-Linked Role. Therefore, ensure the RAM user has the ram:CreateServiceLinkedRole permission.

• Quotas and limitations:

  • After an ImageCache is created, its size is displayed. This value is the total size of the decompressed container image files and the ImageCache index files. ImageCache supports container images with a compressed size of up to 500 GiB.

  • The default quota for ImageCaches is 200 per region. You can submit a ticket to request a quota increase.

  • You can create a maximum of 50 ImageCaches concurrently in a single region. Completed ImageCaches do not count towards this limit.

  • If your ImageCache quota exceeds 10,000, filtering by tag and resource group is ignored when you call the ListImageCaches API. At this scale, do not use tags or resource groups for management.

• Scope:

  • Supported regions: ImageCache is available in China (Beijing), China (Shanghai), China (Hangzhou), China (Ulanqab), China (Shenzhen), China (Hong Kong), and Singapore.

  • Supported image types for CPU instances: linux/amd64 and windows/amd64. The default is linux/amd64.

  • Supported GPU models and image types: For GPU compute, ImageCache supports the G59, G49E, and L20 (GN8IS) instance types, and the linux/amd64 image type. For more information about the GPU models supported by ACS, see Accelerated compute instance families.

  • The ACS console only supports creating linux/amd64 ImageCaches. To create a Windows ImageCache, use the OpenAPI and set the Platform parameter to windows/amd64.

• Network connectivity: When using an existing ImageCache, ensure network connectivity between the pod and the image repository.

• Pull policy: GPU instances only support imagePullPolicy: Always.

Create an ImageCache

Use an ImageCache

After you enable this feature, the pod automatically matches and uses the optimal ImageCache based on the following criteria:

• Image match: The ImageCache image name must exactly match the image specified in the pod.

• Creation time: The most recent available ImageCache is preferred.

1. On the Clusters page, click the name of the target cluster. In the left-side navigation pane, choose Workloads > Pods, and then click Create from YAML.

2. Use the following YAML to create a pod and add the annotation to enable the ImageCache matching feature.

   Ensure that the network configuration and credentials provide access to the specified image repository.

3. apiVersion: v1
   kind: Pod
   metadata:
     labels:
       name: hello-pod
     name: hello-pod
     annotations:
       image.alibabacloud.com/enable-image-cache: "true"
   spec:
     containers:
       - image: egs-registry.cn-hangzhou.cr.aliyuncs.com/egs/vllm:0.9.0.1-pytorch2.7-cu128-20250612 # Replace with your image address.  
         command: ["/bin/sleep", "infinity"]
         imagePullPolicy: Always
         name: hello-pod
         ports:
           - containerPort: 8080
             protocol: TCP
         resources: {}
         securityContext:
           capabilities: {}
           privileged: false
         terminationMessagePath: /dev/termination-log
     dnsPolicy: ClusterFirst
     restartPolicy: Always

4. After the pod is created, click its name to go to the Overview page. When the ImageCache matching feature is enabled, the system automatically adds an annotation with information about the matched ImageCache to the pod.

   Function	Parameter	Example	Description
   ImageCache hit information	image.alibabacloud.com/matched-image-caches	[{"imageCacheId":"imc-*****t15xuii6tz*****","size":30}]	The ID and size (in GiB) of the matched ImageCache.