Deployment Manifest¶
Declarative manifest — instantiates Portable Dependency Envelope
A declarative spec that states the desired placement, resources, permissions, and policy for a unit, so any substrate can reconcile itself to that target instead of following step-by-step install instructions.
A packaged unit still has to be told where to sit, how much it may consume, what it is allowed to do, and which policies apply — and Deployment Manifest is the mechanism that states all of that as a desired end-state rather than a script. Its defining move is that it is declarative: it does not say "do this, then that," it says "this is what correct looks like," and leaves a reconciler on the substrate to make reality match. That inversion is what makes the same unit portable across environments — the manifest carries the placement contract with the unit, so a substrate reads the target and converges to it, instead of a human hand-running install steps that drift between machines. It is the wiring diagram of the envelope, distinct from the engine that runs it and the recipe that built it.
Example¶
A bank runs its payments API in three Kubernetes environments — dev, staging, and a tightly-regulated production cluster — and wants the difference between them to be legible, not folkloric. One manifest describes the deployment: the image reference, a nodeSelector pinning production pods to the PCI-compliance node pool, resource requests and limits (≈250 mCPU request, 1 CPU limit), a non-root securityContext dropping every Linux capability the service doesn't need, and labels marking the workload's data-classification tier so the cluster's admission policy can enforce it.
Promoting from staging to production is now a small, reviewable diff — the node pool and the resource limits change, nothing else — rather than a runbook someone follows by hand at 2 a.m. When an auditor asks "prove production runs non-root in the compliance zone," the answer is the manifest in version control, and the reconciler's guarantee that the live cluster is kept matching it.
How it works¶
What sets a manifest apart from the runtime and the build recipe is that it never acts — it declares, and something else converges to it:
- It separates what from how. The manifest states the target (placement, resources, permissions, policy); the substrate's reconciler owns the steps to reach it.
- It is reconciled, not executed. A controller continuously compares actual state to the declared target and drives the two together, so drift is corrected rather than accumulated.
- It is parameterized per environment. The same base spec is overlaid with per-environment values (node pool, limits, replica count), keeping one source of truth across dev / stage / prod.
- It is diffable. Because it is a declared state in version control, a change is a reviewable diff and a rollback is a revert.
Tuning parameters¶
- Placement strictness — how tightly
nodeSelector/ affinity rules pin the unit. Tight rules guarantee it lands where policy requires but erode the portability the envelope bought; loose rules keep it portable but cede placement control. - Requests vs. limits gap — the headroom between guaranteed resources and the hard cap. A wide gap tolerates bursts but risks noisy-neighbour contention; a narrow one is predictable but throttles spikes.
- Permission tightness — how much the
securityContextdrops. Least privilege shrinks blast radius; every capability retained for convenience widens it. - Rollout strategy — rolling versus recreate, surge and unavailability budgets, trading update speed against continuity.
- Overlay depth — how much is shared base versus per-environment override. More sharing means less drift but less flexibility per environment.
When it helps, and when it misleads¶
Its strength is that it turns deployment into a reproducible, diffable, reviewable artifact: the desired state lives in version control, changes are diffs, and a reconciler keeps the running system honest to it. That is the foundation the whole GitOps discipline of declarative, version-controlled desired state is built on.[n1]
Its failure mode is that a manifest describes intent, not reality — the gap between them is drift, and a manifest that is edited out of band while someone hand-patches the live cluster becomes a confident lie about a system that no longer matches it. The classic misuse is exactly that: mutating live state directly "to fix it fast," so the source of truth and the running system silently diverge. Over-tight placement rules are the subtler trap — pin a unit hard enough to one substrate and you have quietly destroyed the portability the envelope was supposed to provide. And a manifest says nothing about whether the image it points at is correct. The discipline that keeps it honest is a single declarative source of truth with a reconciler enforcing it and no manual drift — if the cluster is wrong, you fix the manifest, not the cluster.
How it implements the components¶
Deployment Manifest realizes the placement-and-governance side of the envelope — the components that say how the unit should sit on a substrate, not how it is built or run:
substrate_compatibility_profile— it declares what the target must provide (architecture, node labels, cluster capabilities) as selectors and affinity rules.resource_and_permission_profile— it declares the CPU / memory requests and limits and the security context and capabilities the unit is granted.policy_and_compliance_label— it carries the labels and annotations that admission control and compliance policy key on.
It does not execute the unit — that is the Container Runtime — nor build or package it (Dockerfile or Build Recipe and the OCI Container Image), nor pin its dependency closure (Lockfile or Dependency Snapshot); the manifest only points at an already-built image and states how it should be placed.
Related¶
- Instantiates: Portable Dependency Envelope — the manifest is the placement-and-resource contract that travels with the unit.
- Consumes: the image reference (OCI Container Image) it deploys; it is read by the Container Runtime that enforces it.
- Sibling mechanisms: Container Runtime · Dockerfile or Build Recipe · Lockfile or Dependency Snapshot · OCI Container Image · Software Bill of Materials
Editorial Notes¶
Form Classification¶
Form family: Representation, Specification & Plan
Rationale: Deployment Manifest operates as a non-executable information artifact that externalizes static or prospective structure because it a declarative spec that states the desired placement, resources, permissions, and policy for a unit, so any substrate can reconcile itself to that target instead of following step-by-step install instructions.
Independent corroboration: The frozen evidence defines Deployment Manifest as 'A declarative spec that states the desired placement, resources, permissions, and policy for a unit, so any substrate can reconcile itself to that target instead of following step-by-step install instructions', so its operative form is Representation, Specification & Plan.
Nearest alternative: Rule, Policy & Commitment — The manifest only declares the desired configuration and never executes, even though its policy fields constrain reconciliation.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Specialized
Rationale: Cloud-native software engineering cohered declarative deployment manifests that state desired placement, resources, permissions, and policy for continuous reconciliation.
Review outcome: Independent reviewer agreement; high confidence.
Notes¶
A manifest is declarative desired-state, which means it is only as strong as the reconciler enforcing it: with a controller continuously converging the substrate to it, it is a guarantee; without one, it is documentation that the running system is free to contradict. The value is in the coupling of declaration to enforcement, not in the file alone.
[n1] Declarative desired-state configuration — where controllers continuously reconcile the actual state of a system toward a declared target — is the operating model of Kubernetes and the basis of GitOps. It is what lets a manifest be a source of truth rather than a one-time install script. ↩