Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท GitOps Principles

Declarative vs Imperative: Why GitOps Needs Desired State

Understand the difference between imperative commands and declarative desired state, how Kubernetes apply merges changes, and why declarative configuration is the foundation of GitOps and Argo CD.

Every Kubernetes change can be made in two styles. The imperative style says what to do: kubectl scale deployment web --replicas=3. The declarative style says what should be: a YAML file that contains replicas: 3, applied whenever you like. GitOps is built entirely on the second style, and understanding why saves you from many surprises with Argo CD.

The commands are read-only here. The runnable code uses stand-ins: a replayable command log and a three-way merge model of kubectl apply. They show the concepts, not real Kubernetes behavior in every corner.

Imperative: commands

Terminal
kubectl create deployment web --image=nginx:1.27
kubectl scale deployment web --replicas=3
kubectl set image deployment/web nginx=nginx:1.27.1
kubectl expose deployment web --port=80

Imperative commands are fast to type and great for exploring. But they have no memory: the history of commands is the only record, and replaying it in a fresh cluster may not give the same result (it depends on what already existed). Two engineers can type different commands and end with different clusters. There is nothing to diff against, so drift cannot even be defined.

Declarative: desired state

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels: { app: web }
  template:
    metadata:
      labels: { app: web }
    spec:
      containers:
        - name: nginx
          image: nginx:1.27.1

Applying the file twice has the same effect as once: it is idempotent. The file is the record. Two clusters given the same file converge on the same result, and a diff between the file and the live object is meaningful.

Two styles

Imperative Do these steps
Declarative Make it look like this

GitOps stores the second kind.

1 / 2

What kubectl apply really does

kubectl apply is declarative, and it uses a three-way merge (client-side apply) between three versions:

  1. the last applied configuration (stored in the kubectl.kubernetes.io/last-applied-configuration annotation),
  2. the new file you are applying,
  3. the live object in the cluster.

A field you removed from the file since last time is deleted from the cluster; a field that is set live but was never in your file (for example by an autoscaler or a controller) is left alone. This is why fields that other controllers manage cause confusing diffs.

Server-side apply (SSA) improves this: the API server tracks which manager owns each field (managedFields) and reports conflicts when two managers fight over one field. Argo CD can use it via the ServerSideApply=true sync option (see Sync Options and Waves).

Stand-in: three-way merge

This model merges simple objects the way client-side apply conceptually does. Change lastApplied, desired or live and watch which fields survive.

JS Stand-in: three-way merge

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The result keeps hpaTarget (never ours), removes debug (we stopped declaring it) and updates the other two fields.

Imperative commands create drift

Compare an imperative history with the declarative state. In this stand-in, three operators each run commands; only the declarative file can tell you what the cluster should be.

JS Stand-in: command replay vs file

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Without the file you could not even say that Carol's change was unexpected.

Declarative layers on top of Kubernetes

Raw YAML is declarative but repetitive. Tools add structure while staying declarative:

  • Kustomize overlays and patches (built into kubectl).
  • Helm charts with values files (templates rendered to YAML).
  • Jsonnet, CUE, cdk8s and plugins that generate YAML.

Argo CD renders any of them into plain manifests and compares those with the cluster. What matters is that the rendered result is a complete desired state (Helm, Kustomize and Config Management is covered in its own chapter).

When imperative is still fine

Declarative does not ban kubectl. Use it freely to read (get, describe, logs) and for emergencies, as long as you then make Git agree. Better still, make an emergency change in Git and let Argo CD apply it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which property means applying the same file twice leaves the cluster unchanged the second time?

    Declarative apply is idempotent: the second run finds nothing to change.
  2. 2. A field is set on a live object by an autoscaler and is not in your file. What does client-side kubectl apply do with it?

    Fields that were never in the last-applied config belong to someone else and are kept.
  3. 3. Why can you not detect drift from a history of imperative commands alone?

    Drift is defined as live differing from desired. Commands do not define a desired state.
  4. 4. What does server-side apply add?

    managedFields records which manager owns each field, so conflicts are explicit.

Summary

  • Imperative commands describe actions; declarative files describe the end state.
  • Declarative config is idempotent, diffable and reviewable, which GitOps needs.
  • kubectl apply merges last-applied, new and live versions; server-side apply tracks field owners.
  • Helm and Kustomize are declarative layers; Argo CD compares their rendered output.
  • Keep imperative commands for reading and emergencies, then fix Git.

Next: The Reconciliation Loop