For the latest stable version, please use Korvet 0.19!

Configuration Reference

Complete configuration reference for Korvet.

All korvet properties have sensible defaults. You can override them via application.yml, environment variables (e.g. KORVET_BROKER_PORT), or command-line arguments (e.g. --korvet.broker.port=9092). Unknown korvet properties fail startup (strict binding) — a typo is caught immediately rather than silently ignored.

General

Prefix: korvet. · Env prefix: KORVET_

Top-level Korvet runtime settings: namespace and the entry points into each sub-system.

`namespace`

Env var: KORVET_NAMESPACE · Type: string · Default: korvet

Logical namespace applied to all storage and registry state this Korvet instance owns. Must not contain whitespace or the : delimiter — colons are appended internally to compose sub-namespaces.

Admin

Prefix: korvet.admin. · Env prefix: KORVET_ADMIN_

HTTP Admin API bootstrap credentials.

`bootstrap`

Env var: KORVET_ADMIN_BOOTSTRAP · Type: boolean · Default: true

Create the default admin credential at startup when it does not already exist.

`password`

Env var: KORVET_ADMIN_PASSWORD · Type: string · Default: admin

Password for the bootstrapped admin credential. Change this before exposing the Admin API.

`username`

Env var: KORVET_ADMIN_USERNAME · Type: string · Default: admin

Username for the bootstrapped admin credential.

Broker

Prefix: korvet.broker. · Env prefix: KORVET_BROKER_

Kafka-wire broker listener and group coordinator: bind address, TLS, request limits, backpressure, and rebalance tuning.

`advertised-host`

Env var: KORVET_BROKER_ADVERTISED_HOST · Type: string

Hostname advertised to clients via the Kafka metadata response. Leave unset (null) to fall back to host; blank/whitespace values are rejected.

`advertised-port`

Env var: KORVET_BROKER_ADVERTISED_PORT · Type: integer

Port advertised to clients via the Kafka metadata response. Defaults to port when unset.

`boss-threads`

Env var: KORVET_BROKER_BOSS_THREADS · Type: integer · Default: 1

Netty boss (accept) thread count.

`cert-file`

Env var: KORVET_BROKER_CERT_FILE · Type: file path

PEM-encoded server certificate (or chain). Required when tls=true.

`client-auth-required`

Env var: KORVET_BROKER_CLIENT_AUTH_REQUIRED · Type: boolean · Default: false

Require clients to present a certificate (mTLS).

`enabled`

Env var: KORVET_BROKER_ENABLED · Type: boolean · Default: true

Enable the broker listener.

`fetch-max-wait`

Env var: KORVET_BROKER_FETCH_MAX_WAIT · Type: duration · Default: 500ms

Maximum time a fetch request will block waiting for fetch.min.bytes to be satisfied.

`fetch-partition-max-bytes`

Env var: KORVET_BROKER_FETCH_PARTITION_MAX_BYTES · Type: data size · Default: 1MB

Default upper bound on per-partition bytes returned by a fetch.

`host`

Env var: KORVET_BROKER_HOST · Type: string · Default: 0.0.0.0

Listener host (interface to bind to).

`id`

Env var: KORVET_BROKER_ID · Type: integer · Default: 0

Numeric broker id advertised to Kafka clients. Must be unique across a multi-node deployment.

`key-file`

Env var: KORVET_BROKER_KEY_FILE · Type: file path

PEM-encoded server private key. Required when tls=true.

`key-password`

Env var: KORVET_BROKER_KEY_PASSWORD · Type: secret

Passphrase protecting keyFile, if encrypted.

`max-pending-bytes`

Env var: KORVET_BROKER_MAX_PENDING_BYTES · Type: data size · Default: 100MB

Backpressure threshold: pause reads from the wire once this many bytes are pending outbound.

`max-request-bytes`

Env var: KORVET_BROKER_MAX_REQUEST_BYTES · Type: data size · Default: 100MB

Maximum size of a single inbound Kafka request. Requests larger than this are rejected.

`port`

Env var: KORVET_BROKER_PORT · Type: integer · Default: 9092

Listener TCP port.

`rebalance-delay`

Env var: KORVET_BROKER_REBALANCE_DELAY · Type: duration · Default: 3s

Grace period before triggering a consumer-group rebalance after a member joins or leaves.

`rebalance-threads`

Env var: KORVET_BROKER_REBALANCE_THREADS · Type: integer · Default: max(2, available CPU cores)

Scheduler thread-pool size for the group coordinator.

`resume-pending-bytes`

Env var: KORVET_BROKER_RESUME_PENDING_BYTES · Type: data size · Default: 50MB

