Kubernetes · Chapter 2 of 28
kubectl and the API
By the end of this chapter you can find any kind the cluster knows and read its fields with kubectl explain, pull exactly the value you need out of an object with jsonpath and custom columns, read an object's events, move between namespaces, and turn a quick kubectl run into a YAML file you apply and keep. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Meet the cluster
- 5 tasks
- Kubernetes
- Free chapter
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.
Why you need this
Jhatpat's cluster already holds hundreds of objects: 14 dark stores' worth of pods, Deployments, nodes and events. Every morning Bhola asks small questions that need exact answers ("which node is the Aliganj catalog on?", "how much CPU may pods use on worker-2?"), and every deploy Ammar wants to know exactly what was changed and by whom.
With chapter 1's commands you can list things and read describe's long page, then scroll and copy by eye. That is slow and easy to get wrong when there are 40 pods, and it gives you nothing you can put in a script. And kubectl run makes a pod, but leaves no record of what you asked for: if the cluster is rebuilt tomorrow, nobody knows what to make again. This chapter shows that everything in Kubernetes is an object in the API, with fields you can ask for by name, and that the object can live in a file.
The lesson
Everything is an object
Each thing you have met so far, a node, a pod, a Deployment, an event, is an object stored in etcd and served by the API server. Each object has a kind (Pod, Node), belongs to an API group and version (v1, apps/v1), and is either namespaced (it lives in one namespace) or cluster-wide. kubectl api-resources lists every kind the API server knows, 73 of them in this cluster:
$ kubectl api-resources
NAME SHORTNAMES APIVERSION NAMESPACED KIND
...
namespaces ns v1 false Namespace
nodes no v1 false Node
pods po v1 true Pod
services svc v1 true Service
deployments deploy apps/v1 true Deployment
replicasets rs apps/v1 true ReplicaSet
...
SHORTNAMES are what you may type instead: kubectl get po, kubectl get deploy. A node is not namespaced (it belongs to the whole cluster); a pod is.
Reading the fields: kubectl explain
Every object has the same four parts at the top: apiVersion, kind, metadata (name, namespace, labels) and spec (what you want), and the cluster adds status (what is). kubectl explain is the reference built into the API server, field by field, with a dot path:
$ kubectl explain pod.spec.containers.ports
KIND: Pod
VERSION: v1
FIELD: ports <[]ContainerPort>
...
FIELDS:
containerPort <integer> -required-
Number of port to expose on the pod's IP address. This must be a valid port
number, 0 < x < 65536.
...
name <string>
If specified, this must be an IANA_SVC_NAME and unique within the pod. ...
<[]ContainerPort> means a list, -required- means the API server refuses the object without it. --recursive prints the whole tree of names without the descriptions, which is the fastest way to find where a field lives:
$ kubectl explain deployment.spec --recursive
...
FIELDS:
minReadySeconds <integer>
paused <boolean>
progressDeadlineSeconds <integer>
replicas <integer>
revisionHistoryLimit <integer>
selector <LabelSelector> -required-
matchExpressions <[]LabelSelectorRequirement>
...
A wrong path says so: kubectl explain pod.spec.containers.imag answers error: field "imag" does not exist.
Every way to get an object
kubectl get takes -o for the shape of the answer. -o wide adds the IP and node of each pod. -o yaml prints the whole object as the API server stores it, defaults and status included:
$ kubectl get pod catalog -o yaml
apiVersion: v1
kind: Pod
metadata:
...
labels:
app: catalog
name: catalog
namespace: ch02
uid: 2f37761d-a40e-49d3-a714-eba5b065ae69
spec:
containers:
- image: jhatpat/catalog:1.2
imagePullPolicy: IfNotPresent
name: catalog
ports:
- containerPort: 8080
protocol: TCP
...
nodeName: worker-3
restartPolicy: Always
...
Ammar wrote six lines of spec; the API server filled in the rest (imagePullPolicy, protocol, restartPolicy), and the scheduler wrote nodeName. -o json is the same object as JSON, which is what tools read.
Exactly the value: jsonpath
-o jsonpath picks fields out of that JSON with a path in braces, starting at the object: .spec.nodeName is the field nodeName inside spec.
$ kubectl get pod catalog -o jsonpath='{.spec.nodeName}'
worker-3
$ kubectl get node worker-1 -o jsonpath='{.status.capacity}'
{"cpu":"4","ephemeral-storage":"100Gi","memory":"8Gi","pods":"110"}
$ kubectl get node worker-1 -o jsonpath='{.status.capacity.memory}'
8Gi
A node's capacity is the whole machine; its allocatable (also in status) is what is left for pods once the system has its share. When you get a list, the objects are in .items, and [*] means every one:
$ kubectl get pods -o jsonpath='{.items[*].metadata.name}'
catalog storefront-5bf47bc8c9-fw2wr storefront-5bf47bc8c9-nw6wp storefront-5bf47bc8c9-x8jl2
$ kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.nodeName}{"\n"}{end}'
catalog worker-3
storefront-5bf47bc8c9-fw2wr worker-2
storefront-5bf47bc8c9-nw6wp worker-1
storefront-5bf47bc8c9-x8jl2 worker-3
{range ...}{end} repeats what is between them for each item; {"\t"} and {"\n"} print a tab and a new line. Put the whole path in single quotes so the shell leaves the braces alone.
The trap: a misspelled field is not an error. -o jsonpath='{.spec.containers[0].imag}' prints nothing at all and exits 0, because the object simply has no field by that name. If the answer is empty, check the path with kubectl explain or -o yaml.
Columns of your own and sorting
-o custom-columns builds a table: a heading, a colon, a path, and a comma before the next column. --sort-by takes a path too:
$ kubectl get pods -o custom-columns=NAME:.metadata.name,IMAGE:.spec.containers[0].image,NODE:.spec.nodeName
NAME IMAGE NODE
catalog jhatpat/catalog:1.2 worker-3
storefront-5bf47bc8c9-fw2wr jhatpat/storefront:1.2 worker-2
storefront-5bf47bc8c9-nw6wp jhatpat/storefront:1.2 worker-1
storefront-5bf47bc8c9-x8jl2 jhatpat/storefront:1.2 worker-3
$ kubectl get pods --sort-by=.spec.nodeName -o wide
NAME READY STATUS RESTARTS AGE IP NODE ...
storefront-5bf47bc8c9-nw6wp 1/1 Running 0 29s 10.244.1.9 worker-1
storefront-5bf47bc8c9-fw2wr 1/1 Running 0 29s 10.244.2.9 worker-2
catalog 1/1 Running 0 29s 10.244.3.9 worker-3
storefront-5bf47bc8c9-x8jl2 1/1 Running 0 29s 10.244.3.16 worker-3
describe and events
describe is for people: it gathers the object and everything related to it on one page, and ends with its events. Events are objects too, so you can list a whole namespace's with kubectl get events:
$ kubectl get events --sort-by=.lastTimestamp
...
6m38s Normal Created pod/catalog Created container: catalog
6m38s Normal Pulled pod/catalog Successfully pulled image "jhatpat/catalog:1.2" in 1.602s (1.602s including waiting). Image size: 61442108 bytes.
6m38s Normal Started pod/catalog Started container catalog
Events are kept for an hour, so they explain what happened recently, not last week.
Namespaces and your context
A namespace is a name prefix for objects: two pods may both be called catalog if they are in different namespaces. This cluster has the system's namespaces and one per chapter; Ammar also made ch02-staging, where the next catalog is tried before it reaches customers:
$ kubectl get namespaces
NAME STATUS AGE
ch02 Active 38s
ch02-staging Active 41s
default Active 22m
ingress-nginx Active 22m
kube-node-lease Active 22m
kube-public Active 22m
kube-system Active 22m
-n ch02-staging asks one namespace once, and -A asks all of them. Which namespace you get when you say nothing comes from your context, an entry in ~/.kube/config that ties together a cluster, a user and a namespace:
$ kubectl config get-contexts
CURRENT NAME CLUSTER AUTHINFO NAMESPACE
* jhatpat jhatpat-lucknow admin ch02
kubectl config set-context --current --namespace=... changes the namespace of the context you are in. Here it moves to the system's namespace and back:
$ kubectl config set-context --current --namespace=kube-system
Context "jhatpat" modified.
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
coredns-5b5c68975-727wd 1/1 Running 0 22m
coredns-5b5c68975-dcjd5 1/1 Running 0 22m
$ kubectl config set-context --current --namespace=ch02
Context "jhatpat" modified.
Only your kubeconfig file changed; the cluster did not. Forgetting where you are is a classic mistake ("my pods are gone!"), so look at the NAMESPACE column, or the "No resources found in ... namespace" line.
Imperative and declarative
There are two ways to tell the cluster what you want. Imperative commands say what to do now: kubectl create deployment menu-board --image=nginx:1.29 --replicas=2, kubectl run, kubectl delete. They are quick, but run it twice and the second fails:
$ kubectl create deployment menu-board --image=nginx:1.29
error: failed to create deployment: deployments.apps "menu-board" already exists
Declarative means you write the object you want in a file and kubectl apply -f it. apply compares the file with the cluster and creates, changes or leaves the object as needed, so running it again is safe:
$ kubectl apply -f namaste.yaml
pod/namaste created
$ kubectl apply -f namaste.yaml
pod/namaste unchanged
apply also writes what you applied into the object, in the annotation kubectl.kubernetes.io/last-applied-configuration, so next time it can tell which fields you removed. A pod made by kubectl run has no such annotation.
YAML for free: --dry-run=client -o yaml
You do not have to type a manifest from memory. Any create or run command with --dry-run=client -o yaml builds the object in kubectl, prints it, and sends nothing to the cluster:
$ kubectl run namaste --image=nginx:1.29 --port=80 --dry-run=client -o yaml
apiVersion: v1
kind: Pod
metadata:
labels:
run: namaste
name: namaste
spec:
containers:
- image: nginx:1.29
name: namaste
ports:
- containerPort: 80
resources: {}
dnsPolicy: ClusterFirst
restartPolicy: Always
status: {}
Send it to a file with > namaste.yaml, read it, and apply the file. --env=NAME=value adds an environment variable the same way. The file is now the record of what you asked for, and the whole cluster can be made again from such files.
Some fields of a running pod cannot change, and the API server says exactly which ones may:
$ kubectl apply -f namaste.yaml
The Pod "namaste" is invalid: spec: Forbidden: pod updates may not change fields other than `spec.containers[*].image`,`spec.initContainers[*].image`,`spec.activeDeadlineSeconds`,`spec.tolerations` (only additions to existing tolerations),...
That is what happens when the port in the file is changed after the pod exists: delete the pod and apply again.
Under kubectl: plain HTTP
Every kubectl command is an HTTPS request to the API server, and kubectl get --raw shows the raw answer to a path, without any formatting. kubectl get --raw /api/v1/namespaces/ch02/pods/catalog returns the catalog pod's JSON, and kubectl get --raw /version the server's version ("gitVersion": "v1.36.5"). Chapter 16 calls the same paths with curl from inside a pod.
Your turn
- Task 1: worker-2's allocatable CPU, with jsonpath, in cpu.txt.
- Task 2: the IP of every pod Ammar made in ch02, with jsonpath, in ips.txt.
- Task 3: generate the catalog-kanpur pod's manifest with a dry run, then apply it.
- Task 4: switch your context to ch02-staging, and write the staging catalog's image in staging.txt.
- Task 5: the interview question. Ammar will ask: "Why do we keep YAML in git instead of running kubectl create?"
The trap: jsonpath prints nothing for a misspelled field, and kubectl uses your context's namespace when you give none. Edit the files with nano, and press Check when you are done.
What you build: 5 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
cpu.txt: worker-2's allocatable CPU
Ask the cluster for one exact value: how much CPU pods may use on the node worker-2.
1. Use kubectl get node worker-2 with -o jsonpath.
2. Give jsonpath the path to the allocatable CPU: status.allocatable.cpu. Do not use capacity.
3. Write the value in cpu.txt, below the notes, on a line of its own.
To pass: cpu.txt has the value exactly as kubectl prints it, with its unit if it has one. You also ran a kubectl command with jsonpath, and the command worked.
- Task 2
ips.txt: the IP of every pod Ammar made
Ask the cluster for the IP of every pod Ammar made in ch02.
1. Use kubectl get pods with -o jsonpath. Ask for every item's status.podIP.
2. Write the IPs in ips.txt, below the notes. Put one IP on each line, or put them on one line with spaces between them.
To pass: ips.txt has the IPs of all four of Ammar's pods: catalog and the three storefront pods. The lines have only IPs, with no names or commas. The IPs belong to the pods that run now. The IP of your own catalog-kanpur pod may be there too. You also ran a kubectl command with jsonpath, and the command worked.
- Task 3
catalog-kanpur.yaml: a manifest from a dry run
Let kubectl write a pod manifest for you, then make the pod from that file.
1. Use kubectl run with --dry-run=client -o yaml. Send its output into catalog-kanpur.yaml.
2. The pod: name catalog-kanpur, image jhatpat/catalog:1.2, containerPort 8080, and the variable CITY with the value kanpur.
3. Make the pod with kubectl apply -f catalog-kanpur.yaml, in ch02.
To pass: catalog-kanpur.yaml has a Pod named catalog-kanpur, and the cluster accepts the file. The pod catalog-kanpur has that image, port and CITY value, and it is Running and ready. It must be made by kubectl apply. A pod made by kubectl run alone does not count: delete it, then apply the file.
- Task 4
staging.txt: switch your context to ch02-staging
Work in another namespace without typing -n each time.
1. Change the namespace of your current context to ch02-staging with kubectl config set-context.
2. List the pods. Find the image of the catalog pod there.
3. Write that image in staging.txt, on a line of its own: repository and tag, like jhatpat/example:9.9.
4. Switch your context back to ch02, so the other tasks work as before.
To pass: you ran kubectl config set-context with --namespace=ch02-staging, and the command worked. staging.txt has the image of the catalog pod in ch02-staging, not the one in ch02.
- Task 5 · interview question
Interview: why Jhatpat keeps YAML in git
Ammar will ask: "Why do we keep YAML in git instead of running kubectl create?"
1. Write two or three sentences in your own words in answer.txt, below the notes.
2. Say how commands like kubectl create and kubectl run are different from files used with kubectl apply -f.
3. Say what git gives you when the files live there.
To pass: answer.txt names the files, YAML or kubectl apply, and says what git gives you, such as history, review, or making the same cluster again.
What you will learn
- Kinds and fields: kubectl api-resources lists every kind; kubectl explain describes its fields.
- Output formats: -o wide, -o yaml, -o json, -o jsonpath, -o custom-columns, --sort-by.
- describe and events: what each part of the cluster did to an object.
- Namespaces and the context: which cluster, user and namespace kubectl uses, and how to switch.
- Imperative and declarative: kubectl create and run against kubectl apply -f.
- YAML from kubectl: --dry-run=client -o yaml writes a manifest for you.
More in Meet the cluster
Build "kubectl and the API" yourself
Jhatpat delivers groceries in ten minutes from 14 dark stores across Lucknow, and its hand-run servers fall over on festival evenings. You move it onto Kubernetes. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.