Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 0: Das Trainingsgelände

Ziel: Eine Labor-VM mit Docker, k3s und Helm, darauf notes-api mit Postgres und ein Lastgenerator, der rund um die Uhr Anfragen schickt. · Dauer: ca. 60 min · Voraussetzung: keine

Briefing

  • Observability heißt: von außen erkennen, was im System passiert – ohne neuen Code und ohne Debugger. Dafür gibt es drei Signale: Metriken (Zahlen über die Zeit), Logs (einzelne Ereignisse) und Traces (der Weg einer Anfrage).
  • Alles läuft in einem k3s auf deiner VM: die Anwendung, die du beobachtest, und die Werkzeuge, mit denen du beobachtest.
  • Der Lastgenerator sorgt dafür, dass es immer etwas zu sehen gibt: vier Lesezugriffe und eine neue Notiz pro Sekunde.
 Laptop ──ssh──► VM obs
                  └─ k3s
                      ├─ Namespace app:        notes-api (2 Pods) ── postgres
                      │                          ▲
                      │                        last (curl, 5 Anfragen/s)
                      └─ Namespace monitoring: ab Tag 2
 Browser ─► http://<VM-IP>:30080  notes-api

Drill 1: Die Labor-VM

Auf dem Laptop (Multipass von multipass.run):

multipass launch 26.04 --name obs --cpus 4 --memory 8G --disk 40G
multipass exec obs -- bash -c "echo '$(cat ~/.ssh/id_ed25519.pub)' \
  >> ~/.ssh/authorized_keys"
multipass info obs | grep IPv4
ssh ubuntu@<IP aus der Ausgabe>
  • 8 GB sind kein Luxus: Prometheus, Grafana, Loki, Tempo und der Collector brauchen zusammen gut 2 GB, k3s selbst noch einmal 1 GB. Dazu kommen Postgres, Docker und Spitzen beim Start. Mit 4 GB lief die Test-VM ab Tag 9 voll und reagierte nicht mehr.
  • Jede andere Linux-VM mit sudo und Internetzugang tut es auch.

Ab hier läuft alles in der VM.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Docker

Docker brauchst du nur zum Bauen von notes-api. Die Pakete kommen direkt von Docker:

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<'EOF'
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: resolute
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt-get update -qq
sudo apt-get install -y -qq docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin jq git unzip >/dev/null
sudo usermod -aG docker ubuntu
  • Zuerst der Schlüssel, mit dem Docker seine Pakete signiert, dann die Paketquelle. resolute ist der Codename von Ubuntu 26.04.
  • usermod -aG docker erlaubt dem Benutzer ubuntu, Docker ohne sudo zu nutzen.

Melde dich ab (exit) und wieder an, damit die Gruppe docker gilt:

docker --version

Erwartet:

Docker version 29.9.2, build a82e528

Fortschritt speichern? Kostenlos registrieren

Drill 3: k3s

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

Erwartet (gekürzt):

[INFO]  Using v1.37.1+k3s1 as release
...
[INFO]  systemd: Starting k3s
  • get.k3s.io ist das offizielle Installationsskript. Es lädt k3s, legt den Dienst an und verlinkt kubectl.
  • --disable traefik --disable servicelb: kein Ingress und kein Load-Balancer. Im Lab erreichst du alles über NodePorts – feste Ports zwischen 30000 und 32767 auf der VM.

Die Zugangsdaten liegen unter /etc/rancher/k3s/k3s.yaml und gehören root. Eine Kopie für dich:

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

Erwartet:

NAME   STATUS   ROLES           AGE   VERSION
obs    Ready    control-plane   52s   v1.37.1+k3s1

KUBECONFIG ist bei k3s Pflicht: Dessen kubectl liest sonst immer /etc/rancher/k3s/k3s.yaml und scheitert mit permission denied.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Helm

Fast alle Werkzeuge in diesem Buch kommen als Helm-Chart:

mkdir -p ~/.local/bin ~/obs-lab
cd ~/obs-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

Erwartet:

v4.3.1+gc0d08d0

Ubuntu nimmt ~/.local/bin beim Anmelden in den PATH auf, sobald der Ordner existiert. Findet die Shell helm nicht, melde dich einmal ab und wieder an.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Begleitcode und Image

git clone -q https://github.com/thomaszachmann/observability-zum-anfassen.git \
  ~/obs-lab/code
ls ~/obs-lab/code ~/obs-lab/code/notes-api

Erwartet:

/home/ubuntu/obs-lab/code:
k8s  LICENSE  notes-api  README.md

/home/ubuntu/obs-lab/code/notes-api:
Dockerfile  faults.go  go.mod  go.sum  logging.go  main.go  main_test.go
metrics.go  store.go  telemetry.go
  • metrics.go liefert die Kennzahlen unter /metrics (Tag 1), logging.go die Logs (Tag 8), telemetry.go ist der Platz für Traces (Tag 10).
  • faults.go baut Störungen ein: Mit NOTES_DELAY wird jede Anfrage langsamer, mit NOTES_ERROR_RATE scheitert ein Teil. Du brauchst sie, um Alarme auszulösen.

Bauen:

cd ~/obs-lab/code/notes-api
docker build -q -t notes-api:0.8.0 --build-arg VERSION=0.8.0 .

Erwartet (die Prüfsumme weicht ab):

sha256:daa3b9a5edafbd1f499d698bba4fcbeb7a7b8c552053e7dd8834aefedf9ab4e2

k3s hat seinen eigenen Container-Speicher und sieht die Images von Docker nicht. Du reichst das Image hinüber:

docker save notes-api:0.8.0 | sudo k3s ctr images import -
sudo k3s ctr images ls -q | grep notes-api:0.8.0

Erwartet (gekürzt):

docker.io/library/notes api:0.8.0         saved
Importing  elapsed: 0.8 s  total:   0.0 B  (0.0 B/s)
docker.io/library/notes-api:0.8.0
  • docker save schreibt das Image als Archiv auf die Standardausgabe, ctr images import - liest es dort. Kein Registry-Umweg nötig.
  • Im Manifest steht image: notes-api:0.8.0. Kubernetes ergänzt das zu docker.io/library/notes-api:0.8.0 und findet es lokal – bei einem festen Tag zieht es nicht neu.

Fortschritt speichern? Kostenlos registrieren

Drill 6: notes-api im Cluster

Die Manifeste liegen unter k8s/. Lies sie einmal durch, bevor du sie anwendest:

cd ~/obs-lab/code
less k8s/notes-api.yaml
  • Zwei Pods, ein Service notes-api vom Typ NodePort auf Port 30080.
  • Der Init-Container migrate legt die Tabelle an, bevor notes-api startet.
  • Der Port heißt http. Den Namen braucht Prometheus an Tag 2.

Zuerst der Namespace und die Zugangsdaten – sie müssen da sein, bevor die Pods starten:

kubectl create namespace app
kubectl -n app create secret generic notes \
  --from-literal=api-key=lab-api-key-123 \
  --from-literal=db-password=lab-db-pw-123 \
  --from-literal=db-url=postgres://notes:lab-db-pw-123@postgres:5432/notes

Erwartet:

namespace/app created
secret/notes created

Dann die Datenbank, die Anwendung und die Last:

kubectl apply -f k8s/postgres.yaml -f k8s/notes-api.yaml -f k8s/last.yaml
kubectl -n app get pods -w

Erwartet (nach ein bis zwei Minuten, Strg+C beendet -w):

NAME                         READY   STATUS    RESTARTS      AGE
last-59b8c4f56-dztnp         2/2     Running   0             40s
notes-api-5499c6f889-6prq5   1/1     Running   0             40s
notes-api-5499c6f889-bthrf   1/1     Running   0             40s
postgres-0                   1/1     Running   0             40s

Ein oder zwei Neustarts bei notes-api sind normal: Der Init-Container migrate scheitert, solange Postgres noch nicht bereit ist, und Kubernetes versucht es wieder.

Achtung: Hängt postgres-0 bei 0/1, ohne je eine Logzeile zu schreiben? Ubuntu-Kernel 7.0.0-42 hat einen Fehler im AppArmor-Profil von containerd: gosu im Postgres-Image kommt nicht aus seiner Schleife, und die Anmeldung über den Unix-Socket hängt. Darum steht in k8s/postgres.yaml für diesen einen Pod appArmorProfile: Unconfined. Prüfe mit uname -r, welchen Kernel du hast.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

curl -s localhost:30080/version

Erwartet:

0.8.0
curl -s localhost:30080/notes | jq length

Erwartet (frühestens zwei Minuten nach dem Start):

100

Der Lastgenerator schreibt eine Notiz pro Sekunde, /notes liefert die neuesten 100. Kurz nach dem Start sind es weniger.

kubectl -n app logs deploy/last -c schreiben

Erwartet: keine Ausgabe. Mit -sS zeigt curl keinen Fortschritt, aber jeden Fehler. Nach einem Rollout von notes-api steht hier gelegentlich Connection timed out: Eine Anfrage ging noch an einen alten Pod, nach fünf Sekunden (-m 5) gibt curl auf und macht weiter.

Challenge

Lege von Hand eine Notiz mit dem Text „Hallo Observability“ an. Der Lastgenerator zeigt im Manifest, wie es geht.

Hinweis: grep -A3 schreiben k8s/last.yaml – Header, Daten, URL.

Lösung

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

Erwartet (die ID weicht ab):

{"id":"0b6c1f0e-7f1a-4a7e-9d8e-5f2c3b1a9e44","text":"Hallo Observability"}

Mit -d schickt curl automatisch ein POST.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Eigener Cluster für Observability: In größeren Umgebungen läuft der Beobachtungs-Stack nicht neben der Anwendung, sondern zentral. Fällt der Anwendungs-Cluster aus, sollen die Werkzeuge, die den Ausfall zeigen, weiterlaufen.
  • Images aus einer Registry: docker save | ctr import ist ein Lab-Trick. Im Betrieb kommen Images aus einer Registry, mit festem Tag oder Digest.
  • Lastgeneratoren: Für echte Lasttests gibt es k6, Locust oder vegeta. Für dieses Buch reicht curl --rate: gleichmäßige Last, ein Container, keine Skripte.