Kubernetes Manifests and Declarative State

Kubernetes Manifests and Declarative State are the written artifacts, and the underlying model they express, through which operators describe the intended configuration of a cluster rather than the steps required to achieve it. A manifest is a structured document, most commonly YAML or JSON, that specifies one or more Kubernetes objects; declarative state is the broader principle that the cluster's behavior is driven by comparing these specified intentions against what is currently running, rather than by executing an ordered sequence of imperative commands.

Manifests as Source of Truth

Structure of a Manifest

A manifest encodes the same structural fields present in any Kubernetes object: apiVersion, kind, metadata, and spec. When submitted to the cluster, this file becomes the authoritative record of desired state for the object it describes, stored in etcd and continuously compared against the actual state observed by controllers.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: codartium-worker
  labels:
    app: codartium-worker
spec:
  replicas: 4
  selector:
    matchLabels:
      app: codartium-worker
  template:
    metadata:
      labels:
        app: codartium-worker
    spec:
      containers:
        - name: worker
          image: codartium/worker:2.3.1
          env:
            - name: QUEUE_NAME
              value: "content-jobs"

Multi-Document Manifests

A single manifest file may contain multiple objects, separated by ---, allowing related resources, such as a Deployment, its Service, and a ConfigMap it consumes, to be described and applied together as a coherent unit.

Declarative vs. Imperative Management

Imperative Commands

Kubernetes supports imperative commands, such as kubectl run or kubectl scale, which directly instruct the API server to perform a specific action immediately. These are useful for quick, ad hoc operations but leave no durable record of intent beyond the object's resulting state.

Declarative Application

The declarative workflow instead centers on manifest files checked into version control, applied to the cluster with kubectl apply. Rather than issuing a command describing an action, the operator edits the desired end state in a file and lets the system compute and apply the necessary changes.

kubectl apply -f deployment.yaml
kubectl diff -f deployment.yaml
kubectl apply -f deployment.yaml --dry-run=server

Three-Way Merge

kubectl apply performs a three-way merge among the manifest supplied by the user, the last-applied configuration recorded as an annotation on the live object, and the current live state of the object in the cluster. This allows Kubernetes to detect fields that were removed from the manifest and should therefore be cleared, while leaving fields modified by other controllers untouched.

Reconciliation of Declared State

Continuous Convergence

Once a manifest has been applied, the responsibility for realizing it shifts entirely to the cluster's controllers. Each relevant controller continuously observes the object's spec and drives the corresponding real-world state, Pods, network rules, storage attachments, toward matching it, independent of whether the manifest is ever applied again.

Drift and Self-Correction

If the live state of an object diverges from its declared spec, whether due to manual changes, node failures, or external interference, the controller responsible for that object detects the divergence on its next reconciliation pass and issues corrective actions to restore the declared state. This property is what allows Kubernetes clusters to self-heal without operator intervention.

Managing Manifests at Scale

Kustomize

Kustomize allows a base set of manifests to be layered with environment-specific overlays, patches, and parameter substitutions, without templating the underlying YAML directly, producing a fully rendered manifest set for each environment from a shared foundation.

Helm Charts

Helm packages related manifests into versioned, parameterized charts, using a templating language to generate manifests from a set of values, enabling reusable, configurable deployment units that can be installed, upgraded, and rolled back as a single release.

kustomize build overlays/production | kubectl apply -f -
helm upgrade --install codartium ./charts/codartium -f values-production.yaml

GitOps

GitOps extends the declarative model to the operational workflow itself: manifests are stored in a Git repository treated as the single source of truth, and an in-cluster or external controller continuously reconciles the live cluster state against the content of that repository, applying changes automatically whenever the repository is updated and, in some implementations, reverting manual changes that drift from it.

Why Declarative State Matters

Because the desired state of the cluster is expressed as data rather than as a sequence of procedural steps, manifests are inherently reviewable, diffable, and versionable. Two operators applying the same manifest to two different clusters converge on the same result regardless of each cluster's prior state, and the history of a manifest's changes in version control doubles as an audit trail of every intentional modification made to the system over time.