Deployments

4 minute read

The Deployment is the most commonly used resource in Kubernetes. It manages ReplicaSets and provides declarative updates, rolling updates, rollbacks, and scaling — everything you need to run applications in production.

What is a Deployment?

A Deployment provides declarative updates to Pods and ReplicaSets. You describe a desired state in a Deployment spec, and the Deployment controller changes the actual state to match.

Deployments manage:

  • Creating and managing ReplicaSets
  • Rolling out new versions with zero downtime
  • Rolling back to previous versions
  • Scaling replicas up or down
  • Pausing and resuming updates
Deployment  ─manages─►  ReplicaSet  ─manages─►  Pods
                              │
                        ┌─────┼─────┐
                        ▼     ▼     ▼
                      Pod1  Pod2  Pod3

Creating a Deployment

Imperative (quick way)

kubectl create deployment nginx --image=nginx:1.27 --replicas=3

Create deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1           # Max Pods above desired count during update
      maxUnavailable: 0     # No Pods below desired count during update
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.27
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"

Apply it:

kubectl apply -f deployment.yaml

Inspecting a Deployment

# List Deployments
kubectl get deployments
# Shorthand: kubectl get deploy

# Detailed info
kubectl describe deployment nginx-deployment

# See the ReplicaSet it created
kubectl get replicasets

# See the Pods
kubectl get pods -l app=nginx

# Check rollout status
kubectl rollout status deployment/nginx-deployment

Output for kubectl get deployments:

NAME               READY   UP-TO-DATE   AVAILABLE   AGE
nginx-deployment   3/3     3            3           45s

Scaling

# Scale to 5 replicas
kubectl scale deployment nginx-deployment --replicas=5

# Or edit the YAML and re-apply
# Change replicas: 5 in deployment.yaml
kubectl apply -f deployment.yaml

# Verify
kubectl get deployment nginx-deployment

Rolling Updates

This is where Deployments truly shine. Update the container image and Kubernetes will gradually replace old Pods with new ones — zero downtime.

Trigger an Update

# Update the image
kubectl set image deployment/nginx-deployment nginx=nginx:1.27.3

# Watch the rollout
kubectl rollout status deployment/nginx-deployment

What Happens During a Rolling Update

With maxSurge: 1 and maxUnavailable: 0 (from our YAML):

Step 1: Create 1 new Pod (v1.27.3)     → 3 old + 1 new = 4 total
Step 2: New Pod is Ready               → Terminate 1 old Pod
Step 3: Create another new Pod          → 2 old + 2 new = 4 total
Step 4: New Pod is Ready               → Terminate 1 old Pod
Step 5: Create last new Pod             → 1 old + 3 new = 4 total
Step 6: New Pod is Ready               → Terminate last old Pod
Done:   0 old + 3 new = 3 total ✅

The key point: at no time are there fewer than 3 Pods available (our desired replica count).

Update Strategies

Strategy Behavior
RollingUpdate (default) Gradually replaces old Pods with new ones
Recreate Kills all old Pods first, then creates new ones (causes downtime) 
# Zero-downtime rolling update
strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 1
    maxUnavailable: 0

# Recreate (use when you can't run two versions simultaneously)
strategy:
  type: Recreate

Rollbacks

Made a mistake? Roll back to the previous version:

# Roll back to the previous revision
kubectl rollout undo deployment/nginx-deployment

# Roll back to a specific revision
kubectl rollout undo deployment/nginx-deployment --to-revision=2

# Check rollout history
kubectl rollout history deployment/nginx-deployment

# See details of a specific revision
kubectl rollout history deployment/nginx-deployment --revision=2

How Rollback Works

When you update a Deployment, Kubernetes creates a new ReplicaSet and scales it up while scaling down the old one. The old ReplicaSet isn’t deleted — it’s kept with 0 replicas. Rolling back simply scales the old ReplicaSet back up.

Before update:
  ReplicaSet-v1 (3 replicas) ← active

After update to v2:
  ReplicaSet-v1 (0 replicas) ← kept for rollback
  ReplicaSet-v2 (3 replicas) ← active

After rollback:
  ReplicaSet-v1 (3 replicas) ← active again
  ReplicaSet-v2 (0 replicas)

Tip: Set spec.revisionHistoryLimit to control how many old ReplicaSets are kept (default: 10).

Pause and Resume

For complex updates, you can pause a rollout, make multiple changes, then resume:

# Pause the Deployment
kubectl rollout pause deployment/nginx-deployment

# Make multiple changes without triggering a rollout each time
kubectl set image deployment/nginx-deployment nginx=nginx:1.27.3
kubectl set resources deployment/nginx-deployment -c=nginx --limits=memory=256Mi

# Resume — triggers a single rollout with all changes
kubectl rollout resume deployment/nginx-deployment

Deployment YAML — Full Example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
  labels:
    app: web-app
  annotations:
    kubernetes.io/change-cause: "Initial deployment v1.0"
spec:
  replicas: 3
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      app: web-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  minReadySeconds: 10              # Wait 10s before considering a Pod ready
  progressDeadlineSeconds: 600     # Fail if update takes longer than 10 minutes
  template:
    metadata:
      labels:
        app: web-app
        version: "1.0"
    spec:
      containers:
      - name: web-app
        image: my-web-app:1.0
        ports:
        - containerPort: 8080
        resources:
          requests:
            memory: "128Mi"
            cpu: "250m"
          limits:
            memory: "256Mi"
            cpu: "500m"
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 15
          periodSeconds: 20

Common Commands Cheat Sheet

Command Description
kubectl create deploy NAME --image=IMAGE Create a Deployment
kubectl get deploy List Deployments
kubectl describe deploy NAME Detailed info
kubectl scale deploy NAME --replicas=N Scale
kubectl set image deploy NAME CONTAINER=IMAGE Update image
kubectl rollout status deploy NAME Watch rollout
kubectl rollout history deploy NAME View history
kubectl rollout undo deploy NAME Rollback
kubectl rollout pause deploy NAME Pause rollout
kubectl rollout resume deploy NAME Resume rollout
kubectl delete deploy NAME Delete Deployment

Summary

  • Deployments are the go-to resource for running stateless applications
  • They manage ReplicaSets which manage Pods
  • Rolling updates provide zero-downtime deployments
  • Rollbacks let you revert to any previous revision
  • Always use the declarative approach (YAML files in Git)
  • Set resource requests/limits and health checks for production workloads

What’s Next?

Your Pods are running, but how do other Pods (or external users) reach them? In the next chapter, we’ll learn about Services — Kubernetes’ built-in service discovery and load balancing.

Next: Services →

Updated:

You may also enjoy