7.0 KiB
Kubernetes and Gitea deployment
The chart and workflow are provided for configuration and cluster validation. No image has been published, no GitOps repository has been modified, and no cluster resources have been applied by this implementation session.
Runtime prerequisites
- PostgreSQL database shared by all worlds, with verified TLS. The runtime needs table/index creation for initial bootstrap, then reads and writes in its own database. A separate migration job and reduced DDL privileges are follow-up work.
- An OIDC provider/client with exact callbacks for each world:
https://<world-host>/auth/callback. Use one client accepting these registered callbacks or extend the chart to use per-world credentials. Never use wildcards. - Harbor registry project and a pull-only robot credential for Kubernetes.
- An ingress controller that supports WebSocket upgrades and preserves Host, certificates covering all world hosts, working DNS, and NetworkPolicy enforcement.
- ArgoCD with read access to the application and GitOps repositories.
Create the runtime secret through your existing secret manager (e.g. External
Secrets or sealed secrets). Do not put actual secret values into this repository.
The named secret aeternalis-runtime must contain:
| Key | Value |
|---|---|
DATABASE_URL |
postgres://user:password@db.example/db?sslmode=verify-full |
OIDC_ISSUER |
Exact HTTPS issuer URL |
OIDC_CLIENT_ID |
Registered client ID |
OIDC_CLIENT_SECRET |
Client secret, if required by your provider |
Certificates from the image's system CA bundle are trusted. Mount a custom CA and configure the PostgreSQL/HTTPS clients if your infrastructure uses a private CA; that mounting is site-specific and not included in the sample chart.
Configure deploy/chart/values.yaml (prefer an external GitOps values file):
- Set image repository, pull secret, runtime secret, TLS secret, and actual hosts.
- Set
networkPolicy.databaseCIDRsandidentityCIDRsto the actual permitted destinations. Empty lists deny these connections, so the server will not start until the allowlists match. Adjust DNS rules for NodeLocal DNSCache if used. - Adjust requests/limits after measuring on cluster hardware. Defaults are initial allocations, not a capacity guarantee.
- Render and inspect with
helm lintandhelm template; validate against the target cluster version using your normal dry-run pipeline.
Keycloak administrator access
Create the exact realm role aeternalis-admin and assign it to your user.
The configured override is OIDC_ADMIN_ROLE (control.adminRole in Helm values);
the SRS deployment already uses aeternalis-admin.
The app checks the verified ID token for either
realm_access.roles or resource_access[OIDC_CLIENT_ID].roles. An access-token-only
role or a role belonging to a different client does not grant access.
For the realm-role approach, configure a User Realm Role mapper on the client's
dedicated scope with token claim realm_access.roles, no role prefix, type
String, Multivalued enabled, and Add to ID token enabled. If client role scope
is restricted, include aeternalis-admin in that scope. The SRS client is
aeternalis-web. Use Keycloak's token evaluation to check the ID token contains:
{"realm_access":{"roles":["aeternalis-admin"]}}
Sign out of the game and sign back in at /control after assigning the role.
Existing game sessions do not gain admin privileges automatically. The admin
grant lasts ten minutes; sign in again from Control to renew it. Production
continues to require verified OIDC; DEV_ADMIN is restricted to loopback development.
See Keycloak role token mappings.
Gitea setup
Enable Actions in the repository. Use a runner with the ubuntu-latest label,
Node/Go setup support, service-container networking, and Docker build capability.
The publication runner should be trusted; do not expose a privileged Docker socket
to untrusted pull-request jobs. The verify job has no deployment credentials.
Action references use upstream version tags; mirror/pin these to reviewed commits
under your organization's supply-chain policy before production use.
Set repository variables:
| Variable | Example |
|---|---|
HARBOR_HOST |
harbor.your-domain (no scheme) |
HARBOR_PROJECT |
games |
GITOPS_REPOSITORY |
https://gitea.your-domain/infra/gitops.git |
GITOPS_BRANCH |
main |
GITOPS_VALUES_FILE |
apps/aeternalis/values.yaml |
Set repository secrets HARBOR_USERNAME, HARBOR_PASSWORD, GITOPS_USERNAME,
and GITOPS_TOKEN. Use a Harbor project-scoped push robot and a token restricted
to the intended GitOps repository. An empty GITOPS_REPOSITORY skips promotion.
Harbor publication still requires its own variables/secrets.
On a push to master or main, CI verifies generated contracts, TypeScript,
production client build, Go tests with the race detector, real PostgreSQL storage
integration, browser tests, Go vet, and Helm rendering. It builds/publishes an image
tagged with the commit SHA, then updates the GitOps values to the image's immutable
digest. ArgoCD reconciles that change. No kubeconfig is handed to CI.
Copy and configure deploy/argocd-application.example.yaml. It uses ArgoCD's
multiple-source Application support: chart from the app repository, values from
the GitOps repository. Pruning is disabled in the example to avoid silently
deleting worlds when editing the list. Monitor promotion failures; concurrent
GitOps commits are rejected by a normal non-force push and must be retried.
Add worlds and retire seasons
Each world gets a distinct Deployment, Service, hostname, ID, seed, and database
row. replicas: 1 and Recreate are intentional. An expiring DB lease also fences
duplicate processes. Increasing replicas does not increase one world's capacity.
To add capacity, append a world entry with a never-used ID and fresh seed, register its OIDC callback and DNS/TLS, and sync ArgoCD. Open destination worlds before the current cohort wins; five worlds launched together have the same deadline. The world directory is supplied to every client, and passages are visible to the same account after signing into a destination.
Retire a finished world's workload only after confirming its persisted outcome and passages. Keep its database row and passage history. Never reuse its ID: restarted IDs restore their old state. Rolling the code back does not roll the database back. Balance/seed changes do not mutate a running saved world's rules.
Before public access
Run a real OIDC login and cross-host survivor transfer, restart/kill a pod during combat and victory, simulate database failure, validate NetworkPolicy and TLS, and test peak boss crowding. Add observability and alerting, versioned migrations, durable event recording, abuse controls, account-level cap policy if chosen, and an operational backup/restore procedure. The current prototype is suitable for controlled development playtests after deployment validation.