How to Use K3s: The Beginner's Guide

CodexFuse Team · 2026-10-31T15:19:29.585Z · 13 min read

Learn how to use K3s: install lightweight Kubernetes with one command, apply the kubeconfig rule, add a worker node, and deploy your first app.

How to Use K3s: The Beginner's Guide (First Install, First Node, the kubeconfig Rule)

Learning how to use K3s is the shortest path from "Kubernetes sounds intimidating" to a running cluster you own. K3s is a lightweight, fully conformant Kubernetes distribution built by Rancher Labs (now SUSE) that packages the entire control plane into a single ~70 MB binary — no cloud account, no managed bill, no multi-day setup. This K3s tutorial takes you from a blank Linux server to your K3s first cluster, through the kubeconfig rule everyone trips over, to adding a worker node and deploying your first app behind Traefik ingress. If containers already make sense to you from the Docker beginner guide, this is the natural next step: orchestration.

What is K3s?

K3s is real Kubernetes with the weight removed — a CNCF-conformant distribution that strips legacy components, packages everything into one small binary, and swaps etcd for embedded SQLite on single-node setups, so a full cluster runs comfortably on a small VPS or a Raspberry Pi. For beginners it matters because you learn genuine Kubernetes skills (kubectl, Deployments, Ingress, Helm) without first learning how to babysit a control plane. This guide is a k3s for beginners walkthrough: install, verify, kubeconfig, worker join, first deployment, first ingress, and Helm — the complete first arc in one sitting.

What do you need before you install K3s?

You need one Linux server and realistic expectations about its size. The official minimums are 2 CPU cores and 2 GB of RAM for a server node, and 1 core with 512 MB for an agent node — K3s runs on x86_64, armhf, and arm64/aarch64, so ARM boxes like the Raspberry Pi are supported. Two rules are non-negotiable: every node must have a unique hostname, and port 6443 must be reachable between nodes. Start with a small server — the what is VPS hosting guide explains the landscape, and cheap VPS hosting options give you a 1 GB box for pocket change — and connect to it over SSH (generate a proper key pair with an SSH key generator rather than password login).

How do you install K3s in one command?

You install K3s with the official script — but you verify the script before you pipe it, because curl | sh from the internet is a trust decision. Follow these seven steps:

1. Download the script and read it. Run curl -sfL https://get.k3s.io -o install-k3s.sh, then open it in an editor or pager. It is the official installer (documented at docs.k3s.io), and reading it once teaches you more about the install than any tutorial.
2. Pick your version deliberately. By default you get the latest channel release; to pin one, set INSTALL_K3S_VERSION="v1.36.5+k3s1" (the stable channel release verified on 2026-10-31; the newest release line is v1.37.1+k3s1, published 2026-09-30). Pinning matters because the newest line is where fresh bugs live.
3. Run the installer on your first server. With the script verified, run it: curl -sfL https://get.k3s.io | sh -. In about thirty seconds you have a fully functional single-node Kubernetes cluster — the service is configured to restart automatically after reboots or crashes.
4. Confirm the node is Ready. The installer ships its own kubectl: sudo k3s kubectl get nodes should list your server as Ready.
5. Check the system pods. sudo k3s kubectl get pods -A shows Traefik, CoreDNS, and the local-path provisioner all running — these are bundled with K3s, not something you install separately.
6. Copy the kubeconfig (the kubeconfig rule). K3s writes its kubeconfig to /etc/rancher/k3s/k3s.yaml, readable only by root. Copy it to ~/.kube/config and take ownership so plain kubectl works without sudo — see the kubeconfig section below.
7. Verify from your laptop. With the kubeconfig in place, kubectl get nodes from your own machine should show the same cluster. If it does, the cluster is yours.

What does the K3s installer put on your server?

The installer is heavier than the marketing suggests — in a good way. Alongside the cluster it installs the kubectl, crictl, and ctr utilities plus the k3s-killall.sh and k3s-uninstall.sh helper scripts, and registers K3s as a systemd service that survives reboots and process crashes. A single-node server install is a fully functional Kubernetes cluster on its own: datastore, control plane, kubelet, and container runtime, all on one machine, with the datastore running as embedded SQLite instead of etcd. That is the whole trick — one binary, one command, and the ceremony of a multi-node control plane simply does not exist until you decide you want it.

How do you know your K3s first cluster is healthy?

A healthy cluster answers three commands cleanly. First, kubectl get nodes shows your server node as Ready with the version string like v1.36.5+k3s1. Second, kubectl get pods -A shows every pod in kube-system (Traefik, CoreDNS, local-path-provisioner, metrics-server) in Running state — nothing stuck in Pending or CrashLoopBackOff. Third, kubectl cluster-info prints the API server address responding on port 6443. If all three pass, your K3s first cluster is genuinely up; the remaining sections are about using it, not fixing it.

