Annotations for Configuring LoadBalancer Ingresses

Updated on 2025-02-28 GMT+08:00

View PDF

You can add annotations to a YAML file for more advanced ingress functions. This section describes the annotations that can be used when you create a LoadBalancer ingress.

Indexes

Category	Ingress Annotation
Load balancer configuration	Basic Configurations for Interconnecting with ELB Adding Resource Tags
Port or protocol configuration	Configuring ELB Certificates Using HTTP/2 Interconnecting with HTTPS Backend Services Configuring a Range of Listening Ports
Advanced features of ELB listeners	Configuring Timeout for an Ingress Configuring a Slow Start Configuring a Custom EIP
Forwarding policy	Configuring the Priorities of Forwarding Rules Configuring a Custom Header Forwarding Policy Writing or Deleting a Header Configuring Advanced Forwarding Rules

Basic Configurations for Interconnecting with ELB

Application scenarios and use cases:

Associate an existing load balancer. For details, see Associating an Existing Load Balancer to an Ingress While Creating the Ingress.
Automatically create a load balancer. For details, see Automatically Creating a Load Balancer While Creating an Ingress.

**Table 1** Annotations for interconnecting with ELB
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.class	String	Select a proper load balancer type. performance: dedicated load balancer, which can be used only in clusters of v1.17 and later.	v1.9 or later
kubernetes.io/ingress.class	String	cce: A proprietary LoadBalancer ingress is used. nginx: Nginx Ingress is used. This parameter is mandatory when an ingress is created by calling the API. For clusters of v1.23 or later, use the parameter ingressClassName. For details, see Creating a LoadBalancer Ingress Using kubectl.	Only clusters of v1.21 or earlier
kubernetes.io/elb.port	String	This parameter indicates the external port registered with the address of the LoadBalancer Service. The value ranges from 1 to 65535. NOTE: Some ports are high-risk ports and are blocked by default, for example, port 21.	v1.9 or later
kubernetes.io/elb.id	String	Mandatory when an existing load balancer is to be interconnected. ID of a load balancer. How to obtain: On the management console, click Service List, and choose Networking > Elastic Load Balance. Click the name of the target load balancer. On the Summary tab page, find and copy the ID.	v1.9 or later
kubernetes.io/elb.ip	String	Mandatory when an existing load balancer is to be interconnected. Service address of a load balancer. The value can be the public IP address of a public network load balancer or the private IP address of a private network load balancer.	v1.9 or later
kubernetes.io/elb.autocreate	Table 14 Object	Mandatory when load balancers are automatically created. Example Automatically created shared load balancer with an EIP bound: '{"type":"public","bandwidth_name":"cce-bandwidth-1551163379627","bandwidth_chargemode":"bandwidth","bandwidth_size":5,"bandwidth_sharetype":"PER","eip_type":"5_bgp","name":"james"}' Automatically created shared load balancer with no EIP bound: {"type":"inner","name":"A-location-d-test"}	v1.9 or later
kubernetes.io/elb.enterpriseID	String	Optional when load balancers are automatically created. Clusters of v1.15 and later versions support this field. In clusters earlier than v1.15, load balancers are created in the default project by default. This parameter indicates the ID of the enterprise project in which the ELB load balancer will be created. If this parameter is not specified or is set to 0, resources will be bound to the default enterprise project. How to obtain: Log in to the management console and choose Enterprise > Project Management on the top menu bar. In the list displayed, click the name of the target enterprise project, and copy the ID on the enterprise project details page.	v1.15 or later
kubernetes.io/elb.subnet-id	String	Optional when load balancers are automatically created. ID of the subnet where the cluster is located. The value can contain 1 to 100 characters. Mandatory when a cluster of v1.11.7-r0 or earlier is to be automatically created. Optional for clusters of a version later than v1.11.7-r0.	Mandatory for clusters earlier than v1.11.7-r0 Discarded in clusters of a version later than v1.11.7-r0

Configuring ELB Certificates

For details about application scenarios and use cases, see Using kubectl to Configure a Certificate Created on the ELB Console.

**Table 2** ELB certificate annotations
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.tls-certificate-ids	String	ELB certificate IDs, which are separated by comma (,). The list length is greater than or equal to 1. The first ID in the list is the server certificate, and the other IDs are SNI certificates in which a domain name must be contained. To obtain the certificate, log in to the CCE console, choose Service List > Networking > Elastic Load Balance, and click Certificates in the navigation pane. In the load balancer list, copy the ID under the target certificate name.	v1.19.16-r2, v1.21.5-r0, v1.23.3-r0, or later

Adding Resource Tags

For details about application scenarios and use cases, see Automatically Creating a Load Balancer While Creating an Ingress.

**Table 3** Annotations
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.tags	String	Add resource tags to a load balancer. This parameter can be configured only when a load balancer is automatically created. A tag is in the format of "key=value". Use commas (,) to separate multiple tags.	v1.23.11-r0, v1.25.6-r0, v1.27.3-r0, or later

Using HTTP/2

For details about application scenarios and use cases, see Configuring HTTP/2 for a LoadBalancer Ingress.

**Table 4** Annotations for using HTTP/2
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.http2-enable	String	Whether HTTP/2 is enabled. Request forwarding using HTTP/2 improves the access performance between your application and the load balancer. However, the load balancer still uses HTTP/1.x to forward requests to the backend server. Options: true: enabled false: disabled (default value) Note: HTTP/2 can be enabled or disabled only when the listener uses HTTPS. This parameter is invalid and defaults to false when the listener protocol is HTTP.	v1.23.13-r0, v1.25.8-r0, v1.27.5-r0, v1.28.3-r0, or later

Interconnecting with HTTPS Backend Services

For details about application scenarios and use cases, see Configuring HTTPS Backend Services for a LoadBalancer Ingress.

**Table 5** Annotations for interconnecting with HTTPS backend services
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.pool-protocol	String	To interconnect with HTTPS backend services, set this parameter to https.	v1.23.8, v1.25.3, or later

Configuring Timeout for an Ingress

For details about application scenarios and use cases, see Configuring Timeout for a LoadBalancer Ingress.

**Table 6** Annotations for configuring timeout of an ingress
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.keepalive_timeout	String	Timeout for client connections. If there are no requests reaching the load balancer during the timeout duration, the load balancer will disconnect the connection from the client and establish a new connection when there is a new request. Value: For TCP listeners, the value ranges from 10 to 4000 (in seconds). The default value is 300. For HTTP or HTTPS listeners, the value ranges from 0 to 4000 (in seconds). The default value is 60. For UDP listeners, this parameter does not take effect.	Dedicated load balancers: v1.19.16-r30, v1.21.10-r10, v1.23.8-r10, v1.25.3-r10, or later Shared load balancers: v1.23.13-r0, v1.25.8-r0, v1.27.5-r0, v1.28.3-r0, or later
kubernetes.io/elb.client_timeout	String	Timeout for waiting for a request from a client. There are two cases: If the client fails to send a request header to the load balancer during the timeout duration, the request will be interrupted. If the interval between two consecutive request bodies reaching the load balancer is greater than the timeout duration, the connection will be disconnected. The value ranges from 1 to 300 (in seconds). The default value is 60. This parameter is available only for HTTP and HTTPS listeners. Minimum value: 1 Maximum value: 300 Default value: 60
kubernetes.io/elb.member_timeout	String	Timeout for waiting for a response from a backend server. After a request is forwarded to the backend server, if the backend server does not respond within the duration specified by member_timeout, the load balancer will stop waiting and return HTTP 504 Gateway Timeout. The value ranges from 1 to 300 (in seconds). The default value is 60. This parameter is available only for HTTP and HTTPS listeners. Minimum value: 1 Maximum value: 300 Default value: 60

Configuring a Slow Start

For details about application scenarios and use cases, see Configuring a Slow Start for a LoadBalancer Ingress.

**Table 7** Annotations for configuring a slow start
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.slowstart	String	Duration of slow start, in seconds. The slow start duration ranges from 30 to 1200. This configuration applies only to dedicated load balancers. Valid only when the allocation policy of the target Service is weighted round robin (WRR) and sticky session is disabled. NOTE: The load balancer linearly increases the proportion of requests to backend servers in slow start mode. When the configured slow start duration elapses, the load balancer sends full share of requests to backend servers and exits the slow start mode.	v1.23 or later

Configuring a Range of Listening Ports

A custom listening port can be configured for an ingress. In this way, both ports 80 and 443 can be exposed.

**Table 8** Annotations for a custom listening port
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.listen-ports	String	Configure multiple listening ports for an ingress. The port number ranges from 1 to 65535. The following is an example for JSON characters: kubernetes.io/elb.listen-ports: '[{"HTTP":80},{"HTTPS":443}]' Only the listening ports that comply with both HTTP and HTTPS are allowed. This function is available only for newly created ingresses in clusters of a version earlier than v1.23.18-r10, v1.25.16-r0, v1.27.16-r0, v1.28.13-r0, v1.29.8-r0, or v1.30.4-r0. Additionally, after you configure multiple listening ports, the annotations cannot be modified or deleted. In clusters of v1.23.18-r10, v1.25.16-r0, v1.27.16-r0, v1.28.13-r0, v1.29.8-r0, v1.30.4-r0, or later, the annotations can be modified or deleted. If both kubernetes.io/elb.listen-ports and kubernetes.io/elb.port are configured, kubernetes.io/elb.listen-ports takes a higher priority. Ingress configuration items such as the blocklist, trustlist, and timeout concurrently take effect on multiple listening ports. When HTTP/2 is enabled for an ingress, HTTP/2 takes effect only on the HTTPS port.	v1.23.14-r0, v1.25.9-r0, v1.27.6-r0, v1.28.4-r0, or later

