TL;DR

Für GitOps-Setups mit Kubernetes gibt es kein universelles Repository-Layout. Mono-Repos eignen sich für kleine Teams mit wenigen Clustern, Multi-Repos für große Organisationen mit strikter Zugriffskontrolle. Entscheidend ist eine klare Trennung von Base-Konfigurationen und Overlays pro Environment, konsistente Namenskonventionen und ein definierter Promotion-Flow.

GitOps Repository-Struktur für Kubernetes

Du hast ArgoCD oder Flux installiert, die ersten Apps deployen sich automatisch — und dann kommt die Frage: Wie strukturiere ich das Repository, wenn es 20 Services, 4 Environments und 3 Teams gibt? Die Repo-Struktur ist das Fundament jedes GitOps-Setups.

Mono-Repo vs. Multi-Repo

Die erste Architekturentscheidung betrifft die Anzahl der Repositories.

Mono-Repo: Alles in einem Repository

gitops-platform/
├── apps/
│   ├── frontend/
│   ├── backend-api/
│   └── worker/
├── infrastructure/
│   ├── cert-manager/
│   ├── ingress-nginx/
│   └── monitoring/
└── clusters/
    ├── production/
    ├── staging/
    └── dev/

Vorteile: Atomare Commits über mehrere Services, einfaches Refactoring, eine einzige Source of Truth. Code Reviews sehen das gesamte Bild.

Nachteile: Alle Teams arbeiten im selben Repo. Zugriffsrechte lassen sich nur auf Branch-Ebene steuern, nicht auf Verzeichnisebene (in GitHub). Bei vielen Commits wird die History unübersichtlich.

Multi-Repo: Ein Repository pro Verantwortungsbereich

# Separate Repositories:
gitops-infrastructure/    # Platform-Team
gitops-app-frontend/      # Frontend-Team
gitops-app-backend/       # Backend-Team
gitops-cluster-config/    # Cluster-Admins

Vorteile: Klare Ownership, granulare Zugriffsrechte, unabhängige Release-Zyklen. Teams blockieren sich nicht gegenseitig.

Nachteile: Cross-Service-Änderungen erfordern mehrere PRs. Konsistenz zwischen Repos muss aktiv gepflegt werden.

Empfehlung: Starte mit einem Mono-Repo. Splitte erst auf, wenn Zugriffsrechte oder Repository-Größe zum Problem werden.

Empfohlene Verzeichnisstruktur

Unabhängig von Mono oder Multi — innerhalb eines Repos hat sich folgendes Layout bewährt. Es trennt klar zwischen wiederverwendbaren Basis-Definitionen und umgebungsspezifischen Anpassungen.

gitops-platform/
├── apps/
│   ├── frontend/
│   │   ├── base/
│   │   │   ├── deployment.yaml
│   │   │   ├── service.yaml
│   │   │   ├── hpa.yaml
│   │   │   └── kustomization.yaml
│   │   └── overlays/
│   │       ├── dev/
│   │       │   ├── kustomization.yaml
│   │       │   └── replicas-patch.yaml
│   │       ├── staging/
│   │       │   ├── kustomization.yaml
│   │       │   └── replicas-patch.yaml
│   │       └── production/
│   │           ├── kustomization.yaml
│   │           ├── replicas-patch.yaml
│   │           └── hpa-patch.yaml
│   └── backend-api/
│       ├── base/
│       └── overlays/
├── infrastructure/
│   ├── cert-manager/
│   │   ├── namespace.yaml
│   │   ├── helmrelease.yaml
│   │   └── kustomization.yaml
│   ├── ingress-nginx/
│   └── monitoring/
└── clusters/
    ├── production/
    │   ├── apps.yaml          # ArgoCD ApplicationSet
    │   └── infrastructure.yaml
    ├── staging/
    └── dev/

Die drei Ebenen erklärt

apps/ enthält Anwendungs-Manifeste. Jede App hat ein base/-Verzeichnis mit der vollständigen Konfiguration und overlays/ für umgebungsspezifische Patches.

infrastructure/ enthält Cluster-Komponenten wie Ingress-Controller, Cert-Manager oder Monitoring-Stack. Diese werden typischerweise vom Platform-Team verwaltet.

clusters/ definiert, welche Apps und Infrastruktur auf welchem Cluster laufen. Hier liegen die ArgoCD Applications oder Flux Kustomizations.

