Was ist Kustomize? Kubernetes-Configs sauber verwalten

Wer mehrere Umgebungen in Kubernetes betreibt, kennt das Problem: Dieselben Manifeste leicht angepasst für Dev, Staging und Prod und irgendwann stimmt irgendetwas nicht mehr. Kustomize löst genau dieses Problem, ohne auf eine Template-Sprache zurückzugreifen. Das Ergebnis sind YAML-Dateien, die immer valides Kubernetes-YAML bleiben und sich trotzdem flexibel anpassen lassen.

Das Problem mit Copy-Paste-Konfigurationen

Ein typisches Kubernetes-Projekt beginnt harmlos: ein Deployment, ein Service, vielleicht ein Ingress. Dann kommt die zweite Umgebung, und man kopiert die Dateien und ändert ein paar Werte. Dann die dritte. Irgendwann hat man sechs Verzeichnisse mit 90 % identischem Inhalt und keine vernünftige Möglichkeit mehr, eine Änderung konsistent durchzuziehen.

Das ist kein seltenes Edge-Case-Szenario, das ist der Normalzustand in wachsenden Teams, die schnell deployments aufgebaut haben ohne bewusste Struktur. Kustomize setzt genau dort an: Statt Dateien zu duplizieren, beschreibt man Unterschiede relativ zu einer Basis.

Was ist Kustomize und wie funktioniert es

Kustomize ist ein Open-Source-Tool zur deklarativen Verwaltung von Kubernetes-Konfigurationen. Es wurde von Google entwickelt und ist seit Kubernetes 1.14 direkt in kubectl integriert. Das Kernprinzip: Es gibt eine Base, also eine Grundkonfiguration, und Overlays, die diese Basis für unterschiedliche Kontexte anpassen.

Wichtig: Kustomize verwendet keine Template-Sprache. Alle Dateien bleiben zu jedem Zeitpunkt gültiges Kubernetes-YAML – kein .Values.image , keine Logik, keine Schleifen. Das macht die Kubernetes-Konfiguration deutlich lesbarer und reduziert die kognitive Last beim Reviewen von Änderungen.

Die kustomization.yaml – das Herzstück

Jede Kustomize-Struktur dreht sich um die Datei kustomization.yaml. Sie beschreibt, welche Ressourcen zusammengeführt werden sollen und welche Modifikationen anzuwenden sind:

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

resources:
  - deployment.yaml
  - service.yaml

namePrefix: dev-

commonLabels:
  environment: development

Diese Datei ist der einzige Ort, an dem Kustomize "weiß", was mit den Ressourcen passieren soll. Alle anderen Dateien bleiben unverändert.

Bases und Overlays in der Praxis

Die typische Verzeichnisstruktur sieht so aus:

k8s/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── prod/
        ├── kustomization.yaml
        └── replica-patch.yaml

Die kustomization.yaml im prod-Overlay referenziert die Base und fügt einen Patch hinzu:

resources:
  - ../../base

patches:
  - path: replica-patch.yaml

Der Patch selbst ist wieder valides YAML und überschreibt nur die Felder, die sich in Produktion unterscheiden, zum Beispiel die Anzahl der Replicas.

Patches und Transformationen

Kustomize unterstützt zwei Arten von Patches, die sich für unterschiedliche Anwendungsfälle eignen.

Strategic Merge Patch funktioniert so, als würde man ein YAML-Fragment über das Original legen. Man gibt nur die Felder an, die sich ändern sollen, und der Rest bleibt erhalten:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3

JSON Patch ist präziser und erlaubt gezielte Operationen wie add, remove oder replace auf einzelne Felder über JSONPath-Syntax. Für die meisten Anwendungsfälle reicht der Strategic Merge Patch, JSON Patch ist dann sinnvoll, wenn man z. B. ein einzelnes Element aus einer Liste entfernen oder an einer bestimmten Position einfügen muss.

Zusätzlich bietet Kustomize Transformationen wie namePrefix, nameSuffix und commonLabels, die global auf alle Ressourcen angewendet werden. Das ist besonders nützlich, um Ressourcen in verschiedenen Overlays eindeutig zu benennen und Verwechslungen zu vermeiden.

ConfigMap- und Secret-Generatoren

Ein häufiges Problem in Kubernetes-Projekten: ConfigMaps und Secrets werden manuell aktualisiert, aber Pods bekommen das nicht mit und laufen weiter mit den alten Werten, bis zum nächsten Restart. Kustomize löst das mit Generatoren.

configMapGenerator:
  - name: app-config
    files:
      - config/app.properties
    options:
      disableNameSuffixHash: false

Kustomize berechnet einen Hash aus dem Inhalt der referenzierten Dateien und hängt ihn an den Namen der ConfigMap. Ändert sich der Inhalt, ändert sich der Name – und Kubernetes rollt den Deployment automatisch neu aus. Wer das Verhalten nicht möchte, kann es mit disableNameSuffixHash: true abschalten.

