Understand ECI Pod Annotations in ACK Serverless - ACK

Add annotations to pods running as Elastic Container Instances (ECIs) to enable specific ECI features—such as spot pricing, fixed IPs, image caches, and Elastic IP Address (EIP) binding. This page lists all supported annotations grouped by category, and identifies which annotations you add at pod creation time versus which the system generates after scheduling.

Usage notes

Annotations apply only to pods scheduled to virtual nodes. They have no effect on pods scheduled to real nodes.
Add annotations to spec.template.metadata.annotations in your workload manifest. For example, when you create a Deployment, add annotations in the spec.template.metadata section.
Annotations take effect only when a pod is created. Adding or modifying annotations on an existing pod has no effect.

Example: Deployment with ECI annotations

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
      annotations:                                    # Annotations go here, not at the Deployment level
        k8s.aliyun.com/eci-use-specs: "2-4Gi"        # Pod size: 2 vCPU, 4 GiB memory
        k8s.aliyun.com/eci-spot-strategy: SpotAsPriceGo  # Use spot pricing
    spec:
      containers:
      - name: nginx
        image: nginx:latest

Annotations you can add when creating pods

Instances

Feature	Annotation	Example	Description
Configure multiple zones to create a pod	`k8s.aliyun.com/eci-vswitch`	`vsw-bp1xpiowfm5vo8o3c****`	vSwitch IDs. Specify multiple IDs to allow pod creation in whichever zone has available resources.
	`k8s.aliyun.com/eci-schedule-strategy`	`VSwitchOrdered`	Scheduling policy when multiple vSwitches are specified. `VSwitchOrdered`: try vSwitches in the order listed. `VSwitchRandom`: pick a vSwitch randomly.
Create pods by specifying multiple specifications / Specify the number of vCPUs and memory size / Specify ECS instance types	`k8s.aliyun.com/eci-use-specs`	`2-4Gi,4-8Gi,ecs.c6.xlarge`	One or more pod specifications. Accepts vCPU-memory combinations (e.g., `2-4Gi`) or Elastic Compute Service (ECS) instance types (e.g., `ecs.c6.xlarge`), or a mix of both.
	`k8s.aliyun.com/eci-gpu-driver-version`	`tesla=525.85.12`	GPU driver version for GPU-accelerated ECS instance families that support multiple GPU driver and CUDA versions.
Specify or exclude ECS instance families	`k8s.aliyun.com/eci-instance-family`	`"ecs.c6,ecs.g6"`	Specifies or excludes ECS instance families when the pod size is set by vCPU and memory.
Specify or exclude ECS instance family generations	`k8s.aliyun.com/eci-instance-generation`	`"6,5"`	Specifies or excludes specific generations of ECS instance families when the pod size is set by vCPU and memory.
Specify a compute category	`k8s.aliyun.com/eci-compute-category`	`economy`	Compute category applied when the pod size is set by vCPU and memory. Valid values: `economy`, `general`. Specify multiple values in order of preference; the system selects the first available category.
Create a preemptible instance	`k8s.aliyun.com/eci-spot-strategy`	`SpotAsPriceGo`	Bid policy for the preemptible instance. `SpotAsPriceGo`: use the current market price automatically. `SpotWithPriceLimit`: cap the hourly price (also set `eci-spot-price-limit`).
	`k8s.aliyun.com/eci-spot-price-limit`	`"0.5"`	Maximum hourly price for the preemptible instance, accurate to up to three decimal places. Required when `eci-spot-strategy` is `SpotWithPriceLimit`.
	`k8s.aliyun.com/eci-spot-duration`	`"0"`	Protection period for the preemptible instance. Unit: hours. Default: `1`. Set to `0` for no protection period.
	`k8s.aliyun.com/eci-spot-fallback`	`"true"`	Whether to fall back to a pay-as-you-go instance if spot inventory is insufficient. Default: `false`.
Use a private pool from an elasticity assurance	`k8s.aliyun.com/eci-privatepool-matchcriteria`	`"Open"`	Private pool matching mode. `Open`: match open private pools. `Target`: use a targeted private pool (also set `eci-privatepool-id`).
	`k8s.aliyun.com/eci-privatepool-id`	`eap-2ze1g68k2melxkkl****`	Private pool ID (elasticity assurance ID). Get this from the Resource Reservations or Private Pools tab in the ECS console. Required when `eci-privatepool-matchcriteria` is `Target`; has no effect when set to `Open`.