Backpressure release threshold: resume reads once pending bytes drop below this. Must be < maxPendingBytes.

`tls`

Env var: KORVET_BROKER_TLS · Type: boolean · Default: false

Enable TLS on the listener. When true, certFile and keyFile are required.

`trust-cert-file`

Env var: KORVET_BROKER_TRUST_CERT_FILE · Type: file path

PEM-encoded CA trust store for verifying client certificates (mTLS). Required when clientAuthRequired=true.

`worker-threads`

Env var: KORVET_BROKER_WORKER_THREADS · Type: integer · Default: 0

Netty worker (IO) thread count. 0 lets Netty pick a default based on CPU count.

Metrics

Prefix: korvet.broker.metrics. · Env prefix: KORVET_BROKER_METRICS_

`offset-cardinality-cap`

Env var: KORVET_BROKER_METRICS_OFFSET_CARDINALITY_CAP · Type: integer · Default: 10000

Maximum number of (topic, partition) pairs published as offset gauges. When the live topic-partition count exceeds this cap, the publisher skips the refresh and logs a warning to prevent unbounded time-series cardinality.

`offset-refresh-interval`

Env var: KORVET_BROKER_METRICS_OFFSET_REFRESH_INTERVAL · Type: duration · Default: 15s

Interval between refreshes of per-topic-partition offset gauges (korvet.broker.max_offset, korvet.broker.log_start_offset).

Sasl

Prefix: korvet.broker.sasl. · Env prefix: KORVET_BROKER_SASL_

`enabled`

Env var: KORVET_BROKER_SASL_ENABLED · Type: boolean · Default: false

Enable SASL authentication on the listener.

`mechanisms`

Env var: KORVET_BROKER_SASL_MECHANISMS · Type: list of string · Default: SCRAM-SHA-256

SASL mechanisms advertised to clients. Must be a non-empty subset of SUPPORTED. Defaults to SCRAM-SHA-256 only — PLAIN must be opted in explicitly and requires TLS.

Redis

Prefix: korvet.redis. · Env prefix: KORVET_REDIS_

Primary Redis client used by the broker, registries, and (unless overridden) storage.

`cluster`

Env var: KORVET_REDIS_CLUSTER · Type: boolean · Default: false

Treat the target as a Redis Cluster (uses Lettuce RedisClusterClient).

`host`

Env var: KORVET_REDIS_HOST · Type: string · Default: localhost

Redis host. Ignored when uri is set.

`io-threads`

Env var: KORVET_REDIS_IO_THREADS · Type: integer · Default: available CPU cores

Size of the Lettuce IO (event-loop) thread pool.

`password`

Env var: KORVET_REDIS_PASSWORD · Type: secret

Password for AUTH.

`port`

Env var: KORVET_REDIS_PORT · Type: integer · Default: 6379

Redis port. Ignored when uri is set.

`timeout`

Env var: KORVET_REDIS_TIMEOUT · Type: duration · Default: 1m

Default per-command timeout.

`uri`

Env var: KORVET_REDIS_URI · Type: string

