Kubernetes Raw Manifest Packaging

Kubernetes Raw Manifest Packaging is the practice of distributing and applying Kubernetes resources as plain, unmodified YAML or JSON files with no templating engine, overlay tool, or package manager involved, relying solely on file organization, kubectl apply semantics, and manual or scripted substitution for whatever minimal environment variation is needed.

The Simplest Form of Distribution

A Directory of Manifests

manifests/
  namespace.yaml
  deployment.yaml
  service.yaml
  configmap.yaml

kubectl apply -f manifests/

Applying an entire directory in one command is the most direct form of Kubernetes packaging: no rendering step exists, what is checked into version control is byte-for-byte identical to what is applied to the cluster, making it trivially auditable but also making any environment-specific difference require either separate directories per environment or manual editing before each apply.

Multi-Document YAML Files

apiVersion: v1
kind: Namespace
metadata:
  name: app
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: app

The --- document separator lets multiple resources live in a single file, applied together in file order, a convention frequently used for small, tightly coupled sets of resources that are always deployed as a unit and rarely need independent versioning.

kubectl apply Semantics as the Underlying Mechanism

Three-Way Merge Patch

kubectl apply -f deployment.yaml

kubectl apply computes a three-way merge between the previously applied configuration (recorded in the kubectl.kubernetes.io/last-applied-configuration annotation), the current live state of the object, and the new manifest being applied, allowing fields not managed by the applied manifest but changed by another actor (an autoscaler adjusting replicas, for instance) to be preserved rather than overwritten.

Server-Side Apply as a Modern Alternative

kubectl apply --server-side -f deployment.yaml --field-manager=ci-pipeline

Server-side apply moves the merge computation to the API server itself and tracks field ownership explicitly per named manager, avoiding the sometimes-surprising annotation-based bookkeeping of client-side apply and providing clearer conflict detection when multiple actors manage the same object.

Environment Variation Without Templating

Directory-Per-Environment Duplication

manifests/
  staging/
    deployment.yaml
  production/
    deployment.yaml

The most straightforward, if maintenance-heavy, way to handle environment differences without any tooling is full duplication of manifests per environment, accepting the risk that the two copies drift out of sync over time as changes are applied to one directory and forgotten in the other.

Shell-Based Substitution

sed "s/REPLICA_COUNT/3/" deployment.yaml.tmpl | kubectl apply -f -

A minimal, ad hoc alternative to a full templating engine uses shell text substitution directly against placeholder tokens, sufficient for a small number of simple substitutions but fragile for anything beyond trivial value replacement, and easy to get subtly wrong with YAML's whitespace sensitivity.

Ordering and Dependency Management

Manual Sequencing Requirements

kubectl apply -f namespace.yaml
kubectl apply -f crd.yaml
kubectl apply -f deployment.yaml

Without a tool computing dependency order automatically, raw manifest packaging requires the person or script applying manifests to know and respect ordering constraints manually, a Namespace before objects within it, a CRD before instances of it, since kubectl apply -f over an unordered directory processes files in an unspecified order that may not respect these dependencies.

kubectl apply -f Directory Recursion

kubectl apply -f manifests/ --recursive

The --recursive flag applies every manifest found in nested subdirectories, useful for organizing manifests by component while still applying them in a single command, though it does not itself introduce any ordering guarantee beyond whatever order the filesystem returns entries in.

When Raw Manifests Remain the Right Choice

Simplicity as a Deliberate Trade-off

For a small number of environments with genuinely minimal variation, or for infrastructure manifests applied rarely and reviewed carefully by hand each time, raw manifest packaging avoids the learning curve, tooling dependency, and templating-language debugging overhead that Helm or Kustomize introduce, making it a reasonable and sometimes preferable choice rather than a primitive stage every project must graduate out of.

Relationship to the Packaging Model and Areas

Raw manifest packaging represents the degenerate case of the packaging model described elsewhere in this knowledge area, where the template and the rendered output are identical because no parameterization exists at all; it is the baseline every other packaging area, Helm's templating, Kustomize's overlays, is built to improve upon once a project's environment variation and scale outgrow what plain, unparameterized YAML can reasonably express.