Add annotations to ACS pods to configure networking, image pull behavior, scheduling, and OS settings. This reference lists all supported annotations organized by category.
Annotations for pod configuration
Set these annotations in metadata.annotations when creating a pod or Deployment.
Pod configuration example
apiVersion: v1
kind: Pod
metadata:
name: annotation-pod
annotations:
# Specify one or more vSwitch IDs to control which zones the pod is created in
network.alibabacloud.com/vswitch-ids: "vsw-foo"
# Attach an EIP automatically when the pod starts
network.alibabacloud.com/pod-with-eip: "true"
spec:
...Deployment configuration example
apiVersion: apps/v1
kind: Deployment
metadata:
name: foo
spec:
template:
metadata:
annotations:
network.alibabacloud.com/vswitch-ids: "vsw-foo"
...Network
| Parameter | Example value | Description |
|---|---|---|
network.alibabacloud.com/vswitch-ids |
"vsw-slw1*,vsw-lkjwo*" |
The vSwitch IDs for the pod. Specify multiple IDs to create pods across zones. Important
When both vSwitches and affinity are set, ACS uses the specified vSwitches and ignores the affinity configuration. Important
If the pod uses a PersistentVolumeClaim (PVC) with |
network.alibabacloud.com/security-group-ids |
"sg-sljwo*,sg-lwirp*" |
The security group IDs for the pod. Specify multiple IDs to attach multiple security groups. |
network.alibabacloud.com/custom-dnsconfig |
{"servers":["20.1.xx.xx","30.1.xx.xx"],"searches":["xx.com","yy.com"],"options":["ndots:2","edns0"]} |
Custom DNS configuration for the pod. See Configure custom DNS using annotations. |
alibabacloud.com/enable-network-policy-agent |
"true" |
Enables NetworkPolicy for the pod. Default: false. See Use network policies in ACS clusters. |
EIP configuration
Use the following annotations to attach an elastic IP address (EIP) to a pod. See Attach an EIP to a pod using annotations.
| Parameter | Example value | Description |
|---|---|---|
network.alibabacloud.com/pod-with-eip |
"true" |
Automatically creates and attaches an EIP to the pod. Valid values: true | false. |
network.alibabacloud.com/pod-eip-instanceid |
"eip-bp14q***" |
Uses an existing EIP. Enter the EIP instance ID. See Apply for an EIP. |
network.alibabacloud.com/eip-bandwidth |
"5" |
Peak bandwidth of the EIP, in Mbit/s. |
network.alibabacloud.com/eip-internet-charge-type |
"PayByTraffic" |
Metering method for the EIP. Valid values: PayByTraffic (default) | PayByBandwidth. See EIP billing methods. |
network.alibabacloud.com/eip-instance-charge-type |
"PrePaid" |
Billing method for the EIP instance. Valid values: PrePaid (subscription) | PostPaid (pay-as-you-go). See Subscription and Pay-as-you-go. |
network.alibabacloud.com/eip-common-bandwidth-package-id |
"cbwp-slex***" |
Attaches the pod's EIP to an existing Internet Shared Bandwidth instance. |
network.alibabacloud.com/eip-isp |
"BGP" |
Line type of the EIP. Valid values: BGP (BGP Multi-ISP) | BGP_PRO (BGP Multi-ISP Pro). See Apply for an EIP. |
network.alibabacloud.com/eip-public-ip-address-pool-id |
"pippool-dlsw***" |
EIP address pool to allocate the EIP from. See IP address pools. |
network.alibabacloud.com/eip-resource-group-id |
Resource group for the EIP. See Apply for an EIP. | |
network.alibabacloud.com/eip-name |
Name of the EIP. | |
network.alibabacloud.com/eip-description |
Description of the EIP. | |
network.alibabacloud.com/eip-security-protection-types |
Security services to apply to the EIP. Separate multiple values with a comma (,). See Apply for an EIP. |
|
network.alibabacloud.com/pod-eip-release-strategy |
"Never" |
Release policy for the pod's EIP when the pod is deleted. Valid values: Follow (default — the EIP is deleted with the pod) | Never (the EIP is retained; delete it manually when no longer needed) | Go-style duration (for example, 5m30s deletes the EIP 5 minutes and 30 seconds after the pod is deleted). |
Image
| Parameter | Example value | Description |
|---|---|---|
registry.alibabacloud.com/plain-http-registry |
"harbor*.pre.com,192.168.XX.XX:5000,reg*.test.com:80" |
Registries that use plain HTTP. Configure this to prevent pull failures when an image repository uses HTTP instead of HTTPS. Separate multiple entries with a comma. See Use a self-managed image repository. |
registry.alibabacloud.com/insecure-registry |
"harbor*.pre.com,192.168.XX.XX:5000,reg*.test.com:80" |
Registries with self-signed certificates. Configure this to skip certificate validation and prevent pull failures. Separate multiple entries with a comma. |
Scheduling
| Parameter | Example value | Description |
|---|---|---|
alpha.alibabacloud.com/compute-qos-strategy |
"best-effort-to-default" |
Compute QoS retry policy for the pod. Valid value: best-effort-to-default — the pod starts with BestEffort compute quality; if resources are insufficient, it falls back to Default compute quality. Important
Do not set the |
Operating system
| Parameter | Example value | Description |
|---|---|---|
alibabacloud.com/os-kernel-config |
{"transparentHugepageEnabled": "madvise","transparentHugepageShmemEnabled": "advise"} |
Transparent Huge Pages settings for the pod's OS. Supported compute classes: GPU and GPU-HPN only. Sub-parameters: transparentHugepageEnabled — maps to /sys/kernel/mm/transparent_hugepage/enabled; valid values: always | madvise | never. transparentHugepageShmemEnabled — maps to /sys/kernel/mm/transparent_hugepage/shmem_enabled; valid values: always | within_size | advise | never | deny | force. |
Annotations added by ACS
Note
ACS writes these annotations to a pod after it is created. They reflect runtime allocation results such as elastic network interface (ENI) and EIP assignments. You cannot set or modify these annotations.
ENI allocation
| Parameter | Example value | Description |
|---|---|---|
network.alibabacloud.com/allocated-eni-id |
"eni-esdxs***" |
ID of the allocated ENI. |
network.alibabacloud.com/vpc-id |
"vpc-sljwo***" |
ID of the VPC the ENI belongs to. |
network.alibabacloud.com/vswitch-id |
"vsw-lskdw***" |
ID of the vSwitch the ENI was assigned to. If you specified multiple vSwitches, this shows the one actually used. |
EIP allocation
| Parameter | Example value | Description |
|---|---|---|
network.alibabacloud.com/allocated-eip-id |
"eip-bp1m***" |
ID of the allocated EIP. |
network.alibabacloud.com/allocated-eip-address |
"116.62.***" |
IP address of the allocated EIP. |
Resource specifications
| Parameter | Example value | Description |
|---|---|---|
alibabacloud.com/pod-use-spec |
"2.5-5Gi" |
Normalized CPU and memory specifications. The format is xxvCPU-xxGiB. |
alibabacloud.com/pod-gpu-use-spec |
"1" |
Normalized number of GPU cards. |
alibabacloud.com/pod-ephemeral-storage |
"30Gi" |
Normalized ephemeral storage size, in GiB. |
Scheduling result
| Parameter | Example value | Description |
|---|---|---|
topology.kubernetes.io/region |
"cn-hangzhou" |
Region where the pod is running. |
topology.kubernetes.io/zone |
"cn-hangzhou-i" |
Zone where the pod is running. |
Other metadata
| Parameter | Example value | Description |
|---|---|---|
alibabacloud.com/instance-id |
"acs-sdsf***" |
Instance ID of the ACS pod. |
alibabacloud.com/request-id |
"6925D4B7-***" |
Request ID of the pod creation call. |
Legacy annotation compatibility
The following annotations are supported for backward compatibility. Use the recommended replacements for new configurations.
| Legacy annotation | Recommended replacement |
|---|---|
k8s.aliyun.com/eci-eip-instanceid |
network.alibabacloud.com/pod-eip-instanceid |
k8s.aliyun.com/eip-charge-type |
network.alibabacloud.com/eip-internet-charge-type |