kubernetes-debugger

# Kubernetes Debugger

Systematic debugging workflows for Kubernetes issues using MCP kubernetes tools.

## Prerequisites

### Install Kubernetes MCP Server

```bash
claude mcp add kubernetes --scope user -- npx mcp-server-kubernetes
```

**Requirements:**
- Access to a Kubernetes cluster configured for kubectl (minikube, Rancher Desktop, GKE, EKS, AKS, etc.)
- kubeconfig at `~/.kube/config` (default) or `KUBECONFIG` env var set
- Helm v3 in PATH (optional, for Helm operations)

**Alternative installation methods:**
```bash
# Global install
npm install -g mcp-server-kubernetes

# Or run directly with npx (no install)
npx mcp-server-kubernetes
```

**Verify installation:**
```bash
claude mcp list  # Should show 'kubernetes' server
```

## Quick Reference: MCP Tools

| Tool | Use For |
|------|---------|
| `kubectl_get` | List resources, check status, find resource names |
| `kubectl_describe` | Detailed info, events, conditions |
| `kubectl_logs` | Container stdout/stderr, application errors |
| `exec_in_pod` | Run commands inside containers |
| `kubectl_rollout` | Deployment rollout status/history |
| `node_management` | Cordon/drain/uncordon nodes |

## Debugging Decision Tree

```
Issue reported
    │
    ├─ Pod not running? ──────────► See: Pod Debugging Workflow
    │
    ├─ Service unreachable? ──────► See: Service/Network Debugging
    │
    ├─ Deployment stuck? ─────────► See: Deployment Debugging
    │
    ├─ Node issues? ──────────────► See: Node Debugging
    │
    └─ Performance/Resources? ────► See: Resource Debugging
```

## Pod Debugging Workflow

### Step 1: Get Pod Status

```
kubectl_get(resourceType="pods", namespace="<ns>")
```

Common statuses and their meaning:
- **Pending**: Scheduling issues (resources, node selector, affinity)
- **CrashLoopBackOff**: Container crashing repeatedly
- **ImagePullBackOff/ErrImagePull**: Cannot pull container image
- **Running** but not ready: Readiness probe failing
- **Terminating**: Stuck deletion (finalizers,