The Runtime Theory
SystemInternalsdistributed systems

Trace a Kubernetes Deployment Reconciliation

Follow a desired replica count through the API server, controllers, scheduler, node agent, runtime, and readiness checks.

The Runtime Theory Team1 min read05 steps

layer stack

System

HWHardware
KKernel
RTRuntime
APPApplication
SYSSystem
CLIClient
NETNetwork
TLSCrypto
SRVServer

adjacent altitudes in this subsystem are still being traced

trace spine

  1. 01 Persist the requested Deployment state
  2. 02 Controller creates or updates a ReplicaSet
  3. 03 Scheduler assigns pending Pods to nodes
  4. 04 Node agent asks the runtime to start containers
  5. 05 Readiness changes traffic eligibility
▸ On this page

Suppose a Deployment is changed from two replicas to three. Kubernetes does not run one synchronous command that creates a complete application. Controllers observe desired state and repeatedly reconcile the objects they own.

1. Store intent

The API server authenticates and validates the request, then stores the Deployment object. The API response confirms that the object was accepted; it does not guarantee that a new Pod is already running or ready.

2. Reconcile the ReplicaSet

The Deployment controller compares the desired pod template and replica count with observed ReplicaSets. It creates or updates a ReplicaSet that will manage the requested number of Pods. Controllers may retry when dependencies are temporarily unavailable.

3. Schedule and start

The scheduler selects a node for each unassigned Pod based on constraints and available resources. A node agent observes the assignment, prepares storage and networking, and asks the container runtime to pull the image if needed and start containers.

4. Report readiness

The kubelet reports Pod status and probe results. A Service implementation updates the set of endpoints eligible for traffic according to readiness and networking configuration. The actual transition can take time or fail at image pull, placement, startup, or health checks.

Kubernetes documents the Deployment controller and Pod lifecycle; implementation details vary across cluster versions and networking plugins.

Not started

Sign in to save your learning progress.

Sign in to save