Lernleitfaden: Praxisteil 11. Integration mit einer echten API: von der Spezifikation bis zum Deployment

Thema: Praxisteil 11. Integration mit einer realen API: von der Spezifikation bis zum Deployment

Schwierigkeitsgrad: Mittelstufe

Geschätzte Lernzeit: 4-6 Stunden

Voraussetzungen: Vertrautheit mit den SDD-Konzepten (Specify, Plan, Tasks, Implement, Validate) aus den Teilen 7-9 des ersten Bandes.

Verständnis der Prinzipien des Code-Reviews (Teil 16 des ersten Bandes).

Grundkenntnisse im Umgang mit der CLI (Kommandozeile) und Python.

Allgemeines Verständnis der Funktionsweise von Webhooks und REST-APIs.

Lernziele: Den lokalen Incident-Processing-Pipeline beherrschen: vom Rohtext-Webhook zum normalisierten Ereignis und zur Readiness-Überprüfung.

Das 25-Punkte-Readiness-Bewertungsmodell anwenden, um über die Zulassung der Auto-Remediation zu entscheiden.

Blockierende Bedingungen (audit_trace, stateful workloads) verstehen und erkennen können, bevor reale Aktionen ausgeführt werden.

Die Phasentrennung in SDD beherrschen, damit die Spezifikation (specify) nicht die Implementierungsphase (implement) ersetzt.

API- und Pipeline-Fehler gemäß der Taxonomie (VALIDATION_ERROR, LLM_CALL_FAILED u.a.) klassifizieren können, um eine Wiederherstellungsstrategie auszuwählen.

Überblick: Dieses Kapitel befasst sich mit der praktischen Integration mit einer realen API im Kontext des Incident-Managements und der Auto-Remediation. Sie lernen, die Pipeline sicher vom Empfang des Rohtext-Webhooks (Grafana/PagerDuty) bis zum kontrollierten Deployment oder Neustart zu führen. Als primärer Lernfall dient der Produktionsvorfall high_memory_usage. Das Kapitel zeigt, wie man mit Skripten aus examples/real-api/ Daten normalisiert, das Readiness-Gateway auf Basis der 25-Punkte-Rubrik durchläuft und einen Probelauf (Dry-Run) durchführt, wobei sichergestellt wird, dass verbotene Aktionen blockiert und erlaubte Aktionen streng begründet werden.

Schlüsselkonzepte: Readiness (Bereitschaft): Formale Bewertung der Pipeline auf einer 25-Punkte-Skala. Umfasst 5 Kategorien (Spec, Implementation, Verification, Process, Security), die von 0 bis 5 bewertet werden. Die Schwelle für die automatische Zulassung liegt bei 23/25. Liegt die Punktzahl darunter, wechselt die Pipeline in den halbmanuellen Modus.

SDD-Phasentrennung: Eine Methodik, die den Lebenszyklus einer Änderung in Phasen unterteilt: Specify (User Story), Plan (Strategie), Tasks (Schritte), Implement (Anwendung), Validate (Überprüfung). Schützt das System vor vorzeitiger Befehlsausführung ('sofort heilen').

Audit Trace (Audit-Trail): Ein kausal-zusammenhängendes Bindungsprotokoll, das den eingehenden Webhook, Benutzerbefehle (z.B. /sdd:specify), erstellte Spezifikationen und Unterschiede (diff) über eine eindeutige incident_id verbindet. Gewährleistet die Beweisbarkeit und Reproduzierbarkeit des Vorfalls.

Dry-Run (Probelauf): Simulation der Ausführung einer Aktion gegen eine Liste vorab genehmigter Aktionen (pre-approved actions), ohne tatsächliche Änderungen an der Infrastruktur vorzunehmen. Ermöglicht die Überprüfung, ob die Aktion durch die Spezifikation erlaubt ist.

Error Taxonomy (Fehlertaxonomie): Klassifizierung von API-Ausfällen (z.B. VALIDATION_ERROR, TOOL_EXECUTION_FAILED), die es dem Orchestrator ermöglicht, die richtige Wiederherstellungsstrategie zu wählen (Stopp, Wiederholung, Degradation, Eskalation) anstatt einen allgemeinen Status 'failed' auszugeben.

Degraded Mode (Degradierter Modus): Ein Systemzustand, in dem die Auto-Remediation deaktiviert wird (z.B. bei LLM-Ausfall oder niedriger Readiness-Bewertung), das System aber weiterhin Beweise sichert und dem Bediener Schritte zur manuellen Bestätigung vorschlägt.

