Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: Kustomize-Quellen

Ziel: notes-api hat eine base und zwei Overlays. prod läuft weiter wie bisher, dev kommt als zweite Application dazu, und ein Feld überlässt du bewusst dem Cluster. · Dauer: ca. 50 min · Voraussetzung: Tag 4

Briefing

  • Liegt im Pfad einer Quelle eine kustomization.yaml, rendert Argo CD den Pfad mit Kustomize. Sonst nimmt es die YAML-Dateien so, wie sie sind, ohne Unterordner.
  • Das übliche Muster: eine base mit allem Gemeinsamen, je Umgebung ein Overlay, das nur die Unterschiede enthält.
  • ignoreDifferences nimmt Felder aus dem Vergleich heraus. Mit der Sync-Option RespectIgnoreDifferences=true lässt Argo CD sie auch beim Sync in Ruhe.
 apps/notes/
   base/                 alle Manifeste aus Tag 4 + kustomization.yaml
   overlays/prod/        nur ../../base           ─► Application notes     (ns notes)
   overlays/dev/         Image 0.7.1, 1 Replikat,  ─► Application notes-dev (ns notes-dev)
                         NodePort 30081

Drill 1: Die base

Alle Dateien wandern nach base, dazu eine kustomization.yaml:

cd ~/argo-lab/argocd-fleet
mkdir -p apps/notes/base
git mv apps/notes/*.yaml apps/notes/base/
cat > apps/notes/base/kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - secret.yaml
  - db-secret.yaml
  - db-pvc.yaml
  - db-deployment.yaml
  - db-service.yaml
  - migrate-job.yaml
  - deployment.yaml
  - service.yaml
  - smoke-job.yaml
EOF
mkdir -p apps/notes/overlays/prod
cat > apps/notes/overlays/prod/kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
EOF
kubectl kustomize apps/notes/overlays/prod | grep "^kind:"

Erwartet:

kind: Secret
kind: Secret
kind: Service
kind: Service
kind: PersistentVolumeClaim
kind: Deployment
kind: Deployment
kind: Job
kind: Job

kubectl kustomize rendert lokal, was Argo CD gleich rendert. So prüfst du ein Overlay, bevor du pushst.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Der gefährliche Zwischenstand

Die Application notes zeigt noch auf apps/notes. Dort liegen nach dem Umzug keine Manifeste mehr, nur Unterordner. Du pushst trotzdem, um zu sehen, was passiert:

git add -A
git commit -m "notes: base und overlay prod"
git push
argocd app get notes --refresh
sleep 20
argocd app get notes

Erwartet (gekürzt):

Sync Status:        OutOfSync from main (0317866)
Health Status:      Healthy

CONDITION  MESSAGE                                                                                                     LAST TRANSITION
SyncError  Skipping sync attempt to [031786604b0cc61737d82058acd58219485d7059]: auto-sync will wipe out all resources  2026-11-14 08:51:36 +0000 UTC
…

Für Argo CD ist der Pfad jetzt leer. Mit prune hieße das: alles löschen, samt Volume und Datenbank. Davor schützt eine Sicherung: Ein automatischer Sync, der alle Objekte entfernen würde, findet nicht statt. Abschalten ließe sie sich mit allowEmpty: true unter automated. Lass das.

Die Reparatur ist der neue Pfad in der Application:

mkdir -p ~/argo-lab/tag06
cd ~/argo-lab/tag06
cat > notes-app.yaml <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: notes
  namespace: argocd
spec:
  project: default
  source:
    repoURL: [email protected]:<du>/argocd-fleet.git
    targetRevision: main
    path: apps/notes/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: notes
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true
EOF
kubectl apply -f notes-app.yaml
argocd app wait notes --operation --health --sync

Erwartet (gekürzt):

application.argoproj.io/notes configured
…
Sync Status:        Synced to main (0317866)
Health Status:      Healthy
…
Phase:              Succeeded
curl -s localhost:30080/notes
kubectl -n notes get deploy

Erwartet:

[{"id":"3fef3430-d55d-431b-bad7-c314189bd7a9","text":"Hallo Argo CD"}]
NAME       READY   UP-TO-DATE   AVAILABLE   AGE
notes      2/2     2            2           23m
notes-db   1/1     1            1           11m

Die Notiz ist noch da, die Deployments sind nicht neu (AGE). Das Overlay rendert genau dieselben Objekte wie vorher, also gab es nichts zu tun. Merke dir die Reihenfolge für das nächste Mal: erst die Application auf den neuen Pfad, dann die Dateien verschieben, oder beides in einem Schritt.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Das Overlay dev

cd ~/argo-lab/argocd-fleet
mkdir -p apps/notes/overlays/dev
cat > apps/notes/overlays/dev/kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
images:
  - name: ghcr.io/thomaszachmann/notes-api
    newTag: 0.7.1
patches:
  - path: replicas.yaml
  - path: nodeport.yaml
EOF
cat > apps/notes/overlays/dev/replicas.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: notes
spec:
  replicas: 1
EOF
cat > apps/notes/overlays/dev/nodeport.yaml <<'EOF'
apiVersion: v1
kind: Service
metadata:
  name: notes
spec:
  ports:
    - port: 80
      targetPort: 8080
      nodePort: 30081
EOF
kubectl kustomize apps/notes/overlays/dev | grep -E "image:|replicas:|nodePort:"

Erwartet:

  - nodePort: 30081
  replicas: 1
        image: ghcr.io/thomaszachmann/notes-api:0.7.1
  replicas: 1
        image: postgres:18.6-alpine
        image: ghcr.io/thomaszachmann/notes-api:0.7.1
        image: curlimages/curl:8.17.0
  • images ersetzt das Tag überall, wo das Image vorkommt, auch im Migrations-Job.
  • Die Patches sind kleine Ausschnitte eines Objekts. Kustomize findet das Ziel über Art und Namen und mischt die Felder hinein.
git add -A
git commit -m "notes: overlay dev"
git push

Die zweite Application unterscheidet sich in Name, Pfad und Ziel-Namespace:

cd ~/argo-lab/tag06
cat > notes-dev-app.yaml <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: notes-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: [email protected]:<du>/argocd-fleet.git
    targetRevision: main
    path: apps/notes/overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: notes-dev
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true
EOF
kubectl apply -f notes-dev-app.yaml
argocd app wait notes-dev --operation --health --sync
curl -s localhost:30081/version
kubectl -n notes-dev get pods

Erwartet (gekürzt):

application.argoproj.io/notes-dev created
…
Phase:              Succeeded
0.7.1
NAME                        READY   STATUS      RESTARTS   AGE
notes-598595685f-fcr9w      1/1     Running     0          8s
notes-db-7ff6499dbc-khsft   1/1     Running     0          30s
notes-migrate-vht6g         0/1     Completed   0          13s

dev hat eine eigene Datenbank mit eigenem Volume. Wellen und Hooks gelten auch hier, denn sie stehen in der base.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Ein Feld dem Cluster überlassen

Die Entwickler wollen in dev selbst skalieren, ohne jedes Mal zu committen. Self-Heal würde ihr kubectl scale sofort zurückdrehen. ignoreDifferences nimmt das Feld heraus. Die ganze Datei:

cat > notes-dev-app.yaml <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: notes-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: [email protected]:<du>/argocd-fleet.git
    targetRevision: main
    path: apps/notes/overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: notes-dev
  ignoreDifferences:
    - group: apps
      kind: Deployment
      name: notes
      jsonPointers:
        - /spec/replicas
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true
EOF
kubectl apply -f notes-dev-app.yaml
kubectl -n notes-dev scale deploy notes --replicas=3
sleep 20
kubectl -n notes-dev get deploy notes
argocd app get notes-dev | grep "Sync Status"

Erwartet:

application.argoproj.io/notes-dev configured
deployment.apps/notes scaled
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
notes   3/3     3            3           44s
Sync Status:        Synced to main (11d6de7)

Drei Pods, trotzdem Synced. Jetzt kommt ein Commit, der etwas ganz anderes in dev ändert:

cd ~/argo-lab/argocd-fleet
sed -i "s/nodePort: 30081/nodePort: 30082/" apps/notes/overlays/dev/nodeport.yaml
git commit -am "dev: NodePort 30082"
git push
argocd app get notes-dev --refresh
argocd app wait notes-dev --operation
kubectl -n notes-dev get deploy notes

Erwartet (gekürzt):

NAME    READY   UP-TO-DATE   AVAILABLE   AGE
notes   1/1     1            1           72s

Wieder ein Pod. ignoreDifferences gilt nur für den Vergleich. Läuft ein Sync, wendet Argo CD das ganze Deployment aus Git an, mit replicas: 1. Damit auch der Sync das Feld in Ruhe lässt, braucht es eine Sync-Option:

cd ~/argo-lab/tag06
cat > notes-dev-app.yaml <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: notes-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: [email protected]:<du>/argocd-fleet.git
    targetRevision: main
    path: apps/notes/overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: notes-dev
  ignoreDifferences:
    - group: apps
      kind: Deployment
      name: notes
      jsonPointers:
        - /spec/replicas
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true
      - RespectIgnoreDifferences=true
EOF
kubectl apply -f notes-dev-app.yaml
kubectl -n notes-dev scale deploy notes --replicas=3
cd ~/argo-lab/argocd-fleet
sed -i "s/nodePort: 30082/nodePort: 30081/" apps/notes/overlays/dev/nodeport.yaml
git commit -am "dev: NodePort 30081"
git push
argocd app get notes-dev --refresh
argocd app wait notes-dev --operation
kubectl -n notes-dev get deploy notes
kubectl -n notes-dev get svc notes

Erwartet (gekürzt):

NAME    READY   UP-TO-DATE   AVAILABLE   AGE
notes   3/3     3            3           118s
NAME    TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
notes   NodePort   10.43.133.159   <none>        80:30081/TCP   2m4s

Der NodePort kam aus Git, die drei Replikate blieben.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

argocd app list -o name

Erwartet: argocd/notes, argocd/notes-dev und argocd/podinfo.

curl -s localhost:30081/version

Erwartet: 0.7.1.

argocd app get notes | grep Path

Erwartet: Path: apps/notes/overlays/prod.

Challenge

Alle Objekte in dev sollen das Label umgebung: dev tragen. Ändere nur das Overlay.

Hinweis: Kustomize kennt commonLabels und labels. Eines davon fasst auch die Selektoren der Deployments an, und die sind unveränderlich.

Lösung

cd ~/argo-lab/argocd-fleet
cat > apps/notes/overlays/dev/kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
labels:
  - pairs:
      umgebung: dev
images:
  - name: ghcr.io/thomaszachmann/notes-api
    newTag: 0.7.1
patches:
  - path: replicas.yaml
  - path: nodeport.yaml
EOF
git commit -am "dev: Label umgebung"
git push
argocd app get notes-dev --refresh
argocd app wait notes-dev --operation --health
kubectl -n notes-dev get deploy,svc -l umgebung=dev

Erwartet (gekürzt):

NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/notes      3/3     3            3           2m39s
deployment.apps/notes-db   1/1     1            1           3m1s

NAME               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
service/notes      NodePort    10.43.133.159   <none>        80:30081/TCP   2m44s
service/notes-db   ClusterIP   10.43.53.180    <none>        5432/TCP       3m1s

labels setzt das Label nur in den Metadaten und Pod-Vorlagen, nicht in den Selektoren.

Ausprobiert: Mit commonLabels: {umgebung: dev} warnt schon kubectl kustomize: 'commonLabels' is deprecated. Argo CD scheitert dann bei jedem Versuch mit Deployment.apps "notes-db" is invalid: spec.selector: Invalid value: … field is immutable und probiert es mit wachsendem Abstand immer wieder. Erst der Commit mit labels beendet die Schleife.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Overlays pro Umgebung sind das häufigste Muster für Fleet-Repos. Tag 8 erzeugt die Applications dazu automatisch.
  • Typische Felder für ignoreDifferences: replicas unter einem Autoscaler, caBundle in Webhooks, Felder, die ein Operator nachträgt.
  • Systemweite Ausnahmen gehören in argocd-cm unter resource.customizations.ignoreDifferences.<gruppe>_<art>.