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
k3sfrom 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 wideExpected (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-systemExpected (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 nodesExpected:
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.tarExpected (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.yamlExpected (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 podsExpected (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: 3000sslip.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"; echoExpected (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/notesto the api. A POST needsContent-Type: application/json, otherwise notes answers withtext required.
Save your progress? Sign up for free
Checkpoint
kubectl get nodesExpected: 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 listExpected: 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"; echoExpected: 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 fremdExpected (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.yamlreplaces them with your own solutions, such as a different ingress controller or MetalLB. - Images: An archive via
ctr images importis 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).