How Do ReplicaSets Work in Kubernetes?

Detailed Answer

A ReplicaSet is a Kubernetes controller that ensures a specified number of Pod replicas are running at any given time. While you will rarely create one directly (Deployments handle that), understanding how ReplicaSets work is essential for debugging and understanding the Kubernetes resource model.

The Core Reconciliation Loop

A ReplicaSet controller runs a continuous loop:

1. Observe: Count the Pods that match the ReplicaSet's label selector.
2. Compare: Check if the actual count matches the desired replicas value.
3. Act:
   • If actual < desired: create new Pods.
   • If actual > desired: delete excess Pods.
   • If actual == desired: do nothing.

This is the fundamental desired state reconciliation pattern that drives all of Kubernetes.

ReplicaSet Manifest

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: web-app-v1
  labels:
    app: web-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web-app
      version: v1
  template:
    metadata:
      labels:
        app: web-app
        version: v1
    spec:
      containers:
        - name: web-app
          image: web-app:1.0
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: 100m
              memory: 128Mi

Key rules:

• selector.matchLabels must be a subset of template.metadata.labels. The template can have additional labels, but must include all selector labels.
• The selector is immutable after creation.
• The template defines the Pod spec that new replicas will use.

How Deployments Use ReplicaSets

When you create a Deployment, it creates a ReplicaSet behind the scenes:

Deployment: web-app
  │
  ├── ReplicaSet: web-app-6b9d5c7f8  (revision 1, 0 replicas)
  ├── ReplicaSet: web-app-7c8e6d9a1  (revision 2, 0 replicas)
  └── ReplicaSet: web-app-8d9f7e0b2  (revision 3, 3 replicas)  ← current

Each time you update the Pod template, a new ReplicaSet is created. The Deployment controller orchestrates the scaling between old and new ReplicaSets.

# See ReplicaSets for a Deployment
kubectl get replicasets -l app=web-app

# See which Deployment owns a ReplicaSet
kubectl get replicaset web-app-8d9f7e0b2 -o jsonpath='{.metadata.ownerReferences[0].name}'

The pod-template-hash Label

Kubernetes automatically adds a pod-template-hash label to each ReplicaSet and its Pods:

kubectl get pods --show-labels

Output:

NAME                       LABELS
web-app-8d9f7e0b2-abc12   app=web-app,pod-template-hash=8d9f7e0b2
web-app-8d9f7e0b2-def34   app=web-app,pod-template-hash=8d9f7e0b2
web-app-8d9f7e0b2-ghi56   app=web-app,pod-template-hash=8d9f7e0b2

This hash ensures that Pods from different ReplicaSets (different revisions of the same Deployment) do not overlap, even if they share the same app label.

Label Selector Mechanics

ReplicaSets support two types of selectors:

matchLabels (equality-based)

selector:
  matchLabels:
    app: web-app
    version: v1

Matches Pods that have both app=web-app AND version=v1.

matchExpressions (set-based)

selector:
  matchExpressions:
    - key: app
      operator: In
      values: ["web-app"]
    - key: environment
      operator: NotIn
      values: ["test"]

Supports operators: In, NotIn, Exists, DoesNotExist.

Orphaned Pods and Adoption

If you change a Pod's labels so it no longer matches the ReplicaSet's selector, the Pod becomes orphaned:

# Remove a Pod from its ReplicaSet (for debugging)
kubectl label pod web-app-8d9f7e0b2-abc12 app- --overwrite

The ReplicaSet sees only 2 matching Pods and creates a third. The orphaned Pod continues running but is no longer managed. This is a useful debugging technique -- you can pull a misbehaving Pod out of rotation without losing it.

Conversely, if an unmanaged Pod's labels match a ReplicaSet's selector, the ReplicaSet adopts it. If the total count then exceeds the desired replicas, the ReplicaSet deletes the excess.

Scaling a ReplicaSet

# Direct scaling (rarely done in practice)
kubectl scale replicaset web-app-8d9f7e0b2 --replicas=5

However, if a Deployment manages this ReplicaSet, the Deployment controller will immediately scale it back. Always scale via the Deployment.

Pod Deletion Priority

When scaling down, the ReplicaSet controller deletes Pods in this priority order:

1. Pods in a Pending or unschedulable state.
2. Pods on nodes with the most replicas of this ReplicaSet (spreading across nodes).
3. Pods that have been Ready for the shortest time.
4. Pods with the most recent creation timestamp.

This heuristic ensures the healthiest, most distributed Pods survive a scale-down.

ReplicaSet vs. ReplicationController

ReplicationController is the predecessor to ReplicaSet. Key differences:

| Feature | ReplicationController | ReplicaSet | |---|---|---| | Selector type | Equality-based only | Equality and set-based | | Used by Deployments | No | Yes | | Status | Deprecated | Current |

Always use ReplicaSets (or better, Deployments).

Summary

ReplicaSets are the workhorse behind Kubernetes Deployments. They maintain the desired Pod count through a continuous reconciliation loop, using label selectors to identify their Pods. While you should almost always interact with Deployments rather than ReplicaSets directly, understanding how ReplicaSets work is essential for debugging rollout issues, understanding Pod adoption and orphaning, and grasping the Kubernetes controller model.