How to specify an ECS instance family to create an ECI instance - Elastic Container Instance

When you create an ECI pod by specifying vCPU and memory, you can add the k8s.aliyun.com/eci-instance-family annotation if you require a specific underlying instance, for example, to use only the ecs.g6 instance family. This topic describes how to specify or exclude ECS instance families when you create an ECI pod.

How it works

When you create an ECI pod by specifying vCPU and memory, the system may use various ECS instance types. It automatically selects an instance type that meets your vCPU and memory requirements and has available inventory. You can add the k8s.aliyun.com/eci-instance-family annotation to narrow the selection by specifying or excluding ECS instance families.

If you specify one or more ECS instance families, the system selects instance types only from those families. If no matching instance types in your specified families are available, the pod creation fails.
If you exclude one or more ECS instance families, the system selects an instance type from any other supported ECS instance family.

Note

For more granular control, you can combine this annotation with k8s.aliyun.com/eci-instance-generation to specify or exclude ECS instance generations.

The following table lists the ECS instance families that you can specify or exclude.

Architecture	Generation of ECS instance families	ECS instance family
Arm	8	g8y, c8y, and r8y
x86	8	g8i, c8i, r8i, hfg8i, hfc8i, and hfr8i
	7	g7, c7, r7, hfg7, hfc7, hfr7, and g7ne
	6	g6e, g6, c6e, c6, r6e, r6, hfc6, hfg6
	5	u1, g5, g5ne, c5, r5, ic5, hfc5, and hfg5
	4	sn2ne, sn1ne, se1ne, and se1

For more information about ECS instance types, see the following topics:

Usage notes

ECI pods created by specifying or excluding an ECS instance family are billed based on the provisioned ECS instance type, not the vCPU and memory that you requested.

Important
After an ECI pod is created, you can run the kubectl describe pod command to view its details. Check the k8s.aliyun.com/eci-instance-spec field to confirm the actual ECS instance type used for billing.
When specifying or excluding ECS instance families, the system cannot automatically select certain specialized instance types, such as GPU instance types (for example, gn6i) or instance types with a local disk (for example, i2g). To use these instance types, you must specify them directly. For more information, see Specify ECS instance types to create a pod.
This feature applies only when you specify vCPU and memory requirements. If you specify an exact ECS instance type, this annotation has no effect.
You can use this feature to create preemptible instances. In this scenario, the system considers both the order of the instance families in your configuration and the market price, prioritizing the price. If you have a strict requirement for a specific instance family, we recommend that you configure only one.

Configuration

Set the value for the k8s.aliyun.com/eci-instance-family annotation to one or more ECS instance families according to the following rules:

You can specify a comma-separated list of ECS instance families that are supported by ECI.

Important
Currently, 8th-generation instance types are available only for the Arm architecture. When you create a pod, you must use a nodeSelector to schedule the pod to an Arm-based node. Therefore, you cannot mix Arm-based and x86-based instance families in the same annotation value. When targeting Arm nodes, you can only specify or exclude other Arm-based families. For a configuration example, see Example 5: Specify an Arm-based instance family.
Prefix an instance family with a hyphen (-) to exclude it.

For example, k8s.aliyun.com/eci-instance-family: "-ecs.c6, -ecs.c5" excludes the ecs.c6 and ecs.c5 instance families.
If you specify multiple instance families, the system tries them in the order provided.

For example, k8s.aliyun.com/eci-instance-family: "ecs.c6, ecs.c5" means the system first tries to select an instance type from the ecs.c6 family. If no suitable instance type with available inventory is found, it falls back to the ecs.c5 family. If the ecs.c5 family also lacks a suitable instance type, the pod creation fails.

When using the k8s.aliyun.com/eci-instance-family annotation, you must first specify the vCPU and memory. You can do this in one of the following ways:

Define requests or limits for a container. We recommend using limits.
Add the k8s.aliyun.com/eci-use-specs annotation to the pod metadata.

Example 1: Specify ECS instance families

Parameter	Result
This specifies 2 vCPUs and 4 GiB of memory using the `limits` field. The annotation `k8s.aliyun.com/eci-instance-family: "ecs.c6, ecs.g6"` prioritizes the ecs.c6 family, with the ecs.g6 family as a fallback.	The system tries to use the ecs.c6.large instance type first, falling back to ecs.g6.large. Note This configuration has the same effect as setting `k8s.aliyun.com/eci-use-specs: "ecs.c6.large,ecs.g6.large"`.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: test
  template:
    metadata:
      name: test
      labels:
        app: test
        alibabacloud.com/eci: "true" 
      annotations:
        k8s.aliyun.com/eci-instance-family: "ecs.c6,ecs.g6"    # Prioritize the ecs.c6 family, and then fall back to the ecs.g6 family.
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80
        resources:
          limits:
            cpu: "2"       # vCPU limit        
            memory: "4Gi"  # Memory limit

Example 2: Exclude ECS instance families

