Kubernetes Kustomize Base Management

Kubernetes Kustomize Base Management is the discipline of designing a base so it remains genuinely environment-agnostic, deciding what belongs in the base versus what must be deferred to overlays, and handling the versioning, nesting, and multi-base composition patterns that arise once a project's Kustomize structure grows beyond a single base and a couple of overlays.

What Belongs in a Base

Environment-Agnostic Structure Only

# base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: web
          image: myapp:latest

A well-designed base contains the structural shape of every resource, container names, port definitions, volume mount paths, and only the values genuinely shared across every environment that will ever consume it; values known in advance to differ by environment (replica count, resource limits, image tag) are still given a reasonable placeholder in the base but are expected to be overridden, never treated as fixed.

Avoiding Overlay-Specific Assumptions

A common base design mistake is baking in an assumption true of only the most common overlay (assuming a specific ingress hostname pattern, or a specific namespace name) directly into the base rather than leaving it overridable; this surfaces as an overlay needing an awkward, indirect patch to undo something the base should never have asserted in the first place.

Versioning and Pinning Bases

Local Bases via Relative Path

resources:
  - ../../base

A locally vendored base, referenced by relative path within the same repository, is implicitly versioned by whatever commit the overlay's repository is checked out at, meaning base and overlay always move together in lockstep with no separate version identifier to track.

Remote Bases with Explicit Version Pinning

resources:
  - github.com/example-org/platform-manifests//base/web?ref=v2.3.1

Referencing a base from a separate, remote repository at an explicit tag or commit ref decouples the base's release cadence from any single overlay's repository, appropriate when a base is shared across multiple, independently maintained applications or teams, at the cost of introducing a network dependency and an explicit upgrade step whenever the pinned ref needs to advance.

Nested Bases

A Base Built From Other Bases

# platform-base/kustomization.yaml
resources:
  - ../security-base
  - ../logging-base
  - web-deployment.yaml

A base can itself reference other bases as its own resources, composing shared cross-cutting concerns (a common security context patch, a standard logging sidecar) into a single combined platform base that individual application overlays then build upon, rather than every application-level overlay needing to independently reference every cross-cutting base directly.

Multi-Base and Variant Patterns

One Base, Many Environment Overlays

base/
overlays/
  staging/
  production/
  qa/

The most common pattern uses a single shared base with one overlay per deployment environment, appropriate when every environment runs structurally the same application with only configuration-level differences.

Multiple Bases for Structurally Different Variants

bases/
  web-standard/
  web-enterprise/
overlays/
  customer-a/       # references web-standard
  customer-b/        # references web-enterprise

When different deployments require structurally different resources, not merely different configuration values, a multi-tenant SaaS product offering a different feature set per customer tier, a multi-base structure with several distinct bases, each composed by whichever overlays actually need that variant, is more appropriate than forcing every structural difference through the patch mechanism of a single shared base.

Testing a Base in Isolation

Building the Base Directly

kustomize build base/

Running kustomize build against a base directly, with no overlay applied, verifies the base itself renders to valid, complete YAML on its own, catching structural errors early, before they are obscured by overlay-applied patches that might otherwise mask an underlying issue in the base.

Snapshot Testing Rendered Output

kustomize build overlays/production > /tmp/rendered.yaml
diff /tmp/rendered.yaml expected/production.yaml

Comparing freshly rendered output against a checked-in expected snapshot catches unintended changes introduced by a base modification, a valuable regression check specifically because Kustomize's patch-based model means a change to a shared base can have non-obvious downstream effects across every overlay that consumes it.

Relationship to the Kustomize Package Model and Resource Organization

Base management is the practical discipline of applying the base-and-overlay structure defined by the Kustomize package model correctly at scale, and it directly extends the resource organization principles discussed elsewhere in this knowledge area: a well-managed base is the single, environment-agnostic source of truth that every organizational and versioning decision downstream, which overlays exist, how they're composed, how they're tested, ultimately depends on remaining accurate and free of overlay-specific assumptions.