Skip to main content

​
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/sentinel/config.go. Full config example: 
sentinel_id = "${POD_NAME}"
workspace_id = "${UNKEY_WORKSPACE_ID}"
environment_id = "${UNKEY_ENVIRONMENT_ID}"
platform = "aws"
region = "us-east-1"
http_port = 8080

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

[clickhouse]
url = "${UNKEY_CLICKHOUSE_URL}"

[redis]
url = "${UNKEY_REDIS_URL}"

[gossip]
bind_addr = "0.0.0.0"
lan_port = 7946
wan_port = 7947
lan_seeds = ["sentinel-gossip.sentinel.svc.cluster.local:7946"]
secret_key = ""

[observability.tracing]
sample_rate = 0.25

[observability.logging]
sample_rate = 1.0
slow_threshold = "1s"

[observability.metrics]
prometheus_port = 9090

​
Field reference

​
sentinel_id
string
Identifies this sentinel instance in logs, traces, and ClickHouse records. Auto-generated if omitted.
​
workspace_id
string
required
Workspace this sentinel serves. Validation rejects empty values.
​
environment_id
string
required
Environment this sentinel serves. Sentinel validates that resolved deployments belong to this environment and returns 404 for mismatches.
​
platform
string
required
Underlying cloud platform identifier (for example, aws).
​
region
string
required
Geographic region identifier (for example, us-east-1). Used for instance selection (sentinel only routes to instances in the same region) and as a label on metrics and traces.
​
http_port
int
default:"8080"
TCP port the HTTP server binds to. Range: 1-65535. Krane-managed deployments set this to 8040.
​
database
object
required
MySQL configuration. Sentinel fails to start without a valid primary DSN.
​
clickhouse
object
ClickHouse analytics configuration. When omitted or when the URL is empty, sentinel uses a no-op analytics backend and no request telemetry is recorded.
​
redis
object
Redis configuration for rate limiting, usage limiting, and key caching. When omitted or when the URL is empty, the middleware engine is disabled and sentinel operates in pass-through mode (no policy evaluation).
​
gossip
object
Gossip-based distributed cache invalidation. When omitted, sentinel uses local-only caches and relies on TTL expiration for data freshness. With gossip enabled, peer sentinel nodes broadcast invalidation events for faster cache convergence.
​
observability
object
Tracing, logging, and metrics configuration.

​
Environment variable injection

Krane renders the TOML configuration at apply time and injects it via the UNKEY_CONFIG_DATA environment variable. Database credentials, Redis URLs, and ClickHouse URLs come from Kubernetes Secrets in the sentinel namespace, which Krane templates into the TOML.