Kustomize — Template-Free Kubernetes Manifest Customization

Introduction

Kustomize changed how teams manage Kubernetes YAML. Instead of templating engines like Helm that inject variables into strings, Kustomize applies structured overlays and patches to base manifests — producing pure YAML at build time. It's now built into kubectl -k and maintained by SIG CLI.

With over 12,000 GitHub stars, Kustomize is used by Argo CD, Flux, Tekton, and most Kubernetes shops that dislike template syntax in YAML. It's often combined with Helm (Helm charts rendered, then customized with Kustomize).

What Kustomize Does

Kustomize reads a kustomization.yaml that declares: (1) base resources to include, (2) patches to apply (strategic merge or JSON patch), (3) common labels/annotations, (4) name prefixes/suffixes, (5) namespaces, (6) configMap/secret generators, (7) image tag overrides. It outputs final YAML with no template syntax.

Architecture Overview

base/
  kustomization.yaml   -> lists resources, common labels/annotations
  deployment.yaml
  service.yaml
        |
overlays/production/
  kustomization.yaml   -> references base + patches
  replica-patch.yaml   -> patch deployment replicas to 10
  configMapGenerator   -> generate configmap from files
        |
   [Kustomize build]
   merges base + patches
   applies prefixes/labels
   generates configmaps
   overrides image tags
        |
   Final YAML -> kubectl apply

Self-Hosting & Configuration

# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
commonLabels:
  app: api

# overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: prod
resources:
  - ../../base
patches:
  - path: replica-patch.yaml
    target: { kind: Deployment, name: api }
images:
  - name: myorg/api
    newTag: v1.2.3
configMapGenerator:
  - name: api-config
    files: [config.yaml]
secretGenerator:
  - name: api-secrets
    envs: [.env.prod]

# overlays/production/replica-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata: { name: api }
spec:
  replicas: 10
  template:
    spec:
      resources:
        requests: { cpu: 500m, memory: 512Mi }
        limits:   { cpu: "2", memory: 2Gi }

Key Features

• Template-free — valid YAML at every layer, no {{ .Values }} madness
• Strategic merge patches — simple declarative overlay syntax
• JSON patches — RFC 6902 for surgical mutations
• ConfigMap/Secret generators — hash-suffixed names trigger rollouts
• Image tag overrides — update image versions across many resources
• Common labels/annotations — apply to all resources at once
• Name prefix/suffix — avoid collisions, distinguish environments
• Built into kubectl — no extra tool needed (kubectl apply -k)

Comparison with Similar Tools

FAQ

Q: Kustomize vs Helm — pick one? A: Not mutually exclusive. Helm for installable packages (charts from third parties). Kustomize for your own apps and environment customization. Many teams use both: helm template ... | kustomize build ....

Q: How do I handle secrets? A: secretGenerator reads env files; or use external solutions (External Secrets Operator, Sealed Secrets) for real secrets. Avoid committing Secret YAML with plaintext values.

Q: Can overlays reference remote bases? A: Yes. resources: [github.com/org/repo/path?ref=v1.2.3]. Works well for sharing base manifests across repos.

Q: Do hash suffixes in configMapGenerator cause problems? A: They are a feature — when a ConfigMap changes, its name changes (hash), triggering a Deployment rollout. Disable with disableNameSuffixHash: true if you manage rollouts another way.

Sources

• GitHub: https://github.com/kubernetes-sigs/kustomize
• Docs: https://kustomize.io
• Governance: Kubernetes SIG CLI
• License: Apache-2.0