Kubernetes PodDisruptionBudget Guide: Prevent Availability Loss During Maintenance and Scaling

Overview

A PDB limits voluntary disruptions for a group of pods. Typical examples include a node drain, cluster maintenance, or an administrator-initiated eviction. It does not prevent every source of downtime: a crashed process, failed node, application bug, or network problem is an involuntary or unrelated failure and must be addressed with other Kubernetes high-availability controls.

The two main budget styles are:

• minAvailable: the minimum number or percentage of selected pods that should remain available.
• maxUnavailable: the maximum number or percentage of selected pods that may be unavailable during a voluntary disruption.

Use one of these fields, not both. The PDB selector must match the labels on the workload's pods, not merely labels on the Deployment or StatefulSet object. A selector that matches no pods protects nothing; a selector that matches several unrelated workloads can make maintenance unexpectedly difficult.

A PDB is also not a replica controller. It does not create pods, spread them across nodes, add capacity, or repair an unhealthy application. Pair it with appropriate replica counts, topology spread or affinity rules, resource requests and limits, and meaningful readiness checks. For sizing those resource settings, see Kubernetes Requests and Limits: A Practical Guide.

How to estimate

Start with the number of replicas that the PDB selects and the minimum service level your application can tolerate during maintenance. Let R represent the expected number of healthy replicas and U represent the maximum number that may be unavailable.

For a simple fixed-count estimate, U = R - M, where M is the minimum number of healthy replicas required. If a service normally runs five replicas and must retain four during a drain, the budget can allow one unavailable replica. The equivalent intent is minAvailable: 4 or maxUnavailable: 1.

Percentages are useful when replica counts change, but inspect the result at the smallest expected scale. A percentage applied to a small workload may round differently than an operator expects. If the application has one replica, a strict availability requirement can make voluntary eviction impossible. That may be the correct safety outcome, but it means node maintenance requires a rescheduling plan or temporary scaling.

Inputs and assumptions

Before creating a PDB Kubernetes administrators can rely on, record these inputs:

1. Selected replicas: Confirm how many pods the label selector matches under normal operation and during scale-down.
2. Safe minimum: Define the smallest number of ready pods that can serve traffic acceptably. Base this on application behavior, not just replica count.
3. Replacement capacity: Check whether another node has enough CPU, memory, storage, and scheduling capacity for a replacement pod. A PDB cannot make an unschedulable pod available.
4. Readiness behavior: Verify that readiness probes reflect real ability to serve requests. A pod that is running but not ready should not be counted as usable capacity.
5. Maintenance concurrency: Decide whether one node, several nodes, or an automated process may be disrupted at once. The budget should match the operational process.
6. Workload ownership: Make sure the selector maps to one intended workload group. Avoid broad labels such as an environment label unless all matching pods share the same availability policy.

Example manifest:

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: payments-pdb
  namespace: production
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      app: payments

This example assumes the payments workload uses the app: payments label on its pods and can tolerate one selected pod being unavailable. If the service has changing replica counts, test the effective result at both its minimum and maximum scale.

Worked examples

Three replicas with a two-pod service floor

If three replicas normally serve traffic and two must remain available, choose minAvailable: 2 or maxUnavailable: 1. Both express the same intended limit for that replica count. During a node drain, Kubernetes may need to wait for a replacement pod to become available before evicting another selected pod.

Five replicas with maintenance headroom

Suppose five replicas are distributed across nodes and the application can operate with four. maxUnavailable: 1 is explicit and easy to review. A percentage may be more convenient if the workload scales, but validate the effective count at three, five, and any other meaningful replica levels.

Why a drain can remain blocked

A command such as kubectl drain can report that eviction is blocked when removing a pod would violate the PDB. First inspect the object and selected pods:

kubectl get pdb -n production
kubectl describe pdb payments-pdb -n production
kubectl get pods -n production -l app=payments -o wide
kubectl get deployment payments -n production

Check the PDB's current healthy, desired, and disrupted counts, then check whether replacement pods are pending because of resource requests, node selectors, taints, affinity, or storage constraints. Do not immediately delete the pod to bypass the budget; that changes a controlled eviction into a potentially disruptive action. For broader workload failures, the CrashLoopBackOff troubleshooting runbook can help separate application health problems from scheduling problems.

When to recalculate

Revisit the PDB whenever replica counts, traffic patterns, deployment strategy, node capacity, or maintenance automation changes. Recalculate it before a cluster upgrade, node-pool rotation, autoscaling change, or migration to a new topology. Also review it after a blocked drain: the incident may reveal that the budget is too strict, replacement capacity is insufficient, or the workload is not distributed as intended.

Use this practical workflow:

1. Confirm the selector matches only the intended pods.
2. Measure the minimum healthy replica count required for acceptable service.
3. Compare that requirement with the workload's minimum autoscaler replica count.
4. Apply the PDB in a non-production environment or during a controlled window.
5. Test an eviction and observe replacement scheduling, readiness, and application errors.
6. Run a drain plan with the same concurrency used by your maintenance tooling.
7. Document the chosen value and the reason, including when an exception or temporary relaxation requires approval.

Finally, connect PDB reviews to deployment planning. Rolling, blue-green, and canary strategies each create different temporary capacity demands; the comparison in Blue-Green vs. Canary vs. Rolling Deployments can help frame those trade-offs. A well-calculated PDB protects availability while leaving maintenance a realistic path forward.