Configure a fault handling policy	`k8s.aliyun.com/eci-fail-strategy`	`fail-back`	What happens when a pod fails to be created. `fail-back` or `fail-over`: retry pod creation automatically. `fail-fast`: report an error immediately.
Set the maximum pending duration	`k8s.aliyun.com/eci-max-pending-minute`	`"30"`	How long the pod can stay in a pending state before the system terminates it. Valid values: `10`–`1440`. Unit: minutes. Default: `240`.
Configure /etc/hosts	`k8s.aliyun.com/eci-custom-hosts`	`"[{\"host\":\"example.com\",\"ip\":\"100.100.XX.XX\"},{\"host\":\"aliyundoc.com\",\"ip\":\"100.100.XX.XX\"}]"`	Custom entries for the pod's `/etc/hosts` file.
Bind custom tags	`k8s.aliyun.com/eci-custom-tags`	`"env:test,name:alice"`	Custom tags to attach to the pod. Maximum three tags. Format: `key:value`, comma-separated.
Assign a RAM role	`k8s.aliyun.com/eci-ram-role-name`	`AliyunECIContainerGroupRole`	RAM role the pod assumes to access other Alibaba Cloud services.

Spot instance example

Use these annotations together when creating a preemptible instance with a price cap:

annotations:
  k8s.aliyun.com/eci-spot-strategy: SpotWithPriceLimit  # Cap the hourly price
  k8s.aliyun.com/eci-spot-price-limit: "0.5"             # Maximum price: 0.500/hour
  k8s.aliyun.com/eci-spot-fallback: "true"               # Fall back to pay-as-you-go if spot is unavailable

Private pool example

Use these annotations together when using a targeted private pool:

annotations:
  k8s.aliyun.com/eci-privatepool-matchcriteria: Target
  k8s.aliyun.com/eci-privatepool-id: eap-2ze1g68k2melxkkl****  # Required when matchcriteria is Target

Images

Feature	Annotation	Example	Description
Accelerate pod creation with image caches	`k8s.aliyun.com/eci-auto-imc`	`"true"`	Whether to automatically match image caches.
	`k8s.aliyun.com/imc-perfect-match`	`"true"`	Whether all container images in the pod must exactly match the image cache.
	`k8s.aliyun.com/imc-match-count-request`	`"2"`	Number of container images that must exactly match the image cache.
	`k8s.aliyun.com/eci-imc-id`	`imc-2zebxkiifuyzzlhl****`	ID of a specific image cache to use.
Pull images without a secret (Container Registry Enterprise Edition)	`k8s.aliyun.com/acr-instance-ids`	`cri-j36zhodptmyq****`	Container Registry Enterprise Edition instance IDs for secret-free image pulls. For cross-region pulls, prefix the region ID: `"cn-beijing:cri-j36zhodptmyq****"`.
	`k8s.aliyun.com/acr-service-arns`	`acs:ram::1609982529******:role/role-assume`	Alibaba Cloud Resource Names (ARNs) of the RAM roles in the Alibaba Cloud account where ECI resources reside. Required when using a RAM role to create resources.
	`k8s.aliyun.com/acr-user-arns`	`acs:ram::1298452580******:role/role-acr`	ARNs of the RAM roles in the Alibaba Cloud account where the Container Registry instance resides. Required when pulling images from a Container Registry instance that belongs to a different Alibaba Cloud account.
Pull from a self-managed image repository (HTTP)	`k8s.aliyun.com/plain-http-registry`	`harbor.pre.com,192.168.XX.XX:5000,reg.test.com:80`	Address of a self-managed image repository that uses plain HTTP. ECI pulls images over HTTP instead of the default HTTPS, preventing protocol mismatch failures.
Pull from a self-managed image repository (self-signed certificate)	`k8s.aliyun.com/insecure-registry`	`harbor.pre.com,192.168.XX.XX:5000,reg.test.com:80`	Address of a self-managed image repository that uses a self-signed certificate. ECI skips certificate verification, preventing authentication failures.

Data caches

