Operations

Orchestrator Configuration


Orchestrator Environment Variables

The orchestrator is one process that serves both the gRPC API and the REST API, so there is a single set of settings.

VariableDefaultDescription
DATABASE_URL(required)PostgreSQL connection string
GRPC_BIND_ADDR127.0.0.1:50051gRPC listener (SDKs, workers, CLI); also --grpc-addr. The Docker image uses 0.0.0.0:50051
HTTP_BIND_ADDR127.0.0.1:8080HTTP listener: REST API under /api/v1, /health, /health/ready, /health/live, /metrics; also --http-addr. The Docker image uses 0.0.0.0:8080
ORCHER_ORCHESTRATOR_CONFIG—Path to the TOML config file; also --config
ORCHER_INSECUREfalseAllow listening on a non-loopback address without authentication; also --insecure
LOG_LEVELinfoLog level: trace, debug, info, warn, error
LOG_FORMATprettyLog format: json, pretty

Authentication

REST and gRPC share one authentication layer, configured in the [security] section of the TOML config:

1
[security]
2
auth_mode = "api-key" # none | api-key | oidc | mtls | api-key-and-mtls
3
tenancy = "single" # single | multi
4
5
# Only for auth_mode = "oidc"
6
# [security.oidc]
7
# issuer = "https://auth.example.com"
8
# audience = "orcher"
9
# organization_claim = "org_id"
10
# scopes_claim = "scope"
  • Without authentication, the orchestrator refuses to listen on a non-loopback gRPC or HTTP address unless you pass --insecure or set ORCHER_INSECURE=true.
  • When auth_mode requires a client certificate (mtls or api-key-and-mtls), the orchestrator serves no REST API.
  • Create the first API key with orchestrator api-key create --name admin --scope '*'; it prints the key once on stdout. After that, manage keys with orcher api-key create|list|get|revoke or the /api/v1/api-keys endpoints (scope api-keys:manage).

Database Connection

PostgreSQL is the exclusive backend. For production, use PgBouncer for connection multiplexing:

1
# Direct connection
2
DATABASE_URL=postgresql://orcher:orcher@localhost:5432/orcher
3
4
# Via PgBouncer (recommended for production)
5
DATABASE_URL=postgresql://orcher:orcher@localhost:6432/orcher

The orchestrator uses a pool of up to 80 connections with a statement cache of 256 prepared statements.


Next Steps