Configure a Classic Load Balancer (CLB) with annotations - Container Compute Service

Use annotations in a Service YAML file to configure CLB instances, listeners, and backend server groups.

Index

Main content	Quick links
Using annotations
CLB operations	Creating a public network CLB instance Creating a private network CLB instance Specifying a load balancer specification Using an existing CLB instance Using an existing CLB instance and forcibly overwriting its listeners Specifying primary and secondary availability zones for a CLB instance Creating a pay-by-bandwidth CLB instance Specifying a vSwitch for a CLB instance Specifying an IP address for a private network CLB instance Adding tags to a CLB instance Creating an IPv6 CLB instance Enabling deletion protection for a CLB instance Enabling configuration modification protection for a CLB instance Specifying a name for a CLB instance Specifying a resource group for a CLB instance Setting a hostname for a Service Creating a pay-as-you-go CLB instance
Listener operations	Configuring session persistence for a TCP listener Configuring session persistence (cookie insertion) for HTTP and HTTPS listeners Configuring an access control list (ACL) for a CLB instance Specifying the forwarding port for a listener Setting the scheduling algorithm for a listener Creating a UDP listener Creating an HTTP listener Creating an HTTPS listener Creating a listener with health checks Enabling connection draining for a listener Configuring additional request headers for a listener Setting the idle timeout for a listener Disabling the HTTP/2 feature for a listener Specifying the request timeout for a listener Specifying the connection timeout for a listener Configuring a security policy for a listener Configuring a listener for both TCP and UDP Configuring Proxy Protocol for TCP and UDP listeners
Backend server group operations	Reusing an existing VServer group Setting the traffic weight for a Service Ignoring backend server weight updates
Related documentation

Annotations

Annotations are case-sensitive.
Check the required CCM version for each annotation before use. To upgrade CCM, see manage components. CCM change log: Cloud Controller Manager.
As of September 11, 2019, for annotations, the alicloud prefix was updated to alibaba-cloud.

For example:

Before the update: service.beta.kubernetes.io/alicloud-loadbalancer-id

After the update: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id

The system remains compatible with the alicloud format. No changes to existing configurations are required.

CLB operations

Create a public load balancer

apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Create a private load balancer

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type

Description

Default

Supported CCM versions

Specifies the address type of the load balancer. Valid values:

internet: Exposes the Service over the public network. This is the default value. The IP Version of the CLB instance must be Internet-facing.
intranet: Exposes the Service over the private network. The IP Version of the CLB instance must be Internal-facing.

internet

v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: "intranet"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Specify load balancer specification

Annotation: Multiple, as shown in the following table.

Annotation

Description

Default

Supported CCM versions

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-instance-charge-type

Specifies the instance billing method. Use PayBySpec to create a pay-by-specification instance.

paybytraffic
paybybandwidth

PayBySpec

v1.9.3 and later

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec

The CLB instance specification. Use this annotation to create an instance with a specific specification or update an existing one. CreateLoadBalancer.

Important

If you modify the specification in the CLB console (this operation is only supported for pay-by-specification instances), CCM may revert the change.

slb.s1.small

v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-instance-charge-type: "PayBySpec"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec: "slb.s1.small"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Use an existing load balancer

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id

Description

Default

Supported CCM versions

The ID of the load balancer instance. Use this annotation to specify an existing CLB instance.

By default, using an existing load balancer instance does not overwrite its listeners. To forcibly overwrite existing listeners, set service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners to "true". This setting overwrites only the listeners for the current Service and does not affect other listeners.
Note
By default, existing listeners are not overwritten for the following reasons:
- If workloads are already bound to listeners on the existing load balancer instance, forcing an overwrite can cause service interruptions.
- CCM supports a limited set of backend configurations and cannot manage complex setups. For complex requirements, configure listeners in the console and ensure they are not overwritten.
Do not forcibly overwrite listeners unless the listener port on the existing CLB instance is no longer in use.
You cannot add additional tags by using the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags annotation when reusing an existing load balancer instance.

None

