Kubernetes ReplicaSet Controller

Kubernetes ReplicaSet Controller is the control loop that maintains a fixed, specified number of interchangeable Pod replicas matching a given label selector, creating new Pods when the observed count falls short and deleting excess Pods when it exceeds the desired number. It is the simplest of the workload controllers in terms of the guarantee it provides, replica count alone, with no concept of ordering, identity, or rollout history, and it typically operates as a subordinate object managed by a Deployment rather than being created directly.

The Core Guarantee: Replica Count

Desired Versus Observed

A ReplicaSet's entire responsibility is ensuring the number of Pods matching its selector equals spec.replicas. It has no preference for which specific Pods fulfill that count; any Pod matching the selector counts identically toward satisfying it, regardless of when it was created or what node it runs on.

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: replicaset-controller-example
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: app
          image: registry.example.com/app:1.0.0

Reaction to Deviation

Scaling Up on Shortfall

If the observed count of matching Pods drops below spec.replicas, whether due to manual deletion, node failure, or a Pod entering a terminal Failed phase, the controller creates new Pods from its template, in parallel if multiple are needed, to close the gap.

Scaling Down on Excess

If the observed count exceeds spec.replicas, for instance after a manual scale-down or an adoption event that brought in additional matching Pods, the controller deletes the excess, using a deterministic priority order that prefers removing Pods that are not yet ready, have restarted more, or are newer, before removing older, stable Pods.

kubectl scale replicaset replicaset-controller-example --replicas=5

Adoption and Ownership Reconciliation

Claiming Matching, Unowned Pods

If a Pod exists without a controlling owner but matches the ReplicaSet's selector, the controller adopts it by setting itself as the controlling ownerReference, folding it into the managed count without creating a redundant new Pod.

metadata:
  ownerReferences:
    - apiVersion: apps/v1
      kind: ReplicaSet
      name: replicaset-controller-example
      controller: true

Releasing Pods That No Longer Match

If a previously owned Pod's labels change such that it no longer satisfies the selector, the controller releases it, removing it from its managed count and creating a replacement to restore the desired total, while the released Pod continues running independently.

Relationship to Deployments

Usually a Managed Object, Not a Direct Target

While a ReplicaSet can be created and managed directly, the common pattern is for a Deployment to own one or more ReplicaSets, using them purely as the mechanism for actually instantiating Pods while the Deployment layer adds rollout history and update orchestration on top.

metadata:
  ownerReferences:
    - apiVersion: apps/v1
      kind: Deployment
      name: parent-deployment
      controller: true

No Native Rollout Capability

A ReplicaSet has no built-in mechanism for gradually transitioning between two different Pod templates; changing its template only affects Pods created after the change, leaving existing Pods untouched, which is precisely the gap the Deployment controller exists to fill.

ReplicaSet Controller Diagram

This minimal, count-only responsibility is intentional: by keeping the ReplicaSet controller focused on a single, well-defined guarantee, higher-level controllers like Deployment can layer richer behavior on top without needing to reimplement basic replica maintenance themselves.