Configuring Full-Port Forwarding for LoadBalancer Services

When accessing a Service through a load balancer, the listener typically forwards traffic to a fixed port on the backend pod. If you want the listener to forward traffic to a backend pod port matching its own port (for example, traffic from listener port 80 is forwarded to backend port 80, and traffic from listener port 81 is forwarded to backend port 81), this fixed-port forwarding mode cannot meet your requirement.

CCE supports pool-level full-port forwarding for dedicated ELB v3 instances. When enabled, the listener routes requests to the backend server using the same port number as the listener. Combined with a port-range listener, a single listener can cover an entire port range, forwarding each port to the identical port on the backend pod without requiring individual port mapping rules.

Features

Full-Port Forwarding Mechanism

Full-port forwarding is a backend server group-level attribute. When enabled, the listener routes requests to the backend server using the same port number as the listener.

Disabled (default): Traffic from all listener ports is forwarded to a fixed container port on the backend pod. For example, traffic from listener ports 80 and 81 is forwarded to the same backend pod port.
Enabled: The listener routes requests to the backend pod using the same port as the frontend port. Traffic from listener port 80 is forwarded to backend pod port 80, traffic from port 81 is forwarded to port 81, and so on.

Used with a Port-Range Listener

Full-port forwarding is typically used together with the port-range listener (kubernetes.io/elb.port-ranges) to enable a single listener to cover an entire port range and forward traffic from each port in the range to the corresponding port on the backend.

Capability	Annotation	Description
Port range listening	kubernetes.io/elb.port-ranges	A listener covers multiple ports (for example, 80-90).
All-port forwarding	kubernetes.io/elb.pools-options (any_port_enabled: true)	Automatic alignment between backend ports and listener ports.

When both features are combined, listener ports map one-to-one to backend pod ports by matching port number (for example, listener port 80 maps to backend port 80, 81 to 81, through 90 to 90). Requests on any port in the range are automatically forwarded to the corresponding port on the backend pod, without requiring individual forwarding rules.

Prerequisites

A CCE Turbo cluster is available, as this feature is not supported by other cluster types.
The cluster version must meet the following requirements:
- v1.30: v1.30.14-r100 or later
- v1.31: v1.31.14-r60 or later
- v1.32: v1.32.13-r30 or later
- v1.33: v1.33.12-r10 or later
- v1.34: v1.34.8-r10 or later
- v1.35: v1.35.5-r10 or later
- v1.36: v1.36.2-r0 or later
- Clusters of later versions

Constraints

This feature is available only for dedicated load balancers.
Only backend server groups using TCP, UDP, or QUIC support full-port forwarding. HTTP, HTTPS, and TLS are not supported.
Full-port forwarding can only be enabled during pool creation. After creation, this setting is immutable and cannot be modified through node pool settings.
Full-port forwarding depends on ELB capabilities. Before using this feature, submit a service ticket to enable the required ELB capabilities.

Configuring Full-Port Forwarding Using kubectl

Use kubectl to access the cluster. For details, see Accessing a Cluster Using kubectl.

Create a YAML file named service-fullport.yaml. The file name can be customized.

vi service-fullport.yaml

The following is an example YAML file for a Service associated with an existing load balancer:

  apiVersion: v1
   kind: Service
   metadata:
     name: test-fullport
     labels:
       app: test-app
     namespace: default
     annotations:
       kubernetes.io/elb.class: performance    # Load balancer type. Only dedicated load balancers are supported.
       kubernetes.io/elb.id: <your_elb_id>    # Load balancer ID. Replace it with the actual value.
       # Configure a listener for a port range from 80 to 90.
       kubernetes.io/elb.port-ranges: |
         {"cce-service-0":["80,90"]}
       # Configure full-port forwarding for the pool.
       kubernetes.io/elb.pools-options: |
         [{"protocol":"TCP","lb_algorithm":"ROUND_ROBIN","any_port_enabled":true}]
       # (Optional) Configure health check. When monitor_port is not specified, targetPort is used.
       kubernetes.io/elb.health-check-flag: 'on'
       kubernetes.io/elb.health-check-option: |
         {"protocol":"TCP","delay":"5","timeout":"10","max_retries":"3"}
   spec:
     selector:
       app: test-app
     externalTrafficPolicy: Cluster
     ports:
       - name: cce-service-0
         targetPort: 80          # When any_port_enabled is enabled, the forwarding port is determined by the listener port. targetPort is used for health checks when monitor_port is not specified.
         nodePort: 0
         port: 80                # Start port in the port range. The value must match that of port-ranges.
         protocol: TCP
     type: LoadBalancer

Key parameters:

kubernetes.io/elb.pools-options: the backend server group configuration, including the backend protocol, load balancing algorithm, and sticky sessions. The annotation value must be a JSON array.

After the kubernetes.io/elb.pools-options annotation is configured, the legacy annotations for load balancing algorithm (kubernetes.io/elb.lb-algorithm), sticky sessions (kubernetes.io/elb.session-affinity-option or kubernetes.io/elb.session-affinity-options), or backend protocol (kubernetes.io/elb.security-pool-protocol) cannot be used.

**Table 1** Parameters for configuring a backend server group
Parameter	Mandatory	Type	Description
protocol	Yes	String	The backend protocol. It specifies the protocol used by backend servers. Constraints: If the frontend protocol and port remain unchanged, this parameter cannot be modified. The custom configuration must match the protocol of the frontend listener. This restriction does not apply to the global configuration. Options: TCP, TLS, UDP, HTTP, HTTPS, and QUIC
lb_algorithm	Yes	String	The load balancing algorithm. Constraints: If the value is SOURCE_IP or QUIC_CID, the weight field of the backend server is invalid. The QUIC_CID algorithm is supported only when the protocol is QUIC. Options: ROUND_ROBIN: weighted round robin algorithm LEAST_CONNECTIONS: weighted least connections algorithm SOURCE_IP: source IP hash algorithm QUIC_CID: connection ID algorithm Default value: QUIC_CID when the backend protocol is QUIC; ROUND_ROBIN for other protocols.
any_port_enabled	No	Boolean	Enables or disables full-port forwarding. It determines whether the backend port matches the frontend listener port. Constraints: Only TCP, UDP, and QUIC support this parameter. Options: true: enabled. The backend port automatically aligns with the listener port. false: disabled. Requests are forwarded to the port specified by protocol_port.

kubernetes.io/elb.port-ranges

**Table 2** Parameters for listening to ports within a range
Parameter	Mandatory	Type	Description
kubernetes.io/elb.port-ranges	Yes	String	When using a dedicated load balancer with TCP, TLS, or UDP selected, you can create listeners that monitor ports within a range from 1 to 65535. Each listener supports a maximum of 10 non-overlapping port ranges. The parameter value is in the following format, where ports_name and port must be unique: '{"<ports_name_1>":["<port_1>,<port_2>","<port_3>,<port_4>"], "<ports_name_2>":["<port_5>,<port_6>","<port_7>,<port_8>"]}' For example, the port names are cce-service-0 and cce-service-1, and the listener listens to ports 100–200 and 300–400, and 500–600 and 700–800, respectively. '{"cce-service-0":["100,200", "300,400"], "cce-service-1":["500,600", "700,800"]}'

Create the Service.
```
kubectl create -f service-test.yaml
```
If information similar to the following is displayed, the Service has been created:
```
service/service-test created
```
Verify the full-port forwarding setting.
1. Log in to the CCE console and click the cluster name to access the cluster console.
2. In the navigation pane, choose Services and Ingresses. Locate the row containing the created Service and click the load balancer name to go to the ELB console.
3. Switch to the Listeners tab. Check whether a supplementary network interface is bound to the listener's backend server and whether the service port is displayed as full-port forwarding.

Configuring the Health Check Port

After full-port forwarding is enabled, if health checks are also enabled, you must configure the health check port. The health check port does not change dynamically with the listener port. A fixed port is required to detect the availability of backend services.

Rules for Choosing a Health Check Port

The rules for determining the health check port are as follows (in ascending order of priority):

Container port (lowest priority): If no health check port is specified, CCE automatically uses the targetPort (container port) of the Service as the health check port. When full-port forwarding is enabled, ensure that targetPort is a valid integer port number (for example, 80). Do not use a named port (for example, http). Otherwise, the default logic does not apply.
Configuring cce-healthz (medium priority): If the global health check configuration kubernetes.io/elb.health-check-option is used and the Service has a port named cce-healthz, the targetPort of the cce-healthz port is used as the health check port for all ports.
Configuring monitor_port (highest priority): If monitor_port is explicitly configured for a port using the kubernetes.io/elb.health-check-options annotation, the configured port number is used.

Configuration Examples

Method 1: If no health check port is specified, use targetPort as the health check port. For example, the health check port is 80.

annotations:
  kubernetes.io/elb.health-check-option: |
    {"protocol":"TCP","delay":"5","timeout":"10","max_retries":"3"}
spec:
  ports:
    - name: cce-service-0
      port: 80
      targetPort: 80               # Health check port = 80 (default)
      protocol: TCP

Method 2: Use the global health-check-option and cce-healthz. The example health check port is 8080.

annotations:
  kubernetes.io/elb.health-check-option: |
    {"protocol":"TCP","delay":"5","timeout":"10","max_retries":"3"}
spec:
  ports:
    - name: cce-service-0          # Service port
      port: 80
      targetPort: 80
      protocol: TCP
    - name: cce-healthz            # Health check port. The name must be cce-healthz.
      port: 80
      targetPort: 8080             # The health check will detect this port.
      protocol: TCP

Method 3: Customize the health check and explicitly configure monitor_port. The following uses port 8080 as an example.

annotations:
  kubernetes.io/elb.health-check-options: |
    [{"target_service_port":"TCP:80","protocol":"TCP","delay":"5","timeout":"10","max_retries":"3","monitor_port":"8080"}]