Architecture
How K3s fits together — server, agent, control plane, and data store.
Server / Agent Model
Server nodes
Run the control plane components: API server, scheduler, controller manager, and the embedded data store. They execute the kubelet and run user workloads as well.
Agent nodes
Worker nodes that join a server. Only run kubelet, kube-proxy, and the container runtime (containerd). No control plane components — reducing surface area and memory footprint.
Mixed mode
A single-node K3s cluster runs both server and agent roles in the same process. For HA, you'll want 3+ dedicated server nodes plus agents for workloads.
Single Binary Design
What's combined
API server, scheduler, controller-manager, kubelet, kube-proxy, container runtime, CNI flannel, Traefik, local-path storage — all into one ~70MB binary.
Why this matters
Fewer moving parts to install, configure, and patch. CVE fixes ship in a single place. You can replace the binary and systemctl restart to upgrade everything.
Trade-off
Slightly opinionated — K3s ships defaults that 'just work'. For maximum flexibility (custom CNI, alternate ingress), upstream Kubernetes still wins.
Data Store
SQLite (default)
Embedded database. Simple, fast, single-server. Suitable for single-node and dev clusters. Bound to a single server.
etcd3
Use etcd3 for HA clusters with 3+ server nodes. Automatic quorum, leader election, proper raft protocol.
Postgres (experimental)
Newer option for very large clusters where SQLite becomes a bottleneck.
Process Model
Parent process
The K3s binary forks into multiple child processes; the parent supervises them and restarts on crash.
Namespacing
Pods run in their standard kernel namespaces. Control plane runs in containerd alongside user workloads.
cgroups
K3s supports both cgroup v1 and cgroup v2. Auto-detected at startup; transparent to the user.