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

# PDBs

> Manage Kubernetes PDBs to protect application availability during voluntary disruptions

Pod Disruption Budgets (PDBs) limit the number of pods that can be simultaneously unavailable during voluntary disruptions like node drains, cluster upgrades, or rolling deployments.

## Key Concepts

<CardGroup cols={2}>
  <Card title="PDB" icon="shield-halved">
    A policy that ensures a minimum number of pods remain available during voluntary disruptions.
  </Card>

  <Card title="Selector" icon="filter">
    Label selector that identifies which pods are protected by this budget.
  </Card>

  <Card title="Budget" icon="calculator">
    Either minAvailable (minimum pods to keep) or maxUnavailable (maximum pods to disrupt).
  </Card>

  <Card title="Disruptions Allowed" icon="check-circle">
    Current number of pods that can be safely disrupted while maintaining the budget.
  </Card>
</CardGroup>

## Required Permissions

| Action     | Permission                                     |
| ---------- | ---------------------------------------------- |
| View PDBs  | `iam:project:infrastructure:kubernetes:read`   |
| Create PDB | `iam:project:infrastructure:kubernetes:write`  |
| Edit PDB   | `iam:project:infrastructure:kubernetes:write`  |
| Delete PDB | `iam:project:infrastructure:kubernetes:delete` |

## PDB Status Values

| Status      | Description                                      |
| ----------- | ------------------------------------------------ |
| **Allowed** | Disruptions are allowed (disruptionsAllowed > 0) |
| **Blocked** | No disruptions allowed (disruptionsAllowed = 0)  |

<Info>
  A "Blocked" status means the PDB is protecting pods at the budget limit. Operations like node drains will wait until more pods become available.
</Info>

## How to View PDBs

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

  <Step title="Search">
    Use the search box to find PDBs by name or namespace.
  </Step>
</Steps>

## How to View PDB Details

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

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

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

    * **Overview**: Name, namespace, status, age
    * **Budget**: minAvailable or maxUnavailable setting
    * **Pod Counts**: currentHealthy, desiredHealthy, expectedPods, disruptionsAllowed
    * **Selector**: Label selector matching protected pods
    * **Conditions**: PDB controller conditions
    * **Labels & Annotations**: Metadata attached to the PDB
  </Step>
</Steps>

## How to Create a PDB

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

  <Step title="Write YAML">
    Enter the PDB manifest in YAML format. Key fields:

    * `spec.selector` - Label selector for target pods
    * `spec.minAvailable` - Minimum pods that must be available (integer or percentage)
    * `spec.maxUnavailable` - Maximum pods that can be unavailable (integer or percentage)
  </Step>

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

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

<Warning>
  You must specify either `minAvailable` OR `maxUnavailable`, not both. Specifying both will result in a validation error.
</Warning>

## How to Edit a PDB

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

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

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

    * Adjust minAvailable or maxUnavailable values
    * Update selector labels
    * Modify metadata
  </Step>

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

## How to Delete a PDB

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

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

  <Step title="Confirm">
    Confirm the deletion. Pods will no longer be protected from disruptions.
  </Step>
</Steps>

<Warning>
  Deleting a PDB removes disruption protection. Voluntary disruptions like node drains can proceed without limits on how many pods go down simultaneously.
</Warning>

## Budget Types

PDBs support two mutually exclusive budget specifications:

### minAvailable

Specifies the minimum number of pods that must remain available:

```yaml theme={null}
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: app-pdb
spec:
  minAvailable: 2        # At least 2 pods must be available
  selector:
    matchLabels:
      app: my-app
```

Or as a percentage:

```yaml theme={null}
spec:
  minAvailable: "50%"    # At least 50% of pods must be available
```

### maxUnavailable

Specifies the maximum number of pods that can be unavailable:

```yaml theme={null}
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: app-pdb
spec:
  maxUnavailable: 1      # At most 1 pod can be unavailable
  selector:
    matchLabels:
      app: my-app
```

Or as a percentage:

```yaml theme={null}
spec:
  maxUnavailable: "25%"  # At most 25% of pods can be unavailable
```

| Field              | Type     | Description                                  |
| ------------------ | -------- | -------------------------------------------- |
| **minAvailable**   | int or % | Minimum pods that must remain available      |
| **maxUnavailable** | int or % | Maximum pods that can be unavailable at once |

<Tip>
  Use percentages for workloads that scale frequently. Use absolute numbers when you need precise control over minimum availability.
