k3s

What this skill does

# k3s - Lightweight Kubernetes Distribution

## Overview

k3s is a fully CNCF-certified Kubernetes distribution packaged as a **single self-contained binary** (≈70 MB). One executable is the control plane, the kubelet, the container runtime supervisor, and a multicall wrapper for `kubectl`/`crictl`/`ctr`. You run `k3s server` to start a control-plane node and `k3s agent` to start a worker; everything else (etcd or SQLite, networking, DNS, ingress, load balancing, storage) is bundled and started for you.

**What k3s bundles (and manages for you):**
- **containerd** — the embedded CRI runtime (no Docker needed; `--docker` to opt into cri-dockerd is deprecated)
- **flannel** — the default CNI (`--flannel-backend`: `vxlan` default, `host-gw`, `wireguard-native`, or `none`)
- **CoreDNS** — cluster DNS (deployed component `coredns`)
- **Traefik** — ingress controller (deployed component `traefik`)
- **ServiceLB / Klipper** — a built-in `LoadBalancer` service implementation (component `servicelb`)
- **local-path-provisioner** — default `local-path` StorageClass (component `local-storage`)
- **metrics-server** — resource metrics (component `metrics-server`)
- **SQLite by default**, with **embedded etcd** (for HA) or an **external datastore** (MySQL/Postgres/etcd/NATS) as alternatives

**Key characteristics:**
- **Single binary, single process tree** — `k3s server`/`k3s agent` supervise all components
- **Batteries-included** — a working cluster (ingress, LB, DNS, storage) right after install
- **Config in one place** — `/etc/rancher/k3s/`: `config.yaml`, `k3s.yaml` (kubeconfig), `registries.yaml`
- **Easy to slim down** — `--disable` any bundled component to bring your own

> **Disambiguation:** This skill is about the **k3s distribution and its `k3s` CLI** — installation, the `server`/`agent` lifecycle, bundled components, tokens, etcd snapshots, certs. It does **not** teach generic Kubernetes or `kubectl` usage; for that, use Kubernetes documentation. Anything k3s-specific (what it adds, bundles, or changes) belongs here.

## When to Use This Skill

Use this skill when:
- **Installing k3s**: the `curl -sfL https://get.k3s.io | sh -` installer and `INSTALL_K3S_*` env vars
- **Bootstrapping a cluster**: single-server, HA with embedded etcd, or an external datastore
- **Joining nodes**: agents (workers) or additional servers via `K3S_URL` + `K3S_TOKEN`
- **Slimming the stack**: `--disable traefik`, `--disable servicelb`, `--flannel-backend=none`, etc.
- **Day-2 operations**: etcd snapshots, certificate rotation, secrets encryption, token rotation
- **Restricted environments**: airgap installs, private/mirror registries (`registries.yaml`)
- **Remote API access**: adding SANs (`--tls-san`) and a readable kubeconfig (`--write-kubeconfig-mode`)
- **Upgrading / uninstalling**: re-running the installer, channels, the bundled uninstall scripts

## Prerequisites

**CRITICAL**: Before proceeding, verify k3s is installed and check the version:

```bash
k3s --version          # prints e.g. "k3s version v1.32.1+k3s1 (…)"
```

**Version note:** This skill is documented against the k3s source at **v1.35.0+k3s1**. Long-standing flags and paths work on any recent k3s; features added in a specific release are annotated inline as `(k3s vX.Y+)`. The "Since" marker is the **first minor cycle** a feature shipped in (k3s backports features to all supported minor lines, so an older patch release may also have it). Always confirm flags on the running version with `k3s server --help` / `k3s agent --help`.

**If k3s is not installed:** do **NOT** silently auto-install on someone's machine. k3s installs a systemd service and modifies the host — confirm intent first, then use the official installer (see [Install](#install)). The canonical install is:

```bash
curl -sfL https://get.k3s.io | sh -
```

