> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubectl Explain Command

> How to use kubectl explain to view Kubernetes resource kinds, field types, nested fields, and API versions from the terminal with examples and command tips

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:

```bash theme={null}
kubectl api-resources
```

Sample output:

```console theme={null}
$ 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`:

```bash theme={null}
kubectl explain pods
```

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

```console theme={null}
$ 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:

```bash theme={null}
kubectl explain pods.spec
```

Example output (some `spec` fields):

```console theme={null}
$ 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:

```bash theme={null}
kubectl explain pods --recursive
```

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

```console theme={null}
$ 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>
```

***

<Callout icon="lightbulb" color="#1CB2FE">
  `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.
</Callout>

***

## 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: <br />`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.

***

## Links and references

* [kubectl reference — explain](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#explain)
* [Kubernetes API conventions — metadata, spec, status](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status)
* [Kubernetes Documentation](https://kubernetes.io/docs/)

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/cka-certification-course-certified-kubernetes-administrator/module/c6d2ac7d-8192-4cff-aa54-e36d888c5bd9/lesson/d8b786c9-9c5d-4436-ac74-c6749622bfaf" />

  <Card title="Practice Lab" icon="flask-conical" cta="Learn more" href="https://learn.kodekloud.com/user/courses/cka-certification-course-certified-kubernetes-administrator/module/c6d2ac7d-8192-4cff-aa54-e36d888c5bd9/lesson/5bcc01c7-a3e8-41a9-adcd-91860641c48c" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.