Skip to content

Storage capacity and overcommit

Updated

Instance disks in Virtainer Free are thin: a disk takes space on the storage only as its guest writes to it. A cloud image that declares a 5 GB disk may hold only 2 GB on the host. That makes disks fast to create and cheap to keep, but it also means the disks on a host can together declare more than the storage holds. That is overcommit.

Overcommit is normal and usually safe: most guests never fill their disks. It becomes a problem only when the disks grow past the free space. For example, forty instances from that 5 GB image take 80 GB on a 100 GB disk but declare 200 GB. Everything works until each guest writes another 1 GB: then the storage is full, while every guest still believes it has room.

Storage → Provisioned capacity shows one ledger per filesystem that holds instance disks (usually just the storage pool), and the host total:

Line Meaning
Physical size The size of the filesystem.
Allocated by disks Space the instance disks already take.
Other files Everything else on the filesystem: base images, metadata and any other files.
Free Space not used by anything.
Provisioned The sum of the sizes the disks declare to their guests.
Remaining growth How much more the disks can take before every one of them is full.
Overcommit Provisioned divided by physical size. Above 1.00× the disks declare more than the storage holds.

When remaining growth is larger than free space, the card shows a warning: the storage would fill up before the disks do.

The Dashboard shows the host’s provisioned total and overcommit ratio under the Disk card.

The same numbers are in the REST API: GET /api/storage/usage (field provisioned) and GET /api/capacity (storage_provisioned_bytes, storage_physical_bytes, storage_overcommit_limit).

Diagnosis checks every filesystem that holds instance disks and reports in Logs & Diagnostics and in the notification bell:

  • Warning when the disks can grow past the free space.
  • Critical when that is the case and either free space is below 10% of the filesystem or the disks can grow by more than twice the free space.
  • Critical when the storage is full (less than 1 GiB free). The finding names the storage and the instances whose disks are on it.

When you create an instance, create or grow a volume, or grow a root disk, the form tells you if the new disk would make the disks declare more than the storage holds. That warning alone does not reject a request. The separate free-space check below still applies, and an enabled provisioned-capacity limit can also refuse it.

Even with the overcommit limit off, each new disk request or growth increment must fit the physical free space available after subtracting space reserved by work already in progress. A request exceeding that amount is refused with HTTP 409. Turning off the ratio limit does not turn off this check.

For example, if 60 GiB is available after accounting for in-progress work, a request for 70 GiB of new disk capacity is refused. Several 20 GiB thin-disk requests can still pass one after another while each fits the updated available space, even if their total promised capacity eventually exceeds the filesystem’s physical size. Each request must pass both checks when the optional ratio limit is enabled.

Storage → Provisioned capacity → Set one (or Change) sets a hard limit on the ratio for the whole host. It is off by default. With a limit set, Virtainer refuses (HTTP 409) any new instance, volume, disk growth or import that would push provisioned capacity past that multiple of the physical storage. Existing disks are never touched. A limit of 1 rejects new promises above the physical size; it does not shrink disks already provisioned. Values from 0.1 to 100 are accepted.

The limit is off by default because a ratio above 1 is normal on a host full of cloud images, and the warnings above follow what the guests actually write. A limit reduces additional promises; it does not guarantee that guest writes can never fail. Snapshots, images and other files also consume physical space, so continue watching free space and diagnosis findings.

When the storage is full, writes from guests fail: each guest sees disk I/O errors on the disk it was writing to. Do not rely on an instance pausing to protect its data. A guest may remount the affected filesystem read-only or stop applications that write.

To recover, free space first: delete snapshots, unused volumes or instances, or grow the storage pool. Then restart the affected instances; a guest that hit write errors may need a filesystem check.