homelab-v3

Joel's production-lite homelab: Talos Kubernetes on Proxmox, reconciled by Argo CD, fronted by Cloudflare Tunnel, and managed through small GitOps changes.

Quick links

Thing	Link
GitOps root app	k8s/apps/_apps.yaml
Bootstrap notes	docs/bootstrap.md
Architecture decisions	docs/adr/
OpenClaw agent overview	docs/agents/
Current phase docs	docs/superpowers/
Terraform/OpenTofu	tofu/
Argo CD UI	argo.joelmccoy.dev
Mealie	mealie.joelmccoy.dev
Kaneo	kaneo.joelmccoy.dev
Grafana	grafana.joelmccoy.dev

Architecture at a glance

Internet
  │
  ▼
Cloudflare DNS + Tunnel
  │
  ▼
cloudflared → Istio Gateway API HTTPS listener
  │
  ▼
Argo CD-managed Kubernetes apps on Talos VMs
  │
  ├─ Cilium networking + Hubble visibility
  ├─ Istio Ambient service mesh
  ├─ Longhorn persistent storage
  ├─ cert-manager wildcard TLS
  └─ kube-prometheus-stack monitoring foundation

Platform building blocks

SVG	Component	What it is used for	Repo	Upstream
	Proxmox VE	Hypervisor for the Talos Kubernetes VMs.	tofu/proxmox.tf	Website
	Talos Linux	Immutable Kubernetes node OS. OpenTofu renders and applies machine config.	tofu/talos.tf	Docs
	Kubernetes	Three combined control-plane/worker nodes for homelab services.	tofu/talos.tf	Docs
	OpenTofu	Provisions Proxmox VMs, Talos bootstrap material, and Cloudflare resources.	tofu/	Docs
	Cloudflare R2	Remote OpenTofu state backend.	tofu/backend.tf	Docs

GitOps apps

The table below inventories GitOps-managed platform components. Some rows are direct Argo CD child apps discovered by k8s/apps/_apps.yaml, while others are notable subcomponents or features configured within those apps via Helm values, plain manifests, or both.

