This Kubernetes Command will Change your Life
Tags: kubernetes, kubectl
Published: 2019-05-29 21:15:05


Okay maybe not change your life. But hear me out. If you are like me and do quite a bit of `kubectl` and deal with kubernetes yaml files you know how much knobs and buttons each primitive in kubernetes has. This command makes that process a little bit more tolerable.

![](https://thepracticaldev.s3.amazonaws.com/i/8fel8i38ge7k6xsm3v2w.png) 

[Kubernetes documentation](https://kubernetes.io/docs/home/) is one of the best out there in the open source industry. Docs cover all the main things you need to know to run your kubernetes workload and if you’d want to dive even more deeper you can just jump to the [API docs](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#-strong-api-overview-strong-) that will give you every single thing each of those elements have to offer. But the documentation sometimes a bit more heavy-handed in the sense that it has more things most of the time than you actually ever need. 

The `kubectl` I am talking about makes learning about kubernetes api options 10x better.

The Command is `kubectl explain`. I got to know about this very recently and if you did not know, now you do. I was kind of mad that I did not know this before. If you were to do a `kubectl` `--``help` if will show up in the second section

    ...
    Basic Commands (Beginner):
      create         Create a resource from a file or from stdin.
      expose         Take a replication controller, service, deployment or pod and expose it as a new Kubernetes Service
      run            Run a particular image on the cluster
      set            Set specific features on objects
    
    Basic Commands (Intermediate):
      explain        Documentation of resources
      get            Display one or many resources
      edit           Edit a resource on the server
      delete         Delete resources by filenames, stdin, resources and names, or by resources and label selector
    ...

Literally over `get` which I think I use the most. How did I miss explain? 

But no point in dwelling in my failures in reading cli docs. Onto what `explain` gives you.
The command is pretty straight forward, it returns the docs on a specific type. So something like `kubectl explain jobs` will return 


    KIND:     Job
    VERSION:  batch/v1
    
    DESCRIPTION:
         Job represents the configuration of a single job.
    
    FIELDS:
       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:
         https://git.k8s.io/community/contributors/devel/api-conventions.md#resources
    
       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:
         https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds
    
       metadata        <Object>
         Standard object's metadata. More info:
         https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata
    
       spec        <Object>
         Specification of the desired behavior of a job. More info:
         https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status
    
       status        <Object>
         Current status of a job. More info:
         https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status

Nothing too crazy but where explain will really change your life is the JsonPath identifier.
Lets take the previous command again and go down deeper in to spec.
`kubectl explain jobs.spec`


    KIND:     Job
    VERSION:  batch/v1
    
    RESOURCE: spec <Object>
    
    DESCRIPTION:
         Specification of the desired behavior of a job. More info:
         https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status
    
         JobSpec describes how the job execution will look like.
    
    FIELDS:
       activeDeadlineSeconds        <integer>
         Specifies the duration in seconds relative to the startTime that the job
         may be active before the system tries to terminate it; value must be
         positive integer
    
       backoffLimit        <integer>
         Specifies the number of retries before marking this job failed. Defaults to
         6
    
       completions        <integer>
         Specifies the desired number of successfully finished pods the job should
         be run with. Setting to nil means that the success of any pod signals the
         success of all pods, and allows parallelism to have any positive value.
         Setting to 1 means that parallelism is limited to 1 and the success of that
         pod signals the success of the job. More info:
         https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
    
       manualSelector        <boolean>
         manualSelector controls generation of pod labels and pod selectors. Leave
         `manualSelector` unset unless you are certain what you are doing. When
         false or unset, the system pick labels unique to this job and appends those
         labels to the pod template. When true, the user is responsible for picking
         unique labels and specifying the selector. Failure to pick a unique label
         may cause this and other jobs to not function correctly. However, You may
         see `manualSelector=true` in jobs that were created with the old
         `extensions/v1beta1` API. More info:
         https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/#specifying-your-own-pod-selector
    
    ...<output-omitted>

And you can keep digging until you reach unit elements.

Want to know what all the available option for a specific resource is?
`--recursive` to recursively find all fields for a resource.
`kubectl explain serviceaccounts --recursive`


    KIND:     ServiceAccount
    VERSION:  v1
    
    DESCRIPTION:
         ServiceAccount binds together: * a name, understood by users, and perhaps
         by peripheral systems, for an identity * a principal that can be
         authenticated and authorized * a set of secrets
    
    FIELDS:
       apiVersion        <string>
       automountServiceAccountToken        <boolean>
       imagePullSecrets        <[]Object>
          name        <string>
       kind        <string>
       metadata        <Object>
          annotations        <map[string]string>
          clusterName        <string>
          creationTimestamp        <string>
          deletionGracePeriodSeconds        <integer>
          deletionTimestamp        <string>
          finalizers        <[]string>
          generateName        <string>
          generation        <integer>
          initializers        <Object>
             pending        <[]Object>
                name        <string>
             result        <Object>
                apiVersion        <string>
                code        <integer>
                details        <Object>
                   causes        <[]Object>
                      field        <string>
                      message        <string>
                      reason        <string>
                   group        <string>
                   kind        <string>
                   name        <string>
                   retryAfterSeconds        <integer>
                   uid        <string>
                kind        <string>
                message        <string>
                metadata        <Object>
                   continue        <string>
                   resourceVersion        <string>
                   selfLink        <string>
                reason        <string>
                status        <string>
          labels        <map[string]string>
          managedFields        <[]Object>
             apiVersion        <string>
             fields        <map[string]>
             manager        <string>
             operation        <string>
             time        <string>
          name        <string>
          namespace        <string>
          ownerReferences        <[]Object>
             apiVersion        <string>
             blockOwnerDeletion        <boolean>
             controller        <boolean>
             kind        <string>
             name        <string>
             uid        <string>
          resourceVersion        <string>
          selfLink        <string>
          uid        <string>
       secrets        <[]Object>
          apiVersion        <string>
          fieldPath        <string>
          kind        <string>
          name        <string>
          namespace        <string>
          resourceVersion        <string>
          uid        <string>

And it works on nested elements too. 
`kubectl explain secrets.metadata--recursive`


    KIND:     Secret
    VERSION:  v1
    
    RESOURCE: metadata <Object>
    
    DESCRIPTION:
         Standard object's metadata. More info:
         https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata
    
         ObjectMeta is metadata that all persisted resources must have, which
         includes all objects users must create.
    
    FIELDS:
       annotations        <map[string]string>
       clusterName        <string>
       creationTimestamp        <string>
       deletionGracePeriodSeconds        <integer>
       deletionTimestamp        <string>
       finalizers        <[]string>
       generateName        <string>
       generation        <integer>
       initializers        <Object>
          pending        <[]Object>
             name        <string>
          result        <Object>
             apiVersion        <string>
             code        <integer>
             details        <Object>
                causes        <[]Object>
                   field        <string>
                   message        <string>
                   reason        <string>
                group        <string>
                kind        <string>
                name        <string>
                retryAfterSeconds        <integer>
                uid        <string>
             kind        <string>
             message        <string>
             metadata        <Object>
                continue        <string>
                resourceVersion        <string>
                selfLink        <string>
             reason        <string>
             status        <string>
       labels        <map[string]string>
       managedFields        <[]Object>
          apiVersion        <string>
          fields        <map[string]>
          manager        <string>
          operation        <string>
          time        <string>
       name        <string>
       namespace        <string>
       ownerReferences        <[]Object>
          apiVersion        <string>
          blockOwnerDeletion        <boolean>
          controller        <boolean>
          kind        <string>
          name        <string>
          uid        <string>
       resourceVersion        <string>
       selfLink        <string>
       uid        <string>

If you are using a different version of any resource you can look at that documentation using `--api-version='<version>'` as well.

I hope this helps you in your kubernetes journey. 

Give me a follow if you like this post. Or find me on twitter [@moficodes](http://twitter.com/moficodes)