Kustomize: Stop Copy-Pasting YAML — Declarative Config Management That Scales

You've been there: three environments — dev, staging, prod — each with its own copy of the same Deployment YAML. A replica count change means editing three files. A new label? Three files. Someone forgets to sync staging with prod, and now your canary is pointing at the wrong ConfigMap. This is the mess Kustomize was built to clean up. Not by introducing a templating language with loops and conditionals, but by letting you declare what changes per environment as pure YAML patches. No Helm charts, no Go templates, no custom scripts. Just kubectl kustomize . and you get exactly the config you need. After this article, you'll be able to structure a multi-environment Kubernetes repo using Kustomize overlays, apply patches without breaking a sweat, and know exactly when Kustomize is the right tool — and when it's not.

Why Kustomize Exists: The Pain of Copy-Paste YAML

Before Kustomize, teams managed environment-specific configs by duplicating YAML files. Dev, staging, prod — each had its own copy of the same Deployment, Service, ConfigMap. A simple change like adding a label meant editing N files. The result: config drift, human error, and late-night firefights. Helm tried to solve this with templates, but templates introduce complexity: conditionals, loops, and a steep learning curve. Kustomize takes a different approach. It says: keep one base config, and describe only the differences per environment. No templates, no scripting. Just YAML patching. This is declarative configuration management at its purest — you declare what you want, not how to get there.

# io.thecodeforge — DevOps tutorial

# Base kustomization.yaml — shared across all environments
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

# Common labels for all resources
commonLabels:
  app.kubernetes.io/name: payment-service
  app.kubernetes.io/managed-by: kustomize

# Common annotations
commonAnnotations:
  version: "1.0.0"
  environment: base

Kustomize Structure: Base + Overlays

The core pattern is a directory tree with a base/ and overlays/ directory. The base contains the canonical YAML for your application — Deployment, Service, ConfigMap — plus a kustomization.yaml that lists them. Each overlay (dev, staging, prod) has its own kustomization.yaml that references the base and adds patches or customizations. This structure mirrors how you think about environments: dev is like prod but with fewer replicas, different resource limits, maybe a different ConfigMap. The overlay only describes the delta. This keeps your base clean and your environments consistent.

# io.thecodeforge — DevOps tutorial

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# Reference the base
resources:
  - ../../base

# Patch the Deployment to increase replicas and resource limits
patchesStrategicMerge:
  - deployment_patch.yaml

# Change the ConfigMap for prod
configMapGenerator:
  - name: app-config
    behavior: replace
    literals:
      - LOG_LEVEL=warn
      - DB_HOST=prod-db.internal

# Set namespace for all resources
namespace: prod

# Add a name prefix to avoid collisions
namePrefix: prod-

Patches: Strategic Merge vs. JSON Patch

Kustomize supports two patch types. patchesStrategicMerge is the most common: you write a partial YAML that gets merged into the target resource. It works like a three-way merge — you only specify the fields you want to change. patchesJson6902 uses JSON Patch (RFC 6902) operations: op: replace, add, remove. Use strategic merge for simple field overrides (replicas, image tag). Use JSON patch when you need to modify lists (like container args) or remove fields. Strategic merge can't delete a field; JSON patch can. Both are declared in kustomization.yaml.

# io.thecodeforge — DevOps tutorial

# Strategic merge patch: only specify fields to override
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-service
spec:
  replicas: 5
  template:
    spec:
      containers:
        - name: app
          resources:
            requests:
              memory: "1Gi"
              cpu: "500m"
            limits:
              memory: "4Gi"
              cpu: "2"

ConfigMap and Secret Generation

One of Kustomize's killer features is generating ConfigMaps and Secrets from literals or files. Instead of writing a ConfigMap YAML by hand, you declare configMapGenerator with key-value pairs or file references. Kustomize creates the ConfigMap with a content-hash suffix, so any change triggers a rolling update of your Deployments. This solves the classic problem: you update a ConfigMap but Pods don't pick it up because the name hasn't changed. With Kustomize, the name changes automatically when content changes. Same for Secrets. Use behavior: merge to add keys from an overlay, or behavior: replace to completely replace the base ConfigMap.

# io.thecodeforge — DevOps tutorial

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

configMapGenerator:
  - name: app-config
    behavior: merge
    literals:
      - LOG_LEVEL=debug
      - DB_HOST=dev-db.internal

secretGenerator:
  - name: db-credentials
    behavior: replace
    literals:
      - username=dev_user
      - password=dev_pass

# Disable name suffix for dev to keep names short
nameSuffix: ""

Kustomize Components: Reusable Patches

Components are a newer feature (stable in Kustomize v4) that let you define reusable patches that can be included by multiple overlays. Think of them as mixins. For example, a component that adds a sidecar container for logging, or a component that attaches a persistent volume. Components are declared in their own directory with a kustomization.yaml using kind: Component. Overlays include them via components: field. This is great for enforcing cross-cutting concerns like monitoring, logging, or security sidecars across all environments.