Redis URI (redis://… or rediss://…). When set, supersedes host/port/username/password.

`username`

Env var: KORVET_REDIS_USERNAME · Type: string

Username for ACL authentication. Leave unset for password-only AUTH.

Circuit Breaker

Prefix: korvet.redis.circuit-breaker. · Env prefix: KORVET_REDIS_CIRCUIT_BREAKER_

Fail-fast circuit breaker around Redis stream operations on the primary client.

`enabled`

Env var: KORVET_REDIS_CIRCUIT_BREAKER_ENABLED · Type: boolean · Default: true

Enable the stream-operation circuit breaker.

`log-interval`

Env var: KORVET_REDIS_CIRCUIT_BREAKER_LOG_INTERVAL · Type: duration · Default: 30s

Minimum interval between breaker-state log lines (rate-limit for repeated open events).

`open-duration`

Env var: KORVET_REDIS_CIRCUIT_BREAKER_OPEN_DURATION · Type: duration · Default: 30s

How long the breaker stays open before allowing a probe call.

Metrics

Prefix: korvet.redis.metrics. · Env prefix: KORVET_REDIS_METRICS_

Client-side latency metrics published by Lettuce for the primary Redis client.

`enabled`

Env var: KORVET_REDIS_METRICS_ENABLED · Type: boolean · Default: false

Enable command-latency metrics collection.

`histogram`

Env var: KORVET_REDIS_METRICS_HISTOGRAM · Type: boolean · Default: false

Publish per-command histograms in addition to summary statistics.

`local-distinction`

Env var: KORVET_REDIS_METRICS_LOCAL_DISTINCTION · Type: boolean · Default: false

Split metrics by local (client) socket address — useful in pooled deployments.

`max-latency`

Env var: KORVET_REDIS_METRICS_MAX_LATENCY · Type: duration · Default: 5m

Upper bound used when bucketing latency samples.

`min-latency`

Env var: KORVET_REDIS_METRICS_MIN_LATENCY · Type: duration · Default: 1ms

Lower bound used when bucketing latency samples.

Pool

Prefix: korvet.redis.pool. · Env prefix: KORVET_REDIS_POOL_

Connection-pool sizing for the primary Redis client.

`max-wait`

Env var: KORVET_REDIS_POOL_MAX_WAIT · Type: duration · Default: 10s

Maximum time a caller will block waiting to borrow a connection from a saturated pool.

`size`

Env var: KORVET_REDIS_POOL_SIZE · Type: integer · Default: 8

Maximum number of pooled connections.

Schema Registry

Prefix: korvet.schema-registry. · Env prefix: KORVET_SCHEMA_REGISTRY_

Embedded Confluent-compatible schema-registry HTTP endpoint.

`default-compatibility`

Env var: KORVET_SCHEMA_REGISTRY_DEFAULT_COMPATIBILITY · Type: none, backward, backward_transitive, forward, forward_transitive, full, full_transitive · Default: backward

Default compatibility level applied to newly-created subjects.

`enabled`

Env var: KORVET_SCHEMA_REGISTRY_ENABLED · Type: boolean · Default: true

Enable the embedded schema-registry HTTP endpoint.

`validate-produce`

Env var: KORVET_SCHEMA_REGISTRY_VALIDATE_PRODUCE · Type: boolean · Default: true

Reject produce requests whose payload doesn’t validate against the subject’s latest schema.

Storage

Prefix: korvet.storage. · Env prefix: KORVET_STORAGE_

Storage settings: Redis-backed local tier and optional object-store cold tier (opt-in via remote-path).

`remote-path`

Env var: KORVET_STORAGE_REMOTE_PATH · Type: string

Object-store path for the cold-tier Iceberg table (e.g. s3://bucket/korvet/cold). Absent/blank disables the cold tier — Korvet runs local-only on Redis Streams.

Iceberg

Prefix: korvet.storage.iceberg. · Env prefix: KORVET_STORAGE_ICEBERG_

`row-group-size`

Env var: KORVET_STORAGE_ICEBERG_ROW_GROUP_SIZE · Type: data size · Default: 128MB

Parquet row-group size for Iceberg data files written by the remote segment store. Maps to Iceberg write.parquet.row-group-size-bytes.

`target-file-size`

Env var: KORVET_STORAGE_ICEBERG_TARGET_FILE_SIZE · Type: data size · Default: 128MB

Target size for Iceberg data files written by the remote segment store. Maps to Iceberg write.target-file-size-bytes.

Offload

Prefix: korvet.storage.offload. · Env prefix: KORVET_STORAGE_OFFLOAD_

Storage offload worker: leader-locked periodic task that rolls eligible segments, offloads sealed segments, and enforces local and remote retention.

`enabled`

Env var: KORVET_STORAGE_OFFLOAD_ENABLED · Type: boolean · Default: true

Enable the storage offload worker. The Redis leader lock ensures at most one enabled instance runs at a time across the cluster.

`lease-duration`

Env var: KORVET_STORAGE_OFFLOAD_LEASE_DURATION · Type: duration · Default: 2m

Redis leader-lock lease duration. Must exceed tickInterval so a slow tick does not let the lease expire mid-flight.

`tick-interval`

Env var: KORVET_STORAGE_OFFLOAD_TICK_INTERVAL · Type: duration · Default: 1m

Tick cadence for the offload loop.

Redis

Prefix: korvet.storage.redis. · Env prefix: KORVET_STORAGE_REDIS_

Sparse overrides for the storage-tier Redis client. Each unset field inherits the corresponding value from korvet.redis.

`cluster`

Env var: KORVET_STORAGE_REDIS_CLUSTER · Type: boolean

Treat the storage Redis target as a Redis Cluster.

`host`

Env var: KORVET_STORAGE_REDIS_HOST · Type: string

Storage Redis host. Ignored when uri is set.

`io-threads`

Env var: KORVET_STORAGE_REDIS_IO_THREADS · Type: integer

Storage Redis Lettuce IO thread-pool size.

`password`

Env var: KORVET_STORAGE_REDIS_PASSWORD · Type: secret

Storage Redis password.

`port`

Env var: KORVET_STORAGE_REDIS_PORT · Type: integer

Storage Redis port. Ignored when uri is set.

`timeout`

Env var: KORVET_STORAGE_REDIS_TIMEOUT · Type: duration

Storage Redis per-command timeout.

`uri`

Env var: KORVET_STORAGE_REDIS_URI · Type: string

Storage Redis URI. When set, overrides the primary Redis URI for storage traffic.

`username`

Env var: KORVET_STORAGE_REDIS_USERNAME · Type: string

Storage Redis ACL username.

Circuit Breaker

Prefix: korvet.storage.redis.circuit-breaker. · Env prefix: KORVET_STORAGE_REDIS_CIRCUIT_BREAKER_

Sparse circuit-breaker overrides for the storage-tier Redis client.

`enabled`

Env var: KORVET_STORAGE_REDIS_CIRCUIT_BREAKER_ENABLED · Type: boolean

Enable the storage Redis stream-operation circuit breaker.

`log-interval`

Env var: KORVET_STORAGE_REDIS_CIRCUIT_BREAKER_LOG_INTERVAL · Type: duration

Minimum interval between storage Redis breaker-state log lines.

`open-duration`

Env var: KORVET_STORAGE_REDIS_CIRCUIT_BREAKER_OPEN_DURATION · Type: duration

How long the storage Redis circuit breaker stays open before allowing a probe call.

Metrics

Prefix: korvet.storage.redis.metrics. · Env prefix: KORVET_STORAGE_REDIS_METRICS_

Sparse metrics overrides for the storage-tier Redis client.

`enabled`

Env var: KORVET_STORAGE_REDIS_METRICS_ENABLED · Type: boolean

Enable command-latency metrics for the storage Redis client.

`histogram`

Env var: KORVET_STORAGE_REDIS_METRICS_HISTOGRAM · Type: boolean

Publish per-command histograms for the storage Redis client.

`local-distinction`

Env var: KORVET_STORAGE_REDIS_METRICS_LOCAL_DISTINCTION · Type: boolean

Split storage Redis metrics by local socket address.

`max-latency`

Env var: KORVET_STORAGE_REDIS_METRICS_MAX_LATENCY · Type: duration

Upper bound used when bucketing storage Redis latency samples.

`min-latency`

Env var: KORVET_STORAGE_REDIS_METRICS_MIN_LATENCY · Type: duration

Lower bound used when bucketing storage Redis latency samples.

Pool

Prefix: korvet.storage.redis.pool. · Env prefix: KORVET_STORAGE_REDIS_POOL_

Sparse pool overrides for the storage-tier Redis client.

`max-wait`

Env var: KORVET_STORAGE_REDIS_POOL_MAX_WAIT · Type: duration

Maximum time a caller will block waiting to borrow a storage Redis connection.

`size`

Env var: KORVET_STORAGE_REDIS_POOL_SIZE · Type: integer

Maximum number of pooled storage Redis connections.

S3

Prefix: korvet.storage.s3. · Env prefix: KORVET_STORAGE_S3_

S3 connection settings for the cold-tier object store. Only consulted when korvet.storage.remote-path starts with s3://.

`access-key-id`

Env var: KORVET_STORAGE_S3_ACCESS_KEY_ID · Type: string

Access-key id. Maps to Iceberg s3.access-key-id.

`endpoint`

Env var: KORVET_STORAGE_S3_ENDPOINT · Type: string

Optional endpoint URL for non-AWS S3-compatible stores (e.g. MinIO). Maps to s3.endpoint.

`path-style-access`

Env var: KORVET_STORAGE_S3_PATH_STYLE_ACCESS · Type: boolean

Use path-style addressing instead of the default virtual-hosted-style. Maps to s3.path-style-access. Required for most non-AWS S3 stores.

`region`

Env var: KORVET_STORAGE_S3_REGION · Type: string

AWS region (e.g. us-east-1). Maps to Iceberg client.region.

`secret-access-key`

Env var: KORVET_STORAGE_S3_SECRET_ACCESS_KEY · Type: secret

Secret access key. Maps to s3.secret-access-key.

Topic configuration patterns

The korvet.topics list is order-sensitive: each entry is a glob pattern plus optional field overrides, evaluated top-to-bottom with first-non-null-wins semantics. Fields not set by any matching pattern fall back to the built-in defaults defined in TopicConfig. Per-topic admin-set overrides beat patterns.

The per-element fields (korvet.topics[n].partitions, retention-time, compression, etc.) live on TopicConfig in a separate module and are not enumerated in the tables above. The full list:

name (required) — glob pattern matched against topic names.
auto-create — whether unknown topics matching this pattern may be auto-created.
partitions, offset-sequence-bits, average-message-bytes
retention-time, retention-bytes
local-retention-time, local-retention-bytes
compression, storage-compression, value-type
remote-storage-enabled, bucket-duration

See the configuration guide for examples.

Environment variables

Every property can be set via an environment variable using Spring Boot’s relaxed binding: uppercase the property name, replace . and - with _. For example:

Property Environment variable

Property	Environment variable
`korvet.broker.max-request-bytes`	`KORVET_BROKER_MAX_REQUEST_BYTES`
`korvet.storage.remote-path`	`KORVET_STORAGE_REMOTE_PATH`
`korvet.storage.offload.enabled`	`KORVET_STORAGE_OFFLOAD_ENABLED`

korvet.broker.max-request-bytes

KORVET_BROKER_MAX_REQUEST_BYTES

korvet.storage.remote-path

KORVET_STORAGE_REMOTE_PATH

korvet.storage.offload.enabled

KORVET_STORAGE_OFFLOAD_ENABLED

The exact env-var name for every property is listed in the tables above.

Migration

The property layout was reorganized in the KorvetProperties refactor. There are no compatibility aliases — old names are rejected by strict binding and must be updated at the same time as the upgrade.

Old property New property Notes

Old property	New property	Notes
`korvet.services`	`korvet.broker.enabled` and/or `korvet.storage.offload.enabled`	The service-selection set is gone. The broker and storage offload worker are enabled by default; disable one explicitly for single-role deployments. See Deployment shapes.
`korvet.broker.sasl` (boolean)	`korvet.broker.sasl.enabled` (nested type)	`sasl` is now a nested group; it also carries `mechanisms`.
`korvet.broker.partition-max-bytes`	`korvet.broker.fetch-partition-max-bytes`	Renamed to group with `fetch-max-wait` and match the Kafka mental model.
`korvet.storage.remote.archiver.*`	`korvet.storage.offload.*`	Archiver and trimmer workers were consolidated into the leader-locked storage offload worker.
`korvet.storage.remote.trimmer.*`	`korvet.storage.offload.*`	Archiver and trimmer workers were consolidated into the leader-locked storage offload worker.
`korvet.storage.remote.trimmer.op-timeout`	removed	Trimming now runs inside the storage offload tick.
`korvet.storage.remote.compactor.` `korvet.storage.remote.messages-per-file` `korvet.storage.remote.files-per-commit` `korvet.storage.remote.target-file-size` `korvet.storage.remote.writer-`	removed	The compactor and the multi-file commit writer were removed when the cold tier moved to one Parquet file per sealed segment with the manifest as the commit point. Tune segment size via topic-level `segment-time`, `segment-bytes`, and `average-message-bytes`.
`korvet.archiver.consumer-group` `korvet.archiver.consumer-name-prefix`	removed	The storage offload worker archives sealed segments directly; it does not use a Kafka-style consumer group.

korvet.services

korvet.broker.enabled and/or korvet.storage.offload.enabled

The service-selection set is gone. The broker and storage offload worker are enabled by default; disable one explicitly for single-role deployments. See Deployment shapes.

korvet.broker.sasl (boolean)

korvet.broker.sasl.enabled (nested type)

sasl is now a nested group; it also carries mechanisms.

korvet.broker.partition-max-bytes

korvet.broker.fetch-partition-max-bytes

Renamed to group with fetch-max-wait and match the Kafka mental model.

korvet.storage.remote.archiver.*

korvet.storage.offload.*

Archiver and trimmer workers were consolidated into the leader-locked storage offload worker.

korvet.storage.remote.trimmer.*

korvet.storage.offload.*

Archiver and trimmer workers were consolidated into the leader-locked storage offload worker.

korvet.storage.remote.trimmer.op-timeout

removed

Trimming now runs inside the storage offload tick.

korvet.storage.remote.compactor.
korvet.storage.remote.messages-per-file
korvet.storage.remote.files-per-commit
korvet.storage.remote.target-file-size
korvet.storage.remote.writer-

removed

The compactor and the multi-file commit writer were removed when the cold tier moved to one Parquet file per sealed segment with the manifest as the commit point. Tune segment size via topic-level segment-time, segment-bytes, and average-message-bytes.

korvet.archiver.consumer-group
korvet.archiver.consumer-name-prefix

removed

The storage offload worker archives sealed segments directly; it does not use a Kafka-style consumer group.