Operations runbook — Configuration management

How env vars, ConfigMaps, and Secrets flow through the AlphaSwarm stack.

The single source of truth

alphaswarm_platform/deployments/compose/.env.schema is the source of truth. Every variable declared anywhere (compose, K8s ConfigMap, K8s Secret, application code, frontend) MUST appear in the schema.

Each entry carries metadata:

key:            ALPHASWARM_FOO_BAR
description:    What this knob controls.
required:       true | false
default:        <value or empty>
targets:        local,kubernetes,cloud
classification: plain | secret | rotation-required

Generation

alphaswarm_platform has no root Makefile; drive the generator script directly:

# Local dev (.env file)
python alphaswarm_platform/build/scripts/generate_config.py --env local --out alphaswarm_platform/deployments/compose/.env.local

# Cloud / sealed-secrets seed
python alphaswarm_platform/build/scripts/generate_config.py --env cloud

# Kubernetes ConfigMap + Secret scaffold
python alphaswarm_platform/build/scripts/generate_config.py --env k8s --kind configmap
python alphaswarm_platform/build/scripts/generate_config.py --env k8s --kind secret

Validation

Pass --diff to run the generator in check mode against a target — produces no output when files are in sync with the schema; prints a unified diff when they've drifted:

python alphaswarm_platform/build/scripts/generate_config.py --env local --diff

How env reaches a service

Adding a new variable

1. Add a block to .env.schema:

   key:            ALPHASWARM_MY_NEW_KNOB
   description:    What it does (one line).
   required:       false
   default:        <safe value or empty>
   targets:        local,kubernetes,cloud
   classification: plain

2. Regenerate every artifact:

   python alphaswarm_platform/build/scripts/generate_config.py --env local
   python alphaswarm_platform/build/scripts/generate_config.py --env k8s --kind configmap
   python alphaswarm_platform/build/scripts/generate_config.py --env k8s --kind secret

3. Add the field to Settings in the alphaswarm_config sibling package (alphaswarm_config/src/alphaswarm_config/engine/settings.py — alphaswarm.config is now a backward-compatible shim over it) so the application can still read it via from alphaswarm.config import settings.

4. Update tests that snapshot the env to include the new key.

Secret classification rules

Class	Examples	Storage
plain	ALPHASWARM_LOG_LEVEL, ALPHASWARM_CORE_API_URL	ConfigMap
secret	ALPHASWARM_DATABASE_PASSWORD, ALPHASWARM_AUTH_SCIM_BEARER_TOKEN_HASH	Secret + sealed-secrets / external-secrets-operator
rotation-required	ALPHASWARM_AUTH_M2M_CLIENT_SECRET, ALPHASWARM_SESSION_COOKIE_SECRET	Secret + rotation cadence in rotate-secrets.md

Never

• Never commit a populated Secret to git. The generator writes a Y2hhbmdlbWU= placeholder; CI/CD or the external secret operator patches the real values.
• Never read os.environ.get(...) directly from alphaswarm/ business code. Use from alphaswarm.config import settings.
• Never hardcode a URL or password. Add it to the schema and route through settings.