Hugo Martins

Understanding 'kubectl explain'

kubectl explain can be used to get more information about which fields a given resource needs, as well as the meaning behind those fields. It can be used in mainly two ways: either for getting information about the fields of a resource (e.g. kubectl explain <resource>) or by getting information about a specific field of a resource (e.g. kubectl explain <resource>.<field/s>).

Together with api-versions and api-resources it can quickly provide a lot of insight into Kubernetes and what needs to be written on a manifest to properly create or edit objects.


Getting information about root fields of Pods:

$ kubectl explain pods
KIND:     Pod

     Pod is a collection of containers that can run on a host. This resource is
     created by clients and scheduled onto hosts.

   apiVersion   <string>
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:

   kind <string>
     Kind is a string value representing the REST resource this object
     represents. Servers may infer this from the endpoint the client submits
     requests to. Cannot be updated. In CamelCase. More info:

   metadata     <Object>
     Standard object's metadata. More info:

   spec <Object>
     Specification of the desired behavior of the pod. More info:

   status       <Object>
     Most recently observed status of the pod. This data may not be up to date.
     Populated by the system. Read-only. More info:

Getting information about the spec of Pods:

kubectl explain pods.spec
KIND:     Pod

RESOURCE: spec <Object>

     Specification of the desired behavior of the pod. More info:

     PodSpec is a description of a pod.

   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     <Object>
     If specified, the pod's scheduling constraints

   automountServiceAccountToken <boolean>
     AutomountServiceAccountToken indicates whether a service account token
     should be automatically mounted.

   containers   <[]Object> -required-
     List of containers belonging to the pod. Containers cannot currently be
     added or removed. There must be at least one container in a Pod. Cannot be

   dnsConfig    <Object>
     Specifies the DNS parameters of a pod. Parameters specified here will be
     merged to the generated DNS configuration based on DNSPolicy.

   dnsPolicy    <string>
     Set DNS policy for the pod. Defaults to "ClusterFirst". Valid values are
     'ClusterFirstWithHostNet', 'ClusterFirst', 'Default' or 'None'. DNS
     parameters given in DNSConfig will be merged with the policy selected with
     DNSPolicy. To have DNS options set along with hostNetwork, you have to
     specify DNS policy explicitly to 'ClusterFirstWithHostNet'.


It explains what this field represents, as well as all the fields that can be configured inside this specific field, and their meanings. It can be a powerful tool to understand Kubernetes. A sort of man for Kubernetes itself.

It can be particularly interesting to use kubectl explain to inspect, when you forget, essential fields in Kubernetes manifests, or internal details.