New modules btrfs_subvolume / btrfs_info (#5832)

* Initial implementation for new modules btrfs_subvolume and btrfs_info

* Improve/flesh out documentation. Add ability to target filesystem by uuid, label or device. Update tests to test targeting filesystem by each supported parameter and when only mountpoint.

* Updates for btrfs modules. Add missing copyright notices. Switch options to contains in return documentation. Update btrfs_subvolume to always use closest parent mount.

* Add maintainers for btrfs module(s) and remove unused class member cause lint failure.

* Add changelog fragment. Attempt to only run against the VMs as part of CI.

* Updates per code review. Remove changelog fragment. Switch use of map to list comprehension. Add trailing comma to last item in multi-line dicts. Clean up documentation with complete senstences for descriptions and correct/consistent use of macros.

* Improved error handling in btrfs_subvolume module: add custom exception type, favor exceptions over immediate call to fail_json and add single top level return for failure scenarios. Normalize name and snapshot_source parameters early in module execution and remove unecessary duplicate normalization throughout processing.

* Add azp/posix/3 to aliases per feedback

* Clean up automatic mounting. Prevent automount when check_mode=True. Immediately fail if a mount is identified as required and automount=True. Identify the minimal subset of subvolumes that need to be mounted instead of just finding a single common root.

* Skip btrfs_subvolume integration tests if btrfs-progs isn't successfully installed.

* Bump version_added for btrfs modules to 6.6.0. Ensure consistent trailing punctuation for module descriptions and document check_mode behavior as attribute description rather than a module level note.

* Remove unused imports from btrfs_subvolume module.

* Fix import.

* Docs improvements.

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

tests/integration/targets/btrfs_subvolume/aliases

@@ -0,0 +1,12 @@
+# Copyright (c) Ansible Projec
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+azp/posix/3
+azp/posix/vm
+destructive
+needs/privileged
+skip/aix
+skip/freebsd
+skip/osx
+skip/macos

tests/integration/targets/btrfs_subvolume/defaults/main.yml

@@ -0,0 +1,20 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+btrfs_subvolume_single_configs:
+- file: "/tmp/disks0.img"
+  loop: "/dev/loop95"
+btrfs_subvolume_multiple_configs:
+- file: "/tmp/diskm0.img"
+  loop: "/dev/loop97"
+- file: "/tmp/diskm1.img"
+  loop: "/dev/loop98"
+- file: "/tmp/diskm2.img"
+  loop: "/dev/loop99"
+btrfs_subvolume_configs: "{{ btrfs_subvolume_single_configs + btrfs_subvolume_multiple_configs }}"
+btrfs_subvolume_single_devices: "{{ btrfs_subvolume_single_configs | map(attribute='loop') }}"
+btrfs_subvolume_single_label: "single"
+btrfs_subvolume_multiple_devices: "{{ btrfs_subvolume_multiple_configs | map(attribute='loop') }}"
+btrfs_subvolume_multiple_label: "multiple"

tests/integration/targets/btrfs_subvolume/tasks/main.yml

@@ -0,0 +1,29 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Install required packages
+  ansible.builtin.package:
+    name:
+      - btrfs-progs # btrfs userspace
+      - util-linux # losetup
+  ignore_errors: True
+  register: btrfs_installed
+
+- name: Execute integration tests tests
+  block:
+  - ansible.builtin.include_tasks: 'setup.yml'
+
+  - name: "Execute test scenario for single device filesystem"
+    ansible.builtin.include_tasks: 'run_filesystem_tests.yml'
+    vars:
+      btrfs_subvolume_target_device: "{{ btrfs_subvolume_single_devices | first }}"
+      btrfs_subvolume_target_label: "{{ btrfs_subvolume_single_label }}"
+
+  - name: "Execute test scenario for multiple device configuration"
+    ansible.builtin.include_tasks: 'run_filesystem_tests.yml'
+    vars:
+      btrfs_subvolume_target_device: "{{ btrfs_subvolume_multiple_devices | first }}"
+      btrfs_subvolume_target_label: "{{ btrfs_subvolume_multiple_label }}"
+  when: btrfs_installed is success

tests/integration/targets/btrfs_subvolume/tasks/run_common_tests.yml

@@ -0,0 +1,15 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- ansible.builtin.include_tasks: 'test_subvolume_simple.yml'
+- ansible.builtin.include_tasks: 'test_subvolume_nested.yml'
+- ansible.builtin.include_tasks: 'test_subvolume_recursive.yml'
+- ansible.builtin.include_tasks: 'test_subvolume_default.yml'
+
+- ansible.builtin.include_tasks: 'test_snapshot_skip.yml'
+- ansible.builtin.include_tasks: 'test_snapshot_clobber.yml'
+- ansible.builtin.include_tasks: 'test_snapshot_error.yml'
+
+- ansible.builtin.include_tasks: 'test_subvolume_whitespace.yml'

tests/integration/targets/btrfs_subvolume/tasks/run_filesystem_tests.yml

@@ -0,0 +1,32 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- ansible.builtin.include_tasks: 'test_filesystem_matching.yml'
+
+- name: "Execute all test scenario for unmounted filesystem"
+  ansible.builtin.include_tasks: 'run_common_tests.yml'
+
+- name: "Execute test scenarios where non-root subvolume is mounted"
+  block:
+  - name: Create subvolume '/nonroot'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      name: "/nonroot"
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      state: "present"
+    register: nonroot
+  - name: "Mount subvolume '/nonroot'"
+    ansible.posix.mount:
+      src: "{{ nonroot.filesystem.devices | first }}"
+      path: /mnt
+      opts: "subvolid={{ nonroot.target_subvolume_id }}"
+      fstype: btrfs
+      state: mounted
+  - name: "Run tests for explicit, mounted single device configuration"
+    ansible.builtin.include_tasks: 'run_common_tests.yml'
+  - name: "Unmount subvolume /nonroot"
+    ansible.posix.mount:
+      path: /mnt
+      state: absent

tests/integration/targets/btrfs_subvolume/tasks/setup.yml

@@ -0,0 +1,37 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: "Create file {{ item.file }} to back loop device {{ item.loop }}"
+  ansible.builtin.command:
+    cmd: "dd if=/dev/zero of={{ item.file }} bs=1M count=200"  ## minimum count 109
+    creates: "{{ item.file }}"
+  with_items: "{{ btrfs_subvolume_configs }}"
+
+- name: "Setup loop device {{ item.loop }}"
+  ansible.builtin.command:
+    cmd: "losetup {{ item.loop }} {{ item.file }}"
+    creates: "{{ item.loop }}"
+  with_items: "{{ btrfs_subvolume_configs }}"
+
+- name: Create single device btrfs filesystem
+  ansible.builtin.command:
+    cmd: "mkfs.btrfs --label {{ btrfs_subvolume_single_label }} -f {{ btrfs_subvolume_single_devices | first }}"
+  changed_when: True
+
+- name: Create multiple device btrfs filesystem
+  ansible.builtin.command:
+    cmd: "mkfs.btrfs --label {{ btrfs_subvolume_multiple_label }} -f -d raid0 {{ btrfs_subvolume_multiple_devices | join(' ') }}"
+  changed_when: True
+
+# Typically created by udev, but apparently missing on Alpine
+- name: Create btrfs control device node
+  ansible.builtin.command:
+    cmd: "mknod /dev/btrfs-control c 10 234"
+    creates: "/dev/btrfs-control"
+
+- name: Force rescan to ensure all device are detected
+  ansible.builtin.command:
+    cmd: "btrfs device scan"
+  changed_when: True

tests/integration/targets/btrfs_subvolume/tasks/test_filesystem_matching.yml

@@ -0,0 +1,80 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: "Match targeted filesystem by label"
+  block:
+  - name: Match '{{ btrfs_subvolume_target_label }}' filesystem by label
+    community.general.btrfs_subvolume:
+      automount: Yes
+      name: "/match_label"
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      state: "present"
+    register: result
+
+  - name: Validate the '{{ btrfs_subvolume_target_label }}' filesystem was chosen
+    ansible.builtin.assert:
+      that:
+        - result.filesystem.label == btrfs_subvolume_target_label
+
+- name: "Match targeted filesystem by uuid"
+  block:
+  - name: Match '{{ btrfs_subvolume_target_label }}' filesystem by uuid
+    community.general.btrfs_subvolume:
+      automount: Yes
+      name: "/match_uuid"
+      filesystem_uuid: "{{ result.filesystem.uuid }}"
+      state: "present"
+    register: result
+
+  - name: Validate the '{{ btrfs_subvolume_target_label }}' filesystem was chosen
+    ansible.builtin.assert:
+      that:
+        - result.filesystem.label == btrfs_subvolume_target_label
+
+- name: "Match targeted filesystem by devices"
+  block:
+  - name: Match '{{ btrfs_subvolume_target_label }}' filesystem by device
+    community.general.btrfs_subvolume:
+      automount: Yes
+      name: "/match_device"
+      filesystem_device: "{{ result.filesystem.devices | first }}"
+      state: "present"
+    register: result
+
+  - name: Validate the '{{ btrfs_subvolume_target_label }}' filesystem was chosen
+    ansible.builtin.assert:
+      that:
+        - result.filesystem.label == btrfs_subvolume_target_label
+
+- name: "Match only mounted filesystem"
+  block:
+  - name: "Mount filesystem '{{ btrfs_subvolume_target_label }}'"
+    ansible.posix.mount:
+      src: "{{ result.filesystem.devices | first }}"
+      path: /mnt
+      opts: "subvolid={{ 5 }}"
+      fstype: btrfs
+      state: mounted
+
+  - name: Print current status
+    community.general.btrfs_info:
+
+  - name: Match '{{ btrfs_subvolume_target_label }}' filesystem when only mount
+    community.general.btrfs_subvolume:
+      automount: Yes
+      name: "/match_only_mounted"
+      state: "present"
+    register: result
+
+  - name: "Unmount filesystem '{{ btrfs_subvolume_target_label }}'"
+    ansible.posix.mount:
+      path: /mnt
+      state: absent
+
+  - name: Validate the '{{ btrfs_subvolume_target_label }}' filesystem was chosen
+    ansible.builtin.assert:
+      that:
+        - result.filesystem.label == btrfs_subvolume_target_label
+  when: False  # TODO don't attempt this if the host already has a pre-existing btrfs filesystem

tests/integration/targets/btrfs_subvolume/tasks/test_snapshot_clobber.yml

@@ -0,0 +1,41 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Create a snapshot, overwriting if one already exists at path
+  block:
+  - name: Create a snapshot named 'snapshot_clobber'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/snapshot_clobber"
+      snapshot_source: "/"
+      snapshot_conflict: "clobber"
+      state: "present"
+    register: result
+  - name: Snapshot 'snapshot_clobber' created
+    ansible.builtin.assert:
+      that:
+      - result is changed
+
+  - name: Create a snapshot named 'snapshot_clobber' (no idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/snapshot_clobber"
+      snapshot_source: "/"
+      snapshot_conflict: "clobber"
+      state: "present"
+    register: result
+  - name: Snapshot 'snapshot_clobber' created (no idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is changed
+
+- name: Cleanup created snapshot
+  community.general.btrfs_subvolume:
+    automount: Yes
+    filesystem_label: "{{ btrfs_subvolume_target_label }}"
+    name: "/snapshot_clobber"
+    state: "absent"

tests/integration/targets/btrfs_subvolume/tasks/test_snapshot_error.yml

@@ -0,0 +1,42 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Create a snapshot, erroring if one already exists at path
+  block:
+  - name: Create a snapshot named 'snapshot_error'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/snapshot_error"
+      snapshot_source: "/"
+      snapshot_conflict: "error"
+      state: "present"
+    register: result
+  - name: Snapshot 'snapshot_error' created
+    ansible.builtin.assert:
+      that:
+      - result is changed
+
+  - name: Create a snapshot named 'snapshot_error' (no idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/snapshot_error"
+      snapshot_source: "/"
+      snapshot_conflict: "error"
+      state: "present"
+    register: result
+    ignore_errors: true
+  - name: Snapshot 'snapshot_error' created (no idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed
+
+- name: Cleanup created snapshot
+  community.general.btrfs_subvolume:
+    automount: Yes
+    filesystem_label: "{{ btrfs_subvolume_target_label }}"
+    name: "/snapshot_error"
+    state: "absent"

tests/integration/targets/btrfs_subvolume/tasks/test_snapshot_skip.yml

@@ -0,0 +1,41 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Create a snapshot if one does not already exist at path
+  block:
+  - name: Create a snapshot named 'snapshot_skip'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/snapshot_skip"
+      snapshot_source: "/"
+      snapshot_conflict: "skip"
+      state: "present"
+    register: result
+  - name: Snapshot 'snapshot_skip' created
+    ansible.builtin.assert:
+      that:
+      - result is changed
+
+  - name: Create a snapshot named 'snapshot_skip' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/snapshot_skip"
+      snapshot_source: "/"
+      snapshot_conflict: "skip"
+      state: "present"
+    register: result
+  - name: Snapshot 'snapshot_skip' created (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed
+
+- name: Cleanup created snapshot
+  community.general.btrfs_subvolume:
+    automount: Yes
+    filesystem_label: "{{ btrfs_subvolume_target_label }}"
+    name: "/snapshot_skip"
+    state: "absent"

tests/integration/targets/btrfs_subvolume/tasks/test_subvolume_default.yml

@@ -0,0 +1,99 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Change the default subvolume
+  block:
+  - name: Update filesystem default subvolume to '@'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      default: True
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/@"
+      state: "present"
+    register: result
+  - name: Subvolume '@' set to default
+    ansible.builtin.assert:
+      that:
+      - result is changed
+  - name: Update filesystem default subvolume to '@' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      default: True
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/@"
+      state: "present"
+    register: result
+  - name: Subvolume '@' set to default (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed
+
+- name: Revert the default subvolume
+  block:
+  - name: Revert filesystem default subvolume to '/'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      default: True
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/"
+      state: "present"
+    register: result
+  - name: Subvolume '/' set to default
+    ansible.builtin.assert:
+      that:
+      - result is changed
+  - name: Revert filesystem default subvolume to '/' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      default: True
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/"
+      state: "present"
+    register: result
+  - name: Subvolume '/' set to default (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed
+
+
+- name: Change the default subvolume again
+  block:
+  - name: Update filesystem default subvolume to '@'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      default: True
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/@"
+      state: "present"
+    register: result
+  - name: Subvolume '@' set to default
+    ansible.builtin.assert:
+      that:
+      - result is changed
+
+- name: Revert custom default subvolume to fs_tree root when deleted
+  block:
+  - name: Delete custom default subvolume '@'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/@"
+      state: "absent"
+    register: result
+  - name: Subvolume '@' deleted
+    ansible.builtin.assert:
+      that:
+      - result is changed
+  - name: Delete custom default subvolume '@' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/@"
+      state: "absent"
+    register: result
+  - name: Subvolume '@' deleted (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed

tests/integration/targets/btrfs_subvolume/tasks/test_subvolume_nested.yml

@@ -0,0 +1,61 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Create parent subvolume 'container'
+  community.general.btrfs_subvolume:
+    automount: Yes
+    filesystem_label: "{{ btrfs_subvolume_target_label }}"
+    name: "/container"
+    state: "present"
+
+- name: Create a nested subvolume
+  block:
+  - name: Create a subvolume named 'nested' inside 'container'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/container/nested"
+      state: "present"
+    register: result
+  - name: Subvolume 'container/nested' created
+    ansible.builtin.assert:
+      that:
+      - result is changed
+  - name: Create a subvolume named 'nested' inside 'container' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/container/nested"
+      state: "present"
+    register: result
+  - name: Subvolume 'container/nested' created (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed
+
+- name: Remove a nested subvolume
+  block:
+  - name: Remove a subvolume named 'nested' inside 'container'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/container/nested"
+      state: "absent"
+    register: result
+  - name: Subvolume 'container/nested' removed
+    ansible.builtin.assert:
+      that:
+      - result is changed
+  - name: Remove a subvolume named 'nested' inside 'container' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/container/nested"
+      state: "absent"
+    register: result
+  - name: Subvolume 'container/nested' removed (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed

tests/integration/targets/btrfs_subvolume/tasks/test_subvolume_recursive.yml

@@ -0,0 +1,86 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Recursively create subvolumes
+  block:
+  - name: Create a subvolume named '/recursive/son/grandson'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/recursive/son/grandson"
+      recursive: Yes
+      state: "present"
+    register: result
+  - name: Subvolume named '/recursive/son/grandson' created
+    ansible.builtin.assert:
+      that:
+      - result is changed
+
+  - name: Create a subvolume named '/recursive/son/grandson' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/recursive/son/grandson"
+      recursive: Yes
+      state: "present"
+    register: result
+  - name: Subvolume named '/recursive/son/grandson' created (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed
+
+  - name: Create a subvolume named '/recursive/daughter/granddaughter'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/recursive/daughter/granddaughter"
+      recursive: Yes
+      state: "present"
+    register: result
+  - name: Subvolume named '/recursive/son/grandson' created
+    ansible.builtin.assert:
+      that:
+      - result is changed
+
+  - name: Create a subvolume named '/recursive/daughter/granddaughter' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/recursive/daughter/granddaughter"
+      recursive: Yes
+      state: "present"
+    register: result
+  - name: Subvolume named '/recursive/son/grandson' created (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed
+
+- name: Recursively remove subvolumes
+  block:
+  - name: Remove subvolume '/recursive' and all descendents
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/recursive"
+      recursive: Yes
+      state: "absent"
+    register: result
+  - name: Subvolume '/recursive' removed
+    ansible.builtin.assert:
+      that:
+      - result is changed
+
+  - name: Remove subvolume '/recursive' and all descendents (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/recursive"
+      recursive: Yes
+      state: "absent"
+    register: result
+  - name: Subvolume '/recursive' removed (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed

tests/integration/targets/btrfs_subvolume/tasks/test_subvolume_simple.yml

@@ -0,0 +1,54 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Create a simple subvolume
+  block:
+  - name: Create a subvolume named 'simple'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/simple"
+      state: "present"
+    register: result
+  - name: Subvolume named 'simple' created
+    ansible.builtin.assert:
+      that:
+      - result is changed
+  - name: Create a subvolume named 'simple' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/simple"
+      state: "present"
+    register: result
+  - name: Subvolume named 'simple' created (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed
+
+- name: Remove a simple subvolume
+  block:
+  - name: Remove a subvolume named 'simple'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/simple"
+      state: "absent"
+    register: result
+  - name: Subvolume named 'simple' removed
+    ansible.builtin.assert:
+      that:
+      - result is changed
+  - name: Remove a subvolume named 'simple' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/simple"
+      state: "absent"
+    register: result
+  - name: Subvolume named 'simple' removed (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed

tests/integration/targets/btrfs_subvolume/tasks/test_subvolume_whitespace.yml

@@ -0,0 +1,62 @@
+---
+# Copyright (c) 2022, Gregory Furlong <gnfzdz@fzdz.io>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Create a subvolume named 'container'
+  community.general.btrfs_subvolume:
+    automount: Yes
+    filesystem_label: "{{ btrfs_subvolume_target_label }}"
+    name: "/container"
+    state: "present"
+
+- name: Create a subvolume with whitespace in the name
+  block:
+  - name: Create a subvolume named 'container/my data'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/container/my data"
+      state: "present"
+    register: result
+  - name: Subvolume named 'container/my data' created
+    ansible.builtin.assert:
+      that:
+      - result is changed
+  - name: Create a subvolume named 'container/my data' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/container/my data"
+      state: "present"
+    register: result
+  - name: Subvolume named 'container/my data' created (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed
+
+- name: Remove a subvolume with whitespace in the name
+  block:
+  - name: Remove a subvolume named 'container/my data'
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/container/my data"
+      state: "absent"
+    register: result
+  - name: Subvolume named 'container/my data' removed
+    ansible.builtin.assert:
+      that:
+      - result is changed
+
+  - name: Remove a subvolume named 'container/my data' (idempotency)
+    community.general.btrfs_subvolume:
+      automount: Yes
+      filesystem_label: "{{ btrfs_subvolume_target_label }}"
+      name: "/container/my data"
+      state: "absent"
+    register: result
+  - name: Subvolume named 'container/my data' removed (idempotency)
+    ansible.builtin.assert:
+      that:
+      - result is not changed