Skip to content
Hands-on IT IT Drills

Day 2: Understanding k3s

Goal: Install k3s on a VM with one command, understand what’s inside the one binary, and make notes reachable via Traefik with images from Rancher Desktop. · Duration: approx. 60 min · Prerequisite: Day 1

Briefing

  • k3s is Rancher’s lightweight Kubernetes distribution: a binary of just under 80 MB with control plane, kubelet, containerd and tools. At its core is the same k3s that Rancher Desktop runs on the Mac.
  • Instead of etcd, a single k3s server stores the state in SQLite. For several servers there is embedded etcd.
  • k3s comes with: Traefik as the ingress controller, ServiceLB for Services of type LoadBalancer, local-path for volumes and a NetworkPolicy controller.
  • Rancher takes the VM k3s from this day under its management on Day 4.
 Mac                               VM k3s (Ubuntu 24.04)
 ┌─────────────────────────┐       ┌──────────────────────────────────────┐
 │ Rancher Desktop         │ .tar  │ k3s (one binary, service k3s)        │
 │  nerdctl save ──────────┼──────►│  containerd ◄─ k3s ctr images import │
 │ kubectl, helm ──────────┼─:6443►│  API server, SQLite state.db         │
 │ curl notes.<IP>.sslip.io┼──:80─►│  Traefik ─► web ─► api ─► db         │
 └─────────────────────────┘       └──────────────────────────────────────┘

Drill 1: The VM

multipass launch 24.04 --name k3s --cpus 2 --memory 3G --disk 20G
source ~/rancher-lab/setup/env.sh
cat > "$LAB/setup/vms.env" <<EOF
# setup/vms.env – addresses of the VMs (Day 2, extended on Day 3 and 5)
export K3S=$(multipass info k3s --format json | jq -r '.info.k3s.ipv4[0]')
EOF
source "$LAB/setup/env.sh"
echo "$K3S"

Expected (abridged, names, IPs and times differ on your machine):

Launched: k3s
…

env.sh reads in vms.env as well. From now on every new shell knows the address as soon as you source env.sh.

Save your progress? Sign up for free

Drill 2: Install k3s

The installer downloads the binary, creates the service k3s and starts it. The version is pinned in the command:

multipass exec k3s -- bash -c \
  'curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION=v1.36.5+k3s1 sh -'
multipass exec k3s -- k3s --version
multipass exec k3s -- sudo k3s kubectl get nodes -o wide

Expected (abridged):

[INFO]  systemd: Creating service file /etc/systemd/system/k3s.service
[INFO]  systemd: Enabling k3s unit
Created symlink /etc/systemd/system/multi-user.target.wants/k3s.service → …
[INFO]  systemd: Starting k3s
k3s version v1.36.5+k3s1 (3dd98cc5)
go version go1.26.8
NAME   STATUS   ROLES           AGE   VERSION        …   CONTAINER-RUNTIME
k3s    Ready    control-plane   36s   v1.36.5+k3s1   …   containerd://2.3.4-k3s1.36

After half a minute a whole cluster is running. If No resources found still shows right after the installer, the node is just registering; a few seconds later it is Ready.

Save your progress? Sign up for free

Drill 3: What’s Inside the Binary

multipass exec k3s -- bash -c 'ls -la /usr/local/bin | grep -E "k3s|kubectl|ctr"'
multipass exec k3s -- sudo ls /var/lib/rancher/k3s/server/db
multipass exec k3s -- sudo ls /var/lib/rancher/k3s/server/manifests
multipass exec k3s -- sudo k3s kubectl get pods -n kube-system

Expected (abridged):

lrwxrwxrwx  1 root root        3 … crictl -> k3s
lrwxrwxrwx  1 root root        3 … ctr -> k3s
-rwxr-xr-x  1 root root 79077538 … k3s
-rwxr-xr-x  1 root root     2318 … k3s-killall.sh
-rwxr-xr-x  1 root root     3189 … k3s-uninstall.sh
lrwxrwxrwx  1 root root        3 … kubectl -> k3s
state.db
state.db-shm
state.db-wal
ccm.yaml
coredns.yaml
local-storage.yaml
metrics-server
rolebindings.yaml
runtimes.yaml
traefik.yaml
NAME                                      READY   STATUS      RESTARTS      AGE
coredns-7cfb7bc9c7-pkm72                  1/1     Running     0             10m
helm-install-traefik-crd-c772p            0/1     Completed   0             10m
helm-install-traefik-kvx5z                0/1     Completed   2 (10m ago)   10m
local-path-provisioner-77b9867795-ckcbx   1/1     Running     0             10m
metrics-server-6dc596dfb8-vsl8r           1/1     Running     0             10m
svclb-traefik-44d8b4d7-r6l49              2/2     Running     0             9m47s
traefik-7c8544f77-2bft9                   1/1     Running     0             9m47s

