Install K3s

Single command, multiple platforms. Pick the install that matches your environment.

Quick Install (Linux)

The standard install script — works on any modern Linux distribution (Ubuntu, Debian, CentOS, RHEL, Alpine, etc.):

curl -sfL https://get.k3s.io | sh -
sudo k3s kubectl get node

Verify the Install

Check that node shows as Ready and that pods are running:

# Wait ~30 seconds for the node to become Ready
sudo k3s kubectl get node
sudo k3s kubectl get pods -A

# Save kubeconfig for non-root access
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config

Add a Worker Node

From a second machine, install K3s in agent mode and join the cluster:

# On the server, get the cluster token
sudo cat /var/lib/rancher/k3s/server/node-token

# On the second machine (replace SERVER_IP and NODE_TOKEN):
curl -sfL https://get.k3s.io | K3S_URL=https://SERVER_IP:6443 \
  K3S_TOKEN=NODE_TOKEN sh -

Install by Platform

🐧 Linux (Standard)

Any modern Linux with systemd. Works on servers, VMs, cloud instances.

🍎 macOS

K3s runs on macOS via multipass VM or via Lima — ideal for local development.

🍓 Raspberry Pi

ARMv7 / ARM64 binaries. K3s on Pi 4 with 2GB+ RAM runs production workloads.

🔌 Air-Gapped

Offline install with private registries and pre-downloaded images (link below).

🐳 Docker (k3d)

k3d creates K3s clusters inside Docker — perfect for local dev or CI.

☁️ Managed (Rancher)

Use Rancher or Imported Existing Cluster for centralized fleet management.

Air-Gapped Install

For installations with no internet access — pre-download the install script, binary, and image tarball:

1. Prepare the air-gap bundle (online machine)

# Download the install script
curl -sfL https://get.k3s.io -o install.sh

# Get the binary (architecture-specific)
# ⚠️ 下面 GitHub Releases URL 是真实下载源（air-gap 镜像无法本地化）
# 所有架构列表和最新版本号见 /k3s/docs/operations/ → Upgrading K3s 部分
curl -fL -o k3s https://github.com/k3s-io/k3s/releases/latest/download/k3s
# For ARM64:
curl -fL -o k3s https://github.com/k3s-io/k3s/releases/latest/download/k3s-arm64

# Get the image tarball (amd64)
# ⚠️ 镜像打包细节见 /k3s/docs/operations/
curl -fL -o k3s-airgap-images-amd64.tar https://github.com/k3s-io/k3s/releases/latest/download/k3s-airgap-images-amd64.tar
mkdir -p /var/lib/rancher/k3s/agent/images/
cp k3s-airgap-images-amd64.tar /var/lib/rancher/k3s/agent/images/

2. Install offline

# Transfer install.sh, k3s binary, and image tarball to the target.
# Then:
chmod +x k3s
sudo cp k3s /usr/local/bin/k3s
sudo INSTALL_K3S_SKIP_ENABLE=true ./install.sh

3. Configure private registry

For private registry, create /etc/rancher/k3s/registries.yaml before starting the service:

mirrors:
  docker.io:
    endpoint:
      - "https://your.private.registry:5000"
configs:
  "your.private.registry:5000":
    auth:
      username: your_user
      password: your_pass
    tls:
      insecure_skip_verify: true

4. Start the service

sudo systemctl enable --now k3s
sudo k3s kubectl get node

Upgrade an Existing Cluster

Method 1: Install Script (server node)

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

Method 2: System Upgrade Controller (automated rolling)

For fleet-wide upgrades without downtime, use the system-upgrade controller to roll servers and agents in waves:

# Apply the controller manifests
kubectl apply -f /k3s/docs/operations/  # 详见 operations 文档中的 controller 部署片段
# Apply a plan
kubectl apply -f /path/to/upgrade-server-plan.yaml  # 见 /k3s/docs/operations/

Next: Deploy Your First App

With K3s installed, deploy a sample workload to verify the cluster:

sudo k3s kubectl create deployment nginx --image=nginx
sudo k3s kubectl expose deployment nginx --port=80 --type=NodePort
sudo k3s kubectl get svc nginx
# Access via http://&lt;node-ip&gt;:<NodePort>

# Or use the bundled Traefik ingress:
# create an Ingress resource pointing to the nginx service on host "demo.local"

→ See documentation index