How to configure a Classic Load Balancer (CLB) instance for an ACK cluster by using annotations - Container Service for Kubernetes

You can use annotations in a Service YAML file to configure resources such as SLB instances, listeners, and backend server groups to use a wide range of load balancing features.

Index

Category	Feature category	Configuration link
Annotation usage notes
Typical operations for CLB instances	Create an SLB instance	Create an Internet-facing SLB instance Create an internal-facing SLB instance Create a pay-by-bandwidth SLB instance Specify the primary and secondary zones when you create an SLB instance Create a pay-as-you-go SLB instance Create an IPv6 SLB instance
	Specify an existing instance	Use an existing SLB instance Use an existing SLB instance and forcibly overwrite existing listeners
	Configure an SLB instance	Specify the specification of an SLB instance Specify a vSwitch for an SLB instance Specify an IP address for an internal-facing SLB instance Add extra tags to an SLB instance Specify the name of an SLB instance Specify the resource group of an SLB instance Set a hostname for a Service
	Enable instance protection	Enable deletion protection for an SLB instance Enable configuration read-only mode for an SLB instance Retain an auto-created SLB instance when you delete a Service
Typical operations for listeners	Session persistence settings	Configure the session persistence timeout period for a TCP listener Configure session persistence (insert cookie) for HTTP and HTTPS listeners
	Port and protocol configuration	Specify a forwarding port for an SLB instance Create a listener with a health check Create a UDP listener Create an HTTP listener Create an HTTPS listener Configure TCP and UDP protocols for a listener at the same time Configure the Proxy Protocol for TCP and UDP listeners
	Advanced configuration	Set the scheduling algorithm for an SLB instance Configure an access control policy group for an SLB instance Configure a security policy for a listener Enable connection draining for a listener Configure extra request headers for a listener Set the idle connection timeout period for a listener Specify the request timeout period for a listener Specify the connection timeout period for a listener Disable the HTTP/2 feature for a listener
Typical operations for backend server groups	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 a CLB instance Directly attach Pod ENIs to the backend of a CLB instance Reuse an existing vServer group Set the weight of a 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) version for the feature. To upgrade the CCM component, see Manage components. For the change history of the CCM component, see Cloud Controller Manager.
As of September 11, 2019, alicloud in the annotations field 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. You do not need to make any changes.

Typical operations for CLB instances

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 that the SLB instance is an internal-facing instance. Valid values:

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

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 specification of an SLB instance

Annotation: Multiple. See the table below.

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

If the Cloud Controller Manager version is v2.5.0 or later, the default value is changed to PayByCLCU.
Pay-by-LCU SLB instances do not support specifications. This means that you cannot set the value to PayByCLCU and specify the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec annotation at the same time.

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 reverted to the original one by CCM. This operation is supported only for pay-by-specification 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 behaviors such as cluster unavailability or traffic interruption, 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 existing listeners by default for the following 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 some complex configurations. If you have complex backend configuration requirements, you can configure listeners in the console without overwriting them.
For these reasons, do not forcibly overwrite listeners unless the listener ports of the existing SLB instance are no longer in use.
(For versions earlier than v2.10.0) When you use an existing SLB instance, you cannot add extra tags (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 existing listeners

Annotation: This operation uses the annotations described in the following table. It forcibly overwrites existing listeners. If a listener port conflict occurs, 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 existing listeners by default for the following 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 some complex configurations. If you have complex backend configuration requirements, you can configure listeners in the console without overwriting them.
For these reasons, do not forcibly overwrite listeners unless the listener ports of the existing SLB instance are no longer in use.
(For versions earlier than v2.10.0) When you use an existing SLB instance, you cannot add extra tags (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 bind 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.

Default value: "false"

Important

When you reuse a CLB instance and set force-override to "true", do not let multiple Services 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 the primary and secondary zones when you create an SLB instance

Annotation: This operation uses the annotations described in the following table. After the primary and secondary zones are specified, they cannot be modified.

SLB instances in some regions do not support primary and secondary zones. The information on the SLB instance creation page takes precedence.

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-master-zoneid	The ID of the zone where the primary 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 zone where the secondary 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 supported, as shown in the table below. 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 Change the metering 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 an SLB instance

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

Annotation

Description

Supported CCM versions

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

Specifies that the SLB instance is an internal-facing instance. Valid values:

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

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 the vSwitch ID.

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: The following table lists the annotations that you can specify. Three of these annotations are required.

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type	Specifies that the SLB instance is an internal-facing 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 Internet. `intranet`: The service is accessed over a private network. The Address Type of the CLB instance must be Internal. 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 the vSwitch ID.	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 parameter must be used together with `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id`. The IP address cannot be changed after it is specified.	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 an SLB instance

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

Description	Supported CCM versions
The list of tags that you want 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, 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. The IP version cannot be changed after the instance is created. To use this feature, you must set the kube-proxy mode of the cluster to 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 an SLB instance

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

Description

Supported CCM versions

Deletion protection for the SLB instance. Valid values:

on
off

Default value: on

Important

For an SLB instance created for a Service of the LoadBalancer type, even if you manually enable deletion protection in the CLB console, you can still delete the SLB instance associated with the Service 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 configuration read-only mode for an SLB instance

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

Description

Supported CCM versions

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 the name of an 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 of an 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. The resource group ID cannot be modified after it is specified. You can query the resource group ID 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 a Service

Annotation: Multiple. For more information, see 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 is changed from the default CLB IP address to your_service_name. When you access the CLB IP address within 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 fails to access an SLB instance.
Adding this annotation does not automatically associate the CLB instance with a domain name. To associate them, go to the domain name service page to purchase a domain name and then 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-as-you-go 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. This specifies the pay-by-specification billing method.
PayByCLCU: pay-by-LCU.

Default value: PayBySpec

Important

If the Cloud Controller Manager version is v2.5.0 or later, the default value is changed to PayByCLCU.
Pay-by-LCU SLB instances do not support specifications. This means that you cannot set the value to PayByCLCU and specify the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec annotation at the same time.

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 an auto-created SLB instance when you delete a Service

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

Description

Supported CCM versions

When you delete a Service of the LoadBalancer type, the CLB instance created for the Service is retained, and the kubernetes.do.not.delete and ack.aliyun.com tags are removed 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, check whether this event exists to confirm that the feature is enabled.

Value:

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 operations for listeners

Configure the session persistence timeout period for a TCP listener

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

Description

Supported CCM versions

The session persistence timeout period. This parameter applies only to TCP listeners. If the SLB instance is configured with multiple TCP listener ports, this configuration is applied to all TCP listeners by default.

Unit: seconds. The value must be an integer from 0 to 3600. 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: This operation uses the annotations described in the following table. To insert a cookie, the following four annotations are required.

This feature is supported only for HTTP and HTTPS listeners.
If you configure multiple HTTP or HTTPS listener ports, this session persistence configuration is applied to all HTTP and HTTPS listeners by default.

Annotation	Description	Supported CCM versions
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session	Specifies whether to enable session persistence. This parameter takes effect only for 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 used to process cookies. This parameter takes effect only for 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`: inserts a cookie. `server`: rewrites a 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 cookie 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 an SLB instance

Annotations: Multiple annotations are supported and described in the following table. The following three annotations are required.

Before you use this annotation to create an SLB instance with access control enabled, 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 in which an application allows access only from specific IP addresses. Using a whitelist poses risks to your services. After a whitelist is configured, only 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 denied. Blacklists are suitable for scenarios in which an application denies 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 an SLB instance

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

Annotation: The annotations described in the following table are supported. 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 Certificate Management 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	Redirects 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 an 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 than backend servers with lower weights.
rr: round-robin. Requests are distributed to backend servers in sequence.
sch: source IP hashing. Requests from the same source IP address are distributed to the same backend server.
tch: four-element hashing. Requests from the same stream (based on source IP address, destination IP address, source port, and destination port) are distributed 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

Note: Multiple values are supported, as shown in the following table.

HTTPS requests are decrypted at the CLB layer and then forwarded to the backend pod 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 Certificate Management 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 a health check

Set up a TCP health check

Annotation: This operation requires all of the annotations described in the following table.

Health checks are enabled for TCP ports by default.

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 parameter applies to TCP health checks. If a backend ECS instance does not respond within the specified period of time, 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 smaller 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 health check successes 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 health check failures 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 two consecutive 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: This operation requires all of the annotations described in the following table.

Health checks are enabled for UDP ports by default.

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 parameter applies to TCP health checks. If a backend ECS instance does not respond within the specified period of time, 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 smaller 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 health check successes 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 health check failures 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 two consecutive 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" # Disable 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. For more information, see 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 listeners. `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 that is used 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 HTTP 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 that is used for health checks. Valid values: `$_ip`: the private IP address of a 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 for health checks. `domain`: The domain name must be 1 to 80 characters in length and can contain only 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 parameter applies to HTTP health checks. If a backend ECS instance does not respond within the specified period of time, 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 smaller 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` parameter is invalid and the timeout period is the value of the `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval` parameter. For more information, see CreateLoadBalancerHTTPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold	The number of consecutive health check successes 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 health check failures 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 two consecutive 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 an HTTP listener. 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"
    # Set the HTTP status code for health checks. This parameter is optional.
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-httpcode: "http_4xx"
    # Set the domain name for health checks. This parameter is optional.
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-domain: "www.aliyun.com"
    # Set the health check method. This parameter is 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

Enable connection draining for a listener

Annotation: This operation requires all of the annotations described in the following table.

This feature is supported only for TCP and UDP.

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 a listener

Note: Multiple values are supported, as shown in the table below.

This feature is supported only for HTTP and HTTPS.

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 period for a listener

Annotation: Multiple. For more information, see the following table.

This feature is supported only for HTTP and HTTPS.

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 a listener

Annotation: Multiple. For more information, see the following table.

This feature is supported only for HTTPS.

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 Certificate Management 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 HTTP/2. 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 period for a listener

Annotation: Multiple. For more information, see the following table.

This feature is supported only for HTTP and HTTPS.

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 period for a listener

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

This feature is supported only for TCP.

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 a listener

Annotation: Multiple values are supported. For more information, see the following table.

This feature is supported only for HTTPS.

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 Certificate Management 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 contains the optional TLS versions and supported cipher suites 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 a listener at the same time

Note

This feature requires your Kubernetes cluster to be v1.24 or later. For more information, see Update the Kubernetes version of 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 the Proxy Protocol is configured, you can use it to pass the source IP address of a client to backend servers. Valid values:

on
off

Default value: off

Important

This feature does not support smooth migration. To switch the Proxy Protocol, you must stop your services for the upgrade. Proceed 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 operations for backend server groups

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 that you want to attach to the backend of a CLB instance using labels. Separate multiple labels with commas (,), for example, `"k1=v1,k2=v2"`. Multiple labels have an 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, which 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 than backend servers with lower weights.
In Local mode, you must set the scheduling algorithm 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 system automatically sets the weight of a node based on the number of pods on the node. For more information about how the weight is calculated, see How do I automatically set the weight of a node in Local mode?.
rr: round-robin. Requests are distributed to backend servers in sequence.

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 a 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 a CLB instance. Valid values:

on: removes unschedulable nodes from the backend server group of the CLB instance.
off: The kubectl cordon and kubectl drain commands set the status of a node to unschedulable. In this case, unschedulable nodes 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 a 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: Attach pods to the backend of the CLB instance to improve network forwarding performance. This feature is available only in Terway network mode.
You can also manually set eni in service.beta.kubernetes.io/backend-type: "eni" to ecs to attach ECS to the CLB backend.
ecs: Attach 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 available only when you reuse an existing SLB instance. For more information and an example, see Deploy services across clusters by reusing an SLB instance.

Set the weight of a Service to receive traffic

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

When multiple Services reuse the same SLB instance, you can use this annotation to set the weight of the current Service to control the traffic it receives. This annotation is available only when you reuse an existing vServer group. For more information and an 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