commit a362b056371b733131c03db04ee61a88626c59d4 Author: brupje Date: Sun Oct 18 14:22:34 2026 +0200 feat: initialise cluster superproject with submodules and platform docs diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..39202a8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,16 @@ +# OS generated files +.DS_Store +Thumbs.db + +# Editor directories and files +*.swp +*.swo +*~ +.vscode/* +!.vscode/settings.json +!.vscode/extensions.json +.idea/ + +# Temporary / log files +*.log +scratch/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..b167ef4 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,12 @@ +[submodule "cluster-infra"] + path = cluster-infra + url = https://git.bnhmeijer.nl/bart/cluster-infra.git +[submodule "HERMS"] + path = HERMS + url = https://git.bnhmeijer.nl/bart/HERMS.git +[submodule "k8s-infra-vmserver"] + path = k8s-infra-vmserver + url = https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git +[submodule "smart-home"] + path = smart-home + url = https://git.bnhmeijer.nl/bart/smart-home.git diff --git a/HERMS b/HERMS new file mode 160000 index 0000000..8c78b80 --- /dev/null +++ b/HERMS @@ -0,0 +1 @@ +Subproject commit 8c78b80131377bdb74e2f263bc00ee2c3fbc6abb diff --git a/README.md b/README.md new file mode 100644 index 0000000..a3518d9 --- /dev/null +++ b/README.md @@ -0,0 +1,119 @@ +# Homelab Cluster Platform + +Centrale Git meta-repository voor de homelab Kubernetes infrastructuur, domotica en gespecialiseerde automatiseringsdiensten van `bnhmeijer.nl` op `vmserver` (`10.2.0.4`). + +--- + +## ๐Ÿงญ Inhoudsopgave + +- [Overzicht](#-overzicht) +- [Git Submodules & Repositories](#-git-submodules--repositories) +- [Aan de Slag](#-aan-de-slag) + - [Nieuwe clone inclusief submodules](#nieuwe-clone-inclusief-submodules) + - [Bestaande checkout bijwerken](#bestaande-checkout-bijwerken) + - [Werken met submodules](#werken-met-submodules) +- [Platform Architectuur](#-platform-architectuur) +- [Documentatie](#-documentatie) + +--- + +## ๐Ÿ“Œ Overzicht + +Deze repository fungeert als **superproject** dat alle componenten van het platform samenbrengt: +* **Infrastructurele Services**: Databases, caching, messaging en reverse proxy configuraties. +* **GitOps & Deployment**: Volledig geautomatiseerde uitrol via Gitea Actions en ArgoCD. +* **Brouwautomatisering (HERMS)**: IoT hardware, firmware, Rust controllers en een Next.js interface. +* **Smart Home**: Home Assistant en sensorkoppelingen binnen het Kubernetes cluster. + +--- + +## ๐Ÿ“ฆ Git Submodules & Repositories + +| Map / Submodule | Git Remote | Doel | Belangrijkste Componenten | +| :--- | :--- | :--- | :--- | +| **[`cluster-infra`](file:///home/bart/git/cluster/cluster-infra)** | `https://git.bnhmeijer.nl/bart/cluster-infra.git` | Kerninfrastructuur & middleware | PostgreSQL, MongoDB, InfluxDB, RabbitMQ, Mosquitto MQTT, Dnsmasq, Apache vhosts | +| **[`k8s-infra-vmserver`](file:///home/bart/git/cluster/k8s-infra-vmserver)** | `https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git` | GitOps configuratierepository | Kustomize manifests, Envoy Gateway HTTPRoutes, ArgoCD ApplicationSets | +| **[`HERMS`](file:///home/bart/git/cluster/HERMS)** | `https://git.bnhmeijer.nl/bart/HERMS.git` | Geautomatiseerd brouwplatform | Rust microservices, Next.js frontend, ESP32 firmware, KiCad hardware | +| **[`smart-home`](file:///home/bart/git/cluster/smart-home)** | `https://git.bnhmeijer.nl/bart/smart-home.git` | Huisautomatisering | Home Assistant, IoT netwerk- en migratiescripts | + +--- + +## ๐Ÿš€ Aan de Slag + +### Nieuwe clone inclusief submodules +Om deze repository inclusief alle onderliggende projecten direct te klonen: +```bash +git clone --recurse-submodules +``` + +### Bestaande checkout bijwerken +Wanneer de repository al is gekloond zonder submodules, of om alle submodules te initialiseren: +```bash +git submodule update --init --recursive +``` + +Om alle submodules naar de nieuwste remote commits te synchroniseren: +```bash +git submodule update --remote --merge +``` + +### Werken met submodules +1. Wijzigingen in code committen en pushen binnen de submodule zelf: + ```bash + cd cluster-infra + git checkout main + git commit -am "feat: nieuwe configuratie" + git push origin main + ``` +2. De nieuwe submodule status vastleggen in deze root repository: + ```bash + cd .. + git add cluster-infra + git commit -m "chore(submodules): update cluster-infra reference" + git push + ``` + +--- + +## ๐Ÿ›๏ธ Platform Architectuur + +```mermaid +flowchart TD + WAN([Internet / LAN]) --> Apache["Apache Reverse Proxy (vmserver: 10.2.0.4)"] + + subgraph Host ["vmserver Bare-Metal"] + Apache -->|SSL & OIDC| Keycloak["Keycloak (login.bnhmeijer.nl)"] + Apache --> Gitea["Gitea (git.bnhmeijer.nl)"] + Apache --> Media["Nextcloud / Jellyfin / *Arr"] + Apache -->|Envoy Gateway NodePort 32608| Gateway["Envoy Gateway API"] + end + + subgraph K8s ["Kubernetes Cluster"] + Gateway --> Routes[HTTPRoutes] + Routes --> InfraWeb["Infra Web Dashboard"] + Routes --> HomeAssistant["Home Assistant"] + Routes --> HermsUI["HERMS UI"] + + ArgoCD["ArgoCD GitOps"] -->|Sync Manifests| K8sWorkloads[Deployments / Services / ConfigMaps] + end + + subgraph CI_CD ["CI/CD Pipeline"] + Gitea -->|Push Trigger| Actions["Gitea Actions"] + Actions -->|Build & Push Image| Registry["Container Registry"] + Actions -->|Update Image Tags| GitOpsRepo["k8s-infra-vmserver"] + GitOpsRepo --> ArgoCD + end +``` + +--- + +## ๐Ÿ“š Documentatie + +Alle gedetailleerde platformdocumentatie bevindt zich in de map **[`docs/`](file:///home/bart/git/cluster/docs)**: + +* ๐Ÿ“„ **[Platform Overzicht & Architectuur](file:///home/bart/git/cluster/docs/platform.md)**: Uitgebreide toelichting over de architectuur, lagen en principes. +* ๐ŸŒ **[Systeemarchitectuur & GitOps](file:///home/bart/git/cluster/docs/architecture.md)**: Diepgaande uitleg over de GitOps pipeline, network ingress en storage. +* ๐Ÿ“Š **[Live Cluster Status](file:///home/bart/git/cluster/docs/cluster-status.md)**: Actuele hardware-specs, namespaces, pods, PVCs en routes op `10.2.0.4`. +* ๐Ÿ›ก๏ธ **[Apache Reverse Proxy & VHosts](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)**: VHosts configuraties, SSL terminatie en OIDC authenticatie. +* ๐Ÿ“ฆ **[Repository Details & Modules](file:///home/bart/git/cluster/docs/repositories.md)**: Mappenstructuur, protocollen (MQTT/NATS) en microservices. +* ๐Ÿ’ก **[Developer & Agent Cheatsheet](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)**: Handige commando's, git conventies en valkuilen. diff --git a/cluster-infra b/cluster-infra new file mode 160000 index 0000000..3bbc88f --- /dev/null +++ b/cluster-infra @@ -0,0 +1 @@ +Subproject commit 3bbc88f0822c521c40db27533eeac25c864dafa2 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e014469 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,29 @@ +# Cluster Workspace Documentatie + +Dit overzicht is bedoeld als referentie- en contextdocumentatie voor ontwikkelaars en AI-assistenten die werken binnen de werkmap `/home/bart/git/cluster`. + +--- + +## ๐Ÿ“Œ Overzicht van de Workspace + +De werkmap `/home/bart/git/cluster` is een centrale **Git meta-repository** (superproject) voor het private home-server / homelab Kubernetes cluster. De individuele subsystemen zijn gekoppeld als **Git submodules** en synchroniseren autonoom met de private Gitea-instantie (`https://git.bnhmeijer.nl`). + +### Submodules in deze repository + +| Submodule | Doel | Primaire technologieรซn | +| :--- | :--- | :--- | +| **[`cluster-infra/`](file:///home/bart/git/cluster/cluster-infra)** | Infrastructurele services & middleware in K8s | K8s, Docker, Postgres, MongoDB, InfluxDB, RabbitMQ, Mosquitto, Dnsmasq, Apache/Nginx vhosts | +| **[`HERMS/`](file:///home/bart/git/cluster/HERMS)** | Geautomatiseerd brouwplatform (Heat Exchange Recirculating Mash System) | Rust (Controller & Storage), Next.js / TypeScript (Frontend), ESP32 C++ (Firmware), KiCad (Hardware PCB), Python (Simulator) | +| **[`k8s-infra-vmserver/`](file:///home/bart/git/cluster/k8s-infra-vmserver)** | GitOps configuratie repository gemonitord door ArgoCD | Kubernetes Kustomize manifests, Gateway API (HTTPRoute) | +| **[`smart-home/`](file:///home/bart/git/cluster/smart-home)** | Huisautomatisering en IoT integraties | Home Assistant / IoT configuraties | + +--- + +## ๐Ÿ“‘ Documentatie-index + +* **[Platform Overzicht & Architectuur](file:///home/bart/git/cluster/docs/platform.md)**: Integraal platformoverzicht, subsystemen, beveiliging en GitOps principes. +* **[Systeemarchitectuur & GitOps](file:///home/bart/git/cluster/docs/architecture.md)**: Hoe services, Gitea Actions pipelines, container registry, ArgoCD en Kubernetes samenwerken. +* **[Live Cluster Status (10.2.0.4)](file:///home/bart/git/cluster/docs/cluster-status.md)**: Actuele status, node-specificaties, namespaces, pods, PVCs en HTTPRoutes van het actieve cluster. +* **[Apache Reverse Proxy & VHosts](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)**: Details over Apache op `10.2.0.4`, `/sites/vhosts`, TLS/OIDC terminatie en koppeling naar Envoy Gateway (NodePort 32608). +* **[Repository Details & Modules](file:///home/bart/git/cluster/docs/repositories.md)**: Gedetailleerde beschrijving van alle componenten, mappen, protocollen (MQTT, NATS) en functies. +* **[AI Cheatsheet & Developer Richtlijnen](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)**: Snelle referentie voor commando's, submodule workflows, conventies en valkuilen. diff --git a/docs/agent-cheatsheet.md b/docs/agent-cheatsheet.md new file mode 100644 index 0000000..f623624 --- /dev/null +++ b/docs/agent-cheatsheet.md @@ -0,0 +1,65 @@ +# AI Agent & Developer Cheatsheet + +Dit document bevat richtlijnen, veelvoorkomende commando's en belangrijke valkuilen voor het werken in deze workspace. + +--- + +## โš ๏ธ Belangrijke Valkuilen & Regels + +1. **Root is de Git meta-repository (met Git submodules)**: + * `/home/bart/git/cluster` beheert het superproject, submodules en de overkoepelende documentatie in `docs/`. + * Gebruik `git submodule update --init --recursive` om submodules binnen te halen of bij te werken. + * Commits op codebase-niveau voer je uit binnen de desbetreffende submodule map (bijv. `git -C cluster-infra ...` of navigeer naar de map). + * Werk vervolgens desgewenst de submodule pointers bij in de root repository. +2. **Submodule status & wijzigingen**: + * Let op 'dirty' of untracked files binnen submodules (`git status` in de root toont of een submodule gewijzigd is). +3. **CI/CD Triggers via Path Filtering**: + * Zowel `cluster-infra` als `HERMS` gebruiken `dorny/paths-filter`. Wijzigingen in documentatie of mappen die niet in de filters staan triggeren geen container build. + * Controleer bij het toevoegen van nieuwe componenten of de workflow (`.gitea/workflows/*.yaml`) het pad herkent. +4. **GitOps Manifest Synchronisatie**: + * Pas productie Kubernetes manifests bij voorkeur aan in de bronrepository (bijv. in `cluster-infra//k8s` of `HERMS/deployments`), zodat de CI/CD pipeline ze gesynchroniseerd kan overzetten naar `k8s-infra-vmserver`. + * Direct wijzigen in `k8s-infra-vmserver` kan leiden tot overschrijvingen bij een volgende geautomatiseerde build als dezelfde bestanden vanuit de bron worden gepusht. + +--- + +## ๐Ÿ› ๏ธ Snelle Commando's + +### Git Status over alle repositories +```bash +for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do + echo "=== $d ===" + git -C "$d" status -s +done +``` + +### Git Remotes verifiรซren +```bash +for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do + echo "=== $d ===" + git -C "$d" remote -v +done +``` + +### Recente commits bekijken +```bash +for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do + echo "=== $d ===" + git -C "$d" log -n 1 --oneline +done +``` + +--- + +## ๐ŸŽจ Design & Coding Conventies + +* **Frontend (`HERMS/frontend`)**: + * **Thema**: SevenGrid Aurora Dark (`#0A0F12` background, Teal `#1DC7B7` accent, Coral `#E26F3A` verwarmingsaccent). + * **Styling**: Tailwind CSS met `rounded-full` pills voor status en switches. + * **Communicatie**: REST via storage API + WebSocket stream voor live telemetry. +* **Backend Services (`HERMS`)**: + * Geschreven in **Rust** (Cargo workspace of individuele crates). + * Foutafhandeling met duidelijke loguitvoer (`tracing` / `log`). +* **MQTT Topics**: + * Altijd strings voor heaters (`hlt`, `mlt`, `boil`). + * Telemetrie publiceren met `retain: true`. + * Commando's op `/cmd`, bevestiging op `/state`. diff --git a/docs/apache-reverse-proxy.md b/docs/apache-reverse-proxy.md new file mode 100644 index 0000000..a2f5fab --- /dev/null +++ b/docs/apache-reverse-proxy.md @@ -0,0 +1,86 @@ +# Apache Reverse Proxy & VHosts (`10.2.0.4`) + +Op host **`vmserver`** (`10.2.0.4`) draait Apache 2 direct als **Edge Reverse Proxy, TLS Terminator en OIDC Authentication Gateway** vรณรณr zowel bare-metal hostdiensten als het Kubernetes cluster. + +--- + +## ๐Ÿ“‚ Locatie & Synchronisatie + +* **Host-pad (live configuratie)**: `/sites/vhosts/` +* **Git Repository**: [`cluster-infra/vhosts/`](file:///home/bart/git/cluster/cluster-infra/vhosts/) in `https://git.bnhmeijer.nl/bart/cluster-infra.git` +* **Certificaten (Let's Encrypt)**: `/etc/letsencrypt/live/thuus.bnhmeijer.nl/` +* **Certbot challenge root**: `/sites/certroot/.well-known` + +--- + +## ๐Ÿ—๏ธ Architectuur: Apache als Edge Gateway + +```mermaid +flowchart TD + Client[Inkomend Verkeer / Browser] -->|Poort 80 / 443| Apache["Apache 2 (10.2.0.4)
/sites/vhosts/"] + + subgraph Apache Functionaliteit + Apache -->|TLS / Let's Encrypt| SSL[SSL Termination] + Apache -->|mod_auth_openidc| OIDC[OIDC Auth via login.bnhmeijer.nl] + end + + subgraph Bare-Metal Host Services + Apache -->|Proxy :3000| Gitea[Gitea git.bnhmeijer.nl] + Apache -->|Proxy :8096| Jellyfin[Jellyfin /jellyfin] + Apache -->|Proxy :8000 / :5000| Radio[Icecast & Radio Chicken] + Apache -->|Proxy :8686, :7878, ...| ArrStack["*Arr Stack (Sonarr, Radarr, etc.)"] + Apache -->|DocRoot /sites/nextcloud| Nextcloud[cloud.bnhmeijer.nl] + Apache -->|Proxy 192.168.2.15:8123| HomeAssistant[ha.bnhmeijer.nl] + end + + subgraph Kubernetes Cluster (vmserver:10.2.0.4) + Apache -->|Proxy 127.0.0.1:32608
(Envoy Gateway NodePort)| EnvoyGW[Envoy Gateway NodePort 32608] + EnvoyGW -->|HTTPRoute: herms.bnhmeijer.nl| HermsUI[herms frontend:3000] + EnvoyGW -->|HTTPRoute: login.bnhmeijer.nl| KeycloakK8s[keycloak:8080] + EnvoyGW -->|HTTPRoute: influx.bnhmeijer.nl| InfluxK8s[influxdb:8086] + EnvoyGW -->|HTTPRoute: thuus.bnhmeijer.nl/argocd| ArgoCDK8s[argocd-server:80] + EnvoyGW -->|HTTPRoute: infra.bnhmeijer.nl| InfraWebK8s[infra-web:3000] + end +``` + +--- + +## ๐Ÿ“‘ Overzicht van VHosts (`/sites/vhosts/`) + +| Configuratiebestand | Domein / Hostname | Doel & Proxy Doel | +| :--- | :--- | :--- | +| [`001-main.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/001-main.conf) | `thuus.bnhmeijer.nl`, `10.2.0.4`, `vmserver.lan` (HTTP:80) | Port 80 redirect naar HTTPS + `/radio/` Icecast streaming | +| [`001-main-le-ssl.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/001-main-le-ssl.conf) | `thuus.bnhmeijer.nl` (HTTPS:443) | **Hoofdportaal**: OIDC auth (Keycloak), Nextcloud alias, Jellyfin, Icecast, *Arr stack, `/argocd` via `127.0.0.1:32608` | +| [`cloud.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/cloud.conf) & [`cloud-ssl.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/cloud-ssl.conf) | `cloud.bnhmeijer.nl` | Nextcloud DocumentRoot `/sites/nextcloud/` | +| [`git.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/git.conf) | `git.bnhmeijer.nl` | Reverse proxy naar Gitea op `127.0.0.1:3000` (512MB body limit) | +| [`hass.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/hass.conf) & [`hass-ssl.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/hass-ssl.conf) | `ha.bnhmeijer.nl` | Reverse proxy + WebSockets naar Home Assistant (`192.168.2.15:8123`) | +| [`herms.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/herms.conf) & [`herms-int.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/herms-int.conf) | `herms.bnhmeijer.nl` | Reverse proxy + WebSockets naar Envoy Gateway NodePort (`127.0.0.1:32608`) | +| [`keycloak.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/keycloak.conf) | `login.bnhmeijer.nl` | Reverse proxy naar Keycloak via Envoy Gateway NodePort (`127.0.0.1:32608`) | +| [`influx-ui.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/influx-ui.conf) | `influx-ui.bnhmeijer.nl`, `influx-ui.lan` | Reverse proxy naar InfluxDB Explorer via Envoy Gateway NodePort (`127.0.0.1:32608`) | + +--- + +## ๐Ÿ” OpenID Connect (OIDC) Configuratie + +In [`001-main-le-ssl.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/001-main-le-ssl.conf) verzorgt `mod_auth_openidc` Single Sign-On (SSO): +* **Metadata URL**: `https://login.bnhmeijer.nl/realms/master/.well-known/openid-configuration` +* **Client ID**: `apache-vmserver` +* **Redirect URI**: `https://thuus.bnhmeijer.nl/oauth2/callback` +* **Doorgegeven Headers**: Claims worden doorgestuurd als `X-User` (`%{OIDC-preferred_username}e`) en `X-Email` (`%{OIDC-email}e`). Interne OIDC headers worden gestript voordat verkeer naar backend-services gaat. + +--- + +## โš™๏ธ Beheer & Herstarten op de Host + +Wanneer vhosts worden aangepast op de host `vmserver`: + +```bash +# Configuratie testen +sudo apache2ctl configtest + +# Apache herladen zonder downtime +sudo systemctl reload apache2 + +# Of volledige herstart +sudo systemctl restart apache2 +``` diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..b73bf20 --- /dev/null +++ b/docs/architecture.md @@ -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//"] + 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/`, maakt ArgoCD automatisch een nieuwe applicatie aan (`cluster-infra-`) 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. diff --git a/docs/cluster-status.md b/docs/cluster-status.md new file mode 100644 index 0000000..d0dd551 --- /dev/null +++ b/docs/cluster-status.md @@ -0,0 +1,100 @@ +# Live Cluster Documentatie (`10.2.0.4`) + +Dit document beschrijft de actuele status, topologie, workloads en configuratie van het live Kubernetes cluster dat draait op host **`vmserver`** (`10.2.0.4`). + +--- + +## ๐Ÿ–ฅ๏ธ 1. Node Specificaties & Host Details + +Het cluster draait momenteel als een gecombineerde single-node control-plane & worker: + +| Eigenschap | Waarde | +| :--- | :--- | +| **Node Naam** | `vmserver` | +| **IP-Adres** | `10.2.0.4` *(gemigreerd vanaf `192.168.2.4` via [`migrate-k8s-node-ip.sh`](file:///home/bart/git/cluster/cluster-infra/migrate-k8s-node-ip.sh))* | +| **Rollen** | `control-plane` (draait tevens workloads) | +| **Kubernetes Versie** | `v1.37.0` | +| **OS & Kernel** | Ubuntu 24.04.4 LTS / Linux `6.8.0-142-generic` (x86_64) | +| **Container Runtime** | `containerd://2.2.1` | +| **CPU Capaciteit** | 12 vCPU cores (~16% / 1.7 cores in gebruik) | +| **Geheugencapaciteit** | 60.4 GiB RAM (~49% / 26.6 GiB in gebruik) | +| **Lokale Opslag** | ~287 GB | + +--- + +## ๐ŸŒ 2. Cluster Networking & Ingress + +### Networking & CNI +* **CNI Provider**: **Calico** (`calico-node` en `calico-kube-controllers`). +* **Pod CIDR**: `10.10.174.0/...` +* **Service CIDR**: `10.96.0.0/12` +* **DNS**: + * **CoreDNS**: In-cluster DNS resolutie (`10.96.0.10`). + * **Dnsmasq**: Draait op het hostnetwerk (`10.2.0.4:53`) voor lokale domeinen (`*.lan`). + +### Gateway API & Ingress Routing +De ingress-routering verloopt via **Envoy Gateway** met HTTPRoute configuraties: + +| Hostnames | Doelservice | Namespace | Doel | +| :--- | :--- | :--- | :--- | +| `thuus.bnhmeijer.nl` | `argocd-server:80` | `argocd` | ArgoCD Web UI & GitOps beheer | +| `herms.bnhmeijer.nl`, `herms.lan` | `frontend:3000` | `herms` | HERMS Brouwinstallatie Web UI | +| `login.bnhmeijer.nl` | `keycloak:8080` | `keycloak` | Keycloak Identity & Access Management | +| `influx.bnhmeijer.nl`, `influx.lan` | `influxdb:8086` | `cluster-infra` | InfluxDB Time-Series API | +| `influx-ui.bnhmeijer.nl`, `influx-ui.lan` | `influxdb-explorer:80` | `cluster-infra` | InfluxDB Web Explorer | +| `infra.bnhmeijer.nl`, `infra.lan`, `dns.bnhmeijer.nl`, `dns.lan` | `infra-web:3000` | `cluster-infra` | Infra Web Dashboard & DNS beheer | +| `gravitymon.lan` | `gravitymon-2-nats:8002` | `herms` | HTTP Ingress voor Gravitymon hydrometers | + +--- + +## ๐Ÿ’พ 3. Opslag & Persistent Volumes (PVCs) + +Het cluster gebruikt Rancher's **`local-path-provisioner`** (`local-path-storage` namespace) als dynamische CSI provisioner: + +| Namespace | PVC Naam | Volume | Grootte | Toewijzing | Status | +| :--- | :--- | :--- | :--- | :--- | :--- | +| `cluster-infra` | `influxdb-storage-influxdb-0` | `pvc-6928459f-...` | 10 GiB | InfluxDB Data | **Bound** | +| `cluster-infra` | `mongodb-data-mongodb-0` | `pvc-151480ce-...` | 10 GiB | MongoDB Data | **Bound** | +| `cluster-infra` | `rabbitmq-data-rabbitmq-0` | `pvc-44ef79fe-...` | 5 GiB | RabbitMQ Queue Data | **Bound** | +| `cluster-infra` | `influxdb-explorer-data` | `pvc-f03fb841-...` | 2 GiB | Explorer User State | **Bound** | +| `cluster-infra` | `dnsmasq-data` | `pvc-1246f9a0-...` | 1 GiB | Dnsmasq Configuratie | **Bound** | +| `keycloak` | `postgres-pvc` | `pvc-ad5f9b7d-...` | 1 GiB | Keycloak Database | **Bound** | + +--- + +## ๐Ÿ“ฆ 4. Namespaces & Actieve Workloads + +### `herms` (Bierbrouwsysteem) +* **`frontend`**: Next.js UI (SevenGrid Aurora Dark Mode). +* **`herms-controller`**: Rust microservice voor stappen, PID-berekening en timers. +* **`herms-storage`**: Rust opslag- en databeheerservice. +* **`gravitymon-2-nats`**: Rust hydrometer event ingress. +* **`nats`**: NATS message bus voor microservices. +* **`mosquitto`**: MQTT broker voor communicatie met firmware / sensoren. + +### `cluster-infra` (Gedeelde Middleware) +* **`influxdb-0`** & **`influxdb-explorer`**: Opslag en analyse van telemetriegegevens. +* **`mongodb-0`**: NoSQL documentopslag. +* **`rabbitmq-0`**: AMQP message broker. +* **`dnsmasq`**: Lokale DNS server (HostPort 53). +* **`email-service`**: Interne mailservice. +* **`infra-web`**: Dashboard voor netwerk/infrastructuur. + +### `argocd` (GitOps Engine) +* Bevat `argocd-server`, `argocd-repo-server`, `argocd-application-controller`, `argocd-applicationset-controller`, `argocd-dex-server`, `argocd-redis` en `argocd-notifications-controller`. +* **Actieve ArgoCD Applicaties**: + * `cluster-infra-dnsmasq` (Healthy) + * `cluster-infra-email-service` (Healthy) + * `cluster-infra-influxdb` (Healthy) + * `cluster-infra-infra-web` (Healthy) + * `cluster-infra-mongodb` (Healthy) + * `cluster-infra-rabbitmq` (Healthy) + * `herms-suite` (Healthy) + +### `keycloak` (Identiteit & Toegangsbeheer) +* **`keycloak`**: Quarkus-based Keycloak Server bereikbaar via `login.bnhmeijer.nl`. +* **`postgres`**: Dedicated PostgreSQL database voor Keycloak realm-data. + +### `kube-system` & `envoy-gateway-system` +* Control-plane componenten: `kube-apiserver`, `etcd`, `kube-controller-manager`, `kube-scheduler`, `kube-proxy`, `metrics-server`. +* Data-plane en ingress proxies: `envoy-gateway` en `envoy-default-eg`. diff --git a/docs/platform.md b/docs/platform.md new file mode 100644 index 0000000..bb2b3f0 --- /dev/null +++ b/docs/platform.md @@ -0,0 +1,126 @@ +# Platform Overzicht & Architectuur + +Dit document biedt een integraal overzicht van het homelab- en serverplatform gehost op `vmserver` (`10.2.0.4`) binnen het domein `bnhmeijer.nl`. + +--- + +## ๐ŸŽฏ Doel & Filosofie van het Platform + +Het platform fungeert als een betrouwbare, geautomatiseerde en zelf-gehoste infrastructurele backbone voor: +1. **Centrale infrastructuurdiensten**: Databases, message brokers en interne netwerkdiensten. +2. **GitOps & CI/CD**: Volledig geautomatiseerde build- en deploymentpijplijnen vanaf broncode tot Kubernetes pod. +3. **Smart Home & IoT**: Integratie van domotica (Home Assistant) en sensoren in het thuisnetwerk. +4. **Gespecialiseerde Automatisering (HERMS)**: Een geavanceerd biersysteem met sensoren, actuatoren, microservices en webinterfaces. + +--- + +## ๐Ÿ›๏ธ Systeemlagen + +Het platform is opgebouwd in duidelijke scheiding van lagen: + +```mermaid +flowchart TD + Internet([Publiek Internet / Lokaal LAN]) --> ApacheEdge["Apache Reverse Proxy (vmserver: 10.2.0.4)"] + + subgraph HostLevel ["Host Laag (vmserver / bare-metal)"] + ApacheEdge + Gitea["Gitea (git.bnhmeijer.nl)"] + Keycloak["Keycloak (login.bnhmeijer.nl)"] + MediaDiensten["Media & Storage (Jellyfin, Nextcloud, *Arr)"] + DnsmasqHost["Dnsmasq (Lokale DNS / DHCP)"] + end + + ApacheEdge -->|SSL / OIDC Terminatie| Keycloak + ApacheEdge -->|Reverse Proxy| Gitea + ApacheEdge -->|Reverse Proxy| MediaDiensten + ApacheEdge -->|"Cluster Ingress (NodePort 32608)"| EnvoyGateway["Envoy Gateway API (k8s)"] + + subgraph K8sCluster ["Kubernetes Cluster"] + EnvoyGateway --> HTTPRoutes[HTTPRoutes] + + subgraph Namespaces + subgraph NS_ClusterInfra ["namespace: cluster-infra"] + Postgres[(PostgreSQL)] + Mongo[(MongoDB)] + Influx[(InfluxDB)] + RabbitMQ[(RabbitMQ)] + Mosquitto[Mosquitto MQTT] + InfraWeb[Infra Web Dashboard] + end + + subgraph NS_SmartHome ["namespace: smart-home"] + HomeAssistant[Home Assistant] + end + + subgraph NS_HERMS ["namespace: herms"] + HermsFrontend[HERMS Web UI] + HermsController[HERMS Controller] + HermsStorage[HERMS Storage] + NATS[NATS Broker] + end + + subgraph NS_ArgoCD ["namespace: argocd"] + ArgoCD[ArgoCD ApplicationSets] + end + end + + HTTPRoutes --> InfraWeb + HTTPRoutes --> HomeAssistant + HTTPRoutes --> HermsFrontend + end + + subgraph GitOpsPipeline ["CI/CD & GitOps"] + Gitea -->|Gitea Actions CI| ContainerReg[Gitea Container Registry] + ContainerReg --> GitOpsCommit[Update manifests in k8s-infra-vmserver] + GitOpsCommit --> ArgoCD + ArgoCD -->|Reconcile & Deploy| Namespaces + end +``` + +--- + +## ๐Ÿ“ฆ Repositories & Submodules + +De werkmap `/home/bart/git/cluster` is gestructureerd als een **Git superproject** dat de verschillende subsystemen als submodules integreert: + +| Submodule | Doel | Primaire Stack | +| :--- | :--- | :--- | +| **[`cluster-infra`](file:///home/bart/git/cluster/cluster-infra)** | Kerninfrastructuur & databases in K8s | PostgreSQL, MongoDB, InfluxDB, RabbitMQ, Mosquitto, Dnsmasq, Apache vhosts | +| **[`k8s-infra-vmserver`](file:///home/bart/git/cluster/k8s-infra-vmserver)** | GitOps repository gemonitord door ArgoCD | Kubernetes Kustomize manifests, HTTPRoutes, Service definities | +| **[`HERMS`](file:///home/bart/git/cluster/HERMS)** | Geautomatiseerd brouwplatform (brouwautomatisering) | Rust microservices, Next.js / TypeScript GUI, ESP32 C++, KiCad PCB | +| **[`smart-home`](file:///home/bart/git/cluster/smart-home)** | Huisautomatisering & IoT | Home Assistant, netwerk- en migratiescripts | + +--- + +## ๐Ÿ”’ Beveiliging, Ingress & Identiteitsbeheer + +1. **SSL / TLS**: + * Alle inkomende HTTPS-verbindingen worden afgehandeld door Apache met geautomatiseerde Let's Encrypt SSL-certificaten. +2. **Authenticatie & Autorisatie (OIDC)**: + * Beschermde diensten worden beveiligd via `mod_auth_openidc` gekoppeld aan de centrale Keycloak-instantie (`https://login.bnhmeijer.nl`). +3. **Cluster Routing**: + * Apache fungeert als edge gateway en forwardt verkeer bestemd voor Kubernetes pods naar **Envoy Gateway** via NodePort `127.0.0.1:32608`. Envoy routeert vervolgens op basis van `HTTPRoute` resources in de K8s namespaces. + +--- + +## ๐Ÿ”„ GitOps Workflow + +De broncode en configuraties worden beheerd volgens strikte GitOps-principes: +1. **Wijziging in Broncode**: Een ontwikkelaar pusht code naar `main` in bijv. `cluster-infra` of `HERMS`. +2. **CI Pipeline (Gitea Actions)**: + * Detecteert gewijzigde componenten via `dorny/paths-filter`. + * Bouwt geoptimaliseerde Docker images en pusht deze naar de private Gitea container registry. + * Werkt de container image tag bij in de GitOps-repository [`k8s-infra-vmserver`](file:///home/bart/git/cluster/k8s-infra-vmserver). +3. **CD Reconciliatie (ArgoCD)**: + * ArgoCD detecteert de gewijzigde manifests in `k8s-infra-vmserver`. + * Past automatisch een rolling update / sync toe op de Kubernetes cluster workloads. + +--- + +## ๐Ÿ“š Verder Lezen + +* **[Systeemarchitectuur & GitOps Details](file:///home/bart/git/cluster/docs/architecture.md)** +* **[Live Cluster Status & Hardware](file:///home/bart/git/cluster/docs/cluster-status.md)** +* **[Apache Reverse Proxy & VHosts](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)** +* **[Repository- & Module-overzicht](file:///home/bart/git/cluster/docs/repositories.md)** +* **[AI Agent & Developer Cheatsheet](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)** diff --git a/docs/repositories.md b/docs/repositories.md new file mode 100644 index 0000000..d8bf116 --- /dev/null +++ b/docs/repositories.md @@ -0,0 +1,90 @@ +# Repository Details & Modules + +Dit document bevat specifieke details over de vier repositories in deze workspace, inclusief mappenstructuur, protocollen en configuraties. + +--- + +## 1. ๐Ÿบ HERMS Repository + +* **Pad**: `/home/bart/git/cluster/HERMS` +* **Git Remote**: `https://git.bnhmeijer.nl/bart/HERMS.git` +* **Doel**: Geautomatiseerd Heat Exchange Recirculating Mash System (bierbrouwen). + +### Submodules & Componenten +* **`frontend/`**: + * Next.js, React, Tailwind CSS. + * Geรฏmplementeerd met het SevenGrid Aurora Dark Mode thema (`#0A0F12`, Aurora Teal `#1DC7B7`, Coral `#E26F3A`). + * Realtime updates via WebSockets (`/api/ws`) en NATS opslag events (`herms.storage.>`). + * Live monitoring voor vaten: HLT (Warmtewisselaar), MLT (Maischketel), BK (Kookketel). +* **`herms-controller/`**: + * Rust microservice. + * Beheert timers, receptstappen en automatische PID/doeltemperatuurberekeningen op basis van ketelafhankelijkheden (`depends_on`, `difference_abs`, `delay_minutes`). + * Publiceert doeltemperaturen naar MQTT. +* **`herms-storage/`**: + * Rust REST API service met NATS integratie. + * Slaat recepten, batchlogs en telemetrie op. + * Schrijft metingen door naar InfluxDB (Line Protocol). +* **`gravitymon-2-nats/`**: + * Rust microservice die HTTP POST data van Gravitymon hydrometers ontvangt en op NATS publiceert. +* **`firmware/` & `mock-esp/`**: + * `firmware/`: C++ PlatformIO code voor de ESP32 microcontroller op de installatie. + * `mock-esp/`: Python simulator voor het nabootsen van keteltemperaturen, pompen en verwarmingselementen over MQTT. +* **`bierpcb/`**: + * KiCad PCB project met schema's, relais-aansturingen, thermokoppelingangscircuits (MAX31855/MAX31856) en I2C IO expanders. +* **`recepten/`**: + * JSON bierrecepten met stappen (maischstappen, kooktijden, ingrediรซnten). + +### MQTT Protocol Regels +* **Base topic**: `//` (bijv. `avr59/hermsdev/` of `avr59/installation1/`). +* **KeteI Identifiers (``)**: Altijd string, nooit indexnummer (`hlt`, `mlt`, `boil`). +* **Command-to-State regel**: Een commando op `...//cmd` MOET direct door de ontvanger worden bevestigd op `...//state` met `retain: true`. +* **Telemetry**: Actuele temperatuur op `heater//temperature/state` (payload bijv. `"65.2"`). + +--- + +## 2. ๐ŸŒ cluster-infra Repository + +* **Pad**: `/home/bart/git/cluster/cluster-infra` +* **Git Remote**: `https://git.bnhmeijer.nl/bart/cluster-infra.git` +* **Doel**: Gedeelde infrastructurele componenten en middleware. + +### Aanwezige Services +* **`postgresql/`**: PostgreSQL cluster configuratie en persistent storage. +* **`mongodb/`**: MongoDB replica/single instance. +* **`influxdb/`**: InfluxDB time-series database. +* **`rabbitmq/`**: AMQP message broker. +* **`mosquitto/`**: Eclipse Mosquitto MQTT broker. +* **`dnsmasq/`**: Lokale DNS caching en forwarding. +* **`email-service/`**: Interne mailrelay / notificatiedienst. +* **`infra-web/`**: Dashboard/webinterface voor infrastructuurbeheer. +* **`vhosts/`**: Apache/Nginx SSL en non-SSL reverse proxy configuraties voor bnhmeijer.nl domeinen. +* **`argocd/`**: ApplicationSet configuratie voor automatische ontdekking van workloads. + +### Hoe een nieuwe service toevoegen aan cluster-infra +1. Maak een map aan: `mkdir -p /k8s` +2. Plaats eventueel een `Dockerfile` in `/`. +3. Voeg Kubernetes manifests toe in `/k8s/` (`deployment.yaml`, `service.yaml`, `kustomization.yaml`). +4. Commit & push naar `main`. De Gitea Actions workflow bouwt en synchroniseert dit automatisch naar `k8s-infra-vmserver`. + +--- + +## 3. ๐Ÿš€ k8s-infra-vmserver Repository + +* **Pad**: `/home/bart/git/cluster/k8s-infra-vmserver` +* **Git Remote**: `https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git` +* **Doel**: GitOps source-of-truth voor ArgoCD. + +### Mappenstructuur +* **`workloads/`**: + * **`cluster-infra/`**: Wordt automatisch gevuld door CI/CD wanneer componenten in `cluster-infra` wijzigen. + * **`demo/`**: Bevat de demonstratieapplicatie (`podinfo`) en bijbehorende Gateway API `HTTPRoute` (`/demo`). + * **`herms/`**: De productiemanifests voor de HERMS microservices. + +--- + +## 4. ๐Ÿ  smart-home Repository + +* **Pad**: `/home/bart/git/cluster/smart-home` +* **Git Remote**: `https://git.bnhmeijer.nl/bart/smart-home.git` +* **Doel**: Smart home configuraties (Home Assistant integraties, scripts, automatiseringen). +* **Status**: In initiรซle opstartfase. diff --git a/k8s-infra-vmserver b/k8s-infra-vmserver new file mode 160000 index 0000000..cdbaf9e --- /dev/null +++ b/k8s-infra-vmserver @@ -0,0 +1 @@ +Subproject commit cdbaf9e6b7423971fb5b28dc669b3a0920345b70 diff --git a/smart-home b/smart-home new file mode 160000 index 0000000..9125a3f --- /dev/null +++ b/smart-home @@ -0,0 +1 @@ +Subproject commit 9125a3fa3f7cff334b6ccb44d97129769b0ea340