Skip to content
Hands-on IT IT Drills

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, kubectl and helm.
  • In this book Rancher Desktop runs with containerd as the runtime. nerdctl talks to containerd the way docker talks 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" version

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

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

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

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

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

Expected (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; echo

Expected: the VM is running.

{"vmState":"STARTED","locked":false}
kubectl --context rancher-desktop get nodes

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

Expected: 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-reset deletes the VM and images; uninstalling via Homebrew requires administrator rights.