Linux Storage Role

This role allows users to configure local storage with minimal input.

As of now, the role supports managing file systems and mount entries on

disks
LVM volume groups
Stratis pools (with Stratis v3 and newer)

Encryption (using LUKS) and RAID (using MD) is also supported. Support for managing pre-existing devices is limited, but new LVM volumes and Stratis filesystems can be added to existing setups and mount points and some other features can be added to (or removed from) existing devices.

Requirements

See below

Collection requirements

The role requires external collections. Use the following command to install them:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Role Variables

NOTE: Beginning with version 1.3.0, unspecified parameters are interpreted differently for existing and non-existing pools/volumes. For new/non-existent pools and volumes, any omitted parameters will use the default value as described in defaults/main.yml. For existing pools and volumes, omitted parameters will inherit whatever setting the pool or volume already has. This means that to change/override role defaults in an existing pool or volume, you must explicitly specify the new values/settings in the role variables.

`storage_pools`

The storage_pools variable is a list of pools to manage. Each pool contains a nested list of volume dicts as described below, as well as the following keys:

name

This specifies the name of the pool to manage/create as a string. (One example of a pool is an LVM volume group.)
type

This specifies the type of pool to manage. Valid values for type: lvm, stratis.
state

Valid values are present (default behavior) or absent. Pools marked as absent will be removed by the role. Pools marked as present will be either created (if pool with the specified name doesn't already exist) or preserved.
grow_to_fill

When set, the pool Physical Volumes will be resized to match their respective device sizes. (e.g. after Virtual Machine disk size increase)

Default: false

NOTE: This argument is valid only for LVM pools.
shared

If set to true, the role creates or manages a shared volume group. Requires lvmlockd and dlm services configured and running.

Default: false

WARNING: Modifying the shared value on an existing pool is a destructive operation. The pool itself will be removed as part of the process.

NOTE: This argument is valid only for LVM pools.
disks

A list which specifies the set of disks to use as backing storage for the pool. Supported identifiers include: device node (like /dev/sda or /dev/mapper/mpathb), device node basename (like sda or mpathb), /dev/disk/ symlink (like /dev/disk/by-id/wwn-0x5000c5005bc37f3f).

For LVM pools this can be also used to add and remove disks to/from an existing pool. Disks in the list that are not used by the pool will be added to the pool. Disks that are currently used by the pool but not present in the list will be removed from the pool only if storage_safe_mode is set to false.
raid_level

When used with type: lvm it manages a volume group with a mdraid array of given level on it. Input disks are in this case used as RAID members. Accepted values are: linear, raid0, raid1, raid4, raid5, raid6, raid10
volumes

This is a list of volumes that belong to the current pool. It follows the same pattern as the storage_volumes variable, explained below.
encryption

This specifies whether the pool will be encrypted using LUKS. WARNING: Toggling encryption for a pool is a destructive operation, meaning the pool itself will be removed as part of the process of adding/removing the encryption layer.
encryption_password

This string specifies a password or passphrase used to unlock/open the LUKS volume(s).
encryption_key

This string specifies the full path to the key file on the managed nodes used to unlock the LUKS volume(s). It is the responsibility of the user of this role to securely copy this file to the managed nodes, or otherwise ensure that the file is on the managed nodes.
encryption_cipher

This string specifies a non-default cipher to be used by LUKS.
encryption_key_size

This integer specifies the LUKS key size (in bytes).
encryption_luks_version

This integer specifies the LUKS version to use.
encryption_clevis_pin

For Stratis pools, the clevis method that should be used to encrypt the created pool. Accepted values are: tang and tpm2
encryption_tang_url

When creating a Stratis pool encrypted via NBDE using a tang server, specifies the URL of the server.
encryption_tang_thumbprint

When creating a Stratis pool encrypted via NBDE using a tang server, specifies the thumbprint of the server.

`storage_volumes`

The storage_volumes variable is a list of volumes to manage. Each volume has the following variables:

name

This specifies the name of the volume.
type

This specifies the type of volume on which the file system will reside. Valid values for type: lvm, disk, partition or raid. The default is determined according to the OS and release (currently lvm).

NOTE: Support for managing partition volumes is currently very limited, the role allows creating only a single partition spanning the entire disk.
state

Valid values are present (default behavior) or absent. Volumes marked as absent will be removed by the role. Volumes marked as present will be either created (if volume with specified name doesn't exist) or preserved and possibly changed to match other values (for example if a volume with the specified name exists but doesn't have the required size it will be resized if possible).
disks

This specifies the set of disks to use as backing storage for the file system. This is currently only relevant for volumes of type disk, where the list must contain only a single item.
size

The size specifies the size of the file system. The format for this is intended to be human-readable, e.g.: "10g", "50 GiB". The size of LVM volumes can be specified as a percentage of the pool/VG size, eg: "50%" as of v1.4.2.

When using compression or deduplication, size can be set higher than actual available space, e.g.: 3 times the size of the volume, based on duplicity and/or compressibility of stored data.

NOTE: The requested volume size may be reduced as necessary so the volume can fit in the available pool space, but only if the required reduction is not more than 2% of the requested volume size.
fs_type

This indicates the desired file system type to use, e.g.: "xfs", "ext4", "swap". The default is determined according to the OS and release (currently xfs for all the supported systems). Use "unformatted" if you do not want file system to be present. WARNING: Using "unformatted" file system type on an existing filesystem is a destructive operation and will destroy all data on the volume.
fs_label

The fs_label is a string to be used for a file system label.
fs_create_options

The fs_create_options specifies custom arguments to mkfs as a string.
mount_point

The mount_point specifies the directory on which the file system will be mounted.
mount_options

The mount_options specifies custom mount options as a string, e.g.: 'ro'.
mount_user

The mount_user specifies desired owner of the mount directory.
mount_group

The mount_group specifies desired group of the mount directory.
mount_mode

The mount_mode specifies desired permissions of the mount directory.
raid_level

Specifies RAID level. LVM RAID can be created as well. "Regular" RAID volume requires type to be raid. LVM RAID needs that volume has storage_pools parent with type lvm, raid_disks need to be specified as well. Accepted values are:
- for LVM RAID volume: raid0, raid1, raid4, raid5, raid6, raid10, striped, mirror
- for RAID volume: linear, raid0, raid1, raid4, raid5, raid6, raid10
WARNING: Changing raid_level for a volume is a destructive operation, meaning all data on that volume will be lost as part of the process of removing old and adding new RAID. RAID reshaping is currently not supported.
raid_device_count

When type is raid specifies number of active RAID devices.
raid_spare_count

When type is raid specifies number of spare RAID devices.
raid_metadata_version

When type is raid specifies RAID metadata version as a string, e.g.: '1.0'.
raid_chunk_size

When type is raid specifies RAID chunk size as a string, e.g.: '512 KiB'. Chunk size has to be multiple of 4 KiB.
raid_stripe_size

When type is lvm specifies LVM RAID stripe size as a string, e.g.: '512 KiB'.
raid_disks

Specifies which disks should be used for LVM RAID volume. raid_level needs to be specified and volume has to have storage_pools parent with type lvm. Accepts sublist of disks of parent storage_pools. In case multiple LVM RAID volumes within the same storage pool, the same disk can be used in multiple raid_disks.
encryption

This specifies whether the volume will be encrypted using LUKS. WARNING: Toggling encryption for a volume is a destructive operation, meaning all data on that volume will be removed as part of the process of adding/removing the encryption layer.
encryption_password

This string specifies a password or passphrase used to unlock/open the LUKS volume.
encryption_key

This string specifies the full path to the key file on the managed nodes used to unlock the LUKS volume(s). It is the responsibility of the user of this role to securely copy this file to the managed nodes, or otherwise ensure that the file is on the managed nodes.
encryption_cipher

This string specifies a non-default cipher to be used by LUKS.
encryption_key_size

This integer specifies the LUKS key size (in bits).
encryption_luks_version

This integer specifies the LUKS version to use.
deduplication

This specifies whether the Virtual Data Optimizer (VDO) will be used. When set, duplicate data stored on storage volume will be deduplicated resulting in more storage capacity. Can be used together with compression and vdo_pool_size. Volume has to be part of the LVM storage_pool. Limit one VDO storage_volume per storage_pool. Underlying volume has to be at least 9 GB (bare minimum is around 5 GiB).
compression

This specifies whether the Virtual Data Optimizer (VDO) will be used. When set, data stored on storage volume will be compressed resulting in more storage capacity. Volume has to be part of the LVM storage_pool. Can be used together with deduplication and vdo_pool_size. Limit one VDO storage_volume per storage_pool.
vdo_pool_size

When Virtual Data Optimizer (VDO) is used, this specifies the actual size the volume will take on the device. Virtual size of VDO volume is set by size parameter. vdo_pool_size format is intended to be human-readable, e.g.: "30g", "50GiB". Default value is equal to the size of the volume.
cached

This specifies whether the volume should be cached or not. This is currently supported only for LVM volumes where dm-cache is used.
cache_size

Size of the cache. cache_size format is intended to be human-readable, e.g.: "30g", "50GiB".
cache_mode

Mode for the cache. Supported values include writethrough (default) and writeback.
cache_devices

List of devices that will be used for the cache. These should be either physical volumes or drives these physical volumes are allocated on. Generally you want to select fast devices like SSD or NVMe drives for cache.
thin

Whether the volume should be thinly provisioned or not. This is supported only for LVM volumes.
thin_pool_name

For thin volumes, this can be used to specify the name of the LVM thin pool that will be used for the volume. If the pool with the provided name already exists, the volume will be added to that pool. If it doesn't exist a new pool named thin_pool_name will be created. If not specified:
- if there are no existing thin pools present, a new thin pool will be created with an automatically generated name,
- if there is exactly one existing thin pool, the thin volume will be added to it and
- if there are multiple thin pools present an exception will be raised.
thin_pool_size

Size for the thin pool. thin_pool_size format is intended to be human-readable, e.g.: "30g", "50GiB".

`storage_safe_mode`

When true (the default), an error will occur instead of automatically removing existing devices and/or formatting.

`storage_udevadm_trigger`

When true (the default is false), the role will use udevadm trigger to cause udev changes to take effect immediately. This may help on some platforms with "buggy" udev.

Example Playbook

- name: Manage storage
  hosts: all
  roles:
    - name: linux-system-roles.storage
      storage_pools:
        - name: app
          disks:
            - sdb
            - sdc
          volumes:
            - name: shared
              size: "100 GiB"
              mount_point: "/mnt/app/shared"
              #fs_type: xfs
              state: present
            - name: users
              size: "400g"
              fs_type: ext4
              mount_point: "/mnt/app/users"
      storage_volumes:
        - name: images
          type: disk
          disks: ["mpathc"]
          mount_point: /opt/images
          fs_label: images

rpm-ostree

See README-ostree.md

License

MIT

linux-system-roles / storage

readme