lvm_logical_volume
lvm_logical_volume manages one LVM logical volume on the node: a virtual
disk inside a volume group, which a later run can grow. The module runs
the programs of the package lvm2, such as lvcreate and lvextend.
The module creates a volume, grows the volume together with the volume's
filesystem, and never shrinks the volume.
- lvm_logical_volume:
name: postgresql
volume_group: data
size: 50GiB
grow_filesystem_with_volume: true
- create_filesystem_on_empty_device:
device: /dev/data/postgresql
filesystem_type: ext4
lvm_volume_group makes the volume group
first.
Set up
Install the package lvm2, which has the same name on every distribution.
No service has to be started.
- when: {equals: ["{{ .node.package_manager }}", apt]}
apt_package: {packages: [{name: lvm2, version: newest_when_first_installed}]}
- when: {equals: ["{{ .node.package_manager }}", dnf]}
dnf_package: {packages: [{name: lvm2, version: newest_when_first_installed}]}
To grow a filesystem with its volume, LVM runs the filesystem's own
programs, which the filesystem's package brings: e2fsprogs for ext2,
ext3, and ext4, and xfsprogs for xfs. The module also runs wipefs from
the package util-linux, which every node has.
Inputs
| Input | Meaning | When omitted |
|---|---|---|
name |
The logical volume's name: 1 to 127 letters, digits, +, _, ., and -. |
Required. |
volume_group |
The name of the volume group that holds the logical volume. | Required. |
state |
present or deleted_with_all_its_data. deleted_with_all_its_data accepts only name and volume_group. |
present |
size |
A whole number and MiB, GiB, or TiB, such as 50GiB, or all_free_space_when_created. |
Required for present. |
grow_filesystem_with_volume |
true: when the module grows the volume, LVM also grows the ext2, ext3, ext4, or xfs filesystem on it. A volume that holds nothing yet grows alone. A volume that holds anything else, such as swap, fails the task and is not grown. false: only the volume grows; for a volume that holds something else, such as swap. |
Required for state: present. |
lvcreate_options |
More options for lvcreate when the volume is created, as a list, such as ["--type", "raid1", "--mirrors", "1"]. Not used for a volume that exists. The module writes the options for the name, the size, and --yes --wipesignatures y itself. |
No more options. |
With state: present:
- A missing volume is created with that size. LVM rounds a size up to
whole extents of the volume group, which are 4 MiB unless the volume
group was made with another size:
50MiBgives a volume of 52 MiB.all_free_space_when_createdgives the new volume all free space. - A smaller existing volume grows to
size, and the filesystem on it grows with it (lvextend --resizefs), mounted or not. The module first looks withwipefs --no-actwhether the volume holds an ext2, ext3, ext4, or xfs filesystem. A volume that holds nothing yet grows alone, and the reason says so. A volume that holds anything else fails the task and is named with what it holds. Withgrow_filesystem_with_volume: falseonly the volume grows. - An existing volume of that size is unchanged. The module compares
after the rounding. With
all_free_space_when_created, an existing volume is unchanged whatever its size. - A larger existing volume fails the task. The module never shrinks a volume, because that destroys the data behind the new end.
A filesystem grows only together with its volume. When the volume
already has its size, the module changes nothing, also when the filesystem
on it is smaller. That happens after a run with
grow_filesystem_with_volume: false, or after someone grew the volume by
hand. For a mounted ext4 or XFS filesystem, use
grow_filesystem_to_fill_device.
For an ext2 or ext3 filesystem, grow the filesystem by hand with
resize2fs /dev/data/postgresql.
With state: deleted_with_all_its_data, the module deletes the volume
(lvremove --yes) and everything on it. It deletes only the volume that
the task names:
- A volume in use, such as one with a mounted filesystem, fails the task.
- A volume that other volumes depend on fails the task, which names them: a volume with snapshots, and a thin pool with the volumes in it. LVM would delete them together with the volume. Delete each of them first, with its own task.
- A volume that does not exist is unchanged.
Outputs
| Output | Meaning |
|---|---|
created |
true when the task created the volume, and in a dryrun when a run would create it. Otherwise false. |
device |
The volume's path, /dev/<volume_group>/<name>, such as /dev/data/postgresql. Not given for deleted_with_all_its_data. |
A later node task reads created and device as
.node_tasks.<id>.created and .node_tasks.<id>.device.
What a dryrun reports
would_changewith what a run would do:would create the logical volume data/postgresql with 50 GiB,would grow the logical volume data/postgresql from 50 GiB to 80 GiB, together with the filesystem on it, orwould delete the logical volume data/postgresql with all its data (50 GiB). For a volume that holds nothing yet, the reason ends withand no filesystem, because the volume holds none yet.unchangedwhen the volume has its size.- A failure, with the same reason as in a run, for a volume that is
larger than
size, and for a volume that should grow together with its filesystem and holds something other than an ext2, ext3, ext4, or xfs filesystem. No node task changes such a state. not_checkedfor a state that an earlier node task of the same playbook may change, because in a dryrun that task has changed nothing yet: while a program oflvm2is missing, while the volume group does not exist or has too little free space, and fordeleted_with_all_its_datawhile the volume is in use or other volumes depend on it. A run fails once with the same reason.- What a dryrun cannot know: whether the filesystem's own program will
succeed, such as
resize2fsfor a filesystem that is mounted read-only. The run then fails after the volume grew, and says so. - What its reads leave on the node:
vgsandlvswrite only LVM's own files below/run, which a reboot removes:/run/lvm/hintson Debian 13, and the directory/run/lock/lvmon Rocky Linux 9.lvextend --helpandwipefs --no-actleave nothing.
Examples
A volume of 50 GiB for PostgreSQL's data. To grow the volume later, write a larger size: the next run grows the volume and its filesystem, while the filesystem stays mounted:
- lvm_logical_volume:
name: postgresql
volume_group: data
size: 50GiB
grow_filesystem_with_volume: true
A volume for swap. The swap volume holds no filesystem, so the task says that only the volume grows:
- lvm_logical_volume:
name: swap
volume_group: data
size: 8GiB
grow_filesystem_with_volume: false
A volume is deleted with everything on it, after its filesystem was unmounted:
- fstab_mount:
mount_point: /var/lib/postgresql
state: unmounted_and_removed_from_fstab
- lvm_logical_volume:
name: postgresql
volume_group: data
state: deleted_with_all_its_data
Errors and what they mean
Every reason starts with lvm_logical_volume. How often MMX tries a task
that fails depends on what failed:
- Once, in a dryrun too, when no node task changes what is in the way: an input that breaks a rule, a volume that would have to shrink, or a volume that holds something other than a filesystem that LVM grows.
- Once in a run, and not checked in a dryrun, when an earlier node task may change what is in the way: it adds a device to the volume group, unmounts the filesystem, or deletes the snapshots.
- Once, when the task changed the node and then failed, such as for a volume that grew while its filesystem did not: another try would find the volume at its size and report success.
- Again, when another command of LVM failed.
| The reason holds | What it means, and what to do |
|---|---|
the program lvs is not installed; install the package lvm2 ... |
A program that the module runs is not on the node. Install lvm2 in an earlier node task; see Set up. |
lvm_logical_volume.state: deleted_with_all_its_data accepts only name and volume_group; remove size |
A task with state: deleted_with_all_its_data holds another input. Remove the input that the reason names. |
the volume group data does not exist |
The node has no such volume group. Create it in an earlier node task with lvm_volume_group. |
the volume group data has 10 GiB free, and the new logical volume data/postgresql needs 50 GiB |
The volume does not fit. Nothing was created. Write a smaller size, or add a device to the volume group in an earlier node task. |
the volume group data has no free space |
all_free_space_when_created for a new volume, and nothing is left. Add a device to the volume group, or delete a volume. |
the logical volume data/postgresql has 80 GiB, and the task asks for 50 GiB. The module never shrinks ... |
The volume is larger than size. Nothing was changed. Write the size that the volume has. |
... needs 30 GiB more for 80 GiB, and the volume group data has 10 GiB free |
The volume cannot grow that far. Nothing was changed. Write a smaller size, or add a device to the volume group in an earlier node task. |
the logical volume data/swap holds no ext2, ext3, ext4, or xfs filesystem (found: swap area ...), and grow_filesystem_with_volume is true |
The volume should grow together with its filesystem and holds something else; found: names what it holds. Nothing was changed. For such a volume, such as swap, set grow_filesystem_with_volume: false. A volume that holds nothing does not fail: it grows alone. |
growing the logical volume ...: and LVM's words, then The logical volume still has 50 GiB |
LVM refused and grew nothing, for a reason that the module does not know. Read LVM's words. |
growing the logical volume ...: and LVM's words, then The logical volume now has 80 GiB, and its filesystem is still smaller |
The volume grew, and the filesystem's own program failed afterwards, such as resize2fs for a filesystem that is mounted read-only. Read the program's words in the reason and remove the cause, then grow a mounted ext4 or XFS filesystem with grow_filesystem_to_fill_device, or ext2 or ext3 by hand with resize2fs. The next run changes nothing. |
the logical volume data/postgresql is in use |
deleted_with_all_its_data for a volume whose filesystem is mounted, or which a program holds open. Nothing was deleted. Unmount the filesystem in an earlier node task, with fstab_mount and state: unmounted_and_removed_from_fstab, or stop the program. |
other logical volumes depend on the logical volume data/postgresql, and LVM deletes them together with it: before-upgrade (a snapshot of it) |
deleted_with_all_its_data for a volume with snapshots, or for a thin pool with volumes in it. The reason names the first five and counts the rest. Nothing was deleted. Delete each of them in an earlier node task, with its own lvm_logical_volume task and state: deleted_with_all_its_data. |
the module writes lvcreate's option --size itself |
lvcreate_options holds an option for the name, the size, or the signatures. Leave the option out; write name and size. |
creating the logical volume ...: and LVM's words |
lvcreate refused, for example an option of lvcreate_options or a mirror that needs more devices than the volume group has. Read LVM's words at the end of the reason. MMX reports changed for a command that ran, also when LVM refused it and created nothing. |
A reason that ends with This was after lvcreate created the logical volume ... |
A command of LVM that reads failed right after the creation. The task reports created: true: another try would find the volume and report that the task created nothing. Run again; the next run compares the size. |
When a provider has enlarged a physical volume's device, run
lvm_volume_group in an earlier node task
with that device listed and
grow_physical_volumes_with_their_devices: true. This choice makes the extra whole
extents available to the volume group.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/partitions_and_lvm.py runs the whole test on Debian 12 and 13 and Ubuntu 24.04 and 26.04, in a virtual machine. The table of
lvm_volume_group lists the
versions of lvm2, 2.03.16 to 2.03.36. The suite grows an ext4 filesystem
while it is mounted, an xfs filesystem while it is not mounted, which is
where LVM 2.03.31 and newer differ from older LVM, and an ext3
filesystem. LVM 2.03.11 and 2.03.43 also grew an ext2 filesystem with its
volume.
Making thin pools and snapshots and moving data between devices are not
part of the module: they stay shell tasks. The module deletes a
snapshot or a thin volume as it deletes any volume, by its name.
Why it works this way
-
all_free_space_when_creatednames when the size applies. An existing volume keeps its size; the creation-only naming rule makes that visible. -
grow_filesystem_with_volumeis required forpresent. The right value depends on the task; settings with no safe guess are required. -
The module grows a volume and never shrinks one. Growing is why teams use LVM, and it loses nothing. Shrinking destroys data when the filesystem is not shrunk first.
-
grow_filesystem_with_volumeis explicit. Most volumes hold a filesystem that LVM grows: ext2, ext3, ext4, or xfs. A grown volume with a small filesystem is a trap: the next run finds the volume at its size and grows nothing. -
The module looks at the volume before it grows it with a filesystem. LVM refuses a volume without a filesystem that it can grow, and no reading command of LVM says so beforehand. With the module's own look, a dryrun promises no growth that the run refuses, and the reason names what the volume holds. The mistake is loud and loses nothing.
-
A volume that holds nothing grows alone. It has no filesystem that could be left small, so the module grows it with a plain
lvextend. Otherwise a first run that stopped betweenlvcreateand the filesystem's task would block every later run with a larger size: the volume's task would fail, and the filesystem's task behind it would never run. -
lvcreategets--yes --wipesignatures y. The space of a new volume can hold the signature of a filesystem that an earlier volume had there.lvcreatethen asks whether to wipe it, answers "no" itself when it has no terminal, and creates nothing. That space belongs to no volume, so nothing that exists is lost, and a followingcreate_filesystem_on_empty_devicetask finds the new volume empty. -
lvremovegets--yesonly fordeleted_with_all_its_data: the state's name already says that the data is destroyed. LVM still refuses a volume that is in use. -
The module deletes no volume that other volumes depend on. For a volume with snapshots, and for a thin pool with volumes in it, LVM asks whether to remove them too, and
--yeswould answer that question as well: on LVM 2.03.11 and 2.03.43,lvremove --yesdeleted two snapshots with their volume, and two thin volumes with their pool. The task names one volume, so the module deletes one volume. A snapshot of a thin volume is a volume of its own and stays when its origin is deleted, so it is not in the way. -
The module passes
--fsmode managewhere LVM has that option. LVM 2.03.31 and newer grow an xfs filesystem that is not mounted only with it, and then mount the filesystem for a moment themselves; older LVM does the same without the option. The module readslvextend --helpto learn which LVM the node has. -
The module compares sizes after LVM's rounding. LVM rounds a size up to whole extents. Without the same rounding, a task with
50MiBwould find its volume of 52 MiB "larger" and fail on every run. -
The module checks free space and use itself before it calls LVM, so the reason says in plain words what is in the way. LVM's own refusal stays behind it.
-
A state that an earlier node task may change does not fail a dryrun. A playbook unmounts a filesystem and then deletes its volume, or adds a device to the volume group and then grows a volume. In its dryrun the earlier task has changed nothing yet. So the dryrun reports the later task as
not_checked, and only a run, where the state is real, fails.
This page is official_extra_modules/lvm_logical_volume/README.md in the MMX repository.