> ## 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.

# Deployments

> Manage Kubernetes deployments with scaling, rolling restarts, and lifecycle controls

Deployments provide declarative updates for Pods and ReplicaSets. They manage the desired state of your application, handling rolling updates, rollbacks, and scaling automatically.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Deployment" icon="layers">
    A controller that manages ReplicaSets and provides declarative updates to Pods.
  </Card>

  <Card title="ReplicaSet" icon="clone">
    Ensures a specified number of pod replicas are running at any time.
  </Card>

  <Card title="Rolling Update" icon="rotate">
    Gradual replacement of pods with new versions while maintaining availability.
  </Card>

  <Card title="Scaling" icon="arrows-left-right">
    Adjusting the number of pod replicas to match demand.
  </Card>
</CardGroup>

## Required Permissions

| Action             | Permission                                     |
| ------------------ | ---------------------------------------------- |
| View deployments   | `iam:project:infrastructure:kubernetes:read`   |
| Scale deployment   | `iam:project:infrastructure:kubernetes:write`  |
| Restart deployment | `iam:project:infrastructure:kubernetes:write`  |
| Create deployment  | `iam:project:infrastructure:kubernetes:write`  |
| Edit deployment    | `iam:project:infrastructure:kubernetes:write`  |
| Delete deployment  | `iam:project:infrastructure:kubernetes:delete` |

## Deployment Status Values

| Status          | Description                                              |
| --------------- | -------------------------------------------------------- |
| **Available**   | Minimum required replicas are available and ready        |
| **Progressing** | Deployment is creating, updating, or scaling pods        |
| **Failed**      | Deployment failed to progress (ReplicaFailure condition) |
| **Unknown**     | Deployment status cannot be determined                   |

## Replica Metrics

| Metric          | Description                                          |
| --------------- | ---------------------------------------------------- |
| **Ready**       | Pods that are ready to serve traffic (ready/desired) |
| **Up-to-date**  | Pods updated to the latest pod template spec         |
| **Available**   | Pods available for at least minReadySeconds          |
| **Unavailable** | Pods that are not yet available                      |

## How to View Deployments

<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 deployments across all namespaces.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find deployments by name, or filter by status.
  </Step>
</Steps>

## How to View Deployment Details

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

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

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

    * Replica status and pod distribution
    * Container specifications
    * Update strategy configuration
    * Labels, annotations, and selectors
    * Conditions and events
  </Step>
</Steps>

## How to Scale a Deployment

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

  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the deployment 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 (0-100).
  </Step>

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

<Warning>
  Scaling to 0 replicas stops all pods for the deployment. The application will become unavailable.
</Warning>

## How to Restart a Deployment

Restart triggers a rolling restart of all pods without changing the deployment spec.

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

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

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

  <Step title="Monitor">
    Watch the deployment status change to Progressing as pods are replaced.
  </Step>
</Steps>

<Info>
  Restart performs a rolling restart, replacing pods gradually to maintain availability. It adds a `kubectl.kubernetes.io/restartedAt` annotation to trigger the update.
</Info>

## How to Create a Deployment

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

  <Step title="Write YAML">
    Enter the deployment manifest in YAML format. A template is provided.
  </Step>

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

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

## How to Edit a Deployment

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

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

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

    * Container image (triggers rolling update)
    * Resource requests/limits
    * Environment variables
    * Replica count
  </Step>

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

<Info>
  Changes to the pod template spec trigger a rolling update. The deployment controller gradually replaces old pods with new ones.
</Info>

## How to Delete a Deployment

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

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

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

**Delete behavior:**

* Deletes the deployment, associated ReplicaSets, and all pods (cascade delete)
* Pods are terminated gracefully with default grace period

<Warning>
  Deleting a deployment removes all managed pods immediately. Ensure you have backups or can recreate the deployment if needed.
</Warning>

## Update Strategies

Deployments support two update strategies:

| Strategy          | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| **RollingUpdate** | Gradually replaces pods (default). Configurable via `maxSurge` and `maxUnavailable`. |
| **Recreate**      | Terminates all existing pods before creating new ones. Causes downtime.              |

**RollingUpdate parameters:**

* `maxSurge` - Maximum pods above desired count during update (default: 25%)
* `maxUnavailable` - Maximum unavailable pods during update (default: 25%)

## Troubleshooting

<AccordionGroup>
  <Accordion title="Deployment stuck in Progressing">
    * Insufficient cluster resources (CPU, memory)
    * Image pull failures (check image name and pull secrets)
    * Pod scheduling failures (check node affinity, taints)
    * Readiness probe never passes
    * Check deployment events for specific errors
  </Accordion>

  <Accordion title="Pods not becoming ready">
    * Readiness probe failing (check probe configuration)
    * Application not starting correctly (check container logs)
    * Dependencies not available (databases, services)
    * Resource limits too restrictive
  </Accordion>

  <Accordion title="Rolling update taking too long">
    * `maxUnavailable` set too low
    * Pods taking long to become ready
    * PodDisruptionBudget blocking evictions
    * Consider adjusting update strategy parameters
  </Accordion>

  <Accordion title="Scale operation not taking effect">
    * Check for resource quotas limiting pod count
    * Verify sufficient node capacity
    * HorizontalPodAutoscaler may be overriding manual scale
    * Check deployment events for errors
  </Accordion>

  <Accordion title="Restart not replacing pods">
    * Deployment must have at least 1 replica
    * Check if pods are stuck terminating
    * Verify deployment controller is healthy
    * Review deployment events
  </Accordion>

  <Accordion title="Cannot delete deployment">
    * Finalizers may be blocking deletion
    * Verify you have delete permission
    * Check if namespace is terminating
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between scaling and updating?">
    **Scaling** changes the number of replicas without modifying the pod spec. **Updating** changes the pod template, triggering a rolling update to replace all pods with the new configuration.
  </Accordion>

  <Accordion title="How does rolling update maintain availability?">
    The deployment controller creates new pods before terminating old ones, respecting `maxSurge` and `maxUnavailable` settings. Traffic continues to flow to ready pods throughout the update.
  </Accordion>

  <Accordion title="What happens if I scale during an update?">
    The new replica count applies to the final state. Kubernetes handles both operations, ensuring the target state is eventually reached.
  </Accordion>

  <Accordion title="Can I rollback a deployment?">
    Yes. Deployments maintain revision history. Use `kubectl rollout undo` or edit the deployment to restore a previous pod template spec.
  </Accordion>

  <Accordion title="Why are some replicas unavailable?">
    Pods may be unavailable because they're starting up, failing readiness probes, being evicted, or experiencing errors. Check the deployment's pod list for specific status.
  </Accordion>

  <Accordion title="How do I update without downtime?">
    Use RollingUpdate strategy (default) with appropriate `maxSurge` and `maxUnavailable` values. Ensure your application handles graceful shutdown and has proper readiness probes.
  </Accordion>

  <Accordion title="What's the difference between restart and redeploy?">
    **Restart** triggers a rolling restart using the same image and configuration. **Redeploy** (updating the image or spec) creates pods with the new configuration. Restart is useful for picking up config changes from ConfigMaps/Secrets.
  </Accordion>

  <Accordion title="How do I scale to zero?">
    Set replicas to 0. The deployment and ReplicaSet remain, but all pods are terminated. Scale back up by setting replicas to a positive number.
  </Accordion>
</AccordionGroup>