Rolling Updates with Deployment

You've built a Deployment, and your app is running smoothly. But now you need to push a new version — new code, updated config, or a different image tag. A simple kubectl delete followed by kubectl create would cause downtime, and your users would see errors. That's exactly the problem this lesson solves: you'll learn how to perform a rolling update with Deployment, the safe, zero-downtime way to update running applications in Kubernetes.

The problem this lesson solves

Updating a live application is risky. If you stop all old Pods before starting new ones, your users face a gap — 503 errors, dropped connections, angry customers. If you start all new Pods first, you might run out of cluster resources or accidentally serve traffic from both old and new versions simultaneously (which can cause data corruption or API mismatches).

Kubernetes Deployments exist precisely to manage this tension. A rolling update increments the new version gradually, replacing old Pods one by one (or in batches) while verifying each new Pod is healthy before moving to the next. This means:

• Zero downtime — users are always served by a working Pod.
• Controlled rollout speed — you can pause, resume, or roll back if something goes wrong.
• Automatic health checking — Kubernetes waits for readiness probes before replacing the next Pod.

The pain this lesson solves: you go from "fear of updating" to "confident, automated rollouts."

Core concept / mental model

Think of a Deployment as a fleet manager for immutable Pods. You tell it the desired state (your YAML definition), and it drives the current state toward that desired state. During an update, the Deployment creates a ReplicaSet for the new version and gradually scales it up while scaling the old ReplicaSet down to zero.

Pro tip: A ReplicaSet is the underlying controller that ensures a specified number of identical Pod replicas are running. A Deployment wraps a ReplicaSet with update logic — like rolling updates and rollbacks.

The mental model: imagine a line of production workers (Pods) on a conveyor belt. To update their tools, you don't stop the whole line. Instead, you bring in a new worker with new tools (new ReplicaSet), verify they work, then pull out one old worker at a time. The line never stops.

Key definitions

• Rolling update strategy — the Deployment's strategy.type: RollingUpdate (default).
• maxSurge — maximum number of Pods above the desired replica count during the update (default 25%).
• maxUnavailable — maximum number of Pods that can be unavailable during the update (default 25%).

If your desired replica count is 4, with defaults: - maxSurge = 25% → 1 extra Pod allowed above 4 (total 5). - maxUnavailable = 25% → only 1 Pod can be down at a time.

This ensures availability stays high while new Pods spin up.

How it works step by step

When you execute kubectl set image deployment/myapp myapp=myapp:v2 or apply an updated YAML file (kubectl apply -f deployment-v2.yaml), the Deployment controller follows this sequence:

1. Detect change — The controller notices the Pod template (e.g., image tag) has changed.
2. Create new ReplicaSet — A ReplicaSet for the new Pod template is created, with replica count 0.
3. Scale up new ReplicaSet — Add 1 new Pod (controlled by maxSurge).
4. Scale down old ReplicaSet — Remove 1 old Pod (controlled by maxUnavailable).
5. Repeat — Until all old Pods are replaced by new ones.
6. Declare update complete — The old ReplicaSet is scaled to 0, but remains in history for rollback.

Pro tip: You can watch the progress with kubectl rollout status deployment myapp.

Example with real numbers

Assume a Deployment with replicas=3, default rolling update settings:

Notice the total Pods never drops below 3 (except briefly if maxUnavailable allows), and never exceeds 4.

Hands-on walkthrough

Let's perform a rolling update with a real Deployment. We'll start with a simple nginx app, update the image, and monitor the rollout.

Step 1: Create the initial Deployment

# deployment-v1.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: nginx:1.23-alpine
        ports:
        - containerPort: 80

kubectl apply -f deployment-v1.yaml
deployment.apps/myapp created

Step 2: Verify initial state

kubectl get pods -l app=myapp

Expected output (names and status vary):

NAME                     READY   STATUS    RESTARTS   AGE
myapp-6d9f9c8c8-abc12   1/1     Running   0          30s
myapp-6d9f9c8c8-def34   1/1     Running   0          30s
myapp-6d9f9c8c8-ghi56   1/1     Running   0          30s

Step 3: Perform the rolling update

Update the image to a newer version:

