You can add annotations to the YAML file of a Service to configure Network Load Balancer (NLB) instances to use various load balancing features. NLB instances are next-generation Layer 4 load balancers developed by Alibaba Cloud for the Internet of Everything (IoE). NLB instances provides ultrahigh performance and auto scaling. This topic describes how to use annotations to configure NLB instances, listeners, and backend server groups.
Table of contents
Usage notes
The Kubernetes version of your cluster must be 1.24 or later and the cloud controller manager (CCM) must be of V2.5.0 or later. For more information about how to update a cluster, see Manually update ACK clusters. For more information about how to update a component, see Manage components.
To configure an NLB instance for a Service, the
spec.loadBalancerClass
parameter of the Service must be set toalibabacloud.com/nlb
. Otherwise, a Classic Load Balancer (CLB) instance is created by default.You cannot modify the
spec.loadBalancerClass
parameter of a Service to change the type of a load balancer instance between CLB and NLB after the Service is created.You cannot use the Container Service for Kubernetes (ACK) console to manage NLB instances. To manage NLB instances, use kubectl.
Common operations to manage NLB instances
Create an Internet-facing NLB instance
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps
Description | Default value | Supported CCM version |
The zones in which the NLB instance is deployed. You can log on to the NLB console to view the regions and zones that support NLB. You must select at least two zones for each NLB instance. Separate multiple zones with commas (,). Example: | No impact on workloads | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Create an internal-facing NLB instance
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type
Description | Default value | Supported CCM version |
Creates an internal-facing NLB instance. You can change the value of the annotation to change the network type of an NLB instance. Valid values:
You can log on to the NLB console to view the regions and zones that support NLB. You must select at least two zones for each NLB instance. Separate multiple zones with commas (,). Example: | internet | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: "intranet"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Specify the name of an NLB instance
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-name
Description | Default value | Supported CCM version |
The name of an NLB instance. The name must be 2 to 128 characters in length, and can contain letters, digits, periods (.), underscores (_), and hyphens (-). The name must start with a letter. | No impact on workloads | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-name: "${your-nlb-name}" # The name of the NLB instance.
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Specify the resource group to which an NLB instance belongs
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-resource-group-id
Description | Default value | Supported CCM version |
The ID of the resource group to which the NLB instance belongs. The resource group cannot be changed after it is specified. You can log on to the Resource Management console to query resource group IDs. | No impact on workloads | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-resource-group-id: "${your-resource-group-id}" # The ID of the resource group.
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Create a dual-stack NLB instance
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip-version
Description | Default value | Supported CCM version |
The IP version of an NLB instance. The IP version cannot be changed after it is specified. To use this annotation, make sure that the kube-proxy mode of the cluster is set to IPVS. Valid values:
| ipv4 | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip-version: "DualStack"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Add additional tags to an NLB instance
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags
Description | Default value | Supported CCM version |
The additional tags that you want to add. Separate multiple tags with commas (,). Example: Important After this annotation is added to a Service to specify additional tags, the operations performed on the NLB instance tags in the console may be overwritten. | No impact on workloads | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags: "Key1=Value1,Key2=Value2"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Use an existing NLB instance
The following annotations are used.
Annotation | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id | The ID of an existing NLB instance that you want to use. | No impact on workloads | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners | The annotation specifies whether to overwrite the existing listeners of the NLB instance. Valid values:
| false | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id: "${your-nlb-id}" # The ID of the existing NLB instance that you want to use.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners: "true"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Associate an EIP bandwidth plan with an NLB instance
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-bandwidth-package-id
Description | Default value | Supported CCM version |
The ID of the Elastic IP Address (EIP) bandwidth plan with which you want to associate the NLB instance. You can log on to the Virtual Private Cloud (VPC) console to query the IDs of EIP bandwidth plans. | No impact on workloads | CCM 2.9.1 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-bandwidth-package-id: "cbwp-xxxxxxxxxx"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Enable deletion protection for an NLB instance
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-modification-protection
Description | Default value | Supported CCM version |
Specifies whether to enable deletion protection for an NLB instance. Valid values:
Important If you manually enable deletion protection in the NLB console for an NLB instance that is created for a LoadBalancer Service, you can run the | on | CCM 2.9.1 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-delete-protection: "on"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Enable the configuration read-only mode for an NLB instance
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-modification-protection
Description | Default value | Supported CCM version |
Specifies whether to enable the configuration read-only mode for the NLB instance. Valid values:
| ConsoleProtection | CCM 2.9.1 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-modification-protection: "ConsoleProtection"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Specify the network type of an IPv6 NLB instance
The following annotations are used.
Annotation | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip-version | The IP version of an NLB instance. The IP version cannot be changed after it is specified. To use this annotation, make sure that the kube-proxy mode of the cluster is set to IPVS. Valid values:
| ipv4 | CCM 2.5.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ipv6-address-type | Specifies the network type of the IPv6 NLB instance. Valid values:
Note To use a public IPv6 address, an IPv6 gateway must be created in the VPC in which the NLB instance resides. For more information, see Create and manage an IPv6 gateway. | intranet | CCM 2.9.1 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip-version: "DualStack"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ipv6-address-type: internet # Specify a public IPv6 address.
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Retain automatically created NLB instances when you delete a Service
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-preserve-lb-on-delete
Description | Default value | Supported CCM version |
When you delete a LoadBalancer Service, the NLB instances created by using the Service are retained, and the If this feature is enabled, a Warning event of the Valid values:
Important Perform this operation by deleting the Service instead of modifying the Service type. Otherwise, the Service may be incorrectly re-associated with the Service. | No impact on workloads | CCM 2.10.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-preserve-lb-on-delete: "true"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Common operations to manage listeners
Configure security groups for listeners
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-security-group-ids
Description | Default value | Supported CCM version |
The IDs of the security groups configured for listeners. Separate multiple IDs with commas (,). Example: | No impact on workloads | CCM 2.6.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-security-group-ids: "sg-aaaaa,sg-bbbbb" # Separate multiple security group IDs with commas (,).
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Configure both TCP and UDP for a listener
Description | Default value | Supported CCM version |
Only clusters whose Kubernetes version is 1.24 and later support this feature. For more information about how to update an ACK cluster, see Manually update ACK clusters. | No impact on workloads | N/A |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: udp
port: 80
protocol: UDP
targetPort: 81
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Create TCP listeners
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Create a UDP listener
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: udp
port: 80
protocol: UDP
targetPort: 80
selector:
app: nginx
sessionAffinity: None
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Create TCP/SSL listeners
The following annotations are used.
Annotation | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port | The protocol types of the listeners. Separate multiple listener types with commas (,). Example: | No impact on workloads | CCM 2.5.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id | The server certificate ID. You can log on to the Certificate Management Service console to view SSL certificate IDs. | No impact on workloads |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "tcpssl:443"
# If the certificate is deployed in a region in the Chinese mainland, the SSL certificate ID appended with region information is ${your-cert-id}-cn-hangzhou.
# If the certificate is deployed in a region outside the Chinese mainland, the SSL certificate ID appended with region information is ${your-cert-id}-ap-southeast-1.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id: "${The appended certificate ID}"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Enable mutual authentication
The following annotations are used.
Annotations | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port | The protocol types of the listeners. Separate multiple listener types with commas (,). Example: | No impact on workloads | CCM 2.5.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id | The server certificate ID. You can log on to the Certificate Management Service console to view SSL certificate IDs. | No impact on workloads | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cacert-id | The certificate authority (CA) certificate ID. You can log on to the Certificate Management Service console to view CA certificate IDs. | No impact on workloads | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cacert | Specifies whether to enable mutual authentication. Valid values:
| No impact on workloads |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "tcpssl:443"
# If the cluster is deployed in a region in the Chinese mainland, the SSL certificate ID appended with region information is ${your-cert-id}-cn-hangzhou.
# If the cluster is deployed in a region outside the Chinese mainland, the SSL certificate ID appended with region information is ${your-cert-id}-ap-southeast-1.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id: "${The appended certificate ID}"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cacert-id: "${your-cacert-id}" # The CA certificate ID.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cacert: "on"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Configure a TLS security policy
The following annotations are used.
Annotations | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port | The protocol types of the listeners. Separate multiple listener types with commas (,). Example: | No impact on workloads | CCM 2.5.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id | The server certificate ID. You can log on to the Certificate Management Service console to view SSL certificate IDs. | No impact on workloads | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-tls-cipher-policy | The ID of the security policy. System and custom security policies are supported. Valid values:
| tls_cipher_policy_1_0 |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "tcpssl:443"
# If the cluster is deployed in a region in the Chinese mainland, the SSL certificate ID appended with region information is ${your-cert-id}-cn-hangzhou.
# If the cluster is deployed in a region outside the Chinese mainland, the SSL certificate ID appended with region information is ${your-cert-id}-ap-southeast-1.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id: "${The appended certificate ID}"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-tls-cipher-policy: "tls_cipher_policy_1_0"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Configure proxy protocol
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-proxy-protocol
Description | Default value | Supported CCM version |
Specifies whether to enable proxy protocol to pass client IP addresses to backend servers. Valid values:
Important Before you enable proxy protocol, check whether proxy protocol V2 is enabled for the backend service. If proxy protocol V2 is disabled, the client IP addresses cannot be passed to backend servers. Configure with caution. | off | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-proxy-protocol: "on"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Configure proxy protocol with additional information
The following annotations are used.
Annotation | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-proxy-protocol | Specifies whether to enable proxy protocol to pass client IP addresses to backend servers. Valid values:
Important Before you enable proxy protocol, check whether proxy protocol V2 is enabled for the backend service. If proxy protocol V2 is disabled, the client IP addresses cannot be passed to backend servers. Configure with caution. | off | CCM 2.5.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ppv2-pvl-vpc-id-enabled | Specifies whether the proxy protocol is used to pass the VpcId parameter to backend servers. Valid values:
| off | CCM 2.9.1 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ppv2-pvl-ep-id-enabled | Indicates whether the proxy protocol is used to pass the PrivateLinkEpId parameter to backend servers. Valid values:
| off | CCM 2.9.1 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ppv2-pvl-eps-id-enabled | Specifies whether the proxy protocol is used to pass the PrivateLinkEpsId parameter to backend servers. Valid values:
| off | CCM 2.9.1 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-proxy-protocol: "on"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ppv2-pvl-ep-id-enabled: "on"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ppv2-pvl-eps-id-enabled: "on"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ppv2-pvl-vpc-id-enabled: "on"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Specify the maximum number of connections that can be created per second
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cps
Description | Default value | Supported CCM version |
The maximum number of connections that can be created per second on the NLB instance. Valid values: 0 to 1000000. A value of 0 indicates that the number of connections that can be created per second is unlimited. | No impact on workloads | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cps: "100"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Specify the timeout period of idle connections for the listeners
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-idle-timeout
Description | Default value | Supported CCM version |
The timeout period of idle connections. Unit: seconds Valid values: 10 to 900. | 900 | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-idle-timeout: "60"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Configure an ALPN policy
The following annotations are used.
Annotations | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port | The protocol types of the listeners. Separate multiple listener types with commas (,). Example: | No impact on workloads | CCM 2.5.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id | The server certificate ID. You can log on to the Certificate Management Service console to view SSL certificate IDs. | No impact on workloads | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-alpn | Specify whether to enable Application-Layer Protocol Negotiation (ALPN). Valid values:
| off | CCM 2.10.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-alpn-policy | The ALPN policy. Valid values:
For more information about the possible values of this annotation, see the | No impact on workloads |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-protocol-port: "tcpssl:443"
# If the cluster is deployed in a region in the Chinese mainland, the SSL certificate ID appended with region information is ${your-cert-id}-cn-hangzhou.
# If the cluster is deployed in a region outside the Chinese mainland, the SSL certificate ID appended with region information is ${your-cert-id}-ap-southeast-1.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cert-id: "${The appended certificate ID}"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-alpn: "on"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-alpn-policy: "HTTP1Only"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Common operations to manage backend server groups
Set the scheduling algorithm
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-scheduler
Description | Default value | Supported CCM version |
The routing algorithm. Valid values:
For more information about the possible values of this annotation, see the | wrr | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-scheduler: "sch"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Configure connection draining
The following annotations are used.
Annotations | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-connection-drain | The annotation specifies whether to enable connection draining. Valid values:
| off | CCM 2.5.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-connection-drain-timeout | Specify a timeout period for connection draining. Unit: seconds Valid values: 10 to 900. | No impact on workloads |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
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:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Configure client IP preservation
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-preserve-client-ip
Description | Default value | Supported CCM version |
The annotation specifies whether to enable client IP preservation. Valid values:
| off | CCM 2.5.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-preserve-client-ip: "on"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Configure TCP health checks
The following annotations are used. To configure TCP health checks, all annotations in the following table are required. By default, health checks are enabled for TCP ports.
Annotations | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-flag | Specifies whether to enable health checks. Valid values:
| on | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type | The protocol that you want to use for health checks. Valid values:
| tcp | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-port | The backend server port that is used for health checks. Valid values: 0 to 65535. Default value: 0. A value of 0 indicates that the health check port specified on a backend server is used. | 0 | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout | The timeout period of health checks. Unit: seconds Valid values: 1 to 300. | 5 | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold | The number of consecutive successful health checks that must occur before an unhealthy backend server is declared healthy. Valid values: 2 to 10. | 2 | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold | The number of consecutive failed health checks that must occur before a healthy backend server is declared unhealthy. Valid values: 2 to 10. | 2 | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval | The interval at which health checks are performed. Unit: seconds Valid values: 1 to 50. | 10 |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-flag: "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: "5"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Configure HTTP health checks
The following annotations are used. To configure TCP health checks, all annotations in the following table are required. By default, health checks are enabled for TCP ports.
Annotations | Description | Default value | Supported CCM version |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-flag | Specifies whether to enable health checks. Valid values:
| on | CCM 2.5.0 and later |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-type | The protocol that you want to use for health checks. Valid values:
| tcp | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-uri | The path that is used for health checks. The path must be 1 to 80 characters in length, and can contain only letters, digits, and special characters. The URL must start with a forward slash (/). For more information, see CreateServerGroup. Note This annotation takes effect only when the | No impact on workloads | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-domain | The domain name that you want to use for health checks. Valid values:
Note This annotation takes effect only when the | No impact on workloads | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-port | The backend server port that is used for health checks. Valid values: 0 to 65535. Default value: 0. A value of 0 indicates that the health check port specified on a backend server is used. | 0 | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-connect-timeout | The timeout period of health checks. Unit: seconds Valid values: 1 to 300. | 5 | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-healthy-threshold | The number of consecutive successful health checks that must occur before an unhealthy backend server is declared healthy. Valid values: 2 to 10. | 2 | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-unhealthy-threshold | The number of consecutive failed health checks that must occur before a healthy backend server is declared unhealthy. Valid values: 2 to 10. | 2 | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval | The interval at which health checks are performed. Unit: seconds Valid values: 1 to 50. | 10 | |
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-method | The method that you want to use to perform health checks. Valid values:
Note This annotation takes effect only when the |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
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-health-check-domain: "www.test.com"
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-connect-timeout: "10"
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-interval: "5"
# Optional. Specify the health check method.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-health-check-method: "head"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Specify the backend server group type
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-server-group-type
Description | Default value | Supported CCM version |
Specifies the backend server group type. Valid values:
For more information about NLB server groups, see Overview of NLB server groups. | Instance | CCM 2.8.0 and later |
apiVersion: v1
kind: Service
metadata:
annotations:
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-zone-maps: "${zone-A}:${vsw-A},${zone-B}:${vsw-B}" # Example: cn-hangzhou-k:vsw-i123456,cn-hangzhou-j:vsw-j654321.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-server-group-type: "Ip"
name: nginx
namespace: default
spec:
externalTrafficPolicy: Local
ports:
- name: tcp
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: nginx
loadBalancerClass: "alibabacloud.com/nlb"
type: LoadBalancer
Reuse an existing vServer group
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port
This annotation can be used to reuse a vServer group. This annotation takes effect only when you use an existing NLB instance. For more information, see Reuse an existing SLB instance to expose Services in different ACK clusters.
Set weights for Services to enable weighted round robin
Annotation: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight
When multiple Services use the same NLB instance, you can use this annotation to specify the percentage of traffic distributed to the current Service. This annotation takes effect only when the existing vServer group is reused. For more information, see Reuse an existing SLB instance to expose Services in different ACK clusters.