sdlc.dev

Kubernetes path · Running and reaching your app · Topic 4 of 13

Deployments, rolling updates and rollbacks

Not started

A Deployment describes a pod template and how many copies of it you want. It does not manage pods itself: it creates a ReplicaSet for the current template, and the ReplicaSet keeps the right number of pods alive. When you change the template (usually the image), the Deployment creates a second ReplicaSet and shifts pods from the old one to the new one in steps. The old ReplicaSet is kept, scaled to zero, as the record you roll back to.

Why it matters: Most production changes in Kubernetes are a Deployment rollout. Knowing how it swaps pods tells you why a bad readiness probe stalls it and how to get back fast.

  1. 1Deployment, ReplicaSet, Pods

    A Deployment manages ReplicaSets; a ReplicaSet keeps N identical pods running. Each change to the pod template creates a new ReplicaSet.

  2. 2Rolling by default

    The RollingUpdate strategy scales the new ReplicaSet up and the old one down in steps, bounded by maxSurge and maxUnavailable (25% each by default).

  3. 3Readiness gates the rollout

    Old pods are only removed as new ones become ready, so a version that never gets ready stalls the rollout instead of replacing everything.

  4. 4Rollback is a re-rollout

    kubectl rollout undo scales an earlier ReplicaSet back up; Kubernetes keeps 10 old ReplicaSets by default for this.

1

How it works

The explanation, with examples you can run.

The manifest

apiVersion: apps/v1kind: Deploymentmetadata:  name: webspec:  replicas: 4  revisionHistoryLimit: 10  selector:    matchLabels:      app: web  strategy:    type: RollingUpdate    rollingUpdate:      maxSurge: 25%          # the defaults, written out      maxUnavailable: 25%  template:    metadata:      labels:        app: web    spec:      containers:        - name: app          image: ghcr.io/acme/web:1.4.2          ports:            - containerPort: 3000

The selector must match the template's labels; it is how the Deployment finds its ReplicaSets and pods, and it cannot be changed later.

A rolling update, step by step

kubectl set image deployment/web app=ghcr.io/acme/web:1.5.0kubectl rollout status deployment/webkubectl get rs -l app=web# NAME             DESIRED   CURRENT   READY# web-7c9d8f6b5d   0         0         0       <- 1.4.2, kept for rollback# web-5f4b7d9c8e   4         4         4       <- 1.5.0

With 4 replicas, 25% rounds to one pod each way: the controller may run up to 5 pods and must keep at least 3 available. It starts a new pod, waits for it to become ready, removes an old one, and repeats. The word "ready" carries the whole rollout: a new pod counts only when its readiness probe passes (and it has been ready for minReadySeconds, if set). That is what stops a broken version from replacing every working pod.

If new pods never become ready, the rollout stops making progress. After progressDeadlineSeconds (600 by default) the Deployment's Progressing condition turns false with reason ProgressDeadlineExceeded, which kubectl rollout status reports as an error. Kubernetes does not roll back on its own.

Rolling back

kubectl rollout history deployment/webkubectl rollout undo deployment/web                  # back to the previous revisionkubectl rollout undo deployment/web --to-revision=3

Undo copies an old ReplicaSet's template back into the Deployment, and the same rolling process runs in reverse. It is fast because the old images are usually still cached on the nodes. If you manage manifests in git (or with Argo CD or Flux), revert the commit too, or the next sync will roll forward again.

Other strategies and helpers

  • strategy: Recreate stops all old pods before starting new ones: downtime, but never two versions at once (useful when versions cannot coexist).
  • Set maxUnavailable: 0 for zero lost capacity during rollouts, at the cost of needing room for surge pods.
  • Canary and blue-green releases need traffic splitting (Gateway API weights, a service mesh, or tools such as Argo Rollouts).
  • A PodDisruptionBudget limits how many pods voluntary disruptions, such as node drains, may take at once. Rollouts are governed by the strategy instead.
  • Version tags are mutable; deploy by digest (or at least unique tags) so a rollback really returns to the old bits.
2

Check yourself

3 questions. Get them all right to finish this topic.

  1. 1.A Deployment has replicas: 4 and the default strategy. During a rollout, what are the bounds on the pod count?
  2. 2.The new version's pods never pass their readiness probe. What happens with the default strategy?
  3. 3.What does a change to the replica count create?

0 of 3 right so far. Get all three to finish this topic.

Go deeper