How to configure a Classic Load Balancer by using annotations in an ACK cluster - Container Service for Kubernetes

You can use a wide range of load balancing features by adding annotations to a Service YAML file. These annotations allow you to configure Classic Load Balancer (CLB) instances, listeners, and backend server groups.

Index

Category	Feature category	Configuration link
Annotation usage notes
Typical CLB operations	Create an SLB instance	Create an Internet-facing SLB instance Create an internal-facing SLB instance Create a pay-by-bandwidth SLB instance Specify primary and secondary zones when you create an SLB instance Create a pay-by-usage SLB instance Create an IPv6 SLB instance
	Specify an existing instance	Use an existing SLB instance Use an existing SLB instance and forcibly overwrite its existing listeners
	Configure an SLB instance	Specify the SLB instance specification Specify a vSwitch for the SLB instance Specify an IP address for an internal-facing SLB instance Add extra tags to the SLB instance Specify a name for the SLB instance Specify the resource group for the SLB instance Set a hostname for the Service
	Enable instance protection	Enable deletion protection for the SLB instance Enable configuration read-only mode for the SLB instance Retain the auto-created SLB instance when the Service is deleted
Typical listener operations	Session persistence settings	Configure the session persistence timeout for a TCP listener Configure session persistence (insert cookie) for HTTP and HTTPS listeners
	Port and protocol configuration	Specify a forwarding port for the SLB instance Create a listener with health checks Create a UDP listener Create an HTTP listener Create an HTTPS listener Configure TCP and UDP protocols for the listener at the same time Configure the Proxy Protocol for TCP and UDP listeners
	Advanced configuration	Set the scheduling algorithm for the SLB instance Configure an access control policy group for the SLB instance Configure a security policy for the listener Configure connection draining for the listener Configure extra request headers for the listener Set the idle connection timeout for the listener Specify the request timeout for the listener Specify the connection timeout for the listener Disable the HTTP/2 feature for the listener
Typical backend server group operations	Configuration management	Use worker nodes with a specific label as backend servers Use the nodes where pods reside as backend servers Remove unschedulable nodes from the backend server group of the CLB instance Directly attach pod ENIs to the backend of the CLB instance Reuse an existing vServer group Set the weight of the Service to receive traffic Ignore backend server weight updates
References

Annotation usage notes

Annotations are case-sensitive.
Before you use an annotation, check the supported Cloud Controller Manager (CCM) versions for the feature. To upgrade the CCM component, see Manage components. For more information about the change history of the CCM component, see Cloud Controller Manager.
Since September 11, 2019, alicloud in the annotations field has been 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. You do not need to make any changes.

Typical CLB operations

Create an Internet-facing SLB instance

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

Create an internal-facing SLB instance

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

Description

Supported CCM versions

Specifies the address type of the SLB instance. Valid values:

internet: The Service is accessed over the Internet. The Address Type of the CLB instance must be Public.
intranet: The Service is accessed over a private network. The Address Type of the CLB instance must be Private.

Default value: 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 the SLB instance specification

Annotation: Multiple annotations are available, as described in the following table.

Annotation

Description

Supported CCM versions

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

The billing method of the instance. Valid values:

PayBySpec: pay-by-specification.
PayByCLCU: pay-by-LCU.

Default value: PayBySpec

Important

For Cloud Controller Manager v2.5.0 and later, the default value is changed to PayByCLCU.
You cannot specify a specification for a pay-by-LCU SLB instance. The PayByCLCU value cannot be used with the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec annotation.

v2.4.0 and later

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

The specification of the SLB instance. You can use this parameter to create a CLB instance of a specific specification or update the specification of an existing CLB instance. Valid values:

slb.s1.small
slb.s2.small
slb.s2.medium
slb.s3.small
slb.s3.medium
slb.s3.large

Default value: slb.s1.small

For more information about the valid values of this parameter, see CreateLoadBalancer.

Important

If you modify the specification of a CLB instance in the CLB console, the specification may be changed back to the original one by CCM. This applies only to pay-by-specification CLB instances. Proceed with caution.

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 SLB instance

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

Description

Supported CCM versions

Important

To prevent unexpected behavior such as cluster unavailability or traffic interruptions, do not reuse the API Server CLB instance or a CLB instance created by CCM. Manually create a new instance in the Classic Load Balancer (CLB) console.

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

By default, using an existing SLB 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 configuration overwrites only the listeners of the current Service and does not affect other listeners.
Note
Reusing an existing SLB instance does not overwrite its existing listeners by default for the following two reasons:
- If services are bound to the listeners of the existing SLB instance, a forced overwrite may cause service interruptions.
- CCM supports limited backend configurations and cannot process complex configurations. If you have complex backend configuration requirements, you can configure listeners in the console without overwriting them.
For these reasons, we recommend that you do not forcibly overwrite listeners. You can forcibly overwrite listeners if the listener ports of the existing SLB instance are no longer in use.
For CCM versions earlier than v2.10.0, you cannot add extra tags when you use an existing SLB instance (annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags).

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}"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Use an existing SLB instance and forcibly overwrite its existing listeners

Annotation: Multiple annotations are available, as described in the following table. These annotations forcibly overwrite existing listeners. If a listener port conflicts, the existing listener is deleted.

Annotation

Description

Supported CCM versions

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

Important

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

By default, using an existing SLB 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 configuration overwrites only the listeners of the current Service and does not affect other listeners.
Note
Reusing an existing SLB instance does not overwrite its existing listeners by default for the following two reasons:
- If services are bound to the listeners of the existing SLB instance, a forced overwrite may cause service interruptions.
- CCM supports limited backend configurations and cannot process complex configurations. If you have complex backend configuration requirements, you can configure listeners in the console without overwriting them.
For these reasons, we recommend that you do not forcibly overwrite listeners. You can forcibly overwrite listeners if the listener ports of the existing SLB instance are no longer in use.
For CCM versions earlier than v2.10.0, you cannot add extra tags when you use an existing SLB instance (annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags).

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

Specifies whether to forcibly overwrite the listeners of the CLB instance when you use an existing SLB instance. Valid values:

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

Default value: "false"

Important

When you reuse an existing CLB instance and set force-override to "true", do not allow multiple Services to reuse the same listener of the CLB instance. Otherwise, listener configuration conflicts may occur.

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 secondary zones when you create an SLB instance

Annotation: Multiple annotations are available, as described in the following table. After an SLB instance is created, you cannot change its primary and secondary zones.

Some regions do not support primary and secondary zones for SLB instances. For more information, see the CLB instance creation page.

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-master-zoneid	The ID of the primary zone where the backend servers are deployed.	v1.9.3.10-gfb99107-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-slave-zoneid	The ID of the secondary zone where the backend servers are deployed.	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 SLB instance

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

Annotation

Description

Supported CCM versions

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

The billing method of the SLB instance. Valid values:

paybytraffic
paybybandwidth

Default value: paybytraffic

v1.9.3 and later

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

The bandwidth of the SLB instance. This is the peak bandwidth. The default value is 50. This parameter applies only to Internet-facing SLB instances. For more information about other limits, see Modify the billing method of an Internet-facing SLB 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 the SLB instance

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

Annotation

Description

Supported CCM versions

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

Specifies the address type of the SLB instance. Valid values:

internet: The Service is accessed over the Internet. The Address Type of the CLB instance must be Public.
intranet: The Service is accessed over a private network. The Address Type of the CLB instance must be Private.

Default value: internet

v1.9.3 and later

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

The ID of the vSwitch to which the SLB instance belongs. The vSwitch must belong to the same virtual private cloud (VPC) as the Kubernetes cluster.

When you set this parameter, you must also set service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type to "intranet".

You can log on to the VPC console to query vSwitch IDs.

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 an internal-facing SLB instance

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

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type	Specifies the address type of the SLB instance. Valid values: `internet`: The Service is accessed over the Internet. This is the default value. The Address Type of the CLB instance must be Public. `intranet`: The Service is accessed over a private network. The Address Type of the CLB instance must be Private. Default value: `internet`	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id	The ID of the vSwitch to which the SLB instance belongs. The vSwitch must belong to the same VPC as the Kubernetes cluster. When you set this parameter, you must also set `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type` to intranet. You can log on to the VPC console to query vSwitch IDs.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip	The IP address of the internal-facing SLB instance. The IP address must be within the destination CIDR block of the vSwitch. Only IPv4 addresses are supported. This annotation must be used with `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id`. You cannot change the IP address after it is created.	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 extra tags to the SLB instance

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

Description	Supported CCM versions
The list of tags to add. Separate multiple tags with commas (,), for example, `"k1=v1,k2=v2"`. For CCM v2.10.0 and later, you can modify the tags of created instances and reused instances. Important After you add this annotation to a Service to specify extra tags, additional modifications to the tags of the corresponding SLB instance in the console may be overwritten.	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 SLB instance

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

Description

Supported CCM versions

The IP version of the SLB instance. You cannot change the IP version after the instance is created. When you use this annotation, the kube-proxy mode of the cluster must be IPVS. Valid values:

ipv4: IPv4.
ipv6: IPv6. The generated IPv6 address can be accessed only in an IPv6 environment.

Default value: 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 the SLB instance

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

Description

Supported CCM versions

The deletion protection feature for the SLB instance. Valid values:

on
off

Default value: on

Important

For an SLB instance created for a LoadBalancer Service, if you manually enable deletion protection in the CLB console, you can still run the kubectl delete svc {your-svc-name} command to delete the SLB instance associated with the Service.

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 configuration read-only mode for the SLB instance

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

Description

Supported CCM versions

The configuration read-only mode for the SLB instance. Valid values:

ConsoleProtection
NonProtection

Default value: 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 name for the SLB instance

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

Description	Supported CCM versions
The name of the SLB instance. The name must be 2 to 128 characters in length, start with a letter or a Chinese character, and can contain digits, periods (.), underscores (_), and hyphens (-).	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 the resource group for the SLB instance

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

Description	Supported CCM versions
The ID of the resource group to which the SLB instance belongs. You cannot change the resource group ID after it is specified. You can query resource group IDs on the Alibaba Cloud Resource Management platform.	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 the Service

Annotation: Multiple annotations are available, as described in the following table.

Annotation

Description

Supported CCM versions

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

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

v1.9.3 and later

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

Sets a hostname for the Service. The hostname must follow DNS naming conventions.

Note the following items:

After you add this annotation, the EXTERNAL-IP of the Service changes from the default CLB IP address to your_service_name. When you access the CLB IP address in the cluster, traffic is routed through the CLB instance and then forwarded to the cluster.
After you add this annotation, if the listener protocol is TCP or UDP, a loopback access issue occurs when you access the CLB IP address within the cluster. For more information, see A client cannot access an SLB instance.
Adding this annotation does not automatically associate the CLB instance with a domain name. To do this, go to the domain name service page to purchase a domain name and associate it with the CLB instance. To purchase a domain name, see What is Alibaba Cloud DNS?.

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:30248/TCP,443:32670/TCP   10s

Create a pay-by-usage SLB instance

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

Description

Supported CCM versions

The billing method of the instance. Valid values:

PayBySpec: The default value. pay-by-specification.
PayByCLCU: pay-by-LCU.

Default value: PayBySpec

Important

For Cloud Controller Manager v2.5.0 and later, the default value is changed to PayByCLCU.
You cannot specify a specification for a pay-by-LCU SLB instance. The PayByCLCU value cannot be used with the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec annotation.

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

Retain the auto-created SLB instance when the Service is deleted

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-preserve-lb-on-delete

Description

Supported CCM versions

Retains the CLB instance created for the Service when you delete the LoadBalancer Service, and deletes the kubernetes.do.not.delete and ack.aliyun.com tags from the CLB instance. The existing servers in the vServer group are retained.

When this feature is enabled, a Warning event of the PreservedOnDelete type is generated during Service synchronization. After you configure this annotation, we recommend that you check whether this event exists to confirm that the feature is enabled.

Valid values:

Not empty: enables the retention feature.
Empty or not set: disables the retention feature.

Important

Perform this operation by deleting the Service instead of changing the Service type. Otherwise, the Service may be incorrectly re-associated with the previously retained CLB instance.

v2.10.0 and later

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

Typical listener operations

Configure the session persistence timeout for a TCP listener

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

Description

Supported CCM versions

The session persistence timeout period. This applies only to TCP listeners. If the SLB instance has multiple TCP listeners, this configuration is applied to all of them by default.

Unit: seconds. Valid values: 0 to 3600. Default value: 0. A value of 0 disables session persistence. For more information, see 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 session persistence (insert cookie) for HTTP and HTTPS listeners

Annotation: Multiple annotations are available, as described in the following table. When you insert a cookie, the following four annotations are required.

This feature is supported only by SLB instances that use the HTTP or HTTPS protocols.
If you configure multiple HTTP or HTTPS listeners, this session persistence configuration is applied to all of them by default.

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session	Specifies whether to enable session persistence. This applies only to HTTP and HTTPS listeners. Valid values: `on` `off` Default value: `off` For more information, see CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session-type	The method to process cookies. This applies only to HTTP and HTTPS listeners. This parameter is required when `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session` is set to `on`. Valid values: `insert`: insert cookie. `server`: rewrite cookie. For more information, see CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cookie-timeout	The cookie timeout period. This parameter 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`. Unit: seconds. Valid values: 1 to 86400. For more information, see CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cookie	The name of the cookie configured on the server. The name must be 1 to 200 characters in length and can contain only ASCII letters and digits. It cannot contain commas (,), semicolons (;), or spaces. It cannot start with a dollar sign ($). This parameter 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`. For more information, see CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with commas (,), for example, `https:443,http:80`.	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 policy group for the SLB instance

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

Before you use this annotation to create an SLB instance with access control, you must create an access control policy group in the Classic Load Balancer (CLB) console and record its ID (acl-id).

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-status	Specifies whether to enable access control. Valid values: `on` `off` Default value: `off`	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-id	The ID of the access control policy group that is bound to the listener. This parameter is required when `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-status` is set to `"on"`.	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-type	The type of the access control policy. Valid values: `white`: a whitelist. Only requests from the IP addresses or CIDR blocks in the selected access control policy group are forwarded. Whitelists are suitable for scenarios where an application allows access only from specific IP addresses. Setting a whitelist poses some business risks. After a whitelist is set, only the IP addresses in the whitelist can access the SLB listener. If you enable a whitelist but do not add any IP addresses to the access control policy group, the SLB listener forwards all requests. `black`: a blacklist. All requests from the IP addresses or CIDR blocks in the selected access control policy group are not forwarded. Blacklists are suitable for scenarios where an application restricts access from specific IP addresses. If you enable a blacklist but do not add any IP addresses to the access control policy group, the SLB listener forwards all requests. This parameter is required when the AclStatus parameter is set to on.	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}" # You cannot configure multiple policy groups.
    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

