feat: initialise cluster superproject with submodules and platform docs

2026-10-18 14:22:34 +02:00
commit a362b05637
14 changed files with 734 additions and 0 deletions
@@ -0,0 +1,87 @@
+# 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**:
+
+```mermaid
+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`](file:///home/bart/git/cluster/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/`](file:///home/bart/git/cluster/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`](file:///home/bart/git/cluster/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.