community.general.btrfs_subvolume module – Manage btrfs subvolumes

Note

This module is part of the community.general collection (version 6.6.2).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.btrfs_subvolume.

New in community.general 6.6.0

Synopsis

  • Creates, updates and deletes btrfs subvolumes and snapshots.

Parameters

Parameter

Comments

automount

boolean

Allow the module to temporarily mount the targeted btrfs filesystem in order to validate the current state and make any required changes.

Choices:

  • false ← (default)

  • true

default

boolean

Make the subvolume specified by name the filesystem’s default subvolume.

Choices:

  • false ← (default)

  • true

filesystem_device

path

A block device contained within the btrfs filesystem to be targeted.

Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted.

filesystem_label

string

A descriptive label assigned to the btrfs filesystem to be targeted.

Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted.

filesystem_uuid

string

A unique identifier assigned to the btrfs filesystem to be targeted.

Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted.

name

string / required

Name of the subvolume/snapshot to be targeted.

recursive

boolean

When true, indicates that parent/child subvolumes should be created/removedas necessary to complete the operation (for state=present and state=absent respectively).

Choices:

  • false ← (default)

  • true

snapshot_conflict

string

Policy defining behavior when a subvolume already exists at the path of the requested snapshot.

skip - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that no change is required. Warning, this option does not yet verify that the target subvolume was generated from a snapshot of the requested source.

clobber - If a subvolume already exists at the requested location, delete it first. This option is not idempotent and will result in a new snapshot being generated on every execution.

error - If a subvolume already exists at the requested location, return an error. This option is not idempotent and will result in an error on replay of the module.

Choices:

  • "skip" ← (default)

  • "clobber"

  • "error"

snapshot_source

string

Identifies the source subvolume for the created snapshot.

Infers that the created subvolume is a snapshot.

state

string

Indicates the current state of the targeted subvolume.

Choices:

  • "absent"

  • "present" ← (default)

Attributes

Attribute

Support

Description

check_mode

Support: partial

In some scenarios it may erroneously report intermediate subvolumes being created. After mounting, if a directory like file is found where the subvolume would have been created, the operation is skipped.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • If any or all of the options filesystem_device, filesystem_label or filesystem_uuid parameters are provided, there is expected to be a matching btrfs filesystem. If none are provided and only a single btrfs filesystem exists or only a single btrfs filesystem is mounted, that filesystem will be used; otherwise, the module will take no action and return an error.

Examples

- name: Create a @home subvolume under the root subvolume
  community.general.btrfs_subvolume:
    name: /@home
    device: /dev/vda2

- name: Remove the @home subvolume if it exists
  community.general.btrfs_subvolume:
    name: /@home
    state: absent
    device: /dev/vda2

- name: Create a snapshot of the root subvolume named @
  community.general.btrfs_subvolume:
    name: /@
    snapshot_source: /
    device: /dev/vda2

- name: Create a snapshot of the root subvolume and make it the new default subvolume
  community.general.btrfs_subvolume:
    name: /@
    snapshot_source: /
    default: Yes
    device: /dev/vda2

- name: Create a snapshot of the /@ subvolume and recursively creating intermediate subvolumes as required
  community.general.btrfs_subvolume:
    name: /@snapshots/@2022_06_09
    snapshot_source: /@
    recursive: True
    device: /dev/vda2

- name: Remove the /@ subvolume and recursively delete child subvolumes as required
  community.general.btrfs_subvolume:
    name: /@snapshots/@2022_06_09
    snapshot_source: /@
    recursive: True
    device: /dev/vda2

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

filesystem

dictionary

A summary of the final state of the targeted btrfs filesystem.

Returned: success

default_subvolume

integer

The ID of the filesystem’s default subvolume.

Returned: success and if filesystem is mounted

Sample: 5

devices

list / elements=string

A list of devices assigned to the filesystem.

Returned: success

Sample: ["/dev/sda1", "/dev/sdb1"]

label

string

An optional label assigned to the filesystem.

Returned: success

Sample: "Tank"

subvolumes

list / elements=dictionary

A list of dicts containing metadata for all of the filesystem’s subvolumes.

Returned: success and if filesystem is mounted

id

integer

An identifier assigned to the subvolume, unique within the containing filesystem.

Returned: success

Sample: 256

mountpoints

list / elements=string

Paths where the subvolume is mounted on the targeted host.

Returned: success

Sample: ["/home"]

parent

integer

The identifier of this subvolume’s parent.

Returned: success

Sample: 5

path

string

The full path of the subvolume relative to the btrfs fileystem’s root.

Returned: success

Sample: "/@home"

uuid

string

A unique identifier assigned to the filesystem.

Returned: success

Sample: "96c9c605-1454-49b8-a63a-15e2584c208e"

modifications

list / elements=string

A list where each element describes a change made to the target btrfs filesystem.

Returned: Success

target_subvolume_id

integer

The ID of the subvolume specified with the name parameter, either pre-existing or created as part of module execution.

Returned: Success and subvolume exists after module execution

Sample: 257

Authors

  • Gregory Furlong (@gnfzdz)