ADR-0087 records the maintainer's route (void.aeternalisgames.com:7400 via a dedicated internal MetalLB VIP to the evolution-dev region pod, TLS end to end, CIDR-limited) and operator-opened windows enforced by evo-server. The route is a kustomize component included nowhere; the policy check encodes its shape and refuses enabling until VIP/CIDR, the dev quota and --session-window exist, with a 20-case self-test in the CI deploy stage. The base listener stays loopback. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.7 KiB
ADR-0087: Dev session route and operator-opened session windows
Status
Accepted for M9.8f as design (2026-10-02), evolution-dev only. The route is committed disabled; nothing was applied to the cluster. Enabling it is blocked by policy until the inputs and server-side window enforcement below exist. Narrowly supersedes ADR-0083 (loopback-only listener, never a Service) and ADR-0069 (no LoadBalancer Services) for evolution-dev, and only once enabled.
Context
Internal testers need the native client (M9.8e ZIP) to reach the dev region without
kubectl port-forward. The cluster inventory (INVENTORY.md, 2026-09-29) shows RKE2's
ingress-nginx 1.12.1 DaemonSet serving 80/443 on all four node addresses (public sites
included), MetalLB 0.15.2 in FRR mode with one LoadBalancer (Gitea SSH), and an existing
HTTP Ingress for void.aeternalisgames.com in namespace void. The session protocol is
TLS 1.3 over raw TCP (ADR-0082), not HTTP. Sessions need synthetic carrier inputs, which
ADR-0073 keeps drill-time only so dev history does not grow continuously.
Decision (maintainer, 2026-10-02)
Route. void.aeternalisgames.com:7400 resolves, in internal DNS, to a dedicated
internal MetalLB VIP (never automatically the control-plane address 172.10.1.160) that
fronts one LoadBalancer Service evo-region-session in evolution-dev, which forwards to
the region pod's port 7400. TLS 1.3 terminates in the region pod; its dev-CA server
certificate carries void.aeternalisgames.com, which the client verifies. No HTTP
Ingress, no TLS termination at nginx, no PROXY-protocol prefix. The Service uses
externalTrafficPolicy: Local (client addresses preserved), no node ports, a pinned
metallb.io/loadBalancerIPs annotation and loadBalancerSourceRanges. New connections
reach only a ready pod; after a replacement, clients reconnect with a fresh grant and
baseline (ADR-0083).
Access. Development workstation/test subnet only, in three layers: the edge firewall, the Service source ranges and a NetworkPolicy admitting TCP 7400 to the region pod from exactly those CIDRs. TLS with the dev CA and single-use, short-lived grants stay mandatory; grants remain bearer tokens.
Listener. The base keeps the opt-in listener on loopback through
REGION_SESSION_LISTEN=127.0.0.1:7400. Only the route component
(deploy/kubernetes/region/dev-session-route) binds the pod interface and names the
session port. The listener still starts only when sessions are enabled.
Windows. Sessions and synthetic inputs run only during an operator-opened test window with automatic expiry (default 30 minutes); always-on simulation waits for an explicit disposable-world lifecycle and retention. The endpoint (DNS, MetalLB Service) may stay configured permanently. A small dev-only GitOps configuration holds an activation id, the exact world/region identity and an absolute UTC expiry. Operations, via a manually triggered Gitea workflow: Open (default 30 min), Extend (new explicit expiry), Close (stop accepting sessions, close existing connections, stop synthetic inputs, drain pending commits) and Status (window, expiry, active sessions, committed tick). Expiry is enforced inside evo-server, not by a delayed cleanup job:
- a restart keeps the original absolute deadline, never a fresh duration;
- an expired configuration cannot reopen the listener;
- expiry stops synthetic generation as well as connections;
- a failed workflow cannot leave simulation running; cleanup may later restore the closed Git configuration. Grant expiry alone does not stop the generator.
Enabling (all required; tools/ci/deploy-policy-check.py refuses otherwise)
- The VIP (private, from the MetalLB pool) and permitted client CIDR(s) (private, no wider than /16) replace the REPLACE markers; Service ranges equal the policy's.
deploy/kubernetes/platform/devraisesservices.loadbalancersto exactly 1; node ports stay 0; stage and World0 stay 0.- evo-server implements the session window (
--session-window) as above, with tests and an amendment to this ADR, and the base deployment passes it. - Only
region/devincludes the component. Then: internal DNS for void to the VIP, the edge firewall rule, and a server-side dry-run (quota accounting of the Local health check port is to be confirmed there), a new dev server certificate for void.aeternalisgames.com, and live connectivity recorded separately in VALIDATION.md.
Open points for the maintainer
- Argo delivery. The aevolution-dev Application has no automated sync, and the policy forbids auto-sync outside the platform app (ADR-0069). A workflow commit alone will not deploy; either a manual sync per window or a scoped dev exception must be decided before implementing the workflow. CI holds no cluster credentials (ADR-0020), so Status can report Git state; live fields need a defined read path.
- void namespace. void.aeternalisgames.com already has an HTTP Ingress (namespace
void). Pointing internal DNS at the VIP changes what internal clients reach for that name; confirm or retire the existing route. - Window limits: maximum window length and clock-skew tolerance.
Alternatives considered
- ingress-nginx tcp-services or SNI passthrough on 443: couples game sessions to the shared web ingress (443 likely internet-facing) and needs controller changes.
- Port-forward only (ADR-0083): no tester-friendly endpoint.
- NodePort: opens a port on every node; forbidden by ADR-0069.
- Always-on sessions in dev: continuous synthetic history; rejected for now.
Consequences
One reviewed exception to "no LoadBalancer" for evolution-dev. The policy check and its
fail-closed self-test (tools/ci/deploy-policy-selftest.py) encode the route's shape and
the enabling preconditions. World0 and stage are untouched.