{
    "product": "Cenvero Stratum",
    "generated_at": "2026-11-16T13:19:23+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "compute/storage-pools",
            "title": "Storage Pools",
            "category": "Compute",
            "url": "https://stratum.cenvero.com/docs/compute/storage-pools",
            "headings": [
                {
                    "level": 1,
                    "text": "Storage Pools"
                },
                {
                    "level": 2,
                    "text": "The kinds of pool"
                },
                {
                    "level": 2,
                    "text": "Directory pools"
                },
                {
                    "level": 2,
                    "text": "Block pools"
                },
                {
                    "level": 3,
                    "text": "What to set up on the host"
                },
                {
                    "level": 3,
                    "text": "Creating a block pool"
                },
                {
                    "level": 3,
                    "text": "Which kinds this node offers"
                },
                {
                    "level": 2,
                    "text": "What works on a block pool"
                },
                {
                    "level": 2,
                    "text": "What does not work on a block pool"
                },
                {
                    "level": 2,
                    "text": "Room and quotas"
                },
                {
                    "level": 2,
                    "text": "Deleting a pool, and watching it"
                },
                {
                    "level": 2,
                    "text": "In the console"
                },
                {
                    "level": 2,
                    "text": "Installing the pools with the installer"
                },
                {
                    "level": 2,
                    "text": "See also"
                }
            ],
            "word_count": 1637,
            "markdown": "# Storage Pools\n\nA **pool** is a place on the node where volumes and backups are kept. Every node\nhas a **default pool**, which holds the machines' disks and every volume and backup\nmade before pools existed. You can add more: a **directory pool** on the node's own\ndisk, or a **block pool** on storage the host already has.\n\n> Part of [Compute](/docs/compute/overview), in early access. Changing pools needs a\n> licence that includes Storage (a Compute licence includes it) and is not frozen.\n> Reading them always works.\n\n## The kinds of pool\n\n| Kind | Where its volumes are kept | What the host needs first |\n|---|---|---|\n| Default | The node's storage area, which every node has | Nothing |\n| Directory (`dir`) | A directory the node makes inside its storage area | Nothing. To add space, mount a disk on the directory |\n| Block, thin-provisioned (`thin-provisioned`) | Thin volumes in a thin pool of an LVM volume group | The thin pool, with the LVM tools |\n| Block, ZFS (`zfs`) | Volumes in a ZFS pool, or in a dataset of one | The ZFS pool or dataset, with the ZFS tools |\n\n## Directory pools\n\n`storage pool create --name fast` makes a directory pool called `fast`. The name is 1 to\n63 lowercase letters, digits and hyphens, and it cannot start or end with a hyphen.\n`--location` names the directory when it should differ from the name; it is one name,\nwith no slashes.\n\nThe directory must be missing or empty when the pool is made, so a pool never takes over\nfiles it did not make. To add space to a directory pool, mount a filesystem on its\ndirectory.\n\nA directory pool on a shared filesystem, such as an NFS export, can be declared shared\nbetween the members of a cluster. See [Shared Storage Pools](/docs/clustering/shared-pools).\n\n## Block pools\n\nA block pool keeps its volumes on storage the host already has. The node asks the host's\nown tools for each volume. You set that storage up first, and the node checks it before\nit records the pool. The node never creates it.\n\n### What to set up on the host\n\n- **Thin-provisioned.** A thin pool inside an LVM volume group. The pool must be active\n  and healthy, with room left in it. The LVM tools must be installed (the `lvm2` package\n  on Debian and Ubuntu). Its location is the group and the pool, written `group/pool`.\n\n  ```bash\n  # A thin pool called pool, in the volume group vg0, that takes all of the group's free space\n  sudo lvcreate --type thin-pool --extents 100%FREE --name pool vg0\n  ```\n\n- **ZFS.** A ZFS pool, or a dataset in one. The pool must be healthy and have free space.\n  The ZFS tools must be installed (`zfsutils-linux` on Debian and Ubuntu; on Debian the\n  ZFS module comes from the contrib component, which must be enabled). Its location is\n  the pool's name, or the pool and the dataset written `pool/dataset`.\n\n  ```bash\n  # A dataset called vm in the existing ZFS pool tank, for the node's volumes\n  sudo zfs create -p tank/vm\n  ```\n\n### Creating a block pool\n\n```bash\ncenvero-str-ctl storage pool create --name thin-pool --backend thin-provisioned --location vg0/pool\ncenvero-str-ctl storage pool create --name zfs-pool --backend zfs --location tank/vm\n```\n\nOver the API, `POST /api/v1/storage/pools` takes the same three fields, and the\n[API page](/docs/api#storage-pools) gives the answers. The node refuses a location it\ncannot use, and says why:\n\n- A location in the wrong form: \"a thin-provisioned pool's location is its group and pool\n  name, written as group/pool; a ZFS pool's location is its pool name, or pool/dataset\".\n- A location the host does not have: \"the storage location of this pool does not exist on\n  this node: check its name, or create it first\".\n- A location that is not healthy: \"the storage location of this pool is not healthy on this\n  node, so it cannot be used: check it, then try again\".\n\n### Which kinds this node offers\n\nA block pool is in service only while the node has the tools for its kind. `storage pool\nlist` shows each kind and whether this node can use it now, under `backends`. A tool\ninstalled later is used at once, without a restart.\n\nOn a node without the tools, creating a pool of that kind answers \"this kind of pool is\nnot available on this node\" (**501** over the API). A block pool recorded earlier, whose\ntools have since gone, shows as unreadable, and changes to it are refused until the tools\nare back.\n\n## What works on a block pool\n\n- **Volumes.** Create one with `volume create --pool`, attach and detach it, and grow it\n  with `volume resize`. A volume cannot shrink.\n- **Snapshots.** Take and delete snapshots as on any volume. Going back to a snapshot\n  discards what was written since, and the volume keeps its size, which a revert could\n  otherwise shrink. A machine that uses the volume must be stopped first, or the volume\n  detached.\n- **Backups, in full.** A backup of a volume on a block pool is a full backup, and it is\n  written to the default pool. That pool must have room for the whole volume, and the node\n  checks the room before the backup starts. [Snapshots, backups and\n  schedules](/docs/compute/backups) describes the rest.\n- **Restores.** A restore into a new volume makes the volume the size of the backup. An\n  in-place restore needs the machine stopped or the volume detached, and the backup must be\n  exactly the size of the volume. Otherwise the node says: \"the backup is not the size of\n  this volume, so it cannot be restored in place: restore it into a new volume\".\n- **Templates.** A template is copied to a block pool once, the first time a machine is made\n  there from it. Every machine made from that template on the pool after that is a linked\n  clone of the copy, so it starts at once and takes little space at first. A template with\n  machines on a pool cannot be deleted. [Templates and clones](/docs/compute/templates)\n  describes the rest.\n- **Full clones.** A stopped machine's boot disk can be copied in every direction: from a\n  directory pool to a block pool, from a block pool to a directory pool, or from one block\n  pool to another. Over the API, the clone's `pool` names the pool its boot disk is kept on.\n  On the command line, `vm clone --pool` keeps the clone's boot disk on that pool, and the\n  default pool is used when it is left out.\n- **Machines.** `vm create --pool` makes a machine whose boot disk is a volume on the pool,\n  from an image or from a template. Removing a machine whose disk is on a block pool needs\n  the storage feature in the licence.\n- **Templates from machines.** A stopped machine whose boot disk is on a block pool can be\n  made into a template as usual. The template is a copy in the node's image store, so it can\n  then be placed on any pool.\n\n## What does not work on a block pool\n\n- **Incremental backups.** A block volume takes only full backups, and an automatic backup of\n  one is a full backup too. An incremental backup, or a schedule of incremental backups, is\n  refused with \"an incremental backup is not available on a thin-provisioned or ZFS pool yet:\n  take a full backup, or keep the volume on a directory pool\".\n\n## Room and quotas\n\n- A new ZFS volume takes its full size from its pool when it is made, so a ZFS pool needs that\n  much free space. A thin-provisioned volume takes space as it is written.\n- Set a `pool_used` alert on every thin-provisioned pool, for example at 80%: the pool can fill\n  as its machines write, and a full pool pauses the machines that are writing to it.\n- Before a create, a copy, a restore or a backup starts, the node checks that the pool has the\n  room the work needs. A full pool refuses the work with \"the storage pool is full: free some\n  space, or add a pool\".\n- A restore of copies read back from a backup target needs room for those copies as well as\n  for the new volume. The node holds the room the copies take in the pool each one is written\n  to, from the start of the fetch until it ends. Another create, copy, restore or backup that\n  does not fit beside that room is refused until the fetch ends.\n- A machine's boot disk is not counted against a tenant's volume quota, on any pool. Data\n  volumes are counted. [Current limits](/docs/compute/limits) lists the quotas.\n\n## Deleting a pool, and watching it\n\n- A pool that still holds volumes cannot be deleted, and the default pool cannot be deleted at\n  all. The node answers \"this pool still holds volumes: move or delete them first\".\n- Deleting a block pool removes the node's record of it. The thin pool or ZFS dataset on the\n  host is left as it was.\n- The node reads each block pool's free space on every poll. The `pool_used` condition in\n  [Monitoring](/docs/monitoring#what-a-condition-can-watch) watches the share of a pool in use,\n  for directory and block pools alike.\n\n## In the console\n\nOn the node's **Storage** page, the **Pools** tab lists every pool with its kind, state, size\nand use. **Create a pool** says which kinds this server cannot use.\n\n## Installing the pools with the installer\n\nOn a new server, the installer can check or create a thin-provisioned pool and a ZFS pool for\nyou. See [Storage pools at install](/docs/compute/overview#storage-pools-at-install).\n\n## See also\n\n- [Snapshots, backups and schedules](/docs/compute/backups)\n- [Templates and clones](/docs/compute/templates)\n- [Creating virtual machines](/docs/compute/virtual-machines)\n- [Current limits](/docs/compute/limits)\n"
        }
    ]
}