Skip to main content
Mapagam

Managing ReplicaSets

1. Listing ReplicaSets

Command Description Flags
kubectl get replicaset List all ReplicaSets in the current namespace -o wide to show more details
kubectl get replicaset -n <namespace> List ReplicaSets in a specific namespace -o json or -o yaml for structured output
kubectl get replicaset <replicaset-name> Get details of a specific ReplicaSet --show-labels to display labels

Example: Listing ReplicaSets in default namespace

kubectl get replicaset
NAME                   DESIRED   CURRENT   READY   AGE
nginx-replicaset       3         3         3       5m

Example: Listing ReplicaSets with wide output

kubectl get replicaset -o wide
NAME                   DESIRED   CURRENT   READY   AGE   CONTAINERS   IMAGES
nginx-replicaset       3         3         3       5m    nginx        nginx:1.19

2. Describing ReplicaSet Details

Property Description Example Value
apiVersion API version of the ReplicaSet resource apps/v1
kind Type of the Kubernetes resource ReplicaSet
metadata.name Name of the ReplicaSet my-app-replicaset
metadata.namespace Namespace where the ReplicaSet is created default
spec.replicas Number of desired pods 3
spec.selector.matchLabels Label selector used to identify pods managed by this ReplicaSet {"app": "my-app"}
spec.template.metadata.labels Labels applied to pods created by this ReplicaSet {"app": "my-app"}
spec.template.spec.containers Container specifications for pods created by this ReplicaSet 
[
  {
    "name": "my-app",
    "image": "nginx:latest"
  }
]

Example: Describe a ReplicaSet

kubectl describe replicaset my-app-replicaset

Example: Get ReplicaSet YAML

kubectl get replicaset my-app-replicaset -o yaml
Note: The spec.selector.matchLabels must match the labels in spec.template.metadata.labels for the ReplicaSet to manage pods correctly.

3. Scaling ReplicaSets

Property Description Values
replicas Number of desired pods 3
selector Label selector to identify pods managed by this ReplicaSet {"matchLabels": {"app": "nginx"}}
template Pod template to be used for creating new pods 
{
  "metadata": {
    "labels": {"app": "nginx"}
  },
  "spec": {
    "containers": [
      {
        "name": "nginx",
        "image": "nginx:1.21"
      }
    ]
  }
}

Example: Scaling a ReplicaSet

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: nginx-rs
spec:
  replicas: 5
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21
Note: Scaling a ReplicaSet changes the replicas field in its spec. The controller will create or delete pods to match the desired count.

4. Deleting ReplicaSets

Command Description Notes
kubectl delete replicaset <name> Delete a ReplicaSet by name Deletes the ReplicaSet and its managed Pods
kubectl delete replicaset <name> --cascade=orphan Delete a ReplicaSet but keep its Pods Pods continue running after ReplicaSet deletion
kubectl delete replicaset <name> --cascade=background Delete a ReplicaSet and its Pods asynchronously Pods are deleted in the background

Example: Delete a ReplicaSet

kubectl delete replicaset my-replicaset

Example: Delete a ReplicaSet and keep its Pods

kubectl delete replicaset my-replicaset --cascade=orphan

5. Understanding ReplicaSet Selectors

Selector Type Description Example
matchLabels Matches pods based on label key-value pairs "matchLabels": {"app": "nginx"}
matchExpressions More complex matching using operators like In, NotIn, Exists, DoesNotExist 
"matchExpressions": [
  {
    "key": "environment",
    "operator": "In",
    "values": ["prod", "staging"]
  }
]

Example: ReplicaSet with Label Selectors

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: nginx-replicas
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21
Note: The selector.matchLabels must match the pod template's labels for the ReplicaSet to manage the pods correctly.

6. Viewing ReplicaSet Ownership

Field Description Example Value
metadata.ownerReferences Lists the owning objects that manage this ReplicaSet [{"apiVersion": "apps/v1", "kind": "Deployment", "name": "my-deployment", "uid": "abc123"}]
metadata.labels Labels used to identify the ReplicaSet and its relationship to other resources {"app": "my-app", "version": "v1"}

Example: Describe ReplicaSet to View Ownership

kubectl describe rs my-replicaset

Example: Get ReplicaSet with Owner References

kubectl get rs my-replicaset -o jsonpath="{.metadata.ownerReferences}"

7. Viewing ReplicaSet Pods

Property Description Example
replicas Number of desired pods 3
selector Label selector used to identify pods {app: nginx}
template Pod template used to create new pods 
{
  "metadata": {
    "labels": {
      "app": "nginx"
    }
  },
  "spec": {
    "containers": [
      {
        "name": "nginx",
        "image": "nginx:1.21"
      }
    ]
  }
}

Example: Get ReplicaSet Pod List

kubectl get pods -l app=nginx

Example: Describe ReplicaSet

kubectl describe rs nginx-rs

8. Orphaning Pods During Deletion

When deleting a ReplicaSet, you can choose to orphan its pods instead of terminating them. This is useful for scenarios where you want to retain the pods for debugging or manual management.

Option Description Default Value
orphanPods When set to true, pods are not deleted when the ReplicaSet is deleted. false

Example: Orphaning Pods During ReplicaSet Deletion

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: example-rs
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
    spec:
      containers:
      - name: example-container
        image: nginx:latest
Note: To orphan pods, you must explicitly set the orphanPods field to true in your deletion command or configuration.

9. Understanding ReplicaSet vs Deployment

Feature ReplicaSet Deployment
Purpose Ensures a specified number of pod replicas are running Declares the desired state for a set of pods
Update Strategy Manual updates required Automatically handles updates with rolling strategy
Rollback Support No native rollback support Native rollback capability with revision history
Pod Management Direct pod management Abstracts pod management through controller
Use Case Core building block for pod replication High-level abstraction for managing app versions

When to Use Which?

  • ReplicaSet: When you need fine-grained control over pod replicas or are building custom controllers.
  • Deployment: When you want declarative updates, rollbacks, and higher-level abstraction for managing applications.

10. Troubleshooting ReplicaSet Issues

Issue Description Diagnosis Solution
ReplicaSet Not Scaling Replicas not reaching desired count kubectl get replicaset <rs-name> Check for resource limits or node constraints
Pods Failing to Start ReplicaSet creates pods that immediately crash kubectl describe pod <pod-name> Review pod logs and container image
Incorrect Replica Count Actual replicas differ from desired count kubectl get replicaset <rs-name> -o yaml Verify spec.replicas and selector match

Example: Check ReplicaSet Status

kubectl get replicaset -o wide

Example: Describe ReplicaSet

kubectl describe replicaset <rs-name>
Note: Ensure that the ReplicaSet's selector matches the labels of pods it should manage.
Warning: Avoid manually deleting pods managed by a ReplicaSet as they will be recreated.

Was this article helpful?

Related Cheat Sheets