Configuration reference
Configuration precedence is defaults, YAML passed with --config, KEYSTONE_GATEWAY_* environment variables, then serve flags. Convert a dotted YAML key to an environment variable by uppercasing it and replacing dots with underscores (for example KEYSTONE_GATEWAY_LEASES_DEFAULT_TTL_SECONDS). Every key also has a -- flag with dots replaced by hyphens. Unknown YAML keys are rejected. Restart to apply every configuration or license change; V1 has no reload.
Required means required in the stated deployment shape. Empty defaults require operator input.
| YAML key | Default | Required / valid values | Effect |
|---|---|---|---|
gateway_id | — | always; logical ID | Signed deployment identity |
api.https.enabled / api.http.enabled | false / false | exactly one true | Client transport |
api.https.listen, advertise_url | — | HTTPS; host:port, https:// URL | Bind and client address |
api.https.server_cert_file, server_key_file | — | HTTPS | Server TLS files |
api.https.client_ca_file, principal_mappings_file | — | HTTPS + mtls | Client trust and CN mapping |
api.http.listen, advertise_url | — | HTTP; host:port, http:// URL | Bind and client address |
api.http.allow_insecure_http | false | true for HTTP | Explicit plaintext acknowledgement |
api.http.bearer_credentials_file | — | HTTP + bearer | SHA-256 credential mappings |
api.auth.mode | — | none, bearer, mtls | Authentication policy |
api.auth.principal_id, api.auth.allowed_license_type, api.auth.operator | —, —, false | only none; type phocol or lmc_exporter | One shared perimeter-trust principal |
storage.directory, encryption_key_file | — | always | Encrypted durable state and 32-byte key |
storage.snapshot_directory | — | optional; compatibility only | Not consumed by V1 runtime; actual HA snapshots are under storage.directory/raft/snapshots |
storage.peer.replica_id, listen, target, reconcile_listen, reconcile_target | — | HA only | Other replica and two peer channels |
storage.peer.tls.cert_file, key_file, ca_file | — | HA only | Peer mTLS files |
license.file | — | always | Signed Gateway license |
ha.enabled | false | boolean | Two-node mode |
ha.replica_id | — | always; logical ID | This replica’s signed identity |
ha.bootstrap_expect | 1 | 1 standalone; 2 HA | Raft voter count |
ha.peer_loss_timeout_seconds | 5 | >0 | Delay before degraded-active |
ha.operator_recovery_enabled | false | boolean; reserved | Compatibility setting; no V1 operational effect |
leases.default_ttl_seconds | 120 | min ≤ default ≤ max | Requested default lease length |
leases.min_ttl_seconds, max_ttl_seconds | 30, 300 | >0 | Lease TTL bounds |
leases.max_clock_skew_seconds | 5 | ≥0 | HA leadership skew bound |
leases.expiry_sweep_seconds | 15 | >0 | Expired-record cleanup interval |
telemetry.enabled | false | boolean | Enables customer OTLP export |
telemetry.otlp_endpoint | — | enabled only; no userinfo, query, or fragment | Collector host/URL; use auth_headers for credentials |
telemetry.protocol | grpc | grpc, http/protobuf | OTLP transport |
telemetry.ca_file, auth_headers | empty | optional | Collector TLS trust and Name=Value secrets |
telemetry.export_timeout_seconds | 10 | enabled; >0 | Shutdown export bound |
reports.directory | — | always | Report directory configuration |
reports.retention_days | 90 | ≥0 | Report retention setting |
logging.level, logging.format | info, json | debug/info/warn/error; json/text | Structured log output |
reports.directory is a configuration input; V1’s report CLI writes to standard output and the Gateway does not currently create report files or expose a backup/restore CLI. storage.snapshot_directory is accepted for configuration compatibility but not used by V1 runtime; see backup and recovery. See examples, CLI flags, and security.
Principal and license-type cardinality
api.auth.allowed_license_type is a scalar used only by the single fixed principal in api.auth.mode: none; it accepts phocol or lmc_exporter, not a list. In mtls and bearer modes, leave all three fixed-principal fields empty and define callers in api.https.principal_mappings_file or api.http.bearer_credentials_file instead. Each mapping entry still authorizes exactly one license type. Add separate entries and principal IDs to authorize installations for both types.
Mapping files must contain at least one entry and must not exceed 1 MiB in total; there is no separate maximum number of entries. Common Names and bearer hashes must be unique. Reusing a principal_id is accepted only when every occurrence has identical authority. Each mapped license type must be declared by the verified Gateway license or startup fails. See client authentication for complete multi-principal examples.