All Products
Search
Document Center

Elastic Container Instance:Annotations for Elastic Container Instance-based pods

Last Updated:Mar 31, 2026

ECI-based pods support annotations that activate features not available through standard Kubernetes resource fields. This reference lists all supported annotations, organized by category.

How annotations work

Annotations covered in this reference apply only to pods scheduled to virtual nodes (elastic container instances). They have no effect on pods scheduled to regular nodes.

Annotations take effect only at pod creation time. Adding or modifying annotations on an existing pod has no effect.

Add annotations to spec.template.metadata.annotations in your workload manifest, not to the top-level metadata. The following Deployment shows the correct location:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
      annotations:
        k8s.aliyun.com/eci-use-specs: "2-4Gi,4-8Gi,ecs.c6.xlarge"  # Add ECI annotations here
    spec:
      containers:
      - name: nginx
        image: nginx

To inspect annotations on a running pod, run kubectl describe pod <pod-name>.

Annotations added at pod creation

Instance

AnnotationExampleDescription
k8s.aliyun.com/eci-vswitchvsw-bp1xpiowfm5vo8o3c****vSwitch IDs for the pod. Specify multiple IDs to enable multi-zone scheduling — ECI creates the pod in a zone where sufficient resources exist.
k8s.aliyun.com/eci-schedule-strategyVSwitchOrderedScheduling policy when multiple vSwitches are specified. VSwitchOrdered: tries vSwitches in the order listed. VSwitchRandom: picks a vSwitch at random.
k8s.aliyun.com/eci-use-specs2-4Gi,4-8Gi,ecs.c6.xlargeOne or more pod specifications. Each entry is either a vCPU-memory combination (e.g., 2-4Gi) or an ECS instance type (e.g., ecs.c6.xlarge).
k8s.aliyun.com/eci-gpu-driver-versiontesla=525.85.12GPU driver version for GPU-accelerated instances that support multiple driver and CUDA versions.
k8s.aliyun.com/eci-instance-family"ecs.c6,ecs.g6"ECS instance families to include or exclude when creating a pod by vCPU and memory specification.
k8s.aliyun.com/eci-instance-generation"6,5"ECS instance family generations to include or exclude when creating a pod by vCPU and memory specification.
k8s.aliyun.com/eci-compute-categoryeconomyCompute category to apply when creating a pod by vCPU and memory specification. Valid values: economy, general. Specify multiple values in priority order; ECI selects the first category with available resources.
k8s.aliyun.com/eci-spot-strategySpotAsPriceGoBid policy for preemptible instances. SpotWithPriceLimit: creates a preemptible instance with a user-defined maximum hourly price (also set k8s.aliyun.com/eci-spot-price-limit). SpotAsPriceGo: uses the market price at creation time as the bid price.
k8s.aliyun.com/eci-spot-price-limit"0.5"Maximum hourly price for a preemptible instance, accurate to three decimal places. Required when eci-spot-strategy is SpotWithPriceLimit.
k8s.aliyun.com/eci-spot-duration"0"Protection period for a preemptible instance. Unit: hours. Default: 1. Set to 0 for no protection period.
k8s.aliyun.com/eci-spot-fallback"true"Whether to automatically create a pay-as-you-go instance when preemptible inventory is insufficient. Default: false.
k8s.aliyun.com/eci-privatepool-matchcriteria"Open"Private pool matching mode. Open: matches open private pools automatically. Target: matches a specific private pool — also set k8s.aliyun.com/eci-privatepool-id.
k8s.aliyun.com/eci-privatepool-ideap-2ze1g68k2melxkkl****ID of the elasticity assurance (private pool). Required when eci-privatepool-matchcriteria is Target. Find the ID on the Resource Reservations or Private Pools tab in the ECS console.
k8s.aliyun.com/eci-fail-strategyfail-backFault handling policy. fail-back and fail-over both retry pod creation automatically. fail-fast immediately reports an error without retrying.
k8s.aliyun.com/eci-max-pending-minute"30"Maximum time the pod can remain in a pending state before ECI terminates it. Integer between 10 and 1440. Unit: minutes. Default: 240.
k8s.aliyun.com/eci-custom-hosts"[{\"host\":\"example.com\",\"ip\":\"100.100.XX.XX\"},{\"host\":\"aliyundoc.com\",\"ip\":\"100.100.XX.XX\"}]"Custom entries to add to /etc/hosts.
k8s.aliyun.com/eci-custom-tags"env:test,name:alice"Tags to bind to the pod. Maximum 3 tags. Format: key:value. Separate multiple tags with commas.
k8s.aliyun.com/eci-ram-role-nameAliyunECIContainerGroupRoleRAM role that the pod assumes to access other Alibaba Cloud services.

