How to configure Classic Load Balancer (CLB) for ACK clusters using annotations-Container Service for Kubernetes(ACK)-阿里云帮助中心

To enable rich load balancing features, configure CLB instances, listeners, and backend server groups by adding annotations to your Service YAML file.

Index

Category	Feature category	Configuration link
Annotation usage notes
Typical CLB operations	Create load balancer	Create an Internet-facing SLB instance Create an internal-facing SLB instance Create a bandwidth-billed SLB instance Specify primary and secondary zones when creating an SLB instance Create a usage-based billed SLB instance Create an IPv6 SLB instance
	Specify existing instance	Use an existing SLB instance Use an existing SLB instance and forcibly override existing listeners
	Configure load balancer	Specify SLB instance specification Specify vSwitch for SLB instance Specify IP address for internal-facing SLB Add additional tags to SLB instance Specify SLB instance name Specify resource group for SLB instance Set hostname for Service
	Enable instance protection	Enable deletion protection for SLB instance Enable configuration read-only mode for SLB instance
Typical listener operations	Session persistence settings	Configure session persistence timeout for TCP SLB Configure session persistence (insert cookie) for HTTP and HTTPS listeners
	Port and protocol configuration	Specify redirection port for SLB Create listener with health check Create UDP listener Create HTTP listener Create HTTPS listener Configure additional domain name certificates for HTTPS listener Configure both TCP and UDP protocols for listener Configure Proxy Protocol for TCP and UDP listeners
	Advanced Configuration	Set scheduling algorithm for SLB Configure access control policy group for SLB Configure security policy for listener Set connection draining for listener Configure additional request headers for listener Set idle connection timeout for listener Set request timeout for listener Set connection timeout for listener Disable HTTP/2 for listener
Typical backend server group operations	Configuration Management	Use worker nodes with specified labels as backend servers Use nodes where pods reside as backend servers Remove unschedulable nodes from CLB backend Mount pod ENIs directly to CLB backend Reuse existing vServer group Set traffic weight for Service Ignore backend server weight updates Set default backend server weight
References

Annotation usage notes

Annotation values are case-sensitive.
Before using annotations, check the supported CCM component version for each feature in this document. To upgrade the CCM component, see Components. For CCM component change records, see Cloud Controller Manager.
Starting September 11, 2019, the prefix for the annotations field changed from alicloud to alibaba-cloud.

Example:

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

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

The system remains compatible with the alicloud prefix. No changes are required.

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 version

Specify the SLB instance as internal-facing. Valid values:

internet: The service is accessible over the public network. The corresponding CLB IP Version must be Internet-facing.
intranet: The service is accessible over the private network. The corresponding CLB IP Version must be Internal-facing.

Default value: internet

See Specify vSwitch for SLB instance to manually specify a vSwitch for the CLB. If not specified, the system automatically selects one based on the CCM version:

Versions earlier than v2.13.0: Use the first vSwitch configured for the cluster control plane by default.
Versions v2.13.0 and later: Automatically select one from all available vSwitches.

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

Annotation: Multiple, as listed in the following table.

Annotation

Description

Supported CCM version

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

Billing method for the instance. Valid values:

PayBySpec: Billed by specification.
PayByCLCU: Billed by usage.

Default value: PayBySpec

Important

For Cloud Controller Manager v2.5.0 and later, the default value changes to PayByCLCU.
Usage-based billed SLB instances do not support setting specifications. Therefore, you cannot specify both PayByCLCU and service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec.

v2.4.0 and later

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

Specification of the SLB instance. Use this parameter to create an SLB instance with a specific specification or update the specification of an existing SLB 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 valid values, see CreateLoadBalancer.

Important

If you modify the SLB specification in the CLB console (only supported for specification-billed SLB instances), CCM might revert it to the original specification. 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 version

Important

To avoid unexpected behaviors such as cluster unavailability or traffic interruption, do not reuse API Server CLB instances or CLB instances created by CCM. Create a new instance manually in the Classic Load Balancer (CLB) console.
Do not add or modify the reuse annotation for an existing LoadBalancer Service. Doing so may cause the reuse to fail or prevent the CCM-created load balancer from being released.

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

