> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ReplicaSets

> View and manage Kubernetes ReplicaSets that maintain pod replicas

ReplicaSets ensure a specified number of pod replicas are running at any time. They are typically managed by Deployments rather than created directly, but you can view, scale, and manage them when needed.

## Key Concepts

<CardGroup cols={2}>
  <Card title="ReplicaSet" icon="clone">
    A controller that maintains a stable set of replica pods running at any time.
  </Card>

  <Card title="Selector" icon="filter">
    Label selector that identifies which pods belong to the ReplicaSet.
  </Card>

  <Card title="Replicas" icon="copy">
    The desired number of pod instances to maintain.
  </Card>

  <Card title="Owner Reference" icon="link">
    Link to the parent controller (usually a Deployment) that manages the ReplicaSet.
  </Card>
</CardGroup>

## Required Permissions

| Action            | Permission                                     |
| ----------------- | ---------------------------------------------- |
| View replicasets  | `iam:project:infrastructure:kubernetes:read`   |
| Scale replicaset  | `iam:project:infrastructure:kubernetes:write`  |
| Create replicaset | `iam:project:infrastructure:kubernetes:write`  |
| Edit replicaset   | `iam:project:infrastructure:kubernetes:write`  |
| Delete replicaset | `iam:project:infrastructure:kubernetes:delete` |

## ReplicaSet Status Values

| Status          | Description                     |
| --------------- | ------------------------------- |
| **Running**     | All desired replicas are ready  |
| **NotReady**    | Some replicas are not ready yet |
| **Scaled to 0** | ReplicaSet has zero replicas    |
| **Unknown**     | Status cannot be determined     |

## ReplicaSet Metrics

| Metric            | Description                         |
| ----------------- | ----------------------------------- |
| **Replicas**      | Desired number of pods              |
| **Ready**         | Pods that are ready (ready/desired) |
| **Available**     | Pods available for service          |
| **Fully Labeled** | Pods with all expected labels       |

## How to View ReplicaSets

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="Select Namespace">
    Choose a namespace or select "all" to view ReplicaSets across all namespaces.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find ReplicaSets by name or controlling resource.
  </Step>
</Steps>

<Info>
  The "Controlled By" column shows the parent resource (usually a Deployment) that manages each ReplicaSet.
</Info>

## How to View ReplicaSet Details

<Steps>
  <Step title="Find the ReplicaSet">
    Locate the ReplicaSet in the list.
  </Step>

  <Step title="Click ReplicaSet Name">
    Click on the ReplicaSet name to open the detail drawer.
  </Step>

  <Step title="Review Details">
    View ReplicaSet information including:

    * Replica counts and status
    * Pod template specification
    * Label selectors
    * Owner references
    * Events
  </Step>
</Steps>

## How to Scale a ReplicaSet

<Steps>
  <Step title="Find the ReplicaSet">
    Locate the ReplicaSet in the list.
  </Step>

  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the ReplicaSet row.
  </Step>

  <Step title="Click Scale">
    Select **Scale** to open the scale dialog.
  </Step>

  <Step title="Set Replica Count">
    Enter the desired number of replicas.
  </Step>

  <Step title="Apply">
    Click **Scale** to apply the change.
  </Step>
</Steps>

<Warning>
  If the ReplicaSet is managed by a Deployment, scaling the ReplicaSet directly may be overridden by the Deployment controller. Scale the parent Deployment instead for persistent changes.
</Warning>

## How to Create a ReplicaSet

<Steps>
  <Step title="Click Create ReplicaSet">
    Click the **Create ReplicaSet** button in the page header.
  </Step>

  <Step title="Write YAML">
    Enter the ReplicaSet manifest in YAML format.
  </Step>

  <Step title="Select Namespace">
    Choose the target namespace for the ReplicaSet.
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

<Tip>
  For most use cases, create a Deployment instead of a ReplicaSet directly. Deployments provide rolling updates, rollback capabilities, and better lifecycle management.
</Tip>

## How to Edit a ReplicaSet

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the ReplicaSet row.
  </Step>

  <Step title="Click Edit YAML">
    Select **Edit YAML** to open the editor.
  </Step>

  <Step title="Modify Spec">
    Edit the ReplicaSet specification. Common changes:

    * Replica count
    * Pod template (triggers pod replacement)
    * Labels and annotations
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

<Warning>
  The selector field is immutable after creation. To change the selector, delete and recreate the ReplicaSet.
