Kubectl Explain Command

Use kubectl explain to inspect Kubernetes resource types and their fields directly from the terminal. This is especially useful when you don’t know a resource’s full name, its short name, or the exact API version. kubectl explain reads the API schema (OpenAPI) exposed by your cluster, so the output reflects what your API server supports.

Overview

Discover available resources with kubectl api-resources.
Use the NAME or SHORTNAMES from that list when running kubectl explain.
Inspect top-level fields (spec, status, metadata) or drill into nested fields using dot notation.
Use --recursive to list all nested fields.

Find resources available on your cluster

$ kubectl api-resources

Example output:

NAME                       SHORTNAMES   APIVERSION   NAMESPACED   KIND
bindings                                   v1           true         Binding
componentstatuses        cs            v1           false        ComponentStatus
configmaps                cm            v1           true         ConfigMap
endpoints                 ep            v1           true         Endpoints
events                    ev            v1           true         Event
limitranges               limits        v1           true         LimitRange
namespaces                ns            v1           false        Namespace
nodes                     no            v1           false        Node
controllerrevisions                     apps/v1      true         ControllerRevision
daemonsets                ds            apps/v1      true         DaemonSet
deployments               deploy        apps/v1      true         Deployment
replicationcontrollers    rc            v1           true         ReplicationController
resourcequotas            quota         v1           true         ResourceQuota

Quick reference

Command	What it shows	Example
`kubectl api-resources`	Lists resource names, shortnames and API groups available on the cluster	`kubectl api-resources`
`kubectl explain <resource>`	Top-level fields and their types for a resource	`kubectl explain pods`
`kubectl explain <resource>.<field>`	Details for a specific top-level field using dot notation	`kubectl explain pods.spec`
`kubectl explain <resource> --recursive`	All fields including nested fields	`kubectl explain pods --recursive`

Using kubectl explain

Inspect top-level fields (types and short descriptions)

$ kubectl explain pods

Example output (truncated):

KIND:       Pod
VERSION:    v1

FIELDS:
  apiVersion   <string>
    APIVersion defines the versioned schema of this representation of an object.

  kind <string>
    Kind is a string value representing the REST resource this object represents.

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

  spec  <PodSpec>
    Specification of the desired behavior of the pod.

  status  <PodStatus>
    Most recently observed status of the pod. This data may not be up to date.

Drill into a specific field with dot notation

$ kubectl explain pods.spec

Example output (truncated):

KIND:       Pod
VERSION:    v1

FIELD: spec <PodSpec>

DESCRIPTION:
  Specification of the desired behavior of the pod. More info:
  https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
  PodSpec is a description of a pod.

FIELDS:
  activeDeadlineSeconds <integer>
    Optional duration in seconds the pod may be active on the node relative to
    StartTime before the system will actively try to mark it failed.

  affinity              <Affinity>
    If specified, the pod's scheduling constraints.

  automountServiceAccountToken  <boolean>
    AutomountServiceAccountToken indicates whether a service account token
    should be automatically mounted.

Show all nested fields with --recursive

$ kubectl explain pods --recursive

Example output (truncated):

KIND:       Pod
VERSION:    v1

FIELDS:
  apiVersion   <string>
  kind         <string>
  metadata     <ObjectMeta>
    annotations                <map[string]string>
    creationTimestamp         <string>
    deletionGracePeriodSeconds <integer>
    deletionTimestamp         <string>
    finalizers                <[]string>
    generateName              <string>
    generation                <integer>
    labels                    <map[string]string>
    managedFields             <[]ManagedFieldsEntry>
      apiVersion              <string>
      fieldsType              <string>
      fieldsV1                <FieldsV1>
      manager                 <string>
      operation               <string>
      subresource             <string>
  spec         <PodSpec>
    containers                <[]Container>
      name                    <string>
      image                   <string>
      ports                   <[]ContainerPort>
        containerPort         <integer>
  status       <PodStatus>
    phase                    <string>

Tip: kubectl explain reads the OpenAPI schema served by the API server, so it reflects the API groups and fields supported by your cluster. If a field is missing or differs from online docs, check the API group and version returned by kubectl api-resources and confirm your cluster version.

Warning: kubectl explain shows what the API server exposes. If your user account lacks permissions to read certain API groups, or if a CRD does not publish OpenAPI schema, those resources or fields may not appear in kubectl explain.

Links and references

Official kubectl documentation: https://kubernetes.io/docs/reference/kubectl/
Kubernetes API conventions: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md
Kubernetes API resources overview: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/ (adjust version as needed)

Introduction

Kubernetes Fundamentals

Kubernetes Resources

Scheduling

Container Orchestration - Security

Container Orchestration - Networking

Container Orchestration - Service Mesh

Container Orchestration - Storage

Cloud Native Architecture

Cloud Native Observability

Cloud Native Application Delivery

Conclusion

Kubectl Explain Command

Watch Video

Practice Lab