Help Center/ Cloud Container Engine/ User Guide/ Networking/ Services/ LoadBalancer/ Network and Backend Configuration/ Configuring Health Check on Multiple LoadBalancer Service Ports
Updated on 2026-05-26 GMT+08:00
View PDF
Share

Configuring Health Check on Multiple LoadBalancer Service Ports

The health check annotation for LoadBalancer Services has been upgraded from kubernetes.io/elb.health-check-option to kubernetes.io/elb.health-check-options. You can now configure health checks for specific Service ports without affecting other ports. To apply a global health check to all ports, continue using the original annotation.

Notes and Constraints

  • This function is available in the following versions:
    • v1.19: v1.19.16-r5 or later
    • v1.21: v1.21.8-r0 or later
    • v1.23: v1.23.6-r0 or later
    • v1.25: v1.25.2-r0 or later
    • Versions later than v1.25
  • Either kubernetes.io/elb.health-check-option or kubernetes.io/elb.health-check-options can be configured.
  • The target_service_port field is mandatory and must be unique.

Procedure

Configure health checks for different Service ports. The following is an example using the kubernetes.io/elb.health-check-options annotation:

apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: default
  labels: 
    app: nginx
    version: v1
  annotations:
    kubernetes.io/elb.class: union         # Load balancer type
    kubernetes.io/elb.id: <your_elb_id>    # Load balancer ID. Replace it with the actual value.
    kubernetes.io/elb.lb-algorithm: ROUND_ROBIN  # Load balancer algorithm
    kubernetes.io/elb.health-check-flag: 'on'    # Enable ELB health check.
    kubernetes.io/elb.health-check-options: '[
	{
		"protocol": "TCP",
		"delay": "5",
		"timeout": "10",
		"max_retries": "3",
		"target_service_port": "TCP:1",
		"monitor_port": "22"
	},
	{
		"protocol": "HTTP",
		"delay": "5",
		"timeout": "10",
		"max_retries": "3",
		"path": "/",
		"target_service_port": "TCP:2",
		"monitor_port": "22",
                "expected_codes": "200"
	}
    ]'
spec:
  selector:
    app: nginx
    version: v1
  externalTrafficPolicy: Cluster
  ports:
    - name: cce-service-0
      targetPort: 1
      nodePort: 0
      port: 1
      protocol: TCP
    - name: cce-service-1
      targetPort: 2
      nodePort: 0
      port: 2
      protocol: TCP
  type: LoadBalancer
  loadBalancerIP: **.**.**.**
Table 1 elb.health-check-options

Parameter

Mandatory

Type

Description

target_service_port

Yes

String

Port for health check specified by spec.ports. The value consists of the protocol and port number, for example, TCP:80.

monitor_port

No

String

Re-specified port for health check. If this parameter is not specified, the service port is used by default.

NOTE:

Ensure that the port is in the listening state on the node where the pod is located. Otherwise, the health check result will be affected.

delay

No

String

Health check interval (s)

Value range: 1 to 50. Default value: 5

timeout

No

String

Health check timeout, in seconds.

Value range: 1 to 50. Default value: 10

max_retries

No

String

Maximum number of health check retries.

Value range: 1 to 10. Default value: 3

protocol

No

String

Health check protocol.

Default value: protocol of the associated Service

Value options: HTTPS, TLS, gRPC, TCP, UDP, and HTTP

To use HTTPS, TLS, or gRPC, you need to use a dedicated load balancer, and the cluster version must be v1.28.15-r90, v1.29.15-r50, v1.30.14-r50, v1.31.14-r10, v1.32.9-r10, v1.33.7-r10, v1.34.3-r0, or later. gRPC and TLS depend on the ELB capabilities. Before using this function, submit a service ticket to enable the required ELB capabilities.
  • When the listener's backend protocol is UDP or QUIC, the health check protocol must be UDP.
  • When the listener's backend protocol is TCP, the health check protocol must be TCP, HTTP, or HTTPS.
  • When the listener's backend protocol is TLS, HTTP, HTTPS, or gRPC, the health check protocol must be TCP, HTTP, HTTPS, TLS, or gRPC.
CAUTION:

To change the health check protocol (including the switchover between global check and custom check), disable the health check, enable it again, and change the protocol.

path

No

String

Health check URL. This parameter needs to be configured when the protocol is HTTP, HTTPS, or gRPC.

Default value: /

Value range: 1-80 characters

expected_codes

No

String

Expected response status code. This parameter is supported only by clusters v1.19.16-r50, v1.21.11-r10, v1.23.9-r10, v1.25.4-r10, v1.27.1-r10, or later.

Value:

  • A specific value, for example, 200
  • A list of values that are separated with commas (,), for example, 200, 202
  • A value range, for example, 200–204

Default value: 200. The status code ranges from 200 to 599. For gRPC health checks, the default value is 0, and the status code ranges from 0 to 99.

This parameter is available only for HTTP, HTTPS, or gRPC. It does not take effect for other protocols.
Parent Topic: Network and Backend Configuration