Für Secrets funktioniert das Prinzip identisch, mit dem Unterschied, dass die Werte base64-kodiert werden. Sensible Daten sollten dabei natürlich nicht direkt in der kustomization.yaml liegen, sondern über externe Secret-Management-Lösungen eingespielt werden. Kustomize ist dafür kein Ersatz.

kubectl kustomize – direkt integriert

Seit Kubernetes 1.14 ist Kustomize ohne separate Installation verwendbar. Statt kustomize build und manuelles Pipen in kubectl apply reicht ein einzelner Befehl:

kubectl apply -k overlays/prod/

Das -k Flag weist kubectl an, das Verzeichnis als Kustomize-Struktur zu interpretieren. Wer die generierten Manifeste vor dem Apply inspizieren möchte, kann sie mit kubectl kustomize overlays/prod/ auf stdout ausgeben lassen.

Die direkt in kubectl integrierte Version hinkt allerdings leicht hinter dem separaten kustomize-Binary hinterher. Wer aktuelle Features oder Bug-Fixes benötigt, installiert Kustomize am besten separat:

# Mit brew (macOS/Linux)
brew install kustomize

# Oder direkt via Go
go install sigs.k8s.io/kustomize/kustomize/v5@latest

Kustomize vs. Helm. Wann welches Tool?

Das ist eine der Fragen, die in Kubernetes-Teams regelmäßig aufkommt und die keine universelle Antwort hat.

Helm ist ein vollständiger Paketmanager mit Template-Engine. Es erlaubt Logik in Konfigurationen, verwaltet Release-History und unterstützt Rollbacks. Helm ist die richtige Wahl, wenn man Pakete verteilt, also fertige, wiederverwendbare Applikations-Charts, die von anderen Teams oder Organisationen installiert werden sollen.

Kustomize ist kein Paketmanager, sondern ein Konfigurationsüberlagerer. Es ist die bessere Wahl, wenn man eigene Deployments in verschiedene Umgebungen bringen möchte, ohne Template-Logik zu brauchen. Die Konfiguration bleibt einfacher, die Dateien bleiben lesbar, und es gibt keine zusätzliche Abstraktionsebene.

In der Praxis schließen sich beide nicht aus. Ein verbreitetes Muster ist, Helm für das initiale Rendering von Charts zu verwenden (helm template) und die generierten Manifeste dann via Kustomize zu überlagern. Das kombiniert die Paketierungsfähigkeiten von Helm mit der Einfachheit von Kustomize für umgebungsspezifische Anpassungen.

Kustomize in GitOps-Workflows

Kustomize und GitOps passen gut zusammen, weil beide auf dem Prinzip "Git als einzige Quelle der Wahrheit" aufbauen. Tools wie ArgoCD und Flux haben native Kustomize-Unterstützung eingebaut.

Bei ArgoCD reicht es, in der Application-Ressource das Overlay-Verzeichnis anzugeben:

source:
  repoURL: https://github.com/example/k8s-config
  targetRevision: HEAD
  path: overlays/prod

ArgoCD erkennt automatisch, dass es sich um eine Kustomize-Struktur handelt, und rendert die Manifeste entsprechend. Änderungen an der Base oder einem Overlay triggern einen Sync-Vorgang – der Cluster hält sich immer an den Stand im Repository.

Flux funktioniert ähnlich über die Kustomization-CRD, die auf ein Verzeichnis im Repository zeigt und regelmäßig oder event-gesteuert synchronisiert wird.

Das Ergebnis ist ein nachvollziehbarer, auditierter Deploymentprozess: Jede Konfigurationsänderung ist ein Git-Commit mit Autor, Zeitstempel und Diff.

Fazit

Kustomize ist eine pragmatische Antwort auf ein sehr reales Kubernetes-Problem: gleiche Ressourcen, aber unterschiedliche Umgebungen. Statt Copy-Paste-YAML oder komplexer Template-Logik bekommst du mit Base + Overlays eine saubere, gut reviewbare Struktur und bleibst dabei vollständig in validem Kubernetes-YAML.

Wenn du eigene Workloads betreibst und vor allem Varianten managen willst (Dev/Staging/Prod, Kunden-/Tenant-spezifische Anpassungen, Feature-Toggles über Patches), ist Kustomize oft die einfachste und robusteste Wahl. Helm bleibt stark, wenn du paketieren, verteilen und Releases managen willst, in vielen Teams funktionieren beide Tools sogar kombiniert.

Unterm Strich: Kustomize reduziert Reibung, minimiert Fehlerquellen und macht GitOps-Workflows deutlich angenehmer, gerade dann, wenn deine Infrastruktur wächst und du trotzdem Kontrolle behalten willst.