6 Kubernetes Manifests and Declarative State

Kubernetes Manifests and Declarative State is the practice of describing the desired configuration of Kubernetes objects as structured text files, typically written in YAML or JSON, which are submitted to the cluster so that its control loops can continuously work to make the running system match what is described, rather than issuing a sequence of imperative commands to reach the same end state.

What a Manifest Is

Structure of a Manifest

A manifest is a document that specifies an object's apiVersion, kind, metadata, and spec. It is a textual representation of the desired state of a single Kubernetes resource, or in some cases multiple resources concatenated together.

Manifests as Source of Truth

Because manifests are plain text, they can be stored in version control, reviewed through the same processes used for application code, and diffed to understand exactly what changed between two states of a deployment.

Declarative vs. Imperative Management

Imperative Commands

Imperative management involves issuing direct commands that describe an action to take, such as creating a specific object with specific flags. This approach is fast for one-off changes but does not leave a durable, reviewable record of the resulting state.

Declarative Application

Declarative management instead involves submitting a manifest describing the desired end state and letting Kubernetes compute the difference between that state and what currently exists, applying only the necessary changes. This approach is idempotent: applying the same manifest repeatedly produces the same result.

Applying Manifests

The Apply Workflow

The standard workflow for declarative management involves writing or updating a manifest file and applying it to the cluster, at which point the API server merges the new specification with the object's existing state, preserving fields managed by other clients or controllers.

Server-Side Apply

Server-side apply moves the merging logic into the API server itself, tracking which fields are owned by which client, which resolves ambiguity when multiple actors manage different parts of the same object over time.

Multi-Document Manifests and Organization

Combining Resources

Multiple related resources, such as a Deployment and its associated Service, are frequently defined together in a single file using document separators, or organized into a directory of files applied together as a unit.

Templating and Parameterization

Because raw manifests are static text, tools built around templating or configuration layering are commonly used to parameterize manifests for different environments, such as adjusting replica counts or resource limits between development and production without duplicating the entire manifest.

Reconciliation of Declared State

Continuous Convergence

Once a manifest has been applied, its declared state is stored in the cluster as the object's spec. Controllers then continuously compare this spec against the object's actual status, taking corrective action whenever they diverge, such as recreating a Pod that crashed unexpectedly.

Drift Detection

Any manual, imperative change made directly to a live object risks being overwritten the next time the corresponding manifest is applied, since the declarative model treats the manifest as authoritative. This makes untracked manual changes, sometimes called configuration drift, a common source of confusion in clusters managed declaratively.

GitOps and Declarative Delivery

Declarative manifests are the foundation of GitOps practices, in which a version-controlled repository of manifests is treated as the single source of truth for cluster state, and automated agents continuously reconcile the live cluster against the contents of that repository rather than relying on manual application.