Kubernetes Kustomize Overlay Management

Kubernetes Kustomize Overlay Management is the practice of authoring, maintaining, and promoting environment-specific overlays without letting them drift into duplicated, unmaintainable copies of each other, covering patch authoring choices, avoiding overlay-of-overlay sprawl, and the diffing workflow used to safely promote a change from one environment's overlay to the next.

Choosing a Patch Strategy Per Change

Strategic Merge for Structural Additions

patches:
  - patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: web
      spec:
        template:
          spec:
            containers:
              - name: web
                env:
                  - name: LOG_LEVEL
                    value: debug
    target:
      kind: Deployment
      name: web

A strategic merge patch, expressed as a partial object, is the more readable choice for adding or overriding named fields (an environment variable, a resource limit) since it merges by field name and, for well-known lists like env, by key rather than list position.

JSON6902 for Precise or List-Order-Sensitive Changes

patches:
  - patch: |-
      - op: remove
        path: /spec/template/spec/containers/0/env/2
    target:
      kind: Deployment
      name: web

A JSON6902 patch is preferable when removing a specific element, reordering a list, or making a change strategic merge cannot express cleanly, at the cost of being more brittle, since it references list elements by position, which breaks silently if the base's list order changes upstream.

Avoiding Overlay Sprawl

The Duplication Trap

A common failure mode is an overlay accumulating a near-complete copy of a resource rather than a minimal patch, effectively re-declaring the base rather than adjusting it; this defeats the purpose of the base-and-overlay separation, since a subsequent base change then requires manually propagating the same change into every overlay's duplicated copy.

# anti-pattern: overlay re-declares nearly the entire deployment
# instead of patching only what actually differs

Keeping Overlays Minimal

patches:
  - patch: |-
      - op: replace
        path: /spec/replicas
        value: 5
    target:
      kind: Deployment
      name: web

An overlay containing only the specific fields that genuinely differ for that environment, replica count, resource limits, an environment-specific hostname, stays small and legible, and any base-level fix or feature addition automatically flows to every overlay without modification, since the overlay never re-declared the affected fields at all.

Avoiding Overlay-of-Overlay Anti-Patterns

Overlays Should Reference Bases, Not Other Overlays

# anti-pattern
resources:
  - ../staging   # an overlay referencing another overlay

Referencing one overlay from another creates an implicit, fragile dependency chain where a staging-specific patch unintentionally becomes part of what production inherits; overlays should each independently reference the shared base directly, with any genuinely shared, non-base-appropriate configuration factored into a Component instead.

# preferred
resources:
  - ../../base
components:
  - ../../components/shared-monitoring

Promotion and Diffing Between Environments

Comparing Rendered Output Across Overlays

diff <(kustomize build overlays/staging) <(kustomize build overlays/production)

Before promoting a change validated in staging to production, diffing the two overlays' fully rendered output directly, rather than comparing the overlay source files themselves, surfaces the actual, complete set of differences a deployment would introduce, including any interaction effects between the base and each overlay's specific patches that source-level comparison alone would miss.

Promoting a Specific Change

git log --oneline overlays/staging/
git cherry-pick <commit-touching-staging-patch>

A disciplined promotion workflow applies a validated overlay change to the next environment as an explicit, reviewed action (a targeted commit or pull request touching only the relevant overlay), rather than an ad hoc manual edit, preserving an auditable record of exactly when and why a given configuration difference was introduced into each environment.

Managing Secrets Differences Across Overlays

Referencing, Not Embedding, Environment-Specific Secrets

secretGenerator:
  - name: db-credentials
    envs:
      - secrets.env

overlays/production/secrets.env

Secret values that differ per environment are kept in per-overlay, typically gitignored, files referenced by the overlay's secretGenerator, ensuring the base and any shared components remain free of environment-specific credentials while still allowing each overlay to supply its own values through the same generator mechanism.

Relationship to Kustomize Base Management and the Packaging Model

Overlay management is the environment-specific half of the base-and-overlay structure introduced by the broader Kustomize package model, and it directly complements base management: a well-managed base provides a stable, minimal foundation, while disciplined overlay management, minimal patches, careful patch-strategy choice, and rigorous rendered-output diffing during promotion, is what keeps the environment-specific half of that same structure from accumulating the duplication and drift that undermines the entire packaging approach's value.