For details, see Configure multiple zones, Specify pod specifications, Create preemptible instances, and Use elasticity assurance private pools.

Images

AnnotationExampleDescription
k8s.aliyun.com/eci-auto-imc"true"Whether to automatically match an image cache for the pod.
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-idimc-2zebxkiifuyzzlhl****ID of the image cache to use.
k8s.aliyun.com/acr-instance-idscri-j36zhodptmyq****IDs of Container Registry Enterprise Edition instances to pull images from without a Kubernetes Secret. For cross-region pulls, prefix the region ID: "cn-beijing:cri-j36zhodptmyq****".
k8s.aliyun.com/acr-service-arnsacs:ram::1609982529******:role/role-assumeAlibaba Cloud Resource Names (ARNs) of the 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-arnsacs:ram::1298452580******:role/role-acrARNs of the RAM roles in the Alibaba Cloud account that owns the Container Registry instance. Required for cross-account image pulls.
k8s.aliyun.com/plain-http-registryharbor*.pre.com,192.168.XX.XX:5000,reg*.test.com:80Address of a self-managed image repository that uses plain HTTP. ECI pulls over HTTP instead of HTTPS, preventing protocol-mismatch failures.
k8s.aliyun.com/insecure-registryharbor*.pre.com,192.168.XX.XX:5000,reg*.test.com:80Address of a self-managed image repository that uses a self-signed certificate. ECI skips certificate verification, preventing auth failures.

For details, see Use image caches and Pull images without a Secret.

Data caches

AnnotationExampleDescription
k8s.aliyun.com/eci-data-cache-bucketdefaultBucket that stores the DataCache. Required when creating a pod from a DataCache.
k8s.aliyun.com/eci-data-cache-plPL1Performance level of the disk created from the DataCache. Default: PL1 ESSD (enhanced SSD).
k8s.aliyun.com/eci-data-cache-provisionedIops"40000"Provisioned read/write IOPS for an ESSD AutoPL disk. Valid range: 0 to min{50,000, 1,000 × capacity − baseline IOPS}, where baseline IOPS = min{1,800 + 50 × capacity, 50,000}. Adding this annotation causes ECI to create an ESSD AutoPL disk.
k8s.aliyun.com/eci-data-cache-burstingEnabled"true"Whether to enable performance bursting for the ESSD AutoPL disk. Adding this annotation causes ECI to create an ESSD AutoPL disk.

For details, see Use DataCaches and ESSD AutoPL disks.

Network

