Deployments, ReplicaSets, and Rollout Semantics

Doctrine

A Deployment is not ‘run N pods’. It is a controller that manages ReplicaSets and measures progress against availability gates. When the gates are wrong, rollouts are either unsafe or impossible.

Kubblai doctrine: you don’t earn reliable rollouts through hope. You earn them through honest readiness, capacity headroom, and reversible change.

• Readiness is an availability gate; treat it as a contract.
• maxSurge/maxUnavailable are safety posture knobs, not defaults.
• ReplicaSets are history. Keep enough history to undo, not so much that you lose clarity.

ReplicaSet history and revision reality

Deployments produce ReplicaSets. Each ReplicaSet represents a pod template hash and is the unit of rollback. If you mutate objects outside the Deployment’s ownership, you can create history that cannot be trusted.

In practice, rollbacks are not ‘go back in time’. They are a new rollout toward an older template—with today’s environment, today’s dependencies, and today’s policy.

Progress gates and common stalls

Progress is blocked when new pods don’t become Ready, when placement is impossible, or when strategy posture leaves no headroom to replace old pods.

When rollouts stall, operators often thrash: re-apply YAML, restart controllers, or override readiness. These moves destroy attribution.

• If readiness is wrong, the rollout should stall. Fix readiness or the service.
• If capacity is insufficient, add capacity or reduce requests before you expand.
• If maxUnavailable is zero with no surge, you have defined a deadlock under scarcity.

What to inspect first

Let the controller speak. Read conditions and ReplicaSet state before you edit.

kubectl rollout status deploy/<name> -n <ns>
kubectl describe deploy/<name> -n <ns>
kubectl get rs -n <ns> -o wide
kubectl get pods -n <ns> -l app=<label> -o wide

Field notes

The most expensive rollouts are the ones that ‘mostly work’. Partial readiness flapping and slow startup can pass casual checks while breaking SLOs. Your readiness endpoint must reflect serving ability under real load, not under quiet conditions.

If you want safe rollouts, you must budget for headroom. Zero headroom is a policy choice.