(pre-development) Stars! PBeM service on Kubernetes
Expand Agones runtime discovery and WS-09 gate tracking
+93
-4
+80
-3
doc/agones.md
+80
-3
doc/agones.md
···
1
-
# genesis
1
+
# agones discovery brief (runtime boundary)
2
+
3
+
This document captures Agones-specific discovery needed to close runtime integration gates in Stage 5 planning.
4
+
5
+
Primary planning reference: [`/doc/total-host.workstream-dependency-map.md`](/doc/total-host.workstream-dependency-map.md)
6
+
7
+
## Why this exists
8
+
9
+
`total-host.codex` is intentionally product-first. Agones is introduced at the runtime boundary (`WS-09`) so core host behavior stays implementation-agnostic while platform constraints are still discovered early.
10
+
11
+
Source requirements: [`/doc/total-host.codex.md`](/doc/total-host.codex.md)
12
+
13
+
## What Agones gives us
14
+
15
+
Agones extends Kubernetes for dedicated game server workloads, primarily through CRDs and allocation/runtime controllers.
16
+
17
+
Key upstream references:
18
+
19
+
- [`agones-dev/agones` `site/content/en/docs/Overview/_index.md`](https://github.com/agones-dev/agones/blob/main/site/content/en/docs/Overview/_index.md)
20
+
- [`agones-dev/agones` `site/content/en/docs/Reference/gameserver.md`](https://github.com/agones-dev/agones/blob/main/site/content/en/docs/Reference/gameserver.md)
21
+
- [`agones-dev/agones` `site/content/en/docs/Reference/fleet.md`](https://github.com/agones-dev/agones/blob/main/site/content/en/docs/Reference/fleet.md)
22
+
- [`agones-dev/agones` `site/content/en/docs/Reference/fleetautoscaler.md`](https://github.com/agones-dev/agones/blob/main/site/content/en/docs/Reference/fleetautoscaler.md)
23
+
- [`agones-dev/agones` `site/content/en/docs/Reference/gameserverallocation.md`](https://github.com/agones-dev/agones/blob/main/site/content/en/docs/Reference/gameserverallocation.md)
24
+
- [`agones-dev/agones` `site/content/en/docs/Advanced/allocator-service.md`](https://github.com/agones-dev/agones/blob/main/site/content/en/docs/Advanced/allocator-service.md)
25
+
26
+
## Candidate CRDs and where they might fit
27
+
28
+
| Agones resource | What it does | Potential fit for stargones | Notes |
29
+
|---|---|---|---|
30
+
| `GameServer` | Single dedicated server process with lifecycle states | Runtime unit for one host worker process | Direct control possible, but usually managed via Fleet |
31
+
| `Fleet` | Desired pool of warm GameServers | Baseline control plane for capacity and rollout | Likely primary orchestration primitive |
32
+
| `FleetAutoscaler` | Fleet scaling policy engine | Optional for bursty host workloads | Useful if turn-generation demand varies |
33
+
| `GameServerAllocation` | Atomic selection/allocation of a ready GameServer | Match/scheduling path if we allocate workers on demand | Can be used via Kubernetes API |
34
+
| `Allocator Service` | mTLS gRPC/REST allocation API | External allocation path without direct K8s API access | Relevant for multi-cluster or external orchestrators |
35
+
36
+
## Integration shapes under consideration (not committed)
37
+
38
+
### Shape A: campaign-affine workers
39
+
40
+
- One long-lived runtime worker per campaign (or campaign shard) using Agones scheduling/lifecycle.
41
+
- Simpler campaign locality and state ownership.
42
+
- Could underutilize resources for low-activity campaigns.
43
+
44
+
### Shape B: pooled generation workers
45
+
46
+
- Shared pool of workers; campaigns are loaded for turn generation jobs.
47
+
- Better utilization at scale.
48
+
- Requires stronger artifact locking and isolation guarantees.
49
+
50
+
### Shape C: hybrid
51
+
52
+
- Fixed baseline workers plus burst allocation from shared pool.
53
+
- Most flexible, most policy complexity.
54
+
55
+
## Open decisions to close (`WS-09` gates)
56
+
57
+
- `AGD-01` **Runtime unit**: campaign-affine worker vs pooled worker model.
58
+
- `AGD-02` **Primary Agones control primitive**: direct `GameServer` management vs `Fleet`-first control model.
59
+
- `AGD-03` **Allocation path**: Kubernetes `GameServerAllocation` objects vs external `agones-allocator` service.
60
+
- `AGD-04` **State ownership boundary**: what remains authoritative in stargones storage vs ephemeral worker state.
61
+
- `AGD-05` **Lifecycle mapping**: mapping `LIF-*` transitions to Agones lifecycle states and failure semantics.
62
+
- `AGD-06` **Recovery model**: worker restart/eviction behavior and required replay or reconciliation flows.
63
+
- `AGD-07` **Operational model**: do we run a stargones operator/controller, and if so what exact reconciliation surface it owns.
2
64
3
-
we don't know much about agones architecture. how do we host a game with some seats? what crds does agones have and what are the elements we might want to be creating?
65
+
## Current stance
4
66
5
-
i somewhat imagine us having our own operator, our own all inclusive system. i sort of suspect that's not the totally normal agones usage?
67
+
- We expect to own a stargones-specific control layer/operator regardless of Agones usage style.
68
+
- We are intentionally deferring final selection of Shapes A/B/C until `AGD-*` decisions are resolved.
69
+
- This is acceptable because Stage 5 currently needs boundary clarity, not final platform lock-in.
70
+
71
+
## How this connects to current planning artifacts
72
+
73
+
- `WS-09` gating is tracked in [`/doc/total-host.workstream-dependency-map.md`](/doc/total-host.workstream-dependency-map.md).
74
+
- Requirement-level constraints remain in [`/doc/total-host.codex.md`](/doc/total-host.codex.md).
75
+
- Coverage and release criteria remain in [`/doc/total-host.coverage-matrix.md`](/doc/total-host.coverage-matrix.md).
76
+
77
+
## Next discovery outputs (before implementation lock-in)
78
+
79
+
- `OUT-01` Decision record selecting runtime shape (A/B/C) with tradeoff rationale.
80
+
- `OUT-02` Lifecycle mapping table (`LIF-*` -> runtime events/controllers).
81
+
- `OUT-03` Failure mode table for worker loss, allocation failures, and reconciliation outcomes.
82
+
- `OUT-04` Security model for allocator/API access and operator privileges.
+13
-1
doc/total-host.workstream-dependency-map.md
+13
-1
doc/total-host.workstream-dependency-map.md
···
21
21
| `WS-06` Distribution and Player Isolation | `DST-01`..`DST-03`, `IFC-005`, `SEC-001`, `SEC-002`, `INV-04`, `CAP-201`, `CAP-202` | `WS-03`, `WS-05` | Delivery/API boundary | Ready |
22
22
| `WS-07` Operator Visibility and Diagnostics | `NFR-01`, `NFR-02`, `CAP-301`, `CAP-302`, `IFC-006` | `WS-03`, `WS-04`, `WS-06` | Ops telemetry/log boundary | Ready |
23
23
| `WS-08` Traceability and Compliance Reporting | `TRC-01`..`TRC-05`, `AC-402`, `HND-201` | `WS-01`..`WS-07` | CI/reporting boundary | Ready |
24
-
| `WS-09` Runtime Platform Integration (Agones) | `HND-001`, `HND-003`, `HND-301` (runtime gate ownership) | `WS-03`, `WS-04`, `WS-06`, `WS-07` | Kubernetes/Agones boundary | Discovery in progress |
24
+
| `WS-09` Runtime Platform Integration (Agones) | `HND-001`, `HND-003`, `HND-301` (runtime gate ownership) | `WS-03`, `WS-04`, `WS-06`, `WS-07` | Kubernetes/Agones boundary | Discovery brief drafted (`AGD-01`..`AGD-07` open) |
25
25
| `WS-10` ATProto Lexicon and Telemetry Alignment | `OBS-03`, `OBS-04`, `AC-403` | `WS-07`, `WS-08` | ATProto lexicon boundary | Deferred |
26
26
27
27
## Dependency Graph
···
76
76
77
77
- `WS-09` is the explicit point where Agones platform decisions are introduced.
78
78
- Agones discovery and gate-closure notes are tracked in [`/doc/agones.md`](/doc/agones.md).
79
+
80
+
## WS-09 Gate Checklist (Agones)
81
+
82
+
| Gate | Description | Status |
83
+
|---|---|---|
84
+
| `AGD-01` | Runtime unit selection (campaign-affine vs pooled vs hybrid) | Open |
85
+
| `AGD-02` | Primary control primitive (`Fleet`-first vs direct `GameServer`) | Open |
86
+
| `AGD-03` | Allocation interface (`GameServerAllocation` vs allocator service) | Open |
87
+
| `AGD-04` | State ownership boundary (stargones vs worker) | Open |
88
+
| `AGD-05` | Lifecycle mapping (`LIF-*` to runtime states/events) | Open |
89
+
| `AGD-06` | Recovery semantics for worker/runtime failures | Open |
90
+
| `AGD-07` | Operator/control-plane ownership model | Open |
79
91
80
92
## References
81
93