By default, reusing an existing SLB instance does not override listeners. To forcibly override existing listeners, set service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners to "true". This setting only affects listeners associated with the current Service and does not impact other listeners.
Note
Reusing an existing SLB does not override existing listeners by default for two reasons:
- If business traffic is bound to existing listeners, forced override may cause service interruption.
- CCM currently supports limited backend configurations and cannot handle complex setups. For complex backend requirements, configure listeners manually in the console without overriding.
Considering these scenarios, we do not recommend forcibly overriding listeners. Only override if the listener ports on the existing SLB are no longer in use.
(Versions earlier than v2.10.0) Reusing an existing SLB does not support adding additional 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 override existing listeners

Annotation: Multiple, as listed in the following table. Forcibly overriding existing listeners deletes conflicting listeners.

Annotation

Description

Supported CCM version

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

Important

To avoid unexpected behaviors such as cluster unavailability or traffic interruption, do not reuse API Server CLB instances or CLB instances created by CCM. Create a new instance manually in the Classic Load Balancer (CLB) console.

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

By default, reusing an existing SLB instance does not override listeners. To forcibly override existing listeners, set service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners to "true". This setting only affects listeners associated with the current Service and does not impact other listeners.
Note
Reusing an existing SLB does not override existing listeners by default for two reasons:
- If business traffic is bound to existing listeners, forced override may cause service interruption.
- CCM currently supports limited backend configurations and cannot handle complex setups. For complex backend requirements, configure listeners manually in the console without overriding.
Considering these scenarios, we do not recommend forcibly overriding listeners. Only override if the listener ports on the existing SLB are no longer in use.
(Versions earlier than v2.10.0) Reusing an existing SLB does not support adding additional tags (annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags).

v1.9.3.81-gca19cd4-aliyun and later

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

When binding to an existing SLB, determines whether to synchronize CLB listener configurations based on the Service.

"true": CCM automatically manages CLB listeners (create, update, delete) associated with the Service without affecting other listeners.
"false": CCM does not process CLB listeners.

Default value: "false"

Important

When reusing an existing CLB and setting force-override to "true", do not have multiple Services reuse the same listener on the same CLB. This causes listener configuration conflicts.

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

Annotation: Multiple, as listed in the following table. Primary and secondary zones cannot be modified after creation.

SLB instances in some regions do not support primary and secondary zones. Refer to the CLB creation page for details.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-master-zoneid	Zone ID of the primary backend server.	v1.9.3.10-gfb99107-aliyun and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-slave-zoneid	Zone ID of the backup backend server.	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 bandwidth-billed SLB instance

Annotation: Multiple, as listed in the following table. Both annotations are required.

Annotation

Description

Supported CCM version

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

Billing method for the SLB instance. Valid values:

paybytraffic
paybybandwidth

Default value: paybytraffic

v1.9.3 and later

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

Bandwidth of the SLB instance, representing peak bandwidth. Default value: 50. Applies only to Internet-facing SLB instances. For other limits, see Modify billing method for 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 vSwitch for SLB instance

Annotation: Multiple, as listed in the following table. Both annotations are required.

Annotation

Description

Supported CCM version

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

Specify the SLB instance as internal-facing. Valid values:

internet: The service is accessible over the public network. The corresponding CLB IP Version must be Internet-facing.
intranet: The service is accessible over the private network. The corresponding CLB IP Version must be Internal-facing.

Default value: internet

v1.9.3 and later

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

VSwitch ID of the SLB instance. The vSwitch must belong to the same VPC as the Kubernetes cluster.

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

Log on to the Virtual Private Cloud 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 IP address for internal-facing SLB

Annotation: Multiple, as listed in the following table. All three annotations are required.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type	Specify the SLB instance as internal-facing. Valid values: `internet`: The service is accessible over the public network. This is the default value. The corresponding CLB IP Version must be Internet-facing. `intranet`: The service is accessible over the private network. The corresponding CLB IP Version must be Internal-facing. Default value: `internet`	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id	VSwitch ID of the SLB instance. The vSwitch must belong to the same VPC as the Kubernetes cluster. When setting this parameter, also set `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type` to intranet. Log on to the Virtual Private Cloud console to query the vSwitch ID.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip	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, and this parameter must be used together with `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id`. The IP address cannot be changed after creation.	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 additional tags to SLB instance

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

Description	Supported CCM version
List of tags to add. Separate multiple tags with English commas (,). Example: `"k1=v1,k2=v2"`. Versions v2.10.0 and later support modifying tags for both newly created and reused instances. Important After adding this annotation to specify additional tags, any manual tag modifications made to 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 version