Übungsaufgaben: Titel: Normalisierung eingehender Webhooks

Problem: Sie haben Rohtext-Payloads von den Monitoring-Systemen Grafana und PagerDuty erhalten. Sie müssen das Normalisierungsskript ausführen und sicherstellen, dass die ausgegebene JSON Feld für Feld mit dem Referenz-Incident-Ereignis übereinstimmt.

Lösung: 1. Wechseln Sie in das Beispielverzeichnis: cd book2/examples/real-api

1. Führen Sie das Normalisierungsskript mit den Pfaden zu den Fixtures aus:

python3 scripts/normalize_webhook.py --grafana fixtures/webhook_grafana.json --pagerduty fixtures/webhook_pagerduty.json --expected fixtures/incident_event.expected.json

1. Stellen Sie sicher, dass das Skript mit dem Rückgabecode 0 beendet wird. Ist der Code ungleich Null, überprüfen Sie stderr auf Schema-Validierungsfehler.

Schwierigkeit: Anfänger

Titel: Überprüfung des Readiness-Gateways

Problem: Bewerten Sie drei verschiedene Systemzustände mit dem Readiness-Überprüfungsskript: bestanden (24/25), Audit-Fehler (22/25) und Stateful-Workload-Fehler (24/25, aber kein Backup).

Lösung: Führen Sie die Skripte nacheinander aus und analysieren Sie die Ausgabe:

1. python3 scripts/check_readiness.py --readiness fixtures/readiness_pass.json (Erwartung: Code 0, PASS).
2. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_audit.json (Erwartung: Code 1, BLOCK wegen audit_trace_coverage).
3. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_stateful.json (Erwartung: Code 1, BLOCK wegen fehlendem bestätigtem Backup für Stateful).

Schwierigkeit: Mittelstufe

Titel: Probelauf erlaubter und verbotener Aktionen

Problem: Verwenden Sie das Dry-Run-Skript, um zwei Aktionen gegen die Spezifikation high_memory_usage zu prüfen. Die erste Aktion (restart_pod) sollte erlaubt sein, die zweite (delete_namespace) sollte als nicht autorisiert blockiert werden.

Lösung: 1. Führen Sie die erlaubte Aktion aus: python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action restart_pod Stellen Sie sicher, dass der Rückgabecode 0 ist und in stdout PASS erscheint.

1. Führen Sie die verbotene Aktion aus:

python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action delete_namespace Stellen Sie sicher, dass der Rückgabecode 1 ist und in stderr der Grund für die Blockierung angegeben ist (Aktion nicht in pre-approved enthalten).

Schwierigkeit: Mittelstufe

Titel: Ausfüllen der Readiness-Rubrik für einen eigenen Fall

Problem: Bewerten Sie auf Basis des 25-Punkte-Modells eine hypothetische (oder Ihre aktuelle) Pipeline. Füllen Sie die Tabelle mit 5 Kategorien aus, geben Sie Beweis-Artefakte an und identifizieren Sie blockierende Bedingungen, um die Schwelle von 23/25 zu erreichen.

Lösung: 1. Erstellen Sie eine Tabelle mit den Spalten: Kategorie, Punktzahl, Beweis-Artefakt, Grund für Reduzierung.

1. Gehen Sie Spec, Implementation, Verification, Process, Security durch.
2. Stellen Sie für Spec sicher, dass WHY/WHAT/constraints vorhanden sind.
3. Überprüfen Sie für Security das Vorhandensein von Rollback und Emergency Stop.
4. Liegt das Ergebnis unter 23/25, erstellen Sie eine Liste von Änderungen (z.B.: 'Formalen Eskalationstrigger hinzufügen', 'Dry-Run für Scale-up-Zweig implementieren').

Schwierigkeit: Fortgeschritten

Fallstudien: Titel: Produktionsvorfall high_memory_usage

Szenario: Das Grafana-Monitoring-System erfasst memory_percent=93 auf dem Pod api-7b4 im Namespace appointments-api für 10 Minuten. PagerDuty eskaliert den Vorfall auf critical. Ein Webhook trifft ein, der den Auto-Remediation-Prozess des Systems auslöst.

Herausforderung: Der Speicherverbrauch muss reduziert werden (OOMKill verhindert), ohne den Service zu stören. Das Ausführen eines automatischen Skripts, das einfach Ressourcen neu startet oder löscht, ist riskant — Stateful-Daten könnten verloren gehen oder der Auswirkungsbereich des Fehlers könnte sich erweitern. Das System muss verstehen, ob es automatisch handeln darf und welche Aktion minimal ist.

