Skip to main content

Documentation Index

Fetch the complete documentation index at: https://engineering.unkey.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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
region = "${UNKEY_REGION}.aws"
instance_id = "${POD_NAME}"
apex_domain = "${UNKEY_APEX_DOMAIN}"
max_hops = 10
ctrl_addr = "${UNKEY_CTRL_ADDR}"
prometheus_port = 9090

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

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

[gossip]
bind_addr = "0.0.0.0"
lan_port = 7946
wan_port = 7947
secret_key = "${UNKEY_GOSSIP_SECRET_KEY}"
​
instance_id
string
Instance identifier for logs and tracing.
​
http_port
int
default:"7070"
Plain-HTTP listener port. Serves ACME HTTP-01 challenges and 308-redirects everything else to https://.
​
https_port
int
default:"7443"
HTTPS listener port. Terminates TLS and forwards customer traffic to the sentinel.
​
region
string
required
Region label for routing.
​
apex_domain
string
default:"unkey.cloud"
Apex domain for regional routing.
​
max_hops
int
default:"10"
Maximum number of routing hops.
​
ctrl_addr
string
default:"localhost:8080"
Control API address.
​
prometheus_port
int
Prometheus metrics port. Set to 0 to disable.
​
tls
object
TLS settings for HTTPS.
​
database
object
MySQL configuration.
​
vault
object
Vault connection.
​
gossip
object
Gossip-based cache invalidation.
​
observability
object
Tracing and logging configuration.

​
Environment variables

The Helm chart provides these variables for the default config template:
​
UNKEY_REGION
env
required
Region label.
​
UNKEY_APEX_DOMAIN
env
Apex domain for routing.
​
UNKEY_CTRL_ADDR
env
Control API address.
​
UNKEY_VAULT_URL
env
Vault URL.
​
UNKEY_VAULT_TOKEN
env
Vault token.
​
UNKEY_DATABASE_PRIMARY
env
required
MySQL primary DSN.
​
UNKEY_DATABASE_REPLICA
env
MySQL read replica DSN.
​
UNKEY_GOSSIP_SECRET_KEY
env
required
Gossip secret key.

​
Example configuration

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

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

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

[gossip]
bind_addr = "0.0.0.0"
lan_port = 7946
wan_port = 7947
secret_key = "${UNKEY_GOSSIP_SECRET_KEY}"

[observability.tracing]
sample_rate = 0.1

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