Master Kubernetes Troubleshooting: 100 Essential kubectl Commands

This article is a guide to using kubectl for Kubernetes diagnostics. It lists 100 kubectl commands useful for diagnosing issues in a Kubernetes cluster, covering cluster info, pod diagnostics, service diagnostics, deployment diagnostics, StatefulSet, ConfigMap and Secret, namespace, resource usage, network, PV/PVC, node, resource quotas, CRD, scaling, jobs, capacity, ingress, pod network troubleshooting, configuration validation, RBAC, service accounts, node maintenance, resource cleanup, pod affinity/anti‑affinity, PSP, events, node troubleshooting, kubelet logs, Telepresence, kubeconfig, PodSecurity, PDB, resource locks, service endpoints and DNS, custom metrics, pod priority, overhead, volume snapshots, resource deserialization, node taints, webhook configuration, pod network policies, node conditions, audit logs, and OS details.

Cluster Information

Show Kubernetes version: kubectl version

Show cluster info: kubectl cluster-info

List all nodes: kubectl get nodes

Describe a specific node: kubectl describe node <node-name>

List all namespaces: kubectl get namespaces

List all pods in all namespaces: kubectl get pods --all-namespaces

Pod Diagnostics

List pods in a namespace: kubectl get pods -n <namespace>

Describe a pod: kubectl describe pod <pod-name> -n <namespace>

View pod logs: kubectl logs <pod-name> -n <namespace>

Tail pod logs: kubectl logs -f <pod-name> -n <namespace>

Execute a command in a pod: kubectl exec -it <pod-name> -n <namespace> -- <command>

Pod Health Checks

Check pod readiness: kubectl get pods <pod-name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'

Check pod events: kubectl get events -n <namespace> --field-selector involvedObject.name=<pod-name>

Service Diagnostics

List services in a namespace: kubectl get svc -n <namespace>

Describe a service: kubectl describe svc <service-name> -n <namespace>

Deployment Diagnostics

List deployments in a namespace: kubectl get deployments -n <namespace>

Describe a deployment: kubectl describe deployment <deployment-name> -n <namespace>

Check rollout status: kubectl rollout status deployment/<deployment-name> -n <namespace>

View rollout history: kubectl rollout history deployment/<deployment-name> -n <namespace>

StatefulSet Diagnostics

List StatefulSets: kubectl get statefulsets -n <namespace>

Describe a StatefulSet: kubectl describe statefulset <statefulset-name> -n <namespace>

ConfigMap and Secret Diagnostics

List ConfigMaps: kubectl get configmaps -n <namespace>

Describe a ConfigMap: kubectl describe configmap <configmap-name> -n <namespace>

List Secrets: kubectl get secrets -n <namespace>

Describe a Secret: kubectl describe secret <secret-name> -n <namespace>

Namespace Diagnostics

Describe a namespace: kubectl describe namespace <namespace-name>

Resource Usage

Check pod resource usage: kubectl top pod <pod-name> -n <namespace>

Check node resource usage: kubectl top nodes

Network Diagnostics

Show pod IPs in a namespace: kubectl get pods -n <namespace> -o custom-columns=POD:metadata.name,IP:status.podIP --no-headers

List network policies: kubectl get networkpolicies -n <namespace>

Describe a network policy: kubectl describe networkpolicy <network-policy-name> -n <namespace>

Persistent Volume (PV) and Persistent Volume Claim (PVC) Diagnostics

List PVs: kubectl get pv

Describe a PV: kubectl describe pv <pv-name>

List PVCs in a namespace: kubectl get pvc -n <namespace>

Describe a PVC: kubectl describe pvc <pvc-name> -n <namespace>

Node Diagnostics

List pods on a node: kubectl get pods --field-selector spec.nodeName=<node-name> -n <namespace>

Resource Quotas and Limits

List resource quotas: kubectl get resourcequotas -n <namespace>

Describe a quota: kubectl describe resourcequota <resource-quota-name> -n <namespace>

Custom Resource Definition (CRD) Diagnostics

List custom resources: kubectl get <custom-resource-name> -n <namespace>

Describe a custom resource: kubectl describe <custom-resource-name> <custom-resource-instance-name> -n <namespace>

Scaling and Autoscaling

Scale a deployment: kubectl scale deployment <deployment-name> --replicas=<replica-count> -n <namespace>

Enable autoscaling: kubectl autoscale deployment <deployment-name> --min=<min-pods> --max=<max-pods> --cpu-percent=<cpu-percent> -n <namespace>

Check HPA status: kubectl get hpa -n <namespace>

Job and CronJob Diagnostics

List jobs: kubectl get jobs -n <namespace>

Describe a job: kubectl describe job <job-name> -n <namespace>

List CronJobs: kubectl get cronjobs -n <namespace>

Describe a CronJob: kubectl describe cronjob <cronjob-name> -n <namespace>

Capacity Diagnostics

List PVs sorted by capacity: kubectl get pv --sort-by=.spec.capacity.storage

Show PV reclaim policy: kubectl get pv <pv-name> -o=jsonpath='{.spec.persistentVolumeReclaimPolicy}'

