community.general.btrfs_subvolume module – Manage btrfs subvolumes
Note
This module is part of the community.general collection (version 9.4.0).
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 |
---|---|
Allow the module to temporarily mount the targeted btrfs filesystem in order to validate the current state and make any required changes. Choices:
|
|
Make the subvolume specified by Choices:
|
|
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. |
|
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. |
|
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 of the subvolume/snapshot to be targeted. |
|
When true, indicates that parent/child subvolumes should be created/removedas necessary to complete the operation (for Choices:
|
|
Policy defining behavior when a subvolume already exists at the path of the requested snapshot.
Choices:
|
|
Identifies the source subvolume for the created snapshot. Infers that the created subvolume is a snapshot. |
|
Indicates the current state of the targeted subvolume. Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
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 |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
If any or all of the options
filesystem_device
,filesystem_label
orfilesystem_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 |
---|---|
A summary of the final state of the targeted btrfs filesystem. Returned: success |
|
The ID of the filesystem’s default subvolume. Returned: success and if filesystem is mounted Sample: |
|
A list of devices assigned to the filesystem. Returned: success Sample: |
|
An optional label assigned to the filesystem. Returned: success Sample: |
|
A list of dicts containing metadata for all of the filesystem’s subvolumes. Returned: success and if filesystem is mounted |
|
An identifier assigned to the subvolume, unique within the containing filesystem. Returned: success Sample: |
|
Paths where the subvolume is mounted on the targeted host. Returned: success Sample: |
|
The identifier of this subvolume’s parent. Returned: success Sample: |
|
The full path of the subvolume relative to the btrfs fileystem’s root. Returned: success Sample: |
|
A unique identifier assigned to the filesystem. Returned: success Sample: |
|
A list where each element describes a change made to the target btrfs filesystem. Returned: Success |
|
The ID of the subvolume specified with the Returned: Success and subvolume exists after module execution Sample: |