A Deployment is the Kubernetes workload object that declares the desired state of a stateless application: which container image to run, how many identical Pods should exist and how updates should be rolled out. In Kubernetes, the Deployment controller continuously compares that declaration with the cluster and creates, replaces or removes Pods through ReplicaSets until reality matches the specification.
In this context, Deployment is a specific API resource of kind Deployment in the apps/v1 group, not the general act of releasing software. It is the default choice for web servers, APIs and workers that do not need stable identities or per-replica storage.
How a Deployment manages Pods through ReplicaSets
A Deployment does not manage Pods directly. It owns one or more ReplicaSets, and each ReplicaSet keeps a fixed number of Pods from a single Pod template running. When the template changes, for example because the image tag is updated, the Deployment creates a new ReplicaSet and gradually shifts replicas from the old one to the new one.
This design makes every rollout traceable. Old ReplicaSets are kept, scaled to zero, up to the revisionHistoryLimit, which defaults to 10. A rollback simply scales an earlier ReplicaSet back up, which is why kubectl rollout undo can restore a previous version within seconds.
Pods are selected by labels. The Deployment’s selector must match the labels in its Pod template, and the selector is immutable after creation in apps/v1, so changing it requires creating a new Deployment.
The controller works by continuous reconciliation, not by executing a one-time script. If someone deletes a Pod manually, a node fails or a Pod is evicted, the owning ReplicaSet notices that the observed count is below the desired count and creates a replacement, usually within seconds, on any node with sufficient capacity.
Key fields of a Deployment specification
A Deployment manifest is short, but a few fields determine availability, rollout speed and safety. The table summarizes the fields most often tuned in production.
| Field | Default or typical value | What it controls |
|---|---|---|
| replicas | 1 by default, 2-3 or more in production | Number of Pods kept running |
| strategy.type | RollingUpdate | Update method, alternatively Recreate |
| maxSurge | 25 percent | Extra Pods allowed above the desired count during rollout |
| maxUnavailable | 25 percent | Pods allowed to be unavailable during rollout |
| minReadySeconds | 0 | Time a new Pod must stay ready before counting as available |
| progressDeadlineSeconds | 600 | Time before a stalled rollout is reported as failed |
| revisionHistoryLimit | 10 | Number of old ReplicaSets kept for rollback |
The rollout is only as safe as the readiness probe in the Pod template. A rolling update counts a new Pod as available when its readiness probe succeeds, so a probe that always passes lets a broken version replace a working one without any warning.
Rollout strategies for a Deployment
Kubernetes provides two built-in strategies, and more advanced patterns are built on top of Deployments with additional tooling. The choice depends on whether two versions can run side by side and how much risk a release carries.
| Strategy | How it works | When it fits |
|---|---|---|
| RollingUpdate | Replaces Pods gradually within surge and unavailability limits | Default for stateless services that tolerate mixed versions |
| Recreate | Stops all old Pods before starting new ones | Versions that cannot coexist, accepting downtime |
| Blue-green | Two Deployments, traffic switched at the Service | Instant switch and quick rollback, double capacity |
| Canary | Small share of traffic to the new version first | High-risk releases, needs traffic splitting tooling |
Setting maxUnavailable to zero and maxSurge to one gives a conservative rollout that never drops below full capacity, at the cost of needing spare cluster resources for one extra Pod at a time.
Deployment compared with other Kubernetes objects
A Deployment is one of several workload controllers, and it works together with networking and packaging objects. Choosing the right controller for the workload avoids fragile workarounds.
| Object | Purpose | Relation to Deployment |
|---|---|---|
| Pod | Smallest runnable unit | Created from the Deployment’s template |
| ReplicaSet | Keeps a fixed number of identical Pods | Owned and versioned by the Deployment |
| StatefulSet | Pods with stable names and storage | Used instead for databases and clustered stateful systems |
| DaemonSet | One Pod per node | Used instead for node agents |
| Service | Stable network endpoint for Pods | Routes traffic to the Deployment’s Pods by label |
| Helm | Package manager for manifests | Often templates and installs Deployments |
A practical rule follows from this comparison: if replicas are interchangeable and keep no local state, a Deployment is the right controller. As soon as each replica needs its own persistent volume or a predictable network identity, a StatefulSet is the better fit, even though both ultimately run ordinary Pods.
Common Deployment mistakes
- Running a single replica: any node drain or crash causes downtime; production services usually need at least two replicas and a PodDisruptionBudget.
- Missing or weak probes: without readiness checks, traffic reaches Pods that are still starting, and broken releases roll out completely.
- Mutable image tags: using
latestmakes rollouts unpredictable and rollbacks meaningless; pin tags or digests. - No resource requests: the scheduler cannot place Pods sensibly, and autoscaling has no baseline to work from.
- Fighting the autoscaler: when a HorizontalPodAutoscaler manages replicas, a hardcoded
replicasvalue in every apply resets the scale.
Rollout status should be part of the release pipeline. Running kubectl rollout status with a timeout makes the pipeline fail visibly when a rollout stalls, instead of reporting success while old Pods quietly keep serving traffic.
The simple explanation
A Deployment is a standing order given to Kubernetes: keep this many copies of this application running, and when a new version arrives, swap the copies over carefully.
Kubernetes then acts like a shift manager. If a copy crashes, it starts a replacement. When an update comes, it brings new copies in a few at a time and retires old ones only when the new ones are ready, so the service stays available throughout.
How it is used in practice
An online booking platform runs its search API as a Deployment with six replicas, a readiness probe on a health endpoint, maxSurge of one and maxUnavailable of zero. A Service routes traffic to all ready Pods.
During a release, a new image contains a configuration error that makes the health endpoint fail. The first new Pod never becomes ready, so the rollout stops after one Pod while the six old Pods keep serving every request. The pipeline detects the stalled rollout, runs kubectl rollout undo, and customers see no interruption at all.