v1.9.3.81-gca19cd4-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id: "${YOUR_LOADBALANCER_ID}" # Multiple policy groups cannot be configured.
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Use an existing load balancer and overwrite listeners

Annotation: Multiple, as shown in the following table. This operation forcibly overwrites existing listeners. If a listener port conflicts, the existing listener is deleted.

Annotation

Description

Default

Supported CCM versions

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id

The ID of the existing CLB instance.

By default, using an existing load balancer instance does not override its listeners. To force an override of existing listeners, set the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners annotation to "true". This setting overrides only the listeners for the current Service and does not affect other listeners.
Note
By default, reusing an existing load balancer does not override its listeners for two reasons:
- If services are bound to the listeners of the existing load balancer, forcing an override may cause service disruptions.
- The Cloud Controller Manager (CCM) has limited support for backend configurations and cannot handle complex ones. If you require complex backend configurations, configure the listeners in the console without overriding them.
Do not force an override unless the listener port on the existing CLB instance is no longer in use.
When you use an existing load balancer, adding extra tags with the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags annotation is not supported.

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners

Specifies whether to forcibly overwrite the listeners of the CLB instance. Valid values:

"true": Overwrites the listeners. This overwrites only the listeners for the current Service and does not affect other listeners.
"false": Does not overwrite the listeners.

Important

When you reuse an existing CLB and set force-override to "true", do not reuse the same listener on the same CLB for multiple Services. Otherwise, listener configuration conflicts will occur.

"false"

v1.9.3.81-gca19cd4-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id: "${YOUR_LOADBALANCER_ID}"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners: "true"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Specify primary and standby availability zones

Annotation: Multiple, as shown in the following table. The primary and standby availability zones cannot be changed after the instance is created.

Availability varies by region. Check the CLB instance creation page.

Annotation	Description	Default	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-master-zoneid	The ID of the primary availability zone.	None	v1.9.3.10-gfb99107-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-slave-zoneid	The ID of the standby availability zone.	None	v1.9.3.10-gfb99107-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-master-zoneid: "cn-hangzhou-k"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-slave-zoneid: "cn-hangzhou-j"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Create a pay-by-bandwidth load balancer

Annotation: Multiple, as shown in the following table. The following two annotations are required.

Annotation

Description

Default

Supported CCM versions

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-charge-type

The billing method of the load balancer instance. Valid values:

paybytraffic
paybybandwidth

paybytraffic

v1.9.3 and later

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-bandwidth

The peak bandwidth of the CLB instance. Applies only to public CLB instances. Change the billing method of a public load balancer instance.

v1.9.3.10-gfb99107-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-charge-type: "paybybandwidth"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-bandwidth: "2"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Specify a vSwitch for a load balancer

Annotation: Multiple, as shown in the following table. The following two annotations are required.

Annotation

Description

Default

Supported CCM versions

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type

Specifies the address type of the load balancer. Valid values:

internet: Exposes the Service over the public network. This is the default value. The IP Version of the CLB instance must be Internet-facing.
intranet: Exposes the Service over the private network. The IP Version of the CLB instance must be Internal-facing.

internet

v1.9.3 and later

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id

The ID of the vSwitch to which the load balancer instance belongs. The vSwitch must be in the same VPC as the Kubernetes cluster.

This annotation requires setting service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type to "intranet".

You can find the vSwitch ID in the VPC console.

None

v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
   service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: "intranet"
   service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id: "${YOUR_VSWITCH_ID}"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Specify an IP address for a private load balancer

Annotation: Multiple, as shown in the following table. The following three annotations are required.

Annotation	Description	Default	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type	Specifies the address type of the load balancer. Valid values: `internet`: Exposes the Service over the public network. This is the default value. The IP Version of the CLB instance must be Internet-facing. `intranet`: Exposes the Service over the private network. The IP Version of the CLB instance must be Internal-facing.	internet	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id	The ID of the vSwitch to which the load balancer instance belongs. The vSwitch must be in the same VPC as the Kubernetes cluster. This annotation requires setting `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type` to "intranet". You can find the vSwitch ID in the VPC console.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip	The IP address of the private load balancer instance. The IP address must be within the CIDR block of the vSwitch. Only IPv4 addresses are supported. This annotation must be used with the `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id` annotation. The IP address cannot be changed after the load balancer instance is created.	None	v2.7.0 and later

