Building a Safer Kubernetes AI Agent with Kiro
I used Kiro to map Kube-AutoFix’s architecture, document safety guardrails, and create reusable prompts for Kubernetes AI agents.
The Architecture Clarity Problem
TL;DR: I built Kube-AutoFix, a Kubernetes debugging agent that proposes safe YAML fixes using GPT-4o. Kiro helped me map the codebase, document safety boundaries, and turn the system into a review-ready project. This post shares the architecture, the exact Kiro prompts, and a 3-step workflow you can reuse on any multi-module project today.
What happens when an AI agent is allowed to propose fixes for Kubernetes manifests?
That question is exciting — until you realize how dangerous it is. Infrastructure agents need boundaries, validation, and architecture clarity. Without all three, you're not building a tool; you're building a liability.
I built Kube-AutoFix as a proof-of-work prototype: an autonomous Kubernetes debugging agent using GPT-4o structured outputs, Pydantic validation, YAML safety checks, dry-run support, and namespace isolation.
After the prototype worked, I couldn't easily explain how it worked, why it was structured the way it was, or where the safety boundaries lived. That is where Kiro entered — not as a code generator, but as an architecture partner.
Try This Yourself First
Skip ahead if you want the full project story. But if you just want the Kiro prompts that gave me the most value here they are, copy-paste ready:
Prompt 1 Codebase ingestion:
1
2
3
Analyze this whole project folder and each file separately. Explain what it
contains, each code part, each function. Then give me a module dependency
tree showing how [your main orchestrator] coordinates the other components.Prompt 2 Architectural reasoning:
1
2
3
For each module, explain not just what it does but WHY it was designed that
way. Focus on safety decisions, architectural trade-offs, and anything a new
contributor would need to understand before touching the code.Prompt 3 Safety boundary audit:
1
2
What are the safety boundaries in this system, and are any of them
implicit rather than explicit?Take the output → paste as your README skeleton. You will have a contribution-ready codebase in an afternoon. The full story of how I used these prompts is below.
Architecture Overview
Kube-AutoFix runs a deterministic autonomous loop:
1
2
3
4
5
6
7
1. Deploy → Apply a (potentially broken) YAML manifest to Kubernetes
2. Monitor → Poll pod status every 5 seconds
3. Detect → Identify failures (ImagePullBackOff, CrashLoopBackOff, OOMKilled…)
4. Debug → Collect pod describe output, logs, and events
5. Reason → Send diagnostics + YAML to GPT-4o → structured remediation proposal
6. Fix → Apply corrected manifest (Pydantic-validated, namespace-locked)
7. Repeat → Up to max 5 iterations, then stopTools integrated:
| Layer | Tool / Service | Purpose |
|---|---|---|
| AI Reasoning | OpenAI GPT-4o (Structured Outputs) | Diagnose failures, generate corrected YAML |
| Schema Validation | Pydantic v2 | Strict typed models for every data structure |
| Kubernetes Client | kubernetes Python SDK | Deploy, monitor, debug cluster resources |
| Observability | MLflow Tracing | Causal decision traces — why the agent chose each branch |
| CLI / UI | Click + Rich | Terminal interface with spinners, syntax highlighting |
| AI Development | Kiro | Architecture analysis, documentation, spec-driven clarity |
Safety constraints:
- Namespace-locked to
autofix-agent-env— cannot escape to other namespaces - Every LLM response validated via Pydantic + OpenAI
response_format temperature=0.2deterministic repairs, not creative rewrites- Max 5 iterations the agent stops rather than loops forever
- Dry-run mode reports what it would do without applying changes
The full Kube-AutoFix architecture: deploy → monitor → detect…
Module dependency view: how AgentLoop orchestrates…
The full Kube-AutoFix architecture: deploy → monitor → detect → debug → GPT-4o reason → fix → repeat. Namespace-locked to
autofix-agent-env. Failure path exits after max 5 iterations.Module dependency view: how
AgentLoop orchestrates KubeDeployer, KubeMonitor, KubeDebugger, and LLMEngine — each independently testable and strictly typed.This is not a theoretical system. The cluster it ran on was a real AWS EKS cluster provisioned with
eksctl:eksctl create cluster output: autofix-cluster in us-east-1, 2 × t3.medium nodes, CloudFormation stack deployed, kubeconfig saved, both nodes ready ✅ "EKS cluster is ready." This is the cluster Kube-AutoFix ran against during development and testing.
eksctl create cluster output: autofix-cluster in us-east-1…
My Kiro Workflow (Step by Step)
Phase 1: Codebase Ingestion — What, Where, and How
With 10+ Python files and 7 Pydantic models, I knew how each module worked in isolation. I could not explain how they worked together — which made it impossible to write good documentation or answer reviewer questions.
I opened the project in Kiro and ran Prompt 1 (from the "Try This Yourself" section above). What Kiro produced in under 10 minutes:
- Module dependency map — how
AgentLooporchestratesKubeDeployer,KubeMonitor,KubeDebugger, andLLMEngine - Data flow trace —
PodStatus → DebugBundle → LLMDiagnosis → DeploymentResult - Safety flag — flagged the hardcoded
KUBE_NAMESPACEconstant as an intentional guardrail, not a missing feature
Kiro analyzing the Kube-AutoFix project: the right panel shows the exact prompt…
Kiro analyzing the Kube-AutoFix project: the right panel shows the exact prompt I used, Kiro reading files in real time, and the
PROJECT-ANALYSIS.md output being generated. The left panel shows the full project structure Kiro traversed 10+ modules including core/, k8s/, llm/, observability/, and tests/.Phase 2: Architectural "Why" Analysis
Reviewers kept asking why I made specific design decisions. I ran Prompt 2. Selected Kiro outputs:
config.py:KUBE_NAMESPACE = "autofix-agent-env"is hardcoded intentionally — a safety guardrail. Making it user-configurable would allow the agent to escape its sandbox.
llm/engine.py:temperature=0.2— enforces deterministic fixes. The LLM does not get creative with infrastructure manifests.
k8s/deployer.py:_RESOURCE_REGISTRYmaps resource kinds to API class/method names. This avoids dynamic dispatch — critical when a wrong resource kind creates real cluster state.
Before vs. after:
| Before Kiro | After Kiro |
|---|---|
| Data flow in my head, not documented | PodStatus → DebugBundle → LLMDiagnosis → DeploymentResult explicit |
| Namespace lock in code, unexplained | Documented as a named safety boundary |
| YAML validation in 3 places, no map | Layers identified: Pydantic → YAML syntax → namespace override check |
| "Why temperature=0.2?" (reviewer question) | Answer ready: "deterministic fixes — no creative infrastructure rewrites" |
Phase 3: Spec → README
Kiro's analysis produced this dependency tree, used directly in my README and Cookbook PR:
1
2
3
4
5
6
7
main.py
└── AgentLoop (core/agent_loop.py)
├── KubeDeployer (k8s/deployer.py) → applies YAML to cluster
├── KubeMonitor (k8s/monitor.py) → polls pod health every 5s
├── KubeDebugger (k8s/debugger.py) → collects describe/logs/events
└── LLMEngine (llm/engine.py) → asks GPT-4o to fix the YAML
└── LLMDiagnosis (core/models.py) → structured Pydantic schemaThree artifacts came directly from this output: the project README architecture section, the OpenAI Cookbook PR safety guardrails description (7 LLM rules, 3 validation layers), and all function docstrings.
The Agent in Action
Input:image: nginx:latestttt(typo in manifest)
Agent detects:ImagePullBackOff
GPT-4o diagnoses: Image tag does not exist in Docker Hub
GPT-4o proposes:image: nginx:latest
Validation: Pydantic ✅ → YAML syntax ✅ → namespace lock ✅
Result: Pods →Running✅ in 1 iteration
Real terminal output from a live run: Iteration 1/5 detects ImagePullBackOff…
MLflow artifact view for the ImagePullBackOff run: iteration_1/corrected.yaml…
Real terminal output from a live run: Iteration 1/5 detects
ImagePullBackOff for nginx:latestttt across two pods. The red "Failure Detected" panel shows the structured failure data — pod name, state, reason, image, and full error message — exactly as collected by KubeDebugger and passed to LLMEngine.Observability: MLflow tracing captures the full decision tree not just that the agent ran, but why it chose each branch.
MLflow artifact view for the
ImagePullBackOff run: the iteration_1/corrected.yaml artifact shows the exact fix GPT-4o produced — image: nginx:latest. Also stored: changes.txt, debug_summary.txt, and root_cause.txt — a complete audit trail for every remediation attempt.Key Learnings
1. Kiro is an architecture partner, not a code generator.
Most AI tools want to write code. Kiro helps you understand the code you've already written a more valuable use case for complex multi-module systems.
Most AI tools want to write code. Kiro helps you understand the code you've already written a more valuable use case for complex multi-module systems.
2. Always ask "why", not just "what".
The single most useful prompt pattern: "Explain not just what this does but why it was designed this way." This surfaces design intent that most documentation never captures and is exactly what reviewers and new contributors need.
The single most useful prompt pattern: "Explain not just what this does but why it was designed this way." This surfaces design intent that most documentation never captures and is exactly what reviewers and new contributors need.
3. Documentation as a forcing function.
Asking Kiro to explain the architecture revealed gaps: functions doing too much, validation scattered across three places, safety boundaries that existed in code but nowhere in documentation. The analysis forced better design decisions.
Asking Kiro to explain the architecture revealed gaps: functions doing too much, validation scattered across three places, safety boundaries that existed in code but nowhere in documentation. The analysis forced better design decisions.
4. Clarity multiplies collaboration.
New contributors will understand the architecture in minutes instead of hours. That is a large multiplier for any open-source project.
New contributors will understand the architecture in minutes instead of hours. That is a large multiplier for any open-source project.
Results and Proof of Work
- OpenAI Cookbook PR submitted after Kiro-assisted documentation cleanup → Codex automated review found no major issues after several iterations. This project was submitted as an OpenAI Cookbook contribution and refined through automated review feedback a meaningful signal that the architecture had become clear and safe enough for external evaluation Link to that PR .
- GitHub: github.com/azaynul10/kube-autofix — full setup guide, dry-run instructions, and Kiro-generated architecture documentation
- Reproducible workflow: The three prompts above work on any multi-module Python project — not just this one
Kiro Product Feedback
I want to give feedback specific enough to be useful to the product team.
What Kiro did well:
- Grasped the full Agentic Loop across 10+ modules without needing file-by-file prompting
- Surfaced design intent (the why), not just descriptions (the what)
- Traced complex data flows:
PodStatus → DebugBundle → LLMDiagnosis - Produced output close enough to publication-ready that it shaved hours off README and PR writing
Pain point 1 Severity: Medium (workflow efficiency)
Architecture analysis is hard to export cleanly. Markdown structure from Kiro's output was inconsistent enough that I had to manually reformat it for the README.
Suggested feature: One-click "Export to README-ready Markdown" with consistent heading hierarchy, code blocks, and table formatting.
Architecture analysis is hard to export cleanly. Markdown structure from Kiro's output was inconsistent enough that I had to manually reformat it for the README.
Suggested feature: One-click "Export to README-ready Markdown" with consistent heading hierarchy, code blocks, and table formatting.
Pain point 2 Severity: Medium (communication and onboarding)
Kiro does not generate visual diagrams from codebase analysis. I had to manually draw the module dependency tree.
Suggested feature: Auto-generate Mermaid diagrams from detected module structure — usable directly in GitHub READMEs and documentation sites without extra tooling.
Kiro does not generate visual diagrams from codebase analysis. I had to manually draw the module dependency tree.
Suggested feature: Auto-generate Mermaid diagrams from detected module structure — usable directly in GitHub READMEs and documentation sites without extra tooling.
Pain point 3 Severity: High (safety-critical AI agent projects)
No built-in checklist for safety-critical AI agent review. I manually verified namespace isolation, iteration caps, validation layers, prompt injection risks, and LLM output validation — with no systematic support.
Suggested feature: A "Safety Audit" mode — a guided checklist for AI agent projects covering namespace scope, output validation, retry logic, and determinism settings. Immediately valuable for anyone building LLM-powered infrastructure tooling.
No built-in checklist for safety-critical AI agent review. I manually verified namespace isolation, iteration caps, validation layers, prompt injection risks, and LLM output validation — with no systematic support.
Suggested feature: A "Safety Audit" mode — a guided checklist for AI agent projects covering namespace scope, output validation, retry logic, and determinism settings. Immediately valuable for anyone building LLM-powered infrastructure tooling.
Try This Yourself
The three prompts are in the "Try This Yourself First" section near the top of this article — placed early so you can use them without reading the full story first.
Take Kiro's output → paste as your README skeleton. You will have a strong README and architecture documentation baseline in an afternoon.
Resources
🔗 Kube-AutoFix on GitHub: github.com/azaynul10/kube-autofix
🤖 Kiro: kiro.dev
📚 OpenAI Structured Outputs docs: platform.openai.com/docs/guides/structured-outputs
📊 MLflow Tracing: mlflow.org/docs/latest/tracing
🤖 Kiro: kiro.dev
📚 OpenAI Structured Outputs docs: platform.openai.com/docs/guides/structured-outputs
📊 MLflow Tracing: mlflow.org/docs/latest/tracing
What's Next
I am now applying Kiro to plan my next project: a Terraform module generator that uses GPT-4o to scaffold AWS infrastructure from natural language requirements. Same pattern spec-driven, safety-first, Kiro-documented.
I plan to publish monthly Kiro + Cloud Native tutorials, run community sessions on spec-driven AI development, and provide structured product feedback from cloud-native use cases — starting with the three pain points documented above.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article