# Kustomize — Template-Free Kubernetes Manifest Customization

> Kustomize lets you customize Kubernetes manifests through overlays and patches without templates. Maintained by SIG CLI and built into kubectl, it is the declarative way to manage environment-specific YAML across dev/staging/prod.

## Install

Save in your project root:

# Kustomize — Template-Free Kubernetes Customization

## Quick Use
```bash
# Built into kubectl (1.14+)
kubectl apply -k ./overlays/production

# Or standalone
kustomize build ./overlays/production | kubectl apply -f -
```

```
# Directory layout
base/
  kustomization.yaml
  deployment.yaml
  service.yaml
overlays/
  dev/kustomization.yaml
  staging/kustomization.yaml
  production/kustomization.yaml
```

## 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
```yaml
# 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
| Feature | Kustomize | Helm | Jsonnet / Tanka | cdk8s | ytt (Carvel) |
|---|---|---|---|---|---|
| Template-free | Yes | No (Go tpl) | Partly | No (code) | No (YAML overlays) |
| Learning curve | Low | Moderate | High | Moderate | Moderate |
| Environment overlays | Native | Via values files | Native | Native | Native |
| Package sharing | Via remote refs | Helm charts (mature) | Libraries | npm packages | Bundles |
| Generators | Yes | No | Manual | Manual | Yes |
| Best For | Simple customization | Installable packages | Programmers | TypeScript/Python teams | Overlay-heavy |

## 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

---
Source: https://tokrepo.com/en/workflows/643d48eb-37c8-11f1-9bc6-00163e2b0d79
Author: AI Open Source