Release 4.6.0.

* Proxmox inventory plugin - Fix string to dict conversion (#4348)

  * Re-use the (defined but unused) `plaintext_configs` variable to list
    configuration entries that should be ignored by the string to
    dictionary conversion code. At this point, it only contains the
    `description` string.
  * Convert to a dictionary if the all substrings obtained by splitting
    off the initial value with commas contain a `=` character
  * Limit substring splitting to a single split, so that a substring
    containing `a=b=c` will generate an `a` entry with value `b=c`.

* Added changelog fragment for PR #4349

* Fix changelog fragment for #4349

(cherry picked from commit 3eec63421a)

Co-authored-by: Emmanuel Benoît <tseeker@nocternity.net>

.azure-pipelines/azure-pipelines.yml

@@ -206,14 +206,14 @@ stages:
         parameters:
           testFormat: devel/{0}
           targets:
-            - name: macOS 11.1
-              test: macos/11.1
+            - name: macOS 12.0
+              test: macos/12.0
             - name: RHEL 7.9
               test: rhel/7.9
             - name: RHEL 8.5
               test: rhel/8.5
-            - name: FreeBSD 12.2
-              test: freebsd/12.2
+            - name: FreeBSD 12.3
+              test: freebsd/12.3
             - name: FreeBSD 13.0
               test: freebsd/13.0
           groups:
@@ -310,6 +310,8 @@ stages:
               test: ubuntu1804
             - name: Ubuntu 20.04
               test: ubuntu2004
+            - name: Alpine 3
+              test: alpine3
           groups:
             - 1
             - 2
@@ -324,8 +326,6 @@ stages:
           targets:
             - name: CentOS 6
               test: centos6
-            - name: CentOS 8
-              test: centos8
             - name: Fedora 34
               test: fedora34
             - name: openSUSE 15 py3
@@ -350,6 +350,8 @@ stages:
               test: fedora33
             - name: openSUSE 15 py2
               test: opensuse15py2
+            - name: Alpine 3
+              test: alpine3
           groups:
             - 2
             - 3
@@ -384,6 +386,26 @@ stages:
             - 2
             - 3
 
+### Community Docker
+  - stage: Docker_community_devel
+    displayName: Docker (community images) devel
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: devel/linux-community/{0}
+          targets:
+            - name: Debian Bullseye
+              test: debian-bullseye/3.9
+            - name: ArchLinux
+              test: archlinux/3.10
+            - name: CentOS Stream 8
+              test: centos-stream8/3.8
+          groups:
+            - 1
+            - 2
+            - 3
+
 ### Cloud
   - stage: Cloud_devel
     displayName: Cloud devel
@@ -459,6 +481,7 @@ stages:
       - Docker_2_10
       - Docker_2_11
       - Docker_2_12
+      - Docker_community_devel
       - Cloud_devel
       - Cloud_2_9
       - Cloud_2_10

.github/BOTMETA.yml

@@ -418,6 +418,8 @@ files:
     maintainers: Spredzy
   $modules/cloud/scaleway/scaleway_organization_info.py:
     maintainers: Spredzy
+  $modules/cloud/scaleway/scaleway_private_network.py:
+    maintainers: pastral
   $modules/cloud/scaleway/scaleway_security_group.py:
     maintainers: DenBeke
   $modules/cloud/scaleway/scaleway_security_group_info.py:
@@ -819,7 +821,7 @@ files:
   $modules/packaging/os/opkg.py:
     maintainers: skinp
   $modules/packaging/os/pacman.py:
-    maintainers: elasticdog indrajitr tchernomax
+    maintainers: elasticdog indrajitr tchernomax jraby
     labels: pacman
     ignore: elasticdog
   $modules/packaging/os/pacman_key.py:
@@ -977,6 +979,8 @@ files:
     maintainers: farhan7500 gautamphegde
   $modules/storage/ibm/:
     maintainers: tzure
+  $modules/storage/pmem/pmem.py:
+    maintainers: mizumm
   $modules/storage/vexata/:
     maintainers: vexata
   $modules/storage/zfs/:
@@ -1022,6 +1026,8 @@ files:
   $modules/system/gconftool2.py:
     maintainers: Akasurde kevensen
     labels: gconftool2
+  $modules/system/homectl.py:
+    maintainers: jameslivulpi
   $modules/system/interfaces_file.py:
     maintainers: obourdon hryamzik
     labels: interfaces_file
@@ -1162,7 +1168,8 @@ files:
   $modules/web_infrastructure/jenkins_script.py:
     maintainers: hogarthj
   $modules/web_infrastructure/jira.py:
-    maintainers: Slezhuk tarka pertoft DWSR
+    maintainers: Slezhuk tarka pertoft
+    ignore: DWSR
     labels: jira
   $modules/web_infrastructure/nginx_status_info.py:
     maintainers: resmo
@@ -1231,7 +1238,7 @@ macros:
   team_cyberark_conjur: jvanderhoof ryanprior
   team_e_spirit: MatrixCrawler getjack
   team_flatpak: JayKayy oolongbrothers
-  team_gitlab: Lunik Shaps dj-wasabi marwatk waheedi zanssa scodeman metanovii sh0shin
+  team_gitlab: Lunik Shaps dj-wasabi marwatk waheedi zanssa scodeman metanovii sh0shin nejch lgatellier suukit
   team_hpux: bcoca davx8342
   team_huawei: QijunPan TommyLike edisonxiang freesky-edward hwDCN niuzhenguo xuxiaowei0512 yanzhangi zengchen1024 zhongjun2
   team_ipa: Akasurde Nosmoht fxfitz justchris1

CHANGELOG.rst

@@ -6,6 +6,177 @@ Community General Release Notes
 
 This changelog describes changes after version 3.0.0.
 
+v4.6.0
+======
+
+Release Summary
+---------------
+
+Regular feature and bugfix release.
+
+Minor Changes
+-------------
+
+- jira - when creating a comment, ``fields`` now is used for additional data (https://github.com/ansible-collections/community.general/pull/4304).
+- ldap_entry - add support for recursive deletion (https://github.com/ansible-collections/community.general/issues/3613).
+- mksysb - revamped the module using ``ModuleHelper`` (https://github.com/ansible-collections/community.general/pull/3295).
+- nmcli - add missing connection aliases ``802-3-ethernet`` and ``802-11-wireless`` (https://github.com/ansible-collections/community.general/pull/4108).
+- nmcli - remove nmcli modify dependency on ``type`` parameter (https://github.com/ansible-collections/community.general/issues/2858).
+- npm - add ability to use ``production`` flag when ``ci`` is set (https://github.com/ansible-collections/community.general/pull/4299).
+- pacman - add ``remove_nosave`` parameter to avoid saving modified configuration files as ``.pacsave`` files. (https://github.com/ansible-collections/community.general/pull/4316, https://github.com/ansible-collections/community.general/issues/4315).
+- pacman - now implements proper change detection for ``update_cache=true``. Adds ``cache_updated`` return value to when ``update_cache=true`` to report this result independently of the module's overall changed return value (https://github.com/ansible-collections/community.general/pull/4337).
+- pipx - added options ``editable`` and ``pip_args`` (https://github.com/ansible-collections/community.general/issues/4300).
+- proxmox inventory plugin - add support for client-side jinja filters (https://github.com/ansible-collections/community.general/issues/3553).
+- redis - add authentication parameters ``login_user``, ``tls``, ``validate_certs``, and ``ca_certs`` (https://github.com/ansible-collections/community.general/pull/4207).
+- syslog_json - add option to skip logging of ``gather_facts`` playbook tasks; use v2 callback API (https://github.com/ansible-collections/community.general/pull/4223).
+- zypper - add support for ``--clean-deps`` option to remove packages that depend on a package being removed (https://github.com/ansible-collections/community.general/pull/4195).
+
+Deprecated Features
+-------------------
+
+- pacman - from community.general 5.0.0 on, the ``changed`` status of ``update_cache`` will no longer be ignored if ``name`` or ``upgrade`` is specified. To keep the old behavior, add something like ``register: result`` and ``changed_when: result.packages | length > 0`` to your task (https://github.com/ansible-collections/community.general/pull/4329).
+
+Bugfixes
+--------
+
+- filesize - add support for busybox dd implementation, that is used by default on Alpine linux (https://github.com/ansible-collections/community.general/pull/4288, https://github.com/ansible-collections/community.general/issues/4259).
+- linode inventory plugin - fix configuration handling relating to inventory filtering (https://github.com/ansible-collections/community.general/pull/4336).
+- mksysb - fixed bug for parameter ``backup_dmapi_fs`` was passing the wrong CLI argument (https://github.com/ansible-collections/community.general/pull/3295).
+- pacman - Use ``--groups`` instead of ``--group`` (https://github.com/ansible-collections/community.general/pull/4312).
+- pacman - fix URL based package installation (https://github.com/ansible-collections/community.general/pull/4286, https://github.com/ansible-collections/community.general/issues/4285).
+- pacman - fix ``upgrade=yes`` (https://github.com/ansible-collections/community.general/pull/4275, https://github.com/ansible-collections/community.general/issues/4274).
+- pacman - make sure that ``packages`` is always returned when ``name`` or ``upgrade`` is specified, also if nothing is done (https://github.com/ansible-collections/community.general/pull/4329).
+- pacman - when the ``update_cache`` option is combined with another option such as ``upgrade``, report ``changed`` based on the actions performed by the latter option. This was the behavior in community.general 4.4.0 and before. In community.general 4.5.0, a task combining these options would always report ``changed`` (https://github.com/ansible-collections/community.general/pull/4318).
+- proxmox inventory plugin - always convert strings that follow the ``key=value[,key=value[...]]`` form into dictionaries (https://github.com/ansible-collections/community.general/pull/4349).
+- proxmox inventory plugin - fixed the ``description`` field being ignored if it contained a comma (https://github.com/ansible-collections/community.general/issues/4348).
+- proxmox_kvm - fix error in check when creating or cloning (https://github.com/ansible-collections/community.general/pull/4306).
+- proxmox_kvm - fix error when checking whether Proxmox VM exists (https://github.com/ansible-collections/community.general/pull/4287).
+- terraform - fix ``variable`` handling to allow complex values (https://github.com/ansible-collections/community.general/pull/4281).
+
+Known Issues
+------------
+
+- pacman - ``update_cache`` cannot differentiate between up to date and outdated package lists and will report ``changed`` in both situations (https://github.com/ansible-collections/community.general/pull/4318).
+- pacman - binaries specified in the ``executable`` parameter must support ``--print-format`` in order to be used by this module. In particular, AUR helper ``yay`` is known not to currently support it (https://github.com/ansible-collections/community.general/pull/4312).
+
+v4.5.0
+======
+
+Release Summary
+---------------
+
+Regular feature and bugfix release.
+
+Minor Changes
+-------------
+
+- Avoid internal ansible-core module_utils in favor of equivalent public API available since at least Ansible 2.9. This fixes some instances added since the last time this was fixed (https://github.com/ansible-collections/community.general/pull/4232).
+- ansible_galaxy_install - added option ``no_deps`` to the module (https://github.com/ansible-collections/community.general/issues/4174).
+- gitlab_group_variable - new ``variables`` parameter (https://github.com/ansible-collections/community.general/pull/4038 and https://github.com/ansible-collections/community.general/issues/4074).
+- keycloak_* modules - added connection timeout parameter when calling server (https://github.com/ansible-collections/community.general/pull/4168).
+- linode inventory plugin - add support for caching inventory results (https://github.com/ansible-collections/community.general/pull/4179).
+- opentelemetry_plugin - enrich service when using the ``jenkins``, ``hetzner`` or ``jira`` modules (https://github.com/ansible-collections/community.general/pull/4105).
+- pacman - the module has been rewritten and is now much faster when using ``state=latest``. Operations are now done all packages at once instead of package per package and the configured output format of ``pacman`` no longer affect the module's operation. (https://github.com/ansible-collections/community.general/pull/3907, https://github.com/ansible-collections/community.general/issues/3783, https://github.com/ansible-collections/community.general/issues/4079)
+- passwordstore lookup plugin - add configurable ``lock`` and ``locktimeout`` options to avoid race conditions in itself and in the ``pass`` utility it calls. By default, the plugin now locks on write operations (https://github.com/ansible-collections/community.general/pull/4194).
+- proxmox modules - move common code into ``module_utils`` (https://github.com/ansible-collections/community.general/pull/4029).
+- proxmox_kvm - added EFI disk support when creating VM with OVMF UEFI BIOS with new ``efidisk0`` option (https://github.com/ansible-collections/community.general/pull/4106, https://github.com/ansible-collections/community.general/issues/1638).
+- proxmox_kwm - add ``win11`` to ``ostype`` parameter for Windows 11 and Windows Server 2022 support (https://github.com/ansible-collections/community.general/issues/4023, https://github.com/ansible-collections/community.general/pull/4191).
+
+Bugfixes
+--------
+
+- dconf - skip processes that disappeared while we inspected them (https://github.com/ansible-collections/community.general/issues/4151).
+- gitlab_group_variable - add missing documentation about GitLab versions that support ``environment_scope`` and ``variable_type`` (https://github.com/ansible-collections/community.general/pull/4038).
+- gitlab_group_variable - allow to set same variable name under different environment scopes. Due this change, the return value ``group_variable`` differs from previous version in check mode. It was counting ``updated`` values, because it was accidentally overwriting environment scopes (https://github.com/ansible-collections/community.general/pull/4038).
+- gitlab_group_variable - fix idempotent change behaviour for float and integer variables (https://github.com/ansible-collections/community.general/pull/4038).
+- gitlab_project_variable - ``value`` is not necessary when deleting variables (https://github.com/ansible-collections/community.general/pull/4150).
+- gitlab_runner - make ``project`` and ``owned`` mutually exclusive (https://github.com/ansible-collections/community.general/pull/4136).
+- homebrew_cask - fix force install operation (https://github.com/ansible-collections/community.general/issues/3703).
+- imc_rest - fixes the module failure due to the usage of ``itertools.izip_longest`` which is not available in Python 3 (https://github.com/ansible-collections/community.general/issues/4206).
+- ini_file - when removing nothing do not report changed (https://github.com/ansible-collections/community.general/issues/4154).
+- keycloak_user_federation - creating a user federation while specifying an ID (that does not exist yet) no longer fail with a 404 Not Found (https://github.com/ansible-collections/community.general/pull/4212).
+- keycloak_user_federation - mappers auto-created by keycloak are matched and merged by their name and no longer create duplicated entries (https://github.com/ansible-collections/community.general/pull/4212).
+- mail callback plugin - fix encoding of the name of sender and recipient (https://github.com/ansible-collections/community.general/issues/4060, https://github.com/ansible-collections/community.general/pull/4061).
+- passwordstore lookup plugin - fix error detection for non-English locales (https://github.com/ansible-collections/community.general/pull/4219).
+- passwordstore lookup plugin - prevent returning path names as passwords by accident (https://github.com/ansible-collections/community.general/issues/4185, https://github.com/ansible-collections/community.general/pull/4192).
+- vdo - fix options error (https://github.com/ansible-collections/community.general/pull/4163).
+- yum_versionlock - fix matching of existing entries with names passed to the module. Match yum and dnf lock format (https://github.com/ansible-collections/community.general/pull/4183).
+
+New Modules
+-----------
+
+Cloud
+~~~~~
+
+scaleway
+^^^^^^^^
+
+- scaleway_private_network - Scaleway private network management
+
+Storage
+~~~~~~~
+
+pmem
+^^^^
+
+- pmem - Configure Intel Optane Persistent Memory modules
+
+v4.4.0
+======
+
+Release Summary
+---------------
+
+Regular features and bugfixes release.
+
+Minor Changes
+-------------
+
+- cobbler inventory plugin - add ``include_profiles`` option (https://github.com/ansible-collections/community.general/pull/4068).
+- gitlab_project_variable - new ``variables`` parameter (https://github.com/ansible-collections/community.general/issues/4038).
+- icinga2 inventory plugin - implemented constructed interface (https://github.com/ansible-collections/community.general/pull/4088).
+- linode inventory plugin - allow templating of ``access_token`` variable in Linode inventory plugin (https://github.com/ansible-collections/community.general/pull/4040).
+- lists_mergeby filter plugin - add parameters ``list_merge`` and ``recursive``. These are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9 (https://github.com/ansible-collections/community.general/pull/4058).
+- lxc_container - added ``wait_for_container`` parameter. If ``true`` the module will wait until the running task reports success as the status (https://github.com/ansible-collections/community.general/pull/4039).
+- mail callback plugin - add ``Message-ID`` and ``Date`` headers (https://github.com/ansible-collections/community.general/issues/4055, https://github.com/ansible-collections/community.general/pull/4056).
+- mail callback plugin - properly use Ansible's option handling to split lists (https://github.com/ansible-collections/community.general/pull/4140).
+- nmcli - adds ``routes6`` and ``route_metric6`` parameters for supporting IPv6 routes (https://github.com/ansible-collections/community.general/issues/4059).
+- opennebula - add the release action for VMs in the ``HOLD`` state (https://github.com/ansible-collections/community.general/pull/4036).
+- opentelemetry_plugin - enrich service when using the ``docker_login`` (https://github.com/ansible-collections/community.general/pull/4104).
+- proxmox modules - move ``HAS_PROXMOXER`` check into ``module_utils`` (https://github.com/ansible-collections/community.general/pull/4030).
+- scaleway inventory plugin - add profile parameter ``scw_profile`` (https://github.com/ansible-collections/community.general/pull/4049).
+- snap - add option ``options`` permitting to set options using the ``snap set`` command (https://github.com/ansible-collections/community.general/pull/3943).
+
+Deprecated Features
+-------------------
+
+- mail callback plugin - not specifying ``sender`` is deprecated and will be disallowed in community.general 6.0.0 (https://github.com/ansible-collections/community.general/pull/4140).
+
+Bugfixes
+--------
+
+- cargo - fix detection of outdated packages when ``state=latest`` (https://github.com/ansible-collections/community.general/pull/4052).
+- cargo - fix incorrectly reported changed status for packages with a name containing a hyphen (https://github.com/ansible-collections/community.general/issues/4044, https://github.com/ansible-collections/community.general/pull/4052).
+- gitlab_project_variable - add missing documentation about GitLab versions that support ``environment_scope`` and ``variable_type`` (https://github.com/ansible-collections/community.general/issues/4038).
+- gitlab_project_variable - allow to set same variable name under different environment scopes. Due this change, the return value ``project_variable`` differs from previous version in check mode. It was counting ``updated`` values, because it was accidentally overwriting environment scopes (https://github.com/ansible-collections/community.general/issues/4038).
+- gitlab_project_variable - fix idempotent change behaviour for float and integer variables (https://github.com/ansible-collections/community.general/issues/4038).
+- gitlab_runner - use correct API endpoint to create and retrieve project level runners when using ``project`` (https://github.com/ansible-collections/community.general/pull/3965).
+- listen_ports_facts - local port regex was not handling well IPv6 only binding. Fixes the regex for ``ss`` (https://github.com/ansible-collections/community.general/pull/4092).
+- mail callback plugin - fix crash on Python 3 (https://github.com/ansible-collections/community.general/issues/4025, https://github.com/ansible-collections/community.general/pull/4026).
+- opentelemetry - fix generating a trace with a task containing ``no_log: true`` (https://github.com/ansible-collections/community.general/pull/4043).
+- python_requirements_info - store ``mismatched`` return values per package as documented in the module (https://github.com/ansible-collections/community.general/pull/4078).
+- yarn - fix incorrect handling of ``yarn list`` and ``yarn global list`` output that could result in fatal error (https://github.com/ansible-collections/community.general/pull/4050).
+- yarn - fix incorrectly reported status when installing a package globally (https://github.com/ansible-collections/community.general/issues/4045, https://github.com/ansible-collections/community.general/pull/4050).
+- yarn - fix missing ``~`` expansion in yarn global install folder which resulted in incorrect task status (https://github.com/ansible-collections/community.general/issues/4045, https://github.com/ansible-collections/community.general/pull/4048).
+
+New Modules
+-----------
+
+System
+~~~~~~
+
+- homectl - Manage user accounts with systemd-homed
+
 v4.3.0
 ======
 

CONTRIBUTING.md

@@ -24,7 +24,7 @@ Also, consider taking up a valuable, reviewed, but abandoned pull request which
 
 * Try committing your changes with an informative but short commit message.
 * Do not squash your commits and force-push to your branch if not needed. Reviews of your pull request are much easier with individual commits to comprehend the pull request history. All commits of your pull request branch will be squashed into one commit by GitHub upon merge.
-* Do not add merge commits to your PR. The bot will complain and you will have to rebase ([instructions for rebasing](https://docs.ansible.com/ansible/latest/dev_guide/developing_rebasing.html)) to remove them before your PR can be merged. To avoid that git automatically does merges during pulls, you can configure it to do rebases instead by running `git config pull.rebase true` inside the respository checkout.
+* Do not add merge commits to your PR. The bot will complain and you will have to rebase ([instructions for rebasing](https://docs.ansible.com/ansible/latest/dev_guide/developing_rebasing.html)) to remove them before your PR can be merged. To avoid that git automatically does merges during pulls, you can configure it to do rebases instead by running `git config pull.rebase true` inside the repository checkout.
 * Make sure your PR includes a [changelog fragment](https://docs.ansible.com/ansible/devel/community/development_process.html#changelogs-how-to). (You must not include a fragment for new modules or new plugins, except for test and filter plugins. Also you shouldn't include one for docs-only changes. If you're not sure, simply don't include one, we'll tell you whether one is needed or not :) )
 * Avoid reformatting unrelated parts of the codebase in your PR. These types of changes will likely be requested for reversion, create additional work for reviewers, and may cause approval to be delayed.
 
@@ -36,6 +36,54 @@ If you want to test a PR locally, refer to [our testing guide](https://github.co
 
 If you find any inconsistencies or places in this document which can be improved, feel free to raise an issue or pull request to fix it.
 
+## Run sanity, unit or integration tests locally
+
+You have to check out the repository into a specific path structure to be able to run `ansible-test`. The path to the git checkout must end with `.../ansible_collections/community/general`. Please see [our testing guide](https://github.com/ansible/community-docs/blob/main/test_pr_locally_guide.rst) for instructions on how to check out the repository into a correct path structure. The short version of these instructions is:
+
+```.bash
+mkdir -p ~/dev/ansible_collections/community
+git clone https://github.com/ansible-collections/community.general.git ~/dev/ansible_collections/community/general
+cd ~/dev/ansible_collections/community/general
+```
+
+Then you can run `ansible-test` (which is a part of [ansible-core](https://pypi.org/project/ansible-core/)) inside the checkout. The following example commands expect that you have installed Docker or Podman. Note that Podman has only been supported by more recent ansible-core releases. If you are using Docker, the following will work with Ansible 2.9+.
+
+The following commands show how to run sanity tests:
+
+```.bash
+# Run sanity tests for all files in the collection:
+ansible-test sanity --docker -v
+
+# Run sanity tests for the given files and directories:
+ansible-test sanity --docker -v plugins/modules/system/pids.py tests/integration/targets/pids/
+```
+
+The following commands show how to run unit tests:
+
+```.bash
+# Run all unit tests:
+ansible-test units --docker -v
+
+# Run all unit tests for one Python version (a lot faster):
+ansible-test units --docker -v --python 3.8
+
+# Run a specific unit test (for the nmcli module) for one Python version:
+ansible-test units --docker -v --python 3.8 tests/unit/plugins/modules/net_tools/test_nmcli.py
+```
+
+The following commands show how to run integration tests:
+
+```.bash
+# Run integration tests for the interfaces_files module in a Docker container using the
+# fedora35 operating system image (the supported images depend on your ansible-core version):
+ansible-test integration --docker fedora35 -v interfaces_file
+
+# Run integration tests for the flattened lookup **without any isolation**:
+ansible-test integration -v lookup_flattened
+```
+
+If you are unsure about the integration test target name for a module or plugin, you can take a look in `tests/integration/targets/`. Tests for plugins have the plugin type prepended.
+
 ## Creating new modules or plugins
 
 Creating new modules and plugins requires a bit more work than other Pull Requests.

changelogs/changelog.yaml

@@ -1309,3 +1309,279 @@ releases:
         name: counter
         namespace: null
     release_date: '2022-01-11'
+  4.4.0:
+    changes:
+      bugfixes:
+      - cargo - fix detection of outdated packages when ``state=latest`` (https://github.com/ansible-collections/community.general/pull/4052).
+      - cargo - fix incorrectly reported changed status for packages with a name containing
+        a hyphen (https://github.com/ansible-collections/community.general/issues/4044,
+        https://github.com/ansible-collections/community.general/pull/4052).
+      - gitlab_project_variable - add missing documentation about GitLab versions
+        that support ``environment_scope`` and ``variable_type`` (https://github.com/ansible-collections/community.general/issues/4038).
+      - 'gitlab_project_variable - allow to set same variable name under different
+        environment scopes. Due this change, the return value ``project_variable``
+        differs from previous version in check mode. It was counting ``updated`` values,
+        because it was accidentally overwriting environment scopes (https://github.com/ansible-collections/community.general/issues/4038).
+
+        '
+      - gitlab_project_variable - fix idempotent change behaviour for float and integer
+        variables (https://github.com/ansible-collections/community.general/issues/4038).
+      - gitlab_runner - use correct API endpoint to create and retrieve project level
+        runners when using ``project`` (https://github.com/ansible-collections/community.general/pull/3965).
+      - listen_ports_facts - local port regex was not handling well IPv6 only binding.
+        Fixes the regex for ``ss`` (https://github.com/ansible-collections/community.general/pull/4092).
+      - mail callback plugin - fix crash on Python 3 (https://github.com/ansible-collections/community.general/issues/4025,
+        https://github.com/ansible-collections/community.general/pull/4026).
+      - 'opentelemetry - fix generating a trace with a task containing ``no_log: true``
+        (https://github.com/ansible-collections/community.general/pull/4043).'
+      - python_requirements_info - store ``mismatched`` return values per package
+        as documented in the module (https://github.com/ansible-collections/community.general/pull/4078).
+      - yarn - fix incorrect handling of ``yarn list`` and ``yarn global list`` output
+        that could result in fatal error (https://github.com/ansible-collections/community.general/pull/4050).
+      - yarn - fix incorrectly reported status when installing a package globally
+        (https://github.com/ansible-collections/community.general/issues/4045, https://github.com/ansible-collections/community.general/pull/4050).
+      - yarn - fix missing ``~`` expansion in yarn global install folder which resulted
+        in incorrect task status (https://github.com/ansible-collections/community.general/issues/4045,
+        https://github.com/ansible-collections/community.general/pull/4048).
+      deprecated_features:
+      - mail callback plugin - not specifying ``sender`` is deprecated and will be
+        disallowed in community.general 6.0.0 (https://github.com/ansible-collections/community.general/pull/4140).
+      minor_changes:
+      - cobbler inventory plugin - add ``include_profiles`` option (https://github.com/ansible-collections/community.general/pull/4068).
+      - gitlab_project_variable - new ``variables`` parameter (https://github.com/ansible-collections/community.general/issues/4038).
+      - icinga2 inventory plugin - implemented constructed interface (https://github.com/ansible-collections/community.general/pull/4088).
+      - linode inventory plugin - allow templating of ``access_token`` variable in
+        Linode inventory plugin (https://github.com/ansible-collections/community.general/pull/4040).
+      - lists_mergeby filter plugin - add parameters ``list_merge`` and ``recursive``.
+        These are only supported when used with ansible-base 2.10 or ansible-core,
+        but not with Ansible 2.9 (https://github.com/ansible-collections/community.general/pull/4058).
+      - lxc_container - added ``wait_for_container`` parameter. If ``true`` the module
+        will wait until the running task reports success as the status (https://github.com/ansible-collections/community.general/pull/4039).
+      - mail callback plugin - add ``Message-ID`` and ``Date`` headers (https://github.com/ansible-collections/community.general/issues/4055,
+        https://github.com/ansible-collections/community.general/pull/4056).
+      - mail callback plugin - properly use Ansible's option handling to split lists
+        (https://github.com/ansible-collections/community.general/pull/4140).
+      - nmcli - adds ``routes6`` and ``route_metric6`` parameters for supporting IPv6
+        routes (https://github.com/ansible-collections/community.general/issues/4059).
+      - opennebula - add the release action for VMs in the ``HOLD`` state (https://github.com/ansible-collections/community.general/pull/4036).
+      - opentelemetry_plugin - enrich service when using the ``docker_login`` (https://github.com/ansible-collections/community.general/pull/4104).
+      - proxmox modules - move ``HAS_PROXMOXER`` check into ``module_utils`` (https://github.com/ansible-collections/community.general/pull/4030).
+      - scaleway inventory plugin - add profile parameter ``scw_profile`` (https://github.com/ansible-collections/community.general/pull/4049).
+      - snap - add option ``options`` permitting to set options using the ``snap set``
+        command (https://github.com/ansible-collections/community.general/pull/3943).
+      release_summary: Regular features and bugfixes release.
+    fragments:
+    - 3935-use-gitlab-instance-runner-to-create-runner.yml
+    - 3943-add-option-options-to-snap-module.yml
+    - 4.4.0.yml
+    - 4026-fix-mail-callback.yml
+    - 4030-proxmox-has-proxmoxer.yml
+    - 4036-onevm-add-release-action.yaml
+    - 4038-fix-and-rework-gitlb-project-variable.yml
+    - 4039-cluster-container-wait.yml
+    - 4040-linode-token-templating.yaml
+    - 4043-fix-no-log-opentelemetry.yml
+    - 4048-expand-tilde-in-yarn-global-install-folder.yaml
+    - 4049-profile-for-scaleway-inventory.yml
+    - 4050-properly-parse-json-lines-output-from-yarn.yaml
+    - 4052-fix-detection-of-installed-cargo-packages-with-hyphens.yaml
+    - 4056-add-missing-mail-headers.yml
+    - 4058-lists_mergeby-add-parameters.yml
+    - 4062-nmcli-ipv6-routes-support.yml
+    - 4068-add-include_file-option.yml
+    - 4078-python_requirements_info.yaml
+    - 4088-add-constructed-interface-for-icinga2-inventory.yml
+    - 4092-fix_local_ports_regex_listen_ports_facts.yaml
+    - 4104-opentelemetry_plugin-enrich_docker_login.yaml
+    - 4140-mail-callback-options.yml
+    modules:
+    - description: Manage user accounts with systemd-homed
+      name: homectl
+      namespace: system
+    release_date: '2022-02-01'
+  4.5.0:
+    changes:
+      bugfixes:
+      - dconf - skip processes that disappeared while we inspected them (https://github.com/ansible-collections/community.general/issues/4151).
+      - gitlab_group_variable - add missing documentation about GitLab versions that
+        support ``environment_scope`` and ``variable_type`` (https://github.com/ansible-collections/community.general/pull/4038).
+      - 'gitlab_group_variable - allow to set same variable name under different environment
+        scopes. Due this change, the return value ``group_variable`` differs from
+        previous version in check mode. It was counting ``updated`` values, because
+        it was accidentally overwriting environment scopes (https://github.com/ansible-collections/community.general/pull/4038).
+
+        '
+      - gitlab_group_variable - fix idempotent change behaviour for float and integer
+        variables (https://github.com/ansible-collections/community.general/pull/4038).
+      - gitlab_project_variable - ``value`` is not necessary when deleting variables
+        (https://github.com/ansible-collections/community.general/pull/4150).
+      - gitlab_runner - make ``project`` and ``owned`` mutually exclusive (https://github.com/ansible-collections/community.general/pull/4136).
+      - homebrew_cask - fix force install operation (https://github.com/ansible-collections/community.general/issues/3703).
+      - imc_rest - fixes the module failure due to the usage of ``itertools.izip_longest``
+        which is not available in Python 3 (https://github.com/ansible-collections/community.general/issues/4206).
+      - ini_file - when removing nothing do not report changed (https://github.com/ansible-collections/community.general/issues/4154).
+      - keycloak_user_federation - creating a user federation while specifying an
+        ID (that does not exist yet) no longer fail with a 404 Not Found (https://github.com/ansible-collections/community.general/pull/4212).
+      - keycloak_user_federation - mappers auto-created by keycloak are matched and
+        merged by their name and no longer create duplicated entries (https://github.com/ansible-collections/community.general/pull/4212).
+      - mail callback plugin - fix encoding of the name of sender and recipient (https://github.com/ansible-collections/community.general/issues/4060,
+        https://github.com/ansible-collections/community.general/pull/4061).
+      - passwordstore lookup plugin - fix error detection for non-English locales
+        (https://github.com/ansible-collections/community.general/pull/4219).
+      - passwordstore lookup plugin - prevent returning path names as passwords by
+        accident (https://github.com/ansible-collections/community.general/issues/4185,
+        https://github.com/ansible-collections/community.general/pull/4192).
+      - vdo - fix options error (https://github.com/ansible-collections/community.general/pull/4163).
+      - yum_versionlock - fix matching of existing entries with names passed to the
+        module. Match yum and dnf lock format (https://github.com/ansible-collections/community.general/pull/4183).
+      minor_changes:
+      - Avoid internal ansible-core module_utils in favor of equivalent public API
+        available since at least Ansible 2.9. This fixes some instances added since
+        the last time this was fixed (https://github.com/ansible-collections/community.general/pull/4232).
+      - ansible_galaxy_install - added option ``no_deps`` to the module (https://github.com/ansible-collections/community.general/issues/4174).
+      - gitlab_group_variable - new ``variables`` parameter (https://github.com/ansible-collections/community.general/pull/4038
+        and https://github.com/ansible-collections/community.general/issues/4074).
+      - keycloak_* modules - added connection timeout parameter when calling server
+        (https://github.com/ansible-collections/community.general/pull/4168).
+      - linode inventory plugin - add support for caching inventory results (https://github.com/ansible-collections/community.general/pull/4179).
+      - opentelemetry_plugin - enrich service when using the ``jenkins``, ``hetzner``
+        or ``jira`` modules (https://github.com/ansible-collections/community.general/pull/4105).
+      - pacman - the module has been rewritten and is now much faster when using ``state=latest``.
+        Operations are now done all packages at once instead of package per package
+        and the configured output format of ``pacman`` no longer affect the module's
+        operation. (https://github.com/ansible-collections/community.general/pull/3907,
+        https://github.com/ansible-collections/community.general/issues/3783, https://github.com/ansible-collections/community.general/issues/4079)
+      - passwordstore lookup plugin - add configurable ``lock`` and ``locktimeout``
+        options to avoid race conditions in itself and in the ``pass`` utility it
+        calls. By default, the plugin now locks on write operations (https://github.com/ansible-collections/community.general/pull/4194).
+      - proxmox modules - move common code into ``module_utils`` (https://github.com/ansible-collections/community.general/pull/4029).
+      - proxmox_kvm - added EFI disk support when creating VM with OVMF UEFI BIOS
+        with new ``efidisk0`` option (https://github.com/ansible-collections/community.general/pull/4106,
+        https://github.com/ansible-collections/community.general/issues/1638).
+      - proxmox_kwm - add ``win11`` to ``ostype`` parameter for Windows 11 and Windows
+        Server 2022 support (https://github.com/ansible-collections/community.general/issues/4023,
+        https://github.com/ansible-collections/community.general/pull/4191).
+      release_summary: Regular feature and bugfix release.
+    fragments:
+    - 3703-force-install-homebrew-cask.yml
+    - 3907-pacman-speedup.yml
+    - 3916-fix-vdo-options-type.yml
+    - 4.5.0.yml
+    - 4029-proxmox-refactor.yml
+    - 4061-fix-mail-recipient-encoding.yml
+    - 4086-rework_of_gitlab_proyect_variable_over_gitlab_group_variable.yml
+    - 4105-opentelemetry_plugin-enrich_jira_hetzner_jenkins_services.yaml
+    - 4106-proxmox-efidisk0-support.yaml
+    - 4136-gitlab_runner-make-project-owned-mutually-exclusive.yml
+    - 4150-gitlab-project-variable-absent-fix.yml
+    - 4151-dconf-catch-psutil-nosuchprocess.yaml
+    - 4154-ini_file_changed.yml
+    - 4168-add-keycloak-url-timeout.yml
+    - 4179-linode-inventory-cache.yaml
+    - 4183-fix-yum_versionlock.yaml
+    - 4191-proxmox-add-win11.yml
+    - 4192-improve-passwordstore-consistency.yml
+    - 4194-configurable-passwordstore-locking.yml
+    - 4206-imc-rest-module.yaml
+    - 4212-fixes-for-keycloak-user-federation.yml
+    - 4219-passwordstore-locale-fix.yml
+    - 4232-text-converter-import.yml
+    - 4240-ansible_galaxy_install-no_deps.yml
+    modules:
+    - description: Configure Intel Optane Persistent Memory modules
+      name: pmem
+      namespace: storage.pmem
+    - description: Scaleway private network management
+      name: scaleway_private_network
+      namespace: cloud.scaleway
+    release_date: '2022-02-22'
+  4.6.0:
+    changes:
+      bugfixes:
+      - filesize - add support for busybox dd implementation, that is used by default
+        on Alpine linux (https://github.com/ansible-collections/community.general/pull/4288,
+        https://github.com/ansible-collections/community.general/issues/4259).
+      - linode inventory plugin - fix configuration handling relating to inventory
+        filtering (https://github.com/ansible-collections/community.general/pull/4336).
+      - mksysb - fixed bug for parameter ``backup_dmapi_fs`` was passing the wrong
+        CLI argument (https://github.com/ansible-collections/community.general/pull/3295).
+      - pacman - Use ``--groups`` instead of ``--group`` (https://github.com/ansible-collections/community.general/pull/4312).
+      - pacman - fix URL based package installation (https://github.com/ansible-collections/community.general/pull/4286,
+        https://github.com/ansible-collections/community.general/issues/4285).
+      - pacman - fix ``upgrade=yes`` (https://github.com/ansible-collections/community.general/pull/4275,
+        https://github.com/ansible-collections/community.general/issues/4274).
+      - pacman - make sure that ``packages`` is always returned when ``name`` or ``upgrade``
+        is specified, also if nothing is done (https://github.com/ansible-collections/community.general/pull/4329).
+      - pacman - when the ``update_cache`` option is combined with another option
+        such as ``upgrade``, report ``changed`` based on the actions performed by
+        the latter option. This was the behavior in community.general 4.4.0 and before.
+        In community.general 4.5.0, a task combining these options would always report
+        ``changed`` (https://github.com/ansible-collections/community.general/pull/4318).
+      - proxmox inventory plugin - always convert strings that follow the ``key=value[,key=value[...]]``
+        form into dictionaries (https://github.com/ansible-collections/community.general/pull/4349).
+      - proxmox inventory plugin - fixed the ``description`` field being ignored if
+        it contained a comma (https://github.com/ansible-collections/community.general/issues/4348).
+      - proxmox_kvm - fix error in check when creating or cloning (https://github.com/ansible-collections/community.general/pull/4306).
+      - proxmox_kvm - fix error when checking whether Proxmox VM exists (https://github.com/ansible-collections/community.general/pull/4287).
+      - terraform - fix ``variable`` handling to allow complex values (https://github.com/ansible-collections/community.general/pull/4281).
+      deprecated_features:
+      - 'pacman - from community.general 5.0.0 on, the ``changed`` status of ``update_cache``
+        will no longer be ignored if ``name`` or ``upgrade`` is specified. To keep
+        the old behavior, add something like ``register: result`` and ``changed_when:
+        result.packages | length > 0`` to your task (https://github.com/ansible-collections/community.general/pull/4329).'
+      known_issues:
+      - pacman - ``update_cache`` cannot differentiate between up to date and outdated
+        package lists and will report ``changed`` in both situations (https://github.com/ansible-collections/community.general/pull/4318).
+      - pacman - binaries specified in the ``executable`` parameter must support ``--print-format``
+        in order to be used by this module. In particular, AUR helper ``yay`` is known
+        not to currently support it (https://github.com/ansible-collections/community.general/pull/4312).
+      minor_changes:
+      - jira - when creating a comment, ``fields`` now is used for additional data
+        (https://github.com/ansible-collections/community.general/pull/4304).
+      - ldap_entry - add support for recursive deletion (https://github.com/ansible-collections/community.general/issues/3613).
+      - mksysb - revamped the module using ``ModuleHelper`` (https://github.com/ansible-collections/community.general/pull/3295).
+      - nmcli - add missing connection aliases ``802-3-ethernet`` and ``802-11-wireless``
+        (https://github.com/ansible-collections/community.general/pull/4108).
+      - nmcli - remove nmcli modify dependency on ``type`` parameter (https://github.com/ansible-collections/community.general/issues/2858).
+      - npm - add ability to use ``production`` flag when ``ci`` is set (https://github.com/ansible-collections/community.general/pull/4299).
+      - pacman - add ``remove_nosave`` parameter to avoid saving modified configuration
+        files as ``.pacsave`` files. (https://github.com/ansible-collections/community.general/pull/4316,
+        https://github.com/ansible-collections/community.general/issues/4315).
+      - pacman - now implements proper change detection for ``update_cache=true``.
+        Adds ``cache_updated`` return value to when ``update_cache=true`` to report
+        this result independently of the module's overall changed return value (https://github.com/ansible-collections/community.general/pull/4337).
+      - pipx - added options ``editable`` and ``pip_args`` (https://github.com/ansible-collections/community.general/issues/4300).
+      - proxmox inventory plugin - add support for client-side jinja filters (https://github.com/ansible-collections/community.general/issues/3553).
+      - redis - add authentication parameters ``login_user``, ``tls``, ``validate_certs``,
+        and ``ca_certs`` (https://github.com/ansible-collections/community.general/pull/4207).
+      - syslog_json - add option to skip logging of ``gather_facts`` playbook tasks;
+        use v2 callback API (https://github.com/ansible-collections/community.general/pull/4223).
+      - zypper - add support for ``--clean-deps`` option to remove packages that depend
+        on a package being removed (https://github.com/ansible-collections/community.general/pull/4195).
+      release_summary: Regular feature and bugfix release.
+    fragments:
+    - 3295-mksysb-revamp.yaml
+    - 4.6.0.yml
+    - 4108-nmcli-support-modifcation-without-type-param.yml
+    - 4192-zypper-add-clean-deps.yml
+    - 4207-add-redis-tls-support.yml
+    - 4223-syslog-json-skip-syslog-option.yml
+    - 4275-pacman-sysupgrade.yml
+    - 4281-terraform-complex-variables.yml
+    - 4286-pacman-url-pkgs.yml
+    - 4287-fix-proxmox-vm-chek.yml
+    - 4288-fix-4259-support-busybox-dd.yml
+    - 4299-npm-add-production-with-ci-flag.yml
+    - 4303-pipx-editable.yml
+    - 4304-jira-fields-in-comment.yml
+    - 4306-proxmox-fix-error-on-vm-clone.yml
+    - 4312-pacman-groups.yml
+    - 4316-pacman-remove-nosave.yml
+    - 4318-pacman-restore-old-changed-behavior.yml
+    - 4330-pacman-packages-update_cache.yml
+    - 4336-linode-inventory-filtering.yaml
+    - 4337-pacman-update_cache.yml
+    - 4349-proxmox-inventory-dict-facts.yml
+    - 4352-proxmox-inventory-filters.yml
+    - 4355-ldap-recursive-delete.yml
+    release_date: '2022-03-15'

docs/docsite/helper/lists_mergeby/default-common.yml

@@ -0,0 +1,13 @@
+list1:
+  - name: foo
+    extra: true
+  - name: bar
+    extra: false
+  - name: meh
+    extra: true
+
+list2:
+  - name: foo
+    path: /foo
+  - name: baz
+    path: /baz

docs/docsite/helper/lists_mergeby/default-recursive-true.yml

@@ -0,0 +1,19 @@
+list1:
+  - name: myname01
+    param01:
+      x: default_value
+      y: default_value
+      list:
+        - default_value
+  - name: myname02
+    param01: [1, 1, 2, 3]
+
+list2:
+  - name: myname01
+    param01:
+      y: patch_value
+      z: patch_value
+      list:
+        - patch_value
+  - name: myname02
+    param01: [3, 4, 4, {key: value}]

docs/docsite/helper/lists_mergeby/example-001.yml

@@ -0,0 +1,10 @@
+---
+- name: 1. Merge two lists by common attribute 'name'
+  include_vars:
+    dir: example-001_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-001.out

docs/docsite/helper/lists_mergeby/example-001_vars/default-common.yml

@@ -0,0 +1 @@
+../default-common.yml

docs/docsite/helper/lists_mergeby/example-001_vars/list3.yml

@@ -0,0 +1,2 @@
+list3: "{{ list1|
+           community.general.lists_mergeby(list2, 'name') }}"

docs/docsite/helper/lists_mergeby/example-002.yml

@@ -0,0 +1,10 @@
+---
+- name: 2. Merge two lists by common attribute 'name'
+  include_vars:
+    dir: example-002_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-002.out

docs/docsite/helper/lists_mergeby/example-002_vars/default-common.yml

@@ -0,0 +1 @@
+../default-common.yml

docs/docsite/helper/lists_mergeby/example-002_vars/list3.yml

@@ -0,0 +1,2 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name') }}"

docs/docsite/helper/lists_mergeby/example-003.yml

@@ -0,0 +1,10 @@
+---
+- name: 3. Merge recursive by 'name', replace lists (default)
+  include_vars:
+    dir: example-003_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-003.out

docs/docsite/helper/lists_mergeby/example-003_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-003_vars/list3.yml

@@ -0,0 +1,3 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true) }}"

docs/docsite/helper/lists_mergeby/example-004.yml

@@ -0,0 +1,10 @@
+---
+- name: 4. Merge recursive by 'name', keep lists
+  include_vars:
+    dir: example-004_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-004.out

docs/docsite/helper/lists_mergeby/example-004_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-004_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='keep') }}"

docs/docsite/helper/lists_mergeby/example-005.yml

@@ -0,0 +1,10 @@
+---
+- name: 5. Merge recursive by 'name', append lists
+  include_vars:
+    dir: example-005_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-005.out

docs/docsite/helper/lists_mergeby/example-005_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-005_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='append') }}"

docs/docsite/helper/lists_mergeby/example-006.yml

@@ -0,0 +1,10 @@
+---
+- name: 6. Merge recursive by 'name', prepend lists
+  include_vars:
+    dir: example-006_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-006.out

docs/docsite/helper/lists_mergeby/example-006_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-006_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='prepend') }}"

docs/docsite/helper/lists_mergeby/example-007.yml

@@ -0,0 +1,10 @@
+---
+- name: 7. Merge recursive by 'name', append lists 'remove present'
+  include_vars:
+    dir: example-007_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-007.out

docs/docsite/helper/lists_mergeby/example-007_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-007_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='append_rp') }}"

docs/docsite/helper/lists_mergeby/example-008.yml

@@ -0,0 +1,10 @@
+---
+- name: 8. Merge recursive by 'name', prepend lists 'remove present'
+  include_vars:
+    dir: example-008_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-008.out

docs/docsite/helper/lists_mergeby/example-008_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-008_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='prepend_rp') }}"

docs/docsite/helper/lists_mergeby/examples.yml

@@ -0,0 +1,50 @@
+---
+examples:
+  - label: 'In the example below the lists are merged by the attribute ``name``:'
+    file: example-001_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-001.out
+    lang: 'yaml'
+  - label: 'It is possible to use a list of lists as an input of the filter:'
+    file: example-002_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces the same result as in the previous example:'
+    file: example-002.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=replace`` (default):'
+    file: example-003_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-003.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=keep``:'
+    file: example-004_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-004.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=append``:'
+    file: example-005_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-005.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=prepend``:'
+    file: example-006_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-006.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=append_rp``:'
+    file: example-007_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-007.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=prepend_rp``:'
+    file: example-008_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-008.out
+    lang: 'yaml'

docs/docsite/helper/lists_mergeby/examples_all.rst.j2

@@ -0,0 +1,8 @@
+{% for i in examples %}
+{{ i.label }}
+
+.. code-block:: {{ i.lang }}
+
+  {{ lookup('file', i.file)|indent(2) }}
+
+{% endfor %}

docs/docsite/helper/lists_mergeby/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2

@@ -0,0 +1,57 @@
+Merging lists of dictionaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have two or more lists of dictionaries and want to combine them into a list of merged dictionaries, where the dictionaries are merged by an attribute, you can use the ``lists_mergeby`` filter.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ref:`the documentation for the community.general.yaml callback plugin <ansible_collections.community.general.yaml_callback>`.
+
+Let us use the lists below in the following examples:
+
+.. code-block:: yaml
+
+  {{ lookup('file', 'default-common.yml')|indent(2) }}
+
+{% for i in examples[0:2] %}
+{{ i.label }}
+
+.. code-block:: {{ i.lang }}
+
+  {{ lookup('file', i.file)|indent(2) }}
+
+{% endfor %}
+
+.. versionadded:: 2.0.0
+
+{% for i in examples[2:4] %}
+{{ i.label }}
+
+.. code-block:: {{ i.lang }}
+
+  {{ lookup('file', i.file)|indent(2) }}
+
+{% endfor %}
+
+The filter also accepts two optional parameters: ``recursive`` and ``list_merge``. These parameters are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9. This is available since community.general 4.4.0.
+
+**recursive**
+    Is a boolean, default to ``False``. Should the ``community.general.lists_mergeby`` recursively merge nested hashes. Note: It does not depend on the value of the ``hash_behaviour`` setting in ``ansible.cfg``.
+
+**list_merge**
+    Is a string, its possible values are ``replace`` (default), ``keep``, ``append``, ``prepend``, ``append_rp`` or ``prepend_rp``. It modifies the behaviour of ``community.general.lists_mergeby`` when the hashes to merge contain arrays/lists.
+
+The examples below set ``recursive=true`` and display the differences among all six options of ``list_merge``. Functionality of the parameters is exactly the same as in the filter ``combine``. See :ref:`Combining hashes/dictionaries <combine_filter>` to learn details about these options.
+
+Let us use the lists below in the following examples
+
+.. code-block:: yaml
+
+  {{ lookup('file', 'default-recursive-true.yml')|indent(2) }}
+
+{% for i in examples[4:16] %}
+{{ i.label }}
+
+.. code-block:: {{ i.lang }}
+
+  {{ lookup('file', i.file)|indent(2) }}
+
+{% endfor %}

docs/docsite/helper/lists_mergeby/list3.out.j2

@@ -0,0 +1,2 @@
+list3:
+{{ list3|to_nice_yaml(indent=0) }}

docs/docsite/helper/lists_mergeby/playbook.yml

@@ -0,0 +1,59 @@
+---
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# 1) Run all examples and create example-XXX.out
+# shell> ansible-playbook playbook.yml -e examples=true
+#
+# 2) Optionally, for testing, create examples_all.rst
+# shell> ansible-playbook playbook.yml -e examples_all=true
+#
+# 3) Create docs REST files
+# shell> ansible-playbook playbook.yml -e merging_lists_of_dictionaries=true
+#
+# Notes:
+# * Use YAML callback, e.g. set ANSIBLE_STDOUT_CALLBACK=community.general.yaml
+# * Use sphinx-view to render and review the REST files
+#   shell> sphinx-view <path_to_helper>/examples_all.rst
+# * Proofread and copy completed docs *.rst files into the directory rst.
+# * Then delete the *.rst and *.out files from this directory. Do not
+#   add *.rst and *.out in this directory to the version control.
+#
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# community.general/docs/docsite/helper/lists_mergeby/playbook.yml
+
+- hosts: localhost
+  gather_facts: false
+  tasks:
+
+    - block:
+        - import_tasks: example-001.yml
+          tags: t001
+        - import_tasks: example-002.yml
+          tags: t002
+        - import_tasks: example-003.yml
+          tags: t003
+        - import_tasks: example-004.yml
+          tags: t004
+        - import_tasks: example-005.yml
+          tags: t005
+        - import_tasks: example-006.yml
+          tags: t006
+        - import_tasks: example-007.yml
+          tags: t007
+        - import_tasks: example-008.yml
+          tags: t008
+      when: examples|d(false)|bool
+
+    - block:
+        - include_vars: examples.yml
+        - template:
+            src: examples_all.rst.j2
+            dest: examples_all.rst
+      when: examples_all|d(false)|bool
+
+    - block:
+        - include_vars: examples.yml
+        - template:
+            src: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2
+            dest: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst
+      when: merging_lists_of_dictionaries|d(false)|bool

docs/docsite/rst/filter_guide.rst

@@ -1,3 +1,4 @@
+
 .. _ansible_collections.community.general.docsite.filter_guide:
 
 community.general Filter Guide
@@ -5,858 +6,14 @@ community.general Filter Guide
 
 The :ref:`community.general collection <plugins_in_community.general>` offers several useful filter plugins.
 
-.. contents:: Topics
-
-Paths
------
-
-The ``path_join`` filter has been added in ansible-base 2.10. If you want to use this filter, but also need to support Ansible 2.9, you can use ``community.general``'s ``path_join`` shim, ``community.general.path_join``. This filter redirects to ``path_join`` for ansible-base 2.10 and ansible-core 2.11 or newer, and re-implements the filter for Ansible 2.9.
-
-.. code-block:: yaml+jinja
-
-    # ansible-base 2.10 or newer:
-    path: {{ ('/etc', path, 'subdir', file) | path_join }}
-
-    # Also works with Ansible 2.9:
-    path: {{ ('/etc', path, 'subdir', file) | community.general.path_join }}
-
-.. versionadded:: 3.0.0
-
-Abstract transformations
-------------------------
-
-Dictionaries
-^^^^^^^^^^^^
-
-You can use the ``dict_kv`` filter to create a single-entry dictionary with ``value | community.general.dict_kv(key)``:
-
-.. code-block:: yaml+jinja
-
-    - name: Create a single-entry dictionary
-      debug:
-        msg: "{{ myvar | community.general.dict_kv('thatsmyvar') }}"
-      vars:
-        myvar: myvalue
-
-    - name: Create a list of dictionaries where the 'server' field is taken from a list
-      debug:
-        msg: >-
-          {{ myservers | map('community.general.dict_kv', 'server')
-                       | map('combine', common_config) }}
-      vars:
-        common_config:
-          type: host
-          database: all
-        myservers:
-        - server1
-        - server2
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Create a single-entry dictionary]  **************************************************
-    ok: [localhost] => {
-        "msg": {
-            "thatsmyvar": "myvalue"
-        }
-    }
-
-    TASK [Create a list of dictionaries where the 'server' field is taken from a list]  *******
-    ok: [localhost] => {
-        "msg": [
-            {
-                "database": "all",
-                "server": "server1",
-                "type": "host"
-            },
-            {
-                "database": "all",
-                "server": "server2",
-                "type": "host"
-            }
-        ]
-    }
-
-.. versionadded:: 2.0.0
-
-If you need to convert a list of key-value pairs to a dictionary, you can use the ``dict`` function. Unfortunately, this function cannot be used with ``map``. For this, the ``community.general.dict`` filter can be used:
-
-.. code-block:: yaml+jinja
-
-    - name: Create a dictionary with the dict function
-      debug:
-        msg: "{{ dict([[1, 2], ['a', 'b']]) }}"
-
-    - name: Create a dictionary with the community.general.dict filter
-      debug:
-        msg: "{{ [[1, 2], ['a', 'b']] | community.general.dict }}"
-
-    - name: Create a list of dictionaries with map and the community.general.dict filter
-      debug:
-        msg: >-
-          {{ values | map('zip', ['k1', 'k2', 'k3'])
-                    | map('map', 'reverse')
-                    | map('community.general.dict') }}
-      vars:
-        values:
-          - - foo
-            - 23
-            - a
-          - - bar
-            - 42
-            - b
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Create a dictionary with the dict function]  ****************************************
-    ok: [localhost] => {
-        "msg": {
-            "1": 2,
-            "a": "b"
-        }
-    }
-
-    TASK [Create a dictionary with the community.general.dict filter]  ************************
-    ok: [localhost] => {
-        "msg": {
-            "1": 2,
-            "a": "b"
-        }
-    }
-
-    TASK [Create a list of dictionaries with map and the community.general.dict filter]  ******
-    ok: [localhost] => {
-        "msg": [
-            {
-                "k1": "foo",
-                "k2": 23,
-                "k3": "a"
-            },
-            {
-                "k1": "bar",
-                "k2": 42,
-                "k3": "b"
-            }
-        ]
-    }
-
-.. versionadded:: 3.0.0
-
-Grouping
-^^^^^^^^
-
-If you have a list of dictionaries, the Jinja2 ``groupby`` filter allows to group the list by an attribute. This results in a list of ``(grouper, list)`` namedtuples, where ``list`` contains all dictionaries where the selected attribute equals ``grouper``. If you know that for every ``grouper``, there will be a most one entry in that list, you can use the ``community.general.groupby_as_dict`` filter to convert the original list into a dictionary which maps ``grouper`` to the corresponding dictionary.
-
-One example is ``ansible_facts.mounts``, which is a list of dictionaries where each has one ``device`` element to indicate the device which is mounted. Therefore, ``ansible_facts.mounts | community.general.groupby_as_dict('device')`` is a dictionary mapping a device to the mount information:
-
-.. code-block:: yaml+jinja
-
-    - name: Output mount facts grouped by device name
-      debug:
-        var: ansible_facts.mounts | community.general.groupby_as_dict('device')
-
-    - name: Output mount facts grouped by mount point
-      debug:
-        var: ansible_facts.mounts | community.general.groupby_as_dict('mount')
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Output mount facts grouped by device name] ******************************************
-    ok: [localhost] => {
-        "ansible_facts.mounts | community.general.groupby_as_dict('device')": {
-            "/dev/sda1": {
-                "block_available": 2000,
-                "block_size": 4096,
-                "block_total": 2345,
-                "block_used": 345,
-                "device": "/dev/sda1",
-                "fstype": "ext4",
-                "inode_available": 500,
-                "inode_total": 512,
-                "inode_used": 12,
-                "mount": "/boot",
-                "options": "rw,relatime,data=ordered",
-                "size_available": 56821,
-                "size_total": 543210,
-                "uuid": "ab31cade-d9c1-484d-8482-8a4cbee5241a"
-            },
-            "/dev/sda2": {
-                "block_available": 1234,
-                "block_size": 4096,
-                "block_total": 12345,
-                "block_used": 11111,
-                "device": "/dev/sda2",
-                "fstype": "ext4",
-                "inode_available": 1111,
-                "inode_total": 1234,
-                "inode_used": 123,
-                "mount": "/",
-                "options": "rw,relatime",
-                "size_available": 42143,
-                "size_total": 543210,
-                "uuid": "abcdef01-2345-6789-0abc-def012345678"
-            }
-        }
-    }
-
-    TASK [Output mount facts grouped by mount point] ******************************************
-    ok: [localhost] => {
-        "ansible_facts.mounts | community.general.groupby_as_dict('mount')": {
-            "/": {
-                "block_available": 1234,
-                "block_size": 4096,
-                "block_total": 12345,
-                "block_used": 11111,
-                "device": "/dev/sda2",
-                "fstype": "ext4",
-                "inode_available": 1111,
-                "inode_total": 1234,
-                "inode_used": 123,
-                "mount": "/",
-                "options": "rw,relatime",
-                "size_available": 42143,
-                "size_total": 543210,
-                "uuid": "bdf50b7d-4859-40af-8665-c637ee7a7808"
-            },
-            "/boot": {
-                "block_available": 2000,
-                "block_size": 4096,
-                "block_total": 2345,
-                "block_used": 345,
-                "device": "/dev/sda1",
-                "fstype": "ext4",
-                "inode_available": 500,
-                "inode_total": 512,
-                "inode_used": 12,
-                "mount": "/boot",
-                "options": "rw,relatime,data=ordered",
-                "size_available": 56821,
-                "size_total": 543210,
-                "uuid": "ab31cade-d9c1-484d-8482-8a4cbee5241a"
-            }
-        }
-    }
-
-.. versionadded: 3.0.0
-
-Merging lists of dictionaries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have two lists of dictionaries and want to combine them into a list of merged dictionaries, where two dictionaries are merged if they coincide in one attribute, you can use the ``lists_mergeby`` filter.
-
-.. code-block:: yaml+jinja
-
-    - name: Merge two lists by common attribute 'name'
-      debug:
-        var: list1 | community.general.lists_mergeby(list2, 'name')
-      vars:
-        list1:
-          - name: foo
-            extra: true
-          - name: bar
-            extra: false
-          - name: meh
-            extra: true
-        list2:
-          - name: foo
-            path: /foo
-          - name: baz
-            path: /bazzz
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Merge two lists by common attribute 'name']  ****************************************
-    ok: [localhost] => {
-        "list1 | community.general.lists_mergeby(list2, 'name')": [
-            {
-                "extra": false,
-                "name": "bar"
-            },
-            {
-                "name": "baz",
-                "path": "/bazzz"
-            },
-            {
-                "extra": true,
-                "name": "foo",
-                "path": "/foo"
-            },
-            {
-                "extra": true,
-                "name": "meh"
-            }
-        ]
-    }
-
-.. versionadded: 2.0.0
-
-Counting elements in a sequence
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The ``community.general.counter`` filter plugin allows you to count (hashable) elements in a sequence. Elements are returned as dictionary keys and their counts are stored as dictionary values.
-
-.. code-block:: yaml+jinja
-
-    - name: Count character occurrences in a string
-      debug:
-        msg: "{{ 'abccbaabca' | community.general.counter }}"
-
-    - name: Count items in a list
-      debug:
-        msg: "{{ ['car', 'car', 'bike', 'plane', 'bike'] | community.general.counter }}"
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Count character occurrences in a string] ********************************************
-    ok: [localhost] => {
-        "msg": {
-            "a": 4,
-            "b": 3,
-            "c": 3
-        }
-    }
-
-    TASK [Count items in a list] **************************************************************
-    ok: [localhost] => {
-        "msg": {
-            "bike": 2,
-            "car": 2,
-            "plane": 1
-        }
-    }
-
-This plugin is useful for selecting resources based on current allocation:
-
-.. code-block:: yaml+jinja
-
-    - name: Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks
-      debug:
-        msg: >-
-          {{
-             ( disks | dict2items | map(attribute='value.adapter') | list
-               | community.general.counter | dict2items
-               | rejectattr('value', '>=', 4) | sort(attribute='value') | first
-             ).key
-          }}
-      vars:
-        disks:
-          sda:
-            adapter: scsi_1
-          sdb:
-            adapter: scsi_1
-          sdc:
-            adapter: scsi_1
-          sdd:
-            adapter: scsi_1
-          sde:
-            adapter: scsi_2
-          sdf:
-            adapter: scsi_3
-          sdg:
-            adapter: scsi_3
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks]
-    ok: [localhost] => {
-        "msg": "scsi_2"
-    }
-
-.. versionadded:: 4.3.0
-
-Working with times
-------------------
-
-The ``to_time_unit`` filter allows to convert times from a human-readable string to a unit. For example, ``'4h 30min 12second' | community.general.to_time_unit('hour')`` gives the number of hours that correspond to 4 hours, 30 minutes and 12 seconds.
-
-There are shorthands to directly convert to various units, like ``to_hours``, ``to_minutes``, ``to_seconds``, and so on. The following table lists all units that can be used:
-
-.. list-table:: Units
-   :widths: 25 25 25 25
-   :header-rows: 1
-
-   * - Unit name
-     - Unit value in seconds
-     - Unit strings for filter
-     - Shorthand filter
-   * - Millisecond
-     - 1/1000 second
-     - ``ms``, ``millisecond``, ``milliseconds``, ``msec``, ``msecs``, ``msecond``, ``mseconds``
-     - ``to_milliseconds``
-   * - Second
-     - 1 second
-     - ``s``, ``sec``, ``secs``, ``second``, ``seconds``
-     - ``to_seconds``
-   * - Minute
-     - 60 seconds
-     - ``m``, ``min``, ``mins``, ``minute``, ``minutes``
-     - ``to_minutes``
-   * - Hour
-     - 60*60 seconds
-     - ``h``, ``hour``, ``hours``
-     - ``to_hours``
-   * - Day
-     - 24*60*60 seconds
-     - ``d``, ``day``, ``days``
-     - ``to_days``
-   * - Week
-     - 7*24*60*60 seconds
-     - ``w``, ``week``, ``weeks``
-     - ``to_weeks``
-   * - Month
-     - 30*24*60*60 seconds
-     - ``mo``, ``month``, ``months``
-     - ``to_months``
-   * - Year
-     - 365*24*60*60 seconds
-     - ``y``, ``year``, ``years``
-     - ``to_years``
-
-Note that months and years are using a simplified representation: a month is 30 days, and a year is 365 days. If you need different definitions of months or years, you can pass them as keyword arguments. For example, if you want a year to be 365.25 days, and a month to be 30.5 days, you can write ``'11months 4' | community.general.to_years(year=365.25, month=30.5)``. These keyword arguments can be specified to ``to_time_unit`` and to all shorthand filters.
-
-.. code-block:: yaml+jinja
-
-    - name: Convert string to seconds
-      debug:
-        msg: "{{ '30h 20m 10s 123ms' | community.general.to_time_unit('seconds') }}"
-
-    - name: Convert string to hours
-      debug:
-        msg: "{{ '30h 20m 10s 123ms' | community.general.to_hours }}"
-
-    - name: Convert string to years (using 365.25 days == 1 year)
-      debug:
-        msg: "{{ '400d 15h' | community.general.to_years(year=365.25) }}"
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Convert string to seconds] **********************************************************
-    ok: [localhost] => {
-        "msg": "109210.123"
-    }
-
-    TASK [Convert string to hours] ************************************************************
-    ok: [localhost] => {
-        "msg": "30.336145277778"
-    }
-
-    TASK [Convert string to years (using 365.25 days == 1 year)] ******************************
-    ok: [localhost] => {
-        "msg": "1.096851471595"
-    }
-
-.. versionadded: 0.2.0
-
-Working with versions
----------------------
-
-If you need to sort a list of version numbers, the Jinja ``sort`` filter is problematic. Since it sorts lexicographically, ``2.10`` will come before ``2.9``. To treat version numbers correctly, you can use the ``version_sort`` filter:
-
-.. code-block:: yaml+jinja
-
-    - name: Sort list by version number
-      debug:
-        var: ansible_versions | community.general.version_sort
-      vars:
-        ansible_versions:
-          - '2.8.0'
-          - '2.11.0'
-          - '2.7.0'
-          - '2.10.0'
-          - '2.9.0'
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Sort list by version number] ********************************************************
-    ok: [localhost] => {
-        "ansible_versions | community.general.version_sort": [
-            "2.7.0",
-            "2.8.0",
-            "2.9.0",
-            "2.10.0",
-            "2.11.0"
-        ]
-    }
-
-.. versionadded: 2.2.0
-
-Creating identifiers
---------------------
-
-The following filters allow to create identifiers.
-
-Hashids
-^^^^^^^
-
-`Hashids <https://hashids.org/>`_ allow to convert sequences of integers to short unique string identifiers. This filter needs the `hashids Python library <https://pypi.org/project/hashids/>`_ installed on the controller.
-
-.. code-block:: yaml+jinja
-
-    - name: "Create hashid"
-      debug:
-        msg: "{{ [1234, 5, 6] | community.general.hashids_encode }}"
-
-    - name: "Decode hashid"
-      debug:
-        msg: "{{ 'jm2Cytn' | community.general.hashids_decode }}"
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Create hashid] **********************************************************************
-    ok: [localhost] => {
-        "msg": "jm2Cytn"
-    }
-
-    TASK [Decode hashid] **********************************************************************
-    ok: [localhost] => {
-        "msg": [
-            1234,
-            5,
-            6
-        ]
-    }
-
-The hashids filters accept keyword arguments to allow fine-tuning the hashids generated:
-
-:salt: String to use as salt when hashing.
-:alphabet: String of 16 or more unique characters to produce a hash.
-:min_length: Minimum length of hash produced.
-
-.. versionadded: 3.0.0
-
-Random MACs
-^^^^^^^^^^^
-
-You can use the ``random_mac`` filter to complete a partial `MAC address <https://en.wikipedia.org/wiki/MAC_address>`_ to a random 6-byte MAC address.
-
-.. code-block:: yaml+jinja
-
-    - name: "Create a random MAC starting with ff:"
-      debug:
-        msg: "{{ 'FF' | community.general.random_mac }}"
-
-    - name: "Create a random MAC starting with 00:11:22:"
-      debug:
-        msg: "{{ '00:11:22' | community.general.random_mac }}"
-  
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Create a random MAC starting with ff:] **********************************************
-    ok: [localhost] => {
-        "msg": "ff:69:d3:78:7f:b4"
-    }
-
-    TASK [Create a random MAC starting with 00:11:22:] ****************************************
-    ok: [localhost] => {
-        "msg": "00:11:22:71:5d:3b"
-    }
-
-You can also initialize the random number generator from a seed to create random-but-idempotent MAC addresses:
-
-.. code-block:: yaml+jinja
-
-    "{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}"
-
-Conversions
------------
-
-Parsing CSV files
-^^^^^^^^^^^^^^^^^
-
-Ansible offers the :ref:`community.general.read_csv module <ansible_collections.community.general.read_csv_module>` to read CSV files. Sometimes you need to convert strings to CSV files instead. For this, the ``from_csv`` filter exists.
-
-.. code-block:: yaml+jinja
-
-    - name: "Parse CSV from string"
-      debug:
-        msg: "{{ csv_string | community.general.from_csv }}"
-      vars:
-        csv_string: |
-          foo,bar,baz
-          1,2,3
-          you,this,then
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Parse CSV from string] **************************************************************
-    ok: [localhost] => {
-        "msg": [
-            {
-                "bar": "2",
-                "baz": "3",
-                "foo": "1"
-            },
-            {
-                "bar": "this",
-                "baz": "then",
-                "foo": "you"
-            }
-        ]
-    }
-
-The ``from_csv`` filter has several keyword arguments to control its behavior:
-
-:dialect: Dialect of the CSV file. Default is ``excel``. Other possible choices are ``excel-tab`` and ``unix``. If one of ``delimiter``, ``skipinitialspace`` or ``strict`` is specified, ``dialect`` is ignored.
-:fieldnames: A set of column names to use. If not provided, the first line of the CSV is assumed to contain the column names.
-:delimiter: Sets the delimiter to use. Default depends on the dialect used.
-:skipinitialspace: Set to ``true`` to ignore space directly after the delimiter. Default depends on the dialect used (usually ``false``).
-:strict: Set to ``true`` to error out on invalid CSV input.
-
-.. versionadded: 3.0.0
-
-Converting to JSON
-^^^^^^^^^^^^^^^^^^
-
-`JC <https://pypi.org/project/jc/>`_ is a CLI tool and Python library which allows to interpret output of various CLI programs as JSON. It is also available as a filter in community.general. This filter needs the `jc Python library <https://pypi.org/project/jc/>`_ installed on the controller.
-
-.. code-block:: yaml+jinja
-
-    - name: Run 'ls' to list files in /
-      command: ls /
-      register: result
-
-    - name: Parse the ls output
-      debug:
-        msg: "{{ result.stdout | community.general.jc('ls') }}"
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Run 'ls' to list files in /] ********************************************************
-    changed: [localhost]
-
-    TASK [Parse the ls output] ****************************************************************
-    ok: [localhost] => {
-        "msg": [
-            {
-                "filename": "bin"
-            },
-            {
-                "filename": "boot"
-            },
-            {
-                "filename": "dev"
-            },
-            {
-                "filename": "etc"
-            },
-            {
-                "filename": "home"
-            },
-            {
-                "filename": "lib"
-            },
-            {
-                "filename": "proc"
-            },
-            {
-                "filename": "root"
-            },
-            {
-                "filename": "run"
-            },
-            {
-                "filename": "tmp"
-            }
-        ]
-    }
-
-.. versionadded: 2.0.0
-
-.. _ansible_collections.community.general.docsite.json_query_filter:
-
-Selecting JSON data: JSON queries
----------------------------------
-
-To select a single element or a data subset from a complex data structure in JSON format (for example, Ansible facts), use the ``json_query`` filter.  The ``json_query`` filter lets you query a complex JSON structure and iterate over it using a loop structure.
-
-.. note:: You must manually install the **jmespath** dependency on the Ansible controller before using this filter. This filter is built upon **jmespath**, and you can use the same syntax. For examples, see `jmespath examples <http://jmespath.org/examples.html>`_.
-
-Consider this data structure:
-
-.. code-block:: yaml+jinja
-
-    {
-        "domain_definition": {
-            "domain": {
-                "cluster": [
-                    {
-                        "name": "cluster1"
-                    },
-                    {
-                        "name": "cluster2"
-                    }
-                ],
-                "server": [
-                    {
-                        "name": "server11",
-                        "cluster": "cluster1",
-                        "port": "8080"
-                    },
-                    {
-                        "name": "server12",
-                        "cluster": "cluster1",
-                        "port": "8090"
-                    },
-                    {
-                        "name": "server21",
-                        "cluster": "cluster2",
-                        "port": "9080"
-                    },
-                    {
-                        "name": "server22",
-                        "cluster": "cluster2",
-                        "port": "9090"
-                    }
-                ],
-                "library": [
-                    {
-                        "name": "lib1",
-                        "target": "cluster1"
-                    },
-                    {
-                        "name": "lib2",
-                        "target": "cluster2"
-                    }
-                ]
-            }
-        }
-    }
-
-To extract all clusters from this structure, you can use the following query:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all cluster names
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query('domain.cluster[*].name') }}"
-
-To extract all server names:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all server names
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query('domain.server[*].name') }}"
-
-To extract ports from cluster1:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
-      vars:
-        server_name_cluster1_query: "domain.server[?cluster=='cluster1'].port"
-
-.. note:: You can use a variable to make the query more readable.
-
-To print out the ports from cluster1 in a comma separated string:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1 as a string
-      ansible.builtin.debug:
-        msg: "{{ domain_definition | community.general.json_query('domain.server[?cluster==`cluster1`].port') | join(', ') }}"
-
-.. note:: In the example above, quoting literals using backticks avoids escaping quotes and maintains readability.
-
-You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query('domain.server[?cluster==''cluster1''].port') }}"
-
-.. note:: Escaping single quotes within single quotes in YAML is done by doubling the single quote.
-
-To get a hash map with all ports and names of a cluster:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all server ports and names from cluster1
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
-      vars:
-        server_name_cluster1_query: "domain.server[?cluster=='cluster2'].{name: name, port: port}"
-
-To extract ports from all clusters with name starting with 'server1':
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1
-      ansible.builtin.debug:
-        msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
-      vars:
-        server_name_query: "domain.server[?starts_with(name,'server1')].port"
-
-To extract ports from all clusters with name containing 'server1':
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1
-      ansible.builtin.debug:
-        msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
-      vars:
-        server_name_query: "domain.server[?contains(name,'server1')].port"
-
-.. note:: while using ``starts_with`` and ``contains``, you have to use `` to_json | from_json `` filter for correct parsing of data structure.
-
-Working with Unicode
----------------------
-
-`Unicode <https://unicode.org/main.html>`_ makes it possible to produce two strings which may be visually equivalent, but are comprised of distinctly different characters/character sequences. To address this ``Unicode`` defines `normalization forms <https://unicode.org/reports/tr15/>`_ which avoid these distinctions by choosing a unique character sequence for a given visual representation.
-
-You can use the ``community.general.unicode_normalize`` filter to normalize ``Unicode`` strings within your playbooks.
-
-.. code-block:: yaml+jinja
-
-    - name: Compare Unicode representations
-      debug:
-        msg: "{{ with_combining_character | community.general.unicode_normalize == without_combining_character }}"
-      vars:
-        with_combining_character: "{{ 'Mayagu\u0308ez' }}"
-        without_combining_character: Mayagüez
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Compare Unicode representations] ********************************************************
-    ok: [localhost] => {
-        "msg": true
-    }
-
-The ``community.general.unicode_normalize`` filter accepts a keyword argument to select the ``Unicode`` form used to normalize the input string.
-
-:form: One of ``'NFC'`` (default), ``'NFD'``, ``'NFKC'``, or ``'NFKD'``. See the `Unicode reference <https://unicode.org/reports/tr15/>`_ for more information.
-
-.. versionadded:: 3.7.0
+.. toctree::
+   :maxdepth: 2
+
+   filter_guide_paths
+   filter_guide_abstract_informations
+   filter_guide_working_with_times
+   filter_guide_working_with_versions
+   filter_guide_creating_identifiers
+   filter_guide_conversions
+   filter_guide_selecting_json_data
+   filter_guide_working_with_unicode

docs/docsite/rst/filter_guide_abstract_informations.rst

@@ -0,0 +1,10 @@
+Abstract transformations
+------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   filter_guide_abstract_informations_dictionaries
+   filter_guide_abstract_informations_grouping
+   filter_guide_abstract_informations_merging_lists_of_dictionaries
+   filter_guide_abstract_informations_counting_elements_in_sequence

docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst

@@ -0,0 +1,77 @@
+Counting elements in a sequence
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``community.general.counter`` filter plugin allows you to count (hashable) elements in a sequence. Elements are returned as dictionary keys and their counts are stored as dictionary values.
+
+.. code-block:: yaml+jinja
+
+    - name: Count character occurrences in a string
+      debug:
+        msg: "{{ 'abccbaabca' | community.general.counter }}"
+
+    - name: Count items in a list
+      debug:
+        msg: "{{ ['car', 'car', 'bike', 'plane', 'bike'] | community.general.counter }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Count character occurrences in a string] ********************************************
+    ok: [localhost] => {
+        "msg": {
+            "a": 4,
+            "b": 3,
+            "c": 3
+        }
+    }
+
+    TASK [Count items in a list] **************************************************************
+    ok: [localhost] => {
+        "msg": {
+            "bike": 2,
+            "car": 2,
+            "plane": 1
+        }
+    }
+
+This plugin is useful for selecting resources based on current allocation:
+
+.. code-block:: yaml+jinja
+
+    - name: Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks
+      debug:
+        msg: >-
+          {{
+             ( disks | dict2items | map(attribute='value.adapter') | list
+               | community.general.counter | dict2items
+               | rejectattr('value', '>=', 4) | sort(attribute='value') | first
+             ).key
+          }}
+      vars:
+        disks:
+          sda:
+            adapter: scsi_1
+          sdb:
+            adapter: scsi_1
+          sdc:
+            adapter: scsi_1
+          sdd:
+            adapter: scsi_1
+          sde:
+            adapter: scsi_2
+          sdf:
+            adapter: scsi_3
+          sdg:
+            adapter: scsi_3
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks]
+    ok: [localhost] => {
+        "msg": "scsi_2"
+    }
+
+.. versionadded:: 4.3.0

docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst

@@ -0,0 +1,119 @@
+Dictionaries
+^^^^^^^^^^^^
+
+You can use the ``dict_kv`` filter to create a single-entry dictionary with ``value | community.general.dict_kv(key)``:
+
+.. code-block:: yaml+jinja
+
+    - name: Create a single-entry dictionary
+      debug:
+        msg: "{{ myvar | community.general.dict_kv('thatsmyvar') }}"
+      vars:
+        myvar: myvalue
+
+    - name: Create a list of dictionaries where the 'server' field is taken from a list
+      debug:
+        msg: >-
+          {{ myservers | map('community.general.dict_kv', 'server')
+                       | map('combine', common_config) }}
+      vars:
+        common_config:
+          type: host
+          database: all
+        myservers:
+        - server1
+        - server2
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Create a single-entry dictionary]  **************************************************
+    ok: [localhost] => {
+        "msg": {
+            "thatsmyvar": "myvalue"
+        }
+    }
+
+    TASK [Create a list of dictionaries where the 'server' field is taken from a list]  *******
+    ok: [localhost] => {
+        "msg": [
+            {
+                "database": "all",
+                "server": "server1",
+                "type": "host"
+            },
+            {
+                "database": "all",
+                "server": "server2",
+                "type": "host"
+            }
+        ]
+    }
+
+.. versionadded:: 2.0.0
+
+If you need to convert a list of key-value pairs to a dictionary, you can use the ``dict`` function. Unfortunately, this function cannot be used with ``map``. For this, the ``community.general.dict`` filter can be used:
+
+.. code-block:: yaml+jinja
+
+    - name: Create a dictionary with the dict function
+      debug:
+        msg: "{{ dict([[1, 2], ['a', 'b']]) }}"
+
+    - name: Create a dictionary with the community.general.dict filter
+      debug:
+        msg: "{{ [[1, 2], ['a', 'b']] | community.general.dict }}"
+
+    - name: Create a list of dictionaries with map and the community.general.dict filter
+      debug:
+        msg: >-
+          {{ values | map('zip', ['k1', 'k2', 'k3'])
+                    | map('map', 'reverse')
+                    | map('community.general.dict') }}
+      vars:
+        values:
+          - - foo
+            - 23
+            - a
+          - - bar
+            - 42
+            - b
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Create a dictionary with the dict function]  ****************************************
+    ok: [localhost] => {
+        "msg": {
+            "1": 2,
+            "a": "b"
+        }
+    }
+
+    TASK [Create a dictionary with the community.general.dict filter]  ************************
+    ok: [localhost] => {
+        "msg": {
+            "1": 2,
+            "a": "b"
+        }
+    }
+
+    TASK [Create a list of dictionaries with map and the community.general.dict filter]  ******
+    ok: [localhost] => {
+        "msg": [
+            {
+                "k1": "foo",
+                "k2": 23,
+                "k3": "a"
+            },
+            {
+                "k1": "bar",
+                "k2": 42,
+                "k3": "b"
+            }
+        ]
+    }
+
+.. versionadded:: 3.0.0

docs/docsite/rst/filter_guide_abstract_informations_grouping.rst

@@ -0,0 +1,98 @@
+Grouping
+^^^^^^^^
+
+If you have a list of dictionaries, the Jinja2 ``groupby`` filter allows to group the list by an attribute. This results in a list of ``(grouper, list)`` namedtuples, where ``list`` contains all dictionaries where the selected attribute equals ``grouper``. If you know that for every ``grouper``, there will be a most one entry in that list, you can use the ``community.general.groupby_as_dict`` filter to convert the original list into a dictionary which maps ``grouper`` to the corresponding dictionary.
+
+One example is ``ansible_facts.mounts``, which is a list of dictionaries where each has one ``device`` element to indicate the device which is mounted. Therefore, ``ansible_facts.mounts | community.general.groupby_as_dict('device')`` is a dictionary mapping a device to the mount information:
+
+.. code-block:: yaml+jinja
+
+    - name: Output mount facts grouped by device name
+      debug:
+        var: ansible_facts.mounts | community.general.groupby_as_dict('device')
+
+    - name: Output mount facts grouped by mount point
+      debug:
+        var: ansible_facts.mounts | community.general.groupby_as_dict('mount')
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Output mount facts grouped by device name] ******************************************
+    ok: [localhost] => {
+        "ansible_facts.mounts | community.general.groupby_as_dict('device')": {
+            "/dev/sda1": {
+                "block_available": 2000,
+                "block_size": 4096,
+                "block_total": 2345,
+                "block_used": 345,
+                "device": "/dev/sda1",
+                "fstype": "ext4",
+                "inode_available": 500,
+                "inode_total": 512,
+                "inode_used": 12,
+                "mount": "/boot",
+                "options": "rw,relatime,data=ordered",
+                "size_available": 56821,
+                "size_total": 543210,
+                "uuid": "ab31cade-d9c1-484d-8482-8a4cbee5241a"
+            },
+            "/dev/sda2": {
+                "block_available": 1234,
+                "block_size": 4096,
+                "block_total": 12345,
+                "block_used": 11111,
+                "device": "/dev/sda2",
+                "fstype": "ext4",
+                "inode_available": 1111,
+                "inode_total": 1234,
+                "inode_used": 123,
+                "mount": "/",
+                "options": "rw,relatime",
+                "size_available": 42143,
+                "size_total": 543210,
+                "uuid": "abcdef01-2345-6789-0abc-def012345678"
+            }
+        }
+    }
+
+    TASK [Output mount facts grouped by mount point] ******************************************
+    ok: [localhost] => {
+        "ansible_facts.mounts | community.general.groupby_as_dict('mount')": {
+            "/": {
+                "block_available": 1234,
+                "block_size": 4096,
+                "block_total": 12345,
+                "block_used": 11111,
+                "device": "/dev/sda2",
+                "fstype": "ext4",
+                "inode_available": 1111,
+                "inode_total": 1234,
+                "inode_used": 123,
+                "mount": "/",
+                "options": "rw,relatime",
+                "size_available": 42143,
+                "size_total": 543210,
+                "uuid": "bdf50b7d-4859-40af-8665-c637ee7a7808"
+            },
+            "/boot": {
+                "block_available": 2000,
+                "block_size": 4096,
+                "block_total": 2345,
+                "block_used": 345,
+                "device": "/dev/sda1",
+                "fstype": "ext4",
+                "inode_available": 500,
+                "inode_total": 512,
+                "inode_used": 12,
+                "mount": "/boot",
+                "options": "rw,relatime,data=ordered",
+                "size_available": 56821,
+                "size_total": 543210,
+                "uuid": "ab31cade-d9c1-484d-8482-8a4cbee5241a"
+            }
+        }
+    }
+
+.. versionadded: 3.0.0

docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst

@@ -0,0 +1,292 @@
+Merging lists of dictionaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have two or more lists of dictionaries and want to combine them into a list of merged dictionaries, where the dictionaries are merged by an attribute, you can use the ``lists_mergeby`` filter.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ref:`the documentation for the community.general.yaml callback plugin <ansible_collections.community.general.yaml_callback>`.
+
+Let us use the lists below in the following examples:
+
+.. code-block:: yaml
+
+  list1:
+    - name: foo
+      extra: true
+    - name: bar
+      extra: false
+    - name: meh
+      extra: true
+
+  list2:
+    - name: foo
+      path: /foo
+    - name: baz
+      path: /baz
+
+In the example below the lists are merged by the attribute ``name``:
+
+.. code-block:: yaml+jinja
+
+  list3: "{{ list1|
+             community.general.lists_mergeby(list2, 'name') }}"
+
+This produces:
+
+.. code-block:: yaml
+
+  list3:
+  - extra: false
+    name: bar
+  - name: baz
+    path: /baz
+  - extra: true
+    name: foo
+    path: /foo
+  - extra: true
+    name: meh
+
+
+.. versionadded:: 2.0.0
+
+It is possible to use a list of lists as an input of the filter:
+
+.. code-block:: yaml+jinja
+
+  list3: "{{ [list1, list2]|
+             community.general.lists_mergeby('name') }}"
+
+This produces the same result as in the previous example:
+
+.. code-block:: yaml
+
+  list3:
+  - extra: false
+    name: bar
+  - name: baz
+    path: /baz
+  - extra: true
+    name: foo
+    path: /foo
+  - extra: true
+    name: meh
+
+
+The filter also accepts two optional parameters: ``recursive`` and ``list_merge``. These parameters are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9. This is available since community.general 4.4.0.
+
+**recursive**
+    Is a boolean, default to ``False``. Should the ``community.general.lists_mergeby`` recursively merge nested hashes. Note: It does not depend on the value of the ``hash_behaviour`` setting in ``ansible.cfg``.
+
+**list_merge**
+    Is a string, its possible values are ``replace`` (default), ``keep``, ``append``, ``prepend``, ``append_rp`` or ``prepend_rp``. It modifies the behaviour of ``community.general.lists_mergeby`` when the hashes to merge contain arrays/lists.
+
+The examples below set ``recursive=true`` and display the differences among all six options of ``list_merge``. Functionality of the parameters is exactly the same as in the filter ``combine``. See :ref:`Combining hashes/dictionaries <combine_filter>` to learn details about these options.
+
+Let us use the lists below in the following examples
+
+.. code-block:: yaml
+
+  list1:
+    - name: myname01
+      param01:
+        x: default_value
+        y: default_value
+        list:
+          - default_value
+    - name: myname02
+      param01: [1, 1, 2, 3]
+
+  list2:
+    - name: myname01
+      param01:
+        y: patch_value
+        z: patch_value
+        list:
+          - patch_value
+    - name: myname02
+      param01: [3, 4, 4, {key: value}]
+
+Example ``list_merge=replace`` (default):
+
+.. code-block:: yaml+jinja
+
+  list3: "{{ [list1, list2]|
+             community.general.lists_mergeby('name',
+                                             recursive=true) }}"
+
+This produces:
+
+.. code-block:: yaml
+
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - patch_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 3
+    - 4
+    - 4
+    - key: value
+
+Example ``list_merge=keep``:
+
+.. code-block:: yaml+jinja
+
+  list3: "{{ [list1, list2]|
+             community.general.lists_mergeby('name',
+                                             recursive=true,
+                                             list_merge='keep') }}"
+
+This produces:
+
+.. code-block:: yaml
+
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - default_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 1
+    - 1
+    - 2
+    - 3
+
+Example ``list_merge=append``:
+
+.. code-block:: yaml+jinja
+
+  list3: "{{ [list1, list2]|
+             community.general.lists_mergeby('name',
+                                             recursive=true,
+                                             list_merge='append') }}"
+
+This produces:
+
+.. code-block:: yaml
+
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - default_value
+      - patch_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 1
+    - 1
+    - 2
+    - 3
+    - 3
+    - 4
+    - 4
+    - key: value
+
+Example ``list_merge=prepend``:
+
+.. code-block:: yaml+jinja
+
+  list3: "{{ [list1, list2]|
+             community.general.lists_mergeby('name',
+                                             recursive=true,
+                                             list_merge='prepend') }}"
+
+This produces:
+
+.. code-block:: yaml
+
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - patch_value
+      - default_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 3
+    - 4
+    - 4
+    - key: value
+    - 1
+    - 1
+    - 2
+    - 3
+
+Example ``list_merge=append_rp``:
+
+.. code-block:: yaml+jinja
+
+  list3: "{{ [list1, list2]|
+             community.general.lists_mergeby('name',
+                                             recursive=true,
+                                             list_merge='append_rp') }}"
+
+This produces:
+
+.. code-block:: yaml
+
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - default_value
+      - patch_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 1
+    - 1
+    - 2
+    - 3
+    - 4
+    - 4
+    - key: value
+
+Example ``list_merge=prepend_rp``:
+
+.. code-block:: yaml+jinja
+
+  list3: "{{ [list1, list2]|
+             community.general.lists_mergeby('name',
+                                             recursive=true,
+                                             list_merge='prepend_rp') }}"
+
+This produces:
+
+.. code-block:: yaml
+
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - patch_value
+      - default_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 3
+    - 4
+    - 4
+    - key: value
+    - 1
+    - 1
+    - 2
+

docs/docsite/rst/filter_guide_conversions.rst

@@ -0,0 +1,108 @@
+Conversions
+-----------
+
+Parsing CSV files
+^^^^^^^^^^^^^^^^^
+
+Ansible offers the :ref:`community.general.read_csv module <ansible_collections.community.general.read_csv_module>` to read CSV files. Sometimes you need to convert strings to CSV files instead. For this, the ``from_csv`` filter exists.
+
+.. code-block:: yaml+jinja
+
+    - name: "Parse CSV from string"
+      debug:
+        msg: "{{ csv_string | community.general.from_csv }}"
+      vars:
+        csv_string: |
+          foo,bar,baz
+          1,2,3
+          you,this,then
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Parse CSV from string] **************************************************************
+    ok: [localhost] => {
+        "msg": [
+            {
+                "bar": "2",
+                "baz": "3",
+                "foo": "1"
+            },
+            {
+                "bar": "this",
+                "baz": "then",
+                "foo": "you"
+            }
+        ]
+    }
+
+The ``from_csv`` filter has several keyword arguments to control its behavior:
+
+:dialect: Dialect of the CSV file. Default is ``excel``. Other possible choices are ``excel-tab`` and ``unix``. If one of ``delimiter``, ``skipinitialspace`` or ``strict`` is specified, ``dialect`` is ignored.
+:fieldnames: A set of column names to use. If not provided, the first line of the CSV is assumed to contain the column names.
+:delimiter: Sets the delimiter to use. Default depends on the dialect used.
+:skipinitialspace: Set to ``true`` to ignore space directly after the delimiter. Default depends on the dialect used (usually ``false``).
+:strict: Set to ``true`` to error out on invalid CSV input.
+
+.. versionadded: 3.0.0
+
+Converting to JSON
+^^^^^^^^^^^^^^^^^^
+
+`JC <https://pypi.org/project/jc/>`_ is a CLI tool and Python library which allows to interpret output of various CLI programs as JSON. It is also available as a filter in community.general. This filter needs the `jc Python library <https://pypi.org/project/jc/>`_ installed on the controller.
+
+.. code-block:: yaml+jinja
+
+    - name: Run 'ls' to list files in /
+      command: ls /
+      register: result
+
+    - name: Parse the ls output
+      debug:
+        msg: "{{ result.stdout | community.general.jc('ls') }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Run 'ls' to list files in /] ********************************************************
+    changed: [localhost]
+
+    TASK [Parse the ls output] ****************************************************************
+    ok: [localhost] => {
+        "msg": [
+            {
+                "filename": "bin"
+            },
+            {
+                "filename": "boot"
+            },
+            {
+                "filename": "dev"
+            },
+            {
+                "filename": "etc"
+            },
+            {
+                "filename": "home"
+            },
+            {
+                "filename": "lib"
+            },
+            {
+                "filename": "proc"
+            },
+            {
+                "filename": "root"
+            },
+            {
+                "filename": "run"
+            },
+            {
+                "filename": "tmp"
+            }
+        ]
+    }
+
+.. versionadded: 2.0.0

docs/docsite/rst/filter_guide_creating_identifiers.rst

@@ -0,0 +1,80 @@
+Creating identifiers
+--------------------
+
+The following filters allow to create identifiers.
+
+Hashids
+^^^^^^^
+
+`Hashids <https://hashids.org/>`_ allow to convert sequences of integers to short unique string identifiers. This filter needs the `hashids Python library <https://pypi.org/project/hashids/>`_ installed on the controller.
+
+.. code-block:: yaml+jinja
+
+    - name: "Create hashid"
+      debug:
+        msg: "{{ [1234, 5, 6] | community.general.hashids_encode }}"
+
+    - name: "Decode hashid"
+      debug:
+        msg: "{{ 'jm2Cytn' | community.general.hashids_decode }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Create hashid] **********************************************************************
+    ok: [localhost] => {
+        "msg": "jm2Cytn"
+    }
+
+    TASK [Decode hashid] **********************************************************************
+    ok: [localhost] => {
+        "msg": [
+            1234,
+            5,
+            6
+        ]
+    }
+
+The hashids filters accept keyword arguments to allow fine-tuning the hashids generated:
+
+:salt: String to use as salt when hashing.
+:alphabet: String of 16 or more unique characters to produce a hash.
+:min_length: Minimum length of hash produced.
+
+.. versionadded: 3.0.0
+
+Random MACs
+^^^^^^^^^^^
+
+You can use the ``random_mac`` filter to complete a partial `MAC address <https://en.wikipedia.org/wiki/MAC_address>`_ to a random 6-byte MAC address.
+
+.. code-block:: yaml+jinja
+
+    - name: "Create a random MAC starting with ff:"
+      debug:
+        msg: "{{ 'FF' | community.general.random_mac }}"
+
+    - name: "Create a random MAC starting with 00:11:22:"
+      debug:
+        msg: "{{ '00:11:22' | community.general.random_mac }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Create a random MAC starting with ff:] **********************************************
+    ok: [localhost] => {
+        "msg": "ff:69:d3:78:7f:b4"
+    }
+
+    TASK [Create a random MAC starting with 00:11:22:] ****************************************
+    ok: [localhost] => {
+        "msg": "00:11:22:71:5d:3b"
+    }
+
+You can also initialize the random number generator from a seed to create random-but-idempotent MAC addresses:
+
+.. code-block:: yaml+jinja
+
+    "{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}"

docs/docsite/rst/filter_guide_paths.rst

@@ -0,0 +1,14 @@
+Paths
+-----
+
+The ``path_join`` filter has been added in ansible-base 2.10. If you want to use this filter, but also need to support Ansible 2.9, you can use ``community.general``'s ``path_join`` shim, ``community.general.path_join``. This filter redirects to ``path_join`` for ansible-base 2.10 and ansible-core 2.11 or newer, and re-implements the filter for Ansible 2.9.
+
+.. code-block:: yaml+jinja
+
+    # ansible-base 2.10 or newer:
+    path: {{ ('/etc', path, 'subdir', file) | path_join }}
+
+    # Also works with Ansible 2.9:
+    path: {{ ('/etc', path, 'subdir', file) | community.general.path_join }}
+
+.. versionadded:: 3.0.0

docs/docsite/rst/filter_guide_selecting_json_data.rst

@@ -0,0 +1,144 @@
+.. _ansible_collections.community.general.docsite.json_query_filter:
+
+Selecting JSON data: JSON queries
+---------------------------------
+
+To select a single element or a data subset from a complex data structure in JSON format (for example, Ansible facts), use the ``json_query`` filter.  The ``json_query`` filter lets you query a complex JSON structure and iterate over it using a loop structure.
+
+.. note:: You must manually install the **jmespath** dependency on the Ansible controller before using this filter. This filter is built upon **jmespath**, and you can use the same syntax. For examples, see `jmespath examples <http://jmespath.org/examples.html>`_.
+
+Consider this data structure:
+
+.. code-block:: yaml+jinja
+
+    {
+        "domain_definition": {
+            "domain": {
+                "cluster": [
+                    {
+                        "name": "cluster1"
+                    },
+                    {
+                        "name": "cluster2"
+                    }
+                ],
+                "server": [
+                    {
+                        "name": "server11",
+                        "cluster": "cluster1",
+                        "port": "8080"
+                    },
+                    {
+                        "name": "server12",
+                        "cluster": "cluster1",
+                        "port": "8090"
+                    },
+                    {
+                        "name": "server21",
+                        "cluster": "cluster2",
+                        "port": "9080"
+                    },
+                    {
+                        "name": "server22",
+                        "cluster": "cluster2",
+                        "port": "9090"
+                    }
+                ],
+                "library": [
+                    {
+                        "name": "lib1",
+                        "target": "cluster1"
+                    },
+                    {
+                        "name": "lib2",
+                        "target": "cluster2"
+                    }
+                ]
+            }
+        }
+    }
+
+To extract all clusters from this structure, you can use the following query:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all cluster names
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query('domain.cluster[*].name') }}"
+
+To extract all server names:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all server names
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query('domain.server[*].name') }}"
+
+To extract ports from cluster1:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
+      vars:
+        server_name_cluster1_query: "domain.server[?cluster=='cluster1'].port"
+
+.. note:: You can use a variable to make the query more readable.
+
+To print out the ports from cluster1 in a comma separated string:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1 as a string
+      ansible.builtin.debug:
+        msg: "{{ domain_definition | community.general.json_query('domain.server[?cluster==`cluster1`].port') | join(', ') }}"
+
+.. note:: In the example above, quoting literals using backticks avoids escaping quotes and maintains readability.
+
+You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query('domain.server[?cluster==''cluster1''].port') }}"
+
+.. note:: Escaping single quotes within single quotes in YAML is done by doubling the single quote.
+
+To get a hash map with all ports and names of a cluster:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all server ports and names from cluster1
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
+      vars:
+        server_name_cluster1_query: "domain.server[?cluster=='cluster2'].{name: name, port: port}"
+
+To extract ports from all clusters with name starting with 'server1':
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1
+      ansible.builtin.debug:
+        msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
+      vars:
+        server_name_query: "domain.server[?starts_with(name,'server1')].port"
+
+To extract ports from all clusters with name containing 'server1':
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1
+      ansible.builtin.debug:
+        msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
+      vars:
+        server_name_query: "domain.server[?contains(name,'server1')].port"
+
+.. note:: while using ``starts_with`` and ``contains``, you have to use `` to_json | from_json `` filter for correct parsing of data structure.

docs/docsite/rst/filter_guide_working_with_times.rst

@@ -0,0 +1,84 @@
+Working with times
+------------------
+
+The ``to_time_unit`` filter allows to convert times from a human-readable string to a unit. For example, ``'4h 30min 12second' | community.general.to_time_unit('hour')`` gives the number of hours that correspond to 4 hours, 30 minutes and 12 seconds.
+
+There are shorthands to directly convert to various units, like ``to_hours``, ``to_minutes``, ``to_seconds``, and so on. The following table lists all units that can be used:
+
+.. list-table:: Units
+   :widths: 25 25 25 25
+   :header-rows: 1
+
+   * - Unit name
+     - Unit value in seconds
+     - Unit strings for filter
+     - Shorthand filter
+   * - Millisecond
+     - 1/1000 second
+     - ``ms``, ``millisecond``, ``milliseconds``, ``msec``, ``msecs``, ``msecond``, ``mseconds``
+     - ``to_milliseconds``
+   * - Second
+     - 1 second
+     - ``s``, ``sec``, ``secs``, ``second``, ``seconds``
+     - ``to_seconds``
+   * - Minute
+     - 60 seconds
+     - ``m``, ``min``, ``mins``, ``minute``, ``minutes``
+     - ``to_minutes``
+   * - Hour
+     - 60*60 seconds
+     - ``h``, ``hour``, ``hours``
+     - ``to_hours``
+   * - Day
+     - 24*60*60 seconds
+     - ``d``, ``day``, ``days``
+     - ``to_days``
+   * - Week
+     - 7*24*60*60 seconds
+     - ``w``, ``week``, ``weeks``
+     - ``to_weeks``
+   * - Month
+     - 30*24*60*60 seconds
+     - ``mo``, ``month``, ``months``
+     - ``to_months``
+   * - Year
+     - 365*24*60*60 seconds
+     - ``y``, ``year``, ``years``
+     - ``to_years``
+
+Note that months and years are using a simplified representation: a month is 30 days, and a year is 365 days. If you need different definitions of months or years, you can pass them as keyword arguments. For example, if you want a year to be 365.25 days, and a month to be 30.5 days, you can write ``'11months 4' | community.general.to_years(year=365.25, month=30.5)``. These keyword arguments can be specified to ``to_time_unit`` and to all shorthand filters.
+
+.. code-block:: yaml+jinja
+
+    - name: Convert string to seconds
+      debug:
+        msg: "{{ '30h 20m 10s 123ms' | community.general.to_time_unit('seconds') }}"
+
+    - name: Convert string to hours
+      debug:
+        msg: "{{ '30h 20m 10s 123ms' | community.general.to_hours }}"
+
+    - name: Convert string to years (using 365.25 days == 1 year)
+      debug:
+        msg: "{{ '400d 15h' | community.general.to_years(year=365.25) }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Convert string to seconds] **********************************************************
+    ok: [localhost] => {
+        "msg": "109210.123"
+    }
+
+    TASK [Convert string to hours] ************************************************************
+    ok: [localhost] => {
+        "msg": "30.336145277778"
+    }
+
+    TASK [Convert string to years (using 365.25 days == 1 year)] ******************************
+    ok: [localhost] => {
+        "msg": "1.096851471595"
+    }
+
+.. versionadded: 0.2.0

docs/docsite/rst/filter_guide_working_with_unicode.rst

@@ -0,0 +1,30 @@
+Working with Unicode
+---------------------
+
+`Unicode <https://unicode.org/main.html>`_ makes it possible to produce two strings which may be visually equivalent, but are comprised of distinctly different characters/character sequences. To address this ``Unicode`` defines `normalization forms <https://unicode.org/reports/tr15/>`_ which avoid these distinctions by choosing a unique character sequence for a given visual representation.
+
+You can use the ``community.general.unicode_normalize`` filter to normalize ``Unicode`` strings within your playbooks.
+
+.. code-block:: yaml+jinja
+
+    - name: Compare Unicode representations
+      debug:
+        msg: "{{ with_combining_character | community.general.unicode_normalize == without_combining_character }}"
+      vars:
+        with_combining_character: "{{ 'Mayagu\u0308ez' }}"
+        without_combining_character: Mayagüez
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Compare Unicode representations] ********************************************************
+    ok: [localhost] => {
+        "msg": true
+    }
+
+The ``community.general.unicode_normalize`` filter accepts a keyword argument to select the ``Unicode`` form used to normalize the input string.
+
+:form: One of ``'NFC'`` (default), ``'NFD'``, ``'NFKC'``, or ``'NFKD'``. See the `Unicode reference <https://unicode.org/reports/tr15/>`_ for more information.
+
+.. versionadded:: 3.7.0

docs/docsite/rst/filter_guide_working_with_versions.rst

@@ -0,0 +1,34 @@
+Working with versions
+---------------------
+
+If you need to sort a list of version numbers, the Jinja ``sort`` filter is problematic. Since it sorts lexicographically, ``2.10`` will come before ``2.9``. To treat version numbers correctly, you can use the ``version_sort`` filter:
+
+.. code-block:: yaml+jinja
+
+    - name: Sort list by version number
+      debug:
+        var: ansible_versions | community.general.version_sort
+      vars:
+        ansible_versions:
+          - '2.8.0'
+          - '2.11.0'
+          - '2.7.0'
+          - '2.10.0'
+          - '2.9.0'
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Sort list by version number] ********************************************************
+    ok: [localhost] => {
+        "ansible_versions | community.general.version_sort": [
+            "2.7.0",
+            "2.8.0",
+            "2.9.0",
+            "2.10.0",
+            "2.11.0"
+        ]
+    }
+
+.. versionadded: 2.2.0

galaxy.yml

@@ -1,6 +1,6 @@
 namespace: community
 name: general
-version: 4.3.0
+version: 4.6.0
 readme: README.md
 authors:
   - Ansible (https://github.com/ansible)

plugins/cache/memcached.py

@@ -20,6 +20,7 @@ DOCUMENTATION = '''
           - List of connection information for the memcached DBs
         default: ['127.0.0.1:11211']
         type: list
+        elements: string
         env:
           - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
         ini:

plugins/callback/mail.py

@@ -11,14 +11,16 @@ name: mail
 type: notification
 short_description: Sends failure events via email
 description:
-- This callback will report failures via email
+- This callback will report failures via email.
 author:
 - Dag Wieers (@dagwieers)
 requirements:
 - whitelisting in configuration
 options:
   mta:
-    description: Mail Transfer Agent, server that accepts SMTP
+    description:
+        - Mail Transfer Agent, server that accepts SMTP.
+    type: str
     env:
         - name: SMTPHOST
     ini:
@@ -26,39 +28,53 @@ options:
           key: smtphost
     default: localhost
   mtaport:
-    description: Mail Transfer Agent Port, port at which server SMTP
+    description:
+        - Mail Transfer Agent Port.
+        - Port at which server SMTP.
+    type: int
     ini:
         - section: callback_mail
           key: smtpport
     default: 25
   to:
-    description: Mail recipient
+    description:
+        - Mail recipient.
+    type: list
+    elements: str
     ini:
         - section: callback_mail
           key: to
-    default: root
+    default: [root]
   sender:
-    description: Mail sender
+    description:
+        - Mail sender.
+        - Note that this will be required from community.general 6.0.0 on.
+    type: str
     ini:
         - section: callback_mail
           key: sender
   cc:
-    description: CC'd recipient
+    description:
+        - CC'd recipients.
+    type: list
+    elements: str
     ini:
         - section: callback_mail
           key: cc
   bcc:
-    description: BCC'd recipient
+    description:
+        - BCC'd recipients.
+    type: list
+    elements: str
     ini:
         - section: callback_mail
           key: bcc
-notes:
-- "TODO: expand configuration options now that plugins can leverage Ansible's configuration"
 '''
 
 import json
 import os
 import re
+import email.utils
 import smtplib
 
 from ansible.module_utils.six import string_types
@@ -88,9 +104,13 @@ class CallbackModule(CallbackBase):
         super(CallbackModule, self).set_options(task_keys=task_keys, var_options=var_options, direct=direct)
 
         self.sender = self.get_option('sender')
+        if self.sender is None:
+            self._display.deprecated(
+                'The sender for the mail callback has not been specified. This will be an error in the future',
+                version='6.0.0', collection_name='community.general')
         self.to = self.get_option('to')
         self.smtphost = self.get_option('mta')
-        self.smtpport = int(self.get_option('mtaport'))
+        self.smtpport = self.get_option('mtaport')
         self.cc = self.get_option('cc')
         self.bcc = self.get_option('bcc')
 
@@ -100,28 +120,34 @@ class CallbackModule(CallbackBase):
 
         smtp = smtplib.SMTP(self.smtphost, port=self.smtpport)
 
-        b_sender = to_bytes(self.sender)
-        b_to = to_bytes(self.to)
-        b_cc = to_bytes(self.cc)
-        b_bcc = to_bytes(self.bcc)
-        b_subject = to_bytes(subject)
-        b_body = to_bytes(body)
-
-        b_content = b'From: %s\n' % b_sender
-        b_content += b'To: %s\n' % b_to
+        sender_address = email.utils.parseaddr(self.sender)
+        if self.to:
+            to_addresses = email.utils.getaddresses(self.to)
         if self.cc:
-            b_content += b'Cc: %s\n' % b_cc
-        b_content += b'Subject: %s\n\n' % b_subject
-        b_content += b_body
-
-        b_addresses = b_to.split(b',')
-        if self.cc:
-            b_addresses += b_cc.split(b',')
+            cc_addresses = email.utils.getaddresses(self.cc)
         if self.bcc:
-            b_addresses += b_bcc.split(b',')
+            bcc_addresses = email.utils.getaddresses(self.bcc)
 
-        for b_address in b_addresses:
-            smtp.sendmail(b_sender, b_address, b_content)
+        content = 'Date: %s\n' % email.utils.formatdate()
+        content += 'From: %s\n' % email.utils.formataddr(sender_address)
+        if self.to:
+            content += 'To: %s\n' % ', '.join([email.utils.formataddr(pair) for pair in to_addresses])
+        if self.cc:
+            content += 'Cc: %s\n' % ', '.join([email.utils.formataddr(pair) for pair in cc_addresses])
+        content += 'Message-ID: %s\n' % email.utils.make_msgid()
+        content += 'Subject: %s\n\n' % subject.strip()
+        content += body
+
+        addresses = to_addresses
+        if self.cc:
+            addresses += cc_addresses
+        if self.bcc:
+            addresses += bcc_addresses
+
+        if not addresses:
+            self._display.warning('No receiver has been specified for the mail callback plugin.')
+
+        smtp.sendmail(self.sender, [address for name, address in addresses], to_bytes(content))
 
         smtp.quit()
 

plugins/callback/opentelemetry.py

@@ -319,9 +319,9 @@ class OpenTelemetrySource(object):
     @staticmethod
     def url_from_args(args):
         # the order matters
-        url_args = ("url", "api_url", "baseurl", "repo", "server_url", "chart_repo_url")
+        url_args = ("url", "api_url", "baseurl", "repo", "server_url", "chart_repo_url", "registry_url", "endpoint", "uri", "updates_url")
         for arg in url_args:
-            if args.get(arg):
+            if args is not None and args.get(arg):
                 return args.get(arg)
         return ""
 

plugins/callback/syslog_json.py

@@ -41,6 +41,16 @@ DOCUMENTATION = '''
         ini:
           - section: callback_syslog_json
             key: syslog_facility
+      setup:
+        description: Log setup tasks.
+        env:
+          - name: ANSIBLE_SYSLOG_SETUP
+        type: bool
+        default: true
+        ini:
+          - section: callback_syslog_json
+            key: syslog_setup
+        version_added: 4.5.0
 '''
 
 import os
@@ -86,23 +96,36 @@ class CallbackModule(CallbackBase):
         self.logger.addHandler(self.handler)
         self.hostname = socket.gethostname()
 
-    def runner_on_failed(self, host, res, ignore_errors=False):
+    def v2_runner_on_failed(self, result, ignore_errors=False):
+        res = result._result
+        host = result._host.get_name()
         self.logger.error('%s ansible-command: task execution FAILED; host: %s; message: %s', self.hostname, host, self._dump_results(res))
 
-    def runner_on_ok(self, host, res):
-        self.logger.info('%s ansible-command: task execution OK; host: %s; message: %s', self.hostname, host, self._dump_results(res))
+    def v2_runner_on_ok(self, result):
+        res = result._result
+        host = result._host.get_name()
+        if result._task.action != "gather_facts" or self.get_option("setup"):
+            self.logger.info('%s ansible-command: task execution OK; host: %s; message: %s', self.hostname, host, self._dump_results(res))
 
-    def runner_on_skipped(self, host, item=None):
+    def v2_runner_on_skipped(self, result):
+        host = result._host.get_name()
         self.logger.info('%s ansible-command: task execution SKIPPED; host: %s; message: %s', self.hostname, host, 'skipped')
 
-    def runner_on_unreachable(self, host, res):
+    def v2_runner_on_unreachable(self, result):
+        res = result._result
+        host = result._host.get_name()
         self.logger.error('%s ansible-command: task execution UNREACHABLE; host: %s; message: %s', self.hostname, host, self._dump_results(res))
 
-    def runner_on_async_failed(self, host, res, jid):
+    def v2_runner_on_async_failed(self, result):
+        res = result._result
+        host = result._host.get_name()
+        jid = result._result.get('ansible_job_id')
         self.logger.error('%s ansible-command: task execution FAILED; host: %s; message: %s', self.hostname, host, self._dump_results(res))
 
-    def playbook_on_import_for_host(self, host, imported_file):
+    def v2_playbook_on_import_for_host(self, result, imported_file):
+        host = result._host.get_name()
         self.logger.info('%s ansible-command: playbook IMPORTED; host: %s; message: imported file %s', self.hostname, host, imported_file)
 
-    def playbook_on_not_import_for_host(self, host, missing_file):
+    def v2_playbook_on_not_import_for_host(self, result, missing_file):
+        host = result._host.get_name()
         self.logger.info('%s ansible-command: playbook NOT IMPORTED; host: %s; message: missing file %s', self.hostname, host, missing_file)

plugins/doc_fragments/keycloak.py

@@ -61,4 +61,11 @@ options:
             - Verify TLS certificates (do not disable this in production).
         type: bool
         default: yes
+
+    connection_timeout:
+        description:
+            - Controls the HTTP connections timeout period (in seconds) to Keycloak API.
+        type: int
+        default: 10
+        version_added: 4.5.0
 '''

plugins/filter/list.py

@@ -1,43 +1,113 @@
 # -*- coding: utf-8 -*-
-# Copyright (c) 2020, Vladimir Botka <vbotka@gmail.com>
+# Copyright (c) 2020-2022, Vladimir Botka <vbotka@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from ansible.errors import AnsibleError, AnsibleFilterError
+from ansible.errors import AnsibleFilterError
 from ansible.module_utils.six import string_types
 from ansible.module_utils.common._collections_compat import Mapping, Sequence
+from ansible.utils.vars import merge_hash
+from ansible.release import __version__ as ansible_version
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 from collections import defaultdict
 from operator import itemgetter
 
 
-def lists_mergeby(l1, l2, index):
-    ''' merge lists by attribute index. Example:
-        - debug: msg="{{ l1|community.general.lists_mergeby(l2, 'index')|list }}" '''
+def merge_hash_wrapper(x, y, recursive=False, list_merge='replace'):
+    ''' Wrapper of the function merge_hash from ansible.utils.vars. Only 2 paramaters are allowed
+        for Ansible 2.9 and lower.'''
 
-    if not isinstance(l1, Sequence):
-        raise AnsibleFilterError('First argument for community.general.lists_mergeby must be list. %s is %s' %
-                                 (l1, type(l1)))
+    if LooseVersion(ansible_version) < LooseVersion('2.10'):
+        if list_merge != 'replace' or recursive:
+            msg = ("Non default options of list_merge(default=replace) or recursive(default=False) "
+                   "are not allowed in Ansible version 2.9 or lower. Ansible version is %s, "
+                   "recursive=%s, and list_merge=%s.")
+            raise AnsibleFilterError(msg % (ansible_version, recursive, list_merge))
+        else:
+            return merge_hash(x, y)
+    else:
+        return merge_hash(x, y, recursive, list_merge)
 
-    if not isinstance(l2, Sequence):
-        raise AnsibleFilterError('Second argument for community.general.lists_mergeby must be list. %s is %s' %
-                                 (l2, type(l2)))
 
-    if not isinstance(index, string_types):
-        raise AnsibleFilterError('Third argument for community.general.lists_mergeby must be string. %s is %s' %
-                                 (index, type(index)))
+def list_mergeby(x, y, index, recursive=False, list_merge='replace'):
+    ''' Merge 2 lists by attribute 'index'. The function merge_hash from ansible.utils.vars is used.
+        This function is used by the function lists_mergeby.
+    '''
 
     d = defaultdict(dict)
-    for l in (l1, l2):
+    for l in (x, y):
         for elem in l:
             if not isinstance(elem, Mapping):
-                raise AnsibleFilterError('Elements of list arguments for lists_mergeby must be dictionaries. Found {0!r}.'.format(elem))
+                msg = "Elements of list arguments for lists_mergeby must be dictionaries. %s is %s"
+                raise AnsibleFilterError(msg % (elem, type(elem)))
             if index in elem.keys():
-                d[elem[index]].update(elem)
+                d[elem[index]].update(merge_hash_wrapper(d[elem[index]], elem, recursive, list_merge))
     return sorted(d.values(), key=itemgetter(index))
 
 
+def lists_mergeby(*terms, **kwargs):
+    ''' Merge 2 or more lists by attribute 'index'. Optional parameters 'recursive' and 'list_merge'
+        control the merging of the lists in values. The function merge_hash from ansible.utils.vars
+        is used. To learn details on how to use the parameters 'recursive' and 'list_merge' see
+        Ansible User's Guide chapter "Using filters to manipulate data" section "Combining
+        hashes/dictionaries".
+
+        Example:
+        - debug:
+            msg: "{{ list1|
+                     community.general.lists_mergeby(list2,
+                                                     'index',
+                                                     recursive=True,
+                                                     list_merge='append')|
+                     list }}"
+    '''
+
+    recursive = kwargs.pop('recursive', False)
+    list_merge = kwargs.pop('list_merge', 'replace')
+    if kwargs:
+        raise AnsibleFilterError("'recursive' and 'list_merge' are the only valid keyword arguments.")
+    if len(terms) < 2:
+        raise AnsibleFilterError("At least one list and index are needed.")
+
+    # allow the user to do `[list1, list2, ...] | lists_mergeby('index')`
+    flat_list = []
+    for sublist in terms[:-1]:
+        if not isinstance(sublist, Sequence):
+            msg = ("All arguments before the argument index for community.general.lists_mergeby "
+                   "must be lists. %s is %s")
+            raise AnsibleFilterError(msg % (sublist, type(sublist)))
+        if len(sublist) > 0:
+            if all(isinstance(l, Sequence) for l in sublist):
+                for item in sublist:
+                    flat_list.append(item)
+            else:
+                flat_list.append(sublist)
+    lists = flat_list
+
+    if not lists:
+        return []
+
+    if len(lists) == 1:
+        return lists[0]
+
+    index = terms[-1]
+
+    if not isinstance(index, string_types):
+        msg = ("First argument after the lists for community.general.lists_mergeby must be string. "
+               "%s is %s")
+        raise AnsibleFilterError(msg % (index, type(index)))
+
+    high_to_low_prio_list_iterator = reversed(lists)
+    result = next(high_to_low_prio_list_iterator)
+    for list in high_to_low_prio_list_iterator:
+        result = list_mergeby(list, result, index, recursive, list_merge)
+
+    return result
+
+
 class FilterModule(object):
     ''' Ansible list filters '''
 

plugins/inventory/cobbler.py

@@ -40,13 +40,25 @@ DOCUMENTATION = '''
         type: boolean
         default: no
       exclude_profiles:
-        description: Profiles to exclude from inventory
+        description:
+          - Profiles to exclude from inventory.
+          - Ignored if I(include_profiles) is specified.
         type: list
         default: []
         elements: str
+      include_profiles:
+        description:
+          - Profiles to include from inventory.
+          - If specified, all other profiles will be excluded.
+          - I(exclude_profiles) is ignored if I(include_profiles) is specified.
+        type: list
+        default: []
+        elements: str
+        version_added: 4.4.0
       group_by:
         description: Keys to group hosts by
         type: list
+        elements: string
         default: [ 'mgmt_classes', 'owners', 'status' ]
       group:
         description: Group to place all hosts into
@@ -71,8 +83,7 @@ password: secure
 import socket
 
 from ansible.errors import AnsibleError
-from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
-from ansible.module_utils.common._collections_compat import MutableMapping
+from ansible.module_utils.common.text.converters import to_text
 from ansible.module_utils.six import iteritems
 from ansible.plugins.inventory import BaseInventoryPlugin, Cacheable, to_safe_group_name
 
@@ -94,18 +105,9 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
     NAME = 'community.general.cobbler'
 
     def __init__(self):
-
         super(InventoryModule, self).__init__()
-
-        # from config
-        self.cobbler_url = None
-        self.exclude_profiles = []  # A list of profiles to exclude
-
-        self.connection = None
-        self.token = None
-
         self.cache_key = None
-        self.use_cache = None
+        self.connection = None
 
     def verify_file(self, path):
         valid = False
@@ -177,6 +179,12 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
             self.inventory.add_child(group_name, child)
         return group_name
 
+    def _exclude_profile(self, profile):
+        if self.include_profiles:
+            return profile not in self.include_profiles
+        else:
+            return profile in self.exclude_profiles
+
     def parse(self, inventory, loader, path, cache=True):
 
         super(InventoryModule, self).parse(inventory, loader, path)
@@ -190,15 +198,16 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
         self.use_cache = cache and self.get_option('cache')
 
         self.exclude_profiles = self.get_option('exclude_profiles')
+        self.include_profiles = self.get_option('include_profiles')
         self.group_by = self.get_option('group_by')
 
         for profile in self._get_profiles():
             if profile['parent']:
                 self.display.vvvv('Processing profile %s with parent %s\n' % (profile['name'], profile['parent']))
-                if profile['parent'] not in self.exclude_profiles:
+                if not self._exclude_profile(profile['parent']):
                     parent_group_name = self._add_safe_group_name(profile['parent'])
                     self.display.vvvv('Added profile parent group %s\n' % parent_group_name)
-                    if profile['name'] not in self.exclude_profiles:
+                    if not self._exclude_profile(profile['name']):
                         group_name = self._add_safe_group_name(profile['name'])
                         self.display.vvvv('Added profile group %s\n' % group_name)
                         self.inventory.add_child(parent_group_name, group_name)
@@ -210,7 +219,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
                 while i < len(profile_elements) - 1:
                     profile_group = '-'.join(profile_elements[0:i + 1])
                     profile_group_child = '-'.join(profile_elements[0:i + 2])
-                    if profile_group in self.exclude_profiles:
+                    if self._exclude_profile(profile_group):
                         self.display.vvvv('Excluding profile %s\n' % profile_group)
                         break
                     group_name = self._add_safe_group_name(profile_group)
@@ -231,7 +240,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
             hostname = host['hostname']  # None
             interfaces = host['interfaces']
 
-            if host['profile'] in self.exclude_profiles:
+            if self._exclude_profile(host['profile']):
                 self.display.vvvv('Excluding host %s in profile %s\n' % (host['name'], host['profile']))
                 continue
 

plugins/inventory/gitlab_runners.py

@@ -35,7 +35,6 @@ DOCUMENTATION = '''
                 version_added: 1.0.0
             type: str
             required: true
-            default: https://gitlab.com
         api_token:
             description: GitLab token for logging in.
             env:

plugins/inventory/icinga2.py

@@ -16,7 +16,17 @@ DOCUMENTATION = '''
         - Get inventory hosts from the Icinga2 API.
         - "Uses a configuration file as an inventory source, it must end in
           C(.icinga2.yml) or C(.icinga2.yaml)."
+    extends_documentation_fragment:
+        - constructed
     options:
+      strict:
+        version_added: 4.4.0
+      compose:
+        version_added: 4.4.0
+      groups:
+        version_added: 4.4.0
+      keyed_groups:
+        version_added: 4.4.0
       plugin:
         description: Name of the plugin.
         required: true
@@ -63,6 +73,20 @@ password: secure
 host_filter: \"linux-servers\" in host.groups
 validate_certs: false
 inventory_attr: name
+groups:
+  # simple name matching
+  webservers: inventory_hostname.startswith('web')
+
+  # using icinga2 template
+  databaseservers: "'db-template' in (icinga2_attributes.templates|list)"
+
+compose:
+  # set all icinga2 attributes to a host variable 'icinga2_attrs'
+  icinga2_attrs: icinga2_attributes
+
+  # set 'ansible_user' and 'ansible_port' from icinga2 host vars
+  ansible_user: icinga2_attributes.vars.ansible_user
+  ansible_port: icinga2_attributes.vars.ansible_port | default(22)
 '''
 
 import json
@@ -180,7 +204,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         """Query for all hosts """
         self.display.vvv("Querying Icinga2 for inventory")
         query_args = {
-            "attrs": ["address", "display_name", "state_type", "state", "groups"],
+            "attrs": ["address", "address6", "name", "display_name", "state_type", "state", "templates", "groups", "vars", "zone"],
         }
         if self.host_filter is not None:
             query_args['host_filter'] = self.host_filter
@@ -190,6 +214,12 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         ansible_inv = self._convert_inv(results_json)
         return ansible_inv
 
+    def _apply_constructable(self, name, variables):
+        strict = self.get_option('strict')
+        self._add_host_to_composed_groups(self.get_option('groups'), variables, name, strict=strict)
+        self._add_host_to_keyed_groups(self.get_option('keyed_groups'), variables, name, strict=strict)
+        self._set_composite_vars(self.get_option('compose'), variables, name, strict=strict)
+
     def _populate(self):
         groups = self._to_json(self.get_inventory_from_icinga())
         return groups
@@ -232,6 +262,10 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
                                         host_attrs['state'])
             self.inventory.set_variable(host_name, 'state_type',
                                         host_attrs['state_type'])
+            # Adds all attributes to a variable 'icinga2_attributes'
+            construct_vars = dict(self.inventory.get_host(host_name).get_vars())
+            construct_vars['icinga2_attributes'] = host_attrs
+            self._apply_constructable(host_name, construct_vars)
         return groups_dict
 
     def parse(self, inventory, loader, path, cache=True):

plugins/inventory/linode.py

@@ -21,7 +21,18 @@ DOCUMENTATION = r'''
           Linode) and not tags.
     extends_documentation_fragment:
         - constructed
+        - inventory_cache
     options:
+        cache:
+            version_added: 4.5.0
+        cache_plugin:
+            version_added: 4.5.0
+        cache_timeout:
+            version_added: 4.5.0
+        cache_connection:
+            version_added: 4.5.0
+        cache_prefix:
+            version_added: 4.5.0
         plugin:
             description: Marks this as an instance of the 'linode' plugin.
             required: true
@@ -43,15 +54,18 @@ DOCUMENTATION = r'''
           description: Populate inventory with instances in this region.
           default: []
           type: list
+          elements: string
         tags:
           description: Populate inventory only with instances which have at least one of the tags listed here.
           default: []
           type: list
+          elements: string
           version_added: 2.0.0
         types:
           description: Populate inventory with instances with this type.
           default: []
           type: list
+          elements: string
         strict:
           version_added: 2.0.0
         compose:
@@ -66,6 +80,12 @@ EXAMPLES = r'''
 # Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment.
 plugin: community.general.linode
 
+# You can use Jinja to template the access token.
+plugin: community.general.linode
+access_token: "{{ lookup('ini', 'token', section='your_username', file='~/.config/linode-cli') }}"
+# For older Ansible versions, you need to write this as:
+# access_token: "{{ lookup('ini', 'token section=your_username file=~/.config/linode-cli') }}"
+
 # Example with regions, types, groups and access token
 plugin: community.general.linode
 access_token: foobar
@@ -104,25 +124,31 @@ import os
 
 from ansible.errors import AnsibleError, AnsibleParserError
 from ansible.module_utils.six import string_types
-from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
+from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable
+from ansible.template import Templar
 
 
 try:
     from linode_api4 import LinodeClient
+    from linode_api4.objects.linode import Instance
     from linode_api4.errors import ApiError as LinodeApiError
     HAS_LINODE = True
 except ImportError:
     HAS_LINODE = False
 
 
-class InventoryModule(BaseInventoryPlugin, Constructable):
+class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
 
     NAME = 'community.general.linode'
 
-    def _build_client(self):
+    def _build_client(self, loader):
         """Build the Linode client."""
 
+        t = Templar(loader=loader)
+
         access_token = self.get_option('access_token')
+        if t.is_template(access_token):
+            access_token = t.template(variable=access_token, disable_lookups=False)
 
         if access_token is None:
             try:
@@ -158,20 +184,23 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         for linode_group in self.linode_groups:
             self.inventory.add_group(linode_group)
 
-    def _filter_by_config(self, regions, types, tags):
+    def _filter_by_config(self):
         """Filter instances by user specified configuration."""
+        regions = self.get_option('regions')
         if regions:
             self.instances = [
                 instance for instance in self.instances
                 if instance.region.id in regions
             ]
 
+        types = self.get_option('types')
         if types:
             self.instances = [
                 instance for instance in self.instances
                 if instance.type.id in types
             ]
 
+        tags = self.get_option('tags')
         if tags:
             self.instances = [
                 instance for instance in self.instances
@@ -224,76 +253,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
             )
         return data
 
-    def _validate_option(self, name, desired_type, option_value):
-        """Validate user specified configuration data against types."""
-        if isinstance(option_value, string_types) and desired_type == list:
-            option_value = [option_value]
-
-        if option_value is None:
-            option_value = desired_type()
-
-        if not isinstance(option_value, desired_type):
-            raise AnsibleParserError(
-                'The option %s (%s) must be a %s' % (
-                    name, option_value, desired_type
-                )
-            )
-
-        return option_value
-
-    def _get_query_options(self, config_data):
-        """Get user specified query options from the configuration."""
-        options = {
-            'regions': {
-                'type_to_be': list,
-                'value': config_data.get('regions', [])
-            },
-            'types': {
-                'type_to_be': list,
-                'value': config_data.get('types', [])
-            },
-            'tags': {
-                'type_to_be': list,
-                'value': config_data.get('tags', [])
-            },
-        }
-
-        for name in options:
-            options[name]['value'] = self._validate_option(
-                name,
-                options[name]['type_to_be'],
-                options[name]['value']
-            )
-
-        regions = options['regions']['value']
-        types = options['types']['value']
-        tags = options['tags']['value']
-
-        return regions, types, tags
-
-    def verify_file(self, path):
-        """Verify the Linode configuration file."""
-        if super(InventoryModule, self).verify_file(path):
-            endings = ('linode.yaml', 'linode.yml')
-            if any((path.endswith(ending) for ending in endings)):
-                return True
-        return False
-
-    def parse(self, inventory, loader, path, cache=True):
-        """Dynamically parse Linode the cloud inventory."""
-        super(InventoryModule, self).parse(inventory, loader, path)
-
-        if not HAS_LINODE:
-            raise AnsibleError('the Linode dynamic inventory plugin requires linode_api4.')
-
-        config_data = self._read_config_data(path)
-        self._build_client()
-
-        self._get_instances_inventory()
+    def _cacheable_inventory(self):
+        return [i._raw_json for i in self.instances]
 
+    def populate(self):
         strict = self.get_option('strict')
-        regions, types, tags = self._get_query_options(config_data)
-        self._filter_by_config(regions, types, tags)
+
+        self._filter_by_config()
 
         self._add_groups()
         self._add_instances_to_groups()
@@ -315,3 +281,44 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
                 variables,
                 instance.label,
                 strict=strict)
+
+    def verify_file(self, path):
+        """Verify the Linode configuration file."""
+        if super(InventoryModule, self).verify_file(path):
+            endings = ('linode.yaml', 'linode.yml')
+            if any((path.endswith(ending) for ending in endings)):
+                return True
+        return False
+
+    def parse(self, inventory, loader, path, cache=True):
+        """Dynamically parse Linode the cloud inventory."""
+        super(InventoryModule, self).parse(inventory, loader, path)
+        self.instances = None
+
+        if not HAS_LINODE:
+            raise AnsibleError('the Linode dynamic inventory plugin requires linode_api4.')
+
+        self._read_config_data(path)
+
+        cache_key = self.get_cache_key(path)
+
+        if cache:
+            cache = self.get_option('cache')
+
+        update_cache = False
+        if cache:
+            try:
+                self.instances = [Instance(None, i["id"], i) for i in self._cache[cache_key]]
+            except KeyError:
+                update_cache = True
+
+        # Check for None rather than False in order to allow
+        # for empty sets of cached instances
+        if self.instances is None:
+            self._build_client(loader)
+            self._get_instances_inventory()
+
+        if update_cache:
+            self._cache[cache_key] = self._cacheable_inventory()
+
+        self.populate()

plugins/inventory/nmap.py

@@ -27,6 +27,7 @@ DOCUMENTATION = '''
         exclude:
             description: list of addresses to exclude
             type: list
+            elements: string
         ports:
             description: Enable/disable scanning for open ports
             type: boolean

plugins/inventory/online.py

@@ -28,6 +28,7 @@ DOCUMENTATION = r'''
         hostnames:
             description: List of preference about what to use as an hostname.
             type: list
+            elements: string
             default:
                 - public_ipv4
             choices:
@@ -37,6 +38,7 @@ DOCUMENTATION = r'''
         groups:
             description: List of groups.
             type: list
+            elements: string
             choices:
                 - location
                 - offer

plugins/inventory/opennebula.py

@@ -95,7 +95,7 @@ except ImportError:
 
 from ansible.errors import AnsibleError
 from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
-from ansible.module_utils._text import to_native
+from ansible.module_utils.common.text.converters import to_native
 
 from collections import namedtuple
 import os

plugins/inventory/proxmox.py

@@ -77,6 +77,12 @@ DOCUMENTATION = '''
           - When set to C(true) (default), will use the first available interface. This can be different from what you expect.
         default: true
         type: bool
+      filters:
+        version_added: 4.6.0
+        description: A list of Jinja templates that allow filtering hosts.
+        type: list
+        elements: str
+        default: []
       strict:
         version_added: 2.5.0
       compose:
@@ -114,15 +120,34 @@ groups:
   mailservers: "'mail' in (proxmox_tags_parsed|list)"
 compose:
   ansible_port: 2222
+
+# Using the inventory to allow ansible to connect via the first IP address of the VM / Container
+# (Default is connection by name of QEMU/LXC guests)
+# Note: my_inv_var demonstrates how to add a string variable to every host used by the inventory.
+# my.proxmox.yml
+plugin: community.general.proxmox
+url: http://pve.domain.com:8006
+user: ansible@pve
+password: secure
+validate_certs: false
+want_facts: true
+compose:
+  ansible_host: proxmox_ipconfig0.ip | default(proxmox_net0.ip) | ipaddr('address')
+  my_inv_var_1: "'my_var1_value'"
+  my_inv_var_2: >
+    "my_var_2_value"
 '''
 
+import itertools
 import re
 
 from ansible.module_utils.common._collections_compat import MutableMapping
 
 from ansible.errors import AnsibleError
 from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable
+from ansible.module_utils.common.text.converters import to_native
 from ansible.module_utils.six.moves.urllib.parse import urlencode
+from ansible.utils.display import Display
 
 from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
@@ -135,6 +160,8 @@ try:
 except ImportError:
     HAS_REQUESTS = False
 
+display = Display()
+
 
 class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
     ''' Host inventory parser for ansible using Proxmox as source. '''
@@ -275,28 +302,19 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
 
         return result
 
-    def _get_vm_config(self, node, vmid, vmtype, name):
+    def _get_vm_config(self, properties, node, vmid, vmtype, name):
         ret = self._get_json("%s/api2/json/nodes/%s/%s/%s/config" % (self.proxmox_url, node, vmtype, vmid))
 
-        node_key = 'node'
-        node_key = self.to_safe('%s%s' % (self.get_option('facts_prefix'), node_key.lower()))
-        self.inventory.set_variable(name, node_key, node)
-
-        vmid_key = 'vmid'
-        vmid_key = self.to_safe('%s%s' % (self.get_option('facts_prefix'), vmid_key.lower()))
-        self.inventory.set_variable(name, vmid_key, vmid)
-
-        vmtype_key = 'vmtype'
-        vmtype_key = self.to_safe('%s%s' % (self.get_option('facts_prefix'), vmtype_key.lower()))
-        self.inventory.set_variable(name, vmtype_key, vmtype)
+        properties[self._fact('node')] = node
+        properties[self._fact('vmid')] = vmid
+        properties[self._fact('vmtype')] = vmtype
 
         plaintext_configs = [
-            'tags',
+            'description',
         ]
 
         for config in ret:
-            key = config
-            key = self.to_safe('%s%s' % (self.get_option('facts_prefix'), key.lower()))
+            key = self._fact(config)
             value = ret[config]
             try:
                 # fixup disk images as they have no key
@@ -306,45 +324,36 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
                 # Additional field containing parsed tags as list
                 if config == 'tags':
                     parsed_key = self.to_safe('%s%s' % (key, "_parsed"))
-                    parsed_value = [tag.strip() for tag in value.split(",")]
-                    self.inventory.set_variable(name, parsed_key, parsed_value)
+                    properties[parsed_key] = [tag.strip() for tag in value.split(",")]
 
                 # The first field in the agent string tells you whether the agent is enabled
                 # the rest of the comma separated string is extra config for the agent
                 if config == 'agent' and int(value.split(',')[0]):
-                    agent_iface_key = self.to_safe('%s%s' % (key, "_interfaces"))
                     agent_iface_value = self._get_agent_network_interfaces(node, vmid, vmtype)
                     if agent_iface_value:
-                        self.inventory.set_variable(name, agent_iface_key, agent_iface_value)
+                        agent_iface_key = self.to_safe('%s%s' % (key, "_interfaces"))
+                        properties[agent_iface_key] = agent_iface_value
 
-                if not (isinstance(value, int) or ',' not in value):
+                if config not in plaintext_configs and not isinstance(value, int) and all("=" in v for v in value.split(",")):
                     # split off strings with commas to a dict
                     # skip over any keys that cannot be processed
                     try:
-                        value = dict(key.split("=") for key in value.split(","))
+                        value = dict(key.split("=", 1) for key in value.split(","))
                     except Exception:
                         continue
 
-                self.inventory.set_variable(name, key, value)
+                properties[key] = value
             except NameError:
                 return None
 
-    def _get_vm_status(self, node, vmid, vmtype, name):
+    def _get_vm_status(self, properties, node, vmid, vmtype, name):
         ret = self._get_json("%s/api2/json/nodes/%s/%s/%s/status/current" % (self.proxmox_url, node, vmtype, vmid))
+        properties[self._fact('status')] = ret['status']
 
-        status = ret['status']
-        status_key = 'status'
-        status_key = self.to_safe('%s%s' % (self.get_option('facts_prefix'), status_key.lower()))
-        self.inventory.set_variable(name, status_key, status)
-
-    def _get_vm_snapshots(self, node, vmid, vmtype, name):
+    def _get_vm_snapshots(self, properties, node, vmid, vmtype, name):
         ret = self._get_json("%s/api2/json/nodes/%s/%s/%s/snapshot" % (self.proxmox_url, node, vmtype, vmid))
-
-        snapshots_key = 'snapshots'
-        snapshots_key = self.to_safe('%s%s' % (self.get_option('facts_prefix'), snapshots_key.lower()))
-
         snapshots = [snapshot['name'] for snapshot in ret if snapshot['name'] != 'current']
-        self.inventory.set_variable(name, snapshots_key, snapshots)
+        properties[self._fact('snapshots')] = snapshots
 
     def to_safe(self, word):
         '''Converts 'bad' characters in a string to underscores so they can be used as Ansible groups
@@ -354,109 +363,130 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
         regex = r"[^A-Za-z0-9\_]"
         return re.sub(regex, "_", word.replace(" ", ""))
 
-    def _apply_constructable(self, name, variables):
-        strict = self.get_option('strict')
-        self._add_host_to_composed_groups(self.get_option('groups'), variables, name, strict=strict)
-        self._add_host_to_keyed_groups(self.get_option('keyed_groups'), variables, name, strict=strict)
-        self._set_composite_vars(self.get_option('compose'), variables, name, strict=strict)
+    def _fact(self, name):
+        '''Generate a fact's full name from the common prefix and a name.'''
+        return self.to_safe('%s%s' % (self.facts_prefix, name.lower()))
+
+    def _group(self, name):
+        '''Generate a group's full name from the common prefix and a name.'''
+        return self.to_safe('%s%s' % (self.group_prefix, name.lower()))
+
+    def _can_add_host(self, name, properties):
+        '''Ensure that a host satisfies all defined hosts filters. If strict mode is
+        enabled, any error during host filter compositing will lead to an AnsibleError
+        being raised, otherwise the filter will be ignored.
+        '''
+        for host_filter in self.host_filters:
+            try:
+                if not self._compose(host_filter, properties):
+                    return False
+            except Exception as e:  # pylint: disable=broad-except
+                message = "Could not evaluate host filter %s for host %s - %s" % (host_filter, name, to_native(e))
+                if self.strict:
+                    raise AnsibleError(message)
+                display.warning(message)
+        return True
+
+    def _add_host(self, name, variables):
+        self.inventory.add_host(name)
+        for k, v in variables.items():
+            self.inventory.set_variable(name, k, v)
+        variables = self.inventory.get_host(name).get_vars()
+        self._set_composite_vars(self.get_option('compose'), variables, name, strict=self.strict)
+        self._add_host_to_composed_groups(self.get_option('groups'), variables, name, strict=self.strict)
+        self._add_host_to_keyed_groups(self.get_option('keyed_groups'), variables, name, strict=self.strict)
+
+    def _handle_item(self, node, ittype, item):
+        '''Handle an item from the list of LXC containers and Qemu VM. The
+        return value will be either None if the item was skipped or the name of
+        the item if it was added to the inventory.'''
+        if item.get('template'):
+            return None
+
+        properties = dict()
+        name, vmid = item['name'], item['vmid']
+
+        # get status, config and snapshots if want_facts == True
+        if self.get_option('want_facts'):
+            self._get_vm_status(properties, node, vmid, ittype, name)
+            self._get_vm_config(properties, node, vmid, ittype, name)
+            self._get_vm_snapshots(properties, node, vmid, ittype, name)
+
+        # ensure the host satisfies filters
+        if not self._can_add_host(name, properties):
+            return None
+
+        # add the host to the inventory
+        self._add_host(name, properties)
+        node_type_group = self._group('%s_%s' % (node, ittype))
+        self.inventory.add_child(self._group('all_' + ittype), name)
+        self.inventory.add_child(node_type_group, name)
+        if item['status'] == 'stopped':
+            self.inventory.add_child(self._group('all_stopped'), name)
+        elif item['status'] == 'running':
+            self.inventory.add_child(self._group('all_running'), name)
+
+        return name
+
+    def _populate_pool_groups(self, added_hosts):
+        '''Generate groups from Proxmox resource pools, ignoring VMs and
+        containers that were skipped.'''
+        for pool in self._get_pools():
+            poolid = pool.get('poolid')
+            if not poolid:
+                continue
+            pool_group = self._group('pool_' + poolid)
+            self.inventory.add_group(pool_group)
+
+            for member in self._get_members_per_pool(poolid):
+                name = member.get('name')
+                if name and name in added_hosts:
+                    self.inventory.add_child(pool_group, name)
 
     def _populate(self):
 
-        self._get_auth()
+        # create common groups
+        self.inventory.add_group(self._group('all_lxc'))
+        self.inventory.add_group(self._group('all_qemu'))
+        self.inventory.add_group(self._group('all_running'))
+        self.inventory.add_group(self._group('all_stopped'))
+        nodes_group = self._group('nodes')
+        self.inventory.add_group(nodes_group)
 
         # gather vm's on nodes
+        self._get_auth()
+        hosts = []
         for node in self._get_nodes():
-            # FIXME: this can probably be cleaner
-            # create groups
-            lxc_group = 'all_lxc'
-            lxc_group = self.to_safe('%s%s' % (self.get_option('group_prefix'), lxc_group.lower()))
-            self.inventory.add_group(lxc_group)
-            qemu_group = 'all_qemu'
-            qemu_group = self.to_safe('%s%s' % (self.get_option('group_prefix'), qemu_group.lower()))
-            self.inventory.add_group(qemu_group)
-            nodes_group = 'nodes'
-            nodes_group = self.to_safe('%s%s' % (self.get_option('group_prefix'), nodes_group.lower()))
-            self.inventory.add_group(nodes_group)
-            running_group = 'all_running'
-            running_group = self.to_safe('%s%s' % (self.get_option('group_prefix'), running_group.lower()))
-            self.inventory.add_group(running_group)
-            stopped_group = 'all_stopped'
-            stopped_group = self.to_safe('%s%s' % (self.get_option('group_prefix'), stopped_group.lower()))
-            self.inventory.add_group(stopped_group)
+            if not node.get('node'):
+                continue
 
-            if node.get('node'):
-                self.inventory.add_host(node['node'])
+            self.inventory.add_host(node['node'])
+            if node['type'] == 'node':
+                self.inventory.add_child(nodes_group, node['node'])
 
-                if node['type'] == 'node':
-                    self.inventory.add_child(nodes_group, node['node'])
+            if node['status'] == 'offline':
+                continue
 
-                if node['status'] == 'offline':
-                    continue
+            # get node IP address
+            if self.get_option("want_proxmox_nodes_ansible_host"):
+                ip = self._get_node_ip(node['node'])
+                self.inventory.set_variable(node['node'], 'ansible_host', ip)
 
-                # get node IP address
-                if self.get_option("want_proxmox_nodes_ansible_host"):
-                    ip = self._get_node_ip(node['node'])
-                    self.inventory.set_variable(node['node'], 'ansible_host', ip)
+            # add LXC/Qemu groups for the node
+            for ittype in ('lxc', 'qemu'):
+                node_type_group = self._group('%s_%s' % (node['node'], ittype))
+                self.inventory.add_group(node_type_group)
 
-                # get LXC containers for this node
-                node_lxc_group = self.to_safe('%s%s' % (self.get_option('group_prefix'), ('%s_lxc' % node['node']).lower()))
-                self.inventory.add_group(node_lxc_group)
-                for lxc in self._get_lxc_per_node(node['node']):
-                    self.inventory.add_host(lxc['name'])
-                    self.inventory.add_child(lxc_group, lxc['name'])
-                    self.inventory.add_child(node_lxc_group, lxc['name'])
-
-                    # get LXC status when want_facts == True
-                    if self.get_option('want_facts'):
-                        self._get_vm_status(node['node'], lxc['vmid'], 'lxc', lxc['name'])
-                        if lxc['status'] == 'stopped':
-                            self.inventory.add_child(stopped_group, lxc['name'])
-                        elif lxc['status'] == 'running':
-                            self.inventory.add_child(running_group, lxc['name'])
-
-                    # get LXC config and snapshots for facts
-                    if self.get_option('want_facts'):
-                        self._get_vm_config(node['node'], lxc['vmid'], 'lxc', lxc['name'])
-                        self._get_vm_snapshots(node['node'], lxc['vmid'], 'lxc', lxc['name'])
-
-                    self._apply_constructable(lxc["name"], self.inventory.get_host(lxc['name']).get_vars())
-
-                # get QEMU vm's for this node
-                node_qemu_group = self.to_safe('%s%s' % (self.get_option('group_prefix'), ('%s_qemu' % node['node']).lower()))
-                self.inventory.add_group(node_qemu_group)
-                for qemu in self._get_qemu_per_node(node['node']):
-                    if qemu.get('template'):
-                        continue
-
-                    self.inventory.add_host(qemu['name'])
-                    self.inventory.add_child(qemu_group, qemu['name'])
-                    self.inventory.add_child(node_qemu_group, qemu['name'])
-
-                    # get QEMU status
-                    self._get_vm_status(node['node'], qemu['vmid'], 'qemu', qemu['name'])
-                    if qemu['status'] == 'stopped':
-                        self.inventory.add_child(stopped_group, qemu['name'])
-                    elif qemu['status'] == 'running':
-                        self.inventory.add_child(running_group, qemu['name'])
-
-                    # get QEMU config and snapshots for facts
-                    if self.get_option('want_facts'):
-                        self._get_vm_config(node['node'], qemu['vmid'], 'qemu', qemu['name'])
-                        self._get_vm_snapshots(node['node'], qemu['vmid'], 'qemu', qemu['name'])
-
-                    self._apply_constructable(qemu["name"], self.inventory.get_host(qemu['name']).get_vars())
+            # get LXC containers and Qemu VMs for this node
+            lxc_objects = zip(itertools.repeat('lxc'), self._get_lxc_per_node(node['node']))
+            qemu_objects = zip(itertools.repeat('qemu'), self._get_qemu_per_node(node['node']))
+            for ittype, item in itertools.chain(lxc_objects, qemu_objects):
+                name = self._handle_item(node['node'], ittype, item)
+                if name is not None:
+                    hosts.append(name)
 
         # gather vm's in pools
-        for pool in self._get_pools():
-            if pool.get('poolid'):
-                pool_group = 'pool_' + pool['poolid']
-                pool_group = self.to_safe('%s%s' % (self.get_option('group_prefix'), pool_group.lower()))
-                self.inventory.add_group(pool_group)
-
-                for member in self._get_members_per_pool(pool['poolid']):
-                    if member.get('name'):
-                        if not member.get('template'):
-                            self.inventory.add_child(pool_group, member['name'])
+        self._populate_pool_groups(hosts)
 
     def parse(self, inventory, loader, path, cache=True):
         if not HAS_REQUESTS:
@@ -468,12 +498,16 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
         # read config from file, this sets 'options'
         self._read_config_data(path)
 
-        # get connection host
+        # read options
         self.proxmox_url = self.get_option('url').rstrip('/')
         self.proxmox_user = self.get_option('user')
         self.proxmox_password = self.get_option('password')
         self.cache_key = self.get_cache_key(path)
         self.use_cache = cache and self.get_option('cache')
+        self.host_filters = self.get_option('filters')
+        self.group_prefix = self.get_option('group_prefix')
+        self.facts_prefix = self.get_option('facts_prefix')
+        self.strict = self.get_option('strict')
 
         # actually populate inventory
         self._populate()

plugins/inventory/scaleway.py

@@ -23,6 +23,7 @@ DOCUMENTATION = r'''
         regions:
             description: Filter results on a specific Scaleway region.
             type: list
+            elements: string
             default:
                 - ams1
                 - par1
@@ -31,6 +32,13 @@ DOCUMENTATION = r'''
         tags:
             description: Filter results on a specific tag.
             type: list
+            elements: string
+        scw_profile:
+            description:
+            - The config profile to use in config file.
+            - By default uses the one specified as C(active_profile) in the config file, or falls back to C(default) if that is not defined.
+            type: string
+            version_added: 4.4.0
         oauth_token:
             description:
             - Scaleway OAuth token.
@@ -45,6 +53,7 @@ DOCUMENTATION = r'''
         hostnames:
             description: List of preference about what to use as an hostname.
             type: list
+            elements: string
             default:
                 - public_ipv4
             choices:
@@ -303,7 +312,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         if not oauth_token and os.path.exists(scw_config_path):
             with open(scw_config_path) as fh:
                 scw_config = yaml.safe_load(fh)
-                active_profile = scw_config.get('active_profile', 'default')
+                ansible_profile = self.get_option('scw_profile')
+
+                if ansible_profile:
+                    active_profile = ansible_profile
+                else:
+                    active_profile = scw_config.get('active_profile', 'default')
+
                 if active_profile == 'default':
                     oauth_token = scw_config.get('secret_key')
                 else:

plugins/inventory/xen_orchestra.py

@@ -62,17 +62,16 @@ DOCUMENTATION = '''
 
 EXAMPLES = '''
 # file must be named xen_orchestra.yaml or xen_orchestra.yml
-simple_config_file:
-    plugin: community.general.xen_orchestra
-    api_host: 192.168.1.255
-    user: xo
-    password: xo_pwd
-    validate_certs: true
-    use_ssl: true
-    groups:
-        kube_nodes: "'kube_node' in tags"
-    compose:
-        ansible_port: 2222
+plugin: community.general.xen_orchestra
+api_host: 192.168.1.255
+user: xo
+password: xo_pwd
+validate_certs: true
+use_ssl: true
+groups:
+    kube_nodes: "'kube_node' in tags"
+compose:
+    ansible_port: 2222
 
 '''
 

plugins/lookup/consul_kv.py

@@ -20,6 +20,7 @@ DOCUMENTATION = '''
       _raw:
         description: List of key(s) to retrieve.
         type: list
+        elements: string
       recurse:
         type: boolean
         description: If true, will retrieve all the values that have the given key as prefix.

plugins/lookup/credstash.py

@@ -17,11 +17,11 @@ DOCUMENTATION = '''
       _terms:
         description: term or list of terms to lookup in the credit store
         type: list
-        required: True
+        elements: string
+        required: true
       table:
         description: name of the credstash table to query
         default: 'credential-store'
-        required: True
       version:
         description: Credstash version
       region:

plugins/lookup/dnstxt.py

@@ -18,6 +18,7 @@ DOCUMENTATION = '''
         description: domain or list of domains to query TXT records from
         required: True
         type: list
+        elements: string
 '''
 
 EXAMPLES = """

plugins/lookup/passwordstore.py

@@ -14,6 +14,8 @@ DOCUMENTATION = '''
     description:
       - Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility.
         It also retrieves YAML style keys stored as multilines in the passwordfile.
+      - To avoid problems when accessing multiple secrets at once, add C(auto-expand-secmem) to
+        C(~/.gnupg/gpg-agent.conf). Where this is not possible, consider using I(lock=readwrite) instead.
     options:
       _terms:
         description: query key.
@@ -77,54 +79,89 @@ DOCUMENTATION = '''
           - warn
           - empty
           - create
+      lock:
+        description:
+          - How to synchronize operations.
+          - The default of C(write) only synchronizes write operations.
+          - C(readwrite) synchronizes all operations (including read). This makes sure that gpg-agent is never called in parallel.
+          - C(none) does not do any synchronization.
+        ini:
+          - section: passwordstore_lookup
+            key: lock
+        type: str
+        default: write
+        choices:
+          - readwrite
+          - write
+          - none
+        version_added: 4.5.0
+      locktimeout:
+        description:
+          - Lock timeout applied when I(lock) is not C(none).
+          - Time with a unit suffix, C(s), C(m), C(h) for seconds, minutes, and hours, respectively. For example, C(900s) equals C(15m).
+          - Correlates with C(pinentry-timeout) in C(~/.gnupg/gpg-agent.conf), see C(man gpg-agent) for details.
+        ini:
+          - section: passwordstore_lookup
+            key: locktimeout
+        type: str
+        default: 15m
+        version_added: 4.5.0
 '''
 EXAMPLES = """
-# Debug is used for examples, BAD IDEA to show passwords on screen
-- name: Basic lookup. Fails if example/test doesn't exist
-  ansible.builtin.debug:
-    msg: "{{ lookup('community.general.passwordstore', 'example/test')}}"
+ansible.cfg: |
+  [passwordstore_lookup]
+  lock=readwrite
+  locktimeout=45s
 
-- name: Basic lookup. Warns if example/test does not exist and returns empty string
-  ansible.builtin.debug:
-    msg: "{{ lookup('community.general.passwordstore', 'example/test missing=warn')}}"
+playbook.yml: |
+  ---
 
-- name: Create pass with random 16 character password. If password exists just give the password
-  ansible.builtin.debug:
-    var: mypassword
-  vars:
-    mypassword: "{{ lookup('community.general.passwordstore', 'example/test create=true')}}"
+  # Debug is used for examples, BAD IDEA to show passwords on screen
+  - name: Basic lookup. Fails if example/test does not exist
+    ansible.builtin.debug:
+      msg: "{{ lookup('community.general.passwordstore', 'example/test')}}"
 
-- name: Create pass with random 16 character password. If password exists just give the password
-  ansible.builtin.debug:
-    var: mypassword
-  vars:
-    mypassword: "{{ lookup('community.general.passwordstore', 'example/test missing=create')}}"
+  - name: Basic lookup. Warns if example/test does not exist and returns empty string
+    ansible.builtin.debug:
+      msg: "{{ lookup('community.general.passwordstore', 'example/test missing=warn')}}"
 
-- name: Prints 'abc' if example/test does not exist, just give the password otherwise
-  ansible.builtin.debug:
-    var: mypassword
-  vars:
-    mypassword: "{{ lookup('community.general.passwordstore', 'example/test missing=empty') | default('abc', true) }}"
+  - name: Create pass with random 16 character password. If password exists just give the password
+    ansible.builtin.debug:
+      var: mypassword
+    vars:
+      mypassword: "{{ lookup('community.general.passwordstore', 'example/test create=true')}}"
 
-- name: Different size password
-  ansible.builtin.debug:
-    msg: "{{ lookup('community.general.passwordstore', 'example/test create=true length=42')}}"
+  - name: Create pass with random 16 character password. If password exists just give the password
+    ansible.builtin.debug:
+      var: mypassword
+    vars:
+      mypassword: "{{ lookup('community.general.passwordstore', 'example/test missing=create')}}"
 
-- name: Create password and overwrite the password if it exists. As a bonus, this module includes the old password inside the pass file
-  ansible.builtin.debug:
-    msg: "{{ lookup('community.general.passwordstore', 'example/test create=true overwrite=true')}}"
+  - name: Prints 'abc' if example/test does not exist, just give the password otherwise
+    ansible.builtin.debug:
+      var: mypassword
+    vars:
+      mypassword: "{{ lookup('community.general.passwordstore', 'example/test missing=empty') | default('abc', true) }}"
 
-- name: Create an alphanumeric password
-  ansible.builtin.debug:
-    msg: "{{ lookup('community.general.passwordstore', 'example/test create=true nosymbols=true') }}"
+  - name: Different size password
+    ansible.builtin.debug:
+      msg: "{{ lookup('community.general.passwordstore', 'example/test create=true length=42')}}"
 
-- name: Return the value for user in the KV pair user, username
-  ansible.builtin.debug:
-    msg: "{{ lookup('community.general.passwordstore', 'example/test subkey=user')}}"
+  - name: Create password and overwrite the password if it exists. As a bonus, this module includes the old password inside the pass file
+    ansible.builtin.debug:
+      msg: "{{ lookup('community.general.passwordstore', 'example/test create=true overwrite=true')}}"
 
-- name: Return the entire password file content
-  ansible.builtin.set_fact:
-    passfilecontent: "{{ lookup('community.general.passwordstore', 'example/test returnall=true')}}"
+  - name: Create an alphanumeric password
+    ansible.builtin.debug:
+      msg: "{{ lookup('community.general.passwordstore', 'example/test create=true nosymbols=true') }}"
+
+  - name: Return the value for user in the KV pair user, username
+    ansible.builtin.debug:
+      msg: "{{ lookup('community.general.passwordstore', 'example/test subkey=user')}}"
+
+  - name: Return the entire password file content
+    ansible.builtin.set_fact:
+      passfilecontent: "{{ lookup('community.general.passwordstore', 'example/test returnall=true')}}"
 """
 
 RETURN = """
@@ -135,13 +172,15 @@ _raw:
   elements: str
 """
 
+from contextlib import contextmanager
 import os
+import re
 import subprocess
 import time
 import yaml
 
-
 from ansible.errors import AnsibleError, AnsibleAssertionError
+from ansible.module_utils.common.file import FileLock
 from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible.module_utils.parsing.convert_bool import boolean
 from ansible.utils.display import Display
@@ -154,6 +193,7 @@ display = Display()
 
 # backhacked check_output with input for python 2.7
 # http://stackoverflow.com/questions/10103551/passing-data-to-subprocess-check-output
+# note: contains special logic for calling 'pass', so not a drop-in replacement for check_output
 def check_output2(*popenargs, **kwargs):
     if 'stdout' in kwargs:
         raise ValueError('stdout argument not allowed, it will be overridden.')
@@ -175,9 +215,10 @@ def check_output2(*popenargs, **kwargs):
         process.wait()
         raise
     retcode = process.poll()
-    if retcode != 0 or \
-            b'encryption failed: Unusable public key' in b_out or \
-            b'encryption failed: Unusable public key' in b_err:
+    if retcode == 0 and (b'encryption failed: Unusable public key' in b_out or
+                         b'encryption failed: Unusable public key' in b_err):
+        retcode = 78  # os.EX_CONFIG
+    if retcode != 0:
         cmd = kwargs.get("args")
         if cmd is None:
             cmd = popenargs[0]
@@ -227,13 +268,13 @@ class LookupModule(LookupBase):
 
             # Collect pass environment variables from the plugin's parameters.
             self.env = os.environ.copy()
+            self.env['LANGUAGE'] = 'C'  # make sure to get errors in English as required by check_output2
 
-            # Set PASSWORD_STORE_DIR if directory is set
-            if self.paramvals['directory']:
-                if os.path.isdir(self.paramvals['directory']):
-                    self.env['PASSWORD_STORE_DIR'] = self.paramvals['directory']
-                else:
-                    raise AnsibleError('Passwordstore directory \'{0}\' does not exist'.format(self.paramvals['directory']))
+            # Set PASSWORD_STORE_DIR
+            if os.path.isdir(self.paramvals['directory']):
+                self.env['PASSWORD_STORE_DIR'] = self.paramvals['directory']
+            else:
+                raise AnsibleError('Passwordstore directory \'{0}\' does not exist'.format(self.paramvals['directory']))
 
             # Set PASSWORD_STORE_UMASK if umask is set
             if 'umask' in self.paramvals:
@@ -261,19 +302,20 @@ class LookupModule(LookupBase):
                     if ':' in line:
                         name, value = line.split(':', 1)
                         self.passdict[name.strip()] = value.strip()
+            if os.path.isfile(os.path.join(self.paramvals['directory'], self.passname + ".gpg")):
+                # Only accept password as found, if there a .gpg file for it (might be a tree node otherwise)
+                return True
         except (subprocess.CalledProcessError) as e:
-            if e.returncode != 0 and 'not in the password store' in e.output:
-                # if pass returns 1 and return string contains 'is not in the password store.'
-                # We need to determine if this is valid or Error.
-                if self.paramvals['missing'] == 'error':
-                    raise AnsibleError('passwordstore: passname {0} not found and missing=error is set'.format(self.passname))
-                else:
-                    if self.paramvals['missing'] == 'warn':
-                        display.warning('passwordstore: passname {0} not found'.format(self.passname))
-                    return False
-            else:
+            # 'not in password store' is the expected error if a password wasn't found
+            if 'not in the password store' not in e.output:
                 raise AnsibleError(e)
-        return True
+
+        if self.paramvals['missing'] == 'error':
+            raise AnsibleError('passwordstore: passname {0} not found and missing=error is set'.format(self.passname))
+        elif self.paramvals['missing'] == 'warn':
+            display.warning('passwordstore: passname {0} not found'.format(self.passname))
+
+        return False
 
     def get_newpass(self):
         if self.paramvals['nosymbols']:
@@ -325,11 +367,30 @@ class LookupModule(LookupBase):
             else:
                 return None
 
-    def run(self, terms, variables, **kwargs):
-        result = []
+    @contextmanager
+    def opt_lock(self, type):
+        if self.get_option('lock') == type:
+            tmpdir = os.environ.get('TMPDIR', '/tmp')
+            lockfile = os.path.join(tmpdir, '.passwordstore.lock')
+            with FileLock().lock_file(lockfile, tmpdir, self.lock_timeout):
+                self.locked = type
+                yield
+            self.locked = None
+        else:
+            yield
+
+    def setup(self, variables):
+        self.locked = None
+        timeout = self.get_option('locktimeout')
+        if not re.match('^[0-9]+[smh]$', timeout):
+            raise AnsibleError("{0} is not a correct value for locktimeout".format(timeout))
+        unit_to_seconds = {"s": 1, "m": 60, "h": 3600}
+        self.lock_timeout = int(timeout[:-1]) * unit_to_seconds[timeout[-1]]
         self.paramvals = {
             'subkey': 'password',
-            'directory': variables.get('passwordstore'),
+            'directory': variables.get('passwordstore', os.environ.get(
+                                       'PASSWORD_STORE_DIR',
+                                       os.path.expanduser('~/.password-store'))),
             'create': False,
             'returnall': False,
             'overwrite': False,
@@ -340,17 +401,27 @@ class LookupModule(LookupBase):
             'missing': 'error',
         }
 
+    def run(self, terms, variables, **kwargs):
+        self.setup(variables)
+        result = []
+
         for term in terms:
             self.parse_params(term)   # parse the input into paramvals
-            if self.check_pass():     # password exists
-                if self.paramvals['overwrite'] and self.paramvals['subkey'] == 'password':
-                    result.append(self.update_password())
-                else:
-                    result.append(self.get_passresult())
-            else:                     # password does not exist
-                if self.paramvals['missing'] == 'create':
-                    result.append(self.generate_password())
-                else:
-                    result.append(None)
+            with self.opt_lock('readwrite'):
+                if self.check_pass():     # password exists
+                    if self.paramvals['overwrite'] and self.paramvals['subkey'] == 'password':
+                        with self.opt_lock('write'):
+                            result.append(self.update_password())
+                    else:
+                        result.append(self.get_passresult())
+                else:                     # password does not exist
+                    if self.paramvals['missing'] == 'create':
+                        with self.opt_lock('write'):
+                            if self.locked == 'write' and self.check_pass():  # lookup password again if under write lock
+                                result.append(self.get_passresult())
+                            else:
+                                result.append(self.generate_password())
+                    else:
+                        result.append(None)
 
         return result

plugins/lookup/tss.py

@@ -14,6 +14,10 @@ description:
     - Uses the Thycotic Secret Server Python SDK to get Secrets from Secret
       Server using token authentication with I(username) and I(password) on
       the REST API at I(base_url).
+    - When using self-signed certificates the environment variable
+      C(REQUESTS_CA_BUNDLE) can be set to a file containing the trusted certificates
+      (in C(.pem) format).
+    - For example, C(export REQUESTS_CA_BUNDLE='/etc/ssl/certs/ca-bundle.trust.crt').
 requirements:
     - python-tss-sdk - https://pypi.org/project/python-tss-sdk/
 options:

plugins/module_utils/identity/keycloak/keycloak.py

@@ -102,6 +102,7 @@ def keycloak_argument_spec():
         auth_username=dict(type='str', aliases=['username']),
         auth_password=dict(type='str', aliases=['password'], no_log=True),
         validate_certs=dict(type='bool', default=True),
+        connection_timeout=dict(type='int', default=10),
         token=dict(type='str', no_log=True),
     )
 
@@ -134,6 +135,7 @@ def get_token(module_params):
         auth_username = module_params.get('auth_username')
         auth_password = module_params.get('auth_password')
         client_secret = module_params.get('auth_client_secret')
+        connection_timeout = module_params.get('connection_timeout')
         auth_url = URL_TOKEN.format(url=base_url, realm=auth_realm)
         temp_payload = {
             'grant_type': 'password',
@@ -147,7 +149,7 @@ def get_token(module_params):
             (k, v) for k, v in temp_payload.items() if v is not None)
         try:
             r = json.loads(to_native(open_url(auth_url, method='POST',
-                                              validate_certs=validate_certs,
+                                              validate_certs=validate_certs, timeout=connection_timeout,
                                               data=urlencode(payload)).read()))
         except ValueError as e:
             raise KeycloakError(
@@ -229,6 +231,7 @@ class KeycloakAPI(object):
         self.module = module
         self.baseurl = self.module.params.get('auth_keycloak_url')
         self.validate_certs = self.module.params.get('validate_certs')
+        self.connection_timeout = self.module.params.get('connection_timeout')
         self.restheaders = connection_header
 
     def get_realm_info_by_id(self, realm='master'):
@@ -240,7 +243,7 @@ class KeycloakAPI(object):
         realm_info_url = URL_REALM_INFO.format(url=self.baseurl, realm=realm)
 
         try:
-            return json.loads(to_native(open_url(realm_info_url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(realm_info_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
 
         except HTTPError as e:
@@ -265,7 +268,7 @@ class KeycloakAPI(object):
         realm_url = URL_REALM.format(url=self.baseurl, realm=realm)
 
         try:
-            return json.loads(to_native(open_url(realm_url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(realm_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
 
         except HTTPError as e:
@@ -290,7 +293,7 @@ class KeycloakAPI(object):
         realm_url = URL_REALM.format(url=self.baseurl, realm=realm)
 
         try:
-            return open_url(realm_url, method='PUT', headers=self.restheaders,
+            return open_url(realm_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(realmrep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not update realm %s: %s' % (realm, str(e)),
@@ -304,7 +307,7 @@ class KeycloakAPI(object):
         realm_url = URL_REALMS.format(url=self.baseurl)
 
         try:
-            return open_url(realm_url, method='POST', headers=self.restheaders,
+            return open_url(realm_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(realmrep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not create realm %s: %s' % (realmrep['id'], str(e)),
@@ -319,7 +322,7 @@ class KeycloakAPI(object):
         realm_url = URL_REALM.format(url=self.baseurl, realm=realm)
 
         try:
-            return open_url(realm_url, method='DELETE', headers=self.restheaders,
+            return open_url(realm_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not delete realm %s: %s' % (realm, str(e)),
@@ -337,7 +340,7 @@ class KeycloakAPI(object):
             clientlist_url += '?clientId=%s' % filter
 
         try:
-            return json.loads(to_native(open_url(clientlist_url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(clientlist_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except ValueError as e:
             self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of clients for realm %s: %s'
@@ -368,7 +371,7 @@ class KeycloakAPI(object):
         client_url = URL_CLIENT.format(url=self.baseurl, realm=realm, id=id)
 
         try:
-            return json.loads(to_native(open_url(client_url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(client_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
 
         except HTTPError as e:
@@ -407,7 +410,7 @@ class KeycloakAPI(object):
         client_url = URL_CLIENT.format(url=self.baseurl, realm=realm, id=id)
 
         try:
-            return open_url(client_url, method='PUT', headers=self.restheaders,
+            return open_url(client_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(clientrep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not update client %s in realm %s: %s'
@@ -422,7 +425,7 @@ class KeycloakAPI(object):
         client_url = URL_CLIENTS.format(url=self.baseurl, realm=realm)
 
         try:
-            return open_url(client_url, method='POST', headers=self.restheaders,
+            return open_url(client_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(clientrep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not create client %s in realm %s: %s'
@@ -438,7 +441,7 @@ class KeycloakAPI(object):
         client_url = URL_CLIENT.format(url=self.baseurl, realm=realm, id=id)
 
         try:
-            return open_url(client_url, method='DELETE', headers=self.restheaders,
+            return open_url(client_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not delete client %s in realm %s: %s'
@@ -453,7 +456,7 @@ class KeycloakAPI(object):
         """
         client_roles_url = URL_CLIENT_ROLES.format(url=self.baseurl, realm=realm, id=cid)
         try:
-            return json.loads(to_native(open_url(client_roles_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(client_roles_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except Exception as e:
             self.module.fail_json(msg="Could not fetch rolemappings for client %s in realm %s: %s"
@@ -485,7 +488,7 @@ class KeycloakAPI(object):
         """
         rolemappings_url = URL_CLIENT_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=gid, client=cid)
         try:
-            rolemappings = json.loads(to_native(open_url(rolemappings_url, method="GET", headers=self.restheaders,
+            rolemappings = json.loads(to_native(open_url(rolemappings_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                          validate_certs=self.validate_certs).read()))
             for role in rolemappings:
                 if rid == role['id']:
@@ -505,7 +508,7 @@ class KeycloakAPI(object):
         """
         available_rolemappings_url = URL_CLIENT_ROLEMAPPINGS_AVAILABLE.format(url=self.baseurl, realm=realm, id=gid, client=cid)
         try:
-            return json.loads(to_native(open_url(available_rolemappings_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(available_rolemappings_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except Exception as e:
             self.module.fail_json(msg="Could not fetch available rolemappings for client %s in group %s, realm %s: %s"
@@ -521,7 +524,7 @@ class KeycloakAPI(object):
         """
         available_rolemappings_url = URL_CLIENT_ROLEMAPPINGS_COMPOSITE.format(url=self.baseurl, realm=realm, id=gid, client=cid)
         try:
-            return json.loads(to_native(open_url(available_rolemappings_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(available_rolemappings_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except Exception as e:
             self.module.fail_json(msg="Could not fetch available rolemappings for client %s in group %s, realm %s: %s"
@@ -538,7 +541,8 @@ class KeycloakAPI(object):
         """
         available_rolemappings_url = URL_CLIENT_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=gid, client=cid)
         try:
-            open_url(available_rolemappings_url, method="POST", headers=self.restheaders, data=json.dumps(role_rep), validate_certs=self.validate_certs)
+            open_url(available_rolemappings_url, method="POST", headers=self.restheaders, data=json.dumps(role_rep),
+                     validate_certs=self.validate_certs, timeout=self.connection_timeout)
         except Exception as e:
             self.module.fail_json(msg="Could not fetch available rolemappings for client %s in group %s, realm %s: %s"
                                       % (cid, gid, realm, str(e)))
@@ -554,7 +558,8 @@ class KeycloakAPI(object):
         """
         available_rolemappings_url = URL_CLIENT_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=gid, client=cid)
         try:
-            open_url(available_rolemappings_url, method="DELETE", headers=self.restheaders, validate_certs=self.validate_certs)
+            open_url(available_rolemappings_url, method="DELETE", headers=self.restheaders,
+                     validate_certs=self.validate_certs, timeout=self.connection_timeout)
         except Exception as e:
             self.module.fail_json(msg="Could not delete available rolemappings for client %s in group %s, realm %s: %s"
                                       % (cid, gid, realm, str(e)))
@@ -568,7 +573,7 @@ class KeycloakAPI(object):
         url = URL_CLIENTTEMPLATES.format(url=self.baseurl, realm=realm)
 
         try:
-            return json.loads(to_native(open_url(url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except ValueError as e:
             self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of client templates for realm %s: %s'
@@ -587,7 +592,7 @@ class KeycloakAPI(object):
         url = URL_CLIENTTEMPLATE.format(url=self.baseurl, id=id, realm=realm)
 
         try:
-            return json.loads(to_native(open_url(url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except ValueError as e:
             self.module.fail_json(msg='API returned incorrect JSON when trying to obtain client templates %s for realm %s: %s'
@@ -633,7 +638,7 @@ class KeycloakAPI(object):
         url = URL_CLIENTTEMPLATE.format(url=self.baseurl, realm=realm, id=id)
 
         try:
-            return open_url(url, method='PUT', headers=self.restheaders,
+            return open_url(url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(clienttrep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not update client template %s in realm %s: %s'
@@ -648,7 +653,7 @@ class KeycloakAPI(object):
         url = URL_CLIENTTEMPLATES.format(url=self.baseurl, realm=realm)
 
         try:
-            return open_url(url, method='POST', headers=self.restheaders,
+            return open_url(url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(clienttrep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not create client template %s in realm %s: %s'
@@ -664,7 +669,7 @@ class KeycloakAPI(object):
         url = URL_CLIENTTEMPLATE.format(url=self.baseurl, realm=realm, id=id)
 
         try:
-            return open_url(url, method='DELETE', headers=self.restheaders,
+            return open_url(url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not delete client template %s in realm %s: %s'
@@ -681,7 +686,7 @@ class KeycloakAPI(object):
         """
         clientscopes_url = URL_CLIENTSCOPES.format(url=self.baseurl, realm=realm)
         try:
-            return json.loads(to_native(open_url(clientscopes_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(clientscopes_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except Exception as e:
             self.module.fail_json(msg="Could not fetch list of clientscopes in realm %s: %s"
@@ -698,7 +703,7 @@ class KeycloakAPI(object):
         """
         clientscope_url = URL_CLIENTSCOPE.format(url=self.baseurl, realm=realm, id=cid)
         try:
-            return json.loads(to_native(open_url(clientscope_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(clientscope_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
 
         except HTTPError as e:
@@ -743,7 +748,7 @@ class KeycloakAPI(object):
         """
         clientscopes_url = URL_CLIENTSCOPES.format(url=self.baseurl, realm=realm)
         try:
-            return open_url(clientscopes_url, method='POST', headers=self.restheaders,
+            return open_url(clientscopes_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(clientscoperep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg="Could not create clientscope %s in realm %s: %s"
@@ -758,7 +763,7 @@ class KeycloakAPI(object):
         clientscope_url = URL_CLIENTSCOPE.format(url=self.baseurl, realm=realm, id=clientscoperep['id'])
 
         try:
-            return open_url(clientscope_url, method='PUT', headers=self.restheaders,
+            return open_url(clientscope_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(clientscoperep), validate_certs=self.validate_certs)
 
         except Exception as e:
@@ -796,7 +801,7 @@ class KeycloakAPI(object):
         # should have a good cid by here.
         clientscope_url = URL_CLIENTSCOPE.format(realm=realm, id=cid, url=self.baseurl)
         try:
-            return open_url(clientscope_url, method='DELETE', headers=self.restheaders,
+            return open_url(clientscope_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
 
         except Exception as e:
@@ -814,7 +819,7 @@ class KeycloakAPI(object):
         """
         protocolmappers_url = URL_CLIENTSCOPE_PROTOCOLMAPPERS.format(id=cid, url=self.baseurl, realm=realm)
         try:
-            return json.loads(to_native(open_url(protocolmappers_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(protocolmappers_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except Exception as e:
             self.module.fail_json(msg="Could not fetch list of protocolmappers in realm %s: %s"
@@ -833,7 +838,7 @@ class KeycloakAPI(object):
         """
         protocolmapper_url = URL_CLIENTSCOPE_PROTOCOLMAPPER.format(url=self.baseurl, realm=realm, id=cid, mapper_id=pid)
         try:
-            return json.loads(to_native(open_url(protocolmapper_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(protocolmapper_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
 
         except HTTPError as e:
@@ -880,7 +885,7 @@ class KeycloakAPI(object):
         """
         protocolmappers_url = URL_CLIENTSCOPE_PROTOCOLMAPPERS.format(url=self.baseurl, id=cid, realm=realm)
         try:
-            return open_url(protocolmappers_url, method='POST', headers=self.restheaders,
+            return open_url(protocolmappers_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(mapper_rep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg="Could not create protocolmapper %s in realm %s: %s"
@@ -896,7 +901,7 @@ class KeycloakAPI(object):
         protocolmapper_url = URL_CLIENTSCOPE_PROTOCOLMAPPER.format(url=self.baseurl, realm=realm, id=cid, mapper_id=mapper_rep['id'])
 
         try:
-            return open_url(protocolmapper_url, method='PUT', headers=self.restheaders,
+            return open_url(protocolmapper_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(mapper_rep), validate_certs=self.validate_certs)
 
         except Exception as e:
@@ -913,7 +918,7 @@ class KeycloakAPI(object):
         """
         groups_url = URL_GROUPS.format(url=self.baseurl, realm=realm)
         try:
-            return json.loads(to_native(open_url(groups_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(groups_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except Exception as e:
             self.module.fail_json(msg="Could not fetch list of groups in realm %s: %s"
@@ -930,7 +935,7 @@ class KeycloakAPI(object):
         """
         groups_url = URL_GROUP.format(url=self.baseurl, realm=realm, groupid=gid)
         try:
-            return json.loads(to_native(open_url(groups_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(groups_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
 
         except HTTPError as e:
@@ -976,7 +981,7 @@ class KeycloakAPI(object):
         """
         groups_url = URL_GROUPS.format(url=self.baseurl, realm=realm)
         try:
-            return open_url(groups_url, method='POST', headers=self.restheaders,
+            return open_url(groups_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(grouprep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg="Could not create group %s in realm %s: %s"
@@ -991,7 +996,7 @@ class KeycloakAPI(object):
         group_url = URL_GROUP.format(url=self.baseurl, realm=realm, groupid=grouprep['id'])
 
         try:
-            return open_url(group_url, method='PUT', headers=self.restheaders,
+            return open_url(group_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(grouprep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not update group %s in realm %s: %s'
@@ -1028,7 +1033,7 @@ class KeycloakAPI(object):
         # should have a good groupid by here.
         group_url = URL_GROUP.format(realm=realm, groupid=groupid, url=self.baseurl)
         try:
-            return open_url(group_url, method='DELETE', headers=self.restheaders,
+            return open_url(group_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg="Unable to delete group %s: %s" % (groupid, str(e)))
@@ -1041,7 +1046,7 @@ class KeycloakAPI(object):
         """
         rolelist_url = URL_REALM_ROLES.format(url=self.baseurl, realm=realm)
         try:
-            return json.loads(to_native(open_url(rolelist_url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(rolelist_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except ValueError as e:
             self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of roles for realm %s: %s'
@@ -1059,7 +1064,7 @@ class KeycloakAPI(object):
         """
         role_url = URL_REALM_ROLE.format(url=self.baseurl, realm=realm, name=quote(name))
         try:
-            return json.loads(to_native(open_url(role_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(role_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except HTTPError as e:
             if e.code == 404:
@@ -1079,7 +1084,7 @@ class KeycloakAPI(object):
         """
         roles_url = URL_REALM_ROLES.format(url=self.baseurl, realm=realm)
         try:
-            return open_url(roles_url, method='POST', headers=self.restheaders,
+            return open_url(roles_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(rolerep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not create role %s in realm %s: %s'
@@ -1093,7 +1098,7 @@ class KeycloakAPI(object):
         """
         role_url = URL_REALM_ROLE.format(url=self.baseurl, realm=realm, name=quote(rolerep['name']))
         try:
-            return open_url(role_url, method='PUT', headers=self.restheaders,
+            return open_url(role_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(rolerep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not update role %s in realm %s: %s'
@@ -1107,7 +1112,7 @@ class KeycloakAPI(object):
         """
         role_url = URL_REALM_ROLE.format(url=self.baseurl, realm=realm, name=quote(name))
         try:
-            return open_url(role_url, method='DELETE', headers=self.restheaders,
+            return open_url(role_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Unable to delete role %s in realm %s: %s'
@@ -1126,7 +1131,7 @@ class KeycloakAPI(object):
                                       % (clientid, realm))
         rolelist_url = URL_CLIENT_ROLES.format(url=self.baseurl, realm=realm, id=cid)
         try:
-            return json.loads(to_native(open_url(rolelist_url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(rolelist_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except ValueError as e:
             self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of roles for client %s in realm %s: %s'
@@ -1150,7 +1155,7 @@ class KeycloakAPI(object):
                                       % (clientid, realm))
         role_url = URL_CLIENT_ROLE.format(url=self.baseurl, realm=realm, id=cid, name=quote(name))
         try:
-            return json.loads(to_native(open_url(role_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(role_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except HTTPError as e:
             if e.code == 404:
@@ -1176,7 +1181,7 @@ class KeycloakAPI(object):
                                       % (clientid, realm))
         roles_url = URL_CLIENT_ROLES.format(url=self.baseurl, realm=realm, id=cid)
         try:
-            return open_url(roles_url, method='POST', headers=self.restheaders,
+            return open_url(roles_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(rolerep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not create role %s for client %s in realm %s: %s'
@@ -1196,7 +1201,7 @@ class KeycloakAPI(object):
                                       % (clientid, realm))
         role_url = URL_CLIENT_ROLE.format(url=self.baseurl, realm=realm, id=cid, name=quote(rolerep['name']))
         try:
-            return open_url(role_url, method='PUT', headers=self.restheaders,
+            return open_url(role_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(rolerep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not update role %s for client %s in realm %s: %s'
@@ -1215,7 +1220,7 @@ class KeycloakAPI(object):
                                       % (clientid, realm))
         role_url = URL_CLIENT_ROLE.format(url=self.baseurl, realm=realm, id=cid, name=quote(name))
         try:
-            return open_url(role_url, method='DELETE', headers=self.restheaders,
+            return open_url(role_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Unable to delete role %s for client %s in realm %s: %s'
@@ -1231,7 +1236,8 @@ class KeycloakAPI(object):
         try:
             authentication_flow = {}
             # Check if the authentication flow exists on the Keycloak serveraders
-            authentications = json.load(open_url(URL_AUTHENTICATION_FLOWS.format(url=self.baseurl, realm=realm), method='GET', headers=self.restheaders))
+            authentications = json.load(open_url(URL_AUTHENTICATION_FLOWS.format(url=self.baseurl, realm=realm), method='GET',
+                                                 headers=self.restheaders, timeout=self.connection_timeout))
             for authentication in authentications:
                 if authentication["alias"] == alias:
                     authentication_flow = authentication
@@ -1250,7 +1256,7 @@ class KeycloakAPI(object):
         flow_url = URL_AUTHENTICATION_FLOW.format(url=self.baseurl, realm=realm, id=id)
 
         try:
-            return open_url(flow_url, method='DELETE', headers=self.restheaders,
+            return open_url(flow_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not delete authentication flow %s in realm %s: %s'
@@ -1274,13 +1280,15 @@ class KeycloakAPI(object):
                     copyfrom=quote(config["copyFrom"])),
                 method='POST',
                 headers=self.restheaders,
-                data=json.dumps(new_name))
+                data=json.dumps(new_name),
+                timeout=self.connection_timeout)
             flow_list = json.load(
                 open_url(
                     URL_AUTHENTICATION_FLOWS.format(url=self.baseurl,
                                                     realm=realm),
                     method='GET',
-                    headers=self.restheaders))
+                    headers=self.restheaders,
+                    timeout=self.connection_timeout))
             for flow in flow_list:
                 if flow["alias"] == config["alias"]:
                     return flow
@@ -1309,14 +1317,16 @@ class KeycloakAPI(object):
                     realm=realm),
                 method='POST',
                 headers=self.restheaders,
-                data=json.dumps(new_flow))
+                data=json.dumps(new_flow),
+                timeout=self.connection_timeout)
             flow_list = json.load(
                 open_url(
                     URL_AUTHENTICATION_FLOWS.format(
                         url=self.baseurl,
                         realm=realm),
                     method='GET',
-                    headers=self.restheaders))
+                    headers=self.restheaders,
+                    timeout=self.connection_timeout))
             for flow in flow_list:
                 if flow["alias"] == config["alias"]:
                     return flow
@@ -1340,7 +1350,8 @@ class KeycloakAPI(object):
                     flowalias=quote(flowAlias)),
                 method='PUT',
                 headers=self.restheaders,
-                data=json.dumps(updatedExec))
+                data=json.dumps(updatedExec),
+                timeout=self.connection_timeout)
         except Exception as e:
             self.module.fail_json(msg="Unable to update executions %s: %s" % (updatedExec, str(e)))
 
@@ -1359,7 +1370,8 @@ class KeycloakAPI(object):
                     id=executionId),
                 method='POST',
                 headers=self.restheaders,
-                data=json.dumps(authenticationConfig))
+                data=json.dumps(authenticationConfig),
+                timeout=self.connection_timeout)
         except Exception as e:
             self.module.fail_json(msg="Unable to add authenticationConfig %s: %s" % (executionId, str(e)))
 
@@ -1382,7 +1394,8 @@ class KeycloakAPI(object):
                     flowalias=quote(flowAlias)),
                 method='POST',
                 headers=self.restheaders,
-                data=json.dumps(newSubFlow))
+                data=json.dumps(newSubFlow),
+                timeout=self.connection_timeout)
         except Exception as e:
             self.module.fail_json(msg="Unable to create new subflow %s: %s" % (subflowName, str(e)))
 
@@ -1404,7 +1417,8 @@ class KeycloakAPI(object):
                     flowalias=quote(flowAlias)),
                 method='POST',
                 headers=self.restheaders,
-                data=json.dumps(newExec))
+                data=json.dumps(newExec),
+                timeout=self.connection_timeout)
         except Exception as e:
             self.module.fail_json(msg="Unable to create new execution %s: %s" % (execution["provider"], str(e)))
 
@@ -1425,7 +1439,8 @@ class KeycloakAPI(object):
                             realm=realm,
                             id=executionId),
                         method='POST',
-                        headers=self.restheaders)
+                        headers=self.restheaders,
+                        timeout=self.connection_timeout)
             elif diff < 0:
                 for i in range(-diff):
                     open_url(
@@ -1434,7 +1449,8 @@ class KeycloakAPI(object):
                             realm=realm,
                             id=executionId),
                         method='POST',
-                        headers=self.restheaders)
+                        headers=self.restheaders,
+                        timeout=self.connection_timeout)
         except Exception as e:
             self.module.fail_json(msg="Unable to change execution priority %s: %s" % (executionId, str(e)))
 
@@ -1454,7 +1470,8 @@ class KeycloakAPI(object):
                         realm=realm,
                         flowalias=quote(config["alias"])),
                     method='GET',
-                    headers=self.restheaders))
+                    headers=self.restheaders,
+                    timeout=self.connection_timeout))
             for execution in executions:
                 if "authenticationConfig" in execution:
                     execConfigId = execution["authenticationConfig"]
@@ -1465,7 +1482,8 @@ class KeycloakAPI(object):
                                 realm=realm,
                                 id=execConfigId),
                             method='GET',
-                            headers=self.restheaders))
+                            headers=self.restheaders,
+                            timeout=self.connection_timeout))
                     execution["authenticationConfig"] = execConfig
             return executions
         except Exception as e:
@@ -1479,7 +1497,7 @@ class KeycloakAPI(object):
         """
         idps_url = URL_IDENTITY_PROVIDERS.format(url=self.baseurl, realm=realm)
         try:
-            return json.loads(to_native(open_url(idps_url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(idps_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except ValueError as e:
             self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of identity providers for realm %s: %s'
@@ -1496,7 +1514,7 @@ class KeycloakAPI(object):
         """
         idp_url = URL_IDENTITY_PROVIDER.format(url=self.baseurl, realm=realm, alias=alias)
         try:
-            return json.loads(to_native(open_url(idp_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(idp_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except HTTPError as e:
             if e.code == 404:
@@ -1516,7 +1534,7 @@ class KeycloakAPI(object):
         """
         idps_url = URL_IDENTITY_PROVIDERS.format(url=self.baseurl, realm=realm)
         try:
-            return open_url(idps_url, method='POST', headers=self.restheaders,
+            return open_url(idps_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(idprep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not create identity provider %s in realm %s: %s'
@@ -1530,7 +1548,7 @@ class KeycloakAPI(object):
         """
         idp_url = URL_IDENTITY_PROVIDER.format(url=self.baseurl, realm=realm, alias=idprep['alias'])
         try:
-            return open_url(idp_url, method='PUT', headers=self.restheaders,
+            return open_url(idp_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(idprep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not update identity provider %s in realm %s: %s'
@@ -1543,7 +1561,7 @@ class KeycloakAPI(object):
         """
         idp_url = URL_IDENTITY_PROVIDER.format(url=self.baseurl, realm=realm, alias=alias)
         try:
-            return open_url(idp_url, method='DELETE', headers=self.restheaders,
+            return open_url(idp_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Unable to delete identity provider %s in realm %s: %s'
@@ -1557,7 +1575,7 @@ class KeycloakAPI(object):
         """
         mappers_url = URL_IDENTITY_PROVIDER_MAPPERS.format(url=self.baseurl, realm=realm, alias=alias)
         try:
-            return json.loads(to_native(open_url(mappers_url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(mappers_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except ValueError as e:
             self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of identity provider mappers for idp %s in realm %s: %s'
@@ -1575,7 +1593,7 @@ class KeycloakAPI(object):
         """
         mapper_url = URL_IDENTITY_PROVIDER_MAPPER.format(url=self.baseurl, realm=realm, alias=alias, id=mid)
         try:
-            return json.loads(to_native(open_url(mapper_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(mapper_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except HTTPError as e:
             if e.code == 404:
@@ -1596,7 +1614,7 @@ class KeycloakAPI(object):
         """
         mappers_url = URL_IDENTITY_PROVIDER_MAPPERS.format(url=self.baseurl, realm=realm, alias=alias)
         try:
-            return open_url(mappers_url, method='POST', headers=self.restheaders,
+            return open_url(mappers_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(mapper), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not create identity provider mapper %s for idp %s in realm %s: %s'
@@ -1611,7 +1629,7 @@ class KeycloakAPI(object):
         """
         mapper_url = URL_IDENTITY_PROVIDER_MAPPER.format(url=self.baseurl, realm=realm, alias=alias, id=mapper['id'])
         try:
-            return open_url(mapper_url, method='PUT', headers=self.restheaders,
+            return open_url(mapper_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(mapper), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not update mapper %s for identity provider %s in realm %s: %s'
@@ -1625,7 +1643,7 @@ class KeycloakAPI(object):
         """
         mapper_url = URL_IDENTITY_PROVIDER_MAPPER.format(url=self.baseurl, realm=realm, alias=alias, id=mid)
         try:
-            return open_url(mapper_url, method='DELETE', headers=self.restheaders,
+            return open_url(mapper_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Unable to delete mapper %s for identity provider %s in realm %s: %s'
@@ -1642,7 +1660,7 @@ class KeycloakAPI(object):
             comps_url += '?%s' % filter
 
         try:
-            return json.loads(to_native(open_url(comps_url, method='GET', headers=self.restheaders,
+            return json.loads(to_native(open_url(comps_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except ValueError as e:
             self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of components for realm %s: %s'
@@ -1659,7 +1677,7 @@ class KeycloakAPI(object):
         """
         comp_url = URL_COMPONENT.format(url=self.baseurl, realm=realm, id=cid)
         try:
-            return json.loads(to_native(open_url(comp_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(comp_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except HTTPError as e:
             if e.code == 404:
@@ -1679,13 +1697,13 @@ class KeycloakAPI(object):
         """
         comps_url = URL_COMPONENTS.format(url=self.baseurl, realm=realm)
         try:
-            resp = open_url(comps_url, method='POST', headers=self.restheaders,
+            resp = open_url(comps_url, method='POST', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(comprep), validate_certs=self.validate_certs)
             comp_url = resp.getheader('Location')
             if comp_url is None:
                 self.module.fail_json(msg='Could not create component in realm %s: %s'
                                           % (realm, 'unexpected response'))
-            return json.loads(to_native(open_url(comp_url, method="GET", headers=self.restheaders,
+            return json.loads(to_native(open_url(comp_url, method="GET", headers=self.restheaders, timeout=self.connection_timeout,
                                                  validate_certs=self.validate_certs).read()))
         except Exception as e:
             self.module.fail_json(msg='Could not create component in realm %s: %s'
@@ -1702,7 +1720,7 @@ class KeycloakAPI(object):
             self.module.fail_json(msg='Cannot update component without id')
         comp_url = URL_COMPONENT.format(url=self.baseurl, realm=realm, id=cid)
         try:
-            return open_url(comp_url, method='PUT', headers=self.restheaders,
+            return open_url(comp_url, method='PUT', headers=self.restheaders, timeout=self.connection_timeout,
                             data=json.dumps(comprep), validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Could not update component %s in realm %s: %s'
@@ -1715,7 +1733,7 @@ class KeycloakAPI(object):
         """
         comp_url = URL_COMPONENT.format(url=self.baseurl, realm=realm, id=cid)
         try:
-            return open_url(comp_url, method='DELETE', headers=self.restheaders,
+            return open_url(comp_url, method='DELETE', headers=self.restheaders, timeout=self.connection_timeout,
                             validate_certs=self.validate_certs)
         except Exception as e:
             self.module.fail_json(msg='Unable to delete component %s in realm %s: %s'

plugins/module_utils/lxd.py

@@ -75,11 +75,14 @@ class LXDClient(object):
         else:
             raise LXDClientException('URL scheme must be unix: or https:')
 
-    def do(self, method, url, body_json=None, ok_error_codes=None, timeout=None):
+    def do(self, method, url, body_json=None, ok_error_codes=None, timeout=None, wait_for_container=None):
         resp_json = self._send_request(method, url, body_json=body_json, ok_error_codes=ok_error_codes, timeout=timeout)
         if resp_json['type'] == 'async':
             url = '{0}/wait'.format(resp_json['operation'])
             resp_json = self._send_request('GET', url)
+            if wait_for_container:
+                while resp_json['metadata']['status'] == 'Running':
+                    resp_json = self._send_request('GET', url)
             if resp_json['metadata']['status'] != 'Success':
                 self._raise_err_from_json(resp_json)
         return resp_json

plugins/module_utils/proxmox.py

@@ -21,6 +21,8 @@ except ImportError:
 
 
 from ansible.module_utils.basic import env_fallback, missing_required_lib
+from ansible.module_utils.common.text.converters import to_native
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 
 def proxmox_auth_argument_spec():
@@ -68,6 +70,9 @@ def ansible_to_proxmox_bool(value):
 class ProxmoxAnsible(object):
     """Base class for Proxmox modules"""
     def __init__(self, module):
+        if not HAS_PROXMOXER:
+            module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
+
         self.module = module
         self.proxmox_api = self._connect()
         # Test token validity
@@ -95,3 +100,46 @@ class ProxmoxAnsible(object):
             return ProxmoxAPI(api_host, verify_ssl=validate_certs, **auth_args)
         except Exception as e:
             self.module.fail_json(msg='%s' % e, exception=traceback.format_exc())
+
+    def version(self):
+        apireturn = self.proxmox_api.version.get()
+        return LooseVersion(apireturn['version'])
+
+    def get_node(self, node):
+        nodes = [n for n in self.proxmox_api.nodes.get() if n['node'] == node]
+        return nodes[0] if nodes else None
+
+    def get_nextvmid(self):
+        vmid = self.proxmox_api.cluster.nextid.get()
+        return vmid
+
+    def get_vmid(self, name, ignore_missing=False, choose_first_if_multiple=False):
+        vms = [vm['vmid'] for vm in self.proxmox_api.cluster.resources.get(type='vm') if vm.get('name') == name]
+
+        if not vms:
+            if ignore_missing:
+                return None
+
+            self.module.fail_json(msg='No VM with name %s found' % name)
+        elif len(vms) > 1:
+            if choose_first_if_multiple:
+                self.module.deprecate(
+                    'Multiple VMs with name %s found, choosing the first one. ' % name +
+                    'This will be an error in the future. To ensure the correct VM is used, ' +
+                    'also pass the vmid parameter.',
+                    version='5.0.0', collection_name='community.general')
+            else:
+                self.module.fail_json(msg='Multiple VMs with name %s found, provide vmid instead' % name)
+
+        return vms[0]
+
+    def get_vm(self, vmid, ignore_missing=False):
+        vms = [vm for vm in self.proxmox_api.cluster.resources.get(type='vm') if vm['vmid'] == int(vmid)]
+
+        if vms:
+            return vms[0]
+        else:
+            if ignore_missing:
+                return None
+
+            self.module.fail_json(msg='VM with vmid %s does not exist in cluster' % vmid)

plugins/module_utils/redis.py

@@ -27,20 +27,20 @@ except ImportError:
     HAS_CERTIFI_PACKAGE = False
 
 
-def fail_imports(module):
+def fail_imports(module, needs_certifi=True):
     errors = []
     traceback = []
     if not HAS_REDIS_PACKAGE:
         errors.append(missing_required_lib('redis'))
         traceback.append(REDIS_IMP_ERR)
-    if not HAS_CERTIFI_PACKAGE:
+    if not HAS_CERTIFI_PACKAGE and needs_certifi:
         errors.append(missing_required_lib('certifi'))
         traceback.append(CERTIFI_IMPORT_ERROR)
     if errors:
         module.fail_json(errors=errors, traceback='\n'.join(traceback))
 
 
-def redis_auth_argument_spec():
+def redis_auth_argument_spec(tls_default=True):
     return dict(
         login_host=dict(type='str',
                         default='localhost',),
@@ -50,7 +50,7 @@ def redis_auth_argument_spec():
                             ),
         login_port=dict(type='int', default=6379),
         tls=dict(type='bool',
-                 default=True),
+                 default=tls_default),
         validate_certs=dict(type='bool',
                             default=True
                             ),
@@ -58,6 +58,30 @@ def redis_auth_argument_spec():
     )
 
 
+def redis_auth_params(module):
+    login_host = module.params['login_host']
+    login_user = module.params['login_user']
+    login_password = module.params['login_password']
+    login_port = module.params['login_port']
+    tls = module.params['tls']
+    validate_certs = 'required' if module.params['validate_certs'] else None
+    ca_certs = module.params['ca_certs']
+    if tls and ca_certs is None:
+        ca_certs = str(certifi.where())
+    if tuple(map(int, redis_version.split('.'))) < (3, 4, 0) and login_user is not None:
+        module.fail_json(
+            msg='The option `username` in only supported with redis >= 3.4.0.')
+    params = {'host': login_host,
+              'port': login_port,
+              'password': login_password,
+              'ssl_ca_certs': ca_certs,
+              'ssl_cert_reqs': validate_certs,
+              'ssl': tls}
+    if login_user is not None:
+        params['username'] = login_user
+    return params
+
+
 class RedisAnsible(object):
     '''Base class for Redis module'''
 
@@ -66,28 +90,8 @@ class RedisAnsible(object):
         self.connection = self._connect()
 
     def _connect(self):
-        login_host = self.module.params['login_host']
-        login_user = self.module.params['login_user']
-        login_password = self.module.params['login_password']
-        login_port = self.module.params['login_port']
-        tls = self.module.params['tls']
-        validate_certs = 'required' if self.module.params['validate_certs'] else None
-        ca_certs = self.module.params['ca_certs']
-        if tls and ca_certs is None:
-            ca_certs = str(certifi.where())
-        if tuple(map(int, redis_version.split('.'))) < (3, 4, 0) and login_user is not None:
-            self.module.fail_json(
-                msg='The option `username` in only supported with redis >= 3.4.0.')
-        params = {'host': login_host,
-                  'port': login_port,
-                  'password': login_password,
-                  'ssl_ca_certs': ca_certs,
-                  'ssl_cert_reqs': validate_certs,
-                  'ssl': tls}
-        if login_user is not None:
-            params['username'] = login_user
         try:
-            return Redis(**params)
+            return Redis(**redis_auth_params(self.module))
         except Exception as e:
             self.module.fail_json(msg='{0}'.format(str(e)))
         return None

plugins/module_utils/scaleway.py

@@ -167,17 +167,61 @@ class Scaleway(object):
 
 
 SCALEWAY_LOCATION = {
-    'par1': {'name': 'Paris 1', 'country': 'FR', "api_endpoint": 'https://api.scaleway.com/instance/v1/zones/fr-par-1'},
-    'EMEA-FR-PAR1': {'name': 'Paris 1', 'country': 'FR', "api_endpoint": 'https://api.scaleway.com/instance/v1/zones/fr-par-1'},
+    'par1': {
+        'name': 'Paris 1',
+        'country': 'FR',
+        'api_endpoint': 'https://api.scaleway.com/instance/v1/zones/fr-par-1',
+        'api_endpoint_vpc': 'https://api.scaleway.com/vpc/v1/zones/fr-par-1'
+    },
 
-    'par2': {'name': 'Paris 2', 'country': 'FR', "api_endpoint": 'https://api.scaleway.com/instance/v1/zones/fr-par-2'},
-    'EMEA-FR-PAR2': {'name': 'Paris 2', 'country': 'FR', "api_endpoint": 'https://api.scaleway.com/instance/v1/zones/fr-par-2'},
+    'EMEA-FR-PAR1': {
+        'name': 'Paris 1',
+        'country': 'FR',
+        'api_endpoint': 'https://api.scaleway.com/instance/v1/zones/fr-par-1',
+        'api_endpoint_vpc': 'https://api.scaleway.com/vpc/v1/zones/fr-par-1'
+    },
 
-    'ams1': {'name': 'Amsterdam 1', 'country': 'NL', "api_endpoint": 'https://api.scaleway.com/instance/v1/zones/nl-ams-1'},
-    'EMEA-NL-EVS': {'name': 'Amsterdam 1', 'country': 'NL', "api_endpoint": 'https://api.scaleway.com/instance/v1/zones/nl-ams-1'},
+    'par2': {
+        'name': 'Paris 2',
+        'country': 'FR',
+        'api_endpoint': 'https://api.scaleway.com/instance/v1/zones/fr-par-2',
+        'api_endpoint_vpc': 'https://api.scaleway.com/vpc/v1/zones/fr-par-2'
+    },
 
-    'waw1': {'name': 'Warsaw 1', 'country': 'PL', "api_endpoint": 'https://api.scaleway.com/instance/v1/zones/pl-waw-1'},
-    'EMEA-PL-WAW1': {'name': 'Warsaw 1', 'country': 'PL', "api_endpoint": 'https://api.scaleway.com/instance/v1/zones/pl-waw-1'},
+    'EMEA-FR-PAR2': {
+        'name': 'Paris 2',
+        'country': 'FR',
+        'api_endpoint': 'https://api.scaleway.com/instance/v1/zones/fr-par-2',
+        'api_endpoint_vpc': 'https://api.scaleway.com/vpc/v1/zones/fr-par-2'
+    },
+
+    'ams1': {
+        'name': 'Amsterdam 1',
+        'country': 'NL',
+        'api_endpoint': 'https://api.scaleway.com/instance/v1/zones/nl-ams-1',
+        'api_endpoint_vpc': 'https://api.scaleway.com/vpc/v1/zones/nl-ams-10'
+    },
+
+    'EMEA-NL-EVS': {
+        'name': 'Amsterdam 1',
+        'country': 'NL',
+        'api_endpoint': 'https://api.scaleway.com/instance/v1/zones/nl-ams-1',
+        'api_endpoint_vpc': 'https://api.scaleway.com/vpc/v1/zones/nl-ams-1'
+    },
+
+    'waw1': {
+        'name': 'Warsaw 1',
+        'country': 'PL',
+        'api_endpoint': 'https://api.scaleway.com/instance/v1/zones/pl-waw-1',
+        'api_endpoint_vpc': 'https://api.scaleway.com/vpc/v1/zones/pl-waw-1'
+    },
+
+    'EMEA-PL-WAW1': {
+        'name': 'Warsaw 1',
+        'country': 'PL',
+        'api_endpoint': 'https://api.scaleway.com/instance/v1/zones/pl-waw-1',
+        'api_endpoint_vpc': 'https://api.scaleway.com/vpc/v1/zones/pl-waw-1'
+    },
 }
 
 SCALEWAY_ENDPOINT = "https://api.scaleway.com"

plugins/modules/cloud/centurylink/clc_blueprint_package.py

@@ -42,7 +42,7 @@ options:
     description:
       - Whether to wait for the tasks to finish before returning.
     type: str
-    default: True
+    default: 'True'
     required: False
 requirements:
     - python = 2.7

plugins/modules/cloud/centurylink/clc_firewall_policy.py

@@ -66,8 +66,8 @@ options:
     description:
       - Whether the firewall policy is enabled or disabled
     type: str
-    choices: [True, False]
-    default: True
+    choices: ['True', 'False']
+    default: 'True'
 requirements:
     - python = 2.7
     - requests >= 2.5.0

plugins/modules/cloud/centurylink/clc_loadbalancer.py

@@ -48,7 +48,7 @@ options:
     description:
       - Port to configure on the public-facing side of the load balancer pool
     type: str
-    choices: [80, 443]
+    choices: ['80', '443']
   nodes:
     description:
       - A list of nodes that needs to be added to the load balancer pool

plugins/modules/cloud/centurylink/clc_server_snapshot.py

@@ -36,7 +36,7 @@ options:
   wait:
     description:
       - Whether to wait for the provisioning tasks to finish before returning.
-    default: True
+    default: 'True'
     required: False
     type: str
 requirements:

plugins/modules/cloud/huawei/hwc_vpc_security_group.py

@@ -51,7 +51,6 @@ options:
               group.s
         type: str
         required: false
-        default: 0
     vpc_id:
         description:
             - Specifies the resource ID of the VPC to which the security group

plugins/modules/cloud/lxd/lxd_container.py

@@ -124,6 +124,13 @@ options:
         required: false
         default: false
         type: bool
+    wait_for_container:
+        description:
+            - If set to C(true), the tasks will wait till the task reports a
+              success status when performing container operations.
+        default: false
+        type: bool
+        version_added: 4.4.0
     force_stop:
         description:
           - If this is true, the C(lxd_container) forces to stop the instance
@@ -414,6 +421,7 @@ class LXDContainerManagement(object):
         self.force_stop = self.module.params['force_stop']
         self.addresses = None
         self.target = self.module.params['target']
+        self.wait_for_container = self.module.params['wait_for_container']
 
         self.type = self.module.params['type']
 
@@ -487,9 +495,9 @@ class LXDContainerManagement(object):
         config = self.config.copy()
         config['name'] = self.name
         if self.target:
-            self.client.do('POST', '{0}?{1}'.format(self.api_endpoint, urlencode(dict(target=self.target))), config)
+            self.client.do('POST', '{0}?{1}'.format(self.api_endpoint, urlencode(dict(target=self.target))), config, wait_for_container=self.wait_for_container)
         else:
-            self.client.do('POST', self.api_endpoint, config)
+            self.client.do('POST', self.api_endpoint, config, wait_for_container=self.wait_for_container)
         self.actions.append('create')
 
     def _start_instance(self):
@@ -745,6 +753,10 @@ def main():
                 default='container',
                 choices=['container', 'virtual-machine'],
             ),
+            wait_for_container=dict(
+                type='bool',
+                default=False
+            ),
             wait_for_ipv4_addresses=dict(
                 type='bool',
                 default=False

plugins/modules/cloud/misc/proxmox.py

@@ -1,5 +1,6 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
+#
 # Copyright: Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
@@ -392,229 +393,189 @@ import traceback
 
 from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
-try:
-    from proxmoxer import ProxmoxAPI
-    HAS_PROXMOXER = True
-except ImportError:
-    HAS_PROXMOXER = False
-
 from ansible.module_utils.basic import AnsibleModule, env_fallback
 from ansible.module_utils.common.text.converters import to_native
 
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    ansible_to_proxmox_bool
-)
-
+    ansible_to_proxmox_bool, proxmox_auth_argument_spec, ProxmoxAnsible)
 
 VZ_TYPE = None
 
 
-def get_nextvmid(module, proxmox):
-    try:
-        vmid = proxmox.cluster.nextid.get()
-        return vmid
-    except Exception as e:
-        module.fail_json(msg="Unable to get next vmid. Failed with exception: %s" % to_native(e),
-                         exception=traceback.format_exc())
+class ProxmoxLxcAnsible(ProxmoxAnsible):
+    def content_check(self, node, ostemplate, template_store):
+        return [True for cnt in self.proxmox_api.nodes(node).storage(template_store).content.get() if cnt['volid'] == ostemplate]
 
+    def is_template_container(self, node, vmid):
+        """Check if the specified container is a template."""
+        proxmox_node = self.proxmox_api.nodes(node)
+        config = getattr(proxmox_node, VZ_TYPE)(vmid).config.get()
+        return config['template']
 
-def get_vmid(proxmox, hostname):
-    return [vm['vmid'] for vm in proxmox.cluster.resources.get(type='vm') if 'name' in vm and vm['name'] == hostname]
+    def create_instance(self, vmid, node, disk, storage, cpus, memory, swap, timeout, clone, **kwargs):
+        proxmox_node = self.proxmox_api.nodes(node)
 
+        # Remove all empty kwarg entries
+        kwargs = dict((k, v) for k, v in kwargs.items() if v is not None)
 
-def get_instance(proxmox, vmid):
-    return [vm for vm in proxmox.cluster.resources.get(type='vm') if vm['vmid'] == int(vmid)]
-
-
-def content_check(proxmox, node, ostemplate, template_store):
-    return [True for cnt in proxmox.nodes(node).storage(template_store).content.get() if cnt['volid'] == ostemplate]
-
-
-def is_template_container(proxmox, node, vmid):
-    """Check if the specified container is a template."""
-    proxmox_node = proxmox.nodes(node)
-    config = getattr(proxmox_node, VZ_TYPE)(vmid).config.get()
-    return config['template']
-
-
-def node_check(proxmox, node):
-    return [True for nd in proxmox.nodes.get() if nd['node'] == node]
-
-
-def proxmox_version(proxmox):
-    apireturn = proxmox.version.get()
-    return LooseVersion(apireturn['version'])
-
-
-def create_instance(module, proxmox, vmid, node, disk, storage, cpus, memory, swap, timeout, clone, **kwargs):
-    proxmox_node = proxmox.nodes(node)
-
-    # Remove all empty kwarg entries
-    kwargs = dict((k, v) for k, v in kwargs.items() if v is not None)
-
-    if VZ_TYPE == 'lxc':
-        kwargs['cpulimit'] = cpus
-        kwargs['rootfs'] = disk
-        if 'netif' in kwargs:
-            kwargs.update(kwargs['netif'])
-            del kwargs['netif']
-        if 'mounts' in kwargs:
-            kwargs.update(kwargs['mounts'])
-            del kwargs['mounts']
-        if 'pubkey' in kwargs:
-            if proxmox_version(proxmox) >= LooseVersion('4.2'):
-                kwargs['ssh-public-keys'] = kwargs['pubkey']
-            del kwargs['pubkey']
-    else:
-        kwargs['cpus'] = cpus
-        kwargs['disk'] = disk
-
-    if clone is not None:
-        if VZ_TYPE != 'lxc':
-            module.fail_json(changed=False, msg="Clone operator is only supported for LXC enabled proxmox clusters.")
-
-        clone_is_template = is_template_container(proxmox, node, clone)
-
-        # By default, create a full copy only when the cloned container is not a template.
-        create_full_copy = not clone_is_template
-
-        # Only accept parameters that are compatible with the clone endpoint.
-        valid_clone_parameters = ['hostname', 'pool', 'description']
-        if module.params['storage'] is not None and clone_is_template:
-            # Cloning a template, so create a full copy instead of a linked copy
-            create_full_copy = True
-        elif module.params['storage'] is None and not clone_is_template:
-            # Not cloning a template, but also no defined storage. This isn't possible.
-            module.fail_json(changed=False, msg="Cloned container is not a template, storage needs to be specified.")
-
-        if module.params['clone_type'] == 'linked':
-            if not clone_is_template:
-                module.fail_json(changed=False, msg="'linked' clone type is specified, but cloned container is not a template container.")
-            # Don't need to do more, by default create_full_copy is set to false already
-        elif module.params['clone_type'] == 'opportunistic':
-            if not clone_is_template:
-                # Cloned container is not a template, so we need our 'storage' parameter
-                valid_clone_parameters.append('storage')
-        elif module.params['clone_type'] == 'full':
-            create_full_copy = True
-            valid_clone_parameters.append('storage')
-
-        clone_parameters = {}
-
-        if create_full_copy:
-            clone_parameters['full'] = '1'
+        if VZ_TYPE == 'lxc':
+            kwargs['cpulimit'] = cpus
+            kwargs['rootfs'] = disk
+            if 'netif' in kwargs:
+                kwargs.update(kwargs['netif'])
+                del kwargs['netif']
+            if 'mounts' in kwargs:
+                kwargs.update(kwargs['mounts'])
+                del kwargs['mounts']
+            if 'pubkey' in kwargs:
+                if self.version() >= LooseVersion('4.2'):
+                    kwargs['ssh-public-keys'] = kwargs['pubkey']
+                del kwargs['pubkey']
         else:
-            clone_parameters['full'] = '0'
-        for param in valid_clone_parameters:
-            if module.params[param] is not None:
-                clone_parameters[param] = module.params[param]
+            kwargs['cpus'] = cpus
+            kwargs['disk'] = disk
 
-        taskid = getattr(proxmox_node, VZ_TYPE)(clone).clone.post(newid=vmid, **clone_parameters)
-    else:
-        taskid = getattr(proxmox_node, VZ_TYPE).create(vmid=vmid, storage=storage, memory=memory, swap=swap, **kwargs)
+        if clone is not None:
+            if VZ_TYPE != 'lxc':
+                self.module.fail_json(changed=False, msg="Clone operator is only supported for LXC enabled proxmox clusters.")
 
-    while timeout:
-        if (proxmox_node.tasks(taskid).status.get()['status'] == 'stopped' and
-                proxmox_node.tasks(taskid).status.get()['exitstatus'] == 'OK'):
-            return True
-        timeout -= 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for creating VM. Last line in task before timeout: %s' %
-                                 proxmox_node.tasks(taskid).log.get()[:1])
+            clone_is_template = self.is_template_container(node, clone)
 
-        time.sleep(1)
-    return False
+            # By default, create a full copy only when the cloned container is not a template.
+            create_full_copy = not clone_is_template
 
+            # Only accept parameters that are compatible with the clone endpoint.
+            valid_clone_parameters = ['hostname', 'pool', 'description']
+            if self.module.params['storage'] is not None and clone_is_template:
+                # Cloning a template, so create a full copy instead of a linked copy
+                create_full_copy = True
+            elif self.module.params['storage'] is None and not clone_is_template:
+                # Not cloning a template, but also no defined storage. This isn't possible.
+                self.module.fail_json(changed=False, msg="Cloned container is not a template, storage needs to be specified.")
 
-def start_instance(module, proxmox, vm, vmid, timeout):
-    taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.start.post()
-    while timeout:
-        if (proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['status'] == 'stopped' and
-                proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
-            return True
-        timeout -= 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for starting VM. Last line in task before timeout: %s' %
-                                 proxmox.nodes(vm[0]['node']).tasks(taskid).log.get()[:1])
+            if self.module.params['clone_type'] == 'linked':
+                if not clone_is_template:
+                    self.module.fail_json(changed=False, msg="'linked' clone type is specified, but cloned container is not a template container.")
+                # Don't need to do more, by default create_full_copy is set to false already
+            elif self.module.params['clone_type'] == 'opportunistic':
+                if not clone_is_template:
+                    # Cloned container is not a template, so we need our 'storage' parameter
+                    valid_clone_parameters.append('storage')
+            elif self.module.params['clone_type'] == 'full':
+                create_full_copy = True
+                valid_clone_parameters.append('storage')
 
-        time.sleep(1)
-    return False
+            clone_parameters = {}
 
+            if create_full_copy:
+                clone_parameters['full'] = '1'
+            else:
+                clone_parameters['full'] = '0'
+            for param in valid_clone_parameters:
+                if self.module.params[param] is not None:
+                    clone_parameters[param] = self.module.params[param]
 
-def stop_instance(module, proxmox, vm, vmid, timeout, force):
-    if force:
-        taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.shutdown.post(forceStop=1)
-    else:
-        taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.shutdown.post()
-    while timeout:
-        if (proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['status'] == 'stopped' and
-                proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
-            return True
-        timeout -= 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for stopping VM. Last line in task before timeout: %s' %
-                                 proxmox.nodes(vm[0]['node']).tasks(taskid).log.get()[:1])
+            taskid = getattr(proxmox_node, VZ_TYPE)(clone).clone.post(newid=vmid, **clone_parameters)
+        else:
+            taskid = getattr(proxmox_node, VZ_TYPE).create(vmid=vmid, storage=storage, memory=memory, swap=swap, **kwargs)
 
-        time.sleep(1)
-    return False
+        while timeout:
+            if (proxmox_node.tasks(taskid).status.get()['status'] == 'stopped' and
+                    proxmox_node.tasks(taskid).status.get()['exitstatus'] == 'OK'):
+                return True
+            timeout -= 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for creating VM. Last line in task before timeout: %s' %
+                                      proxmox_node.tasks(taskid).log.get()[:1])
 
+            time.sleep(1)
+        return False
 
-def umount_instance(module, proxmox, vm, vmid, timeout):
-    taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.umount.post()
-    while timeout:
-        if (proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['status'] == 'stopped' and
-                proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
-            return True
-        timeout -= 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for unmounting VM. Last line in task before timeout: %s' %
-                                 proxmox.nodes(vm[0]['node']).tasks(taskid).log.get()[:1])
+    def start_instance(self, vm, vmid, timeout):
+        taskid = getattr(self.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.start.post()
+        while timeout:
+            if (self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['status'] == 'stopped' and
+                    self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+                return True
+            timeout -= 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for starting VM. Last line in task before timeout: %s' %
+                                      self.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1])
 
-        time.sleep(1)
-    return False
+            time.sleep(1)
+        return False
+
+    def stop_instance(self, vm, vmid, timeout, force):
+        if force:
+            taskid = getattr(self.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.shutdown.post(forceStop=1)
+        else:
+            taskid = getattr(self.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.shutdown.post()
+        while timeout:
+            if (self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['status'] == 'stopped' and
+                    self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+                return True
+            timeout -= 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for stopping VM. Last line in task before timeout: %s' %
+                                      self.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1])
+
+            time.sleep(1)
+        return False
+
+    def umount_instance(self, vm, vmid, timeout):
+        taskid = getattr(self.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.umount.post()
+        while timeout:
+            if (self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['status'] == 'stopped' and
+                    self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+                return True
+            timeout -= 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for unmounting VM. Last line in task before timeout: %s' %
+                                      self.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1])
+
+            time.sleep(1)
+        return False
 
 
 def main():
+    module_args = proxmox_auth_argument_spec()
+    proxmox_args = dict(
+        vmid=dict(type='int', required=False),
+        node=dict(),
+        pool=dict(),
+        password=dict(no_log=True),
+        hostname=dict(),
+        ostemplate=dict(),
+        disk=dict(type='str'),
+        cores=dict(type='int'),
+        cpus=dict(type='int'),
+        memory=dict(type='int'),
+        swap=dict(type='int'),
+        netif=dict(type='dict'),
+        mounts=dict(type='dict'),
+        ip_address=dict(),
+        onboot=dict(type='bool'),
+        features=dict(type='list', elements='str'),
+        storage=dict(default='local'),
+        cpuunits=dict(type='int'),
+        nameserver=dict(),
+        searchdomain=dict(),
+        timeout=dict(type='int', default=30),
+        force=dict(type='bool', default=False),
+        purge=dict(type='bool', default=False),
+        state=dict(default='present', choices=['present', 'absent', 'stopped', 'started', 'restarted']),
+        pubkey=dict(type='str', default=None),
+        unprivileged=dict(type='bool', default=False),
+        description=dict(type='str'),
+        hookscript=dict(type='str'),
+        proxmox_default_behavior=dict(type='str', default='no_defaults', choices=['compatibility', 'no_defaults']),
+        clone=dict(type='int'),
+        clone_type=dict(default='opportunistic', choices=['full', 'linked', 'opportunistic']),
+    )
+    module_args.update(proxmox_args)
+
     module = AnsibleModule(
-        argument_spec=dict(
-            api_host=dict(required=True),
-            api_password=dict(no_log=True, fallback=(env_fallback, ['PROXMOX_PASSWORD'])),
-            api_token_id=dict(no_log=True),
-            api_token_secret=dict(no_log=True),
-            api_user=dict(required=True),
-            vmid=dict(type='int', required=False),
-            validate_certs=dict(type='bool', default=False),
-            node=dict(),
-            pool=dict(),
-            password=dict(no_log=True),
-            hostname=dict(),
-            ostemplate=dict(),
-            disk=dict(type='str'),
-            cores=dict(type='int'),
-            cpus=dict(type='int'),
-            memory=dict(type='int'),
-            swap=dict(type='int'),
-            netif=dict(type='dict'),
-            mounts=dict(type='dict'),
-            ip_address=dict(),
-            onboot=dict(type='bool'),
-            features=dict(type='list', elements='str'),
-            storage=dict(default='local'),
-            cpuunits=dict(type='int'),
-            nameserver=dict(),
-            searchdomain=dict(),
-            timeout=dict(type='int', default=30),
-            force=dict(type='bool', default=False),
-            purge=dict(type='bool', default=False),
-            state=dict(default='present', choices=['present', 'absent', 'stopped', 'started', 'restarted']),
-            pubkey=dict(type='str', default=None),
-            unprivileged=dict(type='bool', default=False),
-            description=dict(type='str'),
-            hookscript=dict(type='str'),
-            proxmox_default_behavior=dict(type='str', default='no_defaults', choices=['compatibility', 'no_defaults']),
-            clone=dict(type='int'),
-            clone_type=dict(default='opportunistic', choices=['full', 'linked', 'opportunistic']),
-        ),
+        argument_spec=module_args,
         required_if=[
             ('state', 'present', ['node', 'hostname']),
             ('state', 'present', ('clone', 'ostemplate'), True),  # Require one of clone and ostemplate. Together with mutually_exclusive this ensures that we
@@ -627,17 +588,13 @@ def main():
         mutually_exclusive=[('clone', 'ostemplate')],  # Creating a new container is done either by cloning an existing one, or based on a template.
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg='proxmoxer required for this module')
+    proxmox = ProxmoxLxcAnsible(module)
+
+    global VZ_TYPE
+    VZ_TYPE = 'openvz' if proxmox.version() < LooseVersion('4.0') else 'lxc'
 
     state = module.params['state']
-    api_host = module.params['api_host']
-    api_password = module.params['api_password']
-    api_token_id = module.params['api_token_id']
-    api_token_secret = module.params['api_token_secret']
-    api_user = module.params['api_user']
     vmid = module.params['vmid']
-    validate_certs = module.params['validate_certs']
     node = module.params['node']
     disk = module.params['disk']
     cpus = module.params['cpus']
@@ -664,68 +621,54 @@ def main():
             if module.params[param] is None:
                 module.params[param] = value
 
-    auth_args = {'user': api_user}
-    if not api_token_id:
-        auth_args['password'] = api_password
-    else:
-        auth_args['token_name'] = api_token_id
-        auth_args['token_value'] = api_token_secret
-
-    try:
-        proxmox = ProxmoxAPI(api_host, verify_ssl=validate_certs, **auth_args)
-        global VZ_TYPE
-        VZ_TYPE = 'openvz' if proxmox_version(proxmox) < LooseVersion('4.0') else 'lxc'
-    except Exception as e:
-        module.fail_json(msg='authorization on proxmox cluster failed with exception: %s' % e)
-
     # If vmid not set get the Next VM id from ProxmoxAPI
     # If hostname is set get the VM id from ProxmoxAPI
     if not vmid and state == 'present':
-        vmid = get_nextvmid(module, proxmox)
+        vmid = proxmox.get_nextvmid()
     elif not vmid and hostname:
-        hosts = get_vmid(proxmox, hostname)
-        if len(hosts) == 0:
-            module.fail_json(msg="Vmid could not be fetched => Hostname doesn't exist (action: %s)" % state)
-        vmid = hosts[0]
+        vmid = proxmox.get_vmid(hostname, choose_first_if_multiple=True)
     elif not vmid:
         module.exit_json(changed=False, msg="Vmid could not be fetched for the following action: %s" % state)
 
     # Create a new container
     if state == 'present' and clone is None:
         try:
-            if get_instance(proxmox, vmid) and not module.params['force']:
+            if proxmox.get_vm(vmid, ignore_missing=True) and not module.params['force']:
                 module.exit_json(changed=False, msg="VM with vmid = %s is already exists" % vmid)
             # If no vmid was passed, there cannot be another VM named 'hostname'
-            if not module.params['vmid'] and get_vmid(proxmox, hostname) and not module.params['force']:
-                module.exit_json(changed=False, msg="VM with hostname %s already exists and has ID number %s" % (hostname, get_vmid(proxmox, hostname)[0]))
-            elif not node_check(proxmox, node):
+            if (not module.params['vmid'] and
+                    proxmox.get_vmid(hostname, ignore_missing=True, choose_first_if_multiple=True) and
+                    not module.params['force']):
+                vmid = proxmox.get_vmid(hostname, choose_first_if_multiple=True)
+                module.exit_json(changed=False, msg="VM with hostname %s already exists and has ID number %s" % (hostname, vmid))
+            elif not proxmox.get_node(node):
                 module.fail_json(msg="node '%s' not exists in cluster" % node)
-            elif not content_check(proxmox, node, module.params['ostemplate'], template_store):
+            elif not proxmox.content_check(node, module.params['ostemplate'], template_store):
                 module.fail_json(msg="ostemplate '%s' not exists on node %s and storage %s"
                                  % (module.params['ostemplate'], node, template_store))
         except Exception as e:
             module.fail_json(msg="Pre-creation checks of {VZ_TYPE} VM {vmid} failed with exception: {e}".format(VZ_TYPE=VZ_TYPE, vmid=vmid, e=e))
 
         try:
-            create_instance(module, proxmox, vmid, node, disk, storage, cpus, memory, swap, timeout, clone,
-                            cores=module.params['cores'],
-                            pool=module.params['pool'],
-                            password=module.params['password'],
-                            hostname=module.params['hostname'],
-                            ostemplate=module.params['ostemplate'],
-                            netif=module.params['netif'],
-                            mounts=module.params['mounts'],
-                            ip_address=module.params['ip_address'],
-                            onboot=ansible_to_proxmox_bool(module.params['onboot']),
-                            cpuunits=module.params['cpuunits'],
-                            nameserver=module.params['nameserver'],
-                            searchdomain=module.params['searchdomain'],
-                            force=ansible_to_proxmox_bool(module.params['force']),
-                            pubkey=module.params['pubkey'],
-                            features=",".join(module.params['features']) if module.params['features'] is not None else None,
-                            unprivileged=ansible_to_proxmox_bool(module.params['unprivileged']),
-                            description=module.params['description'],
-                            hookscript=module.params['hookscript'])
+            proxmox.create_instance(vmid, node, disk, storage, cpus, memory, swap, timeout, clone,
+                                    cores=module.params['cores'],
+                                    pool=module.params['pool'],
+                                    password=module.params['password'],
+                                    hostname=module.params['hostname'],
+                                    ostemplate=module.params['ostemplate'],
+                                    netif=module.params['netif'],
+                                    mounts=module.params['mounts'],
+                                    ip_address=module.params['ip_address'],
+                                    onboot=ansible_to_proxmox_bool(module.params['onboot']),
+                                    cpuunits=module.params['cpuunits'],
+                                    nameserver=module.params['nameserver'],
+                                    searchdomain=module.params['searchdomain'],
+                                    force=ansible_to_proxmox_bool(module.params['force']),
+                                    pubkey=module.params['pubkey'],
+                                    features=",".join(module.params['features']) if module.params['features'] is not None else None,
+                                    unprivileged=ansible_to_proxmox_bool(module.params['unprivileged']),
+                                    description=module.params['description'],
+                                    hookscript=module.params['hookscript'])
 
             module.exit_json(changed=True, msg="Deployed VM %s from template %s" % (vmid, module.params['ostemplate']))
         except Exception as e:
@@ -734,18 +677,21 @@ def main():
     # Clone a container
     elif state == 'present' and clone is not None:
         try:
-            if get_instance(proxmox, vmid) and not module.params['force']:
+            if proxmox.get_vm(vmid, ignore_missing=True) and not module.params['force']:
                 module.exit_json(changed=False, msg="VM with vmid = %s is already exists" % vmid)
             # If no vmid was passed, there cannot be another VM named 'hostname'
-            if not module.params['vmid'] and get_vmid(proxmox, hostname) and not module.params['force']:
-                module.exit_json(changed=False, msg="VM with hostname %s already exists and has ID number %s" % (hostname, get_vmid(proxmox, hostname)[0]))
-            if not get_instance(proxmox, clone):
+            if (not module.params['vmid'] and
+                    proxmox.get_vmid(hostname, ignore_missing=True, choose_first_if_multiple=True) and
+                    not module.params['force']):
+                vmid = proxmox.get_vmid(hostname, choose_first_if_multiple=True)
+                module.exit_json(changed=False, msg="VM with hostname %s already exists and has ID number %s" % (hostname, vmid))
+            if not proxmox.get_vm(clone, ignore_missing=True):
                 module.exit_json(changed=False, msg="Container to be cloned does not exist")
         except Exception as e:
             module.fail_json(msg="Pre-clone checks of {VZ_TYPE} VM {vmid} failed with exception: {e}".format(VZ_TYPE=VZ_TYPE, vmid=vmid, e=e))
 
         try:
-            create_instance(module, proxmox, vmid, node, disk, storage, cpus, memory, swap, timeout, clone)
+            proxmox.create_instance(vmid, node, disk, storage, cpus, memory, swap, timeout, clone)
 
             module.exit_json(changed=True, msg="Cloned VM %s from %s" % (vmid, clone))
         except Exception as e:
@@ -753,64 +699,60 @@ def main():
 
     elif state == 'started':
         try:
-            vm = get_instance(proxmox, vmid)
-            if not vm:
-                module.fail_json(msg='VM with vmid = %s not exists in cluster' % vmid)
-            if getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'running':
+            vm = proxmox.get_vm(vmid)
+            if getattr(proxmox.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'running':
                 module.exit_json(changed=False, msg="VM %s is already running" % vmid)
 
-            if start_instance(module, proxmox, vm, vmid, timeout):
+            if proxmox.start_instance(vm, vmid, timeout):
                 module.exit_json(changed=True, msg="VM %s started" % vmid)
         except Exception as e:
             module.fail_json(msg="starting of VM %s failed with exception: %s" % (vmid, e))
 
     elif state == 'stopped':
         try:
-            vm = get_instance(proxmox, vmid)
-            if not vm:
-                module.fail_json(msg='VM with vmid = %s not exists in cluster' % vmid)
+            vm = proxmox.get_vm(vmid)
 
-            if getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'mounted':
+            if getattr(proxmox.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'mounted':
                 if module.params['force']:
-                    if umount_instance(module, proxmox, vm, vmid, timeout):
+                    if proxmox.umount_instance(vm, vmid, timeout):
                         module.exit_json(changed=True, msg="VM %s is shutting down" % vmid)
                 else:
                     module.exit_json(changed=False, msg=("VM %s is already shutdown, but mounted. "
                                                          "You can use force option to umount it.") % vmid)
 
-            if getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'stopped':
+            if getattr(proxmox.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'stopped':
                 module.exit_json(changed=False, msg="VM %s is already shutdown" % vmid)
 
-            if stop_instance(module, proxmox, vm, vmid, timeout, force=module.params['force']):
+            if proxmox.stop_instance(vm, vmid, timeout, force=module.params['force']):
                 module.exit_json(changed=True, msg="VM %s is shutting down" % vmid)
         except Exception as e:
             module.fail_json(msg="stopping of VM %s failed with exception: %s" % (vmid, e))
 
     elif state == 'restarted':
         try:
-            vm = get_instance(proxmox, vmid)
-            if not vm:
-                module.fail_json(msg='VM with vmid = %s not exists in cluster' % vmid)
-            if (getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'stopped' or
-                    getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'mounted'):
+            vm = proxmox.get_vm(vmid)
+
+            vm_status = getattr(proxmox.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.current.get()['status']
+            if vm_status in ['stopped', 'mounted']:
                 module.exit_json(changed=False, msg="VM %s is not running" % vmid)
 
-            if (stop_instance(module, proxmox, vm, vmid, timeout, force=module.params['force']) and
-                    start_instance(module, proxmox, vm, vmid, timeout)):
+            if (proxmox.stop_instance(vm, vmid, timeout, force=module.params['force']) and
+                    proxmox.start_instance(vm, vmid, timeout)):
                 module.exit_json(changed=True, msg="VM %s is restarted" % vmid)
         except Exception as e:
             module.fail_json(msg="restarting of VM %s failed with exception: %s" % (vmid, e))
 
     elif state == 'absent':
         try:
-            vm = get_instance(proxmox, vmid)
+            vm = proxmox.get_vm(vmid, ignore_missing=True)
             if not vm:
                 module.exit_json(changed=False, msg="VM %s does not exist" % vmid)
 
-            if getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'running':
+            vm_status = getattr(proxmox.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.current.get()['status']
+            if vm_status == 'running':
                 module.exit_json(changed=False, msg="VM %s is running. Stop it before deletion." % vmid)
 
-            if getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'mounted':
+            if vm_status == 'mounted':
                 module.exit_json(changed=False, msg="VM %s is mounted. Stop it with force option before deletion." % vmid)
 
             delete_params = {}
@@ -818,16 +760,16 @@ def main():
             if module.params['purge']:
                 delete_params['purge'] = 1
 
-            taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE).delete(vmid, **delete_params)
+            taskid = getattr(proxmox.proxmox_api.nodes(vm['node']), VZ_TYPE).delete(vmid, **delete_params)
 
             while timeout:
-                if (proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['status'] == 'stopped' and
-                        proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+                task_status = proxmox.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()
+                if (task_status['status'] == 'stopped' and task_status['exitstatus'] == 'OK'):
                     module.exit_json(changed=True, msg="VM %s removed" % vmid)
                 timeout -= 1
                 if timeout == 0:
                     module.fail_json(msg='Reached timeout while waiting for removing VM. Last line in task before timeout: %s'
-                                     % proxmox.nodes(vm[0]['node']).tasks(taskid).log.get()[:1])
+                                     % proxmox.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1])
 
                 time.sleep(1)
         except Exception as e:

plugins/modules/cloud/misc/proxmox_domain_info.py

@@ -76,7 +76,7 @@ proxmox_domains:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR)
+    proxmox_auth_argument_spec, ProxmoxAnsible)
 
 
 class ProxmoxDomainInfoAnsible(ProxmoxAnsible):
@@ -114,9 +114,6 @@ def main():
         changed=False
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
-
     proxmox = ProxmoxDomainInfoAnsible(module)
     domain = module.params['domain']
 

plugins/modules/cloud/misc/proxmox_group_info.py

@@ -73,7 +73,7 @@ proxmox_groups:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR)
+    proxmox_auth_argument_spec, ProxmoxAnsible)
 
 
 class ProxmoxGroupInfoAnsible(ProxmoxAnsible):
@@ -124,9 +124,6 @@ def main():
         changed=False
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
-
     proxmox = ProxmoxGroupInfoAnsible(module)
     group = module.params['group']
 

plugins/modules/cloud/misc/proxmox_nic.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-
+#
 # Copyright: (c) 2021, Lammert Hellinga (@Kogelvis) <lammert@hellinga.it>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
@@ -136,120 +136,96 @@ msg:
   sample: "Nic net0 unchanged on VM with vmid 103"
 '''
 
-try:
-    from proxmoxer import ProxmoxAPI
-    HAS_PROXMOXER = True
-except ImportError:
-    HAS_PROXMOXER = False
-
 from ansible.module_utils.basic import AnsibleModule, env_fallback
-from ansible_collections.community.general.plugins.module_utils.proxmox import proxmox_auth_argument_spec
+from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec, ProxmoxAnsible)
 
 
-def get_vmid(module, proxmox, name):
-    try:
-        vms = [vm['vmid'] for vm in proxmox.cluster.resources.get(type='vm') if vm.get('name') == name]
-    except Exception as e:
-        module.fail_json(msg='Error: %s occurred while retrieving VM with name = %s' % (e, name))
+class ProxmoxNicAnsible(ProxmoxAnsible):
+    def update_nic(self, vmid, interface, model, **kwargs):
+        vm = self.get_vm(vmid)
 
-    if not vms:
-        module.fail_json(msg='No VM found with name: %s' % name)
-    elif len(vms) > 1:
-        module.fail_json(msg='Multiple VMs found with name: %s, provide vmid instead' % name)
+        try:
+            vminfo = self.proxmox_api.nodes(vm['node']).qemu(vmid).config.get()
+        except Exception as e:
+            self.module.fail_json(msg='Getting information for VM with vmid = %s failed with exception: %s' % (vmid, e))
 
-    return vms[0]
+        if interface in vminfo:
+            # Convert the current config to a dictionary
+            config = vminfo[interface].split(',')
+            config.sort()
 
+            config_current = {}
 
-def get_vm(proxmox, vmid):
-    return [vm for vm in proxmox.cluster.resources.get(type='vm') if vm['vmid'] == int(vmid)]
+            for i in config:
+                kv = i.split('=')
+                try:
+                    config_current[kv[0]] = kv[1]
+                except IndexError:
+                    config_current[kv[0]] = ''
 
+            # determine the current model nic and mac-address
+            models = ['e1000', 'e1000-82540em', 'e1000-82544gc', 'e1000-82545em', 'i82551', 'i82557b',
+                      'i82559er', 'ne2k_isa', 'ne2k_pci', 'pcnet', 'rtl8139', 'virtio', 'vmxnet3']
+            current_model = set(models) & set(config_current.keys())
+            current_model = current_model.pop()
+            current_mac = config_current[current_model]
 
-def update_nic(module, proxmox, vmid, interface, model, **kwargs):
-    vm = get_vm(proxmox, vmid)
+            # build nic config string
+            config_provided = "{0}={1}".format(model, current_mac)
+        else:
+            config_provided = model
 
-    try:
-        vminfo = proxmox.nodes(vm[0]['node']).qemu(vmid).config.get()
-    except Exception as e:
-        module.fail_json(msg='Getting information for VM with vmid = %s failed with exception: %s' % (vmid, e))
+        if kwargs['mac']:
+            config_provided = "{0}={1}".format(model, kwargs['mac'])
 
-    if interface in vminfo:
-        # Convert the current config to a dictionary
-        config = vminfo[interface].split(',')
-        config.sort()
+        if kwargs['bridge']:
+            config_provided += ",bridge={0}".format(kwargs['bridge'])
 
-        config_current = {}
+        if kwargs['firewall']:
+            config_provided += ",firewall=1"
 
-        for i in config:
-            kv = i.split('=')
-            try:
-                config_current[kv[0]] = kv[1]
-            except IndexError:
-                config_current[kv[0]] = ''
+        if kwargs['link_down']:
+            config_provided += ',link_down=1'
 
-        # determine the current model nic and mac-address
-        models = ['e1000', 'e1000-82540em', 'e1000-82544gc', 'e1000-82545em', 'i82551', 'i82557b',
-                  'i82559er', 'ne2k_isa', 'ne2k_pci', 'pcnet', 'rtl8139', 'virtio', 'vmxnet3']
-        current_model = set(models) & set(config_current.keys())
-        current_model = current_model.pop()
-        current_mac = config_current[current_model]
+        if kwargs['mtu']:
+            config_provided += ",mtu={0}".format(kwargs['mtu'])
+            if model != 'virtio':
+                self.module.warn(
+                    'Ignoring MTU for nic {0} on VM with vmid {1}, '
+                    'model should be set to \'virtio\': '.format(interface, vmid))
 
-        # build nic config string
-        config_provided = "{0}={1}".format(model, current_mac)
-    else:
-        config_provided = model
+        if kwargs['queues']:
+            config_provided += ",queues={0}".format(kwargs['queues'])
 
-    if kwargs['mac']:
-        config_provided = "{0}={1}".format(model, kwargs['mac'])
+        if kwargs['rate']:
+            config_provided += ",rate={0}".format(kwargs['rate'])
 
-    if kwargs['bridge']:
-        config_provided += ",bridge={0}".format(kwargs['bridge'])
+        if kwargs['tag']:
+            config_provided += ",tag={0}".format(kwargs['tag'])
 
-    if kwargs['firewall']:
-        config_provided += ",firewall=1"
+        if kwargs['trunks']:
+            config_provided += ",trunks={0}".format(';'.join(str(x) for x in kwargs['trunks']))
 
-    if kwargs['link_down']:
-        config_provided += ',link_down=1'
+        net = {interface: config_provided}
+        vm = self.get_vm(vmid)
 
-    if kwargs['mtu']:
-        config_provided += ",mtu={0}".format(kwargs['mtu'])
-        if model != 'virtio':
-            module.warn(
-                'Ignoring MTU for nic {0} on VM with vmid {1}, '
-                'model should be set to \'virtio\': '.format(interface, vmid))
+        if ((interface not in vminfo) or (vminfo[interface] != config_provided)):
+            if not self.module.check_mode:
+                self.proxmox_api.nodes(vm['node']).qemu(vmid).config.set(**net)
+            return True
 
-    if kwargs['queues']:
-        config_provided += ",queues={0}".format(kwargs['queues'])
+        return False
 
-    if kwargs['rate']:
-        config_provided += ",rate={0}".format(kwargs['rate'])
+    def delete_nic(self, vmid, interface):
+        vm = self.get_vm(vmid)
+        vminfo = self.proxmox_api.nodes(vm['node']).qemu(vmid).config.get()
 
-    if kwargs['tag']:
-        config_provided += ",tag={0}".format(kwargs['tag'])
+        if interface in vminfo:
+            if not self.module.check_mode:
+                self.proxmox_api.nodes(vm['node']).qemu(vmid).config.set(vmid=vmid, delete=interface)
+            return True
 
-    if kwargs['trunks']:
-        config_provided += ",trunks={0}".format(';'.join(str(x) for x in kwargs['trunks']))
-
-    net = {interface: config_provided}
-    vm = get_vm(proxmox, vmid)
-
-    if ((interface not in vminfo) or (vminfo[interface] != config_provided)):
-        if not module.check_mode:
-            proxmox.nodes(vm[0]['node']).qemu(vmid).config.set(**net)
-        return True
-
-    return False
-
-
-def delete_nic(module, proxmox, vmid, interface):
-    vm = get_vm(proxmox, vmid)
-    vminfo = proxmox.nodes(vm[0]['node']).qemu(vmid).config.get()
-
-    if interface in vminfo:
-        if not module.check_mode:
-            proxmox.nodes(vm[0]['node']).qemu(vmid).config.set(vmid=vmid, delete=interface)
-        return True
-
-    return False
+        return False
 
 
 def main():
@@ -281,53 +257,33 @@ def main():
         supports_check_mode=True,
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg='proxmoxer required for this module')
+    proxmox = ProxmoxNicAnsible(module)
 
-    api_host = module.params['api_host']
-    api_password = module.params['api_password']
-    api_token_id = module.params['api_token_id']
-    api_token_secret = module.params['api_token_secret']
-    api_user = module.params['api_user']
     interface = module.params['interface']
     model = module.params['model']
     name = module.params['name']
     state = module.params['state']
-    validate_certs = module.params['validate_certs']
     vmid = module.params['vmid']
 
-    auth_args = {'user': api_user}
-    if not (api_token_id and api_token_secret):
-        auth_args['password'] = api_password
-    else:
-        auth_args['token_name'] = api_token_id
-        auth_args['token_value'] = api_token_secret
-
-    try:
-        proxmox = ProxmoxAPI(api_host, verify_ssl=validate_certs, **auth_args)
-    except Exception as e:
-        module.fail_json(msg='authorization on proxmox cluster failed with exception: %s' % e)
-
     # If vmid is not defined then retrieve its value from the vm name,
     if not vmid:
-        vmid = get_vmid(module, proxmox, name)
+        vmid = proxmox.get_vmid(name)
 
     # Ensure VM id exists
-    if not get_vm(proxmox, vmid):
-        module.fail_json(vmid=vmid, msg='VM with vmid = %s does not exist in cluster' % vmid)
+    proxmox.get_vm(vmid)
 
     if state == 'present':
         try:
-            if update_nic(module, proxmox, vmid, interface, model,
-                          bridge=module.params['bridge'],
-                          firewall=module.params['firewall'],
-                          link_down=module.params['link_down'],
-                          mac=module.params['mac'],
-                          mtu=module.params['mtu'],
-                          queues=module.params['queues'],
-                          rate=module.params['rate'],
-                          tag=module.params['tag'],
-                          trunks=module.params['trunks']):
+            if proxmox.update_nic(vmid, interface, model,
+                                  bridge=module.params['bridge'],
+                                  firewall=module.params['firewall'],
+                                  link_down=module.params['link_down'],
+                                  mac=module.params['mac'],
+                                  mtu=module.params['mtu'],
+                                  queues=module.params['queues'],
+                                  rate=module.params['rate'],
+                                  tag=module.params['tag'],
+                                  trunks=module.params['trunks']):
                 module.exit_json(changed=True, vmid=vmid, msg="Nic {0} updated on VM with vmid {1}".format(interface, vmid))
             else:
                 module.exit_json(vmid=vmid, msg="Nic {0} unchanged on VM with vmid {1}".format(interface, vmid))
@@ -336,7 +292,7 @@ def main():
 
     elif state == 'absent':
         try:
-            if delete_nic(module, proxmox, vmid, interface):
+            if proxmox.delete_nic(vmid, interface):
                 module.exit_json(changed=True, vmid=vmid, msg="Nic {0} deleted on VM with vmid {1}".format(interface, vmid))
             else:
                 module.exit_json(vmid=vmid, msg="Nic {0} does not exist on VM with vmid {1}".format(interface, vmid))

plugins/modules/cloud/misc/proxmox_snap.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-
+#
 # Copyright: (c) 2020, Jeffrey van Pelt (@Thulium-Drake) <jeff@vanpelt.one>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
@@ -16,22 +16,6 @@ description:
   - Allows you to create/delete snapshots from instances in Proxmox VE cluster.
   - Supports both KVM and LXC, OpenVZ has not been tested, as it is no longer supported on Proxmox VE.
 options:
-  api_host:
-    description:
-      - The host of the Proxmox VE cluster.
-    required: true
-    type: str
-  api_user:
-    description:
-      - The user to authenticate with.
-    required: true
-    type: str
-  api_password:
-    description:
-      - The password to authenticate with.
-      - You can use PROXMOX_PASSWORD environment variable.
-    type: str
-    required: yes
   hostname:
     description:
       - The instance name.
@@ -41,11 +25,6 @@ options:
       - The instance id.
       - If not set, will be fetched from PromoxAPI based on the hostname.
     type: str
-  validate_certs:
-    description:
-      - Enable / disable https certificate verification.
-    type: bool
-    default: no
   state:
     description:
      - Indicate desired state of the instance snapshot.
@@ -83,6 +62,8 @@ notes:
   - Supports C(check_mode).
 requirements: [ "proxmoxer", "python >= 2.7", "requests" ]
 author: Jeffrey van Pelt (@Thulium-Drake)
+extends_documentation_fragment:
+    - community.general.proxmox.documentation
 '''
 
 EXAMPLES = r'''
@@ -110,102 +91,76 @@ RETURN = r'''#'''
 import time
 import traceback
 
-PROXMOXER_IMP_ERR = None
-try:
-    from proxmoxer import ProxmoxAPI
-    HAS_PROXMOXER = True
-except ImportError:
-    PROXMOXER_IMP_ERR = traceback.format_exc()
-    HAS_PROXMOXER = False
-
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib, env_fallback
 from ansible.module_utils.common.text.converters import to_native
+from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR)
 
 
-VZ_TYPE = None
+class ProxmoxSnapAnsible(ProxmoxAnsible):
+    def snapshot(self, vm, vmid):
+        return getattr(self.proxmox_api.nodes(vm['node']), vm['type'])(vmid).snapshot
 
-
-def get_vmid(proxmox, hostname):
-    return [vm['vmid'] for vm in proxmox.cluster.resources.get(type='vm') if 'name' in vm and vm['name'] == hostname]
-
-
-def get_instance(proxmox, vmid):
-    return [vm for vm in proxmox.cluster.resources.get(type='vm') if int(vm['vmid']) == int(vmid)]
-
-
-def snapshot_create(module, proxmox, vm, vmid, timeout, snapname, description, vmstate):
-    if module.check_mode:
-        return True
-
-    if VZ_TYPE == 'lxc':
-        taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.post(snapname=snapname, description=description)
-    else:
-        taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.post(snapname=snapname, description=description, vmstate=int(vmstate))
-    while timeout:
-        if (proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['status'] == 'stopped' and
-                proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+    def snapshot_create(self, vm, vmid, timeout, snapname, description, vmstate):
+        if self.module.check_mode:
             return True
-        timeout -= 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for creating VM snapshot. Last line in task before timeout: %s' %
-                                 proxmox.nodes(vm[0]['node']).tasks(taskid).log.get()[:1])
 
-        time.sleep(1)
-    return False
+        if vm['type'] == 'lxc':
+            taskid = self.snapshot(vm, vmid).post(snapname=snapname, description=description)
+        else:
+            taskid = self.snapshot(vm, vmid).post(snapname=snapname, description=description, vmstate=int(vmstate))
+        while timeout:
+            if (self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['status'] == 'stopped' and
+                    self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+                return True
+            timeout -= 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for creating VM snapshot. Last line in task before timeout: %s' %
+                                      self.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1])
 
+            time.sleep(1)
+        return False
 
-def snapshot_remove(module, proxmox, vm, vmid, timeout, snapname, force):
-    if module.check_mode:
-        return True
-
-    taskid = getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.delete(snapname, force=int(force))
-    while timeout:
-        if (proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['status'] == 'stopped' and
-                proxmox.nodes(vm[0]['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+    def snapshot_remove(self, vm, vmid, timeout, snapname, force):
+        if self.module.check_mode:
             return True
-        timeout -= 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for removing VM snapshot. Last line in task before timeout: %s' %
-                                 proxmox.nodes(vm[0]['node']).tasks(taskid).log.get()[:1])
 
-        time.sleep(1)
-    return False
+        taskid = self.snapshot(vm, vmid).delete(snapname, force=int(force))
+        while timeout:
+            if (self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['status'] == 'stopped' and
+                    self.proxmox_api.nodes(vm['node']).tasks(taskid).status.get()['exitstatus'] == 'OK'):
+                return True
+            timeout -= 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for removing VM snapshot. Last line in task before timeout: %s' %
+                                      self.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1])
 
-
-def setup_api(api_host, api_user, api_password, validate_certs):
-    api = ProxmoxAPI(api_host, user=api_user, password=api_password, verify_ssl=validate_certs)
-    return api
+            time.sleep(1)
+        return False
 
 
 def main():
+    module_args = proxmox_auth_argument_spec()
+    snap_args = dict(
+        vmid=dict(required=False),
+        hostname=dict(),
+        timeout=dict(type='int', default=30),
+        state=dict(default='present', choices=['present', 'absent']),
+        description=dict(type='str'),
+        snapname=dict(type='str', default='ansible_snap'),
+        force=dict(type='bool', default='no'),
+        vmstate=dict(type='bool', default='no'),
+    )
+    module_args.update(snap_args)
+
     module = AnsibleModule(
-        argument_spec=dict(
-            api_host=dict(required=True),
-            api_user=dict(required=True),
-            api_password=dict(no_log=True, required=True, fallback=(env_fallback, ['PROXMOX_PASSWORD'])),
-            vmid=dict(required=False),
-            validate_certs=dict(type='bool', default='no'),
-            hostname=dict(),
-            timeout=dict(type='int', default=30),
-            state=dict(default='present', choices=['present', 'absent']),
-            description=dict(type='str'),
-            snapname=dict(type='str', default='ansible_snap'),
-            force=dict(type='bool', default='no'),
-            vmstate=dict(type='bool', default='no'),
-        ),
+        argument_spec=module_args,
         supports_check_mode=True
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('python-proxmoxer'),
-                         exception=PROXMOXER_IMP_ERR)
+    proxmox = ProxmoxSnapAnsible(module)
 
     state = module.params['state']
-    api_user = module.params['api_user']
-    api_host = module.params['api_host']
-    api_password = module.params['api_password']
     vmid = module.params['vmid']
-    validate_certs = module.params['validate_certs']
     hostname = module.params['hostname']
     description = module.params['description']
     snapname = module.params['snapname']
@@ -213,37 +168,21 @@ def main():
     force = module.params['force']
     vmstate = module.params['vmstate']
 
-    try:
-        proxmox = setup_api(api_host, api_user, api_password, validate_certs)
-
-    except Exception as e:
-        module.fail_json(msg='authorization on proxmox cluster failed with exception: %s' % to_native(e))
-
     # If hostname is set get the VM id from ProxmoxAPI
     if not vmid and hostname:
-        hosts = get_vmid(proxmox, hostname)
-        if len(hosts) == 0:
-            module.fail_json(msg="Vmid could not be fetched => Hostname does not exist (action: %s)" % state)
-        vmid = hosts[0]
+        vmid = proxmox.get_vmid(hostname, choose_first_if_multiple=True)
     elif not vmid:
         module.exit_json(changed=False, msg="Vmid could not be fetched for the following action: %s" % state)
 
-    vm = get_instance(proxmox, vmid)
-
-    global VZ_TYPE
-    VZ_TYPE = vm[0]['type']
+    vm = proxmox.get_vm(vmid)
 
     if state == 'present':
         try:
-            vm = get_instance(proxmox, vmid)
-            if not vm:
-                module.fail_json(msg='VM with vmid = %s not exists in cluster' % vmid)
-
-            for i in getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.get():
+            for i in proxmox.snapshot(vm, vmid).get():
                 if i['name'] == snapname:
                     module.exit_json(changed=False, msg="Snapshot %s is already present" % snapname)
 
-            if snapshot_create(module, proxmox, vm, vmid, timeout, snapname, description, vmstate):
+            if proxmox.snapshot_create(vm, vmid, timeout, snapname, description, vmstate):
                 if module.check_mode:
                     module.exit_json(changed=False, msg="Snapshot %s would be created" % snapname)
                 else:
@@ -254,13 +193,9 @@ def main():
 
     elif state == 'absent':
         try:
-            vm = get_instance(proxmox, vmid)
-            if not vm:
-                module.fail_json(msg='VM with vmid = %s not exists in cluster' % vmid)
-
             snap_exist = False
 
-            for i in getattr(proxmox.nodes(vm[0]['node']), VZ_TYPE)(vmid).snapshot.get():
+            for i in proxmox.snapshot(vm, vmid).get():
                 if i['name'] == snapname:
                     snap_exist = True
                     continue
@@ -268,7 +203,7 @@ def main():
             if not snap_exist:
                 module.exit_json(changed=False, msg="Snapshot %s does not exist" % snapname)
             else:
-                if snapshot_remove(module, proxmox, vm, vmid, timeout, snapname, force):
+                if proxmox.snapshot_remove(vm, vmid, timeout, snapname, force):
                     if module.check_mode:
                         module.exit_json(changed=False, msg="Snapshot %s would be removed" % snapname)
                     else:

plugins/modules/cloud/misc/proxmox_storage_info.py

@@ -111,7 +111,7 @@ proxmox_storages:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR, proxmox_to_ansible_bool)
+    proxmox_auth_argument_spec, ProxmoxAnsible, proxmox_to_ansible_bool)
 
 
 class ProxmoxStorageInfoAnsible(ProxmoxAnsible):
@@ -170,9 +170,6 @@ def main():
         changed=False
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
-
     proxmox = ProxmoxStorageInfoAnsible(module)
     storage = module.params['storage']
     storagetype = module.params['type']

plugins/modules/cloud/misc/proxmox_tasks_info.py

@@ -116,7 +116,7 @@ msg:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR)
+    proxmox_auth_argument_spec, ProxmoxAnsible)
 
 
 class ProxmoxTaskInfoAnsible(ProxmoxAnsible):
@@ -163,9 +163,6 @@ def main():
         supports_check_mode=True)
     result = dict(changed=False)
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib(
-            'proxmoxer'), exception=PROXMOXER_IMP_ERR)
     proxmox = ProxmoxTaskInfoAnsible(module)
     upid = module.params['task']
     node = module.params['node']

plugins/modules/cloud/misc/proxmox_template.py

@@ -2,7 +2,6 @@
 # -*- coding: utf-8 -*-
 #
 # Copyright: Ansible Project
-#
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
@@ -117,112 +116,81 @@ EXAMPLES = '''
 import os
 import time
 
-try:
-    from proxmoxer import ProxmoxAPI
-    HAS_PROXMOXER = True
-except ImportError:
-    HAS_PROXMOXER = False
-
 from ansible.module_utils.basic import AnsibleModule, env_fallback
+from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec, ProxmoxAnsible)
 
 
-def get_template(proxmox, node, storage, content_type, template):
-    return [True for tmpl in proxmox.nodes(node).storage(storage).content.get()
-            if tmpl['volid'] == '%s:%s/%s' % (storage, content_type, template)]
+class ProxmoxTemplateAnsible(ProxmoxAnsible):
+    def get_template(self, node, storage, content_type, template):
+        return [True for tmpl in self.proxmox_api.nodes(node).storage(storage).content.get()
+                if tmpl['volid'] == '%s:%s/%s' % (storage, content_type, template)]
 
+    def task_status(self, node, taskid, timeout):
+        """
+        Check the task status and wait until the task is completed or the timeout is reached.
+        """
+        while timeout:
+            task_status = self.proxmox_api.nodes(node).tasks(taskid).status.get()
+            if task_status['status'] == 'stopped' and task_status['exitstatus'] == 'OK':
+                return True
+            timeout = timeout - 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for uploading/downloading template. Last line in task before timeout: %s' %
+                                      self.proxmox_api.node(node).tasks(taskid).log.get()[:1])
 
-def task_status(module, proxmox, node, taskid, timeout):
-    """
-    Check the task status and wait until the task is completed or the timeout is reached.
-    """
-    while timeout:
-        task_status = proxmox.nodes(node).tasks(taskid).status.get()
-        if task_status['status'] == 'stopped' and task_status['exitstatus'] == 'OK':
-            return True
-        timeout = timeout - 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for uploading/downloading template. Last line in task before timeout: %s'
-                                 % proxmox.node(node).tasks(taskid).log.get()[:1])
+            time.sleep(1)
+        return False
 
-        time.sleep(1)
-    return False
+    def upload_template(self, node, storage, content_type, realpath, timeout):
+        taskid = self.proxmox_api.nodes(node).storage(storage).upload.post(content=content_type, filename=open(realpath, 'rb'))
+        return self.task_status(node, taskid, timeout)
 
+    def download_template(self, node, storage, template, timeout):
+        taskid = self.proxmox_api.nodes(node).aplinfo.post(storage=storage, template=template)
+        return self.task_status(node, taskid, timeout)
 
-def upload_template(module, proxmox, node, storage, content_type, realpath, timeout):
-    taskid = proxmox.nodes(node).storage(storage).upload.post(content=content_type, filename=open(realpath, 'rb'))
-    return task_status(module, proxmox, node, taskid, timeout)
+    def delete_template(self, node, storage, content_type, template, timeout):
+        volid = '%s:%s/%s' % (storage, content_type, template)
+        self.proxmox_api.nodes(node).storage(storage).content.delete(volid)
+        while timeout:
+            if not self.get_template(node, storage, content_type, template):
+                return True
+            timeout = timeout - 1
+            if timeout == 0:
+                self.module.fail_json(msg='Reached timeout while waiting for deleting template.')
 
-
-def download_template(module, proxmox, node, storage, template, timeout):
-    taskid = proxmox.nodes(node).aplinfo.post(storage=storage, template=template)
-    return task_status(module, proxmox, node, taskid, timeout)
-
-
-def delete_template(module, proxmox, node, storage, content_type, template, timeout):
-    volid = '%s:%s/%s' % (storage, content_type, template)
-    proxmox.nodes(node).storage(storage).content.delete(volid)
-    while timeout:
-        if not get_template(proxmox, node, storage, content_type, template):
-            return True
-        timeout = timeout - 1
-        if timeout == 0:
-            module.fail_json(msg='Reached timeout while waiting for deleting template.')
-
-        time.sleep(1)
-    return False
+            time.sleep(1)
+        return False
 
 
 def main():
+    module_args = proxmox_auth_argument_spec()
+    template_args = dict(
+        node=dict(),
+        src=dict(type='path'),
+        template=dict(),
+        content_type=dict(default='vztmpl', choices=['vztmpl', 'iso']),
+        storage=dict(default='local'),
+        timeout=dict(type='int', default=30),
+        force=dict(type='bool', default=False),
+        state=dict(default='present', choices=['present', 'absent']),
+    )
+    module_args.update(template_args)
+
     module = AnsibleModule(
-        argument_spec=dict(
-            api_host=dict(required=True),
-            api_password=dict(no_log=True, fallback=(env_fallback, ['PROXMOX_PASSWORD'])),
-            api_token_id=dict(no_log=True),
-            api_token_secret=dict(no_log=True),
-            api_user=dict(required=True),
-            validate_certs=dict(type='bool', default=False),
-            node=dict(),
-            src=dict(type='path'),
-            template=dict(),
-            content_type=dict(default='vztmpl', choices=['vztmpl', 'iso']),
-            storage=dict(default='local'),
-            timeout=dict(type='int', default=30),
-            force=dict(type='bool', default=False),
-            state=dict(default='present', choices=['present', 'absent']),
-        ),
+        argument_spec=module_args,
         required_together=[('api_token_id', 'api_token_secret')],
         required_one_of=[('api_password', 'api_token_id')],
         required_if=[('state', 'absent', ['template'])]
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg='proxmoxer required for this module')
+    proxmox = ProxmoxTemplateAnsible(module)
 
     state = module.params['state']
-    api_host = module.params['api_host']
-    api_password = module.params['api_password']
-    api_token_id = module.params['api_token_id']
-    api_token_secret = module.params['api_token_secret']
-    api_user = module.params['api_user']
-    validate_certs = module.params['validate_certs']
     node = module.params['node']
     storage = module.params['storage']
     timeout = module.params['timeout']
 
-    auth_args = {'user': api_user}
-    if not (api_token_id and api_token_secret):
-        auth_args['password'] = api_password
-    else:
-        auth_args['token_name'] = api_token_id
-        auth_args['token_value'] = api_token_secret
-
-    try:
-        proxmox = ProxmoxAPI(api_host, verify_ssl=validate_certs, **auth_args)
-        # Used to test the validity of the token if given
-        proxmox.version.get()
-    except Exception as e:
-        module.fail_json(msg='authorization on proxmox cluster failed with exception: %s' % e)
-
     if state == 'present':
         try:
             content_type = module.params['content_type']
@@ -235,21 +203,21 @@ def main():
                 if not template:
                     module.fail_json(msg='template param for downloading appliance template is mandatory')
 
-                if get_template(proxmox, node, storage, content_type, template) and not module.params['force']:
+                if proxmox.get_template(node, storage, content_type, template) and not module.params['force']:
                     module.exit_json(changed=False, msg='template with volid=%s:%s/%s already exists' % (storage, content_type, template))
 
-                if download_template(module, proxmox, node, storage, template, timeout):
+                if proxmox.download_template(node, storage, template, timeout):
                     module.exit_json(changed=True, msg='template with volid=%s:%s/%s downloaded' % (storage, content_type, template))
 
             template = os.path.basename(src)
-            if get_template(proxmox, node, storage, content_type, template) and not module.params['force']:
+            if proxmox.get_template(node, storage, content_type, template) and not module.params['force']:
                 module.exit_json(changed=False, msg='template with volid=%s:%s/%s is already exists' % (storage, content_type, template))
             elif not src:
                 module.fail_json(msg='src param to uploading template file is mandatory')
             elif not (os.path.exists(src) and os.path.isfile(src)):
                 module.fail_json(msg='template file on path %s not exists' % src)
 
-            if upload_template(module, proxmox, node, storage, content_type, src, timeout):
+            if proxmox.upload_template(node, storage, content_type, src, timeout):
                 module.exit_json(changed=True, msg='template with volid=%s:%s/%s uploaded' % (storage, content_type, template))
         except Exception as e:
             module.fail_json(msg="uploading/downloading of template %s failed with exception: %s" % (template, e))
@@ -259,10 +227,10 @@ def main():
             content_type = module.params['content_type']
             template = module.params['template']
 
-            if not get_template(proxmox, node, storage, content_type, template):
+            if not proxmox.get_template(node, storage, content_type, template):
                 module.exit_json(changed=False, msg='template with volid=%s:%s/%s is already deleted' % (storage, content_type, template))
 
-            if delete_template(module, proxmox, node, storage, content_type, template, timeout):
+            if proxmox.delete_template(node, storage, content_type, template, timeout):
                 module.exit_json(changed=True, msg='template with volid=%s:%s/%s deleted' % (storage, content_type, template))
         except Exception as e:
             module.fail_json(msg="deleting of template %s failed with exception: %s" % (template, e))

plugins/modules/cloud/misc/proxmox_user_info.py

@@ -156,7 +156,7 @@ proxmox_users:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, proxmox_to_ansible_bool, HAS_PROXMOXER, PROXMOXER_IMP_ERR)
+    proxmox_auth_argument_spec, ProxmoxAnsible, proxmox_to_ansible_bool)
 
 
 class ProxmoxUserInfoAnsible(ProxmoxAnsible):
@@ -232,9 +232,6 @@ def main():
         changed=False
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
-
     proxmox = ProxmoxUserInfoAnsible(module)
     domain = module.params['domain']
     user = module.params['user']

plugins/modules/cloud/misc/terraform.py

@@ -443,7 +443,7 @@ def main():
     for k, v in variables.items():
         variables_args.extend([
             '-var',
-            '{0}={1}'.format(k, v)
+            '{0}={1}'.format(k, json.dumps(v))
         ])
     if variables_files:
         for f in variables_files:

plugins/modules/cloud/opennebula/one_vm.py

@@ -1260,6 +1260,11 @@ def resume_vm(module, client, vm):
     vm = client.vm.info(vm.ID)
     changed = False
 
+    state = vm.STATE
+    if state in [VM_STATES.index('HOLD')]:
+        changed = release_vm(module, client, vm)
+        return changed
+
     lcm_state = vm.LCM_STATE
     if lcm_state == LCM_STATES.index('SHUTDOWN_POWEROFF'):
         module.fail_json(msg="Cannot perform action 'resume' because this action is not available " +
@@ -1282,6 +1287,23 @@ def resume_vms(module, client, vms):
     return changed
 
 
+def release_vm(module, client, vm):
+    vm = client.vm.info(vm.ID)
+    changed = False
+
+    state = vm.STATE
+    if state != VM_STATES.index('HOLD'):
+        module.fail_json(msg="Cannot perform action 'release' because this action is not available " +
+                         "because VM is not in state 'HOLD'.")
+    else:
+        changed = True
+
+    if changed and not module.check_mode:
+        client.vm.action('release', vm.ID)
+
+    return changed
+
+
 def check_name_attribute(module, attributes):
     if attributes.get("NAME"):
         import re

plugins/modules/cloud/rackspace/rax_cdb.py

@@ -42,7 +42,7 @@ options:
     description:
       - version of database (MySQL supports 5.1 and 5.6, MariaDB supports 10, Percona supports 5.6)
       - "The available choices are: C(5.1), C(5.6) and  C(10)."
-    default: 5.6
+    default: '5.6'
     aliases: ['version']
   state:
     type: str

plugins/modules/cloud/scaleway/scaleway_private_network.py

@@ -0,0 +1,234 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+#
+# Scaleway VPC management module
+#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: scaleway_private_network
+short_description: Scaleway private network management
+version_added: 4.5.0
+author: Pascal MANGIN (@pastral)
+description:
+    - This module manages private network on Scaleway account
+      (U(https://developer.scaleway.com)).
+extends_documentation_fragment:
+- community.general.scaleway
+
+
+options:
+  state:
+    type: str
+    description:
+     - Indicate desired state of the VPC.
+    default: present
+    choices:
+      - present
+      - absent
+
+  project:
+    type: str
+    description:
+      - Project identifier.
+    required: true
+
+  region:
+    type: str
+    description:
+     - Scaleway region to use (for example C(par1)).
+    required: true
+    choices:
+      - ams1
+      - EMEA-NL-EVS
+      - par1
+      - EMEA-FR-PAR1
+      - par2
+      - EMEA-FR-PAR2
+      - waw1
+      - EMEA-PL-WAW1
+
+  name:
+    type: str
+    description:
+    - Name of the VPC.
+
+  tags:
+    type: list
+    elements: str
+    description:
+    - List of tags to apply to the instance.
+    default: []
+
+'''
+
+EXAMPLES = '''
+- name: Create an private network
+  community.general.scaleway_vpc:
+    project: '{{ scw_project }}'
+    name: 'vpc_one'
+    state: present
+    region: par1
+  register: vpc_creation_task
+
+- name: Make sure private network with name 'foo' is deleted in region par1
+  community.general.scaleway_vpc:
+    name: 'foo'
+    state: absent
+    region: par1
+'''
+
+RETURN = '''
+scaleway_private_network:
+    description: Information on the VPC.
+    returned: success when C(state=present)
+    type: dict
+    sample:
+        {
+            "created_at": "2022-01-15T11:11:12.676445Z",
+            "id": "12345678-f1e6-40ec-83e5-12345d67ed89",
+            "name": "network",
+            "organization_id": "a123b4cd-ef5g-678h-90i1-jk2345678l90",
+            "project_id": "a123b4cd-ef5g-678h-90i1-jk2345678l90",
+            "tags": [
+                "tag1",
+                "tag2",
+                "tag3",
+                "tag4",
+                "tag5"
+            ],
+            "updated_at": "2022-01-15T11:12:04.624837Z",
+            "zone": "fr-par-2"
+        }
+'''
+
+from ansible_collections.community.general.plugins.module_utils.scaleway import SCALEWAY_LOCATION, scaleway_argument_spec, Scaleway
+from ansible.module_utils.basic import AnsibleModule
+
+
+def get_private_network(api, name, page=1):
+    page_size = 10
+    response = api.get('private-networks', params={'name': name, 'order_by': 'name_asc', 'page': page, 'page_size': page_size})
+    if not response.ok:
+        msg = "Error during get private network creation: %s: '%s' (%s)" % (response.info['msg'], response.json['message'], response.json)
+        api.module.fail_json(msg=msg)
+
+    if response.json['total_count'] == 0:
+        return None
+
+    i = 0
+    while i < len(response.json['private_networks']):
+        if response.json['private_networks'][i]['name'] == name:
+            return response.json['private_networks'][i]
+        i += 1
+
+    # search on next page if needed
+    if (page * page_size) < response.json['total_count']:
+        return get_private_network(api, name, page + 1)
+
+    return None
+
+
+def present_strategy(api, wished_private_network):
+
+    changed = False
+    private_network = get_private_network(api, wished_private_network['name'])
+    if private_network is not None:
+        if set(wished_private_network['tags']) == set(private_network['tags']):
+            return changed, private_network
+        else:
+            # private network need to be updated
+            data = {'name': wished_private_network['name'],
+                    'tags': wished_private_network['tags']
+                    }
+            changed = True
+            if api.module.check_mode:
+                return changed, {"status": "private network would be updated"}
+
+            response = api.patch(path='private-networks/' + private_network['id'], data=data)
+            if not response.ok:
+                api.module.fail_json(msg='Error updating private network [{0}: {1}]'.format(response.status_code, response.json))
+
+            return changed, response.json
+
+    # private network need to be create
+    changed = True
+    if api.module.check_mode:
+        return changed, {"status": "private network would be created"}
+
+    data = {'name': wished_private_network['name'],
+            'project_id': wished_private_network['project'],
+            'tags': wished_private_network['tags']
+            }
+
+    response = api.post(path='private-networks/', data=data)
+
+    if not response.ok:
+        api.module.fail_json(msg='Error creating private network [{0}: {1}]'.format(response.status_code, response.json))
+
+    return changed, response.json
+
+
+def absent_strategy(api, wished_private_network):
+
+    changed = False
+    private_network = get_private_network(api, wished_private_network['name'])
+    if private_network is None:
+        return changed, {}
+
+    changed = True
+    if api.module.check_mode:
+        return changed, {"status": "private network would be destroyed"}
+
+    response = api.delete('private-networks/' + private_network['id'])
+
+    if not response.ok:
+        api.module.fail_json(msg='Error deleting private network [{0}: {1}]'.format(
+            response.status_code, response.json))
+
+    return changed, response.json
+
+
+def core(module):
+
+    wished_private_network = {
+        "project": module.params['project'],
+        "tags": module.params['tags'],
+        "name": module.params['name']
+    }
+
+    region = module.params["region"]
+    module.params['api_url'] = SCALEWAY_LOCATION[region]["api_endpoint_vpc"]
+
+    api = Scaleway(module=module)
+    if module.params["state"] == "absent":
+        changed, summary = absent_strategy(api=api, wished_private_network=wished_private_network)
+    else:
+        changed, summary = present_strategy(api=api, wished_private_network=wished_private_network)
+    module.exit_json(changed=changed, scaleway_private_network=summary)
+
+
+def main():
+    argument_spec = scaleway_argument_spec()
+    argument_spec.update(dict(
+        state=dict(default='present', choices=['absent', 'present']),
+        project=dict(required=True),
+        region=dict(required=True, choices=list(SCALEWAY_LOCATION.keys())),
+        tags=dict(type="list", elements="str", default=[]),
+        name=dict()
+    ))
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+    )
+
+    core(module)
+
+
+if __name__ == '__main__':
+    main()

plugins/modules/database/misc/redis.py

@@ -13,6 +13,8 @@ module: redis
 short_description: Various redis commands, replica and flush
 description:
    - Unified utility to interact with redis instances.
+extends_documentation_fragment:
+   - community.general.redis
 options:
     command:
         description:
@@ -22,20 +24,15 @@ options:
             - C(replica) sets a redis instance in replica or master mode. (C(slave) is an alias for C(replica).)
         choices: [ config, flush, replica, slave ]
         type: str
-    login_password:
-        description:
-            - The password used to authenticate with (usually not used)
-        type: str
-    login_host:
-        description:
-            - The host running the database
-        default: localhost
-        type: str
-    login_port:
-        description:
-            - The port to connect to
-        default: 6379
-        type: int
+    tls:
+        default: false
+        version_added: 4.6.0
+    login_user:
+        version_added: 4.6.0
+    validate_certs:
+        version_added: 4.6.0
+    ca_certs:
+        version_added: 4.6.0
     master_host:
         description:
             - The host of the master instance [replica command]
@@ -144,6 +141,8 @@ else:
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible.module_utils.common.text.formatters import human_to_bytes
 from ansible.module_utils.common.text.converters import to_native
+from ansible_collections.community.general.plugins.module_utils.redis import (
+    fail_imports, redis_auth_argument_spec, redis_auth_params)
 import re
 
 
@@ -175,29 +174,28 @@ def flush(client, db=None):
 
 # Module execution.
 def main():
+    redis_auth_args = redis_auth_argument_spec(tls_default=False)
+    module_args = dict(
+        command=dict(type='str', choices=['config', 'flush', 'replica', 'slave']),
+        master_host=dict(type='str'),
+        master_port=dict(type='int'),
+        replica_mode=dict(type='str', default='replica', choices=['master', 'replica', 'slave'],
+                          aliases=["slave_mode"]),
+        db=dict(type='int'),
+        flush_mode=dict(type='str', default='all', choices=['all', 'db']),
+        name=dict(type='str'),
+        value=dict(type='str'),
+    )
+    module_args.update(redis_auth_args)
     module = AnsibleModule(
-        argument_spec=dict(
-            command=dict(type='str', choices=['config', 'flush', 'replica', 'slave']),
-            login_password=dict(type='str', no_log=True),
-            login_host=dict(type='str', default='localhost'),
-            login_port=dict(type='int', default=6379),
-            master_host=dict(type='str'),
-            master_port=dict(type='int'),
-            replica_mode=dict(type='str', default='replica', choices=['master', 'replica', 'slave'], aliases=["slave_mode"]),
-            db=dict(type='int'),
-            flush_mode=dict(type='str', default='all', choices=['all', 'db']),
-            name=dict(type='str'),
-            value=dict(type='str')
-        ),
+        argument_spec=module_args,
         supports_check_mode=True,
     )
 
-    if not redis_found:
-        module.fail_json(msg=missing_required_lib('redis'), exception=REDIS_IMP_ERR)
+    fail_imports(module, module.params['tls'])
+
+    redis_params = redis_auth_params(module)
 
-    login_password = module.params['login_password']
-    login_host = module.params['login_host']
-    login_port = module.params['login_port']
     command = module.params['command']
     if command == "slave":
         command = "replica"
@@ -219,7 +217,7 @@ def main():
                 module.fail_json(msg='In replica mode master port must be provided')
 
         # Connect and check
-        r = redis.StrictRedis(host=login_host, port=login_port, password=login_password)
+        r = redis.StrictRedis(**redis_params)
         try:
             r.ping()
         except Exception as e:
@@ -270,7 +268,7 @@ def main():
                 module.fail_json(msg="In db mode the db number must be provided")
 
         # Connect and check
-        r = redis.StrictRedis(host=login_host, port=login_port, password=login_password, db=db)
+        r = redis.StrictRedis(db=db, **redis_params)
         try:
             r.ping()
         except Exception as e:
@@ -301,7 +299,7 @@ def main():
         except ValueError:
             value = module.params['value']
 
-        r = redis.StrictRedis(host=login_host, port=login_port, password=login_password)
+        r = redis.StrictRedis(**redis_params)
 
         try:
             r.ping()

plugins/modules/database/vertica/vertica_info.py

@@ -25,7 +25,7 @@ options:
   port:
     description:
       Database port to connect to.
-    default: 5433
+    default: '5433'
     type: str
   db:
     description:

plugins/modules/database/vertica/vertica_role.py

@@ -44,7 +44,7 @@ options:
   port:
     description:
       - Vertica cluster port to connect to.
-    default: 5433
+    default: '5433'
     type: str
   login_user:
     description:

plugins/modules/database/vertica/vertica_schema.py

@@ -58,7 +58,7 @@ options:
   port:
     description:
       - Vertica cluster port to connect to.
-    default: 5433
+    default: '5433'
     type: str
   login_user:
     description: