Kubernetes Declarative Change Guidelines

Kubernetes Declarative Change Guidelines are the practical conventions for choosing among Kubernetes's three management approaches, imperative commands, imperative object configuration, and declarative object configuration, and for structuring change management so that version-controlled manifests remain the authoritative record of cluster state rather than a document that drifts silently out of sync with what is actually running.

The Three Management Approaches

Imperative Commands

kubectl create deployment web --image=myapp:1.0
kubectl scale deployment web --replicas=5

Imperative commands operate directly on live objects with no manifest file involved at all, fast for one-off tasks and interactive debugging but leaving no artifact for version control to track, meaning the exact command that produced a given state is not recoverable from the cluster alone after the fact.

Imperative Object Configuration

kubectl replace -f deployment.yaml
kubectl delete -f deployment.yaml

Imperative object configuration operates on a manifest file but through commands that fully replace or delete the object rather than computing a merge, meaning a replace overwrites the entire object, including any fields set by another actor since the manifest was last generated, discarding them without a three-way merge's protection.

Declarative Object Configuration

kubectl apply -f deployment.yaml

Declarative object configuration, kubectl apply, computes a three-way merge between the last-applied configuration, current live state, and the new manifest, preserving fields managed by other actors while applying exactly the changes the manifest author intended, the approach recommended as the default for anything tracked in version control.

When Imperative Commands Remain Appropriate

Debugging, Inspection, and Genuine Emergencies

kubectl scale deployment web --replicas=10

An imperative kubectl scale command issued during an active incident to immediately add capacity is a reasonable, time-critical exception to declarative-first practice, provided the corresponding manifest is updated afterward to reflect the new intended state, closing the gap between what was done in the emergency and what version control describes going forward.

Field Ownership Conflicts in Mixed Management

Server-Side Apply and Field Managers

kubectl apply --server-side -f deployment.yaml --field-manager=ci-pipeline

When multiple actors, a CI pipeline applying declarative manifests, an autoscaler adjusting replicas directly, a human occasionally using kubectl edit, manage the same object, server-side apply's explicit field-manager tracking surfaces conflicts clearly (rejecting a conflicting write unless --force-conflicts is passed) rather than silently overwriting another actor's intended field, a meaningfully clearer failure mode than client-side apply's annotation-based merge produces in the same scenario.

kubectl get deployment web -o yaml --show-managed-fields

GitOps as the Fullest Expression of Declarative Practice

Continuous Reconciliation From a Single Source

apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  syncPolicy:
    automated:
      selfHeal: true

A GitOps controller extends declarative management from a one-time kubectl apply into a continuously enforced guarantee: any manual, out-of-band change to a resource is automatically reverted on the controller's next reconciliation pass, making Git the unambiguous single source of truth rather than merely the intended one, closing the gap that plain kubectl apply alone leaves open between successive applies.

Avoiding the "Worked Once Manually, Forgot to Codify" Anti-Pattern

Every Fix Deserves a Corresponding Commit

A change applied directly to a live cluster to resolve an urgent problem, and never subsequently reflected in the manifest repository, becomes invisible technical debt: the next kubectl apply of the outdated manifest silently reverts the fix, reintroducing the original problem with no obvious connection to why it recurred; treating every manual production change as incomplete until its corresponding manifest update is committed closes this gap systematically rather than relying on memory.

Previewing Changes Before Applying

kubectl diff as a Pre-Apply Safety Check

kubectl diff -f deployment.yaml

Running kubectl diff before kubectl apply shows exactly what would change against current live state, catching an unintended difference, a stale value left over from a previous manual edit, a field the manifest no longer matches, before it is actually applied, extending the same render-review discipline covered under packaging and customization to the final apply step itself.

Relationship to Best Practices Scope and Manifest Quality Guidelines

Declarative change guidelines are the operational counterpart to the manifest authoring practices covered under manifest quality guidelines: a well-written, well-linted manifest still fails to deliver reliable, auditable cluster management if it is inconsistently applied alongside undocumented imperative edits, making disciplined, declarative-first change management, backed by GitOps where the maturity of the environment warrants it, the practice that actually realizes the benefit every other manifest-quality guideline was written to support.