Build config service for guild-to-pod assignments

[vcarl]

Context

Part of load balancer architecture work (see PR #228 for full analysis).

Risk: Medium-High | Reward: High | Code Changes: Required (new service)

Description

Build a new service that manages guild-to-pod assignments. This service tracks which gateway pod handles which guilds and provides an API for routing decisions.

Architecture

HTTP Pods → Config Service → PostgreSQL
                ↓
           Gateway Pods (query for their assigned guilds)

Service Discovery

Use Kubernetes DNS (not hardcoded URLs):

• Config service: config-service.default.svc.cluster.local:3001
• Short name within namespace: config-service:3001

API Endpoints

GET  /health                    - Health check
GET  /guild/:guildId/pod        - Which pod handles this guild?
POST /guild/:guildId/assign     - Assign guild to pod
GET  /pod/:podName/guilds       - List guilds for a pod
POST /rebalance                 - Trigger guild rebalancing

Tasks

• Create apps/config-service/ directory structure
• Implement PostgreSQL connection using same patterns as main app
• Implement guild assignment logic (least-loaded pod)
• Implement health endpoint
• Implement guild lookup endpoint
• Implement pod guilds list endpoint
• Create Dockerfile.config for separate image
• Add GitHub Actions workflow to publish to ghcr
• Deploy to staging with PostgreSQL (Deploy PostgreSQL StatefulSet for config service #231)
• Test guild assignment and lookup

Dependencies

• Deploy PostgreSQL StatefulSet for config service #231 (PostgreSQL StatefulSet)

References

• PR Architecture analysis: Load balancing with SQLite constraint #228 (architecture analysis)
• cluster/proposed/config-service.yaml

[vcarl]

Closing - decided to use deterministic sharding instead of a bespoke config service.

Why Deterministic Sharding?

• No config service or PostgreSQL needed for routing
• Simpler architecture, fewer moving parts
• Guild → pod assignment is calculated: hash(guildId) % numPods
• HTTP service calculates routing directly
• Gateway pods filter based on their shard

Trade-offs Accepted

• Scaling requires pod coordination (not dynamic rebalancing)
• All pods recalculate on replica count change
• Acceptable for our scale (<1000 guilds)

See #234 and #235 for updated implementation approach.