Configuration

Configuration model

Unkey services read configuration from a TOML file passed at startup. Environment variables can be referenced with ${VAR} and are expanded before parsing. Defaults and validation run after parsing. The config schema maps to svc/frontline/config.go. Minimal config example:

http_port = 7070
https_port = 7443
platform = "aws"
region = "${UNKEY_REGION}.aws"
instance_id = "${POD_NAME}"
apex_domain = "${UNKEY_APEX_DOMAIN}"
max_hops = 10
prometheus_port = 9090

[control]
url = "${UNKEY_CONTROL_URL}"
token = "${UNKEY_CONTROL_TOKEN}"

[database]
primary = "${UNKEY_DATABASE_PRIMARY}"
readonly_replica = "${UNKEY_DATABASE_REPLICA}"

[vault]
url = "${UNKEY_VAULT_URL}"
token = "${UNKEY_VAULT_TOKEN}"

string

Instance identifier for logs and tracing.

int

default:"7070"

Plain-HTTP listener port. Serves ACME HTTP-01 challenges and 308-redirects everything else to https://.

int

default:"7443"

HTTPS listener port. Terminates TLS, runs the policy engine, and forwards customer traffic to a deployment instance (or to a peer frontline in another region).

string

required

Cloud provider identifier (for example, aws, gcp, or local).

string

required

Region label for routing.

string

default:"unkey.cloud"

Apex domain for regional routing.

int

default:"10"

Maximum number of routing hops.

object

required

Control API connection settings.

Show Fields

string

required

Control API address.

string

required

Preshared bearer token for authenticated Control API requests.

int

Prometheus metrics port. Set to 0 to disable.

duration

default:"15m"

Maximum duration for a proxied request before the context is cancelled and a 504 is returned.

object

TLS settings for HTTPS.

Show Fields

bool

Disable TLS when true.

string

Path to TLS certificate.

string

Path to TLS key.

object

MySQL configuration.

Show Fields

string

required

Primary DSN.

string

Optional read replica DSN.

object

ClickHouse analytics storage for request-level events. When the URL is empty, a no-op backend is used and no request telemetry is recorded.

Show Fields

string

ClickHouse connection string.

int

default:"5000"

Maximum number of items to collect before flushing a buffer to ClickHouse. Applies to all event buffers (frontline requests, key verifications).

int

default:"10000"

Capacity of the channel buffer holding incoming items. When full, new items are dropped.

int

default:"1"

Number of goroutines that drain each buffer.

object

Redis connection for distributed rate limiting and usage limiting in the policy engine. When the URL is empty, an in-memory counter is used as a fallback and rate limits are not shared across replicas.

Show Fields

string

Redis connection string.

object

Vault connection.

Show Fields

string

Vault URL.

string

Vault token.

object

Tracing and logging configuration.

Show Fields

float

default:"0.25"

Trace sampling rate.

float

default:"1.0"

Log sampling rate.

duration

default:"1s"

Slow log threshold.

object

Go pprof profiling endpoints on a loopback-only listener. Disabled when omitted or when credentials are empty.

Show Fields

string

Basic Auth username for the pprof endpoints.

string

Basic Auth password for the pprof endpoints.

int

default:"6060"

TCP port for the loopback-only (127.0.0.1) pprof server.

Environment variables

The Helm chart provides these variables for the default config template:

env

required

Region label.

env

Apex domain for routing.

env

required

Control API address.

env

required

Preshared bearer token for authenticated Control API requests.

env

Vault URL.

env

Vault token.

env

required

MySQL primary DSN.

env

MySQL read replica DSN.

env

ClickHouse connection string for request telemetry. Optional.

env

Redis connection string for distributed rate limiting. Optional.

Example configuration

http_port = 7070
https_port = 7443
platform = "aws"
region = "${UNKEY_REGION}.aws"
instance_id = "${POD_NAME}"
apex_domain = "${UNKEY_APEX_DOMAIN}"
max_hops = 10
prometheus_port = 9090
request_timeout = "15m"

[control]
url = "${UNKEY_CONTROL_URL}"
token = "${UNKEY_CONTROL_TOKEN}"

[database]
primary = "${UNKEY_DATABASE_PRIMARY}"
readonly_replica = "${UNKEY_DATABASE_REPLICA}"

[clickhouse]
url = "${UNKEY_CLICKHOUSE_URL}"

[redis]
url = "${UNKEY_REDIS_URL}"

[vault]
url = "${UNKEY_VAULT_URL}"
token = "${UNKEY_VAULT_TOKEN}"

[observability.tracing]
sample_rate = 0.1

[observability.logging]
sample_rate = 0.01
slow_threshold = "2s"

Overview

Overview

Services

RFCs

Configuration model

Environment variables

Example configuration

​Configuration model

​Environment variables

​Example configuration

​Related docs

Configuration model

Environment variables

Example configuration

Related docs