k3s(8)
k3s is a lightweight Kubernetes distribution that bundles the entire Kubernetes control plane and worker components into a single binary with minimal dependencies.
Synopsis
k3s [COMMAND] [OPTIONS]Description
k3s is a minimal, production-ready Kubernetes distribution designed for resource-constrained environments, IoT devices, and edge computing. It combines the API server, scheduler, controller manager, kubelet, and container runtime into a single executable, reducing memory footprint and complexity.
Common commands include server (run a control plane node), agent (run a worker node), and kubectl (manage the cluster). k3s automatically manages networking with Flannel and storage with local-path provisioner by default.
Common options
| Flag | What it does |
|---|---|
--server VALUE, -s VALUE | URL of the k3s server to connect to (used by agents) |
--token VALUE, -t VALUE | Cluster token for authentication between nodes |
--cluster-init | Initialize a new cluster (run on the first server node) |
--flannel-backend VALUE | Flannel backend for networking (vxlan, host-gw, none) |
--disable VALUE | Disable optional features (e.g., traefik, servicelb, local-storage) |
--node-name VALUE | Kubernetes node name (defaults to hostname) |
--docker | Use Docker as the container runtime instead of containerd |
--write-kubeconfig VALUE | Path to write kubeconfig file |
--data-dir VALUE, -d VALUE | Directory to store Kubernetes data (default /var/lib/rancher/k3s) |
--bind-address VALUE | Address for k3s server to bind to |
Examples
Start a single-node k3s control plane and worker; downloads to /usr/local/bin/k3s and runs immediately
k3s serverInitialize a new HA cluster on the first control plane node with a custom node name
k3s server --cluster-init --node-name master-1Join a worker node to an existing k3s cluster by providing server URL and cluster token
k3s agent --server https://192.168.1.10:6443 --token mytokenList all nodes in the cluster using the bundled kubectl
k3s kubectl get nodesStart k3s without the Traefik ingress controller and service load balancer
k3s server --disable traefik --disable servicelbRun k3s with Docker runtime and host-gateway Flannel networking
k3s server --docker --flannel-backend host-gwDownload and install k3s from the official installer script
curl -sfL https://get.k3s.io | sh -Start k3s with custom data directory and bind to all network interfaces
k3s server --data-dir /var/k3s --bind-address 0.0.0.0