kubectl set image deployment/myapp myapp=nginx:1.24-alpine
deployment.apps/myapp image updated

Or apply a modified YAML file — same effect. Watch the rollout in real time:

kubectl rollout status deployment/myapp

While that command is running, in another terminal, watch Pods change:

kubectl get pods -l app=myapp --watch

You'll see new Pods starting (with a different generation hash in the name), and old Pods terminating one by one. No downtime.

Step 4: Verify the update

kubectl rollout history deployment/myapp
deployment.apps/myapp
REVISION  CHANGE-CAUSE
1         <none>
2         <none>

The revision number increments with each update. Now check the actual image running:

kubectl get deployment myapp -o jsonpath='{.spec.template.spec.containers[0].image}'
nginx:1.24-alpine

Step 5: Check the old ReplicaSet

kubectl get replicaset -l app=myapp

Expected output shows the old ReplicaSet at 0 replicas, ready for rollback if needed.

Compare options / when to choose what

Rolling update is Kubernetes' default strategy, but not the only one. Here's how it compares to alternatives:

When to choose RollingUpdate: - Your app is stateless or mostly stateless. - You need zero downtime. - You want simplicity — no extra tooling. - You're okay with a rollout that takes minutes (not seconds).

When to avoid RollingUpdate: - Your app cannot run two versions simultaneously (e.g., database schema migrations that break with old code). - You need instant, complete switchovers. - You're dealing with stateful workloads that require careful IP/hostname handling (use StatefulSet with OnDelete strategy).

Pro tip: For most web APIs and microservices, RollingUpdate with readiness probes is the safest bet. Always define a readinessProbe in your Pod template — it tells Kubernetes the Pod is ready to serve traffic before counting it as "available."

Troubleshooting & edge cases

Even with rolling updates, things can go wrong. Here are common failures and fixes.

1. Rolling update stalls

Symptom: kubectl rollout status hangs at "Waiting for deployment spec update to be observed..." or Pods stay in Pending/CrashLoopBackOff.

Fix: - Check Pod logs: kubectl logs <pod-name>. - Verify readiness probe: kubectl get pods | grep Running vs kubectl get pods -o wide. If a Pod is Running but not Ready, your probe is failing. - Scale up resources if Pods are stuck in Pending due to CPU/memory.

2. maxUnavailable reached but new Pods not starting

Symptom: Old Pods are terminating, but new ones won't schedule.

Fix: - Check node resources: kubectl describe nodes. You may need to add nodes. - Check PVC if using persistent volumes. - Verify image pull: kubectl describe pod <new-pod> for ImagePullBackOff.

3. Rollback failure

If you need to revert quickly:

kubectl rollout undo deployment/myapp
deployment.apps/myapp rolled back

But if the undo itself fails (e.g., because the previous revision's image is also broken), you can roll back to a specific revision:

kubectl rollout undo deployment/myapp --to-revision=1

4. Pods crash after update

Symptom: New Pods restart endlessly.

Fix: - kubectl logs <pod-name> --previous to see last log before crash. - kubectl describe pod <pod-name> shows Last State: Terminated with exit code. - Fix your image or configuration, then reapply.

5. Config mismatch between versions

If your old Pods use environment variables that are removed in the new version, your app might break. Use readinessProbe to catch this early.

What you learned & what's next

You now know how to perform a rolling update with Deployment safely, with zero downtime. You understand:

• The mental model of Deployments as fleet managers.
• The step-by-step mechanics of scaling in/out ReplicaSets.
• How to set and verify a rolling update using kubectl set image and kubectl rollout status.
• The differences between RollingUpdate, Recreate, Blue/Green, and Canary strategies.
• How to troubleshoot stalled rollouts, failing Pods, and rollbacks.

What's next: Now that you can update Deployments, the next step is to automate rollbacks when health checks fail — you'll learn about Deployment rollbacks and how to set up automated recovery with readiness probes and PDBs (Pod Disruption Budgets). This is crucial for production safety. In the next lesson, you'll implement a canary release or blue/green deployment pattern, giving you even finer control over risk.

Pro tip: Always set revisionHistoryLimit in your Deployment spec (default 10) to limit the number of old ReplicaSets kept for rollback. Too many can slow down rollout history.