A Complete Guide to Kubectl Describe Command

June 5, 2024

English

Priyansh Khodiyar

Share with friends

In this guide, we will talk about the kubectl describe command - what it is, how to use it, and when to use it with detailed examples.

A Complete Guide to Kubectl Describe Command cover image

kubectl tool has come in handy to us in the deployment of containerized applications on Kubernetes making the deployment and cluster management easy.

Let's explore kubectl describe in detail and understand how this can be used practically for managing Kubernetes applications.

What is Kubectl Describe - A Brief Summary

kubectl describe is a command in the Kubectl tool which provides us with an overview of the component deployed in the Kubernetes cluster.

Syntax of Kubectl Describe Command

kubectl describe [resource_type] [resource_name]

resource_type: Specifies the kind of Kubernetes resource you want to describe (e.g., pods, services, deployments, nodes, etc.).
resource_name: Specifies the name of a specific resource you want to inspect.

Kubectl Describe Example

Let's say you want to get more information about a specific pod named "my-pod" in the "my-namespace" namespace. You would use the following command:

kubectl describe pod my-pod -n my-namespace

The output will contain detailed information about the pod, such as its current state, labels, conditions, volumes, and related events.

Name:         my-pod
Namespace:    my-namespace
Priority:     0
Node:         node-1/192.168.1.10
Start Time:   Wed, 15 Jul 2023 14:30:00 +0000
Labels:       app=my-app
              tier=backend
Annotations:  <none>
Status:       Running
IP:           10.244.1.5
IPs:
  IP:  10.244.1.5
Containers:
  my-container:
    Container ID:   container-id
    Image:          my-image:latest
    Port:           8080/TCP
    Host Port:      0/TCP
    State:          Running
    Started:      Wed, 15 Jul 2023 14:30:05 +0000
    Ready:          True
    Restart Count:  0
    Environment:
      ENV_VAR:      value
    Mounts:
      /data:          /mnt/data
Volumes:
  data:
  Type:          EmptyDir (a temporary directory that shares a pod's lifetime)
    Medium:        
    SizeLimit:     <unset>
Conditions:
  Type              Status
  Initialized       True
  Ready             True
  ContainersReady   True
  PodScheduled      True

The output will also contain a detailed view of Events along with pods, containers, volumes, etc.

What is Kubectl Describe Used for?

When you run kubectl describe with a specific resource type & name, it retrieves all the information about that resource from the Kubernetes API server and presents it in human-readable format on the terminal.

Let's understand this better using some use cases.

Troubleshooting

It provides insights about the resources and which state it is in that can help us debug issues and manage components within your cluster.

When an issue arises in your cluster, kubectl describe can be used in diagnosing the problem.

It allows you to check the state of specific resources like pods, deployments, or services and helps identify any errors and misconfigurations.

Resource Configuration Verification

You can use it to confirm that the settings of a resource if it matches your intended configuration.

This helps you analyze the configuration of Kubernetes resources like pods, deployments, services, etc. By running kubectl describe, you can quickly check the labels, volumes, or any other relevant information.

Investigating Events

kubectl describe also offers a historical context of actions that have taken place.

Kubernetes events can provide valuable insights into the history of actions that have occurred, such as pod scheduling, scaling events, or service updates.

Once you understand that the events are normal as expected, you can review the configuration. It is most useful for validating whether the current state of a resource matches your intended configuration.

This is particularly helpful when you have applied changes to a resource, and you want to ensure the changes were applied correctly.

For security purposes, kubectl describe assists in understanding the properties of certain resources, such as permissions, service accounts, and security policies.

The exact details displayed by kubectl describe vary based on the resource type you are inspecting as the attributes used by different resource types may vary.

Different Types of Kubectl Describe with Examples

kubectl describe can be used with various Kubernetes resource types to provide detailed information about them.

Here are some common types of kubectl describe commands along with examples.

Kubectl Describe for Pods

Due to its heavy reliance on the application configuration or pod manifest, it gets most of the errors. So, it is important to identify the error early on.

While looking at logs is one way of finding out what happened in the pod, checking the events would be a faster way to quickly understand the issue.

To describe a pod named "my-pod" in the "my-namespace" namespace, use,

kubectl describe pod my-pod -n my-namespace

Also Read: Differences between Pods and Nodes

Kubectl Describe for Services

These components are used for network connectivities between the Kubernetes components. Whenever there is any network-related issue, it is depicted in the services.

To understand what happened within the networking of the cluster, you need to use describe command to describe a service named "my-service" in the "my-namespace" namespace.

Here's an example of the kubectl describe command for services.

kubectl describe service my-service -n my-namespace

Also Read: How to Fix CreateContainerConfigError in Kubernetes?

Kubectl Describe for Nodes

A Kubernetes Node is used for running the containerized application present in the pod.

It acts as a virtual machine for the cluster. There can be many errors associated with the nodes like certificate issues.

For instance, to describe a specific node named "node-1", you can use:

kubectl describe node node-1

Kubectl Describe for Deployments

To describe a deployment named "my-deployment" in the "my-namespace" namespace, you can use the following command:

kubectl describe deployment my-deployment -n my-namespace

Kubectl Describe for ReplicaSets

ReplicaSets are used to ensure that there are multiple instances of an application running. This basically ensures the high availability of your application.

When this functionality stops, your application will be prone to failures and no recovery strategies in place as the availability of your application is sabotaged.

To describe a ReplicaSet named "my-replicaset" in the "my-namespace" namespace, use the following kubectl describe command:

kubectl describe replicaset my-replicaset -n my-namespace

Kubectl Describe for StatefulSets

StatefulSets are similar to deployments. The only difference is that StatefulSets are used to hold stateful application which has to store some information as a database within itself.

This can create problems when it's not working properly.

To describe a StatefulSet named "my-statefulset" in the "my-namespace" namespace, use:

kubectl describe statefulset my-statefulset -n my-namespace

Kubectl Describe for PVs and PVC

PVs & PVC are the most important components of storage that ensure that the information is persisted such that the important information is still stored somewhere even after the deletion of a pod.

To describe a PersistentVolume and claim(PVC) named "my-pv" and “my-pvc” respectively, we use the following commands.

kubectl describe pv my-pv
kubectl describe pvc my-pvc -n my-namespace

Kubectl Describe for Namespaces

Namespaces are used for logical isolation of different environments in the cluster.

For example, use the following kubectl describe command to describe a specific namespace named "my-namespace":

kubectl describe namespace my-namespace

Kubectl Describe for ConfigMaps & Secrets

ConfigMaps and Secrets are used to store environment variables/sensitive information. If not configured properly will cause application failures.

To describe a ConfigMap and a secret, use the following kubectl describe command:

kubectl describe configmap my-configmap -n my-namespace
kubectl describe secret my-secret -n my-namespace

Also Read: 13 NGNIX Configuration Options

Different Ways to Use Kubectl Describe

The kubectl describe command can also be used with various extensions and custom resources that are introduced by Kubernetes add-ons or third-party extensions.

These extensions can enhance Kubernetes functionality and provide additional features.

Here are some ways to use kubectl describe with extensions.

Ingress Resources

These resources act as a reverse proxy to the containerized applications deployed in Kubernetes.

To describe an Ingress resource named "my-ingress" in the "my-namespace" namespace

kubectl describe ingress my-ingress -n my-namespace

Also Read: When to Use Kubectl Proxy?

Kubectl Describe for Horizontal Pod Autoscalers

HPA is used to scale the applications in Kubernetes horizontally by allocating more instances of the application.

If HPA is not functioning properly, it directly means that it is not highly available and doesn't meet the expectations of custom scaling according to unpredictive traffic conditions.

To describe a HorizontalPodAutoscaler named "my-hpa" in the "my-namespace" namespace.

kubectl describe hpa my-hpa -n my-namespace

Kubectl Describe for CRDs

If you have custom resources defined in your Kubernetes cluster, you can describe them using kubectl describe.

For example, if you have a CRD called "mycustomresource" in the "mygroup" API group, and you created an instance named "my-instance" in the "my-namespace" namespace:

kubectl describe mycustomresource my-instance -n my-namespace

ResourceQuotas

When your resource quota in your cluster resource is over, you will get multiple errors which will lead to the non-functioning of your applications.

To describe a ResourceQuota named "my-resource-quota" in the "my-namespace" namespace:

kubectl describe resourcequota my-resource-quota -n my-namespace

Kubectl Describe vs Get vs Explain

kubectl describe, kubectl get, and kubectl explain are three essential commands in the Kubernetes command-line interface (CLI) with different purposes.

Let's look at the differences between them.

Kubectl Describe

The kubectl describe command is used to display detailed information about specific Kubernetes resources as seen in the previous sections.

It provides a human-readable summary and understanding of the current state and configuration of a resource.

The output contains detailed metadata, labels, annotations, conditions, events, and other information associated with the specified resource.

Also Read: A Complete Guide to Kubectl Patch Command

Kubectl Get

The kubectl get command is used to retrieve a curated list of Kubernetes resources of a particular type of resource in the cluster. It provides a view of the current state of multiple resources.

You specify the resource type you want to retrieve, and you can optionally filter the results using labels and namespaces.

kubectl get pods -n my-namespace

The output includes a table with the names, statuses, and other relevant details of the requested resources.

NAME               READY   STATUS    RESTARTS   AGE
my-pod-1           1/1     Running   0          5m
my-pod-2           1/1     Running   0          5m
my-pod-3           0/1     Pending   0          2m
another-pod        2/2     Running   1         10m

Kubectl Explain

The kubectl explain command is used to retrieve detailed information about the structure and properties of Kubernetes resources.

It helps you understand the fields and options available for each resource type. You provide the resource type you want to explain, and optionally, you can specify the field you want more details about.

Here is an example of the kubectl explain pod command:

kubectl explain pod

The output includes the API schema and descriptions of the fields, explaining the purpose and possible values of each attribute.

KIND:     Pod
VERSION:  v1
DESCRIPTION:
Pod is a collection of containers that can run on a host. This resource is created by clients and scheduled onto hosts.

FIELDS:
apiVersion <string>
APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#resources

kind <string>
Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds

metadata <Object>
Standard object's metadata. 
More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata

spec <Object>
Specification of the desired behavior of the pod. 
More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status

status <Object>
Most recently observed status of the pod. This data may not be up to date.
Populated by the system. Read-only. 
More info:
https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status

Also Read: Top 13 Heroku Alternatives

Final Words: Kubectl Describe

In conclusion, the kubectl describe command is a powerful tool that can be used to get detailed information about Kubernetes resources.

It can be used to troubleshoot problems, understand the configuration of a resource, or simply get more information about a resource.

The kubectl describe command has a number of different options that can be used to customize the output. For example, you can use the -l option to filter the output by label, or the -o option to specify the output format.

I hope this tutorial has been helpful in teaching you how to use the kubectl describe command. Thank you for reading!