Valid YAML Is Not a Safe Kubernetes Rollout

Review an AI-generated Kubernetes Deployment against the live cluster, image digest, probes, resources, rollout math, shutdown behavior, and rollback evidence.

An AI assistant can produce a neat Kubernetes Deployment in seconds. The indentation is consistent. The field names look familiar. A local parser accepts the YAML, and the proposed image, port, probes, and rolling-update settings all appear to be present.

That is evidence about structure. It is not evidence that the intended cluster can admit the object, place the Pods, pull the approved image, direct traffic correctly, survive a slow start, or recover from a bad release.

A manifest can be syntactically valid while referring to the wrong namespace, changing an immutable selector, fighting an autoscaler, using a movable image tag, restarting an application during a temporary dependency failure, or requesting resources that no eligible node can provide. It can also complete a Kubernetes rollout while the application returns bad results. The control plane and the user do not define success at the same layer.

The useful response is not to ban AI-generated YAML or to decorate every manifest with more fields. It is to require four kinds of evidence: the target API accepts the exact rendered object, the target cluster can run it, traffic behavior is observed through startup and shutdown, and a failed release has a recovery path that matches the real system.

First, Bound the Claim

This workflow is limited to an existing, replicated, stateless HTTP service managed by an apps/v1 Deployment. It is not a universal Kubernetes production checklist. StatefulSets, Jobs, DaemonSets, persistent storage, database migrations, service meshes, ingress controllers, and provider-specific rollout systems introduce different state and failure boundaries.

“Safe” also needs a narrow meaning. No review can prove that a release will never fail. Here, a defensible rollout means that a named owner checked the intended change against the actual target, observed important failure paths, and recorded enough evidence to choose RELEASE or HOLD. That decision expires when the image, manifest, cluster policy, or operating context changes.

Freeze a Target Card Before Asking for YAML

A generic prompt such as “write a production-ready Kubernetes Deployment” omits the facts that determine whether the result fits. Before an AI tool drafts or revises anything, create a small target card from approved internal sources.

• Record the cluster version and distribution, namespace, Deployment name, and current live revision.
• Name the owner of scaling. If a HorizontalPodAutoscaler manages replicas, record that instead of letting a generated manifest silently reclaim the field.
• Identify the Service and routing objects that depend on the Pod labels and ports.
• Record the approved image artifact and digest, required configuration keys, and secret references without exposing secret values.
• State the availability objective, normal and peak load, allowed rollout window, and named rollback authority.
• List relevant admission policies, quotas, node constraints, and organizational release controls.

The target card is a boundary, not model training material. Do not paste kubeconfig files, tokens, Secret values, private registry credentials, customer data, internal hostnames, or unrestricted production output into an AI service. Stable placeholders can preserve relationships such as “application Secret key” or “internal dependency” without disclosing the underlying value.

Freeze the card with a version or timestamp. If the cluster or workload changes during review, update the evidence rather than pretending the original answer still applies.

Gate One: Verify Identity and Server Acceptance

Begin with identity fields because a perfectly tuned probe is irrelevant if the object controls the wrong Pods. The Deployment selector must match the labels in its Pod template. For apps/v1 Deployments, that selector is immutable after creation. Overlapping selectors can also make controllers act on Pods they should not own.

Compare the generated selector, template labels, namespace, resource name, container name, and port references with the live workload and its approved source. Do not approve an unexplained selector rewrite as routine cleanup. A selector change may require a deliberately planned replacement rather than an ordinary apply.

Scaling ownership deserves its own check. Kubernetes documentation advises omitting spec.replicas when a HorizontalPodAutoscaler or similar controller manages the field. A generated value that happens to match today’s replica count can still overwrite an independently managed decision during a later apply.

Next, render the exact artifact that the delivery system would submit. Review that result rather than only reviewing a Helm values file, a Kustomize overlay, or an AI response. With authorized credentials and the intended context, a command such as kubectl apply --dry-run=server --validate=strict -f rendered.yaml can submit a server-side request without persisting the resource.

Preserve the command context, exit status, warnings, and rendered artifact hash. Strict validation can reject invalid input, but the Kubernetes reference notes that validation may fall back to less reliable client-side behavior when server-side field validation is unavailable. Treat the result as one bounded observation.

A successful dry run does not schedule a Pod, pull an image, execute a probe, create traffic, or prove the application works. It is a gate between an untested text artifact and a candidate that deserves runtime testing.

Gate Two: Pin What Will Execute

An image tag is a label that can move. An image digest identifies specific image content and is immutable. For a reviewed release, connect the approved build record to the exact digest that appears in the rendered workload. Pinning a digest prevents a registry tag change from making different Pods run different code under the same manifest.

A digest is not a security certificate. It does not prove who built the image, whether the build was authorized, whether the software is vulnerable, or whether the application behaves correctly. Those questions need separate supply-chain and runtime evidence.

Review imagePullPolicy independently. Kubernetes sets its default when an object is first created; changing the image reference later does not automatically recalculate that field. A plausible AI rewrite can therefore produce a surprising combination of tag and pull policy. Upstream guidance also discourages :latest for production because it makes the running version harder to track and roll back.

