Kubernetes Architecture Diagram
Two paths drawn separately — how a request reaches a container, and how a manifest becomes a running pod — plus the reconciliation loop that explains most of Kubernetes' surprising behaviour.
SVG. No sign-up, no email.
Kubernetes confuses people because two completely different things are usually drawn as one picture: the path a request takes to reach your code, and the path a manifest takes to become a running container. They share almost nothing. Separating them removes most of the mystery.
The request path#
A request arrives at Ingress, which routes by hostname and path. Ingress sends it to a Service — a stable virtual IP that exists precisely because pods do not. The Service forwards to one of its endpoints, and this is the shaded box for a reason.
A pod is only an endpoint when its readiness probe passes. Get that probe wrong and you get the two classic failures. No readiness probe, and traffic arrives before the process can serve it, so a rolling update drops requests. A readiness probe that only checks the process is alive, and a pod that has lost its database stays in rotation, failing every request it receives.
Readiness and liveness are different questions. Readiness asks should I receive traffic right now. Liveness asks should I be killed and restarted. A liveness probe pointed at a dependency turns a slow database into a restart loop across every pod at once.
The deployment path#
You submit a manifest describing desired state. The API server validates and stores it. The scheduler decides which node it goes on — the other shaded box, because a pod stuck in Pending is nearly always a scheduling decision that could not be made: no node has the requested CPU or memory, a taint has not been tolerated, or the requests were copied from an example and are far larger than the workload needs.
The kubelet on the chosen node then makes it real, pulls the image and starts the container. Note what the API server does not do: it never runs anything. It records intent. Everything else is a controller reacting to that record.
The reconciliation loop#
This is the part worth internalising, because it explains behaviour that otherwise looks like magic or malice.
Kubernetes continuously compares desired state to observed state and acts to close the gap. Nothing is a one-off command. Delete a pod that belongs to a Deployment and it comes back — not because deletion failed, but because the desired state still says three replicas and something has to make that true again. Change a resource by hand and it is reverted, because the stored manifest is the authority and your change is a difference to be corrected.
The practical consequence: change the declaration, not the cluster. Any fix applied directly is temporary by design, and the loop will undo it at a moment nobody chose.
Using this diagram#
Trace an outage along the right path. If users get errors but pods are healthy, you are in the request lane — probes, endpoints, Service selectors. If nothing is running at all, you are in the deployment lane — scheduling, images, resource requests. Teams lose hours by debugging the wrong lane, and the two lanes have almost no failure modes in common.