A Map of the Kubernetes Machinery
Summary
- Kubernetes is a set of independent control loops that share one database and one API, not a monolithic scheduler.
- Insight: Every component is a client of the API server; none talk to etcd or to each other directly (except the API server itself).
- Key Concepts: API server (front door), etcd (state store), scheduler (placement), controller-manager (reconciliation), kubelet (node agent), kube-proxy / CNI (networking).
- When to Use: Read this first to build a mental map before studying any single component in depth.
- Limitations/Trade-offs: This is orientation, not operations - each box here hides real failure modes and tuning knobs.
- Related Topics: The reconciliation loop, control plane internals, etcd and Raft.
Foundations
Kubernetes looks like one system but behaves like a committee of small programs.
Each program watches the shared state, notices work it owns, and does a little of it.
There is no central brain issuing commands. There is only a shared record of intent and many workers reacting to it.
That shared record lives in etcd, a consistent key-value store. Only the API server reads and writes it.
The API server (kube-apiserver) is the single front door. Every other component - kubelets, controllers, the scheduler, kubectl, operators - is just an API client.
This hub-and-spoke shape is the most important fact about the architecture. Components do not call each other. They read and write objects through the API, and other components notice.
Mechanics & Interactions
Follow one Deployment from creation to running Pods.
You run kubectl apply. The API server authenticates you, runs admission checks, validates the object, and persists a Deployment into etcd.
The deployment controller (inside kube-controller-manager) is watching Deployments. It sees the new one and creates a ReplicaSet to match the desired replica count.
The replicaset controller sees the ReplicaSet and creates the required number of Pod objects. These Pods have no node assigned yet.
The scheduler watches for Pods with an empty spec.nodeName. For each one it filters feasible nodes, scores them, and writes the chosen node back into the Pod via a binding.
On that node, the kubelet is watching for Pods bound to itself. It pulls images and asks the container runtime to start containers.
The kubelet does not run containers directly. It calls containerd over the Container Runtime Interface (CRI), and containerd manages the container processes.
Meanwhile kube-proxy (or a CNI plugin in proxy-replacement mode) programs the node so Service traffic reaches the new Pods, and the CNI plugin gives each Pod its IP.
Notice the pattern: at no point did one component command another. Each wrote an object; the next reacted.
# Watch the machinery act in real time
kubectl get events --watch
kubectl get pods -o wide --watchAdvanced Considerations & Applications
The control plane splits into three long-running processes plus etcd.
kube-apiserver is stateless and horizontally scalable - run several behind a load balancer. It is the only component that touches etcd.
kube-controller-manager bundles dozens of controllers (deployment, replicaset, node, job, endpoints, and more) into one binary. They elect a single active leader so only one instance acts at a time.
kube-scheduler also runs with leader election. Its only job is placement: pick a node for each unscheduled Pod.
cloud-controller-manager isolates provider-specific logic (load balancers, node lifecycle, routes) so the core stays cloud-agnostic.
On every node sit two agents: the kubelet (owns the node's Pods and reports status) and kube-proxy or an eBPF dataplane (owns Service networking).
Add-ons layer on top as ordinary workloads: CoreDNS for cluster DNS, a CNI plugin for Pod networking, an ingress or Gateway controller, and metrics-server.
This separation is why Kubernetes degrades gracefully. If the scheduler dies, running Pods keep running - only new placement stops. If the API server is down, kubelets keep the current Pods alive from their last known state.
Common Misconceptions
"The master node controls the worker nodes." No component pushes commands to nodes. Kubelets pull their assigned work from the API server.
"Docker runs my Pods." Docker builds images and runs Compose in dev; on nodes, containerd (via CRI) runs Pods. The dockershim was removed in 1.24.
"etcd is a general database I can query for my app." etcd stores cluster state only, and only the API server should touch it. Point your app at the API, or better, don't couple to it at all.
"The scheduler starts containers." The scheduler only writes a node name onto the Pod. The kubelet on that node starts the containers.
"Losing the control plane means losing my apps." Existing Pods keep running during a control-plane outage. You just lose the ability to make changes.
FAQs
What is the single most important component? The API server. It is the only gateway to state and the coordination point for everything else.
Do worker nodes talk to etcd? No. Only the API server reads and writes etcd. Nodes talk to the API server.
Where do custom resources and operators fit? Operators are just more controllers running the same watch-reconcile loop against Custom Resource Definitions you register with the API server.
Is the control plane a single point of failure? It is run redundantly - multiple API servers, an odd-sized etcd cluster, and leader-elected controllers - so it tolerates node loss.
Why does everything feel asynchronous? Because it is. Each component reacts to state changes independently, so effects ripple through the system rather than happening in one transaction.
Related
- Kubernetes Internals Basics
- The Reconciliation Loop Explained
- Control Plane Internals
- etcd, Raft & Cluster State
- Watches, Informers & the List-Watch Pattern
- Why Kubernetes Is a Distributed System
Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).