Use an ImageCache to accelerate the creation of ECI pods - Elastic Container Instance

Pulling container images from a registry at pod creation time adds latency, especially for large images or in environments with slow network access. ImageCache is an Elastic Container Instance (ECI) feature exposed as a Kubernetes CustomResourceDefinition (CRD). Add annotations to your pod metadata to let ECI match a pre-built image cache at pod creation time, so image layers are already on disk instead of being pulled from the registry.

Annotations take effect only when a pod is created. Adding or modifying annotations on an existing pod has no effect.

How it works

Create an ImageCache resource containing the images your pods use.
Add annotations to spec.template.metadata in your pod or Deployment manifest.
When ECI creates the pod, it matches the annotation against available ImageCache resources and mounts the cached layers, skipping the image pull.

ImageCache is a cluster-level resource. Pods in any namespace within the cluster can use it.

Prerequisites

Before you begin, ensure that you have:

A Kubernetes cluster with ECI enabled
At least one ImageCache resource in the Ready state (required when pinning with eci-imc-id)

Annotations

Add the following annotations to the metadata section of your pod spec. For Deployments, place them in spec.template.metadata.

Annotation	Example value	Default	Description
`k8s.aliyun.com/eci-auto-imc`	`"true"`	`"true"`	Enables automatic image cache matching. ECI selects the best match based on image match degree, image size, and creation time. If no cache matches, ECI creates one automatically.
`k8s.aliyun.com/imc-perfect-match`	`"true"`	`"false"`	Requires all container images in the pod to match the image cache.
`k8s.aliyun.com/imc-match-count-request`	`"2"`	—	Specifies the number of container images in the pod that you want to exactly match the image cache.
`k8s.aliyun.com/eci-imc-id`	`imc-2zebxkiifuyzzlhl****`	—	Pins the pod to a specific image cache.

Priority rules

When multiple annotations are set, the following precedence applies:

eci-imc-id (pin to specific cache) overrides automatic matching (eci-auto-imc).
Within automatic matching, imc-perfect-match overrides imc-match-count-request if both are set. Prefer imc-perfect-match.

Configuration examples

For best results in both examples:

Use images that are already included in the ImageCache resource to maximize the cache hit rate.
Set imagePullPolicy: IfNotPresent on every container to skip downloading layers that are already cached.

Example 1: Automatic image cache matching (recommended)

Use eci-auto-imc to let ECI select the best available cache automatically. Add imc-perfect-match: "true" if all images in the pod must be present in the cache.

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"          # Enable automatic cache matching
        k8s.aliyun.com/imc-perfect-match: "true"     # All images must be in the cache
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80
        imagePullPolicy: IfNotPresent                 # Prevents re-downloading cached image layers
      - name: busybox
        image: registry.cn-shanghai.aliyuncs.com/eci_open/busybox:1.30
        command: ["sleep"]
        args: ["999999"]
        imagePullPolicy: IfNotPresent                 # Prevents re-downloading cached image layers

Example 2: Pin to a specific image cache

Use eci-imc-id to target a specific ImageCache resource. The specified cache must be in the Ready state before you apply the manifest, 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****  # ID of the target ImageCache
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80
        imagePullPolicy: IfNotPresent                          # Prevents re-downloading cached image layers

What's next

Overview of the ImageCache feature