From 8149f1bbbf9bab87006ed5a9180851d12281c187 Mon Sep 17 00:00:00 2001 From: CTO Agent Date: Sun, 2 Aug 2026 11:25:41 +0000 Subject: [PATCH] docs(stalwart): Document network architecture with Hetzner LB integration Add comprehensive Network Architecture section explaining: - Two-tier load balancing (K8s LoadBalancer + Hetzner LB) - Why LoadBalancer service type is required (Hetzner CCM auto-management) - Traffic flow from external clients to Stalwart pods - Warning against changing to NodePort (breaks CCM integration) This documents the investigation from DEV-439, confirming that the current LoadBalancer service setup is correct and necessary for our infrastructure. Co-Authored-By: Paperclip --- apps/stalwart/README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/apps/stalwart/README.md b/apps/stalwart/README.md index 098044f..65fa1aa 100644 --- a/apps/stalwart/README.md +++ b/apps/stalwart/README.md @@ -11,6 +11,30 @@ Clean deployment of Stalwart mail server with username/password authentication o - **Backup**: Daily restic backup to S3 at 3 AM - **Web UI**: https://mail.basicstack.de +## Network Architecture + +Stalwart uses a two-tier load balancing setup: + +1. **Kubernetes LoadBalancer Services**: Four separate LoadBalancer services expose SMTP (25, 587, 465) and IMAP (143, 993) ports. The service type `LoadBalancer` is required because the Hetzner Cloud Controller Manager (CCM) automatically provisions and manages the Hetzner Load Balancer when it detects this service type. + +2. **Hetzner Load Balancer**: Automatically managed by the Hetzner CCM. The load balancer distributes traffic across: + - k3s-cp-1 (control plane node) + - k3s-worker-1 through k3s-worker-5 (worker nodes) + +### Traffic Flow + +``` +External Client → Hetzner Load Balancer → NodePort → K8s Service → Stalwart Pod +``` + +The Hetzner CCM watches for LoadBalancer-type services and automatically: +- Creates/updates the Hetzner LB configuration +- Configures health checks +- Maps service ports to node ports +- Manages target nodes + +**Important**: Changing the service type from `LoadBalancer` to `NodePort` would break the automatic Hetzner LB management. The current setup is the correct configuration for our infrastructure. + ## Files - `stalwart-fresh-deployment.yaml` - Main deployment manifest