kubectl, crictl and ctr are just links to k3s. Depending on the name it’s called by, the binary behaves differently. The entire state of the cluster lives in one SQLite file. k3s applies the files in manifests automatically at startup; that is how Traefik and local-path get into the cluster. RKE2 does the same (“Kubernetes hands-on”, Day 12).

Save your progress? Sign up for free

Drill 4: kubectl from the Mac

mkdir -p "$LAB/kube"
multipass exec k3s -- sudo cat /etc/rancher/k3s/k3s.yaml \
  | sed -e "s/127.0.0.1/$K3S/" -e 's/: default$/: k3s/' > "$LAB/kube/k3s.yaml"
chmod 600 "$LAB/kube/k3s.yaml"
export KUBECONFIG="$LAB/kube/k3s.yaml"
kubectl get nodes

Expected:

NAME   STATUS   ROLES           AGE   VERSION
k3s    Ready    control-plane   39s   v1.36.5+k3s1

Every cluster in this book gets its own file under ~/rancher-lab/kube/. Which cluster is meant is decided by KUBECONFIG, not by an accidentally switched context.

Save your progress? Sign up for free

Drill 5: Images from Rancher Desktop

The VM has no registry. The images from Day 1 travel over as an archive and are imported into k3s’s containerd:

nerdctl --namespace k8s.io save -o notes-images.tar \
  notes-api:0.2.0 notes-web:0.1.0 notes-worker:0.1.0
multipass transfer notes-images.tar k3s:/tmp/
multipass exec k3s -- sudo k3s ctr images import /tmp/notes-images.tar
multipass exec k3s -- sudo k3s crictl images | grep notes
multipass exec k3s -- rm /tmp/notes-images.tar
rm notes-images.tar

Expected (abridged):

…
docker.io/library/notes-api      0.2.0      ec38f50335a8c   4.5MB
docker.io/library/notes-web      0.1.0      d50e082fcd584   64.2MB
docker.io/library/notes-worker   0.1.0      2f668f81849cf   45.5MB

containerd expands short names like notes-api to docker.io/library/notes-api. That is why the chart finds the images even though they were never on Docker Hub. The images are arm64 like your VM; a Mac with Apple silicon builds them to match.

Save your progress? Sign up for free

Drill 6: notes on k3s

First the platform (namespace with Pod Security, quota, ServiceAccount notes) and the Secrets, then the chart. Without the ServiceAccount no pods get created at all (Day 1).

mkdir -p "$LAB/tag02" && cd "$LAB/tag02"
cp "$LAB/code/tag02/"* .
kubectl apply -f "$LAB/code/platform/namespace.yaml"
kubectl -n notes create secret generic notes-api --from-literal=api-key=lab-api-key-123
kubectl -n notes create secret generic notes-db --from-literal=password=lab-db-pw-123 \
  --from-literal=db-url='postgres://notes:lab-db-pw-123@db:5432/notes'
cat values-k3s.yaml

Expected (abridged):

namespace/notes created
limitrange/defaults created
resourcequota/notes created
serviceaccount/notes created
secret/notes-api created
secret/notes-db created
# tag02/values-k3s.yaml – Stand Ende Tag 2: notes auf k3s
gateway:
  enabled: false        # kein Envoy Gateway, Traefik aus k3s übernimmt (ingress.yaml)
networkPolicy:
  gatewayNamespace: kube-system   # dort läuft Traefik

The chart from “Kubernetes hands-on” comes with a Gateway for Envoy. k3s has Traefik, so you switch off the Gateway and allow Traefik’s namespace in the NetworkPolicy:

helm -n notes install notes "$LAB/code/notes-chart/notes" -f values-k3s.yaml \
  --wait --timeout 5m | grep -E '^(NAME|STATUS):'
kubectl -n notes get pods

Expected (abridged):

NAME: notes
STATUS: deployed
NAME                      READY   STATUS      RESTARTS      AGE
api-65dfff884-4w7h8       1/1     Running     4 (63s ago)   105s
api-65dfff884-fgp28       1/1     Running     4 (64s ago)   105s
api-65dfff884-mngv7       1/1     Running     4 (61s ago)   105s
db-0                      1/1     Running     0             104s
migrate-q2s75             0/1     Completed   1 (4s ago)    6s
web-7fd8cd6fd9-fmxwj      1/1     Running     0             106s
web-7fd8cd6fd9-kz87m      1/1     Running     0             105s
worker-666579f9d5-xk57l   1/1     Running     0             105s

