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
sudoand 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 servicelbExpected (shortened):
[INFO] Using v1.37.2+k3s1 as release
...
[INFO] systemd: Enabling k3s unit
[INFO] systemd: Starting k3s
get.k3s.iois the official installation script. It downloads k3s, creates the service and linkskubectl.--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 nodesExpected:
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 --shortExpected:
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/loesungExpected:
/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/tagNNcontains the finished files of each day. You write them yourself and compare at the end withdiff.- 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 podsExpected (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/notesExpected:
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/notesExpected (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 notesExpected (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/versionExpected:
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 nodesExpected: one node kro with STATUS
Ready.
helm version --shortExpected: v4.3.1+gc0d08d0.
kubectl -n handarbeit get deploy notesExpected:
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/notesExpected (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 handarbeitSave 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
NotesAppkeeps 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”.