Day 0: The Training Ground
Goal: Set up Rancher Desktop on the Mac, get to know the bundled tools, fetch the companion code and take a first look at the built-in k3s. · Duration: approx. 45 min · Prerequisite: none
Briefing
- Rancher Desktop brings containers and Kubernetes to
your laptop: a small Linux VM with containerd and k3s, plus
nerdctl,docker,kubectlandhelm. - In this book Rancher Desktop runs with containerd
as the runtime.
nerdctltalks to containerd the waydockertalks to Docker. - From Day 2 on, VMs join in that you start via Multipass: k3s, Rancher itself and the cluster werk.
- All files live under
~/rancher-lab, the companion code in~/rancher-lab/code.
Mac
┌──────────────────────────────────────────────────────────────┐
│ ~/rancher-lab/ setup/ code/ notes/ kube/ tagNN/ │
│ ~/.rd/bin: nerdctl, docker, kubectl, helm, rdctl │
│ Rancher Desktop VM (Alpine): containerd ─┬─ Namespace default │
│ └─ Namespace k8s.io ─► k3s v1.36.5
└──────────────────────────────────────────────────────────────┘
Drill 1: Disk Space and Memory
Rancher Desktop creates a VM that grows with every image. In the test, after the images of notes and Postgres, it took up a good 5 GB. Check beforehand:
df -h ~ | tail -1
sysctl -n hw.memsize | awk '{print $1/1073741824 " GB RAM"}'Expected (abridged, values differ on your machine):
/dev/disk3s5 228Gi … … …
16 GB RAM
Warning: With less than 20 GB of free space, stop here and clean up first. If the disk fills up, the only remedy is
rdctl factory-reset, which deletes the VM including its images.
If Colima from the sister books is running, stop it with
colima stop. Two VMs with Docker and Kubernetes don’t get
along well on 16 GB.
Save your progress? Sign up for free
Drill 2: Install and Start Rancher Desktop
brew install --cask rancher
RD="/Applications/Rancher Desktop.app/Contents/Resources/resources/darwin/bin"
"$RD/rdctl" versionExpected (abridged):
🍺 rancher was successfully installed!
rdctl client version: v1.24.0, targeting server version: v1
On first start, Rancher Desktop asks in its window for the runtime,
the Kubernetes version and whether it may change your PATH.
rdctl start sets everything at once, without a window and
without changes to your shell files:
"$RD/rdctl" start --application.admin-access=false \
--application.path-management-strategy=manual \
--application.start-in-background \
--container-engine.name=containerd \
--kubernetes.enabled=true --kubernetes.version=1.36.5 \
--virtual-machine.memory-in-gb=6 --virtual-machine.number-cpus=4 \
--virtual-machine.type=vz --no-modal-dialogsExpected (abridged):
time="…" level=info msg="About to launch /usr/bin/open -a /Applications/Rancher Deskt…
The VM gets 4 CPUs and 6 GB RAM; vz is Apple’s own
virtualization. path-management-strategy=manual means: you
set the path to the tools yourself.
Save your progress? Sign up for free
Drill 3: Wait Until Everything Runs
until "$RD/rdctl" api /v1/backend_state 2>/dev/null | grep -q '"vmState":"STARTED"'; do
sleep 5
done
"$RD/rdctl" api /v1/backend_state; echo
export PATH="$HOME/.rd/bin:$PATH"
which nerdctl kubectl helm rdctlExpected (abridged, after about a minute):
{"vmState":"STARTED","locked":false}
/Users/…/.rd/bin/nerdctl
/Users/…/.rd/bin/kubectl
/Users/…/.rd/bin/helm
/Users/…/.rd/bin/rdctl
From now on all tools live in ~/.rd/bin. From here on,
the path is set by setup/env.sh from the companion code
(Drill 6) as soon as you read it in with source.
Save your progress? Sign up for free
Drill 4: What Rancher Desktop Brings Along
nerdctl version | grep -E 'Version|OS/Arch'
kubectl version --client | head -1
helm version --short
kubectl config get-contextsExpected (abridged):
Version: v2.2.2
OS/Arch: linux/arm64
Version: v0.28.1
Version: v2.3.2
Client Version: v1.37.2
v4.2.3+g43e8b7f
CURRENT NAME CLUSTER AUTHINFO NAMESPACE
* default default default
rancher-desktop rancher-desktop rancher-desktop
nerdctl 2.2, BuildKit 0.28, containerd 2.3, all for arm64. Rancher
Desktop brings its own Helm 4.2; the book uses Helm 4.3 from Homebrew
for the VMs, and both understand the same commands. New is the context
rancher-desktop. The current context stays what it was;
Rancher Desktop doesn’t push itself to the front.
Save your progress? Sign up for free
Drill 5: The Built-in k3s
kubectl --context rancher-desktop get nodes -o wide
kubectl --context rancher-desktop get pods -n kube-systemExpected (abridged):
NAME STATUS ROLES AGE VERSION … OS-IMAGE
lima-rancher-desktop Ready control-plane 5s v1.36.5+k3s1 … Alpine Lin…
NAME READY STATUS RESTARTS AGE
coredns-7cfb7bc9c7-2j8rl 1/1 Running 0 20s
helm-install-traefik-77mgk 0/1 Completed 1 (16s ago) 20s
helm-install-traefik-crd-8bgtf 0/1 Completed 0 20s
local-path-provisioner-77b9867795-q2wrd 1/1 Running 0 20s
metrics-server-6dc596dfb8-2mhs7 1/1 Running 0 20s
svclb-traefik-2da029cb-wspbr 2/2 Running 0 14s
traefik-7c8544f77-f55w7 1/1 Running 0 14s
One node, k3s v1.36.5 on Alpine Linux, with Traefik, ServiceLB, local-path and metrics-server. Exactly this k3s is what you install by hand on a VM on Day 2.
Save your progress? Sign up for free
Drill 6: Companion Code and Working Directory
The companion code is public on GitHub:
mkdir -p ~/rancher-lab && cd ~/rancher-lab
git clone https://github.com/thomaszachmann/rancher-zum-anfassen.git code
mkdir -p setup kube
cp code/setup/env.sh setup/
cp -R code/notes notes
ls codeExpected (abridged):
Cloning into 'code'...
README.md anhb notes notes-chart platform setup tag02 tag04 tag05 …
notes is the application from the Docker and Kubernetes
books, notes-chart its Helm chart 0.3.0 from “Kubernetes
hands-on”, platform/namespace.yaml the part that the chart
doesn’t create itself.
Save your progress? Sign up for free
Checkpoint
rdctl api /v1/backend_state; echoExpected: the VM is running.
{"vmState":"STARTED","locked":false}
kubectl --context rancher-desktop get nodesExpected: one node, Ready, k3s v1.36.5.
NAME STATUS ROLES AGE VERSION
lima-rancher-desktop Ready control-plane 2m v1.36.5+k3s1
ls ~/rancher-lab/code/notesExpected: the three parts of notes.
README.md notes-api notes-web notes-worker
Challenge
Rancher Desktop has saved its settings. Use rdctl to
read out which runtime, which Kubernetes version and how much memory it
runs with.
Hint: rdctl list-settings outputs
JSON.
Solution
rdctl list-settings | jq -c '{engine: .containerEngine.name,
k8s: .kubernetes.version, vm: .virtualMachine | {memoryInGB, numberCPUs, type}}'Expected:
{"engine":"containerd","k8s":"1.36.5","vm":{"memoryInGB":6,"numberCPUs":4,"type":"vz"}}
Everything the window configures lives in these settings.
rdctl set changes them just as well without a window, handy
for scripts and for setting up many machines.
Save your progress? Sign up for free
Enterprise Note
- Managed settings: Companies give Rancher Desktop fixed defaults via MDM, such as the runtime, the Kubernetes version or locked registries.
- License: Rancher Desktop is open source and free for use in companies, unlike some desktop alternatives.
- Same foundation: k3s on the laptop, k3s or RKE2 in the data center: what runs locally later runs similarly, though not identically (permissions, storage, network).
- Cleanup:
rdctl factory-resetdeletes the VM and images; uninstalling via Homebrew requires administrator rights.