EKS_Dubugger: Instructions file for Codex

AGENTS.md

Guidelines for AI coding agents working in the EKS Health Check Dashboard codebase.

Project Overview

Python-based diagnostic tool for Amazon EKS cluster troubleshooting. Single-file application (eks_comprehensive_debugger.py) that analyzes pod evictions, node conditions, OOM kills, CloudWatch metrics, control plane logs, and generates interactive HTML reports.

Version: 5.1.0
Lines of Code: ~22,800 (debugger) + ~1,400 (MCP server)
Analysis Methods: 85
Correlation Rules: 18
Remediation Patterns: 45+
Catalog Coverage: 100% (79 issues across 3 catalogs)
MCP Tools: 18 (AI-agent discoverable via Model Context Protocol)
Unit Tests: 478 tests (all passing, suite runs in about 12s with no cluster access)

Quick Commands

# Setup
python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt

# Run analysis (generates HTML + LLM-JSON reports)
python eks_comprehensive_debugger.py --profile <profile> --region <region> --cluster-name <cluster> --days 2

# With custom kubectl context
python eks_comprehensive_debugger.py --profile <profile> --region <region> --cluster-name <cluster> --kube-context <context-name> --days 1

# Run MCP server (stdio transport — for Claude Desktop)
python eks_mcp_server.py

# Run MCP server with HTTP transport (for remote access)
python eks_mcp_server.py --transport streamable-http --port 8080

# Inspect MCP tools interactively (web UI)
npx @modelcontextprotocol/inspector python eks_mcp_server.py

# Run unit tests
python3 -m pytest tests/ -v

# Lint/type check (optional)
ruff check eks_comprehensive_debugger.py
mypy eks_comprehensive_debugger.py --ignore-missing-imports

File Structure

eks_comprehensive_debugger.py  # Main debugger (~22,800 lines, all-in-one)
eks_mcp_server.py              # MCP server — 18 tools for AI agents (Phase 2)
requirements.txt               # Python dependencies (includes test deps)
.gitignore                     # Git ignore rules
README.md                      # User documentation
AGENTS.md                      # This file
tests/                         # Unit tests (478 tests)
├── __init__.py
├── conftest.py                # Shared fixtures
├── test_severity_classification.py  # Severity logic tests
├── test_input_validation.py         # Security/shell injection tests
├── test_findings.py                 # Findings management tests
├── test_kubectl_execution.py        # Kubectl shell safety tests
├── test_api_cache.py                # APICache tests
├── test_incremental_cache.py        # IncrementalCache tests
├── test_performance_tracker.py      # PerformanceTracker tests
├── test_ssm_integration.py          # SSM node diagnostics tests (Phase 1)
├── test_node_os_parsers.py          # Node OS output parser tests (Phase 1)
├── test_node_selection.py           # Node priority selection tests (Phase 1)
└── test_mcp_server.py               # MCP server tool tests (Phase 2)
venv/                          # Virtual environment (gitignored)