Kubernetes Deployment Controller

Kubernetes Deployment Controller is the control loop responsible for managing the ReplicaSets that back a Deployment object, translating declarative updates to a Pod template into a sequence of ReplicaSet creations and scaling operations that together implement rolling updates, rollbacks, and pause and resume behavior for stateless workloads. It is the layer above ReplicaSet management, adding revision history and rollout orchestration that ReplicaSets alone do not provide.

Managing ReplicaSets, Not Pods Directly

Indirection Through an Intermediate Object

A Deployment never creates or deletes Pods itself; it creates and scales ReplicaSets, each stamped with a hash of a specific Pod template revision, and relies on those ReplicaSets to perform actual Pod creation. This indirection is what makes rollback possible: an old ReplicaSet from a previous revision can simply be scaled back up rather than needing to reconstruct a prior Pod template from scratch.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deployment-controller-example
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: app
          image: registry.example.com/app:2.0.0

Revision History

Tracking Past ReplicaSets

The Deployment controller retains a configurable number of old ReplicaSets, controlled by spec.revisionHistoryLimit, scaled to zero replicas but not deleted, so that a rollback can be performed by simply scaling a previous ReplicaSet back up rather than recreating it.

spec:
  revisionHistoryLimit: 10

kubectl rollout history deployment/deployment-controller-example
kubectl rollout undo deployment/deployment-controller-example --to-revision=3

Rolling Update Orchestration

maxSurge and maxUnavailable

When the Pod template changes, the controller creates a new ReplicaSet and gradually shifts replica counts between it and the old ReplicaSet, bounded by maxSurge (how many Pods above the desired count are allowed temporarily) and maxUnavailable (how many Pods below the desired count are tolerated during the transition).

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%

Progress Monitoring

The controller tracks rollout progress against progressDeadlineSeconds, marking the Deployment's Progressing condition as failed if new Pods have not become available within that window, which surfaces stuck rollouts, commonly caused by a broken image or failing readiness probe, as an explicit condition rather than a silent stall.

kubectl rollout status deployment/deployment-controller-example

Pause and Resume

Batching Multiple Changes

A Deployment can be paused via spec.paused: true, during which the controller stops creating new ReplicaSets or scaling existing ones in response to template changes, allowing multiple edits to be batched and applied together as a single rollout once resumed.

kubectl rollout pause deployment/deployment-controller-example
kubectl rollout resume deployment/deployment-controller-example

Recreate Strategy as an Alternative

All-at-Once Replacement

For workloads that cannot tolerate two versions running simultaneously, the Deployment controller also supports a Recreate strategy, terminating every Pod in the old ReplicaSet before creating any Pod in the new one, trading availability during the transition for strict version isolation.

spec:
  strategy:
    type: Recreate

Deployment Controller Diagram

This layered design, Deployment orchestrating ReplicaSets, which in turn own Pods, is what allows a single declarative image update to trigger a fully automated, gradually rolled out change across a running service without any manual coordination of individual Pods.