Configuration
Broker and topic settings for diskless storage.
Diskless storage is configured almost entirely through broker-level server.properties, plus one topic-level flag that turns it on for a given topic. Keys and defaults below are transcribed from the project's configuration reference — treat them as exact.
Broker settings
These apply cluster-wide. A broker started with ursa.storage.enable=false, the default, behaves exactly like upstream Kafka.
| Property | Default | Description |
|---|---|---|
ursa.storage.enable | false | Master toggle for Ursa storage mode |
ursa.storage.topic.default.enable | false | Enable diskless storage for topics by default |
ursa.storage.oxia.service.url | localhost:6648 | Oxia service URL for metadata |
pulsar.oxia.service.url | oxia://localhost:6648/default | Oxia metadata store URL for Pulsar-managed ledger metadata (format: oxia://host:port/[namespace]) |
ursa.oxia.service.url | oxia://localhost:6648/default | Oxia metadata store URL for Ursa storage metadata (format: oxia://host:port/[namespace]) |
ursa.storage.backend.type | LOCAL | Storage backend: LOCAL, S3, GCS, AZURE_BLOB (AZUREBLOB also accepted for compatibility) |
ursa.storage.path | /tmp/ursa-data | Local storage path for LOCAL, or the remote object prefix for S3/GCS/Azure Blob |
ursa.storage.compaction.prefix | /tmp/compaction-data | Compaction output prefix for remote object storage backends |
ursa.storage.namespace | default | Namespace for Ursa streams |
ursa.storage.wal.directory | /tmp/ursa-wal | Write-ahead log directory |
ursa.storage.write.buffer.flush.interval.ms | 250 | Write buffer flush interval |
ursa.storage.write.buffer.size | 4194304 (4MB) | Size of each WAL write buffer segment |
ursa.storage.write.buffer.flush.size | 268435456 (256MB) | Write buffer flush size threshold |
ursa.storage.producer.state.snapshot.interval.ms | 30000 | Periodic interval (ms) for producer-state snapshot; <= 0 disables time-based snapshot |
ursa.storage.producer.state.snapshot.record.threshold | 10000 | Number of appended records that triggers a producer-state snapshot; <= 0 disables threshold-based snapshot |
ursa.storage.s3.endpoint | "" | Remote object storage endpoint URL; reused as an endpoint override for GCS/Azure-compatible deployments |
ursa.storage.s3.bucket | kafka-ursa-storage | Remote object storage bucket or container name; reused for GCS/Azure backends |
ursa.storage.compaction.bucket | kafka-ursa-storage | Remote object storage bucket or container name for compaction output |
ursa.storage.s3.region | us-east-1 | Remote object storage region, when the selected backend uses one |
ursa.storage.s3.access.key | "" | S3 access key |
ursa.storage.s3.secret.key | "" | S3 secret key |
socket.server.enable.request.pipelining | false | Allow multiple in-flight requests per connection; preserves response order but reduces latency amplification for diskless produces |
Three separate settings point at Oxia because three different things read from it. ursa.storage.oxia.service.url is the general endpoint the diskless storage layer uses for metadata. pulsar.oxia.service.url configures Oxia for Pulsar's own managed-ledger metadata, since the write and read paths underneath diskless storage are built on Pulsar's ManagedLedger abstraction. ursa.oxia.service.url is the endpoint Ursa's storage engine uses for its own stream and log metadata. By default all three point at the same local Oxia instance, just in different URL formats.
socket.server.enable.request.pipelining defaults to false for conservative memory behavior, but is recommended true whenever diskless topics are enabled — see diskless architecture for why the write-buffer flush interval makes it matter.
Topic settings
| Property | Default | Description |
|---|---|---|
ursa.storage.enable | false | Enable diskless mode for this topic |
Set at topic creation, via kafka-topics.sh --create --config ursa.storage.enable=true. Two constraints apply: replication factor must be 1 — the controller enforces this for diskless topics — and the flag can't be changed on an existing topic. Moving a topic between diskless and classic storage means creating a new topic and migrating data into it, not editing the config. Internal topics (__consumer_offsets, __transaction_state) are excluded from diskless mode regardless of this setting.
A minimal diskless broker config
The settings below are enough to point a broker at real S3; everything else can stay at its default.
ursa.storage.enable=true
ursa.storage.backend.type=S3
ursa.storage.s3.bucket=kafka-ursa-storage
ursa.storage.s3.region=us-east-1
ursa.storage.s3.access.key=<your-access-key>
ursa.storage.s3.secret.key=<your-secret-key>Pair this with socket.server.enable.request.pipelining=true once diskless topics are actually taking traffic. See limitations for what this configuration still doesn't cover.