Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Kubernetes ReplicaSet: what a Deployment creates

By updated

Improve this page

Logo Kubernetes

A ReplicaSet maintains a defined number of identical Pods: if a Pod disappears, it creates another one. You almost never create one yourself, because the Deployment does it for you. This lesson explains what happens under a Deployment. You update it and read its two ReplicaSets, you watch a ReplicaSet claim a Pod that already existed, then you read a FailedCreate in the events of a ReplicaSet that does not produce its Pods.

Prerequisites: the lesson Deployments and the demo cluster from First cluster. The control loop that makes this behavior possible is described in The control plane.

What you will learn

  • Explain the role of a ReplicaSet and what it leaves to the Deployment
  • Observe the ReplicaSets created by a Deployment and read why an update creates a new one
  • Predict which Pods a ReplicaSet claims from its selector, including a Pod that already exists
  • Diagnose a ReplicaSet that does not produce the expected Pods from its events

ReplicaSet or Deployment?

The ReplicaSet does one thing: it constantly compares the number of Pods that carry the labels of its selector (the field that says which Pods it manages) with the desired number (replicas), and creates or deletes Pods to make them equal. A label is a key-value tag set on an object, such as app=api: the lesson Labels and annotations covers them in detail. The Deployment adds version management on top: it creates one ReplicaSet per version of the Pod template and sets the number of Pods of each, the old one going down while the new one goes up.

ObjectWhat it does
ReplicaSetMaintains a number of identical Pods
DeploymentCreates and chains ReplicaSets: gradual updates, rollback

A ReplicaSet does neither gradual updates nor rollbacks: changing the image in a standalone ReplicaSet replaces no existing Pod. This is why you go through a Deployment.

Which ReplicaSets does a Deployment create?

Create an api Deployment of three Pods and look at what it produced:

Terminal window
kubectl config use-context kind-demo
kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
replicas: 3
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: api
spec:
containers:
- name: nginx
image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
EOF
kubectl rollout status deployment/api --timeout=90s
kubectl get replicaset -l app=api
Output
Switched to context "kind-demo".
deployment.apps/api created
Waiting for deployment "api" rollout to finish: 0 out of 3 new replicas have been updated...
Waiting for deployment "api" rollout to finish: 0 of 3 updated replicas are available...
Waiting for deployment "api" rollout to finish: 1 of 3 updated replicas are available...
Waiting for deployment "api" rollout to finish: 2 of 3 updated replicas are available...
deployment "api" successfully rolled out
NAME DESIRED CURRENT READY AGE
api-698865cd4b 3 3 3 17s

The name of the ReplicaSet combines the name of the Deployment and a hash of the Pod template. Each object also knows who created it, through its ownerReferences field; Kubernetes uses it to delete the children when the parent is deleted:

Ownership chain: the Deployment creates a ReplicaSet, which maintains 3 Pods whose ownerReferences field points to it.DeploymentReplicaSet3 PodsownerReferences points to the ReplicaSetPodPodPodcreatesmaintains
Source · SVG
Esc to close, + and − to zoom, scroll to move around. 100 %

On the diagram, each arrow goes from the parent to the child: Deployment, ReplicaSet, then Pods. Read this field on the ReplicaSet and on a Pod:

Terminal window
kubectl get replicaset -l app=api -o jsonpath='{.items[0].metadata.ownerReferences[0].kind}{"\n"}'
kubectl get pods -l app=api -o jsonpath='{.items[0].metadata.ownerReferences[0].kind}{"\n"}'
Output
Deployment
ReplicaSet

Why does an update create a new ReplicaSet?

Change the image: the Pod template (template) changes, so its hash changes, so the Deployment creates another ReplicaSet instead of modifying the first one. The old one is kept at zero replicas.

