6.12 Kubernetes Manifest Update Behavior

Kubernetes Manifest Update Behavior is the range of distinct mechanisms available for modifying an already-existing object's configuration, spanning full-body replacement, targeted patching, interactive editing, and manifest-based apply, each carrying different requirements around concurrency control, immutable field handling, and how the resulting change propagates into a controller's subsequent reconciliation behavior.

Full Replacement Updates

The replace Operation

A replace operation, backed by HTTP PUT, requires the caller to submit the object's complete current body, including an up-to-date resourceVersion, and replaces the entire object wholesale with what was submitted, meaning any field the caller's submitted body omits, that was not itself omitted in the live object, is effectively cleared.

Optimistic Concurrency Enforcement

Because replace requires an explicit resourceVersion, the API server rejects the request if the live object's version has advanced since the caller last read it, protecting against a caller unknowingly overwriting a concurrent change made by another actor between their read and their write.

Targeted Patch Updates

Patch Without a Full Read

Patch operations, using any of the supported patch formats, allow a caller to submit only the specific fields being changed, without needing to first read and resubmit the entire object, reducing both the risk of accidentally clobbering unrelated fields and the size of the request itself.

kubectl patch as a Direct Tool

The kubectl patch command exposes this capability directly for scripting and automation purposes, letting an operator or pipeline make a narrow, surgical change, such as updating a single label or a specific container's image, without needing to construct or maintain a full manifest for that change.

Interactive Editing

kubectl edit Workflow

kubectl edit retrieves the live object, opens it in the user's configured text editor, and upon save, computes and submits the resulting difference as an update, functioning as a convenient interactive wrapper around the underlying patch or replace mechanics rather than introducing any fundamentally new update semantics of its own.

Risks of Manual Editing

Because interactive editing bypasses any manifest source of truth, changes made this way are not reflected back into version-controlled manifests, creating configuration drift between what a repository declares and what is actually running unless the change is manually backported into the corresponding manifest afterward.

Manifest-Driven Apply Updates

Apply as the Declarative Update Path

As detailed in the declarative apply behavior, applying an updated manifest against an already-existing object performs a merge-based update respecting field ownership or last-applied tracking, representing the update path most aligned with treating manifests as the ongoing, durable source of truth for an object's configuration.

Handling Immutable Fields During Update

Fields That Reject Modification

Certain fields across various resource types are marked immutable after creation, such as a Deployment's spec.selector or a Service's spec.clusterIP in most configurations, and any update attempt, through any of the above mechanisms, that tries to change such a field is rejected by validation regardless of which update path was used to submit it.

Working Around Immutability

When a genuinely immutable field needs to change, the only path forward is deleting and recreating the object with the new value, since no update mechanism can bypass a field's immutability constraint, a consideration that manifest authors need to account for when designing configuration intended to evolve over time.

Downstream Effects of Spec Updates

Triggering Controller Reconciliation

An update to spec is what actually causes a controller to notice a change and begin reconciling toward the new desired state; for workload controllers, this frequently manifests as a rolling update, where old Pods are gradually replaced by new ones reflecting the updated Pod template, rather than an instantaneous, all-at-once transition.

Generation Increments Signal Meaningful Change

As covered under the object lifecycle model, spec updates increment an object's generation, giving controllers and observers a reliable signal that a meaningful desired-state change has occurred, distinct from status-only updates that leave generation unchanged, which is part of why controllers key their reconciliation triggers off generation changes specifically.