Variables and Secrets

📍 Where to find this in the UI

• Variables expected by a service: Infra → Architecture tab → Services → the relevant ServiceDefinition
• Configuration of an environment: Infra → Environments → {env} → Configuration
• Service ↔ configuration binding: Infra → Environments → {env} → Services → the ServiceInstance

The config consumed by a service (DB URL, JWT secret, external API key, log level…) flows through three levels in Wakastart: declaration on the architecture side, configuration on the environment side, then binding in each ServiceInstance.

1. Architecture: declare what the service expects

When you create a ServiceDefinition, you list the variables your service consumes:

textCopy
ServiceDefinition "backend"
├── requires JWT_SECRET
├── requires DATABASE_URL
├── requires S3_BUCKET
└── requires LOG_LEVEL

Only variables declared here can be bound in environments. If your service needs a new piece of config, you must first declare it in the architecture.

2. Configuration of an environment

The Configuration of an environment is the inventory of values available in that env, from which your services can draw. It is shared across all services in the environment.

Where Configuration entries come from

Secret vs non-secret

Each configuration entry can be marked secret or not:

A secret is stored encrypted in the Wakastart vault. Once created, its value can no longer be viewed in the UI — only your services' pods can read it at startup.

3. Binding: connecting a service to the Configuration

For each ServiceInstance, you create a binding between a variable expected by the service (declared in its ServiceDefinition) and an entry in the env's Configuration.

textCopy
ServiceInstance "backend" in prod env
├── JWT_SECRET     ──bind──>  Configuration entry "jwt-secret" (user secret)
├── DATABASE_URL   ──bind──>  Configuration entry "primary-db-url" (auto, DatabaseInstance)
├── S3_BUCKET      ──bind──>  Configuration entry "medias-bucket" (auto, StorageBucketInstance)
└── LOG_LEVEL      ──bind──>  Configuration entry "log-level" (user)

At pod startup, each env var receives the value of the bound entry.

Pooling: one value, multiple services

If several services need the same value (e.g. STRIPE_API_KEY used by backend and worker), don't create two identical entries. Create a single entry in the env's Configuration and bind it in each ServiceInstance that needs it.

Benefits:

• A single source of truth — no drift between services
• Atomic update — changing the value means changing it in one place; all affected services pick it up on the next restart
• No duplication in secrets — a secret is stored once, not N times

Platform variables are dynamic

Entries generated by the platform or by the environment (DB URL, internal service URL, public hostname of another service in the app, S3 credentials…) are dynamic: if the underlying resource changes (the DB is migrated to a new hostname, a service is renamed, an S3 secret is rotated…), the entry's value follows automatically.

→ You never break a binding by evolving your infrastructure. Restarted services pick up the new values.