Kubernetes Troubleshooting

Kubernetes Troubleshooting

Systematic approaches to diagnose and fix common Kubernetes issues.

Troubleshooting Framework

1. What's the symptom? (pod not starting, service unreachable, etc.)
2. Where's the problem? (pod, service, ingress, node, cluster)
3. What do the events say?
4. What do the logs say?
5. What changed recently?

Pod Issues

Pod Status Quick Reference

| Status | Meaning | First Check | |--------|---------|-------------| | Pending | Can't be scheduled | kubectl describe pod | | ContainerCreating | Image pulling or volume mounting | Events, kubectl get events | | CrashLoopBackOff | Container crashes repeatedly | kubectl logs --previous | | ImagePullBackOff | Can't pull container image | Image name, credentials | | Error | Container exited with error | kubectl logs | | OOMKilled | Out of memory | Increase memory limits | | Evicted | Node under pressure | Node resources, pod priority |

Debugging Commands

# Get pod status
kubectl get pod  -o wide

# Describe pod (events, conditions)
kubectl describe pod 

# Get logs
kubectl logs 
kubectl logs  -c   # specific container
kubectl logs  --previous       # previous crash

# Execute into pod
kubectl exec -it  -- /bin/sh

# Get all events sorted by time
kubectl get events --sort-by='.lastTimestamp'

CrashLoopBackOff

Symptoms: Pod restarts repeatedly
Common Causes:
├─ Application error on startup
├─ Missing config/secrets
├─ Liveness probe failing too soon
├─ Resource limits too low
└─ Dependency not ready

Debug Steps:
1. kubectl logs  --previous
2. kubectl describe pod   # check events
3. Check liveness probe configuration
4. Check resource limits
5. Verify ConfigMaps/Secrets exist

ImagePullBackOff

Symptoms: Container image can't be pulled
Common Causes:
├─ Image doesn't exist
├─ Wrong image name/tag
├─ Private registry, missing credentials
├─ Registry rate limiting
└─ Network issues

Debug Steps:
1. Verify image name: kubectl describe pod 
2. Try pulling manually: docker pull 
3. Check imagePullSecrets in pod spec
4. Verify secret exists: kubectl get secret 
5. Check registry status

Pending Pods

Symptoms: Pod stuck in Pending state
Common Causes:
├─ Insufficient resources (CPU/memory)
├─ No nodes match nodeSelector/affinity
├─ PVC can't be bound
├─ Taint with no toleration
└─ ResourceQuota exceeded

Debug Steps:
1. kubectl describe pod   # check Events
2. kubectl get nodes -o wide   # check node capacity
3. kubectl describe node  # check allocatable
4. kubectl get pvc              # check volume claims
5. kubectl get resourcequota    # check quotas

Service & Networking Issues

Service Not Working

# Check service exists and has endpoints
kubectl get svc 
kubectl get endpoints 

# If no endpoints, check selector matches pods
kubectl get pods -l 

# Test from inside cluster
kubectl run test --rm -it --image=busybox -- wget -qO- :

# Check DNS resolution
kubectl run test --rm -it --image=busybox -- nslookup 

Debugging Checklist

□ Service exists and has correct port
□ Endpoints exist (pods are selected)
□ Pod selector labels match
□ Pods are Running and Ready
□ Container is listening on correct port
□ NetworkPolicy isn't blocking traffic
□ DNS resolves correctly

Ingress Issues

# Check ingress configuration
kubectl describe ingress 

# Check ingress controller logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx

# Verify backend service
kubectl get svc 

# Check TLS secret
kubectl get secret 

Deployment Issues

Deployment Not Rolling Out

# Check rollout status
kubectl rollout status deployment/

# Check deployment events
kubectl describe deployment 

# Check replicaset
kubectl get rs -l app=
kubectl describe rs 

# Rollback if needed
kubectl rollout undo deployment/

Common Deployment Problems

Symptom: New pods not creating
Check:
├─ ResourceQuota limits
├─ PodDisruptionBudget blocking
├─ Node capacity

Symptom: Old pods not terminating
Check:
├─ terminationGracePeriodSeconds
├─ PreStop hooks stuck
├─ Finalizers blocking deletion

Symptom: Rollout stuck
Check:
├─ maxUnavailable settings
├─ Readiness probe never passes
├─ PVC can't be detached

Node Issues

Node Not Ready

# Check node status
kubectl get nodes
kubectl describe node 

# Check node conditions
kubectl get node  -o jsonpath='{.status.conditions[*].type}'

# Check kubelet logs (on node)
journalctl -u kubelet -f

# Drain node if needed
kubectl drain  --ignore-daemonsets --delete-emptydir-data

Resource Pressure

# Check node resources
kubectl top nodes

# Check which pods are using resources
kubectl top pods --all-namespaces

# Find pods on specific node
kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=

Quick Diagnostic Commands

# Overall cluster health
kubectl get nodes
kubectl get pods --all-namespaces | grep -v Running
kubectl get events --sort-by='.lastTimestamp' | tail -20

# Specific namespace health
kubectl get all -n 
kubectl get events -n  --sort-by='.lastTimestamp'

# Resource usage
kubectl top nodes
kubectl top pods -n 

# Network debugging pod
kubectl run netshoot --rm -it --image=nicolaka/netshoot -- /bin/bash

Systematic Debug Template

## Issue: [Brief description]

### Symptom
[What's happening]

### Affected Resources
- Namespace:
- Deployment/Pod:
- Service:

### Investigation

#### Step 1: Check Status

kubectl get pod kubectl describe pod

Findings: [...]

#### Step 2: Check Logs

kubectl logs

Findings: [...]

#### Step 3: Check Events

kubectl get events --sort-by='.lastTimestamp'

Findings: [...]

### Root Cause
[What caused the issue]

### Resolution
[What fixed it]

### Prevention
[How to prevent recurrence]

Emergency Procedures

Force Delete Stuck Pod

# Only use when pod is truly stuck
kubectl delete pod  --grace-period=0 --force

Emergency Rollback

# Immediate rollback
kubectl rollout undo deployment/

# Rollback to specific revision
kubectl rollout history deployment/
kubectl rollout undo deployment/ --to-revision=

Scale Down Quickly

# Scale to zero
kubectl scale deployment/ --replicas=0

# Scale back up
kubectl scale deployment/ --replicas=3

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: latestaiagents
• Source: latestaiagents/agent-skills
• License: MIT
• Homepage: https://latestaiagents.com

Install and usage instructions live in the source repository linked above.