The installation takes just under two minutes. The api restarts until Postgres is ready, as in the sister book.

Save your progress? Sign up for free

Drill 7: Reachable via Traefik

# tag02/ingress.yaml – state at end of Day 2: web via the k3s Traefik
# Template: Drill 7 replaces K3S_IP via sed with the address of the VM k3s.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: notes
spec:
  ingressClassName: traefik
  rules:
    - host: notes.K3S_IP.sslip.io
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 3000

sslip.io is a public DNS service: notes.192.168.64.5.sslip.io resolves to 192.168.64.5. That way every VM gets a hostname without its own DNS.

sed "s/K3S_IP/$K3S/" ingress.yaml | kubectl apply -f -
kubectl -n notes get ingress
kubectl -n kube-system get svc traefik
curl -s "http://notes.$K3S.sslip.io/api/notes"; echo
curl -s -X POST -H 'Content-Type: application/json' -d '{"text":"läuft auf k3s"}' \
  "http://notes.$K3S.sslip.io/api/notes"; echo

Expected (abridged):

ingress.networking.k8s.io/web created
NAME   CLASS     HOSTS                  ADDRESS   PORTS   AGE
web    traefik   notes.….sslip.io       …         80      1s
NAME      TYPE           CLUSTER-IP    EXTERNAL-IP   PORT(S)                      AGE
traefik   LoadBalancer   10.43.17.55   …             80:31126/TCP,443:31116/TCP   7m50s
[]
{"id":"395a46da-…","text":"läuft auf k3s"}

Traefik is a Service of type LoadBalancer, and ServiceLB gives it the IP of the VM as EXTERNAL-IP. For this, the pod svclb-traefik-… runs on every node and forwards ports 80 and 443 to Traefik. Without a cloud there would otherwise be no external address.

Warning: web forwards /api/notes to the api. A POST needs Content-Type: application/json, otherwise notes answers with text required.

Save your progress? Sign up for free

Checkpoint

kubectl get nodes

Expected: one node k3s, Ready, version v1.36.5+k3s1.

NAME   STATUS   ROLES           AGE   VERSION
k3s    Ready    control-plane   12m   v1.36.5+k3s1
helm -n notes list

Expected: release notes with chart notes-0.3.0, status deployed.

NAME    NAMESPACE   REVISION   UPDATED   STATUS     CHART         APP VERSION
notes   notes       1          2026-…    deployed   notes-0.3.0   0.2.0
curl -s "http://notes.$K3S.sslip.io/api/notes"; echo

Expected: your note from Drill 7.

[{"id":"395a46da-…","text":"läuft auf k3s"}]

Challenge

The chart comes with NetworkPolicies. Prove that k3s actually enforces them: a pod in the namespace default must not reach the api, but web may.

Hint: kubectl run with busybox:1.37 and wget -T 3 is enough.

Solution

kubectl -n default run fremd --image=busybox:1.37 --restart=Never -- sleep 600
kubectl -n default wait --for=condition=Ready pod/fremd --timeout=90s
kubectl -n default exec fremd -- wget -qO- -T 3 http://api.notes:8080/version
kubectl -n notes exec deploy/web -- wget -qO- -T 3 http://api:8080/version
kubectl -n default delete pod fremd

Expected (abridged):

pod/fremd created
pod/fremd condition met
wget: can't connect to remote host (10.43.70.183): Connection refused
command terminated with exit code 1
0.2.0
pod "fremd" deleted from default namespace

k3s enforces NetworkPolicies with a built-in controller (kube-router). It rejects forbidden connections immediately (Connection refused). Canal in RKE2 drops them instead; there wget ends in a timeout (“Kubernetes hands-on”, Day 11).

Save your progress? Sign up for free

Enterprise Note

  • High availability: For several servers, k3s starts with embedded etcd (--cluster-init) or uses an external database. SQLite is fine for one server.
  • Where it runs: k3s runs where resources are scarce: edge, branch offices, vehicles, CI runners. For data centers with hardening requirements you tend to pick RKE2.
  • Disabling components: disable: [traefik, servicelb] in /etc/rancher/k3s/config.yaml replaces them with your own solutions, such as a different ingress controller or MetalLB.
  • Images: An archive via ctr images import is a stopgap for a lab. From Day 7 on, the images come from a registry.
  • Management: Nobody manages many k3s clusters via SSH. That is exactly what Rancher is for (from Day 3).