Kubernetes
Intermediate 16 min read Kubernetes

Deployments & ReplicaSets

Deployments declare the desired state of a replicated workload and manage ReplicaSets, which own the pods. Master rolling updates, scaling, rollouts, rollbacks and the self-healing loop.

DeploymentReplicaSetreplicasrolling updaterolloutrollbackmaxSurgemaxUnavailable
Prerequisites: Pods & Containers
Introduction

What is this?

A Deployment declares the desired state of a replicated workload: how many replicas, which image and version, and the update strategy. It creates and manages ReplicaSets, and each ReplicaSet owns and reconciles a set of pods. This gives you self-healing, declarative scaling and safe rolling updates and rollbacks out of the box.

Motivation

Why do you need it?

  • Self-healing: if a pod dies or a node fails, the ReplicaSet creates a replacement immediately.
  • Rolling updates and rollbacks are declarative — kubectl rollout undo reverses a bad release.
  • Scaling is a one-liner and every change is recorded as an auditable revision.
  • Deployments are the standard controller for stateless workloads and the foundation for autoscaling.
Think about it

Mental model

Imagine

A project manager and team leads

Think of

Deployment, ReplicaSet and Pods

The Deployment (PM) sets the goal: three developers on the project. The ReplicaSet (team lead) hires and replaces developers to keep the team at three. Pods (developers) do the actual work.

Mechanics

How it works

  • The Deployment creates a ReplicaSet whose only job is to keep the declared number of healthy pods running.
  • The ReplicaSet owns pods through the pod template labels, which are immutable once the Deployment exists.
  • A rollout creates a new ReplicaSet and scales it up while scaling the old one down, honoring maxSurge and maxUnavailable.
  • The deployment controller watches pod status and immediately replaces failed pods.
  • A rollback scales the previous revision ReplicaSet back up and the current one down.

The Deployment to ReplicaSet to Pod hierarchy during a rollout.

Deployment
ReplicaSet
Pod replicas
Health check
Rollout
Available
Reference

Key commands

kubectl create deployment nginx --image=nginx:1.25

Create a Deployment with one replica from the nginx image.

kubectl get deployments -o wide

Show desired, ready and available replica counts plus the image.

NAME    READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS   IMAGES       SELECTOR
nginx   3/3     3            3           4m    nginx        nginx:1.25   app=nginx
kubectl scale deployment nginx --replicas=5

Declaratively change the replica count.

kubectl set image deployment/nginx nginx=nginx:1.26

Trigger a rolling update by changing the container image.

kubectl rollout status deployment/nginx

Block until the current rollout completes or fails.

kubectl rollout undo deployment/nginx

Roll back to the previous revision.

kubectl rollout history deployment/nginx

List the deployment revision history.

Hands-on

Examples

A Deployment with a rolling update strategy

A Deployment with a rolling update strategy
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
        ports:
        - containerPort: 80

The Deployment wants 3 nginx pods at all times. maxUnavailable: 0 and maxSurge: 1 mean a rollout adds one new pod before removing any old pod, so there is no capacity dip. The selector matches the template labels, which is what ties the Deployment to its ReplicaSets.

Real world

In production

  • GitOps applies the same deployment manifest everywhere; version bumps are just manifest updates.
  • Tuning maxUnavailable and maxSurge controls how fast a release rolls out and how much capacity dips.
  • The HorizontalPodAutoscaler scales deployment replicas based on CPU or custom metrics.
  • Rollout history makes every image change auditable and reversible with one command.
Guidelines

Best practices

  • Use kubectl apply with versioned manifests from git; never hand-edit live objects.
  • Pin image versions and avoid :latest so rollouts are reproducible.
  • Set readiness probes so new pods only receive traffic when actually ready.
  • Keep revisionHistoryLimit modest (for example 10) to bound etcd usage.
  • Use one deployment per workload per environment with clean label selectors.
Watch out

Common mistakes

  • Changing the pod template selector after creation — it is immutable and the Deployment will error.
  • Reusing the same labels for template and selector so ReplicaSets overlap and fight.
  • Rolling out with broken readiness probes, so maxUnavailable waits forever.
  • Forgetting that plain kubectl run creates a Deployment, surprising users who wanted a pod.
Root cause analysis

Common issues

Error
Pods stuck in Pending, 0/N nodes available: Insufficient cpu
Root cause

The cluster has no node with enough allocatable CPU for the replica requests.

Fix

Scale down, raise node capacity, or lower the CPU requests on the container.

Error
Invalid value: ... spec.selector does not match template labels
Root cause

The selector and template labels diverged, and selectors are immutable.

Fix

The selector cannot be edited in place; recreate the Deployment with matching labels.

Error
Rollout stuck: progress deadline exceeded
Root cause

New pods never become ready, often due to image pull failures or failing readiness probes.

Fix

Check kubectl get pods and kubectl describe pod for ImagePullBackOff or probe failures, fix the cause, then kubectl rollout status again.

When things break

Debugging tips

  • kubectl describe deployment <name> shows ReplicaSet events and rollout errors.
  • kubectl rollout status deployment/<name> reports rollout progress and failures.
  • kubectl get rs shows the old and new ReplicaSets side by side during a rollout.
  • kubectl rollout undo deployment/<name> is the fastest first move after a bad release.
Interviews

Interview checkpoint

Practice

Hands-on lab

Scaling, Rolling Updates and Rollbacks
35 min · intermediate
In progress
Objectives
  • Create and scale a Deployment
  • Verify self-healing behavior
  • Trigger and watch a rolling update
  • Roll back to a previous image revision

Scaling, Rolling Updates and Rollbacks

35 min · intermediate

0/6 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/3
1

What does a Deployment use to manage its pod replicas?

2

Deleting a pod owned by a Deployment results in a replacement pod being created.

3

Which command rolls a Deployment back to its previous revision?

Quick reference

Cheat sheet

Deployments
kubectl create deployment app --image=imgCreate a Deployment
kubectl get deployment -o wideStatus and image
kubectl scale deployment app --replicas=5Change replica count
kubectl set image deployment/app c=img:v2Update container image
kubectl rollout status deployment/appWait for rollout
kubectl rollout undo deployment/appRoll back a release
kubectl rollout history deployment/appList revisions
Go deeper

Official documentation

Deployments
docs
ReplicaSet
docs
Rolling updates and rollbacks
docs
kubectl run reference
docs