Terminal window
kubectl set image deployment/api nginx=nginx:1.30.6@sha256:42c68eab6f7e22611786a9fe1d1c019e275c50185bd54b8f75dc2b9184322703
kubectl rollout status deployment/api --timeout=90s
kubectl get replicaset -l app=api -o custom-columns=NOM:.metadata.name,VOULUS:.spec.replicas,PRETS:.status.readyReplicas,IMAGE:.spec.template.spec.containers[0].image
Output
deployment.apps/api image updated
Waiting for deployment "api" rollout to finish: 0 out of 3 new replicas have been updated...
[...]
Waiting for deployment "api" rollout to finish: 1 old replicas are pending termination...
[...]
deployment "api" successfully rolled out
NOM VOULUS PRETS IMAGE
api-6795bfcc6c 3 3 nginx:1.30.6@sha256:42c68eab6f7e22611786a9fe1d1c019e275c50185bd54b8f75dc2b9184322703
api-698865cd4b 0 <none> nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb

Both ReplicaSets exist: the old one (zero Pods) is used to roll back without recreating anything, the new one carries the three Pods. Each has a different selector, because the hash of the template is part of it:

Terminal window
kubectl get replicaset -l app=api -o custom-columns=NOM:.metadata.name,SELECTOR:.spec.selector.matchLabels
Output
NOM SELECTOR
api-6795bfcc6c map[app:api pod-template-hash:6795bfcc6c]
api-698865cd4b map[app:api pod-template-hash:698865cd4b]

It is the pod-template-hash label, set by the Deployment, that tells apart the Pods of each ReplicaSet. The rollback, kubectl rollout undo, reactivates the old ReplicaSet: it is covered in Deployments.

How does a ReplicaSet recognize its Pods?

A ReplicaSet keeps no list of the Pods it created. At every moment, it counts the Pods of the namespace that carry the labels of its selector and that no other controller owns, then compares this number with replicas. It does not care whether those Pods were created by hand. To see it, first create a standalone Pod carrying the label app=solo, then a ReplicaSet that asks for three replicas on this label (a standalone ReplicaSet, for the experiment only):

Terminal window
kubectl run solitaire --labels=app=solo \
--image=nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
kubectl wait --for=condition=Ready pod/solitaire --timeout=90s
kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: ReplicaSet
metadata:
name: solo-rs
spec:
replicas: 3
selector:
matchLabels:
app: solo
template:
metadata:
labels:
app: solo
spec:
containers:
- name: nginx
image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
EOF
kubectl wait --for=jsonpath='{.status.readyReplicas}'=3 replicaset/solo-rs --timeout=90s
kubectl get pods -l app=solo
kubectl describe replicaset solo-rs | sed -n '/^Events:/,$p'
kubectl get pod solitaire -o jsonpath='{.metadata.ownerReferences[0].kind}/{.metadata.ownerReferences[0].name}{"\n"}'
Output
pod/solitaire created
pod/solitaire condition met
replicaset.apps/solo-rs created
replicaset.apps/solo-rs condition met
NAME READY STATUS RESTARTS AGE
solitaire 1/1 Running 0 2s
solo-rs-ksbc6 1/1 Running 0 1s
solo-rs-rqjcl 1/1 Running 0 1s
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal SuccessfulCreate 1s replicaset-controller Created pod: solo-rs-ksbc6
Normal SuccessfulCreate 1s replicaset-controller Created pod: solo-rs-rqjcl
ReplicaSet/solo-rs

The events show two creations for three replicas: the solitaire Pod existed, carried the right label, and the ReplicaSet took it over instead of creating another one. Its ownerReferences now points to solo-rs. The consequence to remember: a ReplicaSet takes ownership of any Pod without an owner whose labels match its selector, so the labels of two controllers must not overlap.

Why does a ReplicaSet not produce its Pods?

When a ReplicaSet keeps its count badly, the cause comes either from the Pods themselves, or from the API refusing to create them. Trigger the second case with a Deployment that asks for a ServiceAccount (the identity of the Pod in the cluster) that does not exist:

Terminal window
kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: compte-absent
spec:
replicas: 2
selector:
matchLabels:
app: compte-absent
template:
metadata:
labels:
app: compte-absent
spec:
serviceAccountName: compte-absent
containers:
- name: nginx
image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
EOF
sleep 5
kubectl get deployment compte-absent
kubectl get replicaset -l app=compte-absent
kubectl get pods -l app=compte-absent
Output
deployment.apps/compte-absent created
NAME READY UP-TO-DATE AVAILABLE AGE
compte-absent 0/2 0 0 5s
NAME DESIRED CURRENT READY AGE
compte-absent-7cfd9f76c8 2 0 0 5s
No resources found in default namespace.