Kustomize Base und Overlays

Das Base/Overlay-Pattern mit Kustomize ist der Standard für GitOps-Repos. Die Base enthält die vollständige Konfiguration, Overlays patchen nur die Unterschiede.

# apps/frontend/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
  - hpa.yaml
commonLabels:
  app.kubernetes.io/name: frontend
  app.kubernetes.io/part-of: platform

# apps/frontend/overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patchesStrategicMerge:
  - replicas-patch.yaml
  - hpa-patch.yaml
namespace: production

# apps/frontend/overlays/production/replicas-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: 5

So bleiben Umgebungsunterschiede explizit und nachvollziehbar. Keine versteckten Variablen, keine Template-Magie.

Environment Promotion

Der Promotion-Flow beschreibt, wie Änderungen von Dev nach Production wandern. Zwei Ansätze sind verbreitet.

Branch-basierte Promotion

main    ──── Production
staging ──── Staging
dev     ──── Dev

Änderungen fließen über Pull Requests: dev → staging → main. Einfach zu verstehen, aber Branch-Konflikte und Drift zwischen Branches sind häufig.

Verzeichnis-basierte Promotion (empfohlen)

main Branch:
  overlays/dev/        → Dev-Cluster
  overlays/staging/    → Staging-Cluster
  overlays/production/ → Production-Cluster

Alles lebt auf dem main-Branch. Promotion bedeutet: Image-Tag im Overlay des nächsten Environments aktualisieren. Kein Branch-Merging, kein Drift.

# Image-Tag in staging promoten
cd apps/frontend/overlays/staging
kustomize edit set image frontend=registry.example.com/frontend:v1.4.2

# Nach Review: dasselbe für production
cd apps/frontend/overlays/production
kustomize edit set image frontend=registry.example.com/frontend:v1.4.2

Namenskonventionen

Konsistente Namen reduzieren die kognitive Last erheblich.

Zugriffskontrolle

Wer darf was ändern? Das lässt sich über CODEOWNERS und Branch Protection regeln:

# .github/CODEOWNERS
/infrastructure/    @platform-team
/apps/frontend/     @frontend-team
/apps/backend-api/  @backend-team
/clusters/production/ @platform-team @sre-team

Für Production-Overlays empfiehlt sich ein zusätzliches Approval-Gate: Mindestens zwei Reviewer, davon einer aus dem SRE-Team.

FAQ

Soll ich Helm Charts oder Kustomize verwenden?

Beide funktionieren mit GitOps. Helm eignet sich gut für Third-Party-Software (cert-manager, nginx), Kustomize für eigene Anwendungen. Viele Teams kombinieren beides — Helm für Infrastructure, Kustomize für Apps.

Wo speichere ich Secrets?

Niemals im Klartext im Git-Repository. Nutze Sealed Secrets, SOPS mit Age/GPG oder External Secrets Operator mit einem Vault-Backend. Die verschlüsselten Secrets liegen dann neben den anderen Manifesten.

Wie gehe ich mit Cluster-spezifischen Konfigurationen um?

Lege unter clusters/ pro Cluster einen Ordner an. Dort definierst du, welche Apps und Infrastruktur-Komponenten auf diesem Cluster laufen. Cluster-spezifische Werte (z.B. Ingress-Domain) gehören in ConfigMaps oder Kustomize-Patches im jeweiligen Overlay.

Wie verhindere ich Konfigurationsdrift?

ArgoCD und Flux erkennen Drift automatisch und korrigieren ihn. Aktiviere Auto-Sync mit Self-Heal bei ArgoCD oder setze prune: true bei Flux Kustomizations. Manuelle kubectl-Änderungen werden dann automatisch überschrieben.

Brauche ich ein separates Repo für die CI-Pipeline?

Ja, trenne Application-Source-Code (mit Dockerfile und CI-Pipeline) von der GitOps-Konfiguration. Die CI-Pipeline baut das Image und aktualisiert dann den Image-Tag im GitOps-Repo. So bleibt die Trennung zwischen Build und Deploy sauber.

Nächster Schritt: Starte mit einem Mono-Repo und dem Base/Overlay-Pattern für eine einzelne Anwendung. Sobald das funktioniert, migriere weitere Services und definiere CODEOWNERS für klare Verantwortlichkeiten.