kubectl explain: Discover Resource Fields
kubectl explain prints the schema documentation for a resource and its fields, sourced from the cluster API server.
Before writing or fixing a manifest, explain tells you the exact field names and types the cluster supports, including for installed CRDs.
What it does
kubectl explain queries the OpenAPI schema the API server publishes and prints the documentation for a type or a dotted field path. Because it reads the live schema, it reflects the actual API version on this cluster, including any CRDs that are installed.
Common usage
kubectl explain deployment.spec.strategy
# the whole tree
kubectl explain deployment --recursive
# pin to a specific API version
kubectl explain ingress --api-version=networking.k8s.io/v1
# works for installed CRDs
kubectl explain certificate.specOptions
| Flag / Syntax | What it does |
|---|---|
| <type>.<field>.<sub> | Explain a specific nested field |
| --recursive | Print the full field tree without descriptions |
| --api-version=<gv> | Explain a specific group/version of the type |
| --output=plaintext-openapiv2 | Use the v2 schema source (fallback) |
In CI
Use kubectl explain <crd> to confirm a CRD is installed and at which version before applying manifests that depend on it. Pin --api-version when a type exists in multiple groups, otherwise explain shows the server-preferred version, which may differ from your manifest.
Common errors in CI
"error: couldn\'t find resource for ... no matches for ..." means the type or CRD is not registered on the cluster; install it first. "field \"<x>\" does not exist" means a typo or a field from a different API version; check with --api-version. On older clusters, deeply nested CRD fields may show nothing if the CRD lacks a structural schema.
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.
# 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