Self-hosted K3s lightweight Kubernetes distribution. This skill should be used when installing or configuring K3s clusters, setting up server/agent nodes, configuring HA with embedded etcd, disabling default components (traefik, servicelb, flannel), replacing Flannel with custom CNI (Calico/tigera-operator, Cilium), configuring private registries (registries.yaml), deploying in airgapped/air-gapped environments (image pre-loading, INSTALL_K3S_SKIP_DOWNLOAD), managing K3s server flags (--cluster-cidr, --service-cidr, --flannel-backend=none, --disable-network-policy), writing /etc/rancher/k3s/config.yaml, troubleshooting containerd/kubelet issues, or integrating K3s with NixOS modules. Covers single-node and multi-node topologies.
K3s is a CNCF-certified Kubernetes distribution built for edge, IoT, and resource-constrained environments. Single binary (~70MB), embeds containerd, SQLite (single-node) or etcd (HA).
| Path | Purpose |
|---|---|
/etc/rancher/k3s/config.yaml | Server/agent configuration |
/etc/rancher/k3s/config.yaml.d/*.yaml | Drop-in config fragments |
/etc/rancher/k3s/registries.yaml | Private registry mirrors + auth |
/etc/rancher/k3s/k3s.yaml | Kubeconfig (default mode 0600) |
/var/lib/rancher/k3s/ | K3s state directory |
/var/lib/rancher/k3s/agent/images/ | Airgap image tarballs |
/var/lib/rancher/k3s/agent/containerd/ | Containerd runtime data |
/var/lib/rancher/k3s/server/manifests/ | Auto-deploy manifests |
# Standard install
curl -sfL https://get.k3s.io | sh -
# With options
curl -sfL https://get.k3s.io | K3S_TOKEN=SECRET sh -s - server \
--cluster-init --write-kubeconfig-mode=0644 --disable=traefik
# Agent join
curl -sfL https://get.k3s.io | K3S_TOKEN=SECRET K3S_URL=https://server:6443 sh -
# Airgap (binary pre-placed)
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh
| Flag | Default | Purpose |
|---|---|---|
--flannel-backend | vxlan | Set to none for custom CNI |
--disable | — | Skip bundled components (traefik, servicelb, local-storage) |
--disable-network-policy | false | Required when using external CNI |
--cluster-cidr | 10.42.0.0/16 | Pod network CIDR |
--service-cidr | 10.43.0.0/16 | Service network CIDR |
--cluster-init | false | Enable embedded etcd for HA |
--write-kubeconfig-mode | 0600 | Kubeconfig file permissions |
--data-dir | /var/lib/rancher/k3s | State directory |
--tls-san | — | Additional SANs for API server cert |
Disable Flannel and built-in network policy to use external CNI:
# /etc/rancher/k3s/config.yaml
flannel-backend: "none"
disable-network-policy: true