---
name: kubernetes-deployment-debugger
description: "A root-cause diagnosis for a Kubernetes Deployment that is crash-looping, pending, or failing its probes: the likely cause ranked from the evidence, the kubectl commands that confirm it, the minimal manifest patch, and what stops it recurring. Use when a Kubernetes Deployment is in CrashLoopBackOff, Pending, ImagePullBackOff, or OOMKilled and the user has the pod events and logs to diagnose it. Do not use for writing new manifests or Helm charts, or cluster-level networking and ingress problems. Related topics: coding, kubernetes."
---

# Kubernetes Deployment Debugger

A root-cause diagnosis for a Kubernetes Deployment that is crash-looping, pending, or failing its probes: the likely cause ranked from the evidence, the kubectl commands that confirm it, the minimal manifest patch, and what stops it recurring.

## When to use

Use this skill when a Kubernetes Deployment is in CrashLoopBackOff, Pending, ImagePullBackOff, or OOMKilled and the user has the pod events and logs to diagnose it. Do not use it for writing new manifests or Helm charts, or cluster-level networking and ingress problems.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Use the pod status to narrow the failure class before reading further, so scheduling, image, memory, application, and probe causes are not mixed.
3. Combine events and logs to name the single most likely cause and the evidence that supports it.
4. List the kubectl commands in order that confirm the cause, with what each should display.
5. Write the minimal patch or YAML snippet touching only the fields at fault and the rollout command to apply and watch it.
6. State the prevention change that stops the failure recurring.

## Inputs

- **Namespace** (free text, e.g. "default")
- **Deployment name** (free text, e.g. "my-app")
- **Pod status seen** (choose one: CrashLoopBackOff, Pending, ImagePullBackOff, OOMKilled, Running but not Ready, Error, Terminating stuck)
- **Observed error message or events** (longer free text)
- **Recent pod logs** (longer free text)
- **Desired replica count** (number from 1 to 100)
- **Container image** (free text, e.g. "repository:tag")
- **Kubernetes version** (choose one: v1.27, v1.28, v1.29, v1.30, v1.31)
- **Cluster type** (choose one: EKS, GKE, AKS, Self-managed, kind or minikube)

## Output

A markdown report with sections Summary, Likely root cause (with evidence), Commands to confirm, Fix (patch or YAML in a code block plus the rollout command), and Prevention.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Kubernetes Deployment Debugger

Work out why my Deployment is unhealthy and give me the commands and patch to fix it.

#### Details
- Namespace: {{Namespace}}
- Deployment name: {{Deployment name}}
- Pod status seen: {{Pod status seen}}
- Observed error message or events: {{Observed error message or events}}
- Recent pod logs: {{Recent pod logs}}
- Desired replica count: {{Desired replica count}}
- Container image: {{Container image}}
- Kubernetes version: {{Kubernetes version}}
- Cluster type: {{Cluster type}}

Read the pod status as the first filter: Pending points at scheduling (resources, node selectors, taints, PVC binding), ImagePullBackOff at the image name or registry credentials, OOMKilled at the memory limit, CrashLoopBackOff at the application exiting (read the previous container's logs), and Running but not Ready at the readiness probe or a dependency. Pair the events with the logs to pick the single most likely cause and say what evidence supports it. Give the kubectl commands in order that confirm the diagnosis (describe, logs --previous, get events --sort-by, exec into the container, rollout history) with what each should show. Provide the minimal change as a kubectl patch or a YAML snippet that touches only the fields at fault, and the rollout command to apply and watch it. Close with the prevention step: a probe adjusted, a resource request set, a readiness gate, or a rollback policy.

## Pitfalls

- Reading the current container's logs for a CrashLoopBackOff when the failure is in the previous container's output.
- Raising the memory limit for an OOMKilled pod without checking whether the application leaks, which only delays the next kill.
- Patching the pod directly instead of the Deployment, so the change disappears on the next rollout.
