Repository-Struktur

Das FluxCD-Repository bildet die zentrale Quelle der Wahrheit für die gesamte Plattform.

Die Struktur trennt klar zwischen:

  • Cluster-Konfiguration

  • Infrastruktur-Komponenten

  • Anwendungen

  • Wiederverwendbaren Modulen

Überblick

fluxcd/
├── clusters/
├── modules/
├── renovate.json
└── validate.sh

Die eigentliche Bereitstellung erfolgt über die Kombination aus:

  1. FluxInstance

  2. Cluster-Konfiguration

  3. Modulen

  4. Kubernetes-Ressourcen

Architekturmodell

repository structure

clusters/

Das Verzeichnis clusters/ beschreibt den gewünschten Zustand eines Clusters.

clusters/
├── home.tamay.cloud/
├── tamay.cloud/
└── test.tamay.cloud/

Jeder Cluster besitzt einen eigenen Einstiegspunkt für FluxCD.

Die eigentliche Synchronisation erfolgt über die jeweilige FluxInstance.

Beispiel:

sync:
  path: clusters/home.tamay.cloud

Dadurch verwaltet jeder Cluster ausschließlich seinen eigenen Teil des Repositories.

Cluster-Struktur

Jeder Cluster besitzt dieselbe Grundstruktur.

cluster/
├── apps/
├── infrastructure/
└── fluxinstance.yaml

fluxinstance.yaml

Die FluxInstance installiert die benötigten Flux-Komponenten und definiert den Synchronisationspfad.

Verantwortlichkeiten:

  • Installation von Flux

  • Definition des GitRepository

  • Definition des Cluster-Pfads

  • Reconciliation-Einstellungen

infrastructure/

Der Infrastruktur-Bereich definiert die Plattform-Komponenten eines Clusters.

Beispiele:

  • Cilium

  • Cert Manager

  • ExternalDNS

  • Velero

  • Piraeus

  • Victoria Metrics

  • Victoria Logs

Die Dateien enthalten dabei keine eigentlichen Ressourcen.

Stattdessen referenzieren sie Module aus modules/infrastructure.

Beispiel:

path: ./modules/infrastructure/cert-manager/overlays/home.tamay.cloud

apps/

Der Anwendungsbereich beschreibt die Workloads eines Clusters.

Beispiele:

  • Immich

  • Vaultwarden

  • Paperless

  • Jellyfin

  • Matrix

  • Home Assistant

Auch hier enthalten die Dateien überwiegend Referenzen auf Module.

Beispiel:

path: ./modules/apps/paperless-ngx/overlays/home.tamay.cloud

Die eigentliche Implementierung liegt niemals im Cluster-Verzeichnis.

modules/

Alle wiederverwendbaren Konfigurationen befinden sich im Verzeichnis modules/.

modules/
├── apps/
└── infrastructure/

modules/apps

Enthält produktive Anwendungen.

Beispiele:

modules/apps/
├── immich/
├── paperless-ngx/
├── vaultwarden/
├── jellyfin/
└── matrix-stack/

modules/infrastructure

Enthält Plattform- und Kubernetes-Komponenten.

Beispiele:

modules/infrastructure/
├── cilium/
├── cert-manager/
├── piraeus/
├── velero/
├── traefik/
└── victoria-metrics/

Modulstruktur

Die meisten Module folgen einem gemeinsamen Aufbau.

module/
├── base/
├── components/
├── overlays/
└── optional:
    ├── crds/
    ├── config/
    ├── schedules/
    └── buckets/

Weitere Details werden in Overlays und Components beschrieben.

Cluster als Composition Layer

Die Dateien unter clusters/ übernehmen die Rolle einer Composition Layer.

Sie definieren:

  • Welche Module installiert werden

  • Welche Cluster-Overlays verwendet werden

  • Welche Abhängigkeiten existieren

  • Welche Konfiguration aktiviert wird

Dadurch bleiben Anwendungen und Infrastruktur vollständig entkoppelt.

Dependency Management

Flux Kustomizations werden zusätzlich zur Modellierung von Abhängigkeiten verwendet.

Beispiele:

cert-manager
    |
    +-- cert-manager-webhook-hetzner

cilium
    |
    +-- cilium-config

garage-operator
    |
    +-- garage-buckets

victoria-metrics-operator
    |
    +-- victoria-metrics-k8s-stack

Die Reihenfolge der Bereitstellung wird dadurch deklarativ beschrieben.

Kustomization-Typen

Standard-Kustomizations

Referenzieren ausschließlich ein Overlay.

path: ./modules/apps/compass/overlays/home.tamay.cloud

Parametrisierte Kustomizations

Verwenden postBuild.substitute.

postBuild:
  substitute:
    host: paperless.home.tamay.cloud

Cluster-spezifische Werte können dadurch zentral definiert werden.

Verschlüsselte Kustomizations

Verwenden SOPS zur Laufzeitentschlüsselung.

decryption:
  provider: sops

Secrets verbleiben verschlüsselt im Repository.

Designprinzipien

Git als Source of Truth

Der vollständige Zustand der Plattform wird aus Git abgeleitet.

Modularität

Komponenten werden unabhängig voneinander entwickelt und betrieben.

Wiederverwendbarkeit

Konfigurationen werden nur einmal definiert.

Multi-Cluster-Fähigkeit

Dieselbe Komponente kann auf mehreren Clustern mit unterschiedlichen Overlays betrieben werden.

Deklarative Abhängigkeiten

Abhängigkeiten zwischen Komponenten werden über dependsOn modelliert.

Vorteile

  • Einheitliche Repository-Struktur

  • Hohe Wiederverwendbarkeit

  • Einfache Erweiterbarkeit

  • Klare Verantwortlichkeiten

  • Multi-Cluster-Unterstützung

  • Vereinfachte Disaster Recovery