apiVersion: v1
kind: Service
metadata:
 annotations:
  service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: "intranet"
  service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id: "${YOUR_VSWITCH_ID}"
  service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip: "192.168.x.x"
 name: nginx
 namespace: default
spec:
 type: LoadBalancer
 ports:
 - port: 80
   targetPort: 80
   name: http
 selector:
   app: nginx

Add tags to a load balancer

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags

Description	Default	Supported CCM versions
A comma-separated list of tags to add, for example, `"k1=v1,k2=v2"`.	None	v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags: "Key1=Value1,Key2=Value2" 
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Create an IPv6 load balancer

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip-version

Description

Default

Supported CCM versions

The IP version of the load balancer instance. The IP version cannot be changed after the instance is created. To use this feature, kube-proxy in your cluster must run in IPVS mode. Valid values:

ipv4: IPv4.
ipv6: IPv6. The resulting IPv6 address is only accessible from IPv6-enabled environments.

ipv4

v1.9.3.220-g24b1885-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip-version: "ipv6"
  name: nginx
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
  type: LoadBalancer

Enable deletion protection for a load balancer

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-delete-protection

Description

Default

Supported CCM versions

Specifies whether deletion protection is enabled for the load balancer instance. Valid values:

on
off

Important

Note that if you enable deletion protection in the CLB console, the load balancer instance can still be deleted by running the kubectl delete svc {your-svc-name} command.

v1.9.3.313-g748f81e-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-delete-protection: "on"
  name: nginx
spec:
  externalTrafficPolicy: Local
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
  type: LoadBalancer

Enable modification protection for a load balancer

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-modification-protection

Description

Default

Supported CCM versions

Specifies the modification protection status for the load balancer instance. Valid values:

ConsoleProtection
NonProtection

ConsoleProtection

v1.9.3.313-g748f81e-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-modification-protection: "ConsoleProtection"
  name: nginx
spec:
  externalTrafficPolicy: Local
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
  type: LoadBalancer

Specify a load balancer name

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-name

Description	Default	Supported CCM versions
The CLB instance name. Must be 2–128 characters, starting with a letter or Chinese character. Can contain digits, periods (.), underscores (_), and hyphens (-).	None	v1.9.3.313-g748f81e-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-name: "your-svc-name"
  name: nginx
spec:
  externalTrafficPolicy: Local
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
  type: LoadBalancer

Specify a resource group for a load balancer

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-resource-group-id

Description	Default	Supported CCM versions
The ID of the resource group for the load balancer instance. The resource group ID cannot be changed once set. You can find resource group IDs in the Resource Management console.	None	v1.9.3.313-g748f81e-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-resource-group-id: "rg-xxxx"
  name: nginx
spec:
  externalTrafficPolicy: Local
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
  type: LoadBalancer

Set a hostname for a Service

Annotation: Multiple, as shown in the following table.

Annotation

Description

Default

Supported CCM versions

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port

Separate multiple values with commas (,), for example, https:443,http:80.

None

v1.9.3 and later

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-hostname

Specifies a hostname for the Service. The hostname must conform to DNS naming conventions.

Note the following:

After you add this annotation, the EXTERNAL-IP of the Service changes from the default CLB IP address to ${your_service_hostname}. When you access the CLB IP address from within the cluster, traffic is routed through the CLB instance and then forwarded back to the cluster.
After you add this annotation, if the listener protocol is TCP or UDP, this causes a hairpinning issue when accessing the CLB IP address from within the cluster. Clients cannot access a load balancer.
This annotation does not automatically create a DNS record. You must manually create a DNS A or CNAME record that points the hostname to the CLB instance's IP address. What is Alibaba Cloud Domains?.

None

v2.3.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "http:80"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-hostname: "${your_service_hostname}"
  name: nginx-svc
  namespace: default
