How to Set Up K3s High Availability Cluster

K3s supports high availability (HA) by running multiple server nodes with an embedded etcd datastore. This ensures your cluster stays operational even if a control plane node fails.

Prerequisites

• Three Breeze instances with at least 2 GB RAM each (for server nodes)
• Network connectivity between all nodes on port 6443 and 2379-2380
• Ubuntu 22.04 or similar Linux distribution

Initialize the First Server

Start the first K3s server node with embedded etcd:

curl -sfL https://get.k3s.io | K3S_TOKEN=mySecretToken sh -s - server \
  --cluster-init \
  --tls-san=lb.example.com

The --cluster-init flag enables embedded etcd for HA mode.

Join Additional Server Nodes

On the second and third server nodes, join the existing cluster:

curl -sfL https://get.k3s.io | K3S_TOKEN=mySecretToken sh -s - server \
  --server https://node1-ip:6443 \
  --tls-san=lb.example.com

Add Worker Nodes

curl -sfL https://get.k3s.io | K3S_TOKEN=mySecretToken sh -s - agent \
  --server https://lb.example.com:6443

Load Balancer Configuration

Place a TCP load balancer in front of your server nodes on port 6443:

• Use HAProxy or Nginx stream module to distribute API requests
• Health check each node at /readyz on port 6443
• Point the --tls-san to your load balancer hostname

Verify the Cluster

kubectl get nodes
kubectl get endpoints -n kube-system