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>

plugins/modules/btrfs_info.py

@@ -0,0 +1,109 @@
+#!/usr/bin/python
+
+# 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
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = r'''
+---
+module: btrfs_info
+short_description: Query btrfs filesystem info
+version_added: "6.6.0"
+description: Query status of available btrfs filesystems, including uuid, label, subvolumes and mountpoints.
+
+author:
+    - Gregory Furlong (@gnfzdz)
+
+extends_documentation_fragment:
+      - community.general.attributes
+      - community.general.attributes.info_module
+'''
+
+EXAMPLES = r'''
+
+- name: Query information about mounted btrfs filesystems
+  community.general.btrfs_info:
+  register: my_btrfs_info
+
+'''
+
+RETURN = r'''
+
+filesystems:
+    description: Summaries of the current state for all btrfs filesystems found on the target host.
+    type: list
+    elements: dict
+    returned: success
+    contains:
+        uuid:
+            description: A unique identifier assigned to the filesystem.
+            type: str
+            sample: 96c9c605-1454-49b8-a63a-15e2584c208e
+        label:
+            description: An optional label assigned to the filesystem.
+            type: str
+            sample: Tank
+        devices:
+            description: A list of devices assigned to the filesystem.
+            type: list
+            sample:
+                - /dev/sda1
+                - /dev/sdb1
+        default_subvolume:
+            description: The id of the filesystem's default subvolume.
+            type: int
+            sample: 5
+        subvolumes:
+            description: A list of dicts containing metadata for all of the filesystem's subvolumes.
+            type: list
+            elements: dict
+            contains:
+                id:
+                    description: An identifier assigned to the subvolume, unique within the containing filesystem.
+                    type: int
+                    sample: 256
+                mountpoints:
+                    description: Paths where the subvolume is mounted on the targeted host.
+                    type: list
+                    sample: ['/home']
+                parent:
+                    description: The identifier of this subvolume's parent.
+                    type: int
+                    sample: 5
+                path:
+                    description: The full path of the subvolume relative to the btrfs fileystem's root.
+                    type: str
+                    sample: /@home
+
+'''
+
+
+from ansible_collections.community.general.plugins.module_utils.btrfs import BtrfsFilesystemsProvider
+from ansible.module_utils.basic import AnsibleModule
+
+
+def run_module():
+    module_args = dict()
+
+    module = AnsibleModule(
+        argument_spec=module_args,
+        supports_check_mode=True
+    )
+
+    provider = BtrfsFilesystemsProvider(module)
+    filesystems = [x.get_summary() for x in provider.get_filesystems()]
+    result = {
+        "filesystems": filesystems,
+    }
+    module.exit_json(**result)
+
+
+def main():
+    run_module()
+
+
+if __name__ == '__main__':
+    main()