Configuration Reference

Generated by make docs-sync from tools/gendocs/config. Source of truth is the koanf:"..." struct tags + doc comments in internal/config/*.go. Do not edit by hand — make docs-sync re-runs the generator and git diff will catch drift.

Defaults are seeded by internal/config/config.go::defaultConfig() (and the per-section applyXxxDefaults helpers). The reference below names the type + the doc comment; the runtime default is in the seed.

Top-level structure

The root config is a single YAML document. The Config struct (internal/config/config.go) lists every top-level section; each section has its own struct in the same package.

Sections covered below:

• server
• logging
• storage
• health
• nats
• agent
• security
• identity
• secrets
• events
• cluster
• gitops
• webhook
• metrics
• tracing
• profiling
• blueprints

server

ServerConfig configures the HTTP and gRPC listeners.

server.cors

CORSConfig configures the HTTP CORS middleware. CORS lives outside the auth chain so OPTIONS preflight returns 204 before rate-limit is consulted (PROJECT-DETAILS §4.4 acceptance criterion).

server.tls

TLSConfig configures TLS termination for the listeners. Three modes: - Enabled=false: plain TCP. Insecure; only appropriate for dev loopback or behind a TLS-terminating ingress. - Enabled=true + CertFile/KeyFile both set: file-sourced cert/key. Conventional production setup with externally-provisioned PKI. - Enabled=true + CertFile/KeyFile both empty: identity-provider sourced. The embedded provider (Epic 09) issues a server SVID for spiffe://<td>/server/control-plane and refreshes it on each signing-CA rotation. Requires Identity.Enabled=true. Both modes enforce TLS 1.3 minimum + mTLS request semantics (ClientAuth = tls.VerifyClientCertIfGiven so API-key clients can still authenticate over TLS without a peer cert).

logging

LoggingConfig configures the structured logger.

storage

StorageConfig configures the persistence backend.

health

HealthConfig configures the kscore-server liveness/readiness surface. PROJECT-DETAILS §4.4: /health/ready respects a startup grace period to avoid false-not-ready signals during boot.

nats

NATSConfig configures the v1.0 NATS transport. Endpoints (Task 2/3) supersedes URLs for richer config (priority, weight, tags). Both are accepted for ergonomics: simple deployments list URLs; HA deployments use Endpoints. They are mutually exclusive in external mode — populating both is rejected at Validate.

nats.bootstrap

BootstrapConfig governs the v1.0 server-side bootstrap registration handler (Epic 05 task 9). Defaults to disabled — operators opt in by setting Enabled=true and populating PSKs. A “default on with no PSKs” stance would be a footgun (looks permissive, actually rejects everything); explicit opt-in surfaces the dependency. PSKs are config-listed in v1.0; consumed PSKs are tracked in- memory so a server restart wipes the consumption record. Operators are expected to rotate PSKs (issue fresh ones per agent, don’t reuse). v1.x will persist consumption in the state DB and add an API endpoint to issue PSKs.

nats.bootstrap.psks

BootstrapPSK describes one operator-issued bootstrap credential. Secret is hex-encoded so config files stay copy-pasteable; the validator hex-decodes once at construction. ExpiresAt is the hard cutoff after which Validate rejects the PSK.

nats.circuitbreaker

CircuitBreakerConfig configures the per-endpoint circuit breaker (Epic 05 task 7). State machine: closed → open → half-open → closed. PROJECT-DETAILS §4.2. v1.0 wiring: each endpoint owns one breaker. ConnectionManager drives transitions via the disconnect/reconnect callbacks already in place from task 2; Health degrades to error when every endpoint is OPEN. Active dial-time eviction (skipping OPEN endpoints when nats.go picks the next reconnect target) is deferred to v0.x — it requires replacing nats.go’s native multi-URL failover with a per-endpoint dial loop, which is a substantial refactor for marginal v1.0 benefit.

nats.dedup

DedupConfig configures producer-side message dedup (Epic 05 task 6). Defaults follow PROJECT-DETAILS §4.2: 5m window, large but bounded entry cap. Per-subject overrides let operators shrink the window for low-RTT subjects (heartbeats) or enlarge it for high- retry ones.

nats.dedup.persubjectoverrides

SubjectOverride applies a non-default WindowDuration to subjects matching Prefix (longest prefix wins; equality counts as a prefix match).

nats.embedded

EmbeddedNATSConfig configures the in-process nats-server/v2 instance started when Mode == NATSModeEmbedded. JetStream is gated by JetStreamConfig.Enabled — there is no separate embedded toggle so the two flags can never disagree.

nats.endpoints

EndpointConfig is the structured form of a single NATS endpoint consumed by ConnectionManager. Priority orders the connect-attempt list (higher first). Weight is reserved for post-v1.0 load distribution and ignored today. Tags are operator labels passed through to EndpointSnapshot for observability.

nats.jetstream

JetStreamConfig governs JetStream enablement and per-stream defaults. v1.0 streams (commands + events) inherit StreamMaxAge, StreamMaxBytes, StreamMaxMsgs, and StreamReplicas; per-stream overrides are reserved for v1.x. Enabled is the single switch — when true, the embedded server (if running) starts with JetStream and Manager auto-creates the commands/events streams. When false, no streams are touched and the embedded server runs without JetStream.

agent

AgentConfig governs the kscore-agent daemon (Epic 06). Loaded from the same config file as the server’s sections (per PROJECT-DETAILS §4.6, agent’s config file lists agent.* alongside nats.* and security.*); the kscore-server binary ignores this section. AgentID is generally set by Task 6’s bootstrap engine and persisted to disk; for v1.0’s pre-bootstrap world it must be supplied via config. ClusterName is shared with the rest of the system via NATSConfig.ClusterName — the agent reads it from there.

security

SecurityConfig governs the agent-side SecurityEnforcer (Epic 06 task 4/5) and the control-plane-side command signer. Both binaries read the same security.* section so the HMAC secret, default policy, and command/principal rules stay in lockstep. HMACSecret is hex-encoded so config files stay copy-pasteable; the binary decodes once at startup. Empty HMACSecret disables the HMAC check (escape hatch for fresh agents pre-bootstrap; v1.x can require non-empty when bootstrap-derived keys land). PROJECT-DETAILS §4.6 lists security.{authorization, command_filter} as the agent’s top-level security keys; v1.0 flattens them into the fields below.

identity

IdentityConfig drives the embedded identity provider boot in kscore-server (Epic 09 task 12). All fields have v0.1 defaults that work for a single-server dev / external-tester install; production multi-CP deployments override TrustDomain + StoragePath.

secrets

SecretsConfig drives the Epic 10 secrets boot in kscore-server. The shape mirrors PROJECT-DETAILS §4.11’s YAML example exactly: secrets: enabled: true default_backend: file backends: - name: file type: encrypted_file file: { path: /var/lib/keystone/secrets.bin, master_key: env:KSCORE_SECRETS_MASTER } - name: vault type: vault vault: { address: https://vault.internal , auth_method: approle, … } routing: - prefix: secret/ backend: vault - prefix: kv/ backend: file cache: { enabled: true, max_entries: 10000, default_ttl: 5m } lease: { poll_interval: 30s, jitter: 0.1, default_strategy: lazy } Enabled defaults to false — operators opt in. A stock kscore-server without secrets.enabled: true runs the rest of the stack unchanged; the gRPC SecretsService returns codes.Unavailable + REST returns 503 when called.

secrets.audit

SecretsAuditConfig drives the audit-emission infrastructure (Epic 10 task 11). Wires LogAuditor (always) + BufferedAuditor (when BufferSize > 0) + an optional SamplingAuditor wrapping the log auditor when SamplingFraction < 1.0. Epic 12’s AuditStore will plug in here once it ships.

secrets.backends

SecretsBackendConfig is one operator-declared backend instance. Exactly one of [File] / [Vault] must be set and must match [Type].

secrets.backends.file

SecretsFileBackendConfig drives the encrypted-file backend (internal/secrets/file). MasterKey is the scheme-prefixed value resolved by masterkey.Resolve — env:VAR_NAME, file:/path/to/keyfile, or inline:<hex\|base64>.

secrets.backends.vault

SecretsVaultBackendConfig drives the Vault backend (internal/secrets/vault).

secrets.backends.vault.approle

SecretsVaultAppRoleConfig — RoleID + SecretID. SecretID may itself be a wrapping token (per Vault’s response-wrapping flow).

secrets.backends.vault.kubernetes

SecretsVaultK8sConfig — Kubernetes ServiceAccount-based auth.

secrets.backends.vault.ldap

SecretsVaultLDAPConfig — LDAP username/password auth.

secrets.backends.vault.mounts

SecretsVaultMountConfig declares the KV engine version for one Vault mount path — see internal/secrets/vault.MountConfig.

secrets.backends.vault.tls

SecretsVaultTLSConfig configures HTTPS to Vault.

secrets.cache

SecretsCacheConfig drives the [secrets.SecretCache]. Enabled defaults to true when secrets are enabled — operators rarely want to disable caching, but explicit enabled: false falls back to the no-op cache.

secrets.lease

SecretsLeaseConfig drives the [secrets.LeaseManager].

secrets.routing

SecretsRouteConfig is one row in the broker’s routing table.

events

EventsConfig drives the Epic 11 events boot in kscore-server. events: enabled: true publisher: enabled: true buffer_size: 1000 flush_timeout: 100ms store_first: true subscriber: enabled: true dedup_size: 1000 Enabled defaults to true — events are foundational v1.0 infrastructure and most deployments running NATS expect them on. Operators explicitly disable via events.enabled: false. When disabled, the gRPC EventService returns codes.Unavailable + REST returns 503; the JetStreamPublisher / Subscriber are skipped at boot. Validation requires NATS JetStream to be enabled when events is enabled — the publisher / subscriber both need a JetStream context.

events.publisher

EventsPublisherConfig drives the JetStreamPublisher (Epic 11 task 3). - Enabled: gates the publisher specifically. Defaults true when parent Events is enabled. Setting false runs Events with the NoopPublisher (subscriber + REST list/get still work). - BufferSize / FlushTimeout: async-pipeline knobs from task 3. Defaults match the package’s Default* constants. - StoreFirst: when true (default), publisher persists to the EventStore before NATS publish; failures abort. When false, publishes go straight to NATS (no audit trail). Most deployments leave this on.

events.retention

EventsRetentionConfig drives the Epic 11 task 8 retention enforcer — the hourly scheduler that calls events.EventStore.ApplyRetention to bound store growth. Defaults to enabled with a built-in catch-all policy matching the §4.9 JetStream stream defaults (7 days / 1M events). Operators either keep the catch-all and add per-type overrides, or set events.retention.enabled: false to opt out entirely. events: retention: enabled: true interval: 1h jitter: 0.1 policies: - type: "" # catch-all max_age: 168h # 7 days max_count: 1000000 - type: agent.heartbeat max_age: 24h - type: job.output max_age: 720h # 30 days

events.retention.policies

EventsRetentionPolicy is one row in the retention table. Type empty is the catch-all rule (applies to every event type not matched by a more-specific policy). Each policy must have at least one limit (MaxAge > 0 OR MaxCount > 0) — zero-zero is rejected by validation as a no-op typo.

events.subscriber

EventsSubscriberConfig drives the JetStreamSubscriber (Epic 11 task 4). - Enabled: gates the subscriber specifically. Defaults true. Setting false makes SubscribeEvents return Unavailable. - DedupSize: bounded ID dedup ring (task 4). Defaults 1000.

cluster

ClusterConfig drives the Epic 13 clustering/HA boot in kscore-server (PROJECT-DETAILS §4.15). cluster: enabled: false node: name: "" # empty → derived from etcd.name advertise_addr: "" # host:port peers dial (server↔server) etcd: mode: embedded # embedded | external name: kscore-1 data_dir: ./data/etcd client_urls: ["http://127.0.0.1:2379 "] peer_urls: ["http://127.0.0.1:2380 "] endpoints: [] # external mode only lease_ttl_seconds: 15 dial_timeout: 5s auto_sync_interval: 5m membership: heartbeat_interval: 5s key_prefix: /kscore/cluster election: session_ttl_seconds: 3 recampaign_delay: 1s shard: virtual_nodes: 150 rebalance_cooldown: 5s health: check_interval: 5s failure_threshold: 3 latency_window: 100 failover: cooldown: 10s agent_batch: 100 job_batch: 50 recovery: connect_timeout: 5s connect_retries: 3 fencing: mode: read_only # strict | read_only | graceful coordination: listen_addr: "" # host:port mTLS listener bind; empty → none heartbeat_interval: 5s heartbeat_timeout: 2s failure_threshold: 3 retry_max: 4 retry_base_delay: 100ms retry_max_delay: 2s shutdown: timeout: 30s Enabled defaults to false: the single-node path stays the default and clustering is strictly opt-in. When disabled, no etcd is started and the ClusterService/CoordinationService are not registered (later Epic 13 tasks). The wiring that translates this into a running internal/cluster.EtcdClient lands with a later Epic 13 task; Task 1 ships the config surface + validation.

cluster.coordination

ClusterCoordinationConfig is the operator-facing server↔server CoordinationService/Client config (Epic 13 tasks 12/13). The runtime equivalents are the dedicated mTLS coordination listener + controlplane.CoordinationClientConfig; boot wiring maps onto them.

cluster.election

ClusterElectionConfig is the operator-facing leader-election config (Epic 13 task 3). The runtime equivalent is cluster.ElectionConfig; boot wiring (later task) maps onto it. The election session lease is separate from the membership lease: it is tuned to the “first/new leader < 3s” failover SLO, not the membership 3×-heartbeat anti-flap rule. SLO verification + any tuning is Epic 13 task 18.

cluster.etcd

ClusterEtcdConfig is the operator-facing etcd backend config. internal/cluster owns the runtime equivalent (cluster.EtcdConfig); boot wiring (later task) maps this onto it.

cluster.failover

ClusterFailoverConfig is the operator-facing failover config (Epic 13 task 8). The runtime equivalent is cluster.FailoverManagerConfig; boot wiring (later task) maps onto it.

cluster.fencing

ClusterFencingConfig is the operator-facing split-brain fencing config (Epic 13 task 11). The runtime equivalent is cluster.FencingManagerConfig; boot wiring (later task) maps onto it.

cluster.health

ClusterHealthConfig is the operator-facing health-monitor config (Epic 13 task 7). The runtime equivalent is cluster.HealthMonitorConfig; boot wiring (later task) maps onto it.

cluster.membership

ClusterMembershipConfig is the operator-facing membership config (Epic 13 task 2). The runtime equivalent is cluster.MembershipConfig; boot wiring (later task) maps onto it.

cluster.node

ClusterNodeConfig identifies this server within the cluster (Epic 13 boot wiring). Distinct from cluster.etcd.name (the etcd member name): Name is this node’s stable Keystone member identity, recorded in the membership record and reused across restarts so RecoveryManager can reclaim this node’s shards.

cluster.recovery

ClusterRecoveryConfig is the operator-facing restart-recovery config (Epic 13 task 10). The runtime equivalent is cluster.RecoveryManagerConfig; boot wiring (later task) maps onto it.

cluster.shard

ClusterShardConfig is the operator-facing consistent-hash + rebalance config (Epic 13 tasks 4/6). The runtime equivalents are the cluster.HashRing vnode count and the ShardManager cooldown; boot wiring (later task) maps onto them.

cluster.shutdown

ClusterShutdownConfig is the operator-facing graceful-shutdown config (Epic 13 task 14). The runtime equivalent is cluster.GracefulShutdownConfig; boot wiring (later task) maps onto it.

gitops

GitOpsConfig drives the Epic 16 GitOps integration. Task 1 ships the inbound webhook receiver sub-config only; verification, rollback and outbound webhooks extend this struct in later tasks. gitops: webhook: enabled: false addr: “:8081” path: “/webhooks” max_body_bytes: 1048576 sources: github: method: hmac # none|hmac|bearer secret: ${KSCORE_GITOPS_WEBHOOK_SOURCES_GITHUB_SECRET} gitlab: method: bearer secret: … Enabled defaults to false: the receiver opens a network port and (from task 4) re-emits onto the event bus, so it is opt-in rather than on-by-default infrastructure. Operators turn it on with gitops.webhook.enabled: true.

gitops.webhook

GitOpsWebhookConfig is the inbound webhook receiver block. Addr defaults to “:8081” — distinct from the main REST API on server.httpport (:8080); colliding the two would wedge boot.

webhook

WebhookConfig drives the outbound webhooks subsystem (Epic 16 tasks 11..18 / PROJECT-DETAILS §4.14). The top-level webhook key is owned by outbound for v1.0; inbound non-GitOps webhooks are v1.x (the GitOps inbound block lives at gitops.webhook). webhook: outbound: enabled: false max_retries: 3 retry_backoff: 1s timeout: 10s max_payload_size: 1048576 delivery_retention: 168h max_concurrent_deliveries: 32 refresh_interval: 30s Enabled defaults to false (opt-in; the same posture as gitops.webhook.enabled).

webhook.outbound

WebhookOutboundConfig is the outbound-webhooks block. - MaxRetries / RetryBackoff drive the task-14 RetryQueue. - Timeout caps each task-13 Dispatcher.Deliver call. - MaxPayloadSize bounds the JSON event payload — over-size events are recorded as one synthetic failed delivery. - DeliveryRetention is the task-9 / task-11 retention enforcer horizon (auto-invocation = post-v1.0 dot release per §4.14). - MaxConcurrentDeliveries / RefreshInterval drive the task-12 Manager (fan-out cap and subscription-cache reload cadence).

metrics

MetricsConfig configures the Prometheus exposition surface. PROJECT-DETAILS §4.16: /metrics is on the main HTTP server, unauthenticated, no rate-limit — same posture as /health/*.

tracing

TracingConfig configures the Epic 17 task 4 OTel trace pipeline. Disabled by default — 100% sampling adds 5-10% latency at scale (PROJECT-DETAILS §4.16 gotcha), so operators opt in explicitly.

profiling

ProfilingConfig configures the opt-in pprof endpoint. PROJECT-DETAILS §4.16 — “Default off; opt-in via profiling.enabled=true. Listen port default 6060.” Default Host is 127.0.0.1: pprof can leak heap state and bottleneck under CPU profile load, so operators who flip Enabled must explicitly widen the bind to reach the LAN.

blueprints

BlueprintsConfig wires the optional v1.0 BlueprintService. Epic 19 task 2b — until the gate-v1.0 ROADMAP item “Remote / distributed blueprint apply wiring” lands, the server-side BlueprintService applies blueprints against the server’s local stdlib StateRunner (the same convergence path kscore-blueprint uses today). CatalogPath enables ListBlueprints / GetBlueprint / ApplyBlueprint over gRPC; empty disables them (clients reach Unavailable).