|
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, or to localhost when host binds to all interfaces (0.0.0.0); 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.
produce-timeout
Env var: KORVET_BROKER_PRODUCE_TIMEOUT · Type: duration · Default: 5s
Server-side cap on how long a single partition’s storage write may run before it is surfaced as REQUEST_TIMED_OUT. Because produce responses are sent in request order per connection, a stalled write would otherwise hold the head of the in-order response queue (and every pipelined request behind it) for the client’s full timeoutMs — collapsing throughput on the connection. The effective bound per partition is the smaller of this value and the client-supplied request timeout. Set to zero to disable the server-side cap.
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.
response-queue-timeout
Env var: KORVET_BROKER_RESPONSE_QUEUE_TIMEOUT · Type: duration · Default: 10s
Upper bound on how long a single request may hold the head of the per-connection, in-order response queue before it is failed with REQUEST_TIMED_OUT. Prevents a request whose handler never completes from stalling every later request on the connection. Fetch requests additionally get their fetchMaxWait long-poll budget on top of this.
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: 3s
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 split by tier: a Redis-backed local tier and optional object-store remote tier.
Local
Prefix: korvet.storage.local. · Env prefix: KORVET_STORAGE_LOCAL_
Redis-backed local tier settings.
Compression
Prefix: korvet.storage.local.compression. · Env prefix: KORVET_STORAGE_LOCAL_COMPRESSION_
codec
Env var: KORVET_STORAGE_LOCAL_COMPRESSION_CODEC · Type: none, gzip, snappy, lz4, zstd · Default: lz4
Compression codec for values at rest in Redis. none keeps the self-describing format but stores values uncompressed. Values: none, gzip, snappy, lz4, zstd.
min-bytes
Env var: KORVET_STORAGE_LOCAL_COMPRESSION_MIN_BYTES · Type: integer · Default: 64
Values smaller than this are stored uncompressed (compression overhead exceeds the saving).
Redis
Prefix: korvet.storage.local.redis. · Env prefix: KORVET_STORAGE_LOCAL_REDIS_
Sparse overrides for the local storage Redis client. Each unset field inherits the corresponding value from korvet.redis.
cluster
Env var: KORVET_STORAGE_LOCAL_REDIS_CLUSTER · Type: boolean
Treat the storage Redis target as a Redis Cluster.
host
Env var: KORVET_STORAGE_LOCAL_REDIS_HOST · Type: string
Storage Redis host. Ignored when uri is set.
io-threads
Env var: KORVET_STORAGE_LOCAL_REDIS_IO_THREADS · Type: integer
Storage Redis Lettuce IO thread-pool size.
password
Env var: KORVET_STORAGE_LOCAL_REDIS_PASSWORD · Type: secret
Storage Redis password.
port
Env var: KORVET_STORAGE_LOCAL_REDIS_PORT · Type: integer
Storage Redis port. Ignored when uri is set.
timeout
Env var: KORVET_STORAGE_LOCAL_REDIS_TIMEOUT · Type: duration
Storage Redis per-command timeout.
uri
Env var: KORVET_STORAGE_LOCAL_REDIS_URI · Type: string
Storage Redis URI. When set, overrides the primary Redis URI for storage traffic.
username
Env var: KORVET_STORAGE_LOCAL_REDIS_USERNAME · Type: string
Storage Redis ACL username.
Circuit Breaker
Prefix: korvet.storage.local.redis.circuit-breaker. · Env prefix: KORVET_STORAGE_LOCAL_REDIS_CIRCUIT_BREAKER_
Sparse circuit-breaker overrides for the local storage Redis client.
enabled
Env var: KORVET_STORAGE_LOCAL_REDIS_CIRCUIT_BREAKER_ENABLED · Type: boolean
Enable the storage Redis stream-operation circuit breaker.
log-interval
Env var: KORVET_STORAGE_LOCAL_REDIS_CIRCUIT_BREAKER_LOG_INTERVAL · Type: duration
Minimum interval between storage Redis breaker-state log lines.
open-duration
Env var: KORVET_STORAGE_LOCAL_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.local.redis.metrics. · Env prefix: KORVET_STORAGE_LOCAL_REDIS_METRICS_
Sparse metrics overrides for the local storage Redis client.
enabled
Env var: KORVET_STORAGE_LOCAL_REDIS_METRICS_ENABLED · Type: boolean
Enable command-latency metrics for the storage Redis client.
histogram
Env var: KORVET_STORAGE_LOCAL_REDIS_METRICS_HISTOGRAM · Type: boolean
Publish per-command histograms for the storage Redis client.
local-distinction
Env var: KORVET_STORAGE_LOCAL_REDIS_METRICS_LOCAL_DISTINCTION · Type: boolean
Split storage Redis metrics by local socket address.
max-latency
Env var: KORVET_STORAGE_LOCAL_REDIS_METRICS_MAX_LATENCY · Type: duration
Upper bound used when bucketing storage Redis latency samples.
min-latency
Env var: KORVET_STORAGE_LOCAL_REDIS_METRICS_MIN_LATENCY · Type: duration
Lower bound used when bucketing storage Redis latency samples.
Pool
Prefix: korvet.storage.local.redis.pool. · Env prefix: KORVET_STORAGE_LOCAL_REDIS_POOL_
Sparse pool overrides for the local storage Redis client.
max-wait
Env var: KORVET_STORAGE_LOCAL_REDIS_POOL_MAX_WAIT · Type: duration
Maximum time a caller will block waiting to borrow a storage Redis connection.
size
Env var: KORVET_STORAGE_LOCAL_REDIS_POOL_SIZE · Type: integer
Maximum number of pooled storage Redis connections.
Remote
Prefix: korvet.storage.remote. · Env prefix: KORVET_STORAGE_REMOTE_
Optional object-store remote tier settings.
path
Env var: KORVET_STORAGE_REMOTE_PATH · Type: string
Object-store path for the remote Iceberg table (e.g. s3://bucket/korvet/cold). Absent/blank disables the remote tier — Korvet runs local-only on Redis Streams.
Iceberg
Prefix: korvet.storage.remote.iceberg. · Env prefix: KORVET_STORAGE_REMOTE_ICEBERG_
row-group-size
Env var: KORVET_STORAGE_REMOTE_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_REMOTE_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.
S3
Prefix: korvet.storage.remote.s3. · Env prefix: KORVET_STORAGE_REMOTE_S3_
S3 connection settings for the remote tier object store. Only consulted when korvet.storage.remote.path starts with s3://.
access-key-id
Env var: KORVET_STORAGE_REMOTE_S3_ACCESS_KEY_ID · Type: string
Access-key id. Maps to Iceberg s3.access-key-id.
endpoint
Env var: KORVET_STORAGE_REMOTE_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_REMOTE_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_REMOTE_S3_REGION · Type: string
AWS region (e.g. us-east-1). Maps to Iceberg client.region.
secret-access-key
Env var: KORVET_STORAGE_REMOTE_S3_SECRET_ACCESS_KEY · Type: secret
Secret access key. Maps to s3.secret-access-key.
Worker
Prefix: korvet.storage.worker. · Env prefix: KORVET_STORAGE_WORKER_
Storage worker: leader-locked periodic task that rolls eligible segments, offloads sealed segments, and enforces local and remote retention.
enabled
Env var: KORVET_STORAGE_WORKER_ENABLED · Type: boolean · Default: true
Enable the storage worker. The Redis leader lock ensures at most one enabled instance runs at a time across the cluster.
lease-duration
Env var: KORVET_STORAGE_WORKER_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_WORKER_TICK_INTERVAL · Type: duration · Default: 1m
Tick cadence for the storage worker loop.
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 -
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 |
|---|---|
|
|
|
|
|
|
The exact env-var name for every property is listed in the tables above.
