What is a Kubernetes PodDisruptionBudget and what does it actually protect?

A PodDisruptionBudget (PDB) is a contract between a workload and whoever performs voluntary disruptions. The workload owner declares how many replicas must stay running, or how many may be down at once. Any actor that removes pods through the Eviction API must respect that limit. If an eviction would breach the budget, the API server rejects it and the caller has to wait and retry.

The PDB applies only to callers that use the Eviction API. Anything that deletes pods directly, or kills them outside the API, bypasses it.

Disruption source Governed by PDB? Why
kubectl drain Yes Evicts pods through the Eviction API
Node maintenance and upgrade tooling Yes, if it evicts Most tools drain nodes before replacing them
Cluster autoscaler scale-down Yes Evicts pods before removing a node
Node crash, kernel panic, power loss No Pods disappear without any API request
OOM kill No The kubelet and kernel act locally
Direct pod deletion (kubectl delete pod) No A delete request is not an eviction
Deployment rolling update No Governed by the Deployment's own maxUnavailable and maxSurge

The false-confidence trap

A PDB does not make a service highly available. It only slows down planned removals so they don't take out too many replicas at once. If three replicas share one node or one zone and that node or zone fails, all three go down, and the budget plays no part.

Unplanned failures are handled by redundancy: enough replicas, spread across nodes and zones with topology spread constraints or anti-affinity. Treat the PDB as a guard on maintenance, layered on top of that redundancy, not as a substitute for it.

How does a node drain work with the Eviction API?

Draining a node looks like a single command, but it is a sequence of API calls, and the PDB sits in the middle of that sequence.

First, the node is cordoned: it is marked unschedulable so no new pods land on it. Then the drain sends an eviction request for each pod on the node through the Eviction API, rather than deleting pods directly. That difference matters. A plain delete ignores budgets. An eviction is checked by the API server against any PDB that selects the pod. If the eviction would push the workload below its budget, the API server rejects it with HTTP 429. The drain does not force the pod out. It waits and retries until the budget has room again.

 cordon node ──► pick pod ──► POST eviction
                                   │
                         PDB allows disruption?
                          │                 │
                         yes                no (429)
                          │                 │
                 pod terminates      wait, then retry
                          │                 │
                 next pod ◄─────────────────┘

The budget's "room" is computed by the disruption controller, and it counts only pods that are Ready. Pods that are merely Running do not count. This makes readiness probes part of your disruption policy:

  • A flaky probe makes the healthy count drop, and drains stall.
  • A slow probe on new replicas keeps the budget at zero for longer.
  • A probe that reports Ready before the app can serve traffic makes the budget allow evictions it should block.

A PDB only limits how fast pods are evicted. It does not check whether their replacements can be scheduled. If the rest of the cluster has no free CPU, memory, or zone capacity, the evicted pods stay Pending, the Ready count stays low, and the drain stops. You still need spare capacity or surge room.

+-----------------+
| kubectl drain   |
+--------+--------+
         |
         v
+-----------------+     +---------------------------+
| cordon node     |     | disruption controller     |
| (unschedulable) |     | counts only Ready pods    |
+--------+--------+     | -> disruptions allowed    |
         |              +-------------+-------------+
         v                            |
+-----------------+                   v
| pick next pod   |     +---------------------------+
+--------+--------+     | API server: PDB check     |
         |              | on eviction request       |
         v              +------+-------------+------+
+-----------------+            |             |
| POST eviction   +----------->+             |
+-----------------+            |             |
         ^                allowed          denied (429)
         |                     |             |
         |                     v             v
         |        +------------------+  +--------------+
         |        | pod terminates;  |  | wait, then   |
         +--------+ replacement must |  | retry same   |
         |        | find capacity    |  | eviction     |
         |        +------------------+  +------+-------+
         |                                     |
         +-------------------------------------+

A drain cordons the node, then evicts pods one at a time; the API server checks each eviction against the PDB, whose budget counts only Ready pods, and a 429 rejection makes the drain wait and retry.

How do you implement a PodDisruptionBudget correctly?

A PodDisruptionBudget is a small object: a name, a namespace, a label selector, and either minAvailable or maxUnavailable. It must live in the same namespace as the pods it protects, and its selector.matchLabels should match the labels in the Deployment's pod template (spec.template.metadata.labels), not the Deployment's own metadata labels.

Get the selector exactly right

The selector controls what the budget covers, so it needs care:

  • Match the intended pods and nothing else. A selector that also catches a sidecar job or a canary Deployment counts those pods toward the budget and distorts the numbers.
  • Avoid overlapping PDBs. If two budgets select the same pod, the Eviction API refuses to evict that pod. Your drain stalls with an error instead of making a decision.
  • Watch for empty matches. A selector that matches zero pods is accepted without complaint. It protects nothing, and you will usually find out during an outage.

Read the status

kubectl get pdb shows allowed disruptions per budget. kubectl describe pdb <name> shows the status fields:

  • currentHealthy is how many selected pods are Ready right now.
  • desiredHealthy is the minimum the budget requires.
  • disruptionsAllowed is the difference between them, floored at zero.

If disruptionsAllowed is 0 before any drain starts, the drain will block.

Unhealthy pods count against you

By default, pods that are not Ready, such as those stuck in CrashLoopBackOff or failing readiness probes, still use up the budget. A Deployment with one broken replica can therefore block every eviction. Newer API fields, such as unhealthyPodEvictionPolicy, let you allow evicting pods that are already unhealthy. Check whether your cluster's API server supports this before you rely on it.

# PDB for a 3-replica Deployment. Check status after applying:
#   kubectl get pdb -n shop
#   kubectl describe pdb checkout-pdb -n shop
# With 3 Ready pods and minAvailable: 2, expect currentHealthy=3,
# desiredHealthy=2, disruptionsAllowed=1.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout
  namespace: shop
  labels:
    team: payments          # Deployment metadata labels: NOT what the PDB selects
spec:
  replicas: 3
  selector:
    matchLabels:
      app: checkout
  template:
    metadata:
      labels:
        app: checkout       # the PDB selector must match these pod template labels
    spec:
      containers:
        - name: checkout
          image: registry.example.com/shop/checkout:1.0.0
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: checkout-pdb
  namespace: shop           # same namespace as the pods
spec:
  minAvailable: 2           # set minAvailable or maxUnavailable, not both
  selector:
    matchLabels:
      app: checkout         # no other PDB should select these pods
  # Optional: allow eviction of pods that are already not Ready.
  # Confirm your API server supports this field before relying on it.
  # unhealthyPodEvictionPolicy: AlwaysAllow

A minimal Deployment and matching PodDisruptionBudget whose selector targets the pod template labels, with comments showing how to check currentHealthy, desiredHealthy, and disruptionsAllowed.

Should you use minAvailable or maxUnavailable?

The two fields express the same constraint from opposite directions, which is why the API rejects a PDB that sets both. Allowing both would permit contradictory budgets. Each field accepts an integer or a percentage of the expected pod count. Percentages are rounded up for both fields. That rounding has different effects depending on the field:

Replicas Budget Rounded result Evictions allowed
3 minAvailable: 90% 2.7 → 3 must stay up 0
3 maxUnavailable: 50% 1.5 → 2 may go down 2
10 maxUnavailable: 10% 1 may go down 1

On small replica counts, a percentage can silently block every eviction, or it can allow more disruption than you meant.

Why maxUnavailable fits autoscaled workloads

A fixed minAvailable: 3 does not scale with the workload. At 20 replicas it permits 17 simultaneous evictions. When the autoscaler shrinks the workload to 3, it permits none. maxUnavailable: 1 always allows exactly one eviction at a time, whatever the replica count.

Illustrative estimate: the 2-of-2 trap

The following compares two services with assumed inputs, not measurements:

  • 3 replicas, maxUnavailable: 1: One eviction is allowed. The drain evicts a pod, waits for its replacement to become Ready, and then proceeds.
  • 2 replicas, minAvailable: 2: Zero evictions are allowed. Every eviction request is refused, and the drain retries until it times out.

Changing the second budget to minAvailable: 1 unblocks the drain, but one pod then carries all traffic and you have no redundancy. The better fix is a third replica, which allows one eviction while still keeping two pods serving.

# Stateless API running 3 replicas.
# maxUnavailable: 1 permits one eviction at a time at any replica count,
# so it keeps working as an autoscaler grows or shrinks the Deployment.
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api-pdb
  namespace: shop
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      app: api
---
# The 2-of-2 trap: with only 2 replicas, minAvailable: 2 leaves
# 0 allowed disruptions, so every eviction is refused and the drain stalls.
#
# Fix: keep the budget, add capacity instead of loosening it:
#   kubectl -n shop scale deployment/payments --replicas=3
# With 3 replicas this budget allows 1 eviction while 2 pods keep serving.
# Confirm with: kubectl -n shop get pdb  (see the ALLOWED DISRUPTIONS column)
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: payments-pdb
  namespace: shop
spec:
  minAvailable: 2   # set only one of minAvailable / maxUnavailable
  selector:
    matchLabels:
      app: payments

Two PodDisruptionBudgets: maxUnavailable: 1 for a 3-replica API, and a minAvailable: 2 budget that blocks drains at 2 replicas and allows one eviction once the Deployment is scaled to 3.

Who should use PDBs, and when should you avoid strict budgets?

PDBs pay off for three groups. Owners of multi-replica stateless services get a guarantee that a drain never takes every replica at once. Owners of stateful systems get a way to encode how many members can safely leave. Platform teams running cluster upgrades get a contract: if every workload declares a budget, they can drain nodes without checking with each team.

Quorum-based workloads

For etcd-style consensus clusters and replicated databases, derive the budget from quorum math rather than intuition.

