Skip to content
Hands-on IT IT Drills

Day 0: The Training Ground

Goal: A lab VM with k3s and Helm, the companion code, and notes-api deployed once by hand in the cluster, so you see what kro will take off your hands later. · Duration: approx. 45 min · Prerequisite: none

Briefing

  • kro stands for Kube Resource Orchestrator. It is a controller that runs in the cluster. You describe your own API to it, and it generates a CRD plus controller from that, without you writing any code.
  • The description is called a ResourceGraphDefinition (RGD). It contains a schema (which fields may the team set?) and resources (which objects are created from it?). Values flow from one object to the next via CEL expressions of the form ${…}.
  • Everything runs in a k3s on your VM. notes-api is reachable via NodePorts, that is, fixed ports between 30000 and 32767 on the VM.
 Laptop ──ssh──► VM kro
                  └─ k3s
                      ├─ kro-system:  kro (from Day 1)
                      ├─ handarbeit:  notes-api by hand (today)
                      └─ app:         NotesApp instances (from Day 4)
 curl ─► http://<VM-IP>:30080  notes-api

Drill 1: The Lab VM

On the laptop (Multipass from multipass.run):

multipass launch 24.04 --name kro --cpus 2 --memory 4G --disk 30G
multipass exec kro -- bash -c "echo '$(cat ~/.ssh/id_ed25519.pub)' \
  >> ~/.ssh/authorized_keys"
multipass info kro | grep IPv4
ssh ubuntu@<IP aus der Ausgabe>
  • 4 GB is enough for kro, three small databases and a few notes-api pods. The kro controller itself needs about 100 MB.
  • Any other Linux VM with sudo and internet access will do as well.

From here on, everything runs inside the VM.

Save your progress? Sign up for free

Drill 2: k3s

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.37.2+k3s1 \
  sh -s - --disable traefik --disable servicelb

Expected (shortened):

[INFO]  Using v1.37.2+k3s1 as release
...
[INFO]  systemd: Enabling k3s unit
[INFO]  systemd: Starting k3s
  • get.k3s.io is the official installation script. It downloads k3s, creates the service and links kubectl.
  • --disable traefik --disable servicelb: You don’t need an ingress controller or a load balancer; everything runs via NodePorts.

The credentials belong to root. You make yourself a copy:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown "$(id -u):$(id -g)" ~/.kube/config
chmod 600 ~/.kube/config
echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc
export KUBECONFIG=~/.kube/config
kubectl get nodes

Expected:

NAME   STATUS   ROLES           AGE   VERSION
kro    Ready    control-plane   25s   v1.37.2+k3s1

KUBECONFIG is mandatory with k3s. Without the variable, its kubectl always reads /etc/rancher/k3s/k3s.yaml and fails with permission denied.

Save your progress? Sign up for free

Drill 3: Helm

kro comes as a Helm chart:

mkdir -p ~/.local/bin ~/kro-lab
cd ~/kro-lab
curl -fsSLO https://get.helm.sh/helm-v4.3.1-linux-amd64.tar.gz
tar xzf helm-v4.3.1-linux-amd64.tar.gz
mv linux-amd64/helm ~/.local/bin/
rm -r linux-amd64 helm-v4.3.1-linux-amd64.tar.gz
helm version --short

Expected:

v4.3.1+gc0d08d0

Ubuntu adds ~/.local/bin to the PATH at login as soon as the directory exists. If the shell can’t find helm, log out and back in once.

Save your progress? Sign up for free

Drill 4: The Companion Code

git clone -q https://github.com/thomaszachmann/kro-zum-anfassen.git ~/kro-lab/code
ls ~/kro-lab/code ~/kro-lab/code/loesung

Expected:

/home/ubuntu/kro-lab/code:
LICENSE  loesung  README.md  wettkampf

/home/ubuntu/kro-lab/code/loesung:
pruefung  tag02  tag04  tag06  tag08  tag10  tag13
tag01     tag03  tag05  tag07  tag09  tag12  tag14
  • loesung/tagNN contains the finished files of each day. You write them yourself and compare at the end with diff.
  • You won’t need wettkampf/ until Day 15.

