Finding your way around kubectl

Finding your way around kubectl

Nobody memorises the Kubernetes API. The cluster can describe itself, and this chapter is how you make it do that. Everything here works offline, against the version you are actually running - which is more than the internet can promise.

What kinds of object exist?

kubectl api-resources
kubectl api-resources | grep -i ingress
kubectl api-resources --namespaced=false      # cluster-scoped kinds

The output gives you four things per kind: the plural name you type, its short name (deploy, svc, po), the API group and version, and whether it is namespaced.

graph LR A["api-resources<br/>which kinds exist?"] --> B["explain<br/>which fields does it have?"] B --> C["get -o yaml<br/>what is stored right now?"] C --> D["describe<br/>what happened to it?"] D --> E["logs<br/>what did the app say?"]

What fields does a kind have?

kubectl explain is the API reference, generated from the running server.

kubectl explain pod                            # top level
kubectl explain pod.spec                       # one level down
kubectl explain pod.spec.containers.resources  # keep drilling
kubectl explain deploy.spec.strategy --recursive | head -20
kubectl explain ingress.spec.rules

Read the -required- markers: they tell you the minimum manifest for any kind.

Command help

kubectl help
kubectl create --help          # every subcommand has its own help
kubectl create deploy --help   # with examples at the bottom
kubectl options                # global flags

The examples at the bottom of --help are usually the fastest answer.

What does the object look like right now?

kubectl get pod web -o yaml            # everything, including defaults the API filled in
kubectl get pod web -o jsonpath='{.status.podIP}'
kubectl get pods -o wide               # node, IP, age
kubectl get deploy web -o yaml | grep -A5 strategy

get -o yaml shows the object; describe shows the object plus events, plus the objects around it.

describe

kubectl describe pod web
kubectl describe node worker01
kubectl describe svc web-svc

Scroll to the bottom. The Events block is the single most useful output in Kubernetes: it is the controller telling you, in plain text, what it tried and what went wrong.

Events expire (about an hour by default). Absence of events on an old object means nothing.

logs

kubectl logs web
kubectl logs web -c sidecar            # a specific container
kubectl logs web --previous            # the instance that crashed
kubectl logs -l app=web --tail=50      # by label, across Pods
kubectl logs -f deploy/web             # follow, via the controller

describe before logs: if the container never started, there are no logs and the reason is in the events.

Generate manifests instead of writing them

kubectl run web --image nginx --dry-run=client -o yaml > web.yaml
kubectl create deploy web --image nginx --dry-run=client -o yaml
kubectl create ingress web --rule="web.k8s.lab/*=web-svc:80" --dry-run=client -o yaml

This is the intended workflow: generate a skeleton imperatively, edit it, apply it declaratively.

References