Introduction

ProgressDeadlineExceeded means the Deployment controller expected forward progress but did not see enough healthy new Pods become available in time. The Deployment object itself is rarely the real problem. More often the new ReplicaSet cannot pull the image, pass readiness, get scheduled, or start successfully with the new configuration.

Symptoms

  • kubectl rollout status hangs and eventually times out
  • kubectl describe deployment shows ProgressDeadlineExceeded
  • Old Pods remain while new Pods fail or never become ready
  • The rollout began after an image change, config update, or probe adjustment

Common Causes

  • The new container image cannot be pulled or started
  • Readiness or startup probes fail on the new version
  • The cluster lacks resources to schedule the replacement Pods
  • A bad ConfigMap, Secret, or environment variable breaks the new ReplicaSet

Step-by-Step Fix

  1. 1.Inspect the Deployment and new ReplicaSet
  2. 2.The Deployment condition tells you it stalled, but the ReplicaSet and Pod events tell you why.
bash
kubectl describe deployment my-deployment
kubectl get rs -l app=my-app
  1. 1.Describe one of the failing new Pods
  2. 2.Pod events are usually the shortest path to image pull, scheduling, probe, or startup failures.
bash
kubectl describe pod my-deployment-abc123
  1. 1.Check readiness and startup behavior
  2. 2.A rollout cannot progress if the new Pods never reach Ready.
  3. 3.Rollback quickly if production traffic is at risk
  4. 4.Once you know the new revision is unhealthy, restoring the last known-good version is often the safest move before deeper debugging.
bash
kubectl rollout undo deployment/my-deployment

Prevention

  • Validate new images and configuration changes before production rollout
  • Keep readiness probes honest but not overly strict for startup timing
  • Monitor rollout progress and Pod events in CI/CD
  • Maintain enough cluster capacity for the chosen rollout strategy