How to Fine‑Tune Kubernetes Rolling Updates with maxUnavailable & maxSurge

Introduction

When using Kubernetes rolling updates, you may encounter deployments that are either too fast and unstable or too slow and provide a poor experience. This article explains the features that control the update rate.

Meaning

The Deployment controller reduces the replica count of the old ReplicaSet (old_rs) to zero and increases the replica count of the new ReplicaSet (new_rs) to the desired number (replicas). Two parameters control the speed:

maxUnavailable : the maximum number or percentage of replicas that may be unavailable during the update. A smaller value yields a more stable, smoother update.

maxSurge : the maximum number or percentage of extra replicas that can be created above the desired count. A larger value speeds up the update.

Value Range

Both parameters accept either an absolute number or a percentage of the desired replicas.

maxUnavailable: [0, replicas] (or 0%‑100%) – rounded down.

maxSurge: [0, replicas] (or 0%‑100%) – rounded up.

Note: they cannot both be set to zero.

Recommended Configuration

In production we usually set:

maxUnavailable = 0

maxSurge = 1

This “one‑up, one‑down” rule means a new pod must become ready before an old pod is terminated, providing the smoothest possible rollout, though it may feel slow.

Custom Strategy

The Deployment controller enforces the following inequality when adjusting ReplicaSet counts:

<code>(desiredReplicas - maxUnavailable) <= actualReadyReplicas <= (desiredReplicas + maxSurge)</code>

Example

If the desired replica count is 10 and you want at least 80% of pods to be ready, you could set maxUnavailable = 2 and maxSurge = 2 (often kept equal).

<code>8 <= actualReadyReplicas <= 12</code>

This ensures that during the update the number of ready pods always stays within the specified range.

Conclusion

The article clarifies the often‑overlooked Kubernetes rolling‑update controls maxUnavailable and maxSurge, helping you balance stability and speed when releasing new versions. Future posts will explore multi‑ReplicaSet rollouts and the underlying source‑code implementation.