Kubectl Explain Command

In this lesson we cover how to use kubectl explain to discover Kubernetes resource kinds and their fields directly from your terminal. kubectl explain reads the Kubernetes API schema (OpenAPI) exposed to kubectl and prints documentation for resource kinds and their fields — a fast way to confirm exact field names, types, and API versions when authoring manifests. Why use kubectl explain?

Quick, terminal-first lookup without opening external docs.
Confirms resource name, API group/version, and field types.
Helpful for validating YAML manifests and discovering nested fields for complex resources.

Quick command reference

Purpose	Command	Notes
List available resource kinds and short names	`kubectl api-resources`	Useful when you forget the exact resource name or API group/version.
Show top-level fields for a resource	`kubectl explain pods`	Replace `pods` with any resource name from `kubectl api-resources`.
Inspect a nested field	`kubectl explain pods.spec`	Use dot notation to traverse fields.
Print every field recursively	`kubectl explain pods --recursive`	Expands all nested fields — useful when building a full manifest.

1) Discover resource kinds

If you need to list available resources, short names, and their API versions, run:

kubectl api-resources

Sample output:

$ kubectl api-resources

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

Tip: If a CRD (CustomResourceDefinition) is installed in the cluster, it will also appear in kubectl api-resources with its API group/version.

2) Inspect top-level fields for a resource

After identifying the resource name, run kubectl explain <resource> to view the top-level fields exposed by the API for that resource. Example for pods:

kubectl explain pods

Example output (top-level fields for a Pod):

$ kubectl explain pods

KIND:       Pod
VERSION:    v1

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

  kind         <string>
    Kind is a string value representing the REST resource this object
    represents. Servers may infer this from the endpoint the client submits.

  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. More info:
    https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

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

3) Inspect nested fields (dot notation)

To drill into nested fields, append the field path using dot notation:

kubectl explain pods.spec

Example output (some spec fields):

$ kubectl explain pods.spec

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 and kill
        associated containers. Value must be a positive integer.

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

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

Use dot notation to traverse as deep as you need, for example: kubectl explain deployment.spec.template.spec.containers.

4) Expand every field recursively

To see a comprehensive listing of all nested fields (helpful when authoring a complete manifest), use:

kubectl explain pods --recursive

This expands all nested fields and shows their types. Example (truncated):

$ kubectl explain pods --recursive

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>
  status       <PodStatus>

kubectl explain consults the API schema available to your kubectl (usually the cluster’s OpenAPI schema). If you are offline or not connected to a cluster, the results may not reflect server-side CRDs or custom API versions.

Field types and YAML mapping

Understanding the type labels in kubectl explain helps construct correct YAML values.

Shown type	YAML example
`<string>`	`name: my-app`
`<integer>`	`replicas: 3`
`<boolean>`	`readOnly: true`
`<map[string]string>`	`labels: {"app": "nginx"}` or in YAML: `yaml<br>labels:<br> app: nginx<br>`
`<[]string>`	`yaml<br>finalizers:<br> - kubernetes<br>`
`<ObjectMeta>`, `<PodSpec>`, etc.	Nested YAML sections (see `kubectl explain` for field details)

Practical tips

Use kubectl api-resources to find the canonical resource name and shortnames.
Use kubectl explain <resource> for top-level fields and kubectl explain <resource>.<field> to inspect nested fields.
Use --recursive to export full schemas when building manifests from scratch.
The field types you see (e.g., <string>, <integer>, <boolean>, <ObjectMeta>) guide how to format values in YAML.
If a field appears optional, check the resource’s CRD or API documentation for server-side defaults or validation.

Introduction

Core Concepts

Scheduling

Logging & Monitoring

Application Lifecycle Management

Cluster Maintenance

Security

Storage

Networking

Design and Install a Kubernetes Cluster

Install "Kubernetes the kubeadm way"

Troubleshooting

Helm Basics (2025 Updates)

Kustomize Basics (2025 Updates)

Other Topics

Mock Exams

Kubectl Explain Command

Quick command reference

1) Discover resource kinds

2) Inspect top-level fields for a resource

3) Inspect nested fields (dot notation)

4) Expand every field recursively

Field types and YAML mapping

Practical tips

Links and references

Watch Video

Practice Lab

​Quick command reference

​1) Discover resource kinds

​2) Inspect top-level fields for a resource

​3) Inspect nested fields (dot notation)

​4) Expand every field recursively

​Field types and YAML mapping

​Practical tips

​Links and references

Watch Video

Practice Lab

Quick command reference

1) Discover resource kinds

2) Inspect top-level fields for a resource

3) Inspect nested fields (dot notation)

4) Expand every field recursively

Field types and YAML mapping

Practical tips

Links and references