Configure ECI Pod Annotations on ACK Virtual Nodes - ACK

Add annotations to Elastic Container Instance (ECI)-based pods to enable ECI-specific features. This reference lists all supported annotations, organized by category.

Important

These annotations apply only to pods scheduled to virtual nodes. They have no effect on pods scheduled to real nodes.

How to apply annotations

Annotations must be set at pod creation time. Adding or modifying annotations on an existing pod has no effect.

In most cases, you work with Deployments rather than bare pods. Place annotations in the spec.template.metadata.annotations field:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        k8s.aliyun.com/eci-use-specs: "2-4Gi"
    spec:
      ...

Annotations set at creation time

Instances

Annotation	Example	Description
`k8s.aliyun.com/eci-vswitch`	`vsw-bp1xpiowfm5vo8o3c****`	One or more vSwitch IDs. Multiple IDs enable multi-zone scheduling so that pods are created in zones with available resources.
`k8s.aliyun.com/eci-schedule-strategy`	`VSwitchOrdered`	The multi-zone scheduling policy. `VSwitchOrdered` schedules resources in the order the vSwitches are listed. `VSwitchRandom` schedules resources randomly across the specified zones.
`k8s.aliyun.com/eci-use-specs`	`2-4Gi,4-8Gi,ecs.c6.xlarge`	One or more pod specifications. Each value can be a vCPU-and-memory combination (for example, `2-4Gi`) or an ECS instance type (for example, `ecs.c6.xlarge`). Related docs: Specify multiple specifications, Specify vCPUs and memory, Specify ECS instance types
`k8s.aliyun.com/eci-gpu-driver-version`	`tesla=525.85.12`	The GPU driver and CUDA version for GPU-accelerated instances that support multiple driver versions.
`k8s.aliyun.com/eci-instance-family`	`"ecs.c6,ecs.g6"`	ECS instance families to include or exclude when creating pods by vCPU and memory. See Specify or exclude instance families.
`k8s.aliyun.com/eci-instance-generation`	`"6,5"`	Generations of ECS instance families to include or exclude when creating pods by vCPU and memory. See Specify or exclude instance family generations.
`k8s.aliyun.com/eci-compute-category`	`economy`	The compute category when creating pods by vCPU and memory. Valid values: `economy`, `general`. You can specify multiple values; the system selects based on the specified order. See Specify a compute category.
`k8s.aliyun.com/eci-spot-strategy`	`SpotAsPriceGo`	The bid policy for preemptible instances. `SpotWithPriceLimit` uses the maximum hourly price you specify (requires `eci-spot-price-limit`). `SpotAsPriceGo` uses the current market price at the time of purchase. See Create a preemptible instance.
`k8s.aliyun.com/eci-spot-price-limit`	`"0.5"`	The maximum hourly price for a preemptible instance. Accurate to up to three decimal places. Valid only when `eci-spot-strategy` is `SpotWithPriceLimit`.
`k8s.aliyun.com/eci-spot-duration`	`"0"`	The protection period for the preemptible instance. Unit: hours. Default: `1`. Set to `0` to disable the protection period.
`k8s.aliyun.com/eci-spot-fallback`	`"true"`	When set to `true`, automatically creates a pay-as-you-go instance if preemptible instance inventory is insufficient. Default: `false`.
`k8s.aliyun.com/eci-privatepool-matchcriteria`	`"Open"`	The private pool matching mode. `Open` matches open private pools. `Target` targets a specific private pool (requires `eci-privatepool-id`). See Use an elasticity assurance private pool.
`k8s.aliyun.com/eci-privatepool-id`	`eap-2ze1g68k2melxkkl****`	The private pool ID (elasticity assurance ID). Find this on the Resource Reservations or Private Pools tab in the ECS console. Required when `eci-privatepool-matchcriteria` is `Target`. Invalid when set to `Open`.
`k8s.aliyun.com/eci-fail-strategy`	`fail-back`	The fault handling policy. `fail-back` and `fail-over` both retry pod creation automatically after a failure. `fail-fast` reports an error immediately. See Configure a fault handling policy.
`k8s.aliyun.com/eci-max-pending-minute`	`"30"`	The maximum time a pod stays in pending state before the system terminates it. Valid range: 10–1440. Unit: minutes. Default: `240`. See Specify the maximum pending duration.
`k8s.aliyun.com/eci-custom-hosts`	`"[{\"host\":\"example.com\",\"ip\":\"100.100.XX.XX\"}]"`	Entries to add to the pod's `/etc/hosts` file. See Configure hosts for a pod.
`k8s.aliyun.com/eci-custom-tags`	`"env:test,name:alice"`	Custom tags to bind to the pod. Maximum three tags. Separate key and value with a colon (`:`); separate multiple tags with commas (`,`). See Bind custom tags to a pod.
`k8s.aliyun.com/eci-ram-role-name`	`AliyunECIContainerGroupRole`	The RAM role to assign to the pod, allowing it to access other Alibaba Cloud services. See Assign a RAM role to a pod.

