Kubernetes · Chapter 1 of 28

What Kubernetes is for

By the end of this chapter you can say what problem Kubernetes solves for Jhatpat, name the parts of a cluster and what each one does, list the cluster's nodes with kubectl, start a pod, read what it printed, see why it was put where it was, and watch the cluster replace a pod that dies. 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 delivers groceries in ten minutes from 14 dark stores across Lucknow: about 62,000 orders on a normal day, and four times that on a festival evening. Until now its services (the storefront, the catalog, the cart, orders, payments) ran on three virtual machines that Tushar set up by hand, with a script that copied each new version to the machines one by one.

On Dhanteras last year, Saturday 18 October 2025, at 8:12 pm, one machine's disk filled up with logs. The cart service on it stopped. Nothing noticed: the load balancer kept sending a third of all customers to that machine, and 2,300 orders failed in 40 minutes, until Tushar logged in and found it. A week earlier, the deploy script had stopped halfway, and for a day a third of customers saw old prices. Ritika, Jhatpat's founder, has one rule for this Diwali (Sunday 8 November): a customer must never see an empty cart at 9 pm on Dhanteras.

Scripts and hand-run machines cannot keep that rule. A script does what it is told once, when it is run: it does not notice at 8:12 pm that the cart has stopped, it does not start a new one on a machine that has room, and it does not stop sending customers to the dead one. You would need a watcher for every service on every machine, and someone awake to read its alerts. Ammar, Jhatpat's platform lead, is moving the services to Kubernetes, which does that watching as its whole job. You do the move with him.

The lesson

Desired state

Kubernetes works on one idea. You do not tell it what to do step by step ("start the cart on machine 2"). You tell it what you want to be true ("3 copies of the cart, each with 256 MiB of memory"), and it writes that down. Then small programs called controllers compare what you want with what is running, all day, and fix any difference they find. A copy died? One is missing: start one. A machine went away? Its copies are missing: start them elsewhere.

That is the difference from a script. A script acts once. A controller keeps acting for as long as the cluster runs, so the evening of Dhanteras looks after itself.

The cluster and its nodes

A Kubernetes cluster is a set of machines working as one. The machines that run your apps are nodes. Jhatpat's cluster has four, and kubectl (say it "cube control") lists them:

$ kubectl get nodes
NAME         STATUS   ROLES    AGE    VERSION
payments-1   Ready    <none>   105s   v1.36.5
worker-1     Ready    <none>   105s   v1.36.5
worker-2     Ready    <none>   105s   v1.36.5
worker-3     Ready    <none>   105s   v1.36.5

Ready means the node is healthy and can take work. VERSION is the Kubernetes version its node agent runs. -o wide adds more columns: each node's address inside the cluster's network, its operating system and its container runtime (containerd, the program that actually starts containers on that machine):

$ kubectl get nodes -o wide
NAME         STATUS   ROLES    AGE    VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION             CONTAINER-RUNTIME
payments-1   Ready    <none>   106s   v1.36.5   10.20.0.21    <none>        Ubuntu 24.04.3 LTS   6.8.0-79-generic (amd64)   containerd://2.1.4
worker-1     Ready    <none>   106s   v1.36.5   10.20.0.11    <none>        Ubuntu 24.04.3 LTS   6.8.0-79-generic (amd64)   containerd://2.1.4
worker-2     Ready    <none>   106s   v1.36.5   10.20.0.12    <none>        Ubuntu 24.04.3 LTS   6.8.0-79-generic (amd64)   containerd://2.1.4
worker-3     Ready    <none>   106s   v1.36.5   10.20.0.13    <none>        Ubuntu 24.04.3 LTS   6.8.0-79-generic (amd64)   containerd://2.1.4

Every object in Kubernetes can carry labels, short key and value pairs that say what it is (chapter 4 is about them). Ammar labelled each node with the pool it belongs to, and -L shows a label as a column of its own:

