ReviewsLion

Reviews of online services and software

Kubernetes RollingUpdate Strategy Explained: maxSurge vs maxUnavailable with Deployment Examples

Kubernetes Deployments are designed to help applications change safely while remaining available. When a new container image, configuration, or pod template is applied, the Deployment controller usually performs a RollingUpdate, replacing old Pods with new ones gradually instead of stopping everything at once.

TLDR: In a Kubernetes Deployment, maxSurge controls how many extra Pods may be created above the desired replica count during an update. maxUnavailable controls how many desired Pods may be unavailable during that same update. Together, they define the speed and safety of a rolling release, balancing resource usage against application availability.

Table of contents:

What the RollingUpdate Strategy Does

A RollingUpdate strategy updates Pods in small steps. Rather than deleting all old Pods and then creating new ones, Kubernetes creates some new Pods, waits for them to become ready, and then removes some old Pods. This process continues until every old Pod has been replaced.

This is the default strategy for Kubernetes Deployments because it supports zero downtime or near-zero downtime releases when applications are configured correctly. It is especially useful for stateless web services, APIs, workers, and microservices that can run multiple replicas at the same time.

A Deployment using RollingUpdate has two important fields under strategy.rollingUpdate:

  • maxSurge: The maximum number of extra Pods Kubernetes can run temporarily during the update.
  • maxUnavailable: The maximum number of Pods that can be unavailable during the update.

Understanding maxSurge

maxSurge defines how many Pods may exist above the desired replica count while the rollout is in progress. It allows Kubernetes to create new Pods before terminating old ones.

For example, if a Deployment has replicas: 4 and maxSurge: 1, Kubernetes may temporarily run up to 5 Pods. The extra Pod gives the system room to start a new version before removing an old version.

maxSurge can be specified as either:

  • An absolute number, such as 1 or 2
  • A percentage, such as 25% or 50%

If a percentage is used, Kubernetes calculates the value based on the desired replica count and rounds it up. For example, 25% of 4 replicas equals 1, while 25% of 5 replicas is rounded up to 2.

Understanding maxUnavailable

maxUnavailable defines how many desired Pods may be unavailable during a rollout. A Pod is considered unavailable if it is not running, not ready, or failing readiness checks.

For example, if a Deployment has replicas: 4 and maxUnavailable: 1, Kubernetes must keep at least 3 available Pods during the update. It may remove one old Pod before or while creating a new one, but it cannot reduce availability below the configured limit.

Like maxSurge, maxUnavailable can be configured as either a number or a percentage. If a percentage is used, Kubernetes rounds it down. For example, 25% of 5 replicas becomes 1.

How maxSurge and maxUnavailable Work Together

The two values work as a pair. maxSurge decides how far Kubernetes can scale up temporarily, while maxUnavailable decides how far it can scale down safely. Their combination controls the rollout pattern.

Consider a Deployment with 4 replicas:

  • maxSurge: 1 allows up to 5 total Pods during the update.
  • maxUnavailable: 1 allows at least 3 Pods to remain available.

In this case, Kubernetes may create one new Pod, wait for it to become ready, and then terminate one old Pod. This repeats until all Pods run the new version.

Deployment Example with maxSurge and maxUnavailable

The following example shows a Deployment with 4 replicas and a controlled rolling update strategy:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
spec:
  replicas: 4
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1
  selector:
    matchLabels:
      app: webapp
  template:
    metadata:
      labels:
        app: webapp
    spec:
      containers:
        - name: webapp
          image: example/webapp:2.0
          ports:
            - containerPort: 8080

With this configuration, Kubernetes can temporarily run 5 Pods and can allow 1 Pod to be unavailable. This is a balanced setup for many services because it keeps most replicas available while avoiding a large temporary resource increase.

Example Using Percentages

Percentages are useful when Deployments scale to different replica counts in different environments. For example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 8
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: example/api:3.1
          ports:
            - containerPort: 3000

For 8 replicas, maxSurge: 25% allows 2 extra Pods, so the Deployment may temporarily run 10 Pods. maxUnavailable: 25% allows 2 Pods to be unavailable, so Kubernetes must keep at least 6 Pods available.

Choosing the Right Values

The best values depend on the application’s traffic patterns, startup time, resource requirements, and tolerance for reduced capacity.

  • High availability services: A common choice is maxSurge: 1 or 25% and maxUnavailable: 0. This ensures old Pods are not removed until new Pods are ready.
  • Resource constrained clusters: A lower maxSurge may be preferred because extra Pods require CPU, memory, and scheduling capacity.
  • Fast internal workloads: Higher values may speed up rollouts if temporary unavailability is acceptable.
  • Slow starting applications: A conservative maxUnavailable helps avoid reducing available capacity while Pods are still becoming ready.

A very safe configuration is:

rollingUpdate:
  maxSurge: 1
  maxUnavailable: 0

This tells Kubernetes to create one new Pod above the desired count and only remove old Pods after the new Pod is ready. The tradeoff is that the cluster must have enough spare resources to schedule the surge Pod.

Important Role of Readiness Probes

Rolling updates depend heavily on readiness probes. A new Pod should not receive traffic until it is truly ready to handle requests. If readiness probes are missing or too weak, Kubernetes may count a Pod as available before the application is actually prepared.

A good readiness probe checks meaningful application health, such as database connectivity, dependency availability, or a dedicated health endpoint. This makes maxUnavailable more reliable because Kubernetes has a better signal for whether the rollout can continue safely.

Common Misconfigurations

Several mistakes can make rolling updates unsafe or slow:

  • Setting maxUnavailable too high: This can reduce capacity quickly and cause user-facing errors during deployment.
  • Setting maxSurge too high: This can overload nodes or cause Pods to remain pending because of insufficient resources.
  • Using no readiness probe: Kubernetes may send traffic to Pods that are not truly ready.
  • Ignoring application shutdown behavior: Pods need time to finish requests before termination. A suitable terminationGracePeriodSeconds and graceful shutdown logic are important.

maxSurge vs maxUnavailable in Simple Terms

maxSurge answers the question: How many extra Pods may run during the update?

maxUnavailable answers the question: How many Pods may be unavailable while the update is happening?

If the goal is maximum availability, the Deployment should usually use a low maxUnavailable, often 0. If the goal is faster rollouts, higher values for maxSurge and maxUnavailable may be acceptable, provided the cluster and application can handle them.

FAQ

What is the default RollingUpdate configuration in Kubernetes?

For Deployments, Kubernetes defaults to maxSurge: 25% and maxUnavailable: 25% when no custom values are specified.

Can maxSurge and maxUnavailable both be zero?

No. Kubernetes requires at least one of them to be greater than zero. Otherwise, it would have no way to either add new Pods or remove old ones during the rollout.

Does maxSurge require extra cluster resources?

Yes. Any surge Pods run in addition to the desired replica count, so the cluster must have enough CPU, memory, and scheduling capacity.

Which setting is better for zero downtime?

A common zero-downtime-friendly setup is maxSurge: 1 and maxUnavailable: 0, combined with strong readiness probes and graceful shutdown handling.

Does RollingUpdate work for stateful applications?

Deployments can update Pods for many workloads, but stateful applications often require more careful handling. Kubernetes StatefulSet may be more appropriate when stable identity, ordered rollout, or persistent storage behavior is required.

Related Posts: