Kubernetes CLI Troubleshooting Commands: kubectl Debugging Guide

Kubernetes adds layers of abstraction that can make troubleshooting challenging. The right kubectl CLI troubleshooting commands cut through that complexity.

This guide covers essential kubectl commands for debugging Kubernetes issues. For general CLI troubleshooting, see our essential guide.

Pod Troubleshooting Commands

Pods are the basic unit of Kubernetes. Most troubleshooting starts here.

List Pod Status

kubectl get pods -n your-namespace

Look for pods not in Running state. Pending, CrashLoopBackOff, and Error states indicate problems.

Describe Pod Details

kubectl describe pod pod-name -n your-namespace

Shows events, conditions, and configuration. The Events section often reveals why a pod is failing.

Pod Logs

kubectl logs pod-name -n your-namespace

Application logs are usually the first place to find error details.

Previous Container Logs

kubectl logs pod-name -n your-namespace --previous

When a container has restarted, --previous shows logs from the last run.

Follow Logs in Real-time

kubectl logs -f pod-name -n your-namespace

Stream logs as they’re written.

Multi-container Pod Logs

kubectl logs pod-name -c container-name -n your-namespace

Specify which container when pods have sidecars.

Execute Commands in Pod

kubectl exec -it pod-name -n your-namespace -- /bin/sh

Interactive shell for debugging from inside the pod.

Deployment Troubleshooting Commands

Deployment issues affect application availability.

Deployment Status

kubectl get deployment deployment-name -n your-namespace

Check READY column—0/3 means no pods are healthy.

Rollout Status

kubectl rollout status deployment/deployment-name -n your-namespace

Watch a deployment progress. Useful during releases.

Rollout History

kubectl rollout history deployment/deployment-name -n your-namespace

See previous revisions for comparison or rollback.

Rollback Deployment

kubectl rollout undo deployment/deployment-name -n your-namespace

Quickly revert to the previous version.

Deployment Events

kubectl describe deployment deployment-name -n your-namespace | tail -20

Events section shows scheduling and scaling issues.

Service and Networking Commands

Network issues in Kubernetes can be subtle.

Service Details

kubectl get svc -n your-namespace

Verify services exist and have correct ports.

Service Endpoints

kubectl get endpoints service-name -n your-namespace

Empty endpoints means the service can’t find matching pods. Check label selectors.

Describe Service

kubectl describe svc service-name -n your-namespace

Shows selector, ports, and associated endpoints.

DNS Resolution Test

kubectl run dns-test --rm -it --image=busybox --restart=Never -- nslookup service-name.namespace.svc.cluster.local

Verify internal DNS is resolving correctly.

Network Policy Check

kubectl get networkpolicies -n your-namespace

Network policies can block traffic unexpectedly.

Port Forward for Testing

kubectl port-forward pod/pod-name 8080:80 -n your-namespace

Access pod directly, bypassing services. Useful for isolating issues.

Node Troubleshooting Commands

Node issues affect all pods scheduled there.

Node Status

kubectl get nodes

Look for NotReady status indicating node problems.

Node Details

kubectl describe node node-name

Shows conditions, capacity, allocated resources, and events.

Node Resource Usage

kubectl top nodes

Requires metrics-server. Shows CPU and memory utilization.

Pods on a Node

kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=node-name

Find all pods running on a specific node.

Cordon Node

kubectl cordon node-name

Prevent new pods from scheduling while you investigate.

Resource Troubleshooting Commands

Resource constraints cause scheduling failures and OOM kills.

Pod Resource Usage

kubectl top pods -n your-namespace

Current CPU and memory consumption.

Resource Requests and Limits

kubectl get pods -n your-namespace -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].resources}{"\n"}{end}'

Verify resource configurations.

Events for Resource Issues

kubectl get events -n your-namespace --sort-by='.lastTimestamp' | grep -i -E "(oom|evict|fail|error)"

Find recent resource-related problems.

Pending Pod Reasons

kubectl get pods -n your-namespace --field-selector=status.phase=Pending -o json | jq '.items[].status.conditions'

Understand why pods can’t be scheduled.

Cluster-wide Troubleshooting

For issues affecting the entire cluster.

All Unhealthy Pods

kubectl get pods --all-namespaces | grep -v Running | grep -v Completed

Quick scan for problems across all namespaces.

Recent Events Cluster-wide

kubectl get events --all-namespaces --sort-by='.lastTimestamp' | tail -30

See what’s happening across the cluster.

Component Status

kubectl get componentstatuses

Check health of core components (deprecated but still useful).

API Server Connectivity

kubectl cluster-info

Verify you can reach the API server.

Building Kubernetes Troubleshooting Runbooks

Structure your kubectl CLI troubleshooting commands into runbooks:

# Pod Crash Investigation

## Step 1: Identify Failing Pods
```bash
kubectl get pods -n production | grep -v Running
```

## Step 2: Get Pod Details
```bash
kubectl describe pod POD_NAME -n production
```

## Step 3: Check Container Logs
```bash
kubectl logs POD_NAME -n production --previous
```

## Step 4: Check Node Status
```bash
kubectl describe node $(kubectl get pod POD_NAME -n production -o jsonpath='{.spec.nodeName}')
```

For more templates, see our Kubernetes runbook templates.

Making kubectl Commands Executable

Stew transforms your kubectl CLI troubleshooting commands into executable runbooks. Run commands with a click, see output inline, and share procedures across your team.

Join the waitlist and make Kubernetes debugging faster.