How Kubernetes Works — desired state to running workloads
How Kubernetes works, shown on an interactive canvas: manifests, the control plane, scheduling, and the reconciliation loop that keeps workloads running.
Kubernetes runs containerised applications by continuously reconciling: you declare the desired state, and the control plane and worker nodes work to make the cluster match it.
How Kubernetes Works — desired state to running workloads
The interactive FlowJam canvas for this explanation — every lane, row and arrow above is a real QueryChart diagram you can open and edit.
How to read this visual
- Read the four columns left to right: Declare, Schedule, Run, Maintain.
- The control plane rows (top) decide; the worker node rows (bottom) do. Arrows from top to bottom are commands; the loop back up from "Pod is healthy?" is the reconciliation cycle.
- The desired state in the manifest is the source of truth — every other box exists to move reality toward it.
Declaring the desired state
"kubectl apply a desired-state manifest" is how everything starts: the developer describes the target — "3 replicas of the API, image v2.1, port 8080" — and submits it. "API server stores the desired state in etcd" is the commit point: the control plane's API server is the front door, and etcd is the cluster's source of truth. Everything that follows is a consequence of this one write.
Scheduling
"Scheduler watches and picks nodes for the pods" and "Scheduler assigns each pod to a healthy node" are the control plane choosing where work runs. The scheduler considers each node's resources and constraints and places the pod on the best candidate — the developer does not choose machines, only the desired state.
Running on the workers
"kubelet on the node pulls images and starts containers" is the worker half of the arrangement: the kubelet is the control plane's agent on each node, talking to the container runtime to start the assigned pods and report health back. "A Service routes traffic to the running pods" adds the stable network entry point — pods come and go, but the Service name does not change.
Maintaining the state
"Controller reconciles — restarts failures, scales replicas" is the feedback loop, and "Pod is healthy?" is its probe — liveness and readiness checks decide whether a pod is replaced (the "No" branch loops back into reconciliation) or kept. "Deployment stays at the desired state" is the terminal state: not a finished job, but a running system that matches its manifest.
Key relationships and takeaways
- Kubernetes is declarative: you state the target, not the steps, and the system does the rest.
- The control plane decides, the kubelet executes — nothing runs without the desired state in etcd.
- Reconciliation is the loop: compare, apply the difference, repeat, forever.
- Probes decide health, and health decides replacement — a failing pod is restarted without human action.
- Kubernetes orchestrates the containers Docker packages, which is why the two visuals connect.
When to use this visual
- Explaining the control plane versus worker distinction to a team new to Kubernetes.
- Teaching the declarative model before someone writes their first Deployment and Service manifests.
- Grounding a conversation about self-healing — what Kubernetes fixes automatically and what still needs an operator.
How it works
Annotate the manifest you actually run
On the apply step, add notes about your real Deployment and Service — replica counts, images, ports — so the diagram reflects your cluster.
Add the network layer
Insert an Ingress box between the Service and the users, and note how your cluster exposes traffic, since that is the part most teams customise first.
Show your scaling rules
Extend the reconcile step with a Horizontal Pod Autoscaler branch that scales replicas on CPU or custom metrics, ending in its own state.
Add the failure and storage paths
Include persistent volumes for stateful workloads and the anti-affinity rules you use, each with a comment explaining why.
Frequently asked questions
What is Kubernetes in simple terms?
Kubernetes is a system that runs containerised applications across a cluster of machines and keeps them running. You tell it what you want — how many copies of each application, which image, which ports — and it schedules the work onto machines, restarts failures, scales up and down, and routes traffic. The visual captures that as declare, schedule, run and maintain.
What is the control plane in Kubernetes?
The control plane is the set of components that make decisions about the cluster: the API server that accepts your manifests, etcd that stores the desired state, the scheduler that places pods, and the controllers that reconcile reality toward the desired state. It is the brain. The worker nodes are the muscle — each runs a kubelet that starts and monitors the pods assigned to it.
What does 'declarative' mean in Kubernetes?
It means you describe the target state instead of issuing commands to reach it. You apply a manifest saying "run three replicas"; Kubernetes figures out the steps and keeps taking them whenever reality drifts. If a pod dies, the controller creates a replacement to return to three — no human reruns a command. The manifest is the source of truth, and reconciliation is the mechanism.
How does Kubernetes keep applications healthy?
Through probes and the reconciliation loop. Liveness probes tell Kubernetes whether a container is alive — a failing liveness probe restarts it. Readiness probes tell it whether a pod can serve traffic — a failing readiness probe removes it from the Service. The controller compares the running state to the desired state and applies the difference continuously, which is the loop the "Pod is healthy?" decision in the visual represents.
Edit this visual in QueryChart (FlowJam)
Open this exact Kubernetes canvas as your own chart, rename the components to your cluster, and annotate your workloads.