Chapter 44 of 47 · Under the hood

Kubernetes cluster architecture

You know the objects now: Pod, ReplicaSet, Deployment and Service. This chapter shows the machinery that makes them work. A cluster is a group of machines that work together to run your applications. Inside it there are two kinds of node: the control plane, which decides, and worker nodes, which run your containers. Everything you write is an API object that describes the state you want.

Kubernetes itselfwhat you work withwhat it is made oflit up in the walk-through

The map

Click a box to see what it does. Click it again to fold or unfold what is inside. With the keyboard, use the arrow keys to move and Enter to fold.

Two kinds of node

Follow one kubectl apply

What happens between typing the command and a container running? ▶ Play it on the map

1. You run kubectl apply -f web.yaml. kubectl sends the Deployment to the API server, which checks who you are and whether the object is valid.
2. The API server saves the Deployment in etcd. At this point nothing is running. The cluster only knows what you want.
3. Controllers react. The Deployment controller sees a Deployment without a ReplicaSet and creates one. The ReplicaSet controller sees 0 of 3 Pods and creates 3 Pod objects, still with no node.
4. The scheduler places the Pods. It sees Pods with no node, scores the worker nodes, and writes the chosen node name into each Pod.
5. The kubelet starts them. The kubelet on each chosen node sees a Pod assigned to it, tells the container runtime to pull the image and start the containers, then reports the Pod as Running.
6. Traffic finds them. A Service whose selector matches the Pods' labels lists their IPs, and kube-proxy on every node updates its rules so the ClusterIP reaches them.

Every arrow in this story goes through the API server. The scheduler never calls the kubelet; it writes a field, and the kubelet notices.

The objects you write

A Deployment, a Service and a ConfigMap are enough to run most stateless apps:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3                 # the ReplicaSet keeps 3 Pods alive
  selector:
    matchLabels: { app: web }
  template:                   # the Pod template
    metadata:
      labels: { app: web }
    spec:
      containers:
        - name: web
          image: nginx:1.27
          ports: [{ containerPort: 80 }]
---
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  type: ClusterIP             # the default
  selector: { app: web }      # matches the Pod labels above
  ports: [{ port: 80, targetPort: 80 }]

The link between a Service and its Pods is only the label app: web. Get the label wrong and the Service has no endpoints, which is one of the most common "it does not work" bugs.

Try it yourself

You need Docker, kind and kubectl. Versions and names in the output will differ on your machine.

1. Step 1 · Create a cluster

   kind runs each node as a Docker container. This cluster has a single node that is both control plane and worker.

   $ kind create cluster --name lab
   $ kubectl get nodes
   NAME                STATUS   ROLES           AGE   VERSION
   lab-control-plane   Ready    control-plane   40s   v1.31.0

2. Step 2 · Find the control plane

   The components from the map are Pods in the kube-system namespace. There is no cloud-controller-manager on kind.

   $ kubectl get pods -n kube-system
   NAME                                        READY   STATUS
   coredns-7c65d6cfc9-6bz8q                    1/1     Running
   etcd-lab-control-plane                      1/1     Running
   kube-apiserver-lab-control-plane            1/1     Running
   kube-controller-manager-lab-control-plane   1/1     Running
   kube-proxy-4x2mv                            1/1     Running
   kube-scheduler-lab-control-plane            1/1     Running

3. Step 3 · Deploy and look at the chain

   $ kubectl create deployment web --image=nginx:1.27 --replicas=3
   $ kubectl get deploy,rs,pods
   NAME                  READY   UP-TO-DATE   AVAILABLE
   deployment.apps/web   3/3     3            3
   
   NAME                             DESIRED   CURRENT   READY
   replicaset.apps/web-6d4cf56db6   3         3         3
   
   NAME                       READY   STATUS
   pod/web-6d4cf56db6-8kq2p   1/1     Running
   pod/web-6d4cf56db6-m7x4t   1/1     Running
   pod/web-6d4cf56db6-zt9wn   1/1     Running

   The Pod names carry the ReplicaSet's name, which carries the Deployment's name.

4. Step 4 · Put a Service in front

   $ kubectl expose deployment web --port=80
   $ kubectl get endpointslices -l kubernetes.io/service-name=web
   NAME        ADDRESSTYPE   PORTS   ENDPOINTS
   web-x7k2d   IPv4          80      10.244.0.5,10.244.0.6,10.244.0.7

5. Step 5 · Watch it heal

   Delete one Pod and watch the ReplicaSet create a replacement within seconds.

   $ kubectl delete pod web-6d4cf56db6-8kq2p
   $ kubectl get pods
   NAME                   READY   STATUS    AGE
   web-6d4cf56db6-m7x4t   1/1     Running   3m
   web-6d4cf56db6-zt9wn   1/1     Running   3m
   web-6d4cf56db6-qr5vb   1/1     Running   4s
   $ kind delete cluster --name lab

Recap

• A cluster has two kinds of node: the control plane decides, worker nodes run Pods.
• The API server is the only door, and etcd is the only memory. Everything else watches the API server.
• The scheduler picks a node; the kubelet on that node starts the containers through the container runtime.
• You write objects (Deployment, Service, ConfigMap, Secret) that describe the desired state; controllers make it true.
• A Deployment manages ReplicaSets, a ReplicaSet manages Pods, a Pod holds containers, and a Service finds Pods by label.

Quick check