Files
aevolution/docs/networking/DEV_SESSION_OPERATIONS.md
T
dingoandClaude Opus 5.5 8a1e5ef53d Check rendered kustomize output in the deploy policy (M9.8f review)
The policy check now renders every overlay with pinned, checksum-verified
kustomize v5.8.1 (ADR-0088) and validates effective namespaces, session/input/
listener environment and arguments, ports, Services, quotas, policies, Ingresses
and Secrets, so inline/JSON patches and namespace changes cannot bypass it.
Route enabling is gated on an ADR-0087 amendment with tested server windows, route
addresses must be RFC 1918 or explicitly approved, and the Local health-check node
port is documented with its enabling evidence. Self-test grows to 33 cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 18:02:57 -04:00

95 lines
4.4 KiB
Markdown

# Dev session operations (M9.7)
Decision: [ADR-0083](../adr/0083-dev-region-sessions.md); protocol:
[DEV_SESSION_PROTOCOL](DEV_SESSION_PROTOCOL.md). **evolution-dev only.** Stage and
World0 have no session Secret, and `evo-server` refuses any environment but `dev`.
## 1. Build the tools
```sh
cmake -P tools/prepare-mbedtls.cmake
cmake --preset network && cmake --build --preset network # evo-dev-session
# Desktop client with remote mode (also needs SDL prepared):
cmake --preset client-network && cmake --build --preset client-network
```
The server image (`deploy/docker/Dockerfile`, `server-runtime`) is built with
`EVO_BUILD_NETWORK=ON`; a new image digest must be pinned in the dev overlay as usual
(ADR-0071) before the session flags exist in the cluster.
## 2. Create credentials on the operator machine (once)
```sh
evo-dev-session credentials --environment dev \
--server-name dev-region.evolution.test --out ~/aevolution-dev-session
```
Writes `dev-ca.pem` (public; give to dev clients), `server.pem` (public),
`server.key` and `grant.key` (secrets, owner-only, never overwritten). Keep the
directory private. Never commit these files; the policy check rejects Secrets in Git.
## 3. Provision the Secret (cluster administrator, out of band)
```sh
kubectl -n evolution-dev create secret generic evolution-dev-session \
--from-file=server.pem=$HOME/aevolution-dev-session/server.pem \
--from-file=server.key=$HOME/aevolution-dev-session/server.key \
--from-file=grant.key=$HOME/aevolution-dev-session/grant.key
```
The Deployment mounts it optionally (0440). Consumed grants are recorded in
`/objects/dev-session-grants.v1` on the region's persistent volume (fsynced before
each Welcome), so a restarted pod refuses grants its predecessor used. Corrupt or
unwritable ledgers fail closed (`error session-grant-ledger`, or sessions refused).
A sibling `.lock` file enforces one ledger owner across startup and compaction.
Do not delete or replace this lock file while a server might be running; its
presence does not mean a stale lock. Process exit releases the OS lock automatically.
A competing startup fails before modifying the ledger. Incomplete final records and
oversized lines are refused without rewriting; investigate the storage failure
rather than deleting grant history to force startup.
Rotation: create new credentials, replace the Secret, restart evo-region and
redistribute `dev-ca.pem`. Old grants stop verifying with the new key.
## 4. Session drill (enables sessions temporarily, then restores Git values)
```sh
EVO_DEV_SESSION=./build/network/evo-dev-session \
tools/ops/session-drill.sh ~/aevolution-dev-session [--context <name>]
```
Expected: `probe durable ...` before and after the forced pod deletion, a second
`probe welcome` with a higher epoch, `PASS session drill`. Record the output in
engineering/VALIDATION.md. Exit 1 on any missing observation; Git values are restored
on every exit path.
## 5. Interactive engineering session
While a drill-style override is active (`REGION_INPUTS=development-v1`,
`REGION_SESSION=dev`; revert afterwards: `kubectl -n evolution-dev set env
deployment/evo-region REGION_INPUTS= REGION_SESSION=`):
```sh
evo-dev-session grants --environment dev --key ~/aevolution-dev-session/grant.key \
--world 100 --frame 9 --region 1 --subject 7 --count 16 --out grants.bin
kubectl -n evolution-dev port-forward deploy/evo-region 17400:7400 &
evo-client --connect 127.0.0.1:17400 --server-name dev-region.evolution.test \
--ca ~/aevolution-dev-session/dev-ca.pem --grants grants.bin
```
The listener binds the pod's loopback, so only port-forward reaches it; nothing is
exposed through a Service, NodePort or Ingress. A grant bundle lasts at most one hour
and each connection consumes one grant. WASD sends intentions; the small chip under
the intention dot turns white (admitted), green (durable, no effect) or red/grey
(rejected or outcome unknown). Console lines report every session event.
## 6. Planned direct route (M9.8f, disabled)
ADR-0087 designs `void.aeternalisgames.com:7400` through a dedicated internal MetalLB
VIP to the region pod (TLS end to end, development/test CIDR only), opened only in
operator windows that evo-server itself expires. The manifests are in
`deploy/kubernetes/region/dev-session-route` and are not included anywhere; the policy
check refuses to enable them until the VIP, client CIDR, dev quota and server-enforced
session windows exist (ADR-0087 enabling list). Until then use the port-forward
procedures above.