AnnotationExampleDescription
k8s.aliyun.com/eci-security-groupsg-bp1dktddjsg5nktv****Security group IDs to assign to the pod. Maximum 5 groups. All groups must belong to the same virtual private cloud (VPC) and be of the same type.
k8s.aliyun.com/eci-eip-instanceideip-bp1q5n8cq4p7f6dzu****ID of an existing Elastic IP Address (EIP) to associate with the instance.
k8s.aliyun.com/eci-with-eip"true"Whether to automatically create an EIP and associate it with the instance at creation time.
k8s.aliyun.com/eip-bandwidth"5"Maximum bandwidth of the EIP. Unit: Mbit/s. Default: 5.
k8s.aliyun.com/eip-common-bandwidth-package-idcbwp-2zeukbj916scmj51m****ID of an existing EIP bandwidth plan to associate with the instance.
k8s.aliyun.com/eip-ispBGPLine type for the EIP. Applies to pay-as-you-go EIPs only. BGP: BGP (Multi-ISP) line. BGP_PRO: BGP (Multi-ISP) Pro line.
k8s.aliyun.com/eip-internet-charge-typePayByBandwidthMetering method for the EIP. PayByBandwidth: pay-by-bandwidth. PayByTraffic: pay-by-traffic.
k8s.aliyun.com/eip-public-ip-address-pool-idpippool-bp187arfugi543y1s****ID of the IP address pool from which the EIP is allocated.
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-bandwidth100MPeak public bandwidth of the IPv6 address.
k8s.aliyun.com/eci-private-ip-address"172.16.0.1"Private IPv4 address to assign to the pod. The address must be idle.
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 to retain a fixed IP address after the pod is deleted and the address becomes idle. Unit: hours. Default: 48.
kubernetes.io/ingress-bandwidth40MMaximum inbound bandwidth for the pod.
kubernetes.io/egress-bandwidth20MMaximum outbound bandwidth 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\"}"Custom Domain Name System (DNS) server configuration. Use in hybrid cloud scenarios to resolve internal domain names.

For details, see Assign security groups, Associate an EIP, Assign an IPv6 address, Use a fixed IP address, and Configure custom DNS.

Storage

AnnotationExampleDescription
k8s.aliyun.com/eci-extra-ephemeral-storage50GiSize of the temporary storage space for the pod.
k8s.aliyun.com/eci-ephemeral-storage-options"{\"encrypted\":\"true\"}"Options for the temporary storage space. Set encrypted to true to enable encryption.

For details, see Expand temporary storage and Encrypt temporary storage.

Container configuration

AnnotationExampleDescription
k8s.aliyun.com/eci-ntp-server100.100.*.*IP address of the Network Time Protocol (NTP) server to use in the pod.

For details, see Configure the NTP service.

Logs

AnnotationExampleDescription
k8s.aliyun.com/eci-sls-enable"false"Whether to collect logs for the pod when using Simple Log Service (SLS) custom resource definitions (CRDs). Set to false to disable log collection for specific pods and prevent unnecessary Logtail instances from being created.

For details, see Collect logs with SLS CRDs.

O&M

AnnotationExampleDescription
k8s.aliyun.com/eci-core-pattern/pod/data/dump/coreDirectory where core dump files are stored.

For details, see View core dump files.

Annotations added by the system

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

AnnotationExampleDescription
k8s.aliyun.com/eci-request-id45942504-4688-51BA-BBAB-4B692C4F39C0Request ID for the pod creation call.
k8s.aliyun.com/eci-instance-ideci-2ze1y0la40qgva09****Pod ID.
k8s.aliyun.com/eci-instance-spec2.0-4.0GiActual specifications of the pod. If the value is a vCPU-memory combination (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-categoryeconomyCompute category of the instance type selected for the pod: economy or general.
k8s.aliyun.com/allocated-eipInstanceIdeip-bp1q5n8cq4p7f6dzu****ID of the EIP associated with the instance.
k8s.aliyun.com/allocated-eipAddress47.99..Public IP address of the EIP.
k8s.aliyun.com/allocated-ipv6Address2001:d**:1:1:1:1:1:1IPv6 address assigned to the pod.
k8s.aliyun.com/eci-created-by-templatetrueWhether the pod was created from a template.
k8s.aliyun.com/eni-instance-ideni-2ze6d7oo5ukqj26o****ID of the elastic network interface (ENI) bound to the pod.
k8s.aliyun.com/eci-vpcvpc-2zeghwzptn5zii0w7****ID of the virtual private cloud (VPC) the pod belongs to.
k8s.aliyun.com/eci-matched-image-cacheimc-2zedy3v37800iimu****ID of the image cache matched for the pod.
k8s.aliyun.com/eci-schedule-resultfinished(Retired) Scheduling result. Use the ContainerInstanceCreated condition instead.