spec:
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
  type: LoadBalancer

Expected output:

NAME         TYPE           CLUSTER-IP       EXTERNAL-IP            PORT(S)                      AGE
nginx-svc    LoadBalancer   47.100.XX.XX     www.example.com        80/TCP,443/TCP   10s

Create a pay-by-consumption load balancer

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-instance-charge-type

Description

Default

Supported CCM versions

The instance billing method. Valid values:

PayBySpec: The default value. Billed by specification.
PayByCLCU: Billed by consumption.

Important

You cannot set a specification for a load balancer instance that is billed by consumption. The value PayByCLCU cannot be used together with the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec annotation.

PayBySpec

v2.4.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-instance-charge-type: "PayByCLCU"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Common listener actions

Configure TCP session persistence

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-persistence-timeout

Description

Default

Supported CCM versions

Specifies the session persistence time for TCP listeners. If a load balancer instance has multiple TCP listeners, this setting applies to all of them by default.

Value range: 0–3600 seconds. Default: 0 (session persistence disabled). CreateLoadBalancerTCPListener.

v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-persistence-timeout: "1800"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Configure a sticky session (insert cookie)

Multiple annotations are required, as shown in the following table. The insert cookie method requires three annotations.

This feature applies only to load balancer instances with HTTP or HTTPS listeners.
By default, this sticky session setting applies to all configured HTTP and HTTPS listeners.

Annotation	Description	Default	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session	Enables or disables sticky sessions. This setting applies only to HTTP and HTTPS listeners. Valid values: `on` `off` CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener.	off	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session-type	Specifies the cookie handling method. This setting is effective only for HTTP and HTTPS listeners. This annotation is required when `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session` is set to `on`. Valid values: `insert`: Inserts a cookie. `server`: Rewrites a cookie. CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cookie-timeout	The cookie timeout in seconds. The valid range is 1 to 86,400. This annotation is required when `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session` is set to `on` and `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session-type` is set to `insert`. CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cookie	The name of the cookie that is configured on the server. The name must be 1 to 200 characters long and contain only ASCII letters and digits. It cannot contain commas (,), semicolons (;), or spaces, and must not start with a dollar sign ($). This annotation is required when `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session` is set to `on` and `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session-type` is set to `server`. CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Specifies the listener port(s) to which the sticky session settings apply. By default, the settings apply to all listeners. Separate multiple entries with a comma (,). Example: `https:443,http:80`.	None	v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session: "on"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session-type: "insert"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cookie-timeout: "1800"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "http:80"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Configure an access control list

Note: The three annotations in the following table are required.

Before using these annotations, create an access control list in the Classic Load Balancer (CLB) console and record its ID.

Annotation	Description	Default	Supported versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-status	Specifies whether to enable access control. Valid values: `on` `off`	off	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-id	The ID of the access control list to associate with the listener. This parameter is required when `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-status` is set to `"on"`.	None	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-type	Access control type. Possible values: `white`: A whitelist that forwards only requests from the IP addresses or IP address ranges in the selected access control list. A whitelist is suitable for scenarios where an application must be accessible only from specific IP addresses. Using a whitelist can pose business risks. If you enable a whitelist but the access control list is empty, the listener forwards all requests. `black`: A blacklist that blocks all requests from the IP addresses or IP address ranges in the selected access control list. A blacklist is suitable for scenarios where you want to restrict access from specific IP addresses. If you enable a blacklist but the access control list is empty, all requests are forwarded.	None	v1.9.3.164-g2105d2e-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-status: "on"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-id: "${YOUR_ACL_ID}"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-type: "white"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Configure port forwarding for a load balancer

Port forwarding redirects requests from an HTTP port to an HTTPS port.

Annotations: The following three annotations are required.

Annotation	Description	Default	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with a comma, for example, `https:443,http:80`.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	The Alibaba Cloud certificate ID. Log in to the CLB console and view the certificate ID on the Certificates page. Note To create a certificate, see Select an Alibaba Cloud-issued certificate.	None	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-forward-port	Forwards HTTP requests to an HTTPS port, for example, `80:443`.	None	v1.9.3.164-g2105d2e-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "https:443,http:80"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id: "${YOUR_CERT_ID}"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-forward-port: "80:443"
  name: nginx
  namespace: default
