Kubeadm cluster on bare metal and one cloud node. Flux CD, Cilium, Gateway API. Manifests for the public sites live here.
  • Python 80.2%
  • Shell 16.5%
  • Dockerfile 2.8%
  • Makefile 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-17 20:14:52 +00:00
apps ci(forgejo): give amd64 job containers the docker CLI 2026-11-17 15:14:06 -05:00
clusters docs: internal WireGuard-only service pattern (mechanism, firewall, add-next-service, negative tests + verification log) 2026-10-27 00:17:45 -04:00
docs apps: re-pin the contact APIs to their new :sha tags 2026-11-02 18:09:48 -05:00
infographic/home-k8s-mesh cillium gateway config switch to linode node as gateway 2026-09-14 23:47:48 -04:00
infrastructure docs: Grafana persistence + admin-password ownership and recovery path 2026-10-27 01:04:12 -04:00
monitoring/controllers/home monitoring: suppress the dead kubelet_volume_stats rules in kubernetes-storage 2026-10-27 02:22:46 -04:00
.gitignore Initial HomeK8s tree matching lab GitOps layout. 2026-09-10 23:38:04 -04:00
Makefile Initial HomeK8s tree matching lab GitOps layout. 2026-09-10 23:38:04 -04:00
README.md README: rewrite the public front door from the live cluster 2026-10-29 01:23:33 -04:00

HomeK8s

A three-node Kubernetes cluster: two machines on a home network and one cloud VPS, joined with kubeadm and reconciled from this repository by Flux CD. The manifests here run the public sites listed below, plus the git server and CI that build them.

Architecture

flowchart LR
  net([Internet]) --> cf["Cloudflare TLS"]
  cf --> t["cloudflared<br/>rpi, host service"]
  t --> gw["Cilium Gateway<br/>gateway-system/public<br/>10.10.0.2:8080"]
  gw --> rt["HTTPRoute"]
  rt --> svc["Service"]
  svc --> pod["Pods<br/>siriussec"]

Public requests terminate at Cloudflare and are carried by a cloudflared tunnel on rpi to the Cilium Gateway on siriussec at http://10.10.0.2:8080, where a Gateway API HTTPRoute selects the Service. The tunnel is the only public ingress.

Nodes and pods reach each other over a WireGuard mesh in 10.10.0.0/24. Cilium routes pod traffic natively across that tunnel — 10.244.0.0/16, no VXLAN overlay, and kube-proxy is replaced by Cilium's BPF data path.

Nodes

Node Roles WireGuard IP Architecture OS, kernel Runtime
siriussec control-plane, gateway, worker 10.10.0.2 amd64 Arch Linux, 6.18.50-2-lts containerd 2.3.5
rpi traffic, worker 10.10.0.1 arm64 Debian 13, 6.18.39+rpt-rpi-2712 containerd 2.3.4
linode none 10.10.0.5 amd64 Debian 13, 6.12.113+deb13-amd64 containerd 2.3.5

siriussec is the only node carrying the gateway role: Cilium's host-network Envoy must run on the same node as the backends, so every public workload is pinned there along with the default local-path volume. rpi is the WireGuard hub and runs the cloudflared tunnel host service; it is arm64 and carries network-adjacent pods, marked with a dedicated=network:PreferNoSchedule preference so the application nodes are used first.

linode is a cloud worker and is the least permanent node of the three — confirm the current node list with kubectl get nodes rather than relying on this table.

Stack

Layer Component Version
Cluster Kubernetes (kubeadm) v1.36.4
CNI and data path Cilium chart 1.20.1
GitOps Flux CD six Kustomizations, watching master
Ingress Cloudflare Tunnel into Cilium Gateway API —
Monitoring kube-prometheus-stack chart 92.14.0
Databases CloudNativePG operator 1.30.0, postgresql:16
Container runtime containerd 2.3.5 (2.3.4 on rpi)

Storage is the Rancher local-path provisioner, the default StorageClass, backed by /opt/local-path-provisioner on siriussec. Host-path volumes that must stay on the Pi use a second, static local-static StorageClass with Retain.

Services

Public hostnames, all terminating on the Gateway above:

Hostname Route What it serves
forgejo.siriusdevops.com forgejo/forgejo Forgejo git server and container registry
siriusdevops.com, www.siriusdevops.com siriusdevops/siriusdevops Static site and contact API
siriusgrowthsolutions.com, www.siriusgrowthsolutions.com sirius-growth/sirius-growth Static site, contact API, client portal
piedmonthomesvc.com, www.piedmonthomesvc.com piedmont/piedmont Static site and contact API

The git server and the client portal each run a single-instance CloudNativePG cluster (forgejo/pg, sirius-growth/portal). CI runs on the cluster itself: three Forgejo Actions runners execute jobs inside their own Docker-in-Docker sidecars, covering both arm64 and amd64.

Two services are deliberately not public. They answer on the bare WireGuard address, with no hostname and no Host header, and are reachable only from inside the tunnel:

Service Route Address Response
Grafana monitoring/grafana → internal http://10.10.0.2:8081/ 302 to /login
Hubble UI kube-system/hubble-ui → hubble-ui http://10.10.0.2:8084/ 200

Each needs its own Gateway object: Cilium renders one route table per Gateway, so two hostname-less routes sharing a Gateway would answer for either backend. The host firewall, not the Gateway, is the access boundary.

Repository layout

Flux watches master and runs six Kustomizations from these paths:

Path Kustomization Contents
clusters/homek8s flux-system Bootstrap and the top-level Kustomization list
infrastructure/home infrastructure Storage, Cilium, internal gateways, node tuning
infrastructure/networking/gateway-api gateway-api-crds Gateway API CRDs
infrastructure/databases/base databases CloudNativePG operator, vendored and patched
apps/home apps The workloads this cluster runs
monitoring/controllers/home monitoring Prometheus, Grafana, dashboards, alert rules

A new app is a directory under apps/base/<app>/ holding its namespace, workload, Service and HTTPRoute, plus one line in apps/home/kustomization.yaml. Push to master and Flux applies it.

Reference

docs/cluster-overview.md is the longer operator write-up. It is a snapshot and will drift; where it disagrees with kubectl, kubectl wins.

Audit

Read live on 2026-10-29 01:21 America/New_York, at commit aa0f67fe33394bd565b1f07813ed4355fa926934 on master.

Commands behind the tables above:

kubectl get nodes -o wide
kubectl version -o json
kubectl -n flux-system get kustomizations
kubectl get hr -A
kubectl get httproute -A
kubectl get cluster -A
kubectl get deploy -A
kubectl get storageclass
curl -H 'Host: <hostname>' http://10.10.0.2:8080/        # 200 for all seven
curl http://10.10.0.2:8081/                              # 302 → /login
curl http://10.10.0.2:8084/                              # 200

If this file disagrees with kubectl, kubectl wins.