Lesson 3 of 8 in Kubernetes
Deployments: replicas, rollouts and rollbacks
A Deployment describes how many identical Pods you want and which container image they run. It creates a ReplicaSet to keep that count, and it replaces the ReplicaSet gradually when you change the Pod template.
Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.
Read these first: Pods: the smallest thing Kubernetes runs
The problem this solves
A bare Pod does not come back when it dies, and a Pod cannot be upgraded in place. To release a new version you need to start new Pods, wait until they are healthy, and only then stop the old ones. Doing that by hand risks downtime.
A Deployment does this for you. It keeps the right number of Pods running, swaps old Pods for new ones in small steps, and remembers earlier versions so you can go back.
How it works
- Control
- Runs code
- Other
A Deployment owns a ReplicaSet, the ReplicaSet keeps the Pods running, and an older ReplicaSet is kept for rollback.
- Deployment to ReplicaSet: 1 owns the current one
- ReplicaSet to Pods: 2 keeps 3 running
- Deployment to Old ReplicaSet: 3 keeps for rollback
- People and clients
- Control
- Other
You change the image, the Deployment starts a new ReplicaSet and scales it up, and it scales the old ReplicaSet down as new Pods become Ready.
- You to Deployment: 1 change the image
- Deployment to New ReplicaSet: 2 add new Pods
- Deployment to Old ReplicaSet: 3 remove old Pods
You rarely touch ReplicaSets. The Deployment creates one for each version of the Pod template. The ReplicaSet's only job is to keep the number of matching Pods equal to replicas. Delete a Pod and the ReplicaSet makes another.
When you change the Pod template, for example the image, the Deployment creates a new ReplicaSet and moves Pods across in steps. By default it allows a little extra capacity during the change and never takes more than a quarter of the Pods out of service. It only removes old Pods as new ones report Ready.
Because the old ReplicaSet is kept at zero replicas, kubectl rollout undo can scale it back up. Changing only replicas does not create a new version.
Try it yourself
Run these in a throwaway folder on your kind cluster.
- 1Create a Deployment with 3 replicas
cat > web.yaml <<'EOF' apiVersion: apps/v1 kind: Deployment metadata: name: web spec: replicas: 3 selector: matchLabels: app: web template: metadata: labels: app: web spec: containers: - name: nginx image: nginx:1.27 ports: - containerPort: 80 EOF kubectl apply -f web.yaml kubectl rollout status deployment/web kubectl get pods -l app=web - 2Delete a Pod and watch it return
kubectl delete pod <pod-name> kubectl get pods -l app=web
Use a real name from the previous list. A replacement appears with a new name, because the ReplicaSet restored the count of 3.
- 3Roll out a new image
kubectl set image deployment/web nginx=nginx:1.27-alpine kubectl rollout status deployment/web kubectl rollout history deployment/web
nginx=names the container inside the Pod template, not the image. History now lists two revisions. - 4Roll out a broken image
kubectl set image deployment/web nginx=nginx:this-tag-does-not-exist kubectl get pods -l app=web
After a few seconds some new Pods show
ErrImagePull, thenImagePullBackOff. The old Pods keep serving because the new ones never became Ready. - 5Roll back
kubectl rollout undo deployment/web kubectl rollout status deployment/web
- 6Clean up
kubectl delete -f web.yaml rm web.yaml
What breaks, and where to look
Pods show ErrImagePull and then ImagePullBackOff.
- WHY IT HAPPENS
- The node cannot download the image. The usual causes are a typo in the name or tag, a tag that does not exist, or a private registry with no pull credentials.
- CHECK FIRST
- Run
kubectl describe pod <pod-name>and read the Events for the exact pull error. Confirm the same name and tag works withdocker pull <image>on your machine.
kubectl rollout statushangs, then prints: error: deployment "web" exceeded its progress deadline.- WHY IT HAPPENS
- New Pods never became Ready, for example because the image cannot be pulled or the app crashes. After the progress deadline the Deployment reports the rollout as failed but does not undo it.
- CHECK FIRST
- Run
kubectl get pods -l app=web, thenkubectl describeon a new Pod. Fix the cause or runkubectl rollout undo deployment/web.
kubectl applyfails with a message that spec.selector is invalid and the field is immutable.- WHY IT HAPPENS
- You changed the label selector of an existing Deployment. The selector ties a Deployment to its Pods and cannot be edited after creation.
- CHECK FIRST
- Keep the original
matchLabels, or delete the Deployment withkubectl delete deployment weband apply the new manifest.
When not to use this
- Do not use a Deployment for programs that need a stable identity and their own disk per copy, such as databases. StatefulSet exists for that, and many teams use a managed database instead.
- A rolling update only protects you if the readiness check is honest. Without a readiness probe, Kubernetes treats a Pod as ready as soon as its container starts.
Check yourself
What keeps the number of Pods at the value in replicas?
The ReplicaSet that the Deployment created. The Deployment manages ReplicaSets, and ReplicaSets manage Pods.
Why does the old version keep serving during a failed rollout?
A rolling update removes old Pods only as new ones become Ready. If the new Pods never become Ready, the old ones stay.
How do you go back to the previous version?
kubectl rollout undo deployment/<name>. The Deployment scales its previous ReplicaSet back up.
Keep going
Lesson 72 of 92 in the DevOps path