6.2 Kubernetes Manifest Structure

Kubernetes Manifest Structure is the concrete textual layout a manifest file follows on disk, typically written in YAML, covering how the top-level object fields are indented and nested, how multiple objects are combined within a single file, and the formatting conventions that make manifests both machine-parseable by the API server and reasonably readable by the humans authoring and reviewing them.

Basic YAML Layout

Top-Level Field Ordering

While YAML itself does not require any particular field order, manifests conventionally place apiVersion and kind first, followed by metadata, then spec, reflecting the logical order in which a reader typically wants to understand an object: what type it is, what it's called, and then what it configures.

Indentation and Nesting

YAML's structure relies entirely on consistent indentation to express nesting, with each further-nested level requiring two additional spaces by convention, meaning a manifest's readability and correctness both hinge on getting this whitespace exactly right, since tabs are not permitted and inconsistent indentation produces a parse error rather than being silently corrected.

Scalars, Mappings, and Sequences

Manifest fields are expressed using YAML's three core constructs: scalars for simple string, number, or boolean values, mappings for key-value structures like metadata, and sequences for ordered lists like a Pod's containers array, each container itself typically a mapping nested within the sequence.

Multi-Document Manifests

The Triple-Dash Separator

A single manifest file can contain multiple distinct objects separated by a line containing only three dashes, ---, allowing related objects, such as a Deployment and its corresponding Service, to be defined together in one file and applied as a single unit rather than requiring separate files for every object.

Application Order Within a File

When a multi-document manifest is applied, the API server processes each document independently in the order it appears in the file, though because Kubernetes controllers reconcile asynchronously, ordering within the file does not guarantee a corresponding ordering of when each object's underlying effects actually take hold in the cluster.

JSON as an Alternative Format

Equivalent Structural Representation

Because YAML is effectively a superset of JSON's data model, any manifest can equally be expressed in JSON, using the same field names and nesting but with JSON's explicit braces, brackets, and quoting instead of YAML's whitespace-driven structure, and the API server accepts either format interchangeably based on the request's content type.

When JSON Is Preferred

JSON manifests are more common when manifests are generated programmatically by tooling rather than hand-authored, since JSON's stricter, less whitespace-sensitive syntax is easier to produce correctly from code, whereas YAML's more permissive, human-friendly syntax is generally preferred for manifests intended to be read and edited directly by people.

Common Structural Conventions

Comments for Human Context

YAML supports comments prefixed with #, which are stripped entirely before the manifest is parsed into an object and have no effect on the resulting API object, existing purely to help human readers understand non-obvious configuration choices within the file itself.

Anchors and Aliases

YAML's native anchor and alias syntax, using & to define a reusable block and * to reference it elsewhere in the same file, can reduce duplication within a manifest, such as repeating a common label set across multiple objects, though this feature is used sparingly since it can reduce a manifest's readability if overused.

File and Directory Organization Conventions

While the API server has no concept of file organization, common conventions group manifests by application or by object kind into directories, and many tools that consume manifests, such as kubectl apply -f, can operate recursively across a directory of manifest files, letting an entire application's configuration be organized and applied as a coherent unit.

Structural Validity Versus Semantic Correctness

Two Distinct Failure Modes

A manifest can be structurally invalid, meaning it fails to parse as valid YAML or JSON at all, or it can parse correctly but be semantically invalid against the resource's schema, such as specifying a field of the wrong type; structural parsing happens entirely client-side or at the very start of request handling, while semantic validation happens against the API server's schema and validation logic as described in the API validation model.