Kubernetes Deployment Explained
Learn how Kubernetes Deployments manage ReplicaSets and Pods, perform rolling updates, control maxSurge and maxUnavailable, track revisions and safely roll back releases.
BitCodeMatrix
Kubernetes Deployment Explained
Rolling Updates, Rollbacks and Revision History
Practical guide for Kubernetes, DevOps and Cloud Engineers
Introduction
A Kubernetes Deployment provides declarative management for Pods and ReplicaSets. For a typical stateless application, you declare the desired number of replicas and the Pod template, and Kubernetes works continuously to make the running workload match that desired state.
The important difference between a Deployment and a standalone ReplicaSet is lifecycle management. A ReplicaSet maintains a Pod population. A Deployment sits above ReplicaSets and manages application revisions, rollouts and rollbacks.
This makes Deployment one of the most important Kubernetes resources to understand for production engineering. A deployment is not simply a YAML file with replicas. It is a controller-driven mechanism for changing application versions while controlling how much capacity is available during the transition.
1. What Is a Kubernetes Deployment?
A Deployment is a Kubernetes workload resource that enables declarative updates for Pods and ReplicaSets. You specify the desired application state, and the Deployment controller creates and manages ReplicaSets to move the cluster toward that state.
2. Why Use a Deployment Instead of a Standalone ReplicaSet?
A standalone ReplicaSet can maintain a number of Pods, but it is not the normal resource for application version management. When you change the application image or another part of the Pod template, a Deployment can create a new ReplicaSet and coordinate the transition between the old and new versions.
3. Deployment Architecture
Kubernetes API
|
v
Deployment
replicas: 3
|
+-----------+-----------+
| |
v v
ReplicaSet v1 ReplicaSet v2
old revision new revision
| |
Pods v1 Pods v2
Pod Pod Pod Pod Pod
^
|
rollout controller
During a rollout, the Deployment controller manages the relative scale of old and new ReplicaSets. The exact sequence depends on the Deployment strategy and its rolling-update parameters.
4. A Production-Style Deployment Manifest
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
labels:
app: web
spec:
replicas: 3
revisionHistoryLimit: 10
progressDeadlineSeconds: 600
selector:
matchLabels:
app: web
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 1
maxSurge: 1
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: nginx:1.27
ports:
- containerPort: 80
The selector must match the Pod template labels. The Deployment selector is immutable after creation in apps/v1, so it should be designed carefully before the resource is created.
5. What Triggers a New Deployment Revision?
A Deployment revision is created when the Deployment's Pod template changes. Examples include changing the container image or modifying Pod-template labels. Changing the Deployment's replica count by itself does not create a new Deployment revision.
6. Rolling Updates: The Default Strategy
The default Deployment strategy is RollingUpdate. Kubernetes gradually scales the new ReplicaSet up and the old ReplicaSet down rather than terminating all old Pods first.
Version 1
ReplicaSet v1
Pod v1
Pod v1
Pod v1
update image
Version 2 rollout
ReplicaSet v1 ReplicaSet v2
Pod v1 Pod v2
Pod v1 Pod v2
Pod v1
gradually shift
Final state
ReplicaSet v2
Pod v2
Pod v2
Pod v2
The purpose is to allow the application to transition between versions while controlling availability and temporary extra capacity.
7. maxSurge: How Many Extra Pods Can Exist?
maxSurge defines the maximum number of Pods that can be scheduled above the desired replica count during a RollingUpdate. It can be an absolute number or a percentage. The default is 25%.
When a percentage is used, Kubernetes rounds the calculated maxSurge value up to an absolute number.
8. maxUnavailable: How Many Pods Can Be Unavailable?
maxUnavailable defines the maximum number of Pods that can be unavailable during a RollingUpdate. It can be an absolute number or a percentage. The default is 25%.
When a percentage is used, Kubernetes rounds the calculated maxUnavailable value down to an absolute number.
9. maxSurge and maxUnavailable Together
These two settings should be considered together. maxSurge controls temporary extra capacity; maxUnavailable controls the amount of capacity that may be unavailable during the update.
The correct values depend on application behavior, cluster capacity, startup time and availability requirements. There is no universal production value.
10. Recreate Strategy
A Deployment can use strategy.type: Recreate. With this strategy, existing Pods are terminated before new Pods are created during an upgrade.
strategy:
type: Recreate
Recreate can be appropriate when the old and new versions cannot safely coexist. The trade-off is downtime during the transition.
11. Step-by-Step Rolling Update Example
Assume a Deployment has three replicas running version 1:
replicas: 3
image: myapp:v1
Update the image:
kubectl set image deployment/web web=myapp:v2
The Deployment controller observes that the Pod template changed and creates a new revision/ReplicaSet.
Before:
RS-v1: 3 Pods
RS-v2: 0 Pods
During rollout:
RS-v1: 2 Pods
RS-v2: 1 Pod
Then:
RS-v1: 1 Pod
RS-v2: 2 Pods
Final:
RS-v1: 0 Pods
RS-v2: 3 Pods
The exact intermediate counts depend on maxSurge, maxUnavailable, Pod readiness and other rollout conditions.
12. Essential Deployment Commands
13. Monitoring a Rollout
- kubectl rollout status deployment/web
- kubectl get deployment web
- kubectl get rs
- kubectl get pods -l app=web
- kubectl describe deployment web
- kubectl get events --sort-by=.lastTimestamp
A Deployment rollout should be observed at multiple layers. Deployment status tells you about rollout progress; ReplicaSets show old/new revision populations; Pods show individual startup and health problems; events often reveal scheduling, image, volume or admission failures.
14. Deployment Status and Conditions
Deployment status exposes observations such as available replicas, updated replicas, ready replicas and rollout conditions. The controller can report conditions such as Progressing and Available. A stalled rollout can surface the ProgressDeadlineExceeded reason when the configured progress deadline is exceeded.
15. progressDeadlineSeconds
progressDeadlineSeconds specifies how long Kubernetes waits for Deployment progress before marking the Deployment as failed to progress. The default is 600 seconds (10 minutes). The controller continues processing the Deployment after this condition is reported.
spec:
progressDeadlineSeconds: 600
A progress deadline is not a magical rollback mechanism. It is a status signal that the rollout has not progressed as expected. Engineers still need to diagnose why the new Pods are not becoming available.
16. What Happens When a Rollout Fails?
Suppose version 2 contains an invalid image name. New Pods may fail with ImagePullBackOff. The Deployment controller can stop further rollout progress depending on the rolling-update availability constraints.
- kubectl set image deployment/web web=myapp:does-not-exist
- kubectl rollout status deployment/web
- kubectl get pods
- kubectl describe pod <failing-pod>
- kubectl describe deployment web
The key troubleshooting principle is to inspect the new ReplicaSet and its Pods. The Deployment tells you that the rollout is unhealthy; Pod events and logs generally tell you why.
17. Pausing and Resuming a Deployment
A Deployment can be paused. While paused, changes to the PodTemplateSpec do not trigger new rollouts until the Deployment is resumed.
kubectl rollout pause deployment/web
# Make one or more Pod-template changes
kubectl set image deployment/web web=myapp:v2
# Resume
kubectl rollout resume deployment/web
18. Deployment Revision History
Deployment revision history is stored in the ReplicaSets controlled by the Deployment. Each time the Pod template changes and a rollout is triggered, Kubernetes assigns a new Deployment revision.
kubectl rollout history deployment/web
19. revisionHistoryLimit
The revisionHistoryLimit field controls how many old ReplicaSets the Deployment retains for rollback. The default is 10.
spec:
revisionHistoryLimit: 10
Setting revisionHistoryLimit to 0 causes old ReplicaSets with zero replicas to be cleaned up, which removes retained rollback history. The ideal value depends on deployment frequency, rollback requirements and cluster resource considerations.
20. Inspecting a Specific Revision
kubectl rollout history deployment/web
kubectl rollout history deployment/web --revision=3
The rollout history output can show revision numbers and, when a change-cause annotation is present, its recorded change cause.
The kubernetes.io/change-cause annotation is not automatically populated by Kubernetes. A deployment tool or user can set it so that revision history is easier to interpret.
21. Rolling Back a Deployment
If a newly deployed version is unhealthy, Kubernetes provides rollout undo commands to restore an earlier retained Pod-template revision.
# Roll back to the previous revision
kubectl rollout undo deployment/web
# Roll back to a specific revision
kubectl rollout undo deployment/web --to-revision=2
# Verify
kubectl rollout status deployment/web
A rollback is itself a change to the Deployment's Pod template and results in a new rollout. Kubernetes can reuse an existing ReplicaSet when rolling back, while the Deployment revision history records the revision relationship.
22. Real-World Rollback Scenario
Imagine a web application is running version 10. You deploy version 11. The Pods start successfully, but the application returns errors because of a software defect.
- Confirm the new revision is responsible for the problem.
- Check Deployment and Pod status.
- Inspect logs and application metrics.
- Check the rollout history.
- Select a known-good retained revision.
- Execute the rollback.
- Monitor the new rollout until the previous application behavior is restored.
- Investigate the failed release separately before attempting another deployment.
23. What a Rollback Does—and Does Not—Guarantee
Rollback restores the Deployment's earlier Pod-template configuration. It does not magically undo external side effects created by the application.
24. Why Scaling Does Not Create a Revision
A Deployment revision represents a Pod-template rollout, not every change made to the Deployment. Scaling the Deployment changes the desired replica count but does not modify the Pod template, so it does not create a new revision.
kubectl scale deployment/web --replicas=5
kubectl rollout history deployment/web
This distinction allows operational scaling and application version history to remain separate.
25. Updating an Image Safely
kubectl set image deployment/web web=myapp:v2
kubectl rollout status deployment/web
For GitOps or declarative workflows, update the version in the manifest or source-controlled configuration rather than treating kubectl commands as the long-term source of truth.
26. Deployment Selector: A Critical Design Detail
The Deployment selector identifies the Pods managed by the Deployment. In apps/v1, the selector is required and immutable after creation. It must match the labels on the Pod template.
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
Do not create another Deployment, ReplicaSet or controller with an overlapping selector for the same Pods. Overlapping controllers can fight over the same workload population and produce incorrect behavior.
27. Readiness and Rolling Updates
A rollout should not be judged only by whether containers have started. Application readiness matters. A Pod can be Running but not Ready.
readinessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 5
periodSeconds: 10
When new Pods are not ready, the Deployment may be unable to reduce old capacity or complete the rollout as expected, depending on the rollout parameters and availability state.
28. minReadySeconds
minReadySeconds specifies the minimum number of seconds a newly created Pod must remain Ready without container crashes before it is considered available.
spec:
minReadySeconds: 30
This can be useful when an application may briefly report Ready immediately after startup but needs a sustained healthy period before being considered available by the Deployment.
29. Hands-On Lab: Create a Deployment
cat <<'EOF' > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 3
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 1
maxSurge: 1
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: nginx:1.27
ports:
- containerPort: 80
EOF
- kubectl apply -f deployment.yaml
- kubectl get deployment web
- kubectl get rs
- kubectl get pods -l app=web
- kubectl rollout status deployment/web
30. Hands-On Lab: Perform a Rolling Update
- kubectl set image deployment/web web=nginx:1.28
- kubectl rollout status deployment/web
- kubectl get rs
- kubectl get pods -l app=web
Observe that the Deployment creates a new ReplicaSet for the changed Pod template and gradually shifts the workload from the old ReplicaSet to the new one.
31. Hands-On Lab: Roll Back the Deployment
- kubectl rollout history deployment/web
- kubectl rollout undo deployment/web
- kubectl rollout status deployment/web
- kubectl get rs
- kubectl get pods -l app=web
For a controlled exercise, inspect a specific revision before rolling back:
- kubectl rollout history deployment/web --revision=1
32. Hands-On Lab: Diagnose a Failed Rollout
Deploy an intentionally invalid image tag in a disposable environment:
- kubectl set image deployment/web web=nginx:this-tag-does-not-exist
- kubectl rollout status deployment/web
- kubectl get pods -l app=web
- kubectl describe deployment web
- kubectl describe pod <new-pod-name>
The purpose is to practice separating symptoms from root causes: the Deployment may report rollout progress problems, while the Pod events reveal the image-pull failure.
33. Deployment Troubleshooting Guide
34. Deployment Debugging Command Set
# Deployment
kubectl get deployment web
kubectl describe deployment web
# Rollout
kubectl rollout status deployment/web
kubectl rollout history deployment/web
# ReplicaSets
kubectl get rs
kubectl describe rs
# Pods
kubectl get pods -l app=web -o wide
kubectl describe pod <pod>
kubectl logs <pod>
kubectl logs <pod> --previous
# Events
kubectl get events --sort-by=.lastTimestamp
35. Kubernetes Deployment Best Practices
- Use Deployments for typical stateless application workloads rather than managing ReplicaSets directly.
- Use precise, stable selectors and make sure the selector matches the Pod-template labels.
- Choose RollingUpdate or Recreate based on actual application compatibility and availability requirements.
- Set maxSurge and maxUnavailable deliberately instead of blindly accepting defaults for critical production workloads.
- Define meaningful readiness probes so rollout progress reflects actual application readiness.
- Use startup probes for applications with legitimately long startup times.
- Set realistic CPU and memory requests so replacement Pods can be scheduled.
- Use minReadySeconds when a sustained Ready period is important before a Pod counts as available.
- Keep sufficient revision history for operational rollback while avoiding unnecessary accumulation of old ReplicaSets.
- Monitor rollout status and application health rather than assuming a successful kubectl apply means a successful release.
- Use declarative manifests and version control as the source of truth.
- Treat rollback as a release-management action and separately plan database/data rollback or forward-fix behavior.
36. Common Deployment Mistakes
- Changing the Deployment selector after creation; apps/v1 selectors are immutable.
- Using overlapping selectors between multiple controllers.
- Assuming RollingUpdate guarantees zero downtime under every failure condition.
- Setting maxUnavailable too aggressively for a small production workload.
- Setting maxSurge high without considering cluster capacity.
- Using a liveness probe as a substitute for readiness.
- Ignoring readiness failures when a rollout is stuck.
- Setting revisionHistoryLimit to zero and then expecting old revisions to remain available for rollback.
- Assuming rollback reverses database schema or external system changes.
- Using imperative kubectl commands without updating the declarative source of truth.
- Not monitoring the rollout after applying a new image.
- Assuming a new revision is created for every Deployment field change.
37. Kubernetes Deployment Interview Questions
What is a Kubernetes Deployment?
A Kubernetes workload resource that enables declarative management and updates of Pods and ReplicaSets.
What is the relationship between Deployment, ReplicaSet and Pod?
The Deployment manages ReplicaSets, and ReplicaSets manage the Pod replicas for a particular Pod-template revision.
What is the default Deployment strategy?
RollingUpdate.
What is the difference between RollingUpdate and Recreate?
RollingUpdate gradually replaces old Pods with new Pods; Recreate terminates existing Pods before creating new ones during an upgrade.
What is maxSurge?
The maximum number of Pods that can be scheduled above the desired replica count during a RollingUpdate.
What is maxUnavailable?
The maximum number of Pods that can be unavailable during a RollingUpdate.
What are the default maxSurge and maxUnavailable values?
Both default to 25%.
What creates a Deployment revision?
A change to the Deployment Pod template, such as changing the container image or another Pod-template field.
Does scaling create a revision?
No. Changing replicas does not change the Pod template and does not create a Deployment revision.
Where is Deployment revision history stored?
In the ReplicaSets controlled by the Deployment.
What is revisionHistoryLimit?
The number of old ReplicaSets retained for rollback; the default is 10.
What happens if revisionHistoryLimit is zero?
Old ReplicaSets with zero replicas are cleaned up, removing retained rollback history.
How do you roll back a Deployment?
Use kubectl rollout undo deployment/<name>, optionally with --to-revision=<number>.
Does rollback create a new revision?
Rollback changes the Deployment Pod template and results in a new rollout; Kubernetes may reuse an existing ReplicaSet while tracking revision history.
What is progressDeadlineSeconds?
The maximum time allowed for Deployment progress before the Deployment is marked as having exceeded its progress deadline; the default is 600 seconds.
Why might a Deployment remain stuck during a rolling update?
New Pods may fail to start, remain Pending, fail readiness, fail image pulls, lack resources, or otherwise prevent rollout progress.
38. Scenario-Based Interview Question
Scenario: A Deployment has 10 replicas and is configured with maxUnavailable: 2 and maxSurge: 3. A new image is released. During the rollout, what are the two key constraints you should reason about?
- The rollout can temporarily schedule extra Pods above the desired count, bounded by maxSurge.
- The rollout can tolerate a bounded number of unavailable Pods, controlled by maxUnavailable.
- The actual sequence depends on Pod readiness and controller reconciliation, so do not assume a fixed step-by-step count without considering the current state.
39. Advanced Topic: Multiple Updates During a Rollout
A Deployment can receive another Pod-template update while an existing rollout is still in progress. Kubernetes can create a new ReplicaSet for the latest update and roll over the ReplicaSet that was previously being scaled.
Update A
RS-v2 <- rollout in progress
Update B arrives
RS-v3 <- new desired revision
RS-v2 <- becomes an older revision and is scaled down
RS-v1 <- older revision
This behavior matters in CI/CD systems where multiple releases can be triggered close together. The latest desired Pod template becomes the target state, while older ReplicaSets may be scaled down.
40. Deployment and Canary Releases
A Deployment can be part of a canary architecture, but a single Deployment's standard RollingUpdate is not the same thing as an application-level canary release with controlled user percentages.
For canary patterns, Kubernetes documentation describes using multiple Deployments, with traffic management or other routing mechanisms used to expose a subset of users or traffic to the canary version.
41. Real-World Production Release Workflow
- Build and test the application image.
- Publish an immutable or appropriately controlled image version.
- Update the Deployment Pod template in the declarative configuration.
- Apply the change through the organization's deployment process.
- Watch kubectl rollout status or the equivalent deployment-system status.
- Monitor new Pod readiness, logs, application metrics and errors.
- If healthy, allow the rollout to complete.
- If unhealthy, stop further promotion and diagnose the new ReplicaSet/Pods.
- Rollback to a retained known-good revision when appropriate.
- Investigate the failed release and separately assess database or external-system changes.
42. Summary
Kubernetes Deployment is the primary controller for declarative application updates. It manages ReplicaSets, and each meaningful Pod-template change can create a new Deployment revision.
RollingUpdate is the default strategy. maxSurge controls temporary additional capacity, while maxUnavailable controls how much capacity may be unavailable during the transition. Recreate provides a different behavior by terminating existing Pods before creating the new set during an upgrade.
Deployment revision history is stored in the ReplicaSets controlled by the Deployment. revisionHistoryLimit controls how many old ReplicaSets are retained for rollback, with a default of 10. Rollbacks restore a previous Pod-template revision but do not undo external side effects such as database changes.
43. Suggested Next Articles
- Kubernetes Service Explained: ClusterIP, NodePort and LoadBalancer
- Kubernetes DNS Explained: CoreDNS and Service Discovery
- Kubernetes Ingress Explained: Routing External Traffic to Applications
- Kubernetes ConfigMap Explained: Managing Application Configuration
- Kubernetes Secrets Explained: Managing Sensitive Configuration
- Kubernetes CPU and Memory Requests vs Limits
- Kubernetes Horizontal Pod Autoscaler Explained
- Kubernetes Deployment Strategies: Rolling, Recreate, Blue-Green and Canary
Official Kubernetes References
Deployments concept documentation: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
Deployment API reference: https://kubernetes.io/docs/reference/kubernetes-api/apps/deployment-v1/
Update a Deployment Without Downtime: https://kubernetes.io/docs/tasks/run-application/update-deployment-rolling/
Kubernetes well-known labels and annotations: https://kubernetes.io/docs/reference/labels-annotations-taints/
ReplicaSet concepts: https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/
BitCodeMatrix.com | Kubernetes Learning Series