Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 78 ยท Workloads

Deployments

Learn how Kubernetes Deployments manage ReplicaSets: the manifest, scaling, rollout status, revision history and the controller logic behind them.

A Deployment is the object you will use for almost every stateless application on Kubernetes: web servers, APIs, workers, anything where one pod is as good as another. You describe the pods you want and how many, and the Deployment makes it so. When you later change the description, for example a new image version, it moves the cluster from the old state to the new one gradually and safely.

The trick is that a Deployment does not manage pods itself. It manages ReplicaSets, and each ReplicaSet manages pods. One ReplicaSet exists per version of the pod template, which is exactly what makes updates and rollbacks possible. This lesson covers the manifest, scaling, the commands for watching a rollout, and a Python model of the controller. The mechanics of how the switch between versions happens are in Rolling updates and rollbacks.

Three layers

Deployment Owns the desired version and history.
ReplicaSet One per pod template version.
Pods The running copies.

You edit the top layer; the controllers handle the rest.

1 / 2

A Deployment manifest

This manifest is read-only here; the site has no cluster. It runs three copies of a small web server.

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 3
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: nginx:1.27
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 100m
              memory: 64Mi

Compare it with a ReplicaSet manifest: it is nearly identical. The additions are strategy (how updates happen) and revisionHistoryLimit (how many old ReplicaSets to keep, default 10). The selector is immutable after creation, and it must match the template's labels.

Create and inspect it with these read-only commands:

Terminal
kubectl apply -f web-deployment.yaml
kubectl get deployment web
kubectl get replicaset -l app=web
kubectl get pods -l app=web

The pods get names like web-6f7c9b8d5-k2x9q: the Deployment name, a hash of the pod template (6f7c9b8d5, shared with the ReplicaSet name), and a random suffix. If the middle part changes, the template changed.

What counts as a change

Only edits to spec.template create a new ReplicaSet and trigger a rollout: image, environment variables, command, resources, labels on the pod template and so on. Changing spec.replicas just scales the current ReplicaSet and creates no new revision. Changing labels or annotations on the Deployment's own metadata triggers nothing.

This is why people sometimes force a restart by touching the template, which is what kubectl rollout restart deployment/web does: it adds a kubectl.kubernetes.io/restartedAt annotation to the pod template, which changes the hash and therefore starts a normal rolling update.

Scaling

Terminal
kubectl scale deployment web --replicas=5
kubectl autoscale deployment web --min=3 --max=10 --cpu-percent=70

The first command changes the replica count by hand. If you use GitOps or kubectl apply, prefer editing spec.replicas in the file, otherwise the next apply will reset it. If an autoscaler is in charge (see the Horizontal Pod Autoscaler), remove replicas from the manifest so the two do not fight.

Watching a rollout

A Deployment reports progress in its status and through the rollout subcommands:

Terminal
kubectl set image deployment/web web=nginx:1.28
kubectl rollout status deployment/web
kubectl rollout history deployment/web
kubectl describe deployment web

rollout status blocks until the rollout finishes or fails. Typical output while waiting looks like:

TEXT
Waiting for deployment "web" rollout to finish: 1 out of 3 new replicas have been updated...
Waiting for deployment "web" rollout to finish: 2 out of 3 new replicas have been updated...
Waiting for deployment "web" rollout to finish: 1 old replicas are pending termination...
deployment "web" successfully rolled out

(Written from knowledge of kubectl's behavior, since no cluster was available.) The exit code is 0 on success and non-zero if the rollout exceeds progressDeadlineSeconds (default 600 seconds), which makes the command handy in CI scripts.

The status fields to know:

  • replicas: total pods across all ReplicaSets of this Deployment.
  • updatedReplicas: pods running the newest template.
  • readyReplicas: pods that pass their readiness checks.
  • availableReplicas: pods that have been ready for at least minReadySeconds.
  • conditions: Available, Progressing and, if things go wrong, ReplicaFailure.

The controller, in Python

The Deployment controller is a reconcile loop like the one for ReplicaSets, one level up. On every pass it hashes the pod template, looks for an existing ReplicaSet with that hash, creates one if none exists, and then adjusts replica counts. The stand-in below does that, with a trivially simple "scale the new one to the target, old ones to zero" rule (the real controller does this gradually; see the next lesson). The hash is not Kubernetes' real hash function, just a short digest to show the idea.

Python A Deployment controller creating ReplicaSets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at step 5. Putting the old template back finds the existing ReplicaSet with the same hash and reuses it instead of making a new one. That is exactly how Kubernetes rollbacks work: a rollback is "make the pod template equal to an earlier revision's template", and the old ReplicaSet is simply scaled back up.

Validating a Deployment

Many mistakes in a Deployment are mechanical: a selector that does not match the template labels, a missing image, a replica count that is not a number. The stand-in below parses a manifest with a simple dictionary and checks the most common rules. It is a teaching aid, not a replacement for kubectl apply --dry-run=server or schema validators such as kubeconform.

Python Check the selector and template

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Good habits

  • Pin image tags (or better, digests) so a rollout always means a deliberate change, and :latest never silently changes under you.
  • Always set readiness probes (see probes). The rollout only advances when new pods are ready; without a probe, "ready" just means "started".
  • Set resource requests so the scheduler can place pods sensibly and autoscalers have a baseline.
  • Use kubectl diff -f file.yaml before applying to see what would change.
  • Label with the recommended keys such as app.kubernetes.io/name and app.kubernetes.io/version.
  • Do not edit the ReplicaSets or pods a Deployment owns; the controller will revert you.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which edit to a Deployment creates a new ReplicaSet?

    Only changes to spec.template alter the pod template hash and so create a new ReplicaSet. Scaling just changes the count on the current one.
  2. 2. What does kubectl rollout restart deployment/web actually change?

    The annotation changes the template, so the Deployment controller creates a new ReplicaSet and rolls pods over gradually.
  3. 3. Why does a rollback reuse an old ReplicaSet instead of creating a new one?

    Deployments keep old ReplicaSets (up to revisionHistoryLimit) scaled to zero. A matching template finds one and scales it up again.
  4. 4. A Deployment's selector says app: web but the template labels say app: site. What happens when you apply it?

    The API validates that the template labels satisfy the selector, since otherwise the controller could never find the pods it creates.
  5. 5. Which status field counts pods that have been ready for at least minReadySeconds?

    availableReplicas adds the minReadySeconds requirement on top of readiness, protecting rollouts from pods that flap.

Summary

  • A Deployment manages ReplicaSets, one per pod template version, and those manage pods.
  • Only changes to spec.template start a rollout; changing replicas just scales.
  • kubectl rollout status, history and describe show progress, and status fields tell you updated, ready and available counts.
  • A rollback finds the old ReplicaSet with the matching template and scales it up again.
  • Pin image tags, add readiness probes and requests, and never edit the objects a Deployment owns.

Next: Rolling updates and rollbacks.