# io.thecodeforge — DevOps tutorial

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component

patchesStrategicMerge:
  - sidecar_patch.yaml

Kustomize vs. Helm: When to Use Which

This is the debate that won't die. Here's the truth: Kustomize is better when your configs are mostly static with small per-environment variations. It's pure YAML — no learning curve beyond Kubernetes itself. Helm is better when you need to package and distribute an application with configurable parameters, especially if you're publishing a chart for others to use. Helm's templating allows complex logic (loops, conditionals) that Kustomize can't do. But that complexity is also its weakness: Helm charts are harder to debug, and template errors can produce invalid YAML. My rule: if you control the deployment and just need env-specific tweaks, use Kustomize. If you're building a reusable package for a community, use Helm. Or use both — Helm to package, Kustomize to customize per environment.

# io.thecodeforge — DevOps tutorial

# Comparison table is in the JSON structure below this code block.

Production Patterns: Multi-Tenant and Multi-Cluster

In production, you often need to manage configs for multiple tenants or clusters. Kustomize scales well here. For multi-tenant, create an overlay per tenant with its own namespace, name prefix, and ConfigMap. For multi-cluster, you can have a top-level directory per cluster (us-east, eu-west) with overlays per environment inside. Use kustomize build with --load_restrictor none if you need to reference resources outside the kustomization root (but be careful — this can break reproducibility). Another pattern: use kustomize edit in CI to programmatically modify the kustomization.yaml, then build and apply. This is how you automate canary deployments or feature flags.

# io.thecodeforge — DevOps tutorial

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namespace: tenant-alpha
namePrefix: alpha-

patchesStrategicMerge:
  - deployment_patch.yaml

configMapGenerator:
  - name: app-config
    behavior: merge
    literals:
      - TENANT_ID=alpha
      - FEATURE_NEW_PAYMENT=true

Kustomize in CI/CD: GitOps and ArgoCD

Kustomize is a natural fit for GitOps workflows. Tools like ArgoCD and Flux natively support Kustomize. You point ArgoCD at a Git repo with a kustomization.yaml, and it automatically syncs the rendered config. This means your Git repo is the single source of truth — no manual kubectl apply. In CI, you can run kustomize build to validate the config and even diff it against the live cluster. Use kustomize build . | kubectl diff -f - to see what would change. This catches errors before they hit production. For multi-environment pipelines, use separate branches or directories. I prefer directories: clusters/prod/, clusters/staging/ — each with its own kustomization.yaml that references a shared base.

# io.thecodeforge — DevOps tutorial

#!/bin/bash
set -euo pipefail

# Validate Kustomize config for each environment
for env in dev staging prod; do
  echo "Validating $env..."
  kustomize build overlays/$env > /dev/null
  echo "$env config is valid"
done

# Diff against live cluster (requires kubectl context)
kustomize build overlays/prod | kubectl diff -f - || true

# Apply (in production, use a GitOps tool instead)
# kustomize build overlays/prod | kubectl apply -f -

When Kustomize Breaks: Limitations and Workarounds

Kustomize is not a silver bullet. It struggles with complex transformations that require conditionals or loops. For example, you can't say 'if environment is prod, add this sidecar, else skip it' — you'd need two overlays. Also, Kustomize's patch matching is fragile: it matches on apiVersion, kind, and name. If you rename a resource in the base, all patches break silently. Another pain point: patchesStrategicMerge can't delete a field; you need JSON patch for that. And JSON patch with array indices is brittle. For very complex configs, consider using kustomize with helm via helm template piped into kustomize. Or use a tool like jsonnet or yq for heavy lifting. Know when to walk away.

# io.thecodeforge — DevOps tutorial

# JSON patch to remove a container from a Deployment
patchesJson6902:
  - target:
      version: v1
      kind: Deployment
      name: payment-service
    patch: |-
      - op: remove
        path: /spec/template/spec/containers/1

Debugging Kustomize: Common Errors and Fixes

The most common error: error: json: unknown field "patchesStrategicMerge" — you're using an old Kustomize version. Upgrade to v4+. Another: error: no matches for Id — your patch target doesn't match any resource. Check apiVersion, kind, and name. Use kustomize build to see the rendered resources and their names. If you see error: accumulating resources: accumulation err='...', it's usually a YAML syntax error in one of your files. Run yamllint on all YAML files. For namePrefix issues, use kustomize build and grep for the prefix to verify it's applied. And always, always run kustomize build before applying — never apply a kustomization without reviewing the output.

# io.thecodeforge — DevOps tutorial

# Render and inspect
kustomize build overlays/prod | less

# Check for specific resource
kustomize build overlays/prod | grep -A 20 "kind: Deployment"

# Validate YAML syntax
find overlays -name "*.yaml" -exec yamllint {} +

# Diff against live cluster
kustomize build overlays/prod | kubectl diff -f -