Phase9

docs/operations/game-node.md

@@ -0,0 +1,63 @@
+# Game node operations
+
+Game nodes run Docker workloads for Minecraft servers and connect to the control plane through the node-agent.
+
+## Capacity
+
+Each node exposes:
+
+- `maxServers`, `maxRamMb`, `platformRamMb`
+- Host port pool: `portRangeStart`–`portRangeEnd` (default `25565`–`25664`)
+
+The scheduler places new servers on the least-loaded eligible node.
+
+## Enrollment
+
+1. Create a `GameNode` row in the control plane database.
+2. Generate an enrollment token and distribute it securely to the node host.
+3. Start `node-agent` with matching `NODE_ID` and `NODE_TOKEN`.
+4. Confirm node status becomes `ONLINE` in the admin API.
+
+## Port allocation
+
+Host ports are unique per node (`@@unique([nodeId, hostPort])`). Do not manually assign ports outside the configured range.
+
+## Draining
+
+Before maintenance:
+
+1. Set node status to `DRAINING` via admin API.
+2. Wait for running servers to stop or migrate.
+3. Perform maintenance.
+4. Return node to `ONLINE` or decommission.
+
+## Firewall
+
+Allow:
+
+- Outbound WebSocket to control plane API
+- Inbound TCP on allocated Minecraft host port range
+- Docker bridge traffic locally
+
+Deny:
+
+- Public access to Docker API
+- Unrestricted inbound on management ports
+
+## Ansible
+
+Bootstrap with:
+
+```bash
+ansible-playbook -i inventories/production deploy/ansible/game-node.yml
+```
+
+Copy the `hgc-node-agent` binary to `/usr/local/bin/hgc-node-agent` and provide TLS materials via `NODE_TLS_CERT` / `NODE_TLS_KEY` or CA enrollment.
+
+## Failure scenarios
+
+| Scenario | Action |
+|----------|--------|
+| Node offline | Servers marked `UNKNOWN`; reschedule starts when node returns |
+| Port exhaustion | Provisioning fails with `NO_NODE_AVAILABLE`; add node or expand port range |
+| Disk full | Stop new provisions; prune unused images; expand volume |