Kubernetes Rolling Updates and Rollback: A Practical Guide

Desired Outcome

Upgrade a running Kubernetes Deployment to a newer container image while keeping the service available. The goal is to replace old Pods with new ones gradually, avoiding downtime.

Prerequisites

• kubectl configured to access the target cluster and authenticated with a role that permits edit on Deployments in the target namespace.
• A Deployment already created, for example my-app with at least one replica.
• Understanding of the maxSurge and maxUnavailable parameters that control how many Pods are created beyond the desired capacity and how many Pods may be unavailable during the update.

Procedure

1. Configure RollingUpdate parameters

Set the strategy to RollingUpdate and define the limits. The following command adds environment variables that the Deployment controller reads:

kubectl set env deployment/my-app -n prod \
  MAX_SURGE=25% \
  MAX_UNAVAILABLE=25%

Replace my-app with your Deployment name and prod with the namespace. The placeholders represent a percentage of the desired replica count. By default Kubernetes uses 25% for both values; you can adjust them based on cluster capacity and tolerance for temporary unavailability.

2. Trigger the update

Restart the Deployment to pick up the new template. This does not change the image itself but forces a new rollout:

kubectl rollout restart deployment/my-app -n prod

3. Monitor the rollout

Check the current status to ensure the process is progressing:

kubectl rollout status deployment/my-app -n prod

Typical output looks like deployment "my-app" successfully rolled out. If the output contains warning or failed, inspect the Pod events with kubectl describe pod <pod-name> to see why a Pod may be stuck in CrashLoopBackOff or ImagePullBackOff.

4. Review revision history

To confirm that each step created a new revision, run:

kubectl rollout history deployment/my-app -n prod

Each revision entry shows a REVISION number, the container image, and the timestamp. The numbers should increase sequentially. You can also roll back to a specific revision using kubectl rollout undo deployment/my-app --to-revision=3.

Expected Checks

• Output of kubectl rollout status includes “successfully rolled out”.
• New Pods report the updated container image when inspected with kubectl describe pod <pod-name>.
• Service traffic remains stable; a quick curl or health‑check endpoint can verify availability.

Recovery – Rollback

If any check fails, revert the Deployment to the previous revision instantly:

kubectl rollout undo deployment/my-app -n prod

This command restores the last successful revision without recreating the Deployment object. After undoing, re‑run the status command to verify that the rollout is now “successfully rolled out” again.

Limitations and Risks

• Setting maxSurge too high may overload nodes, causing eviction of other workloads.
• Setting maxUnavailable too low can stall the rollout if nodes become unschedulable.
• Frequent rollbacks accumulate revision history in etcd, potentially degrading API server performance.

Mitigation strategies include monitoring node pressure, using horizontal pod autoscaling, and limiting the number of retained revisions with spec.revisionHistoryLimit.

Practical verification after rollback

Execute the status check again:

kubectl rollout status deployment/my-app -n prod

Confirm that the Deployment reports a new revision number that matches the previous one, and that no error messages appear.