Configuring the Priorities of Forwarding Rules

When ingresses use the same load balancer listener, forwarding rules can be prioritized based on the following rules:

Forwarding rules of different ingresses: The rules are sorted based on the priorities (ranging from 1 to 1000) of the kubernetes.io/elb.ingress-order annotation. A smaller value indicates a higher priority.
Forwarding rules of an ingress: If the kubernetes.io/elb.rule-priority-enabled annotation is set to true, the forwarding rules are sorted based on the sequence in which they are added during ingress creation. A forwarding rule added earlier indicates a higher priority. If the kubernetes.io/elb.rule-priority-enabled annotation is not configured, the default sorting of the forwarding rules on the load balancer will be used.

If the preceding annotations are not configured, the default sorting of the forwarding rules on the load balancer will be used, regardless of whether the forwarding rules are of the same ingress or different ingresses under the same load balancer listener.

For details about application scenarios and use cases, see Configuring the Priorities of Forwarding Rules for LoadBalancer Ingresses.

**Table 9** Annotations for configuring the priorities of forwarding rules
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.ingress-order	String	Specifies the sequence of forwarding rules of different ingresses. The value ranges from 1 to 1000. A smaller value indicates a higher priority. The priority of a forwarding rule must be unique under the same load balancer listener. This parameter is available only for dedicated load balancers. NOTE: When this annotation is configured, the kubernetes.io/elb.rule-priority-enabled annotation is enabled by default. The forwarding rules of each ingress will be sorted.	v1.23.15-r0, v1.25.10-r0, v1.27.7-r0, v1.28.5-r0, v1.29.1-r10, or later
kubernetes.io/elb.rule-priority-enabled	String	This parameter can only be set to true, indicating to sort the forwarding rules of an ingress. The priorities of the forwarding rules are determined based on the sequence in which they are added during ingress creation. A forwarding rule added earlier indicates a higher priority. If this parameter is not configured, the default sorting of the forwarding rules on the load balancer will be used. After this parameter is enabled, it cannot be disabled. This parameter is available only for dedicated load balancers.

Configuring a Custom Header Forwarding Policy

For details about application scenarios and use cases, see Configuring a Custom Header Forwarding Policy for a LoadBalancer Ingress.

**Table 10** Annotations for configuring a custom header forwarding policy
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.headers.${svc_name}	String	Custom header of the Service associated with an ingress. ${svc_name} is the Service name. Format: a JSON string, for example, {"key": "test", "values": ["value1", "value2"]} key/value indicates the key-value pair of the custom header. A maximum of eight values can be configured. Enter 1 to 40 characters for a key. Only letters, digits, hyphens (-), and underscores (_) are allowed. Enter 1 to 128 characters for a value. Asterisks () and question marks (?) are allowed, but spaces and double quotation marks are not allowed. An asterisk can match zero or more characters, and a question mark can match one character. Either a custom header or grayscale release can be configured. Enter 1 to 51 characters for ${svc_name}*.	v1.23.16-r0, v1.25.11-r0, v1.27.8-r0, v1.28.6-r0, v1.29.2-r0, or later

Configuring a Custom EIP

For details about application scenarios and use cases, see Configuring a Custom EIP for a LoadBalancer Ingress.

**Table 11** Annotations of custom EIP configurations
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.custom-eip-id	String	ID of the custom EIP, which can be seen on the EIP console The EIP must be bindable.	v1.23.18-r0, v1.25.13-r0, v1.27.10-r0, v1.28.8-r0, v1.29.4-r0, v1.30.1-r0, or later

Writing or Deleting a Header

For details about application scenarios and use cases, see Configuring Header Writing or Deletion for a LoadBalancer Ingress.

**Table 12** Annotations for writing or deleting a header
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.actions.${svc_name}	String	Rewrite the header of the Service associated with an ingress. ${svc_name} indicates the Service name, which contains a maximum of 51 characters. If the annotation value is set to [], the header rewriting policy is deleted. An annotation value is a JSON string array. For example: [{"type":"InsertHeader","InsertHeaderConfig":{"key":"aa","value_type":"USER_DEFINED","value":"aa"}}] NOTE: A maximum of five configurations are allowed for writing or deleting a header.	v1.23.18-r10, v1.25.16-r0, v1.27.16-r0, v1.28.13-r0, v1.29.8-r0, v1.30.4-r0, or later

