cluster/docs/architecture.md

Systeemarchitectuur & GitOps

Dit document beschrijft de algehele architectuur van het homelab-cluster, het netwerkverkeer en de geautomatiseerde deployment-pipeline.

---

🏗️ GitOps & Deployment Pipeline

Alle services volgen een strict GitOps-model aangedreven door Gitea Actions en ArgoCD:

flowchart TD
    subgraph Development
        Dev[Developer push naar main]
    end

    subgraph CI Pipeline ["Gitea Actions (git.bnhmeijer.nl)"]
        Trigger[Push / PR Trigger] --> Filter[dorny/paths-filter: Detecteer gewijzigde componenten]
        Filter -->|Component gewijzigd| Build[Bouw Docker Image]
        Build --> PushReg[Push image naar Container Registry git.bnhmeijer.nl]
        PushReg --> SyncGitOps[Update manifests met nieuwe tag in k8s-infra-vmserver]
    end

    subgraph GitOps Repo ["k8s-infra-vmserver (Git)"]
        GitOpsPath["workloads/cluster-infra/<service>/"]
    end

    subgraph Kubernetes Cluster
        Argo[ArgoCD ApplicationSet]
        K8sWorkloads[K8s Deployments / Services / HTTPRoutes]
    end

    Dev --> Trigger
    SyncGitOps -->|Commit & Push| GitOpsPath
    GitOpsPath -->|Gemonitord via Git poll / webhook| Argo
    Argo -->|Reconcile & Deploy| K8sWorkloads

ArgoCD ApplicationSet

In cluster-infra/argocd/applicationset.yaml is een ApplicationSet gedefinieerd:

• Repo URL: https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git
• Directories: workloads/cluster-infra/*
• Doel Namespace: cluster-infra
• Sync Policy: Geautomatiseerd (prune: true, selfHeal: true, CreateNamespace=true).

Zodra een service manifests toevoegt onder workloads/cluster-infra/<service>, maakt ArgoCD automatisch een nieuwe applicatie aan (cluster-infra-<service>) en houdt deze synchroon.

---

🌐 Netwerk, Ingress & Routing (Apache + Envoy Gateway)

Het externe netwerkverkeer wordt op twee lagen afgehandeld:

1. Edge Reverse Proxy & TLS/OIDC (Apache op 10.2.0.4):

   • Apache draait rechtstreeks op de host vmserver (10.2.0.4) en leest zijn configuraties uit /sites/vhosts/ (versiebeheerd in cluster-infra/vhosts/).
   • Verzorgt SSL-terminatie met Let's Encrypt certificaten (/etc/letsencrypt/live/thuus.bnhmeijer.nl/).
   • Verzorgt OpenID Connect (OIDC) authenticatie via Keycloak (https://login.bnhmeijer.nl).
   • Routeert lokaal naar bare-metal hostdiensten (Gitea op port 3000, Jellyfin, Icecast, *Arr stack, Nextcloud) en stuurt clusterverkeer door naar Envoy Gateway NodePort 127.0.0.1:32608.
   • Zie voor alle details: docs/apache-reverse-proxy.md.

2. In-Cluster Gateway API (Envoy Gateway):

   • Ontvangt verkeer vanaf Apache op NodePort 32608.
   • HTTPRoute resources koppelen domeinen en paden aan specifieke Kubernetes pods/services:
     • thuus.bnhmeijer.nl/argocd \rightarrow argocd/argocd-server:80
     • herms.bnhmeijer.nl & herms.lan \rightarrow herms/frontend:3000
     • login.bnhmeijer.nl \rightarrow keycloak/keycloak:8080
     • influx.bnhmeijer.nl & influx-ui.bnhmeijer.nl \rightarrow InfluxDB services in cluster-infra
     • infra.bnhmeijer.nl \rightarrow cluster-infra/infra-web:3000
     • gravitymon.lan \rightarrow herms/gravitymon-2-nats:8002

---

💾 Data & Berichtuitwisseling (Middleware Layer)

Binnen het cluster worden verschillende persistente opslag- en messaging-engines gebruikt:

1. Mosquitto (MQTT):
   • Broker voor IoT-hardware, sensoren en ESP32 firmware communicatie.
   • Hoofdgebruiker: HERMS firmware/hardware en Home Assistant.
2. NATS:
   • Lichtgewicht high-throughput pub/sub event bus voor microservice-interne communicatie binnen HERMS.
3. InfluxDB:
   • Time-series database voor temperatuur- en procesmetingen van het brouwproces en sensordata.
4. PostgreSQL & MongoDB:
   • Relationele en document stores voor algemene cluster- en applicatiedata.
5. RabbitMQ:
   • Enterprise message broker voor asynchrone taken en wachtrijen.