Context
ProgressDeadlineExceeded means a Deployment failed to make expected progress within its configured interval. It does not tell you which startup dependency failed, and it does not automatically undo the release. Existing replicas may still serve users while new replicas are stuck. Treat rollout progress and current availability as related but different observations.
Before investigating, record the namespace, Deployment, release identifier, expected image, and last known healthy revision. You need read access to Deployments, ReplicaSets, Pods, and events. Capture the live state before a pipeline retries or another release replaces the evidence.
1. Read conditions and rollout configuration
kubectl -n shop get deployment catalog -o yaml
kubectl -n shop describe deployment catalog
kubectl -n shop rollout status deployment/catalog --timeout=30s
Inspect observedGeneration, desired replicas, available replicas, and the Progressing condition's reason. Compare progressDeadlineSeconds with minReadySeconds and the actual startup process. Also check whether the Deployment is paused. The controller does not estimate progress during a pause, which changes how a seemingly long elapsed rollout should be interpreted.
2. Identify the new ReplicaSet and its Pods
kubectl -n shop get replicasets -l app=catalog
kubectl -n shop get pods -l app=catalog -o wide
kubectl -n shop get events --sort-by=.metadata.creationTimestamp
Confirm the selector matches your workload before drawing conclusions. Compare the new ReplicaSet's desired and current counts. If it has no created Pods, inspect its events for admission or quota failures. If Pods exist but remain Pending, follow scheduling evidence. If containers are waiting or restarting, inspect the specific waiting reason and current or previous container logs as permitted.
3. Separate startup work from rollout policy
For an explicitly illustrative example, a new catalog revision references an unavailable configuration object. Old replicas continue serving, but replacement Pods cannot start. Increasing the deadline changes when the stalled rollout is reported; it cannot supply the missing configuration. Fix that dependency in the reviewed release configuration and then observe the new revision.
A slow but legitimate initialization path needs a different correction. Measure representative startup and availability transitions before adjusting timing. Include time needed for image retrieval and controlled scheduling pressure. Avoid using an arbitrarily large deadline that leaves a broken release appearing inconclusive throughout an operating shift.
Diagnose the stage before choosing a response
| Observation | Stalled stage | Next evidence |
|---|---|---|
| New ReplicaSet cannot create Pods | Admission | ReplicaSet events and namespace policy |
| New Pods remain Pending | Placement | Pod scheduling events and constraints |
| Container waits or repeatedly exits | Initialization | Waiting reason and sanitized logs |
| New Pods run but never become available | Availability transition | Conditions, readiness and minReadySeconds |
Changing maxSurge or maxUnavailable also changes capacity and rollout behavior. Review those settings only when resource or availability evidence makes them relevant. A capacity-constrained rollout can require a planned resource change; it should not trigger an unreviewed relaxation of availability expectations.
Verify recovery and keep a release SOP
Choose either a corrected release or a reviewed rollback based on application compatibility and the incident process. Do not assume the Deployment condition caused an automatic rollback. After the chosen action, confirm the intended image, current generation, replica counts, successful rollout status, and a harmless user transaction.
Store a release checklist with expected initialization steps, progress deadline rationale, minimum available capacity, and escalation owner. Monitor both stalled-rollout conditions and user-facing errors. Preserve the first failure event and revision identifiers in the incident record, so a successful retry does not erase the explanation of what originally blocked progress.
Explore Clouvenix containers kubernetes for implementation and operational handover.