Check image availability from the target environment, registry authorization through approved mechanisms, container command and arguments, declared ports, and every ConfigMap or Secret key reference. Keep the actual secret material outside the model and outside published test logs.

Gate Three: Give Each Probe One Job

Startup, readiness, and liveness probes are not three spellings of “healthy.” They drive different control-plane actions, so copying one endpoint into all three fields can turn a temporary problem into a restart loop.

A startup probe answers whether initialization has completed. When one is configured, Kubernetes waits for it to succeed before running liveness and readiness probes. This creates room for a genuinely slow start without weakening the steady-state liveness contract.

A readiness probe answers whether this container should receive matching Service traffic now. When readiness fails, the EndpointSlice controller removes the Pod’s address from EndpointSlices for matching Services. The container keeps running and can become ready again.

A liveness probe answers whether restarting the container is the correct response to an unrecoverable local failure. After enough failures, the kubelet restarts the container according to policy. Kubernetes explicitly warns that a poor liveness design can create cascading failures—for example, when load makes several Pods fail a check and their restarts push more work onto the remaining Pods.

Turn those definitions into three written contracts before choosing endpoints or thresholds:

• Startup contract: What work must finish before normal checks begin, and how long has that taken in observed slow cases?
• Readiness contract: What local state makes this instance temporarily unable to serve the traffic it is assigned?
• Liveness contract: What condition is both local and unlikely to recover without a restart?

Then test the contracts. Delay initialization. Make a required dependency temporarily unavailable. Apply representative load. Observe timeouts, consecutive-failure thresholds, recovery, events, restart counts, and endpoint state. A threshold copied from an example is not evidence for this application.

Readiness withdrawal is also not a promise of zero failed requests. Existing connections, in-flight work, load-balancer behavior, and data-plane update timing still need observation. Likewise, a successful liveness probe does not mean the application is returning correct business results. Pair platform status with a bounded application-level check.

Gate Four: Derive Resources From Measurements

Resource fields influence different failure paths. The scheduler uses requests when deciding whether a Pod fits on a node. On Linux, CPU limits generally create a hard ceiling that can throttle execution, while a memory-limit breach can activate out-of-memory handling and terminate a process. Treating CPU and memory as interchangeable percentages hides that difference.

Measure normal use, peak use, initialization, and relevant background work. Include sidecars and memory-backed emptyDir volumes where used; Kubernetes accounts memory-backed volume pages as memory use. Test the candidate under a representative load and preserve the observed scheduling state, throttling signals, memory high-water mark, restarts, and eviction-related events.

Do not let an AI assistant invent attractive round numbers. A request that is too small can increase contention and eviction exposure. A request that is too large can leave Pods Pending even when average cluster utilization looks low. A limit can be technically accepted and operationally damaging.

The rollout itself may temporarily require more capacity than steady state. Resource review must therefore include the maximum number of old, new, and terminating Pods that may coexist under the selected strategy and target conditions.

Gate Five: Calculate the Rollout

Words such as “rolling” and “zero downtime” are not calculations. Review desired replicas or autoscaler ownership, maxSurge, maxUnavailable, spare schedulable capacity, readiness behavior, and minReadySeconds together.

Write down the intended worst case: how many Pods may be unavailable, how many extra Pods may exist, and whether the cluster can place the surge while the old version is still running. Percentages are resolved against the desired replica count and use rounding rules, so small Deployments deserve particular attention.

minReadySeconds can require a newly ready Pod to remain ready before Kubernetes counts it as available. That is different from proving the application passed a business check. Use it as one stability signal, then observe the service under the conditions that matter to users.

progressDeadlineSeconds is also easy to overstate. When a Deployment fails to progress before the deadline, Kubernetes records a condition with reason: ProgressDeadlineExceeded. The Deployment controller does not automatically undo the change; higher-level automation may react, but that behavior must be separately identified and tested.

Revision history determines whether a prior Deployment revision remains available to the rollout tooling. Setting revisionHistoryLimit to zero removes that ability. Even when history exists, a Deployment rollback only addresses the recorded workload template. It does not reverse an external database change, repair mutated configuration, recover deleted data, or restore an image tag that now points somewhere else.

Watch updated, available, unavailable, old, and terminating replicas during the exercise. Do not equate a zero exit from rollout-status tooling with a complete user-facing verification.

Gate Six: Observe Shutdown and Disruption

A Pod is not moved intact to another node. If replacement is needed, Kubernetes creates a new Pod identity. Applications that rely on unrecorded local state or a particular Pod surviving need a different design or an explicit state boundary.

During ordinary Pod deletion, the kubelet attempts graceful termination and eventually force-kills processes that remain after the grace period. Test the actual application’s signal handling. Start representative requests, begin termination, and record when readiness changes, whether new work arrives, what happens to in-flight work, and whether the process exits before the deadline.

