Kustomize Bases and Overlays

Overview

Kustomize is a declarative configuration composition tool for Kubernetes. Instead of copying almost-identical YAML files for dev, staging, and production, teams define a reusable base and then layer environment-specific overlays on top. The final manifest is rendered by walking the resource graph, applying name transformations, labels, image substitutions, generated ConfigMaps or Secrets, and targeted patches.

The important mechanism is patch-based composition rather than template rendering. A base does not know which overlays will consume it, and overlays can apply small, focused changes without modifying the original resource files. That makes Kustomize useful for GitOps workflows where reviewability matters: the source repository stores plain Kubernetes objects plus explicit transformations, and the rendered output can be diffed before it is applied.

Kustomize is built into kubectl through kubectl apply -k, kubectl diff -k, and kubectl kustomize. This makes it a low-friction infrastructure-as-code layer for Kubernetes teams that want environment reuse without introducing a separate templating language.

Core Concepts

Resources and Transformations

A kustomization.yaml declares input resources and transformations. Resources are Kubernetes YAML files or other kustomization directories. Transformations include cross-cutting fields such as name prefixes, labels, annotations, namespace assignment, image replacement, generated ConfigMaps, and patches.

Bases and Overlays

A base is a directory containing reusable resources and its own kustomization.yaml. An overlay is another kustomization directory that references one or more bases and applies customizations. The base has no dependency on the overlay, so multiple overlays can reuse the same base safely.

Patches as Small Intentional Diffs

Patches are used when a transformation needs to change specific fields. Kustomize supports strategic merge patches for Kubernetes-aware object merging and JSON 6902 patches for exact path-based operations. The docs recommend small patches that do one thing, such as increasing replicas separately from setting resource limits.

Key Concept: Rendered Manifests Stay Kubernetes-Native

Kustomize does not invent a new runtime object model. It renders ordinary Kubernetes manifests, so the output can be inspected, diffed, committed, policy-checked, or applied by any Kubernetes-compatible deployment workflow.

How It Works

Build a Reusable Base

The base lists stable resources. It should contain defaults that are valid in most environments: container names, ports, selectors, service definitions, and conservative replica counts.

# base/kustomization.yaml
resources:
  - deployment.yaml
  - service.yaml

# base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: example/api:latest

Add Environment Overlays

Each overlay imports the base and applies environment-specific transformations. The source Kubernetes objects remain shared; only the differences live in the overlay.

# overlays/prod/kustomization.yaml
resources:
  - ../../base

namePrefix: prod-
namespace: production

images:
  - name: example/api
    newTag: "2026.04.22"

patches:
  - path: replicas.yaml
    target:
      group: apps
      version: v1
      kind: Deployment
      name: api

Render, Diff, and Apply

The same source directory can be rendered for inspection, diffed against cluster state, or applied. This supports review-before-apply deployment pipelines.

kubectl kustomize overlays/prod/
kubectl diff -k overlays/prod/
kubectl apply -k overlays/prod/

Practical Applications

Multi-Environment Kubernetes Deployments

Use one base for the application and overlays for dev, staging, and production. Dev might lower replicas and use a debug image tag; production might add stricter resource limits, a production namespace, and a release image digest.

GitOps Review Workflows

Because the input and output are YAML, Kustomize works well with pull-request review and policy engines. A CI job can run kubectl kustomize, validate the rendered manifests, and show kubectl diff -k output before merge.

Platform Defaults with Team Overrides

A platform team can publish bases that encode organizational defaults, while application teams own overlays that customize image tags, replica counts, namespaces, and environment-specific config.

Implementation Patterns

Directory Layout by Ownership

A common pattern separates reusable base resources from overlays. Keep generated output out of the source directory unless your deployment system explicitly requires committed render artifacts.

app/
  base/
    deployment.yaml
    service.yaml
    kustomization.yaml
  overlays/
    dev/
      kustomization.yaml
      replicas.yaml
    prod/
      kustomization.yaml
      replicas.yaml
      resources.yaml

Prefer Built-In Transformers Before Patches

Use images to change image names or tags, namePrefix and nameSuffix for naming, and labels for common metadata. Reach for patches when the change is structurally specific and cannot be expressed with a built-in transformer.

Use JSON 6902 for Precise Field Edits

Strategic merge patches are convenient for common Kubernetes types, but they are not universal. JSON 6902 patches make the target and field path explicit, which is useful for CRDs or fields where merge semantics are ambiguous.

Performance Considerations

Render cost: Kustomize rendering is usually small compared with applying resources to a cluster, but very large bases with many overlays can slow CI if every environment is rendered repeatedly.
Diff cost: kubectl diff -k talks to the cluster and can be slower than local rendering. Run local schema validation first, then cluster diff for deploy candidates.
Patch count: Many tiny patches improve reviewability but can make render behavior hard to trace. Group related field changes only when they share one operational intent.
Generator hashes: ConfigMap and Secret generators may add content hashes to names. This helps rollout changes but can surprise downstream references if replacement rules are incomplete.
Remote bases: Referencing bases from remote repositories couples rendering to network availability and remote version pinning. Prefer immutable refs when remote bases are necessary.

Common Pitfalls

Duplicating bases per environment: Copying a base into every overlay destroys the reuse model and causes configuration drift. Keep shared resources in one base and express differences as overlays.
Using overlays as templates: Kustomize is not a general-purpose templating system. If every field is parameterized, the configuration becomes harder to review than plain YAML.
Patch target ambiguity: A patch should target a specific group, version, kind, name, namespace, label selector, or annotation selector. Loose targets can accidentally modify more resources than intended.
Selector-breaking labels: Adding labels to selectors changes workload identity and can trigger unexpected replacement behavior. Be explicit about whether common labels should include selectors.
Skipping rendered-output review: Always inspect or diff the rendered manifests. Kustomize transformations compose, and the final Kubernetes YAML is the artifact that actually matters.