Kubernetes Manifest Update Behavior

Kubernetes Manifest Update Behavior is the specific behavior of a full-object replace operation — issued as kubectl replace -f or through a raw HTTP PUT request — in which an entire manifest is submitted to overwrite an existing object's complete content wholesale, distinct from both the patch-based partial updates apply performs and the fail-if-exists semantics of create. A replace-style update requires the submitted manifest to represent the object's entire intended state, since anything the manifest omits that the live object currently has is removed, not merely left untouched.

Full Replacement Versus Partial Patch

The Submitted Object Becomes the New Object

Unlike a patch, which describes only the changes to make, a PUT-based update request is interpreted as the object's new complete state; any field present on the live object but absent from the submitted manifest is treated as intentionally removed, which is the opposite default behavior from apply's more forgiving three-way merge, where unmentioned fields are typically left alone.

resourceVersion as a Mandatory Precondition

A replace request must include the target object's current resourceVersion in the submitted manifest, and the API server rejects the request with a conflict error if that resourceVersion does not match the object's actual current version — meaning a replace workflow inherently requires first reading the current object (to obtain its resourceVersion and full current content) before submitting an update, unlike apply or create, which can be issued without any prior read.

The Read-Modify-Write Pattern

Why a Prior Read Is Required

Because a replace must supply the complete object and the exact current resourceVersion, the standard pattern is to first get the object, apply the desired modification to the retrieved content locally, and then submit the modified full object back as the update, ensuring both that no unrelated fields are accidentally dropped and that the resourceVersion precondition is satisfied.

Protection Against Lost Updates

This required read-modify-write cycle, combined with the resourceVersion precondition, is precisely what protects against the classic lost-update race condition: if another client modifies the object between the initial read and the replace submission, the resourceVersion mismatch causes the replace to fail rather than silently overwriting the intervening change, forcing the client to re-read and retry with current data.

Immutability Enforcement During Update

Rejecting Changes to Immutable Fields

A replace request that alters a field the target type has designated as immutable once set — such as a Pod's node assignment or certain identity-related fields — is rejected during validation exactly as it would be under any other update mechanism, since immutability rules apply uniformly regardless of whether the update arrives as a full replace or a partial patch.

Common Source of Replace Failures

Because a replace submits the entire object, including every field the prior get returned, an update attempt that inadvertently includes an unintended change to an immutable field (through careless local editing of the retrieved object) is a common cause of replace failures, distinct from resourceVersion conflicts, and requires the client to isolate exactly which field triggered the immutability rejection before resubmitting.

When Replace Is Preferred Over Apply

Explicit, Complete State Assertions

Replace is well suited to situations where a client wants to assert the object's entire state explicitly and be certain that no stray, previously-set fields from other actors persist unintentionally, trading apply's convenience and coexistence-friendliness for a stricter, more deliberate all-or-nothing update.

Programmatic Workflows With Read-Before-Write Already in Place

Controllers and automation that already read an object as part of their normal reconciliation logic, and therefore already have its current resourceVersion and full content in hand, often use replace-style updates naturally, since the read-modify-write cycle replace requires is simply the pattern their reconciliation loop was already following.