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
According to the
[official Kubernetes Cheatsheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#viewing-and-finding-resources),
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:
- WIDE (additional columns)
- Custom Go Template
-l⇒ The label to filter by
-w⇒ Watch, which polls the API when a resource change occurs
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
kubectl describe nodes my-node # Describes that specific node kubectl describe pods my-pod # Describes that specific pod
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
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,
provides two incredibly useful pieces of information which I relied on
- Field types relative to Go types (the language of Cloud, according to many… a topic for another day)
- 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)).