Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 78 ยท Getting Started

Cluster Architecture

Understand the Kubernetes control plane (API server, etcd, scheduler, controllers) and node components, and follow a request from kubectl to a running pod.

A Kubernetes cluster is a set of machines that work as one. Some of them run the cluster's brain, called the control plane; the rest, called worker nodes, run your applications. Knowing which component does what pays off every time something goes wrong, because almost every symptom can be traced to one of a handful of programs.

This lesson names each part, shows how a single kubectl apply travels through them, and ends with a small Python model of the most important component: the API server, which stores objects and tells everyone else when they change.

The control plane decides

API server The only front door.
etcd The database of all objects.
Scheduler Chooses a node for each pod.
Controllers Reconcile desired and actual.
1 / 2

The control plane

The control plane makes global decisions: where to run things, what to do when something fails. It consists of four main programs.

  • kube-apiserver. Every request goes through it: yours (via kubectl), the scheduler's, the kubelets', the controllers'. It authenticates the caller, checks authorization, validates the object, runs admission checks and then stores the result. It is the only component that talks to etcd.
  • etcd. A consistent, distributed key-value store holding the entire state of the cluster: every pod, Service, Secret and ConfigMap. Lose etcd and you lose the cluster's memory, so it is backed up and often run on three or five machines.
  • kube-scheduler. Watches for pods that have no node yet and picks one for each, based on resources, constraints and preferences. See How the Scheduler Works.
  • kube-controller-manager. Runs dozens of controllers in one process: the Deployment controller, the node controller (which notices dead nodes), the Job controller and more. Each one is a reconcile loop like the one in What Is Kubernetes?.

Cloud providers add a fifth piece, the cloud-controller-manager, which talks to the provider's API to create load balancers or attach disks.

On managed services (EKS, GKE, AKS) the provider runs the control plane for you and you only see worker nodes. See Running a Local Cluster.

The worker nodes

Each node runs three components.

  • kubelet. An agent that registers the node with the API server, watches for pods assigned to it, tells the runtime to start the containers, runs probes and reports status back.
  • Container runtime. The software that actually pulls images and runs containers, reached through the Container Runtime Interface (CRI). Common choices are containerd and CRI-O.
  • kube-proxy. Maintains network rules so that traffic sent to a Service reaches one of its pods. How Services Really Work opens this up.

Add-ons run as ordinary pods: cluster DNS (CoreDNS), a network plugin, a metrics server and so on.

flowchart LR
    U["kubectl"] --> A["API server"]
    A <--> E[("etcd")]
    S["Scheduler"] --> A
    C["Controller manager"] --> A
    K["kubelet (node)"] --> A
    K --> R["Container runtime"]

Everything talks to the API server; only the API server talks to etcd.

Following one request

Suppose you run kubectl apply -f web.yaml for a Deployment with three replicas. What happens?

  1. kubectl reads your kubeconfig, finds the API server address and credentials, and sends the manifest as an HTTPS request.
  2. The API server authenticates you, checks RBAC authorization, runs admission controllers and validates the object, then writes the Deployment to etcd.
  3. The Deployment controller is watching Deployments. It is notified of the new one, and creates a ReplicaSet object through the API server.
  4. The ReplicaSet controller sees the ReplicaSet and creates three Pod objects, still with no node assigned.
  5. The scheduler is watching for unassigned pods. For each one it chooses a node and writes that choice (the nodeName field) back via the API server.
  6. The kubelet on each chosen node is watching for pods assigned to it. It tells the runtime to pull the image and start the containers, then reports the pod's status.

Notice the pattern: nobody calls anybody directly. Each component watches the API server for the objects it cares about, does one small job and writes its result back. That decoupling is why you can restart the scheduler without disturbing running pods, and why new controllers can be added without changing the old ones.

The control plane being down does not stop running pods. Containers keep running on their nodes; what you lose is the ability to change anything or to react to failures until the control plane returns.

A model of the API server

The real API server is a large Go program, but its core behaviour is simple: store objects, version them, and let clients watch for changes. The stand-in below implements just that. Every write increments a global version (in real Kubernetes this is the resourceVersion), and watchers register interest in a kind of object.

Python API server with watchers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the output from top to bottom: the controller reacts to the Deployment, the scheduler reacts to each new pod, and the kubelet reacts to the scheduler's update. No component called another. That is the shape of the real system, although the real one adds authentication, validation, optimistic concurrency and a persistent store.

Optimistic concurrency

Many components update the same objects, so the API server must stop them from overwriting each other. Every object carries a resourceVersion. A client that updates an object sends the version it last saw; if the object has changed in between, the update is rejected with a conflict and the client re-reads and retries. This is cheaper than locking, and every controller you write or read about handles conflicts that way.

Python Detecting a conflicting update

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which component is the only one that reads from and writes to etcd?

    All other components talk to the API server, which validates requests and stores objects in etcd.
  2. 2. After you apply a Deployment, who decides which node a new pod runs on?

    The scheduler watches for pods without a node, picks one and records it in the pod's nodeName. The kubelet on that node then starts the containers.
  3. 3. The control plane becomes unreachable for ten minutes. What happens to pods already running on worker nodes?

    Containers are run by the kubelet and runtime on each node. Without the control plane no new decisions are made, but existing workloads continue.
  4. 4. Why does the API server reject an update with a conflict error?

    Optimistic concurrency compares the resourceVersion you send with the current one. A mismatch means someone else updated the object first, and you must re-read and retry.

Summary

  • The control plane (API server, etcd, scheduler, controller manager) decides; worker nodes (kubelet, runtime, kube-proxy) execute.
  • The API server is the single front door and the only component that talks to etcd.
  • Components never call each other; they watch the API server and write results back.
  • A running workload survives a control plane outage, but cannot be changed or healed until it returns.
  • resourceVersion provides optimistic concurrency. The Python models above are stand-ins, not the real code.

Next, get a cluster of your own: Running a Local Cluster.