- Python 80.2%
- Shell 16.5%
- Dockerfile 2.8%
- Makefile 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| apps | ||
| clusters | ||
| docs | ||
| infographic/home-k8s-mesh | ||
| infrastructure | ||
| monitoring/controllers/home | ||
| .gitignore | ||
| Makefile | ||
| README.md | ||
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.