All Products
Search

This Product

    Container Service for Kubernetes:Accelerate pod creation with ImageCache

    Document Center

    Container Service for Kubernetes:Accelerate pod creation with ImageCache

    Last Updated:Jun 18, 2026

    Before an ECI runs, it must pull the required container images, and image pulling is the main delay in pod startup. ImageCache pre-creates cache snapshots of container images so that subsequent pod creation can reuse the cache to cut pod startup time on virtual nodes.

    Actual time saved varies by image count, size, and network conditions.

    Billing

    Image cache creation and usage may incur fees. See Image caches billing.

    Prerequisites

    Make sure you have:

    • An ACK cluster with virtual nodes enabled

    • kubectl access to the cluster

    Step 1: Enable ImageCache support

    Check whether your cluster supports ImageCache:

    kubectl get crd/imagecaches.eci.alibabacloud.com

    • If information about imagecaches.eci.alibabacloud.com is returned, ImageCache is supported. Proceed to Step 2.

    • If an error is returned, update ACK Virtual Node to the latest version.

    Step 2: Create an image cache

    Use automatic creation unless you need maximum speed for the first pod.

    Method When to use How it works
    Automatic Most cases — saves cost If no matching cache exists, the system creates one during pod creation. Future pods with the same images reuse it.
    Manual First-time creation requiring maximum speed Create an image cache in advance using a YAML template, then reference it when creating the pod.

    For manual creation, see Manage ImageCaches and Image cache annotations. Compare methods in Methods to create an image cache.

    Step 3: Use an image cache to create pods

    Add annotations to the metadata section of your pod spec (or spec.template.metadata in a Deployment) to select an image cache.

    Important

    Annotations only take effect at pod creation. Changing annotations on an existing pod has no effect.

    Annotations reference

    ImageCache is a cluster-level resource usable across namespaces.

    Important

    • Image matching: Use the same image references in your pod spec as in the ImageCache to maximize match degree.

    • Pull policy: Set imagePullPolicy to IfNotPresent to skip re-downloading cached layers.

    Annotation Example value Default Description
    k8s.aliyun.com/eci-auto-imc "true" true Enables automatic image cache matching. Selects the best match by image match degree, size, and creation time. Creates a new cache if no match exists.
    k8s.aliyun.com/imc-perfect-match "true" false Requires all pod images to fully match the image cache. Takes precedence over imc-match-count-request.
    k8s.aliyun.com/imc-match-count-request "2" — The number of pod images that must match the image cache.
    k8s.aliyun.com/eci-imc-id imc-2zebxkiifuyzzlhl**** — Pins the pod to a specific image cache by ID. Takes precedence over automatic matching.

    Annotation precedence: If both imc-perfect-match and imc-match-count-request are set, imc-perfect-match takes precedence. When eci-imc-id is specified, it overrides automatic matching.

    Automatically match an image cache (recommended)

    Enable eci-auto-imc and optionally add imc-perfect-match for stricter matching:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true"
      annotations:
        k8s.aliyun.com/eci-auto-imc: "true"          # Enables automatic image cache matching
        k8s.aliyun.com/imc-perfect-match: "true"      # All images in the pod must fully match the cache
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80
        imagePullPolicy: IfNotPresent
      - name: busybox
        image: registry.cn-shanghai.aliyuncs.com/eci_open/busybox:1.30
        command: ["sleep"]
        args: ["999999"]
        imagePullPolicy: IfNotPresent

    Specify an image cache

    Important

    The specified image cache must be in Ready state. Otherwise, pod creation fails.

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true"
      annotations:
        k8s.aliyun.com/eci-imc-id: imc-2ze5tm5gehgtiiga****  # Pins to a specific image cache
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80
        imagePullPolicy: IfNotPresent

    Apply annotations in bulk

    Use the Elastic Container Instance Effect feature in eci-profile to apply ImageCache annotations to all matching pods. See Configure eci-profile to automatically use the ImageCache feature.

    Next steps