Images

Annotation	Example	Description
`k8s.aliyun.com/eci-auto-imc`	`"true"`	Enables automatic image cache matching to accelerate pod creation. See Use image caches to accelerate pod creation.
`k8s.aliyun.com/imc-perfect-match`	`"true"`	Requires all container images in the pod to exactly match the image cache.
`k8s.aliyun.com/imc-match-count-request`	`"2"`	The number of container images that must exactly match the image cache.
`k8s.aliyun.com/eci-imc-id`	`imc-2zebxkiifuyzzlhl****`	The ID of a specific image cache to use.
`k8s.aliyun.com/acr-instance-ids`	`cri-j36zhodptmyq****`	Container Registry Enterprise Edition instance IDs for secretless image pulls. For cross-region pulls, prefix the region ID: `"cn-beijing:cri-j36zhodptmyq****"`. See Pull images without a secret.
`k8s.aliyun.com/acr-service-arns`	`acs:ram::1609982529******:role/role-assume`	The Alibaba Cloud Resource Names (ARNs) of RAM roles in the Alibaba Cloud account that owns the ECI resources. Required when using a RAM role to create resources.
`k8s.aliyun.com/acr-user-arns`	`acs:ram::1298452580******:role/role-acr`	The ARNs of RAM roles in the Alibaba Cloud account that owns the Container Registry instance. Required when pulling images from a Container Registry instance in a different Alibaba Cloud account.
`k8s.aliyun.com/plain-http-registry`	`harbor***.pre.com,192.168.XX.XX:5000`	Self-managed image registry addresses that use HTTP. ECI pulls images over HTTP instead of the default HTTPS, preventing protocol mismatch failures. See Pull from a self-managed registry.
`k8s.aliyun.com/insecure-registry`	`harbor***.pre.com,192.168.XX.XX:5000`	Self-managed image registry addresses that use self-signed certificates. ECI skips certificate verification, preventing authentication failures.

Data caches

Annotation	Example	Description
`k8s.aliyun.com/eci-data-cache-bucket`	`default`	The bucket used to store the DataCache. Required when creating pods with DataCaches. See Use a DataCache to create a pod.
`k8s.aliyun.com/eci-data-cache-pl`	`PL1`	The performance level of the disk created from the DataCache. Default: `PL1` enterprise SSD (ESSD).
`k8s.aliyun.com/eci-data-cache-provisionedIops`	`"40000"`	The read/write IOPS provisioned for an ESSD AutoPL disk. Valid range: `0` to `min{50000, 1000 × storage capacity − Baseline IOPS}`, where Baseline IOPS = `min{1800 + 50 × storage capacity, 50000}`. Adding this annotation creates an ESSD AutoPL disk. See ESSD AutoPL disks.
`k8s.aliyun.com/eci-data-cache-burstingEnabled`	`"true"`	Enables the performance burst feature for an ESSD AutoPL disk. Adding this annotation creates an ESSD AutoPL disk. See ESSD AutoPL disks.

Network

