Article 19 – Kubectl Mastery: Navigation, Inspection, and Hacks

The Complexity of a Growing API

As your cluster grows, the number of supported API resources increases. You have to manage Ingresses, ServiceAccounts, NetworkPolicies, and custom resources.

If you need to write a configuration file for a resource you’ve never used before, looking up configuration formats online often returns outdated templates that result in syntax errors.

Additionally, when debugging an outage, scrolling through pages of raw YAML output in your terminal to find an IP address or container status is slow. You need native command-line methods to navigate, query, and filter resources.

Querying and Filtering the API

The kubectl CLI utility provides built-in options to inspect and navigate the API Server directly:

  • Resource Discovery: Running kubectl api-resources lists all resource types supported by your cluster, including their short names (e.g., po for pods), API groups, namespaced scope status, and resource Kind.
  • Inline Documentation: Running kubectl explain <resource> queries the API schemas directly to print field descriptions. Appending the --recursive flag prints the entire nested resource tree (e.g., kubectl explain deployment.spec --recursive).
  • Custom Output: You can expand default tables by appending -o wide (which shows pod IPs and node names). You can also extract specific fields using JSONPath filters or format output into custom tables using -o custom-columns.
  • Recursive Operations: The -R flag allows you to apply, delete, or modify configuration files recursively across deep directory structures (e.g., kubectl apply -f . -R).

Practical Kubectl Command Tricks

Let’s practice these commands to speed up cluster navigation.

First, lookup the short-name alias and API group for Horizontal Pod Autoscalers:

$ kubectl api-resources | grep -i horizontalpod
horizontalpodautoscalers   hpa          autoscaling/v2                         true         HorizontalPodAutoscaler

You can now run kubectl get hpa instead of typing the full resource name.

If you are writing a YAML file and need to verify the fields and policy options allowed under a container’s image pull configuration, run explain:

$ kubectl explain pod.spec.containers.imagePullPolicy
KIND:       Pod
VERSION:    v1

FIELD:      imagePullPolicy <string>

DESCRIPTION:
    Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always
    if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated.

If you need to list the names and IP addresses of all pods in the active namespace without displaying the other columns, query the JSONPath directly:

$ kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.podIP}{"\n"}{end}'
nginx-webserver    10.244.1.5
helper-pod         10.244.1.6
my-web-deploy-abc  10.244.1.7

This query loops through the pods list, prints the pod name, adds a tab separator, prints the pod IP, and adds a newline before repeating the loop.

You can also use custom columns to format output as a clean table:

$ kubectl get pods -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,IP:.status.podIP
NAME                NODE            IP
nginx-webserver     worker-node-1   10.244.1.5
helper-pod          worker-node-1   10.244.1.6
my-web-deploy-abc   worker-node-2   10.244.1.7

To quickly find which pods are running on a specific node without using selectors:

$ kubectl get pods --field-selector spec.nodeName=worker-node-1

Learning these command structures allows you to query your cluster and diagnose issues directly from the CLI.

Related Posts