A long grace period is not proof of graceful behavior. A short period is not automatically efficient. The value must cover measured shutdown work while still meeting the system’s operational needs.

Do not use a PodDisruptionBudget as a generic rollout shield. PDBs limit some voluntary evictions, but they cannot prevent involuntary disruption, and direct deletion can bypass them. More subtly, Deployment and StatefulSet controllers are not constrained by PDBs during their own rolling upgrades. The workload’s update strategy governs that release path.

Build a Negative-Test Matrix

A credible review tries to make the candidate fail in controlled conditions. Use an authorized non-production environment that reflects the target’s important policies and runtime behavior. For each test, record the expected signal, observed signal, traffic effect, recovery action, timestamp, and owner.

• Use an unavailable or unauthorized image reference and observe the pull failure.
• Delay initialization beyond the normal case and verify startup behavior.
• Make readiness fail temporarily, then recover it without restarting the container.
• Trigger the local failure that liveness is meant to detect and confirm the restart path.
• Use an intentionally unschedulable request in the test lane and inspect scheduling evidence.
• Exercise memory pressure and distinguish an application error from an OOM-related restart.
• Submit a candidate that violates a representative policy or quota and preserve the rejection.
• Remove spare capacity and verify how the rollout behaves when surge Pods cannot be placed.
• Terminate a Pod with in-flight work and inspect completion, refusal, retry, or loss.
• Release a deliberately bad application revision, stop the rollout, and rehearse the authorized recovery path.

These tests are not a command checklist to run blindly against production. The owner chooses safe fixtures, permissions, environment, and abort conditions. AI can help organize observations, but it should not receive live credentials or independent authority to execute cluster changes.

Assemble a Release Evidence Packet

The final decision should point to artifacts, not confidence. A compact packet can include:

• the target card and cluster/version scope;
• the rendered-manifest hash and reviewed live change;
• the approved image digest and build reference;
• server validation output and unresolved warnings;
• measured resource and scheduling evidence;
• startup, readiness, liveness, and shutdown observations;
• rollout math and observed replica states;
• an application-level result check;
• the rehearsed recovery action and anything it cannot reverse;
• a named owner’s dated RELEASE or HOLD decision.

If any item changes, identify which evidence must be repeated. A new image under the same manifest is still a new executable artifact. A cluster-policy change can invalidate an earlier dry run. A new dependency can make an old readiness contract incomplete.

Worked Example: Accepted, Then Held

Consider a fictional AI-generated Deployment for a small HTTP service. It is well formatted and the target server accepts it in a dry run. The proposal uses an image tagged latest, declares no measured resource requests, sends startup, readiness, and liveness checks to one dependency-heavy endpoint, chooses a replacement strategy incompatible with the stated availability objective, and retains no rollout history.

None of those choices is proof that AI is uniquely bad at Kubernetes. A person can make the same errors. The problem is that fluent configuration makes the choices look coordinated even though each came from a missing requirement.

The reviewer records HOLD. The build owner supplies the approved digest. Workload measurements produce initial request and limit candidates for controlled load testing. The application team separates startup, readiness, and liveness contracts and demonstrates slow-start and temporary-dependency behavior. The platform owner calculates capacity for the chosen rolling-update settings. The service owner observes termination with in-flight requests. Finally, the release owner rehearses recovery from a bad revision and records that external state is outside Deployment rollback.

The corrected candidate is not approved because it contains more YAML. It is approved only if the evidence supports the target card and no unresolved failure crosses the stated boundary. Another cluster, workload, traffic pattern, or policy set would require another decision.

What This Review Does Not Prove

It does not establish zero downtime, complete Kubernetes security, regulatory compliance, image provenance, absence of vulnerabilities, or universal production readiness. It does not replace application tests, observability, incident planning, provider documentation, or accountable platform review.

It also does not mean every Deployment needs every optional field. Extra configuration can create extra failure modes. The goal is not maximal YAML; it is a traceable connection between an intended behavior, the field that influences it, and an observation from the real target or a representative test lane.

AI is useful for proposing questions, comparing a draft with a target card, and organizing an evidence packet. It is not the target cluster, the workload owner, or the release authority.

Source and Version Note

Sources were checked on August 23, 2026. The current upstream Kubernetes documentation is v1.36. Readers should use documentation for their deployed cluster version and distribution, because supported fields, feature states, admission behavior, and operational tooling can differ.

• Supported Documentation Versions identifies the current and archived upstream documentation sets.
• Deployments documents selectors, autoscaler ownership, rollout status, progress deadlines, availability, and revision history.
• Liveness, Readiness, and Startup Probes defines the three probe actions and warns about cascading failures from poor liveness design.
• Resource Management for Pods and Containers explains scheduling requests, CPU and memory limits, and memory-backed volume accounting.
• Images distinguishes tags from digests and documents image-pull policy behavior.
• kubectl apply defines server dry-run and strict-validation options and their limits.
• Disruptions explains voluntary and involuntary disruptions and the boundary of PodDisruptionBudgets.
• Pod Lifecycle documents Pod replacement, readiness, probes, and graceful termination.