Introduction

Sometimes you need to see detailed information about a Kubernetes object to understand its current state and troubleshoot issues. The kubectl describe command shows you this detailed view, including events and status.

When you want to check why a pod is not starting properly by seeing its events and status.

When you need to see detailed information about a deployment, such as replicas and conditions.

When you want to inspect the configuration and status of a service or other Kubernetes resource.

When you want to debug issues by looking at recent events related to a resource.

When you want to verify labels, annotations, and other metadata on a Kubernetes object.

Commands

This command creates a deployment named example-deployment using the nginx image. It sets up the resource we will describe next.

Terminal

kubectl create deployment example-deployment --image=nginx

Expected OutputExpected

deployment.apps/example-deployment created

→

--image - Specifies the container image to use for the deployment

This command shows detailed information about the example-deployment, including its current state, replicas, and events.

Terminal

kubectl describe deployment example-deployment

Expected OutputExpected

Name: example-deployment Namespace: default CreationTimestamp: 2024-06-01T12:00:00Z Labels: <none> Annotations: deployment.kubernetes.io/revision: 1 Selector: app=example-deployment Replicas: 1 desired | 1 updated | 1 total | 1 available | 0 unavailable StrategyType: RollingUpdate MinReadySeconds: 0 RollingUpdateStrategy: 25% max unavailable, 25% max surge Pod Template: Labels: app=example-deployment Containers: nginx: Image: nginx Port: <none> Environment: <none> Mounts: <none> Conditions: Type Status Reason ---- ------ ------ Available True MinimumReplicasAvailable Progressing True NewReplicaSetAvailable Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal ScalingReplicaSet 10s deployment-controller Scaled up replica set example-deployment-xxxx to 1

This command shows detailed information about the pod(s) created by the deployment, filtered by the label app=example-deployment.

Terminal

kubectl describe pod -l app=example-deployment

Expected OutputExpected

Name: example-deployment-xxxx Namespace: default Priority: 0 Node: node-1/192.168.1.10 Start Time: 2024-06-01T12:00:10Z Labels: app=example-deployment Annotations: <none> Status: Running IP: 10.244.1.5 Containers: nginx: Container ID: docker://abcdef123456 Image: nginx Image ID: docker-pullable://nginx@sha256:xxxx Port: <none> State: Running Started: 2024-06-01T12:00:15Z Ready: True Restart Count: 0 Conditions: Type Status Initialized True Ready True ContainersReady True PodScheduled True Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Scheduled 20s default-scheduler Successfully assigned default/example-deployment-xxxx to node-1 Normal Pulled 18s kubelet Container image "nginx" already present on machine Normal Created 18s kubelet Created container nginx Normal Started 17s kubelet Started container nginx

→

-l - Filters resources by label selector

Key Concept

If you remember nothing else from this pattern, remember: kubectl describe shows detailed status and events of Kubernetes objects to help you understand and debug them.

Common Mistakes

Using kubectl describe without specifying the resource name or label selector

The command will fail or show too much information, making it hard to find what you need.

Always specify the exact resource name or use a label selector to narrow down the output.

Expecting kubectl describe to show logs or container output

kubectl describe shows metadata and events, not container logs.

Use kubectl logs to see container output instead.

Summary

Create a deployment to have a resource to inspect.

Use kubectl describe deployment to see detailed info and events about the deployment.

Use kubectl describe pod with a label selector to see detailed info about pods created by the deployment.