sairohithguntupally/kubectl-why-pending

kubectl-why-pending is a plugin for kubectl, the command-line tool used to manage Kubernetes clusters. Kubernetes is a system for running containers across multiple machines, and when a container fails to start, it often gets stuck in a state called Pending. The standard way to investigate is to run kubectl describe and read through a wall of status output. This plugin replaces that process with a plain-English explanation and a specific suggested fix. The tool re-runs the same scheduling logic that Kubernetes uses internally, but against your real cluster state, then translates the results into human-readable causes. It is particularly focused on bare-metal and on-premises clusters, where problems like resource fragmentation are common but cloud-managed services automatically paper over them. For example, if your cluster has enough memory in total but no single machine has enough free memory to fit the pod, the tool explains that distinction and tells you how to resolve it. The list of things it detects covers the most common reasons a pod stays Pending: insufficient resources on any single node, node labels or requirements that do not match any available machine, untolerated taints that block certain nodes from accepting work, GPU or other special hardware not being advertised by any node, unbound storage volumes, and scheduling constraints like one copy per machine that run out of eligible machines. For GPU failures, it traces through the full chain of components that need to be working and identifies exactly which one is broken. Output can go to the terminal in plain text or as JSON or YAML for use in scripts, dashboards, or automated alerts. Exit codes are designed so you can use it in CI pipelines: a non-zero code means something is blocked. JSON mode gives a per-node breakdown showing which node was ruled out and why. Installation is through Krew, the official kubectl plugin manager, with a single command. The plugin can check one specific pod, all pending pods in a namespace, or all pending pods across the entire cluster. It is MIT-licensed and written in Go.