Kubernetes Zero-Downtime Rolling Updates: Readiness, maxSurge, and Graceful Shutdown

A Kubernetes Deployment can replace Pods gradually, but RollingUpdate is not a standalone guarantee of zero failed requests. A safe rollout depends on enough capacity, a meaningful readiness signal, controlled surge and unavailability, application shutdown behavior, load-balancer propagation, and compatibility between old and new versions.

The phrase “zero downtime” is best treated as an engineering objective. The configuration below reduces common gaps, but long-lived connections, cluster shortages, a broken readiness endpoint, or an incompatible database migration can still cause disruption.

Understand the rollout budget

maxUnavailable controls how many desired replicas may be unavailable during the update. maxSurge controls how many additional Pods may be created above the desired replica count. Each accepts an integer or percentage.

If the cluster cannot schedule the surge Pod, a zero-unavailable rollout can stall. That is safer than dropping planned capacity, but it still needs an alert and a capacity response. Resource requests therefore participate directly in rollout design.

A Deployment configured for cautious progression

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  minReadySeconds: 10
  progressDeadlineSeconds: 600
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: api
          image: registry.example.com/team/api:1.4.0
          ports:
            - name: http
              containerPort: 3000
          readinessProbe:
            httpGet:
              path: /health/ready
              port: http
            periodSeconds: 5
            timeoutSeconds: 2
            failureThreshold: 2
  

The readiness endpoint must represent the new Pod's ability to serve normal traffic. A process listening on a port is not enough if routes, configuration, or critical initialization are incomplete. minReadySeconds adds a stability interval after readiness, while progressDeadlineSeconds lets the Deployment report that progression has stalled. The controller continues retrying; monitoring must react to the reported condition.

Graceful termination belongs in the application

During Pod termination, Kubernetes updates endpoint conditions so regular traffic should stop using the terminating endpoint and sends the container's stop signal, normally SIGTERM unless configured otherwise. The application must stop accepting new work, drain what it can, and exit before the grace period ends. At the deadline, remaining processes can be forcefully terminated.

let ready = true;

app.get('/health/ready', (_req, res) => {
  res.sendStatus(ready ? 204 : 503);
});

const server = app.listen(3000);

process.on('SIGTERM', () => {
  ready = false;

  server.close(() => {
    process.exit(0);
  });

  setTimeout(() => {
    process.exit(1);
  }, 25_000).unref();
});
  

This Node.js sketch marks the instance unready and stops accepting new HTTP connections while allowing existing work a bounded drain. Production code should make shutdown idempotent, handle SIGINT where appropriate, close database and queue clients, and define policies for WebSockets, streaming responses, and background jobs. Keep the application deadline shorter than terminationGracePeriodSeconds so Kubernetes has a small safety margin.

A fixed preStop sleep is sometimes used to cover endpoint-propagation delays, but it is not a universal substitute for correct signal handling and observed infrastructure behavior. It also consumes the Pod's termination grace period. Add one only with measured justification.

Traffic can exist beyond a Kubernetes Service. An ingress controller, service mesh, cloud load balancer, client-side cache, or persistent connection may observe endpoint changes on a different schedule. Measure the complete request path during termination instead of assuming endpoint removal is instantaneous everywhere. For long requests, compare the longest accepted processing time with the grace period and define whether work should finish, be checkpointed, or return a retryable response. Graceful shutdown is a product behavior as much as a process signal.

Use compatible release sequencing

Old and new Pods run together during a rolling update. Database changes, events, caches, and APIs must tolerate that overlap. Prefer expand-and-contract migrations: add backward-compatible schema first, deploy code that can work with both forms, migrate data, and remove the old form in a later release. A single destructive migration can defeat perfect Pod rollout settings.

A PodDisruptionBudget protects availability during many voluntary disruptions, such as node maintenance, but it does not replace the Deployment's rolling-update strategy or application readiness. Each mechanism addresses a different controller and failure path.

Observe, pause, and roll back

kubectl rollout status deployment/api --timeout=10m
kubectl rollout history deployment/api
kubectl get deployment api -o wide
kubectl get pods -l app=api -w
kubectl rollout undo deployment/api
  

Watch readiness, available replicas, error rate, latency, saturation, and restart count during the rollout. A successful controller status does not prove that business outcomes are healthy, so combine Kubernetes state with application service-level indicators. Define who can trigger rollback and whether the release includes a migration that makes rollback unsafe.

Common rollout pitfalls

• Using a shallow readiness check that succeeds before the application can serve requests.
• Setting maxUnavailable: 0 without cluster capacity for the surge Pod.
• Ignoring SIGTERM and losing in-flight work at the grace-period deadline.
• Running a backward-incompatible database migration before mixed versions have finished.
• Treating a rollout completion message as proof that user errors did not increase.
• Assuming a disruption budget controls every Deployment update detail.

Build the readiness signal with the Kubernetes probes guide, and verify that the cluster can schedule surge capacity with the requests and limits guide.

Frequently asked questions

Does RollingUpdate guarantee zero downtime?

No. It provides controlled replacement mechanics. Readiness, spare capacity, graceful shutdown, traffic propagation, and version compatibility determine whether users experience errors.

Why can maxUnavailable zero stall?

The controller needs new available capacity before removing old capacity. If the surge Pod cannot schedule or become ready, progression waits rather than intentionally reducing the desired available count.

What does minReadySeconds add?

It requires a newly ready Pod to remain ready without crashing for the configured time before the Deployment considers it available.

Where are the rollout semantics defined?

See the official Kubernetes Deployment documentation and the Pod termination lifecycle.

Validate the complete production model

The linked mock combines rollout budgets with readiness, resources, Docker startup, networking, and storage decisions.

Quick quiz

DevOps

Docker and Kubernetes Production Readiness Mock Test

A practical assessment covering Docker Compose health checks, container DNS and storage, Kubernetes probes, resources, OOM diagnostics, and safer rolling updates.

15 questions25 min

Inline play

Start the trivia-style player right inside the article.

Play inlineView details

Practical takeaway: protect capacity while the new version proves readiness, drain the old version within a measured grace period, and monitor user-facing outcomes throughout the overlap.