Last reviewed: November 8, 2026 (Asia/Shanghai); primary references checked November 7 UTC.
Direct answer
Review a Kubernetes Deployment rollout in a coding-agent patch by calculating its unavailable and surge allowances, checking what makes a new Pod available, and collecting completion evidence for the candidate’s exact revision. Exercise a healthy update and a stalled update in an approved disposable environment. Require a separate recovery decision: progressDeadlineSeconds reports stalled progress; it does not automatically restore the previous release.
The Kubernetes Deployments reference defines the controller behavior. The rollout status reference explains how to watch a specific revision. The rollout undo reference documents selecting and previewing a rollback target. Together, they support checking both the replacement policy and the evidence used to approve it.
Who this is for
Use this workflow when a coding agent changes an apps/v1 Deployment, its Pod template, or the Helm values and Kustomize overlays that render it. It is intended for maintainers reviewing stateless application updates that temporarily run old and new versions together. StatefulSets and other workload controllers require their own controller-specific review.
Give the agent the minimum serving capacity, supported replica range, target Kubernetes version, scheduling constraints, and release procedure. Ask it to identify the changed template and explain the integer rollout allowances. The examples below are review fixtures and proposed acceptance checks; no authenticated cluster tests or deployments were performed for this article.
Key takeaways
- Calculate percentage settings at the smallest supported replica count, as well as normal and maximum scale.
- Reserve capacity for surge Pods and for old Pods that are still terminating.
- Treat readiness, minimum-ready duration, controller progress, and CLI timeout as separate observations.
- Pin
kubectl rollout statusto the candidate revision so another update cannot supply its success result. - Preview a retained rollback target and verify its application compatibility before executing recovery.
Sources checked
Three primary Kubernetes pages were retrieved successfully on November 7, 2026 UTC:
- Deployments documents rollout triggers, percentage rounding, availability, progress conditions, retained revisions, and the scope of rollback.
- kubectl rollout status
documents
--revision, rollover behavior, and the watch timeout. - kubectl rollout undo
documents
--to-revisionand server-side dry-run without persisting the resource.
These maintained technical references support an evergreen task. The Deployment page reports a July 7, 2026 modification; both command references report an August 26, 2026 update for Kubernetes v1.37. Match the documentation and command options to the target server and client versions. The review below uses established Deployment fields and does not depend on optional terminating-replica status fields.
Contract details to verify
Identify the intended change and availability floor
Render every affected environment before reviewing the strategy. Compare the current and candidate Pod templates, image references, replica ownership, readiness configuration, and scheduling requirements. A Deployment rollout is triggered by a change to .spec.template; changing only the replica count or rollout strategy does not create a new template revision. Do not accept a successful status check for an unchanged template as proof that new application code ran.
Keep the Deployment selector stable. In apps/v1, it is immutable after creation. If an agent responds to a selector error by proposing deletion and recreation, that introduces a different replacement operation requiring its own availability review.
Write an acceptance statement such as: “Four API replicas must remain available while the candidate is introduced; the test environment can schedule one additional replica; both versions must work against the current application data.” The serving floor and overlap compatibility are application decisions. A syntactically valid strategy cannot establish either one.
Convert percentages into replica counts
For a RollingUpdate Deployment, Kubernetes rounds percentage maxUnavailable down and percentage maxSurge up. Both settings default to 25%. They cannot both be zero. The following calculations apply those documented rules to a healthy starting Deployment:
| Desired replicas | 25% unavailable, rounded down | 25% surge, rounded up | Configured availability floor |
|---|---|---|---|
| 1 | 0 | 1 | 1 |
| 3 | 0 | 1 | 3 |
| 4 | 1 | 1 | 3 |
| 6 | 1 | 2 | 5 |
The floor is desired replicas minus the unavailable allowance. It describes the rollout policy, not a guarantee against independent failures. Notice that moving from three to four replicas changes the default unavailable allowance from zero to one. Review the computed values rather than assuming an unchanged percentage has an unchanged operational meaning.
For the four-replica contract above, this fragment belongs under an existing Deployment’s spec, alongside its reviewed selector and Pod template:
replicas: 4
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 0
maxSurge: 1
minReadySeconds: 20
progressDeadlineSeconds: 300
revisionHistoryLimit: 5
These are illustrative choices, not universal defaults. With no unavailable allowance, the controller needs a replacement to become available before removing healthy old capacity. If quota or scheduling constraints prevent the extra Pod, progress can stall. Diagnose that constraint instead of asking the agent to loosen the serving floor merely to make the rollout finish.
Also account for termination overlap. The Deployment reference warns that terminating Pods can continue consuming resources, so actual resource demand can exceed what a simple replicas + maxSurge calculation suggests. Inspect old Pod deletion timestamps and shutdown duration when planning headroom. The surge setting is insufficient as a hard ceiling on total CPU or memory consumption.
Separate availability, progress, and waiting time
minReadySeconds specifies how long a new Pod must remain ready without any container crashing before it counts as available. Its default is zero. In the fragment, a brief readiness success is insufficient: the Pod must satisfy the 20-second availability requirement. The readiness handler must still measure a useful serving condition. Use the health-probe review guide
when that contract also changes.
progressDeadlineSeconds detects lack of rollout progress. It must exceed minReadySeconds and defaults to 600 seconds. Progress includes controller actions such as scaling ReplicaSets and new Pods becoming ready or available. It is not an unconditional wall-clock limit on the entire release. A paused rollout also suspends progress-deadline checking.
When the deadline is exceeded, the controller reports Progressing=False with reason ProgressDeadlineExceeded. Kubernetes does not automatically roll back because of this condition; the controller continues retrying. Record which release controller or authorized operator will decide whether to repair forward or restore an earlier template.
The --timeout on kubectl rollout status limits the CLI watch. A watch timeout can happen before the controller’s progress deadline, and ending the watch does not cancel the rollout. Preserve the exit status and inspect current conditions before choosing recovery. Do not convert every nonzero CLI result into an automatic rollback instruction.
Bind status evidence to the candidate revision
Before the test update, record the source revision and rendered manifest. After the approved test deployment, capture the Deployment UID, generation, observed generation, template, and controller revision. Compare the owned ReplicaSet’s template with the candidate; a revision number by itself is not a source-code identity.
For an illustrative Deployment named api, this read-only capture exposes the relevant state:
kubectl --context review-cluster --namespace agent-review \
get deployment api -o json |
jq '{uid: .metadata.uid,
generation: .metadata.generation,
observedGeneration: .status.observedGeneration,
revision: .metadata.annotations["deployment.kubernetes.io/revision"],
desired: .spec.replicas,
updated: .status.updatedReplicas,
available: .status.availableReplicas,
conditions: .status.conditions,
template: .spec.template}'
Require controller observation of the candidate generation before interpreting its status. Inspect ReplicaSet owner references against the Deployment UID, and retain old and new Pod identities. Then watch the recorded candidate revision. Here, 7 is an example to replace with the verified revision:
kubectl --context review-cluster --namespace agent-review \
rollout status deployment/api --revision=7 --timeout=6m
The official status reference says the default watch follows the latest rollout, including a newer one that begins during the watch. --revision=7 instead aborts if another revision supersedes it. Treat that abort as an interrupted candidate test. Do not reuse the later rollout’s success for the earlier patch.
Available=True alone is also insufficient: old replicas can maintain minimum availability while the new version is stuck. Inspect updated and available counts, the candidate ReplicaSet, and the Progressing reason. The Deployment reference distinguishes an in-progress rollout from completion, where all desired replicas are updated and available and old replicas have been replaced.
Test progress and recovery independently
Run the candidate through the team’s approved disposable-cluster release workflow. Capture timestamps, controller conditions, ReplicaSet counts, Pod events, and harmless application requests throughout each case. These are proposed checks, not reported results:
| Controlled case | Evidence required |
|---|---|
| Healthy template update | Candidate revision completes; sampled availability respects the agreed floor; application requests remain acceptable |
| New version stays unready while the old version is healthy | Candidate remains incomplete; old capacity is distinguishable; lack of progress is reported without an assumed automatic rollback |
| Extra Pod cannot schedule under the fixture’s capacity constraint | Scheduling or quota diagnostics explain the stall; the review does not silently lower the availability floor |
| Another template update supersedes the watched candidate | The pinned watch aborts; evidence is retained under the original candidate identity |
| Approved recovery to a retained healthy template | Recovery obtains its own revision, completion evidence, and application checks |
Use a known healthy baseline before each failure case and restore it afterward. A few sampled controller counts cannot prove that every request succeeded. Keep application-level checks and their observation window separate from the rollout status result.
Inspect what rollback can actually restore
Deployment history stores Pod templates in retained ReplicaSets. The documented default revisionHistoryLimit is ten; the fragment retains five. Once old history is cleaned up, an absent revision cannot be recovered through rollout undo. Review retention against the team’s recovery needs before approving an agent’s cleanup change.
In the disposable environment, inspect a known healthy revision and preview the operation. Here, 6 is illustrative:
kubectl --context review-cluster --namespace agent-review \
rollout undo deployment/api --to-revision=6 --dry-run=server -o yaml
The undo reference defines server-side dry-run as a server request that does not persist the resource. It previews the operation; it does not demonstrate replacement Pods becoming healthy. Execute recovery only through the approved release procedure after the owner checks the target template and application compatibility.
The Deployment reference states that rollback restores only the Pod-template part. Therefore, include a separate recovery plan for database changes or independently changed configuration objects. Undoing the template cannot establish that those external changes were reversed. A rollback also produces a new Deployment revision: capture that new identity and watch it rather than continuing to watch the historical target number.
Failure modes
The strategy is called safe because all replicas are currently available. Calculate its allowances at supported scales and test a replacement. A healthy steady-state snapshot does not exercise the rollout policy.
A green watch belongs to another commit. Pin the candidate revision and retain the rendered template plus owning Deployment UID. Restart the review when another update supersedes it.
A shorter deadline is presented as automatic recovery. Establish who consumes the failure condition and what that actor is authorized to change. The Deployment controller reports stalled progress without restoring the old template.
Rollback is treated as an application-wide restore. Inspect retained history and external compatibility. A template reversal does not reverse a database migration.
If the patch also changes maintenance or eviction policy, review the PodDisruptionBudget contract as a separate acceptance task.
FAQ
Does maxUnavailable: 0 guarantee zero downtime?
No. It constrains the replacement policy, while readiness accuracy, spare capacity, independent failures, and compatibility between versions still matter. Verify the application through its normal request path during the update.
Does scaling a Deployment create a new rollout revision?
No. The Deployment reference ties new revisions to Pod-template changes. Scaling alone changes the desired count without creating a template revision.
Is a successful rollback dry-run enough to approve recovery?
No. It does not persist the requested change or exercise replacement Pods. Review the target template, execute an authorized recovery test, and collect fresh rollout and application evidence.
Reader next step
Choose one agent-written Deployment patch. Attach the rendered before-and-after templates, integer rollout allowances, serving floor, and surge-capacity assumptions to its pull request. In the disposable environment, verify a healthy candidate, an unready candidate, and a retained-template recovery. Keep the revision-specific watch result, controller conditions, Pod identities, and application observations together so the reviewer can connect each result to the exact change being approved.