</Tip>

## Pod Counts Explained

| Field                  | Description                                     |
| ---------------------- | ----------------------------------------------- |
| **expectedPods**       | Total number of pods selected by the PDB        |
| **currentHealthy**     | Number of pods currently in healthy/ready state |
| **desiredHealthy**     | Minimum healthy pods required by the budget     |
| **disruptionsAllowed** | How many pods can currently be disrupted        |

**Formula**: `disruptionsAllowed = currentHealthy - desiredHealthy`

<Info>
  If `disruptionsAllowed` is 0, voluntary disruptions are blocked until more pods become healthy or the budget is modified.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Node drain is stuck waiting">
    * Check if a PDB is blocking the drain (disruptionsAllowed = 0)
    * Verify pods are healthy and ready
    * Scale up the deployment temporarily to allow disruption
    * Consider using `kubectl drain --disable-eviction` for emergencies (bypasses PDB)
  </Accordion>

  <Accordion title="PDB shows 0 expected pods">
    * Verify the selector matches your pod labels
    * Check pods exist in the same namespace as the PDB
    * Use `kubectl get pods --selector=<labels>` to verify selector
  </Accordion>

  <Accordion title="Cannot create PDB - validation error">
    * Ensure you specify either minAvailable OR maxUnavailable, not both
    * Percentage values must be strings with % suffix (e.g., "50%")
    * Integer values must be non-negative
    * Selector must be valid label selector syntax
  </Accordion>

  <Accordion title="Disruptions allowed is negative">
    * This means fewer pods are healthy than required by the budget
    * Check pod health and resolve any pod failures
    * The budget is currently being violated - no disruptions will be allowed
  </Accordion>

  <Accordion title="PDB not protecting pods during deployment">
    * PDBs only protect against voluntary disruptions (node drain, delete)
    * Rolling update strategy is separate from PDB
    * Configure maxUnavailable in Deployment spec for rolling updates
    * PDBs don't prevent involuntary disruptions (node failure, OOM)
  </Accordion>

  <Accordion title="Cluster upgrade blocked by PDB">
    * PDBs can block node upgrades if pods can't be evicted
    * Ensure replicas > minAvailable to allow rolling evictions
    * Consider temporarily relaxing the PDB during maintenance
    * Scale up workloads before upgrades to allow eviction headroom
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What are voluntary vs involuntary disruptions?">
    **Voluntary**: Planned disruptions like node drain, cluster upgrade, pod deletion by admin. PDBs protect against these.

    **Involuntary**: Unplanned disruptions like hardware failure, kernel panic, OOM kills. PDBs cannot prevent these.
  </Accordion>

  <Accordion title="Should I use minAvailable or maxUnavailable?">
    **minAvailable** is better when you know the minimum pods needed for availability (e.g., "always need at least 2 pods").

    **maxUnavailable** is better when you want to control disruption rate (e.g., "only disrupt 1 pod at a time").
  </Accordion>

  <Accordion title="Can I have multiple PDBs for the same pods?">
    Yes, but it's not recommended. Multiple PDBs selecting the same pods will all be enforced, potentially making eviction impossible. Use a single PDB per workload.
  </Accordion>

  <Accordion title="Do PDBs affect rolling deployments?">
    No. Rolling update behavior is controlled by the Deployment's strategy, not PDBs. PDBs only affect voluntary pod evictions (like node drains), not the deployment controller replacing pods.
  </Accordion>

  <Accordion title="What happens if minAvailable equals replicas?">
    No voluntary disruptions will ever be allowed. This blocks node drains and cluster upgrades. Always set minAvailable \< replicas to allow rolling operations.
  </Accordion>

  <Accordion title="Can PDBs use percentage values?">
    Yes. Both minAvailable and maxUnavailable accept percentages (e.g., "50%"). Percentages are calculated against the total number of pods matching the selector.
  </Accordion>

  <Accordion title="What is the difference between policy/v1beta1 and policy/v1?">
    `policy/v1` is the stable API (Kubernetes 1.21+) and should be used. `policy/v1beta1` is deprecated. The main difference is that v1 has an empty selector behavior change.
  </Accordion>

  <Accordion title="Do PDBs work with StatefulSets?">
    Yes. PDBs work with any pod controller (Deployments, StatefulSets, DaemonSets, ReplicaSets). The selector just needs to match the pod labels.
  </Accordion>
</AccordionGroup>