</Warning>

## How to Delete a ReplicaSet

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the ReplicaSet row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu.
  </Step>

  <Step title="Confirm">
    Confirm the deletion.
  </Step>
</Steps>

<Warning>
  If the ReplicaSet is managed by a Deployment, it will be automatically recreated. Delete the parent Deployment instead to permanently remove the ReplicaSet.
</Warning>

## ReplicaSets vs Deployments

| Feature                 | ReplicaSet | Deployment           |
| ----------------------- | ---------- | -------------------- |
| **Pod replication**     | Yes        | Yes (via ReplicaSet) |
| **Rolling updates**     | No         | Yes                  |
| **Rollback**            | No         | Yes                  |
| **Update history**      | No         | Yes                  |
| **Declarative updates** | Manual     | Automatic            |

<Info>
  Deployments are the recommended way to manage stateless applications. They create and manage ReplicaSets automatically, providing additional features like rolling updates and rollbacks.
</Info>

## Understanding Owner References

Most ReplicaSets are created and managed by Deployments:

* **Controlled By Deployment**: The ReplicaSet is managed by a Deployment. Changes to replica count should be made on the Deployment.
* **No Owner**: The ReplicaSet is standalone and can be managed directly.

When a Deployment updates, it creates a new ReplicaSet with the updated pod template and scales down the old ReplicaSet.

## Troubleshooting

<AccordionGroup>
  <Accordion title="ReplicaSet not creating pods">
    * Check if replica count is greater than zero
    * Verify selector matches pod template labels
    * Check for resource quota limits in namespace
    * Review ReplicaSet events for errors
  </Accordion>

  <Accordion title="Pods not becoming ready">
    * Check pod logs for application errors
    * Verify readiness probe configuration
    * Check if required ConfigMaps/Secrets exist
    * Verify image pull is successful
  </Accordion>

  <Accordion title="Scale changes being reverted">
    * Check if ReplicaSet is managed by a Deployment
    * Scale the parent Deployment instead
    * Check for HorizontalPodAutoscaler targeting the Deployment
  </Accordion>

  <Accordion title="Old ReplicaSets consuming resources">
    * Deployments keep old ReplicaSets for rollback
    * Set `spec.revisionHistoryLimit` on Deployment to limit retained ReplicaSets
    * Default is 10 revisions
  </Accordion>

  <Accordion title="Cannot delete ReplicaSet">
    * If managed by Deployment, it will be recreated
    * Delete the parent Deployment instead
    * Check for finalizers blocking deletion
  </Accordion>

  <Accordion title="Selector mismatch errors">
    * Selectors are immutable after creation
    * Ensure pod template labels match the selector
    * Delete and recreate to change the selector
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Should I create ReplicaSets directly?">
    Generally no. Use Deployments instead, which manage ReplicaSets and provide additional features like rolling updates and rollbacks. Direct ReplicaSet creation is only needed for specific use cases.
  </Accordion>

  <Accordion title="Why are there multiple ReplicaSets for one Deployment?">
    Each time you update a Deployment's pod template, a new ReplicaSet is created. Old ReplicaSets are kept (scaled to 0) for rollback capability. The number retained is controlled by `revisionHistoryLimit`.
  </Accordion>

  <Accordion title="Can I restart pods in a ReplicaSet?">
    ReplicaSets don't have a built-in restart mechanism. Delete pods to have them recreated, or if managed by a Deployment, use the Deployment's restart feature.
  </Accordion>

  <Accordion title="What happens if I scale a Deployment-managed ReplicaSet?">
    The Deployment controller will detect the change and revert it to match the Deployment's replica count. Always scale the Deployment instead.
  </Accordion>

  <Accordion title="How do I identify which Deployment owns a ReplicaSet?">
    Check the "Controlled By" column or the owner references in the ReplicaSet details. The ReplicaSet name usually includes the Deployment name as a prefix.
  </Accordion>

  <Accordion title="Why is my ReplicaSet showing 0/0 replicas?">
    This is normal for old ReplicaSets after a Deployment update. The Deployment scales down old ReplicaSets to 0 but keeps them for rollback history.
  </Accordion>

  <Accordion title="Can I update the pod template in a ReplicaSet?">
    Yes, but existing pods won't be updated. Only new pods (created due to scaling or pod deletion) will use the new template. Use Deployments for proper rolling updates.
  </Accordion>
</AccordionGroup>