K3s — Overview#

Identity#

Purpose#

K3s is a fully conformant, production-ready Kubernetes distribution packaged as a single binary under 100 MB. It targets resource-constrained environments — edge computing, IoT, CI, ARM devices — where the full Kubernetes operational burden is impractical. It achieves its lightweight footprint by running many Kubernetes components inside a single process, substituting SQLite for etcd by default, and removing in-tree cloud provider and storage drivers.

Significance#

K3s is a CNCF (Cloud Native Computing Foundation) project with millions of downloads and wide adoption across edge/IoT deployments and development environments. It is the canonical example of a Kubernetes distribution in the Go ecosystem: it demonstrates how to bundle, fork, and maintain a large upstream project while staying closely aligned with upstream releases. Its approach of packaging containerd, Flannel, CoreDNS, Traefik, and etcd into a single launcher influenced how the community thinks about lightweight Kubernetes. The project tracks upstream k8s releases with patch releases within one week, making it a reference for distribution engineering discipline.

Key metrics#

  • Go files: 323 (excluding vendor)
  • Top-level directories: cmd, contrib, docs, manifests, package, pkg, scripts, tests, updatecli
  • Direct dependencies: ~108 (first require block) — dominated by the entire k8s.io stack, containerd, etcd, flannel, and Rancher ecosystem packages
  • replace directives: 70+ — most k8s.io/* and several containerd/* packages are redirected to k3s-io forks to carry downstream patches
  • First commit / age: Project began ~2019 (Rancher Labs, now CNCF)

Notable characteristics#

  • Single-binary distribution model: All components (server, agent, kubectl, crictl, ctr) are embedded in one binary via a multi-call executable pattern — the binary’s behavior changes based on argv[0] or the first argument.
  • Extensive replace-directive engineering: The go.mod contains 70+ replace directives pointing to github.com/k3s-io/* forks of Kubernetes, etcd, containerd, klog, and other components. This is the primary mechanism for carrying K3s-specific patches on top of upstream code.
  • Kine for storage abstraction: Uses the k3s-developed Kine library as an etcd shim, enabling SQLite, MySQL, MariaDB, and Postgres as backing stores — a significant architectural departure from vanilla Kubernetes.
  • Small original codebase relative to impact: With only 323 Go files, K3s’s own source code is compact; the distribution’s complexity is almost entirely in the orchestration of bundled upstream components and their patched forks.
  • P2P image distribution via libp2p: Integrates Spegel (a libp2p-based distributed OCI registry mirror) directly into the node agent, enabling cluster-local image distribution without a central registry.
Backward Dapr — Testing K3s — Structure Forward