Feature	Annotation	Example	Description
Create a pod using a DataCache	`k8s.aliyun.com/eci-data-cache-bucket`	`default`	Bucket that stores the DataCache. Required when using DataCaches to create pods.
	`k8s.aliyun.com/eci-data-cache-pl`	`PL1`	Performance level of the disk created from the DataCache. Default: `PL1` enhanced SSD (ESSD).
	`k8s.aliyun.com/eci-data-cache-provisionedIops`	`"40000"`	Provisioned read/write IOPS for the ESSD AutoPL disk. Valid range: `0` to `min{50,000, 1000 × storage capacity − baseline IOPS}`, where baseline IOPS = `min{1800 + 50 × storage capacity, 50000}`. Adding this annotation makes the disk an ESSD AutoPL disk. See ESSD AutoPL disks.
	`k8s.aliyun.com/eci-data-cache-burstingEnabled`	`"true"`	Whether to enable the performance burst feature for the ESSD AutoPL disk. Adding this annotation makes the disk an ESSD AutoPL disk. See ESSD AutoPL disks.

Network

Feature	Annotation	Example	Description
Assign security groups	`k8s.aliyun.com/eci-security-group`	`sg-bp1dktddjsg5nktv****`	Security group IDs. Maximum five groups. All groups must belong to the same virtual private cloud (VPC) and be of the same type.
Associate an EIP	`k8s.aliyun.com/eci-eip-instanceid`	`eip-bp1q5n8cq4p7f6dzu****`	ID of an existing EIP to associate with the instance.
	`k8s.aliyun.com/eci-with-eip`	`"true"`	Whether to automatically create an EIP and associate it when the instance is created.
	`k8s.aliyun.com/eip-bandwidth`	`"5"`	Maximum EIP bandwidth. Unit: Mbit/s. Default: `5`.
	`k8s.aliyun.com/eip-common-bandwidth-package-id`	`cbwp-2zeukbj916scmj51m****`	ID of an existing EIP bandwidth plan to associate with the instance. See What is an Internet Shared Bandwidth?
	`k8s.aliyun.com/eip-isp`	`BGP`	Line type for the EIP. Applies only to pay-as-you-go EIPs. `BGP`: BGP (Multi-ISP) line. `BGP_PRO`: BGP (Multi-ISP) Pro line. See What is an EIP.
	`k8s.aliyun.com/eip-internet-charge-type`	`PayByBandwidth`	EIP billing method. `PayByBandwidth`: pay-by-bandwidth. `PayByTraffic`: pay-by-traffic. See Billing overview.
	`k8s.aliyun.com/eip-public-ip-address-pool-id`	`pippool-bp187arfugi543y1s****`	ID of the IP address pool from which the EIP is allocated. See Create and manage IP address pools.
Assign an IPv6 address	`k8s.aliyun.com/eci-enable-ipv6`	`"true"`	Whether to assign an IPv6 address to the pod.
	`k8s.aliyun.com/eci-ipv6-bandwidth-enable`	`"true"`	Whether to enable internet access over the IPv6 address.
	`k8s.aliyun.com/eci-ipv6-bandwidth`	`100M`	Peak public bandwidth of the IPv6 address.
Specify a private IP address	`k8s.aliyun.com/eci-private-ip-address`	`"172.16.0.1"`	Private IP address for the pod. Only IPv4 is supported. The address must be unoccupied.
Use a fixed IP address	`k8s.aliyun.com/eci-fixed-ip`	`"true"`	Whether to assign a fixed IP address to the pod.
	`k8s.aliyun.com/eci-fixed-ip-retain-hour`	`"24"`	How long the fixed IP address is retained after the pod is released and the IP becomes idle. Unit: hours. Default: `48`.
Limit inbound and outbound bandwidth	`kubernetes.io/ingress-bandwidth`	`40M`	Maximum inbound bandwidth.
	`kubernetes.io/egress-bandwidth`	`20M`	Maximum outbound bandwidth.
Configure a custom DNS server	`k8s.aliyun.com/eci-custom-dnsconfig`	`"{\"nameservers\":\"20.1.xx.xx,20.1.xx.xx\",\"searches\":\"xx.com,xx.eee\",\"options\":\"ndots:2,edns0\"}"`	Custom DNS configuration for the pod. Used in hybrid cloud scenarios to resolve internal domain names.