Annotation	Example	Description
`k8s.aliyun.com/eci-security-group`	`sg-bp1dktddjsg5nktv****`	Security groups to assign to the pod. Up to five security groups are supported. All groups must belong to the same virtual private cloud (VPC) and be of the same type. See Assign security groups to a pod.
`k8s.aliyun.com/eci-eip-instanceid`	`eip-bp1q5n8cq4p7f6dzu****`	The ID of an existing elastic IP address (EIP) to associate with the pod. See Associate an EIP.
`k8s.aliyun.com/eci-with-eip`	`"true"`	Automatically creates an EIP and associates it with the pod at creation time.
`k8s.aliyun.com/eip-bandwidth`	`"5"`	The maximum bandwidth of the auto-created EIP. Unit: Mbit/s. Default: `5`.
`k8s.aliyun.com/eip-common-bandwidth-package-id`	`cbwp-2zeukbj916scmj51m****`	The ID of an existing EIP bandwidth plan to associate with the pod. See Internet Shared Bandwidth.
`k8s.aliyun.com/eip-isp`	`BGP`	The line type of the auto-created EIP. Applies to pay-as-you-go EIPs only. Valid values: `BGP` (BGP Multi-ISP), `BGP_PRO` (BGP Multi-ISP Pro). See EIP line types.
`k8s.aliyun.com/eip-internet-charge-type`	`PayByBandwidth`	The metering method for the auto-created EIP. `PayByBandwidth`: pay by bandwidth. `PayByTraffic`: pay by traffic. See EIP billing overview.
`k8s.aliyun.com/eip-public-ip-address-pool-id`	`pippool-bp187arfugi543y1s****`	The ID of the IP address pool from which the auto-created EIP is allocated. See Create and manage IP address pools.
`k8s.aliyun.com/eci-enable-ipv6`	`"true"`	Assigns an IPv6 address to the pod. See Assign an IPv6 address.
`k8s.aliyun.com/eci-ipv6-bandwidth-enable`	`"true"`	Enables Internet access over the pod's IPv6 address.
`k8s.aliyun.com/eci-ipv6-bandwidth`	`100M`	The peak public bandwidth for the IPv6 address.
`k8s.aliyun.com/eci-private-ip-address`	`"172.16.0.1"`	A static private IPv4 address to assign to the pod. The address must be idle. See Specify a private IP address.
`k8s.aliyun.com/eci-fixed-ip`	`"true"`	Configures the pod to retain its private IP address across restarts. See Configure a fixed IP address.
`k8s.aliyun.com/eci-fixed-ip-retain-hour`	`"24"`	How long the fixed IP address is reserved after the pod is released and the address becomes idle. Unit: hours. Default: `48`.
`kubernetes.io/ingress-bandwidth`	`40M`	The inbound bandwidth limit for the pod. See Limit pod bandwidth.
`kubernetes.io/egress-bandwidth`	`20M`	The outbound bandwidth limit for the pod.
`k8s.aliyun.com/eci-custom-dnsconfig`	`"{\"nameservers\":\"20.1.xx.xx,20.1.xx.xx\",\"searches\":\"xx.com,xx.eee\",\"options\":\"ndots:2,edns0\"}"`	A custom Domain Name System (DNS) server for the pod. Useful in hybrid cloud scenarios where internal domain names must be resolved by a specific DNS server. See Configure a custom DNS server.

Storage

Annotation	Example	Description
`k8s.aliyun.com/eci-extra-ephemeral-storage`	`50Gi`	The size of the pod's ephemeral storage space. See Increase ephemeral storage capacity.
`k8s.aliyun.com/eci-ephemeral-storage-options`	`"{\"encrypted\":\"true\"}"`	Ephemeral storage options. Set to `{"encrypted":"true"}` to encrypt the ephemeral storage space. See Encrypt ephemeral storage.
`k8s.aliyun.com/eci-eviction-enable`	`"true"`	Automatically evicts pods whose ephemeral storage space is exhausted. See Automatically evict pods with insufficient ephemeral storage.

Container configuration

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

Logs

Annotation	Example	Description
`k8s.aliyun.com/eci-sls-enable`	`"false"`	Controls whether Simple Log Service (SLS) log collection is enabled for the pod. Set to `false` to disable log collection and prevent automatic Logtail creation. Useful when using SLS custom resource definitions (CRDs) and you want to exclude specific pods from log collection. See Collect logs using SLS CRDs.

O&M

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

Annotations added after scheduling

After the system schedules resources and creates a pod, ECI adds the following read-only annotations. Run kubectl describe pod <pod-name> to view them.

Annotation	Example	Description
`k8s.aliyun.com/eci-request-id`	`45942504-4688-51BA-BBAB-4B692C4F39C0`	The request ID for the pod creation call.
`k8s.aliyun.com/eci-instance-id`	`eci-2ze1y0la40qgva09****`	The ECI instance ID (pod ID).
`k8s.aliyun.com/eci-instance-spec`	`2.0-4.0Gi`	The specifications of the pod. If the value is a vCPU-and-memory size (for example, `2.0-4.0Gi`), billing is based on vCPU and memory. If the value is an ECS instance type (for example, `ecs.c6.large`), billing is based on that instance type.
`k8s.aliyun.com/eci-instance-compute-category`	`economy`	The compute category of the ECS instance type used to create the pod. `economy` pods are billed at the economy compute category rate; `general` pods are billed at the general compute category rate.
`k8s.aliyun.com/allocated-eipInstanceId`	`eip-bp1q5n8cq4p7f6dzu****`	The ID of the EIP associated with the pod.
`k8s.aliyun.com/allocated-eipAddress`	`47.99..`	The EIP address associated with the pod.
`k8s.aliyun.com/allocated-ipv6Address`	`2001:d**:1:1:1:1:1:1`	The 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****`	The ID of the elastic network interface (ENI) bound to the pod.
`k8s.aliyun.com/eci-vpc`	`vpc-2zeghwzptn5zii0w7****`	The VPC to which the pod belongs.
`k8s.aliyun.com/eci-matched-image-cache`	`imc-2zedy3v37800iimu****`	The ID of the image cache matched during pod creation.
`k8s.aliyun.com/eci-schedule-result`	`finished`	Retired. For scheduling results, see ContainerInstanceCreated.