What is the kubeconfig rule?

The kubeconfig rule is simple: K3s writes its admin kubeconfig to /etc/rancher/k3s/k3s.yaml, and the kubectl bundled with K3s uses it automatically — but every other kubectl on earth looks at ~/.kube/config, so nothing else works until you copy it. Run these two lines once per server:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config

Set KUBECONFIG=~/.kube/config (or export it in your shell profile) and plain kubectl now talks to your cluster. Copying the file to your laptop is how you manage the cluster from home — just edit the server: line in the copied file to point at your server's public IP or DNS name. Think of this as the k3s kubeconfig rule: the admin file lives at /etc/rancher/k3s/k3s.yaml on the server, and ~/.kube/config everywhere else. This is also the step Helm needs: K3s's own docs note that Helm requires no special configuration "just be sure you have properly set the kubeconfig path" — get this rule right and Helm works on the first try.

How do you add a worker node to K3s?

Adding a worker node is the same install script with two environment variables and one secret. On your server node, read the join token K3s generated at install time:

sudo cat /var/lib/rancher/k3s/server/node-token

Then on the fresh worker server (unique hostname, remember), run the installer as an agent:

curl -sfL https://get.k3s.io | K3S_URL=https://SERVER_IP:6443 K3S_TOKEN=PASTE_TOKEN_HERE sh -

Setting K3S_URL is what flips the installer from server mode into agent mode: the agent registers with the server over a websocket on port 6443 and shows up in kubectl get nodes within seconds. Behind the scenes the agent also generates its own node password, stored locally and hashed into a Kubernetes secret, so a stolen token alone cannot re-register a node under a false identity. That is the whole k3s add worker node flow — one command per worker, token in hand.

How do you deploy your first app on K3s?

You deploy your first app the same way you would on any Kubernetes cluster: write a Deployment manifest and apply it. This nginx example is the canonical first deployment because it proves scheduling, networking, and the container runtime all work:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:stable
        ports:
        - containerPort: 80

Apply it with kubectl apply -f nginx.yaml, then watch kubectl get pods until both replicas are Running. Verify it serves traffic without any ingress yet: kubectl port-forward deployment/nginx 8080:80 and open http://localhost:8080 — if you see the nginx welcome page, your cluster runs real workloads. Delete the port-forward with Ctrl+C; the Deployment keeps running.

How do you expose an app with Traefik ingress?

Traefik ships with K3s and is already listening on ports 80 and 443, so exposing your deployment is one Ingress manifest away. Traefik is the default ingress controller in K3s, which means a plain Ingress resource is picked up automatically — no ingress class annotation needed:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx
spec:
  rules:
  - host: nginx.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx
            port:
              number: 80

You also need a Service in front of the pods for the Ingress to route to:

apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80

Point nginx.example.com at your server's IP in DNS (or your local hosts file for a test), apply both manifests, and the welcome page loads over plain HTTP through Traefik. K3s even lets you customize Traefik itself declaratively: drop a HelmChartConfig manifest named traefik into /var/lib/rancher/k3s/server/manifests/ and the bundled Helm controller applies your values. For HTTPS later, cert-manager is the standard next install.

How do you use Helm on K3s?

Helm works on K3s with zero special configuration — once your kubeconfig rule is satisfied, the standard Helm CLI talks to the cluster like any other. Install it with the project's official script (read it first, same as the K3s script):

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4
chmod 700 get_helm.sh
./get_helm.sh

Then a chart install is the familiar two commands — for example, Bitnami's nginx:

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install my-site bitnami/nginx

K3s also ships its own Helm controller, which installs and upgrades charts declaratively through a HelmChart custom resource — handy when you want GitOps-style "apply a YAML and the chart appears" behavior. That is how K3s itself deploys its bundled components: the packaged Traefik loads its chart from the cluster's own static chart endpoint. That two-path design is the whole k3s helm story: the CLI for humans, the controller for automation.

Can K3s run on a Raspberry Pi?

Yes — the Pi is one of K3s's home platforms. K3s officially supports arm64/aarch64 alongside x86_64 and armhf, and the docs call out Raspberry Pi setups explicitly. Two Pi-specific rules matter. First, use an external SSD, not the SD card: K3s's own requirements page warns that etcd is write-intensive and "SD cards and eMMC cannot handle the IO load," so a Pi running the embedded etcd in HA mode will chew through SD storage. Second, keep single-node expectations modest — a Pi 4 or 5 makes a fine single-server lab or edge node, but do not plan a production HA trio on SD cards. For a homelab Pi cluster, the same install script and agent-join flow in this guide apply unchanged; a k3s raspberry pi setup uses identical commands because the architecture is identical.

K3s vs Kubernetes: what is actually different?

K3s is not a fork or a toy — it is the same Kubernetes API with different packaging and different defaults. The differences that matter to a beginner:

