DEV Community

loading...

This Kubernetes Command will Change your Life

Mofizur Rahman
Go Developer, Does Container-y stuff, Collects Stickers (in no particular order)
・5 min read

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.

Kubernetes documentation 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 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
...
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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

Discussion (0)