Repository-Struktur

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

Die Struktur orientiert sich an modernen Platform-Engineering-Prinzipien und trennt klar zwischen:

  • Plattform-Capabilities

  • Datenservices

  • Betriebsfunktionen

  • Anwendungen

  • Cluster-Komposition

Das Design folgt dem Platform-Engineering-Gedanken der CNCF, Plattformen als Sammlung wiederverwendbarer Capabilities zu betrachten, die von Anwendungen konsumiert werden.

Überblick

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

Architekturmodell

repository structure

Die Plattform besteht aus vier Ebenen:

Platform
    │
    ▼
Data
    │
    ▼
Operations
    │
    ▼
Applications

Diese Reihenfolge spiegelt die technische Abhängigkeit wider.

clusters/

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

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

Jeder Cluster besitzt eine eigene FluxInstance sowie eine dedizierte Komposition der Plattform.

Cluster-Struktur

Jeder Cluster besitzt dieselbe Grundstruktur.

cluster/
├── 00-platform/
├── 01-data/
├── 02-operations/
├── 03-apps/
├── cluster-vars.yaml
└── fluxinstance.yaml

Die numerische Struktur macht die logische Schichtenfolge sichtbar.

00-platform

Enthält die grundlegenden Plattformfähigkeiten.

Beispiele:

  • Cilium

  • Cert Manager

  • External Secrets

  • Traefik

  • Envoy Gateway

  • NetBird

  • Piraeus

  • Flux

01-data

Enthält wiederverwendbare Datenservices.

Beispiele:

  • CloudNativePG

  • Dragonfly

  • Garage

  • MariaDB

Diese Komponenten werden von Anwendungen konsumiert.

02-operations

Enthält Betriebs- und Plattformfunktionen.

Beispiele:

  • Velero

  • Talos Backup

  • Woodpecker

  • Victoria Metrics

  • Victoria Logs

  • OpenTelemetry

03-apps

Enthält die produktiven Workloads eines Clusters.

Beispiele:

  • Immich

  • Matrix

  • Vaultwarden

  • Paperless NGX

  • Jellyfin

  • Vikunja

fluxinstance.yaml

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

Beispiel:

sync:
  path: clusters/home.tamay.cloud

Verantwortlichkeiten:

  • Installation von Flux

  • Definition des GitRepository

  • Definition des Cluster-Pfads

  • Konfiguration der Reconciliation

modules/

Alle wiederverwendbaren Plattform- und Anwendungsmodule befinden sich unter modules/.

modules/
├── apps/
├── data/
├── operations/
└── platform/

Module enthalten die eigentliche Implementierung einer Capability oder Anwendung.

Cluster referenzieren ausschließlich Module.

modules/platform

Die Plattform-Schicht stellt Kubernetes- und Infrastruktur-Capabilities bereit.

platform/
├── gitops/
├── networking/
├── runtime/
├── security/
└── storage/

GitOps

Plattformfunktionen für deklarativen Betrieb.

Beispiele:

  • Flux Operator

  • Image Automation

  • Renovate Operator

Networking

Netzwerk- und Connectivity-Funktionen.

Beispiele:

  • Cilium

  • Gateway API

  • Envoy Gateway

  • Traefik

  • External DNS

  • NetBird

  • Pangolin

Runtime

Clusterlaufzeit und Node-Funktionen.

Beispiele:

  • Metrics Server

  • Node Feature Discovery

  • Intel Device Plugins

  • Spegel

Security

Sicherheits- und Zertifikatsfunktionen.

Beispiele:

  • Cert Manager

  • Cert Manager Webhook Hetzner

  • External Secrets

Storage

Persistenz und Kubernetes-Speicher.

Beispiele:

  • Piraeus Operator

  • LINSTOR Cluster

  • External Snapshotter

  • Local Path Provisioner

modules/data

Data Services stellen konsumierbare Datendienste bereit.

data/
├── cloudnative-pg/
├── dragonfly-operator/
├── garage-operator/
├── mariadb-operator/
└── tika/

Diese Komponenten stellen Datenbanken, Caches oder Object Storage für Anwendungen bereit.

Beispiele:

  • PostgreSQL

  • MariaDB

  • Redis-kompatibler Cache

  • S3-kompatibler Object Storage

modules/operations

Operations enthält Komponenten für den Betrieb der Plattform.

operations/
├── backup/
├── ci-cd/
└── observability/

Backup

Datensicherung und Wiederherstellung.

Beispiele:

  • Velero

  • Talos Backup

CI/CD

Build- und Delivery-Plattform.

Beispiele:

  • Woodpecker

Observability

Messbarkeit und Überwachung der Plattform.

Beispiele:

  • Victoria Metrics

  • Victoria Logs

  • OpenTelemetry

  • Goldilocks

  • Grafana

modules/apps

Anwendungen liefern direkten Benutzerwert.

Beispiele:

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

Ein App-Modul beinhaltet die vollständige Implementierung einer Anwendung inklusive aller benötigten Overlays und optionalen Components.

Modulstruktur

Die meisten Module folgen einer einheitlichen Struktur.

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

base

Definiert die minimale funktionsfähige Implementierung.

components

Optionale Erweiterungen.

Beispiele:

  • PostgreSQL

  • Dragonfly

  • Gateway API

  • Ingress

  • Backups

overlays

Cluster-spezifische Anpassungen.

Beispiele:

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

Cluster als Composition Layer

Die Cluster-Verzeichnisse übernehmen die Rolle einer Composition Layer.

Sie definieren:

  • Welche Module installiert werden

  • Welche Overlays aktiviert werden

  • Welche Plattform-Capabilities bereitgestellt werden

  • Welche Anwendungen auf einem Cluster betrieben werden

Module bleiben dadurch vollständig wiederverwendbar.

Dependency Management

Abhängigkeiten werden über Flux Kustomizations und dependsOn modelliert.

Typische Beispiele:

Platform
    │
    ▼
Data
    │
    ▼
Operations
    │
    ▼
Apps

Innerhalb der einzelnen Domänen existieren weitere deklarative Abhängigkeiten.

Designprinzipien

Git als Source of Truth

Der vollständige Plattformzustand wird aus Git rekonstruiert.

Plattform als Capability Layer

Plattformfunktionen werden als konsumierbare Capabilities bereitgestellt.

Modularität

Komponenten werden unabhängig entwickelt und betrieben.

Wiederverwendbarkeit

Konfigurationen werden nur einmal definiert.

Multi-Cluster-Fähigkeit

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

Deklarative Abhängigkeiten

Abhängigkeiten werden explizit modelliert.

Vorteile

  • Klare Trennung von Plattform, Datenservices, Betrieb und Anwendungen

  • Hohe Wiederverwendbarkeit

  • Multi-Cluster-Unterstützung

  • GitOps-First-Betrieb

  • Plattformorientierte Struktur

  • Einfache Erweiterbarkeit

  • Vereinfachte Disaster Recovery