kubectl explain for API reference in Kubernetes - Commands & Configuration

Introduction

When working with Kubernetes, you often need to understand the details of API resources and their fields. The kubectl explain command helps you learn about these resources directly from the command line without searching online.

When you want to know what fields are available in a Kubernetes resource like Pod or Deployment.

When you need to understand the structure of a resource before writing a YAML manifest.

When you want to check the meaning of a specific field inside a resource.

When you are troubleshooting and want to confirm the correct API version or field names.

When you want to explore nested fields inside complex Kubernetes objects.

Commands

This command shows the top-level description and fields of the Pod resource. It helps you understand what a Pod is and what fields you can set.

Terminal

kubectl explain pod

Expected Output

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>

   kind         <string>

   metadata     <Object>

   spec         <Object>

   status       <Object>

This command drills down into the spec field of the Pod resource to show its detailed structure and fields you can configure.

Terminal

kubectl explain pod.spec

Expected Output

DESCRIPTION:

     Specification of the desired behavior of the pod.



FIELDS:

   activeDeadlineSeconds   <integer>

   affinity               <Object>

   containers             <[]Object>

   dnsPolicy              <string>

   restartPolicy          <string>

This command shows the top-level description and fields of the Deployment resource, useful for managing app updates.

Terminal

kubectl explain deployment

Expected Output

KIND: Deployment

VERSION: apps/v1



DESCRIPTION:

     Deployment enables declarative updates for Pods and ReplicaSets.



FIELDS:

   apiVersion   <string>

   kind         <string>

   metadata     <Object>

   spec         <Object>

   status       <Object>

This command shows details about the strategy field inside a Deployment spec, explaining how updates are applied.

Terminal

kubectl explain deployment.spec.strategy

Expected Output

DESCRIPTION:

     DeploymentStrategy describes how to replace existing pods with new ones.



FIELDS:

   rollingUpdate   <Object>

   type            <string>

Key Concept

If you remember nothing else from kubectl explain, remember: it lets you explore Kubernetes resource fields and their meanings directly from the command line.

Common Mistakes

Trying to explain a resource that does not exist or is misspelled.

kubectl explain will return an error or no information if the resource name is incorrect.

Check the exact resource name with kubectl api-resources and use the correct spelling.

Using kubectl explain without specifying nested fields when you want detailed info.

You only get top-level fields and miss important nested details.

Use dot notation like pod.spec.containers to see nested field details.

Summary

kubectl explain shows descriptions and fields of Kubernetes API resources.

Use it with resource names and dot notation to explore nested fields.

It helps you write correct YAML manifests and understand resource structure.