Manage ImageCaches-Elastic Container Instance(ECI)-阿里云帮助中心

When you run large container images or scale pods frequently, image pulls from a remote registry can add minutes to pod startup. An ImageCache is a Kubernetes CustomResourceDefinition (CRD) provided by Elastic Container Instance (ECI) that pre-caches container images as snapshots. When ECI creates a pod, it loads images directly from the cache—significantly reducing startup time for large images or frequently scaled workloads.

This topic describes how to create, query, and delete an ImageCache.

An ImageCache is stored as a snapshot and incurs snapshot costs as long as it exists. Delete ImageCaches that are no longer in use.

Prerequisites

Before you begin, ensure that you have:

A Kubernetes cluster with the ack-virtual-node component installed
kubectl access to the cluster

Check whether your cluster supports ImageCaches

Run the following command to verify that the ImageCache CRD is installed:

kubectl get crd/imagecaches.eci.alibabacloud.com

If the CRD is not found, the output looks similar to:

Error from server (NotFound): customresourcedefinitions.apiextensions.k8s.io "imagecaches.eci.alibabacloud.com" not found

Update ack-virtual-node to a version that supports ImageCaches. We recommend that you update the ack-virtual-node component to the latest version to use new features. For version information and update instructions, see ack-virtual-node and Manage system components.

If the CRD is installed, the output looks similar to:

NAME                               CREATED AT
imagecaches.eci.alibabacloud.com   2024-01-23T05:54:44Z

If the installed CRD is not the latest version, apply the updated CRD manifest:

kubectl apply -f imagecache-crd-sample.yaml

<details> <summary>View imagecache-crd-sample.yaml</summary>

apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: imagecaches.eci.alibabacloud.com
spec:
  group: eci.alibabacloud.com
  version: v1
  names:
    kind: ImageCache
    plural: imagecaches
    shortNames:
    - ic
    categories:
    - all
  scope: Cluster
  subresources:
    status: {}
  validation:
    openAPIV3Schema:
      required:
      - spec
      properties:
        spec:
          type: object
          required:
          - images
          properties:
            imagePullSecrets:
              type: array
              items:
                type: string
            images:
              minItems: 1
              type: array
              items:
                type: string
            imageCacheSize:
              type: integer
            retentionDays:
              type: integer
  additionalPrinterColumns:
  - name: Age
    type: date
    JSONPath: .metadata.creationTimestamp
  - name: CacheId
    type: string
    JSONPath: .status.imageCacheId
  - name: Phase
    type: string
    JSONPath: .status.phase
  - name: Progress
    type: string
    JSONPath: .status.progress

</details>

Create an ImageCache

Configure the YAML manifest

Create a YAML file (for example, imagecache-test.yaml) with the following structure. Each field is annotated inline for quick reference.

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample-test
  annotations:
    k8s.aliyun.com/imc-enable-reuse: "true"  # Enables ImageCache reuse across pods
spec:
  images:                                      # [Required] Images to cache
  - registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
  - registry.cn-shanghai.aliyuncs.com/eci_open/busybox:1.30
  imagePullSecrets:                            # [Optional] Secrets for private image repositories
  - default:secret1                            # Format: namespace:secretName
  - default:secret2
  - kube-system:secret3
  imageCacheSize: 25                           # [Optional] Cache size in GiB. Default: 20. Range: 20-32768.
                                               # Must be >= 2x the image size.
  retentionDays: 7                             # [Optional] Days before the cache is deleted. Default: never expires.

Parameter reference:

Parameter	Type	Required	Description
`spec.images`	String[]	Yes	Container images to include in the cache
`spec.imagePullSecrets`	String[]	No	Secrets for private image repositories, in `namespace:secretName` format. Omit for public images.
`spec.imageCacheSize`	int	No	Cache size in GiB. Default: `20`. Valid range: `20`–`32768`. Set to at least twice the image size.
`spec.retentionDays`	int	No	Number of days to retain the cache before automatic deletion. Left blank by default (never expires).

Use annotations to enable additional ImageCache features. For example, k8s.aliyun.com/imc-enable-reuse: "true" allows multiple pods to share the same ImageCache. For a full list of supported annotations, see ImageCache annotations. For the complete API reference, see Kubernetes ImageCache API.

Apply the manifest

kubectl create -f imagecache-test.yaml

Verify the ImageCache is ready

kubectl get imagecache imagecache-sample-test

The ImageCache is ready when PHASE shows Ready and PROGRESS reaches 100%:

NAME                     AGE     CACHEID                    PHASE   PROGRESS
imagecache-sample-test   5m30s   imc-2ze2kbf9l1onf03z****   Ready   100%

Query ImageCaches

List all ImageCaches in the cluster:

kubectl get imagecache

Get the full configuration and status of a specific ImageCache:

kubectl get imagecache <imagecache-name> -o yaml

Delete an ImageCache

kubectl delete imagecache <imagecache-name>

An ImageCache is a snapshot. Delete ImageCaches that are no longer needed to avoid ongoing snapshot costs.