spec:
  ports:
  - name: https
    port: 443
    protocol: TCP
    targetPort: 80
  - name: http
    port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Load balancer scheduling algorithm

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-scheduler

Description

Default

Supported versions

The scheduling algorithm. Valid values:

wrr: weighted round robin. A backend server with a higher weight receives more incoming requests.
rr: round robin. Backend servers receive requests sequentially.

v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-scheduler: "wrr"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Create a UDP listener

apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: UDP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Create an HTTP listener

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port

Description	Default	Supported CCM versions
Separate multiple values with commas, for example, `https:443,http:80`.	None	v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "http:80"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Create an HTTPS listener

Annotation: For the required annotations, see the following table.

The CLB layer decrypts HTTPS requests and sends them to backend Pods as HTTP requests.

Annotation

Description

Default

Supported CCM versions

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port

Separate multiple values with commas, for example, https:443,http:80.

None

v1.9.3 and later

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id

The Alibaba Cloud certificate ID.

Log on to the CLB console and view the certificate ID on the Certificates page.

Note

To create a certificate, see Select an Alibaba Cloud-issued certificate.

None

v1.9.3.164-g2105d2e-aliyun and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "https:443"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id: "${YOUR_CERT_ID}"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Create a listener with a health check

Configure a TCP health check

Annotations: The following table lists the required annotations.

By default, health checks are enabled for TCP ports.

Annotation	Description	Default	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-switch	Specifies whether to enable health checks for TCP and UDP listeners. Valid values: `on` `off`	on	v2.6.0 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type	The health check type. Valid values: `tcp` `http` CreateLoadBalancerTCPListener.	tcp	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout	The time to wait for a health check response, in seconds. If a backend server does not respond within this period, the health check fails. Valid values: 1–300. If the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout` is less than the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval`, the former setting is invalid and the timeout is set to the value of the latter. CreateLoadBalancerTCPListener.	5	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold	The number of consecutive successful health checks required to change a backend server's status from `fail` to `success`. Valid values: 2–10. CreateLoadBalancerTCPListener.	3	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold	The number of consecutive failed health checks required to change a backend server's status from `success` to `fail`. Valid values: 2–10. CreateLoadBalancerTCPListener.	3	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval	The interval between health checks, in seconds. Valid values: 1–50. CreateLoadBalancerTCPListener.	2	v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-switch: "on"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type: "tcp"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout: "8"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold: "4"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold: "4"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval: "3"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Configure UDP health checks

Annotation: Multiple, as shown in the table below. All the following annotations are required.

By default, health checks are enabled for UDP ports.

Annotation	Description	Default	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-switch	Specifies whether to enable health checks for TCP and UDP listeners. Valid values: `on` `off`	on	v2.6.0 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout	The response timeout for a health check. This parameter applies to UDP listeners. If a backend server fails to respond within this timeout, the health check fails. Unit: seconds. Value range: [1, 300]. If the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout` is less than the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval`, the former setting is invalid, and the timeout is set to the value of the latter. CreateLoadBalancerUDPListener.	5	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold	The number of consecutive successful health checks required to change a backend server's status from `fail` to `success`. Value range: [2, 10]. CreateLoadBalancerUDPListener.	3	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold	The number of consecutive failed health checks required to change a backend server's status from `success` to `fail`. Value range: [2, 10]. CreateLoadBalancerUDPListener.	3	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval	The interval between health checks. Unit: seconds. Value range: [1, 50]. CreateLoadBalancerUDPListener.	2	v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-switch: "on"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval: "5"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout: "10"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold: "3"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold: "3"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: UDP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Disable health checks for TCP and UDP

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-switch

Description

Default

Supported CCM versions

Specifies whether to enable health checks for TCP and UDP listeners. Valid values:

on
off