Illustrative estimate (assumed numbers, not a benchmark). Assume clusters of 3 and 5 members.

  • Quorum = floor(n / 2) + 1
  • Tolerable losses = n − quorum
  • For n = 3: quorum is 2, so the cluster tolerates 1 loss.
  • For n = 5: quorum is 3, so the cluster tolerates 2 losses.

Even for 5 members, set maxUnavailable: 1. The second slot of tolerance should stay free for an unplanned failure during maintenance. Before relying on the budget, confirm that the application handles a member leaving cleanly, including leader re-election and replica catch-up when the member rejoins.

When to avoid or rethink a budget

Configuration Effect on drains Better choice
minAvailable equal to the replica count Blocks the drain indefinitely Leave room for at least one eviction
maxUnavailable: 0 Blocks the drain indefinitely maxUnavailable: 1 with enough replicas
Single replica, any budget Either blocks the drain or protects nothing Add replicas, or accept downtime

A budget that can never be satisfied does not prevent disruption. It stalls the upgrade until someone forces deletion, and that bypasses the budget entirely. A single-replica workload cannot be protected in any meaningful way, so the real decision is to run more replicas or to schedule and accept the downtime.

What are the alternatives and complements to a PodDisruptionBudget?

A PDB only answers one question: may this eviction proceed right now? It does not decide where replicas run, whether there is room to reschedule them, or what happens to requests already in flight. Other mechanisms cover those gaps.

Placement. Two replicas on the same node are lost together in one drain, whatever the budget says. Spread them with topologySpreadConstraints, using topologyKey: kubernetes.io/hostname for nodes or topology.kubernetes.io/zone for zones, maxSkew: 1 and whenUnsatisfiable: DoNotSchedule. Required pod anti-affinity on the hostname key is stricter, but it can leave pods Pending when there are fewer nodes than replicas.

Capacity. An eviction the PDB allows still fails in practice if the evicted pod has nowhere to land. Add nodes before cordoning and draining, so replacements schedule immediately. Running one replica beyond your minimum also lets the budget permit evictions without stalling the drain.

Graceful shutdown. Once an eviction is allowed, the application is responsible for in-flight requests. Removal from endpoints and SIGTERM happen in parallel, so a short preStop sleep gives load balancers time to stop routing traffic before the process exits. Set terminationGracePeriodSeconds longer than your slowest request. On SIGTERM, stop accepting new connections and drain the existing ones.

Failure mode Mechanism that handles it
Too many replicas evicted at once PodDisruptionBudget
All replicas on one node or zone Topology spread, anti-affinity
No room to reschedule Pre-drain node scale-up, extra replicas
Requests dropped mid-flight preStop hook, grace period, connection draining
Forced deletion or node crash Replicas and spread (PDB doesn't apply)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      # Keep replicas on different nodes so one drain removes at most one
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app: web
        # Also balance across zones so a zone outage can't take every replica
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app: web
      # The preStop sleep counts against this, so leave room for the slowest request too
      terminationGracePeriodSeconds: 45
      containers:
        - name: web
          image: registry.example.com/web:1.4.2
          lifecycle:
            preStop:
              exec:
                # Delay SIGTERM so endpoint removal reaches load balancers first (image must include sleep)
                command: ["sleep", "10"]

A Deployment that spreads replicas across nodes and zones and adds a preStop delay and termination grace period, so a drain allowed by the PDB does not take out co-located replicas or drop in-flight requests.

How do PDBs affect engineering cost and cluster upgrade time?

PDBs are cheap to write but not free to own. Every budget is a promise one team makes about its workload, and the platform team has to honour all of them at once during a maintenance window. With dozens of budgets across many namespaces, reviewing each one and finding its owner when a drain stalls is the main ongoing cost. The YAML itself is rarely the expensive part.

Audit before the window

Run the audit a day or two before the upgrade so there is time to fix problems:

  • kubectl get pdb --all-namespaces lists every budget with its ALLOWED DISRUPTIONS column. Any row showing 0 will block eviction of matching pods.
  • kubectl get pdb -A -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}' reduces that list to the blocking budgets only.
  • kubectl describe pdb <name> -n <namespace> shows the selector and current healthy count. Use it to tell apart an unhealthy workload from a budget that can never allow a disruption, such as minAvailable equal to the replica count.

Agree on the override path up front

Decide before the window who may unblock a stuck drain and how. For example, run kubectl drain --timeout so a stall fails loudly instead of hanging. Then require the workload owner, or a named on-call engineer, to approve any kubectl delete pod that bypasses the Eviction API. Record each override. If engineers can bypass a budget without anyone knowing, the budget no longer protects anything.

A well-sized budget repays the effort. Upgrades finish inside their window. The cluster autoscaler can drain and remove underused nodes. Nobody force-deletes pods at 2 a.m. and then spends the next day on the incident review.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to kubernetes poddisruptionbudget, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.