Master K3s: Complete Guide to Install, Configure, and Scale Lightweight Kubernetes

1. Introduction to K3s

K3s is a lightweight, CNCF‑certified Kubernetes distribution optimized for edge computing, IoT, and resource‑constrained environments. It packages the control‑plane, kubelet, and containerd into a single binary, reducing memory and storage requirements.

2. Key Features

Single‑binary deployment (includes Kubernetes master, kubelet, and containerd)

Supports x86_64, ARM64, and ARMv7 architectures

Built‑in SQLite store with optional MySQL, PostgreSQL, or external etcd

Default secure configuration with automatic certificate rotation

Embedded control‑plane components in one process

Minimal external dependencies – only a recent Linux kernel and cgroup support are required

3. Installation Guide

3.1 Server Installation

# Install K3s server (default stable channel)
curl -sfL https://get.k3s.io | sh -

# Install a specific version
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.23.6+k3s1 sh -

# Install with external datastore (example MySQL)
curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=true sh -s - server \
    --datastore-endpoint="mysql://root:password@tcp(10.0.0.10:3306)/k3s"

3.2 Agent Installation

# Join a node as an agent
curl -sfL https://get.k3s.io | K3S_URL=https://<server_ip>:6443 K3S_TOKEN=<token> sh -

4. Configuration Options

Datastore: Use embedded SQLite, external MySQL/PostgreSQL, or etcd. Set with --datastore-endpoint or K3S_DATASTORE_ENDPOINT.

Network CNI: Default is Flannel (VXLAN backend). Change with --flannel-backend=host-gw, ipsec, or wireguard. Disable Flannel with --flannel-backend=none to use a custom CNI such as Calico.

TLS and Certificates: Automatic rotation after 90 days. Use --tls-san to add additional SANs.

Image Registry: Configure private mirrors via /etc/rancher/k3s/registries.yaml. Supports multiple mirrors, authentication, and TLS settings.

Service Load Balancer: Built‑in Klipper LB provides LoadBalancer services without cloud provider integration.

5. Networking Components

CoreDNS: Deployed by default for cluster DNS. Disable with --disable coredns and provide an alternative DNS solution.

Traefik Ingress Controller: Default ingress controller listening on ports 80/443. Disable with --disable traefik and replace with a custom ingress.

Service Load Balancer: Klipper LB creates LoadBalancer services using host ports.

6. Persistent Storage

Local Path Provisioner (LPP): Provides local-path storage class using hostPath volumes. Example PVC and pod definitions are included.

Longhorn: Distributed block storage for Kubernetes. Install with

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/master/deploy/longhorn.yaml

and use the longhorn storage class.

7. Helm Integration

Helm works out‑of‑the‑box with K3s. Manifests placed in /var/lib/rancher/k3s/server/manifests are automatically applied. HelmChart CRDs allow declarative Helm releases, e.g., deploying Grafana with custom values.

8. Upgrading K3s

Manual upgrade via install script: curl -sfL https://get.k3s.io | sh - (supports channel and version flags).

Binary upgrade: replace /usr/local/bin/k3s with the new binary and restart the service.

Automated upgrade using system-upgrade-controller and Plan resources for server and agent nodes.

9. Backup and Restore

Embedded SQLite: Copy /var/lib/rancher/k3s/server/db or use sqlite3 backup/restore commands.

External Datastore: Perform regular dumps (e.g., mysqldump) and restore before starting K3s.

Embedded etcd: Use built‑in snapshot mechanism ( --etcd-snapshot-schedule-cron) and restore with --cluster-reset --cluster-reset-restore-path.

10. Additional Resources

K3s official documentation (English and Chinese)

GitHub repository: https://github.com/k3s-io/k3s

Related projects: k3os, autok3s, k3d, Harvester, Octopus