kubectl explain: Usage, Options & Common CI Errors
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
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.resourcesCommon 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.
# 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