Parameter	Result
The annotation `k8s.aliyun.com/eci-use-specs: "2-4Gi"` specifies the vCPU and memory resources (2 vCPUs, 4 GiB of memory). The annotation `k8s.aliyun.com/eci-instance-family: "-ecs.hfg6,-ecs.hfg5"` excludes the ecs.hfg6 and ecs.hfg5 instance families.	The system selects a matching instance type from any supported ECS instance family except ecs.hfg6 and ecs.hfg5.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true" 
      annotations:
        k8s.aliyun.com/eci-use-specs: "2-4Gi"                    # Specify a vCPU and memory range.
        k8s.aliyun.com/eci-instance-family: "-ecs.hfg6,-ecs.hfg5"    # Exclude the ecs.hfg6 and ecs.hfg5 instance families.
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80

Example 3: Specify specific generations of ECS instance families and exclude specific ECS instance families

Parameter

Effect

The k8s.aliyun.com/eci-use-specs: "2-4Gi" annotation is configured to define vCPU and memory resources (2 vCPUs, 4 GiB of memory).
The k8s.aliyun.com/eci-instance-generation: "6,5" annotation is configured. The annotation specifies that the system uses the sixth-generation ECS instance families and then the fifth-generation ECS instance families.
The k8s.aliyun.com/eci-instance-family: "-ecs.hfg5" annotation is configured to exclude the ecs.hfg5 instance families.

The system preferentially selects instance types from the sixth-generation ECS instance families that meet the vCPU and memory specification requirements.
If the resources of the sixth-generation ECS instance families are insufficient, the system selects instance types from the fifth-generation ECS instance families (except ecs.hfg5) that are supported by Elastic Container Instance.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true" 
      annotations:
        k8s.aliyun.com/eci-use-specs: "2-4Gi"                   # Specifies the vCPU and memory specifications.
        k8s.aliyun.com/eci-instance-generation: "6,5"           # Specifies that the sixth-generation and fifth-generation ECS instance families are used in sequence.
        k8s.aliyun.com/eci-instance-family: "-ecs.hfg5"           # Excludes the ecs.hfg5 instance family.
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80

Example 4: Exclude specific generations of ECS instance families and specific ECS instance families

Parameter

Effect

The k8s.aliyun.com/eci-use-specs: "2-4Gi" annotation is configured to define vCPU and memory resources (2 vCPUs, 4 GiB of memory).
The k8s.aliyun.com/eci-instance-generation: "-5,-4" annotation is configured to exclude the fifth-generation and fourth-generation ECS instance families.
The k8s.aliyun.com/eci-instance-family: "-ecs.hfg6" annotation is configured to exclude the ecs.hfg6 instance family.

The system selects instance types from seventh-generation and sixth-generation ECS instance families (except ecs.hfg6) that meet the vCPU and memory specification requirements.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true" 
      annotations:
        k8s.aliyun.com/eci-use-specs: "2-4Gi"                    # Specifies the vCPU and memory specifications in fuzzy search mode.
        k8s.aliyun.com/eci-instance-generation: "-5,-4"          # Excludes the fifth-generation and fourth-generation ECS instance families.
        k8s.aliyun.com/eci-instance-family: "-ecs.hfg6"            # Excludes the ecs.hfg6 instance family.
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80

Example 5: Specify an Arm-based instance family

Parameter

Result

The annotation k8s.aliyun.com/eci-use-specs: "2-4Gi,4-8Gi" specifies the vCPU and memory resources. 2 vCPUs and 4 GiB of memory are used first, followed by 4 vCPUs and 8 GiB of memory.
The annotation k8s.aliyun.com/eci-instance-family: "ecs.c8y" specifies that an instance type from the ecs.c8y family is used.
The labels alibabacloud.com/eci: "true" and kubernetes.io/arch: arm64 schedule the pod to an Arm-based virtual node.

The ecs.c8y.large instance type is used first, followed by the ecs.c8y.xlarge instance type.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true" 
      annotations:
        k8s.aliyun.com/eci-use-specs: "2-4Gi,4-8Gi"              # Specify multiple vCPU and memory ranges.
        k8s.aliyun.com/eci-instance-family: "ecs.c8y"            # Specify the ecs.c8y instance family.
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80
      nodeSelector:
        kubernetes.io/arch: arm64  # Schedule the pod to an Arm node.

Example 6: Invalid configuration

If you use this feature in an unsupported scenario, the system ignores the annotation and generates an IgnoreInstanceTypeFeatures event.

Event name	Type	Message	Description
IgnoreInstanceTypeFeatures	Warning	[eci.containergroup]The instance type features will be ignored as the provided specifications, [%s],correspond exclusively to ECS instance types.	Because `k8s.aliyun.com/eci-use-specs` specifies an exact ECS instance type, the system ignores the annotation for specifying the ECS instance family.

In the following example, the system ignores the annotation that specifies the ecs.c6 instance family. The system creates the ECI pod by using only the ecs.c5.large instance type.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true" 
      annotations:
        k8s.aliyun.com/eci-use-specs: "ecs.c5.large"   # Specify an exact ECS instance type.
        k8s.aliyun.com/eci-instance-family: "ecs.c6"   # This annotation is ignored.
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80

You can see the IgnoreInstanceTypeFeatures event in the pod events.