No Pod exists, so kubectl describe pod has nothing to show: the diagnosis is made one level up, on the ReplicaSet.

Terminal window
kubectl describe replicaset -l app=compte-absent | sed -n '/^Events:/,$p'
Output
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning FailedCreate 2s (x10 over 5s) replicaset-controller Error creating: pods "compte-absent-7cfd9f76c8-" is forbidden: error looking up service account default/compte-absent: serviceaccount "compte-absent" not found

The FailedCreate event gives the exact cause of the refusal, and its (x10 over 5s) counter shows that the ReplicaSet retried ten times in five seconds. The other frequent causes are a reached resource quota or an invalid Pod template.

Two actions repair this failure. The first is to create the missing ServiceAccount in the namespace of the Deployment, with kubectl create serviceaccount compte-absent. The second is to remove serviceAccountName from the Pod template of the Deployment: this template change creates a new ReplicaSet, whose Pods use the default account.

The first action is enough, without touching the Deployment: the ReplicaSet controller retries the creation of the Pods as long as it fails, and the Pods appear by themselves as soon as the ServiceAccount exists. It waits longer and longer between two attempts: measured on kind after ten minutes of failures, the Pods appeared 58 s after the creation of the ServiceAccount.

To avoid waiting, kubectl rollout restart deployment/compte-absent changes the Pod template (a restart annotation): a new ReplicaSet immediately attempts its first creation, without you recreating the Deployment.

When the ReplicaSet does create Pods but they do not start, go down one level: kubectl get pods -l app=<label>, then kubectl describe pod <name-of-a-pod>, as in the lesson Pods.

Clean up the cluster

Delete the objects of this lesson to start again from a clean cluster. The Pods go to Terminating before disappearing. The solitaire Pod leaves with solo-rs, of which it became a child. If you repaired the failure by creating the ServiceAccount, delete it too with kubectl delete serviceaccount compte-absent.

Terminal window
kubectl delete deployment api compte-absent
kubectl delete replicaset solo-rs
kubectl get pods
Output
deployment.apps "api" deleted from default namespace
deployment.apps "compte-absent" deleted from default namespace
replicaset.apps "solo-rs" deleted from default namespace
NAME READY STATUS RESTARTS AGE
api-6795bfcc6c-gz4vv 1/1 Terminating 0 14s
api-6795bfcc6c-jjf5q 1/1 Terminating 0 22s
api-6795bfcc6c-rtp9n 1/1 Terminating 0 29s
solitaire 1/1 Terminating 0 7s
solo-rs-ksbc6 1/1 Terminating 0 6s
solo-rs-rqjcl 1/1 Terminating 0 6s

Put it into practice

The guided lab makes you go back up the chain on a kind cluster, in the replicasets namespace. The api Deployment was updated from nginx 1.30.5 to 1.30.6: you record in ~/replicasets/releve.txt its active ReplicaSet and the old one, kept at zero. The compte-absent Deployment produces no Pod: you record the cause read in the events of its ReplicaSet, then you repair it without recreating it, by one of the two ways seen above. The validation compares your record with the ReplicaSets of the cluster and checks that the two replicas of compte-absent are available.

Key takeaways

  1. A ReplicaSet maintains a number of identical Pods; the Deployment adds versions and updates on top.
  2. A change to the Pod template changes its hash: the Deployment creates a new ReplicaSet and keeps the old one at zero.
  3. A ReplicaSet counts the Pods that carry the labels of its selector and have no other owner controller, including a Pod created by hand.
  4. The selector of two controllers must not overlap.
  5. A ReplicaSet that does not produce its Pods is read in its events: kubectl describe replicaset, Events section, FailedCreate reason.
  6. You almost never create a ReplicaSet yourself: you go through a Deployment.

Test your knowledge

Seven questions to check the Deployment, ReplicaSet, Pods chain, the takeover of an existing Pod and the reading of a FailedCreate.

Knowledge check

Check what you have learned with this interactive quiz

7 questions
5 min
80% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer