KI-gestütztes Infrastruktur-Management: So setzen wir Claude Code mit Kubernetes und OpenTofu ein

Kubernetes produktiv über mehrere Cloud-Anbieter zu betreiben, bedeutet: OpenTofu-Konfigurationen, Helm-Charts, Cluster-Health-Checks, Log-Analysen und Deployment-Pipelines gleichzeitig jonglieren — oft unter Druck, wenn um 2 Uhr nachts etwas bricht. In den letzten Monaten habe ich Claude Code als Infrastruktur-Copilot eingesetzt. Der Workflow hat meine Arbeit an unseren Clustern grundlegend verändert.

Dieser Beitrag zeigt die praktischen Muster, die ich dabei entwickelt habe: was gut funktioniert und wie Sie Claude Code so einrichten, dass es für Infra-Arbeit wirklich nützlich wird — statt zum Risiko.

Der Aufbau

Unsere Infrastruktur umfasst aktuell drei Kubernetes-Umgebungen auf zwei Cloud-Anbietern:

• Staging — auf Google Kubernetes Engine
• Produktion — auf Google Kubernetes Engine
• Kundenspezifisches Deployment — auf StackIT im Account des Kunden

Jede Umgebung wird mit OpenTofu verwaltet (dem Open-Source-Fork von Terraform). Ein gemeinsames Helm-Chart deployt unseren Application-Stack. Die Codebasis umfasst 10 OpenTofu-Module, ein Helm-Chart mit 17 Templates und CI/CD über GitHub Actions. Die beiden GCP-Cluster teilen den Großteil ihrer Konfiguration über dieselben OpenTofu-Module. Der StackIT-Cluster hat einige separate Module für StackIT-spezifische Besonderheiten.

Claude Code sitzt im Zentrum dieses Aufbaus — mit direktem Zugriff auf kubectl, tofu plan und einer Reihe eigener Skills, die typische Ops-Aufgaben in Gespräche verwandeln.

Prinzip 1: Sicherheits-Leitplanken sind Pflicht

Das Wichtigste beim KI-Zugriff auf Ihre Infrastruktur: definieren Sie, was die KI nicht darf.

Unsere CLAUDE.md — eine projektweite Anweisungsdatei, die Claude Code automatisch einliest — zieht harte Grenzen:

For safety reasons, you are not allowed to run `tofu apply`. You can however
suggest `tofu apply` commands to the user. The user will review the command
and run it for you. You are free to run `tofu plan` to study its output.

Zusätzlich zur CLAUDE.md sind gefährliche Befehle explizit in der .claude/settings.json verboten.

Das ist das zentrale Design-Pattern: Lesezugriff großzügig, Schreibzugriff nur mit menschlicher Freigabe. Claude Code darf:

• tofu plan ausführen und die Ausgabe analysieren
• Beliebige kubectl get- und kubectl describe-Befehle ausführen, außer für Secrets
• Konfigurationsdateien lesen und bearbeiten
• Exakte Befehle für mich zur Ausführung vorschlagen

Aber es darf nicht:

• Infrastruktur-Änderungen anwenden (tofu apply)
• Ressourcen löschen
• In die Produktion pushen

Die CLAUDE.md enthält außerdem Domänenwissen, das subtile Fehler verhindert:

Changes to `node_config` (including `resource_labels`, `machine_type`,
`oauth_scopes`, `metadata`, etc.) trigger rolling replacement of all nodes
in the affected node pool, causing temporary pod disruptions.

Das heißt: Wenn Claude Code eine Infrastruktur-Änderung vorschlägt, weiß es bereits, dass es mich warnen muss, falls eine Änderung an einem Node-Pool-Attribut einen Rolling Restart aller Nodes auslösen würde. Genau dieses kontextuelle Bewusstsein ist der Unterschied zwischen „nette Demo” und „wirklich nützlich”.

Prinzip 2: Eigene Skills verwandeln wiederkehrende Ops-Aufgaben in Gespräche

Claude Code unterstützt eigene Skills — Markdown-Dateien mit strukturierten Workflows, die die KI bei natürlicher Sprache oder per Slash-Befehl ausführt. Wir haben für die häufigsten Ops-Aufgaben verschiedene Skills gebaut.

Cluster-Health-Checks

Statt mir die exakten kubectl-Beschwörungsformeln für Node-Status, ausstehende PVCs, fehlgeschlagene Jobs und Zertifikatsabläufe zu merken, frage ich einfach:

