how to configure eci-profile to automatically use imagecache - Elastic Container Instance

The ECI Effect capability in eci-profile lets you define selectors that automatically inject ImageCache-related annotations into matching pods. When a pod matches a selector's label conditions, the system adds the specified annotations without manual intervention — accelerating pod creation without touching individual pod specs.

Note: For background on eci-profile, see Configure an eci-profile.

Prerequisites

Before you begin, ensure that you have:

Access to a Kubernetes cluster with ECI enabled
Permission to edit the eci-profile ConfigMap in the kube-system namespace
kubectl configured to communicate with your cluster

How it works

eci-profile uses a mutating webhook (vk-webhook) to intercept pod creation requests. When a pod is created, the webhook checks the pod's labels and its namespace's labels against the selectors defined in eci-profile. If a match is found, the webhook injects the corresponding annotations into the pod — enabling image cache acceleration automatically.

ImageCache annotations

The following annotations control how image caches are used during pod creation.

Annotation	Example value	Description
`k8s.aliyun.com/eci-auto-imc`	`"true"`	Enables automatic image cache matching. When set to `"true"`, the system selects the most suitable image cache based on: image match degree, image size, and creation time. If no exact match exists, the system creates a new image cache when the pod is created. Default: `"true"`.
`k8s.aliyun.com/imc-perfect-match`	`"true"`	Requires all container images in the pod to exactly match the image cache. Default: `"false"`.
`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 by ID.

Selector fields

Each selector in eci-profile's selectors array has the following fields:

Field	Required	Description
`name`	Yes	A unique name for the selector.
`namespaceSelector`	No	Matches pods based on namespace labels. If omitted, all namespaces are eligible.
`objectSelector`	No	Matches pods based on pod labels. If omitted, all pods in matching namespaces are eligible.
`effect.annotations`	Yes	The annotations to inject into matched pods.

When multiple labels are specified in namespaceSelector.matchLabels or objectSelector.matchLabels, all labels must match (AND logic).

Configure selectors

Open the eci-profile ConfigMap for editing:
```
kubectl -n kube-system edit cm eci-profile
```

Add your selectors to the selectors field in array form:

selectors: |
 [
  {
      "name": "demo",
      "namespaceSelector": {
          "matchLabels": {
              "app": "nginx"
          }
      },
      "objectSelector": {
          "matchLabels": {
              "type": "test"
          }
      },
      "effect": {
          "annotations": {
              "k8s.aliyun.com/eci-auto-imc": "true"
          }
      }
  }
 ]

Save and exit the editor. Kubernetes applies the changes automatically.

Verify the configuration

Run the following command to confirm the selectors are active:

kubectl get mutatingwebhookconfigurations -o yaml vk-webhook

If the returned YAML contains the configured selectors, the selectors take effect. If the selectors are absent, check for JSON formatting errors in the selectors field of the ConfigMap.

Example

The following example defines two selectors with different matching strategies.

Edit the eci-profile ConfigMap:

kubectl -n kube-system edit cm eci-profile

Add the following content to the selectors field:

[
  ...
  {
    "name": "image-cache-selector-1",
    "objectSelector": {
      "matchLabels": {
        "image-cache": "true"
      }
    },
    "effect": {
      "annotations": {
        "k8s.aliyun.com/eci-imc-id": "imc-uf6ic***************"
      }
    }
  },
  {
    "name": "image-cache-selector-2",
    "namespaceSelector": {
      "matchLabels": {
        "image-cache": "true"
      }
    },
    "effect": {
      "annotations": {
        "k8s.aliyun.com/eci-auto-imc": "true"
      }
    }
  }
]

How each selector works:

image-cache-selector-1: Any pod with the image-cache: true label gets the annotation k8s.aliyun.com/eci-imc-id: imc-uf6ic*************** injected automatically, pinning it to the specified image cache.
image-cache-selector-2: Any pod created in a namespace with the image-cache: true label gets the annotation k8s.aliyun.com/eci-auto-imc: "true" injected automatically, enabling automatic image cache matching for all pods in that namespace.

What's next

Configure an eci-profile