--- title: 'Was ist Kustomize? Kubernetes-Configs sauber verwalten' description: 'Kustomize verwaltet Kubernetes-Konfigurationen über Bases und Overlays – ohne Templates. So bleiben YAML-Dateien lesbar, valide und flexibel anpassbar.' image: src: /images/blog/what-is-kustomize.jpg authors: - name: Thomas Ens to: /about/thomasens avatar: src: /images/blog/authors/thomas.jpeg date: 2026-04-10 tags: published: true --- Wer mehrere Umgebungen in [Kubernetes](/de/blog/what-is-kubernetes) betreibt, kennt das Problem: Dieselben Manifeste leicht angepasst für Dev, Staging und Prod und irgendwann stimmt irgendetwas nicht mehr. [Kustomize](https://kustomize.io/) 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](/de/blog/simplify-kubernetes-configuration) 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: ```yaml 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: ```yaml 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: ```yaml 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. ```yaml 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: ```bash 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: ```bash # 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](/de/blog/what-is-a-helm-chart) 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: ```yaml 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.