Das löst den Skill k8s-status aus. Er startet ein Shell-Skript, das Nodes, Pod-Zustände, Ressourcenauslastung, PVC-Status, Zertifikatsablauf und fehlgeschlagene Jobs prüft. Claude Code formatiert das Ergebnis zu einem strukturierten Health-Report mit Gesamtstatus (HEALTHY / WARNING / CRITICAL) und konkreten Handlungsempfehlungen.

Log-Analyse

Der Skill k8s-logs holt Logs aus allen Pods des Deployments, filtert Errors und Warnings, liefert Ausgabe mit Zeitstempeln und Zählern und schlägt die nächsten Schritte vor. Entscheidend: Der Skill wrappt ein Shell-Skript mit Flags für --errors, --previous, --since und --container. Claude Code wählt die passenden Flags intelligent, je nach Frage.

Infrastruktur-Planung

Der Skill tofu-plan kümmert sich um die Umgebungsauswahl, führt den Plan mit korrektem Laden der Umgebungsvariablen über direnv aus, parst die Ausgabe in eine strukturierte Zusammenfassung (X Additions, Y Changes, Z Destructions) und hebt destruktive Änderungen mit deutlichen Warnungen hervor. Anschließend schlägt er den exakten tofu apply-Befehl vor, falls ich weitermachen möchte — führt ihn aber nie selbst aus.

Umgebungs-Vergleich

Der Skill cluster-diff vergleicht main.tf und values.yaml zwischen zwei beliebigen Umgebungen und zeigt Unterschiede in Cluster-Konfiguration, Ressourcenlimits, Replica-Zahlen und Feature-Flags. Unbezahlbar, um Konfigurations-Drift aufzudecken.

Selbstheilende Authentifizierung

Einer der kreativeren Skills: init-cluster behandelt Authentifizierungsfehler bei Kubernetes. Wenn ein kubectl-Befehl mit „certificate has expired” oder „Unauthorized” abbricht, führt der Skill automatisch durch die Re-Authentifizierung — abhängig vom Cloud-Anbieter. GKE nutzt gcloud Re-Auth, StackIT verlangt einen frischen kubeconfig-Download.

Bei StackIT-Clustern, deren Zertifikate nach 7 Tagen ablaufen, spart das überraschend viel Zeit. Wenn alle Stricke reißen, kann der Skill einen Slack-Webhook auslösen und ein Teammitglied um Hilfe bitten — inklusive des konkreten Fehlers und dessen, was bereits versucht wurde.

Prinzip 3: Domänenwissen vermitteln, nicht nur Befehle

In der CLAUDE.md steckt das stille Team-Wissen, das den Unterschied zwischen einem nützlichen Assistenten und einem gefährlichen macht. Ein paar Beispiele aus unserem Setup:

Plattform-spezifische Stolperfallen:

Note: The clusterissuer is called `cert-manager`, not `letsencrypt-prod`.
Note: Alloy requires trailing commas in maps and lists, be sure to add these.

Architektonische Konventionen:

If you add outputs to a module, these outputs should usually also be added
to the top-level `main.tf` file in the respective environment.

If a service uses persistent volumes, make sure to include an appropriate
deploymentStrategy value.

Umgebungs-Bewusstsein:

All commands that interact with a Kubernetes cluster must be run from the
corresponding subdirectory in `opentofu/environments`.

Das ist genau die Sorte Wissen, die sonst in einem Team-Wiki schlummert, das niemand liest, oder nur in jemandes Kopf existiert. In der CLAUDE.md wird es jedes Mal zuverlässig angewendet. Mit der Zeit wird die Datei zu einem lebenden Dokument: Jedes Mal, wenn ich einen Fehler abfange oder merke, dass eine Konvention undokumentiert ist, ergänze ich CLAUDE.md oder passe den jeweiligen Skill an. Der Agent wird jeden Tag besser.

Prinzip 4: Gestaffelte Berechtigungen für den Team-Einsatz

Die settings.json von Claude Code unterstützt feingranulare Berechtigungen. In unserem Setup sind Lese-Operationen vorab freigegeben, während alles, was Zustand ändert, eine Bestätigung verlangt.