Configuring Advanced Forwarding Rules

For details about application scenarios and use cases, see Configuring Advanced Forwarding Rules for a LoadBalancer Ingress.

**Table 13** Annotations for writing or deleting a header
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/elb.conditions.${svc_name}	String	Configure an advanced forwarding rule. ${svc_name} indicates the Service name, which contains a maximum of 51 characters. If the annotation value is set to [], the advanced forwarding rule is deleted. The annotation value is in the form of a JSON array. For details, see Table 2. NOTICE: Due to ELB API restrictions, a kubernetes.io/elb.conditions.{svcName} can contain a maximum of 10 key-value pairs. The rules in a condition array are connected by an AND relationship, while the values in the same rule block are connected by an OR relationship. For example, if both Method and QueryString are configured, the target traffic can be distributed only when both rules are met. However, if the Method value is GET or POST, the target traffic can be distributed only when both rules are met and the Method value must be GET or POST.	v1.23.18-r10, v1.25.16-r0, v1.27.16-r0, v1.28.13-r0, v1.29.8-r0, v1.30.4-r0, or later

Parameters for Automatically Creating a Load Balancer

**Table 14** elb.autocreate data structure
Parameter	Mandatory	Type	Description
name	No	String	Name of the automatically created load balancer. The value can contain 1 to 64 characters. Only letters, digits, underscores (_), hyphens (-), and periods (.) are allowed. Default: cce-lb+service.UID
type	No	String	Network type of the load balancer. public: public network load balancer inner: private network load balancer Default: inner
bandwidth_name	Yes for public network load balancers	String	Bandwidth name. The default value is cce-bandwidth-******. The value can contain 1 to 64 characters. Only letters, digits, underscores (_), hyphens (-), and periods (.) are allowed.
bandwidth_chargemode	No	String	Bandwidth mode. bandwidth: billed by bandwidth traffic: billed by traffic Default: bandwidth
bandwidth_size	Yes for public network load balancers	Integer	Bandwidth size. The value ranges from 1 Mbit/s to 2000 Mbit/s by default. Configure this parameter based on the bandwidth range allowed in your region. The minimum increment for bandwidth adjustment varies depending on the bandwidth range. The minimum increment is 1 Mbit/s if the allowed bandwidth does not exceed 300 Mbit/s. The minimum increment is 50 Mbit/s if the allowed bandwidth ranges from 300 Mbit/s to 1000 Mbit/s. The minimum increment is 500 Mbit/s if the allowed bandwidth exceeds 1000 Mbit/s.
bandwidth_sharetype	Yes for public network load balancers	String	Bandwidth sharing mode. PER: dedicated bandwidth
eip_type	Yes for public network load balancers	String	EIP type. 5_bgp: dynamic BGP The specific type varies with regions. For details, see the EIP console.
vip_subnet_cidr_id	No	String	Subnet where a load balancer is located. The subnet must belong to the VPC where the cluster resides. If this parameter is not specified, the ELB load balancer and the cluster are in the same subnet. This field can be specified only for clusters of v1.21 or later.
vip_address	No	String	Private IP address of the load balancer. Only IPv4 addresses are supported. The IP address must be in the ELB CIDR block. If this parameter is not specified, an IP address will be automatically assigned from the ELB CIDR block. This parameter is available only in clusters of v1.23.11-r0, v1.25.6-r0, v1.27.3-r0, or later versions.
available_zone	Yes	Array of strings	AZ where the load balancer is located. This parameter is available only for dedicated load balancers.
l4_flavor_name	Yes	String	Flavor name of the layer-4 load balancer. This parameter is available only for dedicated load balancers.
l7_flavor_name	No	String	Flavor name of the layer-7 load balancer. This parameter is available only for dedicated load balancers. The value of this parameter must be the same as that of l4_flavor_name, that is, both are elastic specifications or fixed specifications.
elb_virsubnet_ids	No	Array of strings	Subnet where the backend server of the load balancer is located. If this parameter is left blank, the default cluster subnet is used. Load balancers occupy different number of subnet IP addresses based on their specifications. Do not use the subnet CIDR blocks of other resources (such as clusters and nodes) as the load balancer CIDR block. This parameter is available only for dedicated load balancers. Example: "elb_virsubnet_ids": [ "14567f27-8ae4-42b8-ae47-9f847a4690dd" ]