Managing storage with Incus: pools and volumes

Read this page in French

In Incus, all storage rests on two objects: pools (the data reservoirs, based on dir, ZFS, btrfs or LVM) and volumes (the storage units inside them). This guide shows how to list, create and inspect pools, manage custom volumes, choose the right backend, and why ZFS changes everything for snapshots. Everything was tested on Incus 7.0. For anyone who wants their instance data organised properly.

What you will learn

• The concepts: pool, volume, snapshot.
• List and inspect storage pools.
• Create a pool and choose its backend.
• Manage custom volumes and attach them to an instance.

The concepts in brief

Three notions structure Incus storage.

• A pool is the reservoir where Incus keeps instance disks and volumes. It rests on a backend: dir (a plain directory), ZFS, btrfs, LVM or Ceph.
• A volume is a storage unit inside a pool. Every instance has its disk volume; you can also create custom volumes to share data.
• A snapshot freezes the state of a volume at a point in time, so you can step back if something goes wrong.

Listing and inspecting pools

At initialisation, incus admin init created a default pool. You find it with:

incus storage list
incus storage show default

config:
  source: /var/lib/incus/storage-pools/default
name: default
driver: dir
used_by:
  - /1.0/instances/c1
  - /1.0/instances/vm1

Here the default pool uses the dir backend and already serves two instances (c1, vm1).

Creating a storage pool

You create a pool with incus storage create <name> <backend>. The simplest, dir, works everywhere:

incus storage create data dir
# Storage pool data created

For a ZFS or btrfs backend, the matching tools have to be installed on the host, otherwise Incus refuses:

incus storage create fast zfs
# Error: Required tool 'zpool' is missing

Install the backend you want

Before creating a ZFS or btrfs pool, install the packages: apt install zfsutils-linux (ZFS) or apt install btrfs-progs (btrfs). Likewise lvm2 for LVM. The dir backend needs nothing.

Choosing the right backend

The backend decides both performance and features (fast snapshots, compression).

Backend	Fast snapshots	When to choose it
dir	no (a copy)	tests, simplicity, no prerequisites
ZFS	yes	recommended: instant snapshots and clones, compression
btrfs	yes	alternative to ZFS, built into the kernel
LVM	yes (block level)	block volumes, existing LVM infrastructure
Ceph	yes	distributed cluster storage

Glissez pour voir

For serious use, ZFS is the reference choice: its snapshots and clones are near instant and only occupy the differences. dir stays perfect for learning or for a lab.

ZFS on a loopback file never shrinks

Instead of a dedicated disk or dataset, incus admin init can create a ZFS pool on a loopback file. The trap, learned the hard way: that file grows up to its limit but never shrinks, even after deleting instances or images. You can enlarge it (incus storage set <pool> size=...) but not reduce it. In production, prefer a dataset or a dedicated disk over the loopback.

Managing custom volumes

Beyond instance disks, you create custom volumes to store data independently, for example to share between instances:

incus storage volume create data vol1
incus storage volume list data

+--------+-------+--------------+---------+
|  TYPE  | NAME  | CONTENT-TYPE | USED BY |
+--------+-------+--------------+---------+
| custom | vol1  | filesystem   | 0       |
+--------+-------+--------------+---------+

You then attach that volume to an instance, at a given mount point:

incus storage volume attach data vol1 c1 /mnt/data

The vol1 volume becomes reachable at /mnt/data inside the c1 container. Since it lives in the pool and not inside the instance, it survives the container being deleted.

Volume snapshots

Like instances, volumes can be snapshotted:

incus storage volume snapshot create data vol1 before-update
incus storage volume snapshot list data vol1

On a ZFS or btrfs pool those snapshots are instant and cheap; on dir they rest on a full copy.

Key points

• Incus storage is organised in pools (reservoirs) and volumes (units inside them).
• incus storage list and show inspect pools; incus storage create creates one.
• The ZFS, btrfs and LVM backends need their tools installed, otherwise Required tool missing.
• ZFS is recommended for its instant snapshots and clones; dir for simplicity.
• A custom volume attaches to an instance and survives its deletion.

FAQ: common questions about Incus storage

Which storage backends does Incus support?

Incus supports several backends for its pools: dir (a plain directory, no prerequisites), ZFS, btrfs, LVM and Ceph for distributed cluster storage. ZFS is the most recommended for its instant snapshots and clones. The dir backend suits tests and labs.

Which storage backend should you choose for Incus?

ZFS is the reference choice: its snapshots and clones are close to instant and only occupy the differences. btrfs is a kernel-integrated alternative. LVM suits an existing block infrastructure, Ceph suits distributed cluster storage.

Why does Incus refuse to create a pool with Required tool missing?

Because the chosen backend (ZFS, btrfs or LVM) needs its command-line tools on the host. Without them Incus returns, for example, Required tool zpool is missing. Install the matching packages: zfsutils-linux for ZFS, btrfs-progs for btrfs, lvm2 for LVM.

How do you share a volume between several Incus instances?

You create a custom volume in a pool with incus storage volume create, then attach it to each instance with incus storage volume attach, giving a mount point.

Next steps

• Shared CephFS storage: what storage becomes when instances move between cluster nodes.
• Terraform provider: declare pools and volumes as code to replay the same storage on another server.
• Securing Incus: cap the space consumed per instance or per project, before a container saturates the pool.

×

📖 Voir la documentation →