till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-16 18:59:40 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
managarten/docs/decisions/002-cluster-federation-architecture.md
Till-JS d2f00c1d77 📝 docs(landing): add blueprints section for architecture decisions 
Add new blueprints content collection and pages for documenting
architecture decisions, technology strategies and long-term planning.

- Add blueprints collection schema with status tracking (draft/proposal/accepted/implemented/superseded)
- Create index and detail pages for blueprints at /blueprints
- Add first blueprint: Mana Cluster & Federation Architecture
- Add ADR-002 in docs/decisions for internal reference
- Add nav.blueprints translation for all 5 languages
- Add blueprints link to main navigation
2026-02-01 00:07:34 +01:00

5.1 KiB
Raw Blame History

ADR-002: Mana Cluster & Federation Architecture

Status: Accepted Date: 2026-01-31 Author: Till Schneider Category: Architecture, Infrastructure

Context

Die gesamte Mana-Infrastruktur läuft aktuell auf einem einzigen Mac Mini M4. Dies stellt ein erhebliches Risiko dar:

  • Single Point of Failure: Fällt der Mac Mini aus, sind alle Services offline
  • Keine Daten-Redundanz: Hardware-Defekt kann zu Datenverlust führen
  • Keine Skalierungsmöglichkeit: Ressourcen auf ein Gerät beschränkt
  • Kein B2B-Support: Keine Möglichkeit für Kunden, eigene Instanzen zu betreiben

Decision

Wir implementieren ein selbstheilendes, dezentrales Multi-Node-Cluster mit folgenden Technologie-Entscheidungen:

1. Orchestrierung: K3s (Kubernetes)

Gewählt: K3s Abgelehnt: Nomad (HashiCorp), Docker Swarm

Begründung:

  • Apache 2.0 Lizenz (echtes Open Source)
  • CNCF-Governance (neutral, community-driven)
  • Industriestandard mit riesigem Ecosystem
  • Native HA-Unterstützung
  • ARM64 + x86_64 Support

Kritischer Faktor: HashiCorp wechselte im August 2023 zu BSL (Business Source License). Dies ist keine Open-Source-Lizenz und birgt langfristige Risiken für kommerzielle Nutzung.

2. Datenbank: YugabyteDB

Gewählt: YugabyteDB Abgelehnt: CockroachDB, TiDB

Begründung:

  • Apache 2.0 Lizenz (keine Feature-Gating wie bei CockroachDB)
  • 99% PostgreSQL-Kompatibilität (Drizzle ORM funktioniert ohne Änderungen)
  • Geo-Distribution ohne Enterprise-Lizenz
  • Trigger und Stored Procedures unterstützt

Migration: Bestehende PostgreSQL-Datenbanken können via pg_dump/ysqlsh migriert werden.

3. Mesh Networking: Headscale

Gewählt: Headscale (self-hosted Tailscale) Abgelehnt: ZeroTier (BSL), natives WireGuard

Begründung:

  • BSD-Lizenz
  • WireGuard-basiert (modern, schnell, sicher)
  • Zero-Config für neue Nodes
  • Exzellentes NAT Traversal

4. Distributed Computing: Ray

Gewählt: Ray Begründung:

  • Apache 2.0 Lizenz
  • Python-native (passt zu ML-Workloads)
  • Einfache Task-Distribution
  • Integration mit Ollama möglich

5. Federated Learning: Flower

Gewählt: Flower Begründung:

  • Apache 2.0 Lizenz
  • Einfache Integration
  • Privacy-by-Design

Consequences

Positive

  1. High Availability: Automatisches Failover bei Node-Ausfall
  2. Keine Vendor Lock-in: Alle Kernkomponenten echtes Open Source
  3. Skalierbarkeit: Von 2 Nodes bis zu global verteilten Clustern
  4. B2B-Ready: Kunden können isolierte oder föderierte Instanzen betreiben
  5. Heterogene Hardware: Mac, Linux, Windows, Raspberry Pi im selben Cluster

Negative

  1. Komplexität: Kubernetes hat steilere Lernkurve als Docker Compose
  2. Migration: Bestehende docker-compose.yml muss zu K8s Manifests konvertiert werden
  3. Ressourcen: K3s benötigt ~500MB RAM pro Node (mehr als Nomad)

Neutral

  1. LISTEN/NOTIFY: Nicht von YugabyteDB unterstützt, muss auf Redis Pub/Sub migriert werden (falls verwendet)

B2B Deployment Tiers

Tier Name Beschreibung Datenisolation
1 Isolated Komplett eigenes Cluster, keine Verbindung zu Mana 100%
2 Federated Compute Eigene DB, kann anonymisierte Compute-Tasks ausführen 100%
3 Federated Learning Wie Tier 2, plus lokales ML-Training mit Gradienten-Sharing 100%
4 Full Federation Maximum Sharing mit Differential Privacy und ZK-Proofs 100%

Open-Source Stack

Orchestration:     K3s (Apache 2.0)
Mesh Networking:   Headscale (BSD)
Database:          YugabyteDB (Apache 2.0)
Object Storage:    MinIO (AGPL 3.0)
LLM Runtime:       Ollama (MIT)
Distributed AI:    Ray (Apache 2.0)
Federated ML:      Flower (Apache 2.0)
Secrets:           Infisical (MIT)
IaC:               OpenTofu (MPL 2.0)
Monitoring:        VictoriaMetrics (Apache 2.0)

Vermiedene Technologien (BSL/SSPL)

  • HashiCorp: Terraform, Vault, Nomad, Consul
  • CockroachDB
  • MongoDB
  • Elasticsearch
  • ZeroTier

Hardware-Empfehlungen

Mana Central (Minimal HA)

  • 2x Mac Mini M4 (16GB RAM, 512GB SSD)
  • Kosten: ~2.400€

Mana Central (Empfohlen)

  • 2x Mac Mini M4 Pro (24GB RAM)
  • 1x Raspberry Pi 5 (Tiebreaker)
  • Kosten: ~4.000€

Migrations-Roadmap

  1. Phase 1 (Woche 1-2): Zweiter Mac Mini, K3s HA Cluster, Headscale
  2. Phase 2 (Woche 3-4): PostgreSQL → YugabyteDB Migration
  3. Phase 3 (Woche 5-6): Ray Cluster für verteilte AI-Workloads
  4. Phase 4 (Woche 7-8): B2B Deployment Kit (Helm Charts)
  5. Phase 5 (Woche 9-12): Federation Features (Tier 2-4)

References

Full Documentation

Siehe auch: apps/manacore/apps/landing/src/content/blueprints/001-mana-cluster-federation-architecture.md für die ausführliche Version mit Diagrammen.