All Products
Search
Document Center

ECI Pod Annotation

Last Updated: Mar 29, 2022

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.

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.

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.

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.

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.

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