kustomize-Befehle: Base, Overlays und Patches anwenden

kustomize erzeugt Kubernetes-Manifeste aus Basismaterial und umgebungsspezifischen Änderungen. Es ist in kubectl integriert (kubectl apply -k), lässt sich aber auch eigenständig verwenden. Diese Referenz zeigt Aufbau, Patches und Prüfkommandos.

Grundbefehle

kustomize build overlays/prod          # Manifeste rendern
kubectl kustomize overlays/prod        # dasselbe über kubectl
kubectl apply -k overlays/prod         # rendern und anwenden
kubectl diff -k overlays/prod          # Unterschied zum Cluster zeigen
kustomize create --autodetect          # Gerüst aus vorhandenen YAML-Dateien

kubectl diff -k ist der wichtigste Prüfschritt überhaupt: Es zeigt vor dem Anwenden, welche Felder sich im Cluster ändern würden.

Aufbau einer kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
  - ingress.yaml

namespace: app-prod
namePrefix: prod-

labels:
  - pairs:
      env: prod
    includeSelectors: true

images:
  - name: registry.example.org/team/app
    newTag: 1.4.0

replicas:
  - name: app
    count: 4

patches:
  - path: res-patch.yaml
    target:
      kind: Deployment
      name: app

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

secretGenerator:
  - name: app-secret
    envs:
      - secrets.env

Patches

Patches sind das Kernwerkzeug. Zwei Formen sind üblich:

# Als Patch-Datei (strategischer Merge-Patch)
# res-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  template:
    spec:
      containers:
        - name: app
          resources:
            limits:
              memory: 1Gi

# Als Inline-JSON-Patch (fein genaue Pfade)
patches:
  - target:
      kind: Deployment
      name: app
    patch: |-
      - op: replace
        path: /spec/template/spec/containers/0/image
        value: registry.example.org/team/app:1.4.0

Zwei Regeln vermeiden die meisten Fehler: Im strategischen Merge-Patch müssen die Objekte einen Namen tragen, damit Kustomize sie zuordnen kann. Und ein Patch, dessen Ziel nicht gefunden wird, schlägt still fehl – bei unerwartetem Ergebnis zuerst prüfen, ob der target korrekt ist.

Prüfen und Erkunden

# Fertiges Ergebnis ansehen
kustomize build overlays/prod | less
kustomize build overlays/prod | kubectl apply --dry-run=server -f -

# Alle Dateien und Bilder auflisten
kustomize build overlays/prod | grep -E '^\s*image:'
kustomize build overlays/prod | grep -c '^kind:'

# Struktur auflisten
kustomize cfg tree overlays/prod

Praxis-Tipps

  • Basis frei von Umgebungsdetails halten: Keine festen Replikate, keine Hostnamen, keine Namespaces in der Base. Diese Werte gehören ausschließlich in Overlays.
  • ConfigMap-Generator nutzen: Der automatische Namens-Hash bewirkt, dass Pods bei geänderter Konfiguration neu starten. Ohne ihn läuft der alte Prozess mit alter Konfiguration weiter.
  • namePrefix bei mehrfach genutzter Base: Verhindert, dass zwei Instanzen derselben Base im Cluster kollidieren.
  • Nicht mit Helm mischen, ohne es zu wissen: Ein Helm-Chart kann als helmCharts-Eintrag eingebunden werden; dann braucht der Build die Option --enable-helm.
  • Overlay-Struktur dokumentieren: In größeren Repositories ist die Frage „welche Overlays gibt es?“ der häufigste Einstiegspunkt – eine kurze README spart viel Zeit.

Verwandte Grundlagen: Kustomize, kubectl-Befehle, helm-Befehle, Kubernetes.