**Where things live (memorize these):**
| Path | What |
|------|------|
| `/etc/rancher/k3s/k3s.yaml` | Admin kubeconfig written by the server (root-owned `0600` by default) |
| `/etc/rancher/k3s/config.yaml` | Server/agent config file (see [Configuration File](#configuration-file)) |
| `/etc/rancher/k3s/registries.yaml` | Private/mirror registry config |
| `/var/lib/rancher/k3s` | Data dir (`--data-dir`/`-d`); `${HOME}/.rancher/k3s` when run non-root |
| `/var/lib/rancher/k3s/server/db/` | Datastore (SQLite/etcd) |
| `/var/lib/rancher/k3s/server/db/snapshots/` | Default etcd snapshot directory |
| `/var/lib/rancher/k3s/server/node-token` | Token agents use to join (read on the first server) |

## Install

The installer script detects systemd/openrc, installs the binary, writes a service, and starts it. Configure it entirely through **environment variables** (set them before the pipe):

```bash
# Latest stable, server (control-plane) node — default behavior
curl -sfL https://get.k3s.io | sh -

# Pin a channel or exact version
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=latest sh -
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.32.1+k3s1 sh -

# Pass server flags through INSTALL_K3S_EXEC
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable traefik --tls-san k8s.example.com" sh -

# Install an AGENT and join an existing server
curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=<node-token> sh -
```

**Key installer variables** (all verified in `install.sh`):
| Variable | Purpose |
|----------|---------|
| `INSTALL_K3S_EXEC` | Args/subcommand passed to the k3s service (e.g. `server --disable traefik`) |
| `INSTALL_K3S_CHANNEL` | Release channel: `stable` (default), `latest`, `testing` |
| `INSTALL_K3S_VERSION` | Exact version to install (e.g. `v1.32.1+k3s1`) |
| `INSTALL_K3S_SKIP_DOWNLOAD` | `true` = don't fetch the binary (airgap — you stage it yourself) |
| `INSTALL_K3S_SKIP_START` | `true` = install but don't start the service |
| `INSTALL_K3S_SKIP_ENABLE` | `true` = don't enable the service at boot |
| `INSTALL_K3S_BIN_DIR` | Install dir for the binary, links, and uninstall script |
| `INSTALL_K3S_SYMLINK` | `skip` to avoid the `kubectl`/`crictl`/`ctr` symlinks |
| `INSTALL_K3S_NAME` | Suffix for the service name (run multiple k3s instances) |

`K3S_URL` + `K3S_TOKEN` make the installer set up an **agent** by default; without `K3S_URL` it installs a **server**.

> The installer also creates uninstall scripts: **`/usr/local/bin/k3s-uninstall.sh`** (server) and **`/usr/local/bin/k3s-agent-uninstall.sh`** (agent). See [recipes.md](references/recipes.md#uninstall) for upgrade and uninstall flows.

## The `k3s` Binary: Subcommand Map

`k3s` is a multicall binary — symlinks named `kubectl`/`crictl`/`ctr` invoke those passthroughs directly.

| Subcommand | Purpose |
|------------|---------|
| `k3s server` | Run a control-plane node (also runs an agent unless `--disable-agent`) |
| `k3s agent` | Run a worker node; needs `K3S_URL` + a token |
| `k3s kubectl` | Bundled kubectl (args forwarded verbatim) |
| `k3s crictl` | Bundled crictl (CRI debugging) |
| `k3s ctr` | Bundled containerd `ctr` |
| `k3s token` | Manage join tokens: `create`, `delete`, `generate`, `list`, `rotate` |
| `k3s etcd-snapshot` | Manage embedded-etcd snapshots: `save`, `ls`, `delete`, `prune` |
| `k3s secrets-encrypt` | Secrets-at-rest encryption: `status`, `enable`, `disable`, `prepare`, `rotate`, `reencrypt`, `rotate-keys` |
| `k3s certificate` | Component certs: `check`, `rotate`, `rotate-ca` |
| `k3s check-config` | Validate the host's kernel/config for k3s |
| `k3s completion` | Shell completion (`bash`/`zsh`, `-i` to install) |

Global flags on the root app: `--debug` (env `K3S_DEBUG`) and `--data-dir`/`-d` (env `K3S_DATA_DIR`).

## Core Workflows

### 1. Single-server cluster + get the kubeconfig

```bash
# Start a server (the installer does this; here's the equivalent direct invocation)
k3s server

# The admin kubeconfig is written here:
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
k3s kubectl get nodes
```

The kubeconfig is root-owned `0600` by default. To make it readable by