EIP example

Use these annotations together when automatically creating and associating an EIP:

annotations:
  k8s.aliyun.com/eci-with-eip: "true"                  # Auto-create an EIP
  k8s.aliyun.com/eip-bandwidth: "10"                   # 10 Mbit/s bandwidth
  k8s.aliyun.com/eip-internet-charge-type: PayByTraffic # Bill by traffic

IPv6 example

Use these annotations together to enable IPv6 with internet access:

annotations:
  k8s.aliyun.com/eci-enable-ipv6: "true"           # Assign an IPv6 address
  k8s.aliyun.com/eci-ipv6-bandwidth-enable: "true"  # Enable internet access over IPv6
  k8s.aliyun.com/eci-ipv6-bandwidth: "100M"         # Peak bandwidth: 100 Mbit/s

Storage

Feature	Annotation	Example	Description
Increase ephemeral storage capacity	`k8s.aliyun.com/eci-extra-ephemeral-storage`	`50Gi`	Size of the ephemeral storage space.
Encrypt ephemeral storage	`k8s.aliyun.com/eci-ephemeral-storage-options`	`"{\"encrypted\":\"true\"}"`	Options for the ephemeral storage space. Set to `{"encrypted":"true"}` to enable encryption.
Auto-evict pods with insufficient ephemeral storage	`k8s.aliyun.com/eci-eviction-enable`	`"true"`	Whether to automatically evict pods that run out of ephemeral storage space.

Container configuration

Feature	Annotation	Example	Description
Configure the NTP service	`k8s.aliyun.com/eci-ntp-server`	`100.100..`	IP address of the Network Time Protocol (NTP) server.

Logs

Feature	Annotation	Example	Description
Collect logs using Simple Log Service CRDs	`k8s.aliyun.com/eci-sls-enable`	`"false"`	Whether to enable log collection. Set to `false` to opt specific pods out of log collection when using Simple Log Service custom resource definitions (CRDs), preventing unnecessary Logtail instances from being created.

O&M

Feature	Annotation	Example	Description
View core dump files	`k8s.aliyun.com/eci-core-pattern`	`/pod/data/dump/core`	Directory where core dump files are stored.

Annotations added after scheduling

After the system schedules resources and creates a pod, these annotations are automatically added. Run kubectl describe pod <pod-name> to view them.

Annotation	Example	Description
`k8s.aliyun.com/eci-request-id`	`45942504-4688-51BA-BBAB-4B692C4F39C0`	Request ID for the pod creation call.
`k8s.aliyun.com/eci-instance-id`	`eci-2ze1y0la40qgva09****`	ECI instance ID of the pod.
`k8s.aliyun.com/eci-instance-spec`	`2.0-4.0Gi`	Actual specifications of the pod. If the value is a vCPU-memory pair (e.g., `2.0-4.0Gi`), billing is based on vCPU and memory. If the value is an ECS instance type (e.g., `ecs.c6.large`), billing is based on that instance type.
`k8s.aliyun.com/eci-instance-compute-category`	`economy`	Compute category of the ECS instance type used for the pod. `economy`: billed at economy category rates. `general`: billed at general category rates.
`k8s.aliyun.com/allocated-eipInstanceId`	`eip-bp1q5n8cq4p7f6dzu****`	ID of the EIP associated with the instance.
`k8s.aliyun.com/allocated-eipAddress`	`47.99..`	Public IP address of the associated EIP.
`k8s.aliyun.com/allocated-ipv6Address`	`2001:d**:1:1:1:1:1:1`	IPv6 address assigned to the pod.
`k8s.aliyun.com/eci-created-by-template`	`true`	Whether the pod was created from a template.
`k8s.aliyun.com/eni-instance-id`	`eni-2ze6d7oo5ukqj26o****`	ID of the elastic network interface (ENI) bound to the pod.
`k8s.aliyun.com/eci-vpc`	`vpc-2zeghwzptn5zii0w7****`	ID of the VPC the pod belongs to.
`k8s.aliyun.com/eci-matched-image-cache`	`imc-2zedy3v37800iimu****`	ID of the image cache matched during pod creation.
`k8s.aliyun.com/eci-schedule-result`	`finished`	Scheduling result. Retired. For current pod scheduling status, see ContainerInstanceCreated.