Claude Prompt to Troubleshoot a Kubernetes Cluster

What this prompt does

This prompt turns a vague Kubernetes symptom into a structured debugging session by requiring cluster context upfront — K8s version, cloud provider, cluster type, and namespace. That context is not boilerplate: kubectl behavior, available API objects, and common failure modes differ materially between EKS 1.28 managed node groups and GKE Autopilot 1.30, or between a kubeadm cluster and AKS. Supplying it stops the AI from producing generic advice that does not apply to your environment.

The output is structured into six concrete sections. First, an ordered set of exact kubectl commands to run before anything else — not a suggestion to "check the logs" but the specific flag combinations that surface the right signal for the symptom you described. Second, a ranked list of probable causes ordered by likelihood for that symptom pattern. Third, a decision tree keyed to actual command output, so you follow what your cluster is telling you rather than cycling through a checklist. Fourth, a Fix section with ready-to-apply YAML and commands — not "consider adding resource limits" but the actual resources.requests and resources.limits block to paste. Fifth, Prevention: probe configs, PodDisruptionBudget examples, and alert thresholds so the issue does not repeat. Sixth, Related Issues that commonly break alongside the primary failure — useful during cluster upgrades or namespace migrations.

When to use it

• A pod is stuck in CrashLoopBackOff and kubectl logs shows nothing because the container exits before writing output.
• Nodes report NotReady and you need to determine whether it is a kubelet, CNI, or cloud-provider issue before escalating.
• A StatefulSet pod is pending indefinitely and you suspect a PersistentVolume binding failure or StorageClass misconfiguration.
• Deployments fail with Insufficient cpu or Insufficient memory and you need to identify which namespace quota or LimitRange is blocking scheduling.
• A service is unreachable from inside the cluster and you need to distinguish between a DNS resolution failure, a missing Endpoints object, or a NetworkPolicy block.
• An OOMKill is happening intermittently and you need to set requests and limits correctly without starving the container under burst load.

Example output

For input: issue = "Pod OOMKilled repeatedly", K8s 1.29, EKS managed node group, namespace = payments:

## Diagnosis Commands

kubectl get pods -n payments -o wide
kubectl describe pod payments-api-7d9f8b-xkp2q -n payments
kubectl logs payments-api-7d9f8b-xkp2q -n payments --previous
kubectl top pod payments-api-7d9f8b-xkp2q -n payments --containers
kubectl get events -n payments --sort-by='.lastTimestamp' | grep -i oom

## Common Causes (ranked)
1. Memory limit set too low for actual workload peak
2. Memory leak in application code — usage grows unbounded
3. JVM/Node.js runtime heap uncapped, consuming host memory

## Root Cause Analysis
- `kubectl top` shows memory near limit at steady state → raise limit (cause 1)
- `kubectl top` shows memory growing monotonically across restarts → leak (cause 2)
- Java process present AND heap flag missing → runtime default consuming entire cgroup (cause 3)

## Fix

resources:
  requests:
    memory: "512Mi"
  limits:
    memory: "1Gi"

For JVM workloads: add -Xmx768m so heap stays 25% below the container limit,
leaving headroom for off-heap buffers and GC overhead.

## Prevention

readinessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 15

startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  failureThreshold: 30
  periodSeconds: 5

# PodDisruptionBudget to prevent all pods evicted during node drain
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: payments-api-pdb
  namespace: payments
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: payments-api

Alert: container_memory_working_set_bytes > 0.85 * kube_pod_container_resource_limits{resource="memory"} for 5m

## Related Issues
- Horizontal Pod Autoscaler may be fighting OOM restarts: check HPA min/max and current replica count
- Node memory pressure can cause kubelet to evict pods before OOM — check node conditions alongside pod events

Pro tips

• Fill [kubectl_output] before asking — paste the output of kubectl describe pod and kubectl get events -n <namespace> --sort-by='.lastTimestamp' directly into the variable. The decision tree branches on actual output; "none available" collapses it to a generic list.
• Specify [cluster_type] precisely — EKS managed node group, GKE Autopilot, or kubeadm on bare-metal each has different constraints. GKE Autopilot enforces its own resource floor and ceiling that silently override your manifest values; not naming it means the fix may be technically correct but unapplicable.
• Use kubectl debug for empty-log CrashLoopBackOff — when the container exits before writing anything, attach an ephemeral debug container: kubectl debug -it pod/<name> --image=busybox:latest --target=<container-name>. This is separate from what the prompt produces, but pairs naturally with the Diagnosis Commands output to inspect the filesystem, env vars, and network from inside the pod namespace without redeploying.
• Iterate with the decision tree output — run the first batch of Diagnosis Commands, then paste their output back into a follow-up message. The Root Cause Analysis section gives you explicit branch points (memory growing monotonically vs steady-state near limit), so each follow-up is targeted rather than exploratory.
• Cross-check the Related Issues section against recent changes — if the prompt surfaces a NetworkPolicy concern alongside your PVC problem, check whether both symptoms appeared after the same cluster upgrade or namespace migration. Shared root causes are common and the Related Issues section is where the prompt surfaces them.