Control-plane configuration
Configure public URLs, persistence, database access, network paths, and retention.
Control-plane configuration defines the installation's network identity, persistent state, database, and operational storage. Use the environment template from the pinned release bundle.
Configuration precedence
Deployment environment values override the bundle's defaults. Organization and project settings control resource policy inside the installation and cannot override the deployment's database or encryption paths.
Invalid required configuration prevents the affected service from starting. An invalid public URL or inaccessible state path is reported in startup health; Infra does not silently select a replacement production value.
Deployment settings
The complete environment reference covers all server, worker, agent, Connector, secret-provider, notification, and retention variables. The deployment values in this table are the settings most installations configure first.
| Variable | Type | Default | Behavior |
|---|---|---|---|
INFRA_PUBLIC_URL | HTTPS origin | Required | External console and API origin; no path suffix |
INFRA_DATABASE_URL | PostgreSQL connection string | Bundled database in the bundle template | External deployments must set a reachable database |
INFRA_STATE_DIR | Absolute path | /var/lib/infra in the service container | Stores installation identity and protected local state |
INFRA_ENCRYPTION_KEY_FILE | Absolute file path | /run/secrets/infra-encryption-key | Required persistent encryption material |
INFRA_METRICS_DIR | Absolute path | /var/lib/infra/metrics | Persistent local observation storage when selected |
INFRA_LOGS_DIR | Absolute path | /var/lib/infra/logs | Persistent local journal and log storage when selected |
INFRA_TRUST_PROXY | Boolean | false | Trusts forwarded identity headers only when enabled |
INFRA_SHUTDOWN_TIMEOUT_SECONDS | Integer seconds | 120 | Inclusive range 10–3600; waits for safe worker shutdown |
Boolean values accept true or false; other strings are rejected. Secrets
should use the deployment's secret-injection facility rather than being committed
to environment templates.
Public URL and proxy
The public URL must match the origin used by operators, SSO, and API clients. A reverse proxy must support long-lived console and journal connections and preserve the intended request origin.
Enable trusted proxy headers only when the proxy replaces untrusted incoming forwarded headers and direct access to the application listener is restricted. Otherwise clients can supply misleading source or protocol information.
Changing the public URL requires updating DNS, TLS, SSO callback configuration, CLI contexts, agents, and integrations that store that origin. Review active operations before changing connectivity.
Network connections
Configure access for these control-plane and infrastructure paths:
| Path | Requirement |
|---|---|
| Clients → edge | HTTPS on the configured public listener |
| Edge → application | Private application listener from the deployment bundle |
| Control plane ↔ nodes | Agent HTTPS and authenticated stream endpoints configured at enrollment |
| Nodes ↔ nodes | Region mesh and storage transports |
| Control plane → PostgreSQL | Database TLS and authentication according to deployment policy |
| Backup workers → destination | Destination API and required object paths |
| Connector → hosted service | Outbound HTTPS with the configured trust chain |
The enrollment configuration declares node endpoint ports; they must agree with host firewalls and routing. Do not open all node ports to the internet. Separate management, mesh, and storage paths when the deployment requires independent capacity or isolation.
Persistence
Persist the database, encryption material, installation identity, observation storage, and object-storage references. Node agent state is separate and must remain unique to its host. A replica without the same installation configuration must not create its own encryption identity.
See Control-plane backup for backup boundaries.
Retention
Installation settings → Retention controls raw metrics, aggregated metrics, logs, operation history, and audit records separately. Each setting specifies its unit and accepted range in the form. A value of zero is rejected rather than interpreted as unlimited retention.
Reducing retention changes future cleanup eligibility. Cleanup does not guarantee an immediate drop in filesystem usage, and external archives follow their own policy. Review governance requirements before shortening operational history.
Apply changes
Deployment configuration changes require a controlled service restart. Drain workers according to Upgrades, validate startup health, and compare configured and observed values. Project settings can apply asynchronously and show their operation result in the console.