6.18 Kubernetes Manifest Multi Document File

Kubernetes Manifest Multi Document File is a single YAML file containing more than one distinct API object, each separated by a line consisting solely of three dashes, allowing a set of related objects, such as a Deployment, its Service, and a ConfigMap it depends on, to be authored, reviewed, and applied together as one cohesive unit rather than scattered across many individual files.

The Document Separator Mechanism

YAML's Native Multi-Document Support

The triple-dash separator, ---, is not a Kubernetes-specific convention but a native feature of the YAML specification itself, marking the boundary between independent documents within a single stream; Kubernetes tooling simply parses each resulting document as a separate object rather than treating the file as one large structure.

Leading and Trailing Separators

A file can optionally begin with a leading --- before its first document and can include trailing whitespace or comments after the final document without issue, though the meaningful separators are specifically the ones appearing between two actual object documents within the file.

Practical Benefits of Combining Objects

Cohesive Review and Change History

Grouping tightly related objects into a single file means a single pull request diff shows the complete picture of a related change, such as a Deployment's image update alongside a corresponding ConfigMap change, rather than requiring a reviewer to piece together the full picture across several separate file diffs.

Simplified Application Commands

A multi-document file can be applied with a single kubectl apply -f invocation covering every object it contains, reducing the operational complexity of deploying a related set of objects compared to needing to individually reference each separate file.

Natural Grouping by Application Component

Many teams organize their manifests so that each file represents one coherent application component, bundling a Deployment, Service, and any component-specific ConfigMap or Secret together, making the file structure of a repository mirror the logical structure of the system it describes.

Application Behavior Across Documents

Independent Processing of Each Document

Despite being combined into one file, each document within a multi-document manifest is processed as a fully independent object by the API server; there is no special coupling or transactional guarantee linking the fate of one document to another purely because they share a file.

No Atomicity Across the File

If applying a multi-document file encounters an error partway through, such as one document failing validation, the objects from documents already successfully processed before the failure remain applied, meaning a multi-document file provides no all-or-nothing guarantee, and partial application is a real possibility that manifest authors and pipeline designers need to account for.

Ordering Considerations

Documents are generally processed in the order they appear in the file, which matters when one object's successful creation depends on another already existing, such as a Namespace needing to exist before objects declared within it, though most standard tooling processes documents sequentially in file order without additional coordination beyond that.

Multi-Document Files Versus Directory-Based Organization

When to Combine Versus Separate

Combining objects into one file suits tightly coupled, always-deployed-together resources, while splitting objects into separate files better suits resources with independent lifecycles or that are reused across multiple different combinations, such as a shared ConfigMap referenced by several different Deployments each defined in their own file.

Recursive Directory Application as an Alternative

Rather than relying solely on multi-document files, many workflows instead organize many single-object files within a directory structure and apply the entire directory recursively, achieving a similar practical grouping benefit at the file-system level rather than within a single file's content.

Multi-Document Files as Templating Output

A Common Target Format for Generators

Templating and overlay tools such as Helm and Kustomize typically render their final output as a single multi-document stream, concatenating every generated object together separated by ---, making the multi-document format the de facto standard interchange format between manifest-generating tools and the API server, regardless of how the source configuration was originally organized.