Operations

Bootstrap from zero

kvm install config.svc                                   # or build from source
config.svc config generate bootstrap-dev > config.yaml   # pick a profile
config.svc config generate apikeys > apikeys.yaml
config.svc server -f config.yaml
curl -H "X-Api-Key: $KEY" http://localhost:7123/hives

Storage needs:

• Single node — a writable directory for the bbolt snapshot store (storage.mode: bbolt).
• HA — an operator-run etcd cluster (3 or 5 nodes) plus leader election (ttl: 15s). The reconciler runs on the leader; reads and writes are served by every instance.
• Postgres break-glass source — one-time DDL: config.svc config generate pgsource | psql … (creates the overrides table + NOTIFY trigger).

Seed content by pointing a localdir/fs source at a folder of flat-path documents (see Configuration files), or use git sources for real deployments.

Migration helpers:

• config.svc import-legacy — one-shot conversion of legacy clusterstore/customerstore trees to the hive layout.
• config.svc migrate — applies major-schema-version transforms.

CLI

The client CLI is kis config / kis sd:

kis config hives
kis config get tenant acme:forge:prod:tenant-a:iam
kis config explain tenant acme:forge:prod:tenant-a:iam   # per-field provenance
kis config set cluster dc1:main:iam --file node.yaml
kis config watch
kis sd services
kis sd instances iam

Server admin subcommands on the binary itself: server, config list|generate, import-legacy, migrate, explain, version.

Watch and reload behavior

• Per-backend watches (fsnotify / git ref-poll + webhook / etcd watch / postgres LISTEN-NOTIFY) feed the reconciler; there is no full-tree rescan on a healthy path.
• Subscribers resume by Last-Event-Id; a cursor that is too old gets full_resync.
• The service-side client reconnects forever with jittered exponential backoff and serves its bbolt last-known-good cache meanwhile.
• Read-after-write lag is typically hundreds of milliseconds; use If-Min-Version when a caller must observe its own write.

Break-glass writes

Writes route to the highest-priority writable source (postgres/etcd/localdir). Use:

• X-Reason — flows into audit and into explain provenance.
• X-Schedule-Revert-At — enqueues an audited auto-revert; the revert fails loudly if state diverged in the meantime.
• alert_on_write on the source — pages when anyone writes through it.

Failure modes

Everything fails closed by design:

Symptom	Cause
Writes return 503	Audit sink (the platform audit service) unreachable — writes are never buffered locally. Dev: leave audit.endpoint empty for a no-op emitter
Boot error naming a source	Unreachable source, empty owns, writable: true on fs/git, or owns: ["**"] on the tenant hive
Whole source fails with a file-naming error	A YAML file without a top-level hives: key (the legacy-layout mistake)
Snapshot missing / write 422	CUE validation failure — the metric carries hive, path, and CUE path
400 invalid_path	Predefined-level violation (e.g. environment not in dev/uat/prod)
409 on write	If-Match version conflict

Observability is OpenTelemetry-only (infinity_config_* / infinity_discovery_* metric namespaces) — there is no /metrics endpoint.