List storage classes: kubectl get storageclasses

Ingress and Service Mesh Diagnostics

List Ingresses: kubectl get ingress -n <namespace>

Describe an Ingress: kubectl describe ingress <ingress-name> -n <namespace>

List Istio VirtualServices: kubectl get virtualservices -n <namespace>

Describe a VirtualService: kubectl describe virtualservice <virtualservice-name> -n <namespace>

Pod Network Troubleshooting

Run a debug pod: kubectl run -it --rm --restart=Never --image=busybox net-debug-pod -- /bin/sh

Test connectivity from a pod: kubectl exec -it <pod-name> -n <namespace> -- curl <endpoint-url>

Trace network path between pods: kubectl exec -it <source-pod-name> -n <namespace> -- traceroute <destination-pod-ip>

Check DNS from a pod: kubectl exec -it <pod-name> -n <namespace> -- nslookup <domain-name>

Configuration and Resource Validation

Dry‑run a manifest: kubectl apply --dry-run=client -f <yaml-file>

Check pod security context: kubectl auth can-i list pods --as=system:serviceaccount:<namespace>:<serviceaccount-name>

RBAC and Security

List roles and bindings: kubectl get roles,rolebindings -n <namespace>

Describe a role: kubectl describe role <role-name> -n <namespace>

Service Account Diagnostics

List service accounts: kubectl get serviceaccounts -n <namespace>

Describe a service account: kubectl describe serviceaccount <serviceaccount-name> -n <namespace>

Node Maintenance (Drain/Uncordon)

Drain a node: kubectl drain <node-name> --ignore-daemonsets

Uncordon a node: kubectl uncordon <node-name>

Resource Cleanup

Force delete a pod (use with caution): kubectl delete pod <pod-name> -n <namespace> --grace-period=0 --force

Pod Affinity and Anti‑Affinity

Show pod affinity rules: kubectl get pod <pod-name> -n <namespace> -o=jsonpath='{.spec.affinity}'

Show pod anti‑affinity rules: kubectl get pod <pod-name> -n <namespace> -o=jsonpath='{.spec.affinity.podAntiAffinity}'

Pod Security Policy (PSP)

List PSPs: kubectl get psp

Events

List recent events: kubectl get events --sort-by=.metadata.creationTimestamp

Filter events by namespace: kubectl get events -n <namespace>

Node Troubleshooting

Show node conditions: kubectl describe node <node-name> | grep Conditions -A5

Show node capacity and allocatable resources: kubectl describe node <node-name> | grep -E "Capacity|Allocatable"

Kubelet Logs

View kubelet logs: kubectl logs -n kube-system kubelet-<node-name>

Advanced Debugging with Telepresence

Debug a pod using Telepresence: telepresence --namespace <namespace> --swap-deployment <pod-name>

Kubeconfig and Context

List contexts: kubectl config get-contexts

Switch context: kubectl config use-context <context-name>

PodSecurity (PodSecurityPolicy) Admission Control

List PSP violations: kubectl get psp -A | grep -vE 'NAME|REVIEWED'

Pod Disruption Budget (PDB) Diagnostics

List PDBs: kubectl get pdb -n <namespace>

Describe a PDB: kubectl describe pdb <pdb-name> -n <namespace>

Resource Locks

List resource locks: kubectl get resourcelocks -n <namespace>

Service Endpoints and DNS

Show service endpoints: kubectl get endpoints <service-name> -n <namespace>

Check DNS config inside a pod: kubectl exec -it <pod-name> -n <namespace> -- cat /etc/resolv.conf

Custom Metrics (Prometheus/Grafana)

Port‑forward to query Prometheus or Grafana: use kubectl port-forward to access the services and retrieve custom metrics.

Pod Priority and Preemption

List priority classes: kubectl get priorityclasses

Pod Overhead (Kubernetes 1.18+)

Show pod overhead: kubectl get pod <pod-name> -n <namespace> -o=jsonpath='{.spec.overhead}'

Volume Snapshots

List volume snapshots: kubectl get volumesnapshot -n <namespace>

Describe a snapshot: kubectl describe volumesnapshot <snapshot-name> -n <namespace>

Resource Deserialization

Get a resource as JSON: kubectl get <resource-type> <resource-name> -n <namespace> -o=json

Node Taints

List node taints: kubectl describe node <node-name> | grep Taints

Webhook Configuration

List mutating webhooks: kubectl get mutatingwebhookconfigurations

List validating webhooks: kubectl get validatingwebhookconfigurations

Pod Network Policies

List network policies: kubectl get networkpolicies -n <namespace>

Node Conditions (Kubernetes 1.17+)

Custom node condition query: kubectl get nodes -o custom-columns=NODE:.metadata.name,READY:.status.conditions[?(@.type=="Ready")].status -l 'node-role.kubernetes.io/worker='

Audit Logs

Retrieve audit logs if enabled – check the cluster’s audit log configuration for location.

Node OS Details

Get OS image of a node: kubectl get node <node-name> -o jsonpath='{.status.nodeInfo.osImage}'