Zum Inhalt springen
Trainingslager IT-Trainingslager

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 /metrics und hat eingebaute Störungen, die du per Umgebungsvariable einschaltest.
  • Alles läuft als Docker-Compose-Projekt am-lab auf einer VM. Jeder Baustein bekommt eine eigene kleine Datei, compose.yaml bindet sie mit include: ein.
  • Ein Container last ruft 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. noble ist der Codename von Ubuntu 24.04.
  • jq brauchst du, um JSON-Antworten der APIs lesbar zu machen.
  • 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
docker compose version

Erwartet:

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 code

Erwartet:

alarm-log  LICENSE  loesung  notes-api  README.md
  • notes-api ist der Quellcode der API mit Dockerfile.
  • alarm-log ist ein kleiner Webhook-Empfänger, den du ab Tag 2 brauchst.
  • loesung enthält alle Dateien des Labs: endstand nach Tag 15, pruefung nach Anhang B. Wer festhängt, vergleicht dort mit diff.

~/.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-api

Erwartet (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" > .env

Dann 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:
EOF
  • migrate startet 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, sonst 0. 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/notes

Erwartet:

{"id":"744d3cb6-7070-42f2-b649-ba66aaf1d260","text":"Hallo Alertmanager"}
curl -s localhost:8080/notes

Erwartet:

[{"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_up ist 1, solange Postgres antwortet. Der Healthcheck von Docker ruft alle zehn Sekunden /healthz auf und hält den Wert aktuell.
  • notes_http_requests_total zählt Anfragen nach Pfad und Statuscode. Die Zahl für /notes wächst, weil last lä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/version

Erwartet: 0.8.0.

curl -s localhost:8080/metrics | grep notes_db_up

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

Erwartet:

200 0.314160
docker compose logs notes-api | grep faults

Erwartet:

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

Erwartet:

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_DELAY sind 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.