tudattr/homelab-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README to reflect current cluster state

Browse Source 
- 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
This commit is contained in:
Tuan-Dat Tran
2026-07-01 00:19:34 +02:00
parent 1c2eb6688b
commit acea97f0ce
1 changed files with 19 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
README.md
View File

@@ -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 ## Hardware
| Layer | Host | Role | Resources | | 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 | – | | **Ntfy** | Self-hosted push notifications | – |
| **Stirling PDF** | PDF tools | – | | **Stirling PDF** | PDF tools | – |
| **Karakeep** | Bookmark manager | – | | **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 | – | | **Gitea Runner** | CI/CD runner | – |
| **Zeroclaw** | Per-user instances (×3) via Kustomize overlays | – |
| **Arr Stack** | Media automation suite | Prowlarr · Sonarr · Radarr · Unpackarr | | **Arr Stack** | Media automation suite | Prowlarr · Sonarr · Radarr · Unpackarr |
| **Download clients** | VPN-isolated download clients (×2) | Gluetun sidecar | | **Download clients** | VPN-isolated download clients (×2) | Gluetun sidecar |
| **Jellyfin** | Media server with hardware transcoding | Docker · Intel QuickSync | | **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 ## Repo layout
``` ```
@@ -164,12 +163,12 @@ ansible-homelab/
│ ├── kube_vip/ # kube-vip DaemonSet + TLS SAN config │ ├── kube_vip/ # kube-vip DaemonSet + TLS SAN config
│ ├── docker_host/ # Docker + Intel QuickSync GPU passthrough │ ├── docker_host/ # Docker + Intel QuickSync GPU passthrough
│ ├── proxmox/ # Proxmox node setup │ ├── 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 │ └── raspberry_pi/ # Raspberry Pi: Zigbee2MQTT + Mosquitto via Docker Compose
└── playbooks/ └── playbooks/
argocd-homelab/ argocd-homelab/
├── infrastructure/ # MetalLB, Longhorn, Cert-Manager, ECK, Istio, ... ├── infrastructure/ # MetalLB, Longhorn, Cert-Manager, Istio, Prometheus, ...
├── services/ # Immich, Vaultwarden, arr-stack, Home Assistant, ... ├── services/ # Immich, Vaultwarden, arr-stack, Home Assistant, ...
└── cluster-apps/ # ArgoCD App-of-Apps root + ApplicationSets └── cluster-apps/ # ArgoCD App-of-Apps root + ApplicationSets
``` ```