Understanding maxUnavailable and maxSurge in Kubernetes Rolling Updates

Kubernetes (k8s) uses the Deployment controller to perform rolling updates, gradually replacing old Pods with new ones. Two key parameters, maxUnavailable and maxSurge , control how many Pods may be unavailable or exceed the desired replica count during the update, directly affecting stability and speed.

Parameter definitions : maxUnavailable specifies the maximum number of Pods that can be unavailable during an update (absolute number or percentage, default 25%). maxSurge defines the maximum number of extra Pods that can be created above the desired replica count (also absolute or percentage, default 25%). Together they ensure that the number of ready Pods never falls below desired – maxUnavailable and that total Pods never exceed desired + maxSurge .

Practical cases illustrate how different settings influence the update process:

Case 1 – Using default values (25% each) with 20 replicas shows the classic two‑step process of scaling up the new ReplicaSet and scaling down the old one.

Case 2 – Raising maxUnavailable to 75% speeds up the update by allowing more old Pods to be removed early, at the cost of reduced availability.

Case 3 – Increasing maxSurge to 75% while keeping maxUnavailable at 25% accelerates new Pod creation but requires additional cluster resources.

Case 4 – Setting both parameters to 75% does not yield a “double win” because the total number of Pods cannot exceed the replica target; the benefit of a larger maxSurge is limited by the replica count.

Case 5 – Updating from 5 to 20 replicas demonstrates that the controller first scales the old ReplicaSet up to the final replica count before adding extra Pods, preventing service outage.

Case 6 – Reducing replicas from 20 to 5 while keeping defaults shows that a large maxUnavailable can cause many old Pods to be terminated at once, potentially impacting stability; a staged approach (first adjust resources, then scale down) is recommended.

Best‑practice recommendations include testing parameter settings before production, lowering maxUnavailable during peak traffic, keeping maxSurge modest to avoid resource pressure, and continuously monitoring update performance to fine‑tune the values.

Properly configuring maxUnavailable and maxSurge enables smooth rolling updates, maintains application availability, and optimizes resource utilization in Kubernetes environments.