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>
90 lines
5.7 KiB
Markdown
90 lines
5.7 KiB
Markdown
# 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)
|
|
1. 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.
|
|
2. `deploy/kubernetes/platform/dev` raises `services.loadbalancers` to exactly 1;
|
|
node ports stay 0; stage and World0 stay 0.
|
|
3. evo-server implements the session window (`--session-window`) as above, with tests
|
|
and an amendment to this ADR, and the base deployment passes it.
|
|
4. Only `region/dev` includes 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.
|