ECI Pod Annotation - User Guide for Serverless Kubernetes Clusters| Alibaba Cloud Documentation Center

When you create elastic container instance-based pods in a Kubernetes cluster, you can add annotations to the pods to use the features of Elastic Container Instance. Make sure that the annotations that you want to add comply with the Kubernetes syntax. This topic describes the annotations that are supported by elastic container instance-based pods. This topic also provides examples on how to configure the annotations.

The following table describes the annotations that are supported by elastic container instance-based pods.

Note

The annotations described in the following table are applicable only to the pods that are scheduled to virtual nodes. These pods run on elastic container instances. The annotations cannot be added to the pods that are scheduled to regular nodes.
Add annotations to the metadata field of the pods. For example, when you configure a Deployment, add annotations in the spec.template.metadata field.

Annotation	Example	Description	Reference
k8s.aliyun.com/eci-security-group	sg-bp1dktddjsg5nktv****	The ID of the security group.	Configure a security group
k8s.aliyun.com/eci-vswitch	vsw-bp1xpiowfm5vo8o3c****	The IDs of the vSwitches. You can specify multiple vSwitches across zones.	Specify multiple zones to create an elastic container instance-based pod
k8s.aliyun.com/eci-schedule-strategy	VSwitchOrdered	The multi-zone scheduling policy. Valid values: VSwitchOrdered: Resources in the specified zones are scheduled based on the order in which the vSwitches are specified. VSwitchRandom: Resources in the specified zones are randomly scheduled.
k8s.aliyun.com/eci-ram-role-name	AliyunECIContainerGroupRole	The Resource Access Management (RAM) role that elastic container instances assume to access other Alibaba Cloud services.	None. The following section describes the details.
k8s.aliyun.com/eci-use-specs	2-4Gi,4-8Gi,ecs.c6.xlarge	The types of elastic container instances. You can specify multiple elastic container instance specifications, such as the number of vCPUs and the memory size. You can also specify an ECS instance type.	Specify multiple instance specifications to create an elastic container instance
k8s.aliyun.com/eci-spot-strategy	SpotAsPriceGo	The bidding policy of the preemptible instance. Valid values: SpotAsPriceGo: The instance is billed at the market price at the time of purchase. SpotWithPriceLimit: You must specify the highest price that you want to pay for the preemptible instance.	Create a preemptible instance
k8s.aliyun.com/eci-spot-price-limit	0.5	The highest price of the preemptible instance. This parameter is valid only when k8s.aliyun.com/eci-spot-strategy is set to SpotWithPriceLimit.	Create a preemptible instance
k8s.aliyun.com/eci-cpu-option-core	2	The number of physical CPU cores.	Customize CPU options
k8s.aliyun.com/eci-cpu-option-ht	1	The number of threads per core.	Customize CPU options
k8s.aliyun.com/eci-reschedule-enable	"true"	Specifies whether to enable rescheduling for elastic container instances.	None. The following section describes the details.
k8s.aliyun.com/pod-fail-on-create-err	"true"	Specifies whether to put the elastic container instances that cannot be created into the Failed state.	None. The following section describes the details.
k8s.aliyun.com/eci-image-snapshot-id	imc-2zebxkiifuyzzlhl****	The ID of the image cache. Note To use an image cache to create an elastic container instance, you can specify the image cache that you want to use or enable automatic matching for image caches. We recommend that you enable automatic matching for image caches.	Use the ImageCache CRD to accelerate pod creation
k8s.aliyun.com/eci-image-cache	"true"	Specifies whether to enable automatic matching for image caches. Note To use an image cache to create an elastic container instance, you can specify the image cache that you want to use or enable automatic matching for image caches. We recommend that you enable automatic matching for image caches.	Use the ImageCache CRD to accelerate pod creation
k8s.aliyun.com/acr-instance-id	cri-j36zhodptmyq****	The ID of the Container Registry Enterprise Edition instance. You can specify a Container Registry Enterprise Edition instance that resides in a region different from the region of the elastic container instance. To do this, you must add the region name of the Container Registry Enterprise Edition instance before the ID of the Container Registry Enterprise Edition instance. Example: `"cn-beijng:cri-j36zhodptmyq****"`.	Pull images from a Container Registry Enterprise Edition instance without a password
k8s.aliyun.com/eci-eip-instanceid	eip-bp1q5n8cq4p7f6dzu****	The ID of the elastic IP address (EIP).	Enable Internet access
k8s.aliyun.com/eci-with-eip	"true"	Specifies whether to automatically create an EIP and associate the EIP with the elastic container instance.
k8s.aliyun.com/eip-bandwidth	5	The bandwidth of the EIP.
k8s.aliyun.com/eip-common-bandwidth-package-id	cbwp-2zeukbj916scmj51m****	The ID of the EIP bandwidth plan.
k8s.aliyun.com/eip-isp	BGP	The line type of the EIP. This annotation is applicable only to pay-as-you-go EIPs. Valid values: BGP: BGP (Multi-ISP) line BGP_PRO: BGP (Multi-ISP) Pro line
k8s.aliyun.com/eip-internet-charge-type	PayByBandwidth	The metering method of the EIP. Valid values: PayByBandwidth: Pay-by-bandwidth PayByTraffic: Pay-by-traffic
k8s.aliyun.com/eci-enable-ipv6	"true"	Specifies whether to assign IPv6 addresses.	Assign an IPv6 address to an elastic container instance
kubernetes.io/ingress-bandwidth	40M	The inbound bandwidth.	Set bandwidth throttling for an elastic container instance
kubernetes.io/egress-bandwidth	20M	The outbound bandwidth.	Set bandwidth throttling for an elastic container instance
k8s.aliyun.com/eci-extra-ephemeral-storage	50Gi	The temporary storage capacity.	Customize the temporary storage capacity
k8s.aliyun.com/eci-core-pattern	/pod/data/dump/core	The directory in which core dump files are stored.	View core dump files
k8s.aliyun.com/eci-ntp-server	100.100..	The IP address of the Network Time Protocol (NTP) server.	Configure the NTP service for pods
k8s.aliyun.com/plain-http-registry	"harbor*.pre.com,192.168.XX.XX:5000,reg*.test.com:80"	The IP address of the self-managed image repository. When you create an elastic container instance by using an image in a self-managed image repository over HTTP, you must add this annotation to the instance. This allows Elastic Container Instance to pull the image over HTTP. This prevents image pull failures caused by different protocols.	Use self-managed image repositories
k8s.aliyun.com/insecure-registry	"harbor*.pre.com,192.168.XX.XX:5000,reg*.test.com:80"	The endpoint of the self-managed image repository. When you create an elastic container instance by using an image in a self-managed image repository that uses a self-signed certificate, you must add this annotation to the instance to skip the certificate authentication. This prevents image pull failures caused by certificate authentication failures.	Use self-managed image repositories

