kubectl-describe

Show details of pods in a namespace

$ kubectl describe [[po|pods]] [[-n|--namespace]] [namespace]

$ kubectl describe [[no|nodes]] [[-n|--namespace]] [namespace]

$ kubectl describe [[po|pods]] [pod_name] [[-n|--namespace]] [namespace]

$ kubectl describe [[no|nodes]] [node_name] [[-n|--namespace]] [namespace]

$ kubectl describe [[-f|--filename]] [path/to/manifest.yaml]

kubectl describe TYPE [NAME | -l label_selector] [flags]
kubectl describe -f FILENAME [flags]

Examples:
kubectl describe pod my-nginx-pod
kubectl describe deployment my-app-deployment
kubectl describe service my-web-service
kubectl describe node worker-node-01
kubectl describe pods -l app=my-app

TYPE
    The Kubernetes resource type to describe (e.g., pod, deployment, service, node).

NAME
    The specific name of the resource to describe. If omitted, and a label selector is not provided, it will describe all resources of the specified TYPE (if supported).

-l, --selector=<label_query>
    A selector (label query) to filter resources by. Only resources matching the specified labels will be described.

-f, --filename=<filename>
    File or URL to describe a resource from. Useful for describing resources defined in a YAML/JSON file without applying them to the cluster.

-n, --namespace=<namespace>
    If present, the namespace scope for the request. If omitted, the default namespace from your kubeconfig is used.

-A, --all-namespaces
    If present, list the requested object(s) across all namespaces. This is particularly useful for describing resource types like Pods or Services cluster-wide.

--show-events
    If true, show events associated with the described resource(s). This is often the default behavior for many resource types, but can be explicitly enabled/disabled.

The kubectl describe command retrieves comprehensive, human-readable details about one or more Kubernetes resources. Unlike kubectl get, which provides a summarized, tabular view, describe offers an in-depth breakdown of a resource's current state, configuration, and recent events. It's an indispensable tool for debugging and understanding the health and behavior of components within your Kubernetes cluster.

For instance, when describing a Pod, it will typically show the Pod's status, IP address, conditions, container details (image, ports, state), volumes, and, most critically, a chronological list of events related to the Pod's lifecycle. This includes scheduling, image pulling, container creation failures, and liveness/readiness probe failures. Similarly, describing a Node provides information about its capacity, allocated resources, conditions, and associated events.

The output is designed for operator analysis and is not suitable for programmatic parsing.

The output of kubectl describe is intended for human readability and debugging; its format is not stable and should not be parsed programmatically. For structured data, use kubectl get -o json or kubectl get -o yaml. Accessing detailed resource information requires appropriate Kubernetes Role-Based Access Control (RBAC) permissions.

This command is the first go-to for debugging issues with any Kubernetes resource. The detailed events section is particularly invaluable for diagnosing problems like a pod failing to schedule, an image pull error, or a container crashing repeatedly.

Unlike simply viewing the resource's YAML, kubectl describe aggregates information from various components. For a Pod, it combines data from the API server (Pod spec, status), Kubelet (container status, events), and scheduler (scheduling events) into a single, cohesive view.

kubectl describe has been a foundational command within the Kubernetes CLI (kubectl) since its early days. It was designed from the outset to provide deep insights into the state of Kubernetes objects, which is crucial for troubleshooting and understanding cluster behavior. Its functionality has evolved alongside Kubernetes itself, continuously adapting to new resource types and incorporating more detailed status information and event reporting.

kubectl get, kubectl logs, kubectl exec, kubectl events