Kubernetes Deployment Object Management

Kubernetes Deployment Object Management is the specific set of techniques and tooling used to create, update, and track the Deployment API object itself, distinct from the broader operational concerns of Deployment management scope. It centers on the choice between imperative and declarative object handling, and the field-tracking mechanisms Kubernetes uses to reconcile changes coming from multiple sources without one overwriting another silently.

Imperative Versus Declarative Management

Imperative Commands

Imperative management issues direct commands describing an action to take, kubectl create, kubectl scale, kubectl set image, each mutating a specific field without requiring the full desired object state to be described.

kubectl set image deployment/object-management-example app=registry.example.com/app:1.2.0

Declarative Application

Declarative management instead maintains the full desired state of the object in a manifest file and applies it, letting Kubernetes compute the diff and apply only the necessary changes, the approach kubectl apply implements.

kubectl apply -f object-management-example.yaml

kubectl apply and the Three-Way Merge

last-applied-configuration Annotation

kubectl apply stores the previously applied manifest as JSON in the kubectl.kubernetes.io/last-applied-configuration annotation, and uses it alongside the live object state and the new manifest to compute a three-way merge, correctly detecting fields that were removed from the manifest (and should be cleared) versus fields that were never managed by apply at all (and should be left untouched).

metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment","spec":{"replicas":3}}

Risk of Mixing Imperative and Declarative Changes

Because imperative commands like kubectl scale do not update this annotation, subsequently reapplying an outdated manifest with kubectl apply can silently revert the imperative change back to whatever the manifest declares, a common source of confusion when the two approaches are mixed carelessly on the same object.

Server-Side Apply

Field Managers Replace the Annotation Approach

Server-side apply tracks ownership of individual fields directly through managedFields metadata rather than a single opaque annotation, recording which client (field manager) last set each field, enabling multiple controllers or operators to co-manage different parts of the same object without one's changes clobbering another's.

kubectl apply -f object-management-example.yaml --server-side --field-manager=ci-pipeline

metadata:
  managedFields:
    - manager: ci-pipeline
      operation: Apply
      fieldsV1:
        f:spec:
          f:template:
            f:spec:
              f:containers: {}

Conflict Detection

Server-side apply detects when two field managers attempt to set the same field to different values and returns a conflict error rather than silently overwriting, requiring an explicit --force-conflicts flag to proceed, a stricter safety model than the implicit last-writer-wins behavior of the annotation-based approach.

Drift Detection

Comparing Live State to Source of Truth

Object management in GitOps-style workflows depends on being able to detect drift, differences between the object's live state and the state declared in the source-controlled manifest, typically surfaced through the same diffing mechanism kubectl diff exposes ahead of an actual apply.

kubectl diff -f object-management-example.yaml

Object Management Diagram

Choosing server-side apply with explicit field managers over annotation-based kubectl apply, particularly in environments where multiple automation systems touch the same objects, is the current best practice for avoiding the silent overwrite failure modes that plague purely client-side object management.