Kubernetes Rollout Availability Basics

Kubernetes Rollout Availability Basics is the practice of configuring a Deployment's update strategy so that deploying a new version does not itself become a source of unavailability, covering the maxSurge/maxUnavailable capacity math, stuck-rollout detection via progressDeadlineSeconds, rollback through revision history, and the trade-off between RollingUpdate and Recreate strategies.

The RollingUpdate Strategy

maxSurge and maxUnavailable

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

maxUnavailable bounds how many replicas below the desired count the Deployment may drop to during the rollout, while maxSurge bounds how many replicas above the desired count it may temporarily create; setting maxUnavailable: 0 guarantees full capacity is maintained throughout the rollout, relying on maxSurge to provide the temporary extra capacity needed to bring new replicas up before removing old ones.

The Trade-off Between the Two Parameters

rollingUpdate:
  maxSurge: 25%
  maxUnavailable: 25%

Expressed as percentages (the default for Deployment), maxSurge and maxUnavailable together determine rollout speed versus resource headroom required: a larger maxSurge completes the rollout faster by replacing more replicas simultaneously but requires more spare cluster capacity to schedule the surge pods, while maxUnavailable: 0 maximizes availability guarantees at the cost of requiring maxSurge to be large enough to make meaningful progress each step.

Detecting a Stuck Rollout

progressDeadlineSeconds

spec:
  progressDeadlineSeconds: 600

If a rollout makes no progress (no new replica becomes ready) for longer than progressDeadlineSeconds, the Deployment controller marks the rollout as having a ProgressDeadlineExceeded condition, a critical signal that a new version is stuck, most commonly because its readiness probe never succeeds, distinct from a rollout still actively, if slowly, progressing.

kubectl rollout status deployment/web
kubectl get deployment web -o jsonpath='{.status.conditions[?(@.type=="Progressing")].reason}'

Why This Matters for Availability

A stuck rollout with maxUnavailable: 0 does not itself reduce availability, since old replicas remain in place until new ones prove ready, but it does leave the deployment indefinitely in a mixed-version, non-terminal state unless detected and addressed, making progressDeadlineSeconds the mechanism that surfaces this condition for automated or human intervention rather than leaving a stalled rollout silently unnoticed.

Rollback Through Revision History

Reverting to a Prior ReplicaSet

kubectl rollout history deployment/web
kubectl rollout undo deployment/web --to-revision=3

A Deployment retains prior ReplicaSet revisions (up to spec.revisionHistoryLimit), and kubectl rollout undo reverts to a prior revision using the exact same rolling update mechanics as a forward rollout, meaning a rollback is itself subject to the same maxSurge/maxUnavailable availability guarantees as any other update, not an instant, disruptive swap.

spec:
  revisionHistoryLimit: 10

Recreate Strategy Trade-off

When Full Downtime Is Accepted or Required

spec:
  strategy:
    type: Recreate

Recreate terminates every existing replica before creating any new one, guaranteeing no two versions ever run simultaneously but producing a period of complete unavailability during the transition; this is appropriate specifically when running two versions concurrently would cause incorrect behavior (an incompatible shared schema migration, a singleton resource that cannot have two active holders) and availability during the deployment window is explicitly deprioritized in favor of correctness.

Pausing a Rollout for Manual Verification

Controlled, Staged Progression

kubectl rollout pause deployment/web
kubectl set image deployment/web web=myapp:2.0.0
# verify a limited number of new replicas
kubectl rollout resume deployment/web

Pausing a Deployment before resuming lets an operator apply a change, observe a limited initial batch of new replicas, and manually confirm health before allowing the rollout to continue, a manual canary-style verification step available directly through the Deployment primitive without requiring a separate progressive delivery controller.

Interaction With Pod Disruption Budgets

Rollouts Are Not Constrained by PDBs on Their Own Workload

A PodDisruptionBudget protects against voluntary eviction (node drains, cluster scaling) but does not itself constrain a Deployment's own rolling update of its own pods; availability during a rollout is governed entirely by maxSurge/maxUnavailable, meaning both mechanisms must be configured consistently, since a PodDisruptionBudget alone provides no rollout-time availability guarantee.

Relationship to Replica Reliability and the Reliability Model

Rollout availability basics apply the same replica-count reconciliation mechanics described under replica reliability to the specific, temporary period during which two ReplicaSet generations coexist, and it operationalizes the broader reliability model's preference for graceful, bounded degradation over binary availability by making the exact amount of tolerable capacity reduction during a voluntary code change an explicit, tunable parameter rather than an unmanaged side effect of deployment.