Kubernetes repository layout — base plus per-environment, Kustomize versus Helm

The Kubernetes manifest repository holds every workload that runs in a cluster. The unit of reuse is the workload, the unit of execution is the environment, and the split is base plus per-environment - common manifests plus overlays that describe how each environment differs.

Two layouts

flowchart TB
    subgraph BASE["Base + overlays"]
        B1["base/ (common)"]
        O1["overlays/dev/"]
        O2["overlays/staging/"]
        O3["overlays/prod/"]
        B1 --> O1
        B1 --> O2
        B1 --> O3
    end

A directory-per-environment layout has one full set of manifests per environment. A base-plus-overlays layout has a base/ directory and a set of overlays/<env>/ directories that describe what each environment changes.

The base-plus-overlays layout is the one the Kustomize and Helm ecosystems assume. The directory-per-environment layout is the one a team invents before it has heard of either tool, and it produces the worst drift: every environment’s copy of the same Deployment drifts independently.

The base-plus-per-environment pattern

The base directory holds the common manifests:

base/
  deployment.yaml
  service.yaml
  configmap.yaml
  kustomization.yaml

Each overlay is a small directory that points at the base and adds the environment-specific changes:

overlays/prod/
  kustomization.yaml
  replica-patch.yaml
  ingress-patch.yaml

The kustomization.yaml in each overlay lists the base as a resources: entry, then lists the patches the overlay applies.

The base holds the workload’s structure (the Deployment exists, the Service exposes port 80) and the overlays hold the variation (how many replicas, what hostname, what config values). A change to the workload is a change to the base; a change to an environment is a change to one overlay.

Kustomize versus Helm

The base-plus-overlays pattern can be implemented with either Kustomize or Helm:

flowchart LR
    subgraph KZ["Kustomize"]
        KB[base] --> KP[patch]
        KP --> KR[rendered YAML]
    end
    subgraph HM["Helm"]
        HC[chart] --> HV[values.yaml]
        HV --> HT[Go template]
        HT --> HR[rendered YAML]
    end

Kustomize is patch-based. The base is plain YAML; the overlays are patches that say “in the Deployment named web, set replicas: 10”. There is no template language; the patch is a structural edit. The review surface is small. Kustomize is bundled with kubectl (kubectl apply -k overlays/prod).

Helm is template-based. The chart is YAML with Go-template directives ({ .Values.replicas }); the values file supplies the environment-specific values. Helm is the natural choice when the chart is being published as a reusable artifact.

Worktrees for parallel overlay edits

The per-environment overlays are a natural fit for git worktree: a single working tree cannot hold two checked-out versions of the same file, but two worktrees can. When a change to the base requires simultaneous edits to the dev, staging, and prod overlays, a worktree per overlay makes the work parallel:

git worktree add ../dev-wt -b fix/dev-overlay
git worktree add ../staging-wt -b fix/staging-overlay
git worktree add ../prod-wt -b fix/prod-overlay

Each worktree has its own branch and its own working tree, so the three overlay changes are three parallel branches.

Production discipline

1. Use the base-plus-overlays layout, not directory-per-environment. The base is the unit of reuse; the overlays are the unit of variation.
2. Choose the templater by team size. A small team with no external chart consumers starts on Kustomize; a large team that publishes charts uses Helm.
3. Never commit rendered output. The render is a build artifact; the source of truth is the base plus the overlays.
4. Pin every image by digest, not by tag. A latest tag resolves to whatever the registry served most recently. The Kustomize patch or values.yaml should pin by @sha256:... for every workload.
5. Use a worktree per parallel overlay edit. Two engineers editing the same overlay in the same working tree collide; two worktrees on two branches do not.

Cross-course references

• Kubernetes for Production Sysadmins - Part X (Manifests) covers the Kustomize and Helm mechanics this layout assumes.
• GitOps for Production Engineers - Part V (ArgoCD/Flux) covers the GitOps controller that consumes the overlays.
• Git Internals for Production Engineers - Part XXX covers the git worktree add mechanics for parallel overlay edits.

Quiz