The punchline: everything you learn on K3s transfers to managed Kubernetes (EKS, GKE, AKS) because the API and the tools are identical — only the operational burden is smaller. Choose K3s when you want real multi-node Kubernetes on a small resource budget or ARM hardware; choose a local tool like kind or minikube only when the cluster will never leave your laptop.

What are the 7 beginner mistakes with K3s?

Every one of these comes from a real support thread or a real first install — check them before you debug for an hour:

What comes after your first cluster?

Your single-node cluster is a complete lab — the honest next steps are practice, not architecture. Deploy a second app, add that worker node, break something and fix it with kubectl describe and kubectl logs. When you outgrow one server, high availability means three server nodes installed with --cluster-init so the embedded etcd datastore replicates, with agents joining against any of the three. Beyond that, the Kubernetes ecosystem opens up: a terminal UI like K9s for daily driving, a manager like Rancher when you run several clusters, and a storage story like Longhorn when the local-path provisioner stops being enough. None of that is day one — day one is the seven steps above, and they already put you ahead of most Kubernetes learners.

Sources

• docs.k3s.io, "Quick-Start Guide" (fetched 2026-10-31) — official install script curl -sfL https://get.k3s.io | sh -, systemd auto-restart, bundled utilities (kubectl, crictl, ctr, k3s-killall.sh, k3s-uninstall.sh), kubeconfig at /etc/rancher/k3s/k3s.yaml, agent join via K3S_URL/K3S_TOKEN, node token at /var/lib/rancher/k3s/server/node-token, unique-hostname rule
• docs.k3s.io, "Requirements" (fetched 2026-10-31) — server minimum 2 cores / 2 GB RAM, agent minimum 1 core / 512 MB, x86_64/armhf/arm64 architectures, port table (6443 TCP, 8472 UDP Flannel VXLAN, 2379-2380 etcd HA, 10250 kubelet), external-SSD recommendation for Raspberry Pi / ARM
• docs.k3s.io, "Architecture" (fetched 2026-10-31) — server vs agent node definitions, single-server embedded SQLite, HA = 3+ servers with embedded etcd, agent websocket registration with client-side load balancer
• docs.k3s.io, "Helm" (fetched 2026-10-31) — no special configuration needed for Helm beyond the kubeconfig path; bundled Helm controller managing HelmChart CRDs; packaged Traefik customized via HelmChartConfig
• helm.sh, "Installing Helm" (fetched 2026-10-31) — official get-helm-4 installer script flow, Helm 4.0.0 current line
• GitHub k3s-io/k3s releases API + update.k3s.io channels API (fetched 2026-10-31) — latest v1.37.1+k3s1 (2026-09-30), stable channel v1.36.5+k3s1
• selfhosting.sh, "How to Self-Host k3s" (crawled <1h) — single ~70 MB binary, SQLite single-node, bundled Traefik/CoreDNS/Flannel/local-path provisioner, built by Rancher Labs (now SUSE)
• tutorials.technology, "K3s Tutorial 2026" (crawled 6h) — fully conformant Kubernetes distribution, Raspberry Pi 4 (64-bit) as supported platform, system-upgrade-controller upgrade path
• medium.com/@asushant34, "From Zero to Kubernetes" (updated 16 days ago) — two-server K3s + Rancher first-cluster arc

Frequently asked questions

Is K3s free to use?

Yes — K3s is free and open-source software maintained by Rancher/SUSE, and this entire guide uses only the free install. There is no account, license key, or paid tier standing between you and a running cluster; your only cost is the server it runs on.

Is K3s real Kubernetes or a simplified toy?

It is real Kubernetes: K3s is a CNCF-conformant distribution, so the API, kubectl, manifests, and Helm charts behave exactly as they do on managed Kubernetes. What is "simplified" is the operations — packaging, defaults, and the single-node SQLite datastore — not the Kubernetes you learn.

How much RAM does K3s actually need?

The official minimums are 2 GB of RAM for a server node and 512 MB for an agent node, before your workloads. In practice a single-node lab with a couple of small apps is comfortable on a 2 GB VPS, and that is why the 1 GB-and-up cheap VPS tier is the classic K3s starting point — just leave headroom for whatever you deploy.

Should I use K3s or Docker Compose for my side project?

Use Docker Compose if you run one app on one server and want the simplest possible deploy. Move to K3s when you want Kubernetes primitives — rolling updates, self-healing pods, Ingress routing, Helm charts — or when you are deliberately learning Kubernetes skills that transfer to managed clouds. The Docker beginner guide is the prerequisite either way.

How do I uninstall K3s?

Run the k3s-uninstall.sh script the installer placed on your server — it stops the service, removes the cluster data, and cleans up the installed components. On agent nodes there is a matching k3s-agent-uninstall.sh. Reinstalling afterward is just the install command again.