Konkret: kubectl get läuft ohne Rückfrage (read-only), die Health-Check- und Log-Skripte sind vorab freigegeben, aber alles Destruktive verlangt eine explizite Bestätigung. Die settings.json liegt im Repo, damit das Team dasselbe Berechtigungsmodell teilt. In der settings.local.json (gitignored) kann jeder Entwickler eigene vertraute Befehle ergänzen.

Dieser gestaffelte Ansatz bedeutet: Neue Teammitglieder bekommen sichere Voreinstellungen, erfahrene Betreiber können sich lokal mehr Autonomie freischalten.

Workflow-Beispiele aus der Praxis

Einen CrashLooping-Pod debuggen

Ich: „Die Celery-Worker crashen auf Dev im Loop — kannst du das untersuchen?”

Claude Code:

1. Führt k8s-status für einen Cluster-Überblick aus — bestätigt, dass die Celery-Pods in CrashLoopBackOff sind
2. Führt k8s-logs mit dem previous-Flag aus, um die Logs des abgestürzten Containers zu holen
3. Führt k8s-describe auf dem Pod aus, um Events, Ressourcenlimits und Container-Status zu prüfen
4. Identifiziert die Ursache (z. B. OOM-Kill durch Memory-Limits)
5. Schlägt einen konkreten Fix in values.yaml mit der richtigen Anpassung des Ressourcenlimits vor
6. Führt tofu plan aus, um zu bestätigen, dass die Änderung nicht destruktiv ist
7. Liefert den exakten tofu apply-Befehl für mich zur Ausführung

Was früher 20 Minuten Terminal-Tab-Hopping waren, wird zu einem einzigen Gespräch.

Infrastruktur-Ressourcen hinzufügen

Ich: „Ich brauche eine neue Redis-Instanz für den Staging-Cluster”

Claude Code:

1. Liest das bestehende Redis-Modul, um das Muster zu verstehen
2. Liest die main.tf der Dev-Umgebung, um zu sehen, wie andere Module instanziiert werden
3. Ergänzt die Modul-Referenz mit passender Konfiguration
4. Aktualisiert Outputs sowohl im Modul als auch in der main.tf der Umgebung (weil die CLAUDE.md es so vorgibt)
5. Prüft values.yaml auf benötigte Helm-Chart-Referenzen
6. Führt tofu plan aus und präsentiert eine Zusammenfassung
7. Warnt mich, falls bestehende Ressourcen betroffen wären

Checkliste vor dem Deployment

Ich: „Vergleiche Dev- und Prod-Konfigurationen, bevor ich promote”

Claude Code:

1. Führt cluster-diff zwischen beiden Umgebungen aus
2. Hebt Unterschiede in Replica-Zahlen, Ressourcenlimits und Feature-Flags hervor
3. Markiert Konfigurationen, die in Dev, aber nicht in Prod existieren (neue Features)
4. Flaggt bedenkliche Abweichungen (z. B. aktiviertes Debug-Flag in Dev)

Der Incident um 2 Uhr nachts

Hier zahlt sich das Setup wirklich aus. Ein Monitoring-Alert schlägt an, ich öffne Claude Code auf meinem Laptop:

Ich: „Cluster-Status auf Prod”

In Sekunden habe ich einen vollständigen Health-Report. Pods sind im Zustand Pending.

Ich: „Beschreibe die Pending-Pods”

Scheduling-Fehler — die Nodes sind ausgelastet.

Ich: „Prüfe die Autoscaler-Logs”

Der Node-Pool-Autoscaler hängt. Von hier aus kann Claude Code den Fix vorschlagen, ich gebe ihn frei, und wir sind wieder online. Die komplette Untersuchung läuft in einem Terminal, in einem Gespräch, mit durchgängig erhaltenem Kontext. Kein Wechseln zwischen Dashboards, kein Nachblättern in Runbooks.

Aufbau eines Skills

Für alle, die eigene Skills bauen wollen, hier ein Beispiel. Jeder Skill ist eine Markdown-Datei in .claude/skills/ mit YAML-Frontmatter:

---
name: k8s-status
description: Get a quick overview of Kubernetes cluster health. Use when
  the user asks "how is the cluster", "cluster status", "any issues in k8s",
  "check cluster health", or "what's wrong with the cluster".
---

# Kubernetes Cluster Status

Provide a comprehensive health check of a Kubernetes cluster.

## Workflow

### 1. Select Environment
If the user hasn't specified an environment, list available environments...

