Start your free 14-day ContainIQ trial

Using Kubectl Describe | Tutorial and Example

In this guide, we highlight the `kubectl describe` command and provide an actionable example alongside helpful context.

July 14, 2022
Kumar Harsh
Software Developer

Kubernetes has quickly grown to become one of the most popular container orchestration frameworks in the industry. Kubernetes has many benefits and it known for its flexibility and ease of use. With its growing community, many tools and technologies have been developed to make it simple to use.

<terminal inline>kubectl<terminal inline> is one of the most popular open-source CLIs for interacting with a Kubernetes cluster. In this guide, you will learn about <terminal inline>describe<terminal inline>, one of its popular commands.

What is kubectl describe Used For?

As is evident by its name, the <terminal inline>kubectl describe<terminal inline> command is used to view details of a Kubernetes resource or resource group. Here's how it's used:

kubectl describe <resource-type> <resource-name-prefix>

Common resource types include pods, services, nodes, events, and more. The command takes the prefix of the resource name as input. You can also provide the complete name of the resource and it would work just fine.

Here's how you can use this command:

kubectl describe deployment test-webapp

Here's what the output would look like:

Name:                   test-webapp
Namespace:              default
CreationTimestamp:      Tue, 31 May 2022 10:38:00 +0530
Labels:                 <none>
Annotations:   1
Selector:               run=test-webapp
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:  run=test-webapp
    Port:       80/TCP
    Host Port:  0/TCP
      cpu:     25m
      memory:  10Mi
      cpu:        10m
      memory:     5Mi
    Environment:  <none>
    Mounts:       <none>
  Volumes:        <none>
  Type           Status  Reason
  ----           ------  ------
  Progressing    True    NewReplicaSetAvailable
  Available      True    MinimumReplicasAvailable
OldReplicaSets:  <none>
NewReplicaSet:   test-webapp-d5f9b9d8d (1/1 replicas created)
  Type    Reason             Age   From                   Message
  ----    ------             ----  ----                   -------
  Normal  ScalingReplicaSet  6d8h  deployment-controller  Scaled up replica set test-webapp-d5f9b9d8d to 1
Monitor Kubernetes Events in Real-Time
Monitor the health of your cluster and troubleshoot issues faster with pre-built dashboards that just work.
Learn More Book a Demo
event dashboard

Exploring kubectl describe in Detail

The <terminal inline>kubectl describe<terminal inline> command provides a few options to tailor it to your liking. Here are some of those:

Viewing by label

You can also use metadata labels to filter and identify resources when describing them. Here's what the syntax looks like for that:

Viewing resources using a file

The <terminal inline>kubectl describe<terminal inline> command allows you to query for resources using data stored in a file. Here's what the syntax looks like:

kubectl describe -f test-pod.json

Shorthand syntax

You can use the following syntax too:

kubectl describe <resource-type>/<resource-name>

It works the same as the syntax shared at the beginning of the article.

kubectl describe vs kubectl get

People often debate on whether or not <terminal inline>describe<terminal inline> was needed when there already was a <terminal inline>get<terminal inline> command. To understand this better, let's try to view them side by side:

Here's what a <terminal inline>get<terminal inline> command on a pod returns:

~> kubectl get pod test-webapp-d5f9b9d8d-flqjk

test-webapp-d5f9b9d8d-flqjk 1/1 Running 0 5m22s

Here's what a <terminal inline>describe<terminal inline> call on the same pod returns:

$ kubectl describe pod test-webapp-d5f9b9d8d-flqjk
Name:         test-webapp-d5f9b9d8d-flqjk
Namespace:    default
Priority:     0
Node:         minikube/
Start Time:   Mon, 06 Jun 2022 18:00:04 +0530
Labels:       pod-template-hash=d5f9b9d8d
Annotations:  <none>
Status:       Running
Controlled By:  ReplicaSet/test-webapp-d5f9b9d8d
    Container ID:   docker://d581e3e779ae164630de23594b0c4df8c1eecacdbd6b0b7e68655656d37c7491
    Image ID:       docker-pullable://
    Port:           80/TCP
    Host Port:      0/TCP
    State:          Waiting
      Reason:       CrashLoopBackOff
    Last State:     Terminated
      Reason:       Error
      Exit Code:    137
      Started:      Mon, 06 Jun 2022 18:38:02 +0530
      Finished:     Mon, 06 Jun 2022 18:39:07 +0530
    Ready:          False
    Restart Count:  8
      cpu:     25m
      memory:  10Mi
      cpu:        10m
      memory:     5Mi
    Environment:  <none>
      /var/run/secrets/ from kube-api-access-nnjsx (ro)
  Type              Status
  Initialized       True 
  Ready             False 
  ContainersReady   False 
  PodScheduled      True 
    Type:                    Projected (a volume that contains injected data from multiple sources)
    TokenExpirationSeconds:  3607
    ConfigMapName:           kube-root-ca.crt
    ConfigMapOptional:       <nil>
    DownwardAPI:             true
QoS Class:                   Burstable
Node-Selectors:              <none>
Tolerations:        op=Exists for 300s
                    op=Exists for 300s
  Type     Reason     Age                   From               Message
  ----     ------     ----                  ----               -------
  Normal   Scheduled  42m                   default-scheduler  Successfully assigned default/test-webapp-d5f9b9d8d-flqjk to minikube
  Normal   Pulled     41m                   kubelet            Successfully pulled image "" in 1m0.625635569s
  Normal   Pulled     30m                   kubelet            Successfully pulled image "" in 1.177994667s
  Normal   Pulled     29m                   kubelet            Successfully pulled image "" in 1.104291834s
  Normal   Pulled     28m                   kubelet            Successfully pulled image "" in 1.010987459s
  Normal   Pulling    26m (x5 over 42m)     kubelet            Pulling image ""
  Normal   Created    26m (x5 over 41m)     kubelet            Created container test-webapp
  Normal   Pulled     26m                   kubelet            Successfully pulled image "" in 1.132110626s
  Normal   Started    26m (x5 over 41m)     kubelet            Started container test-webapp
  Warning  BackOff    2m21s (x80 over 29m)  kubelet            Back-off restarting failed container

As you can see, the get command (by default) returns a very quick summary of the status of the resource in question. On the other hand, the describe command prepares a detailed summary of the resource with additional details like container ID, limits, node details, etc.

Also, the <terminal inline>get<terminal inline> command returns the information in a tabular fashion by default. You also have the option to view the information in any other format such as JSON or YAML by passing it as an option. But, the output returned in such a case is quite verbose and is usually difficult to read.

At the end of the day, <terminal inline>describe<terminal inline> provides you with just the right amount of information about your K8s resource. If you are looking for anything less or more, you should look towards <terminal inline>get<terminal inline>.

Final Thoughts

K8s is one of the popular container-orchestration technologies in use right now. The <terminal inline>kubectl describe<terminal inline> command enables developers to look into the current state of their Kubernetes resources. In this guide, we showed you how to use this command as well as contrasted it with another popular command that does a similar job.

Start your free 14-day ContainIQ trial
Start Free TrialBook a Demo
No card required
Kumar Harsh
Software Developer

Kumar is a software developer and technical author. He has written for a number of software companies including LogRocket and Career Karma. Kumar previously worked for Goldman Sachs as a Summer Analyst. He is currently pursuing a Bachelor of Technology in Computer Science at the National Institute of Technology, Patna.