v2.6.0 or later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-switch: "off" # Disable the health check.
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Configure an HTTP health check

Annotation: Multiple, as shown in the following table.

Annotation	Description	Default	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-flag	Valid values: `on`: The default value for TCP listeners is `on` and cannot be changed. `off`: The default value for HTTP listeners is `off`.	off	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type	The protocol for the health check. Valid values: `tcp` `http` CreateLoadBalancerHTTPListener.	tcp	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-uri	The URI path for the health check. This annotation is required only for HTTP health checks.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-httpcode	The HTTP status codes that indicate a successful health check. Separate multiple values with a comma. Valid values: `http_2xx` `http_3xx` `http_4xx` `http_5xx` CreateLoadBalancerHTTPListener.	http_2xx	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-domain	The domain name used for the health check. Valid values: `$_ip`: Use the private IP of the backend server. This is also the default behavior if this annotation is not specified. `domain`: The domain name, which must be 1 to 80 characters long and contain only letters, digits, periods (.), and hyphens (-). CreateLoadBalancerHTTPListener.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout	The time, in seconds, to wait for a response to an HTTP health check. If no response is received within this period, the health check fails. Unit: seconds. Valid values: 1 to 300. If the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout` is less than the value of service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval, `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout` is invalid and the timeout is the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval`. CreateLoadBalancerHTTPListener.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold	The number of consecutive successful health checks required before a backend server is considered healthy (status changes from fail to success). Valid values: 2 to 10. CreateLoadBalancerHTTPListener.	3	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold	The number of consecutive failed health checks required before a backend server is considered unhealthy (status changes from success to fail). Valid values: 2 to 10. CreateLoadBalancerHTTPListener.	3	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval	The interval between health checks. Unit: seconds. Valid values: 1 to 50. CreateLoadBalancerHTTPListener.	2	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with a comma, for example, `https:443,http:80`.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-method	The HTTP method to use for the health check. Valid values: `head` `get`	None	v2.3.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-flag: "on"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type: "http"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-uri: "/test/index.html"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold: "4"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold: "4"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout: "10"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval: "3"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "http:80"
    # Set the HTTP status code for the health check (optional)
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-httpcode: "http_4xx"
    # Set the domain name for the health check (optional)
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-domain: "www.aliyun.com"
    # Set the health check method (optional)
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-method: "head"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Connection drain

Annotation: Multiple, as shown in the following table. All of these annotations are required.

Only TCP and UDP are supported.

Annotation

Description

Default

Supported CCM versions

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-connection-drain

Enables or disables connection drain. Valid values:

on
off

None

v2.0.1 and later

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-connection-drain-timeout

Sets the connection drain timeout in seconds. The valid range is 10 to 900.

None

v2.0.1 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-connection-drain: "on"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-connection-drain-timeout: "30"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Configure additional request headers for a listener

Configuration: Use the annotations in the following table to configure this feature.

This feature supports only HTTP and HTTPS listeners.

Annotation	Description	Default	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with a comma, for example, `https:443,http:80`.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-proto	Specifies whether to use the X-Forwarded-Proto header field to retrieve the listener protocol of the CLB instance. Valid values: `on` `off`	off	v2.1.0 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-slbport	Specifies whether to use the XForwardedFor_SLBPORT header field to retrieve the listener port of the load balancer instance. Valid values: `on` `off`	off	v2.9.1 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-clientsrcport	Specifies whether to use the XForwardedFor_ClientSrcPort header field to retrieve the client's source port. Valid values: `on` `off`	off	v2.9.1 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "http:80"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-proto: "on"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-slbport: "on"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-clientsrcport: "on"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Set idle timeout for a listener

Annotations: See the table below.

This feature only supports listeners that use the HTTP or HTTPS protocol.

Annotation	Description	Default	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with a comma (,), for example, `https:443,http:80`.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-idle-timeout	Specifies the idle timeout for the listener. Unit: seconds. Valid values: [1, 60].	15	v2.1.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "http:80"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-idle-timeout: "30"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Disable HTTP/2 for a listener

Annotation: Multiple annotations are used, as shown in the following table.

This feature is available only for HTTPS listeners.

Annotation	Description	Default	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Use a comma (,) to separate multiple values, for example, `https:443,http:80`.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	The certificate ID on Alibaba Cloud. Log on to the CLB console and find the certificate ID on the Certificates page. Note To create a certificate, see Select an Alibaba Cloud-issued certificate.	None	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-http2-enabled	Enables or disables the HTTP/2 feature. Valid values: `on` `off`	on	v2.1.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "https:443"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id: "${YOUR_CERT_ID}"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-http2-enabled: "off"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Request timeout for a listener

Annotations: The required annotations are listed in the following table.

This feature supports only listeners that use the HTTP or HTTPS protocol.

Annotation

Description

Default

Supported CCM version

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port

Separate multiple values with a comma, for example, https:443,http:80.

None

v1.9.3 and later

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-request-timeout

Specifies the request timeout in seconds. The value must be between 1 and 180.

If a backend server does not respond within the specified timeout, the load balancer returns an HTTP 504 error to the client.

v2.3.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "http:80"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-request-timeout: "60"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Specify connection timeout

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-established-timeout

Only TCP listeners are supported.

Description	Default	Supported CCM version
Specifies the connection timeout in seconds. The value must be an integer from 10 to 900. CreateLoadBalancerTCPListener.	None	v2.3.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-established-timeout: "60"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Configure a listener security policy

Annotations: See the table below for the required annotations.

Only the HTTPS protocol is supported.

Annotation	Description	Default	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with a comma, for example, `https:443,http:80`.	None	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	Specifies the ID of an Alibaba Cloud certificate. In the SLB console, find the certificate ID on the Certificates page. Note To create a certificate, see Select an Alibaba Cloud-issued certificate.	None	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-tls-cipher-policy	Specifies the security policy, which determines the TLS protocol versions and supported cipher suites for an HTTPS listener. CreateLoadBalancerHTTPSListener. Valid values: `tls_cipher_policy_1_0` `tls_cipher_policy_1_1` `tls_cipher_policy_1_2` `tls_cipher_policy_1_2_strict` `tls_cipher_policy_1_2_strict_with_1_3`	tls_cipher_policy_1_0	v2.4.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "https:443,http:80"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id: "${YOUR_CERT_ID}"
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-tls-cipher-policy: "tls_cipher_policy_1_2"
  name: nginx
  namespace: default
spec:
  ports:
  - name: https
    port: 443
    protocol: TCP
    targetPort: 443
  - name: http
    port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Configure TCP and UDP

apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: default
spec:
  ports:
  - name: tcp
    port: 80
    protocol: TCP
    targetPort: 80
  - name: udp
    port: 80
    protocol: UDP
    targetPort: 81
  selector:
    app: nginx
  sessionAffinity: None
  type: LoadBalancer

Configure Proxy Protocol for TCP and UDP listeners

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-proxy-protocol

Description

Default

Supported versions

Enables Proxy Protocol for TCP and UDP listeners. When enabled, the load balancer passes the client source address to backend servers. Valid values:

on
off

Important

This feature does not support seamless migration. Enabling or disabling Proxy Protocol requires a service upgrade, causing a service interruption. Configure this setting with caution.

off

v2.6.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-proxy-protocol: "on"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Backend server group operations

Reuse an existing virtual server group

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port. This annotation enables you to reuse an existing virtual server group. It applies only when you reuse an existing CLB instance. For a detailed example, see Deploy Services across clusters by reusing an existing load balancer.

Set Service traffic weight

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight

When multiple Services reuse the same CLB instance, use this annotation to set the traffic weight for the current Service. This setting applies only when you reuse an existing virtual server group. For a detailed example, see Deploy Services across clusters by reusing an existing load balancer.

Skip backend server weight updates

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ignore-weight-update

Description

Supported CCM versions

Skips updating the weights of backend servers in the virtual server group during Service synchronization. This allows you to manually manage backend server weights. Valid values:

on
off

Default value: off

v2.11.1 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ignore-weight-update: "on"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer