Files

7.7 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):

  1. Set image repository, pull secret, runtime secret, TLS secret, and actual hosts.
  2. Set networkPolicy.databaseCIDRs and identityCIDRs to 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.
  3. Adjust requests/limits after measuring on cluster hardware. Defaults are initial allocations, not a capacity guarantee.
  4. Render and inspect with helm lint and helm 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.

The publish job inherits Docker access from the runner configuration and checks docker version before setting up Buildx. The runner must provide a usable socket or Docker context/environment inside the job container, not just inside the runner pod. The replacement DinD daemon listens on port 2376 and a Unix socket; the previous tcp://docker-host:2375 workflow override does not apply. For TCP, provide the reachable endpoint and required TLS client certificates through the runner configuration. A successful service-container job proves the runner can reach Docker, but does not prove that the publish job can. Check the connection step's output before diagnosing Buildx or registry credentials.

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.