Specify a forwarding port for the SLB instance

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

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

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with commas (,), for example, `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	The ID of the certificate on Alibaba Cloud. 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.	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-forward-port	Forwards HTTP requests to a specified HTTPS port, for example, `80:443`.	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

Set the scheduling algorithm for the SLB instance

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

Description

Supported CCM versions

The scheduling algorithm. Valid values:

wrr: weighted round-robin. Backend servers with higher weights receive more requests.
rr: round-robin. External requests are sequentially distributed to backend servers.
sch: source IP hash. Requests from the same source IP address are scheduled to the same backend server.
tch: four-element hash (source IP address + destination IP address + source port + destination port). Requests from the same stream are scheduled to the same backend server.

Default value: rr.

For more information about the valid values of this parameter, see the Scheduler field in the API documentation for creating the corresponding listener type, such as Create a TCP listener.

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	Supported CCM versions
Separate multiple values with commas (,), for example, `https:443,http:80`.	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: Multiple annotations are available, as described in the following table.

HTTPS requests are decrypted at the CLB layer and then sent to the backend pods as HTTP requests.

Annotation

Description

Supported CCM versions

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

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

v1.9.3 and later

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

The ID of the certificate on Alibaba Cloud.

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.

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 health checks

Set up a TCP health check

Annotation: Multiple annotations are available, as described in the following table. All of the following annotations are required.

Health checks are enabled by default for TCP ports.

Annotation	Description	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` Default value: `on`	v2.6.0 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type	The health check type. Valid values: `tcp` `http` Default value: `tcp`. For more information, see CreateLoadBalancerTCPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout	The period of time to wait for a response from a health check. This applies to TCP health checks. If a backend ECS instance does not respond within the specified 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-connect-timeout` is less than the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval`, the former is invalid and the timeout period is the value of the latter. The default value is 5. For more information, see CreateLoadBalancerTCPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold	The number of consecutive successful health checks required to change the health check status of a backend server from `fail` to `success`. Valid values: 2 to 10. Default value: 3. For more information, see CreateLoadBalancerTCPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold	The number of consecutive failed health checks required to change the health check status of a backend server from success to fail. Valid values: 2 to 10. Default value: 3. For more information, see CreateLoadBalancerTCPListener.	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. Default value: 2. For more information, see CreateLoadBalancerTCPListener.	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

Set up a UDP health check

Annotation: Multiple annotations are available, as described in the following table. All of the following annotations are required.

Health checks are enabled by default for UDP ports.

