The issue opens pre-filled with this page title and URL.
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.
Object
What it does
ReplicaSet
Maintains a number of identical Pods
Deployment
Creates and chains ReplicaSets: gradual updates, rollback
Swipe to see more
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:
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:
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.
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:
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):
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:
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
kubectldeletedeploymentapicompte-absent
kubectldeletereplicasetsolo-rs
kubectlgetpods
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
A ReplicaSet maintains a number of identical Pods; the Deployment adds versions and updates on top.
A change to the Pod template changes its hash: the Deployment creates a new ReplicaSet and keeps the old one at zero.
A ReplicaSet counts the Pods that carry the labels of its selector and have no other owner controller, including a Pod created by hand.
The selector of two controllers must not overlap.
A ReplicaSet that does not produce its Pods is read in its events: kubectl describe replicaset, Events section, FailedCreate reason.
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
⏱️--:--
0 / 7
Review
(0/0)
--:--
0%
0Correct
0To review
0:00Time
-Level
Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.