Configuration Reference
Complete configuration reference for Korvet.
Configuration Properties
Server Configuration
| Property | Default | Description |
|---|---|---|
|
|
Host address to bind the server |
|
|
Port to listen on |
|
|
Broker ID for this server |
|
|
Redis keyspace prefix for all keys |
|
host |
Advertised host for clients (if not set, uses |
|
port |
Advertised port for clients (if not set, uses |
|
|
Netty boss thread pool size |
|
|
Netty worker thread pool size (0 = 2 × CPU cores) |
|
|
Maximum request size |
|
|
Maximum bytes per partition in fetch requests |
|
|
Maximum time to wait for fetch requests |
|
|
Populate segment index from existing bucket keys at startup. Useful after Redis restart or when adding a new node. Runs in background and does not block server startup. |
|
|
Automatically create topics when they don’t exist |
|
|
Default partitions for auto-created topics |
|
|
Bits for sequence number in offset encoding (1-16) |
|
|
Default time-based retention for topics |
|
|
Default size-based retention (-1 = unlimited) |
|
|
Default compression type (none, gzip, snappy, lz4, zstd) |
|
|
Default bucket duration for time-bucketed streams. Must be less than effective local retention time. Supports duration formats like |
|
|
Default compression for values at rest in Redis |
|
|
Default value storage strategy ( |
|
|
Enable remote/tiered storage by default for newly created topics |
|
inherit |
Default local-tier retention time. If unset, inherits from |
|
|
Default local-tier retention size. |
|
|
Use approximate Redis |
|
|
Delay before completing consumer group rebalance |
|
|
Maximum pending bytes before applying backpressure to producers |
|
|
Threshold for resuming reads after backpressure (should be < max-pending-bytes) |
TLS Configuration
| Property | Default | Description |
|---|---|---|
|
|
Enable TLS for the Kafka protocol endpoint |
|
none |
Server certificate file (PEM format) |
|
none |
Server private key file (PEM format) |
|
none |
Password for the private key file |
|
none |
Trusted CA certificates file (PEM format) |
|
|
Require client certificate authentication |
Redis Configuration
| Property | Default | Description |
|---|---|---|
|
none |
Redis connection URI (e.g., |
|
|
Redis host (used if URI not set) |
|
|
Redis port (used if URI not set) |
|
none |
Redis username |
|
none |
Redis password |
|
|
Enable Redis Cluster mode |
|
none |
Connection timeout |
|
|
Connection pool size |
|
indefinite |
Maximum time to wait for a connection when pool is exhausted. When the pool is full, requests will wait up to this duration before timing out. Supports duration formats like |
|
CPU cores |
Lettuce I/O thread pool size |
Redis Metrics Configuration
| Property | Default | Description |
|---|---|---|
|
|
Enable Lettuce command latency metrics |
|
|
Enable histogram buckets for percentiles |
|
|
Track metrics per connection vs per host |
|
|
Maximum expected latency for histograms |
|
|
Minimum expected latency for histograms |
Storage Configuration
Remote Tier (Delta Lake)
Cold storage is enabled automatically when korvet.server.storage.path is configured.
| Property | Default | Description |
|---|---|---|
|
none |
Delta Lake storage path (e.g., |
|
none |
AWS region (required for S3) |
|
none |
Custom S3 endpoint (for MinIO or LocalStack) |
|
|
Credential type: |
|
|
Consumer group name for cold archiver |
|
|
Messages per batch when archiving to cold tier |
|
|
Number of worker threads for reading |
|
|
Number of worker threads for writing to S3 |
See Cold Storage Configuration for complete configuration details and S3 performance tuning.
Default Configuration
The following shows the default application.yml configuration file:
# Korvet Server Configuration
#
# All properties have sensible defaults defined in code.
# Override using environment variables (e.g., KORVET_REDIS_URI) or this file.
# See docs/modules/ROOT/pages/reference/configuration.adoc for full reference.
spring:
application:
name: korvet
# Korvet Configuration
# Uncomment and modify properties to override defaults.
# korvet:
# # Main Redis (hot tier) configuration
# # Defaults: host=localhost, port=6379, pool-size=8
# redis:
# uri: redis://localhost:6379
# # Alternative: specify host/port instead of URI
# # host: localhost
# # port: 6379
# # cluster: false # Enable for Redis Cluster (OSS Cluster API)
# # username: default
# # password: secret
# # pool-size: 8
# # io-thread-pool-size: 4
#
# server:
# # Network configuration (defaults: host=0.0.0.0, port=9092)
# # host: 0.0.0.0
# # port: 9092
# # broker-id: 0
# # keyspace: korvet
# # advertised-host: localhost
# # advertised-port: 9092
#
# # Thread pool configuration
# # boss-threads: 1
# # worker-threads: 0 # 0 = use Netty default (2 * CPU cores)
#
# # Request size limits
# # max-request-size: 100MB
#
# # TLS/SSL configuration
# # tls: true
# # cert-file: /path/to/server.crt
# # key-file: /path/to/server.key
#
# # Topic defaults (used when creating new topics)
# topics:
# auto-create: true
# partitions: 1
# offset-sequence-bits: 10
# retention-time: 7d
# retention-bytes: -1 # -1 = unlimited
# compression: none
#
# storage:
# # Local Storage Configuration (Redis hot tier)
# local:
# bucketing:
# # Time-bucketed streams to avoid large stream keys.
# # Streams are rotated into time-based buckets, limiting key size.
# enabled: true # enabled by default
# duration: 10m # Typical: 5m, 10m, 30m
#
# # Remote Storage Configuration (Delta Lake cold tier)
# # When path is set, tiered storage is enabled automatically.
# # Topics with remote.storage.enable=true will use cold storage for archived data.
# remote:
# # path: s3a://my-bucket/korvet/delta # or file:///tmp/korvet
# # s3:
# # region: us-east-1
# # access-key-id: AKIA...
# # secret-access-key: ...
# # archiver: # Runs automatically when path is set
# # interval: 5m # How often to check for buckets to archive
# # batch-size: 10000 # Records per archive write
# # workers: 1 # Number of archiver threads
# Spring Boot Actuator Configuration
management:
endpoints:
web:
exposure:
include: health,info,prometheus,metrics,s3diagnostics
endpoint:
health:
show-details: always
prometheus:
metrics:
export:
enabled: true
# Logging Configuration
logging:
level:
root: INFO
com.redis.korvet: DEBUG
# Suppress Netty internal messages (native transport detection, buffer allocation, etc.)
io.netty.util.internal: WARN
io.netty.buffer: WARNEnvironment Variables
All configuration can be set via environment variables using Spring Boot’s relaxed binding:
# Server Configuration
export KORVET_SERVER_HOST=0.0.0.0
export KORVET_SERVER_PORT=9092
export KORVET_SERVER_BROKER_ID=0
export KORVET_SERVER_KEYSPACE=korvet
export KORVET_SERVER_ADVERTISED_HOST=localhost
export KORVET_SERVER_ADVERTISED_PORT=9092
# Thread pool configuration
export KORVET_SERVER_BOSS_THREADS=1
export KORVET_SERVER_WORKER_THREADS=0 # 0 = use Netty default (2 * CPU cores)
# Request size limits
export KORVET_SERVER_MAX_REQUEST_SIZE=100MB
export KORVET_SERVER_PARTITION_MAX_SIZE=1MB
# Fetch Configuration
export KORVET_SERVER_FETCH_MAX_WAIT=500ms # Maximum time to wait for fetch requests when no data is available
# Offset Encoding
# Number of bits for sequence number in offset encoding (1-16)
# Default: 10 (supports up to ~1 million messages/second per partition)
# See xref:quick-start/configuration.adoc#_offset_encoding_configuration[Offset Encoding Configuration] for details
export KORVET_SERVER_DEFAULT_OFFSET_SEQUENCE_BITS=10
# Topic Configuration
export KORVET_SERVER_AUTO_CREATE_TOPICS=true
export KORVET_SERVER_DEFAULT_PARTITIONS=1
export KORVET_SERVER_DEFAULT_RETENTION_TIME=7d
export KORVET_SERVER_DEFAULT_RETENTION_SIZE=-1 # -1 = unlimited
export KORVET_SERVER_DEFAULT_COMPRESSION=none # none, gzip, snappy, lz4, zstd
# Bucket Duration for Time-Bucketed Streams
# Must be less than effective local retention time to ensure data is archived before expiry
export KORVET_TOPICS_BUCKET_DURATION=1h # Default: 1h (supports 1h, 30m, PT1H formats)
# Consumer Group Configuration
export KORVET_SERVER_REBALANCE_DELAY=3s # Delay before completing rebalance (default: 3s)
# Backpressure Configuration
export KORVET_SERVER_MAX_PENDING_BYTES=100MB # Max pending bytes before backpressure (default: 100MB)
export KORVET_SERVER_RESUME_PENDING_BYTES=50MB # Resume threshold after backpressure (default: 50MB)
# TLS Configuration (optional)
export KORVET_SERVER_TLS=true
export KORVET_SERVER_CERT_FILE=/path/to/server.crt
export KORVET_SERVER_KEY_FILE=/path/to/server.key
export KORVET_SERVER_KEY_PASSWORD=secret
export KORVET_SERVER_TRUST_CERT_FILE=/path/to/ca.crt
export KORVET_SERVER_CLIENT_AUTH_REQUIRED=false
# Redis Connection
export KORVET_REDIS_URI=redis://localhost:6379
export KORVET_REDIS_HOST=localhost
export KORVET_REDIS_PORT=6379
export KORVET_REDIS_USERNAME=default
export KORVET_REDIS_PASSWORD=secret
export KORVET_REDIS_CLUSTER=false
export KORVET_REDIS_TIMEOUT=5s # Connection timeout (optional)
export KORVET_REDIS_POOL_SIZE=8 # Connection pool size (default: 8)
export KORVET_REDIS_IO_THREAD_POOL_SIZE=4 # Lettuce I/O thread pool size (default: number of CPUs)
# Redis Metrics (optional)
# Enables Lettuce command latency metrics published to Micrometer
export KORVET_REDIS_METRICS_ENABLED=false # Default: false
export KORVET_REDIS_METRICS_HISTOGRAM=false # Default: false
export KORVET_REDIS_METRICS_LOCAL_DISTINCTION=false # Default: false
export KORVET_REDIS_METRICS_MAX_LATENCY=5m # Default: 5m
export KORVET_REDIS_METRICS_MIN_LATENCY=1ms # Default: 1ms
# Remote Storage (optional) - enabled when path is set
export KORVET_SERVER_STORAGE_PATH=s3a://my-bucket/korvet/delta
export KORVET_SERVER_STORAGE_S3_REGION=us-east-1
export KORVET_SERVER_STORAGE_S3_ENDPOINT=http://localhost:4566 # Optional: for LocalStack/MinIO
export KORVET_SERVER_STORAGE_S3_CREDENTIALS_TYPE=iam # or 'static'
export KORVET_SERVER_STORAGE_S3_CREDENTIALS_ROLE_ARN=arn:aws:iam::123456789012:role/KorvetReaderRole
# For static credentials:
export KORVET_SERVER_STORAGE_S3_CREDENTIALS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export KORVET_SERVER_STORAGE_S3_CREDENTIALS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# S3 Performance Tuning (optional)
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_MAX_CONNECTIONS=96 # Default: 96
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_MAX_THREADS=64 # Default: 64
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_READAHEAD_RANGE=256K # Default: 256K
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_INPUT_POLICY=normal # normal, sequential, random
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_FAST_UPLOAD=true # Default: true
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_FAST_UPLOAD_BUFFER=disk # disk, bytebuffer, array
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_FAST_UPLOAD_ACTIVE_BLOCKS=8 # Default: 8
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_BLOCK_SIZE=64M # Default: 64M
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_MULTIPART_SIZE=64M # Default: 64M
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_CONNECTION_TIMEOUT=15000 # ms, Default: 15000
export KORVET_SERVER_STORAGE_S3_PERFORMANCE_SOCKET_TIMEOUT=60000 # ms, Default: 60000
# Cold Tier Archiver Configuration (optional, used when storage path is set)
export KORVET_SERVER_STORAGE_ARCHIVER_CONSUMER_GROUP=korvet-archiver # Default: korvet-archiver
export KORVET_SERVER_STORAGE_ARCHIVER_BATCH_SIZE=10000 # Default: 10000
export KORVET_SERVER_STORAGE_ARCHIVER_BLOCK_DURATION_MS=100 # Default: 100
export KORVET_SERVER_STORAGE_ARCHIVER_READ_WORKERS=1 # Default: 1
export KORVET_SERVER_STORAGE_ARCHIVER_COMMIT_WORKERS=4 # Default: 4
export KORVET_SERVER_STORAGE_ARCHIVER_MAX_BATCHES_PER_COMMIT=10 # Default: 10
export KORVET_SERVER_STORAGE_ARCHIVER_FILES_PER_COMMIT=10 # Default: 10
export KORVET_SERVER_STORAGE_ARCHIVER_STREAM_REFRESH_INTERVAL_MS=30000 # Default: 30000
# Logging
export LOGGING_LEVEL_COM_REDIS_KORVET=DEBUG