$ kubectl get nodes -L jhatpat.in/pool
NAME         STATUS   ROLES    AGE    VERSION   POOL
payments-1   Ready    <none>   106s   v1.36.5   payments
worker-1     Ready    <none>   106s   v1.36.5   general
worker-2     Ready    <none>   106s   v1.36.5   general
worker-3     Ready    <none>   106s   v1.36.5   general

payments-1 is kept for the payments team (chapter 14 shows how), and the three workers run everything else. Each node also has a label that says which zone of the data centre it is in, topology.kubernetes.io/zone: spreading copies over zones means a power cut in one zone does not take Jhatpat down. Finding each node's zone is your first task.

The control plane

Something has to keep the wishes, decide where each app runs, and run the controllers. That is the control plane. In many clusters it runs on machines of its own; in your lab it runs as programs on the lab machine itself, and lab ps shows them:

$ lab ps
  PID   MEMORY  COMMAND
   11     57 MB  etcd
   13    265 MB  kube-apiserver
  125     90 MB  kube-controller-manager
  127     49 MB  kube-scheduler
  130     51 MB  kwok-controller
  135     61 MB  metrics-server
  • etcd is the cluster's database. Every wish and every fact about the cluster is a record in it, and nothing else in Kubernetes keeps state.
  • kube-apiserver is the only door to etcd. kubectl, the controllers, the scheduler and every node talk to the API server, and it checks who you are and whether you may, before it reads or writes anything.
  • kube-scheduler picks a node for every new pod that has none: one with enough room, that the pod is allowed on.
  • kube-controller-manager runs the controllers, one for each kind of thing: Deployments, ReplicaSets, nodes, Jobs and dozens more.
  • On every node, the kubelet watches the API server for pods given to its node, asks the container runtime to start them, and reports back how they are. In this lab, kwok-controller is the kubelet of all four nodes (more on that at the end).

metrics-server measures how much CPU and memory pods use; chapter 23 needs it. Note the sizes: the API server alone uses about 265 MB, which is why a real cluster gives its control plane machines of its own.

How kubectl talks to the cluster

kubectl is a client. It reads the address of the API server and your credentials from a file, ~/.kube/config, and turns each command into a request to the API server over HTTPS:

$ kubectl cluster-info
Kubernetes control plane is running at https://127.0.0.1:6443

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

$ kubectl version
Client Version: v1.36.5
Kustomize Version: v5.8.1
Server Version: v1.36.5

So kubectl get nodes is "API server, give me the list of nodes", and the API server reads them from etcd. Nothing in kubectl talks to the nodes directly.

Your first pod

You never run a container on Kubernetes directly. The smallest thing it runs is a pod: one container, or a few that must live together, with one address in the cluster's network. kubectl run makes a pod from an image. Here is nginx, a web server, in a pod named namaste:

$ kubectl run namaste --image=nginx:1.29
pod/namaste created

$ kubectl get pods -o wide
NAME                          READY   STATUS    RESTARTS   AGE   IP           NODE       NOMINATED NODE   READINESS GATES
namaste                       0/1     Pending   0          0s    <none>       worker-2   <none>           <none>
storefront-5bf47bc8c9-2z9pt   1/1     Running   0          4s    10.244.1.9   worker-1   <none>           <none>
storefront-5bf47bc8c9-6vttd   1/1     Running   0          4s    10.244.3.9   worker-3   <none>           <none>
storefront-5bf47bc8c9-tclfp   1/1     Running   0          4s    10.244.2.9   worker-2   <none>           <none>

$ kubectl get pod namaste
NAME      READY   STATUS              RESTARTS   AGE
namaste   0/1     ContainerCreating   0          1s

$ kubectl get pod namaste -o wide
NAME      READY   STATUS    RESTARTS   AGE   IP            NODE       NOMINATED NODE   READINESS GATES
namaste   1/1     Running   0          4s    10.244.2.16   worker-2   <none>           <none>

pod/namaste created came back at once, before anything ran: the API server only wrote the wish into etcd. Within a second the scheduler had already given it a node (worker-2) but no container existed yet, so it was Pending. Then worker-2's kubelet pulled the image (ContainerCreating) and started it: Running, with an address of its own, 10.244.2.16. READY 1/1 means one container of one is ready. Your pods get other names, nodes and addresses.

The pods are in ch01, this chapter's namespace: a folder for objects, so each chapter's pods do not mix with the others' (chapter 2 explains namespaces). The three storefront pods are Ammar's; you meet them again in a moment.

What the pod printed

A container's output is kept by its node, and kubectl logs fetches it through the API server. nginx says what it did to start:

$ kubectl logs namaste
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Configuration complete; ready for start up
2026/10/26 00:38:50 [notice] 1#1: nginx/1.29.3
2026/10/26 00:38:50 [notice] 1#1: start worker processes

Jhatpat's own apps write their logs the same way. Their hello app says who and where it is, and prints a welcome code that is different for every pod. Here is a pod named chai, from version 1.1 of the image:

$ kubectl logs chai
INFO  [hello] starting hello 1.1 (Node.js 24.11.1)
INFO  [hello] Namaste from Jhatpat, Lucknow! I am pod chai on node worker-1
INFO  [hello] today's welcome code: 5PLXHK
INFO  [hello] listening on :8080

Logs are the first place to look when a pod misbehaves, so learn the habit now.

What happened, step by step

kubectl describe shows everything Kubernetes knows about an object, and at the end its events: what each part of the cluster did to it, oldest first.

$ kubectl describe pod namaste
...
Events:
  Type    Reason     Age   From               Message
  ----    ------     ----  ----               -------
  Normal  Scheduled  3s    default-scheduler  Successfully assigned ch01/namaste to worker-2
  Normal  Pulling    3s    kubelet            Pulling image "nginx:1.29"
  Normal  Pulled     2s    kubelet            Successfully pulled image "nginx:1.29" in 1.610s (1.610s including waiting). Image size: 72195292 bytes.
  Normal  Created    2s    kubelet            Created container: namaste
  Normal  Started    2s    kubelet            Started container namaste

Read the From column: the scheduler chose the node, then that node's kubelet pulled the image, created the container and started it. When a pod is stuck, the last event usually says why (a wrong image name shows up here as Failed to pull image).

A pod alone is not looked after

Delete namaste and watch it with --watch, which keeps printing changes:

$ kubectl get pods namaste --watch
NAME      READY   STATUS    RESTARTS   AGE
namaste   1/1     Running   0          9s
namaste   1/1     Terminating   0          11s
namaste   1/1     Terminating   0          12s
namaste   1/1     Terminating   0          12s

The pod is told to stop (Terminating), and then it is gone. Nothing brings it back, because nobody wished for it to exist: you made one pod, once, by hand. That is exactly Jhatpat's old machine with its cart service on it.

Pods that come back

Ammar's storefront is different. He did not run three pods; he made one Deployment that says "three copies of storefront 1.2":

$ kubectl get deployments
NAME         READY   UP-TO-DATE   AVAILABLE   AGE
storefront   3/3     3            3           23s

READY 3/3: three wanted, three ready. The Deployment's controller keeps it so: when a storefront pod dies, it counts two where three are wanted, and makes a new pod, which the scheduler places and a kubelet starts, all without anyone typing a command. Chapter 5 shows how a Deployment does it; this chapter, you watch it happen.

This lab's cluster

Your lab runs a real Kubernetes 1.36.5 control plane: etcd, the API server, the scheduler, the controller manager and metrics-server are the same programs a production cluster runs, so everything you type with kubectl is answered by real Kubernetes. The four nodes are pretend: a tool called kwok plays their kubelets, and the lab plays the containers and the apps inside them, Jhatpat's and nginx, Redis and PostgreSQL, from each pod's spec. Their logs, their exec shells, their crashes and their network follow what you wrote, the way real ones would, in a lab that starts in a few seconds.

Your turn

  • Task 1: list the nodes with their zones, and write each node and its zone into zones.txt.
  • Task 2: run a pod named hello from jhatpat/hello:1.0.
  • Task 3: read hello's logs and write its welcome code into code.txt.
  • Task 4: delete one storefront pod by its name, and watch a new one take its place.
  • Task 5: the interview question. Ammar will ask: "You deleted a pod and another one appeared. Who made it, and how did it know?"

The trap: a pod's welcome code belongs to that pod. Delete hello and run it again, and you have a new pod with a new code. Edit the files with nano (nano zones.txt, Ctrl+O to save, Ctrl+X to leave), 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.

  1. Task 1

    zones.txt: which zone each node is in

    Find out which zone each node of the cluster is in, and save it in zones.txt.

    1. Run kubectl get nodes. It lists the nodes by name.

    2. Run it again with -L topology.kubernetes.io/zone. This adds a column with each node's zone.

    3. In zones.txt, below the notes, write one line for each node: its name, a space, then its zone. For example: worker-9 lucknow-z.

    To pass: zones.txt has one line for each of the four nodes, payments-1 too, in any order. Names and zones are spelled exactly as kubectl prints them. There are no other lines, so do not copy the NAME header. Lines that start with # are notes and do not count.

  2. Task 2

    Run the hello pod

    Start your first pod and watch it run.

    1. Use kubectl run to start a pod. Name it hello and use the image jhatpat/hello:1.0.

    2. Run kubectl get pods until hello shows Running and 1/1.

    To pass: a pod named hello is in the namespace ch01 (the current one). It runs the image jhatpat/hello:1.0, with that exact tag, and it is Running and ready (1/1). If you used another image, delete hello and run it again.

  3. Task 3

    code.txt: the hello pod's welcome code

    Read what the hello app printed, and save its welcome code.

    1. Read the hello pod's logs with kubectl logs.

    2. Find the line with the welcome code. The code is six capital letters and digits.

    3. Write the code in code.txt, below the notes, on a line of its own.

    To pass: you ran kubectl logs for the hello pod, and the command worked. code.txt has the welcome code of the hello pod that runs now, alone on its line. Each new hello pod prints a new code, so if you made hello again, read its logs again.

  4. Task 4

    Delete a storefront pod and watch it come back

    See Kubernetes replace a pod that is gone.

    1. Run kubectl get pods. You see three pods with names that start with storefront-.

    2. Delete one of them by its full name, with kubectl delete pod.

    3. Wait a few seconds. Run kubectl get pods again. Look at the AGE of each storefront pod.

    To pass: you ran kubectl delete pod, and the command worked. A new storefront pod took the place of the old one, and 3 storefront pods are ready. Do not delete the Deployment storefront itself: delete only a pod.

  5. Task 5 · interview question

    Interview: what keeps 3 pods running

    Ammar will ask: "You deleted a pod and another one appeared. Who made it, and how did it know?"

    1. Write a sentence or two in your own words in answer.txt, below the notes.

    2. Say what keeps 3 storefront pods running.

    3. Say what it does when one of the pods dies.

    To pass: answer.txt names the Deployment, its ReplicaSet or the controller, and says that it makes a new pod.

What you will learn

  • Desired state: you tell Kubernetes what you want running, and it keeps it so.
  • The cluster: nodes that run your apps, and the control plane that decides.
  • The control plane: etcd, the API server, the scheduler and the controller manager.
  • kubectl: the command that talks to the API server; get, describe, run, logs, delete.
  • Pods: the smallest thing Kubernetes runs, one or more containers together.
  • Self-healing: a Deployment's pods come back when one dies; a pod on its own does not.

More in Meet the cluster

Build "What Kubernetes is for" 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.