ReplicaSets and Deployments: Why You Almost Never Create a ReplicaSet Directly

What a ReplicaSet does

A ReplicaSet's sole responsibility is maintaining a desired number of pod replicas. It watches for pods matching its label selector. If a pod is deleted, it creates a replacement. If there are too many pods matching its selector, it deletes the excess. It doesn't know how to update pods — that's not its job.

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
      version: v1.2.3
  template:
    metadata:
      labels:
        app: api
        version: v1.2.3
    spec:
      containers:
      - name: api
        image: myapp:1.2.3

Why Deployments exist: the update problem

If you need to update a ReplicaSet (new image version), you have to delete the old ReplicaSet and create a new one. During the transition, you either have 0 pods (downtime) or you manage the overlap manually. ReplicaSets have no concept of gradual rollout.

Deployments solve this by owning multiple ReplicaSets and managing transitions between them:

Deployment: api
├── ReplicaSet: api-7d9f4b6c5 (image: myapp:1.2.2) → 0 replicas (after rollout)
└── ReplicaSet: api-8a3c2e1f7 (image: myapp:1.2.3) → 3 replicas (current)

During a rolling update:

1. Deployment creates a new ReplicaSet with the updated pod template
2. New RS scales up by maxSurge pods
3. Old RS scales down by maxUnavailable pods
4. Repeat until new RS has all replicas and old RS has 0

The old ReplicaSet is kept (with 0 replicas) as rollback history. kubectl rollout undo deployment/api scales the old RS back up and scales the new RS down.

# View rollout status
kubectl rollout status deployment/api

# View rollout history
kubectl rollout history deployment/api

# Rollback to previous version
kubectl rollout undo deployment/api

# Rollback to a specific revision
kubectl rollout undo deployment/api --to-revision=2

# View what changed in a specific revision
kubectl rollout history deployment/api --revision=3

How the ReplicaSet selector connects to Deployment

Every Deployment generates ReplicaSet names by hashing the pod template. The hash appears in both the ReplicaSet name and the pod names:

$ kubectl get replicasets
NAME               DESIRED   CURRENT   READY   AGE
api-7d9f4b6c5      3         3         3       2d
api-8a3c2e1f7      0         0         0       5d

$ kubectl get pods
NAME                     READY   STATUS    RESTARTS   AGE
api-7d9f4b6c5-x2q8p      1/1     Running   0          2d
api-7d9f4b6c5-m9kl7      1/1     Running   0          2d
api-7d9f4b6c5-p4nr2      1/1     Running   0          2d

The Deployment selects ReplicaSets using pod-template-hash. Each ReplicaSet selects pods using both the user-defined labels and the pod-template-hash:

# ReplicaSet's selector (managed by Deployment, not user-editable)
selector:
  matchLabels:
    app: api
    pod-template-hash: "7d9f4b6c5"  # added automatically by Deployment

This hash isolation prevents the "dangerous pod adoption" problem — ReplicaSets under a Deployment can't accidentally adopt pods from other ReplicaSet versions.

spec:
  revisionHistoryLimit: 3   # keep last 3 ReplicaSets for rollback

# Clean up old ReplicaSets manually (if revisionHistoryLimit was 0 or cleanup failed)
kubectl get rs -l app=api | grep " 0 " | awk '{print $1}' | xargs kubectl delete rs

When you'd create a ReplicaSet directly

Direct ReplicaSet creation is rare. Two situations where it makes sense:

1. Custom controllers: building an operator that manages pod groups with custom update logic. You create ReplicaSets directly and manage transitions yourself.

2. Testing scenarios: creating a fixed set of pods that must never be updated in place (no rolling update). A bare ReplicaSet can't be triggered into a rolling update — updating the spec replaces the ReplicaSet entirely.

For any production workload where you want updates, rollback, and change tracking, use a Deployment.