# kubectl explain: Usage, Options & Common CI Errors

> kubectl explain documents a resource's fields from the live API schema. Recursive field trees, apiVersion, and catching unknown-field errors before apply.

Source: https://latchkey.dev/learn/command-reference/kubectl-explain  
Updated: 2026-06-25

Read field-level docs for any resource from the cluster itself.

kubectl explain prints documentation for a resource and its fields, sourced from the server's OpenAPI schema - so it matches the exact version your cluster runs. It is the fastest way to get a manifest field right.

## What it does

kubectl explain TYPE.path describes a field: its type, whether it is required, and a description. --recursive dumps the full field tree without descriptions - a compact map of valid keys. Because it reads the live schema, --api-version lets you check the exact version you intend to apply.

## Common usage

```Terminal
kubectl explain pod.spec.containers
kubectl explain deployment.spec.strategy
kubectl explain ingress --recursive --api-version=networking.k8s.io/v1
kubectl explain pod.spec.containers.resources
```

## Common errors in CI

explain is a debugging aid for the errors apply throws: when "ValidationError: unknown field \"spec.foo\"" appears, kubectl explain <type>.spec --recursive shows the real, valid field names for this cluster's version - often the field was renamed or moved between apiVersions. "field is required" from validation maps directly to the fields explain marks -required-. Running explain against the same --api-version your manifest declares avoids chasing docs that describe a different API version than the cluster serves.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### kubectl explain: Usage, Options & Common CI Errors?

kubectl explain prints documentation for a resource and its fields, sourced from the server's OpenAPI schema - so it matches the exact version your cluster runs. It is the fastest way to get a manifest field right.

### What it does?

kubectl explain TYPE.path describes a field: its type, whether it is required, and a description. --recursive dumps the full field tree without descriptions - a compact map of valid keys. Because it reads the live schema, --api-version lets you check the exact version you intend to apply.

### Common errors in CI?

explain is a debugging aid for the errors apply throws: when "ValidationError: unknown field \"spec.foo\"" appears, kubectl explain <type>.spec --recursive shows the real, valid field names for this cluster's version - often the field was renamed or moved between apiVersions.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt