lvm

ansible-role-lvm

This Ansible roles installs Linux Logical Volume Manager (LVM) resources like Volume Groups (VG), Logical Volumes (LV) and handles filesystems creation and mountpoints.

Changelog

see CHANGELOG

Role Variables

By default no LVM resources are created. See examples below. The lvm_vgs key is the entrypoint for all LVM resources that should be created.

lvm_vgs: []

First a few examples about creating LVM resources (how deletion is handled see further down below).

Create a volume group (VG) called test-vg-01 which uses device /dev/vdb as physical volume:

lvm_vgs:
  - vgname: test-vg-01
    pvs: /dev/vdb
    state: present

All three parameters are required! vgname is the name of the Volume Group. pvs is a list of comma-separated devices to use as physical devices in this volume group. state controls if the volume group exists.
To delete a VG you need to specify state: absent and also force: true. In contrast to the force parameter of the community.general.lvg module force: true won't delete VGs that still contains (a) logical volume(s)! This is to make it harder to delete data by accident.

Create a volume group (VG) called test-vg-01 which uses devices /dev/vdb and /dev/vdc as physical volumes:

lvm_vgs:
  - vgname: test-vg-01
    pvs: /dev/vdb,/dev/vdc
    state: present

Currently the following additional community.general.lvg parameters are supported:

As previous example but also create a logical volume test-lv-01 and allocate 10% of the available VG space:

lvm_vgs:
  - vgname: test-vg-01
    pvs: /dev/vdb
    state: present
    lvm_lvs:
      - lvname: test-lv-01
        size: 10%VG
        state: present

All logical volumes a volume group contains are listed under lvm_lvs key. lvname, size and state parameters are required! lvname is the name of the logical volume. size specifies the size of the logical volume, according to lvcreate(8) --size, by default in megabytes or optionally with one of [bBsSkKmMgGtTpPeE] units; or according to lvcreate(8) --extents as a percentage of [VG|PVS|FREE]; Float values must begin with a digit. state controls if the logical volume exists. To delete a LV you need to specify state: absent and also force: true.

Currently also the following additional community.general.lvol parameters are supported:

As previous example but also create a ext4 filesystem using logical volume test-lv-01 as device for the filesystem:

lvm_vgs:
  - vgname: test-vg-01
    pvs: /dev/vdb
    state: present
    lvm_lvs:
      - lvname: test-lv-01
        size: 10%VG
        state: present
        fs:
          type: ext4
          state: present

The fs key specifies that the logical volume should contain a filesystem. type specifies the filesystem that should be used. state: present specifies that the filesystem is created if it doesn't already exist. In case of state: absent filesystem signatures on the device are wiped if it contains a filesystem (as known by blkid). When state: absent, all other options but the device are ignored, and the module doesn't fail if the device doesn't actually exist. In case of state: absent also force: true is needed otherwise the filesystem won't be touched. In contrast to the force parameter of the community.general.filesystem module force: true won't override an existing filesystem. You really need to wipe the old one first to be able to create an new filesystem! Again this is to avoid deletion by accident.

As previous example but also create a directory /mnt1 and mount the ext4 filesystem there. This also creates an entry in /etc/fstab (by default).

lvm_vgs:
  - vgname: test-vg-01
    pvs: /dev/vdb
    state: present
    lvm_lvs:
      - lvname: test-lv-01
        size: 10%VG
        state: present
        fs:
          type: ext4
          state: present
          mountpoint:
            state: mounted
            path:
              name: /mnt1

The mountpoint key handles mountpoint related actions. state has the same options as the ansible.posix.mount module provides like mounted, absent, present, unmounted and remounted (also see state). state and path.name are required. path.name specifies the name of the directory the mountpoint should be mounted. If the directory doesn't exists already it will be created. For further options see next example.

As previous example but the filesystem now gets an label mnt1. Also the filesystem gets mounted at /mnt1 with the noatime filesystem option. Also the filesystem gets mounted by using the mnt1 label as mentioned (src: LABEL=mnt1). The owner and group of the /mnt1 directory will be vagrant and the directory permissions will be 0750:

lvm_vgs:
  - vgname: test-vg-01
    pvs: /dev/vdb
    state: present
    lvm_lvs:
      - lvname: test-lv-01
        size: 10%VG
        state: present
        fs:
          type: ext4
          opts: -L mnt1
          state: present
          mountpoint:
            opts: noatime
            state: mounted
            src: LABEL=mnt1
            path:
              name: /mnt1
              mode: '0750'
              owner: vagrant
              group: vagrant

By default mountpoint.src is /dev/ + vgname + / + lvname. In the example above LABEL=mnt1 was used. In opts: -L mnt the option was provided to create a filesystem with that label. So that one can be used later for mountpoint.src.

mountpoint supports the following additional parameters:

Create two volume groups (VG) called test-vg-01 and test-vg-02 which uses device /dev/vdb and /dev/vdc respectively as physical volumes:

lvm_vgs:
  - vgname: test-vg-01
    pvs: /dev/vdb
    state: present
  - vgname: test-vg-02
    pvs: /dev/vdc
    state: present

Here is an example to unmount a mountpoint and delete its entry from /etc/fstab:

mountpoint:
  state: absent
  path:
    name: /vg01lv01

This of course only works if the mountpoint isn't used by a program or service.

As deleting filesystems, logical volumes (LV) and volume groups (VG) potentially can destroy your data extra caution should be taken! In this case specifying state: absent to delete such a resource isn't enough. force: true is also needed. Of course deleting a volume group that still contains a logical volume will fail. Also deleting a logical volume with a filesystem with state: present will fail.

The following example will unmount the specified mountpoint (/vg02lv01) and delete its entry from /etc/fstab, will wipe the ext4 filesystem, deletes the logical volume (vg02lv01) and finally deletes the volume group (vg02) (in that order):

lvm_vgs:
  - vgname: vg02
    pvs: /dev/vdc
    state: absent
    force: true
    lvm_lvs:
      - lvname: vg02lv01
        size: 10%VG
        state: absent
        force: true
        fs:
          type: ext4
          state: absent
          force: true
          mountpoint:
            state: absent
            path:
              name: /vg02lv01

To be able to create filesystems additional packages are needed. For ext(2|3|4) you need e2fsprogs package installed e.g. So depending which filesystem you want to setup you may need to install additional package(s) or remove package(s) not needed from the list. Of course you can add whatever packages you want to install to the list

By default only tools needed for ext(2|3|4) or xfs are installed. For other filesystems you may need btrfsprogs/btrfs-progs, dosfstools, f2fs-tools or reiserfsprogs e.g.:

# Additional packages for SuSE compatible OSes
additional_packages_suse:
  - e2fsprogs
  - xfsprogs

# Additional packages for Debian compatible OSes
additional_packages_debian:
  - e2fsprogs
  - xfsprogs

# Additional packages for Redhat compatible OSes
additional_packages_redhat:
  - e2fsprogs
  - xfsprogs

# Additional packages for Archlinux compatible OSes
additional_packages_arch:
  - e2fsprogs
  - xfsprogs

In general most options of the following modules are supported:

community.general.lvg
community.general.lvol
community.general.filesystem
ansible.posix.mount

Dependencies

This role depends on a few Ansible modules:

community.general.lvg
community.general.lvol
community.general.filesystem
ansible.posix.mount

TODO

Currently the following features are not implemented:

Volume Group resize
Logical Volume shrink
Logical Volume snapshot
Logical Volume/Filesystem resize

Example Playbook

Example 1 (without role tag)

- hosts: your-host
  roles:
    - githubixx.lvm

Example 2 (assign tag to role)

-
  hosts: your-host
  roles:
    -
      role: githubixx.lvm
      tags: role-lvm

More examples

There are a few more examples used for testing this role. See molecule directories.

Testing

This role has a small test setup that is created using Molecule, libvirt (vagrant-libvirt) and QEMU/KVM. Please see my blog post Testing Ansible roles with Molecule, libvirt (vagrant-libvirt) and QEMU/KVM how to setup. The test configuration is here.

Afterwards molecule can be executed: