Unavailable replicas and maxUnavailable — the rolling update guard

Unavailable replicas is the Deployment losing replicas during a rolling update. The maxUnavailable surge and the PDB interaction are the diagnostic. The discipline is to verify the math before the rollout.

The rolling update math

A rolling update replaces old Pods with new Pods in waves. The math is governed by two parameters:

• maxUnavailable — the maximum number (or percentage) of Pods that can be unavailable during the update.
• maxSurge — the maximum number (or percentage) of Pods that can be created above the desired count.

flowchart TD
    A[Old ReplicaSet: 6 replicas] --> B[maxSurge: 2]
    B --> C[New ReplicaSet: 2 replicas]
    C --> D{New Pods Ready?}
    D -->|Yes| E[Terminate 2 old Pods]
    E --> F[Old: 4, New: 2]
    F --> G{Capacity OK?}
    G -->|Yes| H[New ReplicaSet: +2]
    H --> I[Old: 4, New: 4]
    I --> J{New Pods Ready?}
    J -->|Yes| K[Terminate 2 old Pods]
    K --> L[Old: 2, New: 4]
    L --> M[Continue until Old: 0, New: 6]

The math is: total replicas during the rollout = desired + maxSurge. At each step, the controller:

1. Creates maxSurge new Pods.
2. Waits for the new Pods to be Ready.
3. Terminates maxSurge old Pods.
4. Repeats until the old ReplicaSet has 0 replicas.

The diagnostic

A Deployment with unavailable replicas is the controller either:

• Blocked by maxUnavailable (the new Pods cannot replace the old Pods because the new Pods are not Ready).
• Blocked by the PDB (the drain is waiting for the PDB to permit the eviction).

A real kubectl describe deployment for a Deployment with unavailable replicas:

Name:                   billing
Namespace:              prod
CreationTimestamp:      Fri, 16 Aug 2026 04:00:00 +0000
Labels:                 app=billing
Annotations:            deployment.kubernetes.io/revision: 4
Selector:               app=billing
Replicas:               6 desired | 4 updated | 8 total | 4 available | 4 unavailable
StrategyType:           RollingUpdate
MinReadySeconds:        0
RollingUpdateStrategy:  25% max unavailable, 25% max surge
Conditions:
  Type           Status  Reason
  ----           ------  ------
  Available      False   MinimumReplicasUnavailable
  Progressing    True    NewReplicaSetCreated
OldReplicaSets:  <none>
NewReplicaSet:   billing-7d8f (4/6 replicas created)
Events:
  Type    Reason              Age   From                   Message
  ----    ------              ----  ----                   -------
  Normal  ScalingReplicaSet   4m    deployment-controller  Scaled up replica set billing-7d8f to 5
  Normal  ScalingReplicaSet   4m    deployment-controller  Scaled down replica set billing-7d8e to 4

The diagnostic is:

• 4 unavailable — 4 Pods are not Ready.
• 25% max unavailable, 25% max surge — the rollout is configured to allow 1 unavailable at a time (25% of 6).
• ScalingReplicaSet events show the progression.

The remediation is to identify why the new Pods are not Ready.

The PDB interaction

A PodDisruptionBudget (PDB) can block the rollout if the PDB is too restrictive. The PDB says “at most N unavailable” or “at least N available.” The Deployment’s maxUnavailable must be ≤ the PDB’s allowance.

flowchart TD
    A[Deployment rollout] --> B{PDB permits?}
    B -->|Yes| C[Continue]
    B -->|No| D[Stuck]
    D --> E[Increase maxUnavailable or scale PDB]

The diagnostic is the PDB:

kubectl get pdb -n prod -o yaml

The PDB’s minAvailable (or maxUnavailable) is the allowance. The Deployment’s maxUnavailable must be ≤ the PDB’s allowance.

Common causes of unavailable replicas

• New Pods not Ready. The new Pods are failing the readiness probe (see Part CXIX-04).
• PDB too restrictive. The PDB’s minAvailable is too high; the rollout cannot evict enough old Pods.
• Resource exhaustion. The cluster does not have enough capacity for the new Pods (see Part CXIX-01).
• maxSurge=0. The Deployment is configured with maxSurge=0, so the new Pods cannot be created until the old Pods are terminated.

Production discipline

Unavailable replicas is the controller’s hypothesis. The discipline is to verify the math before the rollout, monitor during the rollout, and adjust if the rollout is stuck. The cluster does not sit in a half-converged state.

• Verify the rolling update math before the rollout. The math is: maxUnavailable × replicas.
• Verify the PDB’s allowance. The PDB’s allowance must be ≥ the Deployment’s maxUnavailable.
• Verify the cluster’s capacity. The cluster’s capacity must be ≥ the desired replicas + maxSurge.

Quiz