Annotation	Description	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` Default value: `on`	v2.6.0 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout	The period of time to wait for a response from a health check. This applies to TCP health checks. If a backend ECS instance does not respond within the specified 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-connect-timeout` is less than the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval`, the former is invalid and the timeout period is the value of the latter. The default value is 5. For more information, see CreateLoadBalancerUDPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold	The number of consecutive successful health checks required to change the health check status of a backend server from fail to success. Valid values: 2 to 10. Default value: 3. For more information, see CreateLoadBalancerUDPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold	The number of consecutive failed health checks required to change the health check status of a backend server from success to fail. Valid values: 2 to 10. Default value: 3. For more information, see CreateLoadBalancerUDPListener.	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. Default value: 2. For more information, see CreateLoadBalancerUDPListener.	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 listeners

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

Description

Supported CCM versions

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

on
off

Default value: on

v2.6.0 and later

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

Set up an HTTP health check

Annotation: Multiple annotations are available, as described in the following table.

Annotation	Description	Supported CCM versions
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. You do not need to change this annotation parameter for TCP. `off`: The default value for HTTP listeners is `off`. Default value: `off`	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type	The health check type. Valid values: `tcp` `http` Default value: `tcp` For more information, see CreateLoadBalancerHTTPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-uri	The URI for health checks. You do not need to configure this annotation parameter for TCP health checks.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-httpcode	The HTTP status code that indicates a successful health check. Separate multiple status codes with commas (,). Valid values: `http_2xx` `http_3xx` `http_4xx` `http_5xx` Default value: `http_2xx` For more information, see CreateLoadBalancerHTTPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-domain	The domain name for health checks. Valid values: `$_ip`: the private IP address of the backend server. If you specify an IP address or do not specify this parameter, the SLB instance uses the private IP address of each backend server as the domain name for health checks. `domain`: The domain name must be 1 to 80 characters in length and can contain letters, digits, periods (.), and hyphens (-). For more information, see CreateLoadBalancerHTTPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout	The period of time to wait for a response from a health check. This applies to HTTP health checks. If a backend ECS instance does not respond within the specified 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, the `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout` annotation is invalid and the timeout period is the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval`. For more information, see CreateLoadBalancerHTTPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold	The number of consecutive successful health checks required to change the health check status of a backend server from fail to success. Valid values: 2 to 10. Default value: 3. For more information, see CreateLoadBalancerHTTPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold	The number of consecutive failed health checks required to change the health check status of a backend server from success to fail. Valid values: 2 to 10. Default value: 3. For more information, see CreateLoadBalancerHTTPListener.	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. Default value: 2. For more information, see CreateLoadBalancerHTTPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with commas (,), for example, `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-method	The health check method for HTTP listeners. Valid values: `head` `get`	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"
    # Optional. Set the HTTP status code for the health check.
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-httpcode: "http_4xx"
    # Optional. Set the domain name for the health check.
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-domain: "www.aliyun.com"
    # Optional. Set the method for the health check.
    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

Configure connection draining for the listener

Annotation: Multiple annotations are available, as described in the following table. All of the following annotations are required.

This feature is supported only by the TCP and UDP protocols.

Annotation

Description

Supported CCM versions

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

Specifies whether to enable connection draining. Valid values:

on
off

v2.0.1 and later

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

The connection draining timeout period. Unit: seconds. Valid values: 10 to 900.

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 extra request headers for the listener

Annotation: Multiple annotations are available, as described in the following table.

This feature is supported only by the HTTP and HTTPS protocols.

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with commas (,), for example, `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-proto	Specifies whether to use the X-Forwarded-Proto header to retrieve the listener protocol of the CLB instance. Valid values: `on` `off` Default value: `off`	v2.1.0 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-slbport	Specifies whether to use the X-Forwarded-For-SLBPORT header to retrieve the listener port of the SLB instance. Valid values: `on` `off` Default value: `off`	v2.9.1 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-clientsrcport	Specifies whether to use the X-Forwarded-For-ClientSrcPort header to retrieve the port of the client that accesses the SLB instance. Valid values: `on` `off` Default value: `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 the idle connection timeout for the listener

Annotation: Multiple annotations are available, as described in the following table.

This feature is supported only by the HTTP and HTTPS protocols.

Annotation

Description

Supported CCM versions

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

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

v1.9.3 and later

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

The idle connection timeout period for the listener. Unit: seconds. Valid values: 1 to 60.

Default value: 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 the HTTP/2 feature for the listener

Annotation: Multiple annotations are available, as described in the following table.

This feature is supported only by the HTTPS protocol.

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with commas (,), for example, `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	The ID of the certificate on Alibaba Cloud. 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.	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-http2-enabled	Specifies whether to enable the HTTP/2 feature. Valid values: `on` `off` Default value: `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

Specify the request timeout for the listener

Annotation: Multiple annotations are available, as described in the following table.

This feature is supported only by the HTTP and HTTPS protocols.

Annotation

Description

Supported CCM versions

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

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

v1.9.3 and later

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

The request timeout period. Unit: seconds. Valid values: 1 to 180. Default value: 60

If a backend server does not respond within the timeout period, the SLB instance stops waiting and returns an HTTP 504 error code 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 the connection timeout for the listener

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

This feature is supported only by the TCP protocol.

Description	Supported CCM versions
The connection timeout period. Unit: seconds. Valid values: 10 to 900. For more information, see CreateLoadBalancerTCPListener.	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 security policy for the listener

Annotation: Multiple annotations are available, as described in the following table.

This feature is supported only by the HTTPS protocol.

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with commas (,), for example, `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	The ID of the certificate on Alibaba Cloud. 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.	v1.9.3.164-g2105d2e-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-tls-cipher-policy	A security policy includes the TLS protocol versions and cipher suites that are available for HTTPS. For more information, see 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` Default value: `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 protocols for the listener at the same time

Note

This feature requires a Kubernetes cluster of v1.24 or later. For more information about how to upgrade a cluster, see Upgrade an ACK cluster.

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 the Proxy Protocol for TCP and UDP listeners

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

