Kubernetes Kustomize Package Model

Kubernetes Kustomize Package Model is the specific structure Kustomize imposes on the general template-values-render packaging pattern: a declarative kustomization.yaml file listing resources, patches, and generators, composed through a base-and-overlay hierarchy, that the kustomize engine resolves into fully rendered manifests without ever introducing a templating language into the underlying YAML.

The kustomization.yaml as the Package Manifest

Declaring What a Kustomization Contains

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
namePrefix: prod-
namespace: production
commonLabels:
  environment: production

Every Kustomize package is rooted in a kustomization.yaml file, which is not itself a Kubernetes resource but a build instruction telling the kustomize engine which raw manifests to include and which transformations, prefixes, labels, namespace assignment, to apply uniformly across all of them.

Bases and Overlays

The Base as Shared Foundation

base/
  kustomization.yaml
  deployment.yaml
  service.yaml

A base is simply a kustomization containing the common, environment-agnostic definition of an application, intended to be referenced, never modified directly, by one or more overlays representing specific environments.

Overlays Referencing and Patching a Base

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - path: increase-replicas.yaml
    target:
      kind: Deployment
      name: web

# increase-replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 5

An overlay's resources field pulls in the base, and its patches field applies a strategic merge or JSON patch against specific fields, producing a fully rendered, environment-specific manifest set without duplicating the base's content anywhere.

Patch Strategies

Strategic Merge Patches

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

A JSON6902 patch (as shown with the op/path/value structure) targets a specific field by exact path, useful for precise, surgical changes, while a strategic merge patch expressed as a partial YAML object merges by matching field names, more readable for larger structural changes but requiring the patch author to understand Kubernetes's field-specific merge semantics (list merging by key versus by index, for instance).

Patches Targeting Multiple Resources

patches:
  - patch: |-
      - op: add
        path: /metadata/labels/tier
        value: backend
    target:
      kind: Deployment
      labelSelector: "app.kubernetes.io/component in (web,worker)"

A single patch can target every resource matching a label selector or annotation selector rather than a single named resource, letting one overlay change apply uniformly across an entire category of resources without repeating the same patch block per resource.

Generators

ConfigMap and Secret Generation

configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=debug
    files:
      - app.properties

Generators produce ConfigMap or Secret objects from literal values or files at build time, appending a content hash to the generated object's name; any Deployment referencing that name via Kustomize's automatic reference substitution is thereby forced to roll whenever the generated content actually changes, since its manifest now points at a differently named object.

Components for Cross-Cutting Reuse

Composable, Optional Feature Fragments

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
resources:
  - istio-sidecar-patch.yaml

components:
  - ../../components/istio-sidecar

A Component packages an optional, independently reusable fragment of configuration (enabling a service mesh sidecar, adding a common security patch) that any overlay can opt into by reference, solving the problem of cross-cutting configuration that does not fit neatly into a single base-and-overlay hierarchy.

Building the Final Output

The kustomize build Step

kustomize build overlays/production
kubectl apply -k overlays/production

Running kustomize build (or kubectl apply -k, which invokes the same engine internally) resolves the entire base-overlay-component graph into fully rendered, plain Kubernetes YAML, which is the concrete output every other Kustomize concept, resources, patches, generators, components, ultimately exists to produce.

Relationship to the Packaging Model and Resource Organization

The Kustomize package model is a specific, patch-based instantiation of the broader packaging model's template-values-render structure, where the base plays the role of the template, the overlay's patches play the role of values, and kustomize build performs the rendering; its base-and-overlay hierarchy is also a direct application of the resource organization principles discussed elsewhere, providing a built-in mechanism for the shared-versus-environment-specific separation that any package eventually needs as it grows beyond a single environment.