IP version of the SLB instance. The IP type cannot be changed after creation. When using this feature, ensure the kube-proxy proxy mode of your cluster is IPVS. Valid values:

ipv4: IPv4 type.
ipv6: IPv6 type. The generated IPv6 address is accessible only in IPv6-supported environments.

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

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

Description

Supported CCM version

Deletion protection for SLB instance. Valid values:

on
off

Default value: on

Important

For SLB instances created by LoadBalancer-type Services, even if you manually enable deletion protection in the CLB console, you can still delete the associated SLB instance by running kubectl delete svc {your-svc-name}.

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

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

Description

Supported CCM version

Configuration modification protection for 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 SLB instance name

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

Description	Supported CCM version
Name of the SLB instance. The name must be 2–128 characters long, start with a letter or 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 resource group for SLB instance

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

Description	Supported CCM version
Resource group ID of the SLB instance. Once specified, the resource group ID cannot be modified. Query the resource group ID in the Alibaba Cloud Resource Management console.	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 hostname for Service

Annotation: Multiple, as listed in the following table.

Annotation

Description

Supported CCM version

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

Separate multiple values with English commas (,). Example: https:443,http:80.

v1.9.3 and later

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

Set a hostname for the Service. The hostname must comply with DNS naming rules.

Note the following:

After adding this annotation, the Service's EXTERNAL-IP changes from the default CLB IP to your_service_name. Traffic accessing the CLB IP within the cluster will route through the CLB before forwarding to the cluster.
After adding this annotation, accessing the CLB IP from within the cluster for TCP or UDP listeners causes loopback issues. For details, see Client cannot access CLB.
This annotation does not automatically bind the CLB to a domain name. To bind, purchase a domain name and configure it manually in the Domain Names console. To purchase a domain name, see What is Alibaba Cloud Domain Names?.

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 usage-based billed SLB instance

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

Description

Supported CCM version

Billing method for the instance. Valid values:

PayBySpec: Default value, billed by specification.
PayByCLCU: Billed by usage.

Default value: PayBySpec

Important

For Cloud Controller Manager v2.5.0 and later, the default value changes to PayByCLCU.
Usage-based billed SLB instances do not support setting specifications. Therefore, you cannot specify both PayByCLCU and service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec.

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

Typical listener operations

Configure session persistence timeout for TCP SLB

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

Description

Supported CCM version

Session persistence timeout. Applies only to TCP listeners. If the SLB instance has multiple TCP listeners, this setting applies to all TCP listeners by default.

Unit: seconds. Valid range: [0, 3600]. Default value: 0 (session persistence disabled). 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, as listed in the following table. All four annotations are required when inserting cookies.

Applies only to HTTP and HTTPS SLB instances.
If multiple HTTP or HTTPS listeners are configured, session persistence applies to all HTTP and HTTPS listeners by default.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session	Enable session persistence. 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	Cookie handling method. Applies only to HTTP and HTTPS listeners. 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	Cookie timeout. Required when `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session` is `on` and `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session-type` is `insert`. Unit: seconds. Valid range: [1, 86400]. For more information, see CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cookie	Cookie name configured on the server. Length: 1–200 characters. Can contain only ASCII letters and digits. Cannot contain commas (,), semicolons (;), spaces, or start with a dollar sign ($). Required when `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session` is `on` and `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session-type` is `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 English commas (,). 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 access control policy group for SLB

Annotation: Multiple, as listed in the following table. All three annotations are required.

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

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-status	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	ID of the access control policy group bound to the listener. 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	Access control type. Valid values: `white`: Forward requests only from IP addresses or CIDR blocks in the access control policy group. Whitelisting applies when your application allows access only from specific IPs. Setting a whitelist carries business risks. Once configured, only IPs in the whitelist can access the SLB listener. If the whitelist is empty, the SLB listener forwards all requests. `black`: Requests from IP addresses or CIDR blocks configured in the selected access control policy group will not be forwarded. You can use a blacklist in scenarios in which you want to deny access only from specific IP addresses to an application. If you enable a blacklist but do not add an IP address 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}" # Does not support 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 redirection port for SLB

Port forwarding redirects HTTP requests to HTTPS ports.

Annotation: Multiple, as listed in the following table. All three annotations are required.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with English commas (,). Example: `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	Certificate ID 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	Forward HTTP requests to a specified HTTPS port. 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 scheduling algorithm for SLB

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

Description

Supported CCM version

Scheduling algorithm. Valid values:

wrr: Weighted round-robin. Backend servers with higher weights receive more requests (higher probability).
rr: Round-robin. Distributes external requests sequentially to backend servers.
sch: Consistent hash based on source IP address. Requests from the same source address are scheduled to the same backend server.
tch: Consistent hash based on quadruple (source IP + destination IP + source port + destination port). Requests from the same flow are scheduled to the same backend server.

Default value: rr.

For more valid values, see the Scheduler field in the corresponding listener creation API (such as Create 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 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 HTTP listener

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

Health check: HTTP listener health checks are disabled by default. To ensure backend service availability, configure HTTP or TCP health checks for the listener port.
In-cluster access: When accessing the service via CLB IP from within the cluster, request traffic might be truncated internally, causing access issues. See Set hostname for Service to force traffic through the CLB by adding an annotation. For details, see Notes on accessing LoadBalancer Service External IP from within the cluster.

Description	Supported CCM version
Separate multiple values with English commas (,). 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 HTTPS listener

Annotation: Multiple, as listed in the following table.

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

Health check: HTTPS listener health checks are disabled by default. To ensure backend service availability, configure HTTP or TCP health checks for the listener port.
In-cluster access: When accessing the service via CLB IP from within the cluster, request traffic might be truncated internally, causing access issues. See Set hostname for Service to force traffic through the CLB by adding an annotation. For details, see Notes on accessing LoadBalancer Service External IP from within the cluster.

Annotation

Description

Supported CCM version

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

Separate multiple values with English commas (,). Example: https:443,http:80.

v1.9.3 and later

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

Certificate ID 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

SSL protocol error when accessing CLB from within a cluster

Symptoms

After you Create HTTPS listener for a service, the service works correctly when accessed from outside the cluster. However, when you use curl to access the HTTPS port of the CLB associated with the service from a node or pod inside the cluster, the following error is returned:

curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number

Cause

This issue occurs because of the IP Virtual Server (IPVS) rules on the node:

Service configuration: An HTTPS listener on a CLB supports only the HTTP protocol for backend services. Therefore, the service must be configured to forward traffic from port: 443 to targetPort: 80. ACK then creates an IPVS rule on the node. This rule directly forwards traffic from port 443 to the backend port 80.
Layer 4 forwarding: IPVS operates at Layer 4 of the TCP/IP protocol stack. It only forwards TCP data packets and does not parse application-layer protocols such as TLS or HTTPS.
Protocol mismatch: The client (curl) sends an HTTPS request that contains TLS handshake data. IPVS directly forwards this request to the backend service's HTTP port 80. Because this port is not configured for TLS, it cannot parse the TLS request. As a result, the backend service returns an HTTP 400 error, and the client reports an SSL protocol error.

Solution

Add the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-hostname annotation to the service. This annotation prevents IPVS rules from being generated on the nodes and forces traffic within the cluster to pass through the CLB. This ensures that the CLB correctly handles the TLS handshake. For more information, see .

Configure additional domain name certificates for HTTPS listener

Annotation: Multiple, as listed in the following table.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with English commas (,). Example: `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	Certificate ID 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-domain-extensions	Specify additional domain names and certificate IDs in the format `{domain}:{certificate ID}`. Separate multiple values with English commas (,). Log on to the CLB console and view the certificate ID on the Certificates page.	v2.13.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-domain-extensions: "${DOMAIN_1}:${CERT_ID_1},${DOMAIN_2}:${CERT_ID_2}"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Create listener with health check

Set TCP health check

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

TCP ports have health checks enabled by default.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-switch	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	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	Time to wait for a response from the health check, applicable to TCP mode. If the backend ECS does not respond correctly within the specified time, the health check fails. Unit: seconds. Valid range: [1, 300]. If the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout` is less than that of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval`, the former is invalid, and the timeout equals the latter's value. Default value: 5. For more information, see CreateLoadBalancerTCPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold	Number of consecutive successful health checks required to change the backend server's health status from `fail` to `success`. Valid range: [2, 10]. Default value: 3. For more information, see CreateLoadBalancerTCPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold	Number of consecutive failed health checks required to change the backend server's health status from success to fail. Valid range: [2, 10]. Default value: 3. For more information, see CreateLoadBalancerTCPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval	Health check interval. Unit: seconds. Valid range: [1, 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 UDP health check

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

UDP ports have health checks enabled by default.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-switch	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	Time to wait for a response from the health check, applicable to TCP mode. If the backend ECS does not respond correctly within the specified time, the health check fails. Unit: seconds. Valid range: [1, 300]. If the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout` is less than that of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval`, the former is invalid, and the timeout equals the latter's value. Default value: 5. For more information, see CreateLoadBalancerUDPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold	Number of consecutive successful health checks required to change the backend server's health status from fail to success. Valid range: [2, 10]. Default value: 3. For more information, see CreateLoadBalancerUDPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold	Number of consecutive failed health checks required to change the backend server's health status from success to fail. Valid range: [2, 10]. Default value: 3. For more information, see CreateLoadBalancerUDPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval	Health check interval. Unit: seconds. Valid range: [1, 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 check for TCP and UDP listeners

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

Description

Supported CCM version

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

Set HTTP health check

Annotation: Multiple, as listed in the following table.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-flag	Valid values: `on`: TCP listeners default to `on` and cannot be changed. No need to modify this annotation for TCP. `off`: HTTP listeners default to `off`. Default value: `off`	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type	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	URI for health checks. Not required when health check type is TCP.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-httpcode	HTTP status codes indicating a healthy check. Separate multiple status codes with English 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	Domain name for health checks. Valid values: `$_ip`: Private IP of the backend server. If an IP is specified or this parameter is unset, the SLB uses each backend server's private IP as the health check domain. `domain`: Domain name length: 1–80 characters. 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	Time to wait for a response from the health check, applicable to HTTP mode. If the backend ECS does not respond correctly within the specified time, the health check fails. Unit: seconds. Valid range: [1, 300]. If the value of `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout` is less than that of service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval, then `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout` is invalid, and the timeout equals 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	Number of consecutive successful health checks required to change the backend server's health status from fail to success. Valid range: [2, 10]. Default value: 3. For more information, see CreateLoadBalancerHTTPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold	Number of consecutive failed health checks required to change the backend server's health status from success to fail. Valid range: [2, 10]. Default value: 3. For more information, see CreateLoadBalancerHTTPListener.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval	Health check interval. Unit: seconds. Valid range: [1, 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 English commas (,). Example: `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-method	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"
    # Set HTTP status code for health check (optional)
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-httpcode: "http_4xx"
    # Set domain for health check (optional)
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-domain: "www.aliyun.com"
    # Set health check method (optional)
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-method: "head"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: nginx
  type: LoadBalancer

Set connection draining for listener

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

Applies only to TCP and UDP protocols.

Annotation

Description

Supported CCM version

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

Enable connection draining. Valid values:

on
off

v2.0.1 and later

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

Set connection draining timeout. Unit: seconds. Valid range: [10, 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 additional request headers for listener

Annotation: Multiple, as listed in the following table.

Applies only to HTTP and HTTPS protocols.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with English commas (,). Example: `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-proto	Configure whether to obtain the CLB listener protocol via the X-Forwarded-Proto header. Valid values: `on` `off` Default value: `off`	v2.1.0 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-slbport	Configure whether to obtain the SLB instance listener port via the XForwardedFor_SLBPORT header. Valid values: `on` `off` Default value: `off`	v2.9.1 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-clientsrcport	Configure whether to obtain the client port accessing the SLB instance via the XForwardedFor_ClientSrcPort header. 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 idle connection timeout for listener

Annotation: Multiple, as listed in the following table.

Applies only to HTTP and HTTPS protocols.

Annotation

Description

Supported CCM version

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

Separate multiple values with English commas (,). Example: https:443,http:80.

v1.9.3 and later

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

Set idle connection timeout for the listener. Unit: seconds. Valid range: [1, 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 HTTP/2 for listener

Annotation: Multiple, as listed in the following table.

Applies only to HTTPS protocol.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with English commas (,). Example: `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	Certificate ID 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	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

Set request timeout for listener

Annotation: Multiple, as listed in the following table.

Applies only to HTTP and HTTPS protocols.

Annotation

Description

Supported CCM version

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

Separate multiple values with English commas (,). Example: https:443,http:80.

v1.9.3 and later

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

Set request timeout. Unit: seconds. Valid range: [1, 180]. Default value: 60

If the backend server does not respond within the timeout period, the SLB stops waiting and returns an HTTP 504 error to the client.

v2.3.0 and later

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

Set connection timeout for listener

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

Applies only to TCP protocol.

Description	Supported CCM version
Connection timeout. Unit: seconds. Valid range: [10, 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 security policy for listener

Annotation: Multiple, as listed in the following table.

Applies only to HTTPS protocol.

Annotation	Description	Supported CCM version
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port	Separate multiple values with English commas (,). Example: `https:443,http:80`.	v1.9.3 and later
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id	Certificate ID 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	Security policy includes optional TLS versions and encryption 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 both TCP and UDP protocols for listener

Note

This feature requires Kubernetes cluster version v1.24 or later. For upgrade instructions, see Upgrade ACK cluster Kubernetes version.

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

Configure Proxy Protocol for TCP and UDP listeners

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

When accessing the service via CLB IP from within the cluster, request traffic might be truncated internally, causing access issues. See Set hostname for Service to force traffic through the CLB by adding an annotation. For details, see Notes on accessing LoadBalancer Service External IP from within the cluster.

Description

Supported CCM version

Configure Proxy Protocol for TCP and UDP listeners. When enabled, Proxy Protocol carries the client source address to backend servers. Valid values:

on
off

Default value: off

Important

This feature does not support smooth migration. Switching Proxy Protocol requires service downtime. Configure 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 specified labels as backend servers

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

Description	Supported CCM version
Specify worker nodes to mount to the CLB backend using labels. Separate multiple labels with English commas (,). Example: `"k1=v1,k2=v2"`. Multiple labels use AND logic. Applies only when backend server type is `ecs` mode.	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 nodes where pods reside as backend servers

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

The default externalTrafficPolicy is Cluster mode, which mounts all cluster nodes to the backend. Local mode mounts only nodes where pods reside.

Description

Supported CCM version

Scheduling algorithm. Valid values:

wrr: Weighted round-robin. Backend servers with higher weights receive more requests (higher probability).

Local mode requires setting the scheduling policy to weighted round-robin wrr.

Note
In versions v1.9.3.164-g2105d2e-aliyun and later, services with external traffic policy set to Local mode automatically set node weights based on the number of pods on each node. For weight calculation rules, see How are node weights automatically set in Local mode?.
rr: Round-robin. Distributes external requests sequentially 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 nodes inunschedulable state from CLB backend

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

Description

Supported CCM version

Remove SchedulingDisabled nodes from the CLB backend. Valid values:

on: Remove nodes in unschedulable state from the CLB backend server group.
off: Commands kubectl cordon and kubectl drain set nodes to unschedulable state. Nodes in unschedulable state remain in the CLB backend server group.

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

Mount pod ENIs directly to CLB backend

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

Description

Default value

Supported CCM version

CLB backend server type. Valid values:

eni: Mount pods directly to the CLB backend to improve network forwarding performance. Applies only in Terway network mode.

You can also manually change service.beta.kubernetes.io/backend-type: "eni" to eni or ecs to mount ECS instances to the CLB backend.
ecs: Mount ECS instances to the CLB backend.

Flannel network mode: ecs
Terway network mode:
- Terway clusters created before August 10, 2020: ecs
- Terway clusters created on or 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 existing vServer group

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

Supports reusing existing vServer groups. Applies only when reusing existing CLB instances. For usage examples, see Achieve cross-cluster service deployment by reusing existing SLB instances.

Set traffic weight for Service

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

In scenarios where multiple Services reuse the same CLB, use this annotation to set the traffic weight for the current Service. This annotation applies only when reusing existing vServer groups. For usage examples, see Achieve cross-cluster service deployment by reusing existing SLB instances.

Ignore backend server weight updates

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

Description

Supported CCM version

Skip updating backend server weights in the vServer group during Service synchronization. Use this setting when managing backend server weights manually outside 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

Set default backend server weight

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

Description

Supported CCM version

Set the default weight for servers in the server group. Higher weights result in more request traffic.

Valid range: [0, 100]. If unspecified, the system uses the default weight corresponding to the current network type.

This setting does not apply when the backend instance is ECS and the Service's externalTrafficPolicy is Local mode.

v2.14.0 and later

apiVersion: v1
kind: Service
metadata:
  annotations:
    # Set default server weight in server group to 35
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-default-weight: "35"
  name: nginx
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 443
  selector:
    run: nginx
  type: LoadBalancer