CFN Cloud
2025-10-06

Kubernetes Declarative Configuration Explained: Apply, Drift, and Reconciliation

Understand declarative configuration in Kubernetes, why desired state matters, and how apply, diff, and reconciliation shape safe operations.

Declarative configuration is one of the biggest reasons Kubernetes scales operationally. Instead of remembering a pile of one-off commands, you define the desired state in files and let the cluster reconcile toward it.

What declarative really means

Declarative does not mean “I use YAML.” It means:

  • the desired state is written down
  • the source of truth is reviewable
  • changes are repeatable
  • the cluster can be reconciled back to that known state

This is why kubectl apply is more than a command. It is part of an operating model.

A minimal multi-object example

apiVersion: v1
kind: Namespace
metadata:
  name: demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: nginx:1.25

The normal workflow

kubectl diff -f app.yaml
kubectl apply -f app.yaml
kubectl get -f app.yaml

That order matters. Look at the change, apply the change, then observe the resulting state.

Why this approach is safer

  • changes are reviewable in git
  • reapplying is usually safe and idempotent
  • rollback can be tied to a previous commit or tag
  • drift becomes easier to reason about

This also makes handover easier. Another operator can understand what you intended without replaying your shell history.

Common declarative habits worth building

  • keep namespace explicit
  • keep labels consistent
  • split manifests by concern
  • use kubectl diff before apply
  • define a rollback path in advance

Small habits here reduce a surprising number of production mistakes.

apply vs patch

Use apply when you are managing the whole desired state of a resource.

Use patch when you truly need a narrow targeted edit.

kubectl patch deploy api -p '{"spec":{"replicas":3}}'

In day-to-day production work, it is usually healthier to let the desired state live in files and use patch sparingly.

Drift: why manual edits hurt later

The danger of manual cluster changes is not only that they may be wrong. It is that they create a second source of truth.

Once that happens, operators stop knowing whether the manifest or the live cluster is the real answer.

That is why declarative configuration connects naturally to:

  • kubernetes-quickstart-introduction.md
  • kubernetes-quickstart-architecture.md
  • kubernetes-quickstart-deployment-replicaset.md

Those pages explain why Kubernetes keeps reconciling state and why drift becomes so expensive.

Useful commands beyond apply

Diff before write

kubectl diff -f app.yaml

Dry-run on the server

kubectl apply -f app.yaml --dry-run=server

Apply a directory

kubectl apply -f ./manifests

Apply a Kustomize overlay

kubectl apply -k overlays/prod

Ordering matters more than people think

A clean order often looks like:

  1. namespaces
  2. RBAC and policy
  3. config and secrets
  4. workloads
  5. services and exposure

If the order is messy, the resulting errors often look more mysterious than they really are.

What to review before apply

  • labels and selectors still line up
  • namespace is correct
  • immutable fields are not being changed accidentally
  • resource requests exist where needed
  • secrets are handled separately and safely
  • rollback target is clear

FAQ

Q: Is declarative config only useful if I do full GitOps? A: No. GitOps is one strong form of declarative operations, but even without a controller, reviewed manifests and repeatable apply flows are a major improvement.

Q: Why does drift matter so much? A: Because once manifests and live state disagree, recovery, rollback, and review all become slower and less trustworthy.

Q: When should I worry about server-side apply? A: When multiple tools or teams manage the same resources and field ownership starts causing conflicts.

Next reading

  • Continue with kubernetes-quickstart-deployment-replicaset.md for rollout behavior.
  • Read kubernetes-quickstart-configmap-secret.md to see how declarative config affects application configuration.
  • For safer release strategies, continue with kubernetes-quickstart-canary-release.md.

Wrap-up

Declarative config is valuable because it makes change safer to reason about. The cluster stops being a place where “someone typed something” and becomes a place where intended state can be reviewed, applied, and restored with discipline.

References

View original