Storage and disks

Disk types

Create and inspect a PersistentDisk

cats disk create project-data --size 20GiB
cats disk ls
cats disk get project-data

Create a Cat and an independent disk together:

cats create dev \
  --disk project-data \
  --disk-size 20GiB \
  --mount-at /data

Mount and unmount

cats mount project-data --cat dev --at /data
cats unmount project-data

A mount creates a runtime Attachment with a monotonically increasing fencing epoch. Unmount syncs and detaches before returning the disk to Available. V1 rejects a second read-write attachment even when it targets different logical blocks—the ext4 filesystem itself is single-writer.

Grow a disk

cats disk resize project-data --size 40GiB

V1 supports growth only. Follow the API error if the disk must be Available before resizing in the selected runtime path. Never shrink the backing volume under ext4.

Create a snapshot

cats disk snapshot project-data

The control plane first establishes a durable barrier, then records an immutable root and generation. The current CLI creates and prints the snapshot response; snapshot list/restore convenience commands are not yet exposed by this source CLI.

Durability and cache semantics

The Guest sees standard virtio block devices. Normal writes may complete in managed local cache, but FLUSH/FUA success requires immutable objects to be durable and the authoritative root CAS to succeed. After that point local NVMe is only a deletable cache.

• A small dirty working set does not upload the full sparse disk.
• Empty-cache recovery lazily downloads only the logical chunks read by ext4.
• A stale attachment epoch cannot publish a new root.
• Unflushed Guest page cache or ordinary writes may be lost on permanent host failure.

Delete safely

cats unmount project-data
cats disk delete project-data