From acea97f0ce0d0009682ed6a6e8f6320d75831f02 Mon Sep 17 00:00:00 2001 From: Tuan-Dat Tran Date: Wed, 1 Jul 2026 00:19:34 +0200 Subject: [PATCH] Update README to reflect current cluster state - Move Design notes above Hardware so the why is visible before the detail tables - Gitea: update from Docker on docker-host11 to k8s deployment (migrated June 2026) - Remove Zeroclaw (no namespace on cluster, not registered in ArgoCD) - Drop ECK/Elastic Agent references (elastic-system not active) - Fix infrastructure layout comment: replace ECK with Prometheus --- README.md | 39 +++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index d9ac55e..fa79d65 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,22 @@ graph TB --- +## Design notes + +Everything goes through Git. ArgoCD owns the cluster state; nothing gets `kubectl apply`'d directly. ArgoCD Image Updater handles the image update loop: when a new tag appears in the registry, it commits the change back to Git and ArgoCD picks it up from there. + +Secrets are committed to Git too, encrypted via Sealed Secrets. Only the in-cluster controller holds the decryption key. + +No ports are open on the home router. Internal load balancing goes through MetalLB + Traefik. External access uses Cloudflare tunnels or a WireGuard VPN routed through the edge VPS. + +Longhorn handles block storage by replicating volumes across all 14 agent nodes. The media library lives on a dedicated NFS host instead — latency matters when Jellyfin is reading large video files, and NFS is simpler for that. + +Metrics go to Prometheus + Grafana. Logs go to Loki, also surfaced in Grafana — Promtail runs as a DaemonSet and ships pod logs from every node. + +All VMs are provisioned with Terraform and configured by Ansible. Rebuilding from scratch doesn't require remembering anything. + +--- + ## Hardware | Layer | Host | Role | Resources | @@ -125,9 +141,8 @@ All VMs run Debian 12 on `virtio` network bridges, provisioned from cloud-init t | **Ntfy** | Self-hosted push notifications | – | | **Stirling PDF** | PDF tools | – | | **Karakeep** | Bookmark manager | – | -| **Gitea** | Self-hosted Git (source of truth for ArgoCD) | Docker on docker-host11 | +| **Gitea** | Self-hosted Git (source of truth for ArgoCD) | Kubernetes · Longhorn PVC · SSH via MetalLB · Pangolin tunnel (git.tudattr.dev) | | **Gitea Runner** | CI/CD runner | – | -| **Zeroclaw** | Per-user instances (×3) via Kustomize overlays | – | | **Arr Stack** | Media automation suite | Prowlarr · Sonarr · Radarr · Unpackarr | | **Download clients** | VPN-isolated download clients (×2) | Gluetun sidecar | | **Jellyfin** | Media server with hardware transcoding | Docker · Intel QuickSync | @@ -137,22 +152,6 @@ All VMs run Debian 12 on `virtio` network bridges, provisioned from cloud-init t --- -## Design notes - -Everything goes through Git. ArgoCD owns the cluster state; nothing gets `kubectl apply`'d directly. ArgoCD Image Updater handles the image update loop: when a new tag appears in the registry, it commits the change back to Git and ArgoCD picks it up from there. - -Secrets are committed to Git too, encrypted via Sealed Secrets. Only the in-cluster controller holds the decryption key. - -No ports are open on the home router. Internal load balancing goes through MetalLB + Traefik. External access uses Cloudflare tunnels or a WireGuard VPN routed through the edge VPS. - -Longhorn handles block storage by replicating volumes across all 14 agent nodes. The media library lives on a dedicated NFS host instead — latency matters when Jellyfin is reading large video files, and NFS is simpler for that. - -Metrics go to Prometheus + Grafana. Logs go to Loki, also surfaced in Grafana — Promtail runs as a DaemonSet and ships pod logs from every node. - -All VMs are provisioned with Terraform and configured by Ansible. Rebuilding from scratch doesn't require remembering anything. - ---- - ## Repo layout ``` @@ -164,12 +163,12 @@ ansible-homelab/ │ ├── kube_vip/ # kube-vip DaemonSet + TLS SAN config │ ├── docker_host/ # Docker + Intel QuickSync GPU passthrough │ ├── proxmox/ # Proxmox node setup -│ ├── edge_vps/ # VPS: WireGuard, Traefik, Pangolin, Elastic Agent +│ ├── edge_vps/ # VPS: WireGuard, Traefik, Pangolin │ └── raspberry_pi/ # Raspberry Pi: Zigbee2MQTT + Mosquitto via Docker Compose └── playbooks/ argocd-homelab/ -├── infrastructure/ # MetalLB, Longhorn, Cert-Manager, ECK, Istio, ... +├── infrastructure/ # MetalLB, Longhorn, Cert-Manager, Istio, Prometheus, ... ├── services/ # Immich, Vaultwarden, arr-stack, Home Assistant, ... └── cluster-apps/ # ArgoCD App-of-Apps root + ApplicationSets ```