Tag 0: Das Trainingsgelände
Ziel: Eine Lab-VM mit Docker, der Begleitcode und notes-api mit Postgres als Compose-Projekt, das rund um die Uhr Anfragen bekommt. · Dauer: ca. 40 min · Voraussetzung: keine
Briefing
- Alarme brauchen etwas, das kaputtgehen kann. Hier ist das
notes-api, eine kleine Notiz-API in Go mit Postgres.
Sie liefert Metriken unter
/metricsund hat eingebaute Störungen, die du per Umgebungsvariable einschaltest. - Alles läuft als Docker-Compose-Projekt
am-labauf einer VM. Jeder Baustein bekommt eine eigene kleine Datei,compose.yamlbindet sie mitinclude:ein. - Ein Container
lastruft notes-api zweimal pro Sekunde auf. So entstehen Metriken, ohne dass du selbst klicken musst.
Laptop ──ssh──► VM karma
└─ Docker Compose, Projekt am-lab
├─ postgres (intern)
├─ migrate (legt die Tabelle an, endet dann)
├─ notes-api :8080
└─ last ── GET /notes alle 0,5 s ──► notes-api
Drill 1: Die Lab-VM
Du brauchst eine Linux-VM mit Ubuntu 24.04:
| vCPU | RAM | Platte | Hinweis |
|---|---|---|---|
| 2 | 4 GB | 30 GB | reicht, in Tag 13 hältst du das Compose-Lab an |
| 4 | 8 GB | 40 GB | empfohlen |
Auf dem Laptop geht das zum Beispiel mit Multipass
von multipass.run:
multipass launch 24.04 --name karma --cpus 4 --memory 8G --disk 40G
multipass info karma | grep IPv4
Jede andere Linux-VM mit sudo und Internetzugang tut es
auch. Ab hier läuft alles in der VM. Im Buch hat sie
den Namen karma und die Adresse 172.16.0.61.
Setze deine Adresse ein.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Docker
Die Pakete kommen direkt von Docker, nicht aus Ubuntu:
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: noble
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 docker-compose-plugin jq git >/dev/null
sudo usermod -aG docker ubuntu- Zuerst der Schlüssel, mit dem Docker seine Pakete signiert, dann die
Paketquelle.
nobleist der Codename von Ubuntu 24.04. jqbrauchst du, um JSON-Antworten der APIs lesbar zu machen.usermod -aG dockererlaubt dem Benutzerubuntu, Docker ohnesudozu nutzen.
Melde dich ab (exit) und wieder an, damit die Gruppe
docker gilt:
docker --version
docker compose versionErwartet:
Docker version 29.10.0, build fdd4b8e
Docker Compose version v5.7.1
Fortschritt speichern? Kostenlos registrieren
Drill 3: Begleitcode
Alle Dateien, die du nicht selbst schreibst, liegen auf GitHub:
mkdir -p ~/am-lab ~/.local/bin
cd ~/am-lab
git clone -q https://github.com/thomaszachmann/karma-zum-anfassen.git code
ls codeErwartet:
alarm-log LICENSE loesung notes-api README.md
notes-apiist der Quellcode der API mit Dockerfile.alarm-logist ein kleiner Webhook-Empfänger, den du ab Tag 2 brauchst.loesungenthält alle Dateien des Labs:endstandnach Tag 15,pruefungnach Anhang B. Wer festhängt, vergleicht dort mitdiff.
~/.local/bin nimmt die Werkzeuge promtool
und amtool auf. Ubuntu nimmt den Ordner beim Anmelden in
den PATH auf, sobald er existiert. Melde dich deshalb noch
einmal ab und wieder an.
Fortschritt speichern? Kostenlos registrieren
Drill 4: notes-api bauen
cd ~/am-lab/code/notes-api
docker build -q -t notes-api:0.8.0 --build-arg VERSION=0.8.0 .
docker images notes-apiErwartet (der Bau dauert beim ersten Mal etwa zwei Minuten):
sha256:3ae748d35772de0ba060294f8c8cec07b6d7a6da746960a2763d8202bf26a895
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
notes-api:0.8.0 3ae748d35772 22.3MB 5.82MB
Das Image enthält nur die Go-Binärdatei und die CA-Zertifikate. Es
wird nicht in eine Registry geschoben. Compose findet es lokal unter dem
Namen notes-api:0.8.0.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Das Compose-Projekt
Zuerst eine Datei .env. Compose liest sie automatisch
und setzt daraus Variablen in den anderen Dateien ein.
VM_IP brauchst du ab Tag 1:
cd ~/am-lab
echo "VM_IP=172.16.0.61" > .envDann der erste Baustein, notes.yaml:
cat > notes.yaml <<'EOF'
services:
postgres:
image: postgres:18.7
environment:
POSTGRES_USER: notes
POSTGRES_PASSWORD: lab-db-pw-123
POSTGRES_DB: notes
volumes:
- pgdata:/var/lib/postgresql
healthcheck:
test: ["CMD", "pg_isready", "-U", "notes"]
interval: 5s
migrate:
image: notes-api:0.8.0
command: ["migrate"]
environment:
NOTES_DB_URL: postgres://notes:lab-db-pw-123@postgres:5432/notes?sslmode=disable
depends_on:
postgres:
condition: service_healthy
notes-api:
image: notes-api:0.8.0
environment:
NOTES_DB_URL: postgres://notes:lab-db-pw-123@postgres:5432/notes?sslmode=disable
NOTES_API_KEY: lab-api-key-123
NOTES_ERROR_RATE: ${NOTES_ERROR_RATE:-0}
NOTES_DELAY: ${NOTES_DELAY:-0s}
ports:
- "8080:8080"
depends_on:
migrate:
condition: service_completed_successfully
last:
image: curlimages/curl:8.23.0
entrypoint: ["sh", "-c"]
command: ["while true; do curl -s -o /dev/null -m 5 http://notes-api:8080/notes; sleep 0.5; done"]
depends_on:
- notes-api
volumes:
pgdata:
EOFmigratestartet einmal, legt die Tabelle an und endet. Erst danach startet notes-api (service_completed_successfully).${NOTES_ERROR_RATE:-0}heißt: Wert aus der Shell oder.env, sonst0. Damit schaltest du später Störungen ein, ohne die Datei zu ändern.- Postgres 18 erwartet das Volume unter
/var/lib/postgresql, nicht mehr unter…/data.
Jetzt die Hauptdatei, die alle Bausteine zusammenführt:
cat > compose.yaml <<'EOF'
name: am-lab
include:
- notes.yaml
EOF
docker compose up -d
docker compose ps --format '{{.Service}} {{.Status}}'Erwartet:
last Up 8 seconds
notes-api Up 9 seconds (healthy)
postgres Up 16 seconds (healthy)
migrate fehlt in der Liste, weil der Container schon
fertig ist. docker compose ps -a zeigt ihn mit
Exited (0).
Fortschritt speichern? Kostenlos registrieren
Drill 6: notes-api ausprobieren
Eine Notiz anlegen. Schreiben braucht den API-Key, Lesen nicht:
curl -s -X POST -H "X-API-Key: lab-api-key-123" \
-d '{"text":"Hallo Alertmanager"}' localhost:8080/notesErwartet:
{"id":"744d3cb6-7070-42f2-b649-ba66aaf1d260","text":"Hallo Alertmanager"}
curl -s localhost:8080/notesErwartet:
[{"id":"744d3cb6-7070-42f2-b649-ba66aaf1d260","text":"Hallo Alertmanager"}]
Und die Metriken, aus denen ab Tag 1 Alarme werden:
curl -s localhost:8080/metrics | grep '^notes_'Erwartet (gekürzt):
notes_build_info{store="postgres",version="0.8.0"} 1
notes_db_up 1
notes_http_requests_total{code="200",method="GET",path="/healthz"} 2
notes_http_requests_total{code="200",method="GET",path="/notes"} 23
notes_http_requests_total{code="201",method="POST",path="/notes"} 1
…
notes_db_upist 1, solange Postgres antwortet. Der Healthcheck von Docker ruft alle zehn Sekunden/healthzauf und hält den Wert aktuell.notes_http_requests_totalzählt Anfragen nach Pfad und Statuscode. Die Zahl für/noteswächst, weillastläuft.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
docker compose ps --format '{{.Service}} {{.Status}}'Erwartet: notes-api und postgres sind
healthy, last ist Up.
curl -s localhost:8080/versionErwartet: 0.8.0.
curl -s localhost:8080/metrics | grep notes_db_upErwartet: notes_db_up 1.
Challenge
Starte notes-api so, dass jede Anfrage an /notes 300
Millisekunden wartet. Miss die Antwortzeit mit curl. Stelle
danach den Normalzustand wieder her.
Hinweis: Die Variable NOTES_DELAY liest
Compose aus der Shell. curl -w '%{time_total}' gibt die
Dauer aus.
Lösung
NOTES_DELAY=300ms docker compose up -d notes-api
curl -s -o /dev/null -w '%{http_code} %{time_total}\n' localhost:8080/notesErwartet:
200 0.314160
docker compose logs notes-api | grep faultsErwartet:
notes-api-1 | time=2026-11-16T19:12:55.138Z level=WARN msg="faults enabled" delay=300ms error_rate=0
Ohne die Variable setzt Compose wieder 0s ein und
erzeugt den Container neu:
docker compose up -d notes-api
curl -s -o /dev/null -w '%{http_code} %{time_total}\n' localhost:8080/notesErwartet:
200 0.005120
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Ein Lab auf einer VM ersetzt keine Staging-Umgebung. Alarme testest du im Betrieb trotzdem gegen echte Ausfälle, nicht nur gegen künstliche Störungen.
- Eingebaute Störungen wie
NOTES_DELAYsind ein gutes Muster für Gamedays. In Produktion gehören sie hinter ein Feature-Flag, nie in die Standardkonfiguration. - Passwörter stehen hier im Klartext in
notes.yaml. Im Betrieb gehören sie in Docker-Secrets, einen Vault oder Kubernetes-Secrets.