Instance architecture
UDS versions confirmed by the owner, 2026-10-14: Core v1.13.1 is installed and operator CLI v0.39.0 was just installed. See platform versions for evidence limits and separately pinned delivery tooling.
Recorded baseline: 2026-09-24. This describes the selected design and dated deployment evidence, not a fresh network audit. Check private Homelab/platform issue #1 before any public-edge change.
Overall architecture
Open the architecture chart at full size. On narrow screens, scroll the chart horizontally.
Chart reconciled 2026-10-17; DNS direction corrected 2026-10-18 from the dated placement and dependency records on this page, platform, storage and recovery, and delivery and operations. It summarizes component boundaries, not a new live-health check. Pi-hole is retained for LAN DNS and ad blocking; existing AIStor consumers remain in place during the SeaweedFS transition. Public-edge handoff and workload-specific acceptance retain the limits below.
Physical and cluster placement
| System | Recorded role | State and constraint |
|---|---|---|
| NucBox G5 | RKE2 server, control plane and etcd | Established; tainted against ordinary application workloads. Forgejo may share its hardware while remaining outside Kubernetes. |
| Sager laptop | RKE2 worker | General workloads; secondary game-server and Jellyfin placement are targets. Its GTX 1070 is deferred. |
| OptiPlex 5070 | RKE2 worker | Primary game-server placement. Some game data remains node-local; shared TrueNAS storage is a future option where performance permits. |
| Media server | RKE2 GPU worker | RTX 3080 Ti; ComfyUI is bound to this node and its local assets. |
| TrueNAS SCALE | Outside-cluster storage | Existing datasets, NFS/iSCSI CSI backing, external PostgreSQL and S3-compatible storage. |
| Forgejo and Windows runner | Outside Kubernetes | Forgejo hosts source/issues/releases; Windows Hyper-V retains true Windows execution. |
The RKE2 baseline recorded in the Core readiness record is Kubernetes v1.35.7+rke2r1, with Canal networking and bundled ingress disabled. Four nodes were Ready at that gate. Recheck versions and health before upgrades. Node placement record is historical; owning platform and application repositories control present scheduling.
Client traffic, DNS and ingress
Open the DNS and ingress chart at full size. Dashed lines show DNS lookup or the unconfirmed public-edge target, as labelled; solid lines show application traffic paths.
The resolver supplies addresses; it does not proxy application traffic. MetalLB 0.16.1 in Layer 2 mode supplies service VIPs with node-scoped wired advertisements. Normal UDS HTTP/HTTPS ingress uses the existing Istio tenant and admin gateways, not a second ingress controller. The admin VIP is LAN-only and must never be a public forwarding target.
Owner decision, 2026-09-16, reconfirmed 2026-10-18: retain Pi-hole for LAN DNS and ad blocking. No Technitium migration is planned. Private Homelab/platform #25 was closed on 2026-09-16 after the owner cancelled the replacement. Preserve independent LAN DNS placement and the existing DHCP/client DNS path, split names and filtering. Verify those paths and rollback before any future DNS/routing change. Cloudflare is authoritative for public DNS and the cert-manager DNS-01 integration.
Native Istio routes terminate TLS. Known legacy hosts pass through an explicit SNI allowlist to NPM, which retains TLS termination for them; unknown SNI has no wildcard NPM fallback. The 29-host allowlist and validation in private Homelab/platform are the configuration source. A passing legacy HTTP comparison does not by itself prove certificate trust.
The architecture record describes a target public path through the Sager TCP relay (10.0.0.107) to the tenant VIP. The last captured rollback baseline instead forwarded TCP 80/443 directly to NPM. The global public NAT/LAN DNS handoff is not recorded complete in platform #1; check the actual router and resolver before treating either path as current. Actual Budget and GitchAlerts have individually accepted production routes, which does not prove every legacy host has been cut over.
External dependency boundaries
- TrueNAS provides static NFS datasets and dynamic TrueNAS CSI NFS/iSCSI storage; Kubernetes owns the PV/PVC and driver resources. Media-node local PVs keep ComfyUI models and state on that node. See storage and recovery.
- External PostgreSQL 18 with pgvector supplies Keycloak and suitable apps through separate databases and roles. Database-native backup and restore remain independent of Kubernetes volume backup.
- GitchAuth is the visual identity for the UDS Keycloak sign-in page. On 2026-09-28, the owner confirmed the deployed theme and its dark charcoal background look correct after
Homelab/platform#84;Homelab/platform#47was closed and moved to Done. This is owner-confirmed visual acceptance. Desktop/mobile screenshots and sign-in, MFA, reset and keyboard-flow results were not separately recorded. The owning procedure covers application, verification and rollback without changing the realm, client or authentication policies. - S3-compatible object storage on TrueNAS serves Loki/Velero and other approved consumers. Protect its data and access path independently so a cluster rebuild can reach backups.
- OpenBao holds runtime secret values; ESO reconciles scoped Kubernetes Secrets. Forgejo Actions secrets hold CI credentials. These are distinct trust and recovery domains.
- Renovate is deployed as a background CronJob on UDS, independently of Core, with its schedule enabled on 2026-10-04. The owner accepted dry runs and bot onboarding; private Homelab/renovate runs 93/103 record installation and activation. Its instance-wide autodiscovery follows the bot's repository access and uses no HTTP gateway. Delivery and operations records the evidence and remaining coverage checks.
- Forgejo itself is outside Kubernetes initially, so a failed cluster can still host source and issues; shared NucBox hardware remains a physical failure dependency.
Hostname rules
New applications normally use <app>.app.gitchegumi.com on the standard UDS tenant gateway and its existing wildcard TLS coverage. Migrated applications keep their established production hostnames; their per-host NPM-to-Istio handoff must coordinate allowlist removal and native route activation. Development validation uses <app>.dev.gitchegumi.com where applicable. Do not infer an app's route from the name alone; see applications and the migration procedure.
Failure domains
This is a single RKE2 control-plane/etcd server, not a highly available control plane. MetalLB failover does not move node-local ComfyUI models or OptiPlex game data. A local PV's Retain policy prevents automatic deletion but is not an off-node backup. OpenBao, external PostgreSQL, object storage, DNS, and Forgejo each need their own reachable recovery path; cluster resource recreation does not restore their data.