Description

Supported CCM versions

Configures the Proxy Protocol for TCP and UDP listeners. After you configure the Proxy Protocol, you can use it to carry the source IP address of the client to the backend server. Valid values:

on
off

Default value: off

Important

This feature does not support smooth online migration. Switching the Proxy Protocol requires a service upgrade with downtime. Configure this with caution.

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

Typical backend server group operations

Use worker nodes with a specific label as backend servers

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

Description	Supported CCM versions
Specifies the worker nodes to attach to the backend of the CLB instance. You can specify the worker nodes using labels. Separate multiple labels with commas (,), for example, `"k1=v1,k2=v2"`. Multiple labels have a logical AND relationship.	v1.9.3 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-backend-label: "failure-domain.beta.kubernetes.io/zone=ap-southeast-5a"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer

Use the nodes where pods reside as backend servers

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

By default, externalTrafficPolicy is set to Cluster mode. This attaches all nodes in the cluster to the backend server group. Local mode attaches only the nodes where the pods reside as backend servers.

Description

Supported CCM versions

The scheduling algorithm. Valid values:

wrr: weighted round-robin. Backend servers with higher weights receive more requests.
In Local mode, you must set the scheduling policy to weighted round-robin (wrr).
Note
For CCM v1.9.3.164-g2105d2e-aliyun and later, if the external traffic policy is set to Local mode, the weights of the nodes are automatically set based on the number of pods on the nodes. For more information about the weight calculation rule, see How are node weights automatically set in Local mode?.
rr: round-robin. External requests are sequentially distributed to backend servers.

Default value: rr

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:
  externalTrafficPolicy: Local
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Remove unschedulable nodes from the backend server group of the CLB instance

Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-remove-unscheduled-backend

Description

Supported CCM versions

Removes SchedulingDisabled nodes from the backend server group of the CLB instance. Valid values:

on: removes nodes in the unschedulable state from the backend server group of the CLB instance.
off: The kubectl cordon and kubectl drain commands set nodes to the unschedulable state. In this case, nodes in the unschedulable state are not removed from the backend server group of the CLB instance.

Default value: off

v1.9.3.164-g2105d2e-aliyun and later

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

Directly attach pod ENIs to the backend of the CLB instance

Annotation: service.beta.kubernetes.io/backend-type

Description

Default value

Supported CCM versions

The type of backend server for the CLB instance. Valid values:

eni: Use this value to attach pods to the backend of the CLB instance. This improves network forwarding performance. This value is valid only in Terway network mode.
You can also manually change eni to ecs in service.beta.kubernetes.io/backend-type: "eni" to attach ECS instances to the backend of the CLB instance.
ecs: attaches ECS instances to the backend of the CLB instance.

Flannel network mode: ecs
Terway network mode:
- Terway clusters created before August 10, 2020: ecs
- Terway clusters created after August 10, 2020: eni

v1.9.3.164-g2105d2e-aliyun and later

  apiVersion: v1
  kind: Service
  metadata:
    annotations:
      service.beta.kubernetes.io/backend-type: "eni"
    name: nginx
  spec:
    ports:
    - name: http
      port: 30080
      protocol: TCP
      targetPort: 80
    selector:
      app: nginx
    type: LoadBalancer

Reuse an existing vServer group

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

You can reuse an existing vServer group. This feature is applicable only when you reuse an existing CLB instance. For a usage example, see Deploy services across clusters by reusing an SLB instance.

Set the weight of the Service to receive traffic

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

When multiple Services reuse the same CLB instance, you can use this annotation to set the weight of the current Service to receive traffic. This annotation is applicable only when you reuse an existing vServer group. For a usage example, see Deploy services across clusters by reusing an SLB instance.

Ignore backend server weight updates

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

Description

Supported CCM versions

Skips the update of backend server weights in the vServer group during Service synchronization. This configuration is suitable for scenarios where you need to manually manage backend server weights using a mechanism other than CCM. 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