Recently, I had the (not-so) fun experience of porting custom resource definitions from their YAML manifests into Go structs, to which I had the interesting discovery of the following CLI functions and how they may help my task. The commands are:

kubectl get
kubectl describe
kubectl explain

Breaking Down the Commands

Get

According to the [official Kubernetes Cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#viewing-and-finding-resources), the get command is used to list resources relative to the type provided, yet there’s an interest additional behaviour if you attempt to target a specific resource, it describes the resource’s manifest.

kubectl get services                          # List all services in the namespace
kubectl get pods --all-namespaces             # List all pods in all namespaces
kubectl get pods -o wide                      # List all pods in the current namespace, with more details
kubectl get deployment my-dep                 # List a particular deployment
kubectl get pods                              # List all pods in the namespace
kubectl get pod my-pod -o yaml                # Get a pod's YAML

When working with this command, I’ll frequently use these arguments depending on the use-case/requirements.

  • -o | --output ⇒ Allows one to request the output in the following formats:
    • JSON
    • YAML
    • WIDE (additional columns)
    • Custom Go Template
    • JsonPath
  • -l ⇒ The label to filter by
  • -w ⇒ Watch, which polls the API when a resource change occurs

Describe

Linuxhint describes the describe command (see what I did there?) as,

[Kubectl Describe Pod] is a command that describes any resource in Kubernetes. It is used to show data on a single or even a collection of resources. This command combines a number of API calls to create a thorough description of a resource or set of resources.

Whereas my usage of kubectl get aligns with the idea of wanting to list out a specific resource type within a namespace, I see kubectl describe used as the exhaustive information keeper; providing literally everything it can on the resource’s etcd record.

kubectl describe nodes my-node      # Describes that specific node
kubectl describe pods my-pod        # Describes that specific pod

Explain

CloudARK explains the explain command (see what I did there! I’ll go to sleep now) best, and though their article was published in 2018, I don’t have any concern with the information; their explanation matches the behaviour of the command in 2023.

kubectl explain command is used to show documentation about Kubernetes resources like pod.

The information displayed as output of this command is obtained from the OpenAPI Specification for the Pod [resource]. OpenAPI Spec for all the Types is generated by the main API server when it starts up and is maintained by it in memory. Below we explain details of this process.

It seems that the only way to use ‘kubectl explain’ to discover static information for a custom resource is if that information can be served through the main API server’s OpenAPI Spec.

So this command is what inspiried my little post, because though I used get and describe on a daily basis, I rarely saw the reason or opportunity to use explain . From my [brief] understanding, it truly is the CRD documentation viewer for those who don’t have access to their source code. Moreso, explain provides two incredibly useful pieces of information which I relied on extensively:

  1. Field types relative to Go types (the language of Cloud, according to many… a topic for another day)
  2. Enum definitions if they are present within the CRD itself (often found within the CRD vs internal to the operator to allow for admission-validation prior to webhook validation(s)).

Resources