SVG	App	What it is used for	Repo	Upstream
	Argo CD	GitOps controller and UI. Reconciles everything after bootstrap.	k8s/apps/argo-cd/	Docs
	Cilium	CNI, eBPF datapath, kube-proxy replacement, NetworkPolicy base, and Hubble.	k8s/apps/cilium/	Docs
	Hubble	Network flow observability from Cilium. Relay and UI are enabled.	k8s/apps/cilium/values.yaml	Docs
	Gateway API	Kubernetes-native ingress API used by the Istio gateway and HTTPRoutes.	k8s/apps/gateway-api/	Docs
	Istio base	Installs Istio CRDs and shared control-plane resources.	k8s/apps/istio-base/	Docs
	Istio CNI	Node-level CNI plugin required for Ambient mesh traffic redirection.	k8s/apps/istio-cni/	Docs
	istiod	Istio control plane for xDS, certificates, and mesh configuration.	k8s/apps/istiod/	Docs
	ztunnel	Istio Ambient node proxy that provides L4 mTLS for meshed namespaces.	k8s/apps/istio-ztunnel/	Docs
	Istio Gateway	Internal ClusterIP HTTPS gateway that Cloudflare Tunnel reaches in-cluster.	k8s/apps/istio-gateway/	Docs
	cert-manager	Issues and renews wildcard TLS certificates with Let's Encrypt DNS01.	k8s/apps/cert-manager/	Docs
	Let's Encrypt	Public certificate authority for joelmccoy.dev and *.joelmccoy.dev.	k8s/apps/cert-manager/manifests/	Website
	cloudflared	Outbound-only tunnel from the cluster to Cloudflare's edge.	k8s/apps/cloudflared/	Docs
	external-dns	Watches Gateway API routes and manages Cloudflare DNS records.	k8s/apps/external-dns/	Docs
	Longhorn	Distributed Kubernetes block storage and default StorageClass.	k8s/apps/longhorn/	Docs
	RustFS	In-cluster S3-compatible object storage (Rust). Backs Loki and future Velero, with built-in admin console + Keycloak SSO.	k8s/apps/rustfs/	Docs
	Sealed Secrets	Stores encrypted Kubernetes Secrets safely in git.	k8s/apps/sealed-secrets/	Docs
	kube-prometheus-stack	Monitoring foundation chart for Prometheus Operator and its standard Kubernetes exporters.	k8s/apps/monitoring/	Chart
	Prometheus Operator	Manages Prometheus, Alertmanager, ServiceMonitor, and PrometheusRule custom resources.	k8s/apps/monitoring/values.yaml	Docs
	Prometheus	Scrapes and stores cluster/app metrics. Configured with modest homelab retention.	k8s/apps/monitoring/values.yaml	Docs
	Alertmanager	Alert routing and notification engine, installed by kube-prometheus-stack.	k8s/apps/monitoring/values.yaml	Docs
	node-exporter	Exposes Linux node CPU, memory, filesystem, and network metrics.	k8s/apps/monitoring/values.yaml	Docs
	kube-state-metrics	Converts Kubernetes object state into Prometheus metrics.	k8s/apps/monitoring/values.yaml	Docs
	Grafana	Dashboard UI for Prometheus + Loki. OIDC via Keycloak; admins group → Admin role. Exposed at grafana.joelmccoy.dev.	k8s/apps/monitoring/values.yaml	Docs
	Loki	Log aggregation in Monolithic mode, chunks on RustFS via an Argo-managed bucket bootstrap hook.	k8s/apps/loki/	Docs
	Alloy	DaemonSet log shipper from K8s pods to Loki. Replaces deprecated Promtail.	k8s/apps/alloy/	Docs
	metrics-server	Provides the metrics.k8s.io API for kubectl top and HPA.	k8s/apps/metrics-server/	Docs
	CloudNativePG	Postgres operator. Each app declares its own Cluster CR; DBs live in app namespaces.	k8s/apps/cnpg-operator/	Docs
	Crossplane	Universal control plane. Hosts provider-keycloak for declarative SSO clients per app.	k8s/apps/crossplane/	Docs
	Keycloak operator	Manages Keycloak instance lifecycle via the Keycloak CR.	k8s/apps/keycloak-operator/	Docs
	Keycloak	OIDC identity provider for cluster apps. Realm-level config via keycloak-config-cli PostSync hook; per-app clients via Crossplane Client CRs.	k8s/apps/keycloak/	Docs
	provider-keycloak	Crossplane provider that reconciles Keycloak realms, clients, users via admin API.	k8s/apps/crossplane-providers/	Docs
	Mealie	Recipe manager, meal planner, and shopping list app with Keycloak SSO.	k8s/apps/mealie/	Docs
	Kaneo	Project management and ticket tracking app with Keycloak SSO and API/MCP-friendly auth.	k8s/apps/kaneo/	Docs

Public routes

Hostname	Owner	Purpose
argo.joelmccoy.dev	Argo CD	GitOps UI and operational dashboard.
sso.joelmccoy.dev	Keycloak	OIDC identity provider; serves the homelab realm.
mealie.joelmccoy.dev	Mealie	Recipe manager, meal planner, and shopping list app.
grafana.joelmccoy.dev	Grafana	Metrics + logs dashboards (Prometheus + Loki datasources).
kaneo.joelmccoy.dev	Kaneo	Project management and ticket tracking.
s3.joelmccoy.dev	RustFS	S3 API at /, admin console UI at /rustfs/console/.
*.joelmccoy.dev	Istio Gateway + cert-manager	Wildcard HTTPS listener for future homelab services.

Operating model

• Git is source of truth. Runtime changes should land in this repository and flow through Argo CD.
• OpenTofu owns infrastructure. Proxmox, Talos bootstrap, Cloudflare tunnel, and remote state are described in tofu/.
• Argo CD owns cluster apps. The app-of-apps discovers every k8s/apps/<app>/application.yaml.
• Secrets stay encrypted. Commit SealedSecrets, never plaintext credentials.
• Small PRs beat big-bang changes. Architecture decisions live in docs/adr/.

Validation

The repo's pinned toolchain lives in .mise.toml. Typical checks:

mise install
mise run lint
mise run fmt

PRs run the same pre-commit path in GitHub Actions and render an Argo CD diff preview for app changes.