Configure a RAM role

You can add an annotation to configure a RAM role for a pod and grant the pod the permissions to access Alibaba Cloud services.

Notice

Before you add the annotation, you must create a RAM role and grant permissions to the RAM role. When you create the RAM role, make sure that the trusted service of the RAM role is ECS.
If you use a RAM user, make sure that the RAM user has the ram:passRole permission.

Example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: set-ram-role
  labels:
    app: vk
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
        annotations: 
            k8s.aliyun.com/eci-ram-role-name : "${your_ram_role_name}"  
        labels:
            app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
      nodeName: virtual-kubelet

Configure rescheduling for elastic container instances

Pods may fail to be scheduled to virtual nodes. You can add an annotation to enable rescheduling for pods. This ensures that the system keeps scheduling pods instead of returning failures even if the asynchronous scheduling fails.

Example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: set-eci
  labels:
    app: vk
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
        annotations: 
            k8s.aliyun.com/eci-reschedule-enable: "true"    # Enable rescheduling for elastic container instances. 
        labels:
            app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
      nodeName: virtual-kubelet

Put the pods that fail to be created into the Failed state

By default, if an error occurs when a pod is being created, the system attempts to create the pod for a specified number of times. If the pod fails to be created after the specified number of times, the pod changes to the Pending state. You may want pods to enter the Failed state if the pods fail to be created for specific Jobs. In this case, you can add an annotation to put a pod that fails to be created into the Failed state.

Example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: set-pod-fail-on-create-err
  labels:
    app: vk
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
        annotations: 
            k8s.aliyun.com/pod-fail-on-create-err: "true"  # Set the state to Failed if the pod fails to be created. 
        labels:
            app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
      nodeName: virtual-kubelet