Lösung: 1. Normalisierung: Das Skript normalize_webhook.py führt Daten aus Grafana und PagerDuty zu einem einheitlichen incident_event zusammen (incident_id=HM-2026-05-17-01).

1. Readiness-Gateway: check_readiness.py bewertet die Pipeline. Liegt audit_trace unter 1.0 oder ist der Workload Stateful ohne Backup, wird die Aktion bis zum menschlichen Eingriff blockiert.
2. Probelauf: dry_run.py prüft die Aktion restart_pod gegen die Spezifikation (pre-approved actions).
3. Ausführung: Ist readiness >= 23/25 und dry_run ergibt PASS, wird ein Neustart initiiert, mit obligatorischer Überwachung zweier Fenster und Vorhandensein eines Rollback-Pfads nach 6 Minuten.

Ergebnis: Die automatisierte Pipeline isolierte das Problem sicher. Die erlaubte Aktion wurde mit vollständigem Audit (Audit Trail) ausgeführt. Der Versuch der Pipeline, eine nicht erlaubte oder gefährliche Aktion auszuführen, wurde vom Sicherheits-Gateway strikt blockiert, was einen potenziellen Ausfall des gesamten Services verhinderte.

Gelernte Lektionen: Specify sollte keine konkreten Befehle enthalten (z.B. kubectl delete), sondern WHY und WHAT beschreiben.

Der Auswirkungsbereich muss begrenzt sein (z.B. nur ein bestimmter Pod).

Systemausfälle (z.B. LLM-Probleme) sollten es in den Degraded Mode versetzen, nicht vollständig ohne Erklärung stoppen.

Vollständige Auto-Remediation ohne menschliche Beteiligung (Human Review) auf dem kritischen Pfad bleibt eine riskante Praxis (Frontier).

Verwandte Konzepte: Readiness Model

Audit Trace

Dry-Run

Error Taxonomy

Degraded Mode

Lerntipps: Beginnen Sie mit der Ausführung der fertigen Skripte in book2/examples/real-api/. Versuchen Sie nicht sofort, ein vollwertiges Kubernetes oder GitOps einzurichten — für den Lerndurchgang ist die Logik der Skripte wichtig.

Achten Sie besonders auf die Fixtures readiness_block_*.json. Versuchen Sie, die Werte darin zu ändern (z.B. audit_trace_coverage auf 1.0 erhöhen) und beobachten Sie, wie sich das Ergebnis von check_readiness.py ändert.

Vergleichen Sie die 'Schlecht'- und 'Gut'-Beispiele für Spezifikationen (Specify) aus dem Text. Verstehen Sie, warum die Wahl einer konkreten Implementierung in der Spezifikationsphase die Flexibilität der Planung blockiert.

Dokumentieren Sie stets Ihre Läufe und Entscheidungen (z.B. in capstone/readiness.md). Die Integration mit APIs ist nicht nur Code, sondern auch Beweisartefakte (Audit Trace).

Zusätzliche Ressourcen: Lernskripte (examples/real-api): Ordner mit einer sofort ausführbaren Pipeline ohne externe Abhängigkeiten (Python-Standardbibliothek).

Github spec kit: Framework für die praktische Anwendung der Phasen Specify → Plan → Tasks → Implement.

Anhang D (Schwellenwertkalibrierung): Abschnitt D.5 enthält Tabellen zur Anpassung der Readiness-Schwellenwerte (Niedrig/Standard/Hoch) für verschiedene Typen von Produktionsumgebungen.

Book/part-12-mvp.md: Referenzmaterial aus dem ersten Band, das die Arbeit mit SQLite beschreibt und auf dem das Szenario high_memory_usage aufbaut.

Zusammenfassung: In diesem Kapitel haben Sie gelernt, wie man das Chaos realer API-Webhooks (Grafana, PagerDuty) in einen strengen, kontrollierten und beweisbaren Auto-Remediation-Prozess verwandelt. Die wichtigste Erkenntnis: Jede automatische Aktion muss das Readiness-Gate durchlaufen. Die Verwendung des 25-Punkte-Bewertungsmodells und der obligatorische Probelauf (Dry-Run) stellen sicher, dass das System den definierten Auswirkungsbereich nicht überschreitet. Die SDD-Phasentrennung und der Audit Trail gewährleisten Transparenz: Kann das System seine Bereitschaft nicht nachweisen (z.B. aufgrund unvollständigen Audits), wird es in einen sicheren halbmanuellen Modus versetzt.