Kustomize: Environment-Specific Config

The Problem with Helm for Your Own Apps

Helm is powerful, but charts require learning Go template syntax and add indirection. For your own application where you just need to change an image tag or replica count between dev and production, this complexity often isn't worth it.

Most teams with first-party apps just need: "take these base manifests, and apply a few differences per environment."

What is Kustomize?

Kustomize is a configuration management tool that is built directly into kubectl since Kubernetes 1.14. No installation needed — run kubectl apply -k instead of kubectl apply -f.

Kustomize does not use templating. Instead it uses:

• Bases: canonical, shared manifests
• Overlays: environment-specific patches applied on top
• kustomization.yaml: a manifest that declares what resources to include and what transformations to apply

Kustomize Compilation Pipeline

+--------------------+
| Base Manifests     |--+
| (Golden YAMLs)     |  |
+--------------------+  |
                        |      +------------------------+
+--------------------+  +----> |    Kustomize Engine    |
| Overlay Config     |  |      |                        |
| (kustomization)    |--+      |  1. Parse YAML into    |      +--------------------+
+--------------------+  |      |     Abstract Syntax    |      |  Flat Rendered     |
                        |      |     Trees (AST)        | ---> |  Kubernetes YAML   |
+--------------------+  +----> |  2. Generate CM hashes |      |  (No templates)    |
| Patches            |--+      |  3. Apply patches      |      +---------+----------+
| (RFC 6902 / SMP)   |         |  4. Resolve references |                |
+--------------------+         +------------------------+                | (kubectl apply -k)
                                                                         v
                                                              +--------------------+
                                                              | Kubernetes API     |
                                                              +--------------------+

Core Concepts

Base

The base contains your "golden" manifests — a Deployment, Service, etc. that work for all environments. No environment-specific values here.

base/
  deployment.yaml
  service.yaml
  kustomization.yaml   � lists: resources: [deployment.yaml, service.yaml]

Overlay

An overlay references the base and applies patches. Each environment gets its own overlay directory:

overlays/
  production/
    kustomization.yaml   � references ../../base, adds patches
  staging/
    kustomization.yaml

kustomization.yaml

The kustomization file declares:

• Which resources or bases to include
• namePrefix/nameSuffix to distinguish environments
• images to override image tags without editing YAML
• commonLabels to add labels to all resources
• patches for surgical changes

Low-Level AST Manipulation and Hashing

Instead of performing string replacement, Kustomize parses input YAML manifests into Abstract Syntax Trees (ASTs) using Golang libraries like sigs.k8s.io/yaml and kyaml. This allows Kustomize to be structurally aware of the resources.

1. ConfigMap/Secret Generator Suffixes: When using configMapGenerator or secretGenerator, Kustomize computes a SHA-256 hash of the payload content and appends it as a suffix to the resource name (e.g. my-config-f7b2h38d).
2. Reference Resolution: To avoid breaking references, the Kustomize engine tracks these name changes. It updates any referencing fields—such as volumes.configMap.name, envFrom.configMapRef.name, or env.valueFrom.configMapKeyRef.name—within matching Workloads (Deployments, StatefulSets) using built-in field specs that match resource kinds.
3. Content-Driven Rolling Updates: By appending content hashes to Secret and ConfigMap names, Kustomize ensures that any configuration change automatically changes the resource name in the Pod spec, forcing the kubelet to perform a clean rolling update of the workload.

Patch Types

Strategic Merge Patch (SMP): Utilizes the Kubernetes OpenAPI schema to merge structures. For instance, rather than replacing lists completely, it merges container lists by matching the name field, allowing you to add environment variables or change resource requirements without duplicating the entire container block.

JSON Patch: Implements the RFC 6902 standard. It performs precise, step-by-step structural modifications (e.g. add, replace, remove) targeting specific JSONPaths:

# example JSON patch
- op: replace
  path: /spec/replicas
  value: 3

Kustomize vs Helm