How to use ImageCache to accelerate the creation of pods - Container Service for Kubernetes

Elastic Container Instance provides the ImageCache CustomResourceDefinition (CRD), which caches container image layers so that new elastic container instances start faster. Instead of pulling all image layers from a remote registry each time you create an instance, an ImageCache lets the instance reuse pre-cached layers. This reduces container startup time, especially for large images or environments with unreliable network connectivity.

This topic explains how to deploy the ImageCache CRD, create an ImageCache, and use it to speed up elastic container instance creation. For background information, see Overview of image caches.

Note

The actual time saved depends on the number of images, their sizes, and current network conditions.

Billing

Creating and using an ImageCache may incur fees for associated resources. For details, see Image caches billing.

Before you begin

Verify that your cluster supports the ImageCache CRD by running the following command:

kubectl get crd/imagecaches.eci.alibabacloud.com

If the command returns information about imagecaches.eci.alibabacloud.com, your cluster already supports ImageCache. Proceed to the next step.
If the command returns an error, update the ACK Virtual Node component to the latest version to enable ImageCache support.

Step 1: Create an ImageCache

You can create an ImageCache in one of two ways: automatically or manually.

Method	Description
Automatic creation	When you create an elastic container instance with automatic matching enabled, the system looks for a matching ImageCache. If no match is found, the system creates an ImageCache alongside the elastic container instance. This cache accelerates future instances that use the same images.
Manual creation	If you need the first elastic container instance to start as quickly as possible, create an ImageCache in advance by defining it in a YAML file. For more information, see Manage ImageCaches and Image cache annotations.

Note

Unless you need to accelerate the very first elastic container instance creation, use automatic creation to save costs.
For a detailed comparison of the two methods, see Methods to create an ImageCache.

Step 2: Use an ImageCache to create an elastic container instance

After you have an ImageCache available, you can either let the system automatically match a suitable ImageCache or manually specify one by its ID.

We recommend automatic matching with imc-perfect-match enabled for stricter matching. The following precedence rules apply:

If both imc-perfect-match and imc-match-count-request are configured, imc-perfect-match takes precedence.
If both automatic matching and manual specification are configured, manual specification takes precedence.

For more information, see Overview of image caches.

Key annotations

The following table lists the annotations that control ImageCache matching behavior.

Match method	Annotation	Example value	Description
Automatic matching	`k8s.aliyun.com/eci-auto-imc`	`"true"`	Enables automatic image cache matching. Default value: `"true"`. The system selects the most suitable ImageCache based on: the matching degree of the image, the size of the image, and the time when the image was created. If no ImageCache is exactly matched, the system automatically creates one when the elastic container instance is created.
	`k8s.aliyun.com/imc-perfect-match`	`"true"`	Requires all container images in the pod to fully match the ImageCache. Default value: `"false"`.
	`k8s.aliyun.com/imc-match-count-request`	`"2"`	Sets the number of container images in the pod that must exactly match the ImageCache.
Manual specification	`k8s.aliyun.com/eci-imc-id`	`imc-2zebxkiifuyzzlhl****`	Specifies the ID of an image cache to use when creating the pod.

Configuration guidelines

Cluster-level resource: An ImageCache is a cluster-level resource and can be used across different namespaces.
Annotation placement: Add annotations to the metadata section of the pod configuration. For example, in a Deployment, place them under spec.template.metadata.
Creation-time only: These annotations take effect only when a pod is created. Adding or modifying annotations on an existing elastic container instance has no effect.
Bulk configuration with eci-profile: The eci-profile feature can dynamically add ImageCache-related annotations to pods based on predefined conditions, so you do not need to update each pod YAML file individually. For more information, see Configure eci-profile to automatically use the ImageCache feature.

Important

Image matching: Specify images that align with your ImageCache contents to improve the match degree and take full advantage of caching.
Pull policy: Set imagePullPolicy to IfNotPresent to prevent the container runtime from re-downloading image layers that already exist in the cache.

Example: Automatically match an ImageCache

The following Deployment automatically matches an ImageCache and requires a perfect match for all container images in the pod.

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 match of image caches
        k8s.aliyun.com/imc-perfect-match: "true"  # Specifies that all container images in the pod must match the image 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

Example: Manually specify an ImageCache

If you already have a specific ImageCache that you want to use, specify its ID directly with the k8s.aliyun.com/eci-imc-id annotation.

Important

Make sure that the specified image cache is in the Ready state. Otherwise, the pod fails to be created.

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****  # Specifies an image cache.
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80
        imagePullPolicy: IfNotPresent