Day 1: Rancher Desktop
Goal: Start containers with nerdctl, build the notes images so that k3s finds them without a registry, and run notes with the Helm chart in the built-in k3s. · Duration: approx. 60 min · Prerequisite: Day 0
Briefing
- containerd separates images and containers into
namespaces. nerdctl works in the namespace
default, k3s in the namespacek8s.io. - An image that you build with
nerdctl --namespace k8s.io buildis visible to k3s right away. You don’t need a registry for that. - The notes chart expects a platform part that it doesn’t create
itself: a namespace with Pod Security, a quota and the ServiceAccount
notes. - Today
kubectl port-forwardopens the way in from outside; on Day 2 Traefik takes over.
nerdctl ──► containerd ─┬─ Namespace default : nginx (Drill 1)
└─ Namespace k8s.io : notes-api, notes-web, notes-worker
▲
k3s (Rancher Desktop) starts pods from them
Drill 1: A Container
source ~/rancher-lab/setup/env.sh
mkdir -p "$LAB/tag01" && cd "$LAB/tag01"
nerdctl run -d --name hallo -p 8080:80 nginx:1.30.6-alpine
nerdctl ps
curl -s localhost:8080 | grep -o '<title>.*</title>'
nerdctl rm -f halloExpected (abridged, IDs and times differ on your machine):
39b48194831609272390bbc7e28314b12eee3682a99af508099c449aa24225b1
CONTAINER ID IMAGE … PORTS
39b481948316 docker.io/library/nginx:1.30.6-alpine … 0.0.0.0:8080->80/tcp
<title>Welcome to nginx!</title>
hallo
nerdctl has the same commands as docker. Rancher Desktop forwards the
port from the VM to the Mac, which is why localhost:8080
answers.
Save your progress? Sign up for free
Drill 2: Namespaces in containerd
nerdctl namespace ls
nerdctl --namespace k8s.io images | head -3Expected (abridged):
NAME CONTAINERS IMAGES VOLUMES LABELS
buildkit 0 0 0
default 0 1 0
k8s.io 15 19 0
rancher-desktop-extensions 0 1 0
REPOSITORY TAG IMAGE ID CREATED PLATFORM SIZE
rancher/mirrored-pause 3.6 74c4244427b7 About a m… linux/arm64 491.5kB
…
default holds your nginx image, k8s.io the
images and containers of k3s. The two can’t see each other: Kubernetes
doesn’t find an image in default.
Save your progress? Sign up for free
Drill 3: Build notes for k3s
cd "$NOTES"
nerdctl --namespace k8s.io build -q --build-arg VERSION=0.2.0 \
-t notes-api:0.2.0 notes-api
nerdctl --namespace k8s.io build -q --build-arg VERSION=0.1.0 \
-t notes-web:0.1.0 notes-web
nerdctl --namespace k8s.io build -q --build-arg VERSION=0.1.0 \
-t notes-worker:0.1.0 notes-worker
nerdctl --namespace k8s.io images | grep notes
cd "$LAB/tag01"Expected (abridged, one to two minutes the first time):
…
notes-worker 0.1.0 7c42ba6117f5 1 second ago linux/arm64 167.8MB 45.77MB
notes-web 0.1.0 fd98ab494eb0 22 seconds ago linux/arm64 196.8MB 69.21MB
notes-api 0.2.0 7b228b421269 46 seconds ago linux/arm64 11.28MB 4.089MB
The versions match the chart: api 0.2.0 (appVersion), web and worker
0.1.0. BuildKit runs in the Rancher Desktop VM and writes directly to
k8s.io.
Tip: If space runs short:
nerdctl --namespace k8s.io builder prune -fdeletes the build cache. In the test it accounted for over 1 GB.
Save your progress? Sign up for free
Drill 4: The Chart Without the Platform
What happens if you simply install the chart? The attempt is worth it:
kubectl config use-context rancher-desktop
kubectl create namespace notes
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'
helm -n notes install notes "$LAB/code/notes-chart/notes" \
--set gateway.enabled=false --wait --timeout 2m
kubectl -n notes get pods
kubectl -n notes get events --field-selector reason=FailedCreate \
-o custom-columns=MSG:.message | sort -u | head -2Expected (abridged):
namespace/notes created
secret/notes-api created
secret/notes-db created
Error: INSTALLATION FAILED: resource Deployment/notes/api not ready. status: InProgress,
message: Replicas: 0/3
No resources found in notes namespace.
Create Pod db-0 in StatefulSet db failed error: pods "db-0" is forbidden: error looking
up service account notes/notes: serviceaccount "notes" not found
Error creating: pods "api-65dfff884-" is forbidden: error looking up service account …
Not a single pod. The chart uses the ServiceAccount
notes but doesn’t create it; it belongs to the platform
part (“Kubernetes hands-on”, Day 10). Clean up the failed attempt:
helm -n notes uninstall notes
kubectl delete namespace notesExpected:
release "notes" uninstalled
namespace "notes" deleted
Save your progress? Sign up for free
Drill 5: Platform First, Then the Chart
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'
helm -n notes install notes "$LAB/code/notes-chart/notes" \
--set gateway.enabled=false --wait --timeout 5m | grep -E '^(NAME|STATUS):'
kubectl -n notes get podsExpected (abridged, after just under two minutes):
namespace/notes created
limitrange/defaults created
resourcequota/notes created
serviceaccount/notes created
secret/notes-api created
secret/notes-db created
NAME: notes
STATUS: deployed
NAME READY STATUS RESTARTS AGE
api-65dfff884-4w7h8 1/1 Running 4 (63s 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
…
Now everything runs. The images come from k8s.io (Drill
3): the chart names notes-api, containerd expands that to
docker.io/library/notes-api and finds it locally. The api
restarts a few times until Postgres is ready.
Save your progress? Sign up for free
Drill 6: notes in the Browser
kubectl -n notes port-forward svc/web 3000:3000 &
curl -s -X POST -H 'Content-Type: application/json' -d '{"text":"auf dem Laptop"}' \
localhost:3000/api/notes; echo
curl -s localhost:3000/api/notes; echo
open http://localhost:3000Expected (abridged):
Forwarding from 127.0.0.1:3000 -> 3000
{"id":"…","text":"auf dem Laptop"}
[{"id":"…","text":"auf dem Laptop"}]
port-forward builds a tunnel from the Mac to the web
Service; the chart’s NetworkPolicies don’t apply to it. End the tunnel
with kill %1 and switch the context back:
kill %1
kubectl config use-context defaultSave your progress? Sign up for free
Checkpoint
nerdctl --namespace k8s.io images | grep -c '^notes-'Expected: three notes images in k8s.io.
3
helm --kube-context rancher-desktop -n notes listExpected: release notes, deployed.
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
notes notes 1 2026-… deployed notes-0.3.0 0.2.0
kubectl --context rancher-desktop -n notes get serviceaccount notesExpected: the ServiceAccount from the platform part.
NAME SECRETS AGE
notes 0 5m
Challenge
On Day 2 you need the notes images on a VM without a registry. Pack all three into a single archive file and check how big it is.
Hint: nerdctl save takes several images
at once.
Solution
nerdctl --namespace k8s.io save -o notes-images.tar \
notes-api:0.2.0 notes-web:0.1.0 notes-worker:0.1.0
ls -lh notes-images.tarExpected (abridged):
-rw-r--r-- 1 … …M … notes-images.tar
The archive contains the layers of all three images, shared layers only once. Exactly this file is what you copy to the VM on Day 2 and import there.
Save your progress? Sign up for free
Enterprise Note
- Dev environment: Rancher Desktop gives developers locally the same Kubernetes as k3s or RKE2 later on. Differences remain: one node, no Longhorn, no real network boundaries.
- Images: Locally built images without a registry are convenient but not traceable. In CI you build, sign and push to a registry (Day 7).
- Resources: A running Rancher Desktop VM occupies
memory permanently.
rdctl shutdownstops it when it isn’t needed. - Platform and chart: The separation from Drill 4 applies everywhere: teams get namespaces with permissions and quotas from the platform, charts bring only the application.