阅读中文版本

Kubernetes Deployment ProgressDeadlineExceeded

Fix ProgressDeadlineExceeded by checking rollout status, readiness probes, and image pull or scheduling failures that block progress.

kubectl describe deploy <name> | grep -A 3 "Progressing\|Conditions" && kubectl get rs -l app=<name>

kubectl get pods -l app=<name> -o wide && kubectl describe pod <new-pod> | tail -20

Symptoms

The error “Kubernetes Deployment ProgressDeadlineExceeded” points at a specific failure mode. This guide documents the symptoms you can observe, the commands that isolate the cause, the root cause, the fix, and the checks that prove the fix works.

Observed symptoms include:

• kubectl rollout status reports “exceeded its progress deadline”
• The deployment shows 0 or partial available replicas
• New pods stay Pending or never become Ready

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Inspect the rollout condition and events

kubectl describe deploy <name> | grep -A 3 "Progressing\|Conditions" && kubectl get rs -l app=<name>

The condition message points at the blocking step—Scheduling, Pulling, or Readiness.

Step 2: Trace the new pod status

kubectl get pods -l app=<name> -o wide && kubectl describe pod <new-pod> | tail -20

Pending, ImagePullBackOff, or CrashLooping reveal the specific blocker to fix.

Likely contributors, in order of frequency:

• New pods fail to schedule, pull the image, or pass readiness probes
• The rollout is genuinely slow so the default 600s deadline is too short
• A previous rollout left the replicaset stuck, blocking the new one

Root Cause

A Deployment reports ProgressDeadlineExceeded when its newest ReplicaSet has not progressed—new pods available—within progressDeadlineSeconds. The condition signals a blocking failure downstream, not the deployment itself.

The Fix

Fix the underlying blocker (image, scheduling, probes, or resource limits), raise progressDeadlineSeconds for genuinely slow rollouts, and ensure the new pods pass readiness before the deadline.

Watch out: Raising the deadline hides a real blocker; fix the blocker first, then adjust only if the rollout is legitimately slow.

spec:
  progressDeadlineSeconds: 900   # only after confirming the rollout is legitimately slow
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  template:
    spec:
      containers:
        - name: app
          readinessProbe:
            httpGet: { path: /health, port: 8080 }
            initialDelaySeconds: 5
            periodSeconds: 5

Verify and Prevent

Rerun the rollout and confirm it completes with all replicas available; verify rollout status reports success before the deadline.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.