A Deployment is how you run a stateless application on Kubernetes. You declare which image to run and how many replicas you want, and the Deployment controller keeps that promise: it replaces failed Pods, rolls out new versions gradually and keeps a history so you can roll back in one command.
Why not manage Pods yourself?
A bare Pod has nobody looking after it. If its node dies, the Pod is gone for good. Updating it means deleting it and creating a new one, with downtime in between. A Deployment adds everything a real application needs: self-healing, scaling, gradual rollouts and a way back.
The chain: Deployment, ReplicaSet, Pods
A Deployment does not create Pods directly. It creates a ReplicaSet, and the ReplicaSet creates the Pods. Every time you change the Pod template (a new image, a new environment variable), the Deployment creates a new ReplicaSet and moves replicas from the old one to the new one.
$ kubectl get replicasets -l app=shop-api
NAME DESIRED CURRENT READY AGE
shop-api-6d9f7b8c4 3 3 3 5m
shop-api-5b8c7d6f9 0 0 0 2d
shop-api-7f4a9e2c1 0 0 0 6d
The old ReplicaSets at 0 replicas are your rollback history. revisionHistoryLimit controls how many are kept (10 by default). Note that scaling does not create a revision: only changes to the Pod template do.
Writing a Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: shop-api
labels:
app: shop-api
spec:
replicas: 3
revisionHistoryLimit: 5
selector:
matchLabels:
app: shop-api
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
template:
metadata:
labels:
app: shop-api
spec:
containers:
- name: api
image: ghcr.io/jeffxl/shop-api:1.2.0
ports:
- name: http
containerPort: 8080
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
memory: 256Mi
readinessProbe:
httpGet:
path: /healthz
port: http
periodSeconds: 5
Things to notice:
selector.matchLabelsmust matchtemplate.metadata.labels. The API server rejects the Deployment if they do not.- The selector is immutable. To change it you must delete and recreate the Deployment.
- The readiness probe is what makes rolling updates safe. Without it, Kubernetes considers a Pod ready the moment its process starts. Traffic then reaches an app that is still booting, and old Pods are removed too early.
Rolling updates
Change the image and watch the rollout:
$ kubectl set image deployment/shop-api api=ghcr.io/jeffxl/shop-api:1.3.0
deployment.apps/shop-api image updated
$ kubectl rollout status deployment/shop-api
Waiting for deployment "shop-api" rollout to finish: 1 out of 3 new replicas have been updated...
Waiting for deployment "shop-api" rollout to finish: 2 out of 3 new replicas have been updated...
Waiting for deployment "shop-api" rollout to finish: 1 old replicas are pending termination...
deployment "shop-api" successfully rolled out
Two settings control the pace:
| Setting | Meaning | Trade-off |
|---|---|---|
maxSurge | How many extra Pods may exist above replicas | Faster rollout, needs spare capacity |
maxUnavailable | How many Pods may be missing during the update | 0 keeps full capacity but needs room to surge |
maxSurge: 1 with maxUnavailable: 0 is the safe default: a new Pod must become Ready before an old one is removed. On a cluster with no spare room, maxSurge: 0 with maxUnavailable: 1 works, but you run below capacity during every deploy. Both settings also accept percentages such as 25%.
The other strategy, Recreate, stops all old Pods before starting new ones. That means downtime, so keep it for apps that cannot run two versions at the same time, for example because of an exclusive lock or an incompatible schema change.
Rollbacks
$ kubectl rollout history deployment/shop-api
REVISION CHANGE-CAUSE
3 release 1.2.0
4 release 1.3.0
$ kubectl rollout undo deployment/shop-api
deployment.apps/shop-api rolled back
$ kubectl rollout undo deployment/shop-api --to-revision=3
The CHANGE-CAUSE column is empty unless you fill it. Set the annotation every time you change something:
$ kubectl annotate deployment/shop-api kubernetes.io/change-cause="release 1.3.0"
You can also pause a rollout to make several changes at once and resume it to roll them out together:
$ kubectl rollout pause deployment/shop-api
$ kubectl set image deployment/shop-api api=ghcr.io/jeffxl/shop-api:1.3.1
$ kubectl set env deployment/shop-api LOG_LEVEL=debug
$ kubectl rollout resume deployment/shop-api
When a rollout will not finish
If new Pods do not become Ready within progressDeadlineSeconds (600 by default), the rollout is marked as failed:
$ kubectl rollout status deployment/shop-api
error: deployment "shop-api" exceeded its progress deadline
A failed rollout does not roll back by itself. It just stops. With maxUnavailable: 0 the old Pods are still serving, so a failed deploy is usually not an outage. Look at the new Pods:
$ kubectl get pods -l app=shop-api
NAME READY STATUS RESTARTS AGE
shop-api-6d9f7b8c4-kq2xv 1/1 Running 0 2h
shop-api-6d9f7b8c4-p8mzt 1/1 Running 0 2h
shop-api-6d9f7b8c4-t4r8n 1/1 Running 0 2h
shop-api-8c2e5f1a7-zz9kw 0/1 CrashLoopBackOff 5 6m
$ kubectl describe pod shop-api-8c2e5f1a7-zz9kw
The usual suspects: a readiness probe with the wrong path or port, ImagePullBackOff from a missing tag, a Pending surge Pod because there is no room, or a crash on startup (check kubectl logs --previous). Fix the cause and apply again, or run kubectl rollout undo.
Deployment or StatefulSet?
| Deployment | StatefulSet | |
|---|---|---|
| Pod names | Random suffix | Stable ordinals: db-0, db-1 |
| Storage | Shared or none | One PersistentVolumeClaim per Pod |
| Start and stop order | All at once | One at a time, in order |
| Network identity | None | A stable DNS name per Pod |
| Use for | Web apps, APIs, workers | Databases, queues, clustered systems |
If any replica can serve any request, use a Deployment.
Quick reference
| Task | Command |
|---|---|
| Create or update | kubectl apply -f deployment.yaml |
| Change the image | kubectl set image deployment/<name> <container>=<image> |
| Watch a rollout | kubectl rollout status deployment/<name> |
| History | kubectl rollout history deployment/<name> |
| Roll back | kubectl rollout undo deployment/<name> |
| Pause or resume | kubectl rollout pause deployment/<name> |
| Scale | kubectl scale deployment/<name> --replicas=5 |
| Restart all Pods | kubectl rollout restart deployment/<name> |
| List ReplicaSets | kubectl get rs -l app=<label> |
Exercise
You run kubectl scale deployment/shop-api --replicas=6. How many new entries appear in kubectl rollout history?
Show answer
Answer: D. Only changes to the Pod template create a new ReplicaSet and revision. Scaling changes the replica count of the current ReplicaSet.
Exercise
An app must never run two versions at the same time, for example because of an exclusive lock. Which strategy fits?
Show answer
Answer: B. Recreate stops all old Pods before starting new ones, so versions never overlap. The price is a short downtime during each deploy.
Key takeaways
- Deployment manages ReplicaSets, ReplicaSets manage Pods. Each template change creates a new ReplicaSet.
- Old ReplicaSets at zero replicas are what make rollbacks possible. Scaling does not create a revision.
- The selector is immutable.
- A readiness probe is required for safe rolling updates.
maxSurge: 1andmaxUnavailable: 0keep full capacity during deploys.- A failed rollout stops but does not revert.
- Set
kubernetes.io/change-causeso the history means something.
FAQ
What is the difference between a Deployment and a ReplicaSet?
A ReplicaSet keeps a fixed number of identical Pods running. A Deployment manages ReplicaSets over time so you get versioned rollouts, gradual traffic shifts and rollbacks. You almost never create ReplicaSets yourself.
How do I restart all Pods without changing the image?
Run kubectl rollout restart deployment/<name>. It performs a normal rolling update, which is handy to pick up a changed ConfigMap or Secret used as environment variables.
How far back can I roll back?
As far as revisionHistoryLimit allows. Remember that a rollback only reverts Kubernetes objects. It does not undo database migrations or other changes outside the cluster.
When should I use a StatefulSet instead?
When each replica needs a stable identity and its own storage, as databases and quorum-based systems do. If any replica can handle any request, a Deployment is simpler and better.