Control Plane Load Balancer (CPLB)New#

Warning

Public cloud providers do not support L2 load balancing. If you are using a public cloud, refer to the official documentation for your cloud provider for instructions on how to deploy a load balancer that satisfies the MKE 4 load balancer requirements.

The Control Plane Load Balancer (CPLB) is built into MKE 4 as of version 4.2.0. It provides a virtual IP address (VIP) that serves as a stable endpoint for the MKE 4 manager nodes, ensuring high availability across control plane nodes. When enabled, CPLB automatically manages traffic distribution so that clients can reach MKE even if individual control plane nodes become unavailable.

Important

To work with CPLB you must have the mke4.yaml configuration file. If you are already running an MKE 4 cluster, you can run mkectl config get to obtain the file. Otherwise, refer to Getting Started.

Enable CPLB#

To enable CPLB in your MKE 4 cluster:

In the mke4.yaml configuration file, add the following controlPlaneLoadBalancing section under spec.network:

spec:
  network:
    controlPlaneLoadBalancing:
      enabled: true
      virtualIPs: ["<VIP address>/<netmask>"] # for instance ["172.16.0.100/16"]

Point the MKE 4 cluster to the CPLB. To do this, set .spec.apiServer.externalAddress to the desired virtual IP address (VIP) with the chosen HTTPS Gateway ingress node port for MKE 4 (33001 by default).

A user-defined CIDR address for the VIP address must be routable in the network. For most installations, this is in the same CIDR as the physical interface.
Apply the configuration:
```
mkectl apply -f mke4.yaml
```

Important

As MKE 4 is not aware of external IP address management, the administrator is responsible for ensuring that IP addresses do not collide.

Example of a fully configured CPLB:

spec:
  apiServer:
    externalAddress: "172.16.0.100:33001"  # CPLB VIP + HTTPS Gateway ingress node port
  gatewayMKEIngress:
    nodePorts:
      https: 33001
  network:
    controlPlaneLoadBalancing:
      enabled: true
      virtualIPs:
        - 172.16.0.100/16

Configure multiple load balancers#

When you define multiple VIPs for CPLB, MKE 4 only trusts the one you set to the external address. You can, though, include additional VIPs in the trust chain.

Add the additional VIPs to the mke4.yaml configuration file under spec.apiServer.sans:

spec:
  apiServer:
    sans:
    - <alternative VIP address 1>
    - <alternative VIP address 2>

Apply the configuration:
```
mkectl apply -f mke4.yaml
```

Switch from one load balancer to another#

To switch from one external address to another, you must insert the original load balancer VIP/FQDN into the mke4.yaml configuration file under spec.apiServer.sans.

As an example, to switch from the CPLB to an external load balancer:

In the mke4.yaml configuration file, edit the spec.apiServer settings as follows:

From:

spec:
  apiServer:
    externalAddress: "172.16.0.100:33001"

To:

spec:
  apiServer:
    externalAddress: "new-lb.com"
    sans:
    - 172.16.0.100  # include the old VIP external address to make sure it remains trusted during the transition;
                    # the new external address will be trusted automatically

Apply the configuration:
```
mkectl apply -f mke4.yaml
```
Optional. Remove the original load balancer address from the list of trusted SANs, and run mkectl apply again.

Configure custom TLS#

To use custom TLS certificates, you must provide a domain name for where the custom TLS certificates will be served. Be aware that you cannot use the raw CPLB VIP address as this domain, as the custom TLS feature relies on the TLS SNI extension, which selects the certificates based on a DNS hostname and not an IP address.

If you control DNS resolution in your environment, create an A record that points your desired hostname to the CPLB VIP, then use that hostname as the domain name for custom TLS certificates.

Tip

Refer tio the k0s Control Plane Load Balancing documentation for troubleshooting information.