Skip to content
Hands-on IT IT Drills

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 namespace k8s.io.
  • An image that you build with nerdctl --namespace k8s.io build is 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-forward opens 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 hallo

Expected (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 -3

Expected (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 -f deletes 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 -2

Expected (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 notes

Expected:

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 pods

Expected (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:3000

Expected (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 default

Save 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 list

Expected: 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 notes

Expected: 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.tar

Expected (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 shutdown stops 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.