Cloud Disk Configuration & Tuning | Tigris Object Storage Documentation

On this page

This page covers the settings most worth knowing and when to change them.

Beta

Cloud Disk is in beta and under active development.

Settings are stored with the disk and apply wherever it's mounted. Change them any time:

cloud-disk config mydata set flush-workers=16

cloud-disk config mydata show

cloud-disk config mydata unset flush-workers

While a disk is mounted, performance settings apply immediately, and config set tells you which ones; the rest take effect on the next mount. The defaults cover most deployments, so you'll usually change only a few of these.

At create time

Option Example Description
-size 100G Disk size (500M, 1G, 2T). Sparse — only written data costs storage.
-fstype xfs Filesystem for the disk: ext4 (default), xfs, btrfs.
--set key=value Apply any setting below at create time (repeatable).
--no-mount Create only; don't mount.

Performance — the high-impact knobs

Setting Default When to raise it
max-cache-size 1G The in-RAM cache. Raise it so your working set fits — fewer reads go to Tigris. For read-heavy workloads, a meaningful fraction of RAM (4G, 16G).
flush-workers 8 Concurrent uploads to Tigris. Raise (16–32) for write-heavy workloads.
read-ahead-workers, read-ahead-max-window 4 / auto Prefetching for sequential reads. Raise the window for streaming / scan-heavy workloads; set workers to -1 to disable prefetching.
connections CPU count Parallel device connections. Usually leave alone; lower it on small machines sharing many disks.

Local disk cache

A cache on local disk (SSD) between RAM and Tigris: reads that miss the RAM cache are served from local disk instead of Tigris, and write-back uses it to buffer writes.

Setting Default Description
disk-cache-path /var/lib/cloud-disk Local directory for the cache and write-back buffer. Each disk uses its own subdirectory, so one path is safe to share (and to inherit on forks).
disk-cache-size 0 How much local disk the read cache may use, e.g. 4G, 100G. 0 (the default) turns the read cache off while keeping write-back buffering; size it to your working set for the biggest read speedup.

Cache warming on mount

On mount the disk preloads its index and the data at the start of the disk into cache, so the first reads are fast instead of all going to Tigris. This happens in the background — it never delays the mount; the disk serves immediately and warming fills the cache as it runs. Both are on by default and self-limiting — warming never loads more than your cache can hold, counting the RAM cache (max-cache-size) and the local disk cache (disk-cache-size) together.

Setting Default When to change
warm-start-bytes 1G How much data from the start of the disk to preload into cache on mount (unwritten regions are skipped). Capped to the combined RAM + local-disk cache size, so it never evicts what it just loaded. Lower it to reduce background fetching after mount; 0 preloads no data (the index is still prewarmed — see below).
prewarm-region-map true Preload the disk's index up front so reads don't pause for lookups. Cheap — leave on. Set false on a very large disk to skip it.

Write-back

Write-back buffers writes locally and uploads in the background — much faster. Everything is flushed to Tigris on unmount.

Setting Default Effect
write-back true On by default. Set false for write-through (every fsync lands in Tigris before returning).
max-staging-bytes 1G Write buffer budget. Raise (16G) for bursty write-heavy workloads.
max-dirty-ratio 0.5 How full the cache gets before background uploading starts. Lower = upload sooner.
sync-writeback-ratio 0.8 How full the cache gets before writes pause for the upload to catch up. 0 disables.

Unmount durability

What a clean unmount does with buffered data before finishing, via shutdown-mode:

Mode Behavior
remote (default) Upload everything to Tigris — the bucket is the complete disk. Safest; slowest unmount.
local Save to local disk only; the next mount finishes the upload. Faster unmount.
dirty Exit fast. For quick restarts on the same machine.
ship-wal Like remote, plus uploads the recovery log for another machine to take over.

Reliability

Setting Default When to change
retry-max-retries 30 How many times object-store operations retry before reporting an error. The default rides out ~2 minutes of unavailability.
nbd-request-timeout kernel default (~30s) How long a single disk I/O may take before the kernel gives up on it. Raise (600s) for slow links or heavily loaded disks.

Filesystem & mount

Setting Default Description
fstype ext4 Filesystem created on first mount (ext4, xfs, btrfs).
mount-point /mnt/cloud-disk/<disk> Where the disk is mounted. Set it on a fork so parent and fork can be mounted together.
mount-opts — Extra mount options, e.g. noatime.
readonly off true mounts the disk read-only.

Observability

Setting Default Description
metrics-addr — Expose Prometheus metrics, e.g. :9090.
stats-interval — Log periodic throughput/latency stats, e.g. 10s.
log-file, log-format /var/log/cloud-disk-<disk>.log / console Log destination and format (console or json).

Example: tuned for a database

sudo -E cloud-disk create pg-data -size 200G \

--set disk-cache-size=100G \

--set max-cache-size=16G \

--set flush-workers=16 \

--set max-staging-bytes=16G \

--set metrics-addr=:9090