You can add annotations to the YAML file of a Service to configure load balancing. This topic describes how to use annotations to configure load balancing. You can configure Classic Load Balancer (CLB) instances, listeners, and backend server groups.
Table of contents
Description | Hyperlink |
Usage notes
The values of annotations are case-sensitive.
Starting from September 11, 2019, the keyword
alicloud
inannotations
is changed toalibaba-cloud
.Example:
Before the change:
service.beta.kubernetes.io/alicloud-loadbalancer-id
After the change:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id
The system still supports annotations that use the
alicloud
keyword. You do not need to modify the existing annotations.
Common operations to manage CLB instances
Create an Internet-facing CLB 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 CLB instance
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
Create a CLB instance that uses the specified specifications
For more information about CLB instance specifications, see CreateLoadBalancer. You can call this API operation to create a CLB instance that uses the specified specifications or update the specifications of a CLB instance.
If you use the CLB console to update the specifications of a CLB instance, the Cloud Controller Manager (CCM) may restore the CLB instance to the original specifications. Proceed with caution. You can use the CLB console to modify the specifications of only CLB instances that use the pay-by-specification metering method.
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 CLB instance
By default, the CCM does not overwrite the listeners of an existing CLB instance. To overwrite the listeners of an existing CLB instance, set the annotation
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners
to "true".NoteThe following section explains why the CCM does not overwrite the listeners of an existing CLB instance:
If the listeners of the CLB instance are associated with applications, service interruptions may occur after the configurations of the listeners are overwritten.
The CCM supports limited backend configurations and cannot handle complex configurations. If you require complex backend configurations, you can manually configure listeners in the CLB console without overwriting the existing listeners.
In both cases, we recommend that you do not overwrite the listeners of existing CLB instances. However, you can overwrite an existing listener if the port of the listener is no longer in use.
You cannot add additional tags to an existing CLB instance by using the annotation
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags
.
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 CLB instance and forcefully overwrite the listeners of the CLB instance
Use the following template to create a LoadBalancer Service and forcefully overwrite an existing listener of the CLB instance. If a port conflict occurs, the original listener is deleted.
If you use an existing CLB instance and set forceoverride
to true
, do not associate a listener of the CLB instance with multiple Services. Otherwise, a configuration conflict occurs when these Services overwrite the configuration of the listener.
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 zone and secondary zone when you create a CLB instance
CLB instances cannot be deployed across zones in specific regions, such as the Indonesia (Jakarta) region.
After you specify the primary zone and secondary zone for a CLB instance, the zones cannot be changed.
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-master-zoneid: "ap-southeast-5a"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-slave-zoneid: "ap-southeast-5a"
name: nginx
namespace: default
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
run: nginx
type: LoadBalancer
Create a pay-by-bandwidth CLB instance
Only Internet-facing CLB instances support the pay-by-bandwidth metering method.
For more information about the limits on metering methods for Internet-facing CLB instances, see Change the metering method of an Internet-facing CLB instance.
Both annotations in the following template are required.
Modify the annotation values based on your business requirements.
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
The annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-bandwidth specifies the bandwidth limit.
Specify a vSwitch for a CLB instance
Obtain the ID of a vSwitch in the Virtual Private Cloud (VPC) console. Then, use the annotations in the following template to specify the vSwitch for a CLB instance.
The specified vSwitch and the cluster must be deployed in the same VPC.
Both annotations in the following template are required.
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 CLB instance
Take note of the following limits:
The IP address must fall within the destination CIDR block of the vSwitch to which the CLB instance belongs. Only IPv4 addresses are supported.
The IP address cannot be changed after it is specified.
All annotations in the following template are required.
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 a CLB instance
Separate multiple tags with commas (,). Example: "k1=v1,k2=v2"
.
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 CLB instance
The kube-proxy mode must be set to IPVS.
The assigned IPv6 address can be used only in an IPv6 network.
You cannot change the IP address type after you create an IPv6 CLB instance.
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip-version: "ipv6"
name: nginx
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app: nginx
type: LoadBalancer
Enable deletion protection for a CLB instance
By default, deletion protection is enabled for CLB instances.
If you manually enable deletion protection in the CLB console for a CLB instance that is created for a LoadBalancer Service, you can run the kubectl delete svc {your-svc-name}
command to delete the CLB instance.
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 the configuration read-only mode for a CLB instance
By default, the configuration read-only mode is enabled for a CLB instance.
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 a CLB instance
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 to which a CLB instance belongs
Log on to the Resource Management console to obtain the ID of a resource group. Then, use the annotation in the following template to specify the resource group to which the CLB instance belongs.
You cannot modify the resource group after the CLB instance is created.
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
Specify a hostname for a Service
your_service_name
must comply with the naming conventions of domain names.After you add the annotation, the external IP address of the Service is changed from the default CLB IP address to
your_service_name
. If you access the CLB IP address from within the cluster, the request is first forwarded to the corresponding CLB instance.After you add the annotation, if the listener protocol is TCP or UDP and you access the CLB IP address from within the cluster, a loopback issue occurs. For more information, see Why does the client fail to access a CLB instance?.
This annotation does not automatically associate a domain name with the CLB instance. If you want to associate a domain name with the CLB instance, log on to the Domains console, purchase a domain name, and then associate the domain name with the CLB instance. For more information about how to purchase domain names, see Purchase domain names.
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "http:80"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-hostname: "${your_service_hostname}"
name: nginx-svc
namespace: default
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: nginx
type: LoadBalancer
Expected output:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nginx-svc loadBalancer 47.100.XX.XX www.example.com 80:30248/TCP,443:32670/TCP 10s
Create a pay-by-LCU CLB instance
Supported metering methods:
PayBySpec
: The CLB instance is billed based on its specification. This is the default value.PayByCLCU
: The CLB instance is billed based on LCUs.
You cannot change the specification of a pay-by-LCU CLB instance. You cannot specify PayByCLCU
and add the annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec
at the same time. After you create a pay-by-specification CLB instance, you can only change the metering method of the CLB instance to PayByCLCU
.
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-instance-charge-type: "PayByCLCU"
name: nginx
namespace: default
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
run: nginx
type: LoadBalancer
Common operations to manage listeners
Specify the session persistence period for a TCP-based CLB instance
The annotation
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-persistence-timeout
applies only to TCP listeners.If a CLB instance has multiple TCP listeners, the configuration applies to all the TCP listeners.
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
Enable session persistence for an HTTP or HTTPS listener by inserting a cookie
The annotations in the following template apply only to HTTP-based and HTTPS-based CLB instances.
If a CLB instance has multiple HTTP or HTTPS listeners, the configuration applies to all the HTTP or HTTPS listeners.
To configure session persistence by inserting a cookie, all annotations in the following template are required.
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
Enable access control for a CLB instance
Create an access control list (ACL) in the CLB console and record the ACL ID. Then, use the annotations in the following template to enable access control for a CLB instance.
A whitelist allows access only from specified IP addresses. A blacklist blocks access only from specific IP addresses.
All annotations in the following template are required.
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-status: "on"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-id: "${YOUR_ACL_ID}"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-type: "white"
name: nginx
namespace: default
spec:
ports:
- port: 443
protocol: TCP
targetPort: 443
selector:
run: nginx
type: LoadBalancer
Configure port forwarding for a CLB instance
Port forwarding allows a CLB instance to forward requests from an HTTP port to an HTTPS port.
Create a certificate in the CLB console and record the certificate ID. Then, use the following annotations to configure port forwarding for a CLB instance.
All annotations in the following template are required.
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
Specify the scheduling algorithm for a CLB instance
rr: Requests are distributed to backend servers in sequence. This is the default scheduling algorithm.
wrr: Backend servers with higher weights receive more requests than those with lower weights.
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
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
You must first create a certificate in the CLB console. Then, you can use the certificate ID and the following template to create a LoadBalancer Service and an HTTPS-based CLB instance.
The HTTPS listeners of the CLB instance decrypt HTTPS requests into HTTP requests and forward the requests to pods on the backend servers.
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 that has health checks enabled
Enable TCP health checks
By default, health checks are enabled for TCP ports.
To enable TCP health checks, all annotations in the following template are required.
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
Enable UDP health checks
By default, health checks are enabled for UDP ports.
To enable UDP health checks, all annotations in the following template are required.
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 a TCP or UDP listener
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
Enable HTTP health checks
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"
# Specify the health check method. This annotation 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
Only TCP and UDP are supported. To enable connection draining for a listener, all annotations in the following template are required.
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
Use the X-Forwarded-Proto header to obtain the listener protocol of a CLB instance
Only HTTP and HTTPS are supported.
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"
name: nginx
namespace: default
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
run: nginx
type: LoadBalancer
Specify the timeout period of idle connections for a listener
Only HTTP and HTTPS are supported.
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "http:80"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-idle-timeout: "30"
name: nginx
namespace: default
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
run: nginx
type: LoadBalancer
Disable HTTP/2 for a listener
Only HTTPS is supported.
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 timeout period of requests for a listener
Only HTTP and HTTPS are supported.
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 timeout period of connections for a listener
Only TCP is supported.
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 policies for a listener
Each security policy contains Transport Layer Security (TLS) protocol versions and cipher suites available for HTTPS. Only HTTPS is supported. For more information, see CreateLoadBalancerHTTPSListener.
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 for a listener
Only clusters whose Kubernetes version is 1.24 and later support this feature. For more information about how to update a cluster, 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 Proxy Protocol for TCP and UDP listeners
After Proxy Protocol is configured, client IP addresses can be passed to backend servers.
Enabling this feature results in service interruptions. You must stop your applications before you enable Proxy Protocol. Proceed with caution.
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
Common operations to manage backend server groups
Add worker nodes that have specified labels as the backend servers of a CLB instance
Separate multiple labels with commas (,). Example: "k1=v1,k2=v2"
. A node must have all the specified labels before you can add the node as a backend server.
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
Add the nodes on which pods run as the backend servers of a CLB instance
By default,
externalTrafficPolicy
is set to Cluster for a Service. In Cluster mode, all nodes in the cluster are added as the backend servers of the CLB instance. In Local mode, only nodes where the pods are deployed are added as the backend servers of the CLB instance.In Local mode, you must set the scheduling algorithm to weighted round-robin (WRR).
NoteFor CCM V1.9.3.164-g2105d2e-aliyun and later, node weights are calculated based on the number of pods that run on each node for Services whose externalTrafficPolicy is set to Local. For more information about node weight calculation, see How does the CCM calculate node weights in Local mode? .
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
You can run the
kubectl cordon
andkubectl drain
commands to set a node to the unschedulable state. By default, theservice.beta.kubernetes.io/alibaba-cloud-loadbalancer-remove-unscheduled-backend
annotation is set to off. Nodes in the unschedulable state cannot be removed from the backend server group of a CLB instance.To remove backend servers in the unschedulable state from a CLB instance, set the annotation
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-remove-unscheduled-backend
to on.
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
Add pods that are assigned elastic network interfaces (ENIs) as the backend servers of a CLB instance
When the Terway network plug-in is used, you can use the annotation service.beta.kubernetes.io/backend-type: "eni"
to add pods that are assigned ENIs as the backend servers of a CLB instance. This improves network forwarding performance.
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
You can also change eni
in service.beta.kubernetes.io/backend-type: "eni"
to ecs
. This allows you to add Elastic Compute Service (ECS) instances as backend severs of a CLB instance.
Reuse an existing vServer group
The annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port
can be used to reuse an existing vServer group that is added to a CLB instance. This annotation takes effect only when the CLB instance is reused. For more information, see Use the CCM to deploy services across clusters.
Specify weights for Services to enable weighted round robin
When a reused CLB instance is shared among multiple Services, the annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight
can be used to set the weight of each Service to enable weighted round robin. This annotation takes effect only when an existing vServer group is reused. For more information, see Use the CCM to deploy services across clusters.
Common annotations
Common annotations that are used to configure CLB instances
Annotation | Type | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type | string | The type of CLB instance. Valid values: internet and intranet.
| internet | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-charge-type | string | The metering method of a CLB instance. Valid values: paybytraffic and paybybandwidth. | paybytraffic | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id | string | The ID of the CLB instance. You can specify an existing CLB instance by using the annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id. By default, if you specify an existing CLB instance, the CCM does not overwrite the listeners of the CLB instance. To overwrite the listeners, set the annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners to "true". | None | CCM 1.9.3.81-gca19cd4-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-spec | string | The specifications of the CLB instance. For more information, see CreateLoadBalancer. | slb.s1.small | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-master-zoneid | string | The ID of the zone for the primary backend server. | None | CCM 1.9.3.10-gfb99107-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-slave-zoneid | string | The ID of the zone for the secondary backend server. | None | CCM 1.9.3.10-gfb99107-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners | string | Specifies whether to overwrite the listeners of an existing CLB instance that is specified for a Service. | "false": does not overwrite the listeners of the existing CLB instance. | CCM 1.9.3.81-gca19cd4-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-bandwidth | string | The bandwidth of a CLB instance. This annotation applies only to Internet-facing CLB instances. | 50 | CCM 1.9.3.10-gfb99107-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vswitch-id | string | The ID of the vSwitch to which a CLB instance belongs. To set this annotation, you must set the annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type to intranet. | None | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags | string | The tags that you want to add to a CLB instance. Separate multiple tags with commas (,). Example: | None | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip-version | string | The IP protocol of a CLB instance. Valid values: ipv4 and ipv6. | ipv4 | CCM 1.9.3.220-g24b1885-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-delete-protection | string | Specifies whether to enable deletion protection for a CLB instance. Valid values: on and off. | on | CCM 1.9.3.313-g748f81e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-modification-protection | string | Specifies whether to enable the configuration read-only mode for a CLB instance. Valid values: ConsoleProtection and NonProtection. | ConsoleProtection | CCM 1.9.3.313-g748f81e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-resource-group-id | string | The resource group to which a CLB instance belongs. | None | CCM 1.9.3.313-g748f81e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-name | string | The name of the CLB instance. | None | CCM 1.9.3.313-g748f81e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-hostname | string | The hostname of the Service. The hostname must comply with the naming conventions of domain names. | None | CCM 2.3.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-instance-charge-type | string | The metering method of the CLB instance. Valid values:
| PayBySpec | CCM 2.4.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip | string | The IP address of the internal-facing CLB instance. The IP address must fall within the destination CIDR block of the vSwitch. You must add this annotation together with the | None | CCM 2.7.0 and later |
Common annotations that are used to configure listeners
Annotation | Type | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-scheduler | string | The scheduling algorithm. Valid values: wrr and rr.
| rr | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port | string | The listening port. Separate multiple ports with commas (,). Example: | None | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-persistence-timeout | string | The session persistence period. This annotation applies only to TCP listeners. Valid values: 0 to 3600. Unit: seconds. Default value: 0. By default, session persistence is disabled. For more information, see CreateLoadBalancerTCPListener. | 0 | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session | string | Specifies whether to enable session persistence. Valid values: on and off. Note This annotation applies only to HTTP and HTTPS listeners. For more information, see CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener. | off | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-sticky-session-type | string | The method that is used to process cookies. Valid values:
Note
For more information, see CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener. | None | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cookie-timeout | string | The timeout period of a cookie. Valid values: 1 to 86400. Unit: seconds. Note If 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, you must specify this annotation. For more information, see CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener. | None | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cookie | string | The name of a cookie configured on a backend server. The name must be 1 to 200 characters in length, and can contain only ASCII letters and digits. It cannot contain commas (,), semicolons (;), or space characters. It cannot start with a dollar sign ($). Note If 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, you must specify this annotation. For more information, see CreateLoadBalancerHTTPListener and CreateLoadBalancerHTTPSListener. | None | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id | string | The ID of a certificate for a CLB instance. You must first upload the certificate in the CLB console. | None | CCM 1.9.3.164-g2105d2e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-flag | string | Valid values: on and off.
| Default value: off. This annotation is optional for TCP listeners. By default, the health check feature is enabled for TCP listeners. This feature cannot be disabled. | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type | string | The type of health check. Valid values: tcp and http. For more information, see CreateLoadBalancerTCPListener. | tcp | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-uri | string | The URI that is used for health checks. Note If the type of health check is TCP, this annotation is optional. For more information, see CreateLoadBalancerTCPListener. | None | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-port | string | The port that is used for health checks. Valid values: 1 to 65535. | None | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold | string | The number of consecutive successful health checks that must occur before an unhealthy backend server is declared healthy. Valid values: 2 to 10. For more information, see CreateLoadBalancerTCPListener. | 3 | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold | string | The number of consecutive failed health checks that must occur before a healthy backend server is declared unhealthy. Valid values: 2~10 For more information, see CreateLoadBalancerTCPListener. | 3 | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval | string | The interval between two consecutive health checks. Unit: seconds. Valid values: 1 to 50. Unit: seconds. For more information, see CreateLoadBalancerTCPListener. | 2 | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout | string | The timeout period of a health check. This annotation applies to TCP health checks. If a backend server does not respond within the specified timeout period, the server fails to pass the health check. Valid values: 1 to 300. Unit: seconds. Note If the value of service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout is smaller than that of service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval, service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout does not take effect. In this case, the value of service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval is used as the timeout period. For more information, see CreateLoadBalancerTCPListener. | 5 | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout | string | The timeout period of a health check. This annotation applies to HTTP health checks. If a backend server does not respond within the specified timeout period, the server fails to pass the health check. Valid values: 1 to 300. Unit: seconds. Note If the value of service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout is smaller than that of service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval, service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-timeout does not take effect. In this case, the value of service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval is used as the timeout period. For more information, see CreateLoadBalancerTCPListener. | 5 | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-domain | string | The domain name that is used for health checks.
| None | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-httpcode | string | The HTTP status code that is returned when a health check is successful. Separate multiple HTTP status codes with commas (,). Valid values:
Default value: http_2xx. | http_2xx | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-status | string | Specifies whether to enable access control for a listener. Valid values: on and off. | off | CCM 1.9.3.164-g2105d2e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-id | string | The ID of the network ACL that is associated with a listener. If the annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-status is set to on, this annotation is required. | None | CCM 1.9.3.164-g2105d2e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-acl-type | string | The type of the network ACL. Valid values: white and black.
| None | CCM 1.9.3.164-g2105d2e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-forward-port | string | Redirects HTTP requests to the specified port of an HTTPS listener. Example: | None | CCM 1.9.3.164-g2105d2e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-connection-drain | string | Specifies whether to enable connection draining. Valid values: on and off. | None | CCM 2.0.1 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-connection-drain-timeout | string | The timeout period of connection draining. Unit: seconds. Value values: 10 to 900. | None | CCM 2.0.1 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-xforwardedfor-proto | string | Specifies whether to use the X-Forwarded-Proto header to obtain the listener protocol of a CLB instance. Valid values: on and off. | off | CCM 2.1.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-idle-timeout | string | Specifies the timeout period of idle connections for a listener. Unit: seconds. Valid values: 1 to 60. | 15 | CCM 2.1.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-http2-enabled | string | Specifies whether to enable HTTP/2. Valid values: on and off. | on | CCM 2.1.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-established-timeout | string | The timeout period of connections. Only TCP is supported. Unit: seconds. Value values: 10 to 900. For more information, see CreateLoadBalancerTCPListener. | None | CCM 2.3.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-request-timeout | string | The timeout period of requests. HTTP and HTTPS are supported. Unit: seconds. Valid values: 1 to 180. If no response is received from the backend server within the timeout period, CLB returns an HTTP 504 error code to the client. | 60 | CCM 2.3.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-method | string | The health check method used by HTTP listeners. Valid values: | None | CCM 2.3.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-tls-cipher-policy | string | The TLS security policy. Each security policy contains TLS protocol versions and cipher suites available for HTTPS. For more information, see CreateLoadBalancerHTTPSListener. Valid values:
| tls_cipher_policy_1_0 | CCM 2.4.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-proxy-protocol | string | Specifies whether to enable Proxy Protocol for a TCP or UDP listener. Valid values: on and off. | off | V2.6.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-switch | string | Specifies whether to enable health checks for a TCP or UDP listener. Valid values: on and off. | on | V2.6.0 and later |
Common annotations that are used to configure backend server groups
Annotation | Type | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-backend-label | string | The labels based on which worker nodes are added as backend servers of a CLB instance. | None | CCM 1.9.3 and later |
externalTrafficPolicy | string | The policy that is used to add nodes as backend servers. Valid values:
| Cluster | CCM 1.9.3 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-remove-unscheduled-backend | string | Specifies whether to remove backend servers in the Unschedulable state from a CLB instance. Valid values: on and off. | off | CCM 1.9.3.164-g2105d2e-aliyun and later |
service.beta.kubernetes.io/backend-type | string | The type of resources that are added as the backend servers to a CLB instance. Valid values:
| When the Flannel network plug-in is used, the default value is When the Terway network plug-in is used:
| CCM 1.9.3.164-g2105d2e-aliyun and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port | string | Reuses an existing vServer group. This annotation takes effect only when the existing CLB instance is reused. Separate multiple ports and vServer groups with commas (,). | None | CCM 2.0.1 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight | string | The weight of a Service when a CLB instance is shared by multiple Services. This annotation takes effect only when the existing vServer group is reused. | None | CCM 2.0.1 and later |