finn/homelab
Watch
2
0
Fork
You've already forked homelab
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Page: Platform Architecture
Pages
Home PR Previews Platform Architecture Service Inventory Storage and State
2 Platform Architecture
Finn Dührkop edited this page 2026-10-27 03:43:48 +00:00
Table of contents

Platform architecture

Cluster

  • The configured cluster has three Raspberry Pi nodes: management-pi-1 is the control plane; rack-1-pi-1 and rack-1-pi-2 are workers.
  • Terraform manages Kubernetes resources and Cloudflare configuration. Raspberry Pi host configuration and k3s installation are outside this repository's Terraform scope.
  • nodes.tf discovers nodes from their control-plane label, applies a NoSchedule taint to control-plane nodes, and labels worker nodes for Longhorn storage.
  • The cluster uses k3s built-in Traefik and ServiceLB.
  • The standalone virtual cluster registered in Argo CD is named orchard-core; preview workloads run inside it rather than in a per-repository cluster.

Network and name resolution

  • Public application hostnames are proxied Cloudflare records that target the Cloudflare Tunnel. The configured host set is defined by dns.tf: apex, git, auth, argocd, s3, console-s3, grafana, retro, romarr, prowlarr, bao, and preview.
  • cloudflared forwards those hostnames to Traefik over HTTPS. Origin TLS certificates are managed by cert-manager using DNS-01.
  • CoreDNS rewrites the configured public hostnames to the in-cluster Traefik service; preview subdomains use a matching rewrite rule.
  • jellyfin.113lab.dev is absent from the public tunnel host list. Its Ingress is internal to the LAN and its name is resolved through local router DNS.

Scheduling and shared platform behavior

  • The descheduler runs every 10 minutes and excludes the rustfs, longhorn-system, and kube-system namespaces.
  • Longhorn uses best-effort replica auto-balancing; details and storage boundaries are in the Storage and State page.
  • Forgejo runner Docker data is an emptyDir limited by configuration; a sidecar prunes unused data after 24 hours on a six-hour interval. Forgejo Actions logs and artifacts have a configured 14-day retention period.
  • Single-replica workloads with ReadWriteOnce storage use Recreate where configured, avoiding overlap between pods when a volume moves nodes.

Configuration sources

main.tf wires the Terraform modules. The node selection and labels are in nodes.tf; public hostnames and CoreDNS rewrites are in dns.tf; tunnel, certificate, vCluster, descheduler, and runner details are in modules/cloudflared/, modules/cert-manager/, modules/orchard-vcluster/, modules/descheduler/, and modules/forgejo-runner/.