All Products
Search

This Product

    Elastic Container Instance:ECI pod annotations

    Document Center

    Elastic Container Instance:ECI pod annotations

    Last Updated:Jun 18, 2026

    When creating an ECI pod (an ECI instance) in a Kubernetes cluster, you can add annotations to leverage ECI features without changing Kubernetes semantics. This topic covers both the annotations you can add and those automatically added after pod scheduling.

    ECI pod annotations

    ECI pods support the following annotations:

    Important

    • These annotations apply only to Pods scheduled on virtual nodes (ECI instances) and do not affect Pods on regular nodes.

    • Add annotations to a Pod's metadata. For example, when creating a Deployment, add the annotations under spec>template>metadata.

    • Elastic Container Instance-related annotations are only applied when a pod is created. Adding or modifying these annotations on an existing pod will have no effect.

    Examples

    Feature

    Annotation

    Example value

    Description

    Create pods across multiple availability zones

    k8s.aliyun.com/eci-vswitch

    vsw-bp1xpiowfm5vo8o3c****

    Specifies the ID of a vSwitch. You can specify multiple vSwitch IDs to deploy pods across multiple availability zones.

    k8s.aliyun.com/eci-schedule-strategy

    VSwitchOrdered

    The scheduling policy for multiple availability zones. Valid values:

    • VSwitchOrdered: Attempts to create the pod by using the specified vSwitches in their listed order.

    • VSwitchRandom: Creates the pod in one of the specified vSwitches, selected by an optimal Alibaba Cloud scheduling policy.

    k8s.aliyun.com/eci-use-specs

    2-4Gi,4-8Gi,ecs.c6.xlarge

    Specifies one or more instance specifications for the ECI pod, which can be vCPU and memory combinations or ECS instance types.

    k8s.aliyun.com/eci-gpu-driver-version

    tesla=525.85.12

    Specifies the GPU driver version.

    When you create a GPU-accelerated instance by specifying a GPU instance type that supports multiple driver and CUDA versions, use this annotation to specify the driver and CUDA version.

    Create a pod by specifying or excluding ECS instance families

    k8s.aliyun.com/eci-instance-family

    "ecs.c6,ecs.g6"

    Specifies which ECS instance families to use or avoid when creating an ECI instance based on vCPU and memory requirements.

    Create a pod by specifying or excluding ECS instance generations

    k8s.aliyun.com/eci-instance-generation

    "6,5"

    Specifies which ECS instance generations to use or avoid when creating an ECI instance based on vCPU and memory requirements.

    Create a pod by specifying a compute category

    k8s.aliyun.com/eci-compute-category

    economy

    Specifies a compute category when you create an ECI instance by specifying vCPU and memory.

    • Valid values: economy and general (general-purpose).

    • You can specify multiple compute categories. The system attempts to create the instance by using the categories in the specified order.

    Create a preemptible instance

    k8s.aliyun.com/eci-spot-strategy

    SpotAsPriceGo

    The bidding policy for the preemptible instance. Valid values:

    • SpotWithPriceLimit: Sets a custom maximum price for the preemptible instance. This policy requires you to also set the k8s.aliyun.com/eci-spot-price-limit annotation.

    • SpotAsPriceGo: The system automatically bids at the current market price.

    k8s.aliyun.com/eci-spot-price-limit

    "0.5"

    The maximum hourly price for the preemptible instance. The value supports up to three decimal places.

    This annotation is valid only when k8s.aliyun.com/eci-spot-strategy is set to SpotWithPriceLimit.

    k8s.aliyun.com/eci-spot-duration

    "0"

    The protection period for the preemptible instance. The default value is 1 hour. Set the value to 0 for no protection period.

    k8s.aliyun.com/eci-spot-fallback

    "true"

    Specifies whether to automatically create a pay-as-you-go instance when preemptible instances are unavailable. The default value is false.

    Create a pod by using a private pool with Elasticity Assurance

    k8s.aliyun.com/eci-privatepool-matchcriteria

    "Open"

    Set the private pool matching mode. Valid values:

    • Open: The system automatically matches an available open private pool.

    • Target: You must also specify a private pool ID. Use this mode if your private pool is dedicated.

    k8s.aliyun.com/eci-privatepool-id

    eap-2ze1g68k2melxkkl****

    Specify the private pool ID (which is the elasticity assurance ID). Find it on the Resource reservation page in the ECS console under the Resource Reservations or Private Pools tab.

    • If k8s.aliyun.com/eci-privatepool-matchcriteria is set to Target, you must include this annotation.

    • If k8s.aliyun.com/eci-privatepool-matchcriteria is set to Open, this annotation has no effect.

    Set the fault handling policy for an ECI pod

    k8s.aliyun.com/eci-fail-strategy

    fail-back

    The fault handling policy for the ECI pod. Valid values:

    • fail-back: If pod creation fails, the system automatically retries.

    • fail-over: Same as fail-back.

    • fail-fast: If pod creation fails, the system immediately reports an error.

    Customize the maximum pending duration for an ECI pod

    k8s.aliyun.com/eci-max-pending-minute

    "30"

    The maximum time in minutes that the ECI instance for a pod can remain in the Pending state. If the timeout is exceeded, the system terminates the instance.

    The value must be an integer from 10 to 1440. Default: 240 (4 hours).

    Customize hosts for an ECI pod

    k8s.aliyun.com/eci-custom-hosts

    "[{\"host\":\"example.com\",\"ip\":\"100.100.XX.XX\"},{\"host\":\"aliyundoc.com\",\"ip\":\"100.100.XX.XX\"}]"

    Adds custom host mappings to the ECI pod's /etc/hosts file.

    Bind custom tags to an ECI pod

    k8s.aliyun.com/eci-custom-tags

    "env:test,name:alice"

    Specifies up to three tags to bind to the pod. Tags are key-value pairs separated by a colon (:) and multiple tags are separated by a comma (,).

    Bind a RAM role to an ECI pod

    k8s.aliyun.com/eci-ram-role-name

    AliyunECIContainerGroupRole

    Binds a RAM role to the ECI pod, granting it permissions to access other Alibaba Cloud services.

    Image

    Feature

    Parameter

    Value

    Description

    Accelerate pod creation with an image cache

    k8s.aliyun.com/eci-auto-imc

    "true"

    Set to "true" to automatically match an image cache.

    k8s.aliyun.com/imc-perfect-match

    "true"

    If automatic matching is enabled, specifies whether all container images in the pod must exactly match images in the cache.

    k8s.aliyun.com/imc-match-count-request

    "2"

    If automatic matching is enabled, specifies the number of container images in the pod that must exactly match images in the cache.

    k8s.aliyun.com/eci-imc-id

    imc-2zebxkiifuyzzlhl****

    Specifies the ID of the image cache.

    Pull ACR images without a Secret

    k8s.aliyun.com/acr-instance-ids

    cri-j36zhodptmyq****

    Specifies the Container Registry Enterprise Edition instance to pull images from without a Secret.

    To pull an image from a different region, prefix the instance ID with the region ID. Example: "cn-beijing:cri-j36zhodptmyq****".

    k8s.aliyun.com/acr-service-arns

    acs:ram::1609982529******:role/role-assume

    Specifies the ARN of the RAM role in the account that owns the ECI resource.

    This annotation is required if you use a RAM role to create the resource.

    k8s.aliyun.com/acr-user-arns

    acs:ram::1298452580******:role/role-acr

    Specifies the ARN of the RAM role that belongs to the account of the Container Registry Enterprise Edition instance.

    This annotation is required to pull images from a different account.

    Pull images from a self-managed image repository

    k8s.aliyun.com/plain-http-registry

    harbor***.pre.com,192.168.XX.XX:5000,reg***.test.com:80

    Allows ECI to pull images over HTTP from the specified self-managed image repositories. This prevents pull failures caused by a protocol mismatch.

    k8s.aliyun.com/insecure-registry

    harbor***.pre.com,192.168.XX.XX:5000,reg***.test.com:80

    Skips certificate verification when pulling images from specified self-managed image repositories. This prevents pull failures caused by self-signed certificates.

    DataCache

    Feature

    Parameter

    Value

    Description

    Create a pod from a DataCache

    k8s.aliyun.com/eci-data-cache-bucket

    default

    Specifies the bucket that is used to store the DataCache. You must configure this annotation when you use DataCaches to create pods.

    k8s.aliyun.com/eci-data-cache-pl

    PL1

    Specifies the performance level of the disk that is created based on the DataCache. By default, a PL1 enhanced SSD (ESSD) is used.

    k8s.aliyun.com/eci-data-cache-provisionedIops

    "40000"

    Specifies the read/write IOPS that is provisioned for the ESSD AutoPL disk. Valid values: 0 to min{50000, 1000 × Storage capacity - Baseline IOPS}. Baseline IOPS = min{1,800 + 50 × Storage capacity, 50,000}. For more information, see ESSD AutoPL disks.

    If you add this annotation, the disk that is created based on the DataCache is an ESSD AutoPL disk.

    k8s.aliyun.com/eci-data-cache-burstingEnabled

    "true"

    Specifies whether to enable the performance burst feature for the ESSD AutoPL disk. For more information, see ESSD AutoPL disks.

    If you add this annotation, the disk that is created based on the DataCache is an ESSD AutoPL disk.

    Network

    Feature

    Parameter

    Example value

    Description

    Configure security groups for an ECI pod

    k8s.aliyun.com/eci-security-group

    sg-bp1dktddjsg5nktv****

    Specifies the security group ID. The following requirements apply:

    • You can specify up to five security groups.

    • The specified security groups must belong to the same VPC.

    • The specified security groups must be of the same type.

    Associate an EIP with an ECI instance

    k8s.aliyun.com/eci-eip-instanceid

    eip-bp1q5n8cq4p7f6dzu****

    The ID of the EIP to associate.

    k8s.aliyun.com/eci-with-eip

    "true"

    Automatically creates and associates an EIP if set to "true".

    k8s.aliyun.com/eip-bandwidth

    "5"

    The EIP bandwidth in Mbps. The default is 5 Mbps.

    k8s.aliyun.com/eip-common-bandwidth-package-id

    cbwp-2zeukbj916scmj51m****

    The ID of an existing Common Bandwidth Package. For more information, see Shared Bandwidth.

    k8s.aliyun.com/eip-isp

    BGP

    The EIP line type. This setting applies only to pay-as-you-go EIPs. Valid values:

    • BGP: BGP (Multi-ISP)

    • BGP_PRO: BGP (Multi-ISP) Pro

    For more information, see EIP line types.

    k8s.aliyun.com/eip-internet-charge-type

    PayByBandwidth

    The EIP billing method. Valid values:

    • PayByBandwidth: pay-by-bandwidth

    • PayByTraffic: pay-by-traffic

    For more information, see EIP billing methods.

    k8s.aliyun.com/eip-public-ip-address-pool-id

    pippool-bp187arfugi543y1s****

    The ID of the IP address pool from which to allocate the EIP. For more information, see IP address pools.

    Assign an IPv6 address to an ECI pod

    k8s.aliyun.com/eci-enable-ipv6

    "true"

    Assigns an IPv6 address to the pod if set to "true".

    k8s.aliyun.com/eci-ipv6-bandwidth-enable

    "true"

    Enables public internet access for the ECI instance's IPv6 address if set to "true".

    k8s.aliyun.com/eci-ipv6-bandwidth

    100M

    The peak public bandwidth for the IPv6 address, in Mbps.

    Specify a private IP address for an ECI pod

    k8s.aliyun.com/eci-private-ip-address

    "172.16.0.1"

    Specifies the private IP address for the pod. Only IPv4 addresses are supported. Make sure that the IP address is not in use.

    Configure a fixed IP address for an ECI pod

    k8s.aliyun.com/eci-fixed-ip

    "true"

    Enables a fixed IP address for the pod if set to "true".

    k8s.aliyun.com/eci-fixed-ip-retain-hour

    "24"

    The retention period in hours for the fixed IP address after the pod's release.

    If this annotation is not configured, the default retention period is 48 hours.

    Limit the ingress and egress bandwidth of an ECI pod

    kubernetes.io/ingress-bandwidth

    40M

    The maximum ingress bandwidth, in Mbps.

    kubernetes.io/egress-bandwidth

    20M

    The maximum egress bandwidth, in Mbps.

    Configure custom DNS for an ECI 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\"}

    Specifies custom DNS settings for the ECI pod. Typically used in hybrid cloud scenarios to resolve internal domain names.

    Storage

    Feature

    Parameter

    Value

    Description

    Expand temporary storage

    k8s.aliyun.com/eci-extra-ephemeral-storage

    50Gi

    The size of the temporary storage space.

    Encrypt temporary storage

    k8s.aliyun.com/eci-ephemeral-storage-options

    "{\"encrypted\":\"true\"}"

    Enables encryption for the temporary storage space.

    Container

    Feature

    Parameter

    Example value

    Description

    Configure an NTP service for a pod

    k8s.aliyun.com/eci-ntp-server

    100.100..*

    Specifies the address of the NTP server.

    Logs

    Feature

    Parameter

    Example value

    Description

    Collect logs with an SLS CRD

    k8s.aliyun.com/eci-sls-enable

    "false"

    Set the value to "false" to disable log collection.

    When collecting logs with an SLS custom resource definition (CRD), add this annotation to pods that you want to exclude from log collection. This action prevents the automatic creation of a Logtail configuration and conserves resources.

    O&M

    Feature

    Parameter

    Example value

    Description

    View core dump files

    k8s.aliyun.com/eci-core-pattern

    /pod/data/dump/core

    The directory to store core dump files.

    ECI pod annotations

    The following table lists the annotations added to an ECI Pod after it is scheduled. You can query these annotations by running the kubectl describe command.

    Parameter

    Example value

    Description

    k8s.aliyun.com/eci-request-id

    45942504-4688-51BA-BBAB-4B692C4F39C0

    The request ID.

    k8s.aliyun.com/eci-instance-id

    eci-2ze1y0la40qgva09****

    The ECI instance ID.

    k8s.aliyun.com/eci-instance-spec

    2.0-4.0Gi

    The ECI instance specification used for billing.

    • If the value is a specific vCPU and memory combination (for example, 2.0-4.0Gi), the instance is billed based on vCPU and memory.

    • If the value is an ECS instance type (for example, ecs.c6.large), the instance is billed based on the ECS instance type.

    k8s.aliyun.com/eci-instance-compute-category

    economy

    The compute category of the ECI instance specification.

    • If the value is economy, the instance is billed based on the economy instance specification.

    • If the value is general, the instance is billed based on the general purpose instance specification.

    k8s.aliyun.com/allocated-eipInstanceId

    eip-bp1q5n8cq4p7f6dzu****

    The ID of the associated EIP.

    k8s.aliyun.com/allocated-eipAddress

    47.99.**.**

    The IP address of the associated EIP.

    k8s.aliyun.com/allocated-ipv6Address

    2001:d**:1:1:1:1:1:1

    The associated IPv6 address.

    k8s.aliyun.com/eci-created-by-template

    true

    Indicates whether the ECI instance was created from a template.

    k8s.aliyun.com/eni-instance-id

    eni-2ze6d7oo5ukqj26o****

    The ID of the associated elastic network interface.

    k8s.aliyun.com/eci-vpc

    vpc-2zeghwzptn5zii0w7****

    The VPC ID.

    k8s.aliyun.com/eci-matched-image-cache

    imc-2zedy3v37800iimu****

    The ID of the matched image cache.

    k8s.aliyun.com/eci-schedule-result

    finished

    The scheduling result. This annotation is deprecated. Instead, refer to the ContainerInstanceCreated condition in podStatus.conditions. For more information, see ContainerInstanceCreated.