Lesson 3 of 8 in Kubernetes

Deployments: replicas, rollouts and rollbacks

Core13 min

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

Who owns what
Who owns whatA Deployment owns a ReplicaSet, the ReplicaSet keeps the Pods running, and an older ReplicaSet is kept for rollback.1 owns thecurrent one2 keeps 3running3 keeps for rollbackDeploymentyour desired versionReplicaSetkeeps N Pods alivePods3 copiesOld ReplicaSetscaled to 0, kept
  • Control
  • Runs code
  • Other

A Deployment owns a ReplicaSet, the ReplicaSet keeps the Pods running, and an older ReplicaSet is kept for rollback.

  1. Deployment to ReplicaSet: 1 owns the current one
  2. ReplicaSet to Pods: 2 keeps 3 running
  3. Deployment to Old ReplicaSet: 3 keeps for rollback
What a rolling update does
What a rolling update doesYou 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.1 change theimage2 add newPods3 remove old PodsYouset a new imageDeploymentNew ReplicaSetscales upOld ReplicaSetscales down
  • 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.

  1. You to Deployment: 1 change the image
  2. Deployment to New ReplicaSet: 2 add new Pods
  3. 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.

  1. 1
    Create 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
  2. 2
    Delete 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.

  3. 3
    Roll 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.

  4. 4
    Roll 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, then ImagePullBackOff. The old Pods keep serving because the new ones never became Ready.

  5. 5
    Roll back
    kubectl rollout undo deployment/web
    kubectl rollout status deployment/web
  6. 6
    Clean 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 with docker pull <image> on your machine.
  • kubectl rollout status hangs, 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, then kubectl describe on a new Pod. Fix the cause or run kubectl rollout undo deployment/web.
  • kubectl apply fails 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 with kubectl delete deployment web and 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.

Lesson 72 of 92 in the DevOps path

Search

Search cheat sheets and projects