Using kubectl explain for Field Reference

Working at Exam Speed / Guide 6 of 44 / Beginner

• Kubernetes1.36.4
• Runtimecontainerd 2.2.6
• CNICalico v3.32.1
• TimeAbout 13 min
• Reviewed23 August 2026

Written against the versions above. `explain` reads the OpenAPI schema the API server publishes, so it describes the version you are talking to, including CRDs installed on that cluster. A docs page describes whichever release the page is for.

Before you start

• A cluster and kubectl. Nothing is created.
• Useful straight after guide 10 - generate the skeleton, then use explain to fill in the field you are unsure of.

1. 1

   The field you cannot remember

   Dot notation walks the object. Ask for the probe you are about to write:

   FIELD: livenessProbe <Probe>

   and you get every field it accepts, each with its type and default:

     failureThreshold	<integer>
       Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1.

   The defaults are in there, which is the part people go to the docs for. periodSeconds defaults to 10, failureThreshold to 3, successThreshold must be 1 for liveness. That is a question answered in two seconds without leaving the terminal.

   The same walk works anywhere: kubectl explain deployment.spec.strategy.rollingUpdate gives you maxSurge and maxUnavailable and what they mean.

   $kubectl explain pod.spec.containers.livenessProbeKIND:       PodVERSION:    v1 FIELD: livenessProbe <Probe>  DESCRIPTION:    Periodic probe of container liveness. Container will be restarted if the    probe fails. Cannot be updated. More info:    https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes    Probe describes a health check to be performed against a container to    determine whether it is alive or ready to receive traffic. FIELDS:  exec	<ExecAction>    Exec specifies a command to execute in the container.   failureThreshold	<integer>    Minimum consecutive failures for the probe to be considered failed after    having succeeded. Defaults to 3. Minimum value is 1.   grpc	<GRPCAction>    GRPC specifies a GRPC HealthCheckRequest. 

   Expected resultThe Probe schema with types and defaults.

   Success conditionYou can look up a field's name, type and default without a browser.

2. 2

   The whole shape at once

   When you do not know what you are looking for, --recursive prints the subtree with no descriptions - just the field names and their nesting, which is exactly what you need when the problem is *where does this go*:

   One screen tells you that a Job's Pod template is at spec.template.spec, that backoffLimit is on the Job and not the template, and that restartPolicy is on the template and not the Job. Those three facts are most of what goes wrong in a hand-written Job.

   Pipe it to grep when you know the field name but not its home: kubectl explain job --recursive | grep -i backoff.

   $kubectl explain job.spec --recursive | head -24GROUP:      batchKIND:       JobVERSION:    v1 FIELD: spec <JobSpec>  DESCRIPTION:    Specification of the desired behavior of a job. More info:    https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status    JobSpec describes how the job execution will look like. FIELDS:  activeDeadlineSeconds	<integer>  backoffLimit	<integer>  backoffLimitPerIndex	<integer>  completionMode	<string>  enum: Indexed, NonIndexed  completions	<integer>  managedBy	<string>  manualSelector	<boolean>  maxFailedIndexes	<integer>  parallelism	<integer>  podFailurePolicy	<PodFailurePolicy>

   Expected resultA dense field tree with no prose.

   Success conditionYou can find where a field belongs when you only know its name.

3. 3

   Which apiVersion does this kind use

   The header of any explain gives you the answer:

   GROUP:      batch
   KIND:       CronJob
   VERSION:    v1

   so apiVersion: batch/v1. This is the single most common reason a hand-written manifest is rejected, and the four that catch people are worth memorising anyway:

   • cronjobs, jobs -> batch/v1
   • ingresses, networkpolicies -> networking.k8s.io/v1
   • horizontalpodautoscalers -> autoscaling/v2
   • deployments, statefulsets, daemonsets -> apps/v1

   kubectl api-resources prints the same information for everything at once, along with the short names - hpa, netpol, pvc, sa, cj - each of which saves a few keystrokes several dozen times.

   $kubectl explain cronjob | head -5GROUP:      batchKIND:       CronJobVERSION:    v1 DESCRIPTION:$kubectl api-resources | grep -E '^(cronjobs|ingresses|horizontalpodautoscalers|networkpolicies) 'horizontalpodautoscalers            hpa                                             autoscaling/v2                      true         HorizontalPodAutoscalercronjobs                            cj                                              batch/v1                            true         CronJobnetworkpolicies                                                                     crd.projectcalico.org/v1            true         NetworkPolicyingresses                           ing                                             networking.k8s.io/v1                true         Ingressnetworkpolicies                     netpol                                          networking.k8s.io/v1                true         NetworkPolicynetworkpolicies                     cnp,caliconetworkpolicy,caliconetworkpolicies   projectcalico.org/v3                true         NetworkPolicy

   Expected resultThe group and version for each kind, plus their short names.

   Success conditionYou never guess an apiVersion again.

4. 4

   The two lookups that also beat a browser

   kubectl --help lists the flags and gives worked examples, which is often faster than remembering the flag's exact spelling:

   The other one is explain on a field you would otherwise get subtly wrong. Capabilities, for instance, are add and drop lists of strings - and the strings are written without the CAP_ prefix, which the schema shows you and an example on a blog frequently does not.

   A workflow that costs nothing and saves a lot: generate with --dry-run=client -o yaml, then explain --recursive the section you are adding, then edit.

   $kubectl create job --help | sed -n '1,14p'Create a job with the specified name. Examples:  # Create a job  kubectl create job my-job --image=busybox   # Create a job with a command  kubectl create job my-job --image=busybox -- date   # Create a job from a cron job named "a-cronjob"  kubectl create job test-job --from=cronjob/a-cronjob Options:    --allow-missing-template-keys=true:$kubectl explain pod.spec.containers.securityContext.capabilitiesKIND:       PodVERSION:    v1 FIELD: capabilities <Capabilities>  DESCRIPTION:    The capabilities to add/drop when running containers. Defaults to the    default set of capabilities granted by the container runtime. Note that this    field cannot be set when spec.os.name is windows.    Adds and removes POSIX capabilities from running containers. FIELDS:  add	<[]string>    Added capabilities   drop	<[]string>    Removed capabilities

   Expected resultFlag documentation with examples, and the capabilities schema.

   Success conditionYou have three terminal lookups that replace most doc searches.

Troubleshooting

• explain says the field does not exist.

  Why: Wrong path, or the field lives on a different object than assumed.

  Fix:kubectl explain <kind> --recursive | grep -i <field> finds it wherever it is.

• The docs and the cluster disagree.

  Why: The docs page is for a different release.

  Fix:Trust explain - it is the schema of the server you are talking to.

• explain on a CRD returns nothing useful.

  Why: The CRD was installed without an OpenAPI schema.

  Fix:kubectl get crd <name> -o yaml and read the versions[].schema section.

Official sources

• kubectl explain
• Kubernetes API reference
• kubectl Quick Reference