You don’t have to build an image. notes-api is ready in the GitHub Container Registry: ghcr.io/thomaszachmann/notes-api:0.5.1.

Save your progress? Sign up for free

Drill 5: notes-api by Hand

Before kro comes into play, you bring notes-api into the cluster the way you would without help: command by command.

kubectl create namespace handarbeit
kubectl -n handarbeit create deployment notes \
  --image=ghcr.io/thomaszachmann/notes-api:0.5.1 --port=8080
kubectl -n handarbeit get pods

Expected (after a few seconds):

NAME                     READY   STATUS   RESTARTS     AGE
notes-5f548db6f6-7frk7   0/1     Error    1 (9s ago)   10s

Why? The log tells you:

kubectl -n handarbeit logs deploy/notes

Expected:

time=2026-11-11T18:16:33.664Z level=ERROR msg="start abgebrochen"
  err="NOTES_API_KEY oder NOTES_API_KEY_FILE fehlt"

notes-api requires an API key, and that belongs in a Secret:

kubectl -n handarbeit create secret generic notes-api \
  --from-literal=NOTES_API_KEY=lab-api-key-123
kubectl -n handarbeit set env deployment/notes --from=secret/notes-api
kubectl -n handarbeit rollout status deploy/notes

Expected (shortened):

secret/notes-api created
deployment.apps/notes env updated
...
deployment "notes" successfully rolled out

set env --from=secret/… turns every key of the Secret into an environment variable. That is why the key here is named exactly like the variable, NOTES_API_KEY.

Now the way out is still missing:

kubectl -n handarbeit expose deployment notes --type=NodePort --port=80 \
  --target-port=8080
kubectl -n handarbeit get svc notes

Expected (the port will differ):

service/notes exposed
NAME    TYPE       CLUSTER-IP    EXTERNAL-IP   PORT(S)        AGE
notes   NodePort   10.43.43.73   <none>        80:32097/TCP   0s
curl -s localhost:32097/version

Expected:

0.5.1

Three objects, five commands and a false start, and that without a database, a readiness probe or a fixed port. A team shouldn’t have to do this by hand every time. From Day 4 on, you create the same thing with a single object.

Save your progress? Sign up for free

Checkpoint

kubectl get nodes

Expected: one node kro with STATUS Ready.

helm version --short

Expected: v4.3.1+gc0d08d0.

kubectl -n handarbeit get deploy notes

Expected:

NAME    READY   UP-TO-DATE   AVAILABLE   AGE
notes   1/1     1            1           2m

Challenge

Create a note with the text “Hallo kro” via the NodePort and read it back.

Note: POST /notes with header X-API-Key and JSON {"text": "…"}.

Solution

curl -s -H "X-API-Key: lab-api-key-123" -d '{"text":"Hallo kro"}' \
  localhost:32097/notes
curl -s localhost:32097/notes

Expected (the ID will differ):

{"id":"bb895acb-2aa5-4d1d-bf2e-e61f3f5c6a43","text":"Hallo kro"}
[{"id":"bb895acb-2aa5-4d1d-bf2e-e61f3f5c6a43","text":"Hallo kro"}]

With -d, curl automatically sends a POST. Without a database, notes-api stores in memory; after a pod restart the note is gone.

You no longer need the namespace:

kubectl delete namespace handarbeit

Save your progress? Sign up for free

Enterprise Note

  • Who writes the YAML? In many companies, teams copy manifests from a wiki and adapt them. After a year there are twenty variants of the same app. Your own API like NotesApp keeps the variants together in one place.
  • Platform APIs: What you build in this book is called a “golden path” or “paved road” in platform engineering circles. The platform offers simple building blocks, and the teams don’t need to know the details.
  • NodePorts: They are handy in the lab. In production, an ingress or a gateway sits in front of them; see “Gateway API hands-on”.