### 2. Run Health Check Script
Run the health check script with the selected environment:
.claude/skills/k8s-status/k8s-status.sh <environment>

### 3. Present Summary
Format the output as a structured health report...

### 4. Provide Recommendations
For each issue found, suggest diagnostic commands...

Das description-Feld ist der Auslöser — Claude Code gleicht natürliche Sprache dagegen ab. Der Body ist ein Schritt-für-Schritt-Workflow, dem die KI folgt. Die Shell-Skripte übernehmen die eigentliche Arbeit, der Skill orchestriert den Ablauf.

Der entscheidende Punkt: Skills sind keine starren Skripte. Sie sind strukturierte Leitlinien. Claude Code passt den Workflow an den Kontext an — wenn ich die Umgebung schon genannt habe, überspringt es die Auswahl. Kommt der Health-Check sauber zurück, entfallen die Empfehlungen. Das Markdown-Format gibt Struktur, ohne starr zu sein.

Was ich gelernt habe

Starten Sie mit reinem Lesezugriff. Gewöhnen Sie sich daran, dass Claude Code Ihre Infrastruktur liest, bevor Sie ihm Änderungsvorschläge erlauben. Cluster-Health-Checks und Log-Analyse liefern sofortigen Nutzen bei null Risiko.

Kodieren Sie Ihre Konventionen. Jedes Mal, wenn Sie sich sagen hören „ach ja, und vergiss nicht, auch noch …” — schreiben Sie es in die CLAUDE.md oder in einen Skill. Je mehr Domänenwissen kodiert ist, desto nützlicher wird die KI. Sehen Sie es als ein Runbook, das tatsächlich befolgt wird.

Skills sind die Investition wert. Einen Skill zu schreiben dauert 30 Minuten. Sobald er einmal einen sechs-Flag-kubectl-Befehl um 2 Uhr nachts erspart, hat er sich amortisiert. Der strukturierte Workflow sorgt auch dafür, dass Claude Code jedes Mal denselben Diagnoseprozess durchläuft — das schafft Vertrauen und Konsistenz.

Die menschliche Freigabe bei Schreib-Operationen ist unverzichtbar. Ich habe die manuelle Freigabe für tofu apply nie bereut. Ich war aber mehrfach froh, dass die Leitplanke da war, als eine scheinbar harmlose Änderung das Neu-Aufsetzen eines Node-Pools ausgelöst hätte.

Umgebungs-Bewusstsein über mehrere Cluster zahlt sich aus. Pro-Umgebung-Konfigurationen, durch die Claude Code automatisch navigiert (über direnv und kubeconfig-Pfade), bedeuten: Ich kann „prüfe die Logs auf Prod” sagen, ohne mir Sorgen um Kontextwechsel zu machen oder aus Versehen Befehle gegen den falschen Cluster zu jagen.

Die KI wird besser, je besser Ihre Dokumentation wird. Es entsteht ein positiver Kreislauf: Claude Code für Infra-Management zu nutzen, motiviert dazu, Konventionen sauber zu dokumentieren — und bessere Dokumentation macht die KI nützlicher. Nach ein paar Monaten ist unsere CLAUDE.md das genaueste und aktuellste Stück Dokumentation im Projekt.

Der Einstieg

Wenn Sie diesen Ansatz ausprobieren möchten:

1. Legen Sie eine CLAUDE.md in Ihrem Infra-Repo an — mit Konventionen, Stolperfallen und harten Grenzen (was die KI niemals tun darf)
2. Starten Sie mit einem Health-Check-Skill — das ist der Einstieg mit dem geringsten Risiko und dem höchsten Nutzen
3. Fügen Sie Berechtigungen in der settings.json hinzu, die Lese-Operationen vorab freigeben und bei Schreib-Operationen Bestätigung verlangen
4. Ergänzen Sie Skills schrittweise für Ihre häufigsten Ops-Aufgaben: Log-Prüfung, Ressourcen-Beschreibung, Plan-Analyse
5. Kodieren Sie Team-Wissen sofort, wenn Sie es entdecken — jedes „Achtung, …” wird eine Zeile in der CLAUDE.md

Das Ziel ist nicht, Infrastruktur-Betreiber zu ersetzen. Es ist, ihnen einen Copilot an die Seite zu stellen, der sich an jede Konvention erinnert, nie vergisst, auf destruktive Änderungen zu prüfen — und um 2 Uhr nachts verfügbar ist, ohne zu meckern.