How to Use a Kubernetes PodDisruptionBudget

What a PodDisruptionBudget actually does

A PodDisruptionBudget (PDB) is a policy object that limits voluntary disruptions - node drains, cluster upgrades, or manual kubectl delete pod. It tells Kubernetes: "never bring this Deployment below N running pods." Without one, a drain can evict every pod on a node, including all three replicas if they happen to be co-located.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web-pdb
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: web

With minAvailable: 2 and 3 replicas, a drain is only allowed to proceed if at least 2 pods remain schedulable elsewhere. The drain blocks until that constraint is satisfied.

The missing half: topologySpreadConstraints

A PDB protects during disruption, but the scheduler still has to place the pods first. topologySpreadConstraints tells the scheduler to spread replicas across distinct nodes (or zones) at scheduling time, so the disruption scenario never gets bad to begin with.

Add this inside the spec.template.spec of the Deployment:

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app: web

maxSkew: 1 means no node can have more than one extra pod compared to the least-loaded node. whenUnsatisfiable: DoNotSchedule makes the pod stay Pending rather than violate the spread - a hard guarantee, not a hint.

Putting it together in one file

Both objects go in the same deployment.yaml, separated by ---:

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web-pdb
spec:
  minAvailable: 2
  selector:
    matchLabels: {app: web}
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels: {app: web}
  template:
    metadata:
      labels: {app: web}
    spec:
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels: {app: web}
      containers:
        - name: web
          image: nginx:stable

Apply and verify:

kubectl apply -f deployment.yaml
kubectl get pdb web-pdb          # check ALLOWED DISRUPTIONS
kubectl get pods -o wide          # confirm replicas are on different nodes

What to check in production

• PDB + HPA together - set minAvailable lower than your HPA minimum so scale-down events are not permanently blocked.
• Zone spread - change topologyKey to topology.kubernetes.io/zone for multi-AZ clusters; combine with kubernetes.io/hostname for belt-and-suspenders.
• Every workload, not just the important ones - PDB-less Deployments are the ones that disappear during a routine node upgrade and cause an on-call page.