diff --git a/.azure-pipelines/azure-pipelines.yml b/.azure-pipelines/azure-pipelines.yml
index 97f76b3ba9..610bce0533 100644
--- a/.azure-pipelines/azure-pipelines.yml
+++ b/.azure-pipelines/azure-pipelines.yml
@@ -29,22 +29,20 @@ schedules:
always: true
branches:
include:
+ - stable-10
- stable-9
- - stable-8
- cron: 0 11 * * 0
displayName: Weekly (old stable branches)
always: true
branches:
include:
- - stable-7
+ - stable-8
variables:
- name: checkoutPath
value: ansible_collections/community/general
- name: coverageBranches
value: main
- - name: pipelinesCoverage
- value: coverage
- name: entryPoint
value: tests/utils/shippable/shippable.sh
- name: fetchDepth
@@ -172,10 +170,10 @@ stages:
parameters:
testFormat: devel/{0}
targets:
- - name: Alpine 3.20
- test: alpine/3.20
- # - name: Fedora 40
- # test: fedora/40
+ - name: Alpine 3.21
+ test: alpine/3.21
+ # - name: Fedora 41
+ # test: fedora/41
- name: Ubuntu 22.04
test: ubuntu/22.04
- name: Ubuntu 24.04
@@ -190,12 +188,14 @@ stages:
parameters:
testFormat: devel/{0}
targets:
- - name: macOS 14.3
- test: macos/14.3
- - name: RHEL 9.4
- test: rhel/9.4
- - name: FreeBSD 14.1
- test: freebsd/14.1
+ - name: macOS 15.3
+ test: macos/15.3
+ - name: RHEL 9.5
+ test: rhel/9.5
+ - name: FreeBSD 14.2
+ test: freebsd/14.2
+ - name: FreeBSD 13.5
+ test: freebsd/13.5
groups:
- 1
- 2
@@ -208,8 +208,12 @@ stages:
parameters:
testFormat: 2.18/{0}
targets:
+ - name: macOS 14.3
+ test: macos/14.3
- name: RHEL 9.4
test: rhel/9.4
+ - name: FreeBSD 14.1
+ test: freebsd/14.1
groups:
- 1
- 2
@@ -264,10 +268,10 @@ stages:
parameters:
testFormat: devel/linux/{0}
targets:
- - name: Fedora 40
- test: fedora40
- - name: Alpine 3.20
- test: alpine320
+ - name: Fedora 41
+ test: fedora41
+ - name: Alpine 3.21
+ test: alpine321
- name: Ubuntu 22.04
test: ubuntu2204
- name: Ubuntu 24.04
@@ -284,6 +288,10 @@ stages:
parameters:
testFormat: 2.18/linux/{0}
targets:
+ - name: Fedora 40
+ test: fedora40
+ - name: Alpine 3.20
+ test: alpine320
- name: Ubuntu 24.04
test: ubuntu2404
groups:
@@ -343,7 +351,7 @@ stages:
- name: Debian Bookworm
test: debian-bookworm/3.11
- name: ArchLinux
- test: archlinux/3.12
+ test: archlinux/3.13
groups:
- 1
- 2
diff --git a/.azure-pipelines/templates/coverage.yml b/.azure-pipelines/templates/coverage.yml
index 3c8841aa26..1bf17e053a 100644
--- a/.azure-pipelines/templates/coverage.yml
+++ b/.azure-pipelines/templates/coverage.yml
@@ -28,16 +28,6 @@ jobs:
- bash: .azure-pipelines/scripts/report-coverage.sh
displayName: Generate Coverage Report
condition: gt(variables.coverageFileCount, 0)
- - task: PublishCodeCoverageResults@1
- inputs:
- codeCoverageTool: Cobertura
- # Azure Pipelines only accepts a single coverage data file.
- # That means only Python or PowerShell coverage can be uploaded, but not both.
- # Set the "pipelinesCoverage" variable to determine which type is uploaded.
- # Use "coverage" for Python and "coverage-powershell" for PowerShell.
- summaryFileLocation: "$(outputPath)/reports/$(pipelinesCoverage).xml"
- displayName: Publish to Azure Pipelines
- condition: gt(variables.coverageFileCount, 0)
- bash: .azure-pipelines/scripts/publish-codecov.py "$(outputPath)"
displayName: Publish to codecov.io
condition: gt(variables.coverageFileCount, 0)
diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml
index 989752a0a7..c92ce76034 100644
--- a/.github/BOTMETA.yml
+++ b/.github/BOTMETA.yml
@@ -111,6 +111,9 @@ files:
$connections/lxd.py:
labels: lxd
maintainers: mattclay
+ $connections/proxmox_pct_remote.py:
+ labels: proxmox
+ maintainers: mietzen
$connections/qubes.py:
maintainers: kushaldas
$connections/saltstack.py:
@@ -120,6 +123,8 @@ files:
maintainers: $team_ansible_core
$doc_fragments/:
labels: docs_fragments
+ $doc_fragments/clc.py:
+ maintainers: clc-runner russoz
$doc_fragments/django.py:
maintainers: russoz
$doc_fragments/hpe3par.py:
@@ -135,6 +140,8 @@ files:
$doc_fragments/xenserver.py:
labels: xenserver
maintainers: bvitnik
+ $filters/accumulate.py:
+ maintainers: VannTen
$filters/counter.py:
maintainers: keilr
$filters/crc32.py:
@@ -157,6 +164,14 @@ files:
maintainers: Ajpantuso
$filters/jc.py:
maintainers: kellyjonbrazil
+ $filters/json_diff.yml:
+ maintainers: numo68
+ $filters/json_patch.py:
+ maintainers: numo68
+ $filters/json_patch.yml:
+ maintainers: numo68
+ $filters/json_patch_recipe.yml:
+ maintainers: numo68
$filters/json_query.py: {}
$filters/keep_keys.py:
maintainers: vbotka
@@ -211,6 +226,8 @@ files:
maintainers: opoplawski
$inventories/gitlab_runners.py:
maintainers: morph027
+ $inventories/iocage.py:
+ maintainers: vbotka
$inventories/icinga2.py:
maintainers: BongoEADGC6
$inventories/linode.py:
@@ -290,6 +307,8 @@ files:
$lookups/onepassword_raw.py:
ignore: scottsb
maintainers: azenk
+ $lookups/onepassword_ssh_key.py:
+ maintainers: mohammedbabelly20
$lookups/passwordstore.py: {}
$lookups/random_pet.py:
maintainers: Akasurde
@@ -307,6 +326,8 @@ files:
maintainers: delineaKrehl tylerezimmerman
$module_utils/:
labels: module_utils
+ $module_utils/android_sdkmanager.py:
+ maintainers: shamilovstas
$module_utils/btrfs.py:
maintainers: gnfzdz
$module_utils/cmd_runner_fmt.py:
@@ -357,6 +378,8 @@ files:
$module_utils/oracle/oci_utils.py:
labels: cloud
maintainers: $team_oracle
+ $module_utils/pacemaker.py:
+ maintainers: munchtoast
$module_utils/pipx.py:
labels: pipx
maintainers: russoz
@@ -381,6 +404,8 @@ files:
maintainers: russoz
$module_utils/ssh.py:
maintainers: russoz
+ $module_utils/systemd.py:
+ maintainers: NomakCooper
$module_utils/storage/hpe3par/hpe3par.py:
maintainers: farhan7500 gautamphegde
$module_utils/utm_utils.py:
@@ -418,6 +443,8 @@ files:
ignore: DavidWittman jiuka
labels: alternatives
maintainers: mulby
+ $modules/android_sdk.py:
+ maintainers: shamilovstas
$modules/ansible_galaxy_install.py:
maintainers: russoz
$modules/apache2_mod_proxy.py:
@@ -448,7 +475,7 @@ files:
$modules/bearychat.py:
maintainers: tonyseek
$modules/bigpanda.py:
- maintainers: hkariti
+ ignore: hkariti
$modules/bitbucket_:
maintainers: catcombo
$modules/bootc_manage.py:
@@ -506,6 +533,8 @@ files:
ignore: skornehl
$modules/dconf.py:
maintainers: azaghal
+ $modules/decompress.py:
+ maintainers: shamilovstas
$modules/deploy_helper.py:
maintainers: ramondelafuente
$modules/dimensiondata_network.py:
@@ -846,6 +875,8 @@ files:
maintainers: drybjed jtyr noles
$modules/ldap_entry.py:
maintainers: jtyr
+ $modules/ldap_inc.py:
+ maintainers: pduveau
$modules/ldap_passwd.py:
maintainers: KellerFuchs jtyr
$modules/ldap_search.py:
@@ -1027,6 +1058,8 @@ files:
maintainers: fraff
$modules/pacemaker_cluster.py:
maintainers: matbu
+ $modules/pacemaker_resource.py:
+ maintainers: munchtoast
$modules/packet_:
maintainers: nurfet-becirevic t0mk
$modules/packet_device.py:
@@ -1117,6 +1150,10 @@ files:
$modules/proxmox_kvm.py:
ignore: skvidal
maintainers: helldorado krauthosting
+ $modules/proxmox_backup.py:
+ maintainers: IamLunchbox
+ $modules/proxmox_backup_info.py:
+ maintainers: raoufnezhad mmayabi
$modules/proxmox_nic.py:
maintainers: Kogelvis krauthosting
$modules/proxmox_node_info.py:
@@ -1329,6 +1366,12 @@ files:
maintainers: precurse
$modules/sysrc.py:
maintainers: dlundgren
+ $modules/systemd_creds_decrypt.py:
+ maintainers: konstruktoid
+ $modules/systemd_creds_encrypt.py:
+ maintainers: konstruktoid
+ $modules/systemd_info.py:
+ maintainers: NomakCooper
$modules/sysupgrade.py:
maintainers: precurse
$modules/taiga_issue.py:
@@ -1360,16 +1403,19 @@ files:
keywords: sophos utm
maintainers: $team_e_spirit
$modules/utm_ca_host_key_cert.py:
- maintainers: stearz
+ ignore: stearz
+ maintainers: $team_e_spirit
$modules/utm_ca_host_key_cert_info.py:
- maintainers: stearz
+ ignore: stearz
+ maintainers: $team_e_spirit
$modules/utm_network_interface_address.py:
maintainers: steamx
$modules/utm_network_interface_address_info.py:
maintainers: steamx
$modules/utm_proxy_auth_profile.py:
keywords: sophos utm
- maintainers: $team_e_spirit stearz
+ ignore: stearz
+ maintainers: $team_e_spirit
$modules/utm_proxy_exception.py:
keywords: sophos utm
maintainers: $team_e_spirit RickS-C137
@@ -1505,6 +1551,8 @@ files:
maintainers: baldwinSPC nurfet-becirevic t0mk teebes
docs/docsite/rst/guide_scaleway.rst:
maintainers: $team_scaleway
+ docs/docsite/rst/guide_uthelper.rst:
+ maintainers: russoz
docs/docsite/rst/guide_vardict.rst:
maintainers: russoz
docs/docsite/rst/test_guide.rst:
@@ -1559,6 +1607,6 @@ macros:
team_rhsm: cnsnyder ptoscano
team_scaleway: remyleone abarbare
team_solaris: bcoca fishman jasperla jpdasma mator scathatheworm troy2914 xen0l
- team_suse: commel evrardjp lrupp toabctl AnderEnder alxgu andytom sealor
+ team_suse: commel evrardjp lrupp AnderEnder alxgu andytom sealor
team_virt: joshainglis karmab Thulium-Drake Ajpantuso
team_wdc: mikemoerk
diff --git a/.github/workflows/ansible-test.yml b/.github/workflows/ansible-test.yml
index ca06791a38..c5b26dba9a 100644
--- a/.github/workflows/ansible-test.yml
+++ b/.github/workflows/ansible-test.yml
@@ -45,6 +45,8 @@ jobs:
coverage: ${{ github.event_name == 'schedule' && 'always' || 'never' }}
pull-request-change-detection: 'true'
testing-type: sanity
+ pre-test-cmd: >-
+ git clone --depth=1 --single-branch https://github.com/ansible-collections/community.internal_test_tools.git ../../community/internal_test_tools
units:
# Ansible-test on various stable branches does not yet work well with cgroups v2.
@@ -171,6 +173,8 @@ jobs:
;
git clone --depth=1 --single-branch https://github.com/ansible-collections/community.crypto.git ../../community/crypto
;
+ git clone --depth=1 --single-branch https://github.com/ansible-collections/community.docker.git ../../community/docker
+ ;
git clone --depth=1 --single-branch https://github.com/ansible-collections/community.internal_test_tools.git ../../community/internal_test_tools
pull-request-change-detection: 'true'
target: ${{ matrix.target }}
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
index c93162a72a..e8572fafb6 100644
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -25,6 +25,8 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@v4
+ with:
+ persist-credentials: false
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
diff --git a/.github/workflows/reuse.yml b/.github/workflows/reuse.yml
index e5195f6dcf..3c5e986e57 100644
--- a/.github/workflows/reuse.yml
+++ b/.github/workflows/reuse.yml
@@ -28,7 +28,8 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
+ persist-credentials: false
ref: ${{ github.event.pull_request.head.sha || '' }}
- name: REUSE Compliance Check
- uses: fsfe/reuse-action@v4
+ uses: fsfe/reuse-action@v5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b35c52441b..3608353706 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,993 @@
-# Placeholder changelog
+# Community General Release Notes
-This file is a placeholder; a version-specific `CHANGELOG-vX.md` will be generated during releases from fragments
-under `changelogs/fragments`. On release branches once a release has been created, consult the branch's version-specific
-file for changes that have occurred in that branch.
+**Topics**
+
+- v10\.5\.0
+ - Release Summary
+ - Minor Changes
+ - Bugfixes
+ - New Modules
+- v10\.4\.0
+ - Release Summary
+ - Minor Changes
+ - Deprecated Features
+ - Bugfixes
+ - New Modules
+- v10\.3\.1
+ - Release Summary
+ - Minor Changes
+ - Bugfixes
+- v10\.3\.0
+ - Release Summary
+ - Minor Changes
+ - Deprecated Features
+ - Security Fixes
+ - Bugfixes
+ - New Plugins
+ - Connection
+ - Filter
+ - Lookup
+ - New Modules
+- v10\.2\.0
+ - Release Summary
+ - Minor Changes
+ - Deprecated Features
+ - Security Fixes
+ - Bugfixes
+ - New Plugins
+ - Inventory
+ - New Modules
+- v10\.1\.0
+ - Release Summary
+ - Minor Changes
+ - Deprecated Features
+ - Bugfixes
+ - New Plugins
+ - Filter
+ - New Modules
+- v10\.0\.1
+ - Release Summary
+ - Bugfixes
+- v10\.0\.0
+ - Release Summary
+ - Minor Changes
+ - Breaking Changes / Porting Guide
+ - Deprecated Features
+ - Removed Features \(previously deprecated\)
+ - Bugfixes
+ - Known Issues
+ - New Plugins
+ - Filter
+ - Test
+ - New Modules
+This changelog describes changes after version 9\.0\.0\.
+
+
+## v10\.5\.0
+
+
+### Release Summary
+
+Regular bugfix and feature release\.
+
+
+### Minor Changes
+
+* CmdRunner module utils \- the convenience method cmd\_runner\_fmt\.as\_fixed\(\)
now accepts multiple arguments as a list \([https\://github\.com/ansible\-collections/community\.general/pull/9893](https\://github\.com/ansible\-collections/community\.general/pull/9893)\)\.
+* apache2\_mod\_proxy \- code simplification\, no change in functionality \([https\://github\.com/ansible\-collections/community\.general/pull/9457](https\://github\.com/ansible\-collections/community\.general/pull/9457)\)\.
+* consul\_token \- fix idempotency when policies
or roles
are supplied by name \([https\://github\.com/ansible\-collections/community\.general/issues/9841](https\://github\.com/ansible\-collections/community\.general/issues/9841)\, [https\://github\.com/ansible\-collections/community\.general/pull/9845](https\://github\.com/ansible\-collections/community\.general/pull/9845)\)\.
+* keycloak\_realm \- remove ID requirement when creating a realm to allow Keycloak generating its own realm ID \([https\://github\.com/ansible\-collections/community\.general/pull/9768](https\://github\.com/ansible\-collections/community\.general/pull/9768)\)\.
+* nmap inventory plugin \- adds dns\_servers
option for specifying DNS servers for name resolution\. Accepts hostnames or IP addresses in the same format as the exclude
option \([https\://github\.com/ansible\-collections/community\.general/pull/9849](https\://github\.com/ansible\-collections/community\.general/pull/9849)\)\.
+* proxmox\_kvm \- add missing audio hardware device handling \([https\://github\.com/ansible\-collections/community\.general/issues/5192](https\://github\.com/ansible\-collections/community\.general/issues/5192)\, [https\://github\.com/ansible\-collections/community\.general/pull/9847](https\://github\.com/ansible\-collections/community\.general/pull/9847)\)\.
+* redfish\_config \- add command SetPowerRestorePolicy
to set the desired power state of the system when power is restored \([https\://github\.com/ansible\-collections/community\.general/pull/9837](https\://github\.com/ansible\-collections/community\.general/pull/9837)\)\.
+* redfish\_info \- add command GetPowerRestorePolicy
to get the desired power state of the system when power is restored \([https\://github\.com/ansible\-collections/community\.general/pull/9824](https\://github\.com/ansible\-collections/community\.general/pull/9824)\)\.
+* rocketchat \- option is\_pre740
has been added to control the format of the payload\. For Rocket\.Chat 7\.4\.0 or newer\, it must be set to false
\([https\://github\.com/ansible\-collections/community\.general/pull/9882](https\://github\.com/ansible\-collections/community\.general/pull/9882)\)\.
+* slack callback plugin \- add http\_agent
option to enable the user to set a custom user agent for slack callback plugin \([https\://github\.com/ansible\-collections/community\.general/issues/9813](https\://github\.com/ansible\-collections/community\.general/issues/9813)\, [https\://github\.com/ansible\-collections/community\.general/pull/9836](https\://github\.com/ansible\-collections/community\.general/pull/9836)\)\.
+* systemd\_info \- add wildcard expression support in unitname
option \([https\://github\.com/ansible\-collections/community\.general/pull/9821](https\://github\.com/ansible\-collections/community\.general/pull/9821)\)\.
+* systemd\_info \- extend support to timer units \([https\://github\.com/ansible\-collections/community\.general/pull/9891](https\://github\.com/ansible\-collections/community\.general/pull/9891)\)\.
+* vmadm \- add new options flexible\_disk\_size
and owner\_uuid
\([https\://github\.com/ansible\-collections/community\.general/pull/9892](https\://github\.com/ansible\-collections/community\.general/pull/9892)\)\.
+
+
+### Bugfixes
+
+* cloudlare\_dns \- handle exhausted response stream in case of HTTP errors to show nice error message to the user \([https\://github\.com/ansible\-collections/community\.general/issues/9782](https\://github\.com/ansible\-collections/community\.general/issues/9782)\, [https\://github\.com/ansible\-collections/community\.general/pull/9818](https\://github\.com/ansible\-collections/community\.general/pull/9818)\)\.
+* dnf\_versionlock \- add support for dnf5 \([https\://github\.com/ansible\-collections/community\.general/issues/9556](https\://github\.com/ansible\-collections/community\.general/issues/9556)\)\.
+* homebrew \- fix crash when package names include tap \([https\://github\.com/ansible\-collections/community\.general/issues/9777](https\://github\.com/ansible\-collections/community\.general/issues/9777)\, [https\://github\.com/ansible\-collections/community\.general/pull/9803](https\://github\.com/ansible\-collections/community\.general/pull/9803)\)\.
+* homebrew\_cask \- handle unusual brew version strings \([https\://github\.com/ansible\-collections/community\.general/issues/8432](https\://github\.com/ansible\-collections/community\.general/issues/8432)\, [https\://github\.com/ansible\-collections/community\.general/pull/9881](https\://github\.com/ansible\-collections/community\.general/pull/9881)\)\.
+* nmcli \- enable changing only the order of DNS servers or search suffixes \([https\://github\.com/ansible\-collections/community\.general/issues/8724](https\://github\.com/ansible\-collections/community\.general/issues/8724)\, [https\://github\.com/ansible\-collections/community\.general/pull/9880](https\://github\.com/ansible\-collections/community\.general/pull/9880)\)\.
+* proxmox \- add missing key selection of \'status\'
key to get\_lxc\_status
\([https\://github\.com/ansible\-collections/community\.general/issues/9696](https\://github\.com/ansible\-collections/community\.general/issues/9696)\, [https\://github\.com/ansible\-collections/community\.general/pull/9809](https\://github\.com/ansible\-collections/community\.general/pull/9809)\)\.
+* proxmox\_vm\_info \- the module no longer expects that the key template
exists in a dictionary returned by Proxmox \([https\://github\.com/ansible\-collections/community\.general/issues/9875](https\://github\.com/ansible\-collections/community\.general/issues/9875)\, [https\://github\.com/ansible\-collections/community\.general/pull/9910](https\://github\.com/ansible\-collections/community\.general/pull/9910)\)\.
+* sudoers \- display stdout and stderr raised while failed validation \([https\://github\.com/ansible\-collections/community\.general/issues/9674](https\://github\.com/ansible\-collections/community\.general/issues/9674)\, [https\://github\.com/ansible\-collections/community\.general/pull/9871](https\://github\.com/ansible\-collections/community\.general/pull/9871)\)\.
+
+
+### New Modules
+
+* community\.general\.pacemaker\_resource \- Manage pacemaker resources\.
+
+
+## v10\.4\.0
+
+
+### Release Summary
+
+Regular bugfix and feature release\.
+
+
+### Minor Changes
+
+* bitwarden lookup plugin \- add new option collection\_name
to filter results by collection name\, and new option result\_count
to validate number of results \([https\://github\.com/ansible\-collections/community\.general/pull/9728](https\://github\.com/ansible\-collections/community\.general/pull/9728)\)\.
+* incus connection plugin \- adds remote\_user
and incus\_become\_method
parameters for allowing a non\-root user to connect to an Incus instance \([https\://github\.com/ansible\-collections/community\.general/pull/9743](https\://github\.com/ansible\-collections/community\.general/pull/9743)\)\.
+* iocage inventory plugin \- the new parameter hooks\_results
of the plugin is a list of files inside a jail that provide configuration parameters for the inventory\. The inventory plugin reads the files from the jails and put the contents into the items of created variable iocage\_hooks
\([https\://github\.com/ansible\-collections/community\.general/issues/9650](https\://github\.com/ansible\-collections/community\.general/issues/9650)\, [https\://github\.com/ansible\-collections/community\.general/pull/9651](https\://github\.com/ansible\-collections/community\.general/pull/9651)\)\.
+* jira \- adds client\_cert
and client\_key
parameters for supporting client certificate authentification when connecting to Jira \([https\://github\.com/ansible\-collections/community\.general/pull/9753](https\://github\.com/ansible\-collections/community\.general/pull/9753)\)\.
+* lldp \- adds multivalues
parameter to control behavior when lldpctl outputs an attribute multiple times \([https\://github\.com/ansible\-collections/community\.general/pull/9657](https\://github\.com/ansible\-collections/community\.general/pull/9657)\)\.
+* lvg \- add remove\_extra\_pvs
parameter to control if ansible should remove physical volumes which are not in the pvs
parameter \([https\://github\.com/ansible\-collections/community\.general/pull/9698](https\://github\.com/ansible\-collections/community\.general/pull/9698)\)\.
+* lxd connection plugin \- adds remote\_user
and lxd\_become\_method
parameters for allowing a non\-root user to connect to an LXD instance \([https\://github\.com/ansible\-collections/community\.general/pull/9659](https\://github\.com/ansible\-collections/community\.general/pull/9659)\)\.
+* nmcli \- adds VRF support with new type
value vrf
and new slave\_type
value vrf
as well as new table
parameter \([https\://github\.com/ansible\-collections/community\.general/pull/9658](https\://github\.com/ansible\-collections/community\.general/pull/9658)\, [https\://github\.com/ansible\-collections/community\.general/issues/8014](https\://github\.com/ansible\-collections/community\.general/issues/8014)\)\.
+* proxmox\_kvm \- allow hibernation and suspending of VMs \([https\://github\.com/ansible\-collections/community\.general/issues/9620](https\://github\.com/ansible\-collections/community\.general/issues/9620)\, [https\://github\.com/ansible\-collections/community\.general/pull/9653](https\://github\.com/ansible\-collections/community\.general/pull/9653)\)\.
+* redfish\_command \- add PowerFullPowerCycle
to power command options \([https\://github\.com/ansible\-collections/community\.general/pull/9729](https\://github\.com/ansible\-collections/community\.general/pull/9729)\)\.
+* ssh\_config \- add other\_options
option \([https\://github\.com/ansible\-collections/community\.general/issues/8053](https\://github\.com/ansible\-collections/community\.general/issues/8053)\, [https\://github\.com/ansible\-collections/community\.general/pull/9684](https\://github\.com/ansible\-collections/community\.general/pull/9684)\)\.
+* xen\_orchestra inventory plugin \- add use\_vm\_uuid
and use\_host\_uuid
boolean options to allow switching over to using VM/Xen name labels instead of UUIDs as item names \([https\://github\.com/ansible\-collections/community\.general/pull/9787](https\://github\.com/ansible\-collections/community\.general/pull/9787)\)\.
+
+
+### Deprecated Features
+
+* profitbricks \- module is deprecated and will be removed in community\.general 11\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9733](https\://github\.com/ansible\-collections/community\.general/pull/9733)\)\.
+* profitbricks\_datacenter \- module is deprecated and will be removed in community\.general 11\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9733](https\://github\.com/ansible\-collections/community\.general/pull/9733)\)\.
+* profitbricks\_nic \- module is deprecated and will be removed in community\.general 11\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9733](https\://github\.com/ansible\-collections/community\.general/pull/9733)\)\.
+* profitbricks\_volume \- module is deprecated and will be removed in community\.general 11\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9733](https\://github\.com/ansible\-collections/community\.general/pull/9733)\)\.
+* profitbricks\_volume\_attachments \- module is deprecated and will be removed in community\.general 11\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9733](https\://github\.com/ansible\-collections/community\.general/pull/9733)\)\.
+
+
+### Bugfixes
+
+* apache2\_mod\_proxy \- make compatible with Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9762](https\://github\.com/ansible\-collections/community\.general/pull/9762)\)\.
+* apache2\_mod\_proxy \- passing the cluster\'s page as referer for the member\'s pages\. This makes the module actually work again for halfway modern Apache versions\. According to some comments founds on the net the referer was required since at least 2019 for some versions of Apache 2 \([https\://github\.com/ansible\-collections/community\.general/pull/9762](https\://github\.com/ansible\-collections/community\.general/pull/9762)\)\.
+* elasticsearch\_plugin \- fix ERROR\: D is not a recognized option
issue when configuring proxy settings \([https\://github\.com/ansible\-collections/community\.general/pull/9774](https\://github\.com/ansible\-collections/community\.general/pull/9774)\, [https\://github\.com/ansible\-collections/community\.general/issues/9773](https\://github\.com/ansible\-collections/community\.general/issues/9773)\)\.
+* ipa\_host \- module revoked existing host certificates even if user\_certificate
was not given \([https\://github\.com/ansible\-collections/community\.general/pull/9694](https\://github\.com/ansible\-collections/community\.general/pull/9694)\)\.
+* keycloak\_client \- in check mode\, detect whether the lists in before client \(for example redirect URI list\) contain items that the lists in the desired client do not contain \([https\://github\.com/ansible\-collections/community\.general/pull/9739](https\://github\.com/ansible\-collections/community\.general/pull/9739)\)\.
+* lldp \- fix crash caused by certain lldpctl output where an attribute is defined as branch and leaf \([https\://github\.com/ansible\-collections/community\.general/pull/9657](https\://github\.com/ansible\-collections/community\.general/pull/9657)\)\.
+* onepassword\_doc lookup plugin \- ensure that 1Password Connect support also works for this plugin \([https\://github\.com/ansible\-collections/community\.general/pull/9625](https\://github\.com/ansible\-collections/community\.general/pull/9625)\)\.
+* passwordstore lookup plugin \- fix subkey creation even when create\=false
\([https\://github\.com/ansible\-collections/community\.general/issues/9105](https\://github\.com/ansible\-collections/community\.general/issues/9105)\, [https\://github\.com/ansible\-collections/community\.general/pull/9106](https\://github\.com/ansible\-collections/community\.general/pull/9106)\)\.
+* proxmox inventory plugin \- plugin did not update cache correctly after meta\: refresh\_inventory
\([https\://github\.com/ansible\-collections/community\.general/issues/9710](https\://github\.com/ansible\-collections/community\.general/issues/9710)\, [https\://github\.com/ansible\-collections/community\.general/pull/9760](https\://github\.com/ansible\-collections/community\.general/pull/9760)\)\.
+* redhat\_subscription \- use the \"enable\_content\" option \(when available\) when
+ registering using D\-Bus\, to ensure that subscription\-manager enables the
+ content on registration\; this is particular important on EL 10\+ and Fedora
+ 41\+
+ \([https\://github\.com/ansible\-collections/community\.general/pull/9778](https\://github\.com/ansible\-collections/community\.general/pull/9778)\)\.
+* zfs \- fix handling of multi\-line values of user\-defined ZFS properties \([https\://github\.com/ansible\-collections/community\.general/pull/6264](https\://github\.com/ansible\-collections/community\.general/pull/6264)\)\.
+* zfs\_facts \- parameter type
now accepts multple values as documented \([https\://github\.com/ansible\-collections/community\.general/issues/5909](https\://github\.com/ansible\-collections/community\.general/issues/5909)\, [https\://github\.com/ansible\-collections/community\.general/pull/9697](https\://github\.com/ansible\-collections/community\.general/pull/9697)\)\.
+
+
+### New Modules
+
+* community\.general\.systemd\_info \- Gather C\(systemd\) unit info\.
+
+
+## v10\.3\.1
+
+
+### Release Summary
+
+Bugfix release\.
+
+
+### Minor Changes
+
+* onepassword\_ssh\_key \- refactor to move code to lookup class \([https\://github\.com/ansible\-collections/community\.general/pull/9633](https\://github\.com/ansible\-collections/community\.general/pull/9633)\)\.
+
+
+### Bugfixes
+
+* cloudflare\_dns \- fix crash when deleting a DNS record or when updating a record with solo\=true
\([https\://github\.com/ansible\-collections/community\.general/issues/9652](https\://github\.com/ansible\-collections/community\.general/issues/9652)\, [https\://github\.com/ansible\-collections/community\.general/pull/9649](https\://github\.com/ansible\-collections/community\.general/pull/9649)\)\.
+* homebrew \- make package name parsing more resilient \([https\://github\.com/ansible\-collections/community\.general/pull/9665](https\://github\.com/ansible\-collections/community\.general/pull/9665)\, [https\://github\.com/ansible\-collections/community\.general/issues/9641](https\://github\.com/ansible\-collections/community\.general/issues/9641)\)\.
+* keycloak module utils \- replaces missing return in get\_role\_composites method which caused it to return None instead of composite roles \([https\://github\.com/ansible\-collections/community\.general/issues/9678](https\://github\.com/ansible\-collections/community\.general/issues/9678)\, [https\://github\.com/ansible\-collections/community\.general/pull/9691](https\://github\.com/ansible\-collections/community\.general/pull/9691)\)\.
+* keycloak\_client \- fix and improve existing tests\. The module showed a diff without actual changes\, solved by improving the normalise\_cr\(\)
function \([https\://github\.com/ansible\-collections/community\.general/pull/9644](https\://github\.com/ansible\-collections/community\.general/pull/9644)\)\.
+* proxmox \- adds the pubkey
parameter \(back to\) the update
state \([https\://github\.com/ansible\-collections/community\.general/issues/9642](https\://github\.com/ansible\-collections/community\.general/issues/9642)\, [https\://github\.com/ansible\-collections/community\.general/pull/9645](https\://github\.com/ansible\-collections/community\.general/pull/9645)\)\.
+* proxmox \- fixes a typo in the translation of the pubkey
parameter to proxmox\' ssh\-public\-keys
\([https\://github\.com/ansible\-collections/community\.general/issues/9642](https\://github\.com/ansible\-collections/community\.general/issues/9642)\, [https\://github\.com/ansible\-collections/community\.general/pull/9645](https\://github\.com/ansible\-collections/community\.general/pull/9645)\)\.
+* xml \- ensure file descriptor is closed \([https\://github\.com/ansible\-collections/community\.general/pull/9695](https\://github\.com/ansible\-collections/community\.general/pull/9695)\)\.
+
+
+## v10\.3\.0
+
+
+### Release Summary
+
+Regular bugfix and feature release\.
+
+
+### Minor Changes
+
+* MH module utils \- delegate debug
to the underlying AnsibleModule
instance or issues a warning if an attribute already exists with that name \([https\://github\.com/ansible\-collections/community\.general/pull/9577](https\://github\.com/ansible\-collections/community\.general/pull/9577)\)\.
+* apache2\_mod\_proxy \- better handling regexp extraction \([https\://github\.com/ansible\-collections/community\.general/pull/9609](https\://github\.com/ansible\-collections/community\.general/pull/9609)\)\.
+* apache2\_mod\_proxy \- change type of state
to a list of strings\. No change for the users \([https\://github\.com/ansible\-collections/community\.general/pull/9600](https\://github\.com/ansible\-collections/community\.general/pull/9600)\)\.
+* apache2\_mod\_proxy \- improve readability when using results from fecth\_url\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/9608](https\://github\.com/ansible\-collections/community\.general/pull/9608)\)\.
+* apache2\_mod\_proxy \- refactor repeated code into method \([https\://github\.com/ansible\-collections/community\.general/pull/9599](https\://github\.com/ansible\-collections/community\.general/pull/9599)\)\.
+* apache2\_mod\_proxy \- remove unused parameter and code from Balancer
constructor \([https\://github\.com/ansible\-collections/community\.general/pull/9614](https\://github\.com/ansible\-collections/community\.general/pull/9614)\)\.
+* apache2\_mod\_proxy \- simplified and improved string manipulation \([https\://github\.com/ansible\-collections/community\.general/pull/9614](https\://github\.com/ansible\-collections/community\.general/pull/9614)\)\.
+* apache2\_mod\_proxy \- use deps
to handle dependencies \([https\://github\.com/ansible\-collections/community\.general/pull/9612](https\://github\.com/ansible\-collections/community\.general/pull/9612)\)\.
+* cgroup\_memory\_recap callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* chroot connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* cloud\_init\_data\_facts \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* cobbler inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* context\_demo callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* counter filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* counter\_enabled callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* cpanm \- enable usage of option \-\-with\-recommends
\([https\://github\.com/ansible\-collections/community\.general/issues/9554](https\://github\.com/ansible\-collections/community\.general/issues/9554)\, [https\://github\.com/ansible\-collections/community\.general/pull/9555](https\://github\.com/ansible\-collections/community\.general/pull/9555)\)\.
+* cpanm \- enable usage of option \-\-with\-suggests
\([https\://github\.com/ansible\-collections/community\.general/pull/9555](https\://github\.com/ansible\-collections/community\.general/pull/9555)\)\.
+* crc32 filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* cronvar \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* crypttab \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* default\_without\_diff callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* dense callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* dict filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* dict\_kv filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* diy callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* doas become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* dzdo become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* elastic callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* from\_csv filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* from\_ini filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* funcd connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* gitlab\_runners inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* groupby\_as\_dict filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* hashids filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* icinga2 inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* incus connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* iocage connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* iocage inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* iocage inventory plugin \- the new parameter sudo
of the plugin lets the command iocage list \-l
to run as root on the iocage host\. This is needed to get the IPv4 of a running DHCP jail \([https\://github\.com/ansible\-collections/community\.general/issues/9572](https\://github\.com/ansible\-collections/community\.general/issues/9572)\, [https\://github\.com/ansible\-collections/community\.general/pull/9573](https\://github\.com/ansible\-collections/community\.general/pull/9573)\)\.
+* iptables\_state action plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* jabber callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* jail connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* jc filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* jira \- transition operation now has status\_id
to directly reference wanted transition \([https\://github\.com/ansible\-collections/community\.general/pull/9602](https\://github\.com/ansible\-collections/community\.general/pull/9602)\)\.
+* json\_query filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* keep\_keys filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* keycloak\_\* modules \- refresh\_token
parameter added\. When multiple authentication parameters are provided \(token
\, refresh\_token
\, and auth\_username
/auth\_password
\)\, modules will now automatically retry requests upon authentication errors \(401\)\, using in order the token\, refresh token\, and username/password \([https\://github\.com/ansible\-collections/community\.general/pull/9494](https\://github\.com/ansible\-collections/community\.general/pull/9494)\)\.
+* known\_hosts \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* ksu become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* linode inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* lists filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* lists\_mergeby filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* log\_plays callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* loganalytics callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* logdna callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* logentries callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* logstash callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* lxc connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* lxd connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* lxd inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* machinectl become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* mail callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* memcached cache plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* nmap inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* nmcli \- add a option fail\_over\_mac
\([https\://github\.com/ansible\-collections/community\.general/issues/9570](https\://github\.com/ansible\-collections/community\.general/issues/9570)\, [https\://github\.com/ansible\-collections/community\.general/pull/9571](https\://github\.com/ansible\-collections/community\.general/pull/9571)\)\.
+* nrdp callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* null callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* one\_template \- adds filter
option for retrieving templates which are not owned by the user \([https\://github\.com/ansible\-collections/community\.general/pull/9547](https\://github\.com/ansible\-collections/community\.general/pull/9547)\, [https\://github\.com/ansible\-collections/community\.general/issues/9278](https\://github\.com/ansible\-collections/community\.general/issues/9278)\)\.
+* online inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* opennebula inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* opentelemetry callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* parted \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* pbrun become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* pfexec become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* pickle cache plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* pmrun become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* proxmox \- refactors the proxmox module \([https\://github\.com/ansible\-collections/community\.general/pull/9225](https\://github\.com/ansible\-collections/community\.general/pull/9225)\)\.
+* proxmox inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* proxmox\_pct\_remote connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* proxmox\_template \- add support for checksum validation with new options checksum\_algorithm
and checksum
\([https\://github\.com/ansible\-collections/community\.general/issues/9553](https\://github\.com/ansible\-collections/community\.general/issues/9553)\, [https\://github\.com/ansible\-collections/community\.general/pull/9601](https\://github\.com/ansible\-collections/community\.general/pull/9601)\)\.
+* pulp\_repo \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* qubes connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* random\_mac filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* redfish\_info \- add command GetAccountServiceConfig
to get full information about AccountService configuration \([https\://github\.com/ansible\-collections/community\.general/pull/9403](https\://github\.com/ansible\-collections/community\.general/pull/9403)\)\.
+* redhat\_subscription \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* redis cache plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* remove\_keys filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* replace\_keys filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* reveal\_ansible\_type filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* run0 become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* saltstack connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* say callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* scaleway inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* selective callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* sesu become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* shutdown action plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* slack callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* snap \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9598](https\://github\.com/ansible\-collections/community\.general/pull/9598)\)\.
+* snap\_alias \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9598](https\://github\.com/ansible\-collections/community\.general/pull/9598)\)\.
+* solaris\_zone \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* sorcery \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* splunk callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* stackpath\_compute inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* sudosu become plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* sumologic callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* syslog\_json callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* time filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* timestamp callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* timezone \- open file using open\(\)
as a context manager \([https\://github\.com/ansible\-collections/community\.general/pull/9579](https\://github\.com/ansible\-collections/community\.general/pull/9579)\)\.
+* to\_ini filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* ufw \- add support for vrrp
protocol \([https\://github\.com/ansible\-collections/community\.general/issues/9562](https\://github\.com/ansible\-collections/community\.general/issues/9562)\, [https\://github\.com/ansible\-collections/community\.general/pull/9582](https\://github\.com/ansible\-collections/community\.general/pull/9582)\)\.
+* unicode\_normalize filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* unixy callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* version\_sort filter plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9585](https\://github\.com/ansible\-collections/community\.general/pull/9585)\)\.
+* virtualbox inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* xen\_orchestra inventory plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+* yaml cache plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* yaml callback plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9583](https\://github\.com/ansible\-collections/community\.general/pull/9583)\)\.
+* zone connection plugin \- adjust standard preamble for Python 3 \([https\://github\.com/ansible\-collections/community\.general/pull/9584](https\://github\.com/ansible\-collections/community\.general/pull/9584)\)\.
+
+
+### Deprecated Features
+
+* MH module utils \- attribute debug
definition in subclasses of MH is now deprecated\, as that name will become a delegation to AnsibleModule
in community\.general 12\.0\.0\, and any such attribute will be overridden by that delegation in that version \([https\://github\.com/ansible\-collections/community\.general/pull/9577](https\://github\.com/ansible\-collections/community\.general/pull/9577)\)\.
+* proxmox \- removes default value false
of update
parameter\. This will be changed to a default of true
in community\.general 11\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9225](https\://github\.com/ansible\-collections/community\.general/pull/9225)\)\.
+
+
+### Security Fixes
+
+* keycloak\_client \- Sanitize saml\.encryption\.private\.key
so it does not show in the logs \([https\://github\.com/ansible\-collections/community\.general/pull/9621](https\://github\.com/ansible\-collections/community\.general/pull/9621)\)\.
+
+
+### Bugfixes
+
+* homebrew \- fix incorrect handling of homebrew modules when a tap is requested \([https\://github\.com/ansible\-collections/community\.general/pull/9546](https\://github\.com/ansible\-collections/community\.general/pull/9546)\, [https\://github\.com/ansible\-collections/community\.general/issues/9533](https\://github\.com/ansible\-collections/community\.general/issues/9533)\)\.
+* iocage inventory plugin \- the plugin parses the IP4 tab of the jails list and put the elements into the new variable iocage\_ip4\_dict
\. In multiple interface format the variable iocage\_ip4
keeps the comma\-separated list of IP4 \([https\://github\.com/ansible\-collections/community\.general/issues/9538](https\://github\.com/ansible\-collections/community\.general/issues/9538)\)\.
+* pipx \- honor option global
when state\=latest
\([https\://github\.com/ansible\-collections/community\.general/pull/9623](https\://github\.com/ansible\-collections/community\.general/pull/9623)\)\.
+* proxmox \- fixes idempotency of template conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9225](https\://github\.com/ansible\-collections/community\.general/pull/9225)\, [https\://github\.com/ansible\-collections/community\.general/issues/8811](https\://github\.com/ansible\-collections/community\.general/issues/8811)\)\.
+* proxmox \- fixes incorrect parsing for bind\-only mounts \([https\://github\.com/ansible\-collections/community\.general/pull/9225](https\://github\.com/ansible\-collections/community\.general/pull/9225)\, [https\://github\.com/ansible\-collections/community\.general/issues/8982](https\://github\.com/ansible\-collections/community\.general/issues/8982)\)\.
+* proxmox \- fixes issues with disk\_volume variable \([https\://github\.com/ansible\-collections/community\.general/pull/9225](https\://github\.com/ansible\-collections/community\.general/pull/9225)\, [https\://github\.com/ansible\-collections/community\.general/issues/9065](https\://github\.com/ansible\-collections/community\.general/issues/9065)\)\.
+* proxmox module utils \- fixes ignoring of choose\_first\_if\_multiple
argument in get\_vmid
\([https\://github\.com/ansible\-collections/community\.general/pull/9225](https\://github\.com/ansible\-collections/community\.general/pull/9225)\)\.
+* redhat\_subscription \- do not try to unsubscribe \(i\.e\. remove subscriptions\)
+ when unregistering a system\: newer versions of subscription\-manager\, as
+ available in EL 10 and Fedora 41\+\, do not support entitlements anymore\, and
+ thus unsubscribing will fail
+ \([https\://github\.com/ansible\-collections/community\.general/pull/9578](https\://github\.com/ansible\-collections/community\.general/pull/9578)\)\.
+
+
+### New Plugins
+
+
+#### Connection
+
+* community\.general\.proxmox\_pct\_remote \- Run tasks in Proxmox LXC container instances using pct CLI via SSH\.
+
+
+#### Filter
+
+* community\.general\.json\_diff \- Create a JSON patch by comparing two JSON files\.
+* community\.general\.json\_patch \- Apply a JSON\-Patch \(RFC 6902\) operation to an object\.
+* community\.general\.json\_patch\_recipe \- Apply JSON\-Patch \(RFC 6902\) operations to an object\.
+
+
+#### Lookup
+
+* community\.general\.onepassword\_ssh\_key \- Fetch SSH keys stored in 1Password\.
+
+
+### New Modules
+
+* community\.general\.proxmox\_backup\_info \- Retrieve information on Proxmox scheduled backups\.
+
+
+## v10\.2\.0
+
+
+### Release Summary
+
+Regular bugfix and feature release\.
+
+
+### Minor Changes
+
+* bitwarden lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* cgroup\_memory\_recap callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* chef\_databag lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* chroot connection plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* chroot connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* cobbler inventory plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* cobbler inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* collection\_version lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* consul\_kv lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* context\_demo callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* counter\_enabled callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* credstash lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* cyberarkpassword lookup plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* cyberarkpassword lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* dense callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* dependent lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* dig lookup plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* dig lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* diy callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* dnstxt lookup plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* dnstxt lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* doas become plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9319](https\://github\.com/ansible\-collections/community\.general/pull/9319)\)\.
+* dsv lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* dzdo become plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9319](https\://github\.com/ansible\-collections/community\.general/pull/9319)\)\.
+* elastic callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* etcd lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* etcd3 lookup plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* etcd3 lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* filetree lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* from\_csv filter plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* from\_ini filter plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* funcd connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* github\_app\_access\_token lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* gitlab\_instance\_variable \- add support for raw
variables suboption \([https\://github\.com/ansible\-collections/community\.general/pull/9425](https\://github\.com/ansible\-collections/community\.general/pull/9425)\)\.
+* gitlab\_runners inventory plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* gitlab\_runners inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* hiera lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* icinga2 inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* incus connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* iocage connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* iocage inventory plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* iptables\_state action plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9318](https\://github\.com/ansible\-collections/community\.general/pull/9318)\)\.
+* jabber callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* jail connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* keycloak \- add an action group for Keycloak modules to allow module\_defaults
to be set for Keycloak tasks \([https\://github\.com/ansible\-collections/community\.general/pull/9284](https\://github\.com/ansible\-collections/community\.general/pull/9284)\)\.
+* keyring lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* ksu become plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9319](https\://github\.com/ansible\-collections/community\.general/pull/9319)\)\.
+* lastpass lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* linode inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* lmdb\_kv lookup plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* lmdb\_kv lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* locale\_gen \- invert the logic to determine ubuntu\_mode
\, making it look first for /etc/locale\.gen
\(set ubuntu\_mode
to False
\) and only then looking for /var/lib/locales/supported\.d/
\(set ubuntu\_mode
to True
\) \([https\://github\.com/ansible\-collections/community\.general/pull/9238](https\://github\.com/ansible\-collections/community\.general/pull/9238)\, [https\://github\.com/ansible\-collections/community\.general/issues/9131](https\://github\.com/ansible\-collections/community\.general/issues/9131)\, [https\://github\.com/ansible\-collections/community\.general/issues/8487](https\://github\.com/ansible\-collections/community\.general/issues/8487)\)\.
+* locale\_gen \- new return value mechanism
to better express the semantics of the ubuntu\_mode
\, with the possible values being either glibc
\(ubuntu\_mode\=False
\) or ubuntu\_legacy
\(ubuntu\_mode\=True
\) \([https\://github\.com/ansible\-collections/community\.general/pull/9238](https\://github\.com/ansible\-collections/community\.general/pull/9238)\)\.
+* log\_plays callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* loganalytics callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* logdna callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* logentries callback plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* logentries callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* lxc connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* lxd connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* lxd inventory plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* lxd inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* machinectl become plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9319](https\://github\.com/ansible\-collections/community\.general/pull/9319)\)\.
+* mail callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* manageiq\_alert\_profiles \- improve handling of parameter requirements \([https\://github\.com/ansible\-collections/community\.general/pull/9449](https\://github\.com/ansible\-collections/community\.general/pull/9449)\)\.
+* manifold lookup plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* manifold lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* memcached cache plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9320](https\://github\.com/ansible\-collections/community\.general/pull/9320)\)\.
+* merge\_variables lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* nmap inventory plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* nmap inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* nrdp callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* onepassword lookup plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* onepassword lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* onepassword\_doc lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* online inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* opennebula inventory plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* opennebula inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* opentelemetry callback plugin \- remove code handling Python versions prior to 3\.7 \([https\://github\.com/ansible\-collections/community\.general/pull/9482](https\://github\.com/ansible\-collections/community\.general/pull/9482)\)\.
+* opentelemetry callback plugin \- remove code handling Python versions prior to 3\.7 \([https\://github\.com/ansible\-collections/community\.general/pull/9503](https\://github\.com/ansible\-collections/community\.general/pull/9503)\)\.
+* opentelemetry callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* pacemaker\_cluster \- remove unused code \([https\://github\.com/ansible\-collections/community\.general/pull/9471](https\://github\.com/ansible\-collections/community\.general/pull/9471)\)\.
+* pacemaker\_cluster \- using safer mechanism to run external command \([https\://github\.com/ansible\-collections/community\.general/pull/9471](https\://github\.com/ansible\-collections/community\.general/pull/9471)\)\.
+* passwordstore lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* pbrun become plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9319](https\://github\.com/ansible\-collections/community\.general/pull/9319)\)\.
+* pfexec become plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9319](https\://github\.com/ansible\-collections/community\.general/pull/9319)\)\.
+* pmrun become plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9319](https\://github\.com/ansible\-collections/community\.general/pull/9319)\)\.
+* proxmox inventory plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* proxmox inventory plugin \- strip whitespace from user
\, token\_id
\, and token\_secret
\([https\://github\.com/ansible\-collections/community\.general/issues/9227](https\://github\.com/ansible\-collections/community\.general/issues/9227)\, [https\://github\.com/ansible\-collections/community\.general/pull/9228/](https\://github\.com/ansible\-collections/community\.general/pull/9228/)\)\.
+* proxmox inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* proxmox module utils \- add method api\_task\_complete
that can wait for task completion and return error message \([https\://github\.com/ansible\-collections/community\.general/pull/9256](https\://github\.com/ansible\-collections/community\.general/pull/9256)\)\.
+* proxmox\_backup \- refactor permission checking to improve code readability and maintainability \([https\://github\.com/ansible\-collections/community\.general/pull/9239](https\://github\.com/ansible\-collections/community\.general/pull/9239)\)\.
+* qubes connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* random\_pet lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* redis cache plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* redis cache plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9320](https\://github\.com/ansible\-collections/community\.general/pull/9320)\)\.
+* redis lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* revbitspss lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* saltstack connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* say callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* scaleway inventory plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* scaleway inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* selective callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* sesu become plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9319](https\://github\.com/ansible\-collections/community\.general/pull/9319)\)\.
+* shelvefile lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* shutdown action plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* shutdown action plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9318](https\://github\.com/ansible\-collections/community\.general/pull/9318)\)\.
+* slack callback plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* slack callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* splunk callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* stackpath\_compute inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* sudosu become plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9319](https\://github\.com/ansible\-collections/community\.general/pull/9319)\)\.
+* timestamp callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* to\_ini filter plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* tss lookup plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* tss lookup plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9324](https\://github\.com/ansible\-collections/community\.general/pull/9324)\)\.
+* unixy callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* virtualbox inventory plugin \- clean up string conversions \([https\://github\.com/ansible\-collections/community\.general/pull/9379](https\://github\.com/ansible\-collections/community\.general/pull/9379)\)\.
+* virtualbox inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* xbps \- add root
and repository
options to enable bootstrapping new void installations \([https\://github\.com/ansible\-collections/community\.general/pull/9174](https\://github\.com/ansible\-collections/community\.general/pull/9174)\)\.
+* xen\_orchestra inventory plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9323](https\://github\.com/ansible\-collections/community\.general/pull/9323)\)\.
+* xfconf \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9226](https\://github\.com/ansible\-collections/community\.general/pull/9226)\)\.
+* xfconf\_info \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9226](https\://github\.com/ansible\-collections/community\.general/pull/9226)\)\.
+* yaml callback plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9321](https\://github\.com/ansible\-collections/community\.general/pull/9321)\)\.
+* zone connection plugin \- use f\-strings instead of interpolations or format
\([https\://github\.com/ansible\-collections/community\.general/pull/9322](https\://github\.com/ansible\-collections/community\.general/pull/9322)\)\.
+* zypper \- add quiet
option \([https\://github\.com/ansible\-collections/community\.general/pull/9270](https\://github\.com/ansible\-collections/community\.general/pull/9270)\)\.
+* zypper \- add simple\_errors
option \([https\://github\.com/ansible\-collections/community\.general/pull/9270](https\://github\.com/ansible\-collections/community\.general/pull/9270)\)\.
+
+
+### Deprecated Features
+
+* atomic\_container \- module is deprecated and will be removed in community\.general 13\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9487](https\://github\.com/ansible\-collections/community\.general/pull/9487)\)\.
+* atomic\_host \- module is deprecated and will be removed in community\.general 13\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9487](https\://github\.com/ansible\-collections/community\.general/pull/9487)\)\.
+* atomic\_image \- module is deprecated and will be removed in community\.general 13\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9487](https\://github\.com/ansible\-collections/community\.general/pull/9487)\)\.
+* facter \- module is deprecated and will be removed in community\.general 12\.0\.0\, use community\.general\.facter\_facts
instead \([https\://github\.com/ansible\-collections/community\.general/pull/9451](https\://github\.com/ansible\-collections/community\.general/pull/9451)\)\.
+* locale\_gen \- ubuntu\_mode\=True
\, or mechanism\=ubuntu\_legacy
is deprecated and will be removed in community\.general 13\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9238](https\://github\.com/ansible\-collections/community\.general/pull/9238)\)\.
+* pure module utils \- the module utils is deprecated and will be removed from community\.general 12\.0\.0\. The modules using this were removed in community\.general 3\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9432](https\://github\.com/ansible\-collections/community\.general/pull/9432)\)\.
+* purestorage doc fragments \- the doc fragment is deprecated and will be removed from community\.general 12\.0\.0\. The modules using this were removed in community\.general 3\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9432](https\://github\.com/ansible\-collections/community\.general/pull/9432)\)\.
+* sensu\_check \- module is deprecated and will be removed in community\.general 13\.0\.0\, use collection sensu\.sensu\_go
instead \([https\://github\.com/ansible\-collections/community\.general/pull/9483](https\://github\.com/ansible\-collections/community\.general/pull/9483)\)\.
+* sensu\_client \- module is deprecated and will be removed in community\.general 13\.0\.0\, use collection sensu\.sensu\_go
instead \([https\://github\.com/ansible\-collections/community\.general/pull/9483](https\://github\.com/ansible\-collections/community\.general/pull/9483)\)\.
+* sensu\_handler \- module is deprecated and will be removed in community\.general 13\.0\.0\, use collection sensu\.sensu\_go
instead \([https\://github\.com/ansible\-collections/community\.general/pull/9483](https\://github\.com/ansible\-collections/community\.general/pull/9483)\)\.
+* sensu\_silence \- module is deprecated and will be removed in community\.general 13\.0\.0\, use collection sensu\.sensu\_go
instead \([https\://github\.com/ansible\-collections/community\.general/pull/9483](https\://github\.com/ansible\-collections/community\.general/pull/9483)\)\.
+* sensu\_subscription \- module is deprecated and will be removed in community\.general 13\.0\.0\, use collection sensu\.sensu\_go
instead \([https\://github\.com/ansible\-collections/community\.general/pull/9483](https\://github\.com/ansible\-collections/community\.general/pull/9483)\)\.
+* slack \- the default value auto
of the prepend\_hash
option is deprecated and will change to never
in community\.general 12\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/9443](https\://github\.com/ansible\-collections/community\.general/pull/9443)\)\.
+* yaml callback plugin \- deprecate plugin in favor of result\_format\=yaml
in plugin ansible\.bulitin\.default
\([https\://github\.com/ansible\-collections/community\.general/pull/9456](https\://github\.com/ansible\-collections/community\.general/pull/9456)\)\.
+
+
+### Security Fixes
+
+* keycloak\_authentication \- API calls did not properly set the priority
during update resulting in incorrectly sorted authentication flows\. This apparently only affects Keycloak 25 or newer \([https\://github\.com/ansible\-collections/community\.general/pull/9263](https\://github\.com/ansible\-collections/community\.general/pull/9263)\)\.
+
+
+### Bugfixes
+
+* dig lookup plugin \- correctly handle NoNameserver
exception \([https\://github\.com/ansible\-collections/community\.general/pull/9363](https\://github\.com/ansible\-collections/community\.general/pull/9363)\, [https\://github\.com/ansible\-collections/community\.general/issues/9362](https\://github\.com/ansible\-collections/community\.general/issues/9362)\)\.
+* homebrew \- fix incorrect handling of aliased homebrew modules when the alias is requested \([https\://github\.com/ansible\-collections/community\.general/pull/9255](https\://github\.com/ansible\-collections/community\.general/pull/9255)\, [https\://github\.com/ansible\-collections/community\.general/issues/9240](https\://github\.com/ansible\-collections/community\.general/issues/9240)\)\.
+* htpasswd \- report changes when file permissions are adjusted \([https\://github\.com/ansible\-collections/community\.general/issues/9485](https\://github\.com/ansible\-collections/community\.general/issues/9485)\, [https\://github\.com/ansible\-collections/community\.general/pull/9490](https\://github\.com/ansible\-collections/community\.general/pull/9490)\)\.
+* proxmox\_backup \- fix incorrect key lookup in vmid permission check \([https\://github\.com/ansible\-collections/community\.general/pull/9223](https\://github\.com/ansible\-collections/community\.general/pull/9223)\)\.
+* proxmox\_disk \- fix async method and make resize\_disk
method handle errors correctly \([https\://github\.com/ansible\-collections/community\.general/pull/9256](https\://github\.com/ansible\-collections/community\.general/pull/9256)\)\.
+* proxmox\_template \- fix the wrong path called on proxmox\_template\.task\_status
\([https\://github\.com/ansible\-collections/community\.general/issues/9276](https\://github\.com/ansible\-collections/community\.general/issues/9276)\, [https\://github\.com/ansible\-collections/community\.general/pull/9277](https\://github\.com/ansible\-collections/community\.general/pull/9277)\)\.
+* qubes connection plugin \- fix the printing of debug information \([https\://github\.com/ansible\-collections/community\.general/pull/9334](https\://github\.com/ansible\-collections/community\.general/pull/9334)\)\.
+* redfish\_utils module utils \- Fix VerifyBiosAttributes
command on multi system resource nodes \([https\://github\.com/ansible\-collections/community\.general/pull/9234](https\://github\.com/ansible\-collections/community\.general/pull/9234)\)\.
+
+
+### New Plugins
+
+
+#### Inventory
+
+* community\.general\.iocage \- iocage inventory source\.
+
+
+### New Modules
+
+* community\.general\.android\_sdk \- Manages Android SDK packages\.
+* community\.general\.ldap\_inc \- Use the Modify\-Increment LDAP V3 feature to increment an attribute value\.
+* community\.general\.systemd\_creds\_decrypt \- C\(systemd\)\'s C\(systemd\-creds decrypt\) plugin\.
+* community\.general\.systemd\_creds\_encrypt \- C\(systemd\)\'s C\(systemd\-creds encrypt\) plugin\.
+
+
+## v10\.1\.0
+
+
+### Release Summary
+
+Regular bugfix and feature release\.
+
+
+### Minor Changes
+
+* alternatives \- add family
parameter that allows to utilize the \-\-family
option available in RedHat version of update\-alternatives \([https\://github\.com/ansible\-collections/community\.general/issues/5060](https\://github\.com/ansible\-collections/community\.general/issues/5060)\, [https\://github\.com/ansible\-collections/community\.general/pull/9096](https\://github\.com/ansible\-collections/community\.general/pull/9096)\)\.
+* cloudflare\_dns \- add support for comment
and tags
\([https\://github\.com/ansible\-collections/community\.general/pull/9132](https\://github\.com/ansible\-collections/community\.general/pull/9132)\)\.
+* deps module utils \- add deps\.clear\(\)
to clear out previously declared dependencies \([https\://github\.com/ansible\-collections/community\.general/pull/9179](https\://github\.com/ansible\-collections/community\.general/pull/9179)\)\.
+* homebrew \- greatly speed up module when multiple packages are passed in the name
option \([https\://github\.com/ansible\-collections/community\.general/pull/9181](https\://github\.com/ansible\-collections/community\.general/pull/9181)\)\.
+* homebrew \- remove duplicated package name validation \([https\://github\.com/ansible\-collections/community\.general/pull/9076](https\://github\.com/ansible\-collections/community\.general/pull/9076)\)\.
+* iso\_extract \- adds password
parameter that is passed to 7z \([https\://github\.com/ansible\-collections/community\.general/pull/9159](https\://github\.com/ansible\-collections/community\.general/pull/9159)\)\.
+* launchd \- add plist
option for services such as sshd\, where the plist filename doesn\'t match the service name \([https\://github\.com/ansible\-collections/community\.general/pull/9102](https\://github\.com/ansible\-collections/community\.general/pull/9102)\)\.
+* nmcli \- add sriov
parameter that enables support for SR\-IOV settings \([https\://github\.com/ansible\-collections/community\.general/pull/9168](https\://github\.com/ansible\-collections/community\.general/pull/9168)\)\.
+* pipx \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9180](https\://github\.com/ansible\-collections/community\.general/pull/9180)\)\.
+* pipx\_info \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9180](https\://github\.com/ansible\-collections/community\.general/pull/9180)\)\.
+* proxmox\_template \- add server side artifact fetching support \([https\://github\.com/ansible\-collections/community\.general/pull/9113](https\://github\.com/ansible\-collections/community\.general/pull/9113)\)\.
+* redfish\_command \- add update\_custom\_oem\_header
\, update\_custom\_oem\_params
\, and update\_custom\_oem\_mime\_type
options \([https\://github\.com/ansible\-collections/community\.general/pull/9123](https\://github\.com/ansible\-collections/community\.general/pull/9123)\)\.
+* redfish\_utils module utils \- remove redundant code \([https\://github\.com/ansible\-collections/community\.general/pull/9190](https\://github\.com/ansible\-collections/community\.general/pull/9190)\)\.
+* rpm\_ostree\_pkg \- added the options apply\_live
\([https\://github\.com/ansible\-collections/community\.general/pull/9167](https\://github\.com/ansible\-collections/community\.general/pull/9167)\)\.
+* rpm\_ostree\_pkg \- added the return value needs\_reboot
\([https\://github\.com/ansible\-collections/community\.general/pull/9167](https\://github\.com/ansible\-collections/community\.general/pull/9167)\)\.
+* scaleway\_lb \- minor simplification in the code \([https\://github\.com/ansible\-collections/community\.general/pull/9189](https\://github\.com/ansible\-collections/community\.general/pull/9189)\)\.
+* ssh\_config \- add dynamicforward
option \([https\://github\.com/ansible\-collections/community\.general/pull/9192](https\://github\.com/ansible\-collections/community\.general/pull/9192)\)\.
+
+
+### Deprecated Features
+
+* opkg \- deprecate value \"\"
for parameter force
\([https\://github\.com/ansible\-collections/community\.general/pull/9172](https\://github\.com/ansible\-collections/community\.general/pull/9172)\)\.
+* redfish\_utils module utils \- deprecate method RedfishUtils\.\_init\_session\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/9190](https\://github\.com/ansible\-collections/community\.general/pull/9190)\)\.
+
+
+### Bugfixes
+
+* dnf\_config\_manager \- fix hanging when prompting to import GPG keys \([https\://github\.com/ansible\-collections/community\.general/pull/9124](https\://github\.com/ansible\-collections/community\.general/pull/9124)\, [https\://github\.com/ansible\-collections/community\.general/issues/8830](https\://github\.com/ansible\-collections/community\.general/issues/8830)\)\.
+* dnf\_config\_manager \- forces locale to C
before module starts\. If the locale was set to non\-English\, the output of the dnf config\-manager
could not be parsed \([https\://github\.com/ansible\-collections/community\.general/pull/9157](https\://github\.com/ansible\-collections/community\.general/pull/9157)\, [https\://github\.com/ansible\-collections/community\.general/issues/9046](https\://github\.com/ansible\-collections/community\.general/issues/9046)\)\.
+* flatpak \- force the locale language to C
when running the flatpak command \([https\://github\.com/ansible\-collections/community\.general/pull/9187](https\://github\.com/ansible\-collections/community\.general/pull/9187)\, [https\://github\.com/ansible\-collections/community\.general/issues/8883](https\://github\.com/ansible\-collections/community\.general/issues/8883)\)\.
+* gio\_mime \- fix command line when determining version of gio
\([https\://github\.com/ansible\-collections/community\.general/pull/9171](https\://github\.com/ansible\-collections/community\.general/pull/9171)\, [https\://github\.com/ansible\-collections/community\.general/issues/9158](https\://github\.com/ansible\-collections/community\.general/issues/9158)\)\.
+* github\_key \- in check mode\, a faulty call to \`datetime\.strftime\(\.\.\.\)\`
was being made which generated an exception \([https\://github\.com/ansible\-collections/community\.general/issues/9185](https\://github\.com/ansible\-collections/community\.general/issues/9185)\)\.
+* homebrew\_cask \- allow \+
symbol in Homebrew cask name validation regex \([https\://github\.com/ansible\-collections/community\.general/pull/9128](https\://github\.com/ansible\-collections/community\.general/pull/9128)\)\.
+* keycloak\_clientscope\_type \- sort the default and optional clientscope lists to improve the diff \([https\://github\.com/ansible\-collections/community\.general/pull/9202](https\://github\.com/ansible\-collections/community\.general/pull/9202)\)\.
+* slack \- fail if Slack API response is not OK with error message \([https\://github\.com/ansible\-collections/community\.general/pull/9198](https\://github\.com/ansible\-collections/community\.general/pull/9198)\)\.
+
+
+### New Plugins
+
+
+#### Filter
+
+* community\.general\.accumulate \- Produce a list of accumulated sums of the input list contents\.
+
+
+### New Modules
+
+* community\.general\.decompress \- Decompresses compressed files\.
+* community\.general\.proxmox\_backup \- Start a VM backup in Proxmox VE cluster\.
+
+
+## v10\.0\.1
+
+
+### Release Summary
+
+Bugfix release for inclusion in Ansible 11\.0\.0rc1\.
+
+
+### Bugfixes
+
+* keycloak\_client \- fix diff by removing code that turns the attributes dict which contains additional settings into a list \([https\://github\.com/ansible\-collections/community\.general/pull/9077](https\://github\.com/ansible\-collections/community\.general/pull/9077)\)\.
+* keycloak\_clientscope \- fix diff and end\_state
by removing the code that turns the attributes dict\, which contains additional config items\, into a list \([https\://github\.com/ansible\-collections/community\.general/pull/9082](https\://github\.com/ansible\-collections/community\.general/pull/9082)\)\.
+* redfish\_utils module utils \- remove undocumented default applytime \([https\://github\.com/ansible\-collections/community\.general/pull/9114](https\://github\.com/ansible\-collections/community\.general/pull/9114)\)\.
+
+
+## v10\.0\.0
+
+
+### Release Summary
+
+This is release 10\.0\.0 of community\.general
\, released on 2024\-11\-04\.
+
+
+### Minor Changes
+
+* CmdRunner module util \- argument formats can be specified as plain functions without calling cmd\_runner\_fmt\.as\_func\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8479](https\://github\.com/ansible\-collections/community\.general/pull/8479)\)\.
+* CmdRunner module utils \- the parameter force\_lang
now supports the special value auto
which will automatically try and determine the best parsable locale in the system \([https\://github\.com/ansible\-collections/community\.general/pull/8517](https\://github\.com/ansible\-collections/community\.general/pull/8517)\)\.
+* MH module utils \- add parameter when
to cause\_changes
decorator \([https\://github\.com/ansible\-collections/community\.general/pull/8766](https\://github\.com/ansible\-collections/community\.general/pull/8766)\)\.
+* MH module utils \- minor refactor in decorators \([https\://github\.com/ansible\-collections/community\.general/pull/8766](https\://github\.com/ansible\-collections/community\.general/pull/8766)\)\.
+* alternatives \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* ansible\_galaxy\_install \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9060](https\://github\.com/ansible\-collections/community\.general/pull/9060)\)\.
+* ansible\_galaxy\_install \- add upgrade feature \([https\://github\.com/ansible\-collections/community\.general/pull/8431](https\://github\.com/ansible\-collections/community\.general/pull/8431)\, [https\://github\.com/ansible\-collections/community\.general/issues/8351](https\://github\.com/ansible\-collections/community\.general/issues/8351)\)\.
+* ansible\_galaxy\_install \- minor refactor in the module \([https\://github\.com/ansible\-collections/community\.general/pull/8413](https\://github\.com/ansible\-collections/community\.general/pull/8413)\)\.
+* apache2\_mod\_proxy \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* apache2\_mod\_proxy \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* cargo \- add option directory
\, which allows source directory to be specified \([https\://github\.com/ansible\-collections/community\.general/pull/8480](https\://github\.com/ansible\-collections/community\.general/pull/8480)\)\.
+* cgroup\_memory\_recap\, hipchat\, jabber\, log\_plays\, loganalytics\, logentries\, logstash\, slack\, splunk\, sumologic\, syslog\_json callback plugins \- make sure that all options are typed \([https\://github\.com/ansible\-collections/community\.general/pull/8628](https\://github\.com/ansible\-collections/community\.general/pull/8628)\)\.
+* chef\_databag\, consul\_kv\, cyberarkpassword\, dsv\, etcd\, filetree\, hiera\, onepassword\, onepassword\_doc\, onepassword\_raw\, passwordstore\, redis\, shelvefile\, tss lookup plugins \- make sure that all options are typed \([https\://github\.com/ansible\-collections/community\.general/pull/8626](https\://github\.com/ansible\-collections/community\.general/pull/8626)\)\.
+* chroot\, funcd\, incus\, iocage\, jail\, lxc\, lxd\, qubes\, zone connection plugins \- make sure that all options are typed \([https\://github\.com/ansible\-collections/community\.general/pull/8627](https\://github\.com/ansible\-collections/community\.general/pull/8627)\)\.
+* cmd\_runner module utils \- add decorator cmd\_runner\_fmt\.stack
\([https\://github\.com/ansible\-collections/community\.general/pull/8415](https\://github\.com/ansible\-collections/community\.general/pull/8415)\)\.
+* cmd\_runner module utils \- refactor argument formatting code to its own Python module \([https\://github\.com/ansible\-collections/community\.general/pull/8964](https\://github\.com/ansible\-collections/community\.general/pull/8964)\)\.
+* cmd\_runner\_fmt module utils \- simplify implementation of cmd\_runner\_fmt\.as\_bool\_not\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8512](https\://github\.com/ansible\-collections/community\.general/pull/8512)\)\.
+* cobbler\, linode\, lxd\, nmap\, online\, scaleway\, stackpath\_compute\, virtualbox inventory plugins \- make sure that all options are typed \([https\://github\.com/ansible\-collections/community\.general/pull/8625](https\://github\.com/ansible\-collections/community\.general/pull/8625)\)\.
+* consul\_acl \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* consul\_kv \- add argument for the datacenter option on Consul API \([https\://github\.com/ansible\-collections/community\.general/pull/9026](https\://github\.com/ansible\-collections/community\.general/pull/9026)\)\.
+* copr \- Added includepkgs
and excludepkgs
parameters to limit the list of packages fetched or excluded from the repository\([https\://github\.com/ansible\-collections/community\.general/pull/8779](https\://github\.com/ansible\-collections/community\.general/pull/8779)\)\.
+* cpanm \- add return value cpanm\_version
\([https\://github\.com/ansible\-collections/community\.general/pull/9061](https\://github\.com/ansible\-collections/community\.general/pull/9061)\)\.
+* credstash lookup plugin \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* csv module utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* deco MH module utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* dig lookup plugin \- add port
option to specify DNS server port \([https\://github\.com/ansible\-collections/community\.general/pull/8966](https\://github\.com/ansible\-collections/community\.general/pull/8966)\)\.
+* django module utils \- always retrieve version \([https\://github\.com/ansible\-collections/community\.general/pull/9063](https\://github\.com/ansible\-collections/community\.general/pull/9063)\)\.
+* django\_check \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9063](https\://github\.com/ansible\-collections/community\.general/pull/9063)\)\.
+* django\_command \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9063](https\://github\.com/ansible\-collections/community\.general/pull/9063)\)\.
+* django\_createcachetable \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9063](https\://github\.com/ansible\-collections/community\.general/pull/9063)\)\.
+* doas\, dzdo\, ksu\, machinectl\, pbrun\, pfexec\, pmrun\, sesu\, sudosu become plugins \- make sure that all options are typed \([https\://github\.com/ansible\-collections/community\.general/pull/8623](https\://github\.com/ansible\-collections/community\.general/pull/8623)\)\.
+* etcd3 \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* flatpak \- improve the parsing of Flatpak application IDs based on official guidelines \([https\://github\.com/ansible\-collections/community\.general/pull/8909](https\://github\.com/ansible\-collections/community\.general/pull/8909)\)\.
+* gconftool2 \- make use of ModuleHelper
features to simplify code \([https\://github\.com/ansible\-collections/community\.general/pull/8711](https\://github\.com/ansible\-collections/community\.general/pull/8711)\)\.
+* gcontool2 \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9064](https\://github\.com/ansible\-collections/community\.general/pull/9064)\)\.
+* gcontool2 module utils \- add argument formatter version
\([https\://github\.com/ansible\-collections/community\.general/pull/9064](https\://github\.com/ansible\-collections/community\.general/pull/9064)\)\.
+* gcontool2\_info \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9064](https\://github\.com/ansible\-collections/community\.general/pull/9064)\)\.
+* gio\_mime \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9067](https\://github\.com/ansible\-collections/community\.general/pull/9067)\)\.
+* gio\_mime \- adjust code ahead of the old VardDict
deprecation \([https\://github\.com/ansible\-collections/community\.general/pull/8855](https\://github\.com/ansible\-collections/community\.general/pull/8855)\)\.
+* gio\_mime \- mute the old VarDict
deprecation \([https\://github\.com/ansible\-collections/community\.general/pull/8776](https\://github\.com/ansible\-collections/community\.general/pull/8776)\)\.
+* gio\_mime module utils \- add argument formatter version
\([https\://github\.com/ansible\-collections/community\.general/pull/9067](https\://github\.com/ansible\-collections/community\.general/pull/9067)\)\.
+* github\_app\_access\_token lookup plugin \- adds new private\_key
parameter \([https\://github\.com/ansible\-collections/community\.general/pull/8989](https\://github\.com/ansible\-collections/community\.general/pull/8989)\)\.
+* gitlab\_deploy\_key \- better construct when using dict\.items\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* gitlab\_group \- add many new parameters \([https\://github\.com/ansible\-collections/community\.general/pull/8908](https\://github\.com/ansible\-collections/community\.general/pull/8908)\)\.
+* gitlab\_group \- better construct when using dict\.items\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* gitlab\_group \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* gitlab\_issue \- better construct when using dict\.items\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* gitlab\_merge\_request \- better construct when using dict\.items\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* gitlab\_project \- add option container\_expiration\_policy
to schedule container registry cleanup \([https\://github\.com/ansible\-collections/community\.general/pull/8674](https\://github\.com/ansible\-collections/community\.general/pull/8674)\)\.
+* gitlab\_project \- add option issues\_access\_level
to enable/disable project issues \([https\://github\.com/ansible\-collections/community\.general/pull/8760](https\://github\.com/ansible\-collections/community\.general/pull/8760)\)\.
+* gitlab\_project \- add option model\_registry\_access\_level
to disable model registry \([https\://github\.com/ansible\-collections/community\.general/pull/8688](https\://github\.com/ansible\-collections/community\.general/pull/8688)\)\.
+* gitlab\_project \- add option pages\_access\_level
to disable project pages \([https\://github\.com/ansible\-collections/community\.general/pull/8688](https\://github\.com/ansible\-collections/community\.general/pull/8688)\)\.
+* gitlab\_project \- add option repository\_access\_level
to disable project repository \([https\://github\.com/ansible\-collections/community\.general/pull/8674](https\://github\.com/ansible\-collections/community\.general/pull/8674)\)\.
+* gitlab\_project \- add option service\_desk\_enabled
to disable service desk \([https\://github\.com/ansible\-collections/community\.general/pull/8688](https\://github\.com/ansible\-collections/community\.general/pull/8688)\)\.
+* gitlab\_project \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* gitlab\_project \- sorted parameters in order to avoid future merge conflicts \([https\://github\.com/ansible\-collections/community\.general/pull/8759](https\://github\.com/ansible\-collections/community\.general/pull/8759)\)\.
+* gitlab\_runner \- better construct when using dict\.items\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* hashids filter plugin \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* homebrew \- speed up brew install and upgrade \([https\://github\.com/ansible\-collections/community\.general/pull/9022](https\://github\.com/ansible\-collections/community\.general/pull/9022)\)\.
+* hwc\_ecs\_instance \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* hwc\_evs\_disk \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* hwc\_vpc\_eip \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* hwc\_vpc\_peering\_connect \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* hwc\_vpc\_port \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* hwc\_vpc\_subnet \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* icinga2\_host \- replace loop with dict comprehension \([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* imc\_rest \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* ipa\_dnsrecord \- adds SSHFP
record type for managing SSH fingerprints in FreeIPA DNS \([https\://github\.com/ansible\-collections/community\.general/pull/8404](https\://github\.com/ansible\-collections/community\.general/pull/8404)\)\.
+* ipa\_otptoken \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* jenkins\_node \- add offline\_message
parameter for updating a Jenkins node offline cause reason when the state is \"disabled\" \(offline\) \([https\://github\.com/ansible\-collections/community\.general/pull/9084](https\://github\.com/ansible\-collections/community\.general/pull/9084)\)\.\"
+* jira \- adjust code ahead of the old VardDict
deprecation \([https\://github\.com/ansible\-collections/community\.general/pull/8856](https\://github\.com/ansible\-collections/community\.general/pull/8856)\)\.
+* jira \- mute the old VarDict
deprecation \([https\://github\.com/ansible\-collections/community\.general/pull/8776](https\://github\.com/ansible\-collections/community\.general/pull/8776)\)\.
+* jira \- replace deprecated params when using decorator cause\_changes
\([https\://github\.com/ansible\-collections/community\.general/pull/8791](https\://github\.com/ansible\-collections/community\.general/pull/8791)\)\.
+* keep\_keys filter plugin \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* keycloak module utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* keycloak\_client \- add client\-x509
choice to client\_authenticator\_type
\([https\://github\.com/ansible\-collections/community\.general/pull/8973](https\://github\.com/ansible\-collections/community\.general/pull/8973)\)\.
+* keycloak\_client \- assign auth flow by name \([https\://github\.com/ansible\-collections/community\.general/pull/8428](https\://github\.com/ansible\-collections/community\.general/pull/8428)\)\.
+* keycloak\_client \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* keycloak\_clientscope \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* keycloak\_identity\_provider \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* keycloak\_realm \- add boolean toggle to configure organization support for a given keycloak realm \([https\://github\.com/ansible\-collections/community\.general/issues/9027](https\://github\.com/ansible\-collections/community\.general/issues/9027)\, [https\://github\.com/ansible\-collections/community\.general/pull/8927/](https\://github\.com/ansible\-collections/community\.general/pull/8927/)\)\.
+* keycloak\_user\_federation \- add module argument allowing users to optout of the removal of unspecified mappers\, for example to keep the keycloak default mappers \([https\://github\.com/ansible\-collections/community\.general/pull/8764](https\://github\.com/ansible\-collections/community\.general/pull/8764)\)\.
+* keycloak\_user\_federation \- add the user federation config parameter referral
to the module arguments \([https\://github\.com/ansible\-collections/community\.general/pull/8954](https\://github\.com/ansible\-collections/community\.general/pull/8954)\)\.
+* keycloak\_user\_federation \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* keycloak\_user\_federation \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* keycloak\_user\_federation \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* linode \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* locale\_gen \- add support for multiple locales \([https\://github\.com/ansible\-collections/community\.general/issues/8677](https\://github\.com/ansible\-collections/community\.general/issues/8677)\, [https\://github\.com/ansible\-collections/community\.general/pull/8682](https\://github\.com/ansible\-collections/community\.general/pull/8682)\)\.
+* lxc\_container \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* lxd\_container \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* manageiq\_provider \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* mattermost \- adds support for message priority \([https\://github\.com/ansible\-collections/community\.general/issues/9068](https\://github\.com/ansible\-collections/community\.general/issues/9068)\, [https\://github\.com/ansible\-collections/community\.general/pull/9087](https\://github\.com/ansible\-collections/community\.general/pull/9087)\)\.
+* memcached\, pickle\, redis\, yaml cache plugins \- make sure that all options are typed \([https\://github\.com/ansible\-collections/community\.general/pull/8624](https\://github\.com/ansible\-collections/community\.general/pull/8624)\)\.
+* memset\_dns\_reload \- replace loop with dict\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* memset\_memstore\_info \- replace loop with dict\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* memset\_server\_info \- replace loop with dict\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* memset\_zone \- replace loop with dict\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* memset\_zone\_domain \- replace loop with dict\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* memset\_zone\_record \- replace loop with dict\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* nmcli \- add conn\_enable
param to reload connection \([https\://github\.com/ansible\-collections/community\.general/issues/3752](https\://github\.com/ansible\-collections/community\.general/issues/3752)\, [https\://github\.com/ansible\-collections/community\.general/issues/8704](https\://github\.com/ansible\-collections/community\.general/issues/8704)\, [https\://github\.com/ansible\-collections/community\.general/pull/8897](https\://github\.com/ansible\-collections/community\.general/pull/8897)\)\.
+* nmcli \- add state\=up
and state\=down
to enable/disable connections \([https\://github\.com/ansible\-collections/community\.general/issues/3752](https\://github\.com/ansible\-collections/community\.general/issues/3752)\, [https\://github\.com/ansible\-collections/community\.general/issues/8704](https\://github\.com/ansible\-collections/community\.general/issues/8704)\, [https\://github\.com/ansible\-collections/community\.general/issues/7152](https\://github\.com/ansible\-collections/community\.general/issues/7152)\, [https\://github\.com/ansible\-collections/community\.general/pull/8897](https\://github\.com/ansible\-collections/community\.general/pull/8897)\)\.
+* nmcli \- better construct when using dict\.items\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* npm \- add force
parameter to allow \-\-force
\([https\://github\.com/ansible\-collections/community\.general/pull/8885](https\://github\.com/ansible\-collections/community\.general/pull/8885)\)\.
+* ocapi\_utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* one\_image \- add create
\, template
and datastore\_id
arguments for image creation \([https\://github\.com/ansible\-collections/community\.general/pull/9075](https\://github\.com/ansible\-collections/community\.general/pull/9075)\)\.
+* one\_image \- add wait\_timeout
argument for adjustable timeouts \([https\://github\.com/ansible\-collections/community\.general/pull/9075](https\://github\.com/ansible\-collections/community\.general/pull/9075)\)\.
+* one\_image \- add option persistent
to manage image persistence \([https\://github\.com/ansible\-collections/community\.general/issues/3578](https\://github\.com/ansible\-collections/community\.general/issues/3578)\, [https\://github\.com/ansible\-collections/community\.general/pull/8889](https\://github\.com/ansible\-collections/community\.general/pull/8889)\)\.
+* one\_image \- extend xsd scheme to make it return a lot more info about image \([https\://github\.com/ansible\-collections/community\.general/pull/8889](https\://github\.com/ansible\-collections/community\.general/pull/8889)\)\.
+* one\_image \- refactor code to make it more similar to one\_template
and one\_vnet
\([https\://github\.com/ansible\-collections/community\.general/pull/8889](https\://github\.com/ansible\-collections/community\.general/pull/8889)\)\.
+* one\_image\_info \- extend xsd scheme to make it return a lot more info about image \([https\://github\.com/ansible\-collections/community\.general/pull/8889](https\://github\.com/ansible\-collections/community\.general/pull/8889)\)\.
+* one\_image\_info \- refactor code to make it more similar to one\_template
and one\_vnet
\([https\://github\.com/ansible\-collections/community\.general/pull/8889](https\://github\.com/ansible\-collections/community\.general/pull/8889)\)\.
+* one\_service \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* one\_vm \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* onepassword lookup plugin \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* open\_iscsi \- allow login to a portal with multiple targets without specifying any of them \([https\://github\.com/ansible\-collections/community\.general/pull/8719](https\://github\.com/ansible\-collections/community\.general/pull/8719)\)\.
+* openbsd\_pkg \- adds diff support to show changes in installed package list\. This does not yet work for check mode \([https\://github\.com/ansible\-collections/community\.general/pull/8402](https\://github\.com/ansible\-collections/community\.general/pull/8402)\)\.
+* opennebula\.py \- add VM id
and VM host
to inventory host data \([https\://github\.com/ansible\-collections/community\.general/pull/8532](https\://github\.com/ansible\-collections/community\.general/pull/8532)\)\.
+* opentelemetry callback plugin \- fix default value for store\_spans\_in\_file
causing traces to be produced to a file named None
\([https\://github\.com/ansible\-collections/community\.general/issues/8566](https\://github\.com/ansible\-collections/community\.general/issues/8566)\, [https\://github\.com/ansible\-collections/community\.general/pull/8741](https\://github\.com/ansible\-collections/community\.general/pull/8741)\)\.
+* opkg \- add return value version
\([https\://github\.com/ansible\-collections/community\.general/pull/9086](https\://github\.com/ansible\-collections/community\.general/pull/9086)\)\.
+* passwordstore lookup plugin \- add subkey creation/update support \([https\://github\.com/ansible\-collections/community\.general/pull/8952](https\://github\.com/ansible\-collections/community\.general/pull/8952)\)\.
+* passwordstore lookup plugin \- add the current user to the lockfile file name to address issues on multi\-user systems \([https\://github\.com/ansible\-collections/community\.general/pull/8689](https\://github\.com/ansible\-collections/community\.general/pull/8689)\)\.
+* pids \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* pipx \- add parameter suffix
to module \([https\://github\.com/ansible\-collections/community\.general/pull/8675](https\://github\.com/ansible\-collections/community\.general/pull/8675)\, [https\://github\.com/ansible\-collections/community\.general/issues/8656](https\://github\.com/ansible\-collections/community\.general/issues/8656)\)\.
+* pipx \- added new states install\_all
\, uninject
\, upgrade\_shared
\, pin
\, and unpin
\([https\://github\.com/ansible\-collections/community\.general/pull/8809](https\://github\.com/ansible\-collections/community\.general/pull/8809)\)\.
+* pipx \- added parameter global
to module \([https\://github\.com/ansible\-collections/community\.general/pull/8793](https\://github\.com/ansible\-collections/community\.general/pull/8793)\)\.
+* pipx \- refactor out parsing of pipx list
output to module utils \([https\://github\.com/ansible\-collections/community\.general/pull/9044](https\://github\.com/ansible\-collections/community\.general/pull/9044)\)\.
+* pipx \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* pipx\_info \- add new return value pinned
\([https\://github\.com/ansible\-collections/community\.general/pull/9044](https\://github\.com/ansible\-collections/community\.general/pull/9044)\)\.
+* pipx\_info \- added parameter global
to module \([https\://github\.com/ansible\-collections/community\.general/pull/8793](https\://github\.com/ansible\-collections/community\.general/pull/8793)\)\.
+* pipx\_info \- refactor out parsing of pipx list
output to module utils \([https\://github\.com/ansible\-collections/community\.general/pull/9044](https\://github\.com/ansible\-collections/community\.general/pull/9044)\)\.
+* pipx\_info \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* pkg5\_publisher \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* pkgng \- add option use\_globs
\(default true
\) to optionally disable glob patterns \([https\://github\.com/ansible\-collections/community\.general/issues/8632](https\://github\.com/ansible\-collections/community\.general/issues/8632)\, [https\://github\.com/ansible\-collections/community\.general/pull/8633](https\://github\.com/ansible\-collections/community\.general/pull/8633)\)\.
+* proxmox \- add disk\_volume
and mount\_volumes
keys for better readability \([https\://github\.com/ansible\-collections/community\.general/pull/8542](https\://github\.com/ansible\-collections/community\.general/pull/8542)\)\.
+* proxmox \- allow specification of the API port when using proxmox\_\* \([https\://github\.com/ansible\-collections/community\.general/issues/8440](https\://github\.com/ansible\-collections/community\.general/issues/8440)\, [https\://github\.com/ansible\-collections/community\.general/pull/8441](https\://github\.com/ansible\-collections/community\.general/pull/8441)\)\.
+* proxmox \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* proxmox \- translate the old disk
and mounts
keys to the new handling internally \([https\://github\.com/ansible\-collections/community\.general/pull/8542](https\://github\.com/ansible\-collections/community\.general/pull/8542)\)\.
+* proxmox inventory plugin \- add new fact for LXC interface details \([https\://github\.com/ansible\-collections/community\.general/pull/8713](https\://github\.com/ansible\-collections/community\.general/pull/8713)\)\.
+* proxmox inventory plugin \- clean up authentication code \([https\://github\.com/ansible\-collections/community\.general/pull/8917](https\://github\.com/ansible\-collections/community\.general/pull/8917)\)\.
+* proxmox inventory plugin \- fix urllib3 InsecureRequestWarnings
not being suppressed when a token is used \([https\://github\.com/ansible\-collections/community\.general/pull/9099](https\://github\.com/ansible\-collections/community\.general/pull/9099)\)\.
+* proxmox\_disk \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* proxmox\_kvm \- adds the ciupgrade
parameter to specify whether cloud\-init should upgrade system packages at first boot \([https\://github\.com/ansible\-collections/community\.general/pull/9066](https\://github\.com/ansible\-collections/community\.general/pull/9066)\)\.
+* proxmox\_kvm \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* proxmox\_kvm \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* proxmox\_template \- small refactor in logic for determining whether a template exists or not \([https\://github\.com/ansible\-collections/community\.general/pull/8516](https\://github\.com/ansible\-collections/community\.general/pull/8516)\)\.
+* proxmox\_vm\_info \- add network
option to retrieve current network information \([https\://github\.com/ansible\-collections/community\.general/pull/8471](https\://github\.com/ansible\-collections/community\.general/pull/8471)\)\.
+* redfish\_\* modules \- adds ciphers
option for custom cipher selection \([https\://github\.com/ansible\-collections/community\.general/pull/8533](https\://github\.com/ansible\-collections/community\.general/pull/8533)\)\.
+* redfish\_command \- add UpdateUserAccountTypes
command \([https\://github\.com/ansible\-collections/community\.general/issues/9058](https\://github\.com/ansible\-collections/community\.general/issues/9058)\, [https\://github\.com/ansible\-collections/community\.general/pull/9059](https\://github\.com/ansible\-collections/community\.general/pull/9059)\)\.
+* redfish\_command \- add wait
and wait\_timeout
options to allow a user to block a command until a service is accessible after performing the requested command \([https\://github\.com/ansible\-collections/community\.general/issues/8051](https\://github\.com/ansible\-collections/community\.general/issues/8051)\, [https\://github\.com/ansible\-collections/community\.general/pull/8434](https\://github\.com/ansible\-collections/community\.general/pull/8434)\)\.
+* redfish\_command \- add handling of the PasswordChangeRequired
message from services in the UpdateUserPassword
command to directly modify the user\'s password if the requested user is the one invoking the operation \([https\://github\.com/ansible\-collections/community\.general/issues/8652](https\://github\.com/ansible\-collections/community\.general/issues/8652)\, [https\://github\.com/ansible\-collections/community\.general/pull/8653](https\://github\.com/ansible\-collections/community\.general/pull/8653)\)\.
+* redfish\_confg \- remove CapacityBytes
from required paramaters of the CreateVolume
command \([https\://github\.com/ansible\-collections/community\.general/pull/8956](https\://github\.com/ansible\-collections/community\.general/pull/8956)\)\.
+* redfish\_config \- add parameter storage\_none\_volume\_deletion
to CreateVolume
command in order to control the automatic deletion of non\-RAID volumes \([https\://github\.com/ansible\-collections/community\.general/pull/8990](https\://github\.com/ansible\-collections/community\.general/pull/8990)\)\.
+* redfish\_info \- add command CheckAvailability
to check if a service is accessible \([https\://github\.com/ansible\-collections/community\.general/issues/8051](https\://github\.com/ansible\-collections/community\.general/issues/8051)\, [https\://github\.com/ansible\-collections/community\.general/pull/8434](https\://github\.com/ansible\-collections/community\.general/pull/8434)\)\.
+* redfish\_info \- adds RedfishURI
and StorageId
to Disk inventory \([https\://github\.com/ansible\-collections/community\.general/pull/8937](https\://github\.com/ansible\-collections/community\.general/pull/8937)\)\.
+* redfish\_utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* redfish\_utils module utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* redfish\_utils module utils \- schedule a BIOS configuration job at next reboot when the BIOS config is changed \([https\://github\.com/ansible\-collections/community\.general/pull/9012](https\://github\.com/ansible\-collections/community\.general/pull/9012)\)\.
+* redis cache plugin \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* redis\, redis\_info \- add client\_cert
and client\_key
options to specify path to certificate for Redis authentication \([https\://github\.com/ansible\-collections/community\.general/pull/8654](https\://github\.com/ansible\-collections/community\.general/pull/8654)\)\.
+* redis\_info \- adds support for getting cluster info \([https\://github\.com/ansible\-collections/community\.general/pull/8464](https\://github\.com/ansible\-collections/community\.general/pull/8464)\)\.
+* remove\_keys filter plugin \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* replace\_keys filter plugin \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* scaleway \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* scaleway module utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* scaleway\_compute \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* scaleway\_container \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_container\_info \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_container\_namespace \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_container\_namespace\_info \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_container\_registry \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_container\_registry\_info \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_function \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_function\_info \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_function\_namespace \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_function\_namespace\_info \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8858](https\://github\.com/ansible\-collections/community\.general/pull/8858)\)\.
+* scaleway\_ip \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* scaleway\_lb \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* scaleway\_security\_group \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* scaleway\_security\_group \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* scaleway\_user\_data \- better construct when using dict\.items\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* scaleway\_user\_data \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* sensu\_silence \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* snmp\_facts \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* sorcery \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8833](https\://github\.com/ansible\-collections/community\.general/pull/8833)\)\.
+* sudosu become plugin \- added an option \(alt\_method
\) to enhance compatibility with more versions of su
\([https\://github\.com/ansible\-collections/community\.general/pull/8214](https\://github\.com/ansible\-collections/community\.general/pull/8214)\)\.
+* udm\_dns\_record \- replace loop with dict\.update\(\)
\([https\://github\.com/ansible\-collections/community\.general/pull/8876](https\://github\.com/ansible\-collections/community\.general/pull/8876)\)\.
+* ufw \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* unsafe plugin utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* vardict module utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* vars MH module utils \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8814](https\://github\.com/ansible\-collections/community\.general/pull/8814)\)\.
+* virtualbox inventory plugin \- expose a new parameter enable\_advanced\_group\_parsing
to change how the VirtualBox dynamic inventory parses VM groups \([https\://github\.com/ansible\-collections/community\.general/issues/8508](https\://github\.com/ansible\-collections/community\.general/issues/8508)\, [https\://github\.com/ansible\-collections/community\.general/pull/8510](https\://github\.com/ansible\-collections/community\.general/pull/8510)\)\.
+* vmadm \- replace Python 2\.6 construct with dict comprehensions \([https\://github\.com/ansible\-collections/community\.general/pull/8822](https\://github\.com/ansible\-collections/community\.general/pull/8822)\)\.
+* wdc\_redfish\_command \- minor change to handle upgrade file for Redfish WD platforms \([https\://github\.com/ansible\-collections/community\.general/pull/8444](https\://github\.com/ansible\-collections/community\.general/pull/8444)\)\.
+
+
+### Breaking Changes / Porting Guide
+
+* The collection no longer supports ansible\-core 2\.13 and ansible\-core 2\.14\. While most \(or even all\) modules and plugins might still work with these versions\, they are no longer tested in CI and breakages regarding them will not be fixed \([https\://github\.com/ansible\-collections/community\.general/pull/8921](https\://github\.com/ansible\-collections/community\.general/pull/8921)\)\.
+* cmd\_runner module utils \- CLI arguments created directly from module parameters are no longer assigned a default formatter \([https\://github\.com/ansible\-collections/community\.general/pull/8928](https\://github\.com/ansible\-collections/community\.general/pull/8928)\)\.
+* irc \- the defaults of use\_tls
and validate\_certs
changed from false
to true
\([https\://github\.com/ansible\-collections/community\.general/pull/8918](https\://github\.com/ansible\-collections/community\.general/pull/8918)\)\.
+* rhsm\_repository \- the states present
and absent
have been removed\. Use enabled
and disabled
instead \([https\://github\.com/ansible\-collections/community\.general/pull/8918](https\://github\.com/ansible\-collections/community\.general/pull/8918)\)\.
+
+
+### Deprecated Features
+
+* CmdRunner module util \- setting the value of the ignore\_none
parameter within a CmdRunner
context is deprecated and that feature should be removed in community\.general 12\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/8479](https\://github\.com/ansible\-collections/community\.general/pull/8479)\)\.
+* MH decorator cause\_changes module utils \- deprecate parameters on\_success
and on\_failure
\([https\://github\.com/ansible\-collections/community\.general/pull/8791](https\://github\.com/ansible\-collections/community\.general/pull/8791)\)\.
+* git\_config \- the list\_all
option has been deprecated and will be removed in community\.general 11\.0\.0\. Use the community\.general\.git\_config\_info
module instead \([https\://github\.com/ansible\-collections/community\.general/pull/8453](https\://github\.com/ansible\-collections/community\.general/pull/8453)\)\.
+* git\_config \- using state\=present
without providing value
is deprecated and will be disallowed in community\.general 11\.0\.0\. Use the community\.general\.git\_config\_info
module instead to read a value \([https\://github\.com/ansible\-collections/community\.general/pull/8453](https\://github\.com/ansible\-collections/community\.general/pull/8453)\)\.
+* hipchat \- the hipchat service has been discontinued and the self\-hosted variant has been End of Life since 2020\. The module is therefore deprecated and will be removed from community\.general 11\.0\.0 if nobody provides compelling reasons to still keep it \([https\://github\.com/ansible\-collections/community\.general/pull/8919](https\://github\.com/ansible\-collections/community\.general/pull/8919)\)\.
+* pipx \- support for versions of the command line tool pipx
older than 1\.7\.0
is deprecated and will be removed in community\.general 11\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/8793](https\://github\.com/ansible\-collections/community\.general/pull/8793)\)\.
+* pipx\_info \- support for versions of the command line tool pipx
older than 1\.7\.0
is deprecated and will be removed in community\.general 11\.0\.0 \([https\://github\.com/ansible\-collections/community\.general/pull/8793](https\://github\.com/ansible\-collections/community\.general/pull/8793)\)\.
+
+
+### Removed Features \(previously deprecated\)
+
+* The consul\_acl module has been removed\. Use community\.general\.consul\_token and/or community\.general\.consul\_policy instead \([https\://github\.com/ansible\-collections/community\.general/pull/8921](https\://github\.com/ansible\-collections/community\.general/pull/8921)\)\.
+* The hipchat callback plugin has been removed\. The hipchat service has been discontinued and the self\-hosted variant has been End of Life since 2020 \([https\://github\.com/ansible\-collections/community\.general/pull/8921](https\://github\.com/ansible\-collections/community\.general/pull/8921)\)\.
+* The redhat module utils has been removed \([https\://github\.com/ansible\-collections/community\.general/pull/8921](https\://github\.com/ansible\-collections/community\.general/pull/8921)\)\.
+* The rhn\_channel module has been removed \([https\://github\.com/ansible\-collections/community\.general/pull/8921](https\://github\.com/ansible\-collections/community\.general/pull/8921)\)\.
+* The rhn\_register module has been removed \([https\://github\.com/ansible\-collections/community\.general/pull/8921](https\://github\.com/ansible\-collections/community\.general/pull/8921)\)\.
+* consul \- removed the ack\_params\_state\_absent
option\. It had no effect anymore \([https\://github\.com/ansible\-collections/community\.general/pull/8918](https\://github\.com/ansible\-collections/community\.general/pull/8918)\)\.
+* ejabberd\_user \- removed the logging
option \([https\://github\.com/ansible\-collections/community\.general/pull/8918](https\://github\.com/ansible\-collections/community\.general/pull/8918)\)\.
+* gitlab modules \- remove basic auth feature \([https\://github\.com/ansible\-collections/community\.general/pull/8405](https\://github\.com/ansible\-collections/community\.general/pull/8405)\)\.
+* proxmox\_kvm \- removed the proxmox\_default\_behavior
option\. Explicitly specify the old default values if you were using proxmox\_default\_behavior\=compatibility
\, otherwise simply remove it \([https\://github\.com/ansible\-collections/community\.general/pull/8918](https\://github\.com/ansible\-collections/community\.general/pull/8918)\)\.
+* redhat\_subscriptions \- removed the pool
option\. Use pool\_ids
instead \([https\://github\.com/ansible\-collections/community\.general/pull/8918](https\://github\.com/ansible\-collections/community\.general/pull/8918)\)\.
+
+
+### Bugfixes
+
+* bitwarden lookup plugin \- fix KeyError
in search\_field
\([https\://github\.com/ansible\-collections/community\.general/issues/8549](https\://github\.com/ansible\-collections/community\.general/issues/8549)\, [https\://github\.com/ansible\-collections/community\.general/pull/8557](https\://github\.com/ansible\-collections/community\.general/pull/8557)\)\.
+* bitwarden lookup plugin \- support BWS v0\.3\.0 syntax breaking change \([https\://github\.com/ansible\-collections/community\.general/pull/9028](https\://github\.com/ansible\-collections/community\.general/pull/9028)\)\.
+* cloudflare\_dns \- fix changing Cloudflare SRV records \([https\://github\.com/ansible\-collections/community\.general/issues/8679](https\://github\.com/ansible\-collections/community\.general/issues/8679)\, [https\://github\.com/ansible\-collections/community\.general/pull/8948](https\://github\.com/ansible\-collections/community\.general/pull/8948)\)\.
+* cmd\_runner module utils \- call to get\_best\_parsable\_locales\(\)
was missing parameter \([https\://github\.com/ansible\-collections/community\.general/pull/8929](https\://github\.com/ansible\-collections/community\.general/pull/8929)\)\.
+* collection\_version lookup plugin \- use importlib
directly instead of the deprecated and in ansible\-core 2\.19 removed ansible\.module\_utils\.compat\.importlib
\([https\://github\.com/ansible\-collections/community\.general/pull/9084](https\://github\.com/ansible\-collections/community\.general/pull/9084)\)\.
+* cpanm \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* dig lookup plugin \- fix using only the last nameserver specified \([https\://github\.com/ansible\-collections/community\.general/pull/8970](https\://github\.com/ansible\-collections/community\.general/pull/8970)\)\.
+* django module utils \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* django\_command \- option command
is now split lexically before passed to underlying PythonRunner \([https\://github\.com/ansible\-collections/community\.general/pull/8944](https\://github\.com/ansible\-collections/community\.general/pull/8944)\)\.
+* gconftool2\_info \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* git\_config \- fix behavior of state\=absent
if value
is present \([https\://github\.com/ansible\-collections/community\.general/issues/8436](https\://github\.com/ansible\-collections/community\.general/issues/8436)\, [https\://github\.com/ansible\-collections/community\.general/pull/8452](https\://github\.com/ansible\-collections/community\.general/pull/8452)\)\.
+* gitlab\_group\_access\_token \- fix crash in check mode caused by attempted access to a newly created access token \([https\://github\.com/ansible\-collections/community\.general/pull/8796](https\://github\.com/ansible\-collections/community\.general/pull/8796)\)\.
+* gitlab\_label \- update label\'s color \([https\://github\.com/ansible\-collections/community\.general/pull/9010](https\://github\.com/ansible\-collections/community\.general/pull/9010)\)\.
+* gitlab\_project \- fix container\_expiration\_policy
not being applied when creating a new project \([https\://github\.com/ansible\-collections/community\.general/pull/8790](https\://github\.com/ansible\-collections/community\.general/pull/8790)\)\.
+* gitlab\_project \- fix crash caused by old Gitlab projects not having a container\_expiration\_policy
attribute \([https\://github\.com/ansible\-collections/community\.general/pull/8790](https\://github\.com/ansible\-collections/community\.general/pull/8790)\)\.
+* gitlab\_project\_access\_token \- fix crash in check mode caused by attempted access to a newly created access token \([https\://github\.com/ansible\-collections/community\.general/pull/8796](https\://github\.com/ansible\-collections/community\.general/pull/8796)\)\.
+* gitlab\_runner \- fix paused
parameter being ignored \([https\://github\.com/ansible\-collections/community\.general/pull/8648](https\://github\.com/ansible\-collections/community\.general/pull/8648)\)\.
+* homebrew \- do not fail when brew prints warnings \([https\://github\.com/ansible\-collections/community\.general/pull/8406](https\://github\.com/ansible\-collections/community\.general/pull/8406)\, [https\://github\.com/ansible\-collections/community\.general/issues/7044](https\://github\.com/ansible\-collections/community\.general/issues/7044)\)\.
+* homebrew\_cask \- fix upgrade\_all
returns changed
when nothing upgraded \([https\://github\.com/ansible\-collections/community\.general/issues/8707](https\://github\.com/ansible\-collections/community\.general/issues/8707)\, [https\://github\.com/ansible\-collections/community\.general/pull/8708](https\://github\.com/ansible\-collections/community\.general/pull/8708)\)\.
+* homectl \- the module now tries to use legacycrypt
on Python 3\.13\+ \([https\://github\.com/ansible\-collections/community\.general/issues/4691](https\://github\.com/ansible\-collections/community\.general/issues/4691)\, [https\://github\.com/ansible\-collections/community\.general/pull/8987](https\://github\.com/ansible\-collections/community\.general/pull/8987)\)\.
+* hponcfg \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* ini\_file \- pass absolute paths to module\.atomic\_move\(\)
\([https\://github\.com/ansible/ansible/issues/83950](https\://github\.com/ansible/ansible/issues/83950)\, [https\://github\.com/ansible\-collections/community\.general/pull/8925](https\://github\.com/ansible\-collections/community\.general/pull/8925)\)\.
+* ipa\_host \- add force\_create
\, fix enabled
and disabled
states \([https\://github\.com/ansible\-collections/community\.general/issues/1094](https\://github\.com/ansible\-collections/community\.general/issues/1094)\, [https\://github\.com/ansible\-collections/community\.general/pull/8920](https\://github\.com/ansible\-collections/community\.general/pull/8920)\)\.
+* ipa\_hostgroup \- fix enabled \`\` and \`\`disabled
states \([https\://github\.com/ansible\-collections/community\.general/issues/8408](https\://github\.com/ansible\-collections/community\.general/issues/8408)\, [https\://github\.com/ansible\-collections/community\.general/pull/8900](https\://github\.com/ansible\-collections/community\.general/pull/8900)\)\.
+* java\_keystore \- pass absolute paths to module\.atomic\_move\(\)
\([https\://github\.com/ansible/ansible/issues/83950](https\://github\.com/ansible/ansible/issues/83950)\, [https\://github\.com/ansible\-collections/community\.general/pull/8925](https\://github\.com/ansible\-collections/community\.general/pull/8925)\)\.
+* jenkins\_node \- fixed enabled
\, disable
and absent
node state redirect authorization issues\, same as was present for present
\([https\://github\.com/ansible\-collections/community\.general/pull/9084](https\://github\.com/ansible\-collections/community\.general/pull/9084)\)\.
+* jenkins\_plugin \- pass absolute paths to module\.atomic\_move\(\)
\([https\://github\.com/ansible/ansible/issues/83950](https\://github\.com/ansible/ansible/issues/83950)\, [https\://github\.com/ansible\-collections/community\.general/pull/8925](https\://github\.com/ansible\-collections/community\.general/pull/8925)\)\.
+* kdeconfig \- pass absolute paths to module\.atomic\_move\(\)
\([https\://github\.com/ansible/ansible/issues/83950](https\://github\.com/ansible/ansible/issues/83950)\, [https\://github\.com/ansible\-collections/community\.general/pull/8925](https\://github\.com/ansible\-collections/community\.general/pull/8925)\)\.
+* kernel\_blacklist \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* keycloak\_client \- fix TypeError when sanitizing the saml\.signing\.private\.key
attribute in the module\'s diff or state output\. The sanitize\_cr
function expected a dict where in some cases a list might occur \([https\://github\.com/ansible\-collections/community\.general/pull/8403](https\://github\.com/ansible\-collections/community\.general/pull/8403)\)\.
+* keycloak\_clientscope \- remove IDs from clientscope and its protocol mappers on comparison for changed check \([https\://github\.com/ansible\-collections/community\.general/pull/8545](https\://github\.com/ansible\-collections/community\.general/pull/8545)\)\.
+* keycloak\_clientscope\_type \- fix detect changes in check mode \([https\://github\.com/ansible\-collections/community\.general/issues/9092](https\://github\.com/ansible\-collections/community\.general/issues/9092)\, [https\://github\.com/ansible\-collections/community\.general/pull/9093](https\://github\.com/ansible\-collections/community\.general/pull/9093)\)\.
+* keycloak\_group \- fix crash caused in subgroup creation\. The crash was caused by a missing or empty subGroups
property in Keycloak ≥23 \([https\://github\.com/ansible\-collections/community\.general/issues/8788](https\://github\.com/ansible\-collections/community\.general/issues/8788)\, [https\://github\.com/ansible\-collections/community\.general/pull/8979](https\://github\.com/ansible\-collections/community\.general/pull/8979)\)\.
+* keycloak\_realm \- add normalizations for attributes
and protocol\_mappers
\([https\://github\.com/ansible\-collections/community\.general/pull/8496](https\://github\.com/ansible\-collections/community\.general/pull/8496)\)\.
+* keycloak\_realm \- fix change detection in check mode by sorting the lists in the realms beforehand \([https\://github\.com/ansible\-collections/community\.general/pull/8877](https\://github\.com/ansible\-collections/community\.general/pull/8877)\)\.
+* keycloak\_realm\_key \- fix invalid usage of parent\_id
\([https\://github\.com/ansible\-collections/community\.general/issues/7850](https\://github\.com/ansible\-collections/community\.general/issues/7850)\, [https\://github\.com/ansible\-collections/community\.general/pull/8823](https\://github\.com/ansible\-collections/community\.general/pull/8823)\)\.
+* keycloak\_user\_federation \- add module argument allowing users to configure the update mode for the parameter bindCredential
\([https\://github\.com/ansible\-collections/community\.general/pull/8898](https\://github\.com/ansible\-collections/community\.general/pull/8898)\)\.
+* keycloak\_user\_federation \- fix key error when removing mappers during an update and new mappers are specified in the module args \([https\://github\.com/ansible\-collections/community\.general/pull/8762](https\://github\.com/ansible\-collections/community\.general/pull/8762)\)\.
+* keycloak\_user\_federation \- fix the UnboundLocalError
that occurs when an ID is provided for a user federation mapper \([https\://github\.com/ansible\-collections/community\.general/pull/8831](https\://github\.com/ansible\-collections/community\.general/pull/8831)\)\.
+* keycloak\_user\_federation \- get cleartext IDP clientSecret
from full realm info to detect changes to it \([https\://github\.com/ansible\-collections/community\.general/issues/8294](https\://github\.com/ansible\-collections/community\.general/issues/8294)\, [https\://github\.com/ansible\-collections/community\.general/pull/8735](https\://github\.com/ansible\-collections/community\.general/pull/8735)\)\.
+* keycloak\_user\_federation \- minimize change detection by setting krbPrincipalAttribute
to \'\'
in Keycloak responses if missing \([https\://github\.com/ansible\-collections/community\.general/pull/8785](https\://github\.com/ansible\-collections/community\.general/pull/8785)\)\.
+* keycloak\_user\_federation \- remove lastSync
parameter from Keycloak responses to minimize diff/changes \([https\://github\.com/ansible\-collections/community\.general/pull/8812](https\://github\.com/ansible\-collections/community\.general/pull/8812)\)\.
+* keycloak\_user\_federation \- remove existing user federation mappers if they are not present in the federation configuration and will not be updated \([https\://github\.com/ansible\-collections/community\.general/issues/7169](https\://github\.com/ansible\-collections/community\.general/issues/7169)\, [https\://github\.com/ansible\-collections/community\.general/pull/8695](https\://github\.com/ansible\-collections/community\.general/pull/8695)\)\.
+* keycloak\_user\_federation \- sort desired and after mapper list by name \(analog to before mapper list\) to minimize diff and make change detection more accurate \([https\://github\.com/ansible\-collections/community\.general/pull/8761](https\://github\.com/ansible\-collections/community\.general/pull/8761)\)\.
+* keycloak\_userprofile \- fix empty response when fetching userprofile component by removing parent\=parent\_id
filter \([https\://github\.com/ansible\-collections/community\.general/pull/8923](https\://github\.com/ansible\-collections/community\.general/pull/8923)\)\.
+* keycloak\_userprofile \- improve diff by deserializing the fetched kc\.user\.profile\.config
and serialize it only when sending back \([https\://github\.com/ansible\-collections/community\.general/pull/8940](https\://github\.com/ansible\-collections/community\.general/pull/8940)\)\.
+* launched \- correctly report changed status in check mode \([https\://github\.com/ansible\-collections/community\.general/pull/8406](https\://github\.com/ansible\-collections/community\.general/pull/8406)\)\.
+* locale\_gen \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* lxd\_container \- fix bug introduced in previous commit \([https\://github\.com/ansible\-collections/community\.general/pull/8895](https\://github\.com/ansible\-collections/community\.general/pull/8895)\, [https\://github\.com/ansible\-collections/community\.general/issues/8888](https\://github\.com/ansible\-collections/community\.general/issues/8888)\)\.
+* mksysb \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* modprobe \- fix check mode not being honored for persistent
option \([https\://github\.com/ansible\-collections/community\.general/issues/9051](https\://github\.com/ansible\-collections/community\.general/issues/9051)\, [https\://github\.com/ansible\-collections/community\.general/pull/9052](https\://github\.com/ansible\-collections/community\.general/pull/9052)\)\.
+* nsupdate \- fix \'index out of range\' error when changing NS records by falling back to authority section of the response \([https\://github\.com/ansible\-collections/community\.general/issues/8612](https\://github\.com/ansible\-collections/community\.general/issues/8612)\, [https\://github\.com/ansible\-collections/community\.general/pull/8614](https\://github\.com/ansible\-collections/community\.general/pull/8614)\)\.
+* one\_host \- fix if statements for cases when ID\=0
\([https\://github\.com/ansible\-collections/community\.general/issues/1199](https\://github\.com/ansible\-collections/community\.general/issues/1199)\, [https\://github\.com/ansible\-collections/community\.general/pull/8907](https\://github\.com/ansible\-collections/community\.general/pull/8907)\)\.
+* one\_image \- fix module failing due to a class method typo \([https\://github\.com/ansible\-collections/community\.general/pull/9056](https\://github\.com/ansible\-collections/community\.general/pull/9056)\)\.
+* one\_image\_info \- fix module failing due to a class method typo \([https\://github\.com/ansible\-collections/community\.general/pull/9056](https\://github\.com/ansible\-collections/community\.general/pull/9056)\)\.
+* one\_service \- fix service creation after it was deleted with unique
parameter \([https\://github\.com/ansible\-collections/community\.general/issues/3137](https\://github\.com/ansible\-collections/community\.general/issues/3137)\, [https\://github\.com/ansible\-collections/community\.general/pull/8887](https\://github\.com/ansible\-collections/community\.general/pull/8887)\)\.
+* one\_vnet \- fix module failing due to a variable typo \([https\://github\.com/ansible\-collections/community\.general/pull/9019](https\://github\.com/ansible\-collections/community\.general/pull/9019)\)\.
+* opennebula inventory plugin \- fix invalid reference to IP when inventory runs against NICs with no IPv4 address \([https\://github\.com/ansible\-collections/community\.general/pull/8489](https\://github\.com/ansible\-collections/community\.general/pull/8489)\)\.
+* opentelemetry callback \- do not save the JSON response when using the ansible\.builtin\.uri
module \([https\://github\.com/ansible\-collections/community\.general/pull/8430](https\://github\.com/ansible\-collections/community\.general/pull/8430)\)\.
+* opentelemetry callback \- do not save the content response when using the ansible\.builtin\.slurp
module \([https\://github\.com/ansible\-collections/community\.general/pull/8430](https\://github\.com/ansible\-collections/community\.general/pull/8430)\)\.
+* pam\_limits \- pass absolute paths to module\.atomic\_move\(\)
\([https\://github\.com/ansible/ansible/issues/83950](https\://github\.com/ansible/ansible/issues/83950)\, [https\://github\.com/ansible\-collections/community\.general/pull/8925](https\://github\.com/ansible\-collections/community\.general/pull/8925)\)\.
+* paman \- do not fail if an empty list of packages has been provided and there is nothing to do \([https\://github\.com/ansible\-collections/community\.general/pull/8514](https\://github\.com/ansible\-collections/community\.general/pull/8514)\)\.
+* pipx \- it was ignoring global
when listing existing applications \([https\://github\.com/ansible\-collections/community\.general/pull/9044](https\://github\.com/ansible\-collections/community\.general/pull/9044)\)\.
+* pipx module utils \- add missing command line formatter for argument spec\_metadata
\([https\://github\.com/ansible\-collections/community\.general/pull/9044](https\://github\.com/ansible\-collections/community\.general/pull/9044)\)\.
+* pipx\_info \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* proxmox \- fix idempotency on creation of mount volumes using Proxmox\' special \\:\
syntax \([https\://github\.com/ansible\-collections/community\.general/issues/8407](https\://github\.com/ansible\-collections/community\.general/issues/8407)\, [https\://github\.com/ansible\-collections/community\.general/pull/8542](https\://github\.com/ansible\-collections/community\.general/pull/8542)\)\.
+* proxmox \- fixed an issue where the new volume handling incorrectly converted null
values into \"None\"
strings \([https\://github\.com/ansible\-collections/community\.general/pull/8646](https\://github\.com/ansible\-collections/community\.general/pull/8646)\)\.
+* proxmox \- fixed an issue where volume strings where overwritten instead of appended to in the new build\_volume\(\)
method \([https\://github\.com/ansible\-collections/community\.general/pull/8646](https\://github\.com/ansible\-collections/community\.general/pull/8646)\)\.
+* proxmox \- removed the forced conversion of non\-string values to strings to be consistent with the module documentation \([https\://github\.com/ansible\-collections/community\.general/pull/8646](https\://github\.com/ansible\-collections/community\.general/pull/8646)\)\.
+* proxmox inventory plugin \- fixed a possible error on concatenating responses from proxmox\. In case an API call unexpectedly returned an empty result\, the inventory failed with a fatal error\. Added check for empty response \([https\://github\.com/ansible\-collections/community\.general/issues/8798](https\://github\.com/ansible\-collections/community\.general/issues/8798)\, [https\://github\.com/ansible\-collections/community\.general/pull/8794](https\://github\.com/ansible\-collections/community\.general/pull/8794)\)\.
+* python\_runner module utils \- parameter path\_prefix
was being handled as string when it should be a list \([https\://github\.com/ansible\-collections/community\.general/pull/8944](https\://github\.com/ansible\-collections/community\.general/pull/8944)\)\.
+* redfish\_utils module utils \- do not fail when language is not exactly \"en\" \([https\://github\.com/ansible\-collections/community\.general/pull/8613](https\://github\.com/ansible\-collections/community\.general/pull/8613)\)\.
+* redfish\_utils module utils \- fix issue with URI parsing to gracefully handling trailing slashes when extracting member identifiers \([https\://github\.com/ansible\-collections/community\.general/issues/9047](https\://github\.com/ansible\-collections/community\.general/issues/9047)\, [https\://github\.com/ansible\-collections/community\.general/pull/9057](https\://github\.com/ansible\-collections/community\.general/pull/9057)\)\.
+* snap \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* snap\_alias \- use new VarDict
to prevent deprecation warning \([https\://github\.com/ansible\-collections/community\.general/issues/8410](https\://github\.com/ansible\-collections/community\.general/issues/8410)\, [https\://github\.com/ansible\-collections/community\.general/pull/8411](https\://github\.com/ansible\-collections/community\.general/pull/8411)\)\.
+* udm\_user \- the module now tries to use legacycrypt
on Python 3\.13\+ \([https\://github\.com/ansible\-collections/community\.general/issues/4690](https\://github\.com/ansible\-collections/community\.general/issues/4690)\, [https\://github\.com/ansible\-collections/community\.general/pull/8987](https\://github\.com/ansible\-collections/community\.general/pull/8987)\)\.
+
+
+### Known Issues
+
+* jenkins\_node \- the module is not able to update offline message when node is already offline due to internally using toggleOffline API \([https\://github\.com/ansible\-collections/community\.general/pull/9084](https\://github\.com/ansible\-collections/community\.general/pull/9084)\)\.
+
+
+### New Plugins
+
+
+#### Filter
+
+* community\.general\.keep\_keys \- Keep specific keys from dictionaries in a list\.
+* community\.general\.remove\_keys \- Remove specific keys from dictionaries in a list\.
+* community\.general\.replace\_keys \- Replace specific keys in a list of dictionaries\.
+* community\.general\.reveal\_ansible\_type \- Return input type\.
+
+
+#### Test
+
+* community\.general\.ansible\_type \- Validate input type\.
+
+
+### New Modules
+
+* community\.general\.bootc\_manage \- Bootc Switch and Upgrade\.
+* community\.general\.consul\_agent\_check \- Add\, modify\, and delete checks within a consul cluster\.
+* community\.general\.consul\_agent\_service \- Add\, modify and delete services within a consul cluster\.
+* community\.general\.django\_check \- Wrapper for C\(django\-admin check\)\.
+* community\.general\.django\_createcachetable \- Wrapper for C\(django\-admin createcachetable\)\.
+* community\.general\.homebrew\_services \- Services manager for Homebrew\.
+* community\.general\.ipa\_getkeytab \- Manage keytab file in FreeIPA\.
+* community\.general\.jenkins\_node \- Manage Jenkins nodes\.
+* community\.general\.keycloak\_component \- Allows administration of Keycloak components via Keycloak API\.
+* community\.general\.keycloak\_realm\_keys\_metadata\_info \- Allows obtaining Keycloak realm keys metadata via Keycloak API\.
+* community\.general\.keycloak\_userprofile \- Allows managing Keycloak User Profiles\.
+* community\.general\.krb\_ticket \- Kerberos utils for managing tickets\.
+* community\.general\.one\_vnet \- Manages OpenNebula virtual networks\.
+* community\.general\.zypper\_repository\_info \- List Zypper repositories\.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 119e04e170..be5218f651 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -1,6 +1,937 @@
-Placeholder changelog
-=====================
+===============================
+Community General Release Notes
+===============================
-This file is a placeholder; a version-specific ``CHANGELOG-vX.rst`` will be generated during releases from fragments
-under ``changelogs/fragments``. On release branches once a release has been created, consult the branch's version-specific
-file for changes that have occurred in that branch.
+.. contents:: Topics
+
+This changelog describes changes after version 9.0.0.
+
+v10.5.0
+=======
+
+Release Summary
+---------------
+
+Regular bugfix and feature release.
+
+Minor Changes
+-------------
+
+- CmdRunner module utils - the convenience method ``cmd_runner_fmt.as_fixed()`` now accepts multiple arguments as a list (https://github.com/ansible-collections/community.general/pull/9893).
+- apache2_mod_proxy - code simplification, no change in functionality (https://github.com/ansible-collections/community.general/pull/9457).
+- consul_token - fix idempotency when ``policies`` or ``roles`` are supplied by name (https://github.com/ansible-collections/community.general/issues/9841, https://github.com/ansible-collections/community.general/pull/9845).
+- keycloak_realm - remove ID requirement when creating a realm to allow Keycloak generating its own realm ID (https://github.com/ansible-collections/community.general/pull/9768).
+- nmap inventory plugin - adds ``dns_servers`` option for specifying DNS servers for name resolution. Accepts hostnames or IP addresses in the same format as the ``exclude`` option (https://github.com/ansible-collections/community.general/pull/9849).
+- proxmox_kvm - add missing audio hardware device handling (https://github.com/ansible-collections/community.general/issues/5192, https://github.com/ansible-collections/community.general/pull/9847).
+- redfish_config - add command ``SetPowerRestorePolicy`` to set the desired power state of the system when power is restored (https://github.com/ansible-collections/community.general/pull/9837).
+- redfish_info - add command ``GetPowerRestorePolicy`` to get the desired power state of the system when power is restored (https://github.com/ansible-collections/community.general/pull/9824).
+- rocketchat - option ``is_pre740`` has been added to control the format of the payload. For Rocket.Chat 7.4.0 or newer, it must be set to ``false`` (https://github.com/ansible-collections/community.general/pull/9882).
+- slack callback plugin - add ``http_agent`` option to enable the user to set a custom user agent for slack callback plugin (https://github.com/ansible-collections/community.general/issues/9813, https://github.com/ansible-collections/community.general/pull/9836).
+- systemd_info - add wildcard expression support in ``unitname`` option (https://github.com/ansible-collections/community.general/pull/9821).
+- systemd_info - extend support to timer units (https://github.com/ansible-collections/community.general/pull/9891).
+- vmadm - add new options ``flexible_disk_size`` and ``owner_uuid`` (https://github.com/ansible-collections/community.general/pull/9892).
+
+Bugfixes
+--------
+
+- cloudlare_dns - handle exhausted response stream in case of HTTP errors to show nice error message to the user (https://github.com/ansible-collections/community.general/issues/9782, https://github.com/ansible-collections/community.general/pull/9818).
+- dnf_versionlock - add support for dnf5 (https://github.com/ansible-collections/community.general/issues/9556).
+- homebrew - fix crash when package names include tap (https://github.com/ansible-collections/community.general/issues/9777, https://github.com/ansible-collections/community.general/pull/9803).
+- homebrew_cask - handle unusual brew version strings (https://github.com/ansible-collections/community.general/issues/8432, https://github.com/ansible-collections/community.general/pull/9881).
+- nmcli - enable changing only the order of DNS servers or search suffixes (https://github.com/ansible-collections/community.general/issues/8724, https://github.com/ansible-collections/community.general/pull/9880).
+- proxmox - add missing key selection of ``'status'`` key to ``get_lxc_status`` (https://github.com/ansible-collections/community.general/issues/9696, https://github.com/ansible-collections/community.general/pull/9809).
+- proxmox_vm_info - the module no longer expects that the key ``template`` exists in a dictionary returned by Proxmox (https://github.com/ansible-collections/community.general/issues/9875, https://github.com/ansible-collections/community.general/pull/9910).
+- sudoers - display stdout and stderr raised while failed validation (https://github.com/ansible-collections/community.general/issues/9674, https://github.com/ansible-collections/community.general/pull/9871).
+
+New Modules
+-----------
+
+- community.general.pacemaker_resource - Manage pacemaker resources.
+
+v10.4.0
+=======
+
+Release Summary
+---------------
+
+Regular bugfix and feature release.
+
+Minor Changes
+-------------
+
+- bitwarden lookup plugin - add new option ``collection_name`` to filter results by collection name, and new option ``result_count`` to validate number of results (https://github.com/ansible-collections/community.general/pull/9728).
+- incus connection plugin - adds ``remote_user`` and ``incus_become_method`` parameters for allowing a non-root user to connect to an Incus instance (https://github.com/ansible-collections/community.general/pull/9743).
+- iocage inventory plugin - the new parameter ``hooks_results`` of the plugin is a list of files inside a jail that provide configuration parameters for the inventory. The inventory plugin reads the files from the jails and put the contents into the items of created variable ``iocage_hooks`` (https://github.com/ansible-collections/community.general/issues/9650, https://github.com/ansible-collections/community.general/pull/9651).
+- jira - adds ``client_cert`` and ``client_key`` parameters for supporting client certificate authentification when connecting to Jira (https://github.com/ansible-collections/community.general/pull/9753).
+- lldp - adds ``multivalues`` parameter to control behavior when lldpctl outputs an attribute multiple times (https://github.com/ansible-collections/community.general/pull/9657).
+- lvg - add ``remove_extra_pvs`` parameter to control if ansible should remove physical volumes which are not in the ``pvs`` parameter (https://github.com/ansible-collections/community.general/pull/9698).
+- lxd connection plugin - adds ``remote_user`` and ``lxd_become_method`` parameters for allowing a non-root user to connect to an LXD instance (https://github.com/ansible-collections/community.general/pull/9659).
+- nmcli - adds VRF support with new ``type`` value ``vrf`` and new ``slave_type`` value ``vrf`` as well as new ``table`` parameter (https://github.com/ansible-collections/community.general/pull/9658, https://github.com/ansible-collections/community.general/issues/8014).
+- proxmox_kvm - allow hibernation and suspending of VMs (https://github.com/ansible-collections/community.general/issues/9620, https://github.com/ansible-collections/community.general/pull/9653).
+- redfish_command - add ``PowerFullPowerCycle`` to power command options (https://github.com/ansible-collections/community.general/pull/9729).
+- ssh_config - add ``other_options`` option (https://github.com/ansible-collections/community.general/issues/8053, https://github.com/ansible-collections/community.general/pull/9684).
+- xen_orchestra inventory plugin - add ``use_vm_uuid`` and ``use_host_uuid`` boolean options to allow switching over to using VM/Xen name labels instead of UUIDs as item names (https://github.com/ansible-collections/community.general/pull/9787).
+
+Deprecated Features
+-------------------
+
+- profitbricks - module is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+- profitbricks_datacenter - module is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+- profitbricks_nic - module is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+- profitbricks_volume - module is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+- profitbricks_volume_attachments - module is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+
+Bugfixes
+--------
+
+- apache2_mod_proxy - make compatible with Python 3 (https://github.com/ansible-collections/community.general/pull/9762).
+- apache2_mod_proxy - passing the cluster's page as referer for the member's pages. This makes the module actually work again for halfway modern Apache versions. According to some comments founds on the net the referer was required since at least 2019 for some versions of Apache 2 (https://github.com/ansible-collections/community.general/pull/9762).
+- elasticsearch_plugin - fix ``ERROR: D is not a recognized option`` issue when configuring proxy settings (https://github.com/ansible-collections/community.general/pull/9774, https://github.com/ansible-collections/community.general/issues/9773).
+- ipa_host - module revoked existing host certificates even if ``user_certificate`` was not given (https://github.com/ansible-collections/community.general/pull/9694).
+- keycloak_client - in check mode, detect whether the lists in before client (for example redirect URI list) contain items that the lists in the desired client do not contain (https://github.com/ansible-collections/community.general/pull/9739).
+- lldp - fix crash caused by certain lldpctl output where an attribute is defined as branch and leaf (https://github.com/ansible-collections/community.general/pull/9657).
+- onepassword_doc lookup plugin - ensure that 1Password Connect support also works for this plugin (https://github.com/ansible-collections/community.general/pull/9625).
+- passwordstore lookup plugin - fix subkey creation even when ``create=false`` (https://github.com/ansible-collections/community.general/issues/9105, https://github.com/ansible-collections/community.general/pull/9106).
+- proxmox inventory plugin - plugin did not update cache correctly after ``meta: refresh_inventory`` (https://github.com/ansible-collections/community.general/issues/9710, https://github.com/ansible-collections/community.general/pull/9760).
+- redhat_subscription - use the "enable_content" option (when available) when
+ registering using D-Bus, to ensure that subscription-manager enables the
+ content on registration; this is particular important on EL 10+ and Fedora
+ 41+
+ (https://github.com/ansible-collections/community.general/pull/9778).
+- zfs - fix handling of multi-line values of user-defined ZFS properties (https://github.com/ansible-collections/community.general/pull/6264).
+- zfs_facts - parameter ``type`` now accepts multple values as documented (https://github.com/ansible-collections/community.general/issues/5909, https://github.com/ansible-collections/community.general/pull/9697).
+
+New Modules
+-----------
+
+- community.general.systemd_info - Gather C(systemd) unit info.
+
+v10.3.1
+=======
+
+Release Summary
+---------------
+
+Bugfix release.
+
+Minor Changes
+-------------
+
+- onepassword_ssh_key - refactor to move code to lookup class (https://github.com/ansible-collections/community.general/pull/9633).
+
+Bugfixes
+--------
+
+- cloudflare_dns - fix crash when deleting a DNS record or when updating a record with ``solo=true`` (https://github.com/ansible-collections/community.general/issues/9652, https://github.com/ansible-collections/community.general/pull/9649).
+- homebrew - make package name parsing more resilient (https://github.com/ansible-collections/community.general/pull/9665, https://github.com/ansible-collections/community.general/issues/9641).
+- keycloak module utils - replaces missing return in get_role_composites method which caused it to return None instead of composite roles (https://github.com/ansible-collections/community.general/issues/9678, https://github.com/ansible-collections/community.general/pull/9691).
+- keycloak_client - fix and improve existing tests. The module showed a diff without actual changes, solved by improving the ``normalise_cr()`` function (https://github.com/ansible-collections/community.general/pull/9644).
+- proxmox - adds the ``pubkey`` parameter (back to) the ``update`` state (https://github.com/ansible-collections/community.general/issues/9642, https://github.com/ansible-collections/community.general/pull/9645).
+- proxmox - fixes a typo in the translation of the ``pubkey`` parameter to proxmox' ``ssh-public-keys`` (https://github.com/ansible-collections/community.general/issues/9642, https://github.com/ansible-collections/community.general/pull/9645).
+- xml - ensure file descriptor is closed (https://github.com/ansible-collections/community.general/pull/9695).
+
+v10.3.0
+=======
+
+Release Summary
+---------------
+
+Regular bugfix and feature release.
+
+Minor Changes
+-------------
+
+- MH module utils - delegate ``debug`` to the underlying ``AnsibleModule`` instance or issues a warning if an attribute already exists with that name (https://github.com/ansible-collections/community.general/pull/9577).
+- apache2_mod_proxy - better handling regexp extraction (https://github.com/ansible-collections/community.general/pull/9609).
+- apache2_mod_proxy - change type of ``state`` to a list of strings. No change for the users (https://github.com/ansible-collections/community.general/pull/9600).
+- apache2_mod_proxy - improve readability when using results from ``fecth_url()`` (https://github.com/ansible-collections/community.general/pull/9608).
+- apache2_mod_proxy - refactor repeated code into method (https://github.com/ansible-collections/community.general/pull/9599).
+- apache2_mod_proxy - remove unused parameter and code from ``Balancer`` constructor (https://github.com/ansible-collections/community.general/pull/9614).
+- apache2_mod_proxy - simplified and improved string manipulation (https://github.com/ansible-collections/community.general/pull/9614).
+- apache2_mod_proxy - use ``deps`` to handle dependencies (https://github.com/ansible-collections/community.general/pull/9612).
+- cgroup_memory_recap callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- chroot connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- cloud_init_data_facts - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- cobbler inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- context_demo callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- counter filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- counter_enabled callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- cpanm - enable usage of option ``--with-recommends`` (https://github.com/ansible-collections/community.general/issues/9554, https://github.com/ansible-collections/community.general/pull/9555).
+- cpanm - enable usage of option ``--with-suggests`` (https://github.com/ansible-collections/community.general/pull/9555).
+- crc32 filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- cronvar - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- crypttab - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- default_without_diff callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- dense callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- dict filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- dict_kv filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- diy callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- doas become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- dzdo become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- elastic callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- from_csv filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- from_ini filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- funcd connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- gitlab_runners inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- groupby_as_dict filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- hashids filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- icinga2 inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- incus connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- iocage connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- iocage inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- iocage inventory plugin - the new parameter ``sudo`` of the plugin lets the command ``iocage list -l`` to run as root on the iocage host. This is needed to get the IPv4 of a running DHCP jail (https://github.com/ansible-collections/community.general/issues/9572, https://github.com/ansible-collections/community.general/pull/9573).
+- iptables_state action plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- jabber callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- jail connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- jc filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- jira - transition operation now has ``status_id`` to directly reference wanted transition (https://github.com/ansible-collections/community.general/pull/9602).
+- json_query filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- keep_keys filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- keycloak_* modules - ``refresh_token`` parameter added. When multiple authentication parameters are provided (``token``, ``refresh_token``, and ``auth_username``/``auth_password``), modules will now automatically retry requests upon authentication errors (401), using in order the token, refresh token, and username/password (https://github.com/ansible-collections/community.general/pull/9494).
+- known_hosts - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- ksu become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- linode inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- lists filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- lists_mergeby filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- log_plays callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- loganalytics callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- logdna callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- logentries callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- logstash callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- lxc connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- lxd connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- lxd inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- machinectl become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- mail callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- memcached cache plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- nmap inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- nmcli - add a option ``fail_over_mac`` (https://github.com/ansible-collections/community.general/issues/9570, https://github.com/ansible-collections/community.general/pull/9571).
+- nrdp callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- null callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- one_template - adds ``filter`` option for retrieving templates which are not owned by the user (https://github.com/ansible-collections/community.general/pull/9547, https://github.com/ansible-collections/community.general/issues/9278).
+- online inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- opennebula inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- opentelemetry callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- parted - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- pbrun become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- pfexec become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- pickle cache plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- pmrun become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- proxmox - refactors the proxmox module (https://github.com/ansible-collections/community.general/pull/9225).
+- proxmox inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- proxmox_pct_remote connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- proxmox_template - add support for checksum validation with new options ``checksum_algorithm`` and ``checksum`` (https://github.com/ansible-collections/community.general/issues/9553, https://github.com/ansible-collections/community.general/pull/9601).
+- pulp_repo - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- qubes connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- random_mac filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- redfish_info - add command ``GetAccountServiceConfig`` to get full information about AccountService configuration (https://github.com/ansible-collections/community.general/pull/9403).
+- redhat_subscription - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- redis cache plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- remove_keys filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- replace_keys filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- reveal_ansible_type filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- run0 become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- saltstack connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- say callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- scaleway inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- selective callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- sesu become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- shutdown action plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- slack callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- snap - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9598).
+- snap_alias - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9598).
+- solaris_zone - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- sorcery - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- splunk callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- stackpath_compute inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- sudosu become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- sumologic callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- syslog_json callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- time filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- timestamp callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- timezone - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+- to_ini filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- ufw - add support for ``vrrp`` protocol (https://github.com/ansible-collections/community.general/issues/9562, https://github.com/ansible-collections/community.general/pull/9582).
+- unicode_normalize filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- unixy callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- version_sort filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+- virtualbox inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- xen_orchestra inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+- yaml cache plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- yaml callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+- zone connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+
+Deprecated Features
+-------------------
+
+- MH module utils - attribute ``debug`` definition in subclasses of MH is now deprecated, as that name will become a delegation to ``AnsibleModule`` in community.general 12.0.0, and any such attribute will be overridden by that delegation in that version (https://github.com/ansible-collections/community.general/pull/9577).
+- proxmox - removes default value ``false`` of ``update`` parameter. This will be changed to a default of ``true`` in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/9225).
+
+Security Fixes
+--------------
+
+- keycloak_client - Sanitize ``saml.encryption.private.key`` so it does not show in the logs (https://github.com/ansible-collections/community.general/pull/9621).
+
+Bugfixes
+--------
+
+- homebrew - fix incorrect handling of homebrew modules when a tap is requested (https://github.com/ansible-collections/community.general/pull/9546, https://github.com/ansible-collections/community.general/issues/9533).
+- iocage inventory plugin - the plugin parses the IP4 tab of the jails list and put the elements into the new variable ``iocage_ip4_dict``. In multiple interface format the variable ``iocage_ip4`` keeps the comma-separated list of IP4 (https://github.com/ansible-collections/community.general/issues/9538).
+- pipx - honor option ``global`` when ``state=latest`` (https://github.com/ansible-collections/community.general/pull/9623).
+- proxmox - fixes idempotency of template conversions (https://github.com/ansible-collections/community.general/pull/9225, https://github.com/ansible-collections/community.general/issues/8811).
+- proxmox - fixes incorrect parsing for bind-only mounts (https://github.com/ansible-collections/community.general/pull/9225, https://github.com/ansible-collections/community.general/issues/8982).
+- proxmox - fixes issues with disk_volume variable (https://github.com/ansible-collections/community.general/pull/9225, https://github.com/ansible-collections/community.general/issues/9065).
+- proxmox module utils - fixes ignoring of ``choose_first_if_multiple`` argument in ``get_vmid`` (https://github.com/ansible-collections/community.general/pull/9225).
+- redhat_subscription - do not try to unsubscribe (i.e. remove subscriptions)
+ when unregistering a system: newer versions of subscription-manager, as
+ available in EL 10 and Fedora 41+, do not support entitlements anymore, and
+ thus unsubscribing will fail
+ (https://github.com/ansible-collections/community.general/pull/9578).
+
+New Plugins
+-----------
+
+Connection
+~~~~~~~~~~
+
+- community.general.proxmox_pct_remote - Run tasks in Proxmox LXC container instances using pct CLI via SSH.
+
+Filter
+~~~~~~
+
+- community.general.json_diff - Create a JSON patch by comparing two JSON files.
+- community.general.json_patch - Apply a JSON-Patch (RFC 6902) operation to an object.
+- community.general.json_patch_recipe - Apply JSON-Patch (RFC 6902) operations to an object.
+
+Lookup
+~~~~~~
+
+- community.general.onepassword_ssh_key - Fetch SSH keys stored in 1Password.
+
+New Modules
+-----------
+
+- community.general.proxmox_backup_info - Retrieve information on Proxmox scheduled backups.
+
+v10.2.0
+=======
+
+Release Summary
+---------------
+
+Regular bugfix and feature release.
+
+Minor Changes
+-------------
+
+- bitwarden lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- cgroup_memory_recap callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- chef_databag lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- chroot connection plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- chroot connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- cobbler inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- cobbler inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- collection_version lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- consul_kv lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- context_demo callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- counter_enabled callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- credstash lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- cyberarkpassword lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- cyberarkpassword lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- dense callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- dependent lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- dig lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- dig lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- diy callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- dnstxt lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- dnstxt lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- doas become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319).
+- dsv lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- dzdo become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319).
+- elastic callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- etcd lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- etcd3 lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- etcd3 lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- filetree lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- from_csv filter plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- from_ini filter plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- funcd connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- github_app_access_token lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- gitlab_instance_variable - add support for ``raw`` variables suboption (https://github.com/ansible-collections/community.general/pull/9425).
+- gitlab_runners inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- gitlab_runners inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- hiera lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- icinga2 inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- incus connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- iocage connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- iocage inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- iptables_state action plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9318).
+- jabber callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- jail connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- keycloak - add an action group for Keycloak modules to allow ``module_defaults`` to be set for Keycloak tasks (https://github.com/ansible-collections/community.general/pull/9284).
+- keyring lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- ksu become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319).
+- lastpass lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- linode inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- lmdb_kv lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- lmdb_kv lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- locale_gen - invert the logic to determine ``ubuntu_mode``, making it look first for ``/etc/locale.gen`` (set ``ubuntu_mode`` to ``False``) and only then looking for ``/var/lib/locales/supported.d/`` (set ``ubuntu_mode`` to ``True``) (https://github.com/ansible-collections/community.general/pull/9238, https://github.com/ansible-collections/community.general/issues/9131, https://github.com/ansible-collections/community.general/issues/8487).
+- locale_gen - new return value ``mechanism`` to better express the semantics of the ``ubuntu_mode``, with the possible values being either ``glibc`` (``ubuntu_mode=False``) or ``ubuntu_legacy`` (``ubuntu_mode=True``) (https://github.com/ansible-collections/community.general/pull/9238).
+- log_plays callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- loganalytics callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- logdna callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- logentries callback plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- logentries callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- lxc connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- lxd connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- lxd inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- lxd inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- machinectl become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319).
+- mail callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- manageiq_alert_profiles - improve handling of parameter requirements (https://github.com/ansible-collections/community.general/pull/9449).
+- manifold lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- manifold lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- memcached cache plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9320).
+- merge_variables lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- nmap inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- nmap inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- nrdp callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- onepassword lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- onepassword lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- onepassword_doc lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- online inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- opennebula inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- opennebula inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- opentelemetry callback plugin - remove code handling Python versions prior to 3.7 (https://github.com/ansible-collections/community.general/pull/9482).
+- opentelemetry callback plugin - remove code handling Python versions prior to 3.7 (https://github.com/ansible-collections/community.general/pull/9503).
+- opentelemetry callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- pacemaker_cluster - remove unused code (https://github.com/ansible-collections/community.general/pull/9471).
+- pacemaker_cluster - using safer mechanism to run external command (https://github.com/ansible-collections/community.general/pull/9471).
+- passwordstore lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- pbrun become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319).
+- pfexec become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319).
+- pmrun become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319).
+- proxmox inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- proxmox inventory plugin - strip whitespace from ``user``, ``token_id``, and ``token_secret`` (https://github.com/ansible-collections/community.general/issues/9227, https://github.com/ansible-collections/community.general/pull/9228/).
+- proxmox inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- proxmox module utils - add method ``api_task_complete`` that can wait for task completion and return error message (https://github.com/ansible-collections/community.general/pull/9256).
+- proxmox_backup - refactor permission checking to improve code readability and maintainability (https://github.com/ansible-collections/community.general/pull/9239).
+- qubes connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- random_pet lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- redis cache plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- redis cache plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9320).
+- redis lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- revbitspss lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- saltstack connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- say callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- scaleway inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- scaleway inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- selective callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- sesu become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319).
+- shelvefile lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- shutdown action plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- shutdown action plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9318).
+- slack callback plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- slack callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- splunk callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- stackpath_compute inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- sudosu become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319).
+- timestamp callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- to_ini filter plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- tss lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- tss lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+- unixy callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- virtualbox inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+- virtualbox inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- xbps - add ``root`` and ``repository`` options to enable bootstrapping new void installations (https://github.com/ansible-collections/community.general/pull/9174).
+- xen_orchestra inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+- xfconf - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9226).
+- xfconf_info - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9226).
+- yaml callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+- zone connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+- zypper - add ``quiet`` option (https://github.com/ansible-collections/community.general/pull/9270).
+- zypper - add ``simple_errors`` option (https://github.com/ansible-collections/community.general/pull/9270).
+
+Deprecated Features
+-------------------
+
+- atomic_container - module is deprecated and will be removed in community.general 13.0.0 (https://github.com/ansible-collections/community.general/pull/9487).
+- atomic_host - module is deprecated and will be removed in community.general 13.0.0 (https://github.com/ansible-collections/community.general/pull/9487).
+- atomic_image - module is deprecated and will be removed in community.general 13.0.0 (https://github.com/ansible-collections/community.general/pull/9487).
+- facter - module is deprecated and will be removed in community.general 12.0.0, use ``community.general.facter_facts`` instead (https://github.com/ansible-collections/community.general/pull/9451).
+- locale_gen - ``ubuntu_mode=True``, or ``mechanism=ubuntu_legacy`` is deprecated and will be removed in community.general 13.0.0 (https://github.com/ansible-collections/community.general/pull/9238).
+- pure module utils - the module utils is deprecated and will be removed from community.general 12.0.0. The modules using this were removed in community.general 3.0.0 (https://github.com/ansible-collections/community.general/pull/9432).
+- purestorage doc fragments - the doc fragment is deprecated and will be removed from community.general 12.0.0. The modules using this were removed in community.general 3.0.0 (https://github.com/ansible-collections/community.general/pull/9432).
+- sensu_check - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- sensu_client - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- sensu_handler - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- sensu_silence - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- sensu_subscription - module is deprecated and will be removed in community.general 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+- slack - the default value ``auto`` of the ``prepend_hash`` option is deprecated and will change to ``never`` in community.general 12.0.0 (https://github.com/ansible-collections/community.general/pull/9443).
+- yaml callback plugin - deprecate plugin in favor of ``result_format=yaml`` in plugin ``ansible.bulitin.default`` (https://github.com/ansible-collections/community.general/pull/9456).
+
+Security Fixes
+--------------
+
+- keycloak_authentication - API calls did not properly set the ``priority`` during update resulting in incorrectly sorted authentication flows. This apparently only affects Keycloak 25 or newer (https://github.com/ansible-collections/community.general/pull/9263).
+
+Bugfixes
+--------
+
+- dig lookup plugin - correctly handle ``NoNameserver`` exception (https://github.com/ansible-collections/community.general/pull/9363, https://github.com/ansible-collections/community.general/issues/9362).
+- homebrew - fix incorrect handling of aliased homebrew modules when the alias is requested (https://github.com/ansible-collections/community.general/pull/9255, https://github.com/ansible-collections/community.general/issues/9240).
+- htpasswd - report changes when file permissions are adjusted (https://github.com/ansible-collections/community.general/issues/9485, https://github.com/ansible-collections/community.general/pull/9490).
+- proxmox_backup - fix incorrect key lookup in vmid permission check (https://github.com/ansible-collections/community.general/pull/9223).
+- proxmox_disk - fix async method and make ``resize_disk`` method handle errors correctly (https://github.com/ansible-collections/community.general/pull/9256).
+- proxmox_template - fix the wrong path called on ``proxmox_template.task_status`` (https://github.com/ansible-collections/community.general/issues/9276, https://github.com/ansible-collections/community.general/pull/9277).
+- qubes connection plugin - fix the printing of debug information (https://github.com/ansible-collections/community.general/pull/9334).
+- redfish_utils module utils - Fix ``VerifyBiosAttributes`` command on multi system resource nodes (https://github.com/ansible-collections/community.general/pull/9234).
+
+New Plugins
+-----------
+
+Inventory
+~~~~~~~~~
+
+- community.general.iocage - iocage inventory source.
+
+New Modules
+-----------
+
+- community.general.android_sdk - Manages Android SDK packages.
+- community.general.ldap_inc - Use the Modify-Increment LDAP V3 feature to increment an attribute value.
+- community.general.systemd_creds_decrypt - C(systemd)'s C(systemd-creds decrypt) plugin.
+- community.general.systemd_creds_encrypt - C(systemd)'s C(systemd-creds encrypt) plugin.
+
+v10.1.0
+=======
+
+Release Summary
+---------------
+
+Regular bugfix and feature release.
+
+Minor Changes
+-------------
+
+- alternatives - add ``family`` parameter that allows to utilize the ``--family`` option available in RedHat version of update-alternatives (https://github.com/ansible-collections/community.general/issues/5060, https://github.com/ansible-collections/community.general/pull/9096).
+- cloudflare_dns - add support for ``comment`` and ``tags`` (https://github.com/ansible-collections/community.general/pull/9132).
+- deps module utils - add ``deps.clear()`` to clear out previously declared dependencies (https://github.com/ansible-collections/community.general/pull/9179).
+- homebrew - greatly speed up module when multiple packages are passed in the ``name`` option (https://github.com/ansible-collections/community.general/pull/9181).
+- homebrew - remove duplicated package name validation (https://github.com/ansible-collections/community.general/pull/9076).
+- iso_extract - adds ``password`` parameter that is passed to 7z (https://github.com/ansible-collections/community.general/pull/9159).
+- launchd - add ``plist`` option for services such as sshd, where the plist filename doesn't match the service name (https://github.com/ansible-collections/community.general/pull/9102).
+- nmcli - add ``sriov`` parameter that enables support for SR-IOV settings (https://github.com/ansible-collections/community.general/pull/9168).
+- pipx - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9180).
+- pipx_info - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9180).
+- proxmox_template - add server side artifact fetching support (https://github.com/ansible-collections/community.general/pull/9113).
+- redfish_command - add ``update_custom_oem_header``, ``update_custom_oem_params``, and ``update_custom_oem_mime_type`` options (https://github.com/ansible-collections/community.general/pull/9123).
+- redfish_utils module utils - remove redundant code (https://github.com/ansible-collections/community.general/pull/9190).
+- rpm_ostree_pkg - added the options ``apply_live`` (https://github.com/ansible-collections/community.general/pull/9167).
+- rpm_ostree_pkg - added the return value ``needs_reboot`` (https://github.com/ansible-collections/community.general/pull/9167).
+- scaleway_lb - minor simplification in the code (https://github.com/ansible-collections/community.general/pull/9189).
+- ssh_config - add ``dynamicforward`` option (https://github.com/ansible-collections/community.general/pull/9192).
+
+Deprecated Features
+-------------------
+
+- opkg - deprecate value ``""`` for parameter ``force`` (https://github.com/ansible-collections/community.general/pull/9172).
+- redfish_utils module utils - deprecate method ``RedfishUtils._init_session()`` (https://github.com/ansible-collections/community.general/pull/9190).
+
+Bugfixes
+--------
+
+- dnf_config_manager - fix hanging when prompting to import GPG keys (https://github.com/ansible-collections/community.general/pull/9124, https://github.com/ansible-collections/community.general/issues/8830).
+- dnf_config_manager - forces locale to ``C`` before module starts. If the locale was set to non-English, the output of the ``dnf config-manager`` could not be parsed (https://github.com/ansible-collections/community.general/pull/9157, https://github.com/ansible-collections/community.general/issues/9046).
+- flatpak - force the locale language to ``C`` when running the flatpak command (https://github.com/ansible-collections/community.general/pull/9187, https://github.com/ansible-collections/community.general/issues/8883).
+- gio_mime - fix command line when determining version of ``gio`` (https://github.com/ansible-collections/community.general/pull/9171, https://github.com/ansible-collections/community.general/issues/9158).
+- github_key - in check mode, a faulty call to ```datetime.strftime(...)``` was being made which generated an exception (https://github.com/ansible-collections/community.general/issues/9185).
+- homebrew_cask - allow ``+`` symbol in Homebrew cask name validation regex (https://github.com/ansible-collections/community.general/pull/9128).
+- keycloak_clientscope_type - sort the default and optional clientscope lists to improve the diff (https://github.com/ansible-collections/community.general/pull/9202).
+- slack - fail if Slack API response is not OK with error message (https://github.com/ansible-collections/community.general/pull/9198).
+
+New Plugins
+-----------
+
+Filter
+~~~~~~
+
+- community.general.accumulate - Produce a list of accumulated sums of the input list contents.
+
+New Modules
+-----------
+
+- community.general.decompress - Decompresses compressed files.
+- community.general.proxmox_backup - Start a VM backup in Proxmox VE cluster.
+
+v10.0.1
+=======
+
+Release Summary
+---------------
+
+Bugfix release for inclusion in Ansible 11.0.0rc1.
+
+Bugfixes
+--------
+
+- keycloak_client - fix diff by removing code that turns the attributes dict which contains additional settings into a list (https://github.com/ansible-collections/community.general/pull/9077).
+- keycloak_clientscope - fix diff and ``end_state`` by removing the code that turns the attributes dict, which contains additional config items, into a list (https://github.com/ansible-collections/community.general/pull/9082).
+- redfish_utils module utils - remove undocumented default applytime (https://github.com/ansible-collections/community.general/pull/9114).
+
+v10.0.0
+=======
+
+Release Summary
+---------------
+
+This is release 10.0.0 of ``community.general``, released on 2024-11-04.
+
+Minor Changes
+-------------
+
+- CmdRunner module util - argument formats can be specified as plain functions without calling ``cmd_runner_fmt.as_func()`` (https://github.com/ansible-collections/community.general/pull/8479).
+- CmdRunner module utils - the parameter ``force_lang`` now supports the special value ``auto`` which will automatically try and determine the best parsable locale in the system (https://github.com/ansible-collections/community.general/pull/8517).
+- MH module utils - add parameter ``when`` to ``cause_changes`` decorator (https://github.com/ansible-collections/community.general/pull/8766).
+- MH module utils - minor refactor in decorators (https://github.com/ansible-collections/community.general/pull/8766).
+- alternatives - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- ansible_galaxy_install - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9060).
+- ansible_galaxy_install - add upgrade feature (https://github.com/ansible-collections/community.general/pull/8431, https://github.com/ansible-collections/community.general/issues/8351).
+- ansible_galaxy_install - minor refactor in the module (https://github.com/ansible-collections/community.general/pull/8413).
+- apache2_mod_proxy - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- apache2_mod_proxy - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- cargo - add option ``directory``, which allows source directory to be specified (https://github.com/ansible-collections/community.general/pull/8480).
+- cgroup_memory_recap, hipchat, jabber, log_plays, loganalytics, logentries, logstash, slack, splunk, sumologic, syslog_json callback plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8628).
+- chef_databag, consul_kv, cyberarkpassword, dsv, etcd, filetree, hiera, onepassword, onepassword_doc, onepassword_raw, passwordstore, redis, shelvefile, tss lookup plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8626).
+- chroot, funcd, incus, iocage, jail, lxc, lxd, qubes, zone connection plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8627).
+- cmd_runner module utils - add decorator ``cmd_runner_fmt.stack`` (https://github.com/ansible-collections/community.general/pull/8415).
+- cmd_runner module utils - refactor argument formatting code to its own Python module (https://github.com/ansible-collections/community.general/pull/8964).
+- cmd_runner_fmt module utils - simplify implementation of ``cmd_runner_fmt.as_bool_not()`` (https://github.com/ansible-collections/community.general/pull/8512).
+- cobbler, linode, lxd, nmap, online, scaleway, stackpath_compute, virtualbox inventory plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8625).
+- consul_acl - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- consul_kv - add argument for the datacenter option on Consul API (https://github.com/ansible-collections/community.general/pull/9026).
+- copr - Added ``includepkgs`` and ``excludepkgs`` parameters to limit the list of packages fetched or excluded from the repository(https://github.com/ansible-collections/community.general/pull/8779).
+- cpanm - add return value ``cpanm_version`` (https://github.com/ansible-collections/community.general/pull/9061).
+- credstash lookup plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- csv module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- deco MH module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- dig lookup plugin - add ``port`` option to specify DNS server port (https://github.com/ansible-collections/community.general/pull/8966).
+- django module utils - always retrieve version (https://github.com/ansible-collections/community.general/pull/9063).
+- django_check - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9063).
+- django_command - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9063).
+- django_createcachetable - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9063).
+- doas, dzdo, ksu, machinectl, pbrun, pfexec, pmrun, sesu, sudosu become plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8623).
+- etcd3 - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- flatpak - improve the parsing of Flatpak application IDs based on official guidelines (https://github.com/ansible-collections/community.general/pull/8909).
+- gconftool2 - make use of ``ModuleHelper`` features to simplify code (https://github.com/ansible-collections/community.general/pull/8711).
+- gcontool2 - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9064).
+- gcontool2 module utils - add argument formatter ``version`` (https://github.com/ansible-collections/community.general/pull/9064).
+- gcontool2_info - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9064).
+- gio_mime - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9067).
+- gio_mime - adjust code ahead of the old ``VardDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8855).
+- gio_mime - mute the old ``VarDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8776).
+- gio_mime module utils - add argument formatter ``version`` (https://github.com/ansible-collections/community.general/pull/9067).
+- github_app_access_token lookup plugin - adds new ``private_key`` parameter (https://github.com/ansible-collections/community.general/pull/8989).
+- gitlab_deploy_key - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- gitlab_group - add many new parameters (https://github.com/ansible-collections/community.general/pull/8908).
+- gitlab_group - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- gitlab_group - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- gitlab_issue - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- gitlab_merge_request - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- gitlab_project - add option ``container_expiration_policy`` to schedule container registry cleanup (https://github.com/ansible-collections/community.general/pull/8674).
+- gitlab_project - add option ``issues_access_level`` to enable/disable project issues (https://github.com/ansible-collections/community.general/pull/8760).
+- gitlab_project - add option ``model_registry_access_level`` to disable model registry (https://github.com/ansible-collections/community.general/pull/8688).
+- gitlab_project - add option ``pages_access_level`` to disable project pages (https://github.com/ansible-collections/community.general/pull/8688).
+- gitlab_project - add option ``repository_access_level`` to disable project repository (https://github.com/ansible-collections/community.general/pull/8674).
+- gitlab_project - add option ``service_desk_enabled`` to disable service desk (https://github.com/ansible-collections/community.general/pull/8688).
+- gitlab_project - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- gitlab_project - sorted parameters in order to avoid future merge conflicts (https://github.com/ansible-collections/community.general/pull/8759).
+- gitlab_runner - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- hashids filter plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- homebrew - speed up brew install and upgrade (https://github.com/ansible-collections/community.general/pull/9022).
+- hwc_ecs_instance - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- hwc_evs_disk - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- hwc_vpc_eip - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- hwc_vpc_peering_connect - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- hwc_vpc_port - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- hwc_vpc_subnet - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- icinga2_host - replace loop with dict comprehension (https://github.com/ansible-collections/community.general/pull/8876).
+- imc_rest - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- ipa_dnsrecord - adds ``SSHFP`` record type for managing SSH fingerprints in FreeIPA DNS (https://github.com/ansible-collections/community.general/pull/8404).
+- ipa_otptoken - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- jenkins_node - add ``offline_message`` parameter for updating a Jenkins node offline cause reason when the state is "disabled" (offline) (https://github.com/ansible-collections/community.general/pull/9084)."
+- jira - adjust code ahead of the old ``VardDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8856).
+- jira - mute the old ``VarDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8776).
+- jira - replace deprecated params when using decorator ``cause_changes`` (https://github.com/ansible-collections/community.general/pull/8791).
+- keep_keys filter plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- keycloak module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- keycloak_client - add ``client-x509`` choice to ``client_authenticator_type`` (https://github.com/ansible-collections/community.general/pull/8973).
+- keycloak_client - assign auth flow by name (https://github.com/ansible-collections/community.general/pull/8428).
+- keycloak_client - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- keycloak_clientscope - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- keycloak_identity_provider - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- keycloak_realm - add boolean toggle to configure organization support for a given keycloak realm (https://github.com/ansible-collections/community.general/issues/9027, https://github.com/ansible-collections/community.general/pull/8927/).
+- keycloak_user_federation - add module argument allowing users to optout of the removal of unspecified mappers, for example to keep the keycloak default mappers (https://github.com/ansible-collections/community.general/pull/8764).
+- keycloak_user_federation - add the user federation config parameter ``referral`` to the module arguments (https://github.com/ansible-collections/community.general/pull/8954).
+- keycloak_user_federation - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- keycloak_user_federation - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- keycloak_user_federation - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- linode - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- locale_gen - add support for multiple locales (https://github.com/ansible-collections/community.general/issues/8677, https://github.com/ansible-collections/community.general/pull/8682).
+- lxc_container - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- lxd_container - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- manageiq_provider - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- mattermost - adds support for message priority (https://github.com/ansible-collections/community.general/issues/9068, https://github.com/ansible-collections/community.general/pull/9087).
+- memcached, pickle, redis, yaml cache plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8624).
+- memset_dns_reload - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- memset_memstore_info - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- memset_server_info - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- memset_zone - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- memset_zone_domain - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- memset_zone_record - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- nmcli - add ``conn_enable`` param to reload connection (https://github.com/ansible-collections/community.general/issues/3752, https://github.com/ansible-collections/community.general/issues/8704, https://github.com/ansible-collections/community.general/pull/8897).
+- nmcli - add ``state=up`` and ``state=down`` to enable/disable connections (https://github.com/ansible-collections/community.general/issues/3752, https://github.com/ansible-collections/community.general/issues/8704, https://github.com/ansible-collections/community.general/issues/7152, https://github.com/ansible-collections/community.general/pull/8897).
+- nmcli - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- npm - add ``force`` parameter to allow ``--force`` (https://github.com/ansible-collections/community.general/pull/8885).
+- ocapi_utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- one_image - add ``create``, ``template`` and ``datastore_id`` arguments for image creation (https://github.com/ansible-collections/community.general/pull/9075).
+- one_image - add ``wait_timeout`` argument for adjustable timeouts (https://github.com/ansible-collections/community.general/pull/9075).
+- one_image - add option ``persistent`` to manage image persistence (https://github.com/ansible-collections/community.general/issues/3578, https://github.com/ansible-collections/community.general/pull/8889).
+- one_image - extend xsd scheme to make it return a lot more info about image (https://github.com/ansible-collections/community.general/pull/8889).
+- one_image - refactor code to make it more similar to ``one_template`` and ``one_vnet`` (https://github.com/ansible-collections/community.general/pull/8889).
+- one_image_info - extend xsd scheme to make it return a lot more info about image (https://github.com/ansible-collections/community.general/pull/8889).
+- one_image_info - refactor code to make it more similar to ``one_template`` and ``one_vnet`` (https://github.com/ansible-collections/community.general/pull/8889).
+- one_service - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- one_vm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- onepassword lookup plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- open_iscsi - allow login to a portal with multiple targets without specifying any of them (https://github.com/ansible-collections/community.general/pull/8719).
+- openbsd_pkg - adds diff support to show changes in installed package list. This does not yet work for check mode (https://github.com/ansible-collections/community.general/pull/8402).
+- opennebula.py - add VM ``id`` and VM ``host`` to inventory host data (https://github.com/ansible-collections/community.general/pull/8532).
+- opentelemetry callback plugin - fix default value for ``store_spans_in_file`` causing traces to be produced to a file named ``None`` (https://github.com/ansible-collections/community.general/issues/8566, https://github.com/ansible-collections/community.general/pull/8741).
+- opkg - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9086).
+- passwordstore lookup plugin - add subkey creation/update support (https://github.com/ansible-collections/community.general/pull/8952).
+- passwordstore lookup plugin - add the current user to the lockfile file name to address issues on multi-user systems (https://github.com/ansible-collections/community.general/pull/8689).
+- pids - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- pipx - add parameter ``suffix`` to module (https://github.com/ansible-collections/community.general/pull/8675, https://github.com/ansible-collections/community.general/issues/8656).
+- pipx - added new states ``install_all``, ``uninject``, ``upgrade_shared``, ``pin``, and ``unpin`` (https://github.com/ansible-collections/community.general/pull/8809).
+- pipx - added parameter ``global`` to module (https://github.com/ansible-collections/community.general/pull/8793).
+- pipx - refactor out parsing of ``pipx list`` output to module utils (https://github.com/ansible-collections/community.general/pull/9044).
+- pipx - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- pipx_info - add new return value ``pinned`` (https://github.com/ansible-collections/community.general/pull/9044).
+- pipx_info - added parameter ``global`` to module (https://github.com/ansible-collections/community.general/pull/8793).
+- pipx_info - refactor out parsing of ``pipx list`` output to module utils (https://github.com/ansible-collections/community.general/pull/9044).
+- pipx_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- pkg5_publisher - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- pkgng - add option ``use_globs`` (default ``true``) to optionally disable glob patterns (https://github.com/ansible-collections/community.general/issues/8632, https://github.com/ansible-collections/community.general/pull/8633).
+- proxmox - add ``disk_volume`` and ``mount_volumes`` keys for better readability (https://github.com/ansible-collections/community.general/pull/8542).
+- proxmox - allow specification of the API port when using proxmox_* (https://github.com/ansible-collections/community.general/issues/8440, https://github.com/ansible-collections/community.general/pull/8441).
+- proxmox - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- proxmox - translate the old ``disk`` and ``mounts`` keys to the new handling internally (https://github.com/ansible-collections/community.general/pull/8542).
+- proxmox inventory plugin - add new fact for LXC interface details (https://github.com/ansible-collections/community.general/pull/8713).
+- proxmox inventory plugin - clean up authentication code (https://github.com/ansible-collections/community.general/pull/8917).
+- proxmox inventory plugin - fix urllib3 ``InsecureRequestWarnings`` not being suppressed when a token is used (https://github.com/ansible-collections/community.general/pull/9099).
+- proxmox_disk - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- proxmox_kvm - adds the ``ciupgrade`` parameter to specify whether cloud-init should upgrade system packages at first boot (https://github.com/ansible-collections/community.general/pull/9066).
+- proxmox_kvm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- proxmox_kvm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- proxmox_template - small refactor in logic for determining whether a template exists or not (https://github.com/ansible-collections/community.general/pull/8516).
+- proxmox_vm_info - add ``network`` option to retrieve current network information (https://github.com/ansible-collections/community.general/pull/8471).
+- redfish_* modules - adds ``ciphers`` option for custom cipher selection (https://github.com/ansible-collections/community.general/pull/8533).
+- redfish_command - add ``UpdateUserAccountTypes`` command (https://github.com/ansible-collections/community.general/issues/9058, https://github.com/ansible-collections/community.general/pull/9059).
+- redfish_command - add ``wait`` and ``wait_timeout`` options to allow a user to block a command until a service is accessible after performing the requested command (https://github.com/ansible-collections/community.general/issues/8051, https://github.com/ansible-collections/community.general/pull/8434).
+- redfish_command - add handling of the ``PasswordChangeRequired`` message from services in the ``UpdateUserPassword`` command to directly modify the user's password if the requested user is the one invoking the operation (https://github.com/ansible-collections/community.general/issues/8652, https://github.com/ansible-collections/community.general/pull/8653).
+- redfish_confg - remove ``CapacityBytes`` from required paramaters of the ``CreateVolume`` command (https://github.com/ansible-collections/community.general/pull/8956).
+- redfish_config - add parameter ``storage_none_volume_deletion`` to ``CreateVolume`` command in order to control the automatic deletion of non-RAID volumes (https://github.com/ansible-collections/community.general/pull/8990).
+- redfish_info - add command ``CheckAvailability`` to check if a service is accessible (https://github.com/ansible-collections/community.general/issues/8051, https://github.com/ansible-collections/community.general/pull/8434).
+- redfish_info - adds ``RedfishURI`` and ``StorageId`` to Disk inventory (https://github.com/ansible-collections/community.general/pull/8937).
+- redfish_utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- redfish_utils module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- redfish_utils module utils - schedule a BIOS configuration job at next reboot when the BIOS config is changed (https://github.com/ansible-collections/community.general/pull/9012).
+- redis cache plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- redis, redis_info - add ``client_cert`` and ``client_key`` options to specify path to certificate for Redis authentication (https://github.com/ansible-collections/community.general/pull/8654).
+- redis_info - adds support for getting cluster info (https://github.com/ansible-collections/community.general/pull/8464).
+- remove_keys filter plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- replace_keys filter plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- scaleway - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- scaleway module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- scaleway_compute - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- scaleway_container - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_container_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_container_namespace - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_container_namespace_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_container_registry - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_container_registry_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_function - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_function_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_function_namespace - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_function_namespace_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+- scaleway_ip - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- scaleway_lb - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- scaleway_security_group - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- scaleway_security_group - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- scaleway_user_data - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- scaleway_user_data - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- sensu_silence - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- snmp_facts - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- sorcery - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+- sudosu become plugin - added an option (``alt_method``) to enhance compatibility with more versions of ``su`` (https://github.com/ansible-collections/community.general/pull/8214).
+- udm_dns_record - replace loop with ``dict.update()`` (https://github.com/ansible-collections/community.general/pull/8876).
+- ufw - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- unsafe plugin utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- vardict module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- vars MH module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+- virtualbox inventory plugin - expose a new parameter ``enable_advanced_group_parsing`` to change how the VirtualBox dynamic inventory parses VM groups (https://github.com/ansible-collections/community.general/issues/8508, https://github.com/ansible-collections/community.general/pull/8510).
+- vmadm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+- wdc_redfish_command - minor change to handle upgrade file for Redfish WD platforms (https://github.com/ansible-collections/community.general/pull/8444).
+
+Breaking Changes / Porting Guide
+--------------------------------
+
+- The collection no longer supports ansible-core 2.13 and ansible-core 2.14. While most (or even all) modules and plugins might still work with these versions, they are no longer tested in CI and breakages regarding them will not be fixed (https://github.com/ansible-collections/community.general/pull/8921).
+- cmd_runner module utils - CLI arguments created directly from module parameters are no longer assigned a default formatter (https://github.com/ansible-collections/community.general/pull/8928).
+- irc - the defaults of ``use_tls`` and ``validate_certs`` changed from ``false`` to ``true`` (https://github.com/ansible-collections/community.general/pull/8918).
+- rhsm_repository - the states ``present`` and ``absent`` have been removed. Use ``enabled`` and ``disabled`` instead (https://github.com/ansible-collections/community.general/pull/8918).
+
+Deprecated Features
+-------------------
+
+- CmdRunner module util - setting the value of the ``ignore_none`` parameter within a ``CmdRunner`` context is deprecated and that feature should be removed in community.general 12.0.0 (https://github.com/ansible-collections/community.general/pull/8479).
+- MH decorator cause_changes module utils - deprecate parameters ``on_success`` and ``on_failure`` (https://github.com/ansible-collections/community.general/pull/8791).
+- git_config - the ``list_all`` option has been deprecated and will be removed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead (https://github.com/ansible-collections/community.general/pull/8453).
+- git_config - using ``state=present`` without providing ``value`` is deprecated and will be disallowed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead to read a value (https://github.com/ansible-collections/community.general/pull/8453).
+- hipchat - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The module is therefore deprecated and will be removed from community.general 11.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/pull/8919).
+- pipx - support for versions of the command line tool ``pipx`` older than ``1.7.0`` is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/8793).
+- pipx_info - support for versions of the command line tool ``pipx`` older than ``1.7.0`` is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/8793).
+
+Removed Features (previously deprecated)
+----------------------------------------
+
+- The consul_acl module has been removed. Use community.general.consul_token and/or community.general.consul_policy instead (https://github.com/ansible-collections/community.general/pull/8921).
+- The hipchat callback plugin has been removed. The hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020 (https://github.com/ansible-collections/community.general/pull/8921).
+- The redhat module utils has been removed (https://github.com/ansible-collections/community.general/pull/8921).
+- The rhn_channel module has been removed (https://github.com/ansible-collections/community.general/pull/8921).
+- The rhn_register module has been removed (https://github.com/ansible-collections/community.general/pull/8921).
+- consul - removed the ``ack_params_state_absent`` option. It had no effect anymore (https://github.com/ansible-collections/community.general/pull/8918).
+- ejabberd_user - removed the ``logging`` option (https://github.com/ansible-collections/community.general/pull/8918).
+- gitlab modules - remove basic auth feature (https://github.com/ansible-collections/community.general/pull/8405).
+- proxmox_kvm - removed the ``proxmox_default_behavior`` option. Explicitly specify the old default values if you were using ``proxmox_default_behavior=compatibility``, otherwise simply remove it (https://github.com/ansible-collections/community.general/pull/8918).
+- redhat_subscriptions - removed the ``pool`` option. Use ``pool_ids`` instead (https://github.com/ansible-collections/community.general/pull/8918).
+
+Bugfixes
+--------
+
+- bitwarden lookup plugin - fix ``KeyError`` in ``search_field`` (https://github.com/ansible-collections/community.general/issues/8549, https://github.com/ansible-collections/community.general/pull/8557).
+- bitwarden lookup plugin - support BWS v0.3.0 syntax breaking change (https://github.com/ansible-collections/community.general/pull/9028).
+- cloudflare_dns - fix changing Cloudflare SRV records (https://github.com/ansible-collections/community.general/issues/8679, https://github.com/ansible-collections/community.general/pull/8948).
+- cmd_runner module utils - call to ``get_best_parsable_locales()`` was missing parameter (https://github.com/ansible-collections/community.general/pull/8929).
+- collection_version lookup plugin - use ``importlib`` directly instead of the deprecated and in ansible-core 2.19 removed ``ansible.module_utils.compat.importlib`` (https://github.com/ansible-collections/community.general/pull/9084).
+- cpanm - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- dig lookup plugin - fix using only the last nameserver specified (https://github.com/ansible-collections/community.general/pull/8970).
+- django module utils - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- django_command - option ``command`` is now split lexically before passed to underlying PythonRunner (https://github.com/ansible-collections/community.general/pull/8944).
+- gconftool2_info - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- git_config - fix behavior of ``state=absent`` if ``value`` is present (https://github.com/ansible-collections/community.general/issues/8436, https://github.com/ansible-collections/community.general/pull/8452).
+- gitlab_group_access_token - fix crash in check mode caused by attempted access to a newly created access token (https://github.com/ansible-collections/community.general/pull/8796).
+- gitlab_label - update label's color (https://github.com/ansible-collections/community.general/pull/9010).
+- gitlab_project - fix ``container_expiration_policy`` not being applied when creating a new project (https://github.com/ansible-collections/community.general/pull/8790).
+- gitlab_project - fix crash caused by old Gitlab projects not having a ``container_expiration_policy`` attribute (https://github.com/ansible-collections/community.general/pull/8790).
+- gitlab_project_access_token - fix crash in check mode caused by attempted access to a newly created access token (https://github.com/ansible-collections/community.general/pull/8796).
+- gitlab_runner - fix ``paused`` parameter being ignored (https://github.com/ansible-collections/community.general/pull/8648).
+- homebrew - do not fail when brew prints warnings (https://github.com/ansible-collections/community.general/pull/8406, https://github.com/ansible-collections/community.general/issues/7044).
+- homebrew_cask - fix ``upgrade_all`` returns ``changed`` when nothing upgraded (https://github.com/ansible-collections/community.general/issues/8707, https://github.com/ansible-collections/community.general/pull/8708).
+- homectl - the module now tries to use ``legacycrypt`` on Python 3.13+ (https://github.com/ansible-collections/community.general/issues/4691, https://github.com/ansible-collections/community.general/pull/8987).
+- hponcfg - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- ini_file - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925).
+- ipa_host - add ``force_create``, fix ``enabled`` and ``disabled`` states (https://github.com/ansible-collections/community.general/issues/1094, https://github.com/ansible-collections/community.general/pull/8920).
+- ipa_hostgroup - fix ``enabled `` and ``disabled`` states (https://github.com/ansible-collections/community.general/issues/8408, https://github.com/ansible-collections/community.general/pull/8900).
+- java_keystore - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925).
+- jenkins_node - fixed ``enabled``, ``disable`` and ``absent`` node state redirect authorization issues, same as was present for ``present`` (https://github.com/ansible-collections/community.general/pull/9084).
+- jenkins_plugin - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925).
+- kdeconfig - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925).
+- kernel_blacklist - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- keycloak_client - fix TypeError when sanitizing the ``saml.signing.private.key`` attribute in the module's diff or state output. The ``sanitize_cr`` function expected a dict where in some cases a list might occur (https://github.com/ansible-collections/community.general/pull/8403).
+- keycloak_clientscope - remove IDs from clientscope and its protocol mappers on comparison for changed check (https://github.com/ansible-collections/community.general/pull/8545).
+- keycloak_clientscope_type - fix detect changes in check mode (https://github.com/ansible-collections/community.general/issues/9092, https://github.com/ansible-collections/community.general/pull/9093).
+- keycloak_group - fix crash caused in subgroup creation. The crash was caused by a missing or empty ``subGroups`` property in Keycloak ≥23 (https://github.com/ansible-collections/community.general/issues/8788, https://github.com/ansible-collections/community.general/pull/8979).
+- keycloak_realm - add normalizations for ``attributes`` and ``protocol_mappers`` (https://github.com/ansible-collections/community.general/pull/8496).
+- keycloak_realm - fix change detection in check mode by sorting the lists in the realms beforehand (https://github.com/ansible-collections/community.general/pull/8877).
+- keycloak_realm_key - fix invalid usage of ``parent_id`` (https://github.com/ansible-collections/community.general/issues/7850, https://github.com/ansible-collections/community.general/pull/8823).
+- keycloak_user_federation - add module argument allowing users to configure the update mode for the parameter ``bindCredential`` (https://github.com/ansible-collections/community.general/pull/8898).
+- keycloak_user_federation - fix key error when removing mappers during an update and new mappers are specified in the module args (https://github.com/ansible-collections/community.general/pull/8762).
+- keycloak_user_federation - fix the ``UnboundLocalError`` that occurs when an ID is provided for a user federation mapper (https://github.com/ansible-collections/community.general/pull/8831).
+- keycloak_user_federation - get cleartext IDP ``clientSecret`` from full realm info to detect changes to it (https://github.com/ansible-collections/community.general/issues/8294, https://github.com/ansible-collections/community.general/pull/8735).
+- keycloak_user_federation - minimize change detection by setting ``krbPrincipalAttribute`` to ``''`` in Keycloak responses if missing (https://github.com/ansible-collections/community.general/pull/8785).
+- keycloak_user_federation - remove ``lastSync`` parameter from Keycloak responses to minimize diff/changes (https://github.com/ansible-collections/community.general/pull/8812).
+- keycloak_user_federation - remove existing user federation mappers if they are not present in the federation configuration and will not be updated (https://github.com/ansible-collections/community.general/issues/7169, https://github.com/ansible-collections/community.general/pull/8695).
+- keycloak_user_federation - sort desired and after mapper list by name (analog to before mapper list) to minimize diff and make change detection more accurate (https://github.com/ansible-collections/community.general/pull/8761).
+- keycloak_userprofile - fix empty response when fetching userprofile component by removing ``parent=parent_id`` filter (https://github.com/ansible-collections/community.general/pull/8923).
+- keycloak_userprofile - improve diff by deserializing the fetched ``kc.user.profile.config`` and serialize it only when sending back (https://github.com/ansible-collections/community.general/pull/8940).
+- launched - correctly report changed status in check mode (https://github.com/ansible-collections/community.general/pull/8406).
+- locale_gen - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- lxd_container - fix bug introduced in previous commit (https://github.com/ansible-collections/community.general/pull/8895, https://github.com/ansible-collections/community.general/issues/8888).
+- mksysb - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- modprobe - fix check mode not being honored for ``persistent`` option (https://github.com/ansible-collections/community.general/issues/9051, https://github.com/ansible-collections/community.general/pull/9052).
+- nsupdate - fix 'index out of range' error when changing NS records by falling back to authority section of the response (https://github.com/ansible-collections/community.general/issues/8612, https://github.com/ansible-collections/community.general/pull/8614).
+- one_host - fix if statements for cases when ``ID=0`` (https://github.com/ansible-collections/community.general/issues/1199, https://github.com/ansible-collections/community.general/pull/8907).
+- one_image - fix module failing due to a class method typo (https://github.com/ansible-collections/community.general/pull/9056).
+- one_image_info - fix module failing due to a class method typo (https://github.com/ansible-collections/community.general/pull/9056).
+- one_service - fix service creation after it was deleted with ``unique`` parameter (https://github.com/ansible-collections/community.general/issues/3137, https://github.com/ansible-collections/community.general/pull/8887).
+- one_vnet - fix module failing due to a variable typo (https://github.com/ansible-collections/community.general/pull/9019).
+- opennebula inventory plugin - fix invalid reference to IP when inventory runs against NICs with no IPv4 address (https://github.com/ansible-collections/community.general/pull/8489).
+- opentelemetry callback - do not save the JSON response when using the ``ansible.builtin.uri`` module (https://github.com/ansible-collections/community.general/pull/8430).
+- opentelemetry callback - do not save the content response when using the ``ansible.builtin.slurp`` module (https://github.com/ansible-collections/community.general/pull/8430).
+- pam_limits - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925).
+- paman - do not fail if an empty list of packages has been provided and there is nothing to do (https://github.com/ansible-collections/community.general/pull/8514).
+- pipx - it was ignoring ``global`` when listing existing applications (https://github.com/ansible-collections/community.general/pull/9044).
+- pipx module utils - add missing command line formatter for argument ``spec_metadata`` (https://github.com/ansible-collections/community.general/pull/9044).
+- pipx_info - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- proxmox - fix idempotency on creation of mount volumes using Proxmox' special ``:`` syntax (https://github.com/ansible-collections/community.general/issues/8407, https://github.com/ansible-collections/community.general/pull/8542).
+- proxmox - fixed an issue where the new volume handling incorrectly converted ``null`` values into ``"None"`` strings (https://github.com/ansible-collections/community.general/pull/8646).
+- proxmox - fixed an issue where volume strings where overwritten instead of appended to in the new ``build_volume()`` method (https://github.com/ansible-collections/community.general/pull/8646).
+- proxmox - removed the forced conversion of non-string values to strings to be consistent with the module documentation (https://github.com/ansible-collections/community.general/pull/8646).
+- proxmox inventory plugin - fixed a possible error on concatenating responses from proxmox. In case an API call unexpectedly returned an empty result, the inventory failed with a fatal error. Added check for empty response (https://github.com/ansible-collections/community.general/issues/8798, https://github.com/ansible-collections/community.general/pull/8794).
+- python_runner module utils - parameter ``path_prefix`` was being handled as string when it should be a list (https://github.com/ansible-collections/community.general/pull/8944).
+- redfish_utils module utils - do not fail when language is not exactly "en" (https://github.com/ansible-collections/community.general/pull/8613).
+- redfish_utils module utils - fix issue with URI parsing to gracefully handling trailing slashes when extracting member identifiers (https://github.com/ansible-collections/community.general/issues/9047, https://github.com/ansible-collections/community.general/pull/9057).
+- snap - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- snap_alias - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+- udm_user - the module now tries to use ``legacycrypt`` on Python 3.13+ (https://github.com/ansible-collections/community.general/issues/4690, https://github.com/ansible-collections/community.general/pull/8987).
+
+Known Issues
+------------
+
+- jenkins_node - the module is not able to update offline message when node is already offline due to internally using toggleOffline API (https://github.com/ansible-collections/community.general/pull/9084).
+
+New Plugins
+-----------
+
+Filter
+~~~~~~
+
+- community.general.keep_keys - Keep specific keys from dictionaries in a list.
+- community.general.remove_keys - Remove specific keys from dictionaries in a list.
+- community.general.replace_keys - Replace specific keys in a list of dictionaries.
+- community.general.reveal_ansible_type - Return input type.
+
+Test
+~~~~
+
+- community.general.ansible_type - Validate input type.
+
+New Modules
+-----------
+
+- community.general.bootc_manage - Bootc Switch and Upgrade.
+- community.general.consul_agent_check - Add, modify, and delete checks within a consul cluster.
+- community.general.consul_agent_service - Add, modify and delete services within a consul cluster.
+- community.general.django_check - Wrapper for C(django-admin check).
+- community.general.django_createcachetable - Wrapper for C(django-admin createcachetable).
+- community.general.homebrew_services - Services manager for Homebrew.
+- community.general.ipa_getkeytab - Manage keytab file in FreeIPA.
+- community.general.jenkins_node - Manage Jenkins nodes.
+- community.general.keycloak_component - Allows administration of Keycloak components via Keycloak API.
+- community.general.keycloak_realm_keys_metadata_info - Allows obtaining Keycloak realm keys metadata via Keycloak API.
+- community.general.keycloak_userprofile - Allows managing Keycloak User Profiles.
+- community.general.krb_ticket - Kerberos utils for managing tickets.
+- community.general.one_vnet - Manages OpenNebula virtual networks.
+- community.general.zypper_repository_info - List Zypper repositories.
diff --git a/README.md b/README.md
index 03dad49f39..beeca12078 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,9 @@ SPDX-License-Identifier: GPL-3.0-or-later
# Community General Collection
-[](https://dev.azure.com/ansible/community.general/_build?definitionId=31)
-[](https://github.com/ansible-collections/community.general/actions)
+[](https://docs.ansible.com/ansible/latest/collections/community/general/)
+[](https://dev.azure.com/ansible/community.general/_build?definitionId=31)
+[](https://github.com/ansible-collections/community.general/actions)
[](https://codecov.io/gh/ansible-collections/community.general)
[](https://api.reuse.software/info/github.com/ansible-collections/community.general)
@@ -116,7 +117,7 @@ See the [Releasing guidelines](https://github.com/ansible/community-docs/blob/ma
## Release notes
-See the [changelog](https://github.com/ansible-collections/community.general/blob/main/CHANGELOG.md).
+See the [changelog](https://github.com/ansible-collections/community.general/blob/stable-10/CHANGELOG.md).
## Roadmap
@@ -135,8 +136,8 @@ See [this issue](https://github.com/ansible-collections/community.general/issues
This collection is primarily licensed and distributed as a whole under the GNU General Public License v3.0 or later.
-See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-collections/community.general/blob/main/COPYING) for the full text.
+See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-collections/community.general/blob/stable-10/COPYING) for the full text.
-Parts of the collection are licensed under the [BSD 2-Clause license](https://github.com/ansible-collections/community.general/blob/main/LICENSES/BSD-2-Clause.txt), the [MIT license](https://github.com/ansible-collections/community.general/blob/main/LICENSES/MIT.txt), and the [PSF 2.0 license](https://github.com/ansible-collections/community.general/blob/main/LICENSES/PSF-2.0.txt).
+Parts of the collection are licensed under the [BSD 2-Clause license](https://github.com/ansible-collections/community.general/blob/stable-10/LICENSES/BSD-2-Clause.txt), the [MIT license](https://github.com/ansible-collections/community.general/blob/stable-10/LICENSES/MIT.txt), and the [PSF 2.0 license](https://github.com/ansible-collections/community.general/blob/stable-10/LICENSES/PSF-2.0.txt).
All files have a machine readable `SDPX-License-Identifier:` comment denoting its respective license(s) or an equivalent entry in an accompanying `.license` file. Only changelog fragments (which will not be part of a release) are covered by a blanket statement in `.reuse/dep5`. This conforms to the [REUSE specification](https://reuse.software/spec/).
diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml
index 5aa97d97e9..10a94fd5b9 100644
--- a/changelogs/changelog.yaml
+++ b/changelogs/changelog.yaml
@@ -1,3 +1,1659 @@
---
ancestor: 9.0.0
-releases: {}
+releases:
+ 10.0.0:
+ changes:
+ breaking_changes:
+ - The collection no longer supports ansible-core 2.13 and ansible-core 2.14.
+ While most (or even all) modules and plugins might still work with these
+ versions, they are no longer tested in CI and breakages regarding them will
+ not be fixed (https://github.com/ansible-collections/community.general/pull/8921).
+ - cmd_runner module utils - CLI arguments created directly from module parameters
+ are no longer assigned a default formatter (https://github.com/ansible-collections/community.general/pull/8928).
+ - irc - the defaults of ``use_tls`` and ``validate_certs`` changed from ``false``
+ to ``true`` (https://github.com/ansible-collections/community.general/pull/8918).
+ - rhsm_repository - the states ``present`` and ``absent`` have been removed.
+ Use ``enabled`` and ``disabled`` instead (https://github.com/ansible-collections/community.general/pull/8918).
+ bugfixes:
+ - bitwarden lookup plugin - fix ``KeyError`` in ``search_field`` (https://github.com/ansible-collections/community.general/issues/8549,
+ https://github.com/ansible-collections/community.general/pull/8557).
+ - bitwarden lookup plugin - support BWS v0.3.0 syntax breaking change (https://github.com/ansible-collections/community.general/pull/9028).
+ - cloudflare_dns - fix changing Cloudflare SRV records (https://github.com/ansible-collections/community.general/issues/8679,
+ https://github.com/ansible-collections/community.general/pull/8948).
+ - cmd_runner module utils - call to ``get_best_parsable_locales()`` was missing
+ parameter (https://github.com/ansible-collections/community.general/pull/8929).
+ - collection_version lookup plugin - use ``importlib`` directly instead of
+ the deprecated and in ansible-core 2.19 removed ``ansible.module_utils.compat.importlib``
+ (https://github.com/ansible-collections/community.general/pull/9084).
+ - cpanm - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410,
+ https://github.com/ansible-collections/community.general/pull/8411).
+ - dig lookup plugin - fix using only the last nameserver specified (https://github.com/ansible-collections/community.general/pull/8970).
+ - django module utils - use new ``VarDict`` to prevent deprecation warning
+ (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
+ - django_command - option ``command`` is now split lexically before passed
+ to underlying PythonRunner (https://github.com/ansible-collections/community.general/pull/8944).
+ - gconftool2_info - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410,
+ https://github.com/ansible-collections/community.general/pull/8411).
+ - git_config - fix behavior of ``state=absent`` if ``value`` is present (https://github.com/ansible-collections/community.general/issues/8436,
+ https://github.com/ansible-collections/community.general/pull/8452).
+ - gitlab_group_access_token - fix crash in check mode caused by attempted
+ access to a newly created access token (https://github.com/ansible-collections/community.general/pull/8796).
+ - gitlab_label - update label's color (https://github.com/ansible-collections/community.general/pull/9010).
+ - gitlab_project - fix ``container_expiration_policy`` not being applied when
+ creating a new project (https://github.com/ansible-collections/community.general/pull/8790).
+ - gitlab_project - fix crash caused by old Gitlab projects not having a ``container_expiration_policy``
+ attribute (https://github.com/ansible-collections/community.general/pull/8790).
+ - gitlab_project_access_token - fix crash in check mode caused by attempted
+ access to a newly created access token (https://github.com/ansible-collections/community.general/pull/8796).
+ - gitlab_runner - fix ``paused`` parameter being ignored (https://github.com/ansible-collections/community.general/pull/8648).
+ - homebrew - do not fail when brew prints warnings (https://github.com/ansible-collections/community.general/pull/8406,
+ https://github.com/ansible-collections/community.general/issues/7044).
+ - homebrew_cask - fix ``upgrade_all`` returns ``changed`` when nothing upgraded
+ (https://github.com/ansible-collections/community.general/issues/8707, https://github.com/ansible-collections/community.general/pull/8708).
+ - homectl - the module now tries to use ``legacycrypt`` on Python 3.13+ (https://github.com/ansible-collections/community.general/issues/4691,
+ https://github.com/ansible-collections/community.general/pull/8987).
+ - hponcfg - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410,
+ https://github.com/ansible-collections/community.general/pull/8411).
+ - ini_file - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950,
+ https://github.com/ansible-collections/community.general/pull/8925).
+ - ipa_host - add ``force_create``, fix ``enabled`` and ``disabled`` states
+ (https://github.com/ansible-collections/community.general/issues/1094, https://github.com/ansible-collections/community.general/pull/8920).
+ - ipa_hostgroup - fix ``enabled `` and ``disabled`` states (https://github.com/ansible-collections/community.general/issues/8408,
+ https://github.com/ansible-collections/community.general/pull/8900).
+ - java_keystore - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950,
+ https://github.com/ansible-collections/community.general/pull/8925).
+ - jenkins_node - fixed ``enabled``, ``disable`` and ``absent`` node state
+ redirect authorization issues, same as was present for ``present`` (https://github.com/ansible-collections/community.general/pull/9084).
+ - jenkins_plugin - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950,
+ https://github.com/ansible-collections/community.general/pull/8925).
+ - kdeconfig - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950,
+ https://github.com/ansible-collections/community.general/pull/8925).
+ - kernel_blacklist - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410,
+ https://github.com/ansible-collections/community.general/pull/8411).
+ - keycloak_client - fix TypeError when sanitizing the ``saml.signing.private.key``
+ attribute in the module's diff or state output. The ``sanitize_cr`` function
+ expected a dict where in some cases a list might occur (https://github.com/ansible-collections/community.general/pull/8403).
+ - keycloak_clientscope - remove IDs from clientscope and its protocol mappers
+ on comparison for changed check (https://github.com/ansible-collections/community.general/pull/8545).
+ - keycloak_clientscope_type - fix detect changes in check mode (https://github.com/ansible-collections/community.general/issues/9092,
+ https://github.com/ansible-collections/community.general/pull/9093).
+ - "keycloak_group - fix crash caused in subgroup creation. The crash was caused\
+ \ by a missing or empty ``subGroups`` property in Keycloak \u226523 (https://github.com/ansible-collections/community.general/issues/8788,\
+ \ https://github.com/ansible-collections/community.general/pull/8979)."
+ - keycloak_realm - add normalizations for ``attributes`` and ``protocol_mappers``
+ (https://github.com/ansible-collections/community.general/pull/8496).
+ - keycloak_realm - fix change detection in check mode by sorting the lists
+ in the realms beforehand (https://github.com/ansible-collections/community.general/pull/8877).
+ - keycloak_realm_key - fix invalid usage of ``parent_id`` (https://github.com/ansible-collections/community.general/issues/7850,
+ https://github.com/ansible-collections/community.general/pull/8823).
+ - keycloak_user_federation - add module argument allowing users to configure
+ the update mode for the parameter ``bindCredential`` (https://github.com/ansible-collections/community.general/pull/8898).
+ - keycloak_user_federation - fix key error when removing mappers during an
+ update and new mappers are specified in the module args (https://github.com/ansible-collections/community.general/pull/8762).
+ - keycloak_user_federation - fix the ``UnboundLocalError`` that occurs when
+ an ID is provided for a user federation mapper (https://github.com/ansible-collections/community.general/pull/8831).
+ - keycloak_user_federation - get cleartext IDP ``clientSecret`` from full
+ realm info to detect changes to it (https://github.com/ansible-collections/community.general/issues/8294,
+ https://github.com/ansible-collections/community.general/pull/8735).
+ - keycloak_user_federation - minimize change detection by setting ``krbPrincipalAttribute``
+ to ``''`` in Keycloak responses if missing (https://github.com/ansible-collections/community.general/pull/8785).
+ - keycloak_user_federation - remove ``lastSync`` parameter from Keycloak responses
+ to minimize diff/changes (https://github.com/ansible-collections/community.general/pull/8812).
+ - keycloak_user_federation - remove existing user federation mappers if they
+ are not present in the federation configuration and will not be updated
+ (https://github.com/ansible-collections/community.general/issues/7169, https://github.com/ansible-collections/community.general/pull/8695).
+ - keycloak_user_federation - sort desired and after mapper list by name (analog
+ to before mapper list) to minimize diff and make change detection more accurate
+ (https://github.com/ansible-collections/community.general/pull/8761).
+ - keycloak_userprofile - fix empty response when fetching userprofile component
+ by removing ``parent=parent_id`` filter (https://github.com/ansible-collections/community.general/pull/8923).
+ - keycloak_userprofile - improve diff by deserializing the fetched ``kc.user.profile.config``
+ and serialize it only when sending back (https://github.com/ansible-collections/community.general/pull/8940).
+ - launched - correctly report changed status in check mode (https://github.com/ansible-collections/community.general/pull/8406).
+ - locale_gen - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410,
+ https://github.com/ansible-collections/community.general/pull/8411).
+ - lxd_container - fix bug introduced in previous commit (https://github.com/ansible-collections/community.general/pull/8895,
+ https://github.com/ansible-collections/community.general/issues/8888).
+ - mksysb - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410,
+ https://github.com/ansible-collections/community.general/pull/8411).
+ - modprobe - fix check mode not being honored for ``persistent`` option (https://github.com/ansible-collections/community.general/issues/9051,
+ https://github.com/ansible-collections/community.general/pull/9052).
+ - nsupdate - fix 'index out of range' error when changing NS records by falling
+ back to authority section of the response (https://github.com/ansible-collections/community.general/issues/8612,
+ https://github.com/ansible-collections/community.general/pull/8614).
+ - one_host - fix if statements for cases when ``ID=0`` (https://github.com/ansible-collections/community.general/issues/1199,
+ https://github.com/ansible-collections/community.general/pull/8907).
+ - one_image - fix module failing due to a class method typo (https://github.com/ansible-collections/community.general/pull/9056).
+ - one_image_info - fix module failing due to a class method typo (https://github.com/ansible-collections/community.general/pull/9056).
+ - one_service - fix service creation after it was deleted with ``unique``
+ parameter (https://github.com/ansible-collections/community.general/issues/3137,
+ https://github.com/ansible-collections/community.general/pull/8887).
+ - one_vnet - fix module failing due to a variable typo (https://github.com/ansible-collections/community.general/pull/9019).
+ - opennebula inventory plugin - fix invalid reference to IP when inventory
+ runs against NICs with no IPv4 address (https://github.com/ansible-collections/community.general/pull/8489).
+ - opentelemetry callback - do not save the JSON response when using the ``ansible.builtin.uri``
+ module (https://github.com/ansible-collections/community.general/pull/8430).
+ - opentelemetry callback - do not save the content response when using the
+ ``ansible.builtin.slurp`` module (https://github.com/ansible-collections/community.general/pull/8430).
+ - pam_limits - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950,
+ https://github.com/ansible-collections/community.general/pull/8925).
+ - paman - do not fail if an empty list of packages has been provided and there
+ is nothing to do (https://github.com/ansible-collections/community.general/pull/8514).
+ - pipx - it was ignoring ``global`` when listing existing applications (https://github.com/ansible-collections/community.general/pull/9044).
+ - pipx module utils - add missing command line formatter for argument ``spec_metadata``
+ (https://github.com/ansible-collections/community.general/pull/9044).
+ - pipx_info - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410,
+ https://github.com/ansible-collections/community.general/pull/8411).
+ - proxmox - fix idempotency on creation of mount volumes using Proxmox' special
+ ``:`` syntax (https://github.com/ansible-collections/community.general/issues/8407,
+ https://github.com/ansible-collections/community.general/pull/8542).
+ - proxmox - fixed an issue where the new volume handling incorrectly converted
+ ``null`` values into ``"None"`` strings (https://github.com/ansible-collections/community.general/pull/8646).
+ - proxmox - fixed an issue where volume strings where overwritten instead
+ of appended to in the new ``build_volume()`` method (https://github.com/ansible-collections/community.general/pull/8646).
+ - proxmox - removed the forced conversion of non-string values to strings
+ to be consistent with the module documentation (https://github.com/ansible-collections/community.general/pull/8646).
+ - proxmox inventory plugin - fixed a possible error on concatenating responses
+ from proxmox. In case an API call unexpectedly returned an empty result,
+ the inventory failed with a fatal error. Added check for empty response
+ (https://github.com/ansible-collections/community.general/issues/8798, https://github.com/ansible-collections/community.general/pull/8794).
+ - python_runner module utils - parameter ``path_prefix`` was being handled
+ as string when it should be a list (https://github.com/ansible-collections/community.general/pull/8944).
+ - redfish_utils module utils - do not fail when language is not exactly "en"
+ (https://github.com/ansible-collections/community.general/pull/8613).
+ - redfish_utils module utils - fix issue with URI parsing to gracefully handling
+ trailing slashes when extracting member identifiers (https://github.com/ansible-collections/community.general/issues/9047,
+ https://github.com/ansible-collections/community.general/pull/9057).
+ - snap - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410,
+ https://github.com/ansible-collections/community.general/pull/8411).
+ - snap_alias - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410,
+ https://github.com/ansible-collections/community.general/pull/8411).
+ - udm_user - the module now tries to use ``legacycrypt`` on Python 3.13+ (https://github.com/ansible-collections/community.general/issues/4690,
+ https://github.com/ansible-collections/community.general/pull/8987).
+ deprecated_features:
+ - CmdRunner module util - setting the value of the ``ignore_none`` parameter
+ within a ``CmdRunner`` context is deprecated and that feature should be
+ removed in community.general 12.0.0 (https://github.com/ansible-collections/community.general/pull/8479).
+ - MH decorator cause_changes module utils - deprecate parameters ``on_success``
+ and ``on_failure`` (https://github.com/ansible-collections/community.general/pull/8791).
+ - git_config - the ``list_all`` option has been deprecated and will be removed
+ in community.general 11.0.0. Use the ``community.general.git_config_info``
+ module instead (https://github.com/ansible-collections/community.general/pull/8453).
+ - git_config - using ``state=present`` without providing ``value`` is deprecated
+ and will be disallowed in community.general 11.0.0. Use the ``community.general.git_config_info``
+ module instead to read a value (https://github.com/ansible-collections/community.general/pull/8453).
+ - hipchat - the hipchat service has been discontinued and the self-hosted
+ variant has been End of Life since 2020. The module is therefore deprecated
+ and will be removed from community.general 11.0.0 if nobody provides compelling
+ reasons to still keep it (https://github.com/ansible-collections/community.general/pull/8919).
+ - 'pipx - support for versions of the command line tool ``pipx`` older than
+ ``1.7.0`` is deprecated and will be removed in community.general 11.0.0
+ (https://github.com/ansible-collections/community.general/pull/8793).
+
+ '
+ - 'pipx_info - support for versions of the command line tool ``pipx`` older
+ than ``1.7.0`` is deprecated and will be removed in community.general 11.0.0
+ (https://github.com/ansible-collections/community.general/pull/8793).
+
+ '
+ known_issues:
+ - jenkins_node - the module is not able to update offline message when node
+ is already offline due to internally using toggleOffline API (https://github.com/ansible-collections/community.general/pull/9084).
+ minor_changes:
+ - CmdRunner module util - argument formats can be specified as plain functions
+ without calling ``cmd_runner_fmt.as_func()`` (https://github.com/ansible-collections/community.general/pull/8479).
+ - CmdRunner module utils - the parameter ``force_lang`` now supports the special
+ value ``auto`` which will automatically try and determine the best parsable
+ locale in the system (https://github.com/ansible-collections/community.general/pull/8517).
+ - MH module utils - add parameter ``when`` to ``cause_changes`` decorator
+ (https://github.com/ansible-collections/community.general/pull/8766).
+ - MH module utils - minor refactor in decorators (https://github.com/ansible-collections/community.general/pull/8766).
+ - alternatives - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - ansible_galaxy_install - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9060).
+ - ansible_galaxy_install - add upgrade feature (https://github.com/ansible-collections/community.general/pull/8431,
+ https://github.com/ansible-collections/community.general/issues/8351).
+ - ansible_galaxy_install - minor refactor in the module (https://github.com/ansible-collections/community.general/pull/8413).
+ - apache2_mod_proxy - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - apache2_mod_proxy - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8833).
+ - cargo - add option ``directory``, which allows source directory to be specified
+ (https://github.com/ansible-collections/community.general/pull/8480).
+ - cgroup_memory_recap, hipchat, jabber, log_plays, loganalytics, logentries,
+ logstash, slack, splunk, sumologic, syslog_json callback plugins - make
+ sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8628).
+ - chef_databag, consul_kv, cyberarkpassword, dsv, etcd, filetree, hiera, onepassword,
+ onepassword_doc, onepassword_raw, passwordstore, redis, shelvefile, tss
+ lookup plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8626).
+ - chroot, funcd, incus, iocage, jail, lxc, lxd, qubes, zone connection plugins
+ - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8627).
+ - cmd_runner module utils - add decorator ``cmd_runner_fmt.stack`` (https://github.com/ansible-collections/community.general/pull/8415).
+ - cmd_runner module utils - refactor argument formatting code to its own Python
+ module (https://github.com/ansible-collections/community.general/pull/8964).
+ - cmd_runner_fmt module utils - simplify implementation of ``cmd_runner_fmt.as_bool_not()``
+ (https://github.com/ansible-collections/community.general/pull/8512).
+ - cobbler, linode, lxd, nmap, online, scaleway, stackpath_compute, virtualbox
+ inventory plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8625).
+ - consul_acl - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - consul_kv - add argument for the datacenter option on Consul API (https://github.com/ansible-collections/community.general/pull/9026).
+ - copr - Added ``includepkgs`` and ``excludepkgs`` parameters to limit the
+ list of packages fetched or excluded from the repository(https://github.com/ansible-collections/community.general/pull/8779).
+ - cpanm - add return value ``cpanm_version`` (https://github.com/ansible-collections/community.general/pull/9061).
+ - credstash lookup plugin - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8822).
+ - csv module utils - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - deco MH module utils - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8822).
+ - dig lookup plugin - add ``port`` option to specify DNS server port (https://github.com/ansible-collections/community.general/pull/8966).
+ - django module utils - always retrieve version (https://github.com/ansible-collections/community.general/pull/9063).
+ - django_check - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9063).
+ - django_command - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9063).
+ - django_createcachetable - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9063).
+ - doas, dzdo, ksu, machinectl, pbrun, pfexec, pmrun, sesu, sudosu become plugins
+ - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8623).
+ - etcd3 - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - flatpak - improve the parsing of Flatpak application IDs based on official
+ guidelines (https://github.com/ansible-collections/community.general/pull/8909).
+ - gconftool2 - make use of ``ModuleHelper`` features to simplify code (https://github.com/ansible-collections/community.general/pull/8711).
+ - gcontool2 - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9064).
+ - gcontool2 module utils - add argument formatter ``version`` (https://github.com/ansible-collections/community.general/pull/9064).
+ - gcontool2_info - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9064).
+ - gio_mime - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9067).
+ - gio_mime - adjust code ahead of the old ``VardDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8855).
+ - gio_mime - mute the old ``VarDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8776).
+ - gio_mime module utils - add argument formatter ``version`` (https://github.com/ansible-collections/community.general/pull/9067).
+ - github_app_access_token lookup plugin - adds new ``private_key`` parameter
+ (https://github.com/ansible-collections/community.general/pull/8989).
+ - gitlab_deploy_key - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - gitlab_group - add many new parameters (https://github.com/ansible-collections/community.general/pull/8908).
+ - gitlab_group - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - gitlab_group - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+ - gitlab_issue - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - gitlab_merge_request - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - gitlab_project - add option ``container_expiration_policy`` to schedule
+ container registry cleanup (https://github.com/ansible-collections/community.general/pull/8674).
+ - gitlab_project - add option ``issues_access_level`` to enable/disable project
+ issues (https://github.com/ansible-collections/community.general/pull/8760).
+ - gitlab_project - add option ``model_registry_access_level`` to disable model
+ registry (https://github.com/ansible-collections/community.general/pull/8688).
+ - gitlab_project - add option ``pages_access_level`` to disable project pages
+ (https://github.com/ansible-collections/community.general/pull/8688).
+ - gitlab_project - add option ``repository_access_level`` to disable project
+ repository (https://github.com/ansible-collections/community.general/pull/8674).
+ - gitlab_project - add option ``service_desk_enabled`` to disable service
+ desk (https://github.com/ansible-collections/community.general/pull/8688).
+ - gitlab_project - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - gitlab_project - sorted parameters in order to avoid future merge conflicts
+ (https://github.com/ansible-collections/community.general/pull/8759).
+ - gitlab_runner - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - hashids filter plugin - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - homebrew - speed up brew install and upgrade (https://github.com/ansible-collections/community.general/pull/9022).
+ - hwc_ecs_instance - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8822).
+ - hwc_evs_disk - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - hwc_vpc_eip - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - hwc_vpc_peering_connect - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8822).
+ - hwc_vpc_port - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - hwc_vpc_subnet - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - icinga2_host - replace loop with dict comprehension (https://github.com/ansible-collections/community.general/pull/8876).
+ - imc_rest - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - ipa_dnsrecord - adds ``SSHFP`` record type for managing SSH fingerprints
+ in FreeIPA DNS (https://github.com/ansible-collections/community.general/pull/8404).
+ - ipa_otptoken - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - jenkins_node - add ``offline_message`` parameter for updating a Jenkins
+ node offline cause reason when the state is "disabled" (offline) (https://github.com/ansible-collections/community.general/pull/9084)."
+ - jira - adjust code ahead of the old ``VardDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8856).
+ - jira - mute the old ``VarDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8776).
+ - jira - replace deprecated params when using decorator ``cause_changes``
+ (https://github.com/ansible-collections/community.general/pull/8791).
+ - keep_keys filter plugin - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - keycloak module utils - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8822).
+ - keycloak_client - add ``client-x509`` choice to ``client_authenticator_type``
+ (https://github.com/ansible-collections/community.general/pull/8973).
+ - keycloak_client - assign auth flow by name (https://github.com/ansible-collections/community.general/pull/8428).
+ - keycloak_client - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - keycloak_clientscope - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - keycloak_identity_provider - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - keycloak_realm - add boolean toggle to configure organization support for
+ a given keycloak realm (https://github.com/ansible-collections/community.general/issues/9027,
+ https://github.com/ansible-collections/community.general/pull/8927/).
+ - keycloak_user_federation - add module argument allowing users to optout
+ of the removal of unspecified mappers, for example to keep the keycloak
+ default mappers (https://github.com/ansible-collections/community.general/pull/8764).
+ - keycloak_user_federation - add the user federation config parameter ``referral``
+ to the module arguments (https://github.com/ansible-collections/community.general/pull/8954).
+ - keycloak_user_federation - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - keycloak_user_federation - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8822).
+ - keycloak_user_federation - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8833).
+ - linode - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+ - locale_gen - add support for multiple locales (https://github.com/ansible-collections/community.general/issues/8677,
+ https://github.com/ansible-collections/community.general/pull/8682).
+ - lxc_container - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - lxd_container - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+ - manageiq_provider - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - mattermost - adds support for message priority (https://github.com/ansible-collections/community.general/issues/9068,
+ https://github.com/ansible-collections/community.general/pull/9087).
+ - memcached, pickle, redis, yaml cache plugins - make sure that all options
+ are typed (https://github.com/ansible-collections/community.general/pull/8624).
+ - memset_dns_reload - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - memset_memstore_info - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - memset_server_info - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - memset_zone - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - memset_zone_domain - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - memset_zone_record - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - nmcli - add ``conn_enable`` param to reload connection (https://github.com/ansible-collections/community.general/issues/3752,
+ https://github.com/ansible-collections/community.general/issues/8704, https://github.com/ansible-collections/community.general/pull/8897).
+ - nmcli - add ``state=up`` and ``state=down`` to enable/disable connections
+ (https://github.com/ansible-collections/community.general/issues/3752, https://github.com/ansible-collections/community.general/issues/8704,
+ https://github.com/ansible-collections/community.general/issues/7152, https://github.com/ansible-collections/community.general/pull/8897).
+ - nmcli - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - npm - add ``force`` parameter to allow ``--force`` (https://github.com/ansible-collections/community.general/pull/8885).
+ - ocapi_utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - one_image - add ``create``, ``template`` and ``datastore_id`` arguments
+ for image creation (https://github.com/ansible-collections/community.general/pull/9075).
+ - one_image - add ``wait_timeout`` argument for adjustable timeouts (https://github.com/ansible-collections/community.general/pull/9075).
+ - one_image - add option ``persistent`` to manage image persistence (https://github.com/ansible-collections/community.general/issues/3578,
+ https://github.com/ansible-collections/community.general/pull/8889).
+ - one_image - extend xsd scheme to make it return a lot more info about image
+ (https://github.com/ansible-collections/community.general/pull/8889).
+ - one_image - refactor code to make it more similar to ``one_template`` and
+ ``one_vnet`` (https://github.com/ansible-collections/community.general/pull/8889).
+ - one_image_info - extend xsd scheme to make it return a lot more info about
+ image (https://github.com/ansible-collections/community.general/pull/8889).
+ - one_image_info - refactor code to make it more similar to ``one_template``
+ and ``one_vnet`` (https://github.com/ansible-collections/community.general/pull/8889).
+ - one_service - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+ - one_vm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+ - onepassword lookup plugin - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8833).
+ - open_iscsi - allow login to a portal with multiple targets without specifying
+ any of them (https://github.com/ansible-collections/community.general/pull/8719).
+ - openbsd_pkg - adds diff support to show changes in installed package list.
+ This does not yet work for check mode (https://github.com/ansible-collections/community.general/pull/8402).
+ - opennebula.py - add VM ``id`` and VM ``host`` to inventory host data (https://github.com/ansible-collections/community.general/pull/8532).
+ - opentelemetry callback plugin - fix default value for ``store_spans_in_file``
+ causing traces to be produced to a file named ``None`` (https://github.com/ansible-collections/community.general/issues/8566,
+ https://github.com/ansible-collections/community.general/pull/8741).
+ - opkg - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9086).
+ - passwordstore lookup plugin - add subkey creation/update support (https://github.com/ansible-collections/community.general/pull/8952).
+ - passwordstore lookup plugin - add the current user to the lockfile file
+ name to address issues on multi-user systems (https://github.com/ansible-collections/community.general/pull/8689).
+ - pids - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - pipx - add parameter ``suffix`` to module (https://github.com/ansible-collections/community.general/pull/8675,
+ https://github.com/ansible-collections/community.general/issues/8656).
+ - pipx - added new states ``install_all``, ``uninject``, ``upgrade_shared``,
+ ``pin``, and ``unpin`` (https://github.com/ansible-collections/community.general/pull/8809).
+ - pipx - added parameter ``global`` to module (https://github.com/ansible-collections/community.general/pull/8793).
+ - pipx - refactor out parsing of ``pipx list`` output to module utils (https://github.com/ansible-collections/community.general/pull/9044).
+ - pipx - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - pipx_info - add new return value ``pinned`` (https://github.com/ansible-collections/community.general/pull/9044).
+ - pipx_info - added parameter ``global`` to module (https://github.com/ansible-collections/community.general/pull/8793).
+ - pipx_info - refactor out parsing of ``pipx list`` output to module utils
+ (https://github.com/ansible-collections/community.general/pull/9044).
+ - pipx_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - pkg5_publisher - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - pkgng - add option ``use_globs`` (default ``true``) to optionally disable
+ glob patterns (https://github.com/ansible-collections/community.general/issues/8632,
+ https://github.com/ansible-collections/community.general/pull/8633).
+ - proxmox - add ``disk_volume`` and ``mount_volumes`` keys for better readability
+ (https://github.com/ansible-collections/community.general/pull/8542).
+ - proxmox - allow specification of the API port when using proxmox_* (https://github.com/ansible-collections/community.general/issues/8440,
+ https://github.com/ansible-collections/community.general/pull/8441).
+ - proxmox - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+ - proxmox - translate the old ``disk`` and ``mounts`` keys to the new handling
+ internally (https://github.com/ansible-collections/community.general/pull/8542).
+ - proxmox inventory plugin - add new fact for LXC interface details (https://github.com/ansible-collections/community.general/pull/8713).
+ - proxmox inventory plugin - clean up authentication code (https://github.com/ansible-collections/community.general/pull/8917).
+ - proxmox inventory plugin - fix urllib3 ``InsecureRequestWarnings`` not being
+ suppressed when a token is used (https://github.com/ansible-collections/community.general/pull/9099).
+ - proxmox_disk - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+ - proxmox_kvm - adds the ``ciupgrade`` parameter to specify whether cloud-init
+ should upgrade system packages at first boot (https://github.com/ansible-collections/community.general/pull/9066).
+ - proxmox_kvm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
+ - proxmox_kvm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - proxmox_template - small refactor in logic for determining whether a template
+ exists or not (https://github.com/ansible-collections/community.general/pull/8516).
+ - proxmox_vm_info - add ``network`` option to retrieve current network information
+ (https://github.com/ansible-collections/community.general/pull/8471).
+ - redfish_* modules - adds ``ciphers`` option for custom cipher selection
+ (https://github.com/ansible-collections/community.general/pull/8533).
+ - redfish_command - add ``UpdateUserAccountTypes`` command (https://github.com/ansible-collections/community.general/issues/9058,
+ https://github.com/ansible-collections/community.general/pull/9059).
+ - redfish_command - add ``wait`` and ``wait_timeout`` options to allow a user
+ to block a command until a service is accessible after performing the requested
+ command (https://github.com/ansible-collections/community.general/issues/8051,
+ https://github.com/ansible-collections/community.general/pull/8434).
+ - redfish_command - add handling of the ``PasswordChangeRequired`` message
+ from services in the ``UpdateUserPassword`` command to directly modify the
+ user's password if the requested user is the one invoking the operation
+ (https://github.com/ansible-collections/community.general/issues/8652, https://github.com/ansible-collections/community.general/pull/8653).
+ - redfish_confg - remove ``CapacityBytes`` from required paramaters of the
+ ``CreateVolume`` command (https://github.com/ansible-collections/community.general/pull/8956).
+ - redfish_config - add parameter ``storage_none_volume_deletion`` to ``CreateVolume``
+ command in order to control the automatic deletion of non-RAID volumes (https://github.com/ansible-collections/community.general/pull/8990).
+ - redfish_info - add command ``CheckAvailability`` to check if a service is
+ accessible (https://github.com/ansible-collections/community.general/issues/8051,
+ https://github.com/ansible-collections/community.general/pull/8434).
+ - redfish_info - adds ``RedfishURI`` and ``StorageId`` to Disk inventory (https://github.com/ansible-collections/community.general/pull/8937).
+ - redfish_utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - redfish_utils module utils - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8822).
+ - redfish_utils module utils - schedule a BIOS configuration job at next reboot
+ when the BIOS config is changed (https://github.com/ansible-collections/community.general/pull/9012).
+ - redis cache plugin - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8833).
+ - redis, redis_info - add ``client_cert`` and ``client_key`` options to specify
+ path to certificate for Redis authentication (https://github.com/ansible-collections/community.general/pull/8654).
+ - redis_info - adds support for getting cluster info (https://github.com/ansible-collections/community.general/pull/8464).
+ - remove_keys filter plugin - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - replace_keys filter plugin - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - scaleway - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - scaleway module utils - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8822).
+ - scaleway_compute - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8833).
+ - scaleway_container - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_container_info - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_container_namespace - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_container_namespace_info - replace Python 2.6 construct with dict
+ comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_container_registry - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_container_registry_info - replace Python 2.6 construct with dict
+ comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_function - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_function_info - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_function_namespace - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_function_namespace_info - replace Python 2.6 construct with dict
+ comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
+ - scaleway_ip - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - scaleway_lb - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - scaleway_security_group - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8822).
+ - scaleway_security_group - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8833).
+ - scaleway_user_data - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - scaleway_user_data - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8833).
+ - sensu_silence - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - snmp_facts - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - sorcery - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
+ - sudosu become plugin - added an option (``alt_method``) to enhance compatibility
+ with more versions of ``su`` (https://github.com/ansible-collections/community.general/pull/8214).
+ - udm_dns_record - replace loop with ``dict.update()`` (https://github.com/ansible-collections/community.general/pull/8876).
+ - ufw - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - unsafe plugin utils - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - vardict module utils - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - vars MH module utils - replace Python 2.6 construct with dict comprehensions
+ (https://github.com/ansible-collections/community.general/pull/8814).
+ - virtualbox inventory plugin - expose a new parameter ``enable_advanced_group_parsing``
+ to change how the VirtualBox dynamic inventory parses VM groups (https://github.com/ansible-collections/community.general/issues/8508,
+ https://github.com/ansible-collections/community.general/pull/8510).
+ - vmadm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
+ - wdc_redfish_command - minor change to handle upgrade file for Redfish WD
+ platforms (https://github.com/ansible-collections/community.general/pull/8444).
+ release_summary: This is release 10.0.0 of ``community.general``, released on
+ 2024-11-04.
+ removed_features:
+ - The consul_acl module has been removed. Use community.general.consul_token
+ and/or community.general.consul_policy instead (https://github.com/ansible-collections/community.general/pull/8921).
+ - The hipchat callback plugin has been removed. The hipchat service has been
+ discontinued and the self-hosted variant has been End of Life since 2020
+ (https://github.com/ansible-collections/community.general/pull/8921).
+ - The redhat module utils has been removed (https://github.com/ansible-collections/community.general/pull/8921).
+ - The rhn_channel module has been removed (https://github.com/ansible-collections/community.general/pull/8921).
+ - The rhn_register module has been removed (https://github.com/ansible-collections/community.general/pull/8921).
+ - consul - removed the ``ack_params_state_absent`` option. It had no effect
+ anymore (https://github.com/ansible-collections/community.general/pull/8918).
+ - ejabberd_user - removed the ``logging`` option (https://github.com/ansible-collections/community.general/pull/8918).
+ - gitlab modules - remove basic auth feature (https://github.com/ansible-collections/community.general/pull/8405).
+ - proxmox_kvm - removed the ``proxmox_default_behavior`` option. Explicitly
+ specify the old default values if you were using ``proxmox_default_behavior=compatibility``,
+ otherwise simply remove it (https://github.com/ansible-collections/community.general/pull/8918).
+ - redhat_subscriptions - removed the ``pool`` option. Use ``pool_ids`` instead
+ (https://github.com/ansible-collections/community.general/pull/8918).
+ fragments:
+ - 10.0.0.yml
+ - 8051-Redfish-Wait-For-Service.yml
+ - 8214-sudosu-not-working-on-some-BSD-machines.yml
+ - 8402-add-diif-mode-openbsd-pkg.yml
+ - 8403-fix-typeerror-in-keycloak-client.yaml
+ - 8404-ipa_dnsrecord_sshfp.yml
+ - 8405-gitlab-remove-basic-auth.yml
+ - 8406-fix-homebrew-cask-warning.yaml
+ - 8411-locale-gen-vardict.yml
+ - 8413-galaxy-refactor.yml
+ - 8415-cmd-runner-stack.yml
+ - 8428-assign-auth-flow-by-name-keycloak-client.yaml
+ - 8430-fix-opentelemetry-when-using-logs-with-uri-or-slurp-tasks.yaml
+ - 8431-galaxy-upgrade.yml
+ - 8440-allow-api-port-specification.yaml
+ - 8444-fix-redfish-gen2-upgrade.yaml
+ - 8452-git_config-absent.yml
+ - 8453-git_config-deprecate-read.yml
+ - 8464-redis-add-cluster-info.yml
+ - 8471-proxmox-vm-info-network.yml
+ - 8476-launchd-check-mode-changed.yaml
+ - 8479-cmdrunner-improvements.yml
+ - 8480-directory-feature-cargo.yml
+ - 8489-fix-opennebula-inventory-crash-when-nic-has-no-ip.yml
+ - 8496-keycloak_clientscope-add-normalizations.yaml
+ - 8508-virtualbox-inventory.yml
+ - 8512-as-bool-not.yml
+ - 8514-pacman-empty.yml
+ - 8516-proxmox-template-refactor.yml
+ - 8517-cmd-runner-lang-auto.yml
+ - 8532-expand-opennuebula-inventory-data.yml
+ - 8533-add-ciphers-option.yml
+ - 8542-fix-proxmox-volume-handling.yml
+ - 8545-keycloak-clientscope-remove-id-on-compare.yml
+ - 8557-fix-bug-with-bitwarden.yml
+ - 8613-redfish_utils-language.yaml
+ - 8614-nsupdate-index-out-of-range.yml
+ - 8623-become-types.yml
+ - 8624-cache-types.yml
+ - 8625-inventory-types.yml
+ - 8626-lookup-types.yml
+ - 8627-connection-types.yml
+ - 8628-callback-types.yml
+ - 8632-pkgng-add-option-use_globs.yml
+ - 8646-fix-bug-in-proxmox-volumes.yml
+ - 8648-fix-gitlab-runner-paused.yaml
+ - 8652-Redfish-Password-Change-Required.yml
+ - 8654-add-redis-tls-params.yml
+ - 8674-add-gitlab-project-cleanup-policy.yml
+ - 8675-pipx-install-suffix.yml
+ - 8679-fix-cloudflare-srv.yml
+ - 8682-locale-gen-multiple.yaml
+ - 8688-gitlab_project-add-new-params.yml
+ - 8689-passwordstore-lock-naming.yml
+ - 8695-keycloak_user_federation-mapper-removal.yml
+ - 8708-homebrew_cask-fix-upgrade-all.yml
+ - 8711-gconftool2-refactor.yml
+ - 8713-proxmox_lxc_interfaces.yml
+ - 8719-openiscsi-add-multiple-targets.yaml
+ - 8735-keycloak_identity_provider-get-cleartext-secret-from-realm-info.yml
+ - 8738-limit-packages-for-copr.yml
+ - 8741-fix-opentelemetry-callback.yml
+ - 8759-gitlab_project-sort-params.yml
+ - 8760-gitlab_project-add-issues-access-level.yml
+ - 8761-keycloak_user_federation-sort-desired-and-after-mappers-by-name.yml
+ - 8762-keycloac_user_federation-fix-key-error-when-updating.yml
+ - 8764-keycloak_user_federation-make-mapper-removal-optout.yml
+ - 8766-mh-deco-improve.yml
+ - 8776-mute-vardict-deprecation.yml
+ - 8785-keycloak_user_federation-set-krbPrincipalAttribute-to-empty-string-if-missing.yaml
+ - 8790-gitlab_project-fix-cleanup-policy-on-project-create.yml
+ - 8791-mh-cause-changes-param-depr.yml
+ - 8793-pipx-global.yml
+ - 8794-Fixing-possible-concatination-error.yaml
+ - 8796-gitlab-access-token-check-mode.yml
+ - 8809-pipx-new-params.yml
+ - 8812-keycloak-user-federation-remove-lastSync-param-from-kc-responses.yml
+ - 8814-dict-comprehension.yml
+ - 8822-dict-comprehension.yml
+ - 8823-keycloak-realm-key.yml
+ - 8831-fix-error-when-mapper-id-is-provided.yml
+ - 8833-dict-comprehension.yml
+ - 8855-gio_mime_vardict.yml
+ - 8856-jira_vardict.yml
+ - 8858-dict-comprehension.yml
+ - 8876-dict-items-loop.yml
+ - 8877-keycloak_realm-sort-lists-before-change-detection.yaml
+ - 8885-add-force-flag-for-nmp.yml
+ - 8887-fix-one_service-unique.yml
+ - 8889-refactor-one-image-modules.yml
+ - 8895-fix-comprehension.yaml
+ - 8897-nmcli-add-reload-and-up-down.yml
+ - 8898-add-arg-to-exclude-bind-credential-from-change-check.yaml
+ - 8900-ipa-hostgroup-fix-states.yml
+ - 8907-fix-one-host-id.yml
+ - 8908-add-gitlab-group-params.yml
+ - 8909-flatpak-improve-name-parsing.yaml
+ - 8917-proxmox-clean-auth.yml
+ - 8920-ipa-host-fix-state.yml
+ - 8923-keycloak_userprofile-fix-empty-response-when-fetching-userprofile.yml
+ - 8925-atomic.yml
+ - 8928-cmd-runner-10.0.0.yml
+ - 8929-cmd_runner-bugfix.yml
+ - 8937-add-StorageId-RedfishURI-to-disk-facts.yml
+ - 8940-keycloak_userprofile-improve-diff.yml
+ - 8944-django-command-fix.yml
+ - 8952-password-store-lookup-create-subkey-support.yml
+ - 8954-keycloak-user-federation-add-referral-parameter.yml
+ - 8956-remove-capacitybytes-from-the-required-parameters_list.yml
+ - 8964-cmd-runner-argformat-refactor.yml
+ - 8966-dig-add-port-option.yml
+ - 8970-fix-dig-multi-nameservers.yml
+ - 8973-keycloak_client-add-x509-auth.yml
+ - 8979-keycloak_group-fix-subgroups.yml
+ - 8987-legacycrypt.yml
+ - 8989-github-app-token-from-fact.yml
+ - 8990.yml
+ - 9010-edit-gitlab-label-color.yaml
+ - 9012-dell-pwrbutton-requires-a-job-initiated-at-reboot.yml
+ - 9019-onevnet-bugfix.yml
+ - 9022-improve-homebrew-perf.yml
+ - 9026-consul_kv-datacenter.yml
+ - 9027-support-organizations-in-keycloak-realm.yml
+ - 9028-bitwarden-secrets-manager-syntax-fix.yml
+ - 9044-pipx-fixes.yml
+ - 9047-redfish-uri-parsing.yml
+ - 9052-modprobe-bugfix.yml
+ - 9056-fix-one_image-modules.yml
+ - 9059-redfish_command-updateuseraccounttypes.yml
+ - 9060-ansible-galaxy-install-version.yml
+ - 9061-cpanm-version.yml
+ - 9063-django-version.yml
+ - 9064-gconftool2-version.yml
+ - 9066-proxmox-kvm-ciupgrade.yml
+ - 9067-gio-mime-version.yml
+ - 9075-add-creation-oneimage.yml
+ - 9084-collection_version-importlib.yml
+ - 9084-jenkins_node-add-offline-message.yml
+ - 9086-gio-mime-version.yml
+ - 9087-mattermost-priority.yaml
+ - 9092-keycloak-clientscope-type-fix-check-mode.yml
+ - 9099-proxmox-fix-insecure.yml
+ - deprecate-hipchat.yml
+ - deprecations.yml
+ - removals.yml
+ modules:
+ - description: Bootc Switch and Upgrade.
+ name: bootc_manage
+ namespace: ''
+ - description: Add, modify, and delete checks within a consul cluster.
+ name: consul_agent_check
+ namespace: ''
+ - description: Add, modify and delete services within a consul cluster.
+ name: consul_agent_service
+ namespace: ''
+ - description: Wrapper for C(django-admin check).
+ name: django_check
+ namespace: ''
+ - description: Wrapper for C(django-admin createcachetable).
+ name: django_createcachetable
+ namespace: ''
+ - description: Services manager for Homebrew.
+ name: homebrew_services
+ namespace: ''
+ - description: Manage keytab file in FreeIPA.
+ name: ipa_getkeytab
+ namespace: ''
+ - description: Manage Jenkins nodes.
+ name: jenkins_node
+ namespace: ''
+ - description: Allows administration of Keycloak components via Keycloak API.
+ name: keycloak_component
+ namespace: ''
+ - description: Allows obtaining Keycloak realm keys metadata via Keycloak API.
+ name: keycloak_realm_keys_metadata_info
+ namespace: ''
+ - description: Allows managing Keycloak User Profiles.
+ name: keycloak_userprofile
+ namespace: ''
+ - description: Kerberos utils for managing tickets.
+ name: krb_ticket
+ namespace: ''
+ - description: Manages OpenNebula virtual networks.
+ name: one_vnet
+ namespace: ''
+ - description: List Zypper repositories.
+ name: zypper_repository_info
+ namespace: ''
+ plugins:
+ filter:
+ - description: Keep specific keys from dictionaries in a list.
+ name: keep_keys
+ namespace: null
+ - description: Remove specific keys from dictionaries in a list.
+ name: remove_keys
+ namespace: null
+ - description: Replace specific keys in a list of dictionaries.
+ name: replace_keys
+ namespace: null
+ - description: Return input type.
+ name: reveal_ansible_type
+ namespace: null
+ test:
+ - description: Validate input type.
+ name: ansible_type
+ namespace: null
+ release_date: '2024-11-04'
+ 10.0.1:
+ changes:
+ bugfixes:
+ - keycloak_client - fix diff by removing code that turns the attributes dict
+ which contains additional settings into a list (https://github.com/ansible-collections/community.general/pull/9077).
+ - keycloak_clientscope - fix diff and ``end_state`` by removing the code that
+ turns the attributes dict, which contains additional config items, into
+ a list (https://github.com/ansible-collections/community.general/pull/9082).
+ - redfish_utils module utils - remove undocumented default applytime (https://github.com/ansible-collections/community.general/pull/9114).
+ release_summary: Bugfix release for inclusion in Ansible 11.0.0rc1.
+ fragments:
+ - 10.0.1.yml
+ - 9077-keycloak_client-fix-attributes-dict-turned-into-list.yml
+ - 9082-keycloak_clientscope-fix-attributes-dict-turned-into-list.yml
+ - 9114-redfish-utils-update-remove-default-applytime.yml
+ release_date: '2024-11-11'
+ 10.1.0:
+ changes:
+ bugfixes:
+ - dnf_config_manager - fix hanging when prompting to import GPG keys (https://github.com/ansible-collections/community.general/pull/9124,
+ https://github.com/ansible-collections/community.general/issues/8830).
+ - dnf_config_manager - forces locale to ``C`` before module starts. If the
+ locale was set to non-English, the output of the ``dnf config-manager``
+ could not be parsed (https://github.com/ansible-collections/community.general/pull/9157,
+ https://github.com/ansible-collections/community.general/issues/9046).
+ - flatpak - force the locale language to ``C`` when running the flatpak command
+ (https://github.com/ansible-collections/community.general/pull/9187, https://github.com/ansible-collections/community.general/issues/8883).
+ - gio_mime - fix command line when determining version of ``gio`` (https://github.com/ansible-collections/community.general/pull/9171,
+ https://github.com/ansible-collections/community.general/issues/9158).
+ - github_key - in check mode, a faulty call to ```datetime.strftime(...)```
+ was being made which generated an exception (https://github.com/ansible-collections/community.general/issues/9185).
+ - homebrew_cask - allow ``+`` symbol in Homebrew cask name validation regex
+ (https://github.com/ansible-collections/community.general/pull/9128).
+ - keycloak_clientscope_type - sort the default and optional clientscope lists
+ to improve the diff (https://github.com/ansible-collections/community.general/pull/9202).
+ - slack - fail if Slack API response is not OK with error message (https://github.com/ansible-collections/community.general/pull/9198).
+ deprecated_features:
+ - opkg - deprecate value ``""`` for parameter ``force`` (https://github.com/ansible-collections/community.general/pull/9172).
+ - redfish_utils module utils - deprecate method ``RedfishUtils._init_session()``
+ (https://github.com/ansible-collections/community.general/pull/9190).
+ minor_changes:
+ - alternatives - add ``family`` parameter that allows to utilize the ``--family``
+ option available in RedHat version of update-alternatives (https://github.com/ansible-collections/community.general/issues/5060,
+ https://github.com/ansible-collections/community.general/pull/9096).
+ - cloudflare_dns - add support for ``comment`` and ``tags`` (https://github.com/ansible-collections/community.general/pull/9132).
+ - deps module utils - add ``deps.clear()`` to clear out previously declared
+ dependencies (https://github.com/ansible-collections/community.general/pull/9179).
+ - homebrew - greatly speed up module when multiple packages are passed in
+ the ``name`` option (https://github.com/ansible-collections/community.general/pull/9181).
+ - homebrew - remove duplicated package name validation (https://github.com/ansible-collections/community.general/pull/9076).
+ - iso_extract - adds ``password`` parameter that is passed to 7z (https://github.com/ansible-collections/community.general/pull/9159).
+ - launchd - add ``plist`` option for services such as sshd, where the plist
+ filename doesn't match the service name (https://github.com/ansible-collections/community.general/pull/9102).
+ - nmcli - add ``sriov`` parameter that enables support for SR-IOV settings
+ (https://github.com/ansible-collections/community.general/pull/9168).
+ - pipx - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9180).
+ - pipx_info - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9180).
+ - proxmox_template - add server side artifact fetching support (https://github.com/ansible-collections/community.general/pull/9113).
+ - redfish_command - add ``update_custom_oem_header``, ``update_custom_oem_params``,
+ and ``update_custom_oem_mime_type`` options (https://github.com/ansible-collections/community.general/pull/9123).
+ - redfish_utils module utils - remove redundant code (https://github.com/ansible-collections/community.general/pull/9190).
+ - rpm_ostree_pkg - added the options ``apply_live`` (https://github.com/ansible-collections/community.general/pull/9167).
+ - rpm_ostree_pkg - added the return value ``needs_reboot`` (https://github.com/ansible-collections/community.general/pull/9167).
+ - scaleway_lb - minor simplification in the code (https://github.com/ansible-collections/community.general/pull/9189).
+ - ssh_config - add ``dynamicforward`` option (https://github.com/ansible-collections/community.general/pull/9192).
+ release_summary: Regular bugfix and feature release.
+ fragments:
+ - 10.1.0.yml
+ - 5932-launchd-plist.yml
+ - 7402-proxmox-template-support-server-side-artifact-fetching.yaml
+ - 9076-remove-duplicated-homebrew-package-name-validation.yml
+ - 9096-alternatives-add-family-parameter.yml
+ - 9123-redfish-command-custom-oem-params.yml
+ - 9124-dnf_config_manager.yml
+ - 9128-homebrew_cask-name-regex-fix.yml
+ - 9132-cloudflare_dns-comment-and-tags.yml
+ - 9157-fix-dnf_config_manager-locale.yml
+ - 9159-iso-extract_add_password.yml
+ - 9167-rpm_ostree_pkg-apply_live.yml
+ - 9168-nmcli-add-sriov-parameter.yml
+ - 9171-gio-mime-fix-version.yml
+ - 9172-opkg-deprecate-force-none.yml
+ - 9179-deps-tests.yml
+ - 9180-pipx-version.yml
+ - 9181-improve-homebrew-module-performance.yml
+ - 9186-fix-broken-check-mode-in-github-key.yml
+ - 9187-flatpak-lang.yml
+ - 9189-scalway-lb-simplify-return.yml
+ - 9190-redfish-utils-unused-code.yml
+ - 9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml
+ - 9202-keycloak_clientscope_type-sort-lists.yml
+ - ssh_config_add_dynamicforward_option.yml
+ modules:
+ - description: Decompresses compressed files.
+ name: decompress
+ namespace: ''
+ - description: Start a VM backup in Proxmox VE cluster.
+ name: proxmox_backup
+ namespace: ''
+ plugins:
+ filter:
+ - description: Produce a list of accumulated sums of the input list contents.
+ name: accumulate
+ namespace: null
+ release_date: '2024-12-02'
+ 10.2.0:
+ changes:
+ bugfixes:
+ - dig lookup plugin - correctly handle ``NoNameserver`` exception (https://github.com/ansible-collections/community.general/pull/9363,
+ https://github.com/ansible-collections/community.general/issues/9362).
+ - homebrew - fix incorrect handling of aliased homebrew modules when the alias
+ is requested (https://github.com/ansible-collections/community.general/pull/9255,
+ https://github.com/ansible-collections/community.general/issues/9240).
+ - htpasswd - report changes when file permissions are adjusted (https://github.com/ansible-collections/community.general/issues/9485,
+ https://github.com/ansible-collections/community.general/pull/9490).
+ - proxmox_backup - fix incorrect key lookup in vmid permission check (https://github.com/ansible-collections/community.general/pull/9223).
+ - proxmox_disk - fix async method and make ``resize_disk`` method handle errors
+ correctly (https://github.com/ansible-collections/community.general/pull/9256).
+ - proxmox_template - fix the wrong path called on ``proxmox_template.task_status``
+ (https://github.com/ansible-collections/community.general/issues/9276, https://github.com/ansible-collections/community.general/pull/9277).
+ - qubes connection plugin - fix the printing of debug information (https://github.com/ansible-collections/community.general/pull/9334).
+ - redfish_utils module utils - Fix ``VerifyBiosAttributes`` command on multi
+ system resource nodes (https://github.com/ansible-collections/community.general/pull/9234).
+ deprecated_features:
+ - atomic_container - module is deprecated and will be removed in community.general
+ 13.0.0 (https://github.com/ansible-collections/community.general/pull/9487).
+ - atomic_host - module is deprecated and will be removed in community.general
+ 13.0.0 (https://github.com/ansible-collections/community.general/pull/9487).
+ - atomic_image - module is deprecated and will be removed in community.general
+ 13.0.0 (https://github.com/ansible-collections/community.general/pull/9487).
+ - facter - module is deprecated and will be removed in community.general 12.0.0,
+ use ``community.general.facter_facts`` instead (https://github.com/ansible-collections/community.general/pull/9451).
+ - 'locale_gen - ``ubuntu_mode=True``, or ``mechanism=ubuntu_legacy`` is deprecated
+ and will be removed in community.general 13.0.0 (https://github.com/ansible-collections/community.general/pull/9238).
+
+ '
+ - pure module utils - the module utils is deprecated and will be removed from
+ community.general 12.0.0. The modules using this were removed in community.general
+ 3.0.0 (https://github.com/ansible-collections/community.general/pull/9432).
+ - purestorage doc fragments - the doc fragment is deprecated and will be removed
+ from community.general 12.0.0. The modules using this were removed in community.general
+ 3.0.0 (https://github.com/ansible-collections/community.general/pull/9432).
+ - sensu_check - module is deprecated and will be removed in community.general
+ 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+ - sensu_client - module is deprecated and will be removed in community.general
+ 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+ - sensu_handler - module is deprecated and will be removed in community.general
+ 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+ - sensu_silence - module is deprecated and will be removed in community.general
+ 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+ - sensu_subscription - module is deprecated and will be removed in community.general
+ 13.0.0, use collection ``sensu.sensu_go`` instead (https://github.com/ansible-collections/community.general/pull/9483).
+ - slack - the default value ``auto`` of the ``prepend_hash`` option is deprecated
+ and will change to ``never`` in community.general 12.0.0 (https://github.com/ansible-collections/community.general/pull/9443).
+ - yaml callback plugin - deprecate plugin in favor of ``result_format=yaml``
+ in plugin ``ansible.bulitin.default`` (https://github.com/ansible-collections/community.general/pull/9456).
+ minor_changes:
+ - bitwarden lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - cgroup_memory_recap callback plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+ - chef_databag lookup plugin - use f-strings instead of interpolations or
+ ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+ - chroot connection plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - chroot connection plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9322).
+ - cobbler inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - cobbler inventory plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9323).
+ - collection_version lookup plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+ - consul_kv lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - context_demo callback plugin - use f-strings instead of interpolations or
+ ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+ - counter_enabled callback plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+ - credstash lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - cyberarkpassword lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - cyberarkpassword lookup plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+ - dense callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - dependent lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - dig lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - dig lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - diy callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - dnstxt lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - dnstxt lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - doas become plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9319).
+ - dsv lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - dzdo become plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9319).
+ - elastic callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - etcd lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - etcd3 lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - etcd3 lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - filetree lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - from_csv filter plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - from_ini filter plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - funcd connection plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9322).
+ - github_app_access_token lookup plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+ - gitlab_instance_variable - add support for ``raw`` variables suboption (https://github.com/ansible-collections/community.general/pull/9425).
+ - gitlab_runners inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - gitlab_runners inventory plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+ - hiera lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - icinga2 inventory plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9323).
+ - incus connection plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9322).
+ - iocage connection plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9322).
+ - iocage inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - iptables_state action plugin - use f-strings instead of interpolations or
+ ``format`` (https://github.com/ansible-collections/community.general/pull/9318).
+ - jabber callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - jail connection plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9322).
+ - keycloak - add an action group for Keycloak modules to allow ``module_defaults``
+ to be set for Keycloak tasks (https://github.com/ansible-collections/community.general/pull/9284).
+ - keyring lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - ksu become plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9319).
+ - lastpass lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - linode inventory plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9323).
+ - lmdb_kv lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - lmdb_kv lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - locale_gen - invert the logic to determine ``ubuntu_mode``, making it look
+ first for ``/etc/locale.gen`` (set ``ubuntu_mode`` to ``False``) and only
+ then looking for ``/var/lib/locales/supported.d/`` (set ``ubuntu_mode``
+ to ``True``) (https://github.com/ansible-collections/community.general/pull/9238,
+ https://github.com/ansible-collections/community.general/issues/9131, https://github.com/ansible-collections/community.general/issues/8487).
+ - 'locale_gen - new return value ``mechanism`` to better express the semantics
+ of the ``ubuntu_mode``, with the possible values being either ``glibc``
+ (``ubuntu_mode=False``) or ``ubuntu_legacy`` (``ubuntu_mode=True``) (https://github.com/ansible-collections/community.general/pull/9238).
+
+ '
+ - log_plays callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - loganalytics callback plugin - use f-strings instead of interpolations or
+ ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+ - logdna callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - logentries callback plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - logentries callback plugin - use f-strings instead of interpolations or
+ ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+ - lxc connection plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9322).
+ - lxd connection plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9322).
+ - lxd inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - lxd inventory plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9323).
+ - machinectl become plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9319).
+ - mail callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - manageiq_alert_profiles - improve handling of parameter requirements (https://github.com/ansible-collections/community.general/pull/9449).
+ - manifold lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - manifold lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - memcached cache plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9320).
+ - merge_variables lookup plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+ - nmap inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - nmap inventory plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9323).
+ - nrdp callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - onepassword lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - onepassword lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - onepassword_doc lookup plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+ - online inventory plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9323).
+ - opennebula inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - opennebula inventory plugin - use f-strings instead of interpolations or
+ ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+ - opentelemetry callback plugin - remove code handling Python versions prior
+ to 3.7 (https://github.com/ansible-collections/community.general/pull/9482).
+ - opentelemetry callback plugin - remove code handling Python versions prior
+ to 3.7 (https://github.com/ansible-collections/community.general/pull/9503).
+ - opentelemetry callback plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9321).
+ - pacemaker_cluster - remove unused code (https://github.com/ansible-collections/community.general/pull/9471).
+ - pacemaker_cluster - using safer mechanism to run external command (https://github.com/ansible-collections/community.general/pull/9471).
+ - passwordstore lookup plugin - use f-strings instead of interpolations or
+ ``format`` (https://github.com/ansible-collections/community.general/pull/9324).
+ - pbrun become plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9319).
+ - pfexec become plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9319).
+ - pmrun become plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9319).
+ - proxmox inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - proxmox inventory plugin - strip whitespace from ``user``, ``token_id``,
+ and ``token_secret`` (https://github.com/ansible-collections/community.general/issues/9227,
+ https://github.com/ansible-collections/community.general/pull/9228/).
+ - proxmox inventory plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9323).
+ - proxmox module utils - add method ``api_task_complete`` that can wait for
+ task completion and return error message (https://github.com/ansible-collections/community.general/pull/9256).
+ - proxmox_backup - refactor permission checking to improve code readability
+ and maintainability (https://github.com/ansible-collections/community.general/pull/9239).
+ - qubes connection plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9322).
+ - random_pet lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - redis cache plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - redis cache plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9320).
+ - redis lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - revbitspss lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - saltstack connection plugin - use f-strings instead of interpolations or
+ ``format`` (https://github.com/ansible-collections/community.general/pull/9322).
+ - say callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - scaleway inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - scaleway inventory plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9323).
+ - selective callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - sesu become plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9319).
+ - shelvefile lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - shutdown action plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - shutdown action plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9318).
+ - slack callback plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - slack callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - splunk callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - stackpath_compute inventory plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+ - sudosu become plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9319).
+ - timestamp callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - to_ini filter plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - tss lookup plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - tss lookup plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9324).
+ - unixy callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - virtualbox inventory plugin - clean up string conversions (https://github.com/ansible-collections/community.general/pull/9379).
+ - virtualbox inventory plugin - use f-strings instead of interpolations or
+ ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+ - xbps - add ``root`` and ``repository`` options to enable bootstrapping new
+ void installations (https://github.com/ansible-collections/community.general/pull/9174).
+ - xen_orchestra inventory plugin - use f-strings instead of interpolations
+ or ``format`` (https://github.com/ansible-collections/community.general/pull/9323).
+ - xfconf - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9226).
+ - xfconf_info - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9226).
+ - yaml callback plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9321).
+ - zone connection plugin - use f-strings instead of interpolations or ``format``
+ (https://github.com/ansible-collections/community.general/pull/9322).
+ - zypper - add ``quiet`` option (https://github.com/ansible-collections/community.general/pull/9270).
+ - zypper - add ``simple_errors`` option (https://github.com/ansible-collections/community.general/pull/9270).
+ release_summary: Regular bugfix and feature release.
+ security_fixes:
+ - keycloak_authentication - API calls did not properly set the ``priority``
+ during update resulting in incorrectly sorted authentication flows. This
+ apparently only affects Keycloak 25 or newer (https://github.com/ansible-collections/community.general/pull/9263).
+ fragments:
+ - 10.2.0.yml
+ - 9174-xbps-support-rootdir-and-repository.yml
+ - 9223-proxmox-backup-bugfixes.yml
+ - 9226-xfconf-version.yml
+ - 9228-fix-issue-header.yml
+ - 9234-fix-verify-bios-attributes-multi-system.yml
+ - 9238-locale-gen-rewrite.yml
+ - 9239-proxmox-backup-refactor.yml
+ - 9255-fix-handling-of-aliased-homebrew-packages.yml
+ - 9256-proxmox_disk-fix-async-method-of-resize_disk.yml
+ - 9263-kc_authentication-api-priority.yaml
+ - 9270-zypper-add-simple_errors.yaml
+ - 9277-proxmox_template-fix-the-wrong-path-called-on-proxmox_template.task_status.yaml
+ - 9284-add-keycloak-action-group.yml
+ - 9318-fstr-actionplugins.yml
+ - 9319-fstr-become-plugins.yml
+ - 9320-fstr-cache-plugins.yml
+ - 9321-fstr-callback-plugins.yml
+ - 9322-fstr-connection-plugins.yml
+ - 9323-fstr-inventory-plugins.yml
+ - 9324-fstr-lookup-plugins.yml
+ - 9334-qubes-conn.yml
+ - 9363-dig-nonameservers.yml
+ - 9379-refactor.yml
+ - 9387-pacemaker-cluster-cmd.yml
+ - 9425-gitlab-instance-raw-variable.yml
+ - 9432-deprecate-pure.yml
+ - 9443-slack-prepend_hash.yml
+ - 9449-manageiq-alert-profiles-reqs.yml
+ - 9451-facter-deprecation.yml
+ - 9456-yaml-callback-deprecation.yml
+ - 9482-opentelemetry-python-37.yml
+ - 9483-sensu-deprecation.yml
+ - 9487-atomic-deprecation.yml
+ - 9490-htpasswd-permissions.yml
+ - 9503-opentelemetry-remove-unused-code.yml
+ modules:
+ - description: Manages Android SDK packages.
+ name: android_sdk
+ namespace: ''
+ - description: Use the Modify-Increment LDAP V3 feature to increment an attribute
+ value.
+ name: ldap_inc
+ namespace: ''
+ - description: C(systemd)'s C(systemd-creds decrypt) plugin.
+ name: systemd_creds_decrypt
+ namespace: ''
+ - description: C(systemd)'s C(systemd-creds encrypt) plugin.
+ name: systemd_creds_encrypt
+ namespace: ''
+ plugins:
+ inventory:
+ - description: iocage inventory source.
+ name: iocage
+ namespace: null
+ release_date: '2024-12-31'
+ 10.3.0:
+ changes:
+ bugfixes:
+ - homebrew - fix incorrect handling of homebrew modules when a tap is requested
+ (https://github.com/ansible-collections/community.general/pull/9546, https://github.com/ansible-collections/community.general/issues/9533).
+ - iocage inventory plugin - the plugin parses the IP4 tab of the jails list
+ and put the elements into the new variable ``iocage_ip4_dict``. In multiple
+ interface format the variable ``iocage_ip4`` keeps the comma-separated list
+ of IP4 (https://github.com/ansible-collections/community.general/issues/9538).
+ - pipx - honor option ``global`` when ``state=latest`` (https://github.com/ansible-collections/community.general/pull/9623).
+ - proxmox - fixes idempotency of template conversions (https://github.com/ansible-collections/community.general/pull/9225,
+ https://github.com/ansible-collections/community.general/issues/8811).
+ - proxmox - fixes incorrect parsing for bind-only mounts (https://github.com/ansible-collections/community.general/pull/9225,
+ https://github.com/ansible-collections/community.general/issues/8982).
+ - proxmox - fixes issues with disk_volume variable (https://github.com/ansible-collections/community.general/pull/9225,
+ https://github.com/ansible-collections/community.general/issues/9065).
+ - proxmox module utils - fixes ignoring of ``choose_first_if_multiple`` argument
+ in ``get_vmid`` (https://github.com/ansible-collections/community.general/pull/9225).
+ - 'redhat_subscription - do not try to unsubscribe (i.e. remove subscriptions)
+
+ when unregistering a system: newer versions of subscription-manager, as
+
+ available in EL 10 and Fedora 41+, do not support entitlements anymore,
+ and
+
+ thus unsubscribing will fail
+
+ (https://github.com/ansible-collections/community.general/pull/9578).
+
+ '
+ deprecated_features:
+ - 'MH module utils - attribute ``debug`` definition in subclasses of MH is
+ now deprecated, as that name will become a delegation to ``AnsibleModule``
+ in community.general 12.0.0, and any such attribute will be overridden by
+ that delegation in that version (https://github.com/ansible-collections/community.general/pull/9577).
+
+ '
+ - proxmox - removes default value ``false`` of ``update`` parameter. This
+ will be changed to a default of ``true`` in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/9225).
+ minor_changes:
+ - MH module utils - delegate ``debug`` to the underlying ``AnsibleModule``
+ instance or issues a warning if an attribute already exists with that name
+ (https://github.com/ansible-collections/community.general/pull/9577).
+ - apache2_mod_proxy - better handling regexp extraction (https://github.com/ansible-collections/community.general/pull/9609).
+ - apache2_mod_proxy - change type of ``state`` to a list of strings. No change
+ for the users (https://github.com/ansible-collections/community.general/pull/9600).
+ - apache2_mod_proxy - improve readability when using results from ``fecth_url()``
+ (https://github.com/ansible-collections/community.general/pull/9608).
+ - apache2_mod_proxy - refactor repeated code into method (https://github.com/ansible-collections/community.general/pull/9599).
+ - apache2_mod_proxy - remove unused parameter and code from ``Balancer`` constructor
+ (https://github.com/ansible-collections/community.general/pull/9614).
+ - apache2_mod_proxy - simplified and improved string manipulation (https://github.com/ansible-collections/community.general/pull/9614).
+ - apache2_mod_proxy - use ``deps`` to handle dependencies (https://github.com/ansible-collections/community.general/pull/9612).
+ - cgroup_memory_recap callback plugin - adjust standard preamble for Python
+ 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - chroot connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - cloud_init_data_facts - open file using ``open()`` as a context manager
+ (https://github.com/ansible-collections/community.general/pull/9579).
+ - cobbler inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - context_demo callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - counter filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - counter_enabled callback plugin - adjust standard preamble for Python 3
+ (https://github.com/ansible-collections/community.general/pull/9583).
+ - cpanm - enable usage of option ``--with-recommends`` (https://github.com/ansible-collections/community.general/issues/9554,
+ https://github.com/ansible-collections/community.general/pull/9555).
+ - cpanm - enable usage of option ``--with-suggests`` (https://github.com/ansible-collections/community.general/pull/9555).
+ - crc32 filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - cronvar - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+ - crypttab - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+ - default_without_diff callback plugin - adjust standard preamble for Python
+ 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - dense callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - dict filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - dict_kv filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - diy callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - doas become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - dzdo become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - elastic callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - from_csv filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - from_ini filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - funcd connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - gitlab_runners inventory plugin - adjust standard preamble for Python 3
+ (https://github.com/ansible-collections/community.general/pull/9584).
+ - groupby_as_dict filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - hashids filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - icinga2 inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - incus connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - iocage connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - iocage inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - iocage inventory plugin - the new parameter ``sudo`` of the plugin lets
+ the command ``iocage list -l`` to run as root on the iocage host. This is
+ needed to get the IPv4 of a running DHCP jail (https://github.com/ansible-collections/community.general/issues/9572,
+ https://github.com/ansible-collections/community.general/pull/9573).
+ - iptables_state action plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - jabber callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - jail connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - jc filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - jira - transition operation now has ``status_id`` to directly reference
+ wanted transition (https://github.com/ansible-collections/community.general/pull/9602).
+ - json_query filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - keep_keys filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - keycloak_* modules - ``refresh_token`` parameter added. When multiple authentication
+ parameters are provided (``token``, ``refresh_token``, and ``auth_username``/``auth_password``),
+ modules will now automatically retry requests upon authentication errors
+ (401), using in order the token, refresh token, and username/password (https://github.com/ansible-collections/community.general/pull/9494).
+ - known_hosts - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+ - ksu become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - linode inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - lists filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - lists_mergeby filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - log_plays callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - loganalytics callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - logdna callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - logentries callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - logstash callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - lxc connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - lxd connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - lxd inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - machinectl become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - mail callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - memcached cache plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - nmap inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - nmcli - add a option ``fail_over_mac`` (https://github.com/ansible-collections/community.general/issues/9570,
+ https://github.com/ansible-collections/community.general/pull/9571).
+ - nrdp callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - null callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - one_template - adds ``filter`` option for retrieving templates which are
+ not owned by the user (https://github.com/ansible-collections/community.general/pull/9547,
+ https://github.com/ansible-collections/community.general/issues/9278).
+ - online inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - opennebula inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - opentelemetry callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - parted - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+ - pbrun become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - pfexec become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - pickle cache plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - pmrun become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - proxmox - refactors the proxmox module (https://github.com/ansible-collections/community.general/pull/9225).
+ - proxmox inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - proxmox_pct_remote connection plugin - adjust standard preamble for Python
+ 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - proxmox_template - add support for checksum validation with new options
+ ``checksum_algorithm`` and ``checksum`` (https://github.com/ansible-collections/community.general/issues/9553,
+ https://github.com/ansible-collections/community.general/pull/9601).
+ - pulp_repo - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+ - qubes connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - random_mac filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - redfish_info - add command ``GetAccountServiceConfig`` to get full information
+ about AccountService configuration (https://github.com/ansible-collections/community.general/pull/9403).
+ - redhat_subscription - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+ - redis cache plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - remove_keys filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - replace_keys filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - reveal_ansible_type filter plugin - adjust standard preamble for Python
+ 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - run0 become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - saltstack connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - say callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - scaleway inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - selective callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - sesu become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - shutdown action plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - slack callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - snap - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9598).
+ - snap_alias - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9598).
+ - solaris_zone - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+ - sorcery - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+ - splunk callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - stackpath_compute inventory plugin - adjust standard preamble for Python
+ 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - sudosu become plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - sumologic callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - syslog_json callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - time filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - timestamp callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - timezone - open file using ``open()`` as a context manager (https://github.com/ansible-collections/community.general/pull/9579).
+ - to_ini filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - ufw - add support for ``vrrp`` protocol (https://github.com/ansible-collections/community.general/issues/9562,
+ https://github.com/ansible-collections/community.general/pull/9582).
+ - unicode_normalize filter plugin - adjust standard preamble for Python 3
+ (https://github.com/ansible-collections/community.general/pull/9585).
+ - unixy callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - version_sort filter plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9585).
+ - virtualbox inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - xen_orchestra inventory plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ - yaml cache plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - yaml callback plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9583).
+ - zone connection plugin - adjust standard preamble for Python 3 (https://github.com/ansible-collections/community.general/pull/9584).
+ release_summary: Regular bugfix and feature release.
+ security_fixes:
+ - keycloak_client - Sanitize ``saml.encryption.private.key`` so it does not
+ show in the logs (https://github.com/ansible-collections/community.general/pull/9621).
+ fragments:
+ - 10.3.0.yml
+ - 9225-proxmox-module-refactoring.yml
+ - 9403-redfish-add-get-accountservice.yml
+ - 9494-keycloak-modules-retry-request-on-authentication-error.yaml
+ - 9539-iocage-inventory-dhcp.yml
+ - 9546-fix-handling-of-tap-homebrew-packages.yml
+ - 9547-one_template-filter.yml
+ - 9554-add-cpanm-option_with-recommends-and-suggests.yml
+ - 9570-feat-nmcli-add-fail-over-mac-parameter.yml
+ - 9573-iocage-inventory-sudo.yml
+ - 9577-mh-delegate-debug.yml
+ - 9578-redhat_subscription-no-remove-on-unregister.yml
+ - 9579-with-open.yml
+ - 9582-add-support-for-vrrp.yml
+ - 9583-py3-imports-actionbecomecachecallback.yml
+ - 9584-py3-imports-connectioninventory.yml
+ - 9585-py3-imports-filter.yml
+ - 9586-allow-transition-id-jira.yml
+ - 9598-snap-version.yml
+ - 9599-apache2-mod-proxy-revamp1.yml
+ - 9600-apache2-mod-proxy-revamp2.yml
+ - 9601-proxmox-template-support-for-checksums.yml
+ - 9608-apache2-mod-proxy-revamp3.yml
+ - 9609-apache2-mod-proxy-revamp4.yml
+ - 9612-apache2-mod-proxy-revamp5.yml
+ - 9614-apache2-mod-proxy-revamp7.yml
+ - 9621-keycloak_client-sanitize-saml-encryption-key.yml
+ - 9623-pipx-global-latest.yml
+ modules:
+ - description: Retrieve information on Proxmox scheduled backups.
+ name: proxmox_backup_info
+ namespace: ''
+ plugins:
+ connection:
+ - description: Run tasks in Proxmox LXC container instances using pct CLI
+ via SSH.
+ name: proxmox_pct_remote
+ namespace: null
+ filter:
+ - description: Create a JSON patch by comparing two JSON files.
+ name: json_diff
+ namespace: null
+ - description: Apply a JSON-Patch (RFC 6902) operation to an object.
+ name: json_patch
+ namespace: null
+ - description: Apply JSON-Patch (RFC 6902) operations to an object.
+ name: json_patch_recipe
+ namespace: null
+ lookup:
+ - description: Fetch SSH keys stored in 1Password.
+ name: onepassword_ssh_key
+ namespace: null
+ release_date: '2025-01-27'
+ 10.3.1:
+ changes:
+ bugfixes:
+ - cloudflare_dns - fix crash when deleting a DNS record or when updating a
+ record with ``solo=true`` (https://github.com/ansible-collections/community.general/issues/9652,
+ https://github.com/ansible-collections/community.general/pull/9649).
+ - homebrew - make package name parsing more resilient (https://github.com/ansible-collections/community.general/pull/9665,
+ https://github.com/ansible-collections/community.general/issues/9641).
+ - keycloak module utils - replaces missing return in get_role_composites method
+ which caused it to return None instead of composite roles (https://github.com/ansible-collections/community.general/issues/9678,
+ https://github.com/ansible-collections/community.general/pull/9691).
+ - keycloak_client - fix and improve existing tests. The module showed a diff
+ without actual changes, solved by improving the ``normalise_cr()`` function
+ (https://github.com/ansible-collections/community.general/pull/9644).
+ - proxmox - adds the ``pubkey`` parameter (back to) the ``update`` state (https://github.com/ansible-collections/community.general/issues/9642,
+ https://github.com/ansible-collections/community.general/pull/9645).
+ - proxmox - fixes a typo in the translation of the ``pubkey`` parameter to
+ proxmox' ``ssh-public-keys`` (https://github.com/ansible-collections/community.general/issues/9642,
+ https://github.com/ansible-collections/community.general/pull/9645).
+ - xml - ensure file descriptor is closed (https://github.com/ansible-collections/community.general/pull/9695).
+ minor_changes:
+ - onepassword_ssh_key - refactor to move code to lookup class (https://github.com/ansible-collections/community.general/pull/9633).
+ release_summary: Bugfix release.
+ fragments:
+ - 10.3.1.yml
+ - 9633-onepassword_ssh_key.yml
+ - 9644-kc_client-test-improvement-and-fix.yaml
+ - 9645-proxmox-fix-pubkey.yml
+ - 9649-cloudflare_dns-fix-crash-when-deleting-record.yml
+ - 9665-more-resilient-handling-of-homebrew-packages-names.yml
+ - 9691-keycloak-module-utils-replace-missing-return-in-get_role_composites.yml
+ - 9695-xml-close-file.yml
+ release_date: '2025-02-10'
+ 10.4.0:
+ changes:
+ bugfixes:
+ - apache2_mod_proxy - make compatible with Python 3 (https://github.com/ansible-collections/community.general/pull/9762).
+ - apache2_mod_proxy - passing the cluster's page as referer for the member's
+ pages. This makes the module actually work again for halfway modern Apache
+ versions. According to some comments founds on the net the referer was required
+ since at least 2019 for some versions of Apache 2 (https://github.com/ansible-collections/community.general/pull/9762).
+ - 'elasticsearch_plugin - fix ``ERROR: D is not a recognized option`` issue
+ when configuring proxy settings (https://github.com/ansible-collections/community.general/pull/9774,
+ https://github.com/ansible-collections/community.general/issues/9773).'
+ - ipa_host - module revoked existing host certificates even if ``user_certificate``
+ was not given (https://github.com/ansible-collections/community.general/pull/9694).
+ - keycloak_client - in check mode, detect whether the lists in before client
+ (for example redirect URI list) contain items that the lists in the desired
+ client do not contain (https://github.com/ansible-collections/community.general/pull/9739).
+ - lldp - fix crash caused by certain lldpctl output where an attribute is
+ defined as branch and leaf (https://github.com/ansible-collections/community.general/pull/9657).
+ - onepassword_doc lookup plugin - ensure that 1Password Connect support also
+ works for this plugin (https://github.com/ansible-collections/community.general/pull/9625).
+ - passwordstore lookup plugin - fix subkey creation even when ``create=false``
+ (https://github.com/ansible-collections/community.general/issues/9105, https://github.com/ansible-collections/community.general/pull/9106).
+ - 'proxmox inventory plugin - plugin did not update cache correctly after
+ ``meta: refresh_inventory`` (https://github.com/ansible-collections/community.general/issues/9710,
+ https://github.com/ansible-collections/community.general/pull/9760).'
+ - 'redhat_subscription - use the "enable_content" option (when available)
+ when
+
+ registering using D-Bus, to ensure that subscription-manager enables the
+
+ content on registration; this is particular important on EL 10+ and Fedora
+
+ 41+
+
+ (https://github.com/ansible-collections/community.general/pull/9778).
+
+ '
+ - zfs - fix handling of multi-line values of user-defined ZFS properties (https://github.com/ansible-collections/community.general/pull/6264).
+ - zfs_facts - parameter ``type`` now accepts multple values as documented
+ (https://github.com/ansible-collections/community.general/issues/5909, https://github.com/ansible-collections/community.general/pull/9697).
+ deprecated_features:
+ - profitbricks - module is deprecated and will be removed in community.general
+ 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+ - profitbricks_datacenter - module is deprecated and will be removed in community.general
+ 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+ - profitbricks_nic - module is deprecated and will be removed in community.general
+ 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+ - profitbricks_volume - module is deprecated and will be removed in community.general
+ 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+ - profitbricks_volume_attachments - module is deprecated and will be removed
+ in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/9733).
+ minor_changes:
+ - bitwarden lookup plugin - add new option ``collection_name`` to filter results
+ by collection name, and new option ``result_count`` to validate number of
+ results (https://github.com/ansible-collections/community.general/pull/9728).
+ - incus connection plugin - adds ``remote_user`` and ``incus_become_method``
+ parameters for allowing a non-root user to connect to an Incus instance
+ (https://github.com/ansible-collections/community.general/pull/9743).
+ - iocage inventory plugin - the new parameter ``hooks_results`` of the plugin
+ is a list of files inside a jail that provide configuration parameters for
+ the inventory. The inventory plugin reads the files from the jails and put
+ the contents into the items of created variable ``iocage_hooks`` (https://github.com/ansible-collections/community.general/issues/9650,
+ https://github.com/ansible-collections/community.general/pull/9651).
+ - jira - adds ``client_cert`` and ``client_key`` parameters for supporting
+ client certificate authentification when connecting to Jira (https://github.com/ansible-collections/community.general/pull/9753).
+ - lldp - adds ``multivalues`` parameter to control behavior when lldpctl outputs
+ an attribute multiple times (https://github.com/ansible-collections/community.general/pull/9657).
+ - lvg - add ``remove_extra_pvs`` parameter to control if ansible should remove
+ physical volumes which are not in the ``pvs`` parameter (https://github.com/ansible-collections/community.general/pull/9698).
+ - lxd connection plugin - adds ``remote_user`` and ``lxd_become_method`` parameters
+ for allowing a non-root user to connect to an LXD instance (https://github.com/ansible-collections/community.general/pull/9659).
+ - nmcli - adds VRF support with new ``type`` value ``vrf`` and new ``slave_type``
+ value ``vrf`` as well as new ``table`` parameter (https://github.com/ansible-collections/community.general/pull/9658,
+ https://github.com/ansible-collections/community.general/issues/8014).
+ - proxmox_kvm - allow hibernation and suspending of VMs (https://github.com/ansible-collections/community.general/issues/9620,
+ https://github.com/ansible-collections/community.general/pull/9653).
+ - redfish_command - add ``PowerFullPowerCycle`` to power command options (https://github.com/ansible-collections/community.general/pull/9729).
+ - ssh_config - add ``other_options`` option (https://github.com/ansible-collections/community.general/issues/8053,
+ https://github.com/ansible-collections/community.general/pull/9684).
+ - xen_orchestra inventory plugin - add ``use_vm_uuid`` and ``use_host_uuid``
+ boolean options to allow switching over to using VM/Xen name labels instead
+ of UUIDs as item names (https://github.com/ansible-collections/community.general/pull/9787).
+ release_summary: Regular bugfix and feature release.
+ fragments:
+ - 10.4.0.yaml
+ - 6264-zfs-multiline-property-value.yml
+ - 9106-passwordstore-fix-subkey-creation-even-when-create-==-false.yml
+ - 9625-onepassword_doc.yml
+ - 9651-iocage-inventory-hooks.yml
+ - 9653-proxmox-kvm-allow-vm-hibernation.yml
+ - 9657-lldp-handling-attributes-defined-multiple-times.yml
+ - 9658-add-vrf-commands-to-nmcli-module.yml
+ - 9659-lxd_connection-nonroot-user.yml
+ - 9694-ipa-host-certificate-revoked.yml
+ - 9697-zfs-facts-type.yml
+ - 9698-lvg-remove-extra-pvs-parameter.yml
+ - 9728-bitwarden-collection-name-filter.yml
+ - 9729-redfish-fullpowercycle-command.yml
+ - 9733-profitbrick-deprecation.yml
+ - 9739-keycloak_client-compare-before-desired-directly.yml
+ - 9743-incus_connection-nonroot-user.yml
+ - 9753-jira-add-client-certificate-auth.yml
+ - 9760-proxmox-inventory.yml
+ - 9762-apache2_mod_proxy.yml
+ - 9774-fix-elasticsearch_plugin-proxy-settings.yml
+ - 9778-redhat_subscription-ensure-to-enable-content.yml
+ - 9787-xoa_allow_using_names_in_inventory.yml
+ - ssh_config_add_other_options.yml
+ modules:
+ - description: Gather C(systemd) unit info.
+ name: systemd_info
+ namespace: ''
+ release_date: '2025-02-24'
+ 10.5.0:
+ changes:
+ bugfixes:
+ - cloudlare_dns - handle exhausted response stream in case of HTTP errors
+ to show nice error message to the user (https://github.com/ansible-collections/community.general/issues/9782,
+ https://github.com/ansible-collections/community.general/pull/9818).
+ - dnf_versionlock - add support for dnf5 (https://github.com/ansible-collections/community.general/issues/9556).
+ - homebrew - fix crash when package names include tap (https://github.com/ansible-collections/community.general/issues/9777,
+ https://github.com/ansible-collections/community.general/pull/9803).
+ - homebrew_cask - handle unusual brew version strings (https://github.com/ansible-collections/community.general/issues/8432,
+ https://github.com/ansible-collections/community.general/pull/9881).
+ - nmcli - enable changing only the order of DNS servers or search suffixes
+ (https://github.com/ansible-collections/community.general/issues/8724, https://github.com/ansible-collections/community.general/pull/9880).
+ - proxmox - add missing key selection of ``'status'`` key to ``get_lxc_status``
+ (https://github.com/ansible-collections/community.general/issues/9696, https://github.com/ansible-collections/community.general/pull/9809).
+ - proxmox_vm_info - the module no longer expects that the key ``template``
+ exists in a dictionary returned by Proxmox (https://github.com/ansible-collections/community.general/issues/9875,
+ https://github.com/ansible-collections/community.general/pull/9910).
+ - sudoers - display stdout and stderr raised while failed validation (https://github.com/ansible-collections/community.general/issues/9674,
+ https://github.com/ansible-collections/community.general/pull/9871).
+ minor_changes:
+ - CmdRunner module utils - the convenience method ``cmd_runner_fmt.as_fixed()``
+ now accepts multiple arguments as a list (https://github.com/ansible-collections/community.general/pull/9893).
+ - apache2_mod_proxy - code simplification, no change in functionality (https://github.com/ansible-collections/community.general/pull/9457).
+ - consul_token - fix idempotency when ``policies`` or ``roles`` are supplied
+ by name (https://github.com/ansible-collections/community.general/issues/9841,
+ https://github.com/ansible-collections/community.general/pull/9845).
+ - keycloak_realm - remove ID requirement when creating a realm to allow Keycloak
+ generating its own realm ID (https://github.com/ansible-collections/community.general/pull/9768).
+ - nmap inventory plugin - adds ``dns_servers`` option for specifying DNS servers
+ for name resolution. Accepts hostnames or IP addresses in the same format
+ as the ``exclude`` option (https://github.com/ansible-collections/community.general/pull/9849).
+ - proxmox_kvm - add missing audio hardware device handling (https://github.com/ansible-collections/community.general/issues/5192,
+ https://github.com/ansible-collections/community.general/pull/9847).
+ - redfish_config - add command ``SetPowerRestorePolicy`` to set the desired
+ power state of the system when power is restored (https://github.com/ansible-collections/community.general/pull/9837).
+ - redfish_info - add command ``GetPowerRestorePolicy`` to get the desired
+ power state of the system when power is restored (https://github.com/ansible-collections/community.general/pull/9824).
+ - rocketchat - option ``is_pre740`` has been added to control the format of
+ the payload. For Rocket.Chat 7.4.0 or newer, it must be set to ``false``
+ (https://github.com/ansible-collections/community.general/pull/9882).
+ - slack callback plugin - add ``http_agent`` option to enable the user to
+ set a custom user agent for slack callback plugin (https://github.com/ansible-collections/community.general/issues/9813,
+ https://github.com/ansible-collections/community.general/pull/9836).
+ - systemd_info - add wildcard expression support in ``unitname`` option (https://github.com/ansible-collections/community.general/pull/9821).
+ - systemd_info - extend support to timer units (https://github.com/ansible-collections/community.general/pull/9891).
+ - vmadm - add new options ``flexible_disk_size`` and ``owner_uuid`` (https://github.com/ansible-collections/community.general/pull/9892).
+ release_summary: Regular bugfix and feature release.
+ fragments:
+ - 10.5.0.yml
+ - 9457-apache2-mod-proxy-revamp.yml
+ - 9768-keycloak_realm-remove-id-requirement.yaml
+ - 9777-homebrew-fix-crash-when-packages-include-tap.yml
+ - 9809-proxmox-fix-status-getter.yml
+ - 9818-cloudflare-dns-exhausted-response.yml
+ - 9821-systemd_info-add-wildcards.yml
+ - 9824-redfish-implement-obtaining-powerrestorepolicy.yml
+ - 9836-option-for-http-agent-for-user-to-callback-slack.yml
+ - 9837-redfish-implement-setting-powerrestorepolicy.yml
+ - 9845-consul_token_idempotency.yml
+ - 9847-Adding_audio_device-support_to_proxmox_kvm.yml
+ - 9849-nmap_dns_servers.yml
+ - 9875-proxmox-dont-expect-key-template-to-exist.yml
+ - 9880-nmcli-fix-reorder-same-dns-nameservers-search-suffixes.yml
+ - 9882-fix-payload-to-match-rocketchat-740-requirement.yml
+ - 9891-systemd_info-add_timer.yml
+ - 9892-vmadm-add-new-options.yml
+ - 9893-cmdrunner-as-fixed-args.yml
+ - dnf_versionlock.yml
+ - homebrew_cask.yml
+ - sudoers.yml
+ modules:
+ - description: Manage pacemaker resources.
+ name: pacemaker_resource
+ namespace: ''
+ release_date: '2025-03-24'
diff --git a/changelogs/fragments/8051-Redfish-Wait-For-Service.yml b/changelogs/fragments/8051-Redfish-Wait-For-Service.yml
deleted file mode 100644
index 826c40e8af..0000000000
--- a/changelogs/fragments/8051-Redfish-Wait-For-Service.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-minor_changes:
- - redfish_info - add command ``CheckAvailability`` to check if a service is accessible (https://github.com/ansible-collections/community.general/issues/8051, https://github.com/ansible-collections/community.general/pull/8434).
- - redfish_command - add ``wait`` and ``wait_timeout`` options to allow a user to block a command until a service is accessible after performing the requested command (https://github.com/ansible-collections/community.general/issues/8051, https://github.com/ansible-collections/community.general/pull/8434).
diff --git a/changelogs/fragments/8214-sudosu-not-working-on-some-BSD-machines.yml b/changelogs/fragments/8214-sudosu-not-working-on-some-BSD-machines.yml
deleted file mode 100644
index 411ba8e868..0000000000
--- a/changelogs/fragments/8214-sudosu-not-working-on-some-BSD-machines.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - sudosu become plugin - added an option (``alt_method``) to enhance compatibility with more versions of ``su`` (https://github.com/ansible-collections/community.general/pull/8214).
diff --git a/changelogs/fragments/8402-add-diif-mode-openbsd-pkg.yml b/changelogs/fragments/8402-add-diif-mode-openbsd-pkg.yml
deleted file mode 100644
index 2a4e7dfd8d..0000000000
--- a/changelogs/fragments/8402-add-diif-mode-openbsd-pkg.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - openbsd_pkg - adds diff support to show changes in installed package list. This does not yet work for check mode (https://github.com/ansible-collections/community.general/pull/8402).
diff --git a/changelogs/fragments/8403-fix-typeerror-in-keycloak-client.yaml b/changelogs/fragments/8403-fix-typeerror-in-keycloak-client.yaml
deleted file mode 100644
index b8acf7b09b..0000000000
--- a/changelogs/fragments/8403-fix-typeerror-in-keycloak-client.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_client - fix TypeError when sanitizing the ``saml.signing.private.key`` attribute in the module's diff or state output. The ``sanitize_cr`` function expected a dict where in some cases a list might occur (https://github.com/ansible-collections/community.general/pull/8403).
diff --git a/changelogs/fragments/8404-ipa_dnsrecord_sshfp.yml b/changelogs/fragments/8404-ipa_dnsrecord_sshfp.yml
deleted file mode 100644
index e989f5dbb1..0000000000
--- a/changelogs/fragments/8404-ipa_dnsrecord_sshfp.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - ipa_dnsrecord - adds ``SSHFP`` record type for managing SSH fingerprints in FreeIPA DNS (https://github.com/ansible-collections/community.general/pull/8404).
diff --git a/changelogs/fragments/8405-gitlab-remove-basic-auth.yml b/changelogs/fragments/8405-gitlab-remove-basic-auth.yml
deleted file mode 100644
index f8a03a3d71..0000000000
--- a/changelogs/fragments/8405-gitlab-remove-basic-auth.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-removed_features:
- - gitlab modules - remove basic auth feature (https://github.com/ansible-collections/community.general/pull/8405).
diff --git a/changelogs/fragments/8406-fix-homebrew-cask-warning.yaml b/changelogs/fragments/8406-fix-homebrew-cask-warning.yaml
deleted file mode 100644
index 0e3bf38ed3..0000000000
--- a/changelogs/fragments/8406-fix-homebrew-cask-warning.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - homebrew - do not fail when brew prints warnings (https://github.com/ansible-collections/community.general/pull/8406, https://github.com/ansible-collections/community.general/issues/7044).
diff --git a/changelogs/fragments/8411-locale-gen-vardict.yml b/changelogs/fragments/8411-locale-gen-vardict.yml
deleted file mode 100644
index 5220731281..0000000000
--- a/changelogs/fragments/8411-locale-gen-vardict.yml
+++ /dev/null
@@ -1,11 +0,0 @@
-bugfixes:
- - django module utils - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
- - cpanm - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
- - gconftool2_info - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
- - hponcfg - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
- - kernel_blacklist - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
- - locale_gen - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
- - mksysb - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
- - pipx_info - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
- - snap - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
- - snap_alias - use new ``VarDict`` to prevent deprecation warning (https://github.com/ansible-collections/community.general/issues/8410, https://github.com/ansible-collections/community.general/pull/8411).
diff --git a/changelogs/fragments/8413-galaxy-refactor.yml b/changelogs/fragments/8413-galaxy-refactor.yml
deleted file mode 100644
index edd1601be8..0000000000
--- a/changelogs/fragments/8413-galaxy-refactor.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - ansible_galaxy_install - minor refactor in the module (https://github.com/ansible-collections/community.general/pull/8413).
diff --git a/changelogs/fragments/8415-cmd-runner-stack.yml b/changelogs/fragments/8415-cmd-runner-stack.yml
deleted file mode 100644
index 555683e057..0000000000
--- a/changelogs/fragments/8415-cmd-runner-stack.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - cmd_runner module utils - add decorator ``cmd_runner_fmt.stack`` (https://github.com/ansible-collections/community.general/pull/8415).
diff --git a/changelogs/fragments/8428-assign-auth-flow-by-name-keycloak-client.yaml b/changelogs/fragments/8428-assign-auth-flow-by-name-keycloak-client.yaml
deleted file mode 100644
index d9bb9bc3ea..0000000000
--- a/changelogs/fragments/8428-assign-auth-flow-by-name-keycloak-client.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - keycloak_client - assign auth flow by name (https://github.com/ansible-collections/community.general/pull/8428).
diff --git a/changelogs/fragments/8430-fix-opentelemetry-when-using-logs-with-uri-or-slurp-tasks.yaml b/changelogs/fragments/8430-fix-opentelemetry-when-using-logs-with-uri-or-slurp-tasks.yaml
deleted file mode 100644
index 29da61c8bf..0000000000
--- a/changelogs/fragments/8430-fix-opentelemetry-when-using-logs-with-uri-or-slurp-tasks.yaml
+++ /dev/null
@@ -1,3 +0,0 @@
-bugfixes:
- - opentelemetry callback - do not save the JSON response when using the ``ansible.builtin.uri`` module (https://github.com/ansible-collections/community.general/pull/8430).
- - opentelemetry callback - do not save the content response when using the ``ansible.builtin.slurp`` module (https://github.com/ansible-collections/community.general/pull/8430).
\ No newline at end of file
diff --git a/changelogs/fragments/8431-galaxy-upgrade.yml b/changelogs/fragments/8431-galaxy-upgrade.yml
deleted file mode 100644
index 9be9ca93c8..0000000000
--- a/changelogs/fragments/8431-galaxy-upgrade.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - ansible_galaxy_install - add upgrade feature (https://github.com/ansible-collections/community.general/pull/8431, https://github.com/ansible-collections/community.general/issues/8351).
diff --git a/changelogs/fragments/8440-allow-api-port-specification.yaml b/changelogs/fragments/8440-allow-api-port-specification.yaml
deleted file mode 100644
index 646ee1ab60..0000000000
--- a/changelogs/fragments/8440-allow-api-port-specification.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - proxmox - allow specification of the API port when using proxmox_* (https://github.com/ansible-collections/community.general/issues/8440, https://github.com/ansible-collections/community.general/pull/8441).
diff --git a/changelogs/fragments/8444-fix-redfish-gen2-upgrade.yaml b/changelogs/fragments/8444-fix-redfish-gen2-upgrade.yaml
deleted file mode 100644
index d094327240..0000000000
--- a/changelogs/fragments/8444-fix-redfish-gen2-upgrade.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - wdc_redfish_command - minor change to handle upgrade file for Redfish WD platforms (https://github.com/ansible-collections/community.general/pull/8444).
diff --git a/changelogs/fragments/8452-git_config-absent.yml b/changelogs/fragments/8452-git_config-absent.yml
deleted file mode 100644
index 11e0767713..0000000000
--- a/changelogs/fragments/8452-git_config-absent.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - "git_config - fix behavior of ``state=absent`` if ``value`` is present (https://github.com/ansible-collections/community.general/issues/8436, https://github.com/ansible-collections/community.general/pull/8452)."
diff --git a/changelogs/fragments/8453-git_config-deprecate-read.yml b/changelogs/fragments/8453-git_config-deprecate-read.yml
deleted file mode 100644
index a291568fce..0000000000
--- a/changelogs/fragments/8453-git_config-deprecate-read.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-deprecated_features:
- - "git_config - the ``list_all`` option has been deprecated and will be removed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead (https://github.com/ansible-collections/community.general/pull/8453)."
- - "git_config - using ``state=present`` without providing ``value`` is deprecated and will be disallowed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead to read a value (https://github.com/ansible-collections/community.general/pull/8453)."
diff --git a/changelogs/fragments/8464-redis-add-cluster-info.yml b/changelogs/fragments/8464-redis-add-cluster-info.yml
deleted file mode 100644
index 921307d716..0000000000
--- a/changelogs/fragments/8464-redis-add-cluster-info.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - redis_info - adds support for getting cluster info (https://github.com/ansible-collections/community.general/pull/8464).
diff --git a/changelogs/fragments/8471-proxmox-vm-info-network.yml b/changelogs/fragments/8471-proxmox-vm-info-network.yml
deleted file mode 100644
index f658b78831..0000000000
--- a/changelogs/fragments/8471-proxmox-vm-info-network.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - proxmox_vm_info - add ``network`` option to retrieve current network information (https://github.com/ansible-collections/community.general/pull/8471).
diff --git a/changelogs/fragments/8476-launchd-check-mode-changed.yaml b/changelogs/fragments/8476-launchd-check-mode-changed.yaml
deleted file mode 100644
index dc1e60de36..0000000000
--- a/changelogs/fragments/8476-launchd-check-mode-changed.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - launched - correctly report changed status in check mode (https://github.com/ansible-collections/community.general/pull/8406).
diff --git a/changelogs/fragments/8479-cmdrunner-improvements.yml b/changelogs/fragments/8479-cmdrunner-improvements.yml
deleted file mode 100644
index 075f5f5cd6..0000000000
--- a/changelogs/fragments/8479-cmdrunner-improvements.yml
+++ /dev/null
@@ -1,4 +0,0 @@
-deprecated_features:
- - CmdRunner module util - setting the value of the ``ignore_none`` parameter within a ``CmdRunner`` context is deprecated and that feature should be removed in community.general 12.0.0 (https://github.com/ansible-collections/community.general/pull/8479).
-minor_changes:
- - CmdRunner module util - argument formats can be specified as plain functions without calling ``cmd_runner_fmt.as_func()`` (https://github.com/ansible-collections/community.general/pull/8479).
diff --git a/changelogs/fragments/8480-directory-feature-cargo.yml b/changelogs/fragments/8480-directory-feature-cargo.yml
deleted file mode 100644
index 8892e7c5dd..0000000000
--- a/changelogs/fragments/8480-directory-feature-cargo.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - "cargo - add option ``directory``, which allows source directory to be specified (https://github.com/ansible-collections/community.general/pull/8480)."
diff --git a/changelogs/fragments/8489-fix-opennebula-inventory-crash-when-nic-has-no-ip.yml b/changelogs/fragments/8489-fix-opennebula-inventory-crash-when-nic-has-no-ip.yml
deleted file mode 100644
index 3db86f364e..0000000000
--- a/changelogs/fragments/8489-fix-opennebula-inventory-crash-when-nic-has-no-ip.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - opennebula inventory plugin - fix invalid reference to IP when inventory runs against NICs with no IPv4 address (https://github.com/ansible-collections/community.general/pull/8489).
diff --git a/changelogs/fragments/8496-keycloak_clientscope-add-normalizations.yaml b/changelogs/fragments/8496-keycloak_clientscope-add-normalizations.yaml
deleted file mode 100644
index 8af320cae0..0000000000
--- a/changelogs/fragments/8496-keycloak_clientscope-add-normalizations.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_realm - add normalizations for ``attributes`` and ``protocol_mappers`` (https://github.com/ansible-collections/community.general/pull/8496).
diff --git a/changelogs/fragments/8497-crypt.yml b/changelogs/fragments/8497-crypt.yml
deleted file mode 100644
index f77f6c20f9..0000000000
--- a/changelogs/fragments/8497-crypt.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-known_issues:
- - "homectl - the module does not work under Python 3.13 or newer, since it relies on the removed ``crypt`` standard library module (https://github.com/ansible-collections/community.general/issues/4691, https://github.com/ansible-collections/community.general/pull/8497)."
- - "udm_user - the module does not work under Python 3.13 or newer, since it relies on the removed ``crypt`` standard library module (https://github.com/ansible-collections/community.general/issues/4690, https://github.com/ansible-collections/community.general/pull/8497)."
diff --git a/changelogs/fragments/8508-virtualbox-inventory.yml b/changelogs/fragments/8508-virtualbox-inventory.yml
deleted file mode 100644
index dd14818331..0000000000
--- a/changelogs/fragments/8508-virtualbox-inventory.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-minor_changes:
- - >-
- virtualbox inventory plugin - expose a new parameter ``enable_advanced_group_parsing`` to change how the VirtualBox dynamic inventory parses VM groups (https://github.com/ansible-collections/community.general/issues/8508, https://github.com/ansible-collections/community.general/pull/8510).
\ No newline at end of file
diff --git a/changelogs/fragments/8512-as-bool-not.yml b/changelogs/fragments/8512-as-bool-not.yml
deleted file mode 100644
index f579c19810..0000000000
--- a/changelogs/fragments/8512-as-bool-not.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - cmd_runner_fmt module utils - simplify implementation of ``cmd_runner_fmt.as_bool_not()`` (https://github.com/ansible-collections/community.general/pull/8512).
diff --git a/changelogs/fragments/8514-pacman-empty.yml b/changelogs/fragments/8514-pacman-empty.yml
deleted file mode 100644
index c51ba21acc..0000000000
--- a/changelogs/fragments/8514-pacman-empty.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - "paman - do not fail if an empty list of packages has been provided and there is nothing to do (https://github.com/ansible-collections/community.general/pull/8514)."
diff --git a/changelogs/fragments/8516-proxmox-template-refactor.yml b/changelogs/fragments/8516-proxmox-template-refactor.yml
deleted file mode 100644
index c069985111..0000000000
--- a/changelogs/fragments/8516-proxmox-template-refactor.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - proxmox_template - small refactor in logic for determining whether a template exists or not (https://github.com/ansible-collections/community.general/pull/8516).
diff --git a/changelogs/fragments/8517-cmd-runner-lang-auto.yml b/changelogs/fragments/8517-cmd-runner-lang-auto.yml
deleted file mode 100644
index 086a74e997..0000000000
--- a/changelogs/fragments/8517-cmd-runner-lang-auto.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - CmdRunner module utils - the parameter ``force_lang`` now supports the special value ``auto`` which will automatically try and determine the best parsable locale in the system (https://github.com/ansible-collections/community.general/pull/8517).
diff --git a/changelogs/fragments/8532-expand-opennuebula-inventory-data.yml b/changelogs/fragments/8532-expand-opennuebula-inventory-data.yml
deleted file mode 100644
index a1b0ffe2c0..0000000000
--- a/changelogs/fragments/8532-expand-opennuebula-inventory-data.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - opennebula.py - add VM ``id`` and VM ``host`` to inventory host data (https://github.com/ansible-collections/community.general/pull/8532).
diff --git a/changelogs/fragments/8533-add-ciphers-option.yml b/changelogs/fragments/8533-add-ciphers-option.yml
deleted file mode 100644
index 7f9880ebee..0000000000
--- a/changelogs/fragments/8533-add-ciphers-option.yml
+++ /dev/null
@@ -1,4 +0,0 @@
----
-minor_changes:
- - redfish_* modules - adds ``ciphers`` option for custom cipher selection (https://github.com/ansible-collections/community.general/pull/8533).
-...
diff --git a/changelogs/fragments/8542-fix-proxmox-volume-handling.yml b/changelogs/fragments/8542-fix-proxmox-volume-handling.yml
deleted file mode 100644
index 9b982c0aeb..0000000000
--- a/changelogs/fragments/8542-fix-proxmox-volume-handling.yml
+++ /dev/null
@@ -1,5 +0,0 @@
-bugfixes:
- - proxmox - fix idempotency on creation of mount volumes using Proxmox' special ``:`` syntax (https://github.com/ansible-collections/community.general/issues/8407, https://github.com/ansible-collections/community.general/pull/8542).
-minor_changes:
- - proxmox - add ``disk_volume`` and ``mount_volumes`` keys for better readability (https://github.com/ansible-collections/community.general/pull/8542).
- - proxmox - translate the old ``disk`` and ``mounts`` keys to the new handling internally (https://github.com/ansible-collections/community.general/pull/8542).
diff --git a/changelogs/fragments/8545-keycloak-clientscope-remove-id-on-compare.yml b/changelogs/fragments/8545-keycloak-clientscope-remove-id-on-compare.yml
deleted file mode 100644
index 5986a45b87..0000000000
--- a/changelogs/fragments/8545-keycloak-clientscope-remove-id-on-compare.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_clientscope - remove IDs from clientscope and its protocol mappers on comparison for changed check (https://github.com/ansible-collections/community.general/pull/8545).
diff --git a/changelogs/fragments/8557-fix-bug-with-bitwarden.yml b/changelogs/fragments/8557-fix-bug-with-bitwarden.yml
deleted file mode 100644
index cf41ae209f..0000000000
--- a/changelogs/fragments/8557-fix-bug-with-bitwarden.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - "bitwarden lookup plugin - fix ``KeyError`` in ``search_field`` (https://github.com/ansible-collections/community.general/issues/8549, https://github.com/ansible-collections/community.general/pull/8557)."
\ No newline at end of file
diff --git a/changelogs/fragments/8613-redfish_utils-language.yaml b/changelogs/fragments/8613-redfish_utils-language.yaml
deleted file mode 100644
index 1fc43c895d..0000000000
--- a/changelogs/fragments/8613-redfish_utils-language.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - redfish_utils module utils - do not fail when language is not exactly "en" (https://github.com/ansible-collections/community.general/pull/8613).
diff --git a/changelogs/fragments/8614-nsupdate-index-out-of-range.yml b/changelogs/fragments/8614-nsupdate-index-out-of-range.yml
deleted file mode 100644
index 00b6f8b974..0000000000
--- a/changelogs/fragments/8614-nsupdate-index-out-of-range.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - "nsupdate - fix 'index out of range' error when changing NS records by falling back to authority section of the response (https://github.com/ansible-collections/community.general/issues/8612, https://github.com/ansible-collections/community.general/pull/8614)."
diff --git a/changelogs/fragments/8623-become-types.yml b/changelogs/fragments/8623-become-types.yml
deleted file mode 100644
index c38e67eca1..0000000000
--- a/changelogs/fragments/8623-become-types.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - "doas, dzdo, ksu, machinectl, pbrun, pfexec, pmrun, sesu, sudosu become plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8623)."
diff --git a/changelogs/fragments/8624-cache-types.yml b/changelogs/fragments/8624-cache-types.yml
deleted file mode 100644
index 8efa34b6c0..0000000000
--- a/changelogs/fragments/8624-cache-types.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - "memcached, pickle, redis, yaml cache plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8624)."
diff --git a/changelogs/fragments/8625-inventory-types.yml b/changelogs/fragments/8625-inventory-types.yml
deleted file mode 100644
index a89352a230..0000000000
--- a/changelogs/fragments/8625-inventory-types.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - "cobbler, linode, lxd, nmap, online, scaleway, stackpath_compute, virtualbox inventory plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8625)."
diff --git a/changelogs/fragments/8626-lookup-types.yml b/changelogs/fragments/8626-lookup-types.yml
deleted file mode 100644
index b6ebf35748..0000000000
--- a/changelogs/fragments/8626-lookup-types.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - "chef_databag, consul_kv, cyberarkpassword, dsv, etcd, filetree, hiera, onepassword, onepassword_doc, onepassword_raw, passwordstore, redis, shelvefile, tss lookup plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8626)."
diff --git a/changelogs/fragments/8627-connection-types.yml b/changelogs/fragments/8627-connection-types.yml
deleted file mode 100644
index 9b92735fb8..0000000000
--- a/changelogs/fragments/8627-connection-types.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - "chroot, funcd, incus, iocage, jail, lxc, lxd, qubes, zone connection plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8627)."
diff --git a/changelogs/fragments/8628-callback-types.yml b/changelogs/fragments/8628-callback-types.yml
deleted file mode 100644
index c223a85985..0000000000
--- a/changelogs/fragments/8628-callback-types.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - "cgroup_memory_recap, hipchat, jabber, log_plays, loganalytics, logentries, logstash, slack, splunk, sumologic, syslog_json callback plugins - make sure that all options are typed (https://github.com/ansible-collections/community.general/pull/8628)."
diff --git a/changelogs/fragments/8632-pkgng-add-option-use_globs.yml b/changelogs/fragments/8632-pkgng-add-option-use_globs.yml
deleted file mode 100644
index d3e03959d5..0000000000
--- a/changelogs/fragments/8632-pkgng-add-option-use_globs.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - pkgng - add option ``use_globs`` (default ``true``) to optionally disable glob patterns (https://github.com/ansible-collections/community.general/issues/8632, https://github.com/ansible-collections/community.general/pull/8633).
diff --git a/changelogs/fragments/8646-fix-bug-in-proxmox-volumes.yml b/changelogs/fragments/8646-fix-bug-in-proxmox-volumes.yml
deleted file mode 100644
index b3b03a008b..0000000000
--- a/changelogs/fragments/8646-fix-bug-in-proxmox-volumes.yml
+++ /dev/null
@@ -1,4 +0,0 @@
-bugfixes:
- - proxmox - removed the forced conversion of non-string values to strings to be consistent with the module documentation (https://github.com/ansible-collections/community.general/pull/8646).
- - proxmox - fixed an issue where the new volume handling incorrectly converted ``null`` values into ``"None"`` strings (https://github.com/ansible-collections/community.general/pull/8646).
- - proxmox - fixed an issue where volume strings where overwritten instead of appended to in the new ``build_volume()`` method (https://github.com/ansible-collections/community.general/pull/8646).
diff --git a/changelogs/fragments/8648-fix-gitlab-runner-paused.yaml b/changelogs/fragments/8648-fix-gitlab-runner-paused.yaml
deleted file mode 100644
index d064725f14..0000000000
--- a/changelogs/fragments/8648-fix-gitlab-runner-paused.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - "gitlab_runner - fix ``paused`` parameter being ignored (https://github.com/ansible-collections/community.general/pull/8648)."
\ No newline at end of file
diff --git a/changelogs/fragments/8652-Redfish-Password-Change-Required.yml b/changelogs/fragments/8652-Redfish-Password-Change-Required.yml
deleted file mode 100644
index 44cfd41430..0000000000
--- a/changelogs/fragments/8652-Redfish-Password-Change-Required.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - redfish_command - add handling of the ``PasswordChangeRequired`` message from services in the ``UpdateUserPassword`` command to directly modify the user's password if the requested user is the one invoking the operation (https://github.com/ansible-collections/community.general/issues/8652, https://github.com/ansible-collections/community.general/pull/8653).
diff --git a/changelogs/fragments/8654-add-redis-tls-params.yml b/changelogs/fragments/8654-add-redis-tls-params.yml
deleted file mode 100644
index 0b549f5dd0..0000000000
--- a/changelogs/fragments/8654-add-redis-tls-params.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - redis, redis_info - add ``client_cert`` and ``client_key`` options to specify path to certificate for Redis authentication (https://github.com/ansible-collections/community.general/pull/8654).
diff --git a/changelogs/fragments/8674-add-gitlab-project-cleanup-policy.yml b/changelogs/fragments/8674-add-gitlab-project-cleanup-policy.yml
deleted file mode 100644
index f67e11a6b0..0000000000
--- a/changelogs/fragments/8674-add-gitlab-project-cleanup-policy.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-minor_changes:
- - gitlab_project - add option ``repository_access_level`` to disable project repository (https://github.com/ansible-collections/community.general/pull/8674).
- - gitlab_project - add option ``container_expiration_policy`` to schedule container registry cleanup (https://github.com/ansible-collections/community.general/pull/8674).
diff --git a/changelogs/fragments/8675-pipx-install-suffix.yml b/changelogs/fragments/8675-pipx-install-suffix.yml
deleted file mode 100644
index 4b5a9a99bc..0000000000
--- a/changelogs/fragments/8675-pipx-install-suffix.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - pipx - add parameter ``suffix`` to module (https://github.com/ansible-collections/community.general/pull/8675, https://github.com/ansible-collections/community.general/issues/8656).
diff --git a/changelogs/fragments/8679-fix-cloudflare-srv.yml b/changelogs/fragments/8679-fix-cloudflare-srv.yml
deleted file mode 100644
index bf00fc1305..0000000000
--- a/changelogs/fragments/8679-fix-cloudflare-srv.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - cloudflare_dns - fix changing Cloudflare SRV records (https://github.com/ansible-collections/community.general/issues/8679, https://github.com/ansible-collections/community.general/pull/8948).
diff --git a/changelogs/fragments/8682-locale-gen-multiple.yaml b/changelogs/fragments/8682-locale-gen-multiple.yaml
deleted file mode 100644
index 139f372353..0000000000
--- a/changelogs/fragments/8682-locale-gen-multiple.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - locale_gen - add support for multiple locales (https://github.com/ansible-collections/community.general/issues/8677, https://github.com/ansible-collections/community.general/pull/8682).
diff --git a/changelogs/fragments/8688-gitlab_project-add-new-params.yml b/changelogs/fragments/8688-gitlab_project-add-new-params.yml
deleted file mode 100644
index 0c6b8e505a..0000000000
--- a/changelogs/fragments/8688-gitlab_project-add-new-params.yml
+++ /dev/null
@@ -1,4 +0,0 @@
-minor_changes:
- - gitlab_project - add option ``pages_access_level`` to disable project pages (https://github.com/ansible-collections/community.general/pull/8688).
- - gitlab_project - add option ``service_desk_enabled`` to disable service desk (https://github.com/ansible-collections/community.general/pull/8688).
- - gitlab_project - add option ``model_registry_access_level`` to disable model registry (https://github.com/ansible-collections/community.general/pull/8688).
diff --git a/changelogs/fragments/8689-passwordstore-lock-naming.yml b/changelogs/fragments/8689-passwordstore-lock-naming.yml
deleted file mode 100644
index c5c9a82d78..0000000000
--- a/changelogs/fragments/8689-passwordstore-lock-naming.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - passwordstore lookup plugin - add the current user to the lockfile file name to address issues on multi-user systems (https://github.com/ansible-collections/community.general/pull/8689).
diff --git a/changelogs/fragments/8695-keycloak_user_federation-mapper-removal.yml b/changelogs/fragments/8695-keycloak_user_federation-mapper-removal.yml
deleted file mode 100644
index b518d59e36..0000000000
--- a/changelogs/fragments/8695-keycloak_user_federation-mapper-removal.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_user_federation - remove existing user federation mappers if they are not present in the federation configuration and will not be updated (https://github.com/ansible-collections/community.general/issues/7169, https://github.com/ansible-collections/community.general/pull/8695).
\ No newline at end of file
diff --git a/changelogs/fragments/8708-homebrew_cask-fix-upgrade-all.yml b/changelogs/fragments/8708-homebrew_cask-fix-upgrade-all.yml
deleted file mode 100644
index 6a0cd74302..0000000000
--- a/changelogs/fragments/8708-homebrew_cask-fix-upgrade-all.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - homebrew_cask - fix ``upgrade_all`` returns ``changed`` when nothing upgraded (https://github.com/ansible-collections/community.general/issues/8707, https://github.com/ansible-collections/community.general/pull/8708).
\ No newline at end of file
diff --git a/changelogs/fragments/8711-gconftool2-refactor.yml b/changelogs/fragments/8711-gconftool2-refactor.yml
deleted file mode 100644
index ae214d95ec..0000000000
--- a/changelogs/fragments/8711-gconftool2-refactor.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - gconftool2 - make use of ``ModuleHelper`` features to simplify code (https://github.com/ansible-collections/community.general/pull/8711).
diff --git a/changelogs/fragments/8713-proxmox_lxc_interfaces.yml b/changelogs/fragments/8713-proxmox_lxc_interfaces.yml
deleted file mode 100644
index 32c475157e..0000000000
--- a/changelogs/fragments/8713-proxmox_lxc_interfaces.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - proxmox inventory plugin - add new fact for LXC interface details (https://github.com/ansible-collections/community.general/pull/8713).
\ No newline at end of file
diff --git a/changelogs/fragments/8719-openiscsi-add-multiple-targets.yaml b/changelogs/fragments/8719-openiscsi-add-multiple-targets.yaml
deleted file mode 100644
index 16e523d83d..0000000000
--- a/changelogs/fragments/8719-openiscsi-add-multiple-targets.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - open_iscsi - allow login to a portal with multiple targets without specifying any of them (https://github.com/ansible-collections/community.general/pull/8719).
diff --git a/changelogs/fragments/8735-keycloak_identity_provider-get-cleartext-secret-from-realm-info.yml b/changelogs/fragments/8735-keycloak_identity_provider-get-cleartext-secret-from-realm-info.yml
deleted file mode 100644
index ed3806bd5f..0000000000
--- a/changelogs/fragments/8735-keycloak_identity_provider-get-cleartext-secret-from-realm-info.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_user_federation - get cleartext IDP ``clientSecret`` from full realm info to detect changes to it (https://github.com/ansible-collections/community.general/issues/8294, https://github.com/ansible-collections/community.general/pull/8735).
\ No newline at end of file
diff --git a/changelogs/fragments/8738-limit-packages-for-copr.yml b/changelogs/fragments/8738-limit-packages-for-copr.yml
deleted file mode 100644
index 0e49cc5cd9..0000000000
--- a/changelogs/fragments/8738-limit-packages-for-copr.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - copr - Added ``includepkgs`` and ``excludepkgs`` parameters to limit the list of packages fetched or excluded from the repository(https://github.com/ansible-collections/community.general/pull/8779).
\ No newline at end of file
diff --git a/changelogs/fragments/8741-fix-opentelemetry-callback.yml b/changelogs/fragments/8741-fix-opentelemetry-callback.yml
deleted file mode 100644
index 1b5e63a89f..0000000000
--- a/changelogs/fragments/8741-fix-opentelemetry-callback.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - opentelemetry callback plugin - fix default value for ``store_spans_in_file`` causing traces to be produced to a file named ``None`` (https://github.com/ansible-collections/community.general/issues/8566, https://github.com/ansible-collections/community.general/pull/8741).
diff --git a/changelogs/fragments/8759-gitlab_project-sort-params.yml b/changelogs/fragments/8759-gitlab_project-sort-params.yml
deleted file mode 100644
index 2ff2ed18a7..0000000000
--- a/changelogs/fragments/8759-gitlab_project-sort-params.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - gitlab_project - sorted parameters in order to avoid future merge conflicts (https://github.com/ansible-collections/community.general/pull/8759).
diff --git a/changelogs/fragments/8760-gitlab_project-add-issues-access-level.yml b/changelogs/fragments/8760-gitlab_project-add-issues-access-level.yml
deleted file mode 100644
index 1a77b2f0d4..0000000000
--- a/changelogs/fragments/8760-gitlab_project-add-issues-access-level.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - gitlab_project - add option ``issues_access_level`` to enable/disable project issues (https://github.com/ansible-collections/community.general/pull/8760).
diff --git a/changelogs/fragments/8761-keycloak_user_federation-sort-desired-and-after-mappers-by-name.yml b/changelogs/fragments/8761-keycloak_user_federation-sort-desired-and-after-mappers-by-name.yml
deleted file mode 100644
index 2d7d39345f..0000000000
--- a/changelogs/fragments/8761-keycloak_user_federation-sort-desired-and-after-mappers-by-name.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_user_federation - sort desired and after mapper list by name (analog to before mapper list) to minimize diff and make change detection more accurate (https://github.com/ansible-collections/community.general/pull/8761).
\ No newline at end of file
diff --git a/changelogs/fragments/8762-keycloac_user_federation-fix-key-error-when-updating.yml b/changelogs/fragments/8762-keycloac_user_federation-fix-key-error-when-updating.yml
deleted file mode 100644
index 08da8ae21a..0000000000
--- a/changelogs/fragments/8762-keycloac_user_federation-fix-key-error-when-updating.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_user_federation - fix key error when removing mappers during an update and new mappers are specified in the module args (https://github.com/ansible-collections/community.general/pull/8762).
\ No newline at end of file
diff --git a/changelogs/fragments/8764-keycloak_user_federation-make-mapper-removal-optout.yml b/changelogs/fragments/8764-keycloak_user_federation-make-mapper-removal-optout.yml
deleted file mode 100644
index c457012751..0000000000
--- a/changelogs/fragments/8764-keycloak_user_federation-make-mapper-removal-optout.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - keycloak_user_federation - add module argument allowing users to optout of the removal of unspecified mappers, for example to keep the keycloak default mappers (https://github.com/ansible-collections/community.general/pull/8764).
\ No newline at end of file
diff --git a/changelogs/fragments/8766-mh-deco-improve.yml b/changelogs/fragments/8766-mh-deco-improve.yml
deleted file mode 100644
index 7bf104d2cc..0000000000
--- a/changelogs/fragments/8766-mh-deco-improve.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-minor_changes:
- - MH module utils - add parameter ``when`` to ``cause_changes`` decorator (https://github.com/ansible-collections/community.general/pull/8766).
- - MH module utils - minor refactor in decorators (https://github.com/ansible-collections/community.general/pull/8766).
diff --git a/changelogs/fragments/8776-mute-vardict-deprecation.yml b/changelogs/fragments/8776-mute-vardict-deprecation.yml
deleted file mode 100644
index a74e40e923..0000000000
--- a/changelogs/fragments/8776-mute-vardict-deprecation.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-minor_changes:
- - jira - mute the old ``VarDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8776).
- - gio_mime - mute the old ``VarDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8776).
diff --git a/changelogs/fragments/8785-keycloak_user_federation-set-krbPrincipalAttribute-to-empty-string-if-missing.yaml b/changelogs/fragments/8785-keycloak_user_federation-set-krbPrincipalAttribute-to-empty-string-if-missing.yaml
deleted file mode 100644
index c8a6ff752a..0000000000
--- a/changelogs/fragments/8785-keycloak_user_federation-set-krbPrincipalAttribute-to-empty-string-if-missing.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_user_federation - minimize change detection by setting ``krbPrincipalAttribute`` to ``''`` in Keycloak responses if missing (https://github.com/ansible-collections/community.general/pull/8785).
\ No newline at end of file
diff --git a/changelogs/fragments/8790-gitlab_project-fix-cleanup-policy-on-project-create.yml b/changelogs/fragments/8790-gitlab_project-fix-cleanup-policy-on-project-create.yml
deleted file mode 100644
index ba171a1178..0000000000
--- a/changelogs/fragments/8790-gitlab_project-fix-cleanup-policy-on-project-create.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-bugfixes:
- - gitlab_project - fix crash caused by old Gitlab projects not having a ``container_expiration_policy`` attribute (https://github.com/ansible-collections/community.general/pull/8790).
- - gitlab_project - fix ``container_expiration_policy`` not being applied when creating a new project (https://github.com/ansible-collections/community.general/pull/8790).
diff --git a/changelogs/fragments/8791-mh-cause-changes-param-depr.yml b/changelogs/fragments/8791-mh-cause-changes-param-depr.yml
deleted file mode 100644
index 7f7935af14..0000000000
--- a/changelogs/fragments/8791-mh-cause-changes-param-depr.yml
+++ /dev/null
@@ -1,4 +0,0 @@
-minor_changes:
- - jira - replace deprecated params when using decorator ``cause_changes`` (https://github.com/ansible-collections/community.general/pull/8791).
-deprecated_features:
- - MH decorator cause_changes module utils - deprecate parameters ``on_success`` and ``on_failure`` (https://github.com/ansible-collections/community.general/pull/8791).
diff --git a/changelogs/fragments/8793-pipx-global.yml b/changelogs/fragments/8793-pipx-global.yml
deleted file mode 100644
index c3d7f5157f..0000000000
--- a/changelogs/fragments/8793-pipx-global.yml
+++ /dev/null
@@ -1,12 +0,0 @@
-minor_changes:
- - pipx - added parameter ``global`` to module (https://github.com/ansible-collections/community.general/pull/8793).
- - pipx_info - added parameter ``global`` to module (https://github.com/ansible-collections/community.general/pull/8793).
-deprecated_features:
- - >
- pipx -
- support for versions of the command line tool ``pipx`` older than ``1.7.0`` is deprecated and will be removed in community.general 11.0.0
- (https://github.com/ansible-collections/community.general/pull/8793).
- - >
- pipx_info -
- support for versions of the command line tool ``pipx`` older than ``1.7.0`` is deprecated and will be removed in community.general 11.0.0
- (https://github.com/ansible-collections/community.general/pull/8793).
diff --git a/changelogs/fragments/8794-Fixing-possible-concatination-error.yaml b/changelogs/fragments/8794-Fixing-possible-concatination-error.yaml
deleted file mode 100644
index a94eace415..0000000000
--- a/changelogs/fragments/8794-Fixing-possible-concatination-error.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - proxmox inventory plugin - fixed a possible error on concatenating responses from proxmox. In case an API call unexpectedly returned an empty result, the inventory failed with a fatal error. Added check for empty response (https://github.com/ansible-collections/community.general/issues/8798, https://github.com/ansible-collections/community.general/pull/8794).
diff --git a/changelogs/fragments/8796-gitlab-access-token-check-mode.yml b/changelogs/fragments/8796-gitlab-access-token-check-mode.yml
deleted file mode 100644
index 6585584fac..0000000000
--- a/changelogs/fragments/8796-gitlab-access-token-check-mode.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-bugfixes:
- - gitlab_group_access_token - fix crash in check mode caused by attempted access to a newly created access token (https://github.com/ansible-collections/community.general/pull/8796).
- - gitlab_project_access_token - fix crash in check mode caused by attempted access to a newly created access token (https://github.com/ansible-collections/community.general/pull/8796).
diff --git a/changelogs/fragments/8809-pipx-new-params.yml b/changelogs/fragments/8809-pipx-new-params.yml
deleted file mode 100644
index 775163e987..0000000000
--- a/changelogs/fragments/8809-pipx-new-params.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - pipx - added new states ``install_all``, ``uninject``, ``upgrade_shared``, ``pin``, and ``unpin`` (https://github.com/ansible-collections/community.general/pull/8809).
diff --git a/changelogs/fragments/8812-keycloak-user-federation-remove-lastSync-param-from-kc-responses.yml b/changelogs/fragments/8812-keycloak-user-federation-remove-lastSync-param-from-kc-responses.yml
deleted file mode 100644
index 82496d1083..0000000000
--- a/changelogs/fragments/8812-keycloak-user-federation-remove-lastSync-param-from-kc-responses.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_user_federation - remove ``lastSync`` parameter from Keycloak responses to minimize diff/changes (https://github.com/ansible-collections/community.general/pull/8812).
\ No newline at end of file
diff --git a/changelogs/fragments/8814-dict-comprehension.yml b/changelogs/fragments/8814-dict-comprehension.yml
deleted file mode 100644
index 01b5da4bae..0000000000
--- a/changelogs/fragments/8814-dict-comprehension.yml
+++ /dev/null
@@ -1,23 +0,0 @@
-minor_changes:
- - hashids filter plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - keep_keys filter plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - remove_keys filter plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - replace_keys filter plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - csv module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - vars MH module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - vardict module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - apache2_mod_proxy - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - gitlab_group - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - keycloak_client - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - keycloak_clientscope - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - keycloak_identity_provider - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - keycloak_user_federation - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - linode - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - lxd_container - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - manageiq_provider - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - one_service - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - one_vm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - proxmox - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - proxmox_disk - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - proxmox_kvm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
- - unsafe plugin utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8814).
diff --git a/changelogs/fragments/8822-dict-comprehension.yml b/changelogs/fragments/8822-dict-comprehension.yml
deleted file mode 100644
index cefb673bb8..0000000000
--- a/changelogs/fragments/8822-dict-comprehension.yml
+++ /dev/null
@@ -1,21 +0,0 @@
-minor_changes:
- - credstash lookup plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - keycloak module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - deco MH module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - redfish_utils module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - scaleway module utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - etcd3 - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - gitlab_project - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - hwc_ecs_instance - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - hwc_evs_disk - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - hwc_vpc_eip - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - hwc_vpc_peering_connect - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - hwc_vpc_port - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - hwc_vpc_subnet - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - ipa_otptoken - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - keycloak_user_federation - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - lxc_container - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - proxmox_kvm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - scaleway_security_group - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - ufw - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
- - vmadm - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8822).
diff --git a/changelogs/fragments/8823-keycloak-realm-key.yml b/changelogs/fragments/8823-keycloak-realm-key.yml
deleted file mode 100644
index 4c0e591f8e..0000000000
--- a/changelogs/fragments/8823-keycloak-realm-key.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_realm_key - fix invalid usage of ``parent_id`` (https://github.com/ansible-collections/community.general/issues/7850, https://github.com/ansible-collections/community.general/pull/8823).
\ No newline at end of file
diff --git a/changelogs/fragments/8831-fix-error-when-mapper-id-is-provided.yml b/changelogs/fragments/8831-fix-error-when-mapper-id-is-provided.yml
deleted file mode 100644
index 63ac352057..0000000000
--- a/changelogs/fragments/8831-fix-error-when-mapper-id-is-provided.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_user_federation - fix the ``UnboundLocalError`` that occurs when an ID is provided for a user federation mapper (https://github.com/ansible-collections/community.general/pull/8831).
\ No newline at end of file
diff --git a/changelogs/fragments/8833-dict-comprehension.yml b/changelogs/fragments/8833-dict-comprehension.yml
deleted file mode 100644
index 1515609e69..0000000000
--- a/changelogs/fragments/8833-dict-comprehension.yml
+++ /dev/null
@@ -1,23 +0,0 @@
-minor_changes:
- - redis cache plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - onepassword lookup plugin - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - ocapi_utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - redfish_utils - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - scaleway - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - alternatives - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - apache2_mod_proxy - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - consul_acl - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - imc_rest - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - keycloak_user_federation - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - pids - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - pipx - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - pipx_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - pkg5_publisher - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - scaleway_compute - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - scaleway_ip - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - scaleway_lb - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - scaleway_security_group - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - scaleway_user_data - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - sensu_silence - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - snmp_facts - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
- - sorcery - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8833).
diff --git a/changelogs/fragments/8855-gio_mime_vardict.yml b/changelogs/fragments/8855-gio_mime_vardict.yml
deleted file mode 100644
index 54efa08579..0000000000
--- a/changelogs/fragments/8855-gio_mime_vardict.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - gio_mime - adjust code ahead of the old ``VardDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8855).
diff --git a/changelogs/fragments/8856-jira_vardict.yml b/changelogs/fragments/8856-jira_vardict.yml
deleted file mode 100644
index c4d8357419..0000000000
--- a/changelogs/fragments/8856-jira_vardict.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - jira - adjust code ahead of the old ``VardDict`` deprecation (https://github.com/ansible-collections/community.general/pull/8856).
diff --git a/changelogs/fragments/8858-dict-comprehension.yml b/changelogs/fragments/8858-dict-comprehension.yml
deleted file mode 100644
index 47b4acb329..0000000000
--- a/changelogs/fragments/8858-dict-comprehension.yml
+++ /dev/null
@@ -1,11 +0,0 @@
-minor_changes:
- - scaleway_container - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
- - scaleway_container_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
- - scaleway_container_namespace - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
- - scaleway_container_namespace_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
- - scaleway_container_registry - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
- - scaleway_container_registry_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
- - scaleway_function - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
- - scaleway_function_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
- - scaleway_function_namespace - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
- - scaleway_function_namespace_info - replace Python 2.6 construct with dict comprehensions (https://github.com/ansible-collections/community.general/pull/8858).
diff --git a/changelogs/fragments/8876-dict-items-loop.yml b/changelogs/fragments/8876-dict-items-loop.yml
deleted file mode 100644
index 6bd170c7b2..0000000000
--- a/changelogs/fragments/8876-dict-items-loop.yml
+++ /dev/null
@@ -1,16 +0,0 @@
-minor_changes:
- - gitlab_deploy_key - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - gitlab_group - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - gitlab_issue - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - gitlab_merge_request - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - gitlab_runner - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - icinga2_host - replace loop with dict comprehension (https://github.com/ansible-collections/community.general/pull/8876).
- - memset_dns_reload - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - memset_memstore_info - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - memset_server_info - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - memset_zone - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - memset_zone_domain - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - memset_zone_record - replace loop with ``dict()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - nmcli - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - scaleway_user_data - better construct when using ``dict.items()`` (https://github.com/ansible-collections/community.general/pull/8876).
- - udm_dns_record - replace loop with ``dict.update()`` (https://github.com/ansible-collections/community.general/pull/8876).
diff --git a/changelogs/fragments/8877-keycloak_realm-sort-lists-before-change-detection.yaml b/changelogs/fragments/8877-keycloak_realm-sort-lists-before-change-detection.yaml
deleted file mode 100644
index 3e19866289..0000000000
--- a/changelogs/fragments/8877-keycloak_realm-sort-lists-before-change-detection.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_realm - fix change detection in check mode by sorting the lists in the realms beforehand (https://github.com/ansible-collections/community.general/pull/8877).
\ No newline at end of file
diff --git a/changelogs/fragments/8885-add-force-flag-for-nmp.yml b/changelogs/fragments/8885-add-force-flag-for-nmp.yml
deleted file mode 100644
index 40eaeff74b..0000000000
--- a/changelogs/fragments/8885-add-force-flag-for-nmp.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - npm - add ``force`` parameter to allow ``--force`` (https://github.com/ansible-collections/community.general/pull/8885).
diff --git a/changelogs/fragments/8887-fix-one_service-unique.yml b/changelogs/fragments/8887-fix-one_service-unique.yml
deleted file mode 100644
index 979460b862..0000000000
--- a/changelogs/fragments/8887-fix-one_service-unique.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - one_service - fix service creation after it was deleted with ``unique`` parameter (https://github.com/ansible-collections/community.general/issues/3137, https://github.com/ansible-collections/community.general/pull/8887).
diff --git a/changelogs/fragments/8889-refactor-one-image-modules.yml b/changelogs/fragments/8889-refactor-one-image-modules.yml
deleted file mode 100644
index de552c17a6..0000000000
--- a/changelogs/fragments/8889-refactor-one-image-modules.yml
+++ /dev/null
@@ -1,6 +0,0 @@
-minor_changes:
- - one_image - add option ``persistent`` to manage image persistence (https://github.com/ansible-collections/community.general/issues/3578, https://github.com/ansible-collections/community.general/pull/8889).
- - one_image - refactor code to make it more similar to ``one_template`` and ``one_vnet`` (https://github.com/ansible-collections/community.general/pull/8889).
- - one_image_info - refactor code to make it more similar to ``one_template`` and ``one_vnet`` (https://github.com/ansible-collections/community.general/pull/8889).
- - one_image - extend xsd scheme to make it return a lot more info about image (https://github.com/ansible-collections/community.general/pull/8889).
- - one_image_info - extend xsd scheme to make it return a lot more info about image (https://github.com/ansible-collections/community.general/pull/8889).
diff --git a/changelogs/fragments/8895-fix-comprehension.yaml b/changelogs/fragments/8895-fix-comprehension.yaml
deleted file mode 100644
index aecd0fd83e..0000000000
--- a/changelogs/fragments/8895-fix-comprehension.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - lxd_container - fix bug introduced in previous commit (https://github.com/ansible-collections/community.general/pull/8895, https://github.com/ansible-collections/community.general/issues/8888).
diff --git a/changelogs/fragments/8897-nmcli-add-reload-and-up-down.yml b/changelogs/fragments/8897-nmcli-add-reload-and-up-down.yml
deleted file mode 100644
index 68f481452c..0000000000
--- a/changelogs/fragments/8897-nmcli-add-reload-and-up-down.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-minor_changes:
- - nmcli - add ``conn_enable`` param to reload connection (https://github.com/ansible-collections/community.general/issues/3752, https://github.com/ansible-collections/community.general/issues/8704, https://github.com/ansible-collections/community.general/pull/8897).
- - nmcli - add ``state=up`` and ``state=down`` to enable/disable connections (https://github.com/ansible-collections/community.general/issues/3752, https://github.com/ansible-collections/community.general/issues/8704, https://github.com/ansible-collections/community.general/issues/7152, https://github.com/ansible-collections/community.general/pull/8897).
diff --git a/changelogs/fragments/8898-add-arg-to-exclude-bind-credential-from-change-check.yaml b/changelogs/fragments/8898-add-arg-to-exclude-bind-credential-from-change-check.yaml
deleted file mode 100644
index 8f86d510f9..0000000000
--- a/changelogs/fragments/8898-add-arg-to-exclude-bind-credential-from-change-check.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_user_federation - add module argument allowing users to configure the update mode for the parameter ``bindCredential`` (https://github.com/ansible-collections/community.general/pull/8898).
\ No newline at end of file
diff --git a/changelogs/fragments/8900-ipa-hostgroup-fix-states.yml b/changelogs/fragments/8900-ipa-hostgroup-fix-states.yml
deleted file mode 100644
index c7347e879f..0000000000
--- a/changelogs/fragments/8900-ipa-hostgroup-fix-states.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - ipa_hostgroup - fix ``enabled `` and ``disabled`` states (https://github.com/ansible-collections/community.general/issues/8408, https://github.com/ansible-collections/community.general/pull/8900).
diff --git a/changelogs/fragments/8907-fix-one-host-id.yml b/changelogs/fragments/8907-fix-one-host-id.yml
deleted file mode 100644
index 78fc4080b1..0000000000
--- a/changelogs/fragments/8907-fix-one-host-id.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - one_host - fix if statements for cases when ``ID=0`` (https://github.com/ansible-collections/community.general/issues/1199, https://github.com/ansible-collections/community.general/pull/8907).
diff --git a/changelogs/fragments/8908-add-gitlab-group-params.yml b/changelogs/fragments/8908-add-gitlab-group-params.yml
deleted file mode 100644
index 12de77b43a..0000000000
--- a/changelogs/fragments/8908-add-gitlab-group-params.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - gitlab_group - add many new parameters (https://github.com/ansible-collections/community.general/pull/8908).
diff --git a/changelogs/fragments/8909-flatpak-improve-name-parsing.yaml b/changelogs/fragments/8909-flatpak-improve-name-parsing.yaml
deleted file mode 100644
index 26a9379235..0000000000
--- a/changelogs/fragments/8909-flatpak-improve-name-parsing.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - flatpak - improve the parsing of Flatpak application IDs based on official guidelines (https://github.com/ansible-collections/community.general/pull/8909).
diff --git a/changelogs/fragments/8917-proxmox-clean-auth.yml b/changelogs/fragments/8917-proxmox-clean-auth.yml
deleted file mode 100644
index 0681f326a6..0000000000
--- a/changelogs/fragments/8917-proxmox-clean-auth.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - proxmox inventory plugin - clean up authentication code (https://github.com/ansible-collections/community.general/pull/8917).
diff --git a/changelogs/fragments/8920-ipa-host-fix-state.yml b/changelogs/fragments/8920-ipa-host-fix-state.yml
deleted file mode 100644
index 0f3df64b6a..0000000000
--- a/changelogs/fragments/8920-ipa-host-fix-state.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - ipa_host - add ``force_create``, fix ``enabled`` and ``disabled`` states (https://github.com/ansible-collections/community.general/issues/1094, https://github.com/ansible-collections/community.general/pull/8920).
diff --git a/changelogs/fragments/8923-keycloak_userprofile-fix-empty-response-when-fetching-userprofile.yml b/changelogs/fragments/8923-keycloak_userprofile-fix-empty-response-when-fetching-userprofile.yml
deleted file mode 100644
index 5b3c18ba2c..0000000000
--- a/changelogs/fragments/8923-keycloak_userprofile-fix-empty-response-when-fetching-userprofile.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_userprofile - fix empty response when fetching userprofile component by removing ``parent=parent_id`` filter (https://github.com/ansible-collections/community.general/pull/8923).
\ No newline at end of file
diff --git a/changelogs/fragments/8925-atomic.yml b/changelogs/fragments/8925-atomic.yml
deleted file mode 100644
index 75e48a1dba..0000000000
--- a/changelogs/fragments/8925-atomic.yml
+++ /dev/null
@@ -1,6 +0,0 @@
-bugfixes:
- - "ini_file - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925)."
- - "java_keystore - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925)."
- - "jenkins_plugin - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925)."
- - "kdeconfig - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925)."
- - "pam_limits - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.general/pull/8925)."
diff --git a/changelogs/fragments/8928-cmd-runner-10.0.0.yml b/changelogs/fragments/8928-cmd-runner-10.0.0.yml
deleted file mode 100644
index bbeb838439..0000000000
--- a/changelogs/fragments/8928-cmd-runner-10.0.0.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-breaking_changes:
- - cmd_runner module utils - CLI arguments created directly from module parameters are no longer assigned a default formatter (https://github.com/ansible-collections/community.general/pull/8928).
diff --git a/changelogs/fragments/8929-cmd_runner-bugfix.yml b/changelogs/fragments/8929-cmd_runner-bugfix.yml
deleted file mode 100644
index 2d8e0170f6..0000000000
--- a/changelogs/fragments/8929-cmd_runner-bugfix.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - cmd_runner module utils - call to ``get_best_parsable_locales()`` was missing parameter (https://github.com/ansible-collections/community.general/pull/8929).
diff --git a/changelogs/fragments/8937-add-StorageId-RedfishURI-to-disk-facts.yml b/changelogs/fragments/8937-add-StorageId-RedfishURI-to-disk-facts.yml
deleted file mode 100644
index 6b66918234..0000000000
--- a/changelogs/fragments/8937-add-StorageId-RedfishURI-to-disk-facts.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - redfish_info - adds ``RedfishURI`` and ``StorageId`` to Disk inventory (https://github.com/ansible-collections/community.general/pull/8937).
\ No newline at end of file
diff --git a/changelogs/fragments/8940-keycloak_userprofile-improve-diff.yml b/changelogs/fragments/8940-keycloak_userprofile-improve-diff.yml
deleted file mode 100644
index 93f57cd86a..0000000000
--- a/changelogs/fragments/8940-keycloak_userprofile-improve-diff.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_userprofile - improve diff by deserializing the fetched ``kc.user.profile.config`` and serialize it only when sending back (https://github.com/ansible-collections/community.general/pull/8940).
\ No newline at end of file
diff --git a/changelogs/fragments/8944-django-command-fix.yml b/changelogs/fragments/8944-django-command-fix.yml
deleted file mode 100644
index 755bf5628a..0000000000
--- a/changelogs/fragments/8944-django-command-fix.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-bugfixes:
- - python_runner module utils - parameter ``path_prefix`` was being handled as string when it should be a list (https://github.com/ansible-collections/community.general/pull/8944).
- - django_command - option ``command`` is now split lexically before passed to underlying PythonRunner (https://github.com/ansible-collections/community.general/pull/8944).
diff --git a/changelogs/fragments/8952-password-store-lookup-create-subkey-support.yml b/changelogs/fragments/8952-password-store-lookup-create-subkey-support.yml
deleted file mode 100644
index 73bf1710e7..0000000000
--- a/changelogs/fragments/8952-password-store-lookup-create-subkey-support.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - passwordstore lookup plugin - add subkey creation/update support (https://github.com/ansible-collections/community.general/pull/8952).
\ No newline at end of file
diff --git a/changelogs/fragments/8954-keycloak-user-federation-add-referral-parameter.yml b/changelogs/fragments/8954-keycloak-user-federation-add-referral-parameter.yml
deleted file mode 100644
index cd8347faf0..0000000000
--- a/changelogs/fragments/8954-keycloak-user-federation-add-referral-parameter.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - keycloak_user_federation - add the user federation config parameter ``referral`` to the module arguments (https://github.com/ansible-collections/community.general/pull/8954).
\ No newline at end of file
diff --git a/changelogs/fragments/8956-remove-capacitybytes-from-the-required-parameters_list.yml b/changelogs/fragments/8956-remove-capacitybytes-from-the-required-parameters_list.yml
deleted file mode 100644
index d6879ccb06..0000000000
--- a/changelogs/fragments/8956-remove-capacitybytes-from-the-required-parameters_list.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - redfish_confg - remove ``CapacityBytes`` from required paramaters of the ``CreateVolume`` command (https://github.com/ansible-collections/community.general/pull/8956).
diff --git a/changelogs/fragments/8964-cmd-runner-argformat-refactor.yml b/changelogs/fragments/8964-cmd-runner-argformat-refactor.yml
deleted file mode 100644
index be8adf25e3..0000000000
--- a/changelogs/fragments/8964-cmd-runner-argformat-refactor.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - cmd_runner module utils - refactor argument formatting code to its own Python module (https://github.com/ansible-collections/community.general/pull/8964).
diff --git a/changelogs/fragments/8966-dig-add-port-option.yml b/changelogs/fragments/8966-dig-add-port-option.yml
deleted file mode 100644
index e92f355dd5..0000000000
--- a/changelogs/fragments/8966-dig-add-port-option.yml
+++ /dev/null
@@ -1,4 +0,0 @@
----
-minor_changes:
- - dig lookup plugin - add ``port`` option to specify DNS server port (https://github.com/ansible-collections/community.general/pull/8966).
-...
diff --git a/changelogs/fragments/8970-fix-dig-multi-nameservers.yml b/changelogs/fragments/8970-fix-dig-multi-nameservers.yml
deleted file mode 100644
index e7f93853e9..0000000000
--- a/changelogs/fragments/8970-fix-dig-multi-nameservers.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - dig lookup plugin - fix using only the last nameserver specified (https://github.com/ansible-collections/community.general/pull/8970).
\ No newline at end of file
diff --git a/changelogs/fragments/8973-keycloak_client-add-x509-auth.yml b/changelogs/fragments/8973-keycloak_client-add-x509-auth.yml
deleted file mode 100644
index a7bc125f82..0000000000
--- a/changelogs/fragments/8973-keycloak_client-add-x509-auth.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - keycloak_client - add ``client-x509`` choice to ``client_authenticator_type`` (https://github.com/ansible-collections/community.general/pull/8973).
diff --git a/changelogs/fragments/8979-keycloak_group-fix-subgroups.yml b/changelogs/fragments/8979-keycloak_group-fix-subgroups.yml
deleted file mode 100644
index c64a09add6..0000000000
--- a/changelogs/fragments/8979-keycloak_group-fix-subgroups.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_group - fix crash caused in subgroup creation. The crash was caused by a missing or empty ``subGroups`` property in Keycloak ≥23 (https://github.com/ansible-collections/community.general/issues/8788, https://github.com/ansible-collections/community.general/pull/8979).
diff --git a/changelogs/fragments/8987-legacycrypt.yml b/changelogs/fragments/8987-legacycrypt.yml
deleted file mode 100644
index ce955f3564..0000000000
--- a/changelogs/fragments/8987-legacycrypt.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-bugfixes:
- - "homectl - the module now tries to use ``legacycrypt`` on Python 3.13+ (https://github.com/ansible-collections/community.general/issues/4691, https://github.com/ansible-collections/community.general/pull/8987)."
- - "udm_user - the module now tries to use ``legacycrypt`` on Python 3.13+ (https://github.com/ansible-collections/community.general/issues/4690, https://github.com/ansible-collections/community.general/pull/8987)."
diff --git a/changelogs/fragments/8989-github-app-token-from-fact.yml b/changelogs/fragments/8989-github-app-token-from-fact.yml
deleted file mode 100644
index 6b36d95a62..0000000000
--- a/changelogs/fragments/8989-github-app-token-from-fact.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - github_app_access_token lookup plugin - adds new ``private_key`` parameter (https://github.com/ansible-collections/community.general/pull/8989).
diff --git a/changelogs/fragments/8990.yml b/changelogs/fragments/8990.yml
deleted file mode 100644
index 716fd3c983..0000000000
--- a/changelogs/fragments/8990.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-minor_changes:
- - redfish_config - add parameter ``storage_none_volume_deletion`` to
- ``CreateVolume`` command in order to control the automatic deletion of non-RAID volumes (https://github.com/ansible-collections/community.general/pull/8990).
\ No newline at end of file
diff --git a/changelogs/fragments/9010-edit-gitlab-label-color.yaml b/changelogs/fragments/9010-edit-gitlab-label-color.yaml
deleted file mode 100644
index 0959e57772..0000000000
--- a/changelogs/fragments/9010-edit-gitlab-label-color.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - gitlab_label - update label's color (https://github.com/ansible-collections/community.general/pull/9010).
diff --git a/changelogs/fragments/9012-dell-pwrbutton-requires-a-job-initiated-at-reboot.yml b/changelogs/fragments/9012-dell-pwrbutton-requires-a-job-initiated-at-reboot.yml
deleted file mode 100644
index 131ee68c7c..0000000000
--- a/changelogs/fragments/9012-dell-pwrbutton-requires-a-job-initiated-at-reboot.yml
+++ /dev/null
@@ -1,4 +0,0 @@
-minor_changes:
- - redfish_utils module utils - schedule a BIOS configuration job at next
- reboot when the BIOS config is changed
- (https://github.com/ansible-collections/community.general/pull/9012).
diff --git a/changelogs/fragments/9019-onevnet-bugfix.yml b/changelogs/fragments/9019-onevnet-bugfix.yml
deleted file mode 100644
index 3da3ea0399..0000000000
--- a/changelogs/fragments/9019-onevnet-bugfix.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - one_vnet - fix module failing due to a variable typo (https://github.com/ansible-collections/community.general/pull/9019).
diff --git a/changelogs/fragments/9022-improve-homebrew-perf.yml b/changelogs/fragments/9022-improve-homebrew-perf.yml
deleted file mode 100644
index 077b5caefc..0000000000
--- a/changelogs/fragments/9022-improve-homebrew-perf.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - homebrew - speed up brew install and upgrade (https://github.com/ansible-collections/community.general/pull/9022).
diff --git a/changelogs/fragments/9026-consul_kv-datacenter.yml b/changelogs/fragments/9026-consul_kv-datacenter.yml
deleted file mode 100644
index 73ddd69266..0000000000
--- a/changelogs/fragments/9026-consul_kv-datacenter.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - consul_kv - add argument for the datacenter option on Consul API (https://github.com/ansible-collections/community.general/pull/9026).
diff --git a/changelogs/fragments/9027-support-organizations-in-keycloak-realm.yml b/changelogs/fragments/9027-support-organizations-in-keycloak-realm.yml
deleted file mode 100644
index 7866cc53b8..0000000000
--- a/changelogs/fragments/9027-support-organizations-in-keycloak-realm.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - keycloak_realm - add boolean toggle to configure organization support for a given keycloak realm (https://github.com/ansible-collections/community.general/issues/9027, https://github.com/ansible-collections/community.general/pull/8927/).
diff --git a/changelogs/fragments/9028-bitwarden-secrets-manager-syntax-fix.yml b/changelogs/fragments/9028-bitwarden-secrets-manager-syntax-fix.yml
deleted file mode 100644
index d542692f45..0000000000
--- a/changelogs/fragments/9028-bitwarden-secrets-manager-syntax-fix.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - "bitwarden lookup plugin - support BWS v0.3.0 syntax breaking change (https://github.com/ansible-collections/community.general/pull/9028)."
\ No newline at end of file
diff --git a/changelogs/fragments/9044-pipx-fixes.yml b/changelogs/fragments/9044-pipx-fixes.yml
deleted file mode 100644
index dbf0e3c10d..0000000000
--- a/changelogs/fragments/9044-pipx-fixes.yml
+++ /dev/null
@@ -1,7 +0,0 @@
-minor_changes:
- - pipx - refactor out parsing of ``pipx list`` output to module utils (https://github.com/ansible-collections/community.general/pull/9044).
- - pipx_info - refactor out parsing of ``pipx list`` output to module utils (https://github.com/ansible-collections/community.general/pull/9044).
- - pipx_info - add new return value ``pinned`` (https://github.com/ansible-collections/community.general/pull/9044).
-bugfixes:
- - pipx module utils - add missing command line formatter for argument ``spec_metadata`` (https://github.com/ansible-collections/community.general/pull/9044).
- - pipx - it was ignoring ``global`` when listing existing applications (https://github.com/ansible-collections/community.general/pull/9044).
diff --git a/changelogs/fragments/9047-redfish-uri-parsing.yml b/changelogs/fragments/9047-redfish-uri-parsing.yml
deleted file mode 100644
index 83c9450f44..0000000000
--- a/changelogs/fragments/9047-redfish-uri-parsing.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - redfish_utils module utils - fix issue with URI parsing to gracefully handling trailing slashes when extracting member identifiers (https://github.com/ansible-collections/community.general/issues/9047, https://github.com/ansible-collections/community.general/pull/9057).
diff --git a/changelogs/fragments/9052-modprobe-bugfix.yml b/changelogs/fragments/9052-modprobe-bugfix.yml
deleted file mode 100644
index b9519e9055..0000000000
--- a/changelogs/fragments/9052-modprobe-bugfix.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - modprobe - fix check mode not being honored for ``persistent`` option (https://github.com/ansible-collections/community.general/issues/9051, https://github.com/ansible-collections/community.general/pull/9052).
diff --git a/changelogs/fragments/9056-fix-one_image-modules.yml b/changelogs/fragments/9056-fix-one_image-modules.yml
deleted file mode 100644
index 31b85904fa..0000000000
--- a/changelogs/fragments/9056-fix-one_image-modules.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-bugfixes:
- - one_image - fix module failing due to a class method typo (https://github.com/ansible-collections/community.general/pull/9056).
- - one_image_info - fix module failing due to a class method typo (https://github.com/ansible-collections/community.general/pull/9056).
diff --git a/changelogs/fragments/9059-redfish_command-updateuseraccounttypes.yml b/changelogs/fragments/9059-redfish_command-updateuseraccounttypes.yml
deleted file mode 100644
index 066a84e1e9..0000000000
--- a/changelogs/fragments/9059-redfish_command-updateuseraccounttypes.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - redfish_command - add ``UpdateUserAccountTypes`` command (https://github.com/ansible-collections/community.general/issues/9058, https://github.com/ansible-collections/community.general/pull/9059).
diff --git a/changelogs/fragments/9060-ansible-galaxy-install-version.yml b/changelogs/fragments/9060-ansible-galaxy-install-version.yml
deleted file mode 100644
index 87d5137ad2..0000000000
--- a/changelogs/fragments/9060-ansible-galaxy-install-version.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - ansible_galaxy_install - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9060).
diff --git a/changelogs/fragments/9061-cpanm-version.yml b/changelogs/fragments/9061-cpanm-version.yml
deleted file mode 100644
index af91cac1c0..0000000000
--- a/changelogs/fragments/9061-cpanm-version.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - cpanm - add return value ``cpanm_version`` (https://github.com/ansible-collections/community.general/pull/9061).
diff --git a/changelogs/fragments/9063-django-version.yml b/changelogs/fragments/9063-django-version.yml
deleted file mode 100644
index 3d0287a756..0000000000
--- a/changelogs/fragments/9063-django-version.yml
+++ /dev/null
@@ -1,5 +0,0 @@
-minor_changes:
- - django module utils - always retrieve version (https://github.com/ansible-collections/community.general/pull/9063).
- - django_check - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9063).
- - django_command - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9063).
- - django_createcachetable - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9063).
diff --git a/changelogs/fragments/9064-gconftool2-version.yml b/changelogs/fragments/9064-gconftool2-version.yml
deleted file mode 100644
index 7913c76a81..0000000000
--- a/changelogs/fragments/9064-gconftool2-version.yml
+++ /dev/null
@@ -1,4 +0,0 @@
-minor_changes:
- - gcontool2 module utils - add argument formatter ``version`` (https://github.com/ansible-collections/community.general/pull/9064).
- - gcontool2 - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9064).
- - gcontool2_info - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9064).
diff --git a/changelogs/fragments/9066-proxmox-kvm-ciupgrade.yml b/changelogs/fragments/9066-proxmox-kvm-ciupgrade.yml
deleted file mode 100644
index 91e9127b70..0000000000
--- a/changelogs/fragments/9066-proxmox-kvm-ciupgrade.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - proxmox_kvm - adds the ``ciupgrade`` parameter to specify whether cloud-init should upgrade system packages at first boot (https://github.com/ansible-collections/community.general/pull/9066).
diff --git a/changelogs/fragments/9067-gio-mime-version.yml b/changelogs/fragments/9067-gio-mime-version.yml
deleted file mode 100644
index 9e2fb76082..0000000000
--- a/changelogs/fragments/9067-gio-mime-version.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-minor_changes:
- - gio_mime module utils - add argument formatter ``version`` (https://github.com/ansible-collections/community.general/pull/9067).
- - gio_mime - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9067).
diff --git a/changelogs/fragments/9075-add-creation-oneimage.yml b/changelogs/fragments/9075-add-creation-oneimage.yml
deleted file mode 100644
index 96420d24ef..0000000000
--- a/changelogs/fragments/9075-add-creation-oneimage.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-minor_changes:
- - one_image - add ``create``, ``template`` and ``datastore_id`` arguments for image creation (https://github.com/ansible-collections/community.general/pull/9075).
- - one_image - add ``wait_timeout`` argument for adjustable timeouts (https://github.com/ansible-collections/community.general/pull/9075).
diff --git a/changelogs/fragments/9084-collection_version-importlib.yml b/changelogs/fragments/9084-collection_version-importlib.yml
deleted file mode 100644
index 827b9653d2..0000000000
--- a/changelogs/fragments/9084-collection_version-importlib.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - "collection_version lookup plugin - use ``importlib`` directly instead of the deprecated and in ansible-core 2.19 removed ``ansible.module_utils.compat.importlib`` (https://github.com/ansible-collections/community.general/pull/9084)."
diff --git a/changelogs/fragments/9084-jenkins_node-add-offline-message.yml b/changelogs/fragments/9084-jenkins_node-add-offline-message.yml
deleted file mode 100644
index 3718127513..0000000000
--- a/changelogs/fragments/9084-jenkins_node-add-offline-message.yml
+++ /dev/null
@@ -1,8 +0,0 @@
-minor_changes:
- - jenkins_node - add ``offline_message`` parameter for updating a Jenkins node offline cause reason when the state is "disabled" (offline) (https://github.com/ansible-collections/community.general/pull/9084)."
-
-bugfixes:
- - jenkins_node - fixed ``enabled``, ``disable`` and ``absent`` node state redirect authorization issues, same as was present for ``present`` (https://github.com/ansible-collections/community.general/pull/9084).
-
-known_issues:
- - jenkins_node - the module is not able to update offline message when node is already offline due to internally using toggleOffline API (https://github.com/ansible-collections/community.general/pull/9084).
diff --git a/changelogs/fragments/9086-gio-mime-version.yml b/changelogs/fragments/9086-gio-mime-version.yml
deleted file mode 100644
index 46c3e6cec8..0000000000
--- a/changelogs/fragments/9086-gio-mime-version.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - opkg - add return value ``version`` (https://github.com/ansible-collections/community.general/pull/9086).
diff --git a/changelogs/fragments/9087-mattermost-priority.yaml b/changelogs/fragments/9087-mattermost-priority.yaml
deleted file mode 100644
index f66d4189cc..0000000000
--- a/changelogs/fragments/9087-mattermost-priority.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - mattermost - adds support for message priority (https://github.com/ansible-collections/community.general/issues/9068, https://github.com/ansible-collections/community.general/pull/9087).
diff --git a/changelogs/fragments/9092-keycloak-clientscope-type-fix-check-mode.yml b/changelogs/fragments/9092-keycloak-clientscope-type-fix-check-mode.yml
deleted file mode 100644
index b51eb24136..0000000000
--- a/changelogs/fragments/9092-keycloak-clientscope-type-fix-check-mode.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-bugfixes:
- - keycloak_clientscope_type - fix detect changes in check mode (https://github.com/ansible-collections/community.general/issues/9092, https://github.com/ansible-collections/community.general/pull/9093).
diff --git a/changelogs/fragments/9099-proxmox-fix-insecure.yml b/changelogs/fragments/9099-proxmox-fix-insecure.yml
deleted file mode 100644
index b277a0f933..0000000000
--- a/changelogs/fragments/9099-proxmox-fix-insecure.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-minor_changes:
- - proxmox inventory plugin - fix urllib3 ``InsecureRequestWarnings`` not being suppressed when a token is used (https://github.com/ansible-collections/community.general/pull/9099).
diff --git a/changelogs/fragments/deprecate-hipchat.yml b/changelogs/fragments/deprecate-hipchat.yml
deleted file mode 100644
index 256991ce3b..0000000000
--- a/changelogs/fragments/deprecate-hipchat.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-deprecated_features:
- - "hipchat - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The module is therefore deprecated and will be removed from community.general 11.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/pull/8919)."
diff --git a/changelogs/fragments/deprecations.yml b/changelogs/fragments/deprecations.yml
deleted file mode 100644
index c8f4f6150a..0000000000
--- a/changelogs/fragments/deprecations.yml
+++ /dev/null
@@ -1,8 +0,0 @@
-removed_features:
- - "redhat_subscriptions - removed the ``pool`` option. Use ``pool_ids`` instead (https://github.com/ansible-collections/community.general/pull/8918)."
- - "proxmox_kvm - removed the ``proxmox_default_behavior`` option. Explicitly specify the old default values if you were using ``proxmox_default_behavior=compatibility``, otherwise simply remove it (https://github.com/ansible-collections/community.general/pull/8918)."
- - "ejabberd_user - removed the ``logging`` option (https://github.com/ansible-collections/community.general/pull/8918)."
- - "consul - removed the ``ack_params_state_absent`` option. It had no effect anymore (https://github.com/ansible-collections/community.general/pull/8918)."
-breaking_changes:
- - "irc - the defaults of ``use_tls`` and ``validate_certs`` changed from ``false`` to ``true`` (https://github.com/ansible-collections/community.general/pull/8918)."
- - "rhsm_repository - the states ``present`` and ``absent`` have been removed. Use ``enabled`` and ``disabled`` instead (https://github.com/ansible-collections/community.general/pull/8918)."
diff --git a/changelogs/fragments/removals.yml b/changelogs/fragments/removals.yml
deleted file mode 100644
index 1a1f137194..0000000000
--- a/changelogs/fragments/removals.yml
+++ /dev/null
@@ -1,10 +0,0 @@
-removed_features:
- - "The hipchat callback plugin has been removed. The hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020 (https://github.com/ansible-collections/community.general/pull/8921)."
- - "The consul_acl module has been removed. Use community.general.consul_token and/or community.general.consul_policy instead (https://github.com/ansible-collections/community.general/pull/8921)."
- - "The rhn_channel module has been removed (https://github.com/ansible-collections/community.general/pull/8921)."
- - "The rhn_register module has been removed (https://github.com/ansible-collections/community.general/pull/8921)."
- - "The redhat module utils has been removed (https://github.com/ansible-collections/community.general/pull/8921)."
-breaking_changes:
- - The collection no longer supports ansible-core 2.13 and ansible-core 2.14.
- While most (or even all) modules and plugins might still work with these versions, they are no longer tested in CI and breakages regarding them will not be fixed
- (https://github.com/ansible-collections/community.general/pull/8921)."
diff --git a/docs/docsite/extra-docs.yml b/docs/docsite/extra-docs.yml
index f73d0fe012..156e93309d 100644
--- a/docs/docsite/extra-docs.yml
+++ b/docs/docsite/extra-docs.yml
@@ -20,3 +20,4 @@ sections:
- guide_vardict
- guide_cmdrunner
- guide_modulehelper
+ - guide_uthelper
diff --git a/docs/docsite/rst/filter_guide_abstract_informations_lists_helper.rst b/docs/docsite/rst/filter_guide_abstract_informations_lists_helper.rst
index 63db10a782..505320c79c 100644
--- a/docs/docsite/rst/filter_guide_abstract_informations_lists_helper.rst
+++ b/docs/docsite/rst/filter_guide_abstract_informations_lists_helper.rst
@@ -65,7 +65,7 @@ All three statements are equivalent and give:
.. note:: Be aware that in most cases, filter calls without any argument require ``flatten=true``, otherwise the input is returned as result. The reason for this is, that the input is considered as a variable argument and is wrapped by an additional outer list. ``flatten=true`` ensures that this list is removed before the input is processed by the filter logic.
-The filters ansplugin:`community.general.lists_difference#filter` or :ansplugin:`community.general.lists_symmetric_difference#filter` can be used in the same way as the filters in the examples above. They calculate the difference or the symmetric difference between two or more lists and preserve the item order.
+The filters :ansplugin:`community.general.lists_difference#filter` or :ansplugin:`community.general.lists_symmetric_difference#filter` can be used in the same way as the filters in the examples above. They calculate the difference or the symmetric difference between two or more lists and preserve the item order.
For example, the symmetric difference of ``A``, ``B`` and ``C`` may be written as:
diff --git a/docs/docsite/rst/filter_guide_selecting_json_data.rst b/docs/docsite/rst/filter_guide_selecting_json_data.rst
index 73dbf985ba..3f4e56c141 100644
--- a/docs/docsite/rst/filter_guide_selecting_json_data.rst
+++ b/docs/docsite/rst/filter_guide_selecting_json_data.rst
@@ -124,7 +124,7 @@ To get a hash map with all ports and names of a cluster:
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}"
+ server_name_cluster1_query: "domain.server[?cluster=='cluster1'].{name: name, port: port}"
To extract ports from all clusters with name starting with 'server1':
diff --git a/docs/docsite/rst/guide_cmdrunner.rst b/docs/docsite/rst/guide_cmdrunner.rst
index f7b70a86e1..c1514ee340 100644
--- a/docs/docsite/rst/guide_cmdrunner.rst
+++ b/docs/docsite/rst/guide_cmdrunner.rst
@@ -267,24 +267,54 @@ In these descriptions ``value`` refers to the single parameter passed to the for
+------------+-------------------------+
- ``cmd_runner_fmt.as_fixed()``
- This method receives one parameter ``arg``, the function expects no ``value`` - if one
- is provided then it is ignored.
- The function returns ``arg`` as-is.
+ This method defines one or more fixed arguments that are returned by the generated function
+ regardless whether ``value`` is passed to it or not.
- - Creation:
- ``cmd_runner_fmt.as_fixed("--version")``
+ This method accepts these arguments in one of three forms:
+
+ * one scalar parameter ``arg``, which will be returned as ``[arg]`` by the function, or
+ * one sequence parameter, such as a list, ``arg``, which will be returned by the function as ``arg[0]``, or
+ * multiple parameters ``args``, which will be returned as ``args`` directly by the function.
+
+ See the examples below for each one of those forms. And, stressing that the generated function expects no ``value`` - if one
+ is provided then it is ignored.
+
+ - Creation (one scalar argument):
+ * ``cmd_runner_fmt.as_fixed("--version")``
- Examples:
- +---------+-----------------------+
- | Value | Outcome |
- +=========+=======================+
- | | ``["--version"]`` |
- +---------+-----------------------+
- | 57 | ``["--version"]`` |
- +---------+-----------------------+
+ +---------+--------------------------------------+
+ | Value | Outcome |
+ +=========+======================================+
+ | | * ``["--version"]`` |
+ +---------+--------------------------------------+
+ | 57 | * ``["--version"]`` |
+ +---------+--------------------------------------+
+
+ - Creation (one sequence argument):
+ * ``cmd_runner_fmt.as_fixed(["--list", "--json"])``
+ - Examples:
+ +---------+--------------------------------------+
+ | Value | Outcome |
+ +=========+======================================+
+ | | * ``["--list", "--json"]`` |
+ +---------+--------------------------------------+
+ | True | * ``["--list", "--json"]`` |
+ +---------+--------------------------------------+
+
+ - Creation (multiple arguments):
+ * ``cmd_runner_fmt.as_fixed("--one", "--two", "--three")``
+ - Examples:
+ +---------+--------------------------------------+
+ | Value | Outcome |
+ +=========+======================================+
+ | | * ``["--one", "--two", "--three"]`` |
+ +---------+--------------------------------------+
+ | False | * ``["--one", "--two", "--three"]`` |
+ +---------+--------------------------------------+
- Note:
This is the only special case in which a value can be missing for the formatting function.
- The example also comes from the code in `Quickstart`_.
+ The first example here comes from the code in `Quickstart`_.
In that case, the module has code to determine the command's version so that it can assert compatibility.
There is no *value* to be passed for that CLI argument.
diff --git a/docs/docsite/rst/guide_modulehelper.rst b/docs/docsite/rst/guide_modulehelper.rst
index 68b46e6c94..1f8d305643 100644
--- a/docs/docsite/rst/guide_modulehelper.rst
+++ b/docs/docsite/rst/guide_modulehelper.rst
@@ -346,6 +346,8 @@ However, you can set output variables specifically for that exception, if you so
.. code-block:: python
+ from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelperException
+
def __init_module__(self):
if not complex_validation():
self.do_raise("Validation failed!")
@@ -354,11 +356,16 @@ However, you can set output variables specifically for that exception, if you so
awesomeness = calculate_awesomeness()
if awesomeness > 1000:
self.do_raise("Over awesome, I cannot handle it!", update_output={"awesomeness": awesomeness})
+ # which is just a convenience shortcut for
+ raise ModuleHelperException("...", update_output={...})
All exceptions derived from ``Exception`` are captured and translated into a ``fail_json()`` call.
However, if you do want to call ``self.module.fail_json()`` yourself it will work,
just keep in mind that there will be no automatic handling of output variables in that case.
+Behind the curtains, all ``do_raise()`` does is to raise a ``ModuleHelperException``.
+If you want to create specialized error handling for your code, the best way is to extend that clas and raise it when needed.
+
.. _ansible_collections.community.general.docsite.guide_modulehelper.statemh:
StateModuleHelper
@@ -461,6 +468,11 @@ Additionally, MH will also delegate:
- ``diff_mode`` to ``self.module._diff``
- ``verbosity`` to ``self.module._verbosity``
+Starting in community.general 10.3.0, MH will also delegate the method ``debug`` to ``self.module``.
+If any existing module already has a ``debug`` attribute defined, a warning message will be generated,
+requesting it to be renamed. Upon the release of community.general 12.0.0, the delegation will be
+preemptive and will override any existing method or property in the subclasses.
+
Decorators
""""""""""
diff --git a/docs/docsite/rst/guide_uthelper.rst b/docs/docsite/rst/guide_uthelper.rst
new file mode 100644
index 0000000000..657ced66cf
--- /dev/null
+++ b/docs/docsite/rst/guide_uthelper.rst
@@ -0,0 +1,394 @@
+..
+ Copyright (c) Ansible Project
+ GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+ SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_uthelper:
+
+UTHelper Guide
+==============
+
+Introduction
+^^^^^^^^^^^^
+
+``UTHelper`` was written to reduce the boilerplate code used in unit tests for modules.
+It was originally written to handle tests of modules that run external commands using ``AnsibleModule.run_command()``.
+At the time of writing (Feb 2025) that remains the only type of tests you can use
+``UTHelper`` for, but it aims to provide support for other types of interactions.
+
+Until now, there are many different ways to implement unit tests that validate a module based on the execution of external commands. See some examples:
+
+* `test_apk.py `_ - A very simple one
+* `test_bootc_manage.py `_ -
+ This one has more test cases, but do notice how the code is repeated amongst them.
+* `test_modprobe.py `_ -
+ This one has 15 tests in it, but to achieve that it declares 8 classes repeating quite a lot of code.
+
+As you can notice, there is no consistency in the way these tests are executed -
+they all do the same thing eventually, but each one is written in a very distinct way.
+
+``UTHelper`` aims to:
+
+* provide a consistent idiom to define unit tests
+* reduce the code to a bare minimal, and
+* define tests as data instead
+* allow the test cases definition to be expressed not only as a Python data structure but also as YAML content
+
+Quickstart
+""""""""""
+
+To use UTHelper, your test module will need only a bare minimal of code:
+
+.. code-block:: python
+
+ # tests/unit/plugin/modules/test_ansible_module.py
+ from ansible_collections.community.general.plugins.modules import ansible_module
+ from .uthelper import UTHelper, RunCommandMock
+
+
+ UTHelper.from_module(ansible_module, __name__, mocks=[RunCommandMock])
+
+Then, in the test specification file, you have:
+
+.. code-block:: yaml
+
+ # tests/unit/plugin/modules/test_ansible_module.yaml
+ test_cases:
+ - id: test_ansible_module
+ flags:
+ diff: true
+ input:
+ state: present
+ name: Roger the Shrubber
+ output:
+ shrubbery:
+ looks: nice
+ price: not too expensive
+ changed: true
+ diff:
+ before:
+ shrubbery: null
+ after:
+ shrubbery:
+ looks: nice
+ price: not too expensive
+ mocks:
+ run_command:
+ - command: [/testbin/shrubber, --version]
+ rc: 0
+ out: "2.80.0\n"
+ err: ''
+ - command: [/testbin/shrubber, --make-shrubbery]
+ rc: 0
+ out: 'Shrubbery created'
+ err: ''
+
+.. note::
+
+ If you prefer to pick a different YAML file for the test cases, or if you prefer to define them in plain Python,
+ you can use the convenience methods ``UTHelper.from_file()`` and ``UTHelper.from_spec()``, respectively.
+ See more details below.
+
+
+Using ``UTHelper``
+^^^^^^^^^^^^^^^^^^
+
+Test Module
+"""""""""""
+
+``UTHelper`` is **strictly for unit tests**. To use it, you import the ``.uthelper.UTHelper`` class.
+As mentioned in different parts of this guide, there are three different mechanisms to load the test cases.
+
+.. seealso::
+
+ See the UTHelper class reference below for API details on the three different mechanisms.
+
+
+The easies and most recommended way of using ``UTHelper`` is literally the example shown.
+See a real world example at
+`test_gconftool2.py `_.
+
+The ``from_module()`` method will pick the filename of the test module up (in the example above, ``tests/unit/plugins/modules/test_gconftool2.py``)
+and it will search for ``tests/unit/plugins/modules/test_gconftool2.yaml`` (or ``.yml`` if that is not found).
+In that file it will expect to find the test specification expressed in YAML format, conforming to the structure described below LINK LINK LINK.
+
+If you prefer to read the test specifications a different file path, use ``from_file()`` passing the file handle for the YAML file.
+
+And, if for any reason you prefer or need to pass the data structure rather than dealing with YAML files, use the ``from_spec()`` method.
+A real world example for that can be found at
+`test_snap.py `_.
+
+
+Test Specification
+""""""""""""""""""
+
+The structure of the test specification data is described below.
+
+Top level
+---------
+
+At the top level there are two accepted keys:
+
+- ``anchors: dict``
+ Optional. Placeholder for you to define YAML anchors that can be repeated in the test cases.
+ Its contents are never accessed directly by test Helper.
+- ``test_cases: list``
+ Mandatory. List of test cases, see below for definition.
+
+Test cases
+----------
+
+You write the test cases with five elements:
+
+- ``id: str``
+ Mandatory. Used to identify the test case.
+
+- ``flags: dict``
+ Optional. Flags controling the behavior of the test case. All flags are optional. Accepted flags:
+
+ * ``check: bool``: set to ``true`` if the module is to be executed in **check mode**.
+ * ``diff: bool``: set to ``true`` if the module is to be executed in **diff mode**.
+ * ``skip: str``: set the test case to be skipped, providing the message for ``pytest.skip()``.
+ * ``xfail: str``: set the test case to expect failure, providing the message for ``pytest.xfail()``.
+
+- ``input: dict``
+ Optional. Parameters for the Ansible module, it can be empty.
+
+- ``output: dict``
+ Optional. Expected return values from the Ansible module.
+ All RV names are used here are expected to be found in the module output, but not all RVs in the output must be here.
+ It can include special RVs such as ``changed`` and ``diff``.
+ It can be empty.
+
+- ``mocks: dict``
+ Optional. Mocked interactions, ``run_command`` being the only one supported for now.
+ Each key in this dictionary refers to one subclass of ``TestCaseMock`` and its
+ structure is dictated by the ``TestCaseMock`` subclass implementation.
+ All keys are expected to be named using snake case, as in ``run_command``.
+ The ``TestCaseMock`` subclass is responsible for defining the name used in the test specification.
+ The structure for that specification is dependent on the implementing class.
+ See more details below for the implementation of ``RunCommandMock``
+
+Example using YAML
+------------------
+
+We recommend you use ``UTHelper`` reading the test specifications from a YAML file.
+See an example below of how one actually looks like (excerpt from ``test_opkg.yaml``):
+
+.. code-block:: yaml
+
+ ---
+ anchors:
+ environ: &env-def {environ_update: {LANGUAGE: C, LC_ALL: C}, check_rc: false}
+ test_cases:
+ - id: install_zlibdev
+ input:
+ name: zlib-dev
+ state: present
+ output:
+ msg: installed 1 package(s)
+ mocks:
+ run_command:
+ - command: [/testbin/opkg, --version]
+ environ: *env-def
+ rc: 0
+ out: ''
+ err: ''
+ - command: [/testbin/opkg, list-installed, zlib-dev]
+ environ: *env-def
+ rc: 0
+ out: ''
+ err: ''
+ - command: [/testbin/opkg, install, zlib-dev]
+ environ: *env-def
+ rc: 0
+ out: |
+ Installing zlib-dev (1.2.11-6) to root...
+ Downloading https://downloads.openwrt.org/releases/22.03.0/packages/mips_24kc/base/zlib-dev_1.2.11-6_mips_24kc.ipk
+ Installing zlib (1.2.11-6) to root...
+ Downloading https://downloads.openwrt.org/releases/22.03.0/packages/mips_24kc/base/zlib_1.2.11-6_mips_24kc.ipk
+ Configuring zlib.
+ Configuring zlib-dev.
+ err: ''
+ - command: [/testbin/opkg, list-installed, zlib-dev]
+ environ: *env-def
+ rc: 0
+ out: |
+ zlib-dev - 1.2.11-6
+ err: ''
+ - id: install_zlibdev_present
+ input:
+ name: zlib-dev
+ state: present
+ output:
+ msg: package(s) already present
+ mocks:
+ run_command:
+ - command: [/testbin/opkg, --version]
+ environ: *env-def
+ rc: 0
+ out: ''
+ err: ''
+ - command: [/testbin/opkg, list-installed, zlib-dev]
+ environ: *env-def
+ rc: 0
+ out: |
+ zlib-dev - 1.2.11-6
+ err: ''
+
+TestCaseMocks Specifications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``TestCaseMock`` subclass is free to define the expected data structure.
+
+RunCommandMock Specification
+""""""""""""""""""""""""""""
+
+``RunCommandMock`` mocks can be specified with the key ``run_command`` and it expects a ``list`` in which elements follow the structure:
+
+- ``command: Union[list, str]``
+ Mandatory. The command that is expected to be executed by the module. It corresponds to the parameter ``args`` of the ``AnsibleModule.run_command()`` call.
+ It can be either a list or a string, though the list form is generally recommended.
+- ``environ: dict``
+ Mandatory. All other parameters passed to the ``AnsibleModule.run_command()`` call.
+ Most commonly used are ``environ_update`` and ``check_rc``.
+ Must include all parameters the Ansible module uses in the ``AnsibleModule.run_command()`` call, otherwise the test will fail.
+- ``rc: int``
+ Mandatory. The return code for the command execution.
+ As per usual in bash scripting, a value of ``0`` means success, whereas any other number is an error code.
+- ``out: str``
+ Mandatory. The *stdout* result of the command execution, as one single string containing zero or more lines.
+- ``err: str``
+ Mandatory. The *stderr* result of the command execution, as one single string containing zero or more lines.
+
+
+``UTHelper`` Reference
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. py:module:: .uthelper
+
+ .. py:class:: UTHelper
+
+ A class to encapsulate unit tests.
+
+ .. py:staticmethod:: from_spec(ansible_module, test_module, test_spec, mocks=None)
+
+ Creates an ``UTHelper`` instance from a given test specification.
+
+ :param ansible_module: The Ansible module to be tested.
+ :type ansible_module: module
+ :param test_module: The test module.
+ :type test_module: module
+ :param test_spec: The test specification.
+ :type test_spec: dict
+ :param mocks: List of ``TestCaseMocks`` to be used during testing. Currently only ``RunCommandMock`` exists.
+ :type mocks: list or None
+ :return: An ``UTHelper`` instance.
+ :rtype: UTHelper
+
+ Example usage of ``from_spec()``:
+
+ .. code-block:: python
+
+ import sys
+
+ from ansible_collections.community.general.plugins.modules import ansible_module
+ from .uthelper import UTHelper, RunCommandMock
+
+ TEST_SPEC = dict(
+ test_cases=[
+ ...
+ ]
+ )
+
+ helper = UTHelper.from_spec(ansible_module, sys.modules[__name__], TEST_SPEC, mocks=[RunCommandMock])
+
+ .. py:staticmethod:: from_file(ansible_module, test_module, test_spec_filehandle, mocks=None)
+
+ Creates an ``UTHelper`` instance from a test specification file.
+
+ :param ansible_module: The Ansible module to be tested.
+ :type ansible_module: module
+ :param test_module: The test module.
+ :type test_module: module
+ :param test_spec_filehandle: A file handle to an file stream handle providing the test specification in YAML format.
+ :type test_spec_filehandle: file
+ :param mocks: List of ``TestCaseMocks`` to be used during testing. Currently only ``RunCommandMock`` exists.
+ :type mocks: list or None
+ :return: An ``UTHelper`` instance.
+ :rtype: UTHelper
+
+ Example usage of ``from_file()``:
+
+ .. code-block:: python
+
+ import sys
+
+ from ansible_collections.community.general.plugins.modules import ansible_module
+ from .uthelper import UTHelper, RunCommandMock
+
+ with open("test_spec.yaml", "r") as test_spec_filehandle:
+ helper = UTHelper.from_file(ansible_module, sys.modules[__name__], test_spec_filehandle, mocks=[RunCommandMock])
+
+ .. py:staticmethod:: from_module(ansible_module, test_module_name, mocks=None)
+
+ Creates an ``UTHelper`` instance from a given Ansible module and test module.
+
+ :param ansible_module: The Ansible module to be tested.
+ :type ansible_module: module
+ :param test_module_name: The name of the test module. It works if passed ``__name__``.
+ :type test_module_name: str
+ :param mocks: List of ``TestCaseMocks`` to be used during testing. Currently only ``RunCommandMock`` exists.
+ :type mocks: list or None
+ :return: An ``UTHelper`` instance.
+ :rtype: UTHelper
+
+ Example usage of ``from_module()``:
+
+ .. code-block:: python
+
+ from ansible_collections.community.general.plugins.modules import ansible_module
+ from .uthelper import UTHelper, RunCommandMock
+
+ # Example usage
+ helper = UTHelper.from_module(ansible_module, __name__, mocks=[RunCommandMock])
+
+
+Creating TestCaseMocks
+^^^^^^^^^^^^^^^^^^^^^^
+
+To create a new ``TestCaseMock`` you must extend that class and implement the relevant parts:
+
+.. code-block:: python
+
+ class ShrubberyMock(TestCaseMock):
+ # this name is mandatory, it is the name used in the test specification
+ name = "shrubbery"
+
+ def setup(self, mocker):
+ # perform setup, commonly using mocker to patch some other piece of code
+ ...
+
+ def check(self, test_case, results):
+ # verify the tst execution met the expectations of the test case
+ # for example the function was called as many times as it should
+ ...
+
+ def fixtures(self):
+ # returns a dict mapping names to pytest fixtures that should be used for the test case
+ # for example, in RunCommandMock it creates a fixture that patches AnsibleModule.get_bin_path
+ ...
+
+Caveats
+^^^^^^^
+
+Known issues/opportunities for improvement:
+
+* Only one ``UTHelper`` per test module: UTHelper injects a test function with a fixed name into the module's namespace,
+ so placing a second ``UTHelper`` instance is going to overwrite the function created by the first one.
+* Order of elements in module's namespace is not consistent across executions in Python 3.5, so if adding more tests to the test module
+ might make Test Helper add its function before or after the other test functions.
+ In the community.general collection the CI processes uses ``pytest-xdist`` to paralellize and distribute the tests,
+ and it requires the order of the tests to be consistent.
+
+.. versionadded:: 7.5.0
diff --git a/galaxy.yml b/galaxy.yml
index 3af5356d06..e6250a5bf2 100644
--- a/galaxy.yml
+++ b/galaxy.yml
@@ -5,7 +5,7 @@
namespace: community
name: general
-version: 10.0.0
+version: 10.5.0
readme: README.md
authors:
- Ansible (https://github.com/ansible)
diff --git a/meta/runtime.yml b/meta/runtime.yml
index f5adb64712..6499587af7 100644
--- a/meta/runtime.yml
+++ b/meta/runtime.yml
@@ -16,6 +16,8 @@ action_groups:
- consul_token
proxmox:
- proxmox
+ - proxmox_backup
+ - proxmox_backup_info
- proxmox_disk
- proxmox_domain_info
- proxmox_group_info
@@ -31,6 +33,34 @@ action_groups:
- proxmox_template
- proxmox_user_info
- proxmox_vm_info
+ keycloak:
+ - keycloak_authentication
+ - keycloak_authentication_required_actions
+ - keycloak_authz_authorization_scope
+ - keycloak_authz_custom_policy
+ - keycloak_authz_permission
+ - keycloak_authz_permission_info
+ - keycloak_client
+ - keycloak_client_rolemapping
+ - keycloak_client_rolescope
+ - keycloak_clientscope
+ - keycloak_clientscope_type
+ - keycloak_clientsecret_info
+ - keycloak_clientsecret_regenerate
+ - keycloak_clienttemplate
+ - keycloak_component
+ - keycloak_component_info
+ - keycloak_group
+ - keycloak_identity_provider
+ - keycloak_realm
+ - keycloak_realm_key
+ - keycloak_realm_keys_metadata_info
+ - keycloak_realm_rolemapping
+ - keycloak_role
+ - keycloak_user
+ - keycloak_user_federation
+ - keycloak_user_rolemapping
+ - keycloak_userprofile
plugin_routing:
callback:
actionable:
@@ -54,6 +84,10 @@ plugin_routing:
removal_version: 2.0.0
warning_text: Use the 'default' callback plugin with 'display_failed_stderr
= yes' option.
+ yaml:
+ deprecation:
+ removal_version: 13.0.0
+ warning_text: The plugin has been superseded by the the option `result_format=yaml` in callback plugin ansible.builtin.default from ansible-core 2.13 onwards.
connection:
docker:
redirect: community.docker.docker
@@ -71,140 +105,64 @@ plugin_routing:
nios_next_network:
redirect: infoblox.nios_modules.nios_next_network
modules:
- consul_acl:
- tombstone:
- removal_version: 10.0.0
- warning_text: Use community.general.consul_token and/or community.general.consul_policy instead.
- hipchat:
- deprecation:
- removal_version: 11.0.0
- warning_text: The hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020.
- rax_cbs_attachments:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_cbs:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_cdb_database:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_cdb_user:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_cdb:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_clb_nodes:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_clb_ssl:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_clb:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_dns_record:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_dns:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_facts:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_files_objects:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_files:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_identity:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_keypair:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_meta:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_mon_alarm:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_mon_check:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_mon_entity:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_mon_notification_plan:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_mon_notification:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_network:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_queue:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_scaling_group:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rax_scaling_policy:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on the deprecated package pyrax.
- rhn_channel:
- tombstone:
- removal_version: 10.0.0
- warning_text: RHN is EOL, please contact the community.general maintainers
- if still using this; see the module documentation for more details.
- rhn_register:
- tombstone:
- removal_version: 10.0.0
- warning_text: RHN is EOL, please contact the community.general maintainers
- if still using this; see the module documentation for more details.
- stackdriver:
- tombstone:
- removal_version: 9.0.0
- warning_text: This module relied on HTTPS APIs that do not exist anymore,
- and any new development in the direction of providing an alternative should
- happen in the context of the google.cloud collection.
ali_instance_facts:
tombstone:
removal_version: 3.0.0
warning_text: Use community.general.ali_instance_info instead.
+ atomic_container:
+ deprecation:
+ removal_version: 13.0.0
+ warning_text: Project Atomic was sunset by the end of 2019.
+ atomic_host:
+ deprecation:
+ removal_version: 13.0.0
+ warning_text: Project Atomic was sunset by the end of 2019.
+ atomic_image:
+ deprecation:
+ removal_version: 13.0.0
+ warning_text: Project Atomic was sunset by the end of 2019.
cisco_spark:
redirect: community.general.cisco_webex
+ clc_alert_policy:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: CenturyLink Cloud services went EOL in September 2023.
+ clc_blueprint_package:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: CenturyLink Cloud services went EOL in September 2023.
+ clc_firewall_policy:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: CenturyLink Cloud services went EOL in September 2023.
+ clc_group:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: CenturyLink Cloud services went EOL in September 2023.
+ clc_loadbalancer:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: CenturyLink Cloud services went EOL in September 2023.
+ clc_modify_server:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: CenturyLink Cloud services went EOL in September 2023.
+ clc_publicip:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: CenturyLink Cloud services went EOL in September 2023.
+ clc_server:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: CenturyLink Cloud services went EOL in September 2023.
+ clc_server_snapshot:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: CenturyLink Cloud services went EOL in September 2023.
+ consul_acl:
+ tombstone:
+ removal_version: 10.0.0
+ warning_text: Use community.general.consul_token and/or community.general.consul_policy instead.
docker_compose:
redirect: community.docker.docker_compose
docker_config:
@@ -259,6 +217,10 @@ plugin_routing:
redirect: community.docker.docker_volume
docker_volume_info:
redirect: community.docker.docker_volume_info
+ facter:
+ deprecation:
+ removal_version: 12.0.0
+ warning_text: Use community.general.facter_facts instead.
flowdock:
tombstone:
removal_version: 9.0.0
@@ -352,6 +314,10 @@ plugin_routing:
redirect: community.hrobot.firewall
hetzner_firewall_info:
redirect: community.hrobot.firewall_info
+ hipchat:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: The hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020.
hpilo_facts:
tombstone:
removal_version: 3.0.0
@@ -673,6 +639,26 @@ plugin_routing:
redirect: community.postgresql.postgresql_user
postgresql_user_obj_stat_info:
redirect: community.postgresql.postgresql_user_obj_stat_info
+ profitbricks:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: Supporting library is unsupported since 2021.
+ profitbricks_datacenter:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: Supporting library is unsupported since 2021.
+ profitbricks_nic:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: Supporting library is unsupported since 2021.
+ profitbricks_volume:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: Supporting library is unsupported since 2021.
+ profitbricks_volume_attachments:
+ deprecation:
+ removal_version: 11.0.0
+ warning_text: Supporting library is unsupported since 2021.
purefa_facts:
tombstone:
removal_version: 3.0.0
@@ -685,10 +671,122 @@ plugin_routing:
tombstone:
removal_version: 3.0.0
warning_text: Use community.general.python_requirements_info instead.
+ rax_cbs_attachments:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_cbs:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_cdb_database:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_cdb_user:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_cdb:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_clb_nodes:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_clb_ssl:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_clb:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_dns_record:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_dns:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_facts:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_files_objects:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_files:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_identity:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_keypair:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_meta:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_mon_alarm:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_mon_check:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_mon_entity:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_mon_notification_plan:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_mon_notification:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_network:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_queue:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_scaling_group:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
+ rax_scaling_policy:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on the deprecated package pyrax.
redfish_facts:
tombstone:
removal_version: 3.0.0
warning_text: Use community.general.redfish_info instead.
+ rhn_channel:
+ tombstone:
+ removal_version: 10.0.0
+ warning_text: RHN is EOL.
+ rhn_register:
+ tombstone:
+ removal_version: 10.0.0
+ warning_text: RHN is EOL.
sapcar_extract:
redirect: community.sap_libs.sapcar_extract
sap_task_list_execute:
@@ -721,6 +819,26 @@ plugin_routing:
tombstone:
removal_version: 3.0.0
warning_text: Use community.general.scaleway_volume_info instead.
+ sensu_check:
+ deprecation:
+ removal_version: 13.0.0
+ warning_text: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
+ sensu_client:
+ deprecation:
+ removal_version: 13.0.0
+ warning_text: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
+ sensu_handler:
+ deprecation:
+ removal_version: 13.0.0
+ warning_text: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
+ sensu_silence:
+ deprecation:
+ removal_version: 13.0.0
+ warning_text: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
+ sensu_subscription:
+ deprecation:
+ removal_version: 13.0.0
+ warning_text: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
sf_account_manager:
tombstone:
removal_version: 2.0.0
@@ -745,6 +863,12 @@ plugin_routing:
tombstone:
removal_version: 3.0.0
warning_text: Use community.general.smartos_image_info instead.
+ stackdriver:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module relied on HTTPS APIs that do not exist anymore,
+ and any new development in the direction of providing an alternative should
+ happen in the context of the google.cloud collection.
vertica_facts:
tombstone:
removal_version: 3.0.0
@@ -779,11 +903,6 @@ plugin_routing:
removal_version: 3.0.0
warning_text: Use community.general.xenserver_guest_info instead.
doc_fragments:
- rackspace:
- tombstone:
- removal_version: 9.0.0
- warning_text: This doc fragment was used by rax modules, that relied on the deprecated
- package pyrax.
_gcp:
redirect: community.google._gcp
docker:
@@ -798,11 +917,16 @@ plugin_routing:
redirect: infoblox.nios_modules.nios
postgresql:
redirect: community.postgresql.postgresql
- module_utils:
- rax:
+ purestorage:
+ deprecation:
+ removal_version: 12.0.0
+ warning_text: The modules for purestorage were removed in community.general 3.0.0, this document fragment was left behind.
+ rackspace:
tombstone:
removal_version: 9.0.0
- warning_text: This module util relied on the deprecated package pyrax.
+ warning_text: This doc fragment was used by rax modules, that relied on the deprecated
+ package pyrax.
+ module_utils:
docker.common:
redirect: community.docker.common
docker.swarm:
@@ -821,6 +945,14 @@ plugin_routing:
redirect: infoblox.nios_modules.api
postgresql:
redirect: community.postgresql.postgresql
+ pure:
+ deprecation:
+ removal_version: 12.0.0
+ warning_text: The modules for purestorage were removed in community.general 3.0.0, this module util was left behind.
+ rax:
+ tombstone:
+ removal_version: 9.0.0
+ warning_text: This module util relied on the deprecated package pyrax.
remote_management.dellemc.dellemc_idrac:
redirect: dellemc.openmanage.dellemc_idrac
remote_management.dellemc.ome:
diff --git a/plugins/action/iptables_state.py b/plugins/action/iptables_state.py
index 5ea55af58c..595d0ece66 100644
--- a/plugins/action/iptables_state.py
+++ b/plugins/action/iptables_state.py
@@ -3,8 +3,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
import time
@@ -22,25 +21,33 @@ class ActionModule(ActionBase):
_VALID_ARGS = frozenset(('path', 'state', 'table', 'noflush', 'counters', 'modprobe', 'ip_version', 'wait'))
DEFAULT_SUDOABLE = True
- MSG_ERROR__ASYNC_AND_POLL_NOT_ZERO = (
- "This module doesn't support async>0 and poll>0 when its 'state' param "
- "is set to 'restored'. To enable its rollback feature (that needs the "
- "module to run asynchronously on the remote), please set task attribute "
- "'poll' (=%s) to 0, and 'async' (=%s) to a value >2 and not greater than "
- "'ansible_timeout' (=%s) (recommended).")
- MSG_WARNING__NO_ASYNC_IS_NO_ROLLBACK = (
- "Attempts to restore iptables state without rollback in case of mistake "
- "may lead the ansible controller to loose access to the hosts and never "
- "regain it before fixing firewall rules through a serial console, or any "
- "other way except SSH. Please set task attribute 'poll' (=%s) to 0, and "
- "'async' (=%s) to a value >2 and not greater than 'ansible_timeout' (=%s) "
- "(recommended).")
- MSG_WARNING__ASYNC_GREATER_THAN_TIMEOUT = (
- "You attempt to restore iptables state with rollback in case of mistake, "
- "but with settings that will lead this rollback to happen AFTER that the "
- "controller will reach its own timeout. Please set task attribute 'poll' "
- "(=%s) to 0, and 'async' (=%s) to a value >2 and not greater than "
- "'ansible_timeout' (=%s) (recommended).")
+ @staticmethod
+ def msg_error__async_and_poll_not_zero(task_poll, task_async, max_timeout):
+ return (
+ "This module doesn't support async>0 and poll>0 when its 'state' param "
+ "is set to 'restored'. To enable its rollback feature (that needs the "
+ "module to run asynchronously on the remote), please set task attribute "
+ f"'poll' (={task_poll}) to 0, and 'async' (={task_async}) to a value >2 and not greater than "
+ f"'ansible_timeout' (={max_timeout}) (recommended).")
+
+ @staticmethod
+ def msg_warning__no_async_is_no_rollback(task_poll, task_async, max_timeout):
+ return (
+ "Attempts to restore iptables state without rollback in case of mistake "
+ "may lead the ansible controller to loose access to the hosts and never "
+ "regain it before fixing firewall rules through a serial console, or any "
+ f"other way except SSH. Please set task attribute 'poll' (={task_poll}) to 0, and "
+ f"'async' (={task_async}) to a value >2 and not greater than 'ansible_timeout' (={max_timeout}) "
+ "(recommended).")
+
+ @staticmethod
+ def msg_warning__async_greater_than_timeout(task_poll, task_async, max_timeout):
+ return (
+ "You attempt to restore iptables state with rollback in case of mistake, "
+ "but with settings that will lead this rollback to happen AFTER that the "
+ "controller will reach its own timeout. Please set task attribute 'poll' "
+ f"(={task_poll}) to 0, and 'async' (={task_async}) to a value >2 and not greater than "
+ f"'ansible_timeout' (={max_timeout}) (recommended).")
def _async_result(self, async_status_args, task_vars, timeout):
'''
@@ -95,18 +102,18 @@ class ActionModule(ActionBase):
if module_args.get('state', None) == 'restored':
if not wrap_async:
if not check_mode:
- display.warning(self.MSG_WARNING__NO_ASYNC_IS_NO_ROLLBACK % (
+ display.warning(self.msg_error__async_and_poll_not_zero(
task_poll,
task_async,
max_timeout))
elif task_poll:
- raise AnsibleActionFail(self.MSG_ERROR__ASYNC_AND_POLL_NOT_ZERO % (
+ raise AnsibleActionFail(self.msg_warning__no_async_is_no_rollback(
task_poll,
task_async,
max_timeout))
else:
if task_async > max_timeout and not check_mode:
- display.warning(self.MSG_WARNING__ASYNC_GREATER_THAN_TIMEOUT % (
+ display.warning(self.msg_warning__async_greater_than_timeout(
task_poll,
task_async,
max_timeout))
@@ -119,10 +126,10 @@ class ActionModule(ActionBase):
# remote and local sides (if not the same, make the loop
# longer on the controller); and set a backup file path.
module_args['_timeout'] = task_async
- module_args['_back'] = '%s/iptables.state' % async_dir
+ module_args['_back'] = f'{async_dir}/iptables.state'
async_status_args = dict(mode='status')
- confirm_cmd = 'rm -f %s' % module_args['_back']
- starter_cmd = 'touch %s.starter' % module_args['_back']
+ confirm_cmd = f"rm -f {module_args['_back']}"
+ starter_cmd = f"touch {module_args['_back']}.starter"
remaining_time = max(task_async, max_timeout)
# do work!
diff --git a/plugins/action/shutdown.py b/plugins/action/shutdown.py
index 01201a6405..d5db878812 100644
--- a/plugins/action/shutdown.py
+++ b/plugins/action/shutdown.py
@@ -5,9 +5,8 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
+from __future__ import annotations
-__metaclass__ = type
from ansible.errors import AnsibleError, AnsibleConnectionFailure
from ansible.module_utils.common.text.converters import to_native, to_text
@@ -18,6 +17,10 @@ from ansible.utils.display import Display
display = Display()
+def fmt(mapping, key):
+ return to_native(mapping[key]).strip()
+
+
class TimedOutException(Exception):
pass
@@ -84,31 +87,26 @@ class ActionModule(ActionBase):
def get_distribution(self, task_vars):
# FIXME: only execute the module if we don't already have the facts we need
distribution = {}
- display.debug('{action}: running setup module to get distribution'.format(action=self._task.action))
+ display.debug(f'{self._task.action}: running setup module to get distribution')
module_output = self._execute_module(
task_vars=task_vars,
module_name='ansible.legacy.setup',
module_args={'gather_subset': 'min'})
try:
if module_output.get('failed', False):
- raise AnsibleError('Failed to determine system distribution. {0}, {1}'.format(
- to_native(module_output['module_stdout']).strip(),
- to_native(module_output['module_stderr']).strip()))
+ raise AnsibleError(f"Failed to determine system distribution. {fmt(module_output, 'module_stdout')}, {fmt(module_output, 'module_stderr')}")
distribution['name'] = module_output['ansible_facts']['ansible_distribution'].lower()
distribution['version'] = to_text(
module_output['ansible_facts']['ansible_distribution_version'].split('.')[0])
distribution['family'] = to_text(module_output['ansible_facts']['ansible_os_family'].lower())
- display.debug("{action}: distribution: {dist}".format(action=self._task.action, dist=distribution))
+ display.debug(f"{self._task.action}: distribution: {distribution}")
return distribution
except KeyError as ke:
- raise AnsibleError('Failed to get distribution information. Missing "{0}" in output.'.format(ke.args[0]))
+ raise AnsibleError(f'Failed to get distribution information. Missing "{ke.args[0]}" in output.')
def get_shutdown_command(self, task_vars, distribution):
def find_command(command, find_search_paths):
- display.debug('{action}: running find module looking in {paths} to get path for "{command}"'.format(
- action=self._task.action,
- command=command,
- paths=find_search_paths))
+ display.debug(f'{self._task.action}: running find module looking in {find_search_paths} to get path for "{command}"')
find_result = self._execute_module(
task_vars=task_vars,
# prevent collection search by calling with ansible.legacy (still allows library/ override of find)
@@ -130,42 +128,37 @@ class ActionModule(ActionBase):
if is_string(search_paths):
search_paths = [search_paths]
- # Error if we didn't get a list
- err_msg = "'search_paths' must be a string or flat list of strings, got {0}"
try:
incorrect_type = any(not is_string(x) for x in search_paths)
if not isinstance(search_paths, list) or incorrect_type:
raise TypeError
except TypeError:
- raise AnsibleError(err_msg.format(search_paths))
+ # Error if we didn't get a list
+ err_msg = f"'search_paths' must be a string or flat list of strings, got {search_paths}"
+ raise AnsibleError(err_msg)
full_path = find_command(shutdown_bin, search_paths) # find the path to the shutdown command
if not full_path: # if we could not find the shutdown command
- display.vvv('Unable to find command "{0}" in search paths: {1}, will attempt a shutdown using systemd '
- 'directly.'.format(shutdown_bin, search_paths)) # tell the user we will try with systemd
+
+ # tell the user we will try with systemd
+ display.vvv(f'Unable to find command "{shutdown_bin}" in search paths: {search_paths}, will attempt a shutdown using systemd directly.')
systemctl_search_paths = ['/bin', '/usr/bin']
full_path = find_command('systemctl', systemctl_search_paths) # find the path to the systemctl command
if not full_path: # if we couldn't find systemctl
raise AnsibleError(
- 'Could not find command "{0}" in search paths: {1} or systemctl command in search paths: {2}, unable to shutdown.'.
- format(shutdown_bin, search_paths, systemctl_search_paths)) # we give up here
+ f'Could not find command "{shutdown_bin}" in search paths: {search_paths} or systemctl'
+ f' command in search paths: {systemctl_search_paths}, unable to shutdown.') # we give up here
else:
- return "{0} poweroff".format(full_path[0]) # done, since we cannot use args with systemd shutdown
+ return f"{full_path[0]} poweroff" # done, since we cannot use args with systemd shutdown
# systemd case taken care of, here we add args to the command
args = self._get_value_from_facts('SHUTDOWN_COMMAND_ARGS', distribution, 'DEFAULT_SHUTDOWN_COMMAND_ARGS')
# Convert seconds to minutes. If less that 60, set it to 0.
delay_sec = self.delay
shutdown_message = self._task.args.get('msg', self.DEFAULT_SHUTDOWN_MESSAGE)
- return '{0} {1}'. \
- format(
- full_path[0],
- args.format(
- delay_sec=delay_sec,
- delay_min=delay_sec // 60,
- message=shutdown_message
- )
- )
+
+ af = args.format(delay_sec=delay_sec, delay_min=delay_sec // 60, message=shutdown_message)
+ return f'{full_path[0]} {af}'
def perform_shutdown(self, task_vars, distribution):
result = {}
@@ -174,9 +167,8 @@ class ActionModule(ActionBase):
self.cleanup(force=True)
try:
- display.vvv("{action}: shutting down server...".format(action=self._task.action))
- display.debug("{action}: shutting down server with command '{command}'".
- format(action=self._task.action, command=shutdown_command_exec))
+ display.vvv(f"{self._task.action}: shutting down server...")
+ display.debug(f"{self._task.action}: shutting down server with command '{shutdown_command_exec}'")
if self._play_context.check_mode:
shutdown_result['rc'] = 0
else:
@@ -184,16 +176,13 @@ class ActionModule(ActionBase):
except AnsibleConnectionFailure as e:
# If the connection is closed too quickly due to the system being shutdown, carry on
display.debug(
- '{action}: AnsibleConnectionFailure caught and handled: {error}'.format(action=self._task.action,
- error=to_text(e)))
+ f'{self._task.action}: AnsibleConnectionFailure caught and handled: {e}')
shutdown_result['rc'] = 0
if shutdown_result['rc'] != 0:
result['failed'] = True
result['shutdown'] = False
- result['msg'] = "Shutdown command failed. Error was {stdout}, {stderr}".format(
- stdout=to_native(shutdown_result['stdout'].strip()),
- stderr=to_native(shutdown_result['stderr'].strip()))
+ result['msg'] = f"Shutdown command failed. Error was {fmt(shutdown_result, 'stdout')}, {fmt(shutdown_result, 'stderr')}"
return result
result['failed'] = False
@@ -206,7 +195,7 @@ class ActionModule(ActionBase):
# If running with local connection, fail so we don't shutdown ourself
if self._connection.transport == 'local' and (not self._play_context.check_mode):
- msg = 'Running {0} with local connection would shutdown the control node.'.format(self._task.action)
+ msg = f'Running {self._task.action} with local connection would shutdown the control node.'
return {'changed': False, 'elapsed': 0, 'shutdown': False, 'failed': True, 'msg': msg}
if task_vars is None:
diff --git a/plugins/become/doas.py b/plugins/become/doas.py
index 761e5e1e95..13aef19874 100644
--- a/plugins/become/doas.py
+++ b/plugins/become/doas.py
@@ -2,89 +2,88 @@
# Copyright (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: doas
- short_description: Do As user
+DOCUMENTATION = r"""
+name: doas
+short_description: Do As user
+description:
+ - This become plugins allows your remote/login user to execute commands as another user using the C(doas) utility.
+author: Ansible Core Team
+options:
+ become_user:
+ description: User you 'become' to execute the task.
+ type: string
+ ini:
+ - section: privilege_escalation
+ key: become_user
+ - section: doas_become_plugin
+ key: user
+ vars:
+ - name: ansible_become_user
+ - name: ansible_doas_user
+ env:
+ - name: ANSIBLE_BECOME_USER
+ - name: ANSIBLE_DOAS_USER
+ become_exe:
+ description: C(doas) executable.
+ type: string
+ default: doas
+ ini:
+ - section: privilege_escalation
+ key: become_exe
+ - section: doas_become_plugin
+ key: executable
+ vars:
+ - name: ansible_become_exe
+ - name: ansible_doas_exe
+ env:
+ - name: ANSIBLE_BECOME_EXE
+ - name: ANSIBLE_DOAS_EXE
+ become_flags:
+ description: Options to pass to C(doas).
+ type: string
+ default: ''
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: doas_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_doas_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_DOAS_FLAGS
+ become_pass:
+ description: Password for C(doas) prompt.
+ type: string
+ required: false
+ vars:
+ - name: ansible_become_password
+ - name: ansible_become_pass
+ - name: ansible_doas_pass
+ env:
+ - name: ANSIBLE_BECOME_PASS
+ - name: ANSIBLE_DOAS_PASS
+ ini:
+ - section: doas_become_plugin
+ key: password
+ prompt_l10n:
description:
- - This become plugins allows your remote/login user to execute commands as another user via the doas utility.
- author: Ansible Core Team
- options:
- become_user:
- description: User you 'become' to execute the task.
- type: string
- ini:
- - section: privilege_escalation
- key: become_user
- - section: doas_become_plugin
- key: user
- vars:
- - name: ansible_become_user
- - name: ansible_doas_user
- env:
- - name: ANSIBLE_BECOME_USER
- - name: ANSIBLE_DOAS_USER
- become_exe:
- description: Doas executable.
- type: string
- default: doas
- ini:
- - section: privilege_escalation
- key: become_exe
- - section: doas_become_plugin
- key: executable
- vars:
- - name: ansible_become_exe
- - name: ansible_doas_exe
- env:
- - name: ANSIBLE_BECOME_EXE
- - name: ANSIBLE_DOAS_EXE
- become_flags:
- description: Options to pass to doas.
- type: string
- default: ''
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: doas_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_doas_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_DOAS_FLAGS
- become_pass:
- description: Password for doas prompt.
- type: string
- required: false
- vars:
- - name: ansible_become_password
- - name: ansible_become_pass
- - name: ansible_doas_pass
- env:
- - name: ANSIBLE_BECOME_PASS
- - name: ANSIBLE_DOAS_PASS
- ini:
- - section: doas_become_plugin
- key: password
- prompt_l10n:
- description:
- - List of localized strings to match for prompt detection.
- - If empty we will use the built in one.
- type: list
- elements: string
- default: []
- ini:
- - section: doas_become_plugin
- key: localized_prompts
- vars:
- - name: ansible_doas_prompt_l10n
- env:
- - name: ANSIBLE_DOAS_PROMPT_L10N
-'''
+ - List of localized strings to match for prompt detection.
+ - If empty we will use the built in one.
+ type: list
+ elements: string
+ default: []
+ ini:
+ - section: doas_become_plugin
+ key: localized_prompts
+ vars:
+ - name: ansible_doas_prompt_l10n
+ env:
+ - name: ANSIBLE_DOAS_PROMPT_L10N
+"""
import re
@@ -125,9 +124,9 @@ class BecomeModule(BecomeBase):
flags += ' -n'
become_user = self.get_option('become_user')
- user = '-u %s' % (become_user) if become_user else ''
+ user = f'-u {become_user}' if become_user else ''
success_cmd = self._build_success_command(cmd, shell, noexe=True)
executable = getattr(shell, 'executable', shell.SHELL_FAMILY)
- return '%s %s %s %s -c %s' % (become_exe, flags, user, executable, success_cmd)
+ return f'{become_exe} {flags} {user} {executable} -c {success_cmd}'
diff --git a/plugins/become/dzdo.py b/plugins/become/dzdo.py
index d94c684d1f..d890bede09 100644
--- a/plugins/become/dzdo.py
+++ b/plugins/become/dzdo.py
@@ -2,75 +2,74 @@
# Copyright (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: dzdo
- short_description: Centrify's Direct Authorize
- description:
- - This become plugins allows your remote/login user to execute commands as another user via the dzdo utility.
- author: Ansible Core Team
- options:
- become_user:
- description: User you 'become' to execute the task.
- type: string
- ini:
- - section: privilege_escalation
- key: become_user
- - section: dzdo_become_plugin
- key: user
- vars:
- - name: ansible_become_user
- - name: ansible_dzdo_user
- env:
- - name: ANSIBLE_BECOME_USER
- - name: ANSIBLE_DZDO_USER
- become_exe:
- description: Dzdo executable.
- type: string
- default: dzdo
- ini:
- - section: privilege_escalation
- key: become_exe
- - section: dzdo_become_plugin
- key: executable
- vars:
- - name: ansible_become_exe
- - name: ansible_dzdo_exe
- env:
- - name: ANSIBLE_BECOME_EXE
- - name: ANSIBLE_DZDO_EXE
- become_flags:
- description: Options to pass to dzdo.
- type: string
- default: -H -S -n
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: dzdo_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_dzdo_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_DZDO_FLAGS
- become_pass:
- description: Options to pass to dzdo.
- type: string
- required: false
- vars:
- - name: ansible_become_password
- - name: ansible_become_pass
- - name: ansible_dzdo_pass
- env:
- - name: ANSIBLE_BECOME_PASS
- - name: ANSIBLE_DZDO_PASS
- ini:
- - section: dzdo_become_plugin
- key: password
-'''
+DOCUMENTATION = r"""
+name: dzdo
+short_description: Centrify's Direct Authorize
+description:
+ - This become plugins allows your remote/login user to execute commands as another user using the C(dzdo) utility.
+author: Ansible Core Team
+options:
+ become_user:
+ description: User you 'become' to execute the task.
+ type: string
+ ini:
+ - section: privilege_escalation
+ key: become_user
+ - section: dzdo_become_plugin
+ key: user
+ vars:
+ - name: ansible_become_user
+ - name: ansible_dzdo_user
+ env:
+ - name: ANSIBLE_BECOME_USER
+ - name: ANSIBLE_DZDO_USER
+ become_exe:
+ description: C(dzdo) executable.
+ type: string
+ default: dzdo
+ ini:
+ - section: privilege_escalation
+ key: become_exe
+ - section: dzdo_become_plugin
+ key: executable
+ vars:
+ - name: ansible_become_exe
+ - name: ansible_dzdo_exe
+ env:
+ - name: ANSIBLE_BECOME_EXE
+ - name: ANSIBLE_DZDO_EXE
+ become_flags:
+ description: Options to pass to C(dzdo).
+ type: string
+ default: -H -S -n
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: dzdo_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_dzdo_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_DZDO_FLAGS
+ become_pass:
+ description: Options to pass to C(dzdo).
+ type: string
+ required: false
+ vars:
+ - name: ansible_become_password
+ - name: ansible_become_pass
+ - name: ansible_dzdo_pass
+ env:
+ - name: ANSIBLE_BECOME_PASS
+ - name: ANSIBLE_DZDO_PASS
+ ini:
+ - section: dzdo_become_plugin
+ key: password
+"""
from ansible.plugins.become import BecomeBase
@@ -92,10 +91,10 @@ class BecomeModule(BecomeBase):
flags = self.get_option('become_flags')
if self.get_option('become_pass'):
- self.prompt = '[dzdo via ansible, key=%s] password:' % self._id
- flags = '%s -p "%s"' % (flags.replace('-n', ''), self.prompt)
+ self.prompt = f'[dzdo via ansible, key={self._id}] password:'
+ flags = f"{flags.replace('-n', '')} -p \"{self.prompt}\""
become_user = self.get_option('become_user')
- user = '-u %s' % (become_user) if become_user else ''
+ user = f'-u {become_user}' if become_user else ''
- return ' '.join([becomecmd, flags, user, self._build_success_command(cmd, shell)])
+ return f"{becomecmd} {flags} {user} {self._build_success_command(cmd, shell)}"
diff --git a/plugins/become/ksu.py b/plugins/become/ksu.py
index 2be1832dc2..1c936e46da 100644
--- a/plugins/become/ksu.py
+++ b/plugins/become/ksu.py
@@ -2,90 +2,89 @@
# Copyright (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: ksu
- short_description: Kerberos substitute user
+DOCUMENTATION = r"""
+name: ksu
+short_description: Kerberos substitute user
+description:
+ - This become plugins allows your remote/login user to execute commands as another user using the C(ksu) utility.
+author: Ansible Core Team
+options:
+ become_user:
+ description: User you 'become' to execute the task.
+ type: string
+ ini:
+ - section: privilege_escalation
+ key: become_user
+ - section: ksu_become_plugin
+ key: user
+ vars:
+ - name: ansible_become_user
+ - name: ansible_ksu_user
+ env:
+ - name: ANSIBLE_BECOME_USER
+ - name: ANSIBLE_KSU_USER
+ required: true
+ become_exe:
+ description: C(ksu) executable.
+ type: string
+ default: ksu
+ ini:
+ - section: privilege_escalation
+ key: become_exe
+ - section: ksu_become_plugin
+ key: executable
+ vars:
+ - name: ansible_become_exe
+ - name: ansible_ksu_exe
+ env:
+ - name: ANSIBLE_BECOME_EXE
+ - name: ANSIBLE_KSU_EXE
+ become_flags:
+ description: Options to pass to C(ksu).
+ type: string
+ default: ''
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: ksu_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_ksu_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_KSU_FLAGS
+ become_pass:
+ description: C(ksu) password.
+ type: string
+ required: false
+ vars:
+ - name: ansible_ksu_pass
+ - name: ansible_become_pass
+ - name: ansible_become_password
+ env:
+ - name: ANSIBLE_BECOME_PASS
+ - name: ANSIBLE_KSU_PASS
+ ini:
+ - section: ksu_become_plugin
+ key: password
+ prompt_l10n:
description:
- - This become plugins allows your remote/login user to execute commands as another user via the ksu utility.
- author: Ansible Core Team
- options:
- become_user:
- description: User you 'become' to execute the task.
- type: string
- ini:
- - section: privilege_escalation
- key: become_user
- - section: ksu_become_plugin
- key: user
- vars:
- - name: ansible_become_user
- - name: ansible_ksu_user
- env:
- - name: ANSIBLE_BECOME_USER
- - name: ANSIBLE_KSU_USER
- required: true
- become_exe:
- description: Su executable.
- type: string
- default: ksu
- ini:
- - section: privilege_escalation
- key: become_exe
- - section: ksu_become_plugin
- key: executable
- vars:
- - name: ansible_become_exe
- - name: ansible_ksu_exe
- env:
- - name: ANSIBLE_BECOME_EXE
- - name: ANSIBLE_KSU_EXE
- become_flags:
- description: Options to pass to ksu.
- type: string
- default: ''
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: ksu_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_ksu_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_KSU_FLAGS
- become_pass:
- description: Ksu password.
- type: string
- required: false
- vars:
- - name: ansible_ksu_pass
- - name: ansible_become_pass
- - name: ansible_become_password
- env:
- - name: ANSIBLE_BECOME_PASS
- - name: ANSIBLE_KSU_PASS
- ini:
- - section: ksu_become_plugin
- key: password
- prompt_l10n:
- description:
- - List of localized strings to match for prompt detection.
- - If empty we will use the built in one.
- type: list
- elements: string
- default: []
- ini:
- - section: ksu_become_plugin
- key: localized_prompts
- vars:
- - name: ansible_ksu_prompt_l10n
- env:
- - name: ANSIBLE_KSU_PROMPT_L10N
-'''
+ - List of localized strings to match for prompt detection.
+ - If empty we will use the built in one.
+ type: list
+ elements: string
+ default: []
+ ini:
+ - section: ksu_become_plugin
+ key: localized_prompts
+ vars:
+ - name: ansible_ksu_prompt_l10n
+ env:
+ - name: ANSIBLE_KSU_PROMPT_L10N
+"""
import re
@@ -124,4 +123,4 @@ class BecomeModule(BecomeBase):
flags = self.get_option('become_flags')
user = self.get_option('become_user')
- return '%s %s %s -e %s ' % (exe, user, flags, self._build_success_command(cmd, shell))
+ return f'{exe} {user} {flags} -e {self._build_success_command(cmd, shell)} '
diff --git a/plugins/become/machinectl.py b/plugins/become/machinectl.py
index a0467c2c36..81a9d06f86 100644
--- a/plugins/become/machinectl.py
+++ b/plugins/become/machinectl.py
@@ -2,94 +2,92 @@
# Copyright (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: machinectl
- short_description: Systemd's machinectl privilege escalation
- description:
- - This become plugins allows your remote/login user to execute commands as another user via the machinectl utility.
- author: Ansible Core Team
- options:
- become_user:
- description: User you 'become' to execute the task.
- type: string
- default: ''
- ini:
- - section: privilege_escalation
- key: become_user
- - section: machinectl_become_plugin
- key: user
- vars:
- - name: ansible_become_user
- - name: ansible_machinectl_user
- env:
- - name: ANSIBLE_BECOME_USER
- - name: ANSIBLE_MACHINECTL_USER
- become_exe:
- description: Machinectl executable.
- type: string
- default: machinectl
- ini:
- - section: privilege_escalation
- key: become_exe
- - section: machinectl_become_plugin
- key: executable
- vars:
- - name: ansible_become_exe
- - name: ansible_machinectl_exe
- env:
- - name: ANSIBLE_BECOME_EXE
- - name: ANSIBLE_MACHINECTL_EXE
- become_flags:
- description: Options to pass to machinectl.
- type: string
- default: ''
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: machinectl_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_machinectl_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_MACHINECTL_FLAGS
- become_pass:
- description: Password for machinectl.
- type: string
- required: false
- vars:
- - name: ansible_become_password
- - name: ansible_become_pass
- - name: ansible_machinectl_pass
- env:
- - name: ANSIBLE_BECOME_PASS
- - name: ANSIBLE_MACHINECTL_PASS
- ini:
- - section: machinectl_become_plugin
- key: password
- notes:
- - When not using this plugin with user V(root), it only works correctly with a polkit rule which will alter
- the behaviour of machinectl. This rule must alter the prompt behaviour to ask directly for the user credentials,
- if the user is allowed to perform the action (take a look at the examples section).
- If such a rule is not present the plugin only work if it is used in context with the root user,
- because then no further prompt will be shown by machinectl.
-'''
+DOCUMENTATION = r"""
+name: machinectl
+short_description: Systemd's machinectl privilege escalation
+description:
+ - This become plugins allows your remote/login user to execute commands as another user using the C(machinectl) utility.
+author: Ansible Core Team
+options:
+ become_user:
+ description: User you 'become' to execute the task.
+ type: string
+ default: ''
+ ini:
+ - section: privilege_escalation
+ key: become_user
+ - section: machinectl_become_plugin
+ key: user
+ vars:
+ - name: ansible_become_user
+ - name: ansible_machinectl_user
+ env:
+ - name: ANSIBLE_BECOME_USER
+ - name: ANSIBLE_MACHINECTL_USER
+ become_exe:
+ description: C(machinectl) executable.
+ type: string
+ default: machinectl
+ ini:
+ - section: privilege_escalation
+ key: become_exe
+ - section: machinectl_become_plugin
+ key: executable
+ vars:
+ - name: ansible_become_exe
+ - name: ansible_machinectl_exe
+ env:
+ - name: ANSIBLE_BECOME_EXE
+ - name: ANSIBLE_MACHINECTL_EXE
+ become_flags:
+ description: Options to pass to C(machinectl).
+ type: string
+ default: ''
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: machinectl_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_machinectl_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_MACHINECTL_FLAGS
+ become_pass:
+ description: Password for C(machinectl).
+ type: string
+ required: false
+ vars:
+ - name: ansible_become_password
+ - name: ansible_become_pass
+ - name: ansible_machinectl_pass
+ env:
+ - name: ANSIBLE_BECOME_PASS
+ - name: ANSIBLE_MACHINECTL_PASS
+ ini:
+ - section: machinectl_become_plugin
+ key: password
+notes:
+ - When not using this plugin with user V(root), it only works correctly with a polkit rule which will alter the behaviour
+ of machinectl. This rule must alter the prompt behaviour to ask directly for the user credentials, if the user is allowed
+ to perform the action (take a look at the examples section). If such a rule is not present the plugin only work if it
+ is used in context with the root user, because then no further prompt will be shown by machinectl.
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
# A polkit rule needed to use the module with a non-root user.
# See the Notes section for details.
-/etc/polkit-1/rules.d/60-machinectl-fast-user-auth.rules: |
+/etc/polkit-1/rules.d/60-machinectl-fast-user-auth.rules: |-
polkit.addRule(function(action, subject) {
if(action.id == "org.freedesktop.machine1.host-shell" &&
subject.isInGroup("wheel")) {
return polkit.Result.AUTH_SELF_KEEP;
}
});
-'''
+"""
from re import compile as re_compile
@@ -123,7 +121,7 @@ class BecomeModule(BecomeBase):
flags = self.get_option('become_flags')
user = self.get_option('become_user')
- return '%s -q shell %s %s@ %s' % (become, flags, user, self._build_success_command(cmd, shell))
+ return f'{become} -q shell {flags} {user}@ {self._build_success_command(cmd, shell)}'
def check_success(self, b_output):
b_output = self.remove_ansi_codes(b_output)
diff --git a/plugins/become/pbrun.py b/plugins/become/pbrun.py
index 8a96b75797..92a49fe349 100644
--- a/plugins/become/pbrun.py
+++ b/plugins/become/pbrun.py
@@ -2,87 +2,86 @@
# Copyright (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: pbrun
- short_description: PowerBroker run
- description:
- - This become plugins allows your remote/login user to execute commands as another user via the pbrun utility.
- author: Ansible Core Team
- options:
- become_user:
- description: User you 'become' to execute the task.
- type: string
- default: ''
- ini:
- - section: privilege_escalation
- key: become_user
- - section: pbrun_become_plugin
- key: user
- vars:
- - name: ansible_become_user
- - name: ansible_pbrun_user
- env:
- - name: ANSIBLE_BECOME_USER
- - name: ANSIBLE_PBRUN_USER
- become_exe:
- description: Sudo executable.
- type: string
- default: pbrun
- ini:
- - section: privilege_escalation
- key: become_exe
- - section: pbrun_become_plugin
- key: executable
- vars:
- - name: ansible_become_exe
- - name: ansible_pbrun_exe
- env:
- - name: ANSIBLE_BECOME_EXE
- - name: ANSIBLE_PBRUN_EXE
- become_flags:
- description: Options to pass to pbrun.
- type: string
- default: ''
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: pbrun_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_pbrun_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_PBRUN_FLAGS
- become_pass:
- description: Password for pbrun.
- type: string
- required: false
- vars:
- - name: ansible_become_password
- - name: ansible_become_pass
- - name: ansible_pbrun_pass
- env:
- - name: ANSIBLE_BECOME_PASS
- - name: ANSIBLE_PBRUN_PASS
- ini:
- - section: pbrun_become_plugin
- key: password
- wrap_exe:
- description: Toggle to wrap the command pbrun calls in C(shell -c) or not.
- default: false
- type: bool
- ini:
- - section: pbrun_become_plugin
- key: wrap_execution
- vars:
- - name: ansible_pbrun_wrap_execution
- env:
- - name: ANSIBLE_PBRUN_WRAP_EXECUTION
-'''
+DOCUMENTATION = r"""
+name: pbrun
+short_description: PowerBroker run
+description:
+ - This become plugins allows your remote/login user to execute commands as another user using the C(pbrun) utility.
+author: Ansible Core Team
+options:
+ become_user:
+ description: User you 'become' to execute the task.
+ type: string
+ default: ''
+ ini:
+ - section: privilege_escalation
+ key: become_user
+ - section: pbrun_become_plugin
+ key: user
+ vars:
+ - name: ansible_become_user
+ - name: ansible_pbrun_user
+ env:
+ - name: ANSIBLE_BECOME_USER
+ - name: ANSIBLE_PBRUN_USER
+ become_exe:
+ description: C(pbrun) executable.
+ type: string
+ default: pbrun
+ ini:
+ - section: privilege_escalation
+ key: become_exe
+ - section: pbrun_become_plugin
+ key: executable
+ vars:
+ - name: ansible_become_exe
+ - name: ansible_pbrun_exe
+ env:
+ - name: ANSIBLE_BECOME_EXE
+ - name: ANSIBLE_PBRUN_EXE
+ become_flags:
+ description: Options to pass to C(pbrun).
+ type: string
+ default: ''
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: pbrun_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_pbrun_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_PBRUN_FLAGS
+ become_pass:
+ description: Password for C(pbrun).
+ type: string
+ required: false
+ vars:
+ - name: ansible_become_password
+ - name: ansible_become_pass
+ - name: ansible_pbrun_pass
+ env:
+ - name: ANSIBLE_BECOME_PASS
+ - name: ANSIBLE_PBRUN_PASS
+ ini:
+ - section: pbrun_become_plugin
+ key: password
+ wrap_exe:
+ description: Toggle to wrap the command C(pbrun) calls in C(shell -c) or not.
+ default: false
+ type: bool
+ ini:
+ - section: pbrun_become_plugin
+ key: wrap_execution
+ vars:
+ - name: ansible_pbrun_wrap_execution
+ env:
+ - name: ANSIBLE_PBRUN_WRAP_EXECUTION
+"""
from ansible.plugins.become import BecomeBase
@@ -103,7 +102,7 @@ class BecomeModule(BecomeBase):
flags = self.get_option('become_flags')
become_user = self.get_option('become_user')
- user = '-u %s' % (become_user) if become_user else ''
+ user = f'-u {become_user}' if become_user else ''
noexe = not self.get_option('wrap_exe')
- return ' '.join([become_exe, flags, user, self._build_success_command(cmd, shell, noexe=noexe)])
+ return f"{become_exe} {flags} {user} {self._build_success_command(cmd, shell, noexe=noexe)}"
diff --git a/plugins/become/pfexec.py b/plugins/become/pfexec.py
index d48d622713..65690f359b 100644
--- a/plugins/become/pfexec.py
+++ b/plugins/become/pfexec.py
@@ -2,92 +2,91 @@
# Copyright (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: pfexec
- short_description: profile based execution
+DOCUMENTATION = r"""
+name: pfexec
+short_description: profile based execution
+description:
+ - This become plugins allows your remote/login user to execute commands as another user using the C(pfexec) utility.
+author: Ansible Core Team
+options:
+ become_user:
description:
- - This become plugins allows your remote/login user to execute commands as another user via the pfexec utility.
- author: Ansible Core Team
- options:
- become_user:
- description:
- - User you 'become' to execute the task.
- - This plugin ignores this setting as pfexec uses it's own C(exec_attr) to figure this out,
- but it is supplied here for Ansible to make decisions needed for the task execution, like file permissions.
- type: string
- default: root
- ini:
- - section: privilege_escalation
- key: become_user
- - section: pfexec_become_plugin
- key: user
- vars:
- - name: ansible_become_user
- - name: ansible_pfexec_user
- env:
- - name: ANSIBLE_BECOME_USER
- - name: ANSIBLE_PFEXEC_USER
- become_exe:
- description: Sudo executable.
- type: string
- default: pfexec
- ini:
- - section: privilege_escalation
- key: become_exe
- - section: pfexec_become_plugin
- key: executable
- vars:
- - name: ansible_become_exe
- - name: ansible_pfexec_exe
- env:
- - name: ANSIBLE_BECOME_EXE
- - name: ANSIBLE_PFEXEC_EXE
- become_flags:
- description: Options to pass to pfexec.
- type: string
- default: -H -S -n
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: pfexec_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_pfexec_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_PFEXEC_FLAGS
- become_pass:
- description: pfexec password.
- type: string
- required: false
- vars:
- - name: ansible_become_password
- - name: ansible_become_pass
- - name: ansible_pfexec_pass
- env:
- - name: ANSIBLE_BECOME_PASS
- - name: ANSIBLE_PFEXEC_PASS
- ini:
- - section: pfexec_become_plugin
- key: password
- wrap_exe:
- description: Toggle to wrap the command pfexec calls in C(shell -c) or not.
- default: false
- type: bool
- ini:
- - section: pfexec_become_plugin
- key: wrap_execution
- vars:
- - name: ansible_pfexec_wrap_execution
- env:
- - name: ANSIBLE_PFEXEC_WRAP_EXECUTION
- notes:
- - This plugin ignores O(become_user) as pfexec uses its own C(exec_attr) to figure this out.
-'''
+ - User you 'become' to execute the task.
+ - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, but it is supplied here for
+ Ansible to make decisions needed for the task execution, like file permissions.
+ type: string
+ default: root
+ ini:
+ - section: privilege_escalation
+ key: become_user
+ - section: pfexec_become_plugin
+ key: user
+ vars:
+ - name: ansible_become_user
+ - name: ansible_pfexec_user
+ env:
+ - name: ANSIBLE_BECOME_USER
+ - name: ANSIBLE_PFEXEC_USER
+ become_exe:
+ description: C(pfexec) executable.
+ type: string
+ default: pfexec
+ ini:
+ - section: privilege_escalation
+ key: become_exe
+ - section: pfexec_become_plugin
+ key: executable
+ vars:
+ - name: ansible_become_exe
+ - name: ansible_pfexec_exe
+ env:
+ - name: ANSIBLE_BECOME_EXE
+ - name: ANSIBLE_PFEXEC_EXE
+ become_flags:
+ description: Options to pass to C(pfexec).
+ type: string
+ default: -H -S -n
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: pfexec_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_pfexec_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_PFEXEC_FLAGS
+ become_pass:
+ description: C(pfexec) password.
+ type: string
+ required: false
+ vars:
+ - name: ansible_become_password
+ - name: ansible_become_pass
+ - name: ansible_pfexec_pass
+ env:
+ - name: ANSIBLE_BECOME_PASS
+ - name: ANSIBLE_PFEXEC_PASS
+ ini:
+ - section: pfexec_become_plugin
+ key: password
+ wrap_exe:
+ description: Toggle to wrap the command C(pfexec) calls in C(shell -c) or not.
+ default: false
+ type: bool
+ ini:
+ - section: pfexec_become_plugin
+ key: wrap_execution
+ vars:
+ - name: ansible_pfexec_wrap_execution
+ env:
+ - name: ANSIBLE_PFEXEC_WRAP_EXECUTION
+notes:
+ - This plugin ignores O(become_user) as pfexec uses its own C(exec_attr) to figure this out.
+"""
from ansible.plugins.become import BecomeBase
@@ -106,4 +105,4 @@ class BecomeModule(BecomeBase):
flags = self.get_option('become_flags')
noexe = not self.get_option('wrap_exe')
- return '%s %s %s' % (exe, flags, self._build_success_command(cmd, shell, noexe=noexe))
+ return f'{exe} {flags} {self._build_success_command(cmd, shell, noexe=noexe)}'
diff --git a/plugins/become/pmrun.py b/plugins/become/pmrun.py
index 908c5e759d..a2432d92ee 100644
--- a/plugins/become/pmrun.py
+++ b/plugins/become/pmrun.py
@@ -2,63 +2,62 @@
# Copyright (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: pmrun
- short_description: Privilege Manager run
- description:
- - This become plugins allows your remote/login user to execute commands as another user via the pmrun utility.
- author: Ansible Core Team
- options:
- become_exe:
- description: Sudo executable
- type: string
- default: pmrun
- ini:
- - section: privilege_escalation
- key: become_exe
- - section: pmrun_become_plugin
- key: executable
- vars:
- - name: ansible_become_exe
- - name: ansible_pmrun_exe
- env:
- - name: ANSIBLE_BECOME_EXE
- - name: ANSIBLE_PMRUN_EXE
- become_flags:
- description: Options to pass to pmrun.
- type: string
- default: ''
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: pmrun_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_pmrun_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_PMRUN_FLAGS
- become_pass:
- description: pmrun password.
- type: string
- required: false
- vars:
- - name: ansible_become_password
- - name: ansible_become_pass
- - name: ansible_pmrun_pass
- env:
- - name: ANSIBLE_BECOME_PASS
- - name: ANSIBLE_PMRUN_PASS
- ini:
- - section: pmrun_become_plugin
- key: password
- notes:
- - This plugin ignores the become_user supplied and uses pmrun's own configuration to select the user.
-'''
+DOCUMENTATION = r"""
+name: pmrun
+short_description: Privilege Manager run
+description:
+ - This become plugins allows your remote/login user to execute commands as another user using the C(pmrun) utility.
+author: Ansible Core Team
+options:
+ become_exe:
+ description: C(pmrun) executable.
+ type: string
+ default: pmrun
+ ini:
+ - section: privilege_escalation
+ key: become_exe
+ - section: pmrun_become_plugin
+ key: executable
+ vars:
+ - name: ansible_become_exe
+ - name: ansible_pmrun_exe
+ env:
+ - name: ANSIBLE_BECOME_EXE
+ - name: ANSIBLE_PMRUN_EXE
+ become_flags:
+ description: Options to pass to C(pmrun).
+ type: string
+ default: ''
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: pmrun_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_pmrun_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_PMRUN_FLAGS
+ become_pass:
+ description: C(pmrun) password.
+ type: string
+ required: false
+ vars:
+ - name: ansible_become_password
+ - name: ansible_become_pass
+ - name: ansible_pmrun_pass
+ env:
+ - name: ANSIBLE_BECOME_PASS
+ - name: ANSIBLE_PMRUN_PASS
+ ini:
+ - section: pmrun_become_plugin
+ key: password
+notes:
+ - This plugin ignores the C(become_user) supplied and uses C(pmrun)'s own configuration to select the user.
+"""
from ansible.plugins.become import BecomeBase
from ansible.module_utils.six.moves import shlex_quote
@@ -78,4 +77,4 @@ class BecomeModule(BecomeBase):
become = self.get_option('become_exe')
flags = self.get_option('become_flags')
- return '%s %s %s' % (become, flags, shlex_quote(self._build_success_command(cmd, shell)))
+ return f'{become} {flags} {shlex_quote(self._build_success_command(cmd, shell))}'
diff --git a/plugins/become/run0.py b/plugins/become/run0.py
index a718e86f24..39e4667e7a 100644
--- a/plugins/become/run0.py
+++ b/plugins/become/run0.py
@@ -3,72 +3,71 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
+from __future__ import annotations
-__metaclass__ = type
-DOCUMENTATION = """
- name: run0
- short_description: Systemd's run0
- description:
- - This become plugins allows your remote/login user to execute commands as another user via the C(run0) utility.
- author:
- - Thomas Sjögren (@konstruktoid)
- version_added: '9.0.0'
- options:
- become_user:
- description: User you 'become' to execute the task.
- default: root
- ini:
- - section: privilege_escalation
- key: become_user
- - section: run0_become_plugin
- key: user
- vars:
- - name: ansible_become_user
- - name: ansible_run0_user
- env:
- - name: ANSIBLE_BECOME_USER
- - name: ANSIBLE_RUN0_USER
- type: string
- become_exe:
- description: The C(run0) executable.
- default: run0
- ini:
- - section: privilege_escalation
- key: become_exe
- - section: run0_become_plugin
- key: executable
- vars:
- - name: ansible_become_exe
- - name: ansible_run0_exe
- env:
- - name: ANSIBLE_BECOME_EXE
- - name: ANSIBLE_RUN0_EXE
- type: string
- become_flags:
- description: Options to pass to run0.
- default: ''
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: run0_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_run0_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_RUN0_FLAGS
- type: string
- notes:
- - This plugin will only work when a polkit rule is in place.
+DOCUMENTATION = r"""
+name: run0
+short_description: Systemd's run0
+description:
+ - This become plugins allows your remote/login user to execute commands as another user using the C(run0) utility.
+author:
+ - Thomas Sjögren (@konstruktoid)
+version_added: '9.0.0'
+options:
+ become_user:
+ description: User you 'become' to execute the task.
+ default: root
+ ini:
+ - section: privilege_escalation
+ key: become_user
+ - section: run0_become_plugin
+ key: user
+ vars:
+ - name: ansible_become_user
+ - name: ansible_run0_user
+ env:
+ - name: ANSIBLE_BECOME_USER
+ - name: ANSIBLE_RUN0_USER
+ type: string
+ become_exe:
+ description: C(run0) executable.
+ default: run0
+ ini:
+ - section: privilege_escalation
+ key: become_exe
+ - section: run0_become_plugin
+ key: executable
+ vars:
+ - name: ansible_become_exe
+ - name: ansible_run0_exe
+ env:
+ - name: ANSIBLE_BECOME_EXE
+ - name: ANSIBLE_RUN0_EXE
+ type: string
+ become_flags:
+ description: Options to pass to C(run0).
+ default: ''
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: run0_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_run0_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_RUN0_FLAGS
+ type: string
+notes:
+ - This plugin will only work when a C(polkit) rule is in place.
"""
EXAMPLES = r"""
# An example polkit rule that allows the user 'ansible' in the 'wheel' group
# to execute commands using run0 without authentication.
-/etc/polkit-1/rules.d/60-run0-fast-user-auth.rules: |
+/etc/polkit-1/rules.d/60-run0-fast-user-auth.rules: |-
polkit.addRule(function(action, subject) {
if(action.id == "org.freedesktop.systemd1.manage-units" &&
subject.isInGroup("wheel") &&
diff --git a/plugins/become/sesu.py b/plugins/become/sesu.py
index 4dcb837e70..cf921e2e47 100644
--- a/plugins/become/sesu.py
+++ b/plugins/become/sesu.py
@@ -2,76 +2,75 @@
# Copyright (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: sesu
- short_description: CA Privileged Access Manager
- description:
- - This become plugins allows your remote/login user to execute commands as another user via the sesu utility.
- author: ansible (@nekonyuu)
- options:
- become_user:
- description: User you 'become' to execute the task.
- type: string
- default: ''
- ini:
- - section: privilege_escalation
- key: become_user
- - section: sesu_become_plugin
- key: user
- vars:
- - name: ansible_become_user
- - name: ansible_sesu_user
- env:
- - name: ANSIBLE_BECOME_USER
- - name: ANSIBLE_SESU_USER
- become_exe:
- description: sesu executable.
- type: string
- default: sesu
- ini:
- - section: privilege_escalation
- key: become_exe
- - section: sesu_become_plugin
- key: executable
- vars:
- - name: ansible_become_exe
- - name: ansible_sesu_exe
- env:
- - name: ANSIBLE_BECOME_EXE
- - name: ANSIBLE_SESU_EXE
- become_flags:
- description: Options to pass to sesu.
- type: string
- default: -H -S -n
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: sesu_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_sesu_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_SESU_FLAGS
- become_pass:
- description: Password to pass to sesu.
- type: string
- required: false
- vars:
- - name: ansible_become_password
- - name: ansible_become_pass
- - name: ansible_sesu_pass
- env:
- - name: ANSIBLE_BECOME_PASS
- - name: ANSIBLE_SESU_PASS
- ini:
- - section: sesu_become_plugin
- key: password
-'''
+DOCUMENTATION = r"""
+name: sesu
+short_description: CA Privileged Access Manager
+description:
+ - This become plugins allows your remote/login user to execute commands as another user using the C(sesu) utility.
+author: ansible (@nekonyuu)
+options:
+ become_user:
+ description: User you 'become' to execute the task.
+ type: string
+ default: ''
+ ini:
+ - section: privilege_escalation
+ key: become_user
+ - section: sesu_become_plugin
+ key: user
+ vars:
+ - name: ansible_become_user
+ - name: ansible_sesu_user
+ env:
+ - name: ANSIBLE_BECOME_USER
+ - name: ANSIBLE_SESU_USER
+ become_exe:
+ description: C(sesu) executable.
+ type: string
+ default: sesu
+ ini:
+ - section: privilege_escalation
+ key: become_exe
+ - section: sesu_become_plugin
+ key: executable
+ vars:
+ - name: ansible_become_exe
+ - name: ansible_sesu_exe
+ env:
+ - name: ANSIBLE_BECOME_EXE
+ - name: ANSIBLE_SESU_EXE
+ become_flags:
+ description: Options to pass to C(sesu).
+ type: string
+ default: -H -S -n
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: sesu_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_sesu_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_SESU_FLAGS
+ become_pass:
+ description: Password to pass to C(sesu).
+ type: string
+ required: false
+ vars:
+ - name: ansible_become_password
+ - name: ansible_become_pass
+ - name: ansible_sesu_pass
+ env:
+ - name: ANSIBLE_BECOME_PASS
+ - name: ANSIBLE_SESU_PASS
+ ini:
+ - section: sesu_become_plugin
+ key: password
+"""
from ansible.plugins.become import BecomeBase
@@ -93,4 +92,4 @@ class BecomeModule(BecomeBase):
flags = self.get_option('become_flags')
user = self.get_option('become_user')
- return '%s %s %s -c %s' % (become, flags, user, self._build_success_command(cmd, shell))
+ return f'{become} {flags} {user} -c {self._build_success_command(cmd, shell)}'
diff --git a/plugins/become/sudosu.py b/plugins/become/sudosu.py
index 5454fd2316..509b2725df 100644
--- a/plugins/become/sudosu.py
+++ b/plugins/become/sudosu.py
@@ -2,77 +2,77 @@
# Copyright (c) 2021, Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = """
- name: sudosu
- short_description: Run tasks using sudo su -
+DOCUMENTATION = r"""
+name: sudosu
+short_description: Run tasks using sudo su -
+description:
+ - This become plugin allows your remote/login user to execute commands as another user using the C(sudo) and C(su) utilities
+ combined.
+author:
+ - Dag Wieers (@dagwieers)
+version_added: 2.4.0
+options:
+ become_user:
+ description: User you 'become' to execute the task.
+ type: string
+ default: root
+ ini:
+ - section: privilege_escalation
+ key: become_user
+ - section: sudo_become_plugin
+ key: user
+ vars:
+ - name: ansible_become_user
+ - name: ansible_sudo_user
+ env:
+ - name: ANSIBLE_BECOME_USER
+ - name: ANSIBLE_SUDO_USER
+ become_flags:
+ description: Options to pass to C(sudo).
+ type: string
+ default: -H -S -n
+ ini:
+ - section: privilege_escalation
+ key: become_flags
+ - section: sudo_become_plugin
+ key: flags
+ vars:
+ - name: ansible_become_flags
+ - name: ansible_sudo_flags
+ env:
+ - name: ANSIBLE_BECOME_FLAGS
+ - name: ANSIBLE_SUDO_FLAGS
+ become_pass:
+ description: Password to pass to C(sudo).
+ type: string
+ required: false
+ vars:
+ - name: ansible_become_password
+ - name: ansible_become_pass
+ - name: ansible_sudo_pass
+ env:
+ - name: ANSIBLE_BECOME_PASS
+ - name: ANSIBLE_SUDO_PASS
+ ini:
+ - section: sudo_become_plugin
+ key: password
+ alt_method:
description:
- - This become plugin allows your remote/login user to execute commands as another user via the C(sudo) and C(su) utilities combined.
- author:
- - Dag Wieers (@dagwieers)
- version_added: 2.4.0
- options:
- become_user:
- description: User you 'become' to execute the task.
- type: string
- default: root
- ini:
- - section: privilege_escalation
- key: become_user
- - section: sudo_become_plugin
- key: user
- vars:
- - name: ansible_become_user
- - name: ansible_sudo_user
- env:
- - name: ANSIBLE_BECOME_USER
- - name: ANSIBLE_SUDO_USER
- become_flags:
- description: Options to pass to C(sudo).
- type: string
- default: -H -S -n
- ini:
- - section: privilege_escalation
- key: become_flags
- - section: sudo_become_plugin
- key: flags
- vars:
- - name: ansible_become_flags
- - name: ansible_sudo_flags
- env:
- - name: ANSIBLE_BECOME_FLAGS
- - name: ANSIBLE_SUDO_FLAGS
- become_pass:
- description: Password to pass to C(sudo).
- type: string
- required: false
- vars:
- - name: ansible_become_password
- - name: ansible_become_pass
- - name: ansible_sudo_pass
- env:
- - name: ANSIBLE_BECOME_PASS
- - name: ANSIBLE_SUDO_PASS
- ini:
- - section: sudo_become_plugin
- key: password
- alt_method:
- description:
- - Whether to use an alternative method to call C(su). Instead of running C(su -l user /path/to/shell -c command),
- it runs C(su -l user -c command).
- - Use this when the default one is not working on your system.
- required: false
- type: boolean
- ini:
- - section: community.general.sudosu
- key: alternative_method
- vars:
- - name: ansible_sudosu_alt_method
- env:
- - name: ANSIBLE_SUDOSU_ALT_METHOD
- version_added: 9.2.0
+ - Whether to use an alternative method to call C(su). Instead of running C(su -l user /path/to/shell -c command), it
+ runs C(su -l user -c command).
+ - Use this when the default one is not working on your system.
+ required: false
+ type: boolean
+ ini:
+ - section: community.general.sudosu
+ key: alternative_method
+ vars:
+ - name: ansible_sudosu_alt_method
+ env:
+ - name: ANSIBLE_SUDOSU_ALT_METHOD
+ version_added: 9.2.0
"""
@@ -98,16 +98,16 @@ class BecomeModule(BecomeBase):
flags = self.get_option('become_flags') or ''
prompt = ''
if self.get_option('become_pass'):
- self.prompt = '[sudo via ansible, key=%s] password:' % self._id
+ self.prompt = f'[sudo via ansible, key={self._id}] password:'
if flags: # this could be simplified, but kept as is for now for backwards string matching
flags = flags.replace('-n', '')
- prompt = '-p "%s"' % (self.prompt)
+ prompt = f'-p "{self.prompt}"'
user = self.get_option('become_user') or ''
if user:
- user = '%s' % (user)
+ user = f'{user}'
if self.get_option('alt_method'):
- return ' '.join([becomecmd, flags, prompt, "su -l", user, "-c", self._build_success_command(cmd, shell, True)])
+ return f"{becomecmd} {flags} {prompt} su -l {user} -c {self._build_success_command(cmd, shell, True)}"
else:
- return ' '.join([becomecmd, flags, prompt, 'su -l', user, self._build_success_command(cmd, shell)])
+ return f"{becomecmd} {flags} {prompt} su -l {user} {self._build_success_command(cmd, shell)}"
diff --git a/plugins/cache/memcached.py b/plugins/cache/memcached.py
index 93131172c5..9c4fbec595 100644
--- a/plugins/cache/memcached.py
+++ b/plugins/cache/memcached.py
@@ -4,49 +4,48 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: memcached
- short_description: Use memcached DB for cache
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: memcached
+short_description: Use memcached DB for cache
+description:
+ - This cache uses JSON formatted, per host records saved in memcached.
+requirements:
+ - memcache (python lib)
+options:
+ _uri:
description:
- - This cache uses JSON formatted, per host records saved in memcached.
- requirements:
- - memcache (python lib)
- options:
- _uri:
- description:
- - 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:
- - key: fact_caching_connection
- section: defaults
- _prefix:
- description: User defined prefix to use when creating the DB entries
- type: string
- default: ansible_facts
- env:
- - name: ANSIBLE_CACHE_PLUGIN_PREFIX
- ini:
- - key: fact_caching_prefix
- section: defaults
- _timeout:
- default: 86400
- type: integer
+ - 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:
+ - key: fact_caching_connection
+ section: defaults
+ _prefix:
+ description: User defined prefix to use when creating the DB entries.
+ type: string
+ default: ansible_facts
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+ ini:
+ - key: fact_caching_prefix
+ section: defaults
+ _timeout:
+ default: 86400
+ type: integer
# TODO: determine whether it is OK to change to: type: float
- description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire
- env:
- - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
- ini:
- - key: fact_caching_timeout
- section: defaults
-'''
+ description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire.
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+ ini:
+ - key: fact_caching_timeout
+ section: defaults
+"""
import collections
import os
@@ -191,7 +190,7 @@ class CacheModule(BaseCacheModule):
self._keys = CacheModuleKeys(self._db, self._db.get(CacheModuleKeys.PREFIX) or [])
def _make_key(self, key):
- return "{0}{1}".format(self._prefix, key)
+ return f"{self._prefix}{key}"
def _expire_keys(self):
if self._timeout > 0:
diff --git a/plugins/cache/pickle.py b/plugins/cache/pickle.py
index aeffa68939..2f4b2b7b02 100644
--- a/plugins/cache/pickle.py
+++ b/plugins/cache/pickle.py
@@ -5,44 +5,43 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: pickle
- short_description: Pickle formatted files.
+DOCUMENTATION = r"""
+name: pickle
+short_description: Pickle formatted files
+description:
+ - This cache uses Python's pickle serialization format, in per host files, saved to the filesystem.
+author: Brian Coca (@bcoca)
+options:
+ _uri:
+ required: true
description:
- - This cache uses Python's pickle serialization format, in per host files, saved to the filesystem.
- author: Brian Coca (@bcoca)
- options:
- _uri:
- required: true
- description:
- - Path in which the cache plugin will save the files
- env:
- - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
- ini:
- - key: fact_caching_connection
- section: defaults
- type: path
- _prefix:
- description: User defined prefix to use when creating the files
- env:
- - name: ANSIBLE_CACHE_PLUGIN_PREFIX
- ini:
- - key: fact_caching_prefix
- section: defaults
- type: string
- _timeout:
- default: 86400
- description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire
- env:
- - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
- ini:
- - key: fact_caching_timeout
- section: defaults
- type: float
-'''
+ - Path in which the cache plugin will save the files.
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
+ ini:
+ - key: fact_caching_connection
+ section: defaults
+ type: path
+ _prefix:
+ description: User defined prefix to use when creating the files.
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+ ini:
+ - key: fact_caching_prefix
+ section: defaults
+ type: string
+ _timeout:
+ default: 86400
+ description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire.
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+ ini:
+ - key: fact_caching_timeout
+ section: defaults
+ type: float
+"""
try:
import cPickle as pickle
diff --git a/plugins/cache/redis.py b/plugins/cache/redis.py
index f96aafaa84..41f69d659f 100644
--- a/plugins/cache/redis.py
+++ b/plugins/cache/redis.py
@@ -3,77 +3,75 @@
# Copyright (c) 2017 Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: redis
- short_description: Use Redis DB for cache
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: redis
+short_description: Use Redis DB for cache
+description:
+ - This cache uses JSON formatted, per host records saved in Redis.
+requirements:
+ - redis>=2.4.5 (python lib)
+options:
+ _uri:
description:
- - This cache uses JSON formatted, per host records saved in Redis.
- requirements:
- - redis>=2.4.5 (python lib)
- options:
- _uri:
- description:
- - A colon separated string of connection information for Redis.
- - The format is V(host:port:db:password), for example V(localhost:6379:0:changeme).
- - To use encryption in transit, prefix the connection with V(tls://), as in V(tls://localhost:6379:0:changeme).
- - To use redis sentinel, use separator V(;), for example V(localhost:26379;localhost:26379;0:changeme). Requires redis>=2.9.0.
- type: string
- required: true
- env:
- - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
- ini:
- - key: fact_caching_connection
- section: defaults
- _prefix:
- description: User defined prefix to use when creating the DB entries
- type: string
- default: ansible_facts
- env:
- - name: ANSIBLE_CACHE_PLUGIN_PREFIX
- ini:
- - key: fact_caching_prefix
- section: defaults
- _keyset_name:
- description: User defined name for cache keyset name.
- type: string
- default: ansible_cache_keys
- env:
- - name: ANSIBLE_CACHE_REDIS_KEYSET_NAME
- ini:
- - key: fact_caching_redis_keyset_name
- section: defaults
- version_added: 1.3.0
- _sentinel_service_name:
- description: The redis sentinel service name (or referenced as cluster name).
- type: string
- env:
- - name: ANSIBLE_CACHE_REDIS_SENTINEL
- ini:
- - key: fact_caching_redis_sentinel
- section: defaults
- version_added: 1.3.0
- _timeout:
- default: 86400
- type: integer
+ - A colon separated string of connection information for Redis.
+ - The format is V(host:port:db:password), for example V(localhost:6379:0:changeme).
+ - To use encryption in transit, prefix the connection with V(tls://), as in V(tls://localhost:6379:0:changeme).
+ - To use redis sentinel, use separator V(;), for example V(localhost:26379;localhost:26379;0:changeme). Requires redis>=2.9.0.
+ type: string
+ required: true
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
+ ini:
+ - key: fact_caching_connection
+ section: defaults
+ _prefix:
+ description: User defined prefix to use when creating the DB entries.
+ type: string
+ default: ansible_facts
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+ ini:
+ - key: fact_caching_prefix
+ section: defaults
+ _keyset_name:
+ description: User defined name for cache keyset name.
+ type: string
+ default: ansible_cache_keys
+ env:
+ - name: ANSIBLE_CACHE_REDIS_KEYSET_NAME
+ ini:
+ - key: fact_caching_redis_keyset_name
+ section: defaults
+ version_added: 1.3.0
+ _sentinel_service_name:
+ description: The redis sentinel service name (or referenced as cluster name).
+ type: string
+ env:
+ - name: ANSIBLE_CACHE_REDIS_SENTINEL
+ ini:
+ - key: fact_caching_redis_sentinel
+ section: defaults
+ version_added: 1.3.0
+ _timeout:
+ default: 86400
+ type: integer
# TODO: determine whether it is OK to change to: type: float
- description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire
- env:
- - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
- ini:
- - key: fact_caching_timeout
- section: defaults
-'''
+ description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire.
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+ ini:
+ - key: fact_caching_timeout
+ section: defaults
+"""
import re
import time
import json
from ansible.errors import AnsibleError
-from ansible.module_utils.common.text.converters import to_native
from ansible.parsing.ajson import AnsibleJSONEncoder, AnsibleJSONDecoder
from ansible.plugins.cache import BaseCacheModule
from ansible.utils.display import Display
@@ -131,7 +129,7 @@ class CacheModule(BaseCacheModule):
connection = self._parse_connection(self.re_url_conn, uri)
self._db = StrictRedis(*connection, **kw)
- display.vv('Redis connection: %s' % self._db)
+ display.vv(f'Redis connection: {self._db}')
@staticmethod
def _parse_connection(re_patt, uri):
@@ -164,12 +162,12 @@ class CacheModule(BaseCacheModule):
pass # password is optional
sentinels = [self._parse_connection(self.re_sent_conn, shost) for shost in connections]
- display.vv('\nUsing redis sentinels: %s' % sentinels)
+ display.vv(f'\nUsing redis sentinels: {sentinels}')
scon = Sentinel(sentinels, **kw)
try:
return scon.master_for(self._sentinel_service_name, socket_timeout=0.2)
except Exception as exc:
- raise AnsibleError('Could not connect to redis sentinel: %s' % to_native(exc))
+ raise AnsibleError(f'Could not connect to redis sentinel: {exc}')
def _make_key(self, key):
return self._prefix + key
diff --git a/plugins/cache/yaml.py b/plugins/cache/yaml.py
index a3d6f34521..676423d3b6 100644
--- a/plugins/cache/yaml.py
+++ b/plugins/cache/yaml.py
@@ -5,45 +5,44 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: yaml
- short_description: YAML formatted files.
+DOCUMENTATION = r"""
+name: yaml
+short_description: YAML formatted files
+description:
+ - This cache uses YAML formatted, per host, files saved to the filesystem.
+author: Brian Coca (@bcoca)
+options:
+ _uri:
+ required: true
description:
- - This cache uses YAML formatted, per host, files saved to the filesystem.
- author: Brian Coca (@bcoca)
- options:
- _uri:
- required: true
- description:
- - Path in which the cache plugin will save the files
- env:
- - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
- ini:
- - key: fact_caching_connection
- section: defaults
- type: string
- _prefix:
- description: User defined prefix to use when creating the files
- env:
- - name: ANSIBLE_CACHE_PLUGIN_PREFIX
- ini:
- - key: fact_caching_prefix
- section: defaults
- type: string
- _timeout:
- default: 86400
- description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire
- env:
- - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
- ini:
- - key: fact_caching_timeout
- section: defaults
- type: integer
+ - Path in which the cache plugin will save the files.
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
+ ini:
+ - key: fact_caching_connection
+ section: defaults
+ type: string
+ _prefix:
+ description: User defined prefix to use when creating the files.
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+ ini:
+ - key: fact_caching_prefix
+ section: defaults
+ type: string
+ _timeout:
+ default: 86400
+ description: Expiration timeout in seconds for the cache plugin data. Set to 0 to never expire.
+ env:
+ - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+ ini:
+ - key: fact_caching_timeout
+ section: defaults
+ type: integer
# TODO: determine whether it is OK to change to: type: float
-'''
+"""
import codecs
diff --git a/plugins/callback/cgroup_memory_recap.py b/plugins/callback/cgroup_memory_recap.py
index 643f0f0b88..b4099eae49 100644
--- a/plugins/callback/cgroup_memory_recap.py
+++ b/plugins/callback/cgroup_memory_recap.py
@@ -4,43 +4,43 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: cgroup_memory_recap
- type: aggregate
- requirements:
- - whitelist in configuration
- - cgroups
- short_description: Profiles maximum memory usage of tasks and full execution using cgroups
- description:
- - This is an ansible callback plugin that profiles maximum memory usage of ansible and individual tasks, and displays a recap at the end using cgroups.
- notes:
- - Requires ansible to be run from within a cgroup, such as with C(cgexec -g memory:ansible_profile ansible-playbook ...).
- - This cgroup should only be used by ansible to get accurate results.
- - To create the cgroup, first use a command such as C(sudo cgcreate -a ec2-user:ec2-user -t ec2-user:ec2-user -g memory:ansible_profile).
- options:
- max_mem_file:
- required: true
- description: Path to cgroups C(memory.max_usage_in_bytes) file. Example V(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes).
- type: str
- env:
- - name: CGROUP_MAX_MEM_FILE
- ini:
- - section: callback_cgroupmemrecap
- key: max_mem_file
- cur_mem_file:
- required: true
- description: Path to C(memory.usage_in_bytes) file. Example V(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes).
- type: str
- env:
- - name: CGROUP_CUR_MEM_FILE
- ini:
- - section: callback_cgroupmemrecap
- key: cur_mem_file
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: cgroup_memory_recap
+type: aggregate
+requirements:
+ - whitelist in configuration
+ - cgroups
+short_description: Profiles maximum memory usage of tasks and full execution using cgroups
+description:
+ - This is an Ansible callback plugin that profiles maximum memory usage of Ansible and individual tasks, and displays a
+ recap at the end using cgroups.
+notes:
+ - Requires ansible to be run from within a C(cgroup), such as with C(cgexec -g memory:ansible_profile ansible-playbook ...).
+ - This C(cgroup) should only be used by Ansible to get accurate results.
+ - To create the C(cgroup), first use a command such as C(sudo cgcreate -a ec2-user:ec2-user -t ec2-user:ec2-user -g memory:ansible_profile).
+options:
+ max_mem_file:
+ required: true
+ description: Path to cgroups C(memory.max_usage_in_bytes) file. Example V(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes).
+ type: str
+ env:
+ - name: CGROUP_MAX_MEM_FILE
+ ini:
+ - section: callback_cgroupmemrecap
+ key: max_mem_file
+ cur_mem_file:
+ required: true
+ description: Path to C(memory.usage_in_bytes) file. Example V(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes).
+ type: str
+ env:
+ - name: CGROUP_CUR_MEM_FILE
+ ini:
+ - section: callback_cgroupmemrecap
+ key: cur_mem_file
+"""
import time
import threading
@@ -114,7 +114,7 @@ class CallbackModule(CallbackBase):
max_results = int(f.read().strip()) / 1024 / 1024
self._display.banner('CGROUP MEMORY RECAP')
- self._display.display('Execution Maximum: %0.2fMB\n\n' % max_results)
+ self._display.display(f'Execution Maximum: {max_results:0.2f}MB\n\n')
for task, memory in self.task_results:
- self._display.display('%s (%s): %0.2fMB' % (task.get_name(), task._uuid, memory))
+ self._display.display(f'{task.get_name()} ({task._uuid}): {memory:0.2f}MB')
diff --git a/plugins/callback/context_demo.py b/plugins/callback/context_demo.py
index b9558fc064..28be2882b6 100644
--- a/plugins/callback/context_demo.py
+++ b/plugins/callback/context_demo.py
@@ -4,20 +4,19 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: context_demo
- type: aggregate
- short_description: demo callback that adds play/task context
- description:
- - Displays some play and task context along with normal output.
- - This is mostly for demo purposes.
- requirements:
- - whitelist in configuration
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: context_demo
+type: aggregate
+short_description: demo callback that adds play/task context
+description:
+ - Displays some play and task context along with normal output.
+ - This is mostly for demo purposes.
+requirements:
+ - whitelist in configuration
+"""
from ansible.plugins.callback import CallbackBase
@@ -38,15 +37,15 @@ class CallbackModule(CallbackBase):
self.play = None
def v2_on_any(self, *args, **kwargs):
- self._display.display("--- play: {0} task: {1} ---".format(getattr(self.play, 'name', None), self.task))
+ self._display.display(f"--- play: {getattr(self.play, 'name', None)} task: {self.task} ---")
self._display.display(" --- ARGS ")
for i, a in enumerate(args):
- self._display.display(' %s: %s' % (i, a))
+ self._display.display(f' {i}: {a}')
self._display.display(" --- KWARGS ")
for k in kwargs:
- self._display.display(' %s: %s' % (k, kwargs[k]))
+ self._display.display(f' {k}: {kwargs[k]}')
def v2_playbook_on_play_start(self, play):
self.play = play
diff --git a/plugins/callback/counter_enabled.py b/plugins/callback/counter_enabled.py
index 27adc97a6c..15fc85a01b 100644
--- a/plugins/callback/counter_enabled.py
+++ b/plugins/callback/counter_enabled.py
@@ -6,23 +6,22 @@
Counter enabled Ansible callback plugin (See DOCUMENTATION for more information)
'''
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: counter_enabled
- type: stdout
- short_description: adds counters to the output items (tasks and hosts/task)
- description:
- - Use this callback when you need a kind of progress bar on a large environments.
- - You will know how many tasks has the playbook to run, and which one is actually running.
- - You will know how many hosts may run a task, and which of them is actually running.
- extends_documentation_fragment:
- - default_callback
- requirements:
- - set as stdout callback in C(ansible.cfg) (C(stdout_callback = counter_enabled))
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: counter_enabled
+type: stdout
+short_description: adds counters to the output items (tasks and hosts/task)
+description:
+ - Use this callback when you need a kind of progress bar on a large environments.
+ - You will know how many tasks has the playbook to run, and which one is actually running.
+ - You will know how many hosts may run a task, and which of them is actually running.
+extends_documentation_fragment:
+ - default_callback
+requirements:
+ - set as stdout callback in C(ansible.cfg) (C(stdout_callback = counter_enabled))
+"""
from ansible import constants as C
from ansible.plugins.callback import CallbackBase
@@ -71,7 +70,7 @@ class CallbackModule(CallbackBase):
if not name:
msg = u"play"
else:
- msg = u"PLAY [%s]" % name
+ msg = f"PLAY [{name}]"
self._play = play
@@ -91,25 +90,17 @@ class CallbackModule(CallbackBase):
for host in hosts:
stat = stats.summarize(host)
- self._display.display(u"%s : %s %s %s %s %s %s" % (
- hostcolor(host, stat),
- colorize(u'ok', stat['ok'], C.COLOR_OK),
- colorize(u'changed', stat['changed'], C.COLOR_CHANGED),
- colorize(u'unreachable', stat['unreachable'], C.COLOR_UNREACHABLE),
- colorize(u'failed', stat['failures'], C.COLOR_ERROR),
- colorize(u'rescued', stat['rescued'], C.COLOR_OK),
- colorize(u'ignored', stat['ignored'], C.COLOR_WARN)),
+ self._display.display(
+ f"{hostcolor(host, stat)} : {colorize('ok', stat['ok'], C.COLOR_OK)} {colorize('changed', stat['changed'], C.COLOR_CHANGED)} "
+ f"{colorize('unreachable', stat['unreachable'], C.COLOR_UNREACHABLE)} {colorize('failed', stat['failures'], C.COLOR_ERROR)} "
+ f"{colorize('rescued', stat['rescued'], C.COLOR_OK)} {colorize('ignored', stat['ignored'], C.COLOR_WARN)}",
screen_only=True
)
- self._display.display(u"%s : %s %s %s %s %s %s" % (
- hostcolor(host, stat, False),
- colorize(u'ok', stat['ok'], None),
- colorize(u'changed', stat['changed'], None),
- colorize(u'unreachable', stat['unreachable'], None),
- colorize(u'failed', stat['failures'], None),
- colorize(u'rescued', stat['rescued'], None),
- colorize(u'ignored', stat['ignored'], None)),
+ self._display.display(
+ f"{hostcolor(host, stat, False)} : {colorize('ok', stat['ok'], None)} {colorize('changed', stat['changed'], None)} "
+ f"{colorize('unreachable', stat['unreachable'], None)} {colorize('failed', stat['failures'], None)} "
+ f"{colorize('rescued', stat['rescued'], None)} {colorize('ignored', stat['ignored'], None)}",
log_only=True
)
@@ -124,12 +115,14 @@ class CallbackModule(CallbackBase):
for k in sorted(stats.custom.keys()):
if k == '_run':
continue
- self._display.display('\t%s: %s' % (k, self._dump_results(stats.custom[k], indent=1).replace('\n', '')))
+ _custom_stats = self._dump_results(stats.custom[k], indent=1).replace('\n', '')
+ self._display.display(f'\t{k}: {_custom_stats}')
# print per run custom stats
if '_run' in stats.custom:
self._display.display("", screen_only=True)
- self._display.display('\tRUN: %s' % self._dump_results(stats.custom['_run'], indent=1).replace('\n', ''))
+ _custom_stats_run = self._dump_results(stats.custom['_run'], indent=1).replace('\n', '')
+ self._display.display(f'\tRUN: {_custom_stats_run}')
self._display.display("", screen_only=True)
def v2_playbook_on_task_start(self, task, is_conditional):
@@ -143,13 +136,13 @@ class CallbackModule(CallbackBase):
# that they can secure this if they feel that their stdout is insecure
# (shoulder surfing, logging stdout straight to a file, etc).
if not task.no_log and C.DISPLAY_ARGS_TO_STDOUT:
- args = ', '.join(('%s=%s' % a for a in task.args.items()))
- args = ' %s' % args
- self._display.banner("TASK %d/%d [%s%s]" % (self._task_counter, self._task_total, task.get_name().strip(), args))
+ args = ', '.join(('{k}={v}' for k, v in task.args.items()))
+ args = f' {args}'
+ self._display.banner(f"TASK {self._task_counter}/{self._task_total} [{task.get_name().strip()}{args}]")
if self._display.verbosity >= 2:
path = task.get_path()
if path:
- self._display.display("task path: %s" % path, color=C.COLOR_DEBUG)
+ self._display.display(f"task path: {path}", color=C.COLOR_DEBUG)
self._host_counter = self._previous_batch_total
self._task_counter += 1
@@ -166,15 +159,15 @@ class CallbackModule(CallbackBase):
return
elif result._result.get('changed', False):
if delegated_vars:
- msg = "changed: %d/%d [%s -> %s]" % (self._host_counter, self._host_total, result._host.get_name(), delegated_vars['ansible_host'])
+ msg = f"changed: {self._host_counter}/{self._host_total} [{result._host.get_name()} -> {delegated_vars['ansible_host']}]"
else:
- msg = "changed: %d/%d [%s]" % (self._host_counter, self._host_total, result._host.get_name())
+ msg = f"changed: {self._host_counter}/{self._host_total} [{result._host.get_name()}]"
color = C.COLOR_CHANGED
else:
if delegated_vars:
- msg = "ok: %d/%d [%s -> %s]" % (self._host_counter, self._host_total, result._host.get_name(), delegated_vars['ansible_host'])
+ msg = f"ok: {self._host_counter}/{self._host_total} [{result._host.get_name()} -> {delegated_vars['ansible_host']}]"
else:
- msg = "ok: %d/%d [%s]" % (self._host_counter, self._host_total, result._host.get_name())
+ msg = f"ok: {self._host_counter}/{self._host_total} [{result._host.get_name()}]"
color = C.COLOR_OK
self._handle_warnings(result._result)
@@ -185,7 +178,7 @@ class CallbackModule(CallbackBase):
self._clean_results(result._result, result._task.action)
if self._run_is_verbose(result):
- msg += " => %s" % (self._dump_results(result._result),)
+ msg += f" => {self._dump_results(result._result)}"
self._display.display(msg, color=color)
def v2_runner_on_failed(self, result, ignore_errors=False):
@@ -206,14 +199,16 @@ class CallbackModule(CallbackBase):
else:
if delegated_vars:
- self._display.display("fatal: %d/%d [%s -> %s]: FAILED! => %s" % (self._host_counter, self._host_total,
- result._host.get_name(), delegated_vars['ansible_host'],
- self._dump_results(result._result)),
- color=C.COLOR_ERROR)
+ self._display.display(
+ f"fatal: {self._host_counter}/{self._host_total} [{result._host.get_name()} -> "
+ f"{delegated_vars['ansible_host']}]: FAILED! => {self._dump_results(result._result)}",
+ color=C.COLOR_ERROR
+ )
else:
- self._display.display("fatal: %d/%d [%s]: FAILED! => %s" % (self._host_counter, self._host_total,
- result._host.get_name(), self._dump_results(result._result)),
- color=C.COLOR_ERROR)
+ self._display.display(
+ f"fatal: {self._host_counter}/{self._host_total} [{result._host.get_name()}]: FAILED! => {self._dump_results(result._result)}",
+ color=C.COLOR_ERROR
+ )
if ignore_errors:
self._display.display("...ignoring", color=C.COLOR_SKIP)
@@ -231,9 +226,9 @@ class CallbackModule(CallbackBase):
if result._task.loop and 'results' in result._result:
self._process_items(result)
else:
- msg = "skipping: %d/%d [%s]" % (self._host_counter, self._host_total, result._host.get_name())
+ msg = f"skipping: {self._host_counter}/{self._host_total} [{result._host.get_name()}]"
if self._run_is_verbose(result):
- msg += " => %s" % self._dump_results(result._result)
+ msg += f" => {self._dump_results(result._result)}"
self._display.display(msg, color=C.COLOR_SKIP)
def v2_runner_on_unreachable(self, result):
@@ -244,11 +239,13 @@ class CallbackModule(CallbackBase):
delegated_vars = result._result.get('_ansible_delegated_vars', None)
if delegated_vars:
- self._display.display("fatal: %d/%d [%s -> %s]: UNREACHABLE! => %s" % (self._host_counter, self._host_total,
- result._host.get_name(), delegated_vars['ansible_host'],
- self._dump_results(result._result)),
- color=C.COLOR_UNREACHABLE)
+ self._display.display(
+ f"fatal: {self._host_counter}/{self._host_total} [{result._host.get_name()} -> "
+ f"{delegated_vars['ansible_host']}]: UNREACHABLE! => {self._dump_results(result._result)}",
+ color=C.COLOR_UNREACHABLE
+ )
else:
- self._display.display("fatal: %d/%d [%s]: UNREACHABLE! => %s" % (self._host_counter, self._host_total,
- result._host.get_name(), self._dump_results(result._result)),
- color=C.COLOR_UNREACHABLE)
+ self._display.display(
+ f"fatal: {self._host_counter}/{self._host_total} [{result._host.get_name()}]: UNREACHABLE! => {self._dump_results(result._result)}",
+ color=C.COLOR_UNREACHABLE
+ )
diff --git a/plugins/callback/default_without_diff.py b/plugins/callback/default_without_diff.py
index c138cd4455..3ea55100bf 100644
--- a/plugins/callback/default_without_diff.py
+++ b/plugins/callback/default_without_diff.py
@@ -4,35 +4,33 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = r'''
- name: default_without_diff
- type: stdout
- short_description: The default ansible callback without diff output
- version_added: 8.4.0
- description:
- - This is basically the default ansible callback plugin (P(ansible.builtin.default#callback)) without
- showing diff output. This can be useful when using another callback which sends more detailed information
- to another service, like the L(ARA, https://ara.recordsansible.org/) callback, and you want diff output
- sent to that plugin but not shown on the console output.
- author: Felix Fontein (@felixfontein)
- extends_documentation_fragment:
- - ansible.builtin.default_callback
- - ansible.builtin.result_format_callback
-'''
+DOCUMENTATION = r"""
+name: default_without_diff
+type: stdout
+short_description: The default ansible callback without diff output
+version_added: 8.4.0
+description:
+ - This is basically the default ansible callback plugin (P(ansible.builtin.default#callback)) without showing diff output.
+ This can be useful when using another callback which sends more detailed information to another service, like the L(ARA,
+ https://ara.recordsansible.org/) callback, and you want diff output sent to that plugin but not shown on the console output.
+author: Felix Fontein (@felixfontein)
+extends_documentation_fragment:
+ - ansible.builtin.default_callback
+ - ansible.builtin.result_format_callback
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
# Enable callback in ansible.cfg:
ansible_config: |
[defaults]
stdout_callback = community.general.default_without_diff
# Enable callback with environment variables:
-environment_variable: |
+environment_variable: |-
ANSIBLE_STDOUT_CALLBACK=community.general.default_without_diff
-'''
+"""
from ansible.plugins.callback.default import CallbackModule as Default
diff --git a/plugins/callback/dense.py b/plugins/callback/dense.py
index 490705fd27..67cad4fd8f 100644
--- a/plugins/callback/dense.py
+++ b/plugins/callback/dense.py
@@ -4,22 +4,21 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
name: dense
type: stdout
short_description: minimal stdout output
extends_documentation_fragment:
-- default_callback
+ - default_callback
description:
-- When in verbose mode it will act the same as the default callback.
+ - When in verbose mode it will act the same as the default callback.
author:
-- Dag Wieers (@dagwieers)
+ - Dag Wieers (@dagwieers)
requirements:
-- set as stdout in configuration
-'''
+ - set as stdout in configuration
+"""
HAS_OD = False
try:
@@ -195,7 +194,7 @@ class CallbackModule(CallbackModule_default):
self.disabled = True
def __del__(self):
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline)
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}")
def _add_host(self, result, status):
name = result._host.get_name()
@@ -243,7 +242,7 @@ class CallbackModule(CallbackModule_default):
def _handle_exceptions(self, result):
if 'exception' in result:
- # Remove the exception from the result so it's not shown every time
+ # Remove the exception from the result so it is not shown every time
del result['exception']
if self._display.verbosity == 1:
@@ -252,7 +251,7 @@ class CallbackModule(CallbackModule_default):
def _display_progress(self, result=None):
# Always rewrite the complete line
sys.stdout.write(vt100.restore + vt100.reset + vt100.clearline + vt100.nolinewrap + vt100.underline)
- sys.stdout.write('%s %d:' % (self.type, self.count[self.type]))
+ sys.stdout.write(f'{self.type} {self.count[self.type]}:')
sys.stdout.write(vt100.reset)
sys.stdout.flush()
@@ -260,7 +259,7 @@ class CallbackModule(CallbackModule_default):
for name in self.hosts:
sys.stdout.write(' ')
if self.hosts[name].get('delegate', None):
- sys.stdout.write(self.hosts[name]['delegate'] + '>')
+ sys.stdout.write(f"{self.hosts[name]['delegate']}>")
sys.stdout.write(colors[self.hosts[name]['state']] + name + vt100.reset)
sys.stdout.flush()
@@ -274,8 +273,8 @@ class CallbackModule(CallbackModule_default):
if not self.shown_title:
self.shown_title = True
sys.stdout.write(vt100.restore + vt100.reset + vt100.clearline + vt100.underline)
- sys.stdout.write('%s %d: %s' % (self.type, self.count[self.type], self.task.get_name().strip()))
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline)
+ sys.stdout.write(f'{self.type} {self.count[self.type]}: {self.task.get_name().strip()}')
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}")
sys.stdout.flush()
else:
sys.stdout.write(vt100.restore + vt100.reset + vt100.clearline)
@@ -284,7 +283,7 @@ class CallbackModule(CallbackModule_default):
def _display_results(self, result, status):
# Leave the previous task on screen (as it has changes/errors)
if self._display.verbosity == 0 and self.keep:
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline)
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}")
else:
sys.stdout.write(vt100.restore + vt100.reset + vt100.clearline)
self.keep = False
@@ -309,15 +308,15 @@ class CallbackModule(CallbackModule_default):
if result._task.loop and 'results' in result._result:
self._process_items(result)
else:
- sys.stdout.write(colors[status] + status + ': ')
+ sys.stdout.write(f"{colors[status] + status}: ")
delegated_vars = result._result.get('_ansible_delegated_vars', None)
if delegated_vars:
- sys.stdout.write(vt100.reset + result._host.get_name() + '>' + colors[status] + delegated_vars['ansible_host'])
+ sys.stdout.write(f"{vt100.reset + result._host.get_name()}>{colors[status]}{delegated_vars['ansible_host']}")
else:
sys.stdout.write(result._host.get_name())
- sys.stdout.write(': ' + dump + '\n')
+ sys.stdout.write(f": {dump}\n")
sys.stdout.write(vt100.reset + vt100.save + vt100.clearline)
sys.stdout.flush()
@@ -327,7 +326,7 @@ class CallbackModule(CallbackModule_default):
def v2_playbook_on_play_start(self, play):
# Leave the previous task on screen (as it has changes/errors)
if self._display.verbosity == 0 and self.keep:
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline + vt100.bold)
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}{vt100.bold}")
else:
sys.stdout.write(vt100.restore + vt100.reset + vt100.clearline + vt100.bold)
@@ -341,14 +340,14 @@ class CallbackModule(CallbackModule_default):
name = play.get_name().strip()
if not name:
name = 'unnamed'
- sys.stdout.write('PLAY %d: %s' % (self.count['play'], name.upper()))
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline)
+ sys.stdout.write(f"PLAY {self.count['play']}: {name.upper()}")
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}")
sys.stdout.flush()
def v2_playbook_on_task_start(self, task, is_conditional):
# Leave the previous task on screen (as it has changes/errors)
if self._display.verbosity == 0 and self.keep:
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline + vt100.underline)
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}{vt100.underline}")
else:
# Do not clear line, since we want to retain the previous output
sys.stdout.write(vt100.restore + vt100.reset + vt100.underline)
@@ -365,14 +364,14 @@ class CallbackModule(CallbackModule_default):
self.count['task'] += 1
# Write the next task on screen (behind the prompt is the previous output)
- sys.stdout.write('%s %d.' % (self.type, self.count[self.type]))
+ sys.stdout.write(f'{self.type} {self.count[self.type]}.')
sys.stdout.write(vt100.reset)
sys.stdout.flush()
def v2_playbook_on_handler_task_start(self, task):
# Leave the previous task on screen (as it has changes/errors)
if self._display.verbosity == 0 and self.keep:
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline + vt100.underline)
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}{vt100.underline}")
else:
sys.stdout.write(vt100.restore + vt100.reset + vt100.clearline + vt100.underline)
@@ -388,7 +387,7 @@ class CallbackModule(CallbackModule_default):
self.count[self.type] += 1
# Write the next task on screen (behind the prompt is the previous output)
- sys.stdout.write('%s %d.' % (self.type, self.count[self.type]))
+ sys.stdout.write(f'{self.type} {self.count[self.type]}.')
sys.stdout.write(vt100.reset)
sys.stdout.flush()
@@ -451,13 +450,13 @@ class CallbackModule(CallbackModule_default):
def v2_playbook_on_no_hosts_remaining(self):
if self._display.verbosity == 0 and self.keep:
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline)
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}")
else:
sys.stdout.write(vt100.restore + vt100.reset + vt100.clearline)
self.keep = False
- sys.stdout.write(vt100.white + vt100.redbg + 'NO MORE HOSTS LEFT')
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline)
+ sys.stdout.write(f"{vt100.white + vt100.redbg}NO MORE HOSTS LEFT")
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}")
sys.stdout.flush()
def v2_playbook_on_include(self, included_file):
@@ -465,7 +464,7 @@ class CallbackModule(CallbackModule_default):
def v2_playbook_on_stats(self, stats):
if self._display.verbosity == 0 and self.keep:
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline)
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}")
else:
sys.stdout.write(vt100.restore + vt100.reset + vt100.clearline)
@@ -476,22 +475,16 @@ class CallbackModule(CallbackModule_default):
sys.stdout.write(vt100.bold + vt100.underline)
sys.stdout.write('SUMMARY')
- sys.stdout.write(vt100.restore + vt100.reset + '\n' + vt100.save + vt100.clearline)
+ sys.stdout.write(f"{vt100.restore}{vt100.reset}\n{vt100.save}{vt100.clearline}")
sys.stdout.flush()
hosts = sorted(stats.processed.keys())
for h in hosts:
t = stats.summarize(h)
self._display.display(
- u"%s : %s %s %s %s %s %s" % (
- hostcolor(h, t),
- colorize(u'ok', t['ok'], C.COLOR_OK),
- colorize(u'changed', t['changed'], C.COLOR_CHANGED),
- colorize(u'unreachable', t['unreachable'], C.COLOR_UNREACHABLE),
- colorize(u'failed', t['failures'], C.COLOR_ERROR),
- colorize(u'rescued', t['rescued'], C.COLOR_OK),
- colorize(u'ignored', t['ignored'], C.COLOR_WARN),
- ),
+ f"{hostcolor(h, t)} : {colorize('ok', t['ok'], C.COLOR_OK)} {colorize('changed', t['changed'], C.COLOR_CHANGED)} "
+ f"{colorize('unreachable', t['unreachable'], C.COLOR_UNREACHABLE)} {colorize('failed', t['failures'], C.COLOR_ERROR)} "
+ f"{colorize('rescued', t['rescued'], C.COLOR_OK)} {colorize('ignored', t['ignored'], C.COLOR_WARN)}",
screen_only=True
)
diff --git a/plugins/callback/diy.py b/plugins/callback/diy.py
index cf9369e4b4..b3cd0cdbce 100644
--- a/plugins/callback/diy.py
+++ b/plugins/callback/diy.py
@@ -4,605 +4,599 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = r'''
- name: diy
- type: stdout
- short_description: Customize the output
- version_added: 0.2.0
- description:
- - Callback plugin that allows you to supply your own custom callback templates to be output.
- author: Trevor Highfill (@theque5t)
- extends_documentation_fragment:
- - default_callback
- notes:
- - Uses the P(ansible.builtin.default#callback) callback plugin output when a custom callback V(message(msg\)) is not provided.
- - Makes the callback event data available via the C(ansible_callback_diy) dictionary, which can be used in the templating context for the options.
- The dictionary is only available in the templating context for the options. It is not a variable that is available via the other
- various execution contexts, such as playbook, play, task etc.
- - Options being set by their respective variable input can only be set using the variable if the variable was set in a context that is available to the
- respective callback.
- Use the C(ansible_callback_diy) dictionary to see what is available to a callback. Additionally, C(ansible_callback_diy.top_level_var_names) will output
- the top level variable names available to the callback.
- - Each option value is rendered as a template before being evaluated. This allows for the dynamic usage of an option. For example,
- C("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}")
- - "**Condition** for all C(msg) options:
- if value C(is None or omit),
- then the option is not being used.
- **Effect**: use of the C(default) callback plugin for output"
- - "**Condition** for all C(msg) options:
- if value C(is not None and not omit and length is not greater than 0),
- then the option is being used without output.
- **Effect**: suppress output"
- - "**Condition** for all C(msg) options:
- if value C(is not None and not omit and length is greater than 0),
- then the option is being used with output.
- **Effect**: render value as template and output"
- - "Valid color values: V(black), V(bright gray), V(blue), V(white), V(green), V(bright blue), V(cyan), V(bright green), V(red), V(bright cyan),
- V(purple), V(bright red), V(yellow), V(bright purple), V(dark gray), V(bright yellow), V(magenta), V(bright magenta), V(normal)"
- seealso:
- - name: default – default Ansible screen output
- description: The official documentation on the B(default) callback plugin.
- link: https://docs.ansible.com/ansible/latest/plugins/callback/default.html
- requirements:
- - set as stdout_callback in configuration
- options:
- on_any_msg:
- description: Output to be used for callback on_any.
- ini:
- - section: callback_diy
- key: on_any_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_ON_ANY_MSG
- vars:
- - name: ansible_callback_diy_on_any_msg
- type: str
+DOCUMENTATION = r"""
+name: diy
+type: stdout
+short_description: Customize the output
+version_added: 0.2.0
+description:
+ - Callback plugin that allows you to supply your own custom callback templates to be output.
+author: Trevor Highfill (@theque5t)
+extends_documentation_fragment:
+ - default_callback
+notes:
+ - Uses the P(ansible.builtin.default#callback) callback plugin output when a custom callback V(message(msg\)) is not provided.
+ - Makes the callback event data available using the C(ansible_callback_diy) dictionary, which can be used in the templating
+ context for the options. The dictionary is only available in the templating context for the options. It is not a variable
+ that is available using the other various execution contexts, such as playbook, play, task, and so on so forth.
+ - Options being set by their respective variable input can only be set using the variable if the variable was set in a context
+ that is available to the respective callback. Use the C(ansible_callback_diy) dictionary to see what is available to a
+ callback. Additionally, C(ansible_callback_diy.top_level_var_names) will output the top level variable names available
+ to the callback.
+ - Each option value is rendered as a template before being evaluated. This allows for the dynamic usage of an option. For
+ example, C("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}").
+ - 'B(Condition) for all C(msg) options: if value C(is None or omit), then the option is not being used. B(Effect): use
+ of the C(default) callback plugin for output.'
+ - 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is not greater than 0), then the
+ option is being used without output. B(Effect): suppress output.'
+ - 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is greater than 0), then the option
+ is being used with output. B(Effect): render value as template and output.'
+ - 'Valid color values: V(black), V(bright gray), V(blue), V(white), V(green), V(bright blue), V(cyan), V(bright green),
+ V(red), V(bright cyan), V(purple), V(bright red), V(yellow), V(bright purple), V(dark gray), V(bright yellow), V(magenta),
+ V(bright magenta), V(normal).'
+seealso:
+ - name: default – default Ansible screen output
+ description: The official documentation on the B(default) callback plugin.
+ link: https://docs.ansible.com/ansible/latest/plugins/callback/default.html
+requirements:
+ - set as stdout_callback in configuration
+options:
+ on_any_msg:
+ description: Output to be used for callback on_any.
+ ini:
+ - section: callback_diy
+ key: on_any_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_ON_ANY_MSG
+ vars:
+ - name: ansible_callback_diy_on_any_msg
+ type: str
- on_any_msg_color:
- description:
- - Output color to be used for O(on_any_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: on_any_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_ON_ANY_MSG_COLOR
- vars:
- - name: ansible_callback_diy_on_any_msg_color
- type: str
+ on_any_msg_color:
+ description:
+ - Output color to be used for O(on_any_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: on_any_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_ON_ANY_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_on_any_msg_color
+ type: str
- runner_on_failed_msg:
- description: Output to be used for callback runner_on_failed.
- ini:
- - section: callback_diy
- key: runner_on_failed_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_FAILED_MSG
- vars:
- - name: ansible_callback_diy_runner_on_failed_msg
- type: str
+ runner_on_failed_msg:
+ description: Output to be used for callback runner_on_failed.
+ ini:
+ - section: callback_diy
+ key: runner_on_failed_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_FAILED_MSG
+ vars:
+ - name: ansible_callback_diy_runner_on_failed_msg
+ type: str
- runner_on_failed_msg_color:
- description:
- - Output color to be used for O(runner_on_failed_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_on_failed_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_FAILED_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_on_failed_msg_color
- type: str
+ runner_on_failed_msg_color:
+ description:
+ - Output color to be used for O(runner_on_failed_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_on_failed_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_FAILED_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_on_failed_msg_color
+ type: str
- runner_on_ok_msg:
- description: Output to be used for callback runner_on_ok.
- ini:
- - section: callback_diy
- key: runner_on_ok_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_OK_MSG
- vars:
- - name: ansible_callback_diy_runner_on_ok_msg
- type: str
+ runner_on_ok_msg:
+ description: Output to be used for callback runner_on_ok.
+ ini:
+ - section: callback_diy
+ key: runner_on_ok_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_OK_MSG
+ vars:
+ - name: ansible_callback_diy_runner_on_ok_msg
+ type: str
- runner_on_ok_msg_color:
- description:
- - Output color to be used for O(runner_on_ok_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_on_ok_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_OK_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_on_ok_msg_color
- type: str
+ runner_on_ok_msg_color:
+ description:
+ - Output color to be used for O(runner_on_ok_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_on_ok_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_OK_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_on_ok_msg_color
+ type: str
- runner_on_skipped_msg:
- description: Output to be used for callback runner_on_skipped.
- ini:
- - section: callback_diy
- key: runner_on_skipped_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_SKIPPED_MSG
- vars:
- - name: ansible_callback_diy_runner_on_skipped_msg
- type: str
+ runner_on_skipped_msg:
+ description: Output to be used for callback runner_on_skipped.
+ ini:
+ - section: callback_diy
+ key: runner_on_skipped_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_SKIPPED_MSG
+ vars:
+ - name: ansible_callback_diy_runner_on_skipped_msg
+ type: str
- runner_on_skipped_msg_color:
- description:
- - Output color to be used for O(runner_on_skipped_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_on_skipped_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_SKIPPED_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_on_skipped_msg_color
- type: str
+ runner_on_skipped_msg_color:
+ description:
+ - Output color to be used for O(runner_on_skipped_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_on_skipped_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_SKIPPED_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_on_skipped_msg_color
+ type: str
- runner_on_unreachable_msg:
- description: Output to be used for callback runner_on_unreachable.
- ini:
- - section: callback_diy
- key: runner_on_unreachable_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_UNREACHABLE_MSG
- vars:
- - name: ansible_callback_diy_runner_on_unreachable_msg
- type: str
+ runner_on_unreachable_msg:
+ description: Output to be used for callback runner_on_unreachable.
+ ini:
+ - section: callback_diy
+ key: runner_on_unreachable_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_UNREACHABLE_MSG
+ vars:
+ - name: ansible_callback_diy_runner_on_unreachable_msg
+ type: str
- runner_on_unreachable_msg_color:
- description:
- - Output color to be used for O(runner_on_unreachable_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_on_unreachable_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_UNREACHABLE_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_on_unreachable_msg_color
- type: str
+ runner_on_unreachable_msg_color:
+ description:
+ - Output color to be used for O(runner_on_unreachable_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_on_unreachable_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_UNREACHABLE_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_on_unreachable_msg_color
+ type: str
- playbook_on_start_msg:
- description: Output to be used for callback playbook_on_start.
- ini:
- - section: callback_diy
- key: playbook_on_start_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_START_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_start_msg
- type: str
+ playbook_on_start_msg:
+ description: Output to be used for callback playbook_on_start.
+ ini:
+ - section: callback_diy
+ key: playbook_on_start_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_START_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_start_msg
+ type: str
- playbook_on_start_msg_color:
- description:
- - Output color to be used for O(playbook_on_start_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_start_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_START_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_start_msg_color
- type: str
+ playbook_on_start_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_start_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_start_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_START_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_start_msg_color
+ type: str
- playbook_on_notify_msg:
- description: Output to be used for callback playbook_on_notify.
- ini:
- - section: callback_diy
- key: playbook_on_notify_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NOTIFY_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_notify_msg
- type: str
+ playbook_on_notify_msg:
+ description: Output to be used for callback playbook_on_notify.
+ ini:
+ - section: callback_diy
+ key: playbook_on_notify_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NOTIFY_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_notify_msg
+ type: str
- playbook_on_notify_msg_color:
- description:
- - Output color to be used for O(playbook_on_notify_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_notify_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NOTIFY_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_notify_msg_color
- type: str
+ playbook_on_notify_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_notify_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_notify_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NOTIFY_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_notify_msg_color
+ type: str
- playbook_on_no_hosts_matched_msg:
- description: Output to be used for callback playbook_on_no_hosts_matched.
- ini:
- - section: callback_diy
- key: playbook_on_no_hosts_matched_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NO_HOSTS_MATCHED_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_no_hosts_matched_msg
- type: str
+ playbook_on_no_hosts_matched_msg:
+ description: Output to be used for callback playbook_on_no_hosts_matched.
+ ini:
+ - section: callback_diy
+ key: playbook_on_no_hosts_matched_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NO_HOSTS_MATCHED_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_no_hosts_matched_msg
+ type: str
- playbook_on_no_hosts_matched_msg_color:
- description:
- - Output color to be used for O(playbook_on_no_hosts_matched_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_no_hosts_matched_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NO_HOSTS_MATCHED_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_no_hosts_matched_msg_color
- type: str
+ playbook_on_no_hosts_matched_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_no_hosts_matched_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_no_hosts_matched_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NO_HOSTS_MATCHED_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_no_hosts_matched_msg_color
+ type: str
- playbook_on_no_hosts_remaining_msg:
- description: Output to be used for callback playbook_on_no_hosts_remaining.
- ini:
- - section: callback_diy
- key: playbook_on_no_hosts_remaining_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NO_HOSTS_REMAINING_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_no_hosts_remaining_msg
- type: str
+ playbook_on_no_hosts_remaining_msg:
+ description: Output to be used for callback playbook_on_no_hosts_remaining.
+ ini:
+ - section: callback_diy
+ key: playbook_on_no_hosts_remaining_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NO_HOSTS_REMAINING_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_no_hosts_remaining_msg
+ type: str
- playbook_on_no_hosts_remaining_msg_color:
- description:
- - Output color to be used for O(playbook_on_no_hosts_remaining_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_no_hosts_remaining_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NO_HOSTS_REMAINING_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_no_hosts_remaining_msg_color
- type: str
+ playbook_on_no_hosts_remaining_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_no_hosts_remaining_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_no_hosts_remaining_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_NO_HOSTS_REMAINING_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_no_hosts_remaining_msg_color
+ type: str
- playbook_on_task_start_msg:
- description: Output to be used for callback playbook_on_task_start.
- ini:
- - section: callback_diy
- key: playbook_on_task_start_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_TASK_START_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_task_start_msg
- type: str
+ playbook_on_task_start_msg:
+ description: Output to be used for callback playbook_on_task_start.
+ ini:
+ - section: callback_diy
+ key: playbook_on_task_start_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_TASK_START_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_task_start_msg
+ type: str
- playbook_on_task_start_msg_color:
- description:
- - Output color to be used for O(playbook_on_task_start_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_task_start_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_TASK_START_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_task_start_msg_color
- type: str
+ playbook_on_task_start_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_task_start_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_task_start_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_TASK_START_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_task_start_msg_color
+ type: str
- playbook_on_handler_task_start_msg:
- description: Output to be used for callback playbook_on_handler_task_start.
- ini:
- - section: callback_diy
- key: playbook_on_handler_task_start_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_HANDLER_TASK_START_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_handler_task_start_msg
- type: str
+ playbook_on_handler_task_start_msg:
+ description: Output to be used for callback playbook_on_handler_task_start.
+ ini:
+ - section: callback_diy
+ key: playbook_on_handler_task_start_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_HANDLER_TASK_START_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_handler_task_start_msg
+ type: str
- playbook_on_handler_task_start_msg_color:
- description:
- - Output color to be used for O(playbook_on_handler_task_start_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_handler_task_start_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_HANDLER_TASK_START_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_handler_task_start_msg_color
- type: str
+ playbook_on_handler_task_start_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_handler_task_start_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_handler_task_start_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_HANDLER_TASK_START_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_handler_task_start_msg_color
+ type: str
- playbook_on_vars_prompt_msg:
- description: Output to be used for callback playbook_on_vars_prompt.
- ini:
- - section: callback_diy
- key: playbook_on_vars_prompt_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_VARS_PROMPT_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_vars_prompt_msg
- type: str
+ playbook_on_vars_prompt_msg:
+ description: Output to be used for callback playbook_on_vars_prompt.
+ ini:
+ - section: callback_diy
+ key: playbook_on_vars_prompt_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_VARS_PROMPT_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_vars_prompt_msg
+ type: str
- playbook_on_vars_prompt_msg_color:
- description:
- - Output color to be used for O(playbook_on_vars_prompt_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_vars_prompt_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_VARS_PROMPT_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_vars_prompt_msg_color
- type: str
+ playbook_on_vars_prompt_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_vars_prompt_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_vars_prompt_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_VARS_PROMPT_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_vars_prompt_msg_color
+ type: str
- playbook_on_play_start_msg:
- description: Output to be used for callback playbook_on_play_start.
- ini:
- - section: callback_diy
- key: playbook_on_play_start_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_PLAY_START_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_play_start_msg
- type: str
+ playbook_on_play_start_msg:
+ description: Output to be used for callback playbook_on_play_start.
+ ini:
+ - section: callback_diy
+ key: playbook_on_play_start_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_PLAY_START_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_play_start_msg
+ type: str
- playbook_on_play_start_msg_color:
- description:
- - Output color to be used for O(playbook_on_play_start_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_play_start_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_PLAY_START_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_play_start_msg_color
- type: str
+ playbook_on_play_start_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_play_start_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_play_start_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_PLAY_START_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_play_start_msg_color
+ type: str
- playbook_on_stats_msg:
- description: Output to be used for callback playbook_on_stats.
- ini:
- - section: callback_diy
- key: playbook_on_stats_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_STATS_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_stats_msg
- type: str
+ playbook_on_stats_msg:
+ description: Output to be used for callback playbook_on_stats.
+ ini:
+ - section: callback_diy
+ key: playbook_on_stats_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_STATS_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_stats_msg
+ type: str
- playbook_on_stats_msg_color:
- description:
- - Output color to be used for O(playbook_on_stats_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_stats_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_STATS_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_stats_msg_color
- type: str
+ playbook_on_stats_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_stats_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_stats_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_STATS_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_stats_msg_color
+ type: str
- on_file_diff_msg:
- description: Output to be used for callback on_file_diff.
- ini:
- - section: callback_diy
- key: on_file_diff_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_ON_FILE_DIFF_MSG
- vars:
- - name: ansible_callback_diy_on_file_diff_msg
- type: str
+ on_file_diff_msg:
+ description: Output to be used for callback on_file_diff.
+ ini:
+ - section: callback_diy
+ key: on_file_diff_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_ON_FILE_DIFF_MSG
+ vars:
+ - name: ansible_callback_diy_on_file_diff_msg
+ type: str
- on_file_diff_msg_color:
- description:
- - Output color to be used for O(on_file_diff_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: on_file_diff_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_ON_FILE_DIFF_MSG_COLOR
- vars:
- - name: ansible_callback_diy_on_file_diff_msg_color
- type: str
+ on_file_diff_msg_color:
+ description:
+ - Output color to be used for O(on_file_diff_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: on_file_diff_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_ON_FILE_DIFF_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_on_file_diff_msg_color
+ type: str
- playbook_on_include_msg:
- description: Output to be used for callback playbook_on_include.
- ini:
- - section: callback_diy
- key: playbook_on_include_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_INCLUDE_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_include_msg
- type: str
+ playbook_on_include_msg:
+ description: Output to be used for callback playbook_on_include.
+ ini:
+ - section: callback_diy
+ key: playbook_on_include_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_INCLUDE_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_include_msg
+ type: str
- playbook_on_include_msg_color:
- description:
- - Output color to be used for O(playbook_on_include_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_include_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_INCLUDE_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_include_msg_color
- type: str
+ playbook_on_include_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_include_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_include_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_INCLUDE_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_include_msg_color
+ type: str
- runner_item_on_ok_msg:
- description: Output to be used for callback runner_item_on_ok.
- ini:
- - section: callback_diy
- key: runner_item_on_ok_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_OK_MSG
- vars:
- - name: ansible_callback_diy_runner_item_on_ok_msg
- type: str
+ runner_item_on_ok_msg:
+ description: Output to be used for callback runner_item_on_ok.
+ ini:
+ - section: callback_diy
+ key: runner_item_on_ok_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_OK_MSG
+ vars:
+ - name: ansible_callback_diy_runner_item_on_ok_msg
+ type: str
- runner_item_on_ok_msg_color:
- description:
- - Output color to be used for O(runner_item_on_ok_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_item_on_ok_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_OK_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_item_on_ok_msg_color
- type: str
+ runner_item_on_ok_msg_color:
+ description:
+ - Output color to be used for O(runner_item_on_ok_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_item_on_ok_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_OK_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_item_on_ok_msg_color
+ type: str
- runner_item_on_failed_msg:
- description: Output to be used for callback runner_item_on_failed.
- ini:
- - section: callback_diy
- key: runner_item_on_failed_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_FAILED_MSG
- vars:
- - name: ansible_callback_diy_runner_item_on_failed_msg
- type: str
+ runner_item_on_failed_msg:
+ description: Output to be used for callback runner_item_on_failed.
+ ini:
+ - section: callback_diy
+ key: runner_item_on_failed_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_FAILED_MSG
+ vars:
+ - name: ansible_callback_diy_runner_item_on_failed_msg
+ type: str
- runner_item_on_failed_msg_color:
- description:
- - Output color to be used for O(runner_item_on_failed_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_item_on_failed_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_FAILED_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_item_on_failed_msg_color
- type: str
+ runner_item_on_failed_msg_color:
+ description:
+ - Output color to be used for O(runner_item_on_failed_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_item_on_failed_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_FAILED_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_item_on_failed_msg_color
+ type: str
- runner_item_on_skipped_msg:
- description: Output to be used for callback runner_item_on_skipped.
- ini:
- - section: callback_diy
- key: runner_item_on_skipped_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_SKIPPED_MSG
- vars:
- - name: ansible_callback_diy_runner_item_on_skipped_msg
- type: str
+ runner_item_on_skipped_msg:
+ description: Output to be used for callback runner_item_on_skipped.
+ ini:
+ - section: callback_diy
+ key: runner_item_on_skipped_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_SKIPPED_MSG
+ vars:
+ - name: ansible_callback_diy_runner_item_on_skipped_msg
+ type: str
- runner_item_on_skipped_msg_color:
- description:
- - Output color to be used for O(runner_item_on_skipped_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_item_on_skipped_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_SKIPPED_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_item_on_skipped_msg_color
- type: str
+ runner_item_on_skipped_msg_color:
+ description:
+ - Output color to be used for O(runner_item_on_skipped_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_item_on_skipped_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ITEM_ON_SKIPPED_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_item_on_skipped_msg_color
+ type: str
- runner_retry_msg:
- description: Output to be used for callback runner_retry.
- ini:
- - section: callback_diy
- key: runner_retry_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_RETRY_MSG
- vars:
- - name: ansible_callback_diy_runner_retry_msg
- type: str
+ runner_retry_msg:
+ description: Output to be used for callback runner_retry.
+ ini:
+ - section: callback_diy
+ key: runner_retry_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_RETRY_MSG
+ vars:
+ - name: ansible_callback_diy_runner_retry_msg
+ type: str
- runner_retry_msg_color:
- description:
- - Output color to be used for O(runner_retry_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_retry_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_RETRY_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_retry_msg_color
- type: str
+ runner_retry_msg_color:
+ description:
+ - Output color to be used for O(runner_retry_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_retry_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_RETRY_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_retry_msg_color
+ type: str
- runner_on_start_msg:
- description: Output to be used for callback runner_on_start.
- ini:
- - section: callback_diy
- key: runner_on_start_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_START_MSG
- vars:
- - name: ansible_callback_diy_runner_on_start_msg
- type: str
+ runner_on_start_msg:
+ description: Output to be used for callback runner_on_start.
+ ini:
+ - section: callback_diy
+ key: runner_on_start_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_START_MSG
+ vars:
+ - name: ansible_callback_diy_runner_on_start_msg
+ type: str
- runner_on_start_msg_color:
- description:
- - Output color to be used for O(runner_on_start_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_on_start_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_START_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_on_start_msg_color
- type: str
+ runner_on_start_msg_color:
+ description:
+ - Output color to be used for O(runner_on_start_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_on_start_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_START_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_on_start_msg_color
+ type: str
- runner_on_no_hosts_msg:
- description: Output to be used for callback runner_on_no_hosts.
- ini:
- - section: callback_diy
- key: runner_on_no_hosts_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_NO_HOSTS_MSG
- vars:
- - name: ansible_callback_diy_runner_on_no_hosts_msg
- type: str
+ runner_on_no_hosts_msg:
+ description: Output to be used for callback runner_on_no_hosts.
+ ini:
+ - section: callback_diy
+ key: runner_on_no_hosts_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_NO_HOSTS_MSG
+ vars:
+ - name: ansible_callback_diy_runner_on_no_hosts_msg
+ type: str
- runner_on_no_hosts_msg_color:
- description:
- - Output color to be used for O(runner_on_no_hosts_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: runner_on_no_hosts_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_NO_HOSTS_MSG_COLOR
- vars:
- - name: ansible_callback_diy_runner_on_no_hosts_msg_color
- type: str
+ runner_on_no_hosts_msg_color:
+ description:
+ - Output color to be used for O(runner_on_no_hosts_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: runner_on_no_hosts_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_RUNNER_ON_NO_HOSTS_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_runner_on_no_hosts_msg_color
+ type: str
- playbook_on_setup_msg:
- description: Output to be used for callback playbook_on_setup.
- ini:
- - section: callback_diy
- key: playbook_on_setup_msg
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_SETUP_MSG
- vars:
- - name: ansible_callback_diy_playbook_on_setup_msg
- type: str
+ playbook_on_setup_msg:
+ description: Output to be used for callback playbook_on_setup.
+ ini:
+ - section: callback_diy
+ key: playbook_on_setup_msg
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_SETUP_MSG
+ vars:
+ - name: ansible_callback_diy_playbook_on_setup_msg
+ type: str
- playbook_on_setup_msg_color:
- description:
- - Output color to be used for O(playbook_on_setup_msg).
- - Template should render a L(valid color value,#notes).
- ini:
- - section: callback_diy
- key: playbook_on_setup_msg_color
- env:
- - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_SETUP_MSG_COLOR
- vars:
- - name: ansible_callback_diy_playbook_on_setup_msg_color
- type: str
-'''
+ playbook_on_setup_msg_color:
+ description:
+ - Output color to be used for O(playbook_on_setup_msg).
+ - Template should render a L(valid color value,#notes).
+ ini:
+ - section: callback_diy
+ key: playbook_on_setup_msg_color
+ env:
+ - name: ANSIBLE_CALLBACK_DIY_PLAYBOOK_ON_SETUP_MSG_COLOR
+ vars:
+ - name: ansible_callback_diy_playbook_on_setup_msg_color
+ type: str
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
ansible.cfg: >
# Enable plugin
[defaults]
@@ -623,7 +617,7 @@ ansible.cfg: >
# Newline after every callback
# on_any_msg='{{ " " | join("\n") }}'
-playbook.yml: >
+playbook.yml: >-
---
- name: "Default plugin output: play example"
hosts: localhost
@@ -782,7 +776,7 @@ playbook.yml: >
{{ white }}{{ ansible_callback_diy[key] }}
{% endfor %}
-'''
+"""
import sys
from contextlib import contextmanager
@@ -828,9 +822,9 @@ class CallbackModule(Default):
_callback_options = ['msg', 'msg_color']
for option in _callback_options:
- _option_name = '%s_%s' % (_callback_type, option)
+ _option_name = f'{_callback_type}_{option}'
_option_template = variables.get(
- self.DIY_NS + "_" + _option_name,
+ f"{self.DIY_NS}_{_option_name}",
self.get_option(_option_name)
)
_ret.update({option: self._template(
@@ -867,7 +861,7 @@ class CallbackModule(Default):
handler=None, result=None, stats=None, remove_attr_ref_loop=True):
def _get_value(obj, attr=None, method=None):
if attr:
- return getattr(obj, attr, getattr(obj, "_" + attr, None))
+ return getattr(obj, attr, getattr(obj, f"_{attr}", None))
if method:
_method = getattr(obj, method)
diff --git a/plugins/callback/elastic.py b/plugins/callback/elastic.py
index 0c94d1ba33..cfa66e53b9 100644
--- a/plugins/callback/elastic.py
+++ b/plugins/callback/elastic.py
@@ -2,72 +2,71 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Victor Martinez (@v1v)
- name: elastic
- type: notification
- short_description: Create distributed traces for each Ansible task in Elastic APM
- version_added: 3.8.0
+DOCUMENTATION = r"""
+author: Victor Martinez (@v1v)
+name: elastic
+type: notification
+short_description: Create distributed traces for each Ansible task in Elastic APM
+version_added: 3.8.0
+description:
+ - This callback creates distributed traces for each Ansible task in Elastic APM.
+ - You can configure the plugin with environment variables.
+ - See U(https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html).
+options:
+ hide_task_arguments:
+ default: false
+ type: bool
description:
- - This callback creates distributed traces for each Ansible task in Elastic APM.
- - You can configure the plugin with environment variables.
- - See U(https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html).
- options:
- hide_task_arguments:
- default: false
- type: bool
- description:
- - Hide the arguments for a task.
- env:
- - name: ANSIBLE_OPENTELEMETRY_HIDE_TASK_ARGUMENTS
- apm_service_name:
- default: ansible
- type: str
- description:
- - The service name resource attribute.
- env:
- - name: ELASTIC_APM_SERVICE_NAME
- apm_server_url:
- type: str
- description:
- - Use the APM server and its environment variables.
- env:
- - name: ELASTIC_APM_SERVER_URL
- apm_secret_token:
- type: str
- description:
- - Use the APM server token
- env:
- - name: ELASTIC_APM_SECRET_TOKEN
- apm_api_key:
- type: str
- description:
- - Use the APM API key
- env:
- - name: ELASTIC_APM_API_KEY
- apm_verify_server_cert:
- default: true
- type: bool
- description:
- - Verifies the SSL certificate if an HTTPS connection.
- env:
- - name: ELASTIC_APM_VERIFY_SERVER_CERT
- traceparent:
- type: str
- description:
- - The L(W3C Trace Context header traceparent,https://www.w3.org/TR/trace-context-1/#traceparent-header).
- env:
- - name: TRACEPARENT
- requirements:
- - elastic-apm (Python library)
-'''
+ - Hide the arguments for a task.
+ env:
+ - name: ANSIBLE_OPENTELEMETRY_HIDE_TASK_ARGUMENTS
+ apm_service_name:
+ default: ansible
+ type: str
+ description:
+ - The service name resource attribute.
+ env:
+ - name: ELASTIC_APM_SERVICE_NAME
+ apm_server_url:
+ type: str
+ description:
+ - Use the APM server and its environment variables.
+ env:
+ - name: ELASTIC_APM_SERVER_URL
+ apm_secret_token:
+ type: str
+ description:
+ - Use the APM server token.
+ env:
+ - name: ELASTIC_APM_SECRET_TOKEN
+ apm_api_key:
+ type: str
+ description:
+ - Use the APM API key.
+ env:
+ - name: ELASTIC_APM_API_KEY
+ apm_verify_server_cert:
+ default: true
+ type: bool
+ description:
+ - Verifies the SSL certificate if an HTTPS connection.
+ env:
+ - name: ELASTIC_APM_VERIFY_SERVER_CERT
+ traceparent:
+ type: str
+ description:
+ - The L(W3C Trace Context header traceparent,https://www.w3.org/TR/trace-context-1/#traceparent-header).
+ env:
+ - name: TRACEPARENT
+requirements:
+ - elastic-apm (Python library)
+"""
-EXAMPLES = '''
-examples: |
+EXAMPLES = r"""
+examples: |-
Enable the plugin in ansible.cfg:
[defaults]
callbacks_enabled = community.general.elastic
@@ -76,7 +75,7 @@ examples: |
export ELASTIC_APM_SERVER_URL=
export ELASTIC_APM_SERVICE_NAME=your_service_name
export ELASTIC_APM_API_KEY=your_APM_API_KEY
-'''
+"""
import getpass
import socket
@@ -118,7 +117,7 @@ class TaskData:
if host.uuid in self.host_data:
if host.status == 'included':
# concatenate task include output from multiple items
- host.result = '%s\n%s' % (self.host_data[host.uuid].result, host.result)
+ host.result = f'{self.host_data[host.uuid].result}\n{host.result}'
else:
return
@@ -166,7 +165,7 @@ class ElasticSource(object):
args = None
if not task.no_log and not hide_task_arguments:
- args = ', '.join(('%s=%s' % a for a in task.args.items()))
+ args = ', '.join((f'{k}={v}' for k, v in task.args.items()))
tasks_data[uuid] = TaskData(uuid, name, path, play_name, action, args)
@@ -225,7 +224,7 @@ class ElasticSource(object):
def create_span_data(self, apm_cli, task_data, host_data):
""" create the span with the given TaskData and HostData """
- name = '[%s] %s: %s' % (host_data.name, task_data.play, task_data.name)
+ name = f'[{host_data.name}] {task_data.play}: {task_data.name}'
message = "success"
status = "success"
@@ -259,7 +258,7 @@ class ElasticSource(object):
"ansible.task.host.status": host_data.status}) as span:
span.outcome = status
if 'failure' in status:
- exception = AnsibleRuntimeError(message="{0}: {1} failed with error message {2}".format(task_data.action, name, enriched_error_message))
+ exception = AnsibleRuntimeError(message=f"{task_data.action}: {name} failed with error message {enriched_error_message}")
apm_cli.capture_exception(exc_info=(type(exception), exception, exception.__traceback__), handled=True)
def init_apm_client(self, apm_server_url, apm_service_name, apm_verify_server_cert, apm_secret_token, apm_api_key):
@@ -288,7 +287,7 @@ class ElasticSource(object):
message = result.get('msg', 'failed')
exception = result.get('exception')
stderr = result.get('stderr')
- return ('message: "{0}"\nexception: "{1}"\nstderr: "{2}"').format(message, exception, stderr)
+ return f"message: \"{message}\"\nexception: \"{exception}\"\nstderr: \"{stderr}\""
class CallbackModule(CallbackBase):
diff --git a/plugins/callback/jabber.py b/plugins/callback/jabber.py
index 302687b708..10aa866142 100644
--- a/plugins/callback/jabber.py
+++ b/plugins/callback/jabber.py
@@ -4,45 +4,44 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: jabber
- type: notification
- short_description: post task events to a jabber server
- description:
- - The chatty part of ChatOps with a Hipchat server as a target.
- - This callback plugin sends status updates to a HipChat channel during playbook execution.
- requirements:
- - xmpp (Python library U(https://github.com/ArchipelProject/xmpppy))
- options:
- server:
- description: connection info to jabber server
- type: str
- required: true
- env:
- - name: JABBER_SERV
- user:
- description: Jabber user to authenticate as
- type: str
- required: true
- env:
- - name: JABBER_USER
- password:
- description: Password for the user to the jabber server
- type: str
- required: true
- env:
- - name: JABBER_PASS
- to:
- description: chat identifier that will receive the message
- type: str
- required: true
- env:
- - name: JABBER_TO
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: jabber
+type: notification
+short_description: post task events to a Jabber server
+description:
+ - The chatty part of ChatOps with a Hipchat server as a target.
+ - This callback plugin sends status updates to a HipChat channel during playbook execution.
+requirements:
+ - xmpp (Python library U(https://github.com/ArchipelProject/xmpppy))
+options:
+ server:
+ description: Connection info to Jabber server.
+ type: str
+ required: true
+ env:
+ - name: JABBER_SERV
+ user:
+ description: Jabber user to authenticate as.
+ type: str
+ required: true
+ env:
+ - name: JABBER_USER
+ password:
+ description: Password for the user to the Jabber server.
+ type: str
+ required: true
+ env:
+ - name: JABBER_PASS
+ to:
+ description: Chat identifier that will receive the message.
+ type: str
+ required: true
+ env:
+ - name: JABBER_TO
+"""
import os
@@ -102,7 +101,7 @@ class CallbackModule(CallbackBase):
"""Display Playbook and play start messages"""
self.play = play
name = play.name
- self.send_msg("Ansible starting play: %s" % (name))
+ self.send_msg(f"Ansible starting play: {name}")
def playbook_on_stats(self, stats):
name = self.play
@@ -118,7 +117,7 @@ class CallbackModule(CallbackBase):
if failures or unreachable:
out = self.debug
- self.send_msg("%s: Failures detected \n%s \nHost: %s\n Failed at:\n%s" % (name, self.task, h, out))
+ self.send_msg(f"{name}: Failures detected \n{self.task} \nHost: {h}\n Failed at:\n{out}")
else:
out = self.debug
- self.send_msg("Great! \n Playbook %s completed:\n%s \n Last task debug:\n %s" % (name, s, out))
+ self.send_msg(f"Great! \n Playbook {name} completed:\n{s} \n Last task debug:\n {out}")
diff --git a/plugins/callback/log_plays.py b/plugins/callback/log_plays.py
index daa88bcc11..483976acae 100644
--- a/plugins/callback/log_plays.py
+++ b/plugins/callback/log_plays.py
@@ -4,30 +4,29 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: log_plays
- type: notification
- short_description: write playbook output to log file
- description:
- - This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory.
- requirements:
- - Whitelist in configuration
- - A writeable C(/var/log/ansible/hosts) directory by the user executing Ansible on the controller
- options:
- log_folder:
- default: /var/log/ansible/hosts
- description: The folder where log files will be created.
- type: str
- env:
- - name: ANSIBLE_LOG_FOLDER
- ini:
- - section: callback_log_plays
- key: log_folder
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: log_plays
+type: notification
+short_description: write playbook output to log file
+description:
+ - This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory.
+requirements:
+ - Whitelist in configuration
+ - A writeable C(/var/log/ansible/hosts) directory by the user executing Ansible on the controller
+options:
+ log_folder:
+ default: /var/log/ansible/hosts
+ description: The folder where log files will be created.
+ type: str
+ env:
+ - name: ANSIBLE_LOG_FOLDER
+ ini:
+ - section: callback_log_plays
+ key: log_folder
+"""
import os
import time
@@ -57,7 +56,10 @@ class CallbackModule(CallbackBase):
CALLBACK_NEEDS_WHITELIST = True
TIME_FORMAT = "%b %d %Y %H:%M:%S"
- MSG_FORMAT = "%(now)s - %(playbook)s - %(task_name)s - %(task_action)s - %(category)s - %(data)s\n\n"
+
+ @staticmethod
+ def _make_msg(now, playbook, task_name, task_action, category, data):
+ return f"{now} - {playbook} - {task_name} - {task_action} - {category} - {data}\n\n"
def __init__(self):
@@ -82,22 +84,12 @@ class CallbackModule(CallbackBase):
invocation = data.pop('invocation', None)
data = json.dumps(data, cls=AnsibleJSONEncoder)
if invocation is not None:
- data = json.dumps(invocation) + " => %s " % data
+ data = f"{json.dumps(invocation)} => {data} "
path = os.path.join(self.log_folder, result._host.get_name())
now = time.strftime(self.TIME_FORMAT, time.localtime())
- msg = to_bytes(
- self.MSG_FORMAT
- % dict(
- now=now,
- playbook=self.playbook,
- task_name=result._task.name,
- task_action=result._task.action,
- category=category,
- data=data,
- )
- )
+ msg = to_bytes(self._make_msg(now, self.playbook, result._task.name, result._task.action, category, data))
with open(path, "ab") as fd:
fd.write(msg)
diff --git a/plugins/callback/loganalytics.py b/plugins/callback/loganalytics.py
index fd1b2772c4..224ce7efd8 100644
--- a/plugins/callback/loganalytics.py
+++ b/plugins/callback/loganalytics.py
@@ -3,44 +3,43 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: loganalytics
- type: notification
- short_description: Posts task results to Azure Log Analytics
- author: "Cyrus Li (@zhcli) "
- description:
- - This callback plugin will post task results in JSON formatted to an Azure Log Analytics workspace.
- - Credits to authors of splunk callback plugin.
- version_added: "2.4.0"
- requirements:
- - Whitelisting this callback plugin.
- - An Azure log analytics work space has been established.
- options:
- workspace_id:
- description: Workspace ID of the Azure log analytics workspace.
- type: str
- required: true
- env:
- - name: WORKSPACE_ID
- ini:
- - section: callback_loganalytics
- key: workspace_id
- shared_key:
- description: Shared key to connect to Azure log analytics workspace.
- type: str
- required: true
- env:
- - name: WORKSPACE_SHARED_KEY
- ini:
- - section: callback_loganalytics
- key: shared_key
-'''
+DOCUMENTATION = r"""
+name: loganalytics
+type: notification
+short_description: Posts task results to Azure Log Analytics
+author: "Cyrus Li (@zhcli) "
+description:
+ - This callback plugin will post task results in JSON formatted to an Azure Log Analytics workspace.
+ - Credits to authors of splunk callback plugin.
+version_added: "2.4.0"
+requirements:
+ - Whitelisting this callback plugin.
+ - An Azure log analytics work space has been established.
+options:
+ workspace_id:
+ description: Workspace ID of the Azure log analytics workspace.
+ type: str
+ required: true
+ env:
+ - name: WORKSPACE_ID
+ ini:
+ - section: callback_loganalytics
+ key: workspace_id
+ shared_key:
+ description: Shared key to connect to Azure log analytics workspace.
+ type: str
+ required: true
+ env:
+ - name: WORKSPACE_SHARED_KEY
+ ini:
+ - section: callback_loganalytics
+ key: shared_key
+"""
-EXAMPLES = '''
-examples: |
+EXAMPLES = r"""
+examples: |-
Whitelist the plugin in ansible.cfg:
[defaults]
callback_whitelist = community.general.loganalytics
@@ -51,7 +50,7 @@ examples: |
[callback_loganalytics]
workspace_id = 01234567-0123-0123-0123-01234567890a
shared_key = dZD0kCbKl3ehZG6LHFMuhtE0yHiFCmetzFMc2u+roXIUQuatqU924SsAAAAPemhjbGlAemhjbGktTUJQAQIDBA==
-'''
+"""
import hashlib
import hmac
@@ -84,18 +83,17 @@ class AzureLogAnalyticsSource(object):
def __build_signature(self, date, workspace_id, shared_key, content_length):
# Build authorisation signature for Azure log analytics API call
- sigs = "POST\n{0}\napplication/json\nx-ms-date:{1}\n/api/logs".format(
- str(content_length), date)
+ sigs = f"POST\n{content_length}\napplication/json\nx-ms-date:{date}\n/api/logs"
utf8_sigs = sigs.encode('utf-8')
decoded_shared_key = base64.b64decode(shared_key)
hmac_sha256_sigs = hmac.new(
decoded_shared_key, utf8_sigs, digestmod=hashlib.sha256).digest()
encoded_hash = base64.b64encode(hmac_sha256_sigs).decode('utf-8')
- signature = "SharedKey {0}:{1}".format(workspace_id, encoded_hash)
+ signature = f"SharedKey {workspace_id}:{encoded_hash}"
return signature
def __build_workspace_url(self, workspace_id):
- return "https://{0}.ods.opinsights.azure.com/api/logs?api-version=2016-04-01".format(workspace_id)
+ return f"https://{workspace_id}.ods.opinsights.azure.com/api/logs?api-version=2016-04-01"
def __rfc1123date(self):
return now().strftime('%a, %d %b %Y %H:%M:%S GMT')
diff --git a/plugins/callback/logdna.py b/plugins/callback/logdna.py
index fc9a81ac8a..90fe6d4465 100644
--- a/plugins/callback/logdna.py
+++ b/plugins/callback/logdna.py
@@ -3,59 +3,58 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: logdna
- type: notification
- short_description: Sends playbook logs to LogDNA
- description:
- - This callback will report logs from playbook actions, tasks, and events to LogDNA (U(https://app.logdna.com)).
- requirements:
- - LogDNA Python Library (U(https://github.com/logdna/python))
- - whitelisting in configuration
- options:
- conf_key:
- required: true
- description: LogDNA Ingestion Key.
- type: string
- env:
- - name: LOGDNA_INGESTION_KEY
- ini:
- - section: callback_logdna
- key: conf_key
- plugin_ignore_errors:
- required: false
- description: Whether to ignore errors on failing or not.
- type: boolean
- env:
- - name: ANSIBLE_IGNORE_ERRORS
- ini:
- - section: callback_logdna
- key: plugin_ignore_errors
- default: false
- conf_hostname:
- required: false
- description: Alternative Host Name; the current host name by default.
- type: string
- env:
- - name: LOGDNA_HOSTNAME
- ini:
- - section: callback_logdna
- key: conf_hostname
- conf_tags:
- required: false
- description: Tags.
- type: string
- env:
- - name: LOGDNA_TAGS
- ini:
- - section: callback_logdna
- key: conf_tags
- default: ansible
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: logdna
+type: notification
+short_description: Sends playbook logs to LogDNA
+description:
+ - This callback will report logs from playbook actions, tasks, and events to LogDNA (U(https://app.logdna.com)).
+requirements:
+ - LogDNA Python Library (U(https://github.com/logdna/python))
+ - whitelisting in configuration
+options:
+ conf_key:
+ required: true
+ description: LogDNA Ingestion Key.
+ type: string
+ env:
+ - name: LOGDNA_INGESTION_KEY
+ ini:
+ - section: callback_logdna
+ key: conf_key
+ plugin_ignore_errors:
+ required: false
+ description: Whether to ignore errors on failing or not.
+ type: boolean
+ env:
+ - name: ANSIBLE_IGNORE_ERRORS
+ ini:
+ - section: callback_logdna
+ key: plugin_ignore_errors
+ default: false
+ conf_hostname:
+ required: false
+ description: Alternative Host Name; the current host name by default.
+ type: string
+ env:
+ - name: LOGDNA_HOSTNAME
+ ini:
+ - section: callback_logdna
+ key: conf_hostname
+ conf_tags:
+ required: false
+ description: Tags.
+ type: string
+ env:
+ - name: LOGDNA_TAGS
+ ini:
+ - section: callback_logdna
+ key: conf_tags
+ default: ansible
+"""
import logging
import json
@@ -73,7 +72,7 @@ except ImportError:
# Getting MAC Address of system:
def get_mac():
- mac = "%012x" % getnode()
+ mac = f"{getnode():012x}"
return ":".join(map(lambda index: mac[index:index + 2], range(int(len(mac) / 2))))
@@ -161,7 +160,7 @@ class CallbackModule(CallbackBase):
if ninvalidKeys > 0:
for key in invalidKeys:
del meta[key]
- meta['__errors'] = 'These keys have been sanitized: ' + ', '.join(invalidKeys)
+ meta['__errors'] = f"These keys have been sanitized: {', '.join(invalidKeys)}"
return meta
def sanitizeJSON(self, data):
diff --git a/plugins/callback/logentries.py b/plugins/callback/logentries.py
index c1271543ad..bc5d7e03ce 100644
--- a/plugins/callback/logentries.py
+++ b/plugins/callback/logentries.py
@@ -3,82 +3,79 @@
# Copyright (c) 2017 Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: logentries
- type: notification
- short_description: Sends events to Logentries
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: logentries
+type: notification
+short_description: Sends events to Logentries
+description:
+ - This callback plugin will generate JSON objects and send them to Logentries using TCP for auditing/debugging purposes.
+requirements:
+ - whitelisting in configuration
+ - certifi (Python library)
+ - flatdict (Python library), if you want to use the O(flatten) option
+options:
+ api:
+ description: URI to the Logentries API.
+ type: str
+ env:
+ - name: LOGENTRIES_API
+ default: data.logentries.com
+ ini:
+ - section: callback_logentries
+ key: api
+ port:
+ description: HTTP port to use when connecting to the API.
+ type: int
+ env:
+ - name: LOGENTRIES_PORT
+ default: 80
+ ini:
+ - section: callback_logentries
+ key: port
+ tls_port:
+ description: Port to use when connecting to the API when TLS is enabled.
+ type: int
+ env:
+ - name: LOGENTRIES_TLS_PORT
+ default: 443
+ ini:
+ - section: callback_logentries
+ key: tls_port
+ token:
+ description: The logentries C(TCP token).
+ type: str
+ env:
+ - name: LOGENTRIES_ANSIBLE_TOKEN
+ required: true
+ ini:
+ - section: callback_logentries
+ key: token
+ use_tls:
description:
- - This callback plugin will generate JSON objects and send them to Logentries via TCP for auditing/debugging purposes.
- - Before 2.4, if you wanted to use an ini configuration, the file must be placed in the same directory as this plugin and named C(logentries.ini).
- - In 2.4 and above you can just put it in the main Ansible configuration file.
- requirements:
- - whitelisting in configuration
- - certifi (Python library)
- - flatdict (Python library), if you want to use the O(flatten) option
- options:
- api:
- description: URI to the Logentries API.
- type: str
- env:
- - name: LOGENTRIES_API
- default: data.logentries.com
- ini:
- - section: callback_logentries
- key: api
- port:
- description: HTTP port to use when connecting to the API.
- type: int
- env:
- - name: LOGENTRIES_PORT
- default: 80
- ini:
- - section: callback_logentries
- key: port
- tls_port:
- description: Port to use when connecting to the API when TLS is enabled.
- type: int
- env:
- - name: LOGENTRIES_TLS_PORT
- default: 443
- ini:
- - section: callback_logentries
- key: tls_port
- token:
- description: The logentries C(TCP token).
- type: str
- env:
- - name: LOGENTRIES_ANSIBLE_TOKEN
- required: true
- ini:
- - section: callback_logentries
- key: token
- use_tls:
- description:
- - Toggle to decide whether to use TLS to encrypt the communications with the API server.
- env:
- - name: LOGENTRIES_USE_TLS
- default: false
- type: boolean
- ini:
- - section: callback_logentries
- key: use_tls
- flatten:
- description: Flatten complex data structures into a single dictionary with complex keys.
- type: boolean
- default: false
- env:
- - name: LOGENTRIES_FLATTEN
- ini:
- - section: callback_logentries
- key: flatten
-'''
+ - Toggle to decide whether to use TLS to encrypt the communications with the API server.
+ env:
+ - name: LOGENTRIES_USE_TLS
+ default: false
+ type: boolean
+ ini:
+ - section: callback_logentries
+ key: use_tls
+ flatten:
+ description: Flatten complex data structures into a single dictionary with complex keys.
+ type: boolean
+ default: false
+ env:
+ - name: LOGENTRIES_FLATTEN
+ ini:
+ - section: callback_logentries
+ key: flatten
+"""
-EXAMPLES = '''
-examples: >
+EXAMPLES = r"""
+examples: >-
To enable, add this to your ansible.cfg file in the defaults block
[defaults]
@@ -97,7 +94,7 @@ examples: >
use_tls = true
token = dd21fc88-f00a-43ff-b977-e3a4233c53af
flatten = false
-'''
+"""
import os
import socket
@@ -135,7 +132,7 @@ class PlainTextSocketAppender(object):
# Error message displayed when an incorrect Token has been detected
self.INVALID_TOKEN = "\n\nIt appears the LOGENTRIES_TOKEN parameter you entered is incorrect!\n\n"
# Unicode Line separator character \u2028
- self.LINE_SEP = u'\u2028'
+ self.LINE_SEP = '\u2028'
self._display = display
self._conn = None
@@ -153,7 +150,7 @@ class PlainTextSocketAppender(object):
self.open_connection()
return
except Exception as e:
- self._display.vvvv(u"Unable to connect to Logentries: %s" % to_text(e))
+ self._display.vvvv(f"Unable to connect to Logentries: {e}")
root_delay *= 2
if root_delay > self.MAX_DELAY:
@@ -162,7 +159,7 @@ class PlainTextSocketAppender(object):
wait_for = root_delay + random.uniform(0, root_delay)
try:
- self._display.vvvv("sleeping %s before retry" % wait_for)
+ self._display.vvvv(f"sleeping {wait_for} before retry")
time.sleep(wait_for)
except KeyboardInterrupt:
raise
@@ -175,8 +172,8 @@ class PlainTextSocketAppender(object):
# Replace newlines with Unicode line separator
# for multi-line events
data = to_text(data, errors='surrogate_or_strict')
- multiline = data.replace(u'\n', self.LINE_SEP)
- multiline += u"\n"
+ multiline = data.replace('\n', self.LINE_SEP)
+ multiline += "\n"
# Send data, reconnect if needed
while True:
try:
@@ -249,7 +246,7 @@ class CallbackModule(CallbackBase):
self.use_tls = self.get_option('use_tls')
self.flatten = self.get_option('flatten')
except KeyError as e:
- self._display.warning(u"Missing option for Logentries callback plugin: %s" % to_text(e))
+ self._display.warning(f"Missing option for Logentries callback plugin: {e}")
self.disabled = True
try:
@@ -268,10 +265,10 @@ class CallbackModule(CallbackBase):
if not self.disabled:
if self.use_tls:
- self._display.vvvv("Connecting to %s:%s with TLS" % (self.api_url, self.api_tls_port))
+ self._display.vvvv(f"Connecting to {self.api_url}:{self.api_tls_port} with TLS")
self._appender = TLSSocketAppender(display=self._display, LE_API=self.api_url, LE_TLS_PORT=self.api_tls_port)
else:
- self._display.vvvv("Connecting to %s:%s" % (self.api_url, self.api_port))
+ self._display.vvvv(f"Connecting to {self.api_url}:{self.api_port}")
self._appender = PlainTextSocketAppender(display=self._display, LE_API=self.api_url, LE_PORT=self.api_port)
self._appender.reopen_connection()
@@ -284,7 +281,7 @@ class CallbackModule(CallbackBase):
def emit(self, record):
msg = record.rstrip('\n')
- msg = "{0} {1}".format(self.token, msg)
+ msg = f"{self.token} {msg}"
self._appender.put(msg)
self._display.vvvv("Sent event to logentries")
diff --git a/plugins/callback/logstash.py b/plugins/callback/logstash.py
index aa47ee4eb8..9d299e50ed 100644
--- a/plugins/callback/logstash.py
+++ b/plugins/callback/logstash.py
@@ -4,98 +4,96 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = r'''
- author: Yevhen Khmelenko (@ujenmr)
- name: logstash
- type: notification
- short_description: Sends events to Logstash
- description:
- - This callback will report facts and task events to Logstash U(https://www.elastic.co/products/logstash).
- requirements:
- - whitelisting in configuration
- - logstash (Python library)
- options:
- server:
- description: Address of the Logstash server.
- type: str
- env:
- - name: LOGSTASH_SERVER
- ini:
- - section: callback_logstash
- key: server
- version_added: 1.0.0
- default: localhost
- port:
- description: Port on which logstash is listening.
- type: int
- env:
- - name: LOGSTASH_PORT
- ini:
- - section: callback_logstash
- key: port
- version_added: 1.0.0
- default: 5000
- type:
- description: Message type.
- type: str
- env:
- - name: LOGSTASH_TYPE
- ini:
- - section: callback_logstash
- key: type
- version_added: 1.0.0
- default: ansible
- pre_command:
- description: Executes command before run and its result is added to the C(ansible_pre_command_output) logstash field.
- type: str
- version_added: 2.0.0
- ini:
- - section: callback_logstash
- key: pre_command
- env:
- - name: LOGSTASH_PRE_COMMAND
- format_version:
- description: Logging format.
- type: str
- version_added: 2.0.0
- ini:
- - section: callback_logstash
- key: format_version
- env:
- - name: LOGSTASH_FORMAT_VERSION
- default: v1
- choices:
- - v1
- - v2
+DOCUMENTATION = r"""
+author: Yevhen Khmelenko (@ujenmr)
+name: logstash
+type: notification
+short_description: Sends events to Logstash
+description:
+ - This callback will report facts and task events to Logstash U(https://www.elastic.co/products/logstash).
+requirements:
+ - whitelisting in configuration
+ - logstash (Python library)
+options:
+ server:
+ description: Address of the Logstash server.
+ type: str
+ env:
+ - name: LOGSTASH_SERVER
+ ini:
+ - section: callback_logstash
+ key: server
+ version_added: 1.0.0
+ default: localhost
+ port:
+ description: Port on which logstash is listening.
+ type: int
+ env:
+ - name: LOGSTASH_PORT
+ ini:
+ - section: callback_logstash
+ key: port
+ version_added: 1.0.0
+ default: 5000
+ type:
+ description: Message type.
+ type: str
+ env:
+ - name: LOGSTASH_TYPE
+ ini:
+ - section: callback_logstash
+ key: type
+ version_added: 1.0.0
+ default: ansible
+ pre_command:
+ description: Executes command before run and its result is added to the C(ansible_pre_command_output) logstash field.
+ type: str
+ version_added: 2.0.0
+ ini:
+ - section: callback_logstash
+ key: pre_command
+ env:
+ - name: LOGSTASH_PRE_COMMAND
+ format_version:
+ description: Logging format.
+ type: str
+ version_added: 2.0.0
+ ini:
+ - section: callback_logstash
+ key: format_version
+ env:
+ - name: LOGSTASH_FORMAT_VERSION
+ default: v1
+ choices:
+ - v1
+ - v2
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
ansible.cfg: |
- # Enable Callback plugin
- [defaults]
- callback_whitelist = community.general.logstash
+ # Enable Callback plugin
+ [defaults]
+ callback_whitelist = community.general.logstash
- [callback_logstash]
- server = logstash.example.com
- port = 5000
- pre_command = git rev-parse HEAD
- type = ansible
+ [callback_logstash]
+ server = logstash.example.com
+ port = 5000
+ pre_command = git rev-parse HEAD
+ type = ansible
-11-input-tcp.conf: |
- # Enable Logstash TCP Input
- input {
- tcp {
- port => 5000
- codec => json
- add_field => { "[@metadata][beat]" => "notify" }
- add_field => { "[@metadata][type]" => "ansible" }
- }
- }
-'''
+11-input-tcp.conf: |-
+ # Enable Logstash TCP Input
+ input {
+ tcp {
+ port => 5000
+ codec => json
+ add_field => { "[@metadata][beat]" => "notify" }
+ add_field => { "[@metadata][type]" => "ansible" }
+ }
+ }
+"""
import os
import json
diff --git a/plugins/callback/mail.py b/plugins/callback/mail.py
index 1b847ea34c..80bef26044 100644
--- a/plugins/callback/mail.py
+++ b/plugins/callback/mail.py
@@ -4,84 +4,82 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
name: mail
type: notification
-short_description: Sends failure events via email
+short_description: Sends failure events through email
description:
-- This callback will report failures via email.
+ - This callback will report failures through email.
author:
-- Dag Wieers (@dagwieers)
+ - Dag Wieers (@dagwieers)
requirements:
-- whitelisting in configuration
+ - whitelisting in configuration
options:
mta:
description:
- - Mail Transfer Agent, server that accepts SMTP.
+ - Mail Transfer Agent, server that accepts SMTP.
type: str
env:
- - name: SMTPHOST
+ - name: SMTPHOST
ini:
- - section: callback_mail
- key: smtphost
+ - section: callback_mail
+ key: smtphost
default: localhost
mtaport:
description:
- - Mail Transfer Agent Port.
- - Port at which server SMTP.
+ - Mail Transfer Agent Port.
+ - Port at which server SMTP.
type: int
ini:
- - section: callback_mail
- key: smtpport
+ - section: callback_mail
+ key: smtpport
default: 25
to:
description:
- - Mail recipient.
+ - Mail recipient.
type: list
elements: str
ini:
- - section: callback_mail
- key: to
+ - section: callback_mail
+ key: to
default: [root]
sender:
description:
- - Mail sender.
- - This is required since community.general 6.0.0.
+ - Mail sender.
+ - This is required since community.general 6.0.0.
type: str
required: true
ini:
- - section: callback_mail
- key: sender
+ - section: callback_mail
+ key: sender
cc:
description:
- - CC'd recipients.
+ - CC'd recipients.
type: list
elements: str
ini:
- - section: callback_mail
- key: cc
+ - section: callback_mail
+ key: cc
bcc:
description:
- - BCC'd recipients.
+ - BCC'd recipients.
type: list
elements: str
ini:
- - section: callback_mail
- key: bcc
+ - section: callback_mail
+ key: bcc
message_id_domain:
description:
- - The domain name to use for the L(Message-ID header, https://en.wikipedia.org/wiki/Message-ID).
- - The default is the hostname of the control node.
+ - The domain name to use for the L(Message-ID header, https://en.wikipedia.org/wiki/Message-ID).
+ - The default is the hostname of the control node.
type: str
ini:
- - section: callback_mail
- key: message_id_domain
+ - section: callback_mail
+ key: message_id_domain
version_added: 8.2.0
-
-'''
+"""
import json
import os
@@ -135,14 +133,14 @@ class CallbackModule(CallbackBase):
if self.bcc:
bcc_addresses = email.utils.getaddresses(self.bcc)
- content = 'Date: %s\n' % email.utils.formatdate()
- content += 'From: %s\n' % email.utils.formataddr(sender_address)
+ content = f'Date: {email.utils.formatdate()}\n'
+ content += f'From: {email.utils.formataddr(sender_address)}\n'
if self.to:
- content += 'To: %s\n' % ', '.join([email.utils.formataddr(pair) for pair in to_addresses])
+ content += f"To: {', '.join([email.utils.formataddr(pair) for pair in to_addresses])}\n"
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(domain=self.get_option('message_id_domain'))
- content += 'Subject: %s\n\n' % subject.strip()
+ content += f"Cc: {', '.join([email.utils.formataddr(pair) for pair in cc_addresses])}\n"
+ content += f"Message-ID: {email.utils.make_msgid(domain=self.get_option('message_id_domain'))}\n"
+ content += f'Subject: {subject.strip()}\n\n'
content += body
addresses = to_addresses
@@ -159,23 +157,22 @@ class CallbackModule(CallbackBase):
smtp.quit()
def subject_msg(self, multiline, failtype, linenr):
- return '%s: %s' % (failtype, multiline.strip('\r\n').splitlines()[linenr])
+ msg = multiline.strip('\r\n').splitlines()[linenr]
+ return f'{failtype}: {msg}'
def indent(self, multiline, indent=8):
return re.sub('^', ' ' * indent, multiline, flags=re.MULTILINE)
def body_blob(self, multiline, texttype):
''' Turn some text output in a well-indented block for sending in a mail body '''
- intro = 'with the following %s:\n\n' % texttype
- blob = ''
- for line in multiline.strip('\r\n').splitlines():
- blob += '%s\n' % line
- return intro + self.indent(blob) + '\n'
+ intro = f'with the following {texttype}:\n\n'
+ blob = "\n".join(multiline.strip('\r\n').splitlines())
+ return f"{intro}{self.indent(blob)}\n"
def mail_result(self, result, failtype):
host = result._host.get_name()
if not self.sender:
- self.sender = '"Ansible: %s" ' % host
+ self.sender = f'"Ansible: {host}" '
# Add subject
if self.itembody:
@@ -191,31 +188,32 @@ class CallbackModule(CallbackBase):
elif result._result.get('exception'): # Unrelated exceptions are added to output :-/
subject = self.subject_msg(result._result['exception'], failtype, -1)
else:
- subject = '%s: %s' % (failtype, result._task.name or result._task.action)
+ subject = f'{failtype}: {result._task.name or result._task.action}'
# Make playbook name visible (e.g. in Outlook/Gmail condensed view)
- body = 'Playbook: %s\n' % os.path.basename(self.playbook._file_name)
+ body = f'Playbook: {os.path.basename(self.playbook._file_name)}\n'
if result._task.name:
- body += 'Task: %s\n' % result._task.name
- body += 'Module: %s\n' % result._task.action
- body += 'Host: %s\n' % host
+ body += f'Task: {result._task.name}\n'
+ body += f'Module: {result._task.action}\n'
+ body += f'Host: {host}\n'
body += '\n'
# Add task information (as much as possible)
body += 'The following task failed:\n\n'
if 'invocation' in result._result:
- body += self.indent('%s: %s\n' % (result._task.action, json.dumps(result._result['invocation']['module_args'], indent=4)))
+ body += self.indent(f"{result._task.action}: {json.dumps(result._result['invocation']['module_args'], indent=4)}\n")
elif result._task.name:
- body += self.indent('%s (%s)\n' % (result._task.name, result._task.action))
+ body += self.indent(f'{result._task.name} ({result._task.action})\n')
else:
- body += self.indent('%s\n' % result._task.action)
+ body += self.indent(f'{result._task.action}\n')
body += '\n'
# Add item / message
if self.itembody:
body += self.itembody
elif result._result.get('failed_when_result') is True:
- body += "due to the following condition:\n\n" + self.indent('failed_when:\n- ' + '\n- '.join(result._task.failed_when)) + '\n\n'
+ fail_cond = self.indent('failed_when:\n- ' + '\n- '.join(result._task.failed_when))
+ body += f"due to the following condition:\n\n{fail_cond}\n\n"
elif result._result.get('msg'):
body += self.body_blob(result._result['msg'], 'message')
@@ -228,13 +226,13 @@ class CallbackModule(CallbackBase):
body += self.body_blob(result._result['exception'], 'exception')
if result._result.get('warnings'):
for i in range(len(result._result.get('warnings'))):
- body += self.body_blob(result._result['warnings'][i], 'exception %d' % (i + 1))
+ body += self.body_blob(result._result['warnings'][i], f'exception {i + 1}')
if result._result.get('deprecations'):
for i in range(len(result._result.get('deprecations'))):
- body += self.body_blob(result._result['deprecations'][i], 'exception %d' % (i + 1))
+ body += self.body_blob(result._result['deprecations'][i], f'exception {i + 1}')
body += 'and a complete dump of the error:\n\n'
- body += self.indent('%s: %s' % (failtype, json.dumps(result._result, cls=AnsibleJSONEncoder, indent=4)))
+ body += self.indent(f'{failtype}: {json.dumps(result._result, cls=AnsibleJSONEncoder, indent=4)}')
self.mail(subject=subject, body=body)
@@ -257,4 +255,4 @@ class CallbackModule(CallbackBase):
def v2_runner_item_on_failed(self, result):
# Pass item information to task failure
self.itemsubject = result._result['msg']
- self.itembody += self.body_blob(json.dumps(result._result, cls=AnsibleJSONEncoder, indent=4), "failed item dump '%(item)s'" % result._result)
+ self.itembody += self.body_blob(json.dumps(result._result, cls=AnsibleJSONEncoder, indent=4), f"failed item dump '{result._result['item']}'")
diff --git a/plugins/callback/nrdp.py b/plugins/callback/nrdp.py
index 62f4a89ec8..375876973a 100644
--- a/plugins/callback/nrdp.py
+++ b/plugins/callback/nrdp.py
@@ -4,68 +4,67 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: nrdp
- type: notification
- author: "Remi VERCHERE (@rverchere)"
- short_description: Post task results to a Nagios server through nrdp
- description:
- - This callback send playbook result to Nagios.
- - Nagios shall use NRDP to receive passive events.
- - The passive check is sent to a dedicated host/service for Ansible.
- options:
- url:
- description: URL of the nrdp server.
- required: true
- env:
- - name : NRDP_URL
- ini:
- - section: callback_nrdp
- key: url
- type: string
- validate_certs:
- description: Validate the SSL certificate of the nrdp server. (Used for HTTPS URLs.)
- env:
- - name: NRDP_VALIDATE_CERTS
- ini:
- - section: callback_nrdp
- key: validate_nrdp_certs
- - section: callback_nrdp
- key: validate_certs
- type: boolean
- default: false
- aliases: [ validate_nrdp_certs ]
- token:
- description: Token to be allowed to push nrdp events.
- required: true
- env:
- - name: NRDP_TOKEN
- ini:
- - section: callback_nrdp
- key: token
- type: string
- hostname:
- description: Hostname where the passive check is linked to.
- required: true
- env:
- - name : NRDP_HOSTNAME
- ini:
- - section: callback_nrdp
- key: hostname
- type: string
- servicename:
- description: Service where the passive check is linked to.
- required: true
- env:
- - name : NRDP_SERVICENAME
- ini:
- - section: callback_nrdp
- key: servicename
- type: string
-'''
+DOCUMENTATION = r"""
+name: nrdp
+type: notification
+author: "Remi VERCHERE (@rverchere)"
+short_description: Post task results to a Nagios server through nrdp
+description:
+ - This callback send playbook result to Nagios.
+ - Nagios shall use NRDP to receive passive events.
+ - The passive check is sent to a dedicated host/service for Ansible.
+options:
+ url:
+ description: URL of the nrdp server.
+ required: true
+ env:
+ - name: NRDP_URL
+ ini:
+ - section: callback_nrdp
+ key: url
+ type: string
+ validate_certs:
+ description: Validate the SSL certificate of the nrdp server. (Used for HTTPS URLs).
+ env:
+ - name: NRDP_VALIDATE_CERTS
+ ini:
+ - section: callback_nrdp
+ key: validate_nrdp_certs
+ - section: callback_nrdp
+ key: validate_certs
+ type: boolean
+ default: false
+ aliases: [validate_nrdp_certs]
+ token:
+ description: Token to be allowed to push nrdp events.
+ required: true
+ env:
+ - name: NRDP_TOKEN
+ ini:
+ - section: callback_nrdp
+ key: token
+ type: string
+ hostname:
+ description: Hostname where the passive check is linked to.
+ required: true
+ env:
+ - name: NRDP_HOSTNAME
+ ini:
+ - section: callback_nrdp
+ key: hostname
+ type: string
+ servicename:
+ description: Service where the passive check is linked to.
+ required: true
+ env:
+ - name: NRDP_SERVICENAME
+ ini:
+ - section: callback_nrdp
+ key: servicename
+ type: string
+"""
from ansible.module_utils.six.moves.urllib.parse import urlencode
from ansible.module_utils.common.text.converters import to_bytes
@@ -132,10 +131,10 @@ class CallbackModule(CallbackBase):
xmldata = "\n"
xmldata += "\n"
xmldata += "\n"
- xmldata += "%s\n" % self.hostname
- xmldata += "%s\n" % self.servicename
- xmldata += "%d\n" % state
- xmldata += "\n" % msg
+ xmldata += f"{self.hostname}\n"
+ xmldata += f"{self.servicename}\n"
+ xmldata += f"{state}\n"
+ xmldata += f"\n"
xmldata += "\n"
xmldata += "\n"
@@ -152,7 +151,7 @@ class CallbackModule(CallbackBase):
validate_certs=self.validate_nrdp_certs)
return response.read()
except Exception as ex:
- self._display.warning("NRDP callback cannot send result {0}".format(ex))
+ self._display.warning(f"NRDP callback cannot send result {ex}")
def v2_playbook_on_play_start(self, play):
'''
@@ -170,17 +169,16 @@ class CallbackModule(CallbackBase):
critical = warning = 0
for host in hosts:
stat = stats.summarize(host)
- gstats += "'%s_ok'=%d '%s_changed'=%d \
- '%s_unreachable'=%d '%s_failed'=%d " % \
- (host, stat['ok'], host, stat['changed'],
- host, stat['unreachable'], host, stat['failures'])
+ gstats += (
+ f"'{host}_ok'={stat['ok']} '{host}_changed'={stat['changed']} '{host}_unreachable'={stat['unreachable']} '{host}_failed'={stat['failures']} "
+ )
# Critical when failed tasks or unreachable host
critical += stat['failures']
critical += stat['unreachable']
# Warning when changed tasks
warning += stat['changed']
- msg = "%s | %s" % (name, gstats)
+ msg = f"{name} | {gstats}"
if critical:
# Send Critical
self._send_nrdp(self.CRITICAL, msg)
diff --git a/plugins/callback/null.py b/plugins/callback/null.py
index 6aeeba313a..b59389e39a 100644
--- a/plugins/callback/null.py
+++ b/plugins/callback/null.py
@@ -4,19 +4,18 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: 'null'
- type: stdout
- requirements:
- - set as main display callback
- short_description: Don't display stuff to screen
- description:
- - This callback prevents outputting events to screen.
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: 'null'
+type: stdout
+requirements:
+ - set as main display callback
+short_description: do not display stuff to screen
+description:
+ - This callback prevents outputting events to screen.
+"""
from ansible.plugins.callback import CallbackBase
diff --git a/plugins/callback/opentelemetry.py b/plugins/callback/opentelemetry.py
index 8dc627c214..039408f301 100644
--- a/plugins/callback/opentelemetry.py
+++ b/plugins/callback/opentelemetry.py
@@ -3,122 +3,122 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Victor Martinez (@v1v)
- name: opentelemetry
- type: notification
- short_description: Create distributed traces with OpenTelemetry
- version_added: 3.7.0
+DOCUMENTATION = r"""
+author: Victor Martinez (@v1v)
+name: opentelemetry
+type: notification
+short_description: Create distributed traces with OpenTelemetry
+version_added: 3.7.0
+description:
+ - This callback creates distributed traces for each Ansible task with OpenTelemetry.
+ - You can configure the OpenTelemetry exporter and SDK with environment variables.
+ - See U(https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html).
+ - See
+ U(https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html#opentelemetry-sdk-environment-variables).
+options:
+ hide_task_arguments:
+ default: false
+ type: bool
description:
- - This callback creates distributed traces for each Ansible task with OpenTelemetry.
- - You can configure the OpenTelemetry exporter and SDK with environment variables.
- - See U(https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html).
- - See U(https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html#opentelemetry-sdk-environment-variables).
- options:
- hide_task_arguments:
- default: false
- type: bool
- description:
- - Hide the arguments for a task.
- env:
- - name: ANSIBLE_OPENTELEMETRY_HIDE_TASK_ARGUMENTS
- ini:
- - section: callback_opentelemetry
- key: hide_task_arguments
- version_added: 5.3.0
- enable_from_environment:
- type: str
- description:
- - Whether to enable this callback only if the given environment variable exists and it is set to V(true).
- - This is handy when you use Configuration as Code and want to send distributed traces
- if running in the CI rather when running Ansible locally.
- - For such, it evaluates the given O(enable_from_environment) value as environment variable
- and if set to true this plugin will be enabled.
- env:
- - name: ANSIBLE_OPENTELEMETRY_ENABLE_FROM_ENVIRONMENT
- ini:
- - section: callback_opentelemetry
- key: enable_from_environment
- version_added: 5.3.0
- version_added: 3.8.0
- otel_service_name:
- default: ansible
- type: str
- description:
- - The service name resource attribute.
- env:
- - name: OTEL_SERVICE_NAME
- ini:
- - section: callback_opentelemetry
- key: otel_service_name
- version_added: 5.3.0
- traceparent:
- default: None
- type: str
- description:
- - The L(W3C Trace Context header traceparent,https://www.w3.org/TR/trace-context-1/#traceparent-header).
- env:
- - name: TRACEPARENT
- disable_logs:
- default: false
- type: bool
- description:
- - Disable sending logs.
- env:
- - name: ANSIBLE_OPENTELEMETRY_DISABLE_LOGS
- ini:
- - section: callback_opentelemetry
- key: disable_logs
- version_added: 5.8.0
- disable_attributes_in_logs:
- default: false
- type: bool
- description:
- - Disable populating span attributes to the logs.
- env:
- - name: ANSIBLE_OPENTELEMETRY_DISABLE_ATTRIBUTES_IN_LOGS
- ini:
- - section: callback_opentelemetry
- key: disable_attributes_in_logs
- version_added: 7.1.0
- store_spans_in_file:
- type: str
- description:
- - It stores the exported spans in the given file
- env:
- - name: ANSIBLE_OPENTELEMETRY_STORE_SPANS_IN_FILE
- ini:
- - section: callback_opentelemetry
- key: store_spans_in_file
- version_added: 9.0.0
- otel_exporter_otlp_traces_protocol:
- type: str
- description:
- - E(OTEL_EXPORTER_OTLP_TRACES_PROTOCOL) represents the the transport protocol for spans.
- - See
- U(https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html#envvar-OTEL_EXPORTER_OTLP_TRACES_PROTOCOL).
- default: grpc
- choices:
- - grpc
- - http/protobuf
- env:
- - name: OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
- ini:
- - section: callback_opentelemetry
- key: otel_exporter_otlp_traces_protocol
- version_added: 9.0.0
- requirements:
- - opentelemetry-api (Python library)
- - opentelemetry-exporter-otlp (Python library)
- - opentelemetry-sdk (Python library)
-'''
+ - Hide the arguments for a task.
+ env:
+ - name: ANSIBLE_OPENTELEMETRY_HIDE_TASK_ARGUMENTS
+ ini:
+ - section: callback_opentelemetry
+ key: hide_task_arguments
+ version_added: 5.3.0
+ enable_from_environment:
+ type: str
+ description:
+ - Whether to enable this callback only if the given environment variable exists and it is set to V(true).
+ - This is handy when you use Configuration as Code and want to send distributed traces if running in the CI rather when
+ running Ansible locally.
+ - For such, it evaluates the given O(enable_from_environment) value as environment variable and if set to true this
+ plugin will be enabled.
+ env:
+ - name: ANSIBLE_OPENTELEMETRY_ENABLE_FROM_ENVIRONMENT
+ ini:
+ - section: callback_opentelemetry
+ key: enable_from_environment
+ version_added: 5.3.0
+ version_added: 3.8.0
+ otel_service_name:
+ default: ansible
+ type: str
+ description:
+ - The service name resource attribute.
+ env:
+ - name: OTEL_SERVICE_NAME
+ ini:
+ - section: callback_opentelemetry
+ key: otel_service_name
+ version_added: 5.3.0
+ traceparent:
+ default: None
+ type: str
+ description:
+ - The L(W3C Trace Context header traceparent,https://www.w3.org/TR/trace-context-1/#traceparent-header).
+ env:
+ - name: TRACEPARENT
+ disable_logs:
+ default: false
+ type: bool
+ description:
+ - Disable sending logs.
+ env:
+ - name: ANSIBLE_OPENTELEMETRY_DISABLE_LOGS
+ ini:
+ - section: callback_opentelemetry
+ key: disable_logs
+ version_added: 5.8.0
+ disable_attributes_in_logs:
+ default: false
+ type: bool
+ description:
+ - Disable populating span attributes to the logs.
+ env:
+ - name: ANSIBLE_OPENTELEMETRY_DISABLE_ATTRIBUTES_IN_LOGS
+ ini:
+ - section: callback_opentelemetry
+ key: disable_attributes_in_logs
+ version_added: 7.1.0
+ store_spans_in_file:
+ type: str
+ description:
+ - It stores the exported spans in the given file.
+ env:
+ - name: ANSIBLE_OPENTELEMETRY_STORE_SPANS_IN_FILE
+ ini:
+ - section: callback_opentelemetry
+ key: store_spans_in_file
+ version_added: 9.0.0
+ otel_exporter_otlp_traces_protocol:
+ type: str
+ description:
+ - E(OTEL_EXPORTER_OTLP_TRACES_PROTOCOL) represents the the transport protocol for spans.
+ - See
+ U(https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html#envvar-OTEL_EXPORTER_OTLP_TRACES_PROTOCOL).
+ default: grpc
+ choices:
+ - grpc
+ - http/protobuf
+ env:
+ - name: OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
+ ini:
+ - section: callback_opentelemetry
+ key: otel_exporter_otlp_traces_protocol
+ version_added: 9.0.0
+requirements:
+ - opentelemetry-api (Python library)
+ - opentelemetry-exporter-otlp (Python library)
+ - opentelemetry-sdk (Python library)
+"""
-EXAMPLES = '''
-examples: |
+EXAMPLES = r"""
+examples: |-
Enable the plugin in ansible.cfg:
[defaults]
callbacks_enabled = community.general.opentelemetry
@@ -130,15 +130,14 @@ examples: |
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer your_otel_token"
export OTEL_SERVICE_NAME=your_service_name
export ANSIBLE_OPENTELEMETRY_ENABLED=true
-'''
+"""
import getpass
import json
import os
import socket
-import sys
-import time
import uuid
+from time import time_ns
from collections import OrderedDict
from os.path import basename
@@ -164,31 +163,12 @@ try:
from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
InMemorySpanExporter
)
- # Support for opentelemetry-api <= 1.12
- try:
- from opentelemetry.util._time import _time_ns
- except ImportError as imp_exc:
- OTEL_LIBRARY_TIME_NS_ERROR = imp_exc
- else:
- OTEL_LIBRARY_TIME_NS_ERROR = None
-
except ImportError as imp_exc:
OTEL_LIBRARY_IMPORT_ERROR = imp_exc
- OTEL_LIBRARY_TIME_NS_ERROR = imp_exc
else:
OTEL_LIBRARY_IMPORT_ERROR = None
-if sys.version_info >= (3, 7):
- time_ns = time.time_ns
-elif not OTEL_LIBRARY_TIME_NS_ERROR:
- time_ns = _time_ns
-else:
- def time_ns():
- # Support versions older than 3.7 with opentelemetry-api > 1.12
- return int(time.time() * 1e9)
-
-
class TaskData:
"""
Data about an individual task.
@@ -209,7 +189,7 @@ class TaskData:
if host.uuid in self.host_data:
if host.status == 'included':
# concatenate task include output from multiple items
- host.result = '%s\n%s' % (self.host_data[host.uuid].result, host.result)
+ host.result = f'{self.host_data[host.uuid].result}\n{host.result}'
else:
return
@@ -347,7 +327,7 @@ class OpenTelemetrySource(object):
def update_span_data(self, task_data, host_data, span, disable_logs, disable_attributes_in_logs):
""" update the span with the given TaskData and HostData """
- name = '[%s] %s: %s' % (host_data.name, task_data.play, task_data.name)
+ name = f'[{host_data.name}] {task_data.play}: {task_data.name}'
message = 'success'
res = {}
@@ -470,7 +450,7 @@ class OpenTelemetrySource(object):
def get_error_message_from_results(results, action):
for result in results:
if result.get('failed', False):
- return ('{0}({1}) - {2}').format(action, result.get('item', 'none'), OpenTelemetrySource.get_error_message(result))
+ return f"{action}({result.get('item', 'none')}) - {OpenTelemetrySource.get_error_message(result)}"
@staticmethod
def _last_line(text):
@@ -482,14 +462,14 @@ class OpenTelemetrySource(object):
message = result.get('msg', 'failed')
exception = result.get('exception')
stderr = result.get('stderr')
- return ('message: "{0}"\nexception: "{1}"\nstderr: "{2}"').format(message, exception, stderr)
+ return f"message: \"{message}\"\nexception: \"{exception}\"\nstderr: \"{stderr}\""
@staticmethod
def enrich_error_message_from_results(results, action):
message = ""
for result in results:
if result.get('failed', False):
- message = ('{0}({1}) - {2}\n{3}').format(action, result.get('item', 'none'), OpenTelemetrySource.enrich_error_message(result), message)
+ message = f"{action}({result.get('item', 'none')}) - {OpenTelemetrySource.enrich_error_message(result)}\n{message}"
return message
@@ -535,8 +515,9 @@ class CallbackModule(CallbackBase):
environment_variable = self.get_option('enable_from_environment')
if environment_variable is not None and os.environ.get(environment_variable, 'false').lower() != 'true':
self.disabled = True
- self._display.warning("The `enable_from_environment` option has been set and {0} is not enabled. "
- "Disabling the `opentelemetry` callback plugin.".format(environment_variable))
+ self._display.warning(
+ f"The `enable_from_environment` option has been set and {environment_variable} is not enabled. Disabling the `opentelemetry` callback plugin."
+ )
self.hide_task_arguments = self.get_option('hide_task_arguments')
diff --git a/plugins/callback/say.py b/plugins/callback/say.py
index 9d96ad74d9..e6da490ec7 100644
--- a/plugins/callback/say.py
+++ b/plugins/callback/say.py
@@ -5,20 +5,19 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: say
- type: notification
- requirements:
- - whitelisting in configuration
- - the C(/usr/bin/say) command line program (standard on macOS) or C(espeak) command line program
- short_description: notify using software speech synthesizer
- description:
- - This plugin will use the C(say) or C(espeak) program to "speak" about play events.
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: say
+type: notification
+requirements:
+ - whitelisting in configuration
+ - the C(/usr/bin/say) command line program (standard on macOS) or C(espeak) command line program
+short_description: notify using software speech synthesizer
+description:
+ - This plugin will use the C(say) or C(espeak) program to "speak" about play events.
+"""
import platform
import subprocess
@@ -50,7 +49,7 @@ class CallbackModule(CallbackBase):
self.synthesizer = get_bin_path('say')
if platform.system() != 'Darwin':
# 'say' binary available, it might be GNUstep tool which doesn't support 'voice' parameter
- self._display.warning("'say' executable found but system is '%s': ignoring voice parameter" % platform.system())
+ self._display.warning(f"'say' executable found but system is '{platform.system()}': ignoring voice parameter")
else:
self.FAILED_VOICE = 'Zarvox'
self.REGULAR_VOICE = 'Trinoids'
@@ -69,7 +68,7 @@ class CallbackModule(CallbackBase):
# ansible will not call any callback if disabled is set to True
if not self.synthesizer:
self.disabled = True
- self._display.warning("Unable to find either 'say' or 'espeak' executable, plugin %s disabled" % os.path.basename(__file__))
+ self._display.warning(f"Unable to find either 'say' or 'espeak' executable, plugin {os.path.basename(__file__)} disabled")
def say(self, msg, voice):
cmd = [self.synthesizer, msg]
@@ -78,7 +77,7 @@ class CallbackModule(CallbackBase):
subprocess.call(cmd)
def runner_on_failed(self, host, res, ignore_errors=False):
- self.say("Failure on host %s" % host, self.FAILED_VOICE)
+ self.say(f"Failure on host {host}", self.FAILED_VOICE)
def runner_on_ok(self, host, res):
self.say("pew", self.LASER_VOICE)
@@ -87,13 +86,13 @@ class CallbackModule(CallbackBase):
self.say("pew", self.LASER_VOICE)
def runner_on_unreachable(self, host, res):
- self.say("Failure on host %s" % host, self.FAILED_VOICE)
+ self.say(f"Failure on host {host}", self.FAILED_VOICE)
def runner_on_async_ok(self, host, res, jid):
self.say("pew", self.LASER_VOICE)
def runner_on_async_failed(self, host, res, jid):
- self.say("Failure on host %s" % host, self.FAILED_VOICE)
+ self.say(f"Failure on host {host}", self.FAILED_VOICE)
def playbook_on_start(self):
self.say("Running Playbook", self.REGULAR_VOICE)
@@ -103,15 +102,15 @@ class CallbackModule(CallbackBase):
def playbook_on_task_start(self, name, is_conditional):
if not is_conditional:
- self.say("Starting task: %s" % name, self.REGULAR_VOICE)
+ self.say(f"Starting task: {name}", self.REGULAR_VOICE)
else:
- self.say("Notifying task: %s" % name, self.REGULAR_VOICE)
+ self.say(f"Notifying task: {name}", self.REGULAR_VOICE)
def playbook_on_setup(self):
self.say("Gathering facts", self.REGULAR_VOICE)
def playbook_on_play_start(self, name):
- self.say("Starting play: %s" % name, self.HAPPY_VOICE)
+ self.say(f"Starting play: {name}", self.HAPPY_VOICE)
def playbook_on_stats(self, stats):
self.say("Play complete", self.HAPPY_VOICE)
diff --git a/plugins/callback/selective.py b/plugins/callback/selective.py
index 0696757837..9cc805d3cd 100644
--- a/plugins/callback/selective.py
+++ b/plugins/callback/selective.py
@@ -4,38 +4,37 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: selective
- type: stdout
- requirements:
- - set as main display callback
- short_description: only print certain tasks
- description:
- - This callback only prints tasks that have been tagged with C(print_action) or that have failed.
- This allows operators to focus on the tasks that provide value only.
- - Tasks that are not printed are placed with a C(.).
- - If you increase verbosity all tasks are printed.
- options:
- nocolor:
- default: false
- description: This setting allows suppressing colorizing output.
- env:
- - name: ANSIBLE_NOCOLOR
- - name: ANSIBLE_SELECTIVE_DONT_COLORIZE
- ini:
- - section: defaults
- key: nocolor
- type: boolean
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: selective
+type: stdout
+requirements:
+ - set as main display callback
+short_description: only print certain tasks
+description:
+ - This callback only prints tasks that have been tagged with C(print_action) or that have failed. This allows operators
+ to focus on the tasks that provide value only.
+ - Tasks that are not printed are placed with a C(.).
+ - If you increase verbosity all tasks are printed.
+options:
+ nocolor:
+ default: false
+ description: This setting allows suppressing colorizing output.
+ env:
+ - name: ANSIBLE_NOCOLOR
+ - name: ANSIBLE_SELECTIVE_DONT_COLORIZE
+ ini:
+ - section: defaults
+ key: nocolor
+ type: boolean
+"""
-EXAMPLES = """
- - ansible.builtin.debug: msg="This will not be printed"
- - ansible.builtin.debug: msg="But this will"
- tags: [print_action]
+EXAMPLES = r"""
+- ansible.builtin.debug: msg="This will not be printed"
+- ansible.builtin.debug: msg="But this will"
+ tags: [print_action]
"""
import difflib
@@ -48,13 +47,13 @@ from ansible.module_utils.common.text.converters import to_text
DONT_COLORIZE = False
COLORS = {
'normal': '\033[0m',
- 'ok': '\033[{0}m'.format(C.COLOR_CODES[C.COLOR_OK]),
+ 'ok': f'\x1b[{C.COLOR_CODES[C.COLOR_OK]}m',
'bold': '\033[1m',
'not_so_bold': '\033[1m\033[34m',
- 'changed': '\033[{0}m'.format(C.COLOR_CODES[C.COLOR_CHANGED]),
- 'failed': '\033[{0}m'.format(C.COLOR_CODES[C.COLOR_ERROR]),
+ 'changed': f'\x1b[{C.COLOR_CODES[C.COLOR_CHANGED]}m',
+ 'failed': f'\x1b[{C.COLOR_CODES[C.COLOR_ERROR]}m',
'endc': '\033[0m',
- 'skipped': '\033[{0}m'.format(C.COLOR_CODES[C.COLOR_SKIP]),
+ 'skipped': f'\x1b[{C.COLOR_CODES[C.COLOR_SKIP]}m',
}
@@ -73,7 +72,7 @@ def colorize(msg, color):
if DONT_COLORIZE:
return msg
else:
- return '{0}{1}{2}'.format(COLORS[color], msg, COLORS['endc'])
+ return f"{COLORS[color]}{msg}{COLORS['endc']}"
class CallbackModule(CallbackBase):
@@ -106,15 +105,15 @@ class CallbackModule(CallbackBase):
line_length = 120
if self.last_skipped:
print()
- line = "# {0} ".format(task_name)
- msg = colorize("{0}{1}".format(line, '*' * (line_length - len(line))), 'bold')
+ line = f"# {task_name} "
+ msg = colorize(f"{line}{'*' * (line_length - len(line))}", 'bold')
print(msg)
def _indent_text(self, text, indent_level):
lines = text.splitlines()
result_lines = []
for l in lines:
- result_lines.append("{0}{1}".format(' ' * indent_level, l))
+ result_lines.append(f"{' ' * indent_level}{l}")
return '\n'.join(result_lines)
def _print_diff(self, diff, indent_level):
@@ -147,19 +146,19 @@ class CallbackModule(CallbackBase):
change_string = colorize('FAILED!!!', color)
else:
color = 'changed' if changed else 'ok'
- change_string = colorize("changed={0}".format(changed), color)
+ change_string = colorize(f"changed={changed}", color)
msg = colorize(msg, color)
line_length = 120
spaces = ' ' * (40 - len(name) - indent_level)
- line = "{0} * {1}{2}- {3}".format(' ' * indent_level, name, spaces, change_string)
+ line = f"{' ' * indent_level} * {name}{spaces}- {change_string}"
if len(msg) < 50:
- line += ' -- {0}'.format(msg)
- print("{0} {1}---------".format(line, '-' * (line_length - len(line))))
+ line += f' -- {msg}'
+ print(f"{line} {'-' * (line_length - len(line))}---------")
else:
- print("{0} {1}".format(line, '-' * (line_length - len(line))))
+ print(f"{line} {'-' * (line_length - len(line))}")
print(self._indent_text(msg, indent_level + 4))
if diff:
@@ -239,8 +238,10 @@ class CallbackModule(CallbackBase):
else:
color = 'ok'
- msg = '{0} : ok={1}\tchanged={2}\tfailed={3}\tunreachable={4}\trescued={5}\tignored={6}'.format(
- host, s['ok'], s['changed'], s['failures'], s['unreachable'], s['rescued'], s['ignored'])
+ msg = (
+ f"{host} : ok={s['ok']}\tchanged={s['changed']}\tfailed={s['failures']}\tunreachable="
+ f"{s['unreachable']}\trescued={s['rescued']}\tignored={s['ignored']}"
+ )
print(colorize(msg, color))
def v2_runner_on_skipped(self, result, **kwargs):
@@ -252,17 +253,15 @@ class CallbackModule(CallbackBase):
line_length = 120
spaces = ' ' * (31 - len(result._host.name) - 4)
- line = " * {0}{1}- {2}".format(colorize(result._host.name, 'not_so_bold'),
- spaces,
- colorize("skipped", 'skipped'),)
+ line = f" * {colorize(result._host.name, 'not_so_bold')}{spaces}- {colorize('skipped', 'skipped')}"
reason = result._result.get('skipped_reason', '') or \
result._result.get('skip_reason', '')
if len(reason) < 50:
- line += ' -- {0}'.format(reason)
- print("{0} {1}---------".format(line, '-' * (line_length - len(line))))
+ line += f' -- {reason}'
+ print(f"{line} {'-' * (line_length - len(line))}---------")
else:
- print("{0} {1}".format(line, '-' * (line_length - len(line))))
+ print(f"{line} {'-' * (line_length - len(line))}")
print(self._indent_text(reason, 8))
print(reason)
diff --git a/plugins/callback/slack.py b/plugins/callback/slack.py
index 2a995992ee..8bb081a541 100644
--- a/plugins/callback/slack.py
+++ b/plugins/callback/slack.py
@@ -5,64 +5,67 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: slack
- type: notification
- requirements:
- - whitelist in configuration
- - prettytable (python library)
- short_description: Sends play events to a Slack channel
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: slack
+type: notification
+requirements:
+ - whitelist in configuration
+ - prettytable (python library)
+short_description: Sends play events to a Slack channel
+description:
+ - This is an ansible callback plugin that sends status updates to a Slack channel during playbook execution.
+options:
+ http_agent:
description:
- - This is an ansible callback plugin that sends status updates to a Slack channel during playbook execution.
- options:
- webhook_url:
- required: true
- description: Slack Webhook URL.
- type: str
- env:
- - name: SLACK_WEBHOOK_URL
- ini:
- - section: callback_slack
- key: webhook_url
- channel:
- default: "#ansible"
- description: Slack room to post in.
- type: str
- env:
- - name: SLACK_CHANNEL
- ini:
- - section: callback_slack
- key: channel
- username:
- description: Username to post as.
- type: str
- env:
- - name: SLACK_USERNAME
- default: ansible
- ini:
- - section: callback_slack
- key: username
- validate_certs:
- description: Validate the SSL certificate of the Slack server for HTTPS URLs.
- env:
- - name: SLACK_VALIDATE_CERTS
- ini:
- - section: callback_slack
- key: validate_certs
- default: true
- type: bool
-'''
+ - HTTP user agent to use for requests to Slack.
+ type: string
+ version_added: "10.5.0"
+ webhook_url:
+ required: true
+ description: Slack Webhook URL.
+ type: str
+ env:
+ - name: SLACK_WEBHOOK_URL
+ ini:
+ - section: callback_slack
+ key: webhook_url
+ channel:
+ default: "#ansible"
+ description: Slack room to post in.
+ type: str
+ env:
+ - name: SLACK_CHANNEL
+ ini:
+ - section: callback_slack
+ key: channel
+ username:
+ description: Username to post as.
+ type: str
+ env:
+ - name: SLACK_USERNAME
+ default: ansible
+ ini:
+ - section: callback_slack
+ key: username
+ validate_certs:
+ description: Validate the SSL certificate of the Slack server for HTTPS URLs.
+ env:
+ - name: SLACK_VALIDATE_CERTS
+ ini:
+ - section: callback_slack
+ key: validate_certs
+ default: true
+ type: bool
+"""
import json
import os
import uuid
from ansible import context
-from ansible.module_utils.common.text.converters import to_text
from ansible.module_utils.urls import open_url
from ansible.plugins.callback import CallbackBase
@@ -108,7 +111,7 @@ class CallbackModule(CallbackBase):
self.username = self.get_option('username')
self.show_invocation = (self._display.verbosity > 1)
self.validate_certs = self.get_option('validate_certs')
-
+ self.http_agent = self.get_option('http_agent')
if self.webhook_url is None:
self.disabled = True
self._display.warning('Slack Webhook URL was not provided. The '
@@ -134,18 +137,22 @@ class CallbackModule(CallbackBase):
self._display.debug(data)
self._display.debug(self.webhook_url)
try:
- response = open_url(self.webhook_url, data=data, validate_certs=self.validate_certs,
- headers=headers)
+ response = open_url(
+ self.webhook_url,
+ data=data,
+ validate_certs=self.validate_certs,
+ headers=headers,
+ http_agent=self.http_agent,
+ )
return response.read()
except Exception as e:
- self._display.warning(u'Could not submit message to Slack: %s' %
- to_text(e))
+ self._display.warning(f'Could not submit message to Slack: {e}')
def v2_playbook_on_start(self, playbook):
self.playbook_name = os.path.basename(playbook._file_name)
title = [
- '*Playbook initiated* (_%s_)' % self.guid
+ f'*Playbook initiated* (_{self.guid}_)'
]
invocation_items = []
@@ -156,23 +163,23 @@ class CallbackModule(CallbackBase):
subset = context.CLIARGS['subset']
inventory = [os.path.abspath(i) for i in context.CLIARGS['inventory']]
- invocation_items.append('Inventory: %s' % ', '.join(inventory))
+ invocation_items.append(f"Inventory: {', '.join(inventory)}")
if tags and tags != ['all']:
- invocation_items.append('Tags: %s' % ', '.join(tags))
+ invocation_items.append(f"Tags: {', '.join(tags)}")
if skip_tags:
- invocation_items.append('Skip Tags: %s' % ', '.join(skip_tags))
+ invocation_items.append(f"Skip Tags: {', '.join(skip_tags)}")
if subset:
- invocation_items.append('Limit: %s' % subset)
+ invocation_items.append(f'Limit: {subset}')
if extra_vars:
- invocation_items.append('Extra Vars: %s' %
- ' '.join(extra_vars))
+ invocation_items.append(f"Extra Vars: {' '.join(extra_vars)}")
- title.append('by *%s*' % context.CLIARGS['remote_user'])
+ title.append(f"by *{context.CLIARGS['remote_user']}*")
- title.append('\n\n*%s*' % self.playbook_name)
+ title.append(f'\n\n*{self.playbook_name}*')
msg_items = [' '.join(title)]
if invocation_items:
- msg_items.append('```\n%s\n```' % '\n'.join(invocation_items))
+ _inv_item = '\n'.join(invocation_items)
+ msg_items.append(f'```\n{_inv_item}\n```')
msg = '\n'.join(msg_items)
@@ -192,8 +199,8 @@ class CallbackModule(CallbackBase):
def v2_playbook_on_play_start(self, play):
"""Display Play start messages"""
- name = play.name or 'Play name not specified (%s)' % play._uuid
- msg = '*Starting play* (_%s_)\n\n*%s*' % (self.guid, name)
+ name = play.name or f'Play name not specified ({play._uuid})'
+ msg = f'*Starting play* (_{self.guid}_)\n\n*{name}*'
attachments = [
{
'fallback': msg,
@@ -228,7 +235,7 @@ class CallbackModule(CallbackBase):
attachments = []
msg_items = [
- '*Playbook Complete* (_%s_)' % self.guid
+ f'*Playbook Complete* (_{self.guid}_)'
]
if failures or unreachable:
color = 'danger'
@@ -237,7 +244,7 @@ class CallbackModule(CallbackBase):
color = 'good'
msg_items.append('\n*Success!*')
- msg_items.append('```\n%s\n```' % t)
+ msg_items.append(f'```\n{t}\n```')
msg = '\n'.join(msg_items)
diff --git a/plugins/callback/splunk.py b/plugins/callback/splunk.py
index b2ce48de25..1d4534892a 100644
--- a/plugins/callback/splunk.py
+++ b/plugins/callback/splunk.py
@@ -3,76 +3,75 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: splunk
- type: notification
- short_description: Sends task result events to Splunk HTTP Event Collector
- author: "Stuart Hirst (!UNKNOWN) "
+DOCUMENTATION = r"""
+name: splunk
+type: notification
+short_description: Sends task result events to Splunk HTTP Event Collector
+author: "Stuart Hirst (!UNKNOWN) "
+description:
+ - This callback plugin will send task results as JSON formatted events to a Splunk HTTP collector.
+ - The companion Splunk Monitoring & Diagnostics App is available here U(https://splunkbase.splunk.com/app/4023/).
+ - Credit to "Ryan Currah (@ryancurrah)" for original source upon which this is based.
+requirements:
+ - Whitelisting this callback plugin
+ - 'Create a HTTP Event Collector in Splunk'
+ - 'Define the URL and token in C(ansible.cfg)'
+options:
+ url:
+ description: URL to the Splunk HTTP collector source.
+ type: str
+ env:
+ - name: SPLUNK_URL
+ ini:
+ - section: callback_splunk
+ key: url
+ authtoken:
+ description: Token to authenticate the connection to the Splunk HTTP collector.
+ type: str
+ env:
+ - name: SPLUNK_AUTHTOKEN
+ ini:
+ - section: callback_splunk
+ key: authtoken
+ validate_certs:
+ description: Whether to validate certificates for connections to HEC. It is not recommended to set to V(false) except
+ when you are sure that nobody can intercept the connection between this plugin and HEC, as setting it to V(false) allows
+ man-in-the-middle attacks!
+ env:
+ - name: SPLUNK_VALIDATE_CERTS
+ ini:
+ - section: callback_splunk
+ key: validate_certs
+ type: bool
+ default: true
+ version_added: '1.0.0'
+ include_milliseconds:
+ description: Whether to include milliseconds as part of the generated timestamp field in the event sent to the Splunk
+ HTTP collector.
+ env:
+ - name: SPLUNK_INCLUDE_MILLISECONDS
+ ini:
+ - section: callback_splunk
+ key: include_milliseconds
+ type: bool
+ default: false
+ version_added: 2.0.0
+ batch:
description:
- - This callback plugin will send task results as JSON formatted events to a Splunk HTTP collector.
- - The companion Splunk Monitoring & Diagnostics App is available here U(https://splunkbase.splunk.com/app/4023/).
- - Credit to "Ryan Currah (@ryancurrah)" for original source upon which this is based.
- requirements:
- - Whitelisting this callback plugin
- - 'Create a HTTP Event Collector in Splunk'
- - 'Define the URL and token in C(ansible.cfg)'
- options:
- url:
- description: URL to the Splunk HTTP collector source.
- type: str
- env:
- - name: SPLUNK_URL
- ini:
- - section: callback_splunk
- key: url
- authtoken:
- description: Token to authenticate the connection to the Splunk HTTP collector.
- type: str
- env:
- - name: SPLUNK_AUTHTOKEN
- ini:
- - section: callback_splunk
- key: authtoken
- validate_certs:
- description: Whether to validate certificates for connections to HEC. It is not recommended to set to
- V(false) except when you are sure that nobody can intercept the connection
- between this plugin and HEC, as setting it to V(false) allows man-in-the-middle attacks!
- env:
- - name: SPLUNK_VALIDATE_CERTS
- ini:
- - section: callback_splunk
- key: validate_certs
- type: bool
- default: true
- version_added: '1.0.0'
- include_milliseconds:
- description: Whether to include milliseconds as part of the generated timestamp field in the event
- sent to the Splunk HTTP collector.
- env:
- - name: SPLUNK_INCLUDE_MILLISECONDS
- ini:
- - section: callback_splunk
- key: include_milliseconds
- type: bool
- default: false
- version_added: 2.0.0
- batch:
- description:
- - Correlation ID which can be set across multiple playbook executions.
- env:
- - name: SPLUNK_BATCH
- ini:
- - section: callback_splunk
- key: batch
- type: str
- version_added: 3.3.0
-'''
+ - Correlation ID which can be set across multiple playbook executions.
+ env:
+ - name: SPLUNK_BATCH
+ ini:
+ - section: callback_splunk
+ key: batch
+ type: str
+ version_added: 3.3.0
+"""
-EXAMPLES = '''
-examples: >
+EXAMPLES = r"""
+examples: >-
To enable, add this to your ansible.cfg file in the defaults block
[defaults]
callback_whitelist = community.general.splunk
@@ -83,7 +82,7 @@ examples: >
[callback_splunk]
url = http://mysplunkinstance.datapaas.io:8088/services/collector/event
authtoken = f23blad6-5965-4537-bf69-5b5a545blabla88
-'''
+"""
import json
import uuid
@@ -153,15 +152,14 @@ class SplunkHTTPCollectorSource(object):
data['ansible_result'] = result._result
# This wraps the json payload in and outer json event needed by Splunk
- jsondata = json.dumps(data, cls=AnsibleJSONEncoder, sort_keys=True)
- jsondata = '{"event":' + jsondata + "}"
+ jsondata = json.dumps({"event": data}, cls=AnsibleJSONEncoder, sort_keys=True)
open_url(
url,
jsondata,
headers={
'Content-type': 'application/json',
- 'Authorization': 'Splunk ' + authtoken
+ 'Authorization': f"Splunk {authtoken}"
},
method='POST',
validate_certs=validate_certs
diff --git a/plugins/callback/sumologic.py b/plugins/callback/sumologic.py
index 32ca6e0ed0..5c310d1c50 100644
--- a/plugins/callback/sumologic.py
+++ b/plugins/callback/sumologic.py
@@ -3,10 +3,9 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
name: sumologic
type: notification
short_description: Sends task result events to Sumologic
@@ -15,8 +14,8 @@ description:
- This callback plugin will send task results as JSON formatted events to a Sumologic HTTP collector source.
requirements:
- Whitelisting this callback plugin
- - 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of V(yyyy-MM-dd HH:mm:ss ZZZZ) and a custom timestamp locator
- of V("timestamp": "(.*\)")'
+ - 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of V(yyyy-MM-dd HH:mm:ss ZZZZ) and
+ a custom timestamp locator of V("timestamp": "(.*\)")'
options:
url:
description: URL to the Sumologic HTTP collector source.
@@ -26,10 +25,10 @@ options:
ini:
- section: callback_sumologic
key: url
-'''
+"""
-EXAMPLES = '''
-examples: |
+EXAMPLES = r"""
+examples: |-
To enable, add this to your ansible.cfg file in the defaults block
[defaults]
callback_whitelist = community.general.sumologic
@@ -40,7 +39,7 @@ examples: |
Set the ansible.cfg variable in the callback_sumologic block
[callback_sumologic]
url = https://endpoint1.collection.us2.sumologic.com/receiver/v1/http/R8moSv1d8EW9LAUFZJ6dbxCFxwLH6kfCdcBfddlfxCbLuL-BN5twcTpMk__pYy_cDmp==
-'''
+"""
import json
import uuid
diff --git a/plugins/callback/syslog_json.py b/plugins/callback/syslog_json.py
index 9066d8d9c5..9e5c78c90c 100644
--- a/plugins/callback/syslog_json.py
+++ b/plugins/callback/syslog_json.py
@@ -4,57 +4,56 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: syslog_json
- type: notification
- requirements:
- - whitelist in configuration
- short_description: sends JSON events to syslog
- description:
- - This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format.
- options:
- server:
- description: Syslog server that will receive the event.
- type: str
- env:
- - name: SYSLOG_SERVER
- default: localhost
- ini:
- - section: callback_syslog_json
- key: syslog_server
- port:
- description: Port on which the syslog server is listening.
- type: int
- env:
- - name: SYSLOG_PORT
- default: 514
- ini:
- - section: callback_syslog_json
- key: syslog_port
- facility:
- description: Syslog facility to log as.
- type: str
- env:
- - name: SYSLOG_FACILITY
- default: user
- 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
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: syslog_json
+type: notification
+requirements:
+ - whitelist in configuration
+short_description: sends JSON events to syslog
+description:
+ - This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format.
+options:
+ server:
+ description: Syslog server that will receive the event.
+ type: str
+ env:
+ - name: SYSLOG_SERVER
+ default: localhost
+ ini:
+ - section: callback_syslog_json
+ key: syslog_server
+ port:
+ description: Port on which the syslog server is listening.
+ type: int
+ env:
+ - name: SYSLOG_PORT
+ default: 514
+ ini:
+ - section: callback_syslog_json
+ key: syslog_port
+ facility:
+ description: Syslog facility to log as.
+ type: str
+ env:
+ - name: SYSLOG_FACILITY
+ default: user
+ 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 logging
import logging.handlers
diff --git a/plugins/callback/timestamp.py b/plugins/callback/timestamp.py
index 07cd8d239c..a43ddcbef9 100644
--- a/plugins/callback/timestamp.py
+++ b/plugins/callback/timestamp.py
@@ -5,51 +5,49 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
+from __future__ import annotations
-__metaclass__ = type
DOCUMENTATION = r"""
- name: timestamp
- type: stdout
- short_description: Adds simple timestamp for each header
- version_added: 9.0.0
- description:
- - This callback adds simple timestamp for each header.
- author: kurokobo (@kurokobo)
- options:
- timezone:
- description:
- - Timezone to use for the timestamp in IANA time zone format.
- - For example C(America/New_York), C(Asia/Tokyo)). Ignored on Python < 3.9.
- ini:
- - section: callback_timestamp
- key: timezone
- env:
- - name: ANSIBLE_CALLBACK_TIMESTAMP_TIMEZONE
- type: string
- format_string:
- description:
- - Format of the timestamp shown to user in 1989 C standard format.
- - >
- Refer to L(the Python documentation,https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)
- for the available format codes.
- ini:
- - section: callback_timestamp
- key: format_string
- env:
- - name: ANSIBLE_CALLBACK_TIMESTAMP_FORMAT_STRING
- default: "%H:%M:%S"
- type: string
- seealso:
- - plugin: ansible.posix.profile_tasks
- plugin_type: callback
- description: >
- You can use P(ansible.posix.profile_tasks#callback) callback plugin to time individual tasks and overall execution time
- with detailed timestamps.
- extends_documentation_fragment:
- - ansible.builtin.default_callback
- - ansible.builtin.result_format_callback
+name: timestamp
+type: stdout
+short_description: Adds simple timestamp for each header
+version_added: 9.0.0
+description:
+ - This callback adds simple timestamp for each header.
+author: kurokobo (@kurokobo)
+options:
+ timezone:
+ description:
+ - Timezone to use for the timestamp in IANA time zone format.
+ - For example V(America/New_York), V(Asia/Tokyo)). Ignored on Python < 3.9.
+ ini:
+ - section: callback_timestamp
+ key: timezone
+ env:
+ - name: ANSIBLE_CALLBACK_TIMESTAMP_TIMEZONE
+ type: string
+ format_string:
+ description:
+ - Format of the timestamp shown to user in 1989 C standard format.
+ - Refer to L(the Python documentation,https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)
+ for the available format codes.
+ ini:
+ - section: callback_timestamp
+ key: format_string
+ env:
+ - name: ANSIBLE_CALLBACK_TIMESTAMP_FORMAT_STRING
+ default: "%H:%M:%S"
+ type: string
+seealso:
+ - plugin: ansible.posix.profile_tasks
+ plugin_type: callback
+ description: >-
+ You can use P(ansible.posix.profile_tasks#callback) callback plugin to time individual tasks and overall execution time
+ with detailed timestamps.
+extends_documentation_fragment:
+ - ansible.builtin.default_callback
+ - ansible.builtin.result_format_callback
"""
@@ -85,7 +83,7 @@ def banner(self, msg, color=None, cows=True):
msg = to_text(msg)
if self.b_cowsay and cows:
try:
- self.banner_cowsay("%s @ %s" % (msg, timestamp))
+ self.banner_cowsay(f"{msg} @ {timestamp}")
return
except OSError:
self.warning("somebody cleverly deleted cowsay or something during the PB run. heh.")
@@ -98,7 +96,7 @@ def banner(self, msg, color=None, cows=True):
if star_len <= 3:
star_len = 3
stars = "*" * star_len
- self.display("\n%s %s %s" % (msg, stars, timestamp), color=color)
+ self.display(f"\n{msg} {stars} {timestamp}", color=color)
class CallbackModule(Default):
diff --git a/plugins/callback/unixy.py b/plugins/callback/unixy.py
index 4908202c23..48f9b2d1f0 100644
--- a/plugins/callback/unixy.py
+++ b/plugins/callback/unixy.py
@@ -5,21 +5,20 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: unixy
- type: stdout
- author: Al Bowles (@akatch)
- short_description: condensed Ansible output
- description:
- - Consolidated Ansible output in the style of LINUX/UNIX startup logs.
- extends_documentation_fragment:
- - default_callback
- requirements:
- - set as stdout in configuration
-'''
+DOCUMENTATION = r"""
+name: unixy
+type: stdout
+author: Al Bowles (@akatch)
+short_description: condensed Ansible output
+description:
+ - Consolidated Ansible output in the style of LINUX/UNIX startup logs.
+extends_documentation_fragment:
+ - default_callback
+requirements:
+ - set as stdout in configuration
+"""
from os.path import basename
from ansible import constants as C
@@ -67,24 +66,24 @@ class CallbackModule(CallbackModule_default):
def _process_result_output(self, result, msg):
task_host = result._host.get_name()
- task_result = "%s %s" % (task_host, msg)
+ task_result = f"{task_host} {msg}"
if self._run_is_verbose(result):
- task_result = "%s %s: %s" % (task_host, msg, self._dump_results(result._result, indent=4))
+ task_result = f"{task_host} {msg}: {self._dump_results(result._result, indent=4)}"
return task_result
if self.delegated_vars:
task_delegate_host = self.delegated_vars['ansible_host']
- task_result = "%s -> %s %s" % (task_host, task_delegate_host, msg)
+ task_result = f"{task_host} -> {task_delegate_host} {msg}"
if result._result.get('msg') and result._result.get('msg') != "All items completed":
- task_result += " | msg: " + to_text(result._result.get('msg'))
+ task_result += f" | msg: {to_text(result._result.get('msg'))}"
if result._result.get('stdout'):
- task_result += " | stdout: " + result._result.get('stdout')
+ task_result += f" | stdout: {result._result.get('stdout')}"
if result._result.get('stderr'):
- task_result += " | stderr: " + result._result.get('stderr')
+ task_result += f" | stderr: {result._result.get('stderr')}"
return task_result
@@ -92,30 +91,30 @@ class CallbackModule(CallbackModule_default):
self._get_task_display_name(task)
if self.task_display_name is not None:
if task.check_mode and self.get_option('check_mode_markers'):
- self._display.display("%s (check mode)..." % self.task_display_name)
+ self._display.display(f"{self.task_display_name} (check mode)...")
else:
- self._display.display("%s..." % self.task_display_name)
+ self._display.display(f"{self.task_display_name}...")
def v2_playbook_on_handler_task_start(self, task):
self._get_task_display_name(task)
if self.task_display_name is not None:
if task.check_mode and self.get_option('check_mode_markers'):
- self._display.display("%s (via handler in check mode)... " % self.task_display_name)
+ self._display.display(f"{self.task_display_name} (via handler in check mode)... ")
else:
- self._display.display("%s (via handler)... " % self.task_display_name)
+ self._display.display(f"{self.task_display_name} (via handler)... ")
def v2_playbook_on_play_start(self, play):
name = play.get_name().strip()
if play.check_mode and self.get_option('check_mode_markers'):
if name and play.hosts:
- msg = u"\n- %s (in check mode) on hosts: %s -" % (name, ",".join(play.hosts))
+ msg = f"\n- {name} (in check mode) on hosts: {','.join(play.hosts)} -"
else:
- msg = u"- check mode -"
+ msg = "- check mode -"
else:
if name and play.hosts:
- msg = u"\n- %s on hosts: %s -" % (name, ",".join(play.hosts))
+ msg = f"\n- {name} on hosts: {','.join(play.hosts)} -"
else:
- msg = u"---"
+ msg = "---"
self._display.display(msg)
@@ -126,7 +125,7 @@ class CallbackModule(CallbackModule_default):
msg = "skipped"
task_result = self._process_result_output(result, msg)
- self._display.display(" " + task_result, display_color)
+ self._display.display(f" {task_result}", display_color)
else:
return
@@ -136,10 +135,10 @@ class CallbackModule(CallbackModule_default):
msg = "failed"
item_value = self._get_item_label(result._result)
if item_value:
- msg += " | item: %s" % (item_value,)
+ msg += f" | item: {item_value}"
task_result = self._process_result_output(result, msg)
- self._display.display(" " + task_result, display_color, stderr=self.get_option('display_failed_stderr'))
+ self._display.display(f" {task_result}", display_color, stderr=self.get_option('display_failed_stderr'))
def v2_runner_on_ok(self, result, msg="ok", display_color=C.COLOR_OK):
self._preprocess_result(result)
@@ -149,13 +148,13 @@ class CallbackModule(CallbackModule_default):
msg = "done"
item_value = self._get_item_label(result._result)
if item_value:
- msg += " | item: %s" % (item_value,)
+ msg += f" | item: {item_value}"
display_color = C.COLOR_CHANGED
task_result = self._process_result_output(result, msg)
- self._display.display(" " + task_result, display_color)
+ self._display.display(f" {task_result}", display_color)
elif self.get_option('display_ok_hosts'):
task_result = self._process_result_output(result, msg)
- self._display.display(" " + task_result, display_color)
+ self._display.display(f" {task_result}", display_color)
def v2_runner_item_on_skipped(self, result):
self.v2_runner_on_skipped(result)
@@ -173,7 +172,7 @@ class CallbackModule(CallbackModule_default):
display_color = C.COLOR_UNREACHABLE
task_result = self._process_result_output(result, msg)
- self._display.display(" " + task_result, display_color, stderr=self.get_option('display_failed_stderr'))
+ self._display.display(f" {task_result}", display_color, stderr=self.get_option('display_failed_stderr'))
def v2_on_file_diff(self, result):
if result._task.loop and 'results' in result._result:
@@ -195,25 +194,17 @@ class CallbackModule(CallbackModule_default):
# TODO how else can we display these?
t = stats.summarize(h)
- self._display.display(u" %s : %s %s %s %s %s %s" % (
- hostcolor(h, t),
- colorize(u'ok', t['ok'], C.COLOR_OK),
- colorize(u'changed', t['changed'], C.COLOR_CHANGED),
- colorize(u'unreachable', t['unreachable'], C.COLOR_UNREACHABLE),
- colorize(u'failed', t['failures'], C.COLOR_ERROR),
- colorize(u'rescued', t['rescued'], C.COLOR_OK),
- colorize(u'ignored', t['ignored'], C.COLOR_WARN)),
+ self._display.display(
+ f" {hostcolor(h, t)} : {colorize('ok', t['ok'], C.COLOR_OK)} {colorize('changed', t['changed'], C.COLOR_CHANGED)} "
+ f"{colorize('unreachable', t['unreachable'], C.COLOR_UNREACHABLE)} {colorize('failed', t['failures'], C.COLOR_ERROR)} "
+ f"{colorize('rescued', t['rescued'], C.COLOR_OK)} {colorize('ignored', t['ignored'], C.COLOR_WARN)}",
screen_only=True
)
- self._display.display(u" %s : %s %s %s %s %s %s" % (
- hostcolor(h, t, False),
- colorize(u'ok', t['ok'], None),
- colorize(u'changed', t['changed'], None),
- colorize(u'unreachable', t['unreachable'], None),
- colorize(u'failed', t['failures'], None),
- colorize(u'rescued', t['rescued'], None),
- colorize(u'ignored', t['ignored'], None)),
+ self._display.display(
+ f" {hostcolor(h, t, False)} : {colorize('ok', t['ok'], None)} {colorize('changed', t['changed'], None)} "
+ f"{colorize('unreachable', t['unreachable'], None)} {colorize('failed', t['failures'], None)} {colorize('rescued', t['rescued'], None)} "
+ f"{colorize('ignored', t['ignored'], None)}",
log_only=True
)
if stats.custom and self.get_option('show_custom_stats'):
@@ -223,12 +214,14 @@ class CallbackModule(CallbackModule_default):
for k in sorted(stats.custom.keys()):
if k == '_run':
continue
- self._display.display('\t%s: %s' % (k, self._dump_results(stats.custom[k], indent=1).replace('\n', '')))
+ stat_val = self._dump_results(stats.custom[k], indent=1).replace('\n', '')
+ self._display.display(f'\t{k}: {stat_val}')
# print per run custom stats
if '_run' in stats.custom:
self._display.display("", screen_only=True)
- self._display.display('\tRUN: %s' % self._dump_results(stats.custom['_run'], indent=1).replace('\n', ''))
+ stat_val_run = self._dump_results(stats.custom['_run'], indent=1).replace('\n', '')
+ self._display.display(f'\tRUN: {stat_val_run}')
self._display.display("", screen_only=True)
def v2_playbook_on_no_hosts_matched(self):
@@ -239,23 +232,23 @@ class CallbackModule(CallbackModule_default):
def v2_playbook_on_start(self, playbook):
if context.CLIARGS['check'] and self.get_option('check_mode_markers'):
- self._display.display("Executing playbook %s in check mode" % basename(playbook._file_name))
+ self._display.display(f"Executing playbook {basename(playbook._file_name)} in check mode")
else:
- self._display.display("Executing playbook %s" % basename(playbook._file_name))
+ self._display.display(f"Executing playbook {basename(playbook._file_name)}")
# show CLI arguments
if self._display.verbosity > 3:
if context.CLIARGS.get('args'):
- self._display.display('Positional arguments: %s' % ' '.join(context.CLIARGS['args']),
+ self._display.display(f"Positional arguments: {' '.join(context.CLIARGS['args'])}",
color=C.COLOR_VERBOSE, screen_only=True)
for argument in (a for a in context.CLIARGS if a != 'args'):
val = context.CLIARGS[argument]
if val:
- self._display.vvvv('%s: %s' % (argument, val))
+ self._display.vvvv(f'{argument}: {val}')
def v2_runner_retry(self, result):
- msg = " Retrying... (%d of %d)" % (result._result['attempts'], result._result['retries'])
+ msg = f" Retrying... ({result._result['attempts']} of {result._result['retries']})"
if self._run_is_verbose(result):
- msg += "Result was: %s" % self._dump_results(result._result)
+ msg += f"Result was: {self._dump_results(result._result)}"
self._display.display(msg, color=C.COLOR_DEBUG)
diff --git a/plugins/callback/yaml.py b/plugins/callback/yaml.py
index e41f69ec53..25c797e236 100644
--- a/plugins/callback/yaml.py
+++ b/plugins/callback/yaml.py
@@ -4,32 +4,34 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Unknown (!UNKNOWN)
- name: yaml
- type: stdout
- short_description: YAML-ized Ansible screen output
- description:
- - Ansible output that can be quite a bit easier to read than the
- default JSON formatting.
- extends_documentation_fragment:
- - default_callback
- requirements:
- - set as stdout in configuration
- seealso:
- - plugin: ansible.builtin.default
- plugin_type: callback
- description: >
- There is a parameter O(ansible.builtin.default#callback:result_format) in P(ansible.builtin.default#callback)
- that allows you to change the output format to YAML.
- notes:
- - >
- With ansible-core 2.13 or newer, you can instead specify V(yaml) for the parameter O(ansible.builtin.default#callback:result_format)
- in P(ansible.builtin.default#callback).
-'''
+DOCUMENTATION = r"""
+author: Unknown (!UNKNOWN)
+name: yaml
+type: stdout
+short_description: YAML-ized Ansible screen output
+deprecated:
+ removed_in: 13.0.0
+ why: Starting in ansible-core 2.13, the P(ansible.builtin.default#callback) callback has support for printing output in
+ YAML format.
+ alternative: Use O(ansible.builtin.default#callback:result_format=yaml).
+description:
+ - Ansible output that can be quite a bit easier to read than the default JSON formatting.
+extends_documentation_fragment:
+ - default_callback
+requirements:
+ - set as stdout in configuration
+seealso:
+ - plugin: ansible.builtin.default
+ plugin_type: callback
+ description: >-
+ There is a parameter O(ansible.builtin.default#callback:result_format) in P(ansible.builtin.default#callback) that allows
+ you to change the output format to YAML.
+notes:
+ - With ansible-core 2.13 or newer, you can instead specify V(yaml) for the parameter O(ansible.builtin.default#callback:result_format)
+ in P(ansible.builtin.default#callback).
+"""
import yaml
import json
@@ -45,7 +47,7 @@ from ansible.plugins.callback.default import CallbackModule as Default
# from http://stackoverflow.com/a/15423007/115478
def should_use_block(value):
"""Returns true if string should be in block format"""
- for c in u"\u000a\u000d\u001c\u001d\u001e\u0085\u2028\u2029":
+ for c in "\u000a\u000d\u001c\u001d\u001e\u0085\u2028\u2029":
if c in value:
return True
return False
@@ -113,11 +115,11 @@ class CallbackModule(Default):
# put changed and skipped into a header line
if 'changed' in abridged_result:
- dumped += 'changed=' + str(abridged_result['changed']).lower() + ' '
+ dumped += f"changed={str(abridged_result['changed']).lower()} "
del abridged_result['changed']
if 'skipped' in abridged_result:
- dumped += 'skipped=' + str(abridged_result['skipped']).lower() + ' '
+ dumped += f"skipped={str(abridged_result['skipped']).lower()} "
del abridged_result['skipped']
# if we already have stdout, we don't need stdout_lines
diff --git a/plugins/connection/chroot.py b/plugins/connection/chroot.py
index 3567912359..842c3f05d3 100644
--- a/plugins/connection/chroot.py
+++ b/plugins/connection/chroot.py
@@ -7,82 +7,68 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Maykel Moya (!UNKNOWN)
- name: chroot
- short_description: Interact with local chroot
+DOCUMENTATION = r"""
+author: Maykel Moya (!UNKNOWN)
+name: chroot
+short_description: Interact with local chroot
+description:
+ - Run commands or put/fetch files to an existing chroot on the Ansible controller.
+options:
+ remote_addr:
description:
- - Run commands or put/fetch files to an existing chroot on the Ansible controller.
- options:
- remote_addr:
- description:
- - The path of the chroot you want to access.
- type: string
- default: inventory_hostname
- vars:
- - name: inventory_hostname
- - name: ansible_host
- executable:
- description:
- - User specified executable shell
- type: string
- ini:
- - section: defaults
- key: executable
- env:
- - name: ANSIBLE_EXECUTABLE
- vars:
- - name: ansible_executable
- default: /bin/sh
- chroot_exe:
- description:
- - User specified chroot binary
- type: string
- ini:
- - section: chroot_connection
- key: exe
- env:
- - name: ANSIBLE_CHROOT_EXE
- vars:
- - name: ansible_chroot_exe
- default: chroot
- disable_root_check:
- description:
- - Do not check that the user is not root.
- ini:
- - section: chroot_connection
- key: disable_root_check
- env:
- - name: ANSIBLE_CHROOT_DISABLE_ROOT_CHECK
- vars:
- - name: ansible_chroot_disable_root_check
- default: false
- type: bool
- version_added: 7.3.0
-'''
+ - The path of the chroot you want to access.
+ type: string
+ default: inventory_hostname
+ vars:
+ - name: inventory_hostname
+ - name: ansible_host
+ executable:
+ description:
+ - User specified executable shell.
+ type: string
+ ini:
+ - section: defaults
+ key: executable
+ env:
+ - name: ANSIBLE_EXECUTABLE
+ vars:
+ - name: ansible_executable
+ default: /bin/sh
+ chroot_exe:
+ description:
+ - User specified chroot binary.
+ type: string
+ ini:
+ - section: chroot_connection
+ key: exe
+ env:
+ - name: ANSIBLE_CHROOT_EXE
+ vars:
+ - name: ansible_chroot_exe
+ default: chroot
+ disable_root_check:
+ description:
+ - Do not check that the user is not root.
+ ini:
+ - section: chroot_connection
+ key: disable_root_check
+ env:
+ - name: ANSIBLE_CHROOT_DISABLE_ROOT_CHECK
+ vars:
+ - name: ansible_chroot_disable_root_check
+ default: false
+ type: bool
+ version_added: 7.3.0
+"""
EXAMPLES = r"""
-# Plugin requires root privileges for chroot, -E preserves your env (and location of ~/.ansible):
-# sudo -E ansible-playbook ...
-#
-# Static inventory file
-# [chroots]
-# /path/to/debootstrap
-# /path/to/feboostrap
-# /path/to/lxc-image
-# /path/to/chroot
-
-# playbook
----
- hosts: chroots
connection: community.general.chroot
tasks:
- debug:
msg: "This is coming from chroot environment"
-
"""
import os
@@ -94,7 +80,7 @@ from ansible.errors import AnsibleError
from ansible.module_utils.basic import is_executable
from ansible.module_utils.common.process import get_bin_path
from ansible.module_utils.six.moves import shlex_quote
-from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible.module_utils.common.text.converters import to_bytes
from ansible.plugins.connection import ConnectionBase, BUFSIZE
from ansible.utils.display import Display
@@ -120,15 +106,15 @@ class Connection(ConnectionBase):
# do some trivial checks for ensuring 'host' is actually a chroot'able dir
if not os.path.isdir(self.chroot):
- raise AnsibleError("%s is not a directory" % self.chroot)
+ raise AnsibleError(f"{self.chroot} is not a directory")
chrootsh = os.path.join(self.chroot, 'bin/sh')
# Want to check for a usable bourne shell inside the chroot.
# is_executable() == True is sufficient. For symlinks it
# gets really complicated really fast. So we punt on finding that
- # out. As long as it's a symlink we assume that it will work
+ # out. As long as it is a symlink we assume that it will work
if not (is_executable(chrootsh) or (os.path.lexists(chrootsh) and os.path.islink(chrootsh))):
- raise AnsibleError("%s does not look like a chrootable dir (/bin/sh missing)" % self.chroot)
+ raise AnsibleError(f"{self.chroot} does not look like a chrootable dir (/bin/sh missing)")
def _connect(self):
""" connect to the chroot """
@@ -143,7 +129,7 @@ class Connection(ConnectionBase):
try:
self.chroot_cmd = get_bin_path(self.get_option('chroot_exe'))
except ValueError as e:
- raise AnsibleError(to_native(e))
+ raise AnsibleError(str(e))
super(Connection, self)._connect()
if not self._connected:
@@ -161,7 +147,7 @@ class Connection(ConnectionBase):
executable = self.get_option('executable')
local_cmd = [self.chroot_cmd, self.chroot, executable, '-c', cmd]
- display.vvv("EXEC %s" % local_cmd, host=self.chroot)
+ display.vvv(f"EXEC {local_cmd}", host=self.chroot)
local_cmd = [to_bytes(i, errors='surrogate_or_strict') for i in local_cmd]
p = subprocess.Popen(local_cmd, shell=False, stdin=stdin,
stdout=subprocess.PIPE, stderr=subprocess.PIPE)
@@ -186,7 +172,7 @@ class Connection(ConnectionBase):
exist in any given chroot. So for now we're choosing "/" instead.
This also happens to be the former default.
- Can revisit using $HOME instead if it's a problem
+ Can revisit using $HOME instead if it is a problem
"""
if not remote_path.startswith(os.path.sep):
remote_path = os.path.join(os.path.sep, remote_path)
@@ -195,7 +181,7 @@ class Connection(ConnectionBase):
def put_file(self, in_path, out_path):
""" transfer a file from local to chroot """
super(Connection, self).put_file(in_path, out_path)
- display.vvv("PUT %s TO %s" % (in_path, out_path), host=self.chroot)
+ display.vvv(f"PUT {in_path} TO {out_path}", host=self.chroot)
out_path = shlex_quote(self._prefix_login_path(out_path))
try:
@@ -205,27 +191,27 @@ class Connection(ConnectionBase):
else:
count = ''
try:
- p = self._buffered_exec_command('dd of=%s bs=%s%s' % (out_path, BUFSIZE, count), stdin=in_file)
+ p = self._buffered_exec_command(f'dd of={out_path} bs={BUFSIZE}{count}', stdin=in_file)
except OSError:
raise AnsibleError("chroot connection requires dd command in the chroot")
try:
stdout, stderr = p.communicate()
except Exception:
traceback.print_exc()
- raise AnsibleError("failed to transfer file %s to %s" % (in_path, out_path))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}")
if p.returncode != 0:
- raise AnsibleError("failed to transfer file %s to %s:\n%s\n%s" % (in_path, out_path, stdout, stderr))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}:\n{stdout}\n{stderr}")
except IOError:
- raise AnsibleError("file or module does not exist at: %s" % in_path)
+ raise AnsibleError(f"file or module does not exist at: {in_path}")
def fetch_file(self, in_path, out_path):
""" fetch a file from chroot to local """
super(Connection, self).fetch_file(in_path, out_path)
- display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self.chroot)
+ display.vvv(f"FETCH {in_path} TO {out_path}", host=self.chroot)
in_path = shlex_quote(self._prefix_login_path(in_path))
try:
- p = self._buffered_exec_command('dd if=%s bs=%s' % (in_path, BUFSIZE))
+ p = self._buffered_exec_command(f'dd if={in_path} bs={BUFSIZE}')
except OSError:
raise AnsibleError("chroot connection requires dd command in the chroot")
@@ -237,10 +223,10 @@ class Connection(ConnectionBase):
chunk = p.stdout.read(BUFSIZE)
except Exception:
traceback.print_exc()
- raise AnsibleError("failed to transfer file %s to %s" % (in_path, out_path))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}")
stdout, stderr = p.communicate()
if p.returncode != 0:
- raise AnsibleError("failed to transfer file %s to %s:\n%s\n%s" % (in_path, out_path, stdout, stderr))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}:\n{stdout}\n{stderr}")
def close(self):
""" terminate the connection; nothing to do here """
diff --git a/plugins/connection/funcd.py b/plugins/connection/funcd.py
index 7765f53110..ad01326aff 100644
--- a/plugins/connection/funcd.py
+++ b/plugins/connection/funcd.py
@@ -6,27 +6,26 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Michael Scherer (@mscherer)
- name: funcd
- short_description: Use funcd to connect to target
+DOCUMENTATION = r"""
+author: Michael Scherer (@mscherer)
+name: funcd
+short_description: Use funcd to connect to target
+description:
+ - This transport permits you to use Ansible over Func.
+ - For people who have already setup func and that wish to play with ansible, this permit to move gradually to ansible without
+ having to redo completely the setup of the network.
+options:
+ remote_addr:
description:
- - This transport permits you to use Ansible over Func.
- - For people who have already setup func and that wish to play with ansible,
- this permit to move gradually to ansible without having to redo completely the setup of the network.
- options:
- remote_addr:
- description:
- - The path of the chroot you want to access.
- type: string
- default: inventory_hostname
- vars:
- - name: ansible_host
- - name: ansible_func_host
-'''
+ - The path of the chroot you want to access.
+ type: string
+ default: inventory_hostname
+ vars:
+ - name: ansible_host
+ - name: ansible_func_host
+"""
HAVE_FUNC = False
try:
@@ -72,7 +71,7 @@ class Connection(ConnectionBase):
raise AnsibleError("Internal Error: this module does not support optimized module pipelining")
# totally ignores privilege escalation
- display.vvv("EXEC %s" % cmd, host=self.host)
+ display.vvv(f"EXEC {cmd}", host=self.host)
p = self.client.command.run(cmd)[self.host]
return p[0], p[1], p[2]
@@ -87,14 +86,14 @@ class Connection(ConnectionBase):
""" transfer a file from local to remote """
out_path = self._normalize_path(out_path, '/')
- display.vvv("PUT %s TO %s" % (in_path, out_path), host=self.host)
+ display.vvv(f"PUT {in_path} TO {out_path}", host=self.host)
self.client.local.copyfile.send(in_path, out_path)
def fetch_file(self, in_path, out_path):
""" fetch a file from remote to local """
in_path = self._normalize_path(in_path, '/')
- display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self.host)
+ display.vvv(f"FETCH {in_path} TO {out_path}", host=self.host)
# need to use a tmp dir due to difference of semantic for getfile
# ( who take a # directory as destination) and fetch_file, who
# take a file directly
diff --git a/plugins/connection/incus.py b/plugins/connection/incus.py
index 8adea2d13a..842ad8f924 100644
--- a/plugins/connection/incus.py
+++ b/plugins/connection/incus.py
@@ -5,50 +5,74 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = """
- author: Stéphane Graber (@stgraber)
- name: incus
- short_description: Run tasks in Incus instances via the Incus CLI.
+DOCUMENTATION = r"""
+author: Stéphane Graber (@stgraber)
+name: incus
+short_description: Run tasks in Incus instances using the Incus CLI
+description:
+ - Run commands or put/fetch files to an existing Incus instance using Incus CLI.
+version_added: "8.2.0"
+options:
+ remote_addr:
description:
- - Run commands or put/fetch files to an existing Incus instance using Incus CLI.
- version_added: "8.2.0"
- options:
- remote_addr:
- description:
- - The instance identifier.
- type: string
- default: inventory_hostname
- vars:
- - name: inventory_hostname
- - name: ansible_host
- - name: ansible_incus_host
- executable:
- description:
- - The shell to use for execution inside the instance.
- type: string
- default: /bin/sh
- vars:
- - name: ansible_executable
- - name: ansible_incus_executable
- remote:
- description:
- - The name of the Incus remote to use (per C(incus remote list)).
- - Remotes are used to access multiple servers from a single client.
- type: string
- default: local
- vars:
- - name: ansible_incus_remote
- project:
- description:
- - The name of the Incus project to use (per C(incus project list)).
- - Projects are used to divide the instances running on a server.
- type: string
- default: default
- vars:
- - name: ansible_incus_project
+ - The instance identifier.
+ type: string
+ default: inventory_hostname
+ vars:
+ - name: inventory_hostname
+ - name: ansible_host
+ - name: ansible_incus_host
+ executable:
+ description:
+ - The shell to use for execution inside the instance.
+ type: string
+ default: /bin/sh
+ vars:
+ - name: ansible_executable
+ - name: ansible_incus_executable
+ incus_become_method:
+ description:
+ - Become command used to switch to a non-root user.
+ - Is only used when O(remote_user) is not V(root).
+ type: str
+ default: /bin/su
+ vars:
+ - name: incus_become_method
+ version_added: 10.4.0
+ remote:
+ description:
+ - The name of the Incus remote to use (per C(incus remote list)).
+ - Remotes are used to access multiple servers from a single client.
+ type: string
+ default: local
+ vars:
+ - name: ansible_incus_remote
+ remote_user:
+ description:
+ - User to login/authenticate as.
+ - Can be set from the CLI via the C(--user) or C(-u) options.
+ type: string
+ default: root
+ vars:
+ - name: ansible_user
+ env:
+ - name: ANSIBLE_REMOTE_USER
+ ini:
+ - section: defaults
+ key: remote_user
+ keyword:
+ - name: remote_user
+ version_added: 10.4.0
+ project:
+ description:
+ - The name of the Incus project to use (per C(incus project list)).
+ - Projects are used to divide the instances running on a server.
+ type: string
+ default: default
+ vars:
+ - name: ansible_incus_project
"""
import os
@@ -65,7 +89,6 @@ class Connection(ConnectionBase):
transport = "incus"
has_pipelining = True
- default_user = 'root'
def __init__(self, play_context, new_stdin, *args, **kwargs):
super(Connection, self).__init__(play_context, new_stdin, *args, **kwargs)
@@ -80,10 +103,34 @@ class Connection(ConnectionBase):
super(Connection, self)._connect()
if not self._connected:
- self._display.vvv(u"ESTABLISH Incus CONNECTION FOR USER: root",
+ self._display.vvv(f"ESTABLISH Incus CONNECTION FOR USER: {self.get_option('remote_user')}",
host=self._instance())
self._connected = True
+ def _build_command(self, cmd) -> str:
+ """build the command to execute on the incus host"""
+
+ exec_cmd = [
+ self._incus_cmd,
+ "--project", self.get_option("project"),
+ "exec",
+ f"{self.get_option('remote')}:{self._instance()}",
+ "--"]
+
+ if self.get_option("remote_user") != "root":
+ self._display.vvv(
+ f"INFO: Running as non-root user: {self.get_option('remote_user')}, \
+ trying to run 'incus exec' with become method: {self.get_option('incus_become_method')}",
+ host=self._instance(),
+ )
+ exec_cmd.extend(
+ [self.get_option("incus_become_method"), self.get_option("remote_user"), "-c"]
+ )
+
+ exec_cmd.extend([self.get_option("executable"), "-c", cmd])
+
+ return exec_cmd
+
def _instance(self):
# Return only the leading part of the FQDN as the instance name
# as Incus instance names cannot be a FQDN.
@@ -93,16 +140,11 @@ class Connection(ConnectionBase):
""" execute a command on the Incus host """
super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
- self._display.vvv(u"EXEC {0}".format(cmd),
+ self._display.vvv(f"EXEC {cmd}",
host=self._instance())
- local_cmd = [
- self._incus_cmd,
- "--project", self.get_option("project"),
- "exec",
- "%s:%s" % (self.get_option("remote"), self._instance()),
- "--",
- self._play_context.executable, "-c", cmd]
+ local_cmd = self._build_command(cmd)
+ self._display.vvvvv(f"EXEC {local_cmd}", host=self._instance())
local_cmd = [to_bytes(i, errors='surrogate_or_strict') for i in local_cmd]
in_data = to_bytes(in_data, errors='surrogate_or_strict', nonstring='passthru')
@@ -114,33 +156,71 @@ class Connection(ConnectionBase):
stderr = to_text(stderr)
if stderr == "Error: Instance is not running.\n":
- raise AnsibleConnectionFailure("instance not running: %s" %
- self._instance())
+ raise AnsibleConnectionFailure(f"instance not running: {self._instance()}")
if stderr == "Error: Instance not found\n":
- raise AnsibleConnectionFailure("instance not found: %s" %
- self._instance())
+ raise AnsibleConnectionFailure(f"instance not found: {self._instance()}")
return process.returncode, stdout, stderr
+ def _get_remote_uid_gid(self) -> tuple[int, int]:
+ """Get the user and group ID of 'remote_user' from the instance."""
+
+ rc, uid_out, err = self.exec_command("/bin/id -u")
+ if rc != 0:
+ raise AnsibleError(
+ f"Failed to get remote uid for user {self.get_option('remote_user')}: {err}"
+ )
+ uid = uid_out.strip()
+
+ rc, gid_out, err = self.exec_command("/bin/id -g")
+ if rc != 0:
+ raise AnsibleError(
+ f"Failed to get remote gid for user {self.get_option('remote_user')}: {err}"
+ )
+ gid = gid_out.strip()
+
+ return int(uid), int(gid)
+
def put_file(self, in_path, out_path):
""" put a file from local to Incus """
super(Connection, self).put_file(in_path, out_path)
- self._display.vvv(u"PUT {0} TO {1}".format(in_path, out_path),
+ self._display.vvv(f"PUT {in_path} TO {out_path}",
host=self._instance())
if not os.path.isfile(to_bytes(in_path, errors='surrogate_or_strict')):
- raise AnsibleFileNotFound("input path is not a file: %s" % in_path)
+ raise AnsibleFileNotFound(f"input path is not a file: {in_path}")
- local_cmd = [
- self._incus_cmd,
- "--project", self.get_option("project"),
- "file", "push", "--quiet",
- in_path,
- "%s:%s/%s" % (self.get_option("remote"),
- self._instance(),
- out_path)]
+ if self.get_option("remote_user") != "root":
+ uid, gid = self._get_remote_uid_gid()
+ local_cmd = [
+ self._incus_cmd,
+ "--project",
+ self.get_option("project"),
+ "file",
+ "push",
+ "--uid",
+ str(uid),
+ "--gid",
+ str(gid),
+ "--quiet",
+ in_path,
+ f"{self.get_option('remote')}:{self._instance()}/{out_path}",
+ ]
+ else:
+ local_cmd = [
+ self._incus_cmd,
+ "--project",
+ self.get_option("project"),
+ "file",
+ "push",
+ "--quiet",
+ in_path,
+ f"{self.get_option('remote')}:{self._instance()}/{out_path}",
+ ]
+
+ self._display.vvvvv(f"PUT {local_cmd}", host=self._instance())
local_cmd = [to_bytes(i, errors='surrogate_or_strict') for i in local_cmd]
@@ -150,16 +230,14 @@ class Connection(ConnectionBase):
""" fetch a file from Incus to local """
super(Connection, self).fetch_file(in_path, out_path)
- self._display.vvv(u"FETCH {0} TO {1}".format(in_path, out_path),
+ self._display.vvv(f"FETCH {in_path} TO {out_path}",
host=self._instance())
local_cmd = [
self._incus_cmd,
"--project", self.get_option("project"),
"file", "pull", "--quiet",
- "%s:%s/%s" % (self.get_option("remote"),
- self._instance(),
- in_path),
+ f"{self.get_option('remote')}:{self._instance()}/{in_path}",
out_path]
local_cmd = [to_bytes(i, errors='surrogate_or_strict') for i in local_cmd]
diff --git a/plugins/connection/iocage.py b/plugins/connection/iocage.py
index 79d4f88594..35d5ab0658 100644
--- a/plugins/connection/iocage.py
+++ b/plugins/connection/iocage.py
@@ -7,31 +7,30 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Stephan Lohse (!UNKNOWN)
- name: iocage
- short_description: Run tasks in iocage jails
+DOCUMENTATION = r"""
+author: Stephan Lohse (!UNKNOWN)
+name: iocage
+short_description: Run tasks in iocage jails
+description:
+ - Run commands or put/fetch files to an existing iocage jail.
+options:
+ remote_addr:
description:
- - Run commands or put/fetch files to an existing iocage jail
- options:
- remote_addr:
- description:
- - Path to the jail
- type: string
- vars:
- - name: ansible_host
- - name: ansible_iocage_host
- remote_user:
- description:
- - User to execute as inside the jail
- type: string
- vars:
- - name: ansible_user
- - name: ansible_iocage_user
-'''
+ - Path to the jail.
+ type: string
+ vars:
+ - name: ansible_host
+ - name: ansible_iocage_host
+ remote_user:
+ description:
+ - User to execute as inside the jail.
+ type: string
+ vars:
+ - name: ansible_user
+ - name: ansible_iocage_user
+"""
import subprocess
@@ -55,11 +54,12 @@ class Connection(Jail):
jail_uuid = self.get_jail_uuid()
- kwargs[Jail.modified_jailname_key] = 'ioc-{0}'.format(jail_uuid)
+ kwargs[Jail.modified_jailname_key] = f'ioc-{jail_uuid}'
- display.vvv(u"Jail {iocjail} has been translated to {rawjail}".format(
- iocjail=self.ioc_jail, rawjail=kwargs[Jail.modified_jailname_key]),
- host=kwargs[Jail.modified_jailname_key])
+ display.vvv(
+ f"Jail {self.ioc_jail} has been translated to {kwargs[Jail.modified_jailname_key]}",
+ host=kwargs[Jail.modified_jailname_key]
+ )
super(Connection, self).__init__(play_context, new_stdin, *args, **kwargs)
@@ -81,6 +81,6 @@ class Connection(Jail):
p.wait()
if p.returncode != 0:
- raise AnsibleError(u"iocage returned an error: {0}".format(stdout))
+ raise AnsibleError(f"iocage returned an error: {stdout}")
return stdout.strip('\n')
diff --git a/plugins/connection/jail.py b/plugins/connection/jail.py
index 7d0abdde3a..6f06c96774 100644
--- a/plugins/connection/jail.py
+++ b/plugins/connection/jail.py
@@ -7,33 +7,32 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Ansible Core Team
- name: jail
- short_description: Run tasks in jails
+DOCUMENTATION = r"""
+author: Ansible Core Team
+name: jail
+short_description: Run tasks in jails
+description:
+ - Run commands or put/fetch files to an existing jail.
+options:
+ remote_addr:
description:
- - Run commands or put/fetch files to an existing jail
- options:
- remote_addr:
- description:
- - Path to the jail
- type: string
- default: inventory_hostname
- vars:
- - name: inventory_hostname
- - name: ansible_host
- - name: ansible_jail_host
- remote_user:
- description:
- - User to execute as inside the jail
- type: string
- vars:
- - name: ansible_user
- - name: ansible_jail_user
-'''
+ - Path to the jail.
+ type: string
+ default: inventory_hostname
+ vars:
+ - name: inventory_hostname
+ - name: ansible_host
+ - name: ansible_jail_host
+ remote_user:
+ description:
+ - User to execute as inside the jail.
+ type: string
+ vars:
+ - name: ansible_user
+ - name: ansible_jail_user
+"""
import os
import os.path
@@ -75,14 +74,14 @@ class Connection(ConnectionBase):
self.jexec_cmd = self._search_executable('jexec')
if self.jail not in self.list_jails():
- raise AnsibleError("incorrect jail name %s" % self.jail)
+ raise AnsibleError(f"incorrect jail name {self.jail}")
@staticmethod
def _search_executable(executable):
try:
return get_bin_path(executable)
except ValueError:
- raise AnsibleError("%s command not found in PATH" % executable)
+ raise AnsibleError(f"{executable} command not found in PATH")
def list_jails(self):
p = subprocess.Popen([self.jls_cmd, '-q', 'name'],
@@ -97,7 +96,7 @@ class Connection(ConnectionBase):
""" connect to the jail; nothing to do here """
super(Connection, self)._connect()
if not self._connected:
- display.vvv(u"ESTABLISH JAIL CONNECTION FOR USER: {0}".format(self._play_context.remote_user), host=self.jail)
+ display.vvv(f"ESTABLISH JAIL CONNECTION FOR USER: {self._play_context.remote_user}", host=self.jail)
self._connected = True
def _buffered_exec_command(self, cmd, stdin=subprocess.PIPE):
@@ -115,11 +114,11 @@ class Connection(ConnectionBase):
if self._play_context.remote_user is not None:
local_cmd += ['-U', self._play_context.remote_user]
# update HOME since -U does not update the jail environment
- set_env = 'HOME=~' + self._play_context.remote_user + ' '
+ set_env = f"HOME=~{self._play_context.remote_user} "
local_cmd += [self.jail, self._play_context.executable, '-c', set_env + cmd]
- display.vvv("EXEC %s" % (local_cmd,), host=self.jail)
+ display.vvv(f"EXEC {local_cmd}", host=self.jail)
local_cmd = [to_bytes(i, errors='surrogate_or_strict') for i in local_cmd]
p = subprocess.Popen(local_cmd, shell=False, stdin=stdin,
stdout=subprocess.PIPE, stderr=subprocess.PIPE)
@@ -144,7 +143,7 @@ class Connection(ConnectionBase):
exist in any given chroot. So for now we're choosing "/" instead.
This also happens to be the former default.
- Can revisit using $HOME instead if it's a problem
+ Can revisit using $HOME instead if it is a problem
"""
if not remote_path.startswith(os.path.sep):
remote_path = os.path.join(os.path.sep, remote_path)
@@ -153,7 +152,7 @@ class Connection(ConnectionBase):
def put_file(self, in_path, out_path):
""" transfer a file from local to jail """
super(Connection, self).put_file(in_path, out_path)
- display.vvv("PUT %s TO %s" % (in_path, out_path), host=self.jail)
+ display.vvv(f"PUT {in_path} TO {out_path}", host=self.jail)
out_path = shlex_quote(self._prefix_login_path(out_path))
try:
@@ -163,27 +162,27 @@ class Connection(ConnectionBase):
else:
count = ''
try:
- p = self._buffered_exec_command('dd of=%s bs=%s%s' % (out_path, BUFSIZE, count), stdin=in_file)
+ p = self._buffered_exec_command(f'dd of={out_path} bs={BUFSIZE}{count}', stdin=in_file)
except OSError:
raise AnsibleError("jail connection requires dd command in the jail")
try:
stdout, stderr = p.communicate()
except Exception:
traceback.print_exc()
- raise AnsibleError("failed to transfer file %s to %s" % (in_path, out_path))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}")
if p.returncode != 0:
- raise AnsibleError("failed to transfer file %s to %s:\n%s\n%s" % (in_path, out_path, to_native(stdout), to_native(stderr)))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}:\n{to_native(stdout)}\n{to_native(stderr)}")
except IOError:
- raise AnsibleError("file or module does not exist at: %s" % in_path)
+ raise AnsibleError(f"file or module does not exist at: {in_path}")
def fetch_file(self, in_path, out_path):
""" fetch a file from jail to local """
super(Connection, self).fetch_file(in_path, out_path)
- display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self.jail)
+ display.vvv(f"FETCH {in_path} TO {out_path}", host=self.jail)
in_path = shlex_quote(self._prefix_login_path(in_path))
try:
- p = self._buffered_exec_command('dd if=%s bs=%s' % (in_path, BUFSIZE))
+ p = self._buffered_exec_command(f'dd if={in_path} bs={BUFSIZE}')
except OSError:
raise AnsibleError("jail connection requires dd command in the jail")
@@ -195,10 +194,10 @@ class Connection(ConnectionBase):
chunk = p.stdout.read(BUFSIZE)
except Exception:
traceback.print_exc()
- raise AnsibleError("failed to transfer file %s to %s" % (in_path, out_path))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}")
stdout, stderr = p.communicate()
if p.returncode != 0:
- raise AnsibleError("failed to transfer file %s to %s:\n%s\n%s" % (in_path, out_path, to_native(stdout), to_native(stderr)))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}:\n{to_native(stdout)}\n{to_native(stderr)}")
def close(self):
""" terminate the connection; nothing to do here """
diff --git a/plugins/connection/lxc.py b/plugins/connection/lxc.py
index 2710e6984e..a9e46cf56f 100644
--- a/plugins/connection/lxc.py
+++ b/plugins/connection/lxc.py
@@ -4,34 +4,33 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Joerg Thalheim (!UNKNOWN)
- name: lxc
- short_description: Run tasks in lxc containers via lxc python library
+DOCUMENTATION = r"""
+author: Joerg Thalheim (!UNKNOWN)
+name: lxc
+short_description: Run tasks in LXC containers using lxc python library
+description:
+ - Run commands or put/fetch files to an existing LXC container using lxc python library.
+options:
+ remote_addr:
description:
- - Run commands or put/fetch files to an existing lxc container using lxc python library
- options:
- remote_addr:
- description:
- - Container identifier
- type: string
- default: inventory_hostname
- vars:
- - name: inventory_hostname
- - name: ansible_host
- - name: ansible_lxc_host
- executable:
- default: /bin/sh
- description:
- - Shell executable
- type: string
- vars:
- - name: ansible_executable
- - name: ansible_lxc_executable
-'''
+ - Container identifier.
+ type: string
+ default: inventory_hostname
+ vars:
+ - name: inventory_hostname
+ - name: ansible_host
+ - name: ansible_lxc_host
+ executable:
+ default: /bin/sh
+ description:
+ - Shell executable.
+ type: string
+ vars:
+ - name: ansible_executable
+ - name: ansible_lxc_executable
+"""
import os
import shutil
@@ -82,7 +81,7 @@ class Connection(ConnectionBase):
self._display.vvv("THIS IS A LOCAL LXC DIR", host=self.container_name)
self.container = _lxc.Container(self.container_name)
if self.container.state == "STOPPED":
- raise errors.AnsibleError("%s is not running" % self.container_name)
+ raise errors.AnsibleError(f"{self.container_name} is not running")
@staticmethod
def _communicate(pid, in_data, stdin, stdout, stderr):
@@ -144,10 +143,10 @@ class Connection(ConnectionBase):
read_stdin, write_stdin = os.pipe()
kwargs['stdin'] = self._set_nonblocking(read_stdin)
- self._display.vvv("EXEC %s" % (local_cmd), host=self.container_name)
+ self._display.vvv(f"EXEC {local_cmd}", host=self.container_name)
pid = self.container.attach(_lxc.attach_run_command, local_cmd, **kwargs)
if pid == -1:
- msg = "failed to attach to container %s" % self.container_name
+ msg = f"failed to attach to container {self.container_name}"
raise errors.AnsibleError(msg)
write_stdout = os.close(write_stdout)
@@ -174,18 +173,18 @@ class Connection(ConnectionBase):
def put_file(self, in_path, out_path):
''' transfer a file from local to lxc '''
super(Connection, self).put_file(in_path, out_path)
- self._display.vvv("PUT %s TO %s" % (in_path, out_path), host=self.container_name)
+ self._display.vvv(f"PUT {in_path} TO {out_path}", host=self.container_name)
in_path = to_bytes(in_path, errors='surrogate_or_strict')
out_path = to_bytes(out_path, errors='surrogate_or_strict')
if not os.path.exists(in_path):
- msg = "file or module does not exist: %s" % in_path
+ msg = f"file or module does not exist: {in_path}"
raise errors.AnsibleFileNotFound(msg)
try:
src_file = open(in_path, "rb")
except IOError:
traceback.print_exc()
- raise errors.AnsibleError("failed to open input file to %s" % in_path)
+ raise errors.AnsibleError(f"failed to open input file to {in_path}")
try:
def write_file(args):
with open(out_path, 'wb+') as dst_file:
@@ -194,7 +193,7 @@ class Connection(ConnectionBase):
self.container.attach_wait(write_file, None)
except IOError:
traceback.print_exc()
- msg = "failed to transfer file to %s" % out_path
+ msg = f"failed to transfer file to {out_path}"
raise errors.AnsibleError(msg)
finally:
src_file.close()
@@ -202,7 +201,7 @@ class Connection(ConnectionBase):
def fetch_file(self, in_path, out_path):
''' fetch a file from lxc to local '''
super(Connection, self).fetch_file(in_path, out_path)
- self._display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self.container_name)
+ self._display.vvv(f"FETCH {in_path} TO {out_path}", host=self.container_name)
in_path = to_bytes(in_path, errors='surrogate_or_strict')
out_path = to_bytes(out_path, errors='surrogate_or_strict')
@@ -210,7 +209,7 @@ class Connection(ConnectionBase):
dst_file = open(out_path, "wb")
except IOError:
traceback.print_exc()
- msg = "failed to open output file %s" % out_path
+ msg = f"failed to open output file {out_path}"
raise errors.AnsibleError(msg)
try:
def write_file(args):
@@ -225,7 +224,7 @@ class Connection(ConnectionBase):
self.container.attach_wait(write_file, None)
except IOError:
traceback.print_exc()
- msg = "failed to transfer file from %s to %s" % (in_path, out_path)
+ msg = f"failed to transfer file from {in_path} to {out_path}"
raise errors.AnsibleError(msg)
finally:
dst_file.close()
diff --git a/plugins/connection/lxd.py b/plugins/connection/lxd.py
index d850907182..2670ed1b5f 100644
--- a/plugins/connection/lxd.py
+++ b/plugins/connection/lxd.py
@@ -4,51 +4,75 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Matt Clay (@mattclay)
- name: lxd
- short_description: Run tasks in LXD instances via C(lxc) CLI
+DOCUMENTATION = r"""
+author: Matt Clay (@mattclay)
+name: lxd
+short_description: Run tasks in LXD instances using C(lxc) CLI
+description:
+ - Run commands or put/fetch files to an existing instance using C(lxc) CLI.
+options:
+ remote_addr:
description:
- - Run commands or put/fetch files to an existing instance using C(lxc) CLI.
- options:
- remote_addr:
- description:
- - Instance (container/VM) identifier.
- - Since community.general 8.0.0, a FQDN can be provided; in that case, the first component (the part before C(.))
- is used as the instance identifier.
- type: string
- default: inventory_hostname
- vars:
- - name: inventory_hostname
- - name: ansible_host
- - name: ansible_lxd_host
- executable:
- description:
- - Shell to use for execution inside instance.
- type: string
- default: /bin/sh
- vars:
- - name: ansible_executable
- - name: ansible_lxd_executable
- remote:
- description:
- - Name of the LXD remote to use.
- type: string
- default: local
- vars:
- - name: ansible_lxd_remote
- version_added: 2.0.0
- project:
- description:
- - Name of the LXD project to use.
- type: string
- vars:
- - name: ansible_lxd_project
- version_added: 2.0.0
-'''
+ - Instance (container/VM) identifier.
+ - Since community.general 8.0.0, a FQDN can be provided; in that case, the first component (the part before C(.)) is
+ used as the instance identifier.
+ type: string
+ default: inventory_hostname
+ vars:
+ - name: inventory_hostname
+ - name: ansible_host
+ - name: ansible_lxd_host
+ executable:
+ description:
+ - Shell to use for execution inside instance.
+ type: string
+ default: /bin/sh
+ vars:
+ - name: ansible_executable
+ - name: ansible_lxd_executable
+ lxd_become_method:
+ description:
+ - Become command used to switch to a non-root user.
+ - Is only used when O(remote_user) is not V(root).
+ type: str
+ default: /bin/su
+ vars:
+ - name: lxd_become_method
+ version_added: 10.4.0
+ remote:
+ description:
+ - Name of the LXD remote to use.
+ type: string
+ default: local
+ vars:
+ - name: ansible_lxd_remote
+ version_added: 2.0.0
+ remote_user:
+ description:
+ - User to login/authenticate as.
+ - Can be set from the CLI via the C(--user) or C(-u) options.
+ type: string
+ default: root
+ vars:
+ - name: ansible_user
+ env:
+ - name: ANSIBLE_REMOTE_USER
+ ini:
+ - section: defaults
+ key: remote_user
+ keyword:
+ - name: remote_user
+ version_added: 10.4.0
+ project:
+ description:
+ - Name of the LXD project to use.
+ type: string
+ vars:
+ - name: ansible_lxd_project
+ version_added: 2.0.0
+"""
import os
from subprocess import Popen, PIPE
@@ -64,7 +88,6 @@ class Connection(ConnectionBase):
transport = 'community.general.lxd'
has_pipelining = True
- default_user = 'root'
def __init__(self, play_context, new_stdin, *args, **kwargs):
super(Connection, self).__init__(play_context, new_stdin, *args, **kwargs)
@@ -74,9 +97,6 @@ class Connection(ConnectionBase):
except ValueError:
raise AnsibleError("lxc command not found in PATH")
- if self._play_context.remote_user is not None and self._play_context.remote_user != 'root':
- self._display.warning('lxd does not support remote_user, using default: root')
-
def _host(self):
""" translate remote_addr to lxd (short) hostname """
return self.get_option("remote_addr").split(".", 1)[0]
@@ -86,26 +106,41 @@ class Connection(ConnectionBase):
super(Connection, self)._connect()
if not self._connected:
- self._display.vvv(u"ESTABLISH LXD CONNECTION FOR USER: root", host=self._host())
+ self._display.vvv(f"ESTABLISH LXD CONNECTION FOR USER: {self.get_option('remote_user')}", host=self._host())
self._connected = True
+ def _build_command(self, cmd) -> str:
+ """build the command to execute on the lxd host"""
+
+ exec_cmd = [self._lxc_cmd]
+
+ if self.get_option("project"):
+ exec_cmd.extend(["--project", self.get_option("project")])
+
+ exec_cmd.extend(["exec", f"{self.get_option('remote')}:{self._host()}", "--"])
+
+ if self.get_option("remote_user") != "root":
+ self._display.vvv(
+ f"INFO: Running as non-root user: {self.get_option('remote_user')}, \
+ trying to run 'lxc exec' with become method: {self.get_option('lxd_become_method')}",
+ host=self._host(),
+ )
+ exec_cmd.extend(
+ [self.get_option("lxd_become_method"), self.get_option("remote_user"), "-c"]
+ )
+
+ exec_cmd.extend([self.get_option("executable"), "-c", cmd])
+
+ return exec_cmd
+
def exec_command(self, cmd, in_data=None, sudoable=True):
""" execute a command on the lxd host """
super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
- self._display.vvv(u"EXEC {0}".format(cmd), host=self._host())
+ self._display.vvv(f"EXEC {cmd}", host=self._host())
- local_cmd = [self._lxc_cmd]
- if self.get_option("project"):
- local_cmd.extend(["--project", self.get_option("project")])
- local_cmd.extend([
- "exec",
- "%s:%s" % (self.get_option("remote"), self._host()),
- "--",
- self.get_option("executable"), "-c", cmd
- ])
-
- self._display.vvvvv(u"EXEC {0}".format(local_cmd), host=self._host())
+ local_cmd = self._build_command(cmd)
+ self._display.vvvvv(f"EXEC {local_cmd}", host=self._host())
local_cmd = [to_bytes(i, errors='surrogate_or_strict') for i in local_cmd]
in_data = to_bytes(in_data, errors='surrogate_or_strict', nonstring='passthru')
@@ -116,33 +151,73 @@ class Connection(ConnectionBase):
stdout = to_text(stdout)
stderr = to_text(stderr)
- self._display.vvvvv(u"EXEC lxc output: {0} {1}".format(stdout, stderr), host=self._host())
+ self._display.vvvvv(f"EXEC lxc output: {stdout} {stderr}", host=self._host())
if "is not running" in stderr:
- raise AnsibleConnectionFailure("instance not running: %s" % self._host())
+ raise AnsibleConnectionFailure(f"instance not running: {self._host()}")
if stderr.strip() == "Error: Instance not found" or stderr.strip() == "error: not found":
- raise AnsibleConnectionFailure("instance not found: %s" % self._host())
+ raise AnsibleConnectionFailure(f"instance not found: {self._host()}")
return process.returncode, stdout, stderr
+ def _get_remote_uid_gid(self) -> tuple[int, int]:
+ """Get the user and group ID of 'remote_user' from the instance."""
+
+ rc, uid_out, err = self.exec_command("/bin/id -u")
+ if rc != 0:
+ raise AnsibleError(
+ f"Failed to get remote uid for user {self.get_option('remote_user')}: {err}"
+ )
+ uid = uid_out.strip()
+
+ rc, gid_out, err = self.exec_command("/bin/id -g")
+ if rc != 0:
+ raise AnsibleError(
+ f"Failed to get remote gid for user {self.get_option('remote_user')}: {err}"
+ )
+ gid = gid_out.strip()
+
+ return int(uid), int(gid)
+
def put_file(self, in_path, out_path):
""" put a file from local to lxd """
super(Connection, self).put_file(in_path, out_path)
- self._display.vvv(u"PUT {0} TO {1}".format(in_path, out_path), host=self._host())
+ self._display.vvv(f"PUT {in_path} TO {out_path}", host=self._host())
if not os.path.isfile(to_bytes(in_path, errors='surrogate_or_strict')):
- raise AnsibleFileNotFound("input path is not a file: %s" % in_path)
+ raise AnsibleFileNotFound(f"input path is not a file: {in_path}")
local_cmd = [self._lxc_cmd]
if self.get_option("project"):
local_cmd.extend(["--project", self.get_option("project")])
- local_cmd.extend([
- "file", "push",
- in_path,
- "%s:%s/%s" % (self.get_option("remote"), self._host(), out_path)
- ])
+
+ if self.get_option("remote_user") != "root":
+ uid, gid = self._get_remote_uid_gid()
+ local_cmd.extend(
+ [
+ "file",
+ "push",
+ "--uid",
+ str(uid),
+ "--gid",
+ str(gid),
+ in_path,
+ f"{self.get_option('remote')}:{self._host()}/{out_path}",
+ ]
+ )
+ else:
+ local_cmd.extend(
+ [
+ "file",
+ "push",
+ in_path,
+ f"{self.get_option('remote')}:{self._host()}/{out_path}",
+ ]
+ )
+
+ self._display.vvvvv(f"PUT {local_cmd}", host=self._host())
local_cmd = [to_bytes(i, errors='surrogate_or_strict') for i in local_cmd]
@@ -153,14 +228,14 @@ class Connection(ConnectionBase):
""" fetch a file from lxd to local """
super(Connection, self).fetch_file(in_path, out_path)
- self._display.vvv(u"FETCH {0} TO {1}".format(in_path, out_path), host=self._host())
+ self._display.vvv(f"FETCH {in_path} TO {out_path}", host=self._host())
local_cmd = [self._lxc_cmd]
if self.get_option("project"):
local_cmd.extend(["--project", self.get_option("project")])
local_cmd.extend([
"file", "pull",
- "%s:%s/%s" % (self.get_option("remote"), self._host(), in_path),
+ f"{self.get_option('remote')}:{self._host()}/{in_path}",
out_path
])
diff --git a/plugins/connection/proxmox_pct_remote.py b/plugins/connection/proxmox_pct_remote.py
new file mode 100644
index 0000000000..c46090083e
--- /dev/null
+++ b/plugins/connection/proxmox_pct_remote.py
@@ -0,0 +1,857 @@
+# -*- coding: utf-8 -*-
+# Derived from ansible/plugins/connection/paramiko_ssh.py (c) 2012, Michael DeHaan
+# Copyright (c) 2024 Nils Stein (@mietzen)
+# Copyright (c) 2024 Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import annotations
+
+DOCUMENTATION = r"""
+author: Nils Stein (@mietzen)
+name: proxmox_pct_remote
+short_description: Run tasks in Proxmox LXC container instances using pct CLI via SSH
+requirements:
+ - paramiko
+description:
+ - Run commands or put/fetch files to an existing Proxmox LXC container using pct CLI via SSH.
+ - Uses the Python SSH implementation (Paramiko) to connect to the Proxmox host.
+version_added: "10.3.0"
+options:
+ remote_addr:
+ description:
+ - Address of the remote target.
+ default: inventory_hostname
+ type: string
+ vars:
+ - name: inventory_hostname
+ - name: ansible_host
+ - name: ansible_ssh_host
+ - name: ansible_paramiko_host
+ port:
+ description: Remote port to connect to.
+ type: int
+ default: 22
+ ini:
+ - section: defaults
+ key: remote_port
+ - section: paramiko_connection
+ key: remote_port
+ env:
+ - name: ANSIBLE_REMOTE_PORT
+ - name: ANSIBLE_REMOTE_PARAMIKO_PORT
+ vars:
+ - name: ansible_port
+ - name: ansible_ssh_port
+ - name: ansible_paramiko_port
+ keyword:
+ - name: port
+ remote_user:
+ description:
+ - User to login/authenticate as.
+ - Can be set from the CLI via the C(--user) or C(-u) options.
+ type: string
+ vars:
+ - name: ansible_user
+ - name: ansible_ssh_user
+ - name: ansible_paramiko_user
+ env:
+ - name: ANSIBLE_REMOTE_USER
+ - name: ANSIBLE_PARAMIKO_REMOTE_USER
+ ini:
+ - section: defaults
+ key: remote_user
+ - section: paramiko_connection
+ key: remote_user
+ keyword:
+ - name: remote_user
+ password:
+ description:
+ - Secret used to either login the SSH server or as a passphrase for SSH keys that require it.
+ - Can be set from the CLI via the C(--ask-pass) option.
+ type: string
+ vars:
+ - name: ansible_password
+ - name: ansible_ssh_pass
+ - name: ansible_ssh_password
+ - name: ansible_paramiko_pass
+ - name: ansible_paramiko_password
+ use_rsa_sha2_algorithms:
+ description:
+ - Whether or not to enable RSA SHA2 algorithms for pubkeys and hostkeys.
+ - On paramiko versions older than 2.9, this only affects hostkeys.
+ - For behavior matching paramiko<2.9 set this to V(false).
+ vars:
+ - name: ansible_paramiko_use_rsa_sha2_algorithms
+ ini:
+ - {key: use_rsa_sha2_algorithms, section: paramiko_connection}
+ env:
+ - {name: ANSIBLE_PARAMIKO_USE_RSA_SHA2_ALGORITHMS}
+ default: true
+ type: boolean
+ host_key_auto_add:
+ description: "Automatically add host keys to C(~/.ssh/known_hosts)."
+ env:
+ - name: ANSIBLE_PARAMIKO_HOST_KEY_AUTO_ADD
+ ini:
+ - key: host_key_auto_add
+ section: paramiko_connection
+ type: boolean
+ look_for_keys:
+ default: True
+ description: "Set to V(false) to disable searching for private key files in C(~/.ssh/)."
+ env:
+ - name: ANSIBLE_PARAMIKO_LOOK_FOR_KEYS
+ ini:
+ - {key: look_for_keys, section: paramiko_connection}
+ type: boolean
+ proxy_command:
+ default: ""
+ description:
+ - Proxy information for running the connection via a jumphost.
+ type: string
+ env:
+ - name: ANSIBLE_PARAMIKO_PROXY_COMMAND
+ ini:
+ - {key: proxy_command, section: paramiko_connection}
+ vars:
+ - name: ansible_paramiko_proxy_command
+ pty:
+ default: True
+ description: "C(sudo) usually requires a PTY, V(true) to give a PTY and V(false) to not give a PTY."
+ env:
+ - name: ANSIBLE_PARAMIKO_PTY
+ ini:
+ - section: paramiko_connection
+ key: pty
+ type: boolean
+ record_host_keys:
+ default: True
+ description: "Save the host keys to a file."
+ env:
+ - name: ANSIBLE_PARAMIKO_RECORD_HOST_KEYS
+ ini:
+ - section: paramiko_connection
+ key: record_host_keys
+ type: boolean
+ host_key_checking:
+ description: "Set this to V(false) if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host."
+ type: boolean
+ default: true
+ env:
+ - name: ANSIBLE_HOST_KEY_CHECKING
+ - name: ANSIBLE_SSH_HOST_KEY_CHECKING
+ - name: ANSIBLE_PARAMIKO_HOST_KEY_CHECKING
+ ini:
+ - section: defaults
+ key: host_key_checking
+ - section: paramiko_connection
+ key: host_key_checking
+ vars:
+ - name: ansible_host_key_checking
+ - name: ansible_ssh_host_key_checking
+ - name: ansible_paramiko_host_key_checking
+ use_persistent_connections:
+ description: "Toggles the use of persistence for connections."
+ type: boolean
+ default: False
+ env:
+ - name: ANSIBLE_USE_PERSISTENT_CONNECTIONS
+ ini:
+ - section: defaults
+ key: use_persistent_connections
+ banner_timeout:
+ type: float
+ default: 30
+ description:
+ - Configures, in seconds, the amount of time to wait for the SSH
+ banner to be presented. This option is supported by paramiko
+ version 1.15.0 or newer.
+ ini:
+ - section: paramiko_connection
+ key: banner_timeout
+ env:
+ - name: ANSIBLE_PARAMIKO_BANNER_TIMEOUT
+ timeout:
+ type: int
+ default: 10
+ description: Number of seconds until the plugin gives up on failing to establish a TCP connection.
+ ini:
+ - section: defaults
+ key: timeout
+ - section: ssh_connection
+ key: timeout
+ - section: paramiko_connection
+ key: timeout
+ env:
+ - name: ANSIBLE_TIMEOUT
+ - name: ANSIBLE_SSH_TIMEOUT
+ - name: ANSIBLE_PARAMIKO_TIMEOUT
+ vars:
+ - name: ansible_ssh_timeout
+ - name: ansible_paramiko_timeout
+ cli:
+ - name: timeout
+ lock_file_timeout:
+ type: int
+ default: 60
+ description: Number of seconds until the plugin gives up on trying to write a lock file when writing SSH known host keys.
+ vars:
+ - name: ansible_lock_file_timeout
+ env:
+ - name: ANSIBLE_LOCK_FILE_TIMEOUT
+ private_key_file:
+ description:
+ - Path to private key file to use for authentication.
+ type: string
+ ini:
+ - section: defaults
+ key: private_key_file
+ - section: paramiko_connection
+ key: private_key_file
+ env:
+ - name: ANSIBLE_PRIVATE_KEY_FILE
+ - name: ANSIBLE_PARAMIKO_PRIVATE_KEY_FILE
+ vars:
+ - name: ansible_private_key_file
+ - name: ansible_ssh_private_key_file
+ - name: ansible_paramiko_private_key_file
+ cli:
+ - name: private_key_file
+ option: "--private-key"
+ vmid:
+ description:
+ - LXC Container ID
+ type: int
+ vars:
+ - name: proxmox_vmid
+ proxmox_become_method:
+ description:
+ - Become command used in proxmox
+ type: str
+ default: sudo
+ vars:
+ - name: proxmox_become_method
+notes:
+ - >
+ When NOT using this plugin as root, you need to have a become mechanism,
+ e.g. C(sudo), installed on Proxmox and setup so we can run it without prompting for the password.
+ Inside the container, we need a shell, for example C(sh) and the C(cat) command to be available in the C(PATH) for this plugin to work.
+"""
+
+EXAMPLES = r"""
+# --------------------------------------------------------------
+# Setup sudo with password less access to pct for user 'ansible':
+# --------------------------------------------------------------
+#
+# Open a Proxmox root shell and execute:
+# $ useradd -d /opt/ansible-pct -r -m -s /bin/sh ansible
+# $ mkdir -p /opt/ansible-pct/.ssh
+# $ ssh-keygen -t ed25519 -C 'ansible' -N "" -f /opt/ansible-pct/.ssh/ansible <<< y > /dev/null
+# $ cat /opt/ansible-pct/.ssh/ansible
+# $ mv /opt/ansible-pct/.ssh/ansible.pub /opt/ansible-pct/.ssh/authorized-keys
+# $ rm /opt/ansible-pct/.ssh/ansible*
+# $ chown -R ansible:ansible /opt/ansible-pct/.ssh
+# $ chmod 700 /opt/ansible-pct/.ssh
+# $ chmod 600 /opt/ansible-pct/.ssh/authorized-keys
+# $ echo 'ansible ALL = (root) NOPASSWD: /usr/sbin/pct' > /etc/sudoers.d/ansible_pct
+#
+# Save the displayed private key and add it to your ssh-agent
+#
+# Or use ansible:
+# ---
+# - name: Setup ansible-pct user and configure environment on Proxmox host
+# hosts: proxmox
+# become: true
+# gather_facts: false
+#
+# tasks:
+# - name: Create ansible user
+# ansible.builtin.user:
+# name: ansible
+# comment: Ansible User
+# home: /opt/ansible-pct
+# shell: /bin/sh
+# create_home: true
+# system: true
+#
+# - name: Create .ssh directory
+# ansible.builtin.file:
+# path: /opt/ansible-pct/.ssh
+# state: directory
+# owner: ansible
+# group: ansible
+# mode: '0700'
+#
+# - name: Generate SSH key for ansible user
+# community.crypto.openssh_keypair:
+# path: /opt/ansible-pct/.ssh/ansible
+# type: ed25519
+# comment: 'ansible'
+# force: true
+# mode: '0600'
+# owner: ansible
+# group: ansible
+#
+# - name: Set public key as authorized key
+# ansible.builtin.copy:
+# src: /opt/ansible-pct/.ssh/ansible.pub
+# dest: /opt/ansible-pct/.ssh/authorized-keys
+# remote_src: yes
+# owner: ansible
+# group: ansible
+# mode: '0600'
+#
+# - name: Add sudoers entry for ansible user
+# ansible.builtin.copy:
+# content: 'ansible ALL = (root) NOPASSWD: /usr/sbin/pct'
+# dest: /etc/sudoers.d/ansible_pct
+# owner: root
+# group: root
+# mode: '0440'
+#
+# - name: Fetch private SSH key to localhost
+# ansible.builtin.fetch:
+# src: /opt/ansible-pct/.ssh/ansible
+# dest: ~/.ssh/proxmox_ansible_private_key
+# flat: yes
+# fail_on_missing: true
+#
+# - name: Clean up generated SSH keys
+# ansible.builtin.file:
+# path: /opt/ansible-pct/.ssh/ansible*
+# state: absent
+#
+# - name: Configure private key permissions on localhost
+# hosts: localhost
+# tasks:
+# - name: Set permissions for fetched private key
+# ansible.builtin.file:
+# path: ~/.ssh/proxmox_ansible_private_key
+# mode: '0600'
+#
+# --------------------------------
+# Static inventory file: hosts.yml
+# --------------------------------
+# all:
+# children:
+# lxc:
+# hosts:
+# container-1:
+# ansible_host: 10.0.0.10
+# proxmox_vmid: 100
+# ansible_connection: community.general.proxmox_pct_remote
+# ansible_user: ansible
+# container-2:
+# ansible_host: 10.0.0.10
+# proxmox_vmid: 200
+# ansible_connection: community.general.proxmox_pct_remote
+# ansible_user: ansible
+# proxmox:
+# hosts:
+# proxmox-1:
+# ansible_host: 10.0.0.10
+#
+#
+# ---------------------------------------------
+# Dynamic inventory file: inventory.proxmox.yml
+# ---------------------------------------------
+# plugin: community.general.proxmox
+# url: https://10.0.0.10:8006
+# validate_certs: false
+# user: ansible@pam
+# token_id: ansible
+# token_secret: !vault |
+# $ANSIBLE_VAULT;1.1;AES256
+# ...
+
+# want_facts: true
+# exclude_nodes: true
+# filters:
+# - proxmox_vmtype == "lxc"
+# want_proxmox_nodes_ansible_host: false
+# compose:
+# ansible_host: "'10.0.0.10'"
+# ansible_connection: "'community.general.proxmox_pct_remote'"
+# ansible_user: "'ansible'"
+#
+#
+# ----------------------
+# Playbook: playbook.yml
+# ----------------------
+---
+- hosts: lxc
+ # On nodes with many containers you might want to deactivate the devices facts
+ # or set `gather_facts: false` if you don't need them.
+ # More info on gathering fact subsets:
+ # https://docs.ansible.com/ansible/latest/collections/ansible/builtin/setup_module.html
+ #
+ # gather_facts: true
+ # gather_subset:
+ # - "!devices"
+ tasks:
+ - name: Ping LXC container
+ ansible.builtin.ping:
+"""
+
+import os
+import pathlib
+import socket
+import tempfile
+import typing as t
+
+from ansible.errors import (
+ AnsibleAuthenticationFailure,
+ AnsibleConnectionFailure,
+ AnsibleError,
+)
+from ansible_collections.community.general.plugins.module_utils._filelock import FileLock, LockTimeout
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
+from ansible.module_utils.compat.paramiko import PARAMIKO_IMPORT_ERR, paramiko
+from ansible.module_utils.compat.version import LooseVersion
+from ansible.plugins.connection import ConnectionBase
+from ansible.utils.display import Display
+from ansible.utils.path import makedirs_safe
+from binascii import hexlify
+
+
+display = Display()
+
+
+def authenticity_msg(hostname: str, ktype: str, fingerprint: str) -> str:
+ msg = f"""
+ paramiko: The authenticity of host '{hostname}' can't be established.
+ The {ktype} key fingerprint is {fingerprint}.
+ Are you sure you want to continue connecting (yes/no)?
+ """
+ return msg
+
+
+MissingHostKeyPolicy: type = object
+if paramiko:
+ MissingHostKeyPolicy = paramiko.MissingHostKeyPolicy
+
+
+class MyAddPolicy(MissingHostKeyPolicy):
+ """
+ Based on AutoAddPolicy in paramiko so we can determine when keys are added
+
+ and also prompt for input.
+
+ Policy for automatically adding the hostname and new host key to the
+ local L{HostKeys} object, and saving it. This is used by L{SSHClient}.
+ """
+
+ def __init__(self, connection: Connection) -> None:
+ self.connection = connection
+ self._options = connection._options
+
+ def missing_host_key(self, client, hostname, key) -> None:
+
+ if all((self.connection.get_option('host_key_checking'), not self.connection.get_option('host_key_auto_add'))):
+
+ fingerprint = hexlify(key.get_fingerprint())
+ ktype = key.get_name()
+
+ if self.connection.get_option('use_persistent_connections') or self.connection.force_persistence:
+ # don't print the prompt string since the user cannot respond
+ # to the question anyway
+ raise AnsibleError(authenticity_msg(hostname, ktype, fingerprint)[1:92])
+
+ inp = to_text(
+ display.prompt_until(authenticity_msg(hostname, ktype, fingerprint), private=False),
+ errors='surrogate_or_strict'
+ )
+
+ if inp.lower() not in ['yes', 'y', '']:
+ raise AnsibleError('host connection rejected by user')
+
+ key._added_by_ansible_this_time = True
+
+ # existing implementation below:
+ client._host_keys.add(hostname, key.get_name(), key)
+
+ # host keys are actually saved in close() function below
+ # in order to control ordering.
+
+
+class Connection(ConnectionBase):
+ """ SSH based connections (paramiko) to Proxmox pct """
+
+ transport = 'community.general.proxmox_pct_remote'
+ _log_channel: str | None = None
+
+ def __init__(self, play_context, new_stdin, *args, **kwargs):
+ super(Connection, self).__init__(play_context, new_stdin, *args, **kwargs)
+
+ def _set_log_channel(self, name: str) -> None:
+ """ Mimic paramiko.SSHClient.set_log_channel """
+ self._log_channel = name
+
+ def _parse_proxy_command(self, port: int = 22) -> dict[str, t.Any]:
+ proxy_command = self.get_option('proxy_command') or None
+
+ sock_kwarg = {}
+ if proxy_command:
+ replacers = {
+ '%h': self.get_option('remote_addr'),
+ '%p': port,
+ '%r': self.get_option('remote_user')
+ }
+ for find, replace in replacers.items():
+ proxy_command = proxy_command.replace(find, str(replace))
+ try:
+ sock_kwarg = {'sock': paramiko.ProxyCommand(proxy_command)}
+ display.vvv(f'CONFIGURE PROXY COMMAND FOR CONNECTION: {proxy_command}', host=self.get_option('remote_addr'))
+ except AttributeError:
+ display.warning('Paramiko ProxyCommand support unavailable. '
+ 'Please upgrade to Paramiko 1.9.0 or newer. '
+ 'Not using configured ProxyCommand')
+
+ return sock_kwarg
+
+ def _connect(self) -> Connection:
+ """ activates the connection object """
+
+ if paramiko is None:
+ raise AnsibleError(f'paramiko is not installed: {to_native(PARAMIKO_IMPORT_ERR)}')
+
+ port = self.get_option('port')
+ display.vvv(f'ESTABLISH PARAMIKO SSH CONNECTION FOR USER: {self.get_option("remote_user")} on PORT {to_text(port)} TO {self.get_option("remote_addr")}',
+ host=self.get_option('remote_addr'))
+
+ ssh = paramiko.SSHClient()
+
+ # Set pubkey and hostkey algorithms to disable, the only manipulation allowed currently
+ # is keeping or omitting rsa-sha2 algorithms
+ # default_keys: t.Tuple[str] = ()
+ paramiko_preferred_pubkeys = getattr(paramiko.Transport, '_preferred_pubkeys', ())
+ paramiko_preferred_hostkeys = getattr(paramiko.Transport, '_preferred_keys', ())
+ use_rsa_sha2_algorithms = self.get_option('use_rsa_sha2_algorithms')
+ disabled_algorithms: t.Dict[str, t.Iterable[str]] = {}
+ if not use_rsa_sha2_algorithms:
+ if paramiko_preferred_pubkeys:
+ disabled_algorithms['pubkeys'] = tuple(a for a in paramiko_preferred_pubkeys if 'rsa-sha2' in a)
+ if paramiko_preferred_hostkeys:
+ disabled_algorithms['keys'] = tuple(a for a in paramiko_preferred_hostkeys if 'rsa-sha2' in a)
+
+ # override paramiko's default logger name
+ if self._log_channel is not None:
+ ssh.set_log_channel(self._log_channel)
+
+ self.keyfile = os.path.expanduser('~/.ssh/known_hosts')
+
+ if self.get_option('host_key_checking'):
+ for ssh_known_hosts in ('/etc/ssh/ssh_known_hosts', '/etc/openssh/ssh_known_hosts'):
+ try:
+ ssh.load_system_host_keys(ssh_known_hosts)
+ break
+ except IOError:
+ pass # file was not found, but not required to function
+ except paramiko.hostkeys.InvalidHostKey as e:
+ raise AnsibleConnectionFailure(f'Invalid host key: {to_text(e.line)}')
+ try:
+ ssh.load_system_host_keys()
+ except paramiko.hostkeys.InvalidHostKey as e:
+ raise AnsibleConnectionFailure(f'Invalid host key: {to_text(e.line)}')
+
+ ssh_connect_kwargs = self._parse_proxy_command(port)
+ ssh.set_missing_host_key_policy(MyAddPolicy(self))
+ conn_password = self.get_option('password')
+ allow_agent = True
+
+ if conn_password is not None:
+ allow_agent = False
+
+ try:
+ key_filename = None
+ if self.get_option('private_key_file'):
+ key_filename = os.path.expanduser(self.get_option('private_key_file'))
+
+ # paramiko 2.2 introduced auth_timeout parameter
+ if LooseVersion(paramiko.__version__) >= LooseVersion('2.2.0'):
+ ssh_connect_kwargs['auth_timeout'] = self.get_option('timeout')
+
+ # paramiko 1.15 introduced banner timeout parameter
+ if LooseVersion(paramiko.__version__) >= LooseVersion('1.15.0'):
+ ssh_connect_kwargs['banner_timeout'] = self.get_option('banner_timeout')
+
+ ssh.connect(
+ self.get_option('remote_addr').lower(),
+ username=self.get_option('remote_user'),
+ allow_agent=allow_agent,
+ look_for_keys=self.get_option('look_for_keys'),
+ key_filename=key_filename,
+ password=conn_password,
+ timeout=self.get_option('timeout'),
+ port=port,
+ disabled_algorithms=disabled_algorithms,
+ **ssh_connect_kwargs,
+ )
+ except paramiko.ssh_exception.BadHostKeyException as e:
+ raise AnsibleConnectionFailure(f'host key mismatch for {to_text(e.hostname)}')
+ except paramiko.ssh_exception.AuthenticationException as e:
+ msg = f'Failed to authenticate: {e}'
+ raise AnsibleAuthenticationFailure(msg)
+ except Exception as e:
+ msg = to_text(e)
+ if u'PID check failed' in msg:
+ raise AnsibleError('paramiko version issue, please upgrade paramiko on the machine running ansible')
+ elif u'Private key file is encrypted' in msg:
+ msg = f'ssh {self.get_option("remote_user")}@{self.get_options("remote_addr")}:{port} : ' + \
+ f'{msg}\nTo connect as a different user, use -u .'
+ raise AnsibleConnectionFailure(msg)
+ else:
+ raise AnsibleConnectionFailure(msg)
+ self.ssh = ssh
+ self._connected = True
+ return self
+
+ def _any_keys_added(self) -> bool:
+ for hostname, keys in self.ssh._host_keys.items():
+ for keytype, key in keys.items():
+ added_this_time = getattr(key, '_added_by_ansible_this_time', False)
+ if added_this_time:
+ return True
+ return False
+
+ def _save_ssh_host_keys(self, filename: str) -> None:
+ """
+ not using the paramiko save_ssh_host_keys function as we want to add new SSH keys at the bottom so folks
+ don't complain about it :)
+ """
+
+ if not self._any_keys_added():
+ return
+
+ path = os.path.expanduser('~/.ssh')
+ makedirs_safe(path)
+
+ with open(filename, 'w') as f:
+ for hostname, keys in self.ssh._host_keys.items():
+ for keytype, key in keys.items():
+ # was f.write
+ added_this_time = getattr(key, '_added_by_ansible_this_time', False)
+ if not added_this_time:
+ f.write(f'{hostname} {keytype} {key.get_base64()}\n')
+
+ for hostname, keys in self.ssh._host_keys.items():
+ for keytype, key in keys.items():
+ added_this_time = getattr(key, '_added_by_ansible_this_time', False)
+ if added_this_time:
+ f.write(f'{hostname} {keytype} {key.get_base64()}\n')
+
+ def _build_pct_command(self, cmd: str) -> str:
+ cmd = ['/usr/sbin/pct', 'exec', str(self.get_option('vmid')), '--', cmd]
+ if self.get_option('remote_user') != 'root':
+ cmd = [self.get_option('proxmox_become_method')] + cmd
+ display.vvv(f'INFO Running as non root user: {self.get_option("remote_user")}, trying to run pct with become method: ' +
+ f'{self.get_option("proxmox_become_method")}',
+ host=self.get_option('remote_addr'))
+ return ' '.join(cmd)
+
+ def exec_command(self, cmd: str, in_data: bytes | None = None, sudoable: bool = True) -> tuple[int, bytes, bytes]:
+ """ run a command on inside the LXC container """
+
+ cmd = self._build_pct_command(cmd)
+
+ super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
+
+ bufsize = 4096
+
+ try:
+ self.ssh.get_transport().set_keepalive(5)
+ chan = self.ssh.get_transport().open_session()
+ except Exception as e:
+ text_e = to_text(e)
+ msg = 'Failed to open session'
+ if text_e:
+ msg += f': {text_e}'
+ raise AnsibleConnectionFailure(to_native(msg))
+
+ # sudo usually requires a PTY (cf. requiretty option), therefore
+ # we give it one by default (pty=True in ansible.cfg), and we try
+ # to initialise from the calling environment when sudoable is enabled
+ if self.get_option('pty') and sudoable:
+ chan.get_pty(term=os.getenv('TERM', 'vt100'), width=int(os.getenv('COLUMNS', 0)), height=int(os.getenv('LINES', 0)))
+
+ display.vvv(f'EXEC {cmd}', host=self.get_option('remote_addr'))
+
+ cmd = to_bytes(cmd, errors='surrogate_or_strict')
+
+ no_prompt_out = b''
+ no_prompt_err = b''
+ become_output = b''
+
+ try:
+ chan.exec_command(cmd)
+ if self.become and self.become.expect_prompt():
+ password_prompt = False
+ become_success = False
+ while not (become_success or password_prompt):
+ display.debug('Waiting for Privilege Escalation input')
+
+ chunk = chan.recv(bufsize)
+ display.debug(f'chunk is: {to_text(chunk)}')
+ if not chunk:
+ if b'unknown user' in become_output:
+ n_become_user = to_native(self.become.get_option('become_user'))
+ raise AnsibleError(f'user {n_become_user} does not exist')
+ else:
+ break
+ # raise AnsibleError('ssh connection closed waiting for password prompt')
+ become_output += chunk
+
+ # need to check every line because we might get lectured
+ # and we might get the middle of a line in a chunk
+ for line in become_output.splitlines(True):
+ if self.become.check_success(line):
+ become_success = True
+ break
+ elif self.become.check_password_prompt(line):
+ password_prompt = True
+ break
+
+ if password_prompt:
+ if self.become:
+ become_pass = self.become.get_option('become_pass')
+ chan.sendall(to_bytes(become_pass, errors='surrogate_or_strict') + b'\n')
+ else:
+ raise AnsibleError('A password is required but none was supplied')
+ else:
+ no_prompt_out += become_output
+ no_prompt_err += become_output
+
+ if in_data:
+ for i in range(0, len(in_data), bufsize):
+ chan.send(in_data[i:i + bufsize])
+ chan.shutdown_write()
+ elif in_data == b'':
+ chan.shutdown_write()
+
+ except socket.timeout:
+ raise AnsibleError('ssh timed out waiting for privilege escalation.\n' + to_text(become_output))
+
+ stdout = b''.join(chan.makefile('rb', bufsize))
+ stderr = b''.join(chan.makefile_stderr('rb', bufsize))
+ returncode = chan.recv_exit_status()
+
+ if 'pct: not found' in stderr.decode('utf-8'):
+ raise AnsibleError(
+ f'pct not found in path of host: {to_text(self.get_option("remote_addr"))}')
+
+ return (returncode, no_prompt_out + stdout, no_prompt_out + stderr)
+
+ def put_file(self, in_path: str, out_path: str) -> None:
+ """ transfer a file from local to remote """
+
+ display.vvv(f'PUT {in_path} TO {out_path}', host=self.get_option('remote_addr'))
+ try:
+ with open(in_path, 'rb') as f:
+ data = f.read()
+ returncode, stdout, stderr = self.exec_command(
+ ' '.join([
+ self._shell.executable, '-c',
+ self._shell.quote(f'cat > {out_path}')]),
+ in_data=data,
+ sudoable=False)
+ if returncode != 0:
+ if 'cat: not found' in stderr.decode('utf-8'):
+ raise AnsibleError(
+ f'cat not found in path of container: {to_text(self.get_option("vmid"))}')
+ raise AnsibleError(
+ f'{to_text(stdout)}\n{to_text(stderr)}')
+ except Exception as e:
+ raise AnsibleError(
+ f'error occurred while putting file from {in_path} to {out_path}!\n{to_text(e)}')
+
+ def fetch_file(self, in_path: str, out_path: str) -> None:
+ """ save a remote file to the specified path """
+
+ display.vvv(f'FETCH {in_path} TO {out_path}', host=self.get_option('remote_addr'))
+ try:
+ returncode, stdout, stderr = self.exec_command(
+ ' '.join([
+ self._shell.executable, '-c',
+ self._shell.quote(f'cat {in_path}')]),
+ sudoable=False)
+ if returncode != 0:
+ if 'cat: not found' in stderr.decode('utf-8'):
+ raise AnsibleError(
+ f'cat not found in path of container: {to_text(self.get_option("vmid"))}')
+ raise AnsibleError(
+ f'{to_text(stdout)}\n{to_text(stderr)}')
+ with open(out_path, 'wb') as f:
+ f.write(stdout)
+ except Exception as e:
+ raise AnsibleError(
+ f'error occurred while fetching file from {in_path} to {out_path}!\n{to_text(e)}')
+
+ def reset(self) -> None:
+ """ reset the connection """
+
+ if not self._connected:
+ return
+ self.close()
+ self._connect()
+
+ def close(self) -> None:
+ """ terminate the connection """
+
+ if self.get_option('host_key_checking') and self.get_option('record_host_keys') and self._any_keys_added():
+ # add any new SSH host keys -- warning -- this could be slow
+ # (This doesn't acquire the connection lock because it needs
+ # to exclude only other known_hosts writers, not connections
+ # that are starting up.)
+ lockfile = os.path.basename(self.keyfile)
+ dirname = os.path.dirname(self.keyfile)
+ makedirs_safe(dirname)
+ tmp_keyfile_name = None
+ try:
+ with FileLock().lock_file(lockfile, dirname, self.get_option('lock_file_timeout')):
+ # just in case any were added recently
+
+ self.ssh.load_system_host_keys()
+ self.ssh._host_keys.update(self.ssh._system_host_keys)
+
+ # gather information about the current key file, so
+ # we can ensure the new file has the correct mode/owner
+
+ key_dir = os.path.dirname(self.keyfile)
+ if os.path.exists(self.keyfile):
+ key_stat = os.stat(self.keyfile)
+ mode = key_stat.st_mode & 0o777
+ uid = key_stat.st_uid
+ gid = key_stat.st_gid
+ else:
+ mode = 0o644
+ uid = os.getuid()
+ gid = os.getgid()
+
+ # Save the new keys to a temporary file and move it into place
+ # rather than rewriting the file. We set delete=False because
+ # the file will be moved into place rather than cleaned up.
+
+ with tempfile.NamedTemporaryFile(dir=key_dir, delete=False) as tmp_keyfile:
+ tmp_keyfile_name = tmp_keyfile.name
+ os.chmod(tmp_keyfile_name, mode)
+ os.chown(tmp_keyfile_name, uid, gid)
+ self._save_ssh_host_keys(tmp_keyfile_name)
+
+ os.rename(tmp_keyfile_name, self.keyfile)
+ except LockTimeout:
+ raise AnsibleError(
+ f'writing lock file for {self.keyfile} ran in to the timeout of {self.get_option("lock_file_timeout")}s')
+ except paramiko.hostkeys.InvalidHostKey as e:
+ raise AnsibleConnectionFailure(f'Invalid host key: {e.line}')
+ except Exception as e:
+ # unable to save keys, including scenario when key was invalid
+ # and caught earlier
+ raise AnsibleError(
+ f'error occurred while writing SSH host keys!\n{to_text(e)}')
+ finally:
+ if tmp_keyfile_name is not None:
+ pathlib.Path(tmp_keyfile_name).unlink(missing_ok=True)
+
+ self.ssh.close()
+ self._connected = False
diff --git a/plugins/connection/qubes.py b/plugins/connection/qubes.py
index b54eeb3a84..5a9963df2d 100644
--- a/plugins/connection/qubes.py
+++ b/plugins/connection/qubes.py
@@ -8,38 +8,36 @@
#
# Written by: Kushal Das (https://github.com/kushaldas)
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: qubes
- short_description: Interact with an existing QubesOS AppVM
+DOCUMENTATION = r"""
+name: qubes
+short_description: Interact with an existing QubesOS AppVM
+description:
+ - Run commands or put/fetch files to an existing Qubes AppVM using qubes tools.
+author: Kushal Das (@kushaldas)
+
+
+options:
+ remote_addr:
description:
- - Run commands or put/fetch files to an existing Qubes AppVM using qubes tools.
-
- author: Kushal Das (@kushaldas)
-
-
- options:
- remote_addr:
- description:
- - VM name.
- type: string
- default: inventory_hostname
- vars:
- - name: ansible_host
- remote_user:
- description:
- - The user to execute as inside the VM.
- type: string
- default: The I(user) account as default in Qubes OS.
- vars:
- - name: ansible_user
+ - VM name.
+ type: string
+ default: inventory_hostname
+ vars:
+ - name: ansible_host
+ remote_user:
+ description:
+ - The user to execute as inside the VM.
+ type: string
+ default: The I(user) account as default in Qubes OS.
+ vars:
+ - name: ansible_user
# keyword:
# - name: hosts
-'''
+"""
import subprocess
@@ -78,7 +76,7 @@ class Connection(ConnectionBase):
"""
display.vvvv("CMD: ", cmd)
if not cmd.endswith("\n"):
- cmd = cmd + "\n"
+ cmd = f"{cmd}\n"
local_cmd = []
# For dom0
@@ -95,7 +93,7 @@ class Connection(ConnectionBase):
display.vvvv("Local cmd: ", local_cmd)
- display.vvv("RUN %s" % (local_cmd,), host=self._remote_vmname)
+ display.vvv(f"RUN {local_cmd}", host=self._remote_vmname)
p = subprocess.Popen(local_cmd, shell=False, stdin=subprocess.PIPE,
stdout=subprocess.PIPE, stderr=subprocess.PIPE)
@@ -114,42 +112,42 @@ class Connection(ConnectionBase):
"""Run specified command in a running QubesVM """
super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
- display.vvvv("CMD IS: %s" % cmd)
+ display.vvvv(f"CMD IS: {cmd}")
rc, stdout, stderr = self._qubes(cmd)
- display.vvvvv("STDOUT %r STDERR %r" % (stderr, stderr))
+ display.vvvvv(f"STDOUT {stdout!r} STDERR {stderr!r}")
return rc, stdout, stderr
def put_file(self, in_path, out_path):
""" Place a local file located in 'in_path' inside VM at 'out_path' """
super(Connection, self).put_file(in_path, out_path)
- display.vvv("PUT %s TO %s" % (in_path, out_path), host=self._remote_vmname)
+ display.vvv(f"PUT {in_path} TO {out_path}", host=self._remote_vmname)
with open(in_path, "rb") as fobj:
source_data = fobj.read()
- retcode, dummy, dummy = self._qubes('cat > "{0}"\n'.format(out_path), source_data, "qubes.VMRootShell")
+ retcode, dummy, dummy = self._qubes(f'cat > "{out_path}\"\n', source_data, "qubes.VMRootShell")
# if qubes.VMRootShell service not supported, fallback to qubes.VMShell and
# hope it will have appropriate permissions
if retcode == 127:
- retcode, dummy, dummy = self._qubes('cat > "{0}"\n'.format(out_path), source_data)
+ retcode, dummy, dummy = self._qubes(f'cat > "{out_path}\"\n', source_data)
if retcode != 0:
- raise AnsibleConnectionFailure('Failed to put_file to {0}'.format(out_path))
+ raise AnsibleConnectionFailure(f'Failed to put_file to {out_path}')
def fetch_file(self, in_path, out_path):
"""Obtain file specified via 'in_path' from the container and place it at 'out_path' """
super(Connection, self).fetch_file(in_path, out_path)
- display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self._remote_vmname)
+ display.vvv(f"FETCH {in_path} TO {out_path}", host=self._remote_vmname)
# We are running in dom0
- cmd_args_list = ["qvm-run", "--pass-io", self._remote_vmname, "cat {0}".format(in_path)]
+ cmd_args_list = ["qvm-run", "--pass-io", self._remote_vmname, f"cat {in_path}"]
with open(out_path, "wb") as fobj:
p = subprocess.Popen(cmd_args_list, shell=False, stdout=fobj)
p.communicate()
if p.returncode != 0:
- raise AnsibleConnectionFailure('Failed to fetch file to {0}'.format(out_path))
+ raise AnsibleConnectionFailure(f'Failed to fetch file to {out_path}')
def close(self):
""" Closing the connection """
diff --git a/plugins/connection/saltstack.py b/plugins/connection/saltstack.py
index 1dbc7296c7..f826741926 100644
--- a/plugins/connection/saltstack.py
+++ b/plugins/connection/saltstack.py
@@ -7,16 +7,15 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Michael Scherer (@mscherer)
- name: saltstack
- short_description: Allow ansible to piggyback on salt minions
- description:
- - This allows you to use existing Saltstack infrastructure to connect to targets.
-'''
+DOCUMENTATION = r"""
+author: Michael Scherer (@mscherer)
+name: saltstack
+short_description: Allow ansible to piggyback on salt minions
+description:
+ - This allows you to use existing Saltstack infrastructure to connect to targets.
+"""
import os
import base64
@@ -59,11 +58,11 @@ class Connection(ConnectionBase):
if in_data:
raise errors.AnsibleError("Internal Error: this module does not support optimized module pipelining")
- self._display.vvv("EXEC %s" % cmd, host=self.host)
+ self._display.vvv(f"EXEC {cmd}", host=self.host)
# need to add 'true;' to work around https://github.com/saltstack/salt/issues/28077
- res = self.client.cmd(self.host, 'cmd.exec_code_all', ['bash', 'true;' + cmd])
+ res = self.client.cmd(self.host, 'cmd.exec_code_all', ['bash', f"true;{cmd}"])
if self.host not in res:
- raise errors.AnsibleError("Minion %s didn't answer, check if salt-minion is running and the name is correct" % self.host)
+ raise errors.AnsibleError(f"Minion {self.host} didn't answer, check if salt-minion is running and the name is correct")
p = res[self.host]
return p['retcode'], p['stdout'], p['stderr']
@@ -81,7 +80,7 @@ class Connection(ConnectionBase):
super(Connection, self).put_file(in_path, out_path)
out_path = self._normalize_path(out_path, '/')
- self._display.vvv("PUT %s TO %s" % (in_path, out_path), host=self.host)
+ self._display.vvv(f"PUT {in_path} TO {out_path}", host=self.host)
with open(in_path, 'rb') as in_fh:
content = in_fh.read()
self.client.cmd(self.host, 'hashutil.base64_decodefile', [base64.b64encode(content), out_path])
@@ -93,7 +92,7 @@ class Connection(ConnectionBase):
super(Connection, self).fetch_file(in_path, out_path)
in_path = self._normalize_path(in_path, '/')
- self._display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self.host)
+ self._display.vvv(f"FETCH {in_path} TO {out_path}", host=self.host)
content = self.client.cmd(self.host, 'cp.get_file_str', [in_path])[self.host]
open(out_path, 'wb').write(content)
diff --git a/plugins/connection/zone.py b/plugins/connection/zone.py
index 0a591143e0..baca9312b3 100644
--- a/plugins/connection/zone.py
+++ b/plugins/connection/zone.py
@@ -8,25 +8,24 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- author: Ansible Core Team
- name: zone
- short_description: Run tasks in a zone instance
+DOCUMENTATION = r"""
+author: Ansible Core Team
+name: zone
+short_description: Run tasks in a zone instance
+description:
+ - Run commands or put/fetch files to an existing zone.
+options:
+ remote_addr:
description:
- - Run commands or put/fetch files to an existing zone.
- options:
- remote_addr:
- description:
- - Zone identifier
- type: string
- default: inventory_hostname
- vars:
- - name: ansible_host
- - name: ansible_zone_host
-'''
+ - Zone identifier.
+ type: string
+ default: inventory_hostname
+ vars:
+ - name: ansible_host
+ - name: ansible_zone_host
+"""
import os
import os.path
@@ -62,14 +61,14 @@ class Connection(ConnectionBase):
self.zlogin_cmd = to_bytes(self._search_executable('zlogin'))
if self.zone not in self.list_zones():
- raise AnsibleError("incorrect zone name %s" % self.zone)
+ raise AnsibleError(f"incorrect zone name {self.zone}")
@staticmethod
def _search_executable(executable):
try:
return get_bin_path(executable)
except ValueError:
- raise AnsibleError("%s command not found in PATH" % executable)
+ raise AnsibleError(f"{executable} command not found in PATH")
def list_zones(self):
process = subprocess.Popen([self.zoneadm_cmd, 'list', '-ip'],
@@ -94,7 +93,7 @@ class Connection(ConnectionBase):
# stdout, stderr = p.communicate()
path = process.stdout.readlines()[0].split(':')[3]
- return path + '/root'
+ return f"{path}/root"
def _connect(self):
""" connect to the zone; nothing to do here """
@@ -117,7 +116,7 @@ class Connection(ConnectionBase):
local_cmd = [self.zlogin_cmd, self.zone, cmd]
local_cmd = map(to_bytes, local_cmd)
- display.vvv("EXEC %s" % (local_cmd), host=self.zone)
+ display.vvv(f"EXEC {local_cmd}", host=self.zone)
p = subprocess.Popen(local_cmd, shell=False, stdin=stdin,
stdout=subprocess.PIPE, stderr=subprocess.PIPE)
@@ -140,7 +139,7 @@ class Connection(ConnectionBase):
exist in any given chroot. So for now we're choosing "/" instead.
This also happens to be the former default.
- Can revisit using $HOME instead if it's a problem
+ Can revisit using $HOME instead if it is a problem
"""
if not remote_path.startswith(os.path.sep):
remote_path = os.path.join(os.path.sep, remote_path)
@@ -149,7 +148,7 @@ class Connection(ConnectionBase):
def put_file(self, in_path, out_path):
""" transfer a file from local to zone """
super(Connection, self).put_file(in_path, out_path)
- display.vvv("PUT %s TO %s" % (in_path, out_path), host=self.zone)
+ display.vvv(f"PUT {in_path} TO {out_path}", host=self.zone)
out_path = shlex_quote(self._prefix_login_path(out_path))
try:
@@ -159,27 +158,27 @@ class Connection(ConnectionBase):
else:
count = ''
try:
- p = self._buffered_exec_command('dd of=%s bs=%s%s' % (out_path, BUFSIZE, count), stdin=in_file)
+ p = self._buffered_exec_command(f'dd of={out_path} bs={BUFSIZE}{count}', stdin=in_file)
except OSError:
raise AnsibleError("jail connection requires dd command in the jail")
try:
stdout, stderr = p.communicate()
except Exception:
traceback.print_exc()
- raise AnsibleError("failed to transfer file %s to %s" % (in_path, out_path))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}")
if p.returncode != 0:
- raise AnsibleError("failed to transfer file %s to %s:\n%s\n%s" % (in_path, out_path, stdout, stderr))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}:\n{stdout}\n{stderr}")
except IOError:
- raise AnsibleError("file or module does not exist at: %s" % in_path)
+ raise AnsibleError(f"file or module does not exist at: {in_path}")
def fetch_file(self, in_path, out_path):
""" fetch a file from zone to local """
super(Connection, self).fetch_file(in_path, out_path)
- display.vvv("FETCH %s TO %s" % (in_path, out_path), host=self.zone)
+ display.vvv(f"FETCH {in_path} TO {out_path}", host=self.zone)
in_path = shlex_quote(self._prefix_login_path(in_path))
try:
- p = self._buffered_exec_command('dd if=%s bs=%s' % (in_path, BUFSIZE))
+ p = self._buffered_exec_command(f'dd if={in_path} bs={BUFSIZE}')
except OSError:
raise AnsibleError("zone connection requires dd command in the zone")
@@ -191,10 +190,10 @@ class Connection(ConnectionBase):
chunk = p.stdout.read(BUFSIZE)
except Exception:
traceback.print_exc()
- raise AnsibleError("failed to transfer file %s to %s" % (in_path, out_path))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}")
stdout, stderr = p.communicate()
if p.returncode != 0:
- raise AnsibleError("failed to transfer file %s to %s:\n%s\n%s" % (in_path, out_path, stdout, stderr))
+ raise AnsibleError(f"failed to transfer file {in_path} to {out_path}:\n{stdout}\n{stderr}")
def close(self):
""" terminate the connection; nothing to do here """
diff --git a/plugins/doc_fragments/alicloud.py b/plugins/doc_fragments/alicloud.py
index b462fcacb4..3b810852b7 100644
--- a/plugins/doc_fragments/alicloud.py
+++ b/plugins/doc_fragments/alicloud.py
@@ -11,75 +11,73 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Alicloud only documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
alicloud_access_key:
description:
- - Alibaba Cloud access key. If not set then the value of environment variable E(ALICLOUD_ACCESS_KEY),
- E(ALICLOUD_ACCESS_KEY_ID) will be used instead.
+ - Alibaba Cloud access key. If not set then the value of environment variable E(ALICLOUD_ACCESS_KEY), E(ALICLOUD_ACCESS_KEY_ID)
+ will be used instead.
aliases: ['access_key_id', 'access_key']
type: str
alicloud_secret_key:
description:
- - Alibaba Cloud secret key. If not set then the value of environment variable E(ALICLOUD_SECRET_KEY),
- E(ALICLOUD_SECRET_ACCESS_KEY) will be used instead.
+ - Alibaba Cloud secret key. If not set then the value of environment variable E(ALICLOUD_SECRET_KEY), E(ALICLOUD_SECRET_ACCESS_KEY)
+ will be used instead.
aliases: ['secret_access_key', 'secret_key']
type: str
alicloud_region:
description:
- - The Alibaba Cloud region to use. If not specified then the value of environment variable
- E(ALICLOUD_REGION), E(ALICLOUD_REGION_ID) will be used instead.
+ - The Alibaba Cloud region to use. If not specified then the value of environment variable E(ALICLOUD_REGION), E(ALICLOUD_REGION_ID)
+ will be used instead.
aliases: ['region', 'region_id']
required: true
type: str
alicloud_security_token:
description:
- - The Alibaba Cloud security token. If not specified then the value of environment variable
- E(ALICLOUD_SECURITY_TOKEN) will be used instead.
+ - The Alibaba Cloud security token. If not specified then the value of environment variable E(ALICLOUD_SECURITY_TOKEN)
+ will be used instead.
aliases: ['security_token']
type: str
alicloud_assume_role:
description:
- If provided with a role ARN, Ansible will attempt to assume this role using the supplied credentials.
- - The nested assume_role block supports C(alicloud_assume_role_arn), C(alicloud_assume_role_session_name),
- C(alicloud_assume_role_session_expiration) and C(alicloud_assume_role_policy).
+ - The nested assume_role block supports C(alicloud_assume_role_arn), C(alicloud_assume_role_session_name), C(alicloud_assume_role_session_expiration)
+ and C(alicloud_assume_role_policy).
type: dict
aliases: ['assume_role']
alicloud_assume_role_arn:
description:
- - The Alibaba Cloud C(role_arn). The ARN of the role to assume. If ARN is set to an empty string,
- it does not perform role switching. It supports environment variable E(ALICLOUD_ASSUME_ROLE_ARN).
- ansible will execute with provided credentials.
+ - The Alibaba Cloud C(role_arn). The ARN of the role to assume. If ARN is set to an empty string, it does not perform
+ role switching. It supports environment variable E(ALICLOUD_ASSUME_ROLE_ARN). ansible will execute with provided credentials.
aliases: ['assume_role_arn']
type: str
alicloud_assume_role_session_name:
description:
- - The Alibaba Cloud session_name. The session name to use when assuming the role. If omitted,
- 'ansible' is passed to the AssumeRole call as session name. It supports environment variable
- E(ALICLOUD_ASSUME_ROLE_SESSION_NAME).
+ - The Alibaba Cloud session_name. The session name to use when assuming the role. If omitted, 'ansible' is passed to
+ the AssumeRole call as session name. It supports environment variable E(ALICLOUD_ASSUME_ROLE_SESSION_NAME).
aliases: ['assume_role_session_name']
type: str
alicloud_assume_role_session_expiration:
description:
- - The Alibaba Cloud C(session_expiration). The time after which the established session for assuming
- role expires. Valid value range 900-3600 seconds. Default to 3600 (in this case Alicloud use own default
- value). It supports environment variable E(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION).
+ - The Alibaba Cloud C(session_expiration). The time after which the established session for assuming role expires. Valid
+ value range 900-3600 seconds. Default to 3600 (in this case Alicloud use own default value). It supports environment
+ variable E(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION).
aliases: ['assume_role_session_expiration']
type: int
ecs_role_name:
description:
- - The RAM Role Name attached on a ECS instance for API operations. You can retrieve this from the 'Access Control'
- section of the Alibaba Cloud console.
- - If you're running Ansible from an ECS instance with RAM Instance using RAM Role, Ansible will just access the
- metadata U(http://100.100.100.200/latest/meta-data/ram/security-credentials/) to obtain the STS
- credential. This is a preferred approach over any other when running in ECS as you can avoid hard coding
- credentials. Instead these are leased on-the-fly by Ansible which reduces the chance of leakage.
+ - The RAM Role Name attached on a ECS instance for API operations. You can retrieve this from the 'Access Control' section
+ of the Alibaba Cloud console.
+ - If you are running Ansible from an ECS instance with RAM Instance using RAM Role, Ansible will just access the metadata
+ U(http://100.100.100.200/latest/meta-data/ram/security-credentials/) to obtain the STS credential.
+ This is a preferred approach over any other when running in ECS as you can avoid hard coding credentials. Instead
+ these are leased on-the-fly by Ansible which reduces the chance of leakage.
aliases: ['role_name']
type: str
profile:
description:
- - This is the Alicloud profile name as set in the shared credentials file. It can also be sourced from the
- E(ALICLOUD_PROFILE) environment variable.
+ - This is the Alicloud profile name as set in the shared credentials file. It can also be sourced from the E(ALICLOUD_PROFILE)
+ environment variable.
type: str
shared_credentials_file:
description:
@@ -88,22 +86,14 @@ options:
- If this is not set and a profile is specified, C(~/.aliyun/config.json) will be used.
type: str
author:
- - "He Guimin (@xiaozhu36)"
+ - "He Guimin (@xiaozhu36)"
requirements:
- - "Python >= 3.6"
+ - "Python >= 3.6"
notes:
- - If parameters are not set within the module, the following
- environment variables can be used in decreasing order of precedence
- E(ALICLOUD_ACCESS_KEY) or E(ALICLOUD_ACCESS_KEY_ID),
- E(ALICLOUD_SECRET_KEY) or E(ALICLOUD_SECRET_ACCESS_KEY),
- E(ALICLOUD_REGION) or E(ALICLOUD_REGION_ID),
- E(ALICLOUD_SECURITY_TOKEN),
- E(ALICLOUD_ECS_ROLE_NAME),
- E(ALICLOUD_SHARED_CREDENTIALS_FILE),
- E(ALICLOUD_PROFILE),
- E(ALICLOUD_ASSUME_ROLE_ARN),
- E(ALICLOUD_ASSUME_ROLE_SESSION_NAME),
- E(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION).
- - E(ALICLOUD_REGION) or E(ALICLOUD_REGION_ID) can be typically be used to specify the
- Alicloud region, when required, but this can also be configured in the footmark config file
-'''
+ - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence
+ E(ALICLOUD_ACCESS_KEY) or E(ALICLOUD_ACCESS_KEY_ID), E(ALICLOUD_SECRET_KEY) or E(ALICLOUD_SECRET_ACCESS_KEY), E(ALICLOUD_REGION)
+ or E(ALICLOUD_REGION_ID), E(ALICLOUD_SECURITY_TOKEN), E(ALICLOUD_ECS_ROLE_NAME), E(ALICLOUD_SHARED_CREDENTIALS_FILE),
+ E(ALICLOUD_PROFILE), E(ALICLOUD_ASSUME_ROLE_ARN), E(ALICLOUD_ASSUME_ROLE_SESSION_NAME), E(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION).
+ - E(ALICLOUD_REGION) or E(ALICLOUD_REGION_ID) can be typically be used to specify the Alicloud region, when required, but
+ this can also be configured in the footmark config file.
+"""
diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py
index 9b8488e0a5..2ab083eab2 100644
--- a/plugins/doc_fragments/attributes.py
+++ b/plugins/doc_fragments/attributes.py
@@ -11,22 +11,22 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options: {}
attributes:
- check_mode:
- description: Can run in C(check_mode) and return changed status prediction without modifying target.
- diff_mode:
- description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
-'''
+ check_mode:
+ description: Can run in C(check_mode) and return changed status prediction without modifying target.
+ diff_mode:
+ description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+"""
- PLATFORM = r'''
+ PLATFORM = r"""
options: {}
attributes:
- platform:
- description: Target OS/families that can be operated against.
- support: N/A
-'''
+ platform:
+ description: Target OS/families that can be operated against.
+ support: N/A
+"""
# Should be used together with the standard fragment
INFO_MODULE = r'''
@@ -42,23 +42,23 @@ attributes:
- This action does not modify state.
'''
- CONN = r'''
+ CONN = r"""
options: {}
attributes:
- become:
- description: Is usable alongside C(become) keywords.
- connection:
- description: Uses the target's configured connection information to execute code on it.
- delegation:
- description: Can be used in conjunction with C(delegate_to) and related keywords.
-'''
+ become:
+ description: Is usable alongside C(become) keywords.
+ connection:
+ description: Uses the target's configured connection information to execute code on it.
+ delegation:
+ description: Can be used in conjunction with C(delegate_to) and related keywords.
+"""
- FACTS = r'''
+ FACTS = r"""
options: {}
attributes:
- facts:
- description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
-'''
+ facts:
+ description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
+"""
# Should be used together with the standard fragment and the FACTS fragment
FACTS_MODULE = r'''
@@ -76,18 +76,18 @@ attributes:
support: full
'''
- FILES = r'''
+ FILES = r"""
options: {}
attributes:
- safe_file_operations:
- description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
-'''
+ safe_file_operations:
+ description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
+"""
- FLOW = r'''
+ FLOW = r"""
options: {}
attributes:
- action:
- description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
- async:
- description: Supports being used with the C(async) keyword.
-'''
+ action:
+ description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
+ async:
+ description: Supports being used with the C(async) keyword.
+"""
diff --git a/plugins/doc_fragments/auth_basic.py b/plugins/doc_fragments/auth_basic.py
index 77d127c629..438435a6a3 100644
--- a/plugins/doc_fragments/auth_basic.py
+++ b/plugins/doc_fragments/auth_basic.py
@@ -10,7 +10,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard files documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
api_url:
description:
@@ -29,4 +29,4 @@ options:
- Whether or not to validate SSL certs when supplying a HTTPS endpoint.
type: bool
default: true
-'''
+"""
diff --git a/plugins/doc_fragments/bitbucket.py b/plugins/doc_fragments/bitbucket.py
index 0a66ea0a68..e8b9ea4df8 100644
--- a/plugins/doc_fragments/bitbucket.py
+++ b/plugins/doc_fragments/bitbucket.py
@@ -11,7 +11,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
client_id:
description:
@@ -30,7 +30,7 @@ options:
- O(ignore:username) is an alias of O(user) since community.general 6.0.0. It was an alias of O(workspace) before.
type: str
version_added: 4.0.0
- aliases: [ username ]
+ aliases: [username]
password:
description:
- The App password.
@@ -41,4 +41,4 @@ notes:
- Bitbucket OAuth consumer key and secret can be obtained from Bitbucket profile -> Settings -> Access Management -> OAuth.
- Bitbucket App password can be created from Bitbucket profile -> Personal Settings -> App passwords.
- If both OAuth and Basic Auth credentials are passed, OAuth credentials take precedence.
-'''
+"""
diff --git a/plugins/doc_fragments/clc.py b/plugins/doc_fragments/clc.py
new file mode 100644
index 0000000000..e193033af9
--- /dev/null
+++ b/plugins/doc_fragments/clc.py
@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024, Alexei Znamensky
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+ # Standard documentation fragment
+ DOCUMENTATION = r"""
+options: {}
+requirements:
+ - requests >= 2.5.0
+ - clc-sdk
+notes:
+ - To use this module, it is required to set the below environment variables which enables access to the Centurylink Cloud.
+ - E(CLC_V2_API_USERNAME), the account login ID for the Centurylink Cloud.
+ - E(CLC_V2_API_PASSWORD), the account password for the Centurylink Cloud.
+ - Alternatively, the module accepts the API token and account alias. The API token can be generated using the CLC account
+ login and password using the HTTP API call @ U(https://api.ctl.io/v2/authentication/login).
+ - E(CLC_V2_API_TOKEN), the API token generated from U(https://api.ctl.io/v2/authentication/login).
+ - E(CLC_ACCT_ALIAS), the account alias associated with the Centurylink Cloud.
+ - Users can set E(CLC_V2_API_URL) to specify an endpoint for pointing to a different CLC environment.
+"""
diff --git a/plugins/doc_fragments/consul.py b/plugins/doc_fragments/consul.py
index d4cf119958..0703971a2e 100644
--- a/plugins/doc_fragments/consul.py
+++ b/plugins/doc_fragments/consul.py
@@ -15,7 +15,7 @@ class ModuleDocFragment:
options:
host:
description:
- - Host of the consul agent, defaults to V(localhost).
+ - Host of the Consul agent.
default: localhost
type: str
port:
@@ -25,18 +25,18 @@ options:
default: 8500
scheme:
description:
- - The protocol scheme on which the consul agent is running.
- Defaults to V(http) and can be set to V(https) for secure connections.
+ - The protocol scheme on which the Consul agent is running. Defaults to V(http) and can be set to V(https) for secure
+ connections.
default: http
type: str
validate_certs:
type: bool
description:
- - Whether to verify the TLS certificate of the consul agent.
+ - Whether to verify the TLS certificate of the Consul agent.
default: true
ca_path:
description:
- - The CA bundle to use for https connections
+ - The CA bundle to use for https connections.
type: str
"""
diff --git a/plugins/doc_fragments/dimensiondata.py b/plugins/doc_fragments/dimensiondata.py
index f4d6244540..ece97addf0 100644
--- a/plugins/doc_fragments/dimensiondata.py
+++ b/plugins/doc_fragments/dimensiondata.py
@@ -14,8 +14,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Dimension Data doc fragment
- DOCUMENTATION = r'''
-
+ DOCUMENTATION = r"""
options:
region:
description:
@@ -48,4 +47,4 @@ options:
- This should only be used on private instances of the CloudControl API that use self-signed certificates.
type: bool
default: true
-'''
+"""
diff --git a/plugins/doc_fragments/dimensiondata_wait.py b/plugins/doc_fragments/dimensiondata_wait.py
index 051d8ca1d3..d3ab3b9783 100644
--- a/plugins/doc_fragments/dimensiondata_wait.py
+++ b/plugins/doc_fragments/dimensiondata_wait.py
@@ -14,8 +14,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Dimension Data ("wait-for-completion" parameters) doc fragment
- DOCUMENTATION = r'''
-
+ DOCUMENTATION = r"""
options:
wait:
description:
@@ -34,4 +33,4 @@ options:
- Only applicable if O(wait=true).
type: int
default: 2
-'''
+"""
diff --git a/plugins/doc_fragments/django.py b/plugins/doc_fragments/django.py
index f89ec91448..3dcdb40171 100644
--- a/plugins/doc_fragments/django.py
+++ b/plugins/doc_fragments/django.py
@@ -8,7 +8,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
venv:
description:
@@ -43,20 +43,19 @@ options:
notes:
- The C(django-admin) command is always executed using the C(C) locale, and the option C(--no-color) is always passed.
-
seealso:
- name: django-admin and manage.py in official Django documentation
description: >-
- Refer to this documentation for the builtin commands and options of C(django-admin).
- Please make sure that you select the right version of Django in the version selector on that page.
+ Refer to this documentation for the builtin commands and options of C(django-admin). Please make sure that you select
+ the right version of Django in the version selector on that page.
link: https://docs.djangoproject.com/en/5.0/ref/django-admin/
-'''
+"""
- DATABASE = r'''
+ DATABASE = r"""
options:
database:
description:
- Specify the database to be used.
type: str
default: default
-'''
+"""
diff --git a/plugins/doc_fragments/emc.py b/plugins/doc_fragments/emc.py
index d685c510d2..7c62285a72 100644
--- a/plugins/doc_fragments/emc.py
+++ b/plugins/doc_fragments/emc.py
@@ -10,15 +10,6 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = r'''
-options:
- - See respective platform section for more details
-requirements:
- - See respective platform section for more details
-notes:
- - Ansible modules are available for EMC VNX.
-'''
-
# Documentation fragment for VNX (emc_vnx)
EMC_VNX = r'''
options:
diff --git a/plugins/doc_fragments/gitlab.py b/plugins/doc_fragments/gitlab.py
index c6434c0ced..48182ed35c 100644
--- a/plugins/doc_fragments/gitlab.py
+++ b/plugins/doc_fragments/gitlab.py
@@ -10,7 +10,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard files documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
requirements:
- requests (Python library U(https://pypi.org/project/requests/))
@@ -34,4 +34,4 @@ options:
- The CA certificates bundle to use to verify GitLab server certificate.
type: str
version_added: 8.1.0
-'''
+"""
diff --git a/plugins/doc_fragments/hpe3par.py b/plugins/doc_fragments/hpe3par.py
index 606a2502a6..dadd6e78b3 100644
--- a/plugins/doc_fragments/hpe3par.py
+++ b/plugins/doc_fragments/hpe3par.py
@@ -10,26 +10,26 @@ __metaclass__ = type
class ModuleDocFragment(object):
# HPE 3PAR doc fragment
- DOCUMENTATION = '''
+ DOCUMENTATION = r"""
options:
- storage_system_ip:
- description:
- - The storage system IP address.
- type: str
- required: true
- storage_system_password:
- description:
- - The storage system password.
- type: str
- required: true
- storage_system_username:
- description:
- - The storage system user name.
- type: str
- required: true
+ storage_system_ip:
+ description:
+ - The storage system IP address.
+ type: str
+ required: true
+ storage_system_password:
+ description:
+ - The storage system password.
+ type: str
+ required: true
+ storage_system_username:
+ description:
+ - The storage system user name.
+ type: str
+ required: true
requirements:
- hpe3par_sdk >= 1.0.2. Install using C(pip install hpe3par_sdk).
- WSAPI service should be enabled on the 3PAR storage array.
notes:
- '''
+"""
diff --git a/plugins/doc_fragments/hwc.py b/plugins/doc_fragments/hwc.py
index 8b9ae92b8f..3d478beb59 100644
--- a/plugins/doc_fragments/hwc.py
+++ b/plugins/doc_fragments/hwc.py
@@ -10,56 +10,50 @@ __metaclass__ = type
class ModuleDocFragment(object):
# HWC doc fragment.
- DOCUMENTATION = '''
+ DOCUMENTATION = r"""
options:
- identity_endpoint:
- description:
- - The Identity authentication URL.
- type: str
- required: true
- user:
- description:
- - The user name to login with.
- - Currently only user names are supported, and not user IDs.
- type: str
- required: true
- password:
- description:
- - The password to login with.
- type: str
- required: true
- domain:
- description:
- - The name of the Domain to scope to (Identity v3).
- - Currently only domain names are supported, and not domain IDs.
- type: str
- required: true
- project:
- description:
- - The name of the Tenant (Identity v2) or Project (Identity v3).
- - Currently only project names are supported, and not project IDs.
- type: str
- required: true
- region:
- description:
- - The region to which the project belongs.
- type: str
- id:
- description:
- - The ID of resource to be managed.
- type: str
+ identity_endpoint:
+ description:
+ - The Identity authentication URL.
+ type: str
+ required: true
+ user:
+ description:
+ - The user name to login with.
+ - Currently only user names are supported, and not user IDs.
+ type: str
+ required: true
+ password:
+ description:
+ - The password to login with.
+ type: str
+ required: true
+ domain:
+ description:
+ - The name of the Domain to scope to (Identity v3).
+ - Currently only domain names are supported, and not domain IDs.
+ type: str
+ required: true
+ project:
+ description:
+ - The name of the Tenant (Identity v2) or Project (Identity v3).
+ - Currently only project names are supported, and not project IDs.
+ type: str
+ required: true
+ region:
+ description:
+ - The region to which the project belongs.
+ type: str
+ id:
+ description:
+ - The ID of resource to be managed.
+ type: str
notes:
- - For authentication, you can set identity_endpoint using the
- E(ANSIBLE_HWC_IDENTITY_ENDPOINT) environment variable.
- - For authentication, you can set user using the
- E(ANSIBLE_HWC_USER) environment variable.
- - For authentication, you can set password using the E(ANSIBLE_HWC_PASSWORD) environment
- variable.
- - For authentication, you can set domain using the E(ANSIBLE_HWC_DOMAIN) environment
- variable.
- - For authentication, you can set project using the E(ANSIBLE_HWC_PROJECT) environment
- variable.
+ - For authentication, you can set identity_endpoint using the E(ANSIBLE_HWC_IDENTITY_ENDPOINT) environment variable.
+ - For authentication, you can set user using the E(ANSIBLE_HWC_USER) environment variable.
+ - For authentication, you can set password using the E(ANSIBLE_HWC_PASSWORD) environment variable.
+ - For authentication, you can set domain using the E(ANSIBLE_HWC_DOMAIN) environment variable.
+ - For authentication, you can set project using the E(ANSIBLE_HWC_PROJECT) environment variable.
- For authentication, you can set region using the E(ANSIBLE_HWC_REGION) environment variable.
- - Environment variables values will only be used if the playbook values are
- not set.
-'''
+ - Environment variables values will only be used if the playbook values are not set.
+"""
diff --git a/plugins/doc_fragments/ibm_storage.py b/plugins/doc_fragments/ibm_storage.py
index 7783d9ca56..ca48ef2c4d 100644
--- a/plugins/doc_fragments/ibm_storage.py
+++ b/plugins/doc_fragments/ibm_storage.py
@@ -12,26 +12,25 @@ __metaclass__ = type
class ModuleDocFragment(object):
# ibm_storage documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
- username:
- description:
- - Management user on the spectrum accelerate storage system.
- type: str
- required: true
- password:
- description:
- - Password for username on the spectrum accelerate storage system.
- type: str
- required: true
- endpoints:
- description:
- - The hostname or management IP of Spectrum Accelerate storage system.
- type: str
- required: true
+ username:
+ description:
+ - Management user on the Spectrum Accelerate storage system.
+ type: str
+ required: true
+ password:
+ description:
+ - Password for username on the Spectrum Accelerate storage system.
+ type: str
+ required: true
+ endpoints:
+ description:
+ - The hostname or management IP of Spectrum Accelerate storage system.
+ type: str
+ required: true
notes:
- - This module requires pyxcli python library.
- Use C(pip install pyxcli) in order to get pyxcli.
+ - This module requires pyxcli python library. Use C(pip install pyxcli) in order to get pyxcli.
requirements:
- pyxcli
-'''
+"""
diff --git a/plugins/doc_fragments/influxdb.py b/plugins/doc_fragments/influxdb.py
index fc0ca02ac7..9cf47d340a 100644
--- a/plugins/doc_fragments/influxdb.py
+++ b/plugins/doc_fragments/influxdb.py
@@ -11,72 +11,72 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Parameters for influxdb modules
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
hostname:
description:
- - The hostname or IP address on which InfluxDB server is listening.
+ - The hostname or IP address on which InfluxDB server is listening.
type: str
default: localhost
username:
description:
- - Username that will be used to authenticate against InfluxDB server.
+ - Username that will be used to authenticate against InfluxDB server.
type: str
default: root
- aliases: [ login_username ]
+ aliases: [login_username]
password:
description:
- - Password that will be used to authenticate against InfluxDB server.
+ - Password that will be used to authenticate against InfluxDB server.
type: str
default: root
- aliases: [ login_password ]
+ aliases: [login_password]
port:
description:
- - The port on which InfluxDB server is listening.
+ - The port on which InfluxDB server is listening.
type: int
default: 8086
path:
description:
- - The path on which InfluxDB server is accessible.
- - Only available when using python-influxdb >= 5.1.0.
+ - The path on which InfluxDB server is accessible.
+ - Only available when using python-influxdb >= 5.1.0.
type: str
default: ''
version_added: '0.2.0'
validate_certs:
description:
- - If set to V(false), the SSL certificates will not be validated.
- - This should only set to V(false) used on personally controlled sites using self-signed certificates.
+ - If set to V(false), the SSL certificates will not be validated.
+ - This should only set to V(false) used on personally controlled sites using self-signed certificates.
type: bool
default: true
ssl:
description:
- - Use https instead of http to connect to InfluxDB server.
+ - Use https instead of http to connect to InfluxDB server.
type: bool
default: false
timeout:
description:
- - Number of seconds Requests will wait for client to establish a connection.
+ - Number of seconds Requests will wait for client to establish a connection.
type: int
retries:
description:
- - Number of retries client will try before aborting.
- - V(0) indicates try until success.
- - Only available when using python-influxdb >= 4.1.0.
+ - Number of retries client will try before aborting.
+ - V(0) indicates try until success.
+ - Only available when using C(python-influxdb) >= 4.1.0.
type: int
default: 3
use_udp:
description:
- - Use UDP to connect to InfluxDB server.
+ - Use UDP to connect to InfluxDB server.
type: bool
default: false
udp_port:
description:
- - UDP port to connect to InfluxDB server.
+ - UDP port to connect to InfluxDB server.
type: int
default: 4444
proxies:
description:
- - HTTP(S) proxy to use for Requests to connect to InfluxDB server.
+ - HTTP(S) proxy to use for Requests to connect to InfluxDB server.
type: dict
default: {}
-'''
+"""
diff --git a/plugins/doc_fragments/ipa.py b/plugins/doc_fragments/ipa.py
index 7e091a94aa..0edb947aa5 100644
--- a/plugins/doc_fragments/ipa.py
+++ b/plugins/doc_fragments/ipa.py
@@ -11,61 +11,66 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Parameters for FreeIPA/IPA modules
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
ipa_port:
description:
- - Port of FreeIPA / IPA server.
- - If the value is not specified in the task, the value of environment variable E(IPA_PORT) will be used instead.
- - If both the environment variable E(IPA_PORT) and the value are not specified in the task, then default value is set.
+ - Port of FreeIPA / IPA server.
+ - If the value is not specified in the task, the value of environment variable E(IPA_PORT) will be used instead.
+ - If both the environment variable E(IPA_PORT) and the value are not specified in the task, then default value is set.
type: int
default: 443
ipa_host:
description:
- - IP or hostname of IPA server.
- - If the value is not specified in the task, the value of environment variable E(IPA_HOST) will be used instead.
- - If both the environment variable E(IPA_HOST) and the value are not specified in the task, then DNS will be used to try to discover the FreeIPA server.
- - The relevant entry needed in FreeIPA is the C(ipa-ca) entry.
- - If neither the DNS entry, nor the environment E(IPA_HOST), nor the value are available in the task, then the default value will be used.
+ - IP or hostname of IPA server.
+ - If the value is not specified in the task, the value of environment variable E(IPA_HOST) will be used instead.
+ - If both the environment variable E(IPA_HOST) and the value are not specified in the task, then DNS will be used to
+ try to discover the FreeIPA server.
+ - The relevant entry needed in FreeIPA is the C(ipa-ca) entry.
+ - If neither the DNS entry, nor the environment E(IPA_HOST), nor the value are available in the task, then the default
+ value will be used.
type: str
default: ipa.example.com
ipa_user:
description:
- - Administrative account used on IPA server.
- - If the value is not specified in the task, the value of environment variable E(IPA_USER) will be used instead.
- - If both the environment variable E(IPA_USER) and the value are not specified in the task, then default value is set.
+ - Administrative account used on IPA server.
+ - If the value is not specified in the task, the value of environment variable E(IPA_USER) will be used instead.
+ - If both the environment variable E(IPA_USER) and the value are not specified in the task, then default value is set.
type: str
default: admin
ipa_pass:
description:
- - Password of administrative user.
- - If the value is not specified in the task, the value of environment variable E(IPA_PASS) will be used instead.
- - Note that if the C(urllib_gssapi) library is available, it is possible to use GSSAPI to authenticate to FreeIPA.
- - If the environment variable E(KRB5CCNAME) is available, the module will use this kerberos credentials cache to authenticate to the FreeIPA server.
- - If the environment variable E(KRB5_CLIENT_KTNAME) is available, and E(KRB5CCNAME) is not; the module will use this kerberos keytab to authenticate.
- - If GSSAPI is not available, the usage of O(ipa_pass) is required.
+ - Password of administrative user.
+ - If the value is not specified in the task, the value of environment variable E(IPA_PASS) will be used instead.
+ - Note that if the C(urllib_gssapi) library is available, it is possible to use GSSAPI to authenticate to FreeIPA.
+ - If the environment variable E(KRB5CCNAME) is available, the module will use this kerberos credentials cache to authenticate
+ to the FreeIPA server.
+ - If the environment variable E(KRB5_CLIENT_KTNAME) is available, and E(KRB5CCNAME) is not; the module will use this
+ kerberos keytab to authenticate.
+ - If GSSAPI is not available, the usage of O(ipa_pass) is required.
type: str
ipa_prot:
description:
- - Protocol used by IPA server.
- - If the value is not specified in the task, the value of environment variable E(IPA_PROT) will be used instead.
- - If both the environment variable E(IPA_PROT) and the value are not specified in the task, then default value is set.
+ - Protocol used by IPA server.
+ - If the value is not specified in the task, the value of environment variable E(IPA_PROT) will be used instead.
+ - If both the environment variable E(IPA_PROT) and the value are not specified in the task, then default value is set.
type: str
- choices: [ http, https ]
+ choices: [http, https]
default: https
validate_certs:
description:
- - This only applies if O(ipa_prot) is V(https).
- - If set to V(false), the SSL certificates will not be validated.
- - This should only set to V(false) used on personally controlled sites using self-signed certificates.
+ - This only applies if O(ipa_prot) is V(https).
+ - If set to V(false), the SSL certificates will not be validated.
+ - This should only set to V(false) used on personally controlled sites using self-signed certificates.
type: bool
default: true
ipa_timeout:
description:
- - Specifies idle timeout (in seconds) for the connection.
- - For bulk operations, you may want to increase this in order to avoid timeout from IPA server.
- - If the value is not specified in the task, the value of environment variable E(IPA_TIMEOUT) will be used instead.
- - If both the environment variable E(IPA_TIMEOUT) and the value are not specified in the task, then default value is set.
+ - Specifies idle timeout (in seconds) for the connection.
+ - For bulk operations, you may want to increase this in order to avoid timeout from IPA server.
+ - If the value is not specified in the task, the value of environment variable E(IPA_TIMEOUT) will be used instead.
+ - If both the environment variable E(IPA_TIMEOUT) and the value are not specified in the task, then default value is
+ set.
type: int
default: 10
-'''
+"""
diff --git a/plugins/doc_fragments/keycloak.py b/plugins/doc_fragments/keycloak.py
index 9b21ce52c9..75c458d5fc 100644
--- a/plugins/doc_fragments/keycloak.py
+++ b/plugins/doc_fragments/keycloak.py
@@ -11,69 +11,85 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
- auth_keycloak_url:
- description:
- - URL to the Keycloak instance.
- type: str
- required: true
- aliases:
- - url
+ auth_keycloak_url:
+ description:
+ - URL to the Keycloak instance.
+ type: str
+ required: true
+ aliases:
+ - url
- auth_client_id:
- description:
- - OpenID Connect C(client_id) to authenticate to the API with.
- type: str
- default: admin-cli
+ auth_client_id:
+ description:
+ - OpenID Connect C(client_id) to authenticate to the API with.
+ type: str
+ default: admin-cli
- auth_realm:
- description:
- - Keycloak realm name to authenticate to for API access.
- type: str
+ auth_realm:
+ description:
+ - Keycloak realm name to authenticate to for API access.
+ type: str
- auth_client_secret:
- description:
- - Client Secret to use in conjunction with O(auth_client_id) (if required).
- type: str
+ auth_client_secret:
+ description:
+ - Client Secret to use in conjunction with O(auth_client_id) (if required).
+ type: str
- auth_username:
- description:
- - Username to authenticate for API access with.
- type: str
- aliases:
- - username
+ auth_username:
+ description:
+ - Username to authenticate for API access with.
+ type: str
+ aliases:
+ - username
- auth_password:
- description:
- - Password to authenticate for API access with.
- type: str
- aliases:
- - password
+ auth_password:
+ description:
+ - Password to authenticate for API access with.
+ type: str
+ aliases:
+ - password
- token:
- description:
- - Authentication token for Keycloak API.
- type: str
- version_added: 3.0.0
+ token:
+ description:
+ - Authentication token for Keycloak API.
+ type: str
+ version_added: 3.0.0
- validate_certs:
- description:
- - Verify TLS certificates (do not disable this in production).
- type: bool
- default: true
+ refresh_token:
+ description:
+ - Authentication refresh token for Keycloak API.
+ type: str
+ version_added: 10.3.0
- connection_timeout:
- description:
- - Controls the HTTP connections timeout period (in seconds) to Keycloak API.
- type: int
- default: 10
- version_added: 4.5.0
+ validate_certs:
+ description:
+ - Verify TLS certificates (do not disable this in production).
+ type: bool
+ default: true
- http_agent:
- description:
- - Configures the HTTP User-Agent header.
- type: str
- default: Ansible
- version_added: 5.4.0
-'''
+ connection_timeout:
+ description:
+ - Controls the HTTP connections timeout period (in seconds) to Keycloak API.
+ type: int
+ default: 10
+ version_added: 4.5.0
+
+ http_agent:
+ description:
+ - Configures the HTTP User-Agent header.
+ type: str
+ default: Ansible
+ version_added: 5.4.0
+"""
+
+ ACTIONGROUP_KEYCLOAK = r"""
+options: {}
+attributes:
+ action_group:
+ description: Use C(group/community.general.keycloak) in C(module_defaults) to set defaults for this module.
+ support: full
+ membership:
+ - community.general.keycloak
+"""
diff --git a/plugins/doc_fragments/ldap.py b/plugins/doc_fragments/ldap.py
index e11ab065d8..4dd5fd097f 100644
--- a/plugins/doc_fragments/ldap.py
+++ b/plugins/doc_fragments/ldap.py
@@ -12,12 +12,17 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard LDAP documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
+notes:
+ - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well
+ with the default Ubuntu install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root
+ to modify the server configuration. If you need to use a simple bind to access your server, pass the credentials in O(bind_dn)
+ and O(bind_pw).
options:
bind_dn:
description:
- - A DN to bind with. If this is omitted, we'll try a SASL bind with the EXTERNAL mechanism as default.
- - If this is blank, we'll use an anonymous bind.
+ - A DN to bind with. Try to use a SASL bind with the EXTERNAL mechanism as default when this parameter is omitted.
+ - Use an anonymous bind if the parameter is blank.
type: str
bind_pw:
description:
@@ -57,7 +62,8 @@ options:
version_added: 2.0.0
server_uri:
description:
- - The O(server_uri) parameter may be a comma- or whitespace-separated list of URIs containing only the schema, the host, and the port fields.
+ - The O(server_uri) parameter may be a comma- or whitespace-separated list of URIs containing only the schema, the host,
+ and the port fields.
- The default value lets the underlying LDAP client library look for a UNIX domain socket in its default location.
- Note that when using multiple URIs you cannot determine to which URI your client gets connected.
- For URIs containing additional fields, particularly when using commas, behavior is undefined.
@@ -65,7 +71,7 @@ options:
default: ldapi:///
start_tls:
description:
- - If true, we'll use the START_TLS LDAP extension.
+ - Use the START_TLS LDAP extension if set to V(true).
type: bool
default: false
validate_certs:
@@ -91,4 +97,4 @@ options:
choices: ['enable', 'auto', 'disable']
default: auto
version_added: "6.4.0"
-'''
+"""
diff --git a/plugins/doc_fragments/lxca_common.py b/plugins/doc_fragments/lxca_common.py
index eed6727c2a..85cdeb0f22 100644
--- a/plugins/doc_fragments/lxca_common.py
+++ b/plugins/doc_fragments/lxca_common.py
@@ -10,7 +10,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard Pylxca documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
author:
- Naval Patel (@navalkp)
- Prashant Bhosale (@prabhosa)
@@ -18,19 +18,19 @@ author:
options:
login_user:
description:
- - The username for use in HTTP basic authentication.
+ - The username for use in HTTP basic authentication.
type: str
required: true
login_password:
description:
- - The password for use in HTTP basic authentication.
+ - The password for use in HTTP basic authentication.
type: str
required: true
auth_url:
description:
- - lxca HTTPS full web address.
+ - Lxca HTTPS full web address.
type: str
required: true
@@ -40,4 +40,4 @@ requirements:
notes:
- Additional detail about pylxca can be found at U(https://github.com/lenovo/pylxca).
- Playbooks using these modules can be found at U(https://github.com/lenovo/ansible.lenovo-lxca).
-'''
+"""
diff --git a/plugins/doc_fragments/manageiq.py b/plugins/doc_fragments/manageiq.py
index 8afc183a5c..4b9ea1ff52 100644
--- a/plugins/doc_fragments/manageiq.py
+++ b/plugins/doc_fragments/manageiq.py
@@ -11,7 +11,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard ManageIQ documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
manageiq_connection:
description:
@@ -34,20 +34,21 @@ options:
type: str
token:
description:
- - ManageIQ token. E(MIQ_TOKEN) environment variable if set. Otherwise, required if no username or password is passed in.
+ - ManageIQ token. E(MIQ_TOKEN) environment variable if set. Otherwise, required if no username or password is passed
+ in.
type: str
validate_certs:
description:
- Whether SSL certificates should be verified for HTTPS requests.
type: bool
default: true
- aliases: [ verify_ssl ]
+ aliases: [verify_ssl]
ca_cert:
description:
- The path to a CA bundle file or directory with certificates.
type: str
- aliases: [ ca_bundle_path ]
+ aliases: [ca_bundle_path]
requirements:
- 'manageiq-client U(https://github.com/ManageIQ/manageiq-api-client-python/)'
-'''
+"""
diff --git a/plugins/doc_fragments/nomad.py b/plugins/doc_fragments/nomad.py
index 1571c211c9..68787e835c 100644
--- a/plugins/doc_fragments/nomad.py
+++ b/plugins/doc_fragments/nomad.py
@@ -11,48 +11,48 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard files documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
- host:
- description:
- - FQDN of Nomad server.
- required: true
- type: str
- port:
- description:
- - Port of Nomad server.
- type: int
- default: 4646
- version_added: 8.0.0
- use_ssl:
- description:
- - Use TLS/SSL connection.
- type: bool
- default: true
- timeout:
- description:
- - Timeout (in seconds) for the request to Nomad.
- type: int
- default: 5
- validate_certs:
- description:
- - Enable TLS/SSL certificate validation.
- type: bool
- default: true
- client_cert:
- description:
- - Path of certificate for TLS/SSL.
- type: path
- client_key:
- description:
- - Path of certificate's private key for TLS/SSL.
- type: path
- namespace:
- description:
- - Namespace for Nomad.
- type: str
- token:
- description:
- - ACL token for authentication.
- type: str
-'''
+ host:
+ description:
+ - FQDN of Nomad server.
+ required: true
+ type: str
+ port:
+ description:
+ - Port of Nomad server.
+ type: int
+ default: 4646
+ version_added: 8.0.0
+ use_ssl:
+ description:
+ - Use TLS/SSL connection.
+ type: bool
+ default: true
+ timeout:
+ description:
+ - Timeout (in seconds) for the request to Nomad.
+ type: int
+ default: 5
+ validate_certs:
+ description:
+ - Enable TLS/SSL certificate validation.
+ type: bool
+ default: true
+ client_cert:
+ description:
+ - Path of certificate for TLS/SSL.
+ type: path
+ client_key:
+ description:
+ - Path of certificate's private key for TLS/SSL.
+ type: path
+ namespace:
+ description:
+ - Namespace for Nomad.
+ type: str
+ token:
+ description:
+ - ACL token for authentication.
+ type: str
+"""
diff --git a/plugins/doc_fragments/onepassword.py b/plugins/doc_fragments/onepassword.py
index 4035f81796..a67c9e4dc1 100644
--- a/plugins/doc_fragments/onepassword.py
+++ b/plugins/doc_fragments/onepassword.py
@@ -9,7 +9,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
requirements:
- See U(https://support.1password.com/command-line/)
options:
@@ -18,7 +18,8 @@ options:
aliases: ['vault_password']
type: str
section:
- description: Item section containing the field to retrieve (case-insensitive). If absent will return first match from any section.
+ description: Item section containing the field to retrieve (case-insensitive). If absent will return first match from
+ any section.
domain:
description: Domain of 1Password.
default: '1password.com'
@@ -55,25 +56,25 @@ options:
env:
- name: OP_CONNECT_TOKEN
version_added: 8.1.0
-'''
+"""
- LOOKUP = r'''
+ LOOKUP = r"""
options:
service_account_token:
env:
- name: OP_SERVICE_ACCOUNT_TOKEN
version_added: 8.2.0
notes:
- - This lookup will use an existing 1Password session if one exists. If not, and you have already
- performed an initial sign in (meaning C(~/.op/config), C(~/.config/op/config) or C(~/.config/.op/config) exists), then only the
- O(master_password) is required. You may optionally specify O(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op).
+ - This lookup will use an existing 1Password session if one exists. If not, and you have already performed an initial sign
+ in (meaning C(~/.op/config), C(~/.config/op/config) or C(~/.config/.op/config) exists), then only the O(master_password)
+ is required. You may optionally specify O(subdomain) in this scenario, otherwise the last used subdomain will be used
+ by C(op).
- This lookup can perform an initial login by providing O(subdomain), O(username), O(secret_key), and O(master_password).
- Can target a specific account by providing the O(account_id).
- - Due to the B(very) sensitive nature of these credentials, it is B(highly) recommended that you only pass in the minimal credentials
- needed at any given time. Also, store these credentials in an Ansible Vault using a key that is equal to or greater in strength
- to the 1Password master password.
- - This lookup stores potentially sensitive data from 1Password as Ansible facts.
- Facts are subject to caching if enabled, which means this data could be stored in clear text
- on disk or in a database.
+ - Due to the B(very) sensitive nature of these credentials, it is B(highly) recommended that you only pass in the minimal
+ credentials needed at any given time. Also, store these credentials in an Ansible Vault using a key that is equal to or
+ greater in strength to the 1Password master password.
+ - This lookup stores potentially sensitive data from 1Password as Ansible facts. Facts are subject to caching if enabled,
+ which means this data could be stored in clear text on disk or in a database.
- Tested with C(op) version 2.7.2.
-'''
+"""
diff --git a/plugins/doc_fragments/oneview.py b/plugins/doc_fragments/oneview.py
index a88226d7d7..3caabe4512 100644
--- a/plugins/doc_fragments/oneview.py
+++ b/plugins/doc_fragments/oneview.py
@@ -11,70 +11,67 @@ __metaclass__ = type
class ModuleDocFragment(object):
# OneView doc fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
- config:
- description:
- - Path to a JSON configuration file containing the OneView client configuration.
- The configuration file is optional and when used should be present in the host running the ansible commands.
- If the file path is not provided, the configuration will be loaded from environment variables.
- For links to example configuration files or how to use the environment variables verify the notes section.
- type: path
- api_version:
- description:
- - OneView API Version.
- type: int
- image_streamer_hostname:
- description:
- - IP address or hostname for the HPE Image Streamer REST API.
- type: str
- hostname:
- description:
- - IP address or hostname for the appliance.
- type: str
- username:
- description:
- - Username for API authentication.
- type: str
- password:
- description:
- - Password for API authentication.
- type: str
+ config:
+ description:
+ - Path to a JSON configuration file containing the OneView client configuration. The configuration file is optional
+ and when used should be present in the host running the ansible commands. If the file path is not provided, the configuration
+ will be loaded from environment variables. For links to example configuration files or how to use the environment
+ variables verify the notes section.
+ type: path
+ api_version:
+ description:
+ - OneView API Version.
+ type: int
+ image_streamer_hostname:
+ description:
+ - IP address or hostname for the HPE Image Streamer REST API.
+ type: str
+ hostname:
+ description:
+ - IP address or hostname for the appliance.
+ type: str
+ username:
+ description:
+ - Username for API authentication.
+ type: str
+ password:
+ description:
+ - Password for API authentication.
+ type: str
requirements:
- Python >= 2.7.9
notes:
- - "A sample configuration file for the config parameter can be found at:
- U(https://github.com/HewlettPackard/oneview-ansible/blob/master/examples/oneview_config-rename.json)"
- - "Check how to use environment variables for configuration at:
- U(https://github.com/HewlettPackard/oneview-ansible#environment-variables)"
- - "Additional Playbooks for the HPE OneView Ansible modules can be found at:
- U(https://github.com/HewlettPackard/oneview-ansible/tree/master/examples)"
- - "The OneView API version used will directly affect returned and expected fields in resources.
- Information on setting the desired API version and can be found at:
- U(https://github.com/HewlettPackard/oneview-ansible#setting-your-oneview-version)"
- '''
+ - 'A sample configuration file for the config parameter can be found at:
+ U(https://github.com/HewlettPackard/oneview-ansible/blob/master/examples/oneview_config-rename.json).'
+ - 'Check how to use environment variables for configuration at: U(https://github.com/HewlettPackard/oneview-ansible#environment-variables).'
+ - 'Additional Playbooks for the HPE OneView Ansible modules can be found at: U(https://github.com/HewlettPackard/oneview-ansible/tree/master/examples).'
+ - 'The OneView API version used will directly affect returned and expected fields in resources. Information on setting the
+ desired API version and can be found at: U(https://github.com/HewlettPackard/oneview-ansible#setting-your-oneview-version).'
+"""
- VALIDATEETAG = r'''
+ VALIDATEETAG = r"""
options:
- validate_etag:
- description:
- - When the ETag Validation is enabled, the request will be conditionally processed only if the current ETag
- for the resource matches the ETag provided in the data.
- type: bool
- default: true
-'''
+ validate_etag:
+ description:
+ - When the ETag Validation is enabled, the request will be conditionally processed only if the current ETag for the
+ resource matches the ETag provided in the data.
+ type: bool
+ default: true
+"""
- FACTSPARAMS = r'''
+ FACTSPARAMS = r"""
options:
- params:
- description:
- - List of parameters to delimit, filter and sort the list of resources.
- - "Parameter keys allowed are:"
- - "C(start): The first item to return, using 0-based indexing."
- - "C(count): The number of resources to return."
- - "C(filter): A general filter/query string to narrow the list of items returned."
- - "C(sort): The sort order of the returned data set."
- type: dict
-'''
+ params:
+ description:
+ - List of parameters to delimit, filter and sort the list of resources.
+ - 'Parameter keys allowed are:'
+ - 'V(start): The first item to return, using 0-based indexing.'
+ - 'V(count): The number of resources to return.'
+ - 'V(filter): A general filter/query string to narrow the list of items returned.'
+ - 'V(sort): The sort order of the returned data set.'
+ type: dict
+"""
diff --git a/plugins/doc_fragments/online.py b/plugins/doc_fragments/online.py
index 37e39cfa26..0149872b0a 100644
--- a/plugins/doc_fragments/online.py
+++ b/plugins/doc_fragments/online.py
@@ -10,26 +10,26 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
api_token:
description:
- Online OAuth token.
type: str
required: true
- aliases: [ oauth_token ]
+ aliases: [oauth_token]
api_url:
description:
- Online API URL.
type: str
default: 'https://api.online.net'
- aliases: [ base_url ]
+ aliases: [base_url]
api_timeout:
description:
- HTTP timeout to Online API in seconds.
type: int
default: 30
- aliases: [ timeout ]
+ aliases: [timeout]
validate_certs:
description:
- Validate SSL certs of the Online API.
@@ -37,9 +37,7 @@ options:
default: true
notes:
- Also see the API documentation on U(https://console.online.net/en/api/).
- - If O(api_token) is not set within the module, the following
- environment variables can be used in decreasing order of precedence
+ - If O(api_token) is not set within the module, the following environment variables can be used in decreasing order of precedence
E(ONLINE_TOKEN), E(ONLINE_API_KEY), E(ONLINE_OAUTH_TOKEN), E(ONLINE_API_TOKEN).
- - If one wants to use a different O(api_url) one can also set the E(ONLINE_API_URL)
- environment variable.
-'''
+ - If one wants to use a different O(api_url) one can also set the E(ONLINE_API_URL) environment variable.
+"""
diff --git a/plugins/doc_fragments/opennebula.py b/plugins/doc_fragments/opennebula.py
index 567faf1a77..381f52c272 100644
--- a/plugins/doc_fragments/opennebula.py
+++ b/plugins/doc_fragments/opennebula.py
@@ -10,36 +10,36 @@ __metaclass__ = type
class ModuleDocFragment(object):
# OpenNebula common documentation
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
- api_url:
- description:
- - The ENDPOINT URL of the XMLRPC server.
- - If not specified then the value of the E(ONE_URL) environment variable, if any, is used.
- type: str
- aliases:
- - api_endpoint
- api_username:
- description:
- - The name of the user for XMLRPC authentication.
- - If not specified then the value of the E(ONE_USERNAME) environment variable, if any, is used.
- type: str
- api_password:
- description:
- - The password or token for XMLRPC authentication.
- - If not specified then the value of the E(ONE_PASSWORD) environment variable, if any, is used.
- type: str
- aliases:
- - api_token
- validate_certs:
- description:
- - Whether to validate the TLS/SSL certificates or not.
- - This parameter is ignored if E(PYTHONHTTPSVERIFY) environment variable is used.
- type: bool
- default: true
- wait_timeout:
- description:
- - Time to wait for the desired state to be reached before timeout, in seconds.
- type: int
- default: 300
-'''
+ api_url:
+ description:
+ - The ENDPOINT URL of the XMLRPC server.
+ - If not specified then the value of the E(ONE_URL) environment variable, if any, is used.
+ type: str
+ aliases:
+ - api_endpoint
+ api_username:
+ description:
+ - The name of the user for XMLRPC authentication.
+ - If not specified then the value of the E(ONE_USERNAME) environment variable, if any, is used.
+ type: str
+ api_password:
+ description:
+ - The password or token for XMLRPC authentication.
+ - If not specified then the value of the E(ONE_PASSWORD) environment variable, if any, is used.
+ type: str
+ aliases:
+ - api_token
+ validate_certs:
+ description:
+ - Whether to validate the TLS/SSL certificates or not.
+ - This parameter is ignored if E(PYTHONHTTPSVERIFY) environment variable is used.
+ type: bool
+ default: true
+ wait_timeout:
+ description:
+ - Time to wait for the desired state to be reached before timeout, in seconds.
+ type: int
+ default: 300
+"""
diff --git a/plugins/doc_fragments/openswitch.py b/plugins/doc_fragments/openswitch.py
index a203a3b409..f0e9e87c3d 100644
--- a/plugins/doc_fragments/openswitch.py
+++ b/plugins/doc_fragments/openswitch.py
@@ -11,75 +11,62 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard files documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
host:
description:
- - Specifies the DNS host name or address for connecting to the remote
- device over the specified transport. The value of host is used as
- the destination address for the transport. Note this argument
- does not affect the SSH argument.
+ - Specifies the DNS host name or address for connecting to the remote device over the specified transport. The value
+ of host is used as the destination address for the transport. Note this argument does not affect the SSH argument.
type: str
port:
description:
- - Specifies the port to use when building the connection to the remote
- device. This value applies to either O(transport=cli) or O(transport=rest). The port
- value will default to the appropriate transport common port if
- none is provided in the task. (cli=22, http=80, https=443). Note
- this argument does not affect the SSH transport.
+ - Specifies the port to use when building the connection to the remote device. This value applies to either O(transport=cli)
+ or O(transport=rest). The port value will default to the appropriate transport common port if none is provided in
+ the task. (cli=22, http=80, https=443). Note this argument does not affect the SSH transport.
type: int
default: 0 (use common port)
username:
description:
- - Configures the username to use to authenticate the connection to
- the remote device. This value is used to authenticate
- either the CLI login or the eAPI authentication depending on which
- transport is used. Note this argument does not affect the SSH
- transport. If the value is not specified in the task, the value of
- environment variable E(ANSIBLE_NET_USERNAME) will be used instead.
+ - Configures the username to use to authenticate the connection to the remote device. This value is used to authenticate
+ either the CLI login or the eAPI authentication depending on which transport is used. Note this argument does not
+ affect the SSH transport. If the value is not specified in the task, the value of environment variable E(ANSIBLE_NET_USERNAME)
+ will be used instead.
type: str
password:
description:
- - Specifies the password to use to authenticate the connection to
- the remote device. This is a common argument used for either O(transport=cli)
- or O(transport=rest). Note this argument does not affect the SSH
- transport. If the value is not specified in the task, the value of
- environment variable E(ANSIBLE_NET_PASSWORD) will be used instead.
+ - Specifies the password to use to authenticate the connection to the remote device. This is a common argument used
+ for either O(transport=cli) or O(transport=rest). Note this argument does not affect the SSH transport. If the value
+ is not specified in the task, the value of environment variable E(ANSIBLE_NET_PASSWORD) will be used instead.
type: str
timeout:
description:
- - Specifies the timeout in seconds for communicating with the network device
- for either connecting or sending commands. If the timeout is
- exceeded before the operation is completed, the module will error.
+ - Specifies the timeout in seconds for communicating with the network device for either connecting or sending commands.
+ If the timeout is exceeded before the operation is completed, the module will error.
type: int
default: 10
ssh_keyfile:
description:
- - Specifies the SSH key to use to authenticate the connection to
- the remote device. This argument is only used for O(transport=cli).
- If the value is not specified in the task, the value of
- environment variable E(ANSIBLE_NET_SSH_KEYFILE) will be used instead.
+ - Specifies the SSH key to use to authenticate the connection to the remote device. This argument is only used for O(transport=cli).
+ If the value is not specified in the task, the value of environment variable E(ANSIBLE_NET_SSH_KEYFILE) will be used
+ instead.
type: path
transport:
description:
- - Configures the transport connection to use when connecting to the
- remote device. The transport argument supports connectivity to the
- device over SSH (V(ssh)), CLI (V(cli)), or REST (V(rest)).
+ - Configures the transport connection to use when connecting to the remote device. The transport argument supports connectivity
+ to the device over SSH (V(ssh)), CLI (V(cli)), or REST (V(rest)).
required: true
type: str
- choices: [ cli, rest, ssh ]
+ choices: [cli, rest, ssh]
default: ssh
use_ssl:
description:
- - Configures the O(transport) to use SSL if set to V(true) only when the
- O(transport) argument is configured as rest. If the transport
- argument is not V(rest), this value is ignored.
+ - Configures the O(transport) to use SSL if set to V(true) only when the O(transport) argument is configured as rest.
+ If the transport argument is not V(rest), this value is ignored.
type: bool
default: true
provider:
description:
- - Convenience method that allows all C(openswitch) arguments to be passed as
- a dict object. All constraints (required, choices, etc) must be
- met either by individual arguments or values in this dict.
+ - Convenience method that allows all C(openswitch) arguments to be passed as a dict object. All constraints (required,
+ choices, and so on) must be met either by individual arguments or values in this dict.
type: dict
-'''
+"""
diff --git a/plugins/doc_fragments/oracle.py b/plugins/doc_fragments/oracle.py
index ff0ed2fd5b..702b77f02f 100644
--- a/plugins/doc_fragments/oracle.py
+++ b/plugins/doc_fragments/oracle.py
@@ -8,76 +8,69 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = """
- requirements:
- - Python SDK for Oracle Cloud Infrastructure U(https://oracle-cloud-infrastructure-python-sdk.readthedocs.io)
- notes:
- - For OCI Python SDK configuration, please refer to
- U(https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/configuration.html).
- options:
- config_file_location:
- description:
- - Path to configuration file. If not set then the value of the E(OCI_CONFIG_FILE) environment variable,
- if any, is used. Otherwise, defaults to C(~/.oci/config).
- type: str
- config_profile_name:
- description:
- - The profile to load from the config file referenced by O(config_file_location). If not set, then the
- value of the E(OCI_CONFIG_PROFILE) environment variable, if any, is used. Otherwise, defaults to the
- C(DEFAULT) profile in O(config_file_location).
- default: "DEFAULT"
- type: str
- api_user:
- description:
- - The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the
- value of the E(OCI_USER_OCID) environment variable, if any, is used. This option is required if the user
- is not specified through a configuration file (See O(config_file_location)). To get the user's OCID,
- please refer U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
- type: str
- api_user_fingerprint:
- description:
- - Fingerprint for the key pair being used. If not set, then the value of the E(OCI_USER_FINGERPRINT)
- environment variable, if any, is used. This option is required if the key fingerprint is not
- specified through a configuration file (See O(config_file_location)). To get the key pair's
- fingerprint value please refer
- U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
- type: str
- api_user_key_file:
- description:
- - Full path and filename of the private key (in PEM format). If not set, then the value of the
- OCI_USER_KEY_FILE variable, if any, is used. This option is required if the private key is
- not specified through a configuration file (See O(config_file_location)). If the key is encrypted
- with a pass-phrase, the O(api_user_key_pass_phrase) option must also be provided.
- type: path
- api_user_key_pass_phrase:
- description:
- - Passphrase used by the key referenced in O(api_user_key_file), if it is encrypted. If not set, then
- the value of the OCI_USER_KEY_PASS_PHRASE variable, if any, is used. This option is required if the
- key passphrase is not specified through a configuration file (See O(config_file_location)).
- type: str
- auth_type:
- description:
- - The type of authentication to use for making API requests. By default O(auth_type=api_key) based
- authentication is performed and the API key (see O(api_user_key_file)) in your config file will be
- used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE,
- if any, is used. Use O(auth_type=instance_principal) to use instance principal based authentication
- when running ansible playbooks within an OCI compute instance.
- choices: ['api_key', 'instance_principal']
- default: 'api_key'
- type: str
- tenancy:
- description:
- - OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is
- used. This option is required if the tenancy OCID is not specified through a configuration file
- (See O(config_file_location)). To get the tenancy OCID, please refer to
- U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
- type: str
- region:
- description:
- - The Oracle Cloud Infrastructure region to use for all OCI API requests. If not set, then the
- value of the OCI_REGION variable, if any, is used. This option is required if the region is
- not specified through a configuration file (See O(config_file_location)). Please refer to
- U(https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm) for more information
- on OCI regions.
- type: str
- """
+ DOCUMENTATION = r"""
+requirements:
+ - Python SDK for Oracle Cloud Infrastructure U(https://oracle-cloud-infrastructure-python-sdk.readthedocs.io)
+notes:
+ - For OCI Python SDK configuration, please refer to U(https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/configuration.html).
+options:
+ config_file_location:
+ description:
+ - Path to configuration file. If not set then the value of the E(OCI_CONFIG_FILE) environment variable, if any, is used.
+ Otherwise, defaults to C(~/.oci/config).
+ type: str
+ config_profile_name:
+ description:
+ - The profile to load from the config file referenced by O(config_file_location). If not set, then the value of the
+ E(OCI_CONFIG_PROFILE) environment variable, if any, is used. Otherwise, defaults to the C(DEFAULT) profile in O(config_file_location).
+ default: "DEFAULT"
+ type: str
+ api_user:
+ description:
+ - The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the E(OCI_USER_OCID) environment
+ variable, if any, is used. This option is required if the user is not specified through a configuration file (See
+ O(config_file_location)). To get the user's OCID, please refer U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
+ type: str
+ api_user_fingerprint:
+ description:
+ - Fingerprint for the key pair being used. If not set, then the value of the E(OCI_USER_FINGERPRINT) environment variable,
+ if any, is used. This option is required if the key fingerprint is not specified through a configuration file (See
+ O(config_file_location)). To get the key pair's fingerprint value please refer to
+ U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
+ type: str
+ api_user_key_file:
+ description:
+ - Full path and filename of the private key (in PEM format). If not set, then the value of the E(OCI_USER_KEY_FILE)
+ variable, if any, is used. This option is required if the private key is not specified through a configuration file
+ (See O(config_file_location)). If the key is encrypted with a pass-phrase, the O(api_user_key_pass_phrase) option
+ must also be provided.
+ type: path
+ api_user_key_pass_phrase:
+ description:
+ - Passphrase used by the key referenced in O(api_user_key_file), if it is encrypted. If not set, then the value of the
+ E(OCI_USER_KEY_PASS_PHRASE) variable, if any, is used. This option is required if the key passphrase is not specified
+ through a configuration file (See O(config_file_location)).
+ type: str
+ auth_type:
+ description:
+ - The type of authentication to use for making API requests. By default O(auth_type=api_key) based authentication is
+ performed and the API key (see O(api_user_key_file)) in your config file will be used. If this 'auth_type' module
+ option is not specified, the value of the E(OCI_ANSIBLE_AUTH_TYPE), if any, is used. Use O(auth_type=instance_principal)
+ to use instance principal based authentication when running ansible playbooks within an OCI compute instance.
+ choices: ['api_key', 'instance_principal']
+ default: 'api_key'
+ type: str
+ tenancy:
+ description:
+ - OCID of your tenancy. If not set, then the value of the E(OCI_TENANCY) variable, if any, is used. This option is required
+ if the tenancy OCID is not specified through a configuration file (See O(config_file_location)). To get the tenancy
+ OCID, please refer to U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
+ type: str
+ region:
+ description:
+ - The Oracle Cloud Infrastructure region to use for all OCI API requests. If not set, then the value of the E(OCI_REGION)
+ variable, if any, is used. This option is required if the region is not specified through a configuration file (See
+ O(config_file_location)). Please refer to U(https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm)
+ for more information on OCI regions.
+ type: str
+"""
diff --git a/plugins/doc_fragments/oracle_creatable_resource.py b/plugins/doc_fragments/oracle_creatable_resource.py
index 9d2cc07c9f..5ccd6525c0 100644
--- a/plugins/doc_fragments/oracle_creatable_resource.py
+++ b/plugins/doc_fragments/oracle_creatable_resource.py
@@ -8,19 +8,18 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = """
- options:
- force_create:
- description: Whether to attempt non-idempotent creation of a resource. By default, create resource is an
- idempotent operation, and doesn't create the resource if it already exists. Setting this option
- to true, forcefully creates a copy of the resource, even if it already exists.This option is
- mutually exclusive with O(key_by).
- default: false
- type: bool
- key_by:
- description: The list of comma-separated attributes of this resource which should be used to uniquely
- identify an instance of the resource. By default, all the attributes of a resource except
- O(freeform_tags) are used to uniquely identify a resource.
- type: list
- elements: str
- """
+ DOCUMENTATION = r"""
+options:
+ force_create:
+ description: Whether to attempt non-idempotent creation of a resource. By default, create resource is an idempotent operation,
+ and does not create the resource if it already exists. Setting this option to V(true), forcefully creates a copy of
+ the resource, even if it already exists. This option is mutually exclusive with O(key_by).
+ default: false
+ type: bool
+ key_by:
+ description: The list of comma-separated attributes of this resource which should be used to uniquely identify an instance
+ of the resource. By default, all the attributes of a resource except O(freeform_tags) are used to uniquely identify
+ a resource.
+ type: list
+ elements: str
+"""
diff --git a/plugins/doc_fragments/oracle_display_name_option.py b/plugins/doc_fragments/oracle_display_name_option.py
index b6bc0f2297..ab219352e9 100644
--- a/plugins/doc_fragments/oracle_display_name_option.py
+++ b/plugins/doc_fragments/oracle_display_name_option.py
@@ -8,10 +8,10 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = """
- options:
- display_name:
- description: Use O(display_name) along with the other options to return only resources that match the given
- display name exactly.
- type: str
- """
+ DOCUMENTATION = r"""
+options:
+ display_name:
+ description: Use O(display_name) along with the other options to return only resources that match the given display name
+ exactly.
+ type: str
+"""
diff --git a/plugins/doc_fragments/oracle_name_option.py b/plugins/doc_fragments/oracle_name_option.py
index 523eed702f..5d5c97ef65 100644
--- a/plugins/doc_fragments/oracle_name_option.py
+++ b/plugins/doc_fragments/oracle_name_option.py
@@ -8,10 +8,9 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = """
- options:
- name:
- description: Use O(name) along with the other options to return only resources that match the given name
- exactly.
- type: str
- """
+ DOCUMENTATION = r"""
+options:
+ name:
+ description: Use O(name) along with the other options to return only resources that match the given name exactly.
+ type: str
+"""
diff --git a/plugins/doc_fragments/oracle_tags.py b/plugins/doc_fragments/oracle_tags.py
index 3789dbe912..9cd35f9c7e 100644
--- a/plugins/doc_fragments/oracle_tags.py
+++ b/plugins/doc_fragments/oracle_tags.py
@@ -8,16 +8,14 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = """
- options:
- defined_tags:
- description: Defined tags for this resource. Each key is predefined and scoped to a namespace. For more
- information, see
- U(https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/resourcetags.htm).
- type: dict
- freeform_tags:
- description: Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name,
- type, or namespace. For more information, see
- U(https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/resourcetags.htm).
- type: dict
- """
+ DOCUMENTATION = r"""
+options:
+ defined_tags:
+ description: Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see
+ U(https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/resourcetags.htm).
+ type: dict
+ freeform_tags:
+ description: Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace.
+ For more information, see U(https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/resourcetags.htm).
+ type: dict
+"""
diff --git a/plugins/doc_fragments/oracle_wait_options.py b/plugins/doc_fragments/oracle_wait_options.py
index 0ba2532324..90334711ee 100644
--- a/plugins/doc_fragments/oracle_wait_options.py
+++ b/plugins/doc_fragments/oracle_wait_options.py
@@ -8,20 +8,19 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = """
- options:
- wait:
- description: Whether to wait for create or delete operation to complete.
- default: true
- type: bool
- wait_timeout:
- description: Time, in seconds, to wait when O(wait=true).
- default: 1200
- type: int
- wait_until:
- description: The lifecycle state to wait for the resource to transition into when O(wait=true). By default,
- when O(wait=true), we wait for the resource to get into ACTIVE/ATTACHED/AVAILABLE/PROVISIONED/
- RUNNING applicable lifecycle state during create operation and to get into DELETED/DETACHED/
- TERMINATED lifecycle state during delete operation.
- type: str
- """
+ DOCUMENTATION = r"""
+options:
+ wait:
+ description: Whether to wait for create or delete operation to complete.
+ default: true
+ type: bool
+ wait_timeout:
+ description: Time, in seconds, to wait when O(wait=true).
+ default: 1200
+ type: int
+ wait_until:
+ description: The lifecycle state to wait for the resource to transition into when O(wait=true). By default, when O(wait=true),
+ we wait for the resource to get into ACTIVE/ATTACHED/AVAILABLE/PROVISIONED/ RUNNING applicable lifecycle state during
+ create operation and to get into DELETED/DETACHED/ TERMINATED lifecycle state during delete operation.
+ type: str
+"""
diff --git a/plugins/doc_fragments/pipx.py b/plugins/doc_fragments/pipx.py
index 52593f24f3..b94495d4a1 100644
--- a/plugins/doc_fragments/pipx.py
+++ b/plugins/doc_fragments/pipx.py
@@ -9,34 +9,32 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
global:
description:
- The module will pass the C(--global) argument to C(pipx), to execute actions in global scope.
- The C(--global) is only available in C(pipx>=1.6.0), so make sure to have a compatible version when using this option.
- Moreover, a nasty bug with C(--global) was fixed in C(pipx==1.7.0), so it is strongly recommended you used that version or newer.
+ Moreover, a nasty bug with C(--global) was fixed in C(pipx==1.7.0), so it is strongly recommended you used that version
+ or newer.
type: bool
default: false
executable:
description:
- Path to the C(pipx) installed in the system.
- - >
- If not specified, the module will use C(python -m pipx) to run the tool,
- using the same Python interpreter as ansible itself.
+ - If not specified, the module will use C(python -m pipx) to run the tool, using the same Python interpreter as ansible
+ itself.
type: path
notes:
- - This module requires C(pipx) version 0.16.2.1 or above. From community.general 11.0.0 onwards, the module will require C(pipx>=1.7.0).
- - Please note that C(pipx) requires Python 3.6 or above.
- - This module does not install the C(pipx) python package, however that can be easily done with the module M(ansible.builtin.pip).
- - This module does not require C(pipx) to be in the shell C(PATH), but it must be loadable by Python as a module.
- - >
- This module will honor C(pipx) environment variables such as but not limited to E(PIPX_HOME) and E(PIPX_BIN_DIR)
- passed using the R(environment Ansible keyword, playbooks_environment).
-
+ - This module requires C(pipx) version 0.16.2.1 or above. From community.general 11.0.0 onwards, the module will require
+ C(pipx>=1.7.0).
+ - Please note that C(pipx) requires Python 3.6 or above.
+ - This module does not install the C(pipx) python package, however that can be easily done with the module M(ansible.builtin.pip).
+ - This module does not require C(pipx) to be in the shell C(PATH), but it must be loadable by Python as a module.
+ - This module will honor C(pipx) environment variables such as but not limited to E(PIPX_HOME) and E(PIPX_BIN_DIR) passed
+ using the R(environment Ansible keyword, playbooks_environment).
seealso:
- name: C(pipx) command manual page
description: Manual page for the command.
link: https://pipx.pypa.io/latest/docs/
-
-'''
+"""
diff --git a/plugins/doc_fragments/pritunl.py b/plugins/doc_fragments/pritunl.py
index 396ee0866a..287204c16c 100644
--- a/plugins/doc_fragments/pritunl.py
+++ b/plugins/doc_fragments/pritunl.py
@@ -13,32 +13,28 @@ class ModuleDocFragment(object):
DOCUMENTATION = r"""
options:
- pritunl_url:
- type: str
- required: true
- description:
- - URL and port of the Pritunl server on which the API is enabled.
-
- pritunl_api_token:
- type: str
- required: true
- description:
- - API Token of a Pritunl admin user.
- - It needs to be enabled in Administrators > USERNAME > Enable Token Authentication.
-
- pritunl_api_secret:
- type: str
- required: true
- description:
- - API Secret found in Administrators > USERNAME > API Secret.
-
- validate_certs:
- type: bool
- required: false
- default: true
- description:
- - If certificates should be validated or not.
- - This should never be set to V(false), except if you are very sure that
- your connection to the server can not be subject to a Man In The Middle
- attack.
+ pritunl_url:
+ type: str
+ required: true
+ description:
+ - URL and port of the Pritunl server on which the API is enabled.
+ pritunl_api_token:
+ type: str
+ required: true
+ description:
+ - API Token of a Pritunl admin user.
+ - It needs to be enabled in Administrators > USERNAME > Enable Token Authentication.
+ pritunl_api_secret:
+ type: str
+ required: true
+ description:
+ - API Secret found in Administrators > USERNAME > API Secret.
+ validate_certs:
+ type: bool
+ required: false
+ default: true
+ description:
+ - If certificates should be validated or not.
+ - This should never be set to V(false), except if you are very sure that your connection to the server can not be subject
+ to a Man In The Middle attack.
"""
diff --git a/plugins/doc_fragments/proxmox.py b/plugins/doc_fragments/proxmox.py
index 239dba06da..4641c36d3e 100644
--- a/plugins/doc_fragments/proxmox.py
+++ b/plugins/doc_fragments/proxmox.py
@@ -9,7 +9,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Common parameters for Proxmox VE modules
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
api_host:
description:
@@ -51,10 +51,10 @@ options:
- This should only be used on personally controlled sites using self-signed certificates.
type: bool
default: false
-requirements: [ "proxmoxer", "requests" ]
-'''
+requirements: ["proxmoxer", "requests"]
+"""
- SELECTION = r'''
+ SELECTION = r"""
options:
vmid:
description:
@@ -71,7 +71,7 @@ options:
description:
- Add the new VM to the specified pool.
type: str
-'''
+"""
ACTIONGROUP_PROXMOX = r"""
options: {}
diff --git a/plugins/doc_fragments/purestorage.py b/plugins/doc_fragments/purestorage.py
index 823397763f..c2c6c9a262 100644
--- a/plugins/doc_fragments/purestorage.py
+++ b/plugins/doc_fragments/purestorage.py
@@ -10,18 +10,8 @@ __metaclass__ = type
class ModuleDocFragment(object):
- # Standard Pure Storage documentation fragment
- DOCUMENTATION = r'''
-options:
- - See separate platform section for more details
-requirements:
- - See separate platform section for more details
-notes:
- - Ansible modules are available for the following Pure Storage products: FlashArray, FlashBlade
-'''
-
# Documentation fragment for FlashBlade
- FB = r'''
+ FB = r"""
options:
fb_url:
description:
@@ -33,14 +23,14 @@ options:
type: str
notes:
- This module requires the C(purity_fb) Python library.
- - You must set E(PUREFB_URL) and E(PUREFB_API) environment variables
- if O(fb_url) and O(api_token) arguments are not passed to the module directly.
+ - You must set E(PUREFB_URL) and E(PUREFB_API) environment variables if O(fb_url) and O(api_token) arguments are not passed
+ to the module directly.
requirements:
- purity_fb >= 1.1
-'''
+"""
# Documentation fragment for FlashArray
- FA = r'''
+ FA = r"""
options:
fa_url:
description:
@@ -54,8 +44,8 @@ options:
required: true
notes:
- This module requires the C(purestorage) Python library.
- - You must set E(PUREFA_URL) and E(PUREFA_API) environment variables
- if O(fa_url) and O(api_token) arguments are not passed to the module directly.
+ - You must set E(PUREFA_URL) and E(PUREFA_API) environment variables if O(fa_url) and O(api_token) arguments are not passed
+ to the module directly.
requirements:
- purestorage
-'''
+"""
diff --git a/plugins/doc_fragments/redis.py b/plugins/doc_fragments/redis.py
index 69fd0c9cd5..149c018d79 100644
--- a/plugins/doc_fragments/redis.py
+++ b/plugins/doc_fragments/redis.py
@@ -10,7 +10,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Common parameters for Redis modules
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
login_host:
description:
@@ -40,14 +40,12 @@ options:
validate_certs:
description:
- Specify whether or not to validate TLS certificates.
- - This should only be turned off for personally controlled sites or with
- C(localhost) as target.
+ - This should only be turned off for personally controlled sites or with C(localhost) as target.
type: bool
default: true
ca_certs:
description:
- - Path to root certificates file. If not set and O(tls) is
- set to V(true), certifi ca-certificates will be used.
+ - Path to root certificates file. If not set and O(tls) is set to V(true), certifi ca-certificates will be used.
type: str
client_cert_file:
description:
@@ -59,10 +57,9 @@ options:
- Path to the client private key file.
type: str
version_added: 9.3.0
-requirements: [ "redis", "certifi" ]
+requirements: ["redis", "certifi"]
notes:
- - Requires the C(redis) Python package on the remote host. You can
- install it with pip (C(pip install redis)) or with a package manager.
- Information on the library can be found at U(https://github.com/andymccurdy/redis-py).
-'''
+ - Requires the C(redis) Python package on the remote host. You can install it with pip (C(pip install redis)) or with a
+ package manager. Information on the library can be found at U(https://github.com/andymccurdy/redis-py).
+"""
diff --git a/plugins/doc_fragments/rundeck.py b/plugins/doc_fragments/rundeck.py
index 62c8648e96..b3a8e86753 100644
--- a/plugins/doc_fragments/rundeck.py
+++ b/plugins/doc_fragments/rundeck.py
@@ -11,7 +11,7 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard files documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
url:
type: str
@@ -29,4 +29,4 @@ options:
description:
- Rundeck User API Token.
required: true
-'''
+"""
diff --git a/plugins/doc_fragments/scaleway.py b/plugins/doc_fragments/scaleway.py
index bdb0dd0561..2988865eea 100644
--- a/plugins/doc_fragments/scaleway.py
+++ b/plugins/doc_fragments/scaleway.py
@@ -11,29 +11,29 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
api_token:
description:
- Scaleway OAuth token.
type: str
required: true
- aliases: [ oauth_token ]
+ aliases: [oauth_token]
api_url:
description:
- Scaleway API URL.
type: str
default: https://api.scaleway.com
- aliases: [ base_url ]
+ aliases: [base_url]
api_timeout:
description:
- HTTP timeout to Scaleway API in seconds.
type: int
default: 30
- aliases: [ timeout ]
+ aliases: [timeout]
query_parameters:
description:
- - List of parameters passed to the query string.
+ - List of parameters passed to the query string.
type: dict
default: {}
validate_certs:
@@ -43,9 +43,7 @@ options:
default: true
notes:
- Also see the API documentation on U(https://developer.scaleway.com/).
- - If O(api_token) is not set within the module, the following
- environment variables can be used in decreasing order of precedence
+ - If O(api_token) is not set within the module, the following environment variables can be used in decreasing order of precedence
E(SCW_TOKEN), E(SCW_API_KEY), E(SCW_OAUTH_TOKEN) or E(SCW_API_TOKEN).
- - If one wants to use a different O(api_url) one can also set the E(SCW_API_URL)
- environment variable.
-'''
+ - If one wants to use a different O(api_url) one can also set the E(SCW_API_URL) environment variable.
+"""
diff --git a/plugins/doc_fragments/scaleway_waitable_resource.py b/plugins/doc_fragments/scaleway_waitable_resource.py
index 3ab5c7d6f4..f529d8f5c2 100644
--- a/plugins/doc_fragments/scaleway_waitable_resource.py
+++ b/plugins/doc_fragments/scaleway_waitable_resource.py
@@ -11,23 +11,23 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard documentation fragment
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
wait:
description:
- - Wait for the resource to reach its desired state before returning.
+ - Wait for the resource to reach its desired state before returning.
type: bool
default: true
wait_timeout:
type: int
description:
- - Time to wait for the resource to reach the expected state.
+ - Time to wait for the resource to reach the expected state.
required: false
default: 300
wait_sleep_time:
type: int
description:
- - Time to wait before every attempt to check the state of the resource.
+ - Time to wait before every attempt to check the state of the resource.
required: false
default: 3
-'''
+"""
diff --git a/plugins/doc_fragments/utm.py b/plugins/doc_fragments/utm.py
index 3e0bc6e10c..3b2118485e 100644
--- a/plugins/doc_fragments/utm.py
+++ b/plugins/doc_fragments/utm.py
@@ -9,49 +9,49 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
- headers:
- description:
- - A dictionary of additional headers to be sent to POST and PUT requests.
- - Is needed for some modules.
- type: dict
- required: false
- default: {}
- utm_host:
- description:
- - The REST Endpoint of the Sophos UTM.
- type: str
- required: true
- utm_port:
- description:
- - The port of the REST interface.
- type: int
- default: 4444
- utm_token:
- description:
- - "The token used to identify at the REST-API. See
- U(https://www.sophos.com/en-us/medialibrary/PDFs/documentation/UTMonAWS/Sophos-UTM-RESTful-API.pdf?la=en),
- Chapter 2.4.2."
- type: str
- required: true
- utm_protocol:
- description:
- - The protocol of the REST Endpoint.
- choices: [ http, https ]
- type: str
- default: https
- validate_certs:
- description:
- - Whether the REST interface's ssl certificate should be verified or not.
- type: bool
- default: true
- state:
- description:
- - The desired state of the object.
- - V(present) will create or update an object.
- - V(absent) will delete an object if it was present.
- type: str
- choices: [ absent, present ]
- default: present
-'''
+ headers:
+ description:
+ - A dictionary of additional headers to be sent to POST and PUT requests.
+ - Is needed for some modules.
+ type: dict
+ required: false
+ default: {}
+ utm_host:
+ description:
+ - The REST Endpoint of the Sophos UTM.
+ type: str
+ required: true
+ utm_port:
+ description:
+ - The port of the REST interface.
+ type: int
+ default: 4444
+ utm_token:
+ description:
+ - The token used to identify at the REST-API.
+ - See U(https://www.sophos.com/en-us/medialibrary/PDFs/documentation/UTMonAWS/Sophos-UTM-RESTful-API.pdf?la=en), Chapter
+ 2.4.2.
+ type: str
+ required: true
+ utm_protocol:
+ description:
+ - The protocol of the REST Endpoint.
+ choices: [http, https]
+ type: str
+ default: https
+ validate_certs:
+ description:
+ - Whether the REST interface's SSL certificate should be verified or not.
+ type: bool
+ default: true
+ state:
+ description:
+ - The desired state of the object.
+ - V(present) will create or update an object.
+ - V(absent) will delete an object if it was present.
+ type: str
+ choices: [absent, present]
+ default: present
+"""
diff --git a/plugins/doc_fragments/vexata.py b/plugins/doc_fragments/vexata.py
index 041f404d28..48ff30a276 100644
--- a/plugins/doc_fragments/vexata.py
+++ b/plugins/doc_fragments/vexata.py
@@ -10,15 +10,6 @@ __metaclass__ = type
class ModuleDocFragment(object):
- DOCUMENTATION = r'''
-options:
- - See respective platform section for more details
-requirements:
- - See respective platform section for more details
-notes:
- - Ansible modules are available for Vexata VX100 arrays.
-'''
-
# Documentation fragment for Vexata VX100 series
VX100 = r'''
options:
diff --git a/plugins/doc_fragments/xenserver.py b/plugins/doc_fragments/xenserver.py
index 681d959faa..d1377e8964 100644
--- a/plugins/doc_fragments/xenserver.py
+++ b/plugins/doc_fragments/xenserver.py
@@ -10,32 +10,33 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Common parameters for XenServer modules
- DOCUMENTATION = r'''
+ DOCUMENTATION = r"""
options:
hostname:
description:
- - The hostname or IP address of the XenServer host or XenServer pool master.
- - If the value is not specified in the task, the value of environment variable E(XENSERVER_HOST) will be used instead.
+ - The hostname or IP address of the XenServer host or XenServer pool master.
+ - If the value is not specified in the task, the value of environment variable E(XENSERVER_HOST) will be used instead.
type: str
default: localhost
- aliases: [ host, pool ]
+ aliases: [host, pool]
username:
description:
- - The username to use for connecting to XenServer.
- - If the value is not specified in the task, the value of environment variable E(XENSERVER_USER) will be used instead.
+ - The username to use for connecting to XenServer.
+ - If the value is not specified in the task, the value of environment variable E(XENSERVER_USER) will be used instead.
type: str
default: root
- aliases: [ admin, user ]
+ aliases: [admin, user]
password:
description:
- - The password to use for connecting to XenServer.
- - If the value is not specified in the task, the value of environment variable E(XENSERVER_PASSWORD) will be used instead.
+ - The password to use for connecting to XenServer.
+ - If the value is not specified in the task, the value of environment variable E(XENSERVER_PASSWORD) will be used instead.
type: str
- aliases: [ pass, pwd ]
+ aliases: [pass, pwd]
validate_certs:
description:
- - Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted.
- - If the value is not specified in the task, the value of environment variable E(XENSERVER_VALIDATE_CERTS) will be used instead.
+ - Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted.
+ - If the value is not specified in the task, the value of environment variable E(XENSERVER_VALIDATE_CERTS) will be used
+ instead.
type: bool
default: true
-'''
+"""
diff --git a/plugins/filter/accumulate.py b/plugins/filter/accumulate.py
new file mode 100644
index 0000000000..c48afa0467
--- /dev/null
+++ b/plugins/filter/accumulate.py
@@ -0,0 +1,63 @@
+# Copyright (c) Max Gautier
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+DOCUMENTATION = r"""
+name: accumulate
+short_description: Produce a list of accumulated sums of the input list contents
+version_added: 10.1.0
+author: Max Gautier (@VannTen)
+description:
+ - Passthrough to the L(Python itertools.accumulate function,https://docs.python.org/3/library/itertools.html#itertools.accumulate).
+ - Transforms an input list into the cumulative list of results from applying addition to the elements of the input list.
+ - Addition means the default Python implementation of C(+) for input list elements type.
+options:
+ _input:
+ description: A list.
+ type: list
+ elements: any
+ required: true
+"""
+
+RETURN = r"""
+_value:
+ description: A list of cumulated sums of the elements of the input list.
+ type: list
+ elements: any
+"""
+
+EXAMPLES = r"""
+- name: Enumerate parent directories of some path
+ ansible.builtin.debug:
+ var: >
+ "/some/path/to/my/file"
+ | split('/') | map('split', '/')
+ | community.general.accumulate | map('join', '/')
+ # Produces: ['', '/some', '/some/path', '/some/path/to', '/some/path/to/my', '/some/path/to/my/file']
+
+- name: Growing string
+ ansible.builtin.debug:
+ var: "'abc' | community.general.accumulate"
+ # Produces ['a', 'ab', 'abc']
+"""
+
+from itertools import accumulate
+from collections.abc import Sequence
+
+from ansible.errors import AnsibleFilterError
+
+
+def list_accumulate(sequence):
+ if not isinstance(sequence, Sequence):
+ raise AnsibleFilterError('Invalid value type (%s) for accumulate (%r)' %
+ (type(sequence), sequence))
+
+ return accumulate(sequence)
+
+
+class FilterModule(object):
+
+ def filters(self):
+ return {
+ 'accumulate': list_accumulate,
+ }
diff --git a/plugins/filter/counter.py b/plugins/filter/counter.py
index 1b79294b59..bd4b5d4448 100644
--- a/plugins/filter/counter.py
+++ b/plugins/filter/counter.py
@@ -3,37 +3,37 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: counter
- short_description: Counts hashable elements in a sequence
- version_added: 4.3.0
- author: Rémy Keil (@keilr)
- description:
- - Counts hashable elements in a sequence.
- options:
- _input:
- description: A sequence.
- type: list
- elements: any
- required: true
-'''
+DOCUMENTATION = r"""
+name: counter
+short_description: Counts hashable elements in a sequence
+version_added: 4.3.0
+author: Rémy Keil (@keilr)
+description:
+ - Counts hashable elements in a sequence.
+options:
+ _input:
+ description: A sequence.
+ type: list
+ elements: any
+ required: true
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Count occurrences
ansible.builtin.debug:
msg: >-
{{ [1, 'a', 2, 2, 'a', 'b', 'a'] | community.general.counter }}
# Produces: {1: 1, 'a': 3, 2: 2, 'b': 1}
-'''
+"""
-RETURN = '''
- _value:
- description: A dictionary with the elements of the sequence as keys, and their number of occurrences in the sequence as values.
- type: dictionary
-'''
+RETURN = r"""
+_value:
+ description: A dictionary with the elements of the sequence as keys, and their number of occurrences in the sequence as
+ values.
+ type: dictionary
+"""
from ansible.errors import AnsibleFilterError
from ansible.module_utils.common._collections_compat import Sequence
diff --git a/plugins/filter/crc32.py b/plugins/filter/crc32.py
index 1f0aa2e9b0..e394d23732 100644
--- a/plugins/filter/crc32.py
+++ b/plugins/filter/crc32.py
@@ -2,8 +2,7 @@
# Copyright (c) 2022, Julien Riou
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
from ansible.errors import AnsibleFilterError
from ansible.module_utils.common.text.converters import to_bytes
@@ -16,33 +15,33 @@ except ImportError:
HAS_ZLIB = False
-DOCUMENTATION = '''
- name: crc32
- short_description: Generate a CRC32 checksum
- version_added: 5.4.0
- description:
- - Checksum a string using CRC32 algorithm and return its hexadecimal representation.
- options:
- _input:
- description:
- - The string to checksum.
- type: string
- required: true
- author:
- - Julien Riou
-'''
-
-EXAMPLES = '''
- - name: Checksum a test string
- ansible.builtin.debug:
- msg: "{{ 'test' | community.general.crc32 }}"
-'''
-
-RETURN = '''
- _value:
- description: CRC32 checksum.
+DOCUMENTATION = r"""
+name: crc32
+short_description: Generate a CRC32 checksum
+version_added: 5.4.0
+description:
+ - Checksum a string using CRC32 algorithm and return its hexadecimal representation.
+options:
+ _input:
+ description:
+ - The string to checksum.
type: string
-'''
+ required: true
+author:
+ - Julien Riou
+"""
+
+EXAMPLES = r"""
+- name: Checksum a test string
+ ansible.builtin.debug:
+ msg: "{{ 'test' | community.general.crc32 }}"
+"""
+
+RETURN = r"""
+_value:
+ description: CRC32 checksum.
+ type: string
+"""
def crc32s(value):
diff --git a/plugins/filter/dict.py b/plugins/filter/dict.py
index 720c9def96..23c977dfd6 100644
--- a/plugins/filter/dict.py
+++ b/plugins/filter/dict.py
@@ -4,25 +4,24 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: dict
- short_description: Convert a list of tuples into a dictionary
- version_added: 3.0.0
- author: Felix Fontein (@felixfontein)
- description:
- - Convert a list of tuples into a dictionary. This is a filter version of the C(dict) function.
- options:
- _input:
- description: A list of tuples (with exactly two elements).
- type: list
- elements: tuple
- required: true
-'''
+DOCUMENTATION = r"""
+name: dict
+short_description: Convert a list of tuples into a dictionary
+version_added: 3.0.0
+author: Felix Fontein (@felixfontein)
+description:
+ - Convert a list of tuples into a dictionary. This is a filter version of the C(dict) function.
+options:
+ _input:
+ description: A list of tuples (with exactly two elements).
+ type: list
+ elements: tuple
+ required: true
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Convert list of tuples into dictionary
ansible.builtin.set_fact:
dictionary: "{{ [[1, 2], ['a', 'b']] | community.general.dict }}"
@@ -53,13 +52,13 @@ EXAMPLES = '''
# "k2": 42,
# "k3": "b"
# }
-'''
+"""
-RETURN = '''
- _value:
- description: The dictionary having the provided key-value pairs.
- type: boolean
-'''
+RETURN = r"""
+_value:
+ description: A dictionary with the provided key-value pairs.
+ type: dictionary
+"""
def dict_filter(sequence):
diff --git a/plugins/filter/dict_kv.py b/plugins/filter/dict_kv.py
index 59595f9573..1d73bde301 100644
--- a/plugins/filter/dict_kv.py
+++ b/plugins/filter/dict_kv.py
@@ -3,40 +3,39 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: dict_kv
- short_description: Convert a value to a dictionary with a single key-value pair
- version_added: 1.3.0
- author: Stanislav German-Evtushenko (@giner)
- description:
- - Convert a value to a dictionary with a single key-value pair.
- positional: key
- options:
- _input:
- description: The value for the single key-value pair.
- type: any
- required: true
- key:
- description: The key for the single key-value pair.
- type: any
- required: true
-'''
+DOCUMENTATION = r"""
+name: dict_kv
+short_description: Convert a value to a dictionary with a single key-value pair
+version_added: 1.3.0
+author: Stanislav German-Evtushenko (@giner)
+description:
+ - Convert a value to a dictionary with a single key-value pair.
+positional: key
+options:
+ _input:
+ description: The value for the single key-value pair.
+ type: any
+ required: true
+ key:
+ description: The key for the single key-value pair.
+ type: any
+ required: true
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a one-element dictionary from a value
ansible.builtin.debug:
msg: "{{ 'myvalue' | dict_kv('mykey') }}"
# Produces the dictionary {'mykey': 'myvalue'}
-'''
+"""
-RETURN = '''
- _value:
- description: A dictionary with a single key-value pair.
- type: dictionary
-'''
+RETURN = r"""
+_value:
+ description: A dictionary with a single key-value pair.
+ type: dictionary
+"""
def dict_kv(value, key):
diff --git a/plugins/filter/from_csv.py b/plugins/filter/from_csv.py
index 310138d496..e9a5d73e53 100644
--- a/plugins/filter/from_csv.py
+++ b/plugins/filter/from_csv.py
@@ -5,54 +5,53 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: from_csv
- short_description: Converts CSV text input into list of dicts
- version_added: 2.3.0
- author: Andrew Pantuso (@Ajpantuso)
- description:
- - Converts CSV text input into list of dictionaries.
- options:
- _input:
- description: A string containing a CSV document.
- type: string
- required: true
- dialect:
- description:
- - The CSV dialect to use when parsing the CSV file.
- - Possible values include V(excel), V(excel-tab) or V(unix).
- type: str
- default: excel
- fieldnames:
- description:
- - A list of field names for every column.
- - This is needed if the CSV does not have a header.
- type: list
- elements: str
- delimiter:
- description:
- - A one-character string used to separate fields.
- - When using this parameter, you change the default value used by O(dialect).
- - The default value depends on the dialect used.
- type: str
- skipinitialspace:
- description:
- - Whether to ignore any whitespaces immediately following the delimiter.
- - When using this parameter, you change the default value used by O(dialect).
- - The default value depends on the dialect used.
- type: bool
- strict:
- description:
- - Whether to raise an exception on bad CSV input.
- - When using this parameter, you change the default value used by O(dialect).
- - The default value depends on the dialect used.
- type: bool
-'''
+DOCUMENTATION = r"""
+name: from_csv
+short_description: Converts CSV text input into list of dicts
+version_added: 2.3.0
+author: Andrew Pantuso (@Ajpantuso)
+description:
+ - Converts CSV text input into list of dictionaries.
+options:
+ _input:
+ description: A string containing a CSV document.
+ type: string
+ required: true
+ dialect:
+ description:
+ - The CSV dialect to use when parsing the CSV file.
+ - Possible values include V(excel), V(excel-tab) or V(unix).
+ type: str
+ default: excel
+ fieldnames:
+ description:
+ - A list of field names for every column.
+ - This is needed if the CSV does not have a header.
+ type: list
+ elements: str
+ delimiter:
+ description:
+ - A one-character string used to separate fields.
+ - When using this parameter, you change the default value used by O(dialect).
+ - The default value depends on the dialect used.
+ type: str
+ skipinitialspace:
+ description:
+ - Whether to ignore any whitespaces immediately following the delimiter.
+ - When using this parameter, you change the default value used by O(dialect).
+ - The default value depends on the dialect used.
+ type: bool
+ strict:
+ description:
+ - Whether to raise an exception on bad CSV input.
+ - When using this parameter, you change the default value used by O(dialect).
+ - The default value depends on the dialect used.
+ type: bool
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Parse a CSV file's contents
ansible.builtin.debug:
msg: >-
@@ -71,17 +70,16 @@ EXAMPLES = '''
# "Column 1": "bar",
# "Value": "42",
# }
-'''
+"""
-RETURN = '''
- _value:
- description: A list with one dictionary per row.
- type: list
- elements: dictionary
-'''
+RETURN = r"""
+_value:
+ description: A list with one dictionary per row.
+ type: list
+ elements: dictionary
+"""
from ansible.errors import AnsibleFilterError
-from ansible.module_utils.common.text.converters import to_native
from ansible_collections.community.general.plugins.module_utils.csv import (initialize_dialect, read_csv, CSVError,
DialectNotAvailableError,
@@ -99,7 +97,7 @@ def from_csv(data, dialect='excel', fieldnames=None, delimiter=None, skipinitial
try:
dialect = initialize_dialect(dialect, **dialect_params)
except (CustomDialectFailureError, DialectNotAvailableError) as e:
- raise AnsibleFilterError(to_native(e))
+ raise AnsibleFilterError(str(e))
reader = read_csv(data, dialect, fieldnames)
@@ -109,7 +107,7 @@ def from_csv(data, dialect='excel', fieldnames=None, delimiter=None, skipinitial
for row in reader:
data_list.append(row)
except CSVError as e:
- raise AnsibleFilterError("Unable to process file: %s" % to_native(e))
+ raise AnsibleFilterError(f"Unable to process file: {e}")
return data_list
diff --git a/plugins/filter/from_ini.py b/plugins/filter/from_ini.py
index 6fe83875e6..d77338df99 100644
--- a/plugins/filter/from_ini.py
+++ b/plugins/filter/from_ini.py
@@ -4,53 +4,51 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
+from __future__ import annotations
-DOCUMENTATION = r'''
- name: from_ini
- short_description: Converts INI text input into a dictionary
- version_added: 8.2.0
- author: Steffen Scheib (@sscheib)
- description:
- - Converts INI text input into a dictionary.
- options:
- _input:
- description: A string containing an INI document.
- type: string
- required: true
-'''
+DOCUMENTATION = r"""
+name: from_ini
+short_description: Converts INI text input into a dictionary
+version_added: 8.2.0
+author: Steffen Scheib (@sscheib)
+description:
+ - Converts INI text input into a dictionary.
+options:
+ _input:
+ description: A string containing an INI document.
+ type: string
+ required: true
+"""
-EXAMPLES = r'''
- - name: Slurp an INI file
- ansible.builtin.slurp:
- src: /etc/rhsm/rhsm.conf
- register: rhsm_conf
+EXAMPLES = r"""
+- name: Slurp an INI file
+ ansible.builtin.slurp:
+ src: /etc/rhsm/rhsm.conf
+ register: rhsm_conf
- - name: Display the INI file as dictionary
- ansible.builtin.debug:
- var: rhsm_conf.content | b64decode | community.general.from_ini
+- name: Display the INI file as dictionary
+ ansible.builtin.debug:
+ var: rhsm_conf.content | b64decode | community.general.from_ini
- - name: Set a new dictionary fact with the contents of the INI file
- ansible.builtin.set_fact:
- rhsm_dict: >-
- {{
- rhsm_conf.content | b64decode | community.general.from_ini
- }}
-'''
+- name: Set a new dictionary fact with the contents of the INI file
+ ansible.builtin.set_fact:
+ rhsm_dict: >-
+ {{
+ rhsm_conf.content | b64decode | community.general.from_ini
+ }}
+"""
-RETURN = '''
- _value:
- description: A dictionary representing the INI file.
- type: dictionary
-'''
+RETURN = r"""
+_value:
+ description: A dictionary representing the INI file.
+ type: dictionary
+"""
-__metaclass__ = type
from ansible.errors import AnsibleFilterError
from ansible.module_utils.six import string_types
from ansible.module_utils.six.moves import StringIO
from ansible.module_utils.six.moves.configparser import ConfigParser
-from ansible.module_utils.common.text.converters import to_native
class IniParser(ConfigParser):
@@ -83,8 +81,7 @@ def from_ini(obj):
try:
parser.read_file(StringIO(obj))
except Exception as ex:
- raise AnsibleFilterError(f'from_ini failed to parse given string: '
- f'{to_native(ex)}', orig_exc=ex)
+ raise AnsibleFilterError(f'from_ini failed to parse given string: {ex}', orig_exc=ex)
return parser.as_dict()
diff --git a/plugins/filter/groupby_as_dict.py b/plugins/filter/groupby_as_dict.py
index 8e29c5863c..81a24a1e9f 100644
--- a/plugins/filter/groupby_as_dict.py
+++ b/plugins/filter/groupby_as_dict.py
@@ -3,32 +3,31 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: groupby_as_dict
- short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute
- version_added: 3.1.0
- author: Felix Fontein (@felixfontein)
- description:
- - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute.
- - This filter is similar to the Jinja2 C(groupby) filter. Use the Jinja2 C(groupby) filter if you have multiple entries with the same value,
- or when you need a dictionary with list values, or when you need to use deeply nested attributes.
- positional: attribute
- options:
- _input:
- description: A list of dictionaries
- type: list
- elements: dictionary
- required: true
- attribute:
- description: The attribute to use as the key.
- type: str
- required: true
-'''
+DOCUMENTATION = r"""
+name: groupby_as_dict
+short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute
+version_added: 3.1.0
+author: Felix Fontein (@felixfontein)
+description:
+ - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute.
+ - This filter is similar to the Jinja2 C(groupby) filter. Use the Jinja2 C(groupby) filter if you have multiple entries
+ with the same value, or when you need a dictionary with list values, or when you need to use deeply nested attributes.
+positional: attribute
+options:
+ _input:
+ description: A list of dictionaries.
+ type: list
+ elements: dictionary
+ required: true
+ attribute:
+ description: The attribute to use as the key.
+ type: str
+ required: true
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Arrange a list of dictionaries as a dictionary of dictionaries
ansible.builtin.debug:
msg: "{{ sequence | community.general.groupby_as_dict('key') }}"
@@ -46,13 +45,13 @@ EXAMPLES = '''
# other_value:
# key: other_value
# baz: bar
-'''
+"""
-RETURN = '''
- _value:
- description: A dictionary containing the dictionaries from the list as values.
- type: dictionary
-'''
+RETURN = r"""
+_value:
+ description: A dictionary containing the dictionaries from the list as values.
+ type: dictionary
+"""
from ansible.errors import AnsibleFilterError
from ansible.module_utils.common._collections_compat import Mapping, Sequence
diff --git a/plugins/filter/hashids.py b/plugins/filter/hashids.py
index ac771e6219..6ec64d5f59 100644
--- a/plugins/filter/hashids.py
+++ b/plugins/filter/hashids.py
@@ -4,8 +4,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
from ansible.errors import (
AnsibleError,
diff --git a/plugins/filter/jc.py b/plugins/filter/jc.py
index 2fe3ef9d73..48d53bcbd3 100644
--- a/plugins/filter/jc.py
+++ b/plugins/filter/jc.py
@@ -5,44 +5,43 @@
#
# contributed by Kelly Brazil
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: jc
- short_description: Convert output of many shell commands and file-types to JSON
- version_added: 1.1.0
- author: Kelly Brazil (@kellyjonbrazil)
- description:
- - Convert output of many shell commands and file-types to JSON.
- - Uses the L(jc library,https://github.com/kellyjonbrazil/jc).
- positional: parser
- options:
- _input:
- description: The data to convert.
- type: string
- required: true
- parser:
- description:
- - The correct parser for the input data.
- - For example V(ifconfig).
- - "Note: use underscores instead of dashes (if any) in the parser module name."
- - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers.
- type: string
- required: true
- quiet:
- description: Set to V(false) to not suppress warnings.
- type: boolean
- default: true
- raw:
- description: Set to V(true) to return pre-processed JSON.
- type: boolean
- default: false
- requirements:
- - jc installed as a Python library (U(https://pypi.org/project/jc/))
-'''
+DOCUMENTATION = r"""
+name: jc
+short_description: Convert output of many shell commands and file-types to JSON
+version_added: 1.1.0
+author: Kelly Brazil (@kellyjonbrazil)
+description:
+ - Convert output of many shell commands and file-types to JSON.
+ - Uses the L(jc library,https://github.com/kellyjonbrazil/jc).
+positional: parser
+options:
+ _input:
+ description: The data to convert.
+ type: string
+ required: true
+ parser:
+ description:
+ - The correct parser for the input data.
+ - For example V(ifconfig).
+ - 'Note: use underscores instead of dashes (if any) in the parser module name.'
+ - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers.
+ type: string
+ required: true
+ quiet:
+ description: Set to V(false) to not suppress warnings.
+ type: boolean
+ default: true
+ raw:
+ description: Set to V(true) to return pre-processed JSON.
+ type: boolean
+ default: false
+requirements:
+ - jc installed as a Python library (U(https://pypi.org/project/jc/))
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install the prereqs of the jc filter (jc Python package) on the Ansible controller
delegate_to: localhost
ansible.builtin.pip:
@@ -68,13 +67,13 @@ EXAMPLES = '''
# "operating_system": "GNU/Linux",
# "processor": "x86_64"
# }
-'''
+"""
-RETURN = '''
- _value:
- description: The processed output.
- type: any
-'''
+RETURN = r"""
+_value:
+ description: The processed output.
+ type: any
+"""
from ansible.errors import AnsibleError, AnsibleFilterError
import importlib
diff --git a/plugins/filter/json_diff.yml b/plugins/filter/json_diff.yml
new file mode 100644
index 0000000000..a370564d7a
--- /dev/null
+++ b/plugins/filter/json_diff.yml
@@ -0,0 +1,56 @@
+---
+# Copyright (c) Stanislav Meduna (@numo68)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+DOCUMENTATION:
+ name: json_diff
+ short_description: Create a JSON patch by comparing two JSON files
+ description:
+ - This filter compares the input with the argument and computes a list of operations
+ that can be consumed by the P(community.general.json_patch_recipe#filter) to change the input
+ to the argument.
+ requirements:
+ - jsonpatch
+ version_added: 10.3.0
+ author:
+ - Stanislav Meduna (@numo68)
+ positional: target
+ options:
+ _input:
+ description: A list or a dictionary representing a source JSON object, or a string containing a JSON object.
+ type: raw
+ required: true
+ target:
+ description: A list or a dictionary representing a target JSON object, or a string containing a JSON object.
+ type: raw
+ required: true
+ seealso:
+ - name: RFC 6902
+ description: JavaScript Object Notation (JSON) Patch
+ link: https://datatracker.ietf.org/doc/html/rfc6902
+ - name: RFC 6901
+ description: JavaScript Object Notation (JSON) Pointer
+ link: https://datatracker.ietf.org/doc/html/rfc6901
+ - name: jsonpatch Python Package
+ description: A Python library for applying JSON patches
+ link: https://pypi.org/project/jsonpatch/
+
+RETURN:
+ _value:
+ description: A list of JSON patch operations to apply.
+ type: list
+ elements: dict
+
+EXAMPLES: |
+ - name: Compute a difference
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_diff(target) }}"
+ vars:
+ input: {"foo": 1, "bar":{"baz": 2}, "baw": [1, 2, 3], "hello": "day"}
+ target: {"foo": 1, "bar": {"baz": 2}, "baw": [1, 3], "baq": {"baz": 2}, "hello": "night"}
+ # => [
+ # {"op": "add", "path": "/baq", "value": {"baz": 2}},
+ # {"op": "remove", "path": "/baw/1"},
+ # {"op": "replace", "path": "/hello", "value": "night"}
+ # ]
diff --git a/plugins/filter/json_patch.py b/plugins/filter/json_patch.py
new file mode 100644
index 0000000000..4600bfaf92
--- /dev/null
+++ b/plugins/filter/json_patch.py
@@ -0,0 +1,195 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Stanislav Meduna (@numo68)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import annotations
+from json import loads
+from typing import TYPE_CHECKING
+from ansible.errors import AnsibleFilterError
+
+__metaclass__ = type # pylint: disable=C0103
+
+if TYPE_CHECKING:
+ from typing import Any, Callable, Union
+
+try:
+ import jsonpatch
+
+except ImportError as exc:
+ HAS_LIB = False
+ JSONPATCH_IMPORT_ERROR = exc
+else:
+ HAS_LIB = True
+ JSONPATCH_IMPORT_ERROR = None
+
+OPERATIONS_AVAILABLE = ["add", "copy", "move", "remove", "replace", "test"]
+OPERATIONS_NEEDING_FROM = ["copy", "move"]
+OPERATIONS_NEEDING_VALUE = ["add", "replace", "test"]
+
+
+class FilterModule:
+ """Filter plugin."""
+
+ def check_json_object(self, filter_name: str, object_name: str, inp: Any):
+ if isinstance(inp, (str, bytes, bytearray)):
+ try:
+ return loads(inp)
+ except Exception as e:
+ raise AnsibleFilterError(
+ f"{filter_name}: could not decode JSON from {object_name}: {e}"
+ ) from e
+
+ if not isinstance(inp, (list, dict)):
+ raise AnsibleFilterError(
+ f"{filter_name}: {object_name} is not dictionary, list or string"
+ )
+
+ return inp
+
+ def check_patch_arguments(self, filter_name: str, args: dict):
+
+ if "op" not in args or not isinstance(args["op"], str):
+ raise AnsibleFilterError(f"{filter_name}: 'op' argument is not a string")
+
+ if args["op"] not in OPERATIONS_AVAILABLE:
+ raise AnsibleFilterError(
+ f"{filter_name}: unsupported 'op' argument: {args['op']}"
+ )
+
+ if "path" not in args or not isinstance(args["path"], str):
+ raise AnsibleFilterError(f"{filter_name}: 'path' argument is not a string")
+
+ if args["op"] in OPERATIONS_NEEDING_FROM:
+ if "from" not in args:
+ raise AnsibleFilterError(
+ f"{filter_name}: 'from' argument missing for '{args['op']}' operation"
+ )
+ if not isinstance(args["from"], str):
+ raise AnsibleFilterError(
+ f"{filter_name}: 'from' argument is not a string"
+ )
+
+ def json_patch(
+ self,
+ inp: Union[str, list, dict, bytes, bytearray],
+ op: str,
+ path: str,
+ value: Any = None,
+ **kwargs: dict,
+ ) -> Any:
+
+ if not HAS_LIB:
+ raise AnsibleFilterError(
+ "You need to install 'jsonpatch' package prior to running 'json_patch' filter"
+ ) from JSONPATCH_IMPORT_ERROR
+
+ args = {"op": op, "path": path}
+ from_arg = kwargs.pop("from", None)
+ fail_test = kwargs.pop("fail_test", False)
+
+ if kwargs:
+ raise AnsibleFilterError(
+ f"json_patch: unexpected keywords arguments: {', '.join(sorted(kwargs))}"
+ )
+
+ if not isinstance(fail_test, bool):
+ raise AnsibleFilterError("json_patch: 'fail_test' argument is not a bool")
+
+ if op in OPERATIONS_NEEDING_VALUE:
+ args["value"] = value
+ if op in OPERATIONS_NEEDING_FROM and from_arg is not None:
+ args["from"] = from_arg
+
+ inp = self.check_json_object("json_patch", "input", inp)
+ self.check_patch_arguments("json_patch", args)
+
+ result = None
+
+ try:
+ result = jsonpatch.apply_patch(inp, [args])
+ except jsonpatch.JsonPatchTestFailed as e:
+ if fail_test:
+ raise AnsibleFilterError(
+ f"json_patch: test operation failed: {e}"
+ ) from e
+ else:
+ pass
+ except Exception as e:
+ raise AnsibleFilterError(f"json_patch: patch failed: {e}") from e
+
+ return result
+
+ def json_patch_recipe(
+ self,
+ inp: Union[str, list, dict, bytes, bytearray],
+ operations: list,
+ /,
+ fail_test: bool = False,
+ ) -> Any:
+
+ if not HAS_LIB:
+ raise AnsibleFilterError(
+ "You need to install 'jsonpatch' package prior to running 'json_patch_recipe' filter"
+ ) from JSONPATCH_IMPORT_ERROR
+
+ if not isinstance(operations, list):
+ raise AnsibleFilterError(
+ "json_patch_recipe: 'operations' needs to be a list"
+ )
+
+ if not isinstance(fail_test, bool):
+ raise AnsibleFilterError("json_patch: 'fail_test' argument is not a bool")
+
+ result = None
+
+ inp = self.check_json_object("json_patch_recipe", "input", inp)
+ for args in operations:
+ self.check_patch_arguments("json_patch_recipe", args)
+
+ try:
+ result = jsonpatch.apply_patch(inp, operations)
+ except jsonpatch.JsonPatchTestFailed as e:
+ if fail_test:
+ raise AnsibleFilterError(
+ f"json_patch_recipe: test operation failed: {e}"
+ ) from e
+ else:
+ pass
+ except Exception as e:
+ raise AnsibleFilterError(f"json_patch_recipe: patch failed: {e}") from e
+
+ return result
+
+ def json_diff(
+ self,
+ inp: Union[str, list, dict, bytes, bytearray],
+ target: Union[str, list, dict, bytes, bytearray],
+ ) -> list:
+
+ if not HAS_LIB:
+ raise AnsibleFilterError(
+ "You need to install 'jsonpatch' package prior to running 'json_diff' filter"
+ ) from JSONPATCH_IMPORT_ERROR
+
+ inp = self.check_json_object("json_diff", "input", inp)
+ target = self.check_json_object("json_diff", "target", target)
+
+ try:
+ result = list(jsonpatch.make_patch(inp, target))
+ except Exception as e:
+ raise AnsibleFilterError(f"JSON diff failed: {e}") from e
+
+ return result
+
+ def filters(self) -> dict[str, Callable[..., Any]]:
+ """Map filter plugin names to their functions.
+
+ Returns:
+ dict: The filter plugin functions.
+ """
+ return {
+ "json_patch": self.json_patch,
+ "json_patch_recipe": self.json_patch_recipe,
+ "json_diff": self.json_diff,
+ }
diff --git a/plugins/filter/json_patch.yml b/plugins/filter/json_patch.yml
new file mode 100644
index 0000000000..6fd411d6ff
--- /dev/null
+++ b/plugins/filter/json_patch.yml
@@ -0,0 +1,145 @@
+---
+# Copyright (c) Stanislav Meduna (@numo68)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+DOCUMENTATION:
+ name: json_patch
+ short_description: Apply a JSON-Patch (RFC 6902) operation to an object
+ description:
+ - This filter applies a single JSON patch operation and returns a modified object.
+ - If the operation is a test, the filter returns an ummodified object if the test
+ succeeded and a V(none) value otherwise.
+ requirements:
+ - jsonpatch
+ version_added: 10.3.0
+ author:
+ - Stanislav Meduna (@numo68)
+ positional: op, path, value
+ options:
+ _input:
+ description: A list or a dictionary representing a JSON object, or a string containing a JSON object.
+ type: raw
+ required: true
+ op:
+ description: Operation to perform (see L(RFC 6902, https://datatracker.ietf.org/doc/html/rfc6902)).
+ type: str
+ choices: [add, copy, move, remove, replace, test]
+ required: true
+ path:
+ description: JSON Pointer path to the target location (see L(RFC 6901, https://datatracker.ietf.org/doc/html/rfc6901)).
+ type: str
+ required: true
+ value:
+ description: Value to use in the operation. Ignored for O(op=copy), O(op=move), and O(op=remove).
+ type: raw
+ from:
+ description: The source location for the copy and move operation. Mandatory
+ for O(op=copy) and O(op=move), ignored otherwise.
+ type: str
+ fail_test:
+ description: If V(false), a failed O(op=test) will return V(none). If V(true), the filter
+ invocation will fail with an error.
+ type: bool
+ default: false
+ seealso:
+ - name: RFC 6902
+ description: JavaScript Object Notation (JSON) Patch
+ link: https://datatracker.ietf.org/doc/html/rfc6902
+ - name: RFC 6901
+ description: JavaScript Object Notation (JSON) Pointer
+ link: https://datatracker.ietf.org/doc/html/rfc6901
+ - name: jsonpatch Python Package
+ description: A Python library for applying JSON patches
+ link: https://pypi.org/project/jsonpatch/
+
+RETURN:
+ _value:
+ description: A modified object or V(none) if O(op=test), O(fail_test=false) and the test failed.
+ type: any
+ returned: always
+
+EXAMPLES: |
+ - name: Insert a new element into an array at a specified index
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('add', '/1', {'baz': 'qux'}) }}"
+ vars:
+ input: ["foo": { "one": 1 }, "bar": { "two": 2 }]
+ # => [{"foo": {"one": 1}}, {"baz": "qux"}, {"bar": {"two": 2}}]
+
+ - name: Insert a new key into a dictionary
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('add', '/bar/baz', 'qux') }}"
+ vars:
+ input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
+ # => {"foo": {"one": 1}, "bar": {"baz": "qux", "two": 2}}
+
+ - name: Input is a string
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('add', '/baz', 3) }}"
+ vars:
+ input: '{ "foo": { "one": 1 }, "bar": { "two": 2 } }'
+ # => {"foo": {"one": 1}, "bar": { "two": 2 }, "baz": 3}
+
+ - name: Existing key is replaced
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('add', '/bar', 'qux') }}"
+ vars:
+ input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
+ # => {"foo": {"one": 1}, "bar": "qux"}
+
+ - name: Escaping tilde as ~0 and slash as ~1 in the path
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('add', '/~0~1', 'qux') }}"
+ vars:
+ input: {}
+ # => {"~/": "qux"}
+
+ - name: Add at the end of the array
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('add', '/-', 4) }}"
+ vars:
+ input: [1, 2, 3]
+ # => [1, 2, 3, 4]
+
+ - name: Remove a key
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('remove', '/bar') }}"
+ vars:
+ input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
+ # => {"foo": {"one": 1} }
+
+ - name: Replace a value
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('replace', '/bar', 2) }}"
+ vars:
+ input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
+ # => {"foo": {"one": 1}, "bar": 2}
+
+ - name: Copy a value
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('copy', '/baz', from='/bar') }}"
+ vars:
+ input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
+ # => {"foo": {"one": 1}, "bar": { "two": 2 }, "baz": { "two": 2 }}
+
+ - name: Move a value
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('move', '/baz', from='/bar') }}"
+ vars:
+ input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
+ # => {"foo": {"one": 1}, "baz": { "two": 2 }}
+
+ - name: Successful test
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('test', '/bar/two', 2) | ternary('OK', 'Failed') }}"
+ vars:
+ input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
+ # => OK
+
+ - name: Unuccessful test
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch('test', '/bar/two', 9) | ternary('OK', 'Failed') }}"
+ vars:
+ input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
+ # => Failed
diff --git a/plugins/filter/json_patch_recipe.yml b/plugins/filter/json_patch_recipe.yml
new file mode 100644
index 0000000000..671600b941
--- /dev/null
+++ b/plugins/filter/json_patch_recipe.yml
@@ -0,0 +1,102 @@
+---
+# Copyright (c) Stanislav Meduna (@numo68)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+DOCUMENTATION:
+ name: json_patch_recipe
+ short_description: Apply JSON-Patch (RFC 6902) operations to an object
+ description:
+ - This filter sequentially applies JSON patch operations and returns a modified object.
+ - If there is a test operation in the list, the filter continues if the test
+ succeeded and returns a V(none) value otherwise.
+ requirements:
+ - jsonpatch
+ version_added: 10.3.0
+ author:
+ - Stanislav Meduna (@numo68)
+ positional: operations, fail_test
+ options:
+ _input:
+ description: A list or a dictionary representing a JSON object, or a string containing a JSON object.
+ type: raw
+ required: true
+ operations:
+ description: A list of JSON patch operations to apply.
+ type: list
+ elements: dict
+ required: true
+ suboptions:
+ op:
+ description: Operation to perform (see L(RFC 6902, https://datatracker.ietf.org/doc/html/rfc6902)).
+ type: str
+ choices: [add, copy, move, remove, replace, test]
+ required: true
+ path:
+ description: JSON Pointer path to the target location (see L(RFC 6901, https://datatracker.ietf.org/doc/html/rfc6901)).
+ type: str
+ required: true
+ value:
+ description: Value to use in the operation. Ignored for O(operations[].op=copy), O(operations[].op=move), and O(operations[].op=remove).
+ type: raw
+ from:
+ description: The source location for the copy and move operation. Mandatory
+ for O(operations[].op=copy) and O(operations[].op=move), ignored otherwise.
+ type: str
+ fail_test:
+ description: If V(false), a failed O(operations[].op=test) will return V(none). If V(true), the filter
+ invocation will fail with an error.
+ type: bool
+ default: false
+ seealso:
+ - name: RFC 6902
+ description: JavaScript Object Notation (JSON) Patch
+ link: https://datatracker.ietf.org/doc/html/rfc6902
+ - name: RFC 6901
+ description: JavaScript Object Notation (JSON) Pointer
+ link: https://datatracker.ietf.org/doc/html/rfc6901
+ - name: jsonpatch Python Package
+ description: A Python library for applying JSON patches
+ link: https://pypi.org/project/jsonpatch/
+
+RETURN:
+ _value:
+ description: A modified object or V(none) if O(operations[].op=test), O(fail_test=false)
+ and the test failed.
+ type: any
+ returned: always
+
+EXAMPLES: |
+ - name: Apply a series of operations
+ ansible.builtin.debug:
+ msg: "{{ input | community.general.json_patch_recipe(operations) }}"
+ vars:
+ input: {}
+ operations:
+ - op: 'add'
+ path: '/foo'
+ value: 1
+ - op: 'add'
+ path: '/bar'
+ value: []
+ - op: 'add'
+ path: '/bar/-'
+ value: 2
+ - op: 'add'
+ path: '/bar/0'
+ value: 1
+ - op: 'remove'
+ path: '/bar/0'
+ - op: 'move'
+ from: '/foo'
+ path: '/baz'
+ - op: 'copy'
+ from: '/baz'
+ path: '/bax'
+ - op: 'copy'
+ from: '/baz'
+ path: '/bay'
+ - op: 'replace'
+ path: '/baz'
+ value: [10, 20, 30]
+ # => {"bar":[2],"bax":1,"bay":1,"baz":[10,20,30]}
diff --git a/plugins/filter/json_query.py b/plugins/filter/json_query.py
index 9e8fa4ef2e..8976694a94 100644
--- a/plugins/filter/json_query.py
+++ b/plugins/filter/json_query.py
@@ -3,32 +3,31 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: json_query
- short_description: Select a single element or a data subset from a complex data structure
- description:
- - This filter lets you query a complex JSON structure and iterate over it using a loop structure.
- positional: expr
- options:
- _input:
- description:
- - The JSON data to query.
- type: any
- required: true
- expr:
- description:
- - The query expression.
- - See U(http://jmespath.org/examples.html) for examples.
- type: string
- required: true
- requirements:
- - jmespath
-'''
+DOCUMENTATION = r"""
+name: json_query
+short_description: Select a single element or a data subset from a complex data structure
+description:
+ - This filter lets you query a complex JSON structure and iterate over it using a loop structure.
+positional: expr
+options:
+ _input:
+ description:
+ - The JSON data to query.
+ type: any
+ required: true
+ expr:
+ description:
+ - The query expression.
+ - See U(http://jmespath.org/examples.html) for examples.
+ type: string
+ required: true
+requirements:
+ - jmespath
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Define data to work on in the examples below
ansible.builtin.set_fact:
domain_definition:
@@ -99,13 +98,13 @@ EXAMPLES = '''
msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
vars:
server_name_query: "domain.server[?contains(name,'server1')].port"
-'''
+"""
-RETURN = '''
- _value:
- description: The result of the query.
- type: any
-'''
+RETURN = r"""
+_value:
+ description: The result of the query.
+ type: any
+"""
from ansible.errors import AnsibleError, AnsibleFilterError
diff --git a/plugins/filter/keep_keys.py b/plugins/filter/keep_keys.py
index 97b706a950..98b34b4197 100644
--- a/plugins/filter/keep_keys.py
+++ b/plugins/filter/keep_keys.py
@@ -4,102 +4,101 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: keep_keys
- short_description: Keep specific keys from dictionaries in a list
- version_added: "9.1.0"
- author:
- - Vladimir Botka (@vbotka)
- - Felix Fontein (@felixfontein)
- description: This filter keeps only specified keys from a provided list of dictionaries.
- options:
- _input:
- description:
- - A list of dictionaries.
- - Top level keys must be strings.
- type: list
- elements: dictionary
- required: true
- target:
- description:
- - A single key or key pattern to keep, or a list of keys or keys patterns to keep.
- - If O(matching_parameter=regex) there must be exactly one pattern provided.
- type: raw
- required: true
- matching_parameter:
- description: Specify the matching option of target keys.
- type: str
- default: equal
- choices:
- equal: Matches keys of exactly one of the O(target) items.
- starts_with: Matches keys that start with one of the O(target) items.
- ends_with: Matches keys that end with one of the O(target) items.
- regex:
- - Matches keys that match the regular expresion provided in O(target).
- - In this case, O(target) must be a regex string or a list with single regex string.
-'''
+DOCUMENTATION = r"""
+name: keep_keys
+short_description: Keep specific keys from dictionaries in a list
+version_added: "9.1.0"
+author:
+ - Vladimir Botka (@vbotka)
+ - Felix Fontein (@felixfontein)
+description: This filter keeps only specified keys from a provided list of dictionaries.
+options:
+ _input:
+ description:
+ - A list of dictionaries.
+ - Top level keys must be strings.
+ type: list
+ elements: dictionary
+ required: true
+ target:
+ description:
+ - A single key or key pattern to keep, or a list of keys or keys patterns to keep.
+ - If O(matching_parameter=regex) there must be exactly one pattern provided.
+ type: raw
+ required: true
+ matching_parameter:
+ description: Specify the matching option of target keys.
+ type: str
+ default: equal
+ choices:
+ equal: Matches keys of exactly one of the O(target) items.
+ starts_with: Matches keys that start with one of the O(target) items.
+ ends_with: Matches keys that end with one of the O(target) items.
+ regex:
+ - Matches keys that match the regular expresion provided in O(target).
+ - In this case, O(target) must be a regex string or a list with single regex string.
+"""
-EXAMPLES = '''
- l:
+EXAMPLES = r"""
+- l:
- {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
- {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
# 1) By default match keys that equal any of the items in the target.
- t: [k0_x0, k1_x1]
+- t: [k0_x0, k1_x1]
r: "{{ l | community.general.keep_keys(target=t) }}"
# 2) Match keys that start with any of the items in the target.
- t: [k0, k1]
+- t: [k0, k1]
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}"
# 3) Match keys that end with any of the items in target.
- t: [x0, x1]
+- t: [x0, x1]
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}"
# 4) Match keys by the regex.
- t: ['^.*[01]_x.*$']
+- t: ['^.*[01]_x.*$']
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"
# 5) Match keys by the regex.
- t: '^.*[01]_x.*$'
+- t: '^.*[01]_x.*$'
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"
# The results of above examples 1-5 are all the same.
- r:
+- r:
- {k0_x0: A0, k1_x1: B0}
- {k0_x0: A1, k1_x1: B1}
# 6) By default match keys that equal the target.
- t: k0_x0
+- t: k0_x0
r: "{{ l | community.general.keep_keys(target=t) }}"
# 7) Match keys that start with the target.
- t: k0
+- t: k0
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}"
# 8) Match keys that end with the target.
- t: x0
+- t: x0
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}"
# 9) Match keys by the regex.
- t: '^.*0_x.*$'
+- t: '^.*0_x.*$'
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"
# The results of above examples 6-9 are all the same.
- r:
+- r:
- {k0_x0: A0}
- {k0_x0: A1}
-'''
+"""
-RETURN = '''
- _value:
- description: The list of dictionaries with selected keys.
- type: list
- elements: dictionary
-'''
+RETURN = r"""
+_value:
+ description: The list of dictionaries with selected keys.
+ type: list
+ elements: dictionary
+"""
from ansible_collections.community.general.plugins.plugin_utils.keys_filter import (
_keys_filter_params,
diff --git a/plugins/filter/lists.py b/plugins/filter/lists.py
index d16f955c22..707ec9f1fe 100644
--- a/plugins/filter/lists.py
+++ b/plugins/filter/lists.py
@@ -3,8 +3,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
from ansible.errors import AnsibleFilterError
from ansible.module_utils.common.collections import is_sequence
diff --git a/plugins/filter/lists_mergeby.py b/plugins/filter/lists_mergeby.py
index 0e47d50172..b15df2e089 100644
--- a/plugins/filter/lists_mergeby.py
+++ b/plugins/filter/lists_mergeby.py
@@ -3,68 +3,61 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: lists_mergeby
- short_description: Merge two or more lists of dictionaries by a given attribute
- version_added: 2.0.0
- author: Vladimir Botka (@vbotka)
- description:
- - Merge two or more lists by attribute O(index). Optional
- parameters O(recursive) and O(list_merge) control the merging of
- the nested dictionaries and lists.
- - The function C(merge_hash) from C(ansible.utils.vars) is used.
- - To learn details on how to use the parameters O(recursive) and
- O(list_merge) see Ansible User's Guide chapter "Using filters to
- manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the
- filter P(ansible.builtin.combine#filter).
+DOCUMENTATION = r"""
+name: lists_mergeby
+short_description: Merge two or more lists of dictionaries by a given attribute
+version_added: 2.0.0
+author: Vladimir Botka (@vbotka)
+description:
+ - Merge two or more lists by attribute O(index). Optional parameters O(recursive) and O(list_merge) control the merging
+ of the nested dictionaries and lists.
+ - The function C(merge_hash) from C(ansible.utils.vars) is used.
+ - To learn details on how to use the parameters O(recursive) and O(list_merge) see Ansible User's Guide chapter "Using filters
+ to manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the filter P(ansible.builtin.combine#filter).
+positional: another_list, index
+options:
+ _input:
+ description:
+ - A list of dictionaries, or a list of lists of dictionaries.
+ - The required type of the C(elements) is set to C(raw) because all elements of O(_input) can be either dictionaries
+ or lists.
+ type: list
+ elements: raw
+ required: true
+ another_list:
+ description:
+ - Another list of dictionaries, or a list of lists of dictionaries.
+ - This parameter can be specified multiple times.
+ type: list
+ elements: raw
+ index:
+ description:
+ - The dictionary key that must be present in every dictionary in every list that is used to merge the lists.
+ type: string
+ required: true
+ recursive:
+ description:
+ - Should the combine recursively merge nested dictionaries (hashes).
+ - B(Note:) It does not depend on the value of the C(hash_behaviour) setting in C(ansible.cfg).
+ type: boolean
+ default: false
+ list_merge:
+ description:
+ - Modifies the behaviour when the dictionaries (hashes) to merge contain arrays/lists.
+ type: string
+ default: replace
+ choices:
+ - replace
+ - keep
+ - append
+ - prepend
+ - append_rp
+ - prepend_rp
+"""
- positional: another_list, index
- options:
- _input:
- description:
- - A list of dictionaries, or a list of lists of dictionaries.
- - The required type of the C(elements) is set to C(raw)
- because all elements of O(_input) can be either dictionaries
- or lists.
- type: list
- elements: raw
- required: true
- another_list:
- description:
- - Another list of dictionaries, or a list of lists of dictionaries.
- - This parameter can be specified multiple times.
- type: list
- elements: raw
- index:
- description:
- - The dictionary key that must be present in every dictionary in every list that is used to
- merge the lists.
- type: string
- required: true
- recursive:
- description:
- - Should the combine recursively merge nested dictionaries (hashes).
- - "B(Note:) It does not depend on the value of the C(hash_behaviour) setting in C(ansible.cfg)."
- type: boolean
- default: false
- list_merge:
- description:
- - Modifies the behaviour when the dictionaries (hashes) to merge contain arrays/lists.
- type: string
- default: replace
- choices:
- - replace
- - keep
- - append
- - prepend
- - append_rp
- - prepend_rp
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# Some results below are manually formatted for better readability. The
# dictionaries' keys will be sorted alphabetically in real output.
@@ -193,14 +186,14 @@ EXAMPLES = '''
# r:
# - {index: a, foo: {x:1, y: 3, z: 4}}
# - {index: b, foo: [Y1, Y2]}
-'''
+"""
-RETURN = '''
- _value:
- description: The merged list.
- type: list
- elements: dictionary
-'''
+RETURN = r"""
+_value:
+ description: The merged list.
+ type: list
+ elements: dictionary
+"""
from ansible.errors import AnsibleFilterError
from ansible.module_utils.six import string_types
diff --git a/plugins/filter/random_mac.py b/plugins/filter/random_mac.py
index 662c62b07c..1ece58230c 100644
--- a/plugins/filter/random_mac.py
+++ b/plugins/filter/random_mac.py
@@ -4,28 +4,27 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Make coding more python3-ish
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: random_mac
- short_description: Generate a random MAC address
- description:
- - Generates random networking interfaces MAC addresses for a given prefix.
- options:
- _input:
- description: A string prefix to use as a basis for the random MAC generated.
- type: string
- required: true
- seed:
- description:
- - A randomization seed to initialize the process, used to get repeatable results.
- - If no seed is provided, a system random source such as C(/dev/urandom) is used.
- required: false
- type: string
-'''
+DOCUMENTATION = r"""
+name: random_mac
+short_description: Generate a random MAC address
+description:
+ - Generates random networking interfaces MAC addresses for a given prefix.
+options:
+ _input:
+ description: A string prefix to use as a basis for the random MAC generated.
+ type: string
+ required: true
+ seed:
+ description:
+ - A randomization seed to initialize the process, used to get repeatable results.
+ - If no seed is provided, a system random source such as C(/dev/urandom) is used.
+ required: false
+ type: string
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Random MAC given a prefix
ansible.builtin.debug:
msg: "{{ '52:54:00' | community.general.random_mac }}"
@@ -34,13 +33,13 @@ EXAMPLES = '''
- name: With a seed
ansible.builtin.debug:
msg: "{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}"
-'''
+"""
-RETURN = '''
- _value:
- description: The generated MAC.
- type: string
-'''
+RETURN = r"""
+_value:
+ description: The generated MAC.
+ type: string
+"""
import re
from random import Random, SystemRandom
diff --git a/plugins/filter/remove_keys.py b/plugins/filter/remove_keys.py
index 7a4d912d34..2058803138 100644
--- a/plugins/filter/remove_keys.py
+++ b/plugins/filter/remove_keys.py
@@ -4,102 +4,101 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: remove_keys
- short_description: Remove specific keys from dictionaries in a list
- version_added: "9.1.0"
- author:
- - Vladimir Botka (@vbotka)
- - Felix Fontein (@felixfontein)
- description: This filter removes only specified keys from a provided list of dictionaries.
- options:
- _input:
- description:
- - A list of dictionaries.
- - Top level keys must be strings.
- type: list
- elements: dictionary
- required: true
- target:
- description:
- - A single key or key pattern to remove, or a list of keys or keys patterns to remove.
- - If O(matching_parameter=regex) there must be exactly one pattern provided.
- type: raw
- required: true
- matching_parameter:
- description: Specify the matching option of target keys.
- type: str
- default: equal
- choices:
- equal: Matches keys of exactly one of the O(target) items.
- starts_with: Matches keys that start with one of the O(target) items.
- ends_with: Matches keys that end with one of the O(target) items.
- regex:
- - Matches keys that match the regular expresion provided in O(target).
- - In this case, O(target) must be a regex string or a list with single regex string.
-'''
+DOCUMENTATION = r"""
+name: remove_keys
+short_description: Remove specific keys from dictionaries in a list
+version_added: "9.1.0"
+author:
+ - Vladimir Botka (@vbotka)
+ - Felix Fontein (@felixfontein)
+description: This filter removes only specified keys from a provided list of dictionaries.
+options:
+ _input:
+ description:
+ - A list of dictionaries.
+ - Top level keys must be strings.
+ type: list
+ elements: dictionary
+ required: true
+ target:
+ description:
+ - A single key or key pattern to remove, or a list of keys or keys patterns to remove.
+ - If O(matching_parameter=regex) there must be exactly one pattern provided.
+ type: raw
+ required: true
+ matching_parameter:
+ description: Specify the matching option of target keys.
+ type: str
+ default: equal
+ choices:
+ equal: Matches keys of exactly one of the O(target) items.
+ starts_with: Matches keys that start with one of the O(target) items.
+ ends_with: Matches keys that end with one of the O(target) items.
+ regex:
+ - Matches keys that match the regular expresion provided in O(target).
+ - In this case, O(target) must be a regex string or a list with single regex string.
+"""
-EXAMPLES = '''
- l:
+EXAMPLES = r"""
+- l:
- {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
- {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
# 1) By default match keys that equal any of the items in the target.
- t: [k0_x0, k1_x1]
+- t: [k0_x0, k1_x1]
r: "{{ l | community.general.remove_keys(target=t) }}"
# 2) Match keys that start with any of the items in the target.
- t: [k0, k1]
+- t: [k0, k1]
r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}"
# 3) Match keys that end with any of the items in target.
- t: [x0, x1]
+- t: [x0, x1]
r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}"
# 4) Match keys by the regex.
- t: ['^.*[01]_x.*$']
+- t: ['^.*[01]_x.*$']
r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}"
# 5) Match keys by the regex.
- t: '^.*[01]_x.*$'
+- t: '^.*[01]_x.*$'
r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}"
# The results of above examples 1-5 are all the same.
- r:
+- r:
- {k2_x2: [C0], k3_x3: foo}
- {k2_x2: [C1], k3_x3: bar}
# 6) By default match keys that equal the target.
- t: k0_x0
+- t: k0_x0
r: "{{ l | community.general.remove_keys(target=t) }}"
# 7) Match keys that start with the target.
- t: k0
+- t: k0
r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}"
# 8) Match keys that end with the target.
- t: x0
+- t: x0
r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}"
# 9) Match keys by the regex.
- t: '^.*0_x.*$'
+- t: '^.*0_x.*$'
r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}"
# The results of above examples 6-9 are all the same.
- r:
+- r:
- {k1_x1: B0, k2_x2: [C0], k3_x3: foo}
- {k1_x1: B1, k2_x2: [C1], k3_x3: bar}
-'''
+"""
-RETURN = '''
- _value:
- description: The list of dictionaries with selected keys removed.
- type: list
- elements: dictionary
-'''
+RETURN = r"""
+_value:
+ description: The list of dictionaries with selected keys removed.
+ type: list
+ elements: dictionary
+"""
from ansible_collections.community.general.plugins.plugin_utils.keys_filter import (
_keys_filter_params,
diff --git a/plugins/filter/replace_keys.py b/plugins/filter/replace_keys.py
index 70b264eba6..d47468bd3c 100644
--- a/plugins/filter/replace_keys.py
+++ b/plugins/filter/replace_keys.py
@@ -4,132 +4,131 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: replace_keys
- short_description: Replace specific keys in a list of dictionaries
- version_added: "9.1.0"
- author:
- - Vladimir Botka (@vbotka)
- - Felix Fontein (@felixfontein)
- description: This filter replaces specified keys in a provided list of dictionaries.
- options:
- _input:
+DOCUMENTATION = r"""
+name: replace_keys
+short_description: Replace specific keys in a list of dictionaries
+version_added: "9.1.0"
+author:
+ - Vladimir Botka (@vbotka)
+ - Felix Fontein (@felixfontein)
+description: This filter replaces specified keys in a provided list of dictionaries.
+options:
+ _input:
+ description:
+ - A list of dictionaries.
+ - Top level keys must be strings.
+ type: list
+ elements: dictionary
+ required: true
+ target:
+ description:
+ - A list of dictionaries with attributes C(before) and C(after).
+ - The value of O(target[].after) replaces key matching O(target[].before).
+ type: list
+ elements: dictionary
+ required: true
+ suboptions:
+ before:
description:
- - A list of dictionaries.
- - Top level keys must be strings.
- type: list
- elements: dictionary
- required: true
- target:
- description:
- - A list of dictionaries with attributes C(before) and C(after).
- - The value of O(target[].after) replaces key matching O(target[].before).
- type: list
- elements: dictionary
- required: true
- suboptions:
- before:
- description:
- - A key or key pattern to change.
- - The interpretation of O(target[].before) depends on O(matching_parameter).
- - For a key that matches multiple O(target[].before)s, the B(first) matching O(target[].after) will be used.
- type: str
- after:
- description: A matching key change to.
- type: str
- matching_parameter:
- description: Specify the matching option of target keys.
+ - A key or key pattern to change.
+ - The interpretation of O(target[].before) depends on O(matching_parameter).
+ - For a key that matches multiple O(target[].before)s, the B(first) matching O(target[].after) will be used.
type: str
- default: equal
- choices:
- equal: Matches keys of exactly one of the O(target[].before) items.
- starts_with: Matches keys that start with one of the O(target[].before) items.
- ends_with: Matches keys that end with one of the O(target[].before) items.
- regex: Matches keys that match one of the regular expressions provided in O(target[].before).
-'''
+ after:
+ description: A matching key change to.
+ type: str
+ matching_parameter:
+ description: Specify the matching option of target keys.
+ type: str
+ default: equal
+ choices:
+ equal: Matches keys of exactly one of the O(target[].before) items.
+ starts_with: Matches keys that start with one of the O(target[].before) items.
+ ends_with: Matches keys that end with one of the O(target[].before) items.
+ regex: Matches keys that match one of the regular expressions provided in O(target[].before).
+"""
-EXAMPLES = '''
- l:
+EXAMPLES = r"""
+- l:
- {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
- {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
# 1) By default, replace keys that are equal any of the attributes before.
- t:
+- t:
- {before: k0_x0, after: a0}
- {before: k1_x1, after: a1}
r: "{{ l | community.general.replace_keys(target=t) }}"
# 2) Replace keys that starts with any of the attributes before.
- t:
+- t:
- {before: k0, after: a0}
- {before: k1, after: a1}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}"
# 3) Replace keys that ends with any of the attributes before.
- t:
+- t:
- {before: x0, after: a0}
- {before: x1, after: a1}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='ends_with') }}"
# 4) Replace keys that match any regex of the attributes before.
- t:
+- t:
- {before: "^.*0_x.*$", after: a0}
- {before: "^.*1_x.*$", after: a1}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"
# The results of above examples 1-4 are all the same.
- r:
+- r:
- {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo}
- {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar}
# 5) If more keys match the same attribute before the last one will be used.
- t:
+- t:
- {before: "^.*_x.*$", after: X}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"
# gives
- r:
+- r:
- X: foo
- X: bar
# 6) If there are items with equal attribute before the first one will be used.
- t:
+- t:
- {before: "^.*_x.*$", after: X}
- {before: "^.*_x.*$", after: Y}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"
# gives
- r:
+- r:
- X: foo
- X: bar
# 7) If there are more matches for a key the first one will be used.
- l:
+- l:
- {aaa1: A, bbb1: B, ccc1: C}
- {aaa2: D, bbb2: E, ccc2: F}
- t:
+- t:
- {before: a, after: X}
- {before: aa, after: Y}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}"
# gives
- r:
+- r:
- {X: A, bbb1: B, ccc1: C}
- {X: D, bbb2: E, ccc2: F}
-'''
+"""
-RETURN = '''
- _value:
- description: The list of dictionaries with replaced keys.
- type: list
- elements: dictionary
-'''
+RETURN = r"""
+_value:
+ description: The list of dictionaries with replaced keys.
+ type: list
+ elements: dictionary
+"""
from ansible_collections.community.general.plugins.plugin_utils.keys_filter import (
_keys_filter_params,
diff --git a/plugins/filter/reveal_ansible_type.py b/plugins/filter/reveal_ansible_type.py
index 916aaff930..36fcba3df2 100644
--- a/plugins/filter/reveal_ansible_type.py
+++ b/plugins/filter/reveal_ansible_type.py
@@ -3,119 +3,118 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: reveal_ansible_type
- short_description: Return input type
- version_added: "9.2.0"
- author: Vladimir Botka (@vbotka)
- description: This filter returns input type.
- options:
- _input:
- description: Input data.
- type: raw
- required: true
- alias:
- description: Data type aliases.
- default: {}
- type: dictionary
-'''
+DOCUMENTATION = r"""
+name: reveal_ansible_type
+short_description: Return input type
+version_added: "9.2.0"
+author: Vladimir Botka (@vbotka)
+description: This filter returns input type.
+options:
+ _input:
+ description: Input data.
+ type: raw
+ required: true
+ alias:
+ description: Data type aliases.
+ default: {}
+ type: dictionary
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Substitution converts str to AnsibleUnicode
# -------------------------------------------
# String. AnsibleUnicode.
-data: "abc"
-result: '{{ data | community.general.reveal_ansible_type }}'
+- data: "abc"
+ result: '{{ data | community.general.reveal_ansible_type }}'
# result => AnsibleUnicode
# String. AnsibleUnicode alias str.
-alias: {"AnsibleUnicode": "str"}
-data: "abc"
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+- alias: {"AnsibleUnicode": "str"}
+ data: "abc"
+ result: '{{ data | community.general.reveal_ansible_type(alias) }}'
# result => str
# List. All items are AnsibleUnicode.
-data: ["a", "b", "c"]
-result: '{{ data | community.general.reveal_ansible_type }}'
+- data: ["a", "b", "c"]
+ result: '{{ data | community.general.reveal_ansible_type }}'
# result => list[AnsibleUnicode]
# Dictionary. All keys are AnsibleUnicode. All values are AnsibleUnicode.
-data: {"a": "foo", "b": "bar", "c": "baz"}
-result: '{{ data | community.general.reveal_ansible_type }}'
+- data: {"a": "foo", "b": "bar", "c": "baz"}
+ result: '{{ data | community.general.reveal_ansible_type }}'
# result => dict[AnsibleUnicode, AnsibleUnicode]
# No substitution and no alias. Type of strings is str
# ----------------------------------------------------
# String
-result: '{{ "abc" | community.general.reveal_ansible_type }}'
+- result: '{{ "abc" | community.general.reveal_ansible_type }}'
# result => str
# Integer
-result: '{{ 123 | community.general.reveal_ansible_type }}'
+- result: '{{ 123 | community.general.reveal_ansible_type }}'
# result => int
# Float
-result: '{{ 123.45 | community.general.reveal_ansible_type }}'
+- result: '{{ 123.45 | community.general.reveal_ansible_type }}'
# result => float
# Boolean
-result: '{{ true | community.general.reveal_ansible_type }}'
+- result: '{{ true | community.general.reveal_ansible_type }}'
# result => bool
# List. All items are strings.
-result: '{{ ["a", "b", "c"] | community.general.reveal_ansible_type }}'
+- result: '{{ ["a", "b", "c"] | community.general.reveal_ansible_type }}'
# result => list[str]
# List of dictionaries.
-result: '{{ [{"a": 1}, {"b": 2}] | community.general.reveal_ansible_type }}'
+- result: '{{ [{"a": 1}, {"b": 2}] | community.general.reveal_ansible_type }}'
# result => list[dict]
# Dictionary. All keys are strings. All values are integers.
-result: '{{ {"a": 1} | community.general.reveal_ansible_type }}'
+- result: '{{ {"a": 1} | community.general.reveal_ansible_type }}'
# result => dict[str, int]
# Dictionary. All keys are strings. All values are integers.
-result: '{{ {"a": 1, "b": 2} | community.general.reveal_ansible_type }}'
+- result: '{{ {"a": 1, "b": 2} | community.general.reveal_ansible_type }}'
# result => dict[str, int]
# Type of strings is AnsibleUnicode or str
# ----------------------------------------
# Dictionary. The keys are integers or strings. All values are strings.
-alias: {"AnsibleUnicode": "str"}
-data: {1: 'a', 'b': 'b'}
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+- alias: {"AnsibleUnicode": "str"}
+ data: {1: 'a', 'b': 'b'}
+ result: '{{ data | community.general.reveal_ansible_type(alias) }}'
# result => dict[int|str, str]
# Dictionary. All keys are integers. All values are keys.
-alias: {"AnsibleUnicode": "str"}
-data: {1: 'a', 2: 'b'}
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+- alias: {"AnsibleUnicode": "str"}
+ data: {1: 'a', 2: 'b'}
+ result: '{{ data | community.general.reveal_ansible_type(alias) }}'
# result => dict[int, str]
# Dictionary. All keys are strings. Multiple types values.
-alias: {"AnsibleUnicode": "str"}
-data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': True, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+- alias: {"AnsibleUnicode": "str"}
+ data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': true, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
+ result: '{{ data | community.general.reveal_ansible_type(alias) }}'
# result => dict[str, bool|dict|float|int|list|str]
# List. Multiple types items.
-alias: {"AnsibleUnicode": "str"}
-data: [1, 2, 1.1, 'abc', True, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+- alias: {"AnsibleUnicode": "str"}
+ data: [1, 2, 1.1, 'abc', true, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
+ result: '{{ data | community.general.reveal_ansible_type(alias) }}'
# result => list[bool|dict|float|int|list|str]
-'''
+"""
-RETURN = '''
- _value:
- description: Type of the data.
- type: str
-'''
+RETURN = r"""
+_value:
+ description: Type of the data.
+ type: str
+"""
from ansible_collections.community.general.plugins.plugin_utils.ansible_type import _ansible_type
diff --git a/plugins/filter/time.py b/plugins/filter/time.py
index 25970cd260..e8a867a1fe 100644
--- a/plugins/filter/time.py
+++ b/plugins/filter/time.py
@@ -3,8 +3,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
import re
from ansible.errors import AnsibleFilterError
diff --git a/plugins/filter/to_days.yml b/plugins/filter/to_days.yml
index b5f6424fa3..c76697f1ee 100644
--- a/plugins/filter/to_days.yml
+++ b/plugins/filter/to_days.yml
@@ -5,7 +5,7 @@
DOCUMENTATION:
name: to_days
- short_description: Converte a duration string to days
+ short_description: Converts a duration string to days
version_added: 0.2.0
description:
- Parse a human readable time duration string and convert to days.
diff --git a/plugins/filter/to_hours.yml b/plugins/filter/to_hours.yml
index 353fdfc317..520740897b 100644
--- a/plugins/filter/to_hours.yml
+++ b/plugins/filter/to_hours.yml
@@ -5,7 +5,7 @@
DOCUMENTATION:
name: to_hours
- short_description: Converte a duration string to hours
+ short_description: Converts a duration string to hours
version_added: 0.2.0
description:
- Parse a human readable time duration string and convert to hours.
diff --git a/plugins/filter/to_ini.py b/plugins/filter/to_ini.py
index bdf2dde270..4be1a684e7 100644
--- a/plugins/filter/to_ini.py
+++ b/plugins/filter/to_ini.py
@@ -4,36 +4,36 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
+from __future__ import annotations
-DOCUMENTATION = r'''
- name: to_ini
- short_description: Converts a dictionary to the INI file format
- version_added: 8.2.0
- author: Steffen Scheib (@sscheib)
- description:
- - Converts a dictionary to the INI file format.
- options:
- _input:
- description: The dictionary that should be converted to the INI format.
- type: dictionary
- required: true
-'''
+DOCUMENTATION = r"""
+name: to_ini
+short_description: Converts a dictionary to the INI file format
+version_added: 8.2.0
+author: Steffen Scheib (@sscheib)
+description:
+ - Converts a dictionary to the INI file format.
+options:
+ _input:
+ description: The dictionary that should be converted to the INI format.
+ type: dictionary
+ required: true
+"""
-EXAMPLES = r'''
- - name: Define a dictionary
- ansible.builtin.set_fact:
- my_dict:
- section_name:
- key_name: 'key value'
+EXAMPLES = r"""
+- name: Define a dictionary
+ ansible.builtin.set_fact:
+ my_dict:
+ section_name:
+ key_name: 'key value'
- another_section:
- connection: 'ssh'
+ another_section:
+ connection: 'ssh'
- - name: Write dictionary to INI file
- ansible.builtin.copy:
- dest: /tmp/test.ini
- content: '{{ my_dict | community.general.to_ini }}'
+- name: Write dictionary to INI file
+ ansible.builtin.copy:
+ dest: /tmp/test.ini
+ content: '{{ my_dict | community.general.to_ini }}'
# /tmp/test.ini will look like this:
# [section_name]
@@ -41,22 +41,19 @@ EXAMPLES = r'''
#
# [another_section]
# connection = ssh
-'''
+"""
-RETURN = r'''
- _value:
- description: A string formatted as INI file.
- type: string
-'''
+RETURN = r"""
+_value:
+ description: A string formatted as INI file.
+ type: string
+"""
-__metaclass__ = type
-
from ansible.errors import AnsibleFilterError
from ansible.module_utils.common._collections_compat import Mapping
from ansible.module_utils.six.moves import StringIO
from ansible.module_utils.six.moves.configparser import ConfigParser
-from ansible.module_utils.common.text.converters import to_native
class IniParser(ConfigParser):
@@ -79,7 +76,7 @@ def to_ini(obj):
ini_parser.read_dict(obj)
except Exception as ex:
raise AnsibleFilterError('to_ini failed to parse given dict:'
- f'{to_native(ex)}', orig_exc=ex)
+ f'{ex}', orig_exc=ex)
# catching empty dicts
if obj == dict():
diff --git a/plugins/filter/to_milliseconds.yml b/plugins/filter/to_milliseconds.yml
index 19ed02438c..f25bd86623 100644
--- a/plugins/filter/to_milliseconds.yml
+++ b/plugins/filter/to_milliseconds.yml
@@ -5,7 +5,7 @@
DOCUMENTATION:
name: to_milliseconds
- short_description: Converte a duration string to milliseconds
+ short_description: Converts a duration string to milliseconds
version_added: 0.2.0
description:
- Parse a human readable time duration string and convert to milliseconds.
diff --git a/plugins/filter/to_minutes.yml b/plugins/filter/to_minutes.yml
index e8d6f763a8..924fb6feb3 100644
--- a/plugins/filter/to_minutes.yml
+++ b/plugins/filter/to_minutes.yml
@@ -5,7 +5,7 @@
DOCUMENTATION:
name: to_minutes
- short_description: Converte a duration string to minutes
+ short_description: Converts a duration string to minutes
version_added: 0.2.0
description:
- Parse a human readable time duration string and convert to minutes.
diff --git a/plugins/filter/to_months.yml b/plugins/filter/to_months.yml
index 1f1cd661d8..09e9c38b5d 100644
--- a/plugins/filter/to_months.yml
+++ b/plugins/filter/to_months.yml
@@ -5,7 +5,7 @@
DOCUMENTATION:
name: to_months
- short_description: Converte a duration string to months
+ short_description: Convert a duration string to months
version_added: 0.2.0
description:
- Parse a human readable time duration string and convert to months.
diff --git a/plugins/filter/to_seconds.yml b/plugins/filter/to_seconds.yml
index d858e062a3..49b69d6d69 100644
--- a/plugins/filter/to_seconds.yml
+++ b/plugins/filter/to_seconds.yml
@@ -5,7 +5,7 @@
DOCUMENTATION:
name: to_seconds
- short_description: Converte a duration string to seconds
+ short_description: Converts a duration string to seconds
version_added: 0.2.0
description:
- Parse a human readable time duration string and convert to seconds.
diff --git a/plugins/filter/to_time_unit.yml b/plugins/filter/to_time_unit.yml
index bda124865c..256ca573f4 100644
--- a/plugins/filter/to_time_unit.yml
+++ b/plugins/filter/to_time_unit.yml
@@ -5,7 +5,7 @@
DOCUMENTATION:
name: to_time_unit
- short_description: Converte a duration string to the given time unit
+ short_description: Converts a duration string to the given time unit
version_added: 0.2.0
description:
- Parse a human readable time duration string and convert to the given time unit.
diff --git a/plugins/filter/to_weeks.yml b/plugins/filter/to_weeks.yml
index 7bf31bb65c..750e77c378 100644
--- a/plugins/filter/to_weeks.yml
+++ b/plugins/filter/to_weeks.yml
@@ -5,7 +5,7 @@
DOCUMENTATION:
name: to_weeks
- short_description: Converte a duration string to weeks
+ short_description: Converts a duration string to weeks
version_added: 0.2.0
description:
- Parse a human readable time duration string and convert to weeks.
diff --git a/plugins/filter/to_years.yml b/plugins/filter/to_years.yml
index 33c85a3ece..62f282a8b6 100644
--- a/plugins/filter/to_years.yml
+++ b/plugins/filter/to_years.yml
@@ -5,7 +5,7 @@
DOCUMENTATION:
name: to_years
- short_description: Converte a duration string to years
+ short_description: Converts a duration string to years
version_added: 0.2.0
description:
- Parse a human readable time duration string and convert to years.
diff --git a/plugins/filter/unicode_normalize.py b/plugins/filter/unicode_normalize.py
index dfbf20c573..e897bb9cee 100644
--- a/plugins/filter/unicode_normalize.py
+++ b/plugins/filter/unicode_normalize.py
@@ -4,48 +4,47 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: unicode_normalize
- short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms
- version_added: 3.7.0
- author: Andrew Pantuso (@Ajpantuso)
- description:
- - Normalizes unicode strings to facilitate comparison of characters with normalized forms.
- positional: form
- options:
- _input:
- description: A unicode string.
- type: string
- required: true
- form:
- description:
- - The normal form to use.
- - See U(https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) for details.
- type: string
- default: NFC
- choices:
- - NFC
- - NFD
- - NFKC
- - NFKD
-'''
+DOCUMENTATION = r"""
+name: unicode_normalize
+short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms
+version_added: 3.7.0
+author: Andrew Pantuso (@Ajpantuso)
+description:
+ - Normalizes unicode strings to facilitate comparison of characters with normalized forms.
+positional: form
+options:
+ _input:
+ description: A unicode string.
+ type: string
+ required: true
+ form:
+ description:
+ - The normal form to use.
+ - See U(https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) for details.
+ type: string
+ default: NFC
+ choices:
+ - NFC
+ - NFD
+ - NFKC
+ - NFKD
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Normalize unicode string
ansible.builtin.set_fact:
dictionary: "{{ 'ä' | community.general.unicode_normalize('NFKD') }}"
# The resulting string has length 2: one letter is 'a', the other
# the diacritic combiner.
-'''
+"""
-RETURN = '''
- _value:
- description: The normalized unicode string of the specified normal form.
- type: string
-'''
+RETURN = r"""
+_value:
+ description: The normalized unicode string of the specified normal form.
+ type: string
+"""
from unicodedata import normalize
diff --git a/plugins/filter/version_sort.py b/plugins/filter/version_sort.py
index 09eedbf563..f3fb30035a 100644
--- a/plugins/filter/version_sort.py
+++ b/plugins/filter/version_sort.py
@@ -3,37 +3,36 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
-DOCUMENTATION = '''
- name: version_sort
- short_description: Sort a list according to version order instead of pure alphabetical one
- version_added: 2.2.0
- author: Eric L. (@ericzolf)
- description:
- - Sort a list according to version order instead of pure alphabetical one.
- options:
- _input:
- description: A list of strings to sort.
- type: list
- elements: string
- required: true
-'''
+DOCUMENTATION = r"""
+name: version_sort
+short_description: Sort a list according to version order instead of pure alphabetical one
+version_added: 2.2.0
+author: Eric L. (@ericzolf)
+description:
+ - Sort a list according to version order instead of pure alphabetical one.
+options:
+ _input:
+ description: A list of strings to sort.
+ type: list
+ elements: string
+ required: true
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Convert list of tuples into dictionary
ansible.builtin.set_fact:
dictionary: "{{ ['2.1', '2.10', '2.9'] | community.general.version_sort }}"
# Result is ['2.1', '2.9', '2.10']
-'''
+"""
-RETURN = '''
- _value:
- description: The list of strings sorted by version.
- type: list
- elements: string
-'''
+RETURN = r"""
+_value:
+ description: The list of strings sorted by version.
+ type: list
+ elements: string
+"""
from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
diff --git a/plugins/inventory/cobbler.py b/plugins/inventory/cobbler.py
index 664380da8f..4546bf8d6c 100644
--- a/plugins/inventory/cobbler.py
+++ b/plugins/inventory/cobbler.py
@@ -3,8 +3,7 @@
# Copyright (c) 2020 Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
DOCUMENTATION = '''
author: Orion Poplawski (@opoplawski)
@@ -20,7 +19,7 @@ DOCUMENTATION = '''
- inventory_cache
options:
plugin:
- description: The name of this plugin, it should always be set to V(community.general.cobbler) for this plugin to recognize it as it's own.
+ description: The name of this plugin, it should always be set to V(community.general.cobbler) for this plugin to recognize it as its own.
type: string
required: true
choices: [ 'cobbler', 'community.general.cobbler' ]
@@ -118,7 +117,6 @@ password: secure
import socket
from ansible.errors import AnsibleError
-from ansible.module_utils.common.text.converters import to_text
from ansible.plugins.inventory import BaseInventoryPlugin, Cacheable, to_safe_group_name
from ansible.module_utils.six import text_type
@@ -160,7 +158,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
raise AnsibleError('Could not import xmlrpc client library')
if self.connection is None:
- self.display.vvvv('Connecting to %s\n' % self.cobbler_url)
+ self.display.vvvv(f'Connecting to {self.cobbler_url}\n')
self.connection = xmlrpc_client.Server(self.cobbler_url, allow_none=True)
self.token = None
if self.get_option('user') is not None:
@@ -211,7 +209,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
return self._cache[self.cache_key]['systems']
def _add_safe_group_name(self, group, child=None):
- group_name = self.inventory.add_group(to_safe_group_name('%s%s' % (self.get_option('group_prefix'), group.lower().replace(" ", ""))))
+ group_name = self.inventory.add_group(to_safe_group_name(f"{self.get_option('group_prefix')}{group.lower().replace(' ', '')}"))
if child is not None:
self.inventory.add_child(group_name, child)
return group_name
@@ -243,16 +241,16 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
for profile in self._get_profiles():
if profile['parent']:
- self.display.vvvv('Processing profile %s with parent %s\n' % (profile['name'], profile['parent']))
+ self.display.vvvv(f"Processing profile {profile['name']} with parent {profile['parent']}\n")
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)
+ self.display.vvvv(f'Added profile parent group {parent_group_name}\n')
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.display.vvvv(f'Added profile group {group_name}\n')
self.inventory.add_child(parent_group_name, group_name)
else:
- self.display.vvvv('Processing profile %s without parent\n' % profile['name'])
+ self.display.vvvv(f"Processing profile {profile['name']} without parent\n")
# Create a hierarchy of profile names
profile_elements = profile['name'].split('-')
i = 0
@@ -260,12 +258,12 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
profile_group = '-'.join(profile_elements[0:i + 1])
profile_group_child = '-'.join(profile_elements[0:i + 2])
if self._exclude_profile(profile_group):
- self.display.vvvv('Excluding profile %s\n' % profile_group)
+ self.display.vvvv(f'Excluding profile {profile_group}\n')
break
group_name = self._add_safe_group_name(profile_group)
- self.display.vvvv('Added profile group %s\n' % group_name)
+ self.display.vvvv(f'Added profile group {group_name}\n')
child_group_name = self._add_safe_group_name(profile_group_child)
- self.display.vvvv('Added profile child group %s to %s\n' % (child_group_name, group_name))
+ self.display.vvvv(f'Added profile child group {child_group_name} to {group_name}\n')
self.inventory.add_child(group_name, child_group_name)
i = i + 1
@@ -273,7 +271,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
self.group = to_safe_group_name(self.get_option('group'))
if self.group is not None and self.group != '':
self.inventory.add_group(self.group)
- self.display.vvvv('Added site group %s\n' % self.group)
+ self.display.vvvv(f'Added site group {self.group}\n')
ip_addresses = {}
ipv6_addresses = {}
@@ -286,14 +284,14 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
interfaces = host['interfaces']
if set(host['mgmt_classes']) & set(self.include_mgmt_classes):
- self.display.vvvv('Including host %s in mgmt_classes %s\n' % (host['name'], host['mgmt_classes']))
+ self.display.vvvv(f"Including host {host['name']} in mgmt_classes {host['mgmt_classes']}\n")
else:
if self._exclude_profile(host['profile']):
- self.display.vvvv('Excluding host %s in profile %s\n' % (host['name'], host['profile']))
+ self.display.vvvv(f"Excluding host {host['name']} in profile {host['profile']}\n")
continue
if set(host['mgmt_classes']) & set(self.exclude_mgmt_classes):
- self.display.vvvv('Excluding host %s in mgmt_classes %s\n' % (host['name'], host['mgmt_classes']))
+ self.display.vvvv(f"Excluding host {host['name']} in mgmt_classes {host['mgmt_classes']}\n")
continue
# hostname is often empty for non-static IP hosts
@@ -303,21 +301,21 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
this_dns_name = ivalue.get('dns_name', None)
if this_dns_name is not None and this_dns_name != "":
hostname = make_unsafe(this_dns_name)
- self.display.vvvv('Set hostname to %s from %s\n' % (hostname, iname))
+ self.display.vvvv(f'Set hostname to {hostname} from {iname}\n')
if hostname == '':
- self.display.vvvv('Cannot determine hostname for host %s, skipping\n' % host['name'])
+ self.display.vvvv(f"Cannot determine hostname for host {host['name']}, skipping\n")
continue
self.inventory.add_host(hostname)
- self.display.vvvv('Added host %s hostname %s\n' % (host['name'], hostname))
+ self.display.vvvv(f"Added host {host['name']} hostname {hostname}\n")
# Add host to profile group
if host['profile'] != '':
group_name = self._add_safe_group_name(host['profile'], child=hostname)
- self.display.vvvv('Added host %s to profile group %s\n' % (hostname, group_name))
+ self.display.vvvv(f'Added host {hostname} to profile group {group_name}\n')
else:
- self.display.warning('Host %s has an empty profile\n' % (hostname))
+ self.display.warning(f'Host {hostname} has an empty profile\n')
# Add host to groups specified by group_by fields
for group_by in self.group_by:
@@ -327,7 +325,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
groups = [host[group_by]] if isinstance(host[group_by], str) else host[group_by]
for group in groups:
group_name = self._add_safe_group_name(group, child=hostname)
- self.display.vvvv('Added host %s to group_by %s group %s\n' % (hostname, group_by, group_name))
+ self.display.vvvv(f'Added host {hostname} to group_by {group_by} group {group_name}\n')
# Add to group for this inventory
if self.group is not None:
@@ -377,7 +375,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
try:
self.inventory.set_variable(hostname, 'cobbler', make_unsafe(host))
except ValueError as e:
- self.display.warning("Could not set host info for %s: %s" % (hostname, to_text(e)))
+ self.display.warning(f"Could not set host info for {hostname}: {e}")
if self.get_option('want_ip_addresses'):
self.inventory.set_variable(self.group, 'cobbler_ipv4_addresses', make_unsafe(ip_addresses))
diff --git a/plugins/inventory/gitlab_runners.py b/plugins/inventory/gitlab_runners.py
index bd29e8d310..961f20444b 100644
--- a/plugins/inventory/gitlab_runners.py
+++ b/plugins/inventory/gitlab_runners.py
@@ -4,9 +4,8 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
+from __future__ import annotations
-__metaclass__ = type
DOCUMENTATION = '''
name: gitlab_runners
@@ -22,7 +21,7 @@ DOCUMENTATION = '''
- Uses a YAML configuration file gitlab_runners.[yml|yaml].
options:
plugin:
- description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as it's own.
+ description: The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as its own.
type: str
required: true
choices:
@@ -58,10 +57,12 @@ DOCUMENTATION = '''
'''
EXAMPLES = '''
+---
# gitlab_runners.yml
plugin: community.general.gitlab_runners
host: https://gitlab.com
+---
# Example using constructed features to create groups and set ansible_host
plugin: community.general.gitlab_runners
host: https://gitlab.com
@@ -81,7 +82,6 @@ keyed_groups:
'''
from ansible.errors import AnsibleError, AnsibleParserError
-from ansible.module_utils.common.text.converters import to_native
from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
from ansible_collections.community.general.plugins.plugin_utils.unsafe import make_unsafe
@@ -124,7 +124,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
# Create groups based on variable values and add the corresponding hosts to it
self._add_host_to_keyed_groups(self.get_option('keyed_groups'), host_attrs, host, strict=strict)
except Exception as e:
- raise AnsibleParserError('Unable to fetch hosts from GitLab API, this was the original exception: %s' % to_native(e))
+ raise AnsibleParserError(f'Unable to fetch hosts from GitLab API, this was the original exception: {e}')
def verify_file(self, path):
"""Return the possibly of a file being consumable by this plugin."""
diff --git a/plugins/inventory/icinga2.py b/plugins/inventory/icinga2.py
index d1f2bc617f..7ee87df065 100644
--- a/plugins/inventory/icinga2.py
+++ b/plugins/inventory/icinga2.py
@@ -3,9 +3,8 @@
# Copyright (c) 2021 Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
+from __future__ import annotations
-__metaclass__ = type
DOCUMENTATION = '''
name: icinga2
@@ -141,7 +140,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
'User-Agent': "ansible-icinga2-inv",
'Accept': "application/json",
}
- api_status_url = self.icinga2_url + "/status"
+ api_status_url = f"{self.icinga2_url}/status"
request_args = {
'headers': self.headers,
'url_username': self.icinga2_user,
@@ -151,7 +150,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
open_url(api_status_url, **request_args)
def _post_request(self, request_url, data=None):
- self.display.vvv("Requested URL: %s" % request_url)
+ self.display.vvv(f"Requested URL: {request_url}")
request_args = {
'headers': self.headers,
'url_username': self.icinga2_user,
@@ -160,42 +159,38 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
}
if data is not None:
request_args['data'] = json.dumps(data)
- self.display.vvv("Request Args: %s" % request_args)
+ self.display.vvv(f"Request Args: {request_args}")
try:
response = open_url(request_url, **request_args)
except HTTPError as e:
try:
error_body = json.loads(e.read().decode())
- self.display.vvv("Error returned: {0}".format(error_body))
+ self.display.vvv(f"Error returned: {error_body}")
except Exception:
error_body = {"status": None}
if e.code == 404 and error_body.get('status') == "No objects found.":
raise AnsibleParserError("Host filter returned no data. Please confirm your host_filter value is valid")
- raise AnsibleParserError("Unexpected data returned: {0} -- {1}".format(e, error_body))
+ raise AnsibleParserError(f"Unexpected data returned: {e} -- {error_body}")
response_body = response.read()
json_data = json.loads(response_body.decode('utf-8'))
- self.display.vvv("Returned Data: %s" % json.dumps(json_data, indent=4, sort_keys=True))
+ self.display.vvv(f"Returned Data: {json.dumps(json_data, indent=4, sort_keys=True)}")
if 200 <= response.status <= 299:
return json_data
if response.status == 404 and json_data['status'] == "No objects found.":
raise AnsibleParserError(
- "API returned no data -- Response: %s - %s"
- % (response.status, json_data['status']))
+ f"API returned no data -- Response: {response.status} - {json_data['status']}")
if response.status == 401:
raise AnsibleParserError(
- "API was unable to complete query -- Response: %s - %s"
- % (response.status, json_data['status']))
+ f"API was unable to complete query -- Response: {response.status} - {json_data['status']}")
if response.status == 500:
raise AnsibleParserError(
- "API Response - %s - %s"
- % (json_data['status'], json_data['errors']))
+ f"API Response - {json_data['status']} - {json_data['errors']}")
raise AnsibleParserError(
- "Unexpected data returned - %s - %s"
- % (json_data['status'], json_data['errors']))
+ f"Unexpected data returned - {json_data['status']} - {json_data['errors']}")
def _query_hosts(self, hosts=None, attrs=None, joins=None, host_filter=None):
- query_hosts_url = "{0}/objects/hosts".format(self.icinga2_url)
+ query_hosts_url = f"{self.icinga2_url}/objects/hosts"
self.headers['X-HTTP-Method-Override'] = 'GET'
data_dict = dict()
if hosts:
@@ -302,7 +297,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
if self.templar.is_template(self.icinga2_password):
self.icinga2_password = self.templar.template(variable=self.icinga2_password, disable_lookups=False)
- self.icinga2_url = self.icinga2_url.rstrip('/') + '/v1'
+ self.icinga2_url = f"{self.icinga2_url.rstrip('/')}/v1"
# Not currently enabled
# self.cache_key = self.get_cache_key(path)
diff --git a/plugins/inventory/iocage.py b/plugins/inventory/iocage.py
new file mode 100644
index 0000000000..6edac6d005
--- /dev/null
+++ b/plugins/inventory/iocage.py
@@ -0,0 +1,400 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024 Vladimir Botka
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import annotations
+
+DOCUMENTATION = r'''
+name: iocage
+short_description: iocage inventory source
+version_added: 10.2.0
+author:
+ - Vladimir Botka (@vbotka)
+requirements:
+ - iocage >= 1.8
+description:
+ - Get inventory hosts from the iocage jail manager running on O(host).
+ - By default, O(host) is V(localhost). If O(host) is not V(localhost) it
+ is expected that the user running Ansible on the controller can
+ connect to the O(host) account O(user) with SSH non-interactively and
+ execute the command C(iocage list).
+ - Uses a configuration file as an inventory source, it must end
+ in C(.iocage.yml) or C(.iocage.yaml).
+extends_documentation_fragment:
+ - ansible.builtin.constructed
+ - ansible.builtin.inventory_cache
+options:
+ plugin:
+ description:
+ - The name of this plugin, it should always be set to
+ V(community.general.iocage) for this plugin to recognize
+ it as its own.
+ required: true
+ choices: ['community.general.iocage']
+ type: str
+ host:
+ description: The IP/hostname of the C(iocage) host.
+ type: str
+ default: localhost
+ user:
+ description:
+ - C(iocage) user.
+ It is expected that the O(user) is able to connect to the
+ O(host) with SSH and execute the command C(iocage list).
+ This option is not required if O(host) is V(localhost).
+ type: str
+ sudo:
+ description:
+ - Enable execution as root.
+ - This requires passwordless sudo of the command C(iocage list*).
+ type: bool
+ default: false
+ version_added: 10.3.0
+ sudo_preserve_env:
+ description:
+ - Preserve environment if O(sudo) is enabled.
+ - This requires C(SETENV) sudoers tag.
+ type: bool
+ default: false
+ version_added: 10.3.0
+ get_properties:
+ description:
+ - Get jails' properties.
+ Creates dictionary C(iocage_properties) for each added host.
+ type: bool
+ default: false
+ env:
+ description:
+ - O(user)'s environment on O(host).
+ - Enable O(sudo_preserve_env) if O(sudo) is enabled.
+ type: dict
+ default: {}
+ hooks_results:
+ description:
+ - List of paths to the files in a jail.
+ - Content of the files is stored in the items of the list C(iocage_hooks).
+ - If a file is not available the item keeps the dash character C(-).
+ - The variable C(iocage_hooks) is not created if O(hooks_results) is empty.
+ type: list
+ elements: path
+ version_added: 10.4.0
+notes:
+ - You might want to test the command C(ssh user@host iocage list -l) on
+ the controller before using this inventory plugin with O(user) specified
+ and with O(host) other than V(localhost).
+ - If you run this inventory plugin on V(localhost) C(ssh) is not used.
+ In this case, test the command C(iocage list -l).
+ - This inventory plugin creates variables C(iocage_*) for each added host.
+ - The values of these variables are collected from the output of the
+ command C(iocage list -l).
+ - The names of these variables correspond to the output columns.
+ - The column C(NAME) is used to name the added host.
+ - The option O(hooks_results) expects the C(poolname) of a jail is mounted to
+ C(/poolname). For example, if you activate the pool C(iocage) this plugin
+ expects to find the O(hooks_results) items in the path
+ C(/iocage/iocage/jails//root). If you mount the C(poolname) to a
+ different path the easiest remedy is to create a symlink.
+'''
+
+EXAMPLES = r'''
+---
+# file name must end with iocage.yaml or iocage.yml
+plugin: community.general.iocage
+host: 10.1.0.73
+user: admin
+
+---
+# user is not required if iocage is running on localhost (default)
+plugin: community.general.iocage
+
+---
+# run cryptography without legacy algorithms
+plugin: community.general.iocage
+host: 10.1.0.73
+user: admin
+env:
+ CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1
+
+---
+# execute as root
+# sudoers example 'admin ALL=(ALL) NOPASSWD:SETENV: /usr/local/bin/iocage list*'
+plugin: community.general.iocage
+host: 10.1.0.73
+user: admin
+sudo: true
+sudo_preserve_env: true
+env:
+ CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1
+
+---
+# enable cache
+plugin: community.general.iocage
+host: 10.1.0.73
+user: admin
+env:
+ CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1
+cache: true
+
+---
+# see inventory plugin ansible.builtin.constructed
+plugin: community.general.iocage
+host: 10.1.0.73
+user: admin
+env:
+ CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1
+cache: true
+strict: false
+compose:
+ ansible_host: iocage_ip4
+ release: iocage_release | split('-') | first
+groups:
+ test: inventory_hostname.startswith('test')
+keyed_groups:
+ - prefix: distro
+ key: iocage_release
+ - prefix: state
+ key: iocage_state
+
+---
+# Read the file /var/db/dhclient-hook.address.epair0b in the jails and use it as ansible_host
+plugin: community.general.iocage
+host: 10.1.0.73
+user: admin
+hooks_results:
+ - /var/db/dhclient-hook.address.epair0b
+compose:
+ ansible_host: iocage_hooks.0
+groups:
+ test: inventory_hostname.startswith('test')
+'''
+
+import re
+import os
+from subprocess import Popen, PIPE
+
+from ansible.errors import AnsibleError, AnsibleParserError
+from ansible.module_utils.common.text.converters import to_native, to_text
+from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable
+from ansible.utils.display import Display
+
+display = Display()
+
+
+def _parse_ip4(ip4):
+ ''' Return dictionary iocage_ip4_dict. default = {ip4: [], msg: ''}.
+ If item matches ifc|IP or ifc|CIDR parse ifc, ip, and mask.
+ Otherwise, append item to msg.
+ '''
+
+ iocage_ip4_dict = {}
+ iocage_ip4_dict['ip4'] = []
+ iocage_ip4_dict['msg'] = ''
+
+ items = ip4.split(',')
+ for item in items:
+ if re.match('^\\w+\\|(?:\\d{1,3}\\.){3}\\d{1,3}.*$', item):
+ i = re.split('\\||/', item)
+ if len(i) == 3:
+ iocage_ip4_dict['ip4'].append({'ifc': i[0], 'ip': i[1], 'mask': i[2]})
+ else:
+ iocage_ip4_dict['ip4'].append({'ifc': i[0], 'ip': i[1], 'mask': '-'})
+ else:
+ iocage_ip4_dict['msg'] += item
+
+ return iocage_ip4_dict
+
+
+class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
+ ''' Host inventory parser for ansible using iocage as source. '''
+
+ NAME = 'community.general.iocage'
+ IOCAGE = '/usr/local/bin/iocage'
+
+ def __init__(self):
+ super(InventoryModule, self).__init__()
+
+ def verify_file(self, path):
+ valid = False
+ if super(InventoryModule, self).verify_file(path):
+ if path.endswith(('iocage.yaml', 'iocage.yml')):
+ valid = True
+ else:
+ self.display.vvv('Skipping due to inventory source not ending in "iocage.yaml" nor "iocage.yml"')
+ return valid
+
+ def parse(self, inventory, loader, path, cache=True):
+ super(InventoryModule, self).parse(inventory, loader, path)
+
+ self._read_config_data(path)
+ cache_key = self.get_cache_key(path)
+
+ user_cache_setting = self.get_option('cache')
+ attempt_to_read_cache = user_cache_setting and cache
+ cache_needs_update = user_cache_setting and not cache
+
+ if attempt_to_read_cache:
+ try:
+ results = self._cache[cache_key]
+ except KeyError:
+ cache_needs_update = True
+ if not attempt_to_read_cache or cache_needs_update:
+ results = self.get_inventory(path)
+ if cache_needs_update:
+ self._cache[cache_key] = results
+
+ self.populate(results)
+
+ def get_inventory(self, path):
+ host = self.get_option('host')
+ sudo = self.get_option('sudo')
+ sudo_preserve_env = self.get_option('sudo_preserve_env')
+ env = self.get_option('env')
+ get_properties = self.get_option('get_properties')
+ hooks_results = self.get_option('hooks_results')
+
+ cmd = []
+ my_env = os.environ.copy()
+ if host == 'localhost':
+ my_env.update({str(k): str(v) for k, v in env.items()})
+ else:
+ user = self.get_option('user')
+ cmd.append("ssh")
+ cmd.append(f"{user}@{host}")
+ cmd.extend([f"{k}={v}" for k, v in env.items()])
+
+ cmd_list = cmd.copy()
+ if sudo:
+ cmd_list.append('sudo')
+ if sudo_preserve_env:
+ cmd_list.append('--preserve-env')
+ cmd_list.append(self.IOCAGE)
+ cmd_list.append('list')
+ cmd_list.append('--long')
+ try:
+ p = Popen(cmd_list, stdout=PIPE, stderr=PIPE, env=my_env)
+ stdout, stderr = p.communicate()
+ if p.returncode != 0:
+ raise AnsibleError(f'Failed to run cmd={cmd_list}, rc={p.returncode}, stderr={to_native(stderr)}')
+
+ try:
+ t_stdout = to_text(stdout, errors='surrogate_or_strict')
+ except UnicodeError as e:
+ raise AnsibleError(f'Invalid (non unicode) input returned: {e}') from e
+
+ except Exception as e:
+ raise AnsibleParserError(f'Failed to parse {to_native(path)}: {e}') from e
+
+ results = {'_meta': {'hostvars': {}}}
+ self.get_jails(t_stdout, results)
+
+ if get_properties:
+ for hostname, host_vars in results['_meta']['hostvars'].items():
+ cmd_get_properties = cmd.copy()
+ cmd_get_properties.append(self.IOCAGE)
+ cmd_get_properties.append("get")
+ cmd_get_properties.append("--all")
+ cmd_get_properties.append(f"{hostname}")
+ try:
+ p = Popen(cmd_get_properties, stdout=PIPE, stderr=PIPE, env=my_env)
+ stdout, stderr = p.communicate()
+ if p.returncode != 0:
+ raise AnsibleError(
+ f'Failed to run cmd={cmd_get_properties}, rc={p.returncode}, stderr={to_native(stderr)}')
+
+ try:
+ t_stdout = to_text(stdout, errors='surrogate_or_strict')
+ except UnicodeError as e:
+ raise AnsibleError(f'Invalid (non unicode) input returned: {e}') from e
+
+ except Exception as e:
+ raise AnsibleError(f'Failed to get properties: {e}') from e
+
+ self.get_properties(t_stdout, results, hostname)
+
+ if hooks_results:
+ cmd_get_pool = cmd.copy()
+ cmd_get_pool.append(self.IOCAGE)
+ cmd_get_pool.append('get')
+ cmd_get_pool.append('--pool')
+ try:
+ p = Popen(cmd_get_pool, stdout=PIPE, stderr=PIPE, env=my_env)
+ stdout, stderr = p.communicate()
+ if p.returncode != 0:
+ raise AnsibleError(
+ f'Failed to run cmd={cmd_get_pool}, rc={p.returncode}, stderr={to_native(stderr)}')
+ try:
+ iocage_pool = to_text(stdout, errors='surrogate_or_strict').strip()
+ except UnicodeError as e:
+ raise AnsibleError(f'Invalid (non unicode) input returned: {e}') from e
+ except Exception as e:
+ raise AnsibleError(f'Failed to get pool: {e}') from e
+
+ for hostname, host_vars in results['_meta']['hostvars'].items():
+ iocage_hooks = []
+ for hook in hooks_results:
+ path = "/" + iocage_pool + "/iocage/jails/" + hostname + "/root" + hook
+ cmd_cat_hook = cmd.copy()
+ cmd_cat_hook.append('cat')
+ cmd_cat_hook.append(path)
+ try:
+ p = Popen(cmd_cat_hook, stdout=PIPE, stderr=PIPE, env=my_env)
+ stdout, stderr = p.communicate()
+ if p.returncode != 0:
+ iocage_hooks.append('-')
+ continue
+
+ try:
+ iocage_hook = to_text(stdout, errors='surrogate_or_strict').strip()
+ except UnicodeError as e:
+ raise AnsibleError(f'Invalid (non unicode) input returned: {e}') from e
+
+ except Exception:
+ iocage_hooks.append('-')
+ else:
+ iocage_hooks.append(iocage_hook)
+
+ results['_meta']['hostvars'][hostname]['iocage_hooks'] = iocage_hooks
+
+ return results
+
+ def get_jails(self, t_stdout, results):
+ lines = t_stdout.splitlines()
+ if len(lines) < 5:
+ return
+ indices = [i for i, val in enumerate(lines[1]) if val == '|']
+ for line in lines[3::2]:
+ jail = [line[i + 1:j].strip() for i, j in zip(indices[:-1], indices[1:])]
+ iocage_name = jail[1]
+ iocage_ip4_dict = _parse_ip4(jail[6])
+ if iocage_ip4_dict['ip4']:
+ iocage_ip4 = ','.join([d['ip'] for d in iocage_ip4_dict['ip4']])
+ else:
+ iocage_ip4 = '-'
+ results['_meta']['hostvars'][iocage_name] = {}
+ results['_meta']['hostvars'][iocage_name]['iocage_jid'] = jail[0]
+ results['_meta']['hostvars'][iocage_name]['iocage_boot'] = jail[2]
+ results['_meta']['hostvars'][iocage_name]['iocage_state'] = jail[3]
+ results['_meta']['hostvars'][iocage_name]['iocage_type'] = jail[4]
+ results['_meta']['hostvars'][iocage_name]['iocage_release'] = jail[5]
+ results['_meta']['hostvars'][iocage_name]['iocage_ip4_dict'] = iocage_ip4_dict
+ results['_meta']['hostvars'][iocage_name]['iocage_ip4'] = iocage_ip4
+ results['_meta']['hostvars'][iocage_name]['iocage_ip6'] = jail[7]
+ results['_meta']['hostvars'][iocage_name]['iocage_template'] = jail[8]
+ results['_meta']['hostvars'][iocage_name]['iocage_basejail'] = jail[9]
+
+ def get_properties(self, t_stdout, results, hostname):
+ properties = dict([x.split(':', 1) for x in t_stdout.splitlines()])
+ results['_meta']['hostvars'][hostname]['iocage_properties'] = properties
+
+ def populate(self, results):
+ strict = self.get_option('strict')
+
+ for hostname, host_vars in results['_meta']['hostvars'].items():
+ self.inventory.add_host(hostname, group='all')
+ for var, value in host_vars.items():
+ self.inventory.set_variable(hostname, var, value)
+ self._set_composite_vars(self.get_option('compose'), host_vars, hostname, strict=True)
+ self._add_host_to_composed_groups(self.get_option('groups'), host_vars, hostname, strict=strict)
+ self._add_host_to_keyed_groups(self.get_option('keyed_groups'), host_vars, hostname, strict=strict)
diff --git a/plugins/inventory/linode.py b/plugins/inventory/linode.py
index 5c9a4718f5..594cf30eba 100644
--- a/plugins/inventory/linode.py
+++ b/plugins/inventory/linode.py
@@ -3,8 +3,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
DOCUMENTATION = r'''
name: linode
@@ -79,15 +78,18 @@ DOCUMENTATION = r'''
'''
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
@@ -96,6 +98,7 @@ regions:
types:
- g5-standard-2
+---
# Example with keyed_groups, groups, and compose
plugin: community.general.linode
access_token: foobar
@@ -114,6 +117,7 @@ compose:
ansible_ssh_host: ipv4[0]
ansible_port: 2222
+---
# Example where control traffic limited to internal network
plugin: community.general.linode
access_token: foobar
@@ -161,7 +165,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
try:
self.instances = self.client.linode.instances()
except LinodeApiError as exception:
- raise AnsibleError('Linode client raised: %s' % exception)
+ raise AnsibleError(f'Linode client raised: {exception}')
def _add_groups(self):
"""Add Linode instance groups to the dynamic inventory."""
diff --git a/plugins/inventory/lxd.py b/plugins/inventory/lxd.py
index 9ae004f6c5..480af8388c 100644
--- a/plugins/inventory/lxd.py
+++ b/plugins/inventory/lxd.py
@@ -3,8 +3,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
DOCUMENTATION = r'''
name: lxd
@@ -108,15 +107,18 @@ DOCUMENTATION = r'''
'''
EXAMPLES = '''
+---
# simple lxd.yml
plugin: community.general.lxd
url: unix:/var/snap/lxd/common/lxd/unix.socket
+---
# simple lxd.yml including filter
plugin: community.general.lxd
url: unix:/var/snap/lxd/common/lxd/unix.socket
state: RUNNING
+---
# simple lxd.yml including virtual machines and containers
plugin: community.general.lxd
url: unix:/var/snap/lxd/common/lxd/unix.socket
@@ -211,7 +213,7 @@ class InventoryModule(BaseInventoryPlugin):
with open(path, 'r') as json_file:
return json.load(json_file)
except (IOError, json.decoder.JSONDecodeError) as err:
- raise AnsibleParserError('Could not load the test data from {0}: {1}'.format(to_native(path), to_native(err)))
+ raise AnsibleParserError(f'Could not load the test data from {to_native(path)}: {err}')
def save_json_data(self, path, file_name=None):
"""save data as json
@@ -241,7 +243,7 @@ class InventoryModule(BaseInventoryPlugin):
with open(os.path.abspath(os.path.join(cwd, *path)), 'w') as json_file:
json.dump(self.data, json_file)
except IOError as err:
- raise AnsibleParserError('Could not save data: {0}'.format(to_native(err)))
+ raise AnsibleParserError(f'Could not save data: {err}')
def verify_file(self, path):
"""Check the config
@@ -281,7 +283,7 @@ class InventoryModule(BaseInventoryPlugin):
if not isinstance(url, str):
return False
if not url.startswith(('unix:', 'https:')):
- raise AnsibleError('URL is malformed: {0}'.format(to_native(url)))
+ raise AnsibleError(f'URL is malformed: {url}')
return True
def _connect_to_socket(self):
@@ -306,7 +308,7 @@ class InventoryModule(BaseInventoryPlugin):
return socket_connection
except LXDClientException as err:
error_storage[url] = err
- raise AnsibleError('No connection to the socket: {0}'.format(to_native(error_storage)))
+ raise AnsibleError(f'No connection to the socket: {error_storage}')
def _get_networks(self):
"""Get Networknames
@@ -355,7 +357,7 @@ class InventoryModule(BaseInventoryPlugin):
# }
url = '/1.0/instances'
if self.project:
- url = url + '?{0}'.format(urlencode(dict(project=self.project)))
+ url = f"{url}?{urlencode(dict(project=self.project))}"
instances = self.socket.do('GET', url)
@@ -383,10 +385,10 @@ class InventoryModule(BaseInventoryPlugin):
config = {}
if isinstance(branch, (tuple, list)):
config[name] = {branch[1]: self.socket.do(
- 'GET', '/1.0/{0}/{1}/{2}?{3}'.format(to_native(branch[0]), to_native(name), to_native(branch[1]), urlencode(dict(project=self.project))))}
+ 'GET', f'/1.0/{to_native(branch[0])}/{to_native(name)}/{to_native(branch[1])}?{urlencode(dict(project=self.project))}')}
else:
config[name] = {branch: self.socket.do(
- 'GET', '/1.0/{0}/{1}?{2}'.format(to_native(branch), to_native(name), urlencode(dict(project=self.project))))}
+ 'GET', f'/1.0/{to_native(branch)}/{to_native(name)}?{urlencode(dict(project=self.project))}')}
return config
def get_instance_data(self, names):
@@ -449,7 +451,7 @@ class InventoryModule(BaseInventoryPlugin):
None
Returns:
dict(network_configuration): network config"""
- instance_network_interfaces = self._get_data_entry('instances/{0}/state/metadata/network'.format(instance_name))
+ instance_network_interfaces = self._get_data_entry(f'instances/{instance_name}/state/metadata/network')
network_configuration = None
if instance_network_interfaces:
network_configuration = {}
@@ -462,7 +464,7 @@ class InventoryModule(BaseInventoryPlugin):
address_set['family'] = address.get('family')
address_set['address'] = address.get('address')
address_set['netmask'] = address.get('netmask')
- address_set['combined'] = address.get('address') + '/' + address.get('netmask')
+ address_set['combined'] = f"{address.get('address')}/{address.get('netmask')}"
network_configuration[interface_name].append(address_set)
return network_configuration
@@ -479,7 +481,7 @@ class InventoryModule(BaseInventoryPlugin):
None
Returns:
str(prefered_interface): None or interface name"""
- instance_network_interfaces = self._get_data_entry('inventory/{0}/network_interfaces'.format(instance_name))
+ instance_network_interfaces = self._get_data_entry(f'inventory/{instance_name}/network_interfaces')
prefered_interface = None # init
if instance_network_interfaces: # instance have network interfaces
# generator if interfaces which start with the desired pattern
@@ -516,7 +518,7 @@ class InventoryModule(BaseInventoryPlugin):
# "network":"lxdbr0",
# "type":"nic"},
vlan_ids = {}
- devices = self._get_data_entry('instances/{0}/instances/metadata/expanded_devices'.format(to_native(instance_name)))
+ devices = self._get_data_entry(f'instances/{to_native(instance_name)}/instances/metadata/expanded_devices')
for device in devices:
if 'network' in devices[device]:
if devices[device]['network'] in network_vlans:
@@ -579,7 +581,7 @@ class InventoryModule(BaseInventoryPlugin):
else:
path[instance_name][key] = value
except KeyError as err:
- raise AnsibleParserError("Unable to store Information: {0}".format(to_native(err)))
+ raise AnsibleParserError(f"Unable to store Information: {err}")
def extract_information_from_instance_configs(self):
"""Process configuration information
@@ -600,24 +602,24 @@ class InventoryModule(BaseInventoryPlugin):
for instance_name in self.data['instances']:
self._set_data_entry(instance_name, 'os', self._get_data_entry(
- 'instances/{0}/instances/metadata/config/image.os'.format(instance_name)))
+ f'instances/{instance_name}/instances/metadata/config/image.os'))
self._set_data_entry(instance_name, 'release', self._get_data_entry(
- 'instances/{0}/instances/metadata/config/image.release'.format(instance_name)))
+ f'instances/{instance_name}/instances/metadata/config/image.release'))
self._set_data_entry(instance_name, 'version', self._get_data_entry(
- 'instances/{0}/instances/metadata/config/image.version'.format(instance_name)))
+ f'instances/{instance_name}/instances/metadata/config/image.version'))
self._set_data_entry(instance_name, 'profile', self._get_data_entry(
- 'instances/{0}/instances/metadata/profiles'.format(instance_name)))
+ f'instances/{instance_name}/instances/metadata/profiles'))
self._set_data_entry(instance_name, 'location', self._get_data_entry(
- 'instances/{0}/instances/metadata/location'.format(instance_name)))
+ f'instances/{instance_name}/instances/metadata/location'))
self._set_data_entry(instance_name, 'state', self._get_data_entry(
- 'instances/{0}/instances/metadata/config/volatile.last_state.power'.format(instance_name)))
+ f'instances/{instance_name}/instances/metadata/config/volatile.last_state.power'))
self._set_data_entry(instance_name, 'type', self._get_data_entry(
- 'instances/{0}/instances/metadata/type'.format(instance_name)))
+ f'instances/{instance_name}/instances/metadata/type'))
self._set_data_entry(instance_name, 'network_interfaces', self.extract_network_information_from_instance_config(instance_name))
self._set_data_entry(instance_name, 'preferred_interface', self.get_prefered_instance_network_interface(instance_name))
self._set_data_entry(instance_name, 'vlan_ids', self.get_instance_vlans(instance_name))
self._set_data_entry(instance_name, 'project', self._get_data_entry(
- 'instances/{0}/instances/metadata/project'.format(instance_name)))
+ f'instances/{instance_name}/instances/metadata/project'))
def build_inventory_network(self, instance_name):
"""Add the network interfaces of the instance to the inventory
@@ -651,18 +653,18 @@ class InventoryModule(BaseInventoryPlugin):
None
Returns:
dict(interface_name: ip)"""
- prefered_interface = self._get_data_entry('inventory/{0}/preferred_interface'.format(instance_name)) # name or None
+ prefered_interface = self._get_data_entry(f'inventory/{instance_name}/preferred_interface') # name or None
prefered_instance_network_family = self.prefered_instance_network_family
ip_address = ''
if prefered_interface:
- interface = self._get_data_entry('inventory/{0}/network_interfaces/{1}'.format(instance_name, prefered_interface))
+ interface = self._get_data_entry(f'inventory/{instance_name}/network_interfaces/{prefered_interface}')
for config in interface:
if config['family'] == prefered_instance_network_family:
ip_address = config['address']
break
else:
- interfaces = self._get_data_entry('inventory/{0}/network_interfaces'.format(instance_name))
+ interfaces = self._get_data_entry(f'inventory/{instance_name}/network_interfaces')
for interface in interfaces.values():
for config in interface:
if config['family'] == prefered_instance_network_family:
@@ -670,7 +672,7 @@ class InventoryModule(BaseInventoryPlugin):
break
return ip_address
- if self._get_data_entry('inventory/{0}/network_interfaces'.format(instance_name)): # instance have network interfaces
+ if self._get_data_entry(f'inventory/{instance_name}/network_interfaces'): # instance have network interfaces
self.inventory.set_variable(instance_name, 'ansible_connection', 'ssh')
self.inventory.set_variable(instance_name, 'ansible_host', make_unsafe(interface_selection(instance_name)))
else:
@@ -691,7 +693,7 @@ class InventoryModule(BaseInventoryPlugin):
Returns:
None"""
for instance_name in self.data['inventory']:
- instance_state = str(self._get_data_entry('inventory/{0}/state'.format(instance_name)) or "STOPPED").lower()
+ instance_state = str(self._get_data_entry(f'inventory/{instance_name}/state') or "STOPPED").lower()
# Only consider instances that match the "state" filter, if self.state is not None
if self.filter:
@@ -703,34 +705,34 @@ class InventoryModule(BaseInventoryPlugin):
# add network information
self.build_inventory_network(instance_name)
# add os
- v = self._get_data_entry('inventory/{0}/os'.format(instance_name))
+ v = self._get_data_entry(f'inventory/{instance_name}/os')
if v:
self.inventory.set_variable(instance_name, 'ansible_lxd_os', make_unsafe(v.lower()))
# add release
- v = self._get_data_entry('inventory/{0}/release'.format(instance_name))
+ v = self._get_data_entry(f'inventory/{instance_name}/release')
if v:
self.inventory.set_variable(
instance_name, 'ansible_lxd_release', make_unsafe(v.lower()))
# add profile
self.inventory.set_variable(
- instance_name, 'ansible_lxd_profile', make_unsafe(self._get_data_entry('inventory/{0}/profile'.format(instance_name))))
+ instance_name, 'ansible_lxd_profile', make_unsafe(self._get_data_entry(f'inventory/{instance_name}/profile')))
# add state
self.inventory.set_variable(
instance_name, 'ansible_lxd_state', make_unsafe(instance_state))
# add type
self.inventory.set_variable(
- instance_name, 'ansible_lxd_type', make_unsafe(self._get_data_entry('inventory/{0}/type'.format(instance_name))))
+ instance_name, 'ansible_lxd_type', make_unsafe(self._get_data_entry(f'inventory/{instance_name}/type')))
# add location information
- if self._get_data_entry('inventory/{0}/location'.format(instance_name)) != "none": # wrong type by lxd 'none' != 'None'
+ if self._get_data_entry(f'inventory/{instance_name}/location') != "none": # wrong type by lxd 'none' != 'None'
self.inventory.set_variable(
- instance_name, 'ansible_lxd_location', make_unsafe(self._get_data_entry('inventory/{0}/location'.format(instance_name))))
+ instance_name, 'ansible_lxd_location', make_unsafe(self._get_data_entry(f'inventory/{instance_name}/location')))
# add VLAN_ID information
- if self._get_data_entry('inventory/{0}/vlan_ids'.format(instance_name)):
+ if self._get_data_entry(f'inventory/{instance_name}/vlan_ids'):
self.inventory.set_variable(
- instance_name, 'ansible_lxd_vlan_ids', make_unsafe(self._get_data_entry('inventory/{0}/vlan_ids'.format(instance_name))))
+ instance_name, 'ansible_lxd_vlan_ids', make_unsafe(self._get_data_entry(f'inventory/{instance_name}/vlan_ids')))
# add project
self.inventory.set_variable(
- instance_name, 'ansible_lxd_project', make_unsafe(self._get_data_entry('inventory/{0}/project'.format(instance_name))))
+ instance_name, 'ansible_lxd_project', make_unsafe(self._get_data_entry(f'inventory/{instance_name}/project')))
def build_inventory_groups_location(self, group_name):
"""create group by attribute: location
@@ -792,7 +794,7 @@ class InventoryModule(BaseInventoryPlugin):
network = ipaddress.ip_network(to_text(self.groupby[group_name].get('attribute')))
except ValueError as err:
raise AnsibleParserError(
- 'Error while parsing network range {0}: {1}'.format(self.groupby[group_name].get('attribute'), to_native(err)))
+ f"Error while parsing network range {self.groupby[group_name].get('attribute')}: {err}")
for instance_name in self.inventory.hosts:
if self.data['inventory'][instance_name].get('network_interfaces') is not None:
@@ -997,12 +999,12 @@ class InventoryModule(BaseInventoryPlugin):
elif self.groupby[group_name].get('type') == 'project':
self.build_inventory_groups_project(group_name)
else:
- raise AnsibleParserError('Unknown group type: {0}'.format(to_native(group_name)))
+ raise AnsibleParserError(f'Unknown group type: {to_native(group_name)}')
if self.groupby:
for group_name in self.groupby:
if not group_name.isalnum():
- raise AnsibleParserError('Invalid character(s) in groupname: {0}'.format(to_native(group_name)))
+ raise AnsibleParserError(f'Invalid character(s) in groupname: {to_native(group_name)}')
group_type(make_unsafe(group_name))
def build_inventory(self):
@@ -1039,7 +1041,7 @@ class InventoryModule(BaseInventoryPlugin):
None"""
iter_keys = list(self.data['instances'].keys())
for instance_name in iter_keys:
- if self._get_data_entry('instances/{0}/instances/metadata/type'.format(instance_name)) != self.type_filter:
+ if self._get_data_entry(f'instances/{instance_name}/instances/metadata/type') != self.type_filter:
del self.data['instances'][instance_name]
def _populate(self):
@@ -1120,6 +1122,6 @@ class InventoryModule(BaseInventoryPlugin):
self.url = self.get_option('url')
except Exception as err:
raise AnsibleParserError(
- 'All correct options required: {0}'.format(to_native(err)))
+ f'All correct options required: {err}')
# Call our internal helper to populate the dynamic inventory
self._populate()
diff --git a/plugins/inventory/nmap.py b/plugins/inventory/nmap.py
index 48f02c446b..3bd6e9fda3 100644
--- a/plugins/inventory/nmap.py
+++ b/plugins/inventory/nmap.py
@@ -3,8 +3,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
@@ -87,6 +86,11 @@ DOCUMENTATION = '''
type: boolean
default: false
version_added: 6.1.0
+ dns_servers:
+ description: Specify which DNS servers to use for name resolution.
+ type: list
+ elements: string
+ version_added: 10.5.0
use_arp_ping:
description: Whether to always (V(true)) use the quick ARP ping or (V(false)) a slower but more reliable method.
type: boolean
@@ -97,18 +101,20 @@ DOCUMENTATION = '''
- 'TODO: add OS fingerprinting'
'''
EXAMPLES = '''
+---
# inventory.config file in YAML format
plugin: community.general.nmap
strict: false
address: 192.168.0.0/24
-
+---
# a sudo nmap scan to fully use nmap scan power.
plugin: community.general.nmap
sudo: true
strict: false
address: 192.168.0.0/24
+---
# an nmap scan specifying ports and classifying results to an inventory group
plugin: community.general.nmap
address: 192.168.0.0/24
@@ -178,7 +184,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
try:
self._nmap = get_bin_path('nmap')
except ValueError as e:
- raise AnsibleParserError('nmap inventory plugin requires the nmap cli tool to work: {0}'.format(to_native(e)))
+ raise AnsibleParserError(f'nmap inventory plugin requires the nmap cli tool to work: {e}')
super(InventoryModule, self).parse(inventory, loader, path, cache=cache)
@@ -230,6 +236,10 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
if self.get_option('dns_resolve'):
cmd.append('-n')
+ if self.get_option('dns_servers'):
+ cmd.append('--dns-servers')
+ cmd.append(','.join(self.get_option('dns_servers')))
+
if self.get_option('udp_scan'):
cmd.append('-sU')
@@ -248,7 +258,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
p = Popen(cmd, stdout=PIPE, stderr=PIPE)
stdout, stderr = p.communicate()
if p.returncode != 0:
- raise AnsibleParserError('Failed to run nmap, rc=%s: %s' % (p.returncode, to_native(stderr)))
+ raise AnsibleParserError(f'Failed to run nmap, rc={p.returncode}: {to_native(stderr)}')
# parse results
host = None
@@ -259,7 +269,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
try:
t_stdout = to_text(stdout, errors='surrogate_or_strict')
except UnicodeError as e:
- raise AnsibleParserError('Invalid (non unicode) input returned: %s' % to_native(e))
+ raise AnsibleParserError(f'Invalid (non unicode) input returned: {e}')
for line in t_stdout.splitlines():
hits = self.find_host.match(line)
@@ -300,7 +310,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
results[-1]['ports'] = ports
except Exception as e:
- raise AnsibleParserError("failed to parse %s: %s " % (to_native(path), to_native(e)))
+ raise AnsibleParserError(f"failed to parse {to_native(path)}: {e} ")
if cache_needs_update:
self._cache[cache_key] = results
diff --git a/plugins/inventory/online.py b/plugins/inventory/online.py
index 70b8d14192..9e29c91e54 100644
--- a/plugins/inventory/online.py
+++ b/plugins/inventory/online.py
@@ -3,8 +3,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
DOCUMENTATION = r'''
name: online
@@ -138,7 +137,7 @@ class InventoryModule(BaseInventoryPlugin):
try:
response = open_url(url, headers=self.headers)
except Exception as e:
- self.display.warning("An error happened while fetching: %s" % url)
+ self.display.warning(f"An error happened while fetching: {url}")
return None
try:
@@ -245,8 +244,8 @@ class InventoryModule(BaseInventoryPlugin):
}
self.headers = {
- 'Authorization': "Bearer %s" % token,
- 'User-Agent': "ansible %s Python %s" % (ansible_version, python_version.split(' ', 1)[0]),
+ 'Authorization': f"Bearer {token}",
+ 'User-Agent': f"ansible {ansible_version} Python {python_version.split(' ', 1)[0]}",
'Content-type': 'application/json'
}
diff --git a/plugins/inventory/opennebula.py b/plugins/inventory/opennebula.py
index 077d3da5a3..ed26880d07 100644
--- a/plugins/inventory/opennebula.py
+++ b/plugins/inventory/opennebula.py
@@ -3,9 +3,8 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
+from __future__ import annotations
-__metaclass__ = type
DOCUMENTATION = r'''
name: opennebula
@@ -96,7 +95,6 @@ except ImportError:
from ansible.errors import AnsibleError
from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
-from ansible.module_utils.common.text.converters import to_native
from ansible_collections.community.general.plugins.plugin_utils.unsafe import make_unsafe
@@ -128,9 +126,9 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
authstring = fp.read().rstrip()
username, password = authstring.split(":")
except (OSError, IOError):
- raise AnsibleError("Could not find or read ONE_AUTH file at '{e}'".format(e=authfile))
+ raise AnsibleError(f"Could not find or read ONE_AUTH file at '{authfile}'")
except Exception:
- raise AnsibleError("Error occurs when reading ONE_AUTH file at '{e}'".format(e=authfile))
+ raise AnsibleError(f"Error occurs when reading ONE_AUTH file at '{authfile}'")
auth_params = namedtuple('auth', ('url', 'username', 'password'))
@@ -166,13 +164,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
if not (auth.username and auth.password):
raise AnsibleError('API Credentials missing. Check OpenNebula inventory file.')
else:
- one_client = pyone.OneServer(auth.url, session=auth.username + ':' + auth.password)
+ one_client = pyone.OneServer(auth.url, session=f"{auth.username}:{auth.password}")
# get hosts (VMs)
try:
vm_pool = one_client.vmpool.infoextended(-2, -1, -1, 3)
except Exception as e:
- raise AnsibleError("Something happened during XML-RPC call: {e}".format(e=to_native(e)))
+ raise AnsibleError(f"Something happened during XML-RPC call: {e}")
return vm_pool
diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py
index 3ce4f789a3..f2efef9bf8 100644
--- a/plugins/inventory/proxmox.py
+++ b/plugins/inventory/proxmox.py
@@ -3,9 +3,8 @@
# Copyright (c) 2018 Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
+from __future__ import annotations
-__metaclass__ = type
DOCUMENTATION = '''
name: proxmox
@@ -25,7 +24,7 @@ DOCUMENTATION = '''
- inventory_cache
options:
plugin:
- description: The name of this plugin, it should always be set to V(community.general.proxmox) for this plugin to recognize it as it's own.
+ description: The name of this plugin, it should always be set to V(community.general.proxmox) for this plugin to recognize it as its own.
required: true
choices: ['community.general.proxmox']
type: str
@@ -138,6 +137,7 @@ DOCUMENTATION = '''
'''
EXAMPLES = '''
+---
# Minimal example which will not gather additional facts for QEMU/LXC guests
# By not specifying a URL the plugin will attempt to connect to the controller host on port 8006
# my.proxmox.yml
@@ -148,6 +148,7 @@ password: secure
# an example where this is set to `false` and where ansible_host is set with `compose`.
want_proxmox_nodes_ansible_host: true
+---
# Instead of login with password, proxmox supports api token authentication since release 6.2.
plugin: community.general.proxmox
user: ci@pve
@@ -164,6 +165,7 @@ token_secret: !vault |
32643131386134396336623736393634373936356332623632306561356361323737313663633633
6231313333666361656537343562333337323030623732323833
+---
# More complete example demonstrating the use of 'want_facts' and the constructed options
# Note that using facts returned by 'want_facts' in constructed options requires 'want_facts=true'
# my.proxmox.yml
@@ -186,6 +188,7 @@ compose:
# an example where this is set to `false` and where ansible_host is set with `compose`.
want_proxmox_nodes_ansible_host: true
+---
# 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.
@@ -203,6 +206,7 @@ compose:
my_inv_var_2: >
"my_var_2_value"
+---
# Specify the url, user and password using templating
# my.proxmox.yml
plugin: community.general.proxmox
@@ -222,7 +226,6 @@ 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 import string_types
from ansible.module_utils.six.moves.urllib.parse import urlencode
from ansible.utils.display import Display
@@ -275,7 +278,6 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
return self.session
def _get_auth(self):
-
validate_certs = self.get_option('validate_certs')
if validate_certs is False:
@@ -283,33 +285,40 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
disable_warnings()
if self.proxmox_password:
-
credentials = urlencode({'username': self.proxmox_user, 'password': self.proxmox_password})
-
a = self._get_session()
-
- ret = a.post('%s/api2/json/access/ticket' % self.proxmox_url, data=credentials)
-
+ ret = a.post(f'{self.proxmox_url}/api2/json/access/ticket', data=credentials)
json = ret.json()
-
self.headers = {
# only required for POST/PUT/DELETE methods, which we are not using currently
# 'CSRFPreventionToken': json['data']['CSRFPreventionToken'],
- 'Cookie': 'PVEAuthCookie={0}'.format(json['data']['ticket'])
+ 'Cookie': f"PVEAuthCookie={json['data']['ticket']}"
}
-
else:
+ # Clean and format token components
+ user = self.proxmox_user.strip()
+ token_id = self.proxmox_token_id.strip()
+ token_secret = self.proxmox_token_secret.strip()
- self.headers = {'Authorization': 'PVEAPIToken={0}!{1}={2}'.format(self.proxmox_user, self.proxmox_token_id, self.proxmox_token_secret)}
+ # Build token string without newlines
+ token = f'{user}!{token_id}={token_secret}'
+
+ # Set headers with clean token
+ self.headers = {'Authorization': f'PVEAPIToken={token}'}
def _get_json(self, url, ignore_errors=None):
- if not self.use_cache or url not in self._cache.get(self.cache_key, {}):
+ data = []
+ has_data = False
- if self.cache_key not in self._cache:
- self._cache[self.cache_key] = {'url': ''}
+ if self.use_cache:
+ try:
+ data = self._cache[self.cache_key][url]
+ has_data = True
+ except KeyError:
+ self.update_cache = True
- data = []
+ if not has_data:
s = self._get_session()
while True:
ret = s.get(url, headers=self.headers)
@@ -335,28 +344,27 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
data = data + json['data']
break
- self._cache[self.cache_key][url] = data
-
- return make_unsafe(self._cache[self.cache_key][url])
+ self._results[url] = data
+ return make_unsafe(data)
def _get_nodes(self):
- return self._get_json("%s/api2/json/nodes" % self.proxmox_url)
+ return self._get_json(f"{self.proxmox_url}/api2/json/nodes")
def _get_pools(self):
- return self._get_json("%s/api2/json/pools" % self.proxmox_url)
+ return self._get_json(f"{self.proxmox_url}/api2/json/pools")
def _get_lxc_per_node(self, node):
- return self._get_json("%s/api2/json/nodes/%s/lxc" % (self.proxmox_url, node))
+ return self._get_json(f"{self.proxmox_url}/api2/json/nodes/{node}/lxc")
def _get_qemu_per_node(self, node):
- return self._get_json("%s/api2/json/nodes/%s/qemu" % (self.proxmox_url, node))
+ return self._get_json(f"{self.proxmox_url}/api2/json/nodes/{node}/qemu")
def _get_members_per_pool(self, pool):
- ret = self._get_json("%s/api2/json/pools/%s" % (self.proxmox_url, pool))
+ ret = self._get_json(f"{self.proxmox_url}/api2/json/pools/{pool}")
return ret['members']
def _get_node_ip(self, node):
- ret = self._get_json("%s/api2/json/nodes/%s/network" % (self.proxmox_url, node))
+ ret = self._get_json(f"{self.proxmox_url}/api2/json/nodes/{node}/network")
for iface in ret:
try:
@@ -370,7 +378,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
if status_key not in properties or not properties[status_key] == 'running':
return
- ret = self._get_json("%s/api2/json/nodes/%s/lxc/%s/interfaces" % (self.proxmox_url, node, vmid), ignore_errors=[501])
+ ret = self._get_json(f"{self.proxmox_url}/api2/json/nodes/{node}/lxc/{vmid}/interfaces", ignore_errors=[501])
if not ret:
return
@@ -397,15 +405,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
try:
ifaces = self._get_json(
- "%s/api2/json/nodes/%s/%s/%s/agent/network-get-interfaces" % (
- self.proxmox_url, node, vmtype, vmid
- )
+ f"{self.proxmox_url}/api2/json/nodes/{node}/{vmtype}/{vmid}/agent/network-get-interfaces"
)['result']
if "error" in ifaces:
if "class" in ifaces["error"]:
# This happens on Windows, even though qemu agent is running, the IP address
- # cannot be fetched, as it's unsupported, also a command disabled can happen.
+ # cannot be fetched, as it is unsupported, also a command disabled can happen.
errorClass = ifaces["error"]["class"]
if errorClass in ["Unsupported"]:
self.display.v("Retrieving network interfaces from guest agents on windows with older qemu-guest-agents is not supported")
@@ -417,7 +423,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
result.append({
'name': iface['name'],
'mac-address': iface['hardware-address'] if 'hardware-address' in iface else '',
- 'ip-addresses': ["%s/%s" % (ip['ip-address'], ip['prefix']) for ip in iface['ip-addresses']] if 'ip-addresses' in iface else []
+ 'ip-addresses': [f"{ip['ip-address']}/{ip['prefix']}" for ip in iface['ip-addresses']] if 'ip-addresses' in iface else []
})
except requests.HTTPError:
pass
@@ -425,7 +431,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
return result
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))
+ ret = self._get_json(f"{self.proxmox_url}/api2/json/nodes/{node}/{vmtype}/{vmid}/config")
properties[self._fact('node')] = node
properties[self._fact('vmid')] = vmid
@@ -441,13 +447,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
try:
# fixup disk images as they have no key
if config == 'rootfs' or config.startswith(('virtio', 'sata', 'ide', 'scsi')):
- value = ('disk_image=' + value)
+ value = f"disk_image={value}"
# Additional field containing parsed tags as list
if config == 'tags':
stripped_value = value.strip()
if stripped_value:
- parsed_key = key + "_parsed"
+ parsed_key = f"{key}_parsed"
properties[parsed_key] = [tag.strip() for tag in stripped_value.replace(',', ';').split(";")]
# The first field in the agent string tells you whether the agent is enabled
@@ -463,7 +469,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
if agent_enabled:
agent_iface_value = self._get_agent_network_interfaces(node, vmid, vmtype)
if agent_iface_value:
- agent_iface_key = self.to_safe('%s%s' % (key, "_interfaces"))
+ agent_iface_key = self.to_safe(f'{key}_interfaces')
properties[agent_iface_key] = agent_iface_value
if config == 'lxc':
@@ -488,13 +494,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
return None
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))
+ ret = self._get_json(f"{self.proxmox_url}/api2/json/nodes/{node}/{vmtype}/{vmid}/status/current")
properties[self._fact('status')] = ret['status']
if vmtype == 'qemu':
properties[self._fact('qmpstatus')] = ret['qmpstatus']
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))
+ ret = self._get_json(f"{self.proxmox_url}/api2/json/nodes/{node}/{vmtype}/{vmid}/snapshot")
snapshots = [snapshot['name'] for snapshot in ret if snapshot['name'] != 'current']
properties[self._fact('snapshots')] = snapshots
@@ -508,11 +514,11 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
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()))
+ return self.to_safe(f'{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()))
+ return self.to_safe(f'{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
@@ -524,7 +530,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
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))
+ message = f"Could not evaluate host filter {host_filter} for host {name} - {e}"
if self.strict:
raise AnsibleError(message)
display.warning(message)
@@ -565,8 +571,8 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
# 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)
+ node_type_group = self._group(f'{node}_{ittype}')
+ self.inventory.add_child(self._group(f"all_{ittype}"), name)
self.inventory.add_child(node_type_group, name)
item_status = item['status']
@@ -574,7 +580,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
if want_facts and ittype == 'qemu' and self.get_option('qemu_extended_statuses'):
# get more details about the status of the qemu VM
item_status = properties.get(self._fact('qmpstatus'), item_status)
- self.inventory.add_child(self._group('all_%s' % (item_status, )), name)
+ self.inventory.add_child(self._group(f'all_{item_status}'), name)
return name
@@ -585,7 +591,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
poolid = pool.get('poolid')
if not poolid:
continue
- pool_group = self._group('pool_' + poolid)
+ pool_group = self._group(f"pool_{poolid}")
self.inventory.add_group(pool_group)
for member in self._get_members_per_pool(poolid):
@@ -602,7 +608,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
default_groups.extend(['prelaunch', 'paused'])
for group in default_groups:
- self.inventory.add_group(self._group('all_%s' % (group)))
+ self.inventory.add_group(self._group(f'all_{group}'))
nodes_group = self._group('nodes')
if not self.exclude_nodes:
self.inventory.add_group(nodes_group)
@@ -635,7 +641,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
# add LXC/Qemu groups for the node
for ittype in ('lxc', 'qemu'):
- node_type_group = self._group('%s_%s' % (node['node'], ittype))
+ node_type_group = self._group(f"{node['node']}_{ittype}")
self.inventory.add_group(node_type_group)
# get LXC containers and Qemu VMs for this node
@@ -664,7 +670,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
v = self.get_option(o)
if self.templar.is_template(v):
v = self.templar.template(v, disable_lookups=False)
- setattr(self, 'proxmox_%s' % o, v)
+ setattr(self, f'proxmox_{o}', v)
# some more cleanup and validation
self.proxmox_url = self.proxmox_url.rstrip('/')
@@ -678,10 +684,14 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
self.exclude_nodes = self.get_option('exclude_nodes')
self.cache_key = self.get_cache_key(path)
self.use_cache = cache and self.get_option('cache')
+ self.update_cache = not 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._results = {}
self._populate()
+ if self.update_cache:
+ self._cache[self.cache_key] = self._results
diff --git a/plugins/inventory/scaleway.py b/plugins/inventory/scaleway.py
index 4205caeca7..d815890df4 100644
--- a/plugins/inventory/scaleway.py
+++ b/plugins/inventory/scaleway.py
@@ -3,9 +3,8 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
+from __future__ import annotations
-__metaclass__ = type
DOCUMENTATION = r'''
name: scaleway
@@ -77,6 +76,7 @@ EXAMPLES = r'''
# scaleway_inventory.yml file in YAML format
# Example command line: ansible-inventory --list -i scaleway_inventory.yml
+---
# use hostname as inventory_hostname
# use the private IP address to connect to the host
plugin: community.general.scaleway
@@ -91,6 +91,7 @@ variables:
ansible_host: private_ip
state: state
+---
# use hostname as inventory_hostname and public IP address to connect to the host
plugin: community.general.scaleway
hostnames:
@@ -100,6 +101,7 @@ regions:
variables:
ansible_host: public_ip.address
+---
# Using static strings as variables
plugin: community.general.scaleway
hostnames:
@@ -125,7 +127,7 @@ from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
from ansible_collections.community.general.plugins.module_utils.scaleway import SCALEWAY_LOCATION, parse_pagination_link
from ansible_collections.community.general.plugins.plugin_utils.unsafe import make_unsafe
from ansible.module_utils.urls import open_url
-from ansible.module_utils.common.text.converters import to_native, to_text
+from ansible.module_utils.common.text.converters import to_text
from ansible.module_utils.six import raise_from
import ansible.module_utils.six.moves.urllib.parse as urllib_parse
@@ -140,7 +142,7 @@ def _fetch_information(token, url):
headers={'X-Auth-Token': token,
'Content-type': 'application/json'})
except Exception as e:
- raise AnsibleError("Error while fetching %s: %s" % (url, to_native(e)))
+ raise AnsibleError(f"Error while fetching {url}: {e}")
try:
raw_json = json.loads(to_text(response.read()))
except ValueError:
@@ -161,7 +163,7 @@ def _fetch_information(token, url):
def _build_server_url(api_endpoint):
- return "/".join([api_endpoint, "servers"])
+ return f"{api_endpoint}/servers"
def extract_public_ipv4(server_info):
diff --git a/plugins/inventory/stackpath_compute.py b/plugins/inventory/stackpath_compute.py
index 8508b4e797..bc55027155 100644
--- a/plugins/inventory/stackpath_compute.py
+++ b/plugins/inventory/stackpath_compute.py
@@ -4,8 +4,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
DOCUMENTATION = '''
name: stackpath_compute
@@ -139,7 +138,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
"Content-Type": "application/json",
}
resp = open_url(
- self.api_host + '/identity/v1/oauth2/token',
+ f"{self.api_host}/identity/v1/oauth2/token",
headers=headers,
data=payload,
method="POST"
@@ -155,16 +154,16 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
self._authenticate()
for stack_slug in self.stack_slugs:
try:
- workloads = self._stackpath_query_get_list(self.api_host + '/workload/v1/stacks/' + stack_slug + '/workloads')
+ workloads = self._stackpath_query_get_list(f"{self.api_host}/workload/v1/stacks/{stack_slug}/workloads")
except Exception:
- raise AnsibleError("Failed to get workloads from the StackPath API: %s" % traceback.format_exc())
+ raise AnsibleError(f"Failed to get workloads from the StackPath API: {traceback.format_exc()}")
for workload in workloads:
try:
workload_instances = self._stackpath_query_get_list(
- self.api_host + '/workload/v1/stacks/' + stack_slug + '/workloads/' + workload["id"] + '/instances'
+ f"{self.api_host}/workload/v1/stacks/{stack_slug}/workloads/{workload['id']}/instances"
)
except Exception:
- raise AnsibleError("Failed to get workload instances from the StackPath API: %s" % traceback.format_exc())
+ raise AnsibleError(f"Failed to get workload instances from the StackPath API: {traceback.format_exc()}")
for instance in workload_instances:
if instance["phase"] == "RUNNING":
instance["stackSlug"] = stack_slug
@@ -184,7 +183,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
def _populate(self, instances):
for instance in instances:
for group_key in self.group_keys:
- group = group_key + "_" + instance[group_key]
+ group = f"{group_key}_{instance[group_key]}"
group = group.lower().replace(" ", "_").replace("-", "_")
self.inventory.add_group(group)
self.inventory.add_host(instance[self.hostname_key],
@@ -194,14 +193,14 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
self._authenticate()
headers = {
"Content-Type": "application/json",
- "Authorization": "Bearer " + self.auth_token,
+ "Authorization": f"Bearer {self.auth_token}",
}
next_page = True
result = []
cursor = '-1'
while next_page:
resp = open_url(
- url + '?page_request.first=10&page_request.after=%s' % cursor,
+ f"{url}?page_request.first=10&page_request.after={cursor}",
headers=headers,
method="GET"
)
@@ -251,10 +250,10 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
self.stack_slugs = self.get_option('stack_slugs')
if not self.stack_slugs:
try:
- stacks = self._stackpath_query_get_list(self.api_host + '/stack/v1/stacks')
+ stacks = self._stackpath_query_get_list(f"{self.api_host}/stack/v1/stacks")
self._get_stack_slugs(stacks)
except Exception:
- raise AnsibleError("Failed to get stack IDs from the Stackpath API: %s" % traceback.format_exc())
+ raise AnsibleError(f"Failed to get stack IDs from the Stackpath API: {traceback.format_exc()}")
cache_key = self.get_cache_key(path)
# false when refresh_cache or --flush-cache is used
@@ -283,4 +282,4 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
if cache_needs_update or (not cache and self.get_option('cache')):
self._cache[cache_key] = results
except Exception:
- raise AnsibleError("Failed to populate data: %s" % traceback.format_exc())
+ raise AnsibleError(f"Failed to populate data: {traceback.format_exc()}")
diff --git a/plugins/inventory/virtualbox.py b/plugins/inventory/virtualbox.py
index d48c294fd9..db2750f636 100644
--- a/plugins/inventory/virtualbox.py
+++ b/plugins/inventory/virtualbox.py
@@ -3,8 +3,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
@@ -56,15 +55,16 @@ DOCUMENTATION = '''
'''
EXAMPLES = '''
+---
# file must be named vbox.yaml or vbox.yml
-simple_config_file:
- plugin: community.general.virtualbox
- settings_password_file: /etc/virtulbox/secrets
- query:
- logged_in_users: /VirtualBox/GuestInfo/OS/LoggedInUsersList
- compose:
- ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh')
+plugin: community.general.virtualbox
+settings_password_file: /etc/virtualbox/secrets
+query:
+ logged_in_users: /VirtualBox/GuestInfo/OS/LoggedInUsersList
+compose:
+ ansible_connection: ('indows' in vbox_Guest_OS)|ternary('winrm', 'ssh')
+---
# add hosts (all match with minishift vm) to the group container if any of the vms are in ansible_inventory'
plugin: community.general.virtualbox
groups:
@@ -76,7 +76,7 @@ import os
from subprocess import Popen, PIPE
from ansible.errors import AnsibleParserError
-from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_text
from ansible.module_utils.common._collections_compat import MutableMapping
from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable
from ansible.module_utils.common.process import get_bin_path
@@ -203,7 +203,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
else:
# found vars, accumulate in hostvars for clean inventory set
- pref_k = make_unsafe('vbox_' + k.strip().replace(' ', '_'))
+ pref_k = make_unsafe(f"vbox_{k.strip().replace(' ', '_')}")
leading_spaces = len(k) - len(k.lstrip(' '))
if 0 < leading_spaces <= 2:
if prevkey not in hostvars[current_host] or not isinstance(hostvars[current_host][prevkey], dict):
@@ -257,7 +257,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
def _handle_vboxmanage_group_string(self, vboxmanage_group, current_host, cacheable_results):
'''Handles parsing the VM's Group assignment from VBoxManage according to VirtualBox documentation.'''
# Per the VirtualBox documentation, a VM can be part of many groups,
- # and it's possible to have nested groups.
+ # and it is possible to have nested groups.
# Many groups are separated by commas ",", and nested groups use
# slash "/".
# https://www.virtualbox.org/manual/UserManual.html#gui-vmgroups
@@ -352,7 +352,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
try:
p = Popen(cmd, stdout=PIPE)
except Exception as e:
- raise AnsibleParserError(to_native(e))
+ raise AnsibleParserError(str(e))
source_data = p.stdout.read().splitlines()
diff --git a/plugins/inventory/xen_orchestra.py b/plugins/inventory/xen_orchestra.py
index 4094af2468..4a6d431a7d 100644
--- a/plugins/inventory/xen_orchestra.py
+++ b/plugins/inventory/xen_orchestra.py
@@ -3,8 +3,7 @@
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
DOCUMENTATION = '''
name: xen_orchestra
@@ -58,6 +57,20 @@ DOCUMENTATION = '''
description: Use wss when connecting to the Xen Orchestra API
type: boolean
default: true
+ use_vm_uuid:
+ description:
+ - Import Xen VMs to inventory using their UUID as the VM entry name.
+ - If set to V(false) use VM name labels instead of UUIDs.
+ type: boolean
+ default: true
+ version_added: 10.4.0
+ use_host_uuid:
+ description:
+ - Import Xen Hosts to inventory using their UUID as the Host entry name.
+ - If set to V(false) use Host name labels instead of UUIDs.
+ type: boolean
+ default: true
+ version_added: 10.4.0
'''
@@ -73,6 +86,8 @@ groups:
kube_nodes: "'kube_node' in tags"
compose:
ansible_port: 2222
+use_vm_uuid: false
+use_host_uuid: true
'''
@@ -138,7 +153,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
sslopt = None if validate_certs else {'cert_reqs': ssl.CERT_NONE}
self.conn = create_connection(
- '{0}://{1}/api/'.format(proto, xoa_api_host), sslopt=sslopt)
+ f'{proto}://{xoa_api_host}/api/', sslopt=sslopt)
CALL_TIMEOUT = 100
"""Number of 1/10ths of a second to wait before method call times out."""
@@ -162,8 +177,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
sleep(0.1)
waited += 1
- raise AnsibleError(
- 'Method call {method} timed out after {timeout} seconds.'.format(method=method, timeout=self.CALL_TIMEOUT / 10))
+ raise AnsibleError(f'Method call {method} timed out after {self.CALL_TIMEOUT / 10} seconds.')
def login(self, user, password):
result = self.call('session.signIn', {
@@ -171,15 +185,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
})
if 'error' in result:
- raise AnsibleError(
- 'Could not connect: {0}'.format(result['error']))
+ raise AnsibleError(f"Could not connect: {result['error']}")
def get_object(self, name):
answer = self.call('xo.getAllObjects', {'filter': {'type': name}})
if 'error' in answer:
- raise AnsibleError(
- 'Could not request: {0}'.format(answer['error']))
+ raise AnsibleError(f"Could not request: {answer['error']}")
return answer['result']
@@ -200,10 +212,20 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
self._set_composite_vars(self.get_option('compose'), variables, name, strict=strict)
def _add_vms(self, vms, hosts, pools):
+ vm_name_list = []
for uuid, vm in vms.items():
+ if self.vm_entry_name_type == 'name_label':
+ if vm['name_label'] not in vm_name_list:
+ entry_name = vm['name_label']
+ vm_name_list.append(vm['name_label'])
+ else:
+ vm_duplicate_count = vm_name_list.count(vm['name_label'])
+ entry_name = vm['name_label'] + "_" + str(vm_duplicate_count)
+ vm_name_list.append(vm['name_label'])
+ else:
+ entry_name = uuid
group = 'with_ip'
ip = vm.get('mainIpAddress')
- entry_name = uuid
power_state = vm['power_state'].lower()
pool_name = self._pool_group_name_for_uuid(pools, vm['$poolId'])
host_name = self._host_group_name_for_uuid(hosts, vm['$container'])
@@ -250,10 +272,20 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
self._apply_constructable(entry_name, self.inventory.get_host(entry_name).get_vars())
def _add_hosts(self, hosts, pools):
+ host_name_list = []
for host in hosts.values():
- entry_name = host['uuid']
- group_name = 'xo_host_{0}'.format(
- clean_group_name(host['name_label']))
+ if self.host_entry_name_type == 'name_label':
+ if host['name_label'] not in host_name_list:
+ entry_name = host['name_label']
+ host_name_list.append(host['name_label'])
+ else:
+ host_duplicate_count = host_name_list.count(host['name_label'])
+ entry_name = host['name_label'] + "_" + str(host_duplicate_count)
+ host_name_list.append(host['name_label'])
+ else:
+ entry_name = host['uuid']
+
+ group_name = f"xo_host_{clean_group_name(host['name_label'])}"
pool_name = self._pool_group_name_for_uuid(pools, host['$poolId'])
self.inventory.add_group(group_name)
@@ -276,15 +308,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
entry_name, 'product_brand', host['productBrand'])
for pool in pools.values():
- group_name = 'xo_pool_{0}'.format(
- clean_group_name(pool['name_label']))
+ group_name = f"xo_pool_{clean_group_name(pool['name_label'])}"
self.inventory.add_group(group_name)
def _add_pools(self, pools):
for pool in pools.values():
- group_name = 'xo_pool_{0}'.format(
- clean_group_name(pool['name_label']))
+ group_name = f"xo_pool_{clean_group_name(pool['name_label'])}"
self.inventory.add_group(group_name)
@@ -292,16 +322,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
def _pool_group_name_for_uuid(self, pools, pool_uuid):
for pool in pools:
if pool == pool_uuid:
- return 'xo_pool_{0}'.format(
- clean_group_name(pools[pool_uuid]['name_label']))
+ return f"xo_pool_{clean_group_name(pools[pool_uuid]['name_label'])}"
# TODO: Refactor
def _host_group_name_for_uuid(self, hosts, host_uuid):
for host in hosts:
if host == host_uuid:
- return 'xo_host_{0}'.format(
- clean_group_name(hosts[host_uuid]['name_label']
- ))
+ return f"xo_host_{clean_group_name(hosts[host_uuid]['name_label'])}"
def _populate(self, objects):
# Prepare general groups
@@ -347,5 +374,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
if not self.get_option('use_ssl'):
self.protocol = 'ws'
+ self.vm_entry_name_type = 'uuid'
+ if not self.get_option('use_vm_uuid'):
+ self.vm_entry_name_type = 'name_label'
+
+ self.host_entry_name_type = 'uuid'
+ if not self.get_option('use_host_uuid'):
+ self.host_entry_name_type = 'name_label'
+
objects = self._get_objects()
self._populate(make_unsafe(objects))
diff --git a/plugins/lookup/bitwarden.py b/plugins/lookup/bitwarden.py
index 5e31cc6f89..c41ab72ac3 100644
--- a/plugins/lookup/bitwarden.py
+++ b/plugins/lookup/bitwarden.py
@@ -37,9 +37,17 @@ DOCUMENTATION = """
description: Field to fetch. Leave unset to fetch whole response.
type: str
collection_id:
- description: Collection ID to filter results by collection. Leave unset to skip filtering.
+ description:
+ - Collection ID to filter results by collection. Leave unset to skip filtering.
+ - O(collection_id) and O(collection_name) are mutually exclusive.
type: str
version_added: 6.3.0
+ collection_name:
+ description:
+ - Collection name to filter results by collection. Leave unset to skip filtering.
+ - O(collection_id) and O(collection_name) are mutually exclusive.
+ type: str
+ version_added: 10.4.0
organization_id:
description: Organization ID to filter results by organization. Leave unset to skip filtering.
type: str
@@ -48,6 +56,12 @@ DOCUMENTATION = """
description: Pass session key instead of reading from env.
type: str
version_added: 8.4.0
+ result_count:
+ description:
+ - Number of results expected for the lookup query. Task will fail if O(result_count)
+ is set but does not match the number of query results. Leave empty to skip this check.
+ type: int
+ version_added: 10.4.0
"""
EXAMPLES = """
@@ -85,6 +99,16 @@ EXAMPLES = """
ansible.builtin.debug:
msg: >-
{{ lookup('community.general.bitwarden', None, collection_id='bafba515-af11-47e6-abe3-af1200cd18b2') }}
+
+- name: "Get all Bitwarden records from collection"
+ ansible.builtin.debug:
+ msg: >-
+ {{ lookup('community.general.bitwarden', None, collection_name='my_collections/test_collection') }}
+
+- name: "Get Bitwarden record named 'a_test', ensure there is exactly one match"
+ ansible.builtin.debug:
+ msg: >-
+ {{ lookup('community.general.bitwarden', 'a_test', result_count=1) }}
"""
RETURN = """
@@ -99,7 +123,7 @@ RETURN = """
from subprocess import Popen, PIPE
-from ansible.errors import AnsibleError
+from ansible.errors import AnsibleError, AnsibleOptionsError
from ansible.module_utils.common.text.converters import to_bytes, to_text
from ansible.parsing.ajson import AnsibleJSONDecoder
from ansible.plugins.lookup import LookupBase
@@ -207,10 +231,28 @@ class Bitwarden(object):
continue
if matches and not field_matches:
- raise AnsibleError("field {field} does not exist in {search_value}".format(field=field, search_value=search_value))
+ raise AnsibleError(f"field {field} does not exist in {search_value}")
return field_matches
+ def get_collection_ids(self, collection_name: str, organization_id=None) -> list[str]:
+ """Return matching IDs of collections whose name is equal to collection_name."""
+
+ # Prepare set of params for Bitwarden CLI
+ params = ['list', 'collections', '--search', collection_name]
+
+ if organization_id:
+ params.extend(['--organizationid', organization_id])
+
+ out, err = self._run(params)
+
+ # This includes things that matched in different fields.
+ initial_matches = AnsibleJSONDecoder().raw_decode(out)[0]
+
+ # Filter to only return the ID of a collections with exactly matching name
+ return [item['id'] for item in initial_matches
+ if str(item.get('name')).lower() == collection_name.lower()]
+
class LookupModule(LookupBase):
@@ -219,7 +261,9 @@ class LookupModule(LookupBase):
field = self.get_option('field')
search_field = self.get_option('search')
collection_id = self.get_option('collection_id')
+ collection_name = self.get_option('collection_name')
organization_id = self.get_option('organization_id')
+ result_count = self.get_option('result_count')
_bitwarden.session = self.get_option('bw_session')
if not _bitwarden.unlocked:
@@ -228,7 +272,27 @@ class LookupModule(LookupBase):
if not terms:
terms = [None]
- return [_bitwarden.get_field(field, term, search_field, collection_id, organization_id) for term in terms]
+ if collection_name and collection_id:
+ raise AnsibleOptionsError("'collection_name' and 'collection_id' are mutually exclusive!")
+ elif collection_name:
+ collection_ids = _bitwarden.get_collection_ids(collection_name, organization_id)
+ if not collection_ids:
+ raise BitwardenException("No matching collections found!")
+ else:
+ collection_ids = [collection_id]
+
+ results = [
+ _bitwarden.get_field(field, term, search_field, collection_id, organization_id)
+ for collection_id in collection_ids
+ for term in terms
+ ]
+
+ for result in results:
+ if result_count is not None and len(result) != result_count:
+ raise BitwardenException(
+ f"Number of results doesn't match result_count! ({len(result)} != {result_count})")
+
+ return results
_bitwarden = Bitwarden()
diff --git a/plugins/lookup/chef_databag.py b/plugins/lookup/chef_databag.py
index a116b21e5f..eaa6a1aefa 100644
--- a/plugins/lookup/chef_databag.py
+++ b/plugins/lookup/chef_databag.py
@@ -81,11 +81,11 @@ class LookupModule(LookupBase):
setattr(self, arg, parsed)
except ValueError:
raise AnsibleError(
- "can't parse arg {0}={1} as string".format(arg, arg_raw)
+ f"can't parse arg {arg}={arg_raw} as string"
)
if args:
raise AnsibleError(
- "unrecognized arguments to with_sequence: %r" % list(args.keys())
+ f"unrecognized arguments to with_sequence: {list(args.keys())!r}"
)
def run(self, terms, variables=None, **kwargs):
diff --git a/plugins/lookup/collection_version.py b/plugins/lookup/collection_version.py
index 0f93c03c26..28a9c34420 100644
--- a/plugins/lookup/collection_version.py
+++ b/plugins/lookup/collection_version.py
@@ -115,10 +115,10 @@ class LookupModule(LookupBase):
for term in terms:
if not FQCN_RE.match(term):
- raise AnsibleLookupError('"{term}" is not a FQCN'.format(term=term))
+ raise AnsibleLookupError(f'"{term}" is not a FQCN')
try:
- collection_pkg = import_module('ansible_collections.{fqcn}'.format(fqcn=term))
+ collection_pkg = import_module(f'ansible_collections.{term}')
except ImportError:
# Collection not found
result.append(not_found)
@@ -127,7 +127,7 @@ class LookupModule(LookupBase):
try:
data = load_collection_meta(collection_pkg, no_version=no_version)
except Exception as exc:
- raise AnsibleLookupError('Error while loading metadata for {fqcn}: {error}'.format(fqcn=term, error=exc))
+ raise AnsibleLookupError(f'Error while loading metadata for {term}: {exc}')
result.append(data.get('version', no_version))
diff --git a/plugins/lookup/consul_kv.py b/plugins/lookup/consul_kv.py
index 79eb65edb1..cf7226d579 100644
--- a/plugins/lookup/consul_kv.py
+++ b/plugins/lookup/consul_kv.py
@@ -171,7 +171,7 @@ class LookupModule(LookupBase):
values.append(to_text(results[1]['Value']))
except Exception as e:
raise AnsibleError(
- "Error locating '%s' in kv store. Error was %s" % (term, e))
+ f"Error locating '{term}' in kv store. Error was {e}")
return values
@@ -192,7 +192,7 @@ class LookupModule(LookupBase):
if param and len(param) > 0:
name, value = param.split('=')
if name not in paramvals:
- raise AnsibleAssertionError("%s not a valid consul lookup parameter" % name)
+ raise AnsibleAssertionError(f"{name} not a valid consul lookup parameter")
paramvals[name] = value
except (ValueError, AssertionError) as e:
raise AnsibleError(e)
diff --git a/plugins/lookup/credstash.py b/plugins/lookup/credstash.py
index fd284f55c8..0700a5ddcb 100644
--- a/plugins/lookup/credstash.py
+++ b/plugins/lookup/credstash.py
@@ -137,8 +137,8 @@ class LookupModule(LookupBase):
try:
ret.append(credstash.getSecret(term, version, region, table, context=context, **kwargs_pass))
except credstash.ItemNotFound:
- raise AnsibleError('Key {0} not found'.format(term))
+ raise AnsibleError(f'Key {term} not found')
except Exception as e:
- raise AnsibleError('Encountered exception while fetching {0}: {1}'.format(term, e))
+ raise AnsibleError(f'Encountered exception while fetching {term}: {e}')
return ret
diff --git a/plugins/lookup/cyberarkpassword.py b/plugins/lookup/cyberarkpassword.py
index 6a08675b3b..4ed040dc6d 100644
--- a/plugins/lookup/cyberarkpassword.py
+++ b/plugins/lookup/cyberarkpassword.py
@@ -84,7 +84,7 @@ from subprocess import Popen
from ansible.errors import AnsibleError
from ansible.plugins.lookup import LookupBase
-from ansible.module_utils.common.text.converters import to_bytes, to_text, to_native
+from ansible.module_utils.common.text.converters import to_bytes, to_native
from ansible.utils.display import Display
display = Display()
@@ -105,7 +105,7 @@ class CyberarkPassword:
self.extra_parms = []
for key, value in kwargs.items():
self.extra_parms.append('-p')
- self.extra_parms.append("%s=%s" % (key, value))
+ self.extra_parms.append(f"{key}={value}")
if self.appid is None:
raise AnsibleError("CyberArk Error: No Application ID specified")
@@ -130,8 +130,8 @@ class CyberarkPassword:
all_parms = [
CLIPASSWORDSDK_CMD,
'GetPassword',
- '-p', 'AppDescs.AppID=%s' % self.appid,
- '-p', 'Query=%s' % self.query,
+ '-p', f'AppDescs.AppID={self.appid}',
+ '-p', f'Query={self.query}',
'-o', self.output,
'-d', self.b_delimiter]
all_parms.extend(self.extra_parms)
@@ -144,7 +144,7 @@ class CyberarkPassword:
b_credential = to_bytes(tmp_output)
if tmp_error:
- raise AnsibleError("ERROR => %s " % (tmp_error))
+ raise AnsibleError(f"ERROR => {tmp_error} ")
if b_credential and b_credential.endswith(b'\n'):
b_credential = b_credential[:-1]
@@ -164,7 +164,7 @@ class CyberarkPassword:
except subprocess.CalledProcessError as e:
raise AnsibleError(e.output)
except OSError as e:
- raise AnsibleError("ERROR - AIM not installed or clipasswordsdk not in standard location. ERROR=(%s) => %s " % (to_text(e.errno), e.strerror))
+ raise AnsibleError(f"ERROR - AIM not installed or clipasswordsdk not in standard location. ERROR=({e.errno}) => {e.strerror} ")
return [result_dict]
@@ -177,11 +177,11 @@ class LookupModule(LookupBase):
"""
def run(self, terms, variables=None, **kwargs):
- display.vvvv("%s" % terms)
+ display.vvvv(f"{terms}")
if isinstance(terms, list):
return_values = []
for term in terms:
- display.vvvv("Term: %s" % term)
+ display.vvvv(f"Term: {term}")
cyberark_conn = CyberarkPassword(**term)
return_values.append(cyberark_conn.get())
return return_values
diff --git a/plugins/lookup/dependent.py b/plugins/lookup/dependent.py
index 31634e6e6e..1ec4369b32 100644
--- a/plugins/lookup/dependent.py
+++ b/plugins/lookup/dependent.py
@@ -173,8 +173,7 @@ class LookupModule(LookupBase):
values = self.__evaluate(expression, templar, variables=vars)
except Exception as e:
raise AnsibleLookupError(
- 'Caught "{error}" while evaluating {key!r} with item == {item!r}'.format(
- error=e, key=key, item=current))
+ f'Caught "{e}" while evaluating {key!r} with item == {current!r}')
if isinstance(values, Mapping):
for idx, val in sorted(values.items()):
@@ -186,8 +185,7 @@ class LookupModule(LookupBase):
self.__process(result, terms, index + 1, current, templar, variables)
else:
raise AnsibleLookupError(
- 'Did not obtain dictionary or list while evaluating {key!r} with item == {item!r}, but {type}'.format(
- key=key, item=current, type=type(values)))
+ f'Did not obtain dictionary or list while evaluating {key!r} with item == {current!r}, but {type(values)}')
def run(self, terms, variables=None, **kwargs):
"""Generate list."""
@@ -201,16 +199,14 @@ class LookupModule(LookupBase):
for index, term in enumerate(terms):
if not isinstance(term, Mapping):
raise AnsibleLookupError(
- 'Parameter {index} must be a dictionary, got {type}'.format(
- index=index, type=type(term)))
+ f'Parameter {index} must be a dictionary, got {type(term)}')
if len(term) != 1:
raise AnsibleLookupError(
- 'Parameter {index} must be a one-element dictionary, got {count} elements'.format(
- index=index, count=len(term)))
+ f'Parameter {index} must be a one-element dictionary, got {len(term)} elements')
k, v = list(term.items())[0]
if k in vars_so_far:
raise AnsibleLookupError(
- 'The variable {key!r} appears more than once'.format(key=k))
+ f'The variable {k!r} appears more than once')
vars_so_far.add(k)
if isinstance(v, string_types):
data.append((k, v, None))
@@ -218,7 +214,6 @@ class LookupModule(LookupBase):
data.append((k, None, v))
else:
raise AnsibleLookupError(
- 'Parameter {key!r} (index {index}) must have a value of type string, dictionary or list, got type {type}'.format(
- index=index, key=k, type=type(v)))
+ f'Parameter {k!r} (index {index}) must have a value of type string, dictionary or list, got type {type(v)}')
self.__process(result, data, 0, {}, templar, variables)
return result
diff --git a/plugins/lookup/dig.py b/plugins/lookup/dig.py
index aae5ffe834..cbb597b7b5 100644
--- a/plugins/lookup/dig.py
+++ b/plugins/lookup/dig.py
@@ -220,7 +220,6 @@ RETURN = """
from ansible.errors import AnsibleError
from ansible.plugins.lookup import LookupBase
-from ansible.module_utils.common.text.converters import to_native
from ansible.module_utils.parsing.convert_bool import boolean
from ansible.utils.display import Display
import socket
@@ -345,7 +344,7 @@ class LookupModule(LookupBase):
try:
rdclass = dns.rdataclass.from_text(self.get_option('class'))
except Exception as e:
- raise AnsibleError("dns lookup illegal CLASS: %s" % to_native(e))
+ raise AnsibleError(f"dns lookup illegal CLASS: {e}")
myres.retry_servfail = self.get_option('retry_servfail')
for t in terms:
@@ -363,7 +362,7 @@ class LookupModule(LookupBase):
nsaddr = dns.resolver.query(ns)[0].address
nameservers.append(nsaddr)
except Exception as e:
- raise AnsibleError("dns lookup NS: %s" % to_native(e))
+ raise AnsibleError(f"dns lookup NS: {e}")
continue
if '=' in t:
try:
@@ -379,7 +378,7 @@ class LookupModule(LookupBase):
try:
rdclass = dns.rdataclass.from_text(arg)
except Exception as e:
- raise AnsibleError("dns lookup illegal CLASS: %s" % to_native(e))
+ raise AnsibleError(f"dns lookup illegal CLASS: {e}")
elif opt == 'retry_servfail':
myres.retry_servfail = boolean(arg)
elif opt == 'fail_on_error':
@@ -400,7 +399,7 @@ class LookupModule(LookupBase):
else:
domains.append(t)
- # print "--- domain = {0} qtype={1} rdclass={2}".format(domain, qtype, rdclass)
+ # print "--- domain = {domain} qtype={qtype} rdclass={rdclass}"
if port:
myres.port = port
@@ -416,7 +415,7 @@ class LookupModule(LookupBase):
except dns.exception.SyntaxError:
pass
except Exception as e:
- raise AnsibleError("dns.reversename unhandled exception %s" % to_native(e))
+ raise AnsibleError(f"dns.reversename unhandled exception {e}")
domains = reversed_domains
if len(domains) > 1:
@@ -445,25 +444,20 @@ class LookupModule(LookupBase):
ret.append(rd)
except Exception as err:
if fail_on_error:
- raise AnsibleError("Lookup failed: %s" % str(err))
+ raise AnsibleError(f"Lookup failed: {err}")
ret.append(str(err))
except dns.resolver.NXDOMAIN as err:
if fail_on_error:
- raise AnsibleError("Lookup failed: %s" % str(err))
+ raise AnsibleError(f"Lookup failed: {err}")
if not real_empty:
ret.append('NXDOMAIN')
- except dns.resolver.NoAnswer as err:
+ except (dns.resolver.NoAnswer, dns.resolver.Timeout, dns.resolver.NoNameservers) as err:
if fail_on_error:
- raise AnsibleError("Lookup failed: %s" % str(err))
- if not real_empty:
- ret.append("")
- except dns.resolver.Timeout as err:
- if fail_on_error:
- raise AnsibleError("Lookup failed: %s" % str(err))
+ raise AnsibleError(f"Lookup failed: {err}")
if not real_empty:
ret.append("")
except dns.exception.DNSException as err:
- raise AnsibleError("dns.resolver unhandled exception %s" % to_native(err))
+ raise AnsibleError(f"dns.resolver unhandled exception {err}")
return ret
diff --git a/plugins/lookup/dnstxt.py b/plugins/lookup/dnstxt.py
index 1ce511b849..baaa63aa98 100644
--- a/plugins/lookup/dnstxt.py
+++ b/plugins/lookup/dnstxt.py
@@ -64,7 +64,6 @@ except ImportError:
pass
from ansible.errors import AnsibleError
-from ansible.module_utils.common.text.converters import to_native
from ansible.plugins.lookup import LookupBase
# ==============================================================
@@ -108,7 +107,7 @@ class LookupModule(LookupBase):
continue
string = ''
except DNSException as e:
- raise AnsibleError("dns.resolver unhandled exception %s" % to_native(e))
+ raise AnsibleError(f"dns.resolver unhandled exception {e}")
ret.append(''.join(string))
diff --git a/plugins/lookup/dsv.py b/plugins/lookup/dsv.py
index 5e26c43af4..eba3e36368 100644
--- a/plugins/lookup/dsv.py
+++ b/plugins/lookup/dsv.py
@@ -135,17 +135,17 @@ class LookupModule(LookupBase):
result = []
for term in terms:
- display.debug("dsv_lookup term: %s" % term)
+ display.debug(f"dsv_lookup term: {term}")
try:
path = term.lstrip("[/:]")
if path == "":
- raise AnsibleOptionsError("Invalid secret path: %s" % term)
+ raise AnsibleOptionsError(f"Invalid secret path: {term}")
- display.vvv(u"DevOps Secrets Vault GET /secrets/%s" % path)
+ display.vvv(f"DevOps Secrets Vault GET /secrets/{path}")
result.append(vault.get_secret_json(path))
except SecretsVaultError as error:
raise AnsibleError(
- "DevOps Secrets Vault lookup failure: %s" % error.message
+ f"DevOps Secrets Vault lookup failure: {error.message}"
)
return result
diff --git a/plugins/lookup/etcd.py b/plugins/lookup/etcd.py
index 1dec890b20..1e7dc3c960 100644
--- a/plugins/lookup/etcd.py
+++ b/plugins/lookup/etcd.py
@@ -104,7 +104,7 @@ class Etcd:
def __init__(self, url, version, validate_certs):
self.url = url
self.version = version
- self.baseurl = '%s/%s/keys' % (self.url, self.version)
+ self.baseurl = f'{self.url}/{self.version}/keys'
self.validate_certs = validate_certs
def _parse_node(self, node):
@@ -125,7 +125,7 @@ class Etcd:
return path
def get(self, key):
- url = "%s/%s?recursive=true" % (self.baseurl, key)
+ url = f"{self.baseurl}/{key}?recursive=true"
data = None
value = {}
try:
diff --git a/plugins/lookup/etcd3.py b/plugins/lookup/etcd3.py
index 0bda006e34..c67e975b97 100644
--- a/plugins/lookup/etcd3.py
+++ b/plugins/lookup/etcd3.py
@@ -168,7 +168,7 @@ def etcd3_client(client_params):
etcd = etcd3.client(**client_params)
etcd.status()
except Exception as exp:
- raise AnsibleLookupError('Cannot connect to etcd cluster: %s' % (to_native(exp)))
+ raise AnsibleLookupError(f'Cannot connect to etcd cluster: {exp}')
return etcd
@@ -204,7 +204,7 @@ class LookupModule(LookupBase):
cnx_log = dict(client_params)
if 'password' in cnx_log:
cnx_log['password'] = ''
- display.verbose("etcd3 connection parameters: %s" % cnx_log)
+ display.verbose(f"etcd3 connection parameters: {cnx_log}")
# connect to etcd3 server
etcd = etcd3_client(client_params)
@@ -218,12 +218,12 @@ class LookupModule(LookupBase):
if val and meta:
ret.append({'key': to_native(meta.key), 'value': to_native(val)})
except Exception as exp:
- display.warning('Caught except during etcd3.get_prefix: %s' % (to_native(exp)))
+ display.warning(f'Caught except during etcd3.get_prefix: {exp}')
else:
try:
val, meta = etcd.get(term)
if val and meta:
ret.append({'key': to_native(meta.key), 'value': to_native(val)})
except Exception as exp:
- display.warning('Caught except during etcd3.get: %s' % (to_native(exp)))
+ display.warning(f'Caught except during etcd3.get: {exp}')
return ret
diff --git a/plugins/lookup/filetree.py b/plugins/lookup/filetree.py
index ee7bfe27b7..3036e152c2 100644
--- a/plugins/lookup/filetree.py
+++ b/plugins/lookup/filetree.py
@@ -158,7 +158,7 @@ def file_props(root, path):
try:
st = os.lstat(abspath)
except OSError as e:
- display.warning('filetree: Error using stat() on path %s (%s)' % (abspath, e))
+ display.warning(f'filetree: Error using stat() on path {abspath} ({e})')
return None
ret = dict(root=root, path=path)
@@ -172,7 +172,7 @@ def file_props(root, path):
ret['state'] = 'file'
ret['src'] = abspath
else:
- display.warning('filetree: Error file type of %s is not supported' % abspath)
+ display.warning(f'filetree: Error file type of {abspath} is not supported')
return None
ret['uid'] = st.st_uid
@@ -185,7 +185,7 @@ def file_props(root, path):
ret['group'] = to_text(grp.getgrgid(st.st_gid).gr_name)
except KeyError:
ret['group'] = st.st_gid
- ret['mode'] = '0%03o' % (stat.S_IMODE(st.st_mode))
+ ret['mode'] = f'0{stat.S_IMODE(st.st_mode):03o}'
ret['size'] = st.st_size
ret['mtime'] = st.st_mtime
ret['ctime'] = st.st_ctime
@@ -212,7 +212,7 @@ class LookupModule(LookupBase):
term_file = os.path.basename(term)
dwimmed_path = self._loader.path_dwim_relative(basedir, 'files', os.path.dirname(term))
path = os.path.join(dwimmed_path, term_file)
- display.debug("Walking '{0}'".format(path))
+ display.debug(f"Walking '{path}'")
for root, dirs, files in os.walk(path, topdown=True):
for entry in dirs + files:
relpath = os.path.relpath(os.path.join(root, entry), path)
@@ -221,7 +221,7 @@ class LookupModule(LookupBase):
if relpath not in [entry['path'] for entry in ret]:
props = file_props(path, relpath)
if props is not None:
- display.debug(" found '{0}'".format(os.path.join(path, relpath)))
+ display.debug(f" found '{os.path.join(path, relpath)}'")
ret.append(props)
return ret
diff --git a/plugins/lookup/flattened.py b/plugins/lookup/flattened.py
index 0071417a0d..5365f2ca99 100644
--- a/plugins/lookup/flattened.py
+++ b/plugins/lookup/flattened.py
@@ -78,7 +78,7 @@ class LookupModule(LookupBase):
term = term2
if isinstance(term, list):
- # if it's a list, check recursively for items that are a list
+ # if it is a list, check recursively for items that are a list
term = self._do_flatten(term, variables)
ret.extend(term)
else:
diff --git a/plugins/lookup/github_app_access_token.py b/plugins/lookup/github_app_access_token.py
index 1d3c526c33..73fd09a0a9 100644
--- a/plugins/lookup/github_app_access_token.py
+++ b/plugins/lookup/github_app_access_token.py
@@ -55,8 +55,8 @@ EXAMPLES = '''
dest: /srv/checkout
vars:
github_token: >-
- lookup('community.general.github_app_access_token', key_path='/home/to_your/key',
- app_id='123456', installation_id='64209')
+ {{ lookup('community.general.github_app_access_token', key_path='/home/to_your/key',
+ app_id='123456', installation_id='64209') }}
'''
RETURN = '''
@@ -97,7 +97,7 @@ def read_key(path, private_key=None):
with open(path, 'rb') as pem_file:
return jwk_from_pem(pem_file.read())
except Exception as e:
- raise AnsibleError("Error while parsing key file: {0}".format(e))
+ raise AnsibleError(f"Error while parsing key file: {e}")
def encode_jwt(app_id, jwk, exp=600):
@@ -110,7 +110,7 @@ def encode_jwt(app_id, jwk, exp=600):
try:
return jwt_instance.encode(payload, jwk, alg='RS256')
except Exception as e:
- raise AnsibleError("Error while encoding jwt: {0}".format(e))
+ raise AnsibleError(f"Error while encoding jwt: {e}")
def post_request(generated_jwt, installation_id):
@@ -124,19 +124,19 @@ def post_request(generated_jwt, installation_id):
except HTTPError as e:
try:
error_body = json.loads(e.read().decode())
- display.vvv("Error returned: {0}".format(error_body))
+ display.vvv(f"Error returned: {error_body}")
except Exception:
error_body = {}
if e.code == 404:
raise AnsibleError("Github return error. Please confirm your installationd_id value is valid")
elif e.code == 401:
raise AnsibleError("Github return error. Please confirm your private key is valid")
- raise AnsibleError("Unexpected data returned: {0} -- {1}".format(e, error_body))
+ raise AnsibleError(f"Unexpected data returned: {e} -- {error_body}")
response_body = response.read()
try:
json_data = json.loads(response_body.decode('utf-8'))
except json.decoder.JSONDecodeError as e:
- raise AnsibleError("Error while dencoding JSON respone from github: {0}".format(e))
+ raise AnsibleError(f"Error while dencoding JSON respone from github: {e}")
return json_data.get('token')
diff --git a/plugins/lookup/hiera.py b/plugins/lookup/hiera.py
index 02669c98dc..8463a8844e 100644
--- a/plugins/lookup/hiera.py
+++ b/plugins/lookup/hiera.py
@@ -79,8 +79,7 @@ class Hiera(object):
pargs.extend(hiera_key)
- rc, output, err = run_cmd("{0} -c {1} {2}".format(
- self.hiera_bin, self.hiera_cfg, hiera_key[0]))
+ rc, output, err = run_cmd(f"{self.hiera_bin} -c {self.hiera_cfg} {hiera_key[0]}")
return to_text(output.strip())
diff --git a/plugins/lookup/keyring.py b/plugins/lookup/keyring.py
index a4c914ed1a..ebc35a8ee1 100644
--- a/plugins/lookup/keyring.py
+++ b/plugins/lookup/keyring.py
@@ -57,17 +57,17 @@ class LookupModule(LookupBase):
def run(self, terms, variables=None, **kwargs):
if not HAS_KEYRING:
- raise AnsibleError(u"Can't LOOKUP(keyring): missing required python library 'keyring'")
+ raise AnsibleError("Can't LOOKUP(keyring): missing required python library 'keyring'")
self.set_options(var_options=variables, direct=kwargs)
- display.vvvv(u"keyring: %s" % keyring.get_keyring())
+ display.vvvv(f"keyring: {keyring.get_keyring()}")
ret = []
for term in terms:
(servicename, username) = (term.split()[0], term.split()[1])
- display.vvvv(u"username: %s, servicename: %s " % (username, servicename))
+ display.vvvv(f"username: {username}, servicename: {servicename} ")
password = keyring.get_password(servicename, username)
if password is None:
- raise AnsibleError(u"servicename: %s for user %s not found" % (servicename, username))
+ raise AnsibleError(f"servicename: {servicename} for user {username} not found")
ret.append(password.rstrip())
return ret
diff --git a/plugins/lookup/lastpass.py b/plugins/lookup/lastpass.py
index 8eb3090b76..70ef8d1414 100644
--- a/plugins/lookup/lastpass.py
+++ b/plugins/lookup/lastpass.py
@@ -83,9 +83,9 @@ class LPass(object):
def get_field(self, key, field):
if field in ['username', 'password', 'url', 'notes', 'id', 'name']:
- out, err = self._run(self._build_args("show", ["--{0}".format(field), key]))
+ out, err = self._run(self._build_args("show", [f"--{field}", key]))
else:
- out, err = self._run(self._build_args("show", ["--field={0}".format(field), key]))
+ out, err = self._run(self._build_args("show", [f"--field={field}", key]))
return out.strip()
diff --git a/plugins/lookup/lmdb_kv.py b/plugins/lookup/lmdb_kv.py
index a37cff9569..c09321d081 100644
--- a/plugins/lookup/lmdb_kv.py
+++ b/plugins/lookup/lmdb_kv.py
@@ -96,7 +96,7 @@ class LookupModule(LookupBase):
try:
env = lmdb.open(str(db), readonly=True)
except Exception as e:
- raise AnsibleError("LMDB can't open database %s: %s" % (db, to_native(e)))
+ raise AnsibleError(f"LMDB cannot open database {db}: {e}")
ret = []
if len(terms) == 0:
diff --git a/plugins/lookup/manifold.py b/plugins/lookup/manifold.py
index 049d453e4f..9dbd2e118f 100644
--- a/plugins/lookup/manifold.py
+++ b/plugins/lookup/manifold.py
@@ -78,12 +78,14 @@ class ApiError(Exception):
class ManifoldApiClient(object):
- base_url = 'https://api.{api}.manifold.co/v1/{endpoint}'
http_agent = 'python-manifold-ansible-1.0.0'
def __init__(self, token):
self._token = token
+ def _make_url(self, api, endpoint):
+ return f'https://api.{api}.manifold.co/v1/{endpoint}'
+
def request(self, api, endpoint, *args, **kwargs):
"""
Send a request to API backend and pre-process a response.
@@ -98,11 +100,11 @@ class ManifoldApiClient(object):
"""
default_headers = {
- 'Authorization': "Bearer {0}".format(self._token),
+ 'Authorization': f"Bearer {self._token}",
'Accept': "*/*" # Otherwise server doesn't set content-type header
}
- url = self.base_url.format(api=api, endpoint=endpoint)
+ url = self._make_url(api, endpoint)
headers = default_headers
arg_headers = kwargs.pop('headers', None)
@@ -110,23 +112,22 @@ class ManifoldApiClient(object):
headers.update(arg_headers)
try:
- display.vvvv('manifold lookup connecting to {0}'.format(url))
+ display.vvvv(f'manifold lookup connecting to {url}')
response = open_url(url, headers=headers, http_agent=self.http_agent, *args, **kwargs)
data = response.read()
if response.headers.get('content-type') == 'application/json':
data = json.loads(data)
return data
except ValueError:
- raise ApiError('JSON response can\'t be parsed while requesting {url}:\n{json}'.format(json=data, url=url))
+ raise ApiError(f'JSON response can\'t be parsed while requesting {url}:\n{data}')
except HTTPError as e:
- raise ApiError('Server returned: {err} while requesting {url}:\n{response}'.format(
- err=str(e), url=url, response=e.read()))
+ raise ApiError(f'Server returned: {e} while requesting {url}:\n{e.read()}')
except URLError as e:
- raise ApiError('Failed lookup url for {url} : {err}'.format(url=url, err=str(e)))
+ raise ApiError(f'Failed lookup url for {url} : {e}')
except SSLValidationError as e:
- raise ApiError('Error validating the server\'s certificate for {url}: {err}'.format(url=url, err=str(e)))
+ raise ApiError(f'Error validating the server\'s certificate for {url}: {e}')
except ConnectionError as e:
- raise ApiError('Error connecting to {url}: {err}'.format(url=url, err=str(e)))
+ raise ApiError(f'Error connecting to {url}: {e}')
def get_resources(self, team_id=None, project_id=None, label=None):
"""
@@ -152,7 +153,7 @@ class ManifoldApiClient(object):
query_params['label'] = label
if query_params:
- endpoint += '?' + urlencode(query_params)
+ endpoint += f"?{urlencode(query_params)}"
return self.request(api, endpoint)
@@ -188,7 +189,7 @@ class ManifoldApiClient(object):
query_params['label'] = label
if query_params:
- endpoint += '?' + urlencode(query_params)
+ endpoint += f"?{urlencode(query_params)}"
return self.request(api, endpoint)
@@ -200,7 +201,7 @@ class ManifoldApiClient(object):
:return:
"""
api = 'marketplace'
- endpoint = 'credentials?' + urlencode({'resource_id': resource_id})
+ endpoint = f"credentials?{urlencode({'resource_id': resource_id})}"
return self.request(api, endpoint)
@@ -229,7 +230,7 @@ class LookupModule(LookupBase):
if team:
team_data = client.get_teams(team)
if len(team_data) == 0:
- raise AnsibleError("Team '{0}' does not exist".format(team))
+ raise AnsibleError(f"Team '{team}' does not exist")
team_id = team_data[0]['id']
else:
team_id = None
@@ -237,7 +238,7 @@ class LookupModule(LookupBase):
if project:
project_data = client.get_projects(project)
if len(project_data) == 0:
- raise AnsibleError("Project '{0}' does not exist".format(project))
+ raise AnsibleError(f"Project '{project}' does not exist")
project_id = project_data[0]['id']
else:
project_id = None
@@ -252,7 +253,7 @@ class LookupModule(LookupBase):
if labels and len(resources_data) < len(labels):
fetched_labels = [r['body']['label'] for r in resources_data]
not_found_labels = [label for label in labels if label not in fetched_labels]
- raise AnsibleError("Resource(s) {0} do not exist".format(', '.join(not_found_labels)))
+ raise AnsibleError(f"Resource(s) {', '.join(not_found_labels)} do not exist")
credentials = {}
cred_map = {}
@@ -262,17 +263,14 @@ class LookupModule(LookupBase):
for cred_key, cred_val in six.iteritems(resource_credentials[0]['body']['values']):
label = resource['body']['label']
if cred_key in credentials:
- display.warning("'{cred_key}' with label '{old_label}' was replaced by resource data "
- "with label '{new_label}'".format(cred_key=cred_key,
- old_label=cred_map[cred_key],
- new_label=label))
+ display.warning(f"'{cred_key}' with label '{cred_map[cred_key]}' was replaced by resource data with label '{label}'")
credentials[cred_key] = cred_val
cred_map[cred_key] = label
ret = [credentials]
return ret
except ApiError as e:
- raise AnsibleError('API Error: {0}'.format(str(e)))
+ raise AnsibleError(f'API Error: {e}')
except AnsibleError as e:
raise e
except Exception:
diff --git a/plugins/lookup/merge_variables.py b/plugins/lookup/merge_variables.py
index 6287914747..e352524292 100644
--- a/plugins/lookup/merge_variables.py
+++ b/plugins/lookup/merge_variables.py
@@ -149,7 +149,7 @@ class LookupModule(LookupBase):
ret = []
for term in terms:
if not isinstance(term, str):
- raise AnsibleError("Non-string type '{0}' passed, only 'str' types are allowed!".format(type(term)))
+ raise AnsibleError(f"Non-string type '{type(term)}' passed, only 'str' types are allowed!")
if not self._groups: # consider only own variables
ret.append(self._merge_vars(term, initial_value, variables))
@@ -186,9 +186,9 @@ class LookupModule(LookupBase):
return False
def _merge_vars(self, search_pattern, initial_value, variables):
- display.vvv("Merge variables with {0}: {1}".format(self._pattern_type, search_pattern))
+ display.vvv(f"Merge variables with {self._pattern_type}: {search_pattern}")
var_merge_names = sorted([key for key in variables.keys() if self._var_matches(key, search_pattern)])
- display.vvv("The following variables will be merged: {0}".format(var_merge_names))
+ display.vvv(f"The following variables will be merged: {var_merge_names}")
prev_var_type = None
result = None
@@ -226,8 +226,7 @@ class LookupModule(LookupBase):
dest[key] += value
else:
if (key in dest) and dest[key] != value:
- msg = "The key '{0}' with value '{1}' will be overwritten with value '{2}' from '{3}.{0}'".format(
- key, dest[key], value, ".".join(path))
+ msg = f"The key '{key}' with value '{dest[key]}' will be overwritten with value '{value}' from '{'.'.join(path)}.{key}'"
if self._override == "error":
raise AnsibleError(msg)
diff --git a/plugins/lookup/onepassword.py b/plugins/lookup/onepassword.py
index 921cf9acb8..ce0179a31e 100644
--- a/plugins/lookup/onepassword.py
+++ b/plugins/lookup/onepassword.py
@@ -140,11 +140,11 @@ class OnePassCLIBase(with_metaclass(abc.ABCMeta, object)):
if missing:
prefix = "Unable to sign in to 1Password. Missing required parameter"
plural = ""
- suffix = ": {params}.".format(params=", ".join(missing))
+ suffix = f": {', '.join(missing)}."
if len(missing) > 1:
plural = "s"
- msg = "{prefix}{plural}{suffix}".format(prefix=prefix, plural=plural, suffix=suffix)
+ msg = f"{prefix}{plural}{suffix}"
raise AnsibleLookupError(msg)
@abc.abstractmethod
@@ -169,7 +169,7 @@ class OnePassCLIBase(with_metaclass(abc.ABCMeta, object)):
rc = p.wait()
if not ignore_errors and rc != expected_rc:
- raise AnsibleLookupError(to_text(err))
+ raise AnsibleLookupError(str(err))
return rc, out, err
@@ -210,12 +210,12 @@ class OnePassCLIBase(with_metaclass(abc.ABCMeta, object)):
try:
bin_path = get_bin_path(cls.bin)
except ValueError:
- raise AnsibleLookupError("Unable to locate '%s' command line tool" % cls.bin)
+ raise AnsibleLookupError(f"Unable to locate '{cls.bin}' command line tool")
try:
b_out = subprocess.check_output([bin_path, "--version"], stderr=subprocess.PIPE)
except subprocess.CalledProcessError as cpe:
- raise AnsibleLookupError("Unable to get the op version: %s" % cpe)
+ raise AnsibleLookupError(f"Unable to get the op version: {cpe}")
return to_text(b_out).strip()
@@ -300,7 +300,7 @@ class OnePassCLIv1(OnePassCLIBase):
if self.account_id:
args.extend(["--account", self.account_id])
elif self.subdomain:
- account = "{subdomain}.{domain}".format(subdomain=self.subdomain, domain=self.domain)
+ account = f"{self.subdomain}.{self.domain}"
args.extend(["--account", account])
rc, out, err = self._run(args, ignore_errors=True)
@@ -326,7 +326,7 @@ class OnePassCLIv1(OnePassCLIBase):
args = [
"signin",
- "{0}.{1}".format(self.subdomain, self.domain),
+ f"{self.subdomain}.{self.domain}",
to_bytes(self.username),
to_bytes(self.secret_key),
"--raw",
@@ -341,7 +341,7 @@ class OnePassCLIv1(OnePassCLIBase):
args.extend(["--account", self.account_id])
if vault is not None:
- args += ["--vault={0}".format(vault)]
+ args += [f"--vault={vault}"]
if token is not None:
args += [to_bytes("--session=") + token]
@@ -512,7 +512,7 @@ class OnePassCLIv2(OnePassCLIBase):
args = ["account", "list"]
if self.subdomain:
- account = "{subdomain}.{domain}".format(subdomain=self.subdomain, domain=self.domain)
+ account = f"{self.subdomain}.{self.domain}"
args.extend(["--account", account])
rc, out, err = self._run(args)
@@ -525,7 +525,7 @@ class OnePassCLIv2(OnePassCLIBase):
if self.account_id:
args.extend(["--account", self.account_id])
elif self.subdomain:
- account = "{subdomain}.{domain}".format(subdomain=self.subdomain, domain=self.domain)
+ account = f"{self.subdomain}.{self.domain}"
args.extend(["--account", account])
rc, out, err = self._run(args, ignore_errors=True)
@@ -545,7 +545,7 @@ class OnePassCLIv2(OnePassCLIBase):
args = [
"account", "add", "--raw",
- "--address", "{0}.{1}".format(self.subdomain, self.domain),
+ "--address", f"{self.subdomain}.{self.domain}",
"--email", to_bytes(self.username),
"--signin",
]
@@ -553,14 +553,12 @@ class OnePassCLIv2(OnePassCLIBase):
environment_update = {"OP_SECRET_KEY": self.secret_key}
return self._run(args, command_input=to_bytes(self.master_password), environment_update=environment_update)
- def get_raw(self, item_id, vault=None, token=None):
- args = ["item", "get", item_id, "--format", "json"]
-
+ def _add_parameters_and_run(self, args, vault=None, token=None):
if self.account_id:
args.extend(["--account", self.account_id])
if vault is not None:
- args += ["--vault={0}".format(vault)]
+ args += [f"--vault={vault}"]
if self.connect_host and self.connect_token:
if vault is None:
@@ -582,6 +580,10 @@ class OnePassCLIv2(OnePassCLIBase):
return self._run(args)
+ def get_raw(self, item_id, vault=None, token=None):
+ args = ["item", "get", item_id, "--format", "json"]
+ return self._add_parameters_and_run(args, vault=vault, token=token)
+
def signin(self):
self._check_required_params(['master_password'])
@@ -627,7 +629,7 @@ class OnePass(object):
except TypeError as e:
raise AnsibleLookupError(e)
- raise AnsibleLookupError("op version %s is unsupported" % version)
+ raise AnsibleLookupError(f"op version {version} is unsupported")
def set_token(self):
if self._config.config_file_path and os.path.isfile(self._config.config_file_path):
diff --git a/plugins/lookup/onepassword_doc.py b/plugins/lookup/onepassword_doc.py
index 789e51c35a..5ffcf02c69 100644
--- a/plugins/lookup/onepassword_doc.py
+++ b/plugins/lookup/onepassword_doc.py
@@ -46,28 +46,13 @@ RETURN = """
"""
from ansible_collections.community.general.plugins.lookup.onepassword import OnePass, OnePassCLIv2
-from ansible.errors import AnsibleLookupError
-from ansible.module_utils.common.text.converters import to_bytes
from ansible.plugins.lookup import LookupBase
class OnePassCLIv2Doc(OnePassCLIv2):
def get_raw(self, item_id, vault=None, token=None):
args = ["document", "get", item_id]
- if vault is not None:
- args = [*args, "--vault={0}".format(vault)]
-
- if self.service_account_token:
- if vault is None:
- raise AnsibleLookupError("'vault' is required with 'service_account_token'")
-
- environment_update = {"OP_SERVICE_ACCOUNT_TOKEN": self.service_account_token}
- return self._run(args, environment_update=environment_update)
-
- if token is not None:
- args = [*args, to_bytes("--session=") + token]
-
- return self._run(args)
+ return self._add_parameters_and_run(args, vault=vault, token=token)
class LookupModule(LookupBase):
diff --git a/plugins/lookup/onepassword_ssh_key.py b/plugins/lookup/onepassword_ssh_key.py
new file mode 100644
index 0000000000..253d8c68f4
--- /dev/null
+++ b/plugins/lookup/onepassword_ssh_key.py
@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2025, Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import annotations
+
+DOCUMENTATION = """
+name: onepassword_ssh_key
+author:
+ - Mohammed Babelly (@mohammedbabelly20)
+requirements:
+ - C(op) 1Password command line utility version 2 or later.
+short_description: Fetch SSH keys stored in 1Password
+version_added: "10.3.0"
+description:
+ - P(community.general.onepassword_ssh_key#lookup) wraps C(op) command line utility to fetch SSH keys from 1Password.
+notes:
+ - By default, it returns the private key value in PKCS#8 format, unless O(ssh_format=true) is passed.
+ - The pluging works only for C(SSHKEY) type items.
+ - This plugin requires C(op) version 2 or later.
+
+options:
+ _terms:
+ description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve.
+ required: true
+ type: list
+ elements: string
+ ssh_format:
+ description: Output key in SSH format if V(true). Otherwise, outputs in the default format (PKCS#8).
+ default: false
+ type: bool
+
+extends_documentation_fragment:
+ - community.general.onepassword
+ - community.general.onepassword.lookup
+"""
+
+EXAMPLES = """
+- name: Retrieve the private SSH key from 1Password
+ ansible.builtin.debug:
+ msg: "{{ lookup('community.general.onepassword_ssh_key', 'SSH Key', ssh_format=true) }}"
+"""
+
+RETURN = """
+_raw:
+ description: Private key of SSH keypair.
+ type: list
+ elements: string
+"""
+import json
+
+from ansible_collections.community.general.plugins.lookup.onepassword import (
+ OnePass,
+ OnePassCLIv2,
+)
+from ansible.errors import AnsibleLookupError
+from ansible.plugins.lookup import LookupBase
+
+
+class LookupModule(LookupBase):
+ def get_ssh_key(self, out, item_id, ssh_format=False):
+ data = json.loads(out)
+
+ if data.get("category") != "SSH_KEY":
+ raise AnsibleLookupError(f"Item {item_id} is not an SSH key")
+
+ private_key_field = next(
+ (
+ field
+ for field in data.get("fields", {})
+ if field.get("id") == "private_key" and field.get("type") == "SSHKEY"
+ ),
+ None,
+ )
+ if not private_key_field:
+ raise AnsibleLookupError(f"No private key found for item {item_id}.")
+
+ if ssh_format:
+ return (
+ private_key_field.get("ssh_formats", {})
+ .get("openssh", {})
+ .get("value", "")
+ )
+ return private_key_field.get("value", "")
+
+ def run(self, terms, variables=None, **kwargs):
+ self.set_options(var_options=variables, direct=kwargs)
+
+ ssh_format = self.get_option("ssh_format")
+ vault = self.get_option("vault")
+ subdomain = self.get_option("subdomain")
+ domain = self.get_option("domain", "1password.com")
+ username = self.get_option("username")
+ secret_key = self.get_option("secret_key")
+ master_password = self.get_option("master_password")
+ service_account_token = self.get_option("service_account_token")
+ account_id = self.get_option("account_id")
+ connect_host = self.get_option("connect_host")
+ connect_token = self.get_option("connect_token")
+
+ op = OnePass(
+ subdomain=subdomain,
+ domain=domain,
+ username=username,
+ secret_key=secret_key,
+ master_password=master_password,
+ service_account_token=service_account_token,
+ account_id=account_id,
+ connect_host=connect_host,
+ connect_token=connect_token,
+ cli_class=OnePassCLIv2,
+ )
+ op.assert_logged_in()
+
+ return [
+ self.get_ssh_key(op.get_raw(term, vault), term, ssh_format=ssh_format)
+ for term in terms
+ ]
diff --git a/plugins/lookup/passwordstore.py b/plugins/lookup/passwordstore.py
index f35d268995..479f8d537a 100644
--- a/plugins/lookup/passwordstore.py
+++ b/plugins/lookup/passwordstore.py
@@ -315,7 +315,7 @@ class LookupModule(LookupBase):
)
self.realpass = 'pass: the standard unix password manager' in passoutput
except (subprocess.CalledProcessError) as e:
- raise AnsibleError('exit code {0} while running {1}. Error output: {2}'.format(e.returncode, e.cmd, e.output))
+ raise AnsibleError(f'exit code {e.returncode} while running {e.cmd}. Error output: {e.output}')
return self.realpass
@@ -332,7 +332,7 @@ class LookupModule(LookupBase):
for param in params[1:]:
name, value = param.split('=', 1)
if name not in self.paramvals:
- raise AnsibleAssertionError('%s not in paramvals' % name)
+ raise AnsibleAssertionError(f'{name} not in paramvals')
self.paramvals[name] = value
except (ValueError, AssertionError) as e:
raise AnsibleError(e)
@@ -344,12 +344,12 @@ class LookupModule(LookupBase):
except (ValueError, AssertionError) as e:
raise AnsibleError(e)
if self.paramvals['missing'] not in ['error', 'warn', 'create', 'empty']:
- raise AnsibleError("{0} is not a valid option for missing".format(self.paramvals['missing']))
+ raise AnsibleError(f"{self.paramvals['missing']} is not a valid option for missing")
if not isinstance(self.paramvals['length'], int):
if self.paramvals['length'].isdigit():
self.paramvals['length'] = int(self.paramvals['length'])
else:
- raise AnsibleError("{0} is not a correct value for length".format(self.paramvals['length']))
+ raise AnsibleError(f"{self.paramvals['length']} is not a correct value for length")
if self.paramvals['create']:
self.paramvals['missing'] = 'create'
@@ -364,7 +364,7 @@ class LookupModule(LookupBase):
# Set PASSWORD_STORE_DIR
self.env['PASSWORD_STORE_DIR'] = self.paramvals['directory']
elif self.is_real_pass():
- raise AnsibleError('Passwordstore directory \'{0}\' does not exist'.format(self.paramvals['directory']))
+ raise AnsibleError(f"Passwordstore directory '{self.paramvals['directory']}' does not exist")
# Set PASSWORD_STORE_UMASK if umask is set
if self.paramvals.get('umask') is not None:
@@ -394,19 +394,19 @@ class LookupModule(LookupBase):
name, value = line.split(':', 1)
self.passdict[name.strip()] = value.strip()
if (self.backend == 'gopass' or
- os.path.isfile(os.path.join(self.paramvals['directory'], self.passname + ".gpg"))
+ os.path.isfile(os.path.join(self.paramvals['directory'], f"{self.passname}.gpg"))
or not self.is_real_pass()):
# When using real pass, only accept password as found if there is a .gpg file for it (might be a tree node otherwise)
return True
except (subprocess.CalledProcessError) as e:
# '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('exit code {0} while running {1}. Error output: {2}'.format(e.returncode, e.cmd, e.output))
+ raise AnsibleError(f'exit code {e.returncode} while running {e.cmd}. Error output: {e.output}')
if self.paramvals['missing'] == 'error':
- raise AnsibleError('passwordstore: passname {0} not found and missing=error is set'.format(self.passname))
+ raise AnsibleError(f'passwordstore: passname {self.passname} not found and missing=error is set')
elif self.paramvals['missing'] == 'warn':
- display.warning('passwordstore: passname {0} not found'.format(self.passname))
+ display.warning(f'passwordstore: passname {self.passname} not found')
return False
@@ -433,11 +433,11 @@ class LookupModule(LookupBase):
msg_lines = []
subkey_exists = False
- subkey_line = "{0}: {1}".format(subkey, newpass)
+ subkey_line = f"{subkey}: {newpass}"
oldpass = None
for line in self.passoutput:
- if line.startswith("{0}: ".format(subkey)):
+ if line.startswith(f"{subkey}: "):
oldpass = self.passdict[subkey]
line = subkey_line
subkey_exists = True
@@ -449,9 +449,7 @@ class LookupModule(LookupBase):
if self.paramvals["timestamp"] and self.paramvals["backup"] and oldpass and oldpass != newpass:
msg_lines.append(
- "lookup_pass: old subkey '{0}' password was {1} (Updated on {2})\n".format(
- subkey, oldpass, datetime
- )
+ f"lookup_pass: old subkey '{subkey}' password was {oldpass} (Updated on {datetime})\n"
)
msg = os.linesep.join(msg_lines)
@@ -464,12 +462,12 @@ class LookupModule(LookupBase):
if self.paramvals['preserve'] and self.passoutput[1:]:
msg += '\n'.join(self.passoutput[1:]) + '\n'
if self.paramvals['timestamp'] and self.paramvals['backup']:
- msg += "lookup_pass: old password was {0} (Updated on {1})\n".format(self.password, datetime)
+ msg += f"lookup_pass: old password was {self.password} (Updated on {datetime})\n"
try:
check_output2([self.pass_cmd, 'insert', '-f', '-m', self.passname], input=msg, env=self.env)
except (subprocess.CalledProcessError) as e:
- raise AnsibleError('exit code {0} while running {1}. Error output: {2}'.format(e.returncode, e.cmd, e.output))
+ raise AnsibleError(f'exit code {e.returncode} while running {e.cmd}. Error output: {e.output}')
return newpass
def generate_password(self):
@@ -480,17 +478,17 @@ class LookupModule(LookupBase):
subkey = self.paramvals["subkey"]
if subkey != "password":
- msg = "\n\n{0}: {1}".format(subkey, newpass)
+ msg = f"\n\n{subkey}: {newpass}"
else:
msg = newpass
if self.paramvals['timestamp']:
- msg += '\n' + "lookup_pass: First generated by ansible on {0}\n".format(datetime)
+ msg += f"\nlookup_pass: First generated by ansible on {datetime}\n"
try:
check_output2([self.pass_cmd, 'insert', '-f', '-m', self.passname], input=msg, env=self.env)
except (subprocess.CalledProcessError) as e:
- raise AnsibleError('exit code {0} while running {1}. Error output: {2}'.format(e.returncode, e.cmd, e.output))
+ raise AnsibleError(f'exit code {e.returncode} while running {e.cmd}. Error output: {e.output}')
return newpass
@@ -505,16 +503,12 @@ class LookupModule(LookupBase):
else:
if self.paramvals["missing_subkey"] == "error":
raise AnsibleError(
- "passwordstore: subkey {0} for passname {1} not found and missing_subkey=error is set".format(
- self.paramvals["subkey"], self.passname
- )
+ f"passwordstore: subkey {self.paramvals['subkey']} for passname {self.passname} not found and missing_subkey=error is set"
)
if self.paramvals["missing_subkey"] == "warn":
display.warning(
- "passwordstore: subkey {0} for passname {1} not found".format(
- self.paramvals["subkey"], self.passname
- )
+ f"passwordstore: subkey {self.paramvals['subkey']} for passname {self.passname} not found"
)
return None
@@ -524,7 +518,7 @@ class LookupModule(LookupBase):
if self.get_option('lock') == type:
tmpdir = os.environ.get('TMPDIR', '/tmp')
user = os.environ.get('USER')
- lockfile = os.path.join(tmpdir, '.{0}.passwordstore.lock'.format(user))
+ lockfile = os.path.join(tmpdir, f'.{user}.passwordstore.lock')
with FileLock().lock_file(lockfile, tmpdir, self.lock_timeout):
self.locked = type
yield
@@ -538,7 +532,7 @@ class LookupModule(LookupBase):
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))
+ raise AnsibleError(f"{timeout} is not a correct value for locktimeout")
unit_to_seconds = {"s": 1, "m": 60, "h": 3600}
self.lock_timeout = int(timeout[:-1]) * unit_to_seconds[timeout[-1]]
@@ -578,16 +572,20 @@ class LookupModule(LookupBase):
for term in terms:
self.parse_params(term) # parse the input into paramvals
with self.opt_lock('readwrite'):
- if self.check_pass(): # password exists
- if self.paramvals['overwrite']:
+ if self.check_pass(): # password file exists
+ if self.paramvals['overwrite']: # if "overwrite", always update password
with self.opt_lock('write'):
result.append(self.update_password())
- elif self.paramvals["subkey"] != "password" and not self.passdict.get(self.paramvals['subkey']): # password exists but not the subkey
+ elif (
+ self.paramvals["subkey"] != "password"
+ and not self.passdict.get(self.paramvals["subkey"])
+ and self.paramvals["missing"] == "create"
+ ): # target is a subkey, this subkey is not in passdict BUT missing == create
with self.opt_lock('write'):
result.append(self.update_password())
else:
result.append(self.get_passresult())
- else: # password does not exist
+ 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
diff --git a/plugins/lookup/random_pet.py b/plugins/lookup/random_pet.py
index 71a62cbca0..77f1c34a51 100644
--- a/plugins/lookup/random_pet.py
+++ b/plugins/lookup/random_pet.py
@@ -95,6 +95,6 @@ class LookupModule(LookupBase):
values = petname.Generate(words=words, separator=separator, letters=length)
if prefix:
- values = "%s%s%s" % (prefix, separator, values)
+ values = f"{prefix}{separator}{values}"
return [values]
diff --git a/plugins/lookup/redis.py b/plugins/lookup/redis.py
index 17cbf120e9..5c669a7f23 100644
--- a/plugins/lookup/redis.py
+++ b/plugins/lookup/redis.py
@@ -116,5 +116,5 @@ class LookupModule(LookupBase):
ret.append(to_text(res))
except Exception as e:
# connection failed or key not found
- raise AnsibleError('Encountered exception while fetching {0}: {1}'.format(term, e))
+ raise AnsibleError(f'Encountered exception while fetching {term}: {e}')
return ret
diff --git a/plugins/lookup/revbitspss.py b/plugins/lookup/revbitspss.py
index e4118e89eb..89c19cf23c 100644
--- a/plugins/lookup/revbitspss.py
+++ b/plugins/lookup/revbitspss.py
@@ -100,8 +100,8 @@ class LookupModule(LookupBase):
result = []
for term in terms:
try:
- display.vvv("Secret Server lookup of Secret with ID %s" % term)
+ display.vvv(f"Secret Server lookup of Secret with ID {term}")
result.append({term: secret_server.get_pam_secret(term)})
except Exception as error:
- raise AnsibleError("Secret Server lookup failure: %s" % error.message)
+ raise AnsibleError(f"Secret Server lookup failure: {error.message}")
return result
diff --git a/plugins/lookup/shelvefile.py b/plugins/lookup/shelvefile.py
index 70d18338e9..4d965372fb 100644
--- a/plugins/lookup/shelvefile.py
+++ b/plugins/lookup/shelvefile.py
@@ -71,7 +71,7 @@ class LookupModule(LookupBase):
for param in params:
name, value = param.split('=')
if name not in paramvals:
- raise AnsibleAssertionError('%s not in paramvals' % name)
+ raise AnsibleAssertionError(f'{name} not in paramvals')
paramvals[name] = value
except (ValueError, AssertionError) as e:
@@ -86,11 +86,11 @@ class LookupModule(LookupBase):
if shelvefile:
res = self.read_shelve(shelvefile, key)
if res is None:
- raise AnsibleError("Key %s not found in shelve file %s" % (key, shelvefile))
+ raise AnsibleError(f"Key {key} not found in shelve file {shelvefile}")
# Convert the value read to string
ret.append(to_text(res))
break
else:
- raise AnsibleError("Could not locate shelve file in lookup: %s" % paramvals['file'])
+ raise AnsibleError(f"Could not locate shelve file in lookup: {paramvals['file']}")
return ret
diff --git a/plugins/lookup/tss.py b/plugins/lookup/tss.py
index f2d79ed168..ffae6bb824 100644
--- a/plugins/lookup/tss.py
+++ b/plugins/lookup/tss.py
@@ -306,14 +306,14 @@ class TSSClient(object):
return TSSClientV0(**server_parameters)
def get_secret(self, term, secret_path, fetch_file_attachments, file_download_path):
- display.debug("tss_lookup term: %s" % term)
+ display.debug(f"tss_lookup term: {term}")
secret_id = self._term_to_secret_id(term)
if secret_id == 0 and secret_path:
fetch_secret_by_path = True
- display.vvv(u"Secret Server lookup of Secret with path %s" % secret_path)
+ display.vvv(f"Secret Server lookup of Secret with path {secret_path}")
else:
fetch_secret_by_path = False
- display.vvv(u"Secret Server lookup of Secret with ID %d" % secret_id)
+ display.vvv(f"Secret Server lookup of Secret with ID {secret_id}")
if fetch_file_attachments:
if fetch_secret_by_path:
@@ -325,12 +325,12 @@ class TSSClient(object):
if i['isFile']:
try:
file_content = i['itemValue'].content
- with open(os.path.join(file_download_path, str(obj['id']) + "_" + i['slug']), "wb") as f:
+ with open(os.path.join(file_download_path, f"{obj['id']}_{i['slug']}"), "wb") as f:
f.write(file_content)
except ValueError:
- raise AnsibleOptionsError("Failed to download {0}".format(str(i['slug'])))
+ raise AnsibleOptionsError(f"Failed to download {i['slug']}")
except AttributeError:
- display.warning("Could not read file content for {0}".format(str(i['slug'])))
+ display.warning(f"Could not read file content for {i['slug']}")
finally:
i['itemValue'] = "*** Not Valid For Display ***"
else:
@@ -343,9 +343,9 @@ class TSSClient(object):
return self._client.get_secret_json(secret_id)
def get_secret_ids_by_folderid(self, term):
- display.debug("tss_lookup term: %s" % term)
+ display.debug(f"tss_lookup term: {term}")
folder_id = self._term_to_folder_id(term)
- display.vvv(u"Secret Server lookup of Secret id's with Folder ID %d" % folder_id)
+ display.vvv(f"Secret Server lookup of Secret id's with Folder ID {folder_id}")
return self._client.get_secret_ids_by_folderid(folder_id)
@@ -447,4 +447,4 @@ class LookupModule(LookupBase):
for term in terms
]
except SecretServerError as error:
- raise AnsibleError("Secret Server lookup failure: %s" % error.message)
+ raise AnsibleError(f"Secret Server lookup failure: {error.message}")
diff --git a/plugins/module_utils/_filelock.py b/plugins/module_utils/_filelock.py
index a35d0b91cf..4e782064be 100644
--- a/plugins/module_utils/_filelock.py
+++ b/plugins/module_utils/_filelock.py
@@ -46,8 +46,8 @@ class FileLock:
'''
Create a lock file based on path with flock to prevent other processes
using given path.
- Please note that currently file locking only works when it's executed by
- the same user, I.E single user scenarios
+ Please note that currently file locking only works when it is executed by
+ the same user, for example single user scenarios
:kw path: Path (file) to lock
:kw tmpdir: Path where to place the temporary .lock file
diff --git a/plugins/module_utils/android_sdkmanager.py b/plugins/module_utils/android_sdkmanager.py
new file mode 100644
index 0000000000..9cbb2df6b0
--- /dev/null
+++ b/plugins/module_utils/android_sdkmanager.py
@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024, Stanislav Shamilov
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+import re
+
+from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt
+
+__state_map = {
+ "present": "--install",
+ "absent": "--uninstall"
+}
+
+# sdkmanager --help 2>&1 | grep -A 2 -- --channel
+__channel_map = {
+ "stable": 0,
+ "beta": 1,
+ "dev": 2,
+ "canary": 3
+}
+
+
+def __map_channel(channel_name):
+ if channel_name not in __channel_map:
+ raise ValueError("Unknown channel name '%s'" % channel_name)
+ return __channel_map[channel_name]
+
+
+def sdkmanager_runner(module, **kwargs):
+ return CmdRunner(
+ module,
+ command='sdkmanager',
+ arg_formats=dict(
+ state=cmd_runner_fmt.as_map(__state_map),
+ name=cmd_runner_fmt.as_list(),
+ installed=cmd_runner_fmt.as_fixed("--list_installed"),
+ list=cmd_runner_fmt.as_fixed('--list'),
+ newer=cmd_runner_fmt.as_fixed("--newer"),
+ sdk_root=cmd_runner_fmt.as_opt_eq_val("--sdk_root"),
+ channel=cmd_runner_fmt.as_func(lambda x: ["{0}={1}".format("--channel", __map_channel(x))])
+ ),
+ force_lang="C.UTF-8", # Without this, sdkmanager binary crashes
+ **kwargs
+ )
+
+
+class Package:
+ def __init__(self, name):
+ self.name = name
+
+ def __hash__(self):
+ return hash(self.name)
+
+ def __ne__(self, other):
+ if not isinstance(other, Package):
+ return True
+ return self.name != other.name
+
+ def __eq__(self, other):
+ if not isinstance(other, Package):
+ return False
+
+ return self.name == other.name
+
+
+class SdkManagerException(Exception):
+ pass
+
+
+class AndroidSdkManager(object):
+ _RE_INSTALLED_PACKAGES_HEADER = re.compile(r'^Installed packages:$')
+ _RE_UPDATABLE_PACKAGES_HEADER = re.compile(r'^Available Updates:$')
+
+ # Example: ' platform-tools | 27.0.0 | Android SDK Platform-Tools 27 | platform-tools '
+ _RE_INSTALLED_PACKAGE = re.compile(r'^\s*(?P\S+)\s*\|\s*[0-9][^|]*\b\s*\|\s*.+\s*\|\s*(\S+)\s*$')
+
+ # Example: ' platform-tools | 27.0.0 | 35.0.2'
+ _RE_UPDATABLE_PACKAGE = re.compile(r'^\s*(?P\S+)\s*\|\s*[0-9][^|]*\b\s*\|\s*[0-9].*\b\s*$')
+
+ _RE_UNKNOWN_PACKAGE = re.compile(r'^Warning: Failed to find package \'(?P\S+)\'\s*$')
+ _RE_ACCEPT_LICENSE = re.compile(r'^The following packages can not be installed since their licenses or those of '
+ r'the packages they depend on were not accepted')
+
+ def __init__(self, module):
+ self.runner = sdkmanager_runner(module)
+
+ def get_installed_packages(self):
+ with self.runner('installed sdk_root channel') as ctx:
+ rc, stdout, stderr = ctx.run()
+ return self._parse_packages(stdout, self._RE_INSTALLED_PACKAGES_HEADER, self._RE_INSTALLED_PACKAGE)
+
+ def get_updatable_packages(self):
+ with self.runner('list newer sdk_root channel') as ctx:
+ rc, stdout, stderr = ctx.run()
+ return self._parse_packages(stdout, self._RE_UPDATABLE_PACKAGES_HEADER, self._RE_UPDATABLE_PACKAGE)
+
+ def apply_packages_changes(self, packages, accept_licenses=False):
+ """ Install or delete packages, depending on the `module.vars.state` parameter """
+ if len(packages) == 0:
+ return 0, '', ''
+
+ if accept_licenses:
+ license_prompt_answer = 'y'
+ else:
+ license_prompt_answer = 'N'
+ for package in packages:
+ with self.runner('state name sdk_root channel', data=license_prompt_answer) as ctx:
+ rc, stdout, stderr = ctx.run(name=package.name)
+
+ for line in stdout.splitlines():
+ if self._RE_ACCEPT_LICENSE.match(line):
+ raise SdkManagerException("Licenses for some packages were not accepted")
+
+ if rc != 0:
+ self._try_parse_stderr(stderr)
+ return rc, stdout, stderr
+ return 0, '', ''
+
+ def _try_parse_stderr(self, stderr):
+ data = stderr.splitlines()
+ for line in data:
+ unknown_package_regex = self._RE_UNKNOWN_PACKAGE.match(line)
+ if unknown_package_regex:
+ package = unknown_package_regex.group('package')
+ raise SdkManagerException("Unknown package %s" % package)
+
+ @staticmethod
+ def _parse_packages(stdout, header_regexp, row_regexp):
+ data = stdout.splitlines()
+
+ section_found = False
+ packages = set()
+
+ for line in data:
+ if not section_found:
+ section_found = header_regexp.match(line)
+ continue
+ else:
+ p = row_regexp.match(line)
+ if p:
+ packages.add(Package(p.group('name')))
+ return packages
diff --git a/plugins/module_utils/cmd_runner_fmt.py b/plugins/module_utils/cmd_runner_fmt.py
index bd6d00a15d..8b415edcf9 100644
--- a/plugins/module_utils/cmd_runner_fmt.py
+++ b/plugins/module_utils/cmd_runner_fmt.py
@@ -78,7 +78,9 @@ def as_list(ignore_none=None, min_len=0, max_len=None):
return _ArgFormat(func, ignore_none=ignore_none)
-def as_fixed(args):
+def as_fixed(*args):
+ if len(args) == 1 and is_sequence(args[0]):
+ args = args[0]
return _ArgFormat(lambda value: _ensure_list(args), ignore_none=False, ignore_missing_value=True)
diff --git a/plugins/module_utils/deps.py b/plugins/module_utils/deps.py
index a2413d1952..66847ccd25 100644
--- a/plugins/module_utils/deps.py
+++ b/plugins/module_utils/deps.py
@@ -96,3 +96,7 @@ def validate(module, spec=None):
def failed(spec=None):
return any(_deps[d].failed for d in _select_names(spec))
+
+
+def clear():
+ _deps.clear()
diff --git a/plugins/module_utils/gio_mime.py b/plugins/module_utils/gio_mime.py
index 132981a339..c734e13a81 100644
--- a/plugins/module_utils/gio_mime.py
+++ b/plugins/module_utils/gio_mime.py
@@ -12,8 +12,9 @@ from ansible_collections.community.general.plugins.module_utils.cmd_runner impor
def gio_mime_runner(module, **kwargs):
return CmdRunner(
module,
- command=['gio', 'mime'],
+ command=['gio'],
arg_formats=dict(
+ mime=cmd_runner_fmt.as_fixed('mime'),
mime_type=cmd_runner_fmt.as_list(),
handler=cmd_runner_fmt.as_list(),
version=cmd_runner_fmt.as_fixed('--version'),
@@ -29,5 +30,5 @@ def gio_mime_get(runner, mime_type):
out = out.splitlines()[0]
return out.split()[-1]
- with runner("mime_type", output_process=process) as ctx:
+ with runner("mime mime_type", output_process=process) as ctx:
return ctx.run(mime_type=mime_type)
diff --git a/plugins/module_utils/identity/keycloak/keycloak.py b/plugins/module_utils/identity/keycloak/keycloak.py
index 15603331b0..da5080bbfe 100644
--- a/plugins/module_utils/identity/keycloak/keycloak.py
+++ b/plugins/module_utils/identity/keycloak/keycloak.py
@@ -142,6 +142,7 @@ def keycloak_argument_spec():
validate_certs=dict(type='bool', default=True),
connection_timeout=dict(type='int', default=10),
token=dict(type='str', no_log=True),
+ refresh_token=dict(type='str', no_log=True),
http_agent=dict(type='str', default='Ansible'),
)
@@ -151,58 +152,113 @@ def camel(words):
class KeycloakError(Exception):
- pass
+ def __init__(self, msg, authError=None):
+ self.msg = msg
+ self.authError = authError
+
+ def __str__(self):
+ return str(self.msg)
+
+
+def _token_request(module_params, payload):
+ """ Obtains connection header with token for the authentication,
+ using the provided auth_username/auth_password
+ :param module_params: parameters of the module
+ :param payload:
+ type:
+ dict
+ description:
+ Authentication request payload. Must contain at least
+ 'grant_type' and 'client_id', optionally 'client_secret',
+ along with parameters based on 'grant_type'; e.g.,
+ 'username'/'password' for type 'password',
+ 'refresh_token' for type 'refresh_token'.
+ :return: access token
+ """
+ base_url = module_params.get('auth_keycloak_url')
+ if not base_url.lower().startswith(('http', 'https')):
+ raise KeycloakError("auth_url '%s' should either start with 'http' or 'https'." % base_url)
+ auth_realm = module_params.get('auth_realm')
+ auth_url = URL_TOKEN.format(url=base_url, realm=auth_realm)
+ http_agent = module_params.get('http_agent')
+ validate_certs = module_params.get('validate_certs')
+ connection_timeout = module_params.get('connection_timeout')
+
+ try:
+ r = json.loads(to_native(open_url(auth_url, method='POST',
+ validate_certs=validate_certs, http_agent=http_agent, timeout=connection_timeout,
+ data=urlencode(payload)).read()))
+
+ return r['access_token']
+ except ValueError as e:
+ raise KeycloakError(
+ 'API returned invalid JSON when trying to obtain access token from %s: %s'
+ % (auth_url, str(e)))
+ except KeyError:
+ raise KeycloakError(
+ 'API did not include access_token field in response from %s' % auth_url)
+ except Exception as e:
+ raise KeycloakError('Could not obtain access token from %s: %s'
+ % (auth_url, str(e)), authError=e)
+
+
+def _request_token_using_credentials(module_params):
+ """ Obtains connection header with token for the authentication,
+ using the provided auth_username/auth_password
+ :param module_params: parameters of the module. Must include 'auth_username' and 'auth_password'.
+ :return: connection header
+ """
+ client_id = module_params.get('auth_client_id')
+ auth_username = module_params.get('auth_username')
+ auth_password = module_params.get('auth_password')
+ client_secret = module_params.get('auth_client_secret')
+
+ temp_payload = {
+ 'grant_type': 'password',
+ 'client_id': client_id,
+ 'client_secret': client_secret,
+ 'username': auth_username,
+ 'password': auth_password,
+ }
+ # Remove empty items, for instance missing client_secret
+ payload = {k: v for k, v in temp_payload.items() if v is not None}
+
+ return _token_request(module_params, payload)
+
+
+def _request_token_using_refresh_token(module_params):
+ """ Obtains connection header with token for the authentication,
+ using the provided refresh_token
+ :param module_params: parameters of the module. Must include 'refresh_token'.
+ :return: connection header
+ """
+ client_id = module_params.get('auth_client_id')
+ refresh_token = module_params.get('refresh_token')
+ client_secret = module_params.get('auth_client_secret')
+
+ temp_payload = {
+ 'grant_type': 'refresh_token',
+ 'client_id': client_id,
+ 'client_secret': client_secret,
+ 'refresh_token': refresh_token,
+ }
+ # Remove empty items, for instance missing client_secret
+ payload = {k: v for k, v in temp_payload.items() if v is not None}
+
+ return _token_request(module_params, payload)
def get_token(module_params):
""" Obtains connection header with token for the authentication,
- token already given or obtained from credentials
- :param module_params: parameters of the module
- :return: connection header
+ token already given or obtained from credentials
+ :param module_params: parameters of the module
+ :return: connection header
"""
token = module_params.get('token')
- base_url = module_params.get('auth_keycloak_url')
- http_agent = module_params.get('http_agent')
-
- if not base_url.lower().startswith(('http', 'https')):
- raise KeycloakError("auth_url '%s' should either start with 'http' or 'https'." % base_url)
if token is None:
- base_url = module_params.get('auth_keycloak_url')
- validate_certs = module_params.get('validate_certs')
- auth_realm = module_params.get('auth_realm')
- client_id = module_params.get('auth_client_id')
- 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',
- 'client_id': client_id,
- 'client_secret': client_secret,
- 'username': auth_username,
- 'password': auth_password,
- }
- # Remove empty items, for instance missing client_secret
- payload = {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, http_agent=http_agent, timeout=connection_timeout,
- data=urlencode(payload)).read()))
- except ValueError as e:
- raise KeycloakError(
- 'API returned invalid JSON when trying to obtain access token from %s: %s'
- % (auth_url, str(e)))
- except Exception as e:
- raise KeycloakError('Could not obtain access token from %s: %s'
- % (auth_url, str(e)))
+ token = _request_token_using_credentials(module_params)
- try:
- token = r['access_token']
- except KeyError:
- raise KeycloakError(
- 'Could not obtain access token from %s' % auth_url)
return {
'Authorization': 'Bearer ' + token,
'Content-Type': 'application/json'
@@ -272,6 +328,7 @@ class KeycloakAPI(object):
""" Keycloak API access; Keycloak uses OAuth 2.0 to protect its API, an access token for which
is obtained through OpenID connect
"""
+
def __init__(self, module, connection_header):
self.module = module
self.baseurl = self.module.params.get('auth_keycloak_url')
@@ -280,6 +337,72 @@ class KeycloakAPI(object):
self.restheaders = connection_header
self.http_agent = self.module.params.get('http_agent')
+ def _request(self, url, method, data=None):
+ """ Makes a request to Keycloak and returns the raw response.
+ If a 401 is returned, attempts to re-authenticate
+ using first the module's refresh_token (if provided)
+ and then the module's username/password (if provided).
+ On successful re-authentication, the new token is stored
+ in the restheaders for future requests.
+
+ :param url: request path
+ :param method: request method (e.g., 'GET', 'POST', etc.)
+ :param data: (optional) data for request
+ :return: raw API response
+ """
+ def make_request_catching_401():
+ try:
+ return open_url(url, method=method, data=data,
+ http_agent=self.http_agent, headers=self.restheaders,
+ timeout=self.connection_timeout,
+ validate_certs=self.validate_certs)
+ except HTTPError as e:
+ if e.code != 401:
+ raise e
+ return e
+
+ r = make_request_catching_401()
+
+ if isinstance(r, Exception):
+ # Try to refresh token and retry, if available
+ refresh_token = self.module.params.get('refresh_token')
+ if refresh_token is not None:
+ try:
+ token = _request_token_using_refresh_token(self.module.params)
+ self.restheaders['Authorization'] = 'Bearer ' + token
+
+ r = make_request_catching_401()
+ except KeycloakError as e:
+ # Token refresh returns 400 if token is expired/invalid, so continue on if we get a 400
+ if e.authError is not None and e.authError.code != 400:
+ raise e
+
+ if isinstance(r, Exception):
+ # Try to re-auth with username/password, if available
+ auth_username = self.module.params.get('auth_username')
+ auth_password = self.module.params.get('auth_password')
+ if auth_username is not None and auth_password is not None:
+ token = _request_token_using_credentials(self.module.params)
+ self.restheaders['Authorization'] = 'Bearer ' + token
+
+ r = make_request_catching_401()
+
+ if isinstance(r, Exception):
+ # Either no re-auth options were available, or they all failed
+ raise r
+
+ return r
+
+ def _request_and_deserialize(self, url, method, data=None):
+ """ Wraps the _request method with JSON deserialization of the response.
+
+ :param url: request path
+ :param method: request method (e.g., 'GET', 'POST', etc.)
+ :param data: (optional) data for request
+ :return: raw API response
+ """
+ return json.loads(to_native(self._request(url, method, data).read()))
+
def get_realm_info_by_id(self, realm='master'):
""" Obtain realm public info by id
@@ -289,16 +412,14 @@ 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', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(realm_info_url, method='GET')
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not obtain realm %s: %s' % (realm, str(e)),
- exception=traceback.format_exc())
+ self.fail_request(e, msg='Could not obtain realm %s: %s' % (realm, str(e)),
+ exception=traceback.format_exc())
except ValueError as e:
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain realm %s: %s' % (realm, str(e)),
exception=traceback.format_exc())
@@ -320,16 +441,14 @@ class KeycloakAPI(object):
realm_keys_metadata_url = URL_REALM_KEYS_METADATA.format(url=self.baseurl, realm=realm)
try:
- return json.loads(to_native(open_url(realm_keys_metadata_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(realm_keys_metadata_url, method="GET")
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not obtain realm %s: %s' % (realm, str(e)),
- exception=traceback.format_exc())
+ self.fail_request(e, msg='Could not obtain realm %s: %s' % (realm, str(e)),
+ exception=traceback.format_exc())
except ValueError as e:
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain realm %s: %s' % (realm, str(e)),
exception=traceback.format_exc())
@@ -337,6 +456,8 @@ class KeycloakAPI(object):
self.module.fail_json(msg='Could not obtain realm %s: %s' % (realm, str(e)),
exception=traceback.format_exc())
+ # The Keycloak API expects the realm name (like `master`) not the ID when fetching the realm data.
+ # See the Keycloak API docs: https://www.keycloak.org/docs-api/latest/rest-api/#_realms_admin
def get_realm_by_id(self, realm='master'):
""" Obtain realm representation by id
@@ -346,15 +467,14 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(realm_url, method='GET')
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not obtain realm %s: %s' % (realm, str(e)),
- exception=traceback.format_exc())
+ self.fail_request(e, msg='Could not obtain realm %s: %s' % (realm, str(e)),
+ exception=traceback.format_exc())
except ValueError as e:
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain realm %s: %s' % (realm, str(e)),
exception=traceback.format_exc())
@@ -371,11 +491,10 @@ class KeycloakAPI(object):
realm_url = URL_REALM.format(url=self.baseurl, realm=realm)
try:
- return open_url(realm_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(realmrep), validate_certs=self.validate_certs)
+ return self._request(realm_url, method='PUT', data=json.dumps(realmrep))
except Exception as e:
- self.fail_open_url(e, msg='Could not update realm %s: %s' % (realm, str(e)),
- exception=traceback.format_exc())
+ self.fail_request(e, msg='Could not update realm %s: %s' % (realm, str(e)),
+ exception=traceback.format_exc())
def create_realm(self, realmrep):
""" Create a realm in keycloak
@@ -385,11 +504,10 @@ class KeycloakAPI(object):
realm_url = URL_REALMS.format(url=self.baseurl)
try:
- return open_url(realm_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(realmrep), validate_certs=self.validate_certs)
+ return self._request(realm_url, method='POST', data=json.dumps(realmrep))
except Exception as e:
- self.fail_open_url(e, msg='Could not create realm %s: %s' % (realmrep['id'], str(e)),
- exception=traceback.format_exc())
+ self.fail_request(e, msg='Could not create realm %s: %s' % (realmrep['id'], str(e)),
+ exception=traceback.format_exc())
def delete_realm(self, realm="master"):
""" Delete a realm from Keycloak
@@ -400,11 +518,10 @@ class KeycloakAPI(object):
realm_url = URL_REALM.format(url=self.baseurl, realm=realm)
try:
- return open_url(realm_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(realm_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Could not delete realm %s: %s' % (realm, str(e)),
- exception=traceback.format_exc())
+ self.fail_request(e, msg='Could not delete realm %s: %s' % (realm, str(e)),
+ exception=traceback.format_exc())
def get_clients(self, realm='master', filter=None):
""" Obtains client representations for clients in a realm
@@ -418,15 +535,13 @@ class KeycloakAPI(object):
clientlist_url += '?clientId=%s' % filter
try:
- return json.loads(to_native(open_url(clientlist_url, http_agent=self.http_agent, method='GET', headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(clientlist_url, method='GET')
except ValueError as e:
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of clients for realm %s: %s'
% (realm, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain list of clients for realm %s: %s'
- % (realm, str(e)))
+ self.fail_request(e, msg='Could not obtain list of clients for realm %s: %s'
+ % (realm, str(e)))
def get_client_by_clientid(self, client_id, realm='master'):
""" Get client representation by clientId
@@ -450,16 +565,14 @@ 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', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(client_url, method='GET')
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not obtain client %s for realm %s: %s'
- % (id, realm, str(e)))
+ self.fail_request(e, msg='Could not obtain client %s for realm %s: %s'
+ % (id, realm, str(e)))
except ValueError as e:
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain client %s for realm %s: %s'
% (id, realm, str(e)))
@@ -490,11 +603,10 @@ class KeycloakAPI(object):
client_url = URL_CLIENT.format(url=self.baseurl, realm=realm, id=id)
try:
- return open_url(client_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(clientrep), validate_certs=self.validate_certs)
+ return self._request(client_url, method='PUT', data=json.dumps(clientrep))
except Exception as e:
- self.fail_open_url(e, msg='Could not update client %s in realm %s: %s'
- % (id, realm, str(e)))
+ self.fail_request(e, msg='Could not update client %s in realm %s: %s'
+ % (id, realm, str(e)))
def create_client(self, clientrep, realm="master"):
""" Create a client in keycloak
@@ -505,11 +617,10 @@ class KeycloakAPI(object):
client_url = URL_CLIENTS.format(url=self.baseurl, realm=realm)
try:
- return open_url(client_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(clientrep), validate_certs=self.validate_certs)
+ return self._request(client_url, method='POST', data=json.dumps(clientrep))
except Exception as e:
- self.fail_open_url(e, msg='Could not create client %s in realm %s: %s'
- % (clientrep['clientId'], realm, str(e)))
+ self.fail_request(e, msg='Could not create client %s in realm %s: %s'
+ % (clientrep['clientId'], realm, str(e)))
def delete_client(self, id, realm="master"):
""" Delete a client from Keycloak
@@ -521,11 +632,10 @@ class KeycloakAPI(object):
client_url = URL_CLIENT.format(url=self.baseurl, realm=realm, id=id)
try:
- return open_url(client_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(client_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Could not delete client %s in realm %s: %s'
- % (id, realm, str(e)))
+ self.fail_request(e, msg='Could not delete client %s in realm %s: %s'
+ % (id, realm, str(e)))
def get_client_roles_by_id(self, cid, realm="master"):
""" Fetch the roles of the a client on the Keycloak server.
@@ -536,12 +646,10 @@ 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", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(client_roles_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch rolemappings for client %s in realm %s: %s"
- % (cid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch rolemappings for client %s in realm %s: %s"
+ % (cid, realm, str(e)))
def get_client_role_id_by_name(self, cid, name, realm="master"):
""" Get the role ID of a client.
@@ -568,15 +676,13 @@ class KeycloakAPI(object):
"""
rolemappings_url = URL_CLIENT_GROUP_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=gid, client=cid)
try:
- rolemappings = json.loads(to_native(open_url(rolemappings_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ rolemappings = self._request_and_deserialize(rolemappings_url, method="GET")
for role in rolemappings:
if rid == role['id']:
return role
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch rolemappings for client %s in group %s, realm %s: %s"
- % (cid, gid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch rolemappings for client %s in group %s, realm %s: %s"
+ % (cid, gid, realm, str(e)))
return None
def get_client_group_available_rolemappings(self, gid, cid, realm="master"):
@@ -589,12 +695,10 @@ class KeycloakAPI(object):
"""
available_rolemappings_url = URL_CLIENT_GROUP_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", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(available_rolemappings_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch available rolemappings for client %s in group %s, realm %s: %s"
- % (cid, gid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch available rolemappings for client %s in group %s, realm %s: %s"
+ % (cid, gid, realm, str(e)))
def get_client_group_composite_rolemappings(self, gid, cid, realm="master"):
""" Fetch the composite role of a client in a specified group on the Keycloak server.
@@ -606,12 +710,10 @@ class KeycloakAPI(object):
"""
composite_rolemappings_url = URL_CLIENT_GROUP_ROLEMAPPINGS_COMPOSITE.format(url=self.baseurl, realm=realm, id=gid, client=cid)
try:
- return json.loads(to_native(open_url(composite_rolemappings_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(composite_rolemappings_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch available rolemappings for client %s in group %s, realm %s: %s"
- % (cid, gid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch available rolemappings for client %s in group %s, realm %s: %s"
+ % (cid, gid, realm, str(e)))
def get_role_by_id(self, rid, realm="master"):
""" Fetch a role by its id on the Keycloak server.
@@ -622,12 +724,10 @@ class KeycloakAPI(object):
"""
client_roles_url = URL_ROLES_BY_ID.format(url=self.baseurl, realm=realm, id=rid)
try:
- return json.loads(to_native(open_url(client_roles_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(client_roles_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch role for id %s in realm %s: %s"
- % (rid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch role for id %s in realm %s: %s"
+ % (rid, realm, str(e)))
def get_client_roles_by_id_composite_rolemappings(self, rid, cid, realm="master"):
""" Fetch a role by its id on the Keycloak server.
@@ -639,12 +739,10 @@ class KeycloakAPI(object):
"""
client_roles_url = URL_ROLES_BY_ID_COMPOSITES_CLIENTS.format(url=self.baseurl, realm=realm, id=rid, cid=cid)
try:
- return json.loads(to_native(open_url(client_roles_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(client_roles_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch role for id %s and cid %s in realm %s: %s"
- % (rid, cid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch role for id %s and cid %s in realm %s: %s"
+ % (rid, cid, realm, str(e)))
def add_client_roles_by_id_composite_rolemapping(self, rid, roles_rep, realm="master"):
""" Assign roles to composite role
@@ -656,11 +754,10 @@ class KeycloakAPI(object):
"""
available_rolemappings_url = URL_ROLES_BY_ID_COMPOSITES.format(url=self.baseurl, realm=realm, id=rid)
try:
- open_url(available_rolemappings_url, method="POST", http_agent=self.http_agent, headers=self.restheaders, data=json.dumps(roles_rep),
- validate_certs=self.validate_certs, timeout=self.connection_timeout)
+ self._request(available_rolemappings_url, method="POST", data=json.dumps(roles_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could not assign roles to composite role %s and realm %s: %s"
- % (rid, realm, str(e)))
+ self.fail_request(e, msg="Could not assign roles to composite role %s and realm %s: %s"
+ % (rid, realm, str(e)))
def add_group_realm_rolemapping(self, gid, role_rep, realm="master"):
""" Add the specified realm role to specified group on the Keycloak server.
@@ -672,11 +769,10 @@ class KeycloakAPI(object):
"""
url = URL_REALM_GROUP_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, group=gid)
try:
- open_url(url, method="POST", http_agent=self.http_agent, headers=self.restheaders, data=json.dumps(role_rep),
- validate_certs=self.validate_certs, timeout=self.connection_timeout)
+ self._request(url, method="POST", data=json.dumps(role_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could add realm role mappings for group %s, realm %s: %s"
- % (gid, realm, str(e)))
+ self.fail_request(e, msg="Could add realm role mappings for group %s, realm %s: %s"
+ % (gid, realm, str(e)))
def delete_group_realm_rolemapping(self, gid, role_rep, realm="master"):
""" Delete the specified realm role from the specified group on the Keycloak server.
@@ -688,11 +784,10 @@ class KeycloakAPI(object):
"""
url = URL_REALM_GROUP_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, group=gid)
try:
- open_url(url, method="DELETE", http_agent=self.http_agent, headers=self.restheaders, data=json.dumps(role_rep),
- validate_certs=self.validate_certs, timeout=self.connection_timeout)
+ self._request(url, method="DELETE", data=json.dumps(role_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could not delete realm role mappings for group %s, realm %s: %s"
- % (gid, realm, str(e)))
+ self.fail_request(e, msg="Could not delete realm role mappings for group %s, realm %s: %s"
+ % (gid, realm, str(e)))
def add_group_rolemapping(self, gid, cid, role_rep, realm="master"):
""" Fetch the composite role of a client in a specified group on the Keycloak server.
@@ -705,11 +800,10 @@ class KeycloakAPI(object):
"""
available_rolemappings_url = URL_CLIENT_GROUP_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=gid, client=cid)
try:
- open_url(available_rolemappings_url, method="POST", http_agent=self.http_agent, headers=self.restheaders, data=json.dumps(role_rep),
- validate_certs=self.validate_certs, timeout=self.connection_timeout)
+ self._request(available_rolemappings_url, method="POST", data=json.dumps(role_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch available rolemappings for client %s in group %s, realm %s: %s"
- % (cid, gid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch available rolemappings for client %s in group %s, realm %s: %s"
+ % (cid, gid, realm, str(e)))
def delete_group_rolemapping(self, gid, cid, role_rep, realm="master"):
""" Delete the rolemapping of a client in a specified group on the Keycloak server.
@@ -722,11 +816,10 @@ class KeycloakAPI(object):
"""
available_rolemappings_url = URL_CLIENT_GROUP_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=gid, client=cid)
try:
- open_url(available_rolemappings_url, method="DELETE", http_agent=self.http_agent, headers=self.restheaders, data=json.dumps(role_rep),
- validate_certs=self.validate_certs, timeout=self.connection_timeout)
+ self._request(available_rolemappings_url, method="DELETE", data=json.dumps(role_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could not delete available rolemappings for client %s in group %s, realm %s: %s"
- % (cid, gid, realm, str(e)))
+ self.fail_request(e, msg="Could not delete available rolemappings for client %s in group %s, realm %s: %s"
+ % (cid, gid, realm, str(e)))
def get_client_user_rolemapping_by_id(self, uid, cid, rid, realm='master'):
""" Obtain client representation by id
@@ -739,15 +832,13 @@ class KeycloakAPI(object):
"""
rolemappings_url = URL_CLIENT_USER_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=uid, client=cid)
try:
- rolemappings = json.loads(to_native(open_url(rolemappings_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ rolemappings = self._request_and_deserialize(rolemappings_url, method="GET")
for role in rolemappings:
if rid == role['id']:
return role
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch rolemappings for client %s and user %s, realm %s: %s"
- % (cid, uid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch rolemappings for client %s and user %s, realm %s: %s"
+ % (cid, uid, realm, str(e)))
return None
def get_client_user_available_rolemappings(self, uid, cid, realm="master"):
@@ -760,12 +851,10 @@ class KeycloakAPI(object):
"""
available_rolemappings_url = URL_CLIENT_USER_ROLEMAPPINGS_AVAILABLE.format(url=self.baseurl, realm=realm, id=uid, client=cid)
try:
- return json.loads(to_native(open_url(available_rolemappings_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(available_rolemappings_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch effective rolemappings for client %s and user %s, realm %s: %s"
- % (cid, uid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch effective rolemappings for client %s and user %s, realm %s: %s"
+ % (cid, uid, realm, str(e)))
def get_client_user_composite_rolemappings(self, uid, cid, realm="master"):
""" Fetch the composite role of a client for a specified user on the Keycloak server.
@@ -777,12 +866,10 @@ class KeycloakAPI(object):
"""
composite_rolemappings_url = URL_CLIENT_USER_ROLEMAPPINGS_COMPOSITE.format(url=self.baseurl, realm=realm, id=uid, client=cid)
try:
- return json.loads(to_native(open_url(composite_rolemappings_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(composite_rolemappings_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch available rolemappings for user %s of realm %s: %s"
- % (uid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch available rolemappings for user %s of realm %s: %s"
+ % (uid, realm, str(e)))
def get_realm_user_rolemapping_by_id(self, uid, rid, realm='master'):
""" Obtain role representation by id
@@ -794,15 +881,13 @@ class KeycloakAPI(object):
"""
rolemappings_url = URL_REALM_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=uid)
try:
- rolemappings = json.loads(to_native(open_url(rolemappings_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ rolemappings = self._request_and_deserialize(rolemappings_url, method="GET")
for role in rolemappings:
if rid == role['id']:
return role
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch rolemappings for user %s, realm %s: %s"
- % (uid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch rolemappings for user %s, realm %s: %s"
+ % (uid, realm, str(e)))
return None
def get_realm_user_available_rolemappings(self, uid, realm="master"):
@@ -814,12 +899,10 @@ class KeycloakAPI(object):
"""
available_rolemappings_url = URL_REALM_ROLEMAPPINGS_AVAILABLE.format(url=self.baseurl, realm=realm, id=uid)
try:
- return json.loads(to_native(open_url(available_rolemappings_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(available_rolemappings_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch available rolemappings for user %s of realm %s: %s"
- % (uid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch available rolemappings for user %s of realm %s: %s"
+ % (uid, realm, str(e)))
def get_realm_user_composite_rolemappings(self, uid, realm="master"):
""" Fetch the composite role of a realm for a specified user on the Keycloak server.
@@ -830,12 +913,10 @@ class KeycloakAPI(object):
"""
composite_rolemappings_url = URL_REALM_ROLEMAPPINGS_COMPOSITE.format(url=self.baseurl, realm=realm, id=uid)
try:
- return json.loads(to_native(open_url(composite_rolemappings_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(composite_rolemappings_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch effective rolemappings for user %s, realm %s: %s"
- % (uid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch effective rolemappings for user %s, realm %s: %s"
+ % (uid, realm, str(e)))
def get_user_by_username(self, username, realm="master"):
""" Fetch a keycloak user within a realm based on its username.
@@ -848,9 +929,7 @@ class KeycloakAPI(object):
users_url += '?username=%s&exact=true' % username
try:
userrep = None
- users = json.loads(to_native(open_url(users_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ users = self._request_and_deserialize(users_url, method='GET')
for user in users:
if user['username'] == username:
userrep = user
@@ -861,8 +940,8 @@ class KeycloakAPI(object):
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain the user for realm %s and username %s: %s'
% (realm, username, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain the user for realm %s and username %s: %s'
- % (realm, username, str(e)))
+ self.fail_request(e, msg='Could not obtain the user for realm %s and username %s: %s'
+ % (realm, username, str(e)))
def get_service_account_user_by_client_id(self, client_id, realm="master"):
""" Fetch a keycloak service account user within a realm based on its client_id.
@@ -875,15 +954,13 @@ class KeycloakAPI(object):
service_account_user_url = URL_CLIENT_SERVICE_ACCOUNT_USER.format(url=self.baseurl, realm=realm, id=cid)
try:
- return json.loads(to_native(open_url(service_account_user_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(service_account_user_url, method='GET')
except ValueError as e:
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain the service-account-user for realm %s and client_id %s: %s'
% (realm, client_id, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain the service-account-user for realm %s and client_id %s: %s'
- % (realm, client_id, str(e)))
+ self.fail_request(e, msg='Could not obtain the service-account-user for realm %s and client_id %s: %s'
+ % (realm, client_id, str(e)))
def add_user_rolemapping(self, uid, cid, role_rep, realm="master"):
""" Assign a realm or client role to a specified user on the Keycloak server.
@@ -897,19 +974,17 @@ class KeycloakAPI(object):
if cid is None:
user_realm_rolemappings_url = URL_REALM_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=uid)
try:
- open_url(user_realm_rolemappings_url, method="POST", http_agent=self.http_agent, headers=self.restheaders, data=json.dumps(role_rep),
- validate_certs=self.validate_certs, timeout=self.connection_timeout)
+ self._request(user_realm_rolemappings_url, method="POST", data=json.dumps(role_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could not map roles to userId %s for realm %s and roles %s: %s"
- % (uid, realm, json.dumps(role_rep), str(e)))
+ self.fail_request(e, msg="Could not map roles to userId %s for realm %s and roles %s: %s"
+ % (uid, realm, json.dumps(role_rep), str(e)))
else:
user_client_rolemappings_url = URL_CLIENT_USER_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=uid, client=cid)
try:
- open_url(user_client_rolemappings_url, method="POST", http_agent=self.http_agent, headers=self.restheaders, data=json.dumps(role_rep),
- validate_certs=self.validate_certs, timeout=self.connection_timeout)
+ self._request(user_client_rolemappings_url, method="POST", data=json.dumps(role_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could not map roles to userId %s for client %s, realm %s and roles %s: %s"
- % (cid, uid, realm, json.dumps(role_rep), str(e)))
+ self.fail_request(e, msg="Could not map roles to userId %s for client %s, realm %s and roles %s: %s"
+ % (cid, uid, realm, json.dumps(role_rep), str(e)))
def delete_user_rolemapping(self, uid, cid, role_rep, realm="master"):
""" Delete the rolemapping of a client in a specified user on the Keycloak server.
@@ -923,19 +998,17 @@ class KeycloakAPI(object):
if cid is None:
user_realm_rolemappings_url = URL_REALM_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=uid)
try:
- open_url(user_realm_rolemappings_url, method="DELETE", http_agent=self.http_agent, headers=self.restheaders, data=json.dumps(role_rep),
- validate_certs=self.validate_certs, timeout=self.connection_timeout)
+ self._request(user_realm_rolemappings_url, method="DELETE", data=json.dumps(role_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could not remove roles %s from userId %s, realm %s: %s"
- % (json.dumps(role_rep), uid, realm, str(e)))
+ self.fail_request(e, msg="Could not remove roles %s from userId %s, realm %s: %s"
+ % (json.dumps(role_rep), uid, realm, str(e)))
else:
user_client_rolemappings_url = URL_CLIENT_USER_ROLEMAPPINGS.format(url=self.baseurl, realm=realm, id=uid, client=cid)
try:
- open_url(user_client_rolemappings_url, method="DELETE", http_agent=self.http_agent, headers=self.restheaders, data=json.dumps(role_rep),
- validate_certs=self.validate_certs, timeout=self.connection_timeout)
+ self._request(user_client_rolemappings_url, method="DELETE", data=json.dumps(role_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could not remove roles %s for client %s from userId %s, realm %s: %s"
- % (json.dumps(role_rep), cid, uid, realm, str(e)))
+ self.fail_request(e, msg="Could not remove roles %s for client %s from userId %s, realm %s: %s"
+ % (json.dumps(role_rep), cid, uid, realm, str(e)))
def get_client_templates(self, realm='master'):
""" Obtains client template representations for client templates in a realm
@@ -946,14 +1019,13 @@ class KeycloakAPI(object):
url = URL_CLIENTTEMPLATES.format(url=self.baseurl, realm=realm)
try:
- return json.loads(to_native(open_url(url, method='GET', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(url, method='GET')
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'
% (realm, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain list of client templates for realm %s: %s'
- % (realm, str(e)))
+ self.fail_request(e, msg='Could not obtain list of client templates for realm %s: %s'
+ % (realm, str(e)))
def get_client_template_by_id(self, id, realm='master'):
""" Obtain client template representation by id
@@ -965,14 +1037,13 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(url, method='GET')
except ValueError as e:
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain client templates %s for realm %s: %s'
% (id, realm, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain client template %s for realm %s: %s'
- % (id, realm, str(e)))
+ self.fail_request(e, msg='Could not obtain client template %s for realm %s: %s'
+ % (id, realm, str(e)))
def get_client_template_by_name(self, name, realm='master'):
""" Obtain client template representation by name
@@ -1011,11 +1082,10 @@ class KeycloakAPI(object):
url = URL_CLIENTTEMPLATE.format(url=self.baseurl, realm=realm, id=id)
try:
- return open_url(url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(clienttrep), validate_certs=self.validate_certs)
+ return self._request(url, method='PUT', data=json.dumps(clienttrep))
except Exception as e:
- self.fail_open_url(e, msg='Could not update client template %s in realm %s: %s'
- % (id, realm, str(e)))
+ self.fail_request(e, msg='Could not update client template %s in realm %s: %s'
+ % (id, realm, str(e)))
def create_client_template(self, clienttrep, realm="master"):
""" Create a client in keycloak
@@ -1026,11 +1096,10 @@ class KeycloakAPI(object):
url = URL_CLIENTTEMPLATES.format(url=self.baseurl, realm=realm)
try:
- return open_url(url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(clienttrep), validate_certs=self.validate_certs)
+ return self._request(url, method='POST', data=json.dumps(clienttrep))
except Exception as e:
- self.fail_open_url(e, msg='Could not create client template %s in realm %s: %s'
- % (clienttrep['clientId'], realm, str(e)))
+ self.fail_request(e, msg='Could not create client template %s in realm %s: %s'
+ % (clienttrep['clientId'], realm, str(e)))
def delete_client_template(self, id, realm="master"):
""" Delete a client template from Keycloak
@@ -1042,11 +1111,10 @@ class KeycloakAPI(object):
url = URL_CLIENTTEMPLATE.format(url=self.baseurl, realm=realm, id=id)
try:
- return open_url(url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Could not delete client template %s in realm %s: %s'
- % (id, realm, str(e)))
+ self.fail_request(e, msg='Could not delete client template %s in realm %s: %s'
+ % (id, realm, str(e)))
def get_clientscopes(self, realm="master"):
""" Fetch the name and ID of all clientscopes on the Keycloak server.
@@ -1059,12 +1127,10 @@ 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", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(clientscopes_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch list of clientscopes in realm %s: %s"
- % (realm, str(e)))
+ self.fail_request(e, msg="Could not fetch list of clientscopes in realm %s: %s"
+ % (realm, str(e)))
def get_clientscope_by_clientscopeid(self, cid, realm="master"):
""" Fetch a keycloak clientscope from the provided realm using the clientscope's unique ID.
@@ -1077,16 +1143,14 @@ 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", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(clientscope_url, method="GET")
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg="Could not fetch clientscope %s in realm %s: %s"
- % (cid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch clientscope %s in realm %s: %s"
+ % (cid, realm, str(e)))
except Exception as e:
self.module.fail_json(msg="Could not clientscope group %s in realm %s: %s"
% (cid, realm, str(e)))
@@ -1123,11 +1187,10 @@ class KeycloakAPI(object):
"""
clientscopes_url = URL_CLIENTSCOPES.format(url=self.baseurl, realm=realm)
try:
- return open_url(clientscopes_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(clientscoperep), validate_certs=self.validate_certs)
+ return self._request(clientscopes_url, method='POST', data=json.dumps(clientscoperep))
except Exception as e:
- self.fail_open_url(e, msg="Could not create clientscope %s in realm %s: %s"
- % (clientscoperep['name'], realm, str(e)))
+ self.fail_request(e, msg="Could not create clientscope %s in realm %s: %s"
+ % (clientscoperep['name'], realm, str(e)))
def update_clientscope(self, clientscoperep, realm="master"):
""" Update an existing clientscope.
@@ -1138,12 +1201,11 @@ class KeycloakAPI(object):
clientscope_url = URL_CLIENTSCOPE.format(url=self.baseurl, realm=realm, id=clientscoperep['id'])
try:
- return open_url(clientscope_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(clientscoperep), validate_certs=self.validate_certs)
+ return self._request(clientscope_url, method='PUT', data=json.dumps(clientscoperep))
except Exception as e:
- self.fail_open_url(e, msg='Could not update clientscope %s in realm %s: %s'
- % (clientscoperep['name'], realm, str(e)))
+ self.fail_request(e, msg='Could not update clientscope %s in realm %s: %s'
+ % (clientscoperep['name'], realm, str(e)))
def delete_clientscope(self, name=None, cid=None, realm="master"):
""" Delete a clientscope. One of name or cid must be provided.
@@ -1160,8 +1222,8 @@ class KeycloakAPI(object):
# prefer an exception since this is almost certainly a programming error in the module itself.
raise Exception("Unable to delete group - one of group ID or name must be provided.")
- # only lookup the name if cid isn't provided.
- # in the case that both are provided, prefer the ID, since it's one
+ # only lookup the name if cid is not provided.
+ # in the case that both are provided, prefer the ID, since it is one
# less lookup.
if cid is None and name is not None:
for clientscope in self.get_clientscopes(realm=realm):
@@ -1176,11 +1238,10 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(clientscope_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg="Unable to delete clientscope %s: %s" % (cid, str(e)))
+ self.fail_request(e, msg="Unable to delete clientscope %s: %s" % (cid, str(e)))
def get_clientscope_protocolmappers(self, cid, realm="master"):
""" Fetch the name and ID of all clientscopes on the Keycloak server.
@@ -1194,12 +1255,10 @@ 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", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(protocolmappers_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch list of protocolmappers in realm %s: %s"
- % (realm, str(e)))
+ self.fail_request(e, msg="Could not fetch list of protocolmappers in realm %s: %s"
+ % (realm, str(e)))
def get_clientscope_protocolmapper_by_protocolmapperid(self, pid, cid, realm="master"):
""" Fetch a keycloak clientscope from the provided realm using the clientscope's unique ID.
@@ -1214,16 +1273,14 @@ 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", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(protocolmapper_url, method="GET")
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg="Could not fetch protocolmapper %s in realm %s: %s"
- % (pid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch protocolmapper %s in realm %s: %s"
+ % (pid, realm, str(e)))
except Exception as e:
self.module.fail_json(msg="Could not fetch protocolmapper %s in realm %s: %s"
% (cid, realm, str(e)))
@@ -1262,11 +1319,10 @@ class KeycloakAPI(object):
"""
protocolmappers_url = URL_CLIENTSCOPE_PROTOCOLMAPPERS.format(url=self.baseurl, id=cid, realm=realm)
try:
- return open_url(protocolmappers_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(mapper_rep), validate_certs=self.validate_certs)
+ return self._request(protocolmappers_url, method='POST', data=json.dumps(mapper_rep))
except Exception as e:
- self.fail_open_url(e, msg="Could not create protocolmapper %s in realm %s: %s"
- % (mapper_rep['name'], realm, str(e)))
+ self.fail_request(e, msg="Could not create protocolmapper %s in realm %s: %s"
+ % (mapper_rep['name'], realm, str(e)))
def update_clientscope_protocolmappers(self, cid, mapper_rep, realm="master"):
""" Update an existing clientscope.
@@ -1278,12 +1334,11 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(mapper_rep), validate_certs=self.validate_certs)
+ return self._request(protocolmapper_url, method='PUT', data=json.dumps(mapper_rep))
except Exception as e:
- self.fail_open_url(e, msg='Could not update protocolmappers for clientscope %s in realm %s: %s'
- % (mapper_rep, realm, str(e)))
+ self.fail_request(e, msg='Could not update protocolmappers for clientscope %s in realm %s: %s'
+ % (mapper_rep, realm, str(e)))
def get_default_clientscopes(self, realm, client_id=None):
"""Fetch the name and ID of all clientscopes on the Keycloak server.
@@ -1326,18 +1381,16 @@ class KeycloakAPI(object):
if client_id is None:
clientscopes_url = url_template.format(url=self.baseurl, realm=realm)
try:
- return json.loads(to_native(open_url(clientscopes_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout, validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(clientscopes_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch list of %s clientscopes in realm %s: %s" % (scope_type, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch list of %s clientscopes in realm %s: %s" % (scope_type, realm, str(e)))
else:
cid = self.get_client_id(client_id=client_id, realm=realm)
clientscopes_url = url_template.format(url=self.baseurl, realm=realm, cid=cid)
try:
- return json.loads(to_native(open_url(clientscopes_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout, validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(clientscopes_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch list of %s clientscopes in client %s: %s" % (scope_type, client_id, clientscopes_url))
+ self.fail_request(e, msg="Could not fetch list of %s clientscopes in client %s: %s" % (scope_type, client_id, clientscopes_url))
def _decide_url_type_clientscope(self, client_id=None, scope_type="default"):
"""Decides which url to use.
@@ -1403,12 +1456,11 @@ class KeycloakAPI(object):
clientscope_type_url = self._decide_url_type_clientscope(client_id, scope_type).format(realm=realm, id=id, cid=cid, url=self.baseurl)
try:
method = 'PUT' if action == "add" else 'DELETE'
- return open_url(clientscope_type_url, method=method, http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(clientscope_type_url, method=method)
except Exception as e:
place = 'realm' if client_id is None else 'client ' + client_id
- self.fail_open_url(e, msg="Unable to %s %s clientscope %s @ %s : %s" % (action, scope_type, id, place, str(e)))
+ self.fail_request(e, msg="Unable to %s %s clientscope %s @ %s : %s" % (action, scope_type, id, place, str(e)))
def create_clientsecret(self, id, realm="master"):
""" Generate a new client secret by id
@@ -1420,16 +1472,14 @@ class KeycloakAPI(object):
clientsecret_url = URL_CLIENTSECRET.format(url=self.baseurl, realm=realm, id=id)
try:
- return json.loads(to_native(open_url(clientsecret_url, method='POST', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(clientsecret_url, method='POST')
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not obtain clientsecret of client %s for realm %s: %s'
- % (id, realm, str(e)))
+ self.fail_request(e, msg='Could not obtain clientsecret of client %s for realm %s: %s'
+ % (id, realm, str(e)))
except Exception as e:
self.module.fail_json(msg='Could not obtain clientsecret of client %s for realm %s: %s'
% (id, realm, str(e)))
@@ -1444,16 +1494,14 @@ class KeycloakAPI(object):
clientsecret_url = URL_CLIENTSECRET.format(url=self.baseurl, realm=realm, id=id)
try:
- return json.loads(to_native(open_url(clientsecret_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(clientsecret_url, method='GET')
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not obtain clientsecret of client %s for realm %s: %s'
- % (id, realm, str(e)))
+ self.fail_request(e, msg='Could not obtain clientsecret of client %s for realm %s: %s'
+ % (id, realm, str(e)))
except Exception as e:
self.module.fail_json(msg='Could not obtain clientsecret of client %s for realm %s: %s'
% (id, realm, str(e)))
@@ -1468,12 +1516,10 @@ 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", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(groups_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg="Could not fetch list of groups in realm %s: %s"
- % (realm, str(e)))
+ self.fail_request(e, msg="Could not fetch list of groups in realm %s: %s"
+ % (realm, str(e)))
def get_group_by_groupid(self, gid, realm="master"):
""" Fetch a keycloak group from the provided realm using the group's unique ID.
@@ -1486,15 +1532,13 @@ 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", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(groups_url, method="GET")
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg="Could not fetch group %s in realm %s: %s"
- % (gid, realm, str(e)))
+ self.fail_request(e, msg="Could not fetch group %s in realm %s: %s"
+ % (gid, realm, str(e)))
except Exception as e:
self.module.fail_json(msg="Could not fetch group %s in realm %s: %s"
% (gid, realm, str(e)))
@@ -1508,9 +1552,7 @@ class KeycloakAPI(object):
group_children = []
else:
group_children_url = URL_GROUP_CHILDREN.format(url=self.baseurl, realm=realm, groupid=parent['id'])
- group_children = json.loads(to_native(open_url(group_children_url, method="GET", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ group_children = self._request_and_deserialize(group_children_url, method="GET")
subgroups = group_children
else:
subgroups = parent['subGroups']
@@ -1528,7 +1570,6 @@ class KeycloakAPI(object):
:param realm: Realm in which the group resides; default 'master'
:param parents: Optional list of parents when group to look for is a subgroup
"""
- groups_url = URL_GROUPS.format(url=self.baseurl, realm=realm)
try:
if parents:
parent = self.get_subgroup_direct_parent(parents, realm)
@@ -1654,11 +1695,10 @@ class KeycloakAPI(object):
"""
groups_url = URL_GROUPS.format(url=self.baseurl, realm=realm)
try:
- return open_url(groups_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(grouprep), validate_certs=self.validate_certs)
+ return self._request(groups_url, method='POST', data=json.dumps(grouprep))
except Exception as e:
- self.fail_open_url(e, msg="Could not create group %s in realm %s: %s"
- % (grouprep['name'], realm, str(e)))
+ self.fail_request(e, msg="Could not create group %s in realm %s: %s"
+ % (grouprep['name'], realm, str(e)))
def create_subgroup(self, parents, grouprep, realm="master"):
""" Create a Keycloak subgroup.
@@ -1682,11 +1722,10 @@ class KeycloakAPI(object):
parent_id = parent_id["id"]
url = URL_GROUP_CHILDREN.format(url=self.baseurl, realm=realm, groupid=parent_id)
- return open_url(url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(grouprep), validate_certs=self.validate_certs)
+ return self._request(url, method='POST', data=json.dumps(grouprep))
except Exception as e:
- self.fail_open_url(e, msg="Could not create subgroup %s for parent group %s in realm %s: %s"
- % (grouprep['name'], parent_id, realm, str(e)))
+ self.fail_request(e, msg="Could not create subgroup %s for parent group %s in realm %s: %s"
+ % (grouprep['name'], parent_id, realm, str(e)))
def update_group(self, grouprep, realm="master"):
""" Update an existing group.
@@ -1697,11 +1736,10 @@ class KeycloakAPI(object):
group_url = URL_GROUP.format(url=self.baseurl, realm=realm, groupid=grouprep['id'])
try:
- return open_url(group_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(grouprep), validate_certs=self.validate_certs)
+ return self._request(group_url, method='PUT', data=json.dumps(grouprep))
except Exception as e:
- self.fail_open_url(e, msg='Could not update group %s in realm %s: %s'
- % (grouprep['name'], realm, str(e)))
+ self.fail_request(e, msg='Could not update group %s in realm %s: %s'
+ % (grouprep['name'], realm, str(e)))
def delete_group(self, name=None, groupid=None, realm="master"):
""" Delete a group. One of name or groupid must be provided.
@@ -1719,7 +1757,7 @@ class KeycloakAPI(object):
raise Exception("Unable to delete group - one of group ID or name must be provided.")
# only lookup the name if groupid isn't provided.
- # in the case that both are provided, prefer the ID, since it's one
+ # in the case that both are provided, prefer the ID, since it is one
# less lookup.
if groupid is None and name is not None:
for group in self.get_groups(realm=realm):
@@ -1734,10 +1772,9 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(group_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg="Unable to delete group %s: %s" % (groupid, str(e)))
+ self.fail_request(e, msg="Unable to delete group %s: %s" % (groupid, str(e)))
def get_realm_roles(self, realm='master'):
""" Obtains role representations for roles in a realm
@@ -1747,15 +1784,13 @@ 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', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(rolelist_url, method='GET')
except ValueError as e:
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of roles for realm %s: %s'
% (realm, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain list of roles for realm %s: %s'
- % (realm, str(e)))
+ self.fail_request(e, msg='Could not obtain list of roles for realm %s: %s'
+ % (realm, str(e)))
def get_realm_role(self, name, realm='master'):
""" Fetch a keycloak role from the provided realm using the role's name.
@@ -1766,14 +1801,13 @@ class KeycloakAPI(object):
"""
role_url = URL_REALM_ROLE.format(url=self.baseurl, realm=realm, name=quote(name, safe=''))
try:
- return json.loads(to_native(open_url(role_url, method="GET", http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(role_url, method="GET")
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not fetch role %s in realm %s: %s'
- % (name, realm, str(e)))
+ self.fail_request(e, msg='Could not fetch role %s in realm %s: %s'
+ % (name, realm, str(e)))
except Exception as e:
self.module.fail_json(msg='Could not fetch role %s in realm %s: %s'
% (name, realm, str(e)))
@@ -1789,11 +1823,10 @@ class KeycloakAPI(object):
if "composites" in rolerep:
keycloak_compatible_composites = self.convert_role_composites(rolerep["composites"])
rolerep["composites"] = keycloak_compatible_composites
- return open_url(roles_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(rolerep), validate_certs=self.validate_certs)
+ return self._request(roles_url, method='POST', data=json.dumps(rolerep))
except Exception as e:
- self.fail_open_url(e, msg='Could not create role %s in realm %s: %s'
- % (rolerep['name'], realm, str(e)))
+ self.fail_request(e, msg='Could not create role %s in realm %s: %s'
+ % (rolerep['name'], realm, str(e)))
def update_realm_role(self, rolerep, realm='master'):
""" Update an existing realm role.
@@ -1807,14 +1840,13 @@ class KeycloakAPI(object):
if "composites" in rolerep:
composites = copy.deepcopy(rolerep["composites"])
del rolerep["composites"]
- role_response = open_url(role_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(rolerep), validate_certs=self.validate_certs)
+ role_response = self._request(role_url, method='PUT', data=json.dumps(rolerep))
if composites is not None:
self.update_role_composites(rolerep=rolerep, composites=composites, realm=realm)
return role_response
except Exception as e:
- self.fail_open_url(e, msg='Could not update role %s in realm %s: %s'
- % (rolerep['name'], realm, str(e)))
+ self.fail_request(e, msg='Could not update role %s in realm %s: %s'
+ % (rolerep['name'], realm, str(e)))
def get_role_composites(self, rolerep, clientid=None, realm='master'):
composite_url = ''
@@ -1826,16 +1858,10 @@ class KeycloakAPI(object):
else:
composite_url = URL_REALM_ROLE_COMPOSITES.format(url=self.baseurl, realm=realm, name=quote(rolerep["name"], safe=''))
# Get existing composites
- return json.loads(to_native(open_url(
- composite_url,
- method='GET',
- http_agent=self.http_agent,
- headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(composite_url, method='GET')
except Exception as e:
- self.fail_open_url(e, msg='Could not get role %s composites in realm %s: %s'
- % (rolerep['name'], realm, str(e)))
+ self.fail_request(e, msg='Could not get role %s composites in realm %s: %s'
+ % (rolerep['name'], realm, str(e)))
def create_role_composites(self, rolerep, composites, clientid=None, realm='master'):
composite_url = ''
@@ -1848,11 +1874,10 @@ class KeycloakAPI(object):
composite_url = URL_REALM_ROLE_COMPOSITES.format(url=self.baseurl, realm=realm, name=quote(rolerep["name"], safe=''))
# Get existing composites
# create new composites
- return open_url(composite_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(composites), validate_certs=self.validate_certs)
+ return self._request(composite_url, method='POST', data=json.dumps(composites))
except Exception as e:
- self.fail_open_url(e, msg='Could not create role %s composites in realm %s: %s'
- % (rolerep['name'], realm, str(e)))
+ self.fail_request(e, msg='Could not create role %s composites in realm %s: %s'
+ % (rolerep['name'], realm, str(e)))
def delete_role_composites(self, rolerep, composites, clientid=None, realm='master'):
composite_url = ''
@@ -1865,11 +1890,10 @@ class KeycloakAPI(object):
composite_url = URL_REALM_ROLE_COMPOSITES.format(url=self.baseurl, realm=realm, name=quote(rolerep["name"], safe=''))
# Get existing composites
# create new composites
- return open_url(composite_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(composites), validate_certs=self.validate_certs)
+ return self._request(composite_url, method='DELETE', data=json.dumps(composites))
except Exception as e:
- self.fail_open_url(e, msg='Could not create role %s composites in realm %s: %s'
- % (rolerep['name'], realm, str(e)))
+ self.fail_request(e, msg='Could not create role %s composites in realm %s: %s'
+ % (rolerep['name'], realm, str(e)))
def update_role_composites(self, rolerep, composites, clientid=None, realm='master'):
# Get existing composites
@@ -1929,11 +1953,10 @@ class KeycloakAPI(object):
"""
role_url = URL_REALM_ROLE.format(url=self.baseurl, realm=realm, name=quote(name, safe=''))
try:
- return open_url(role_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(role_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Unable to delete role %s in realm %s: %s'
- % (name, realm, str(e)))
+ self.fail_request(e, msg='Unable to delete role %s in realm %s: %s'
+ % (name, realm, str(e)))
def get_client_roles(self, clientid, realm='master'):
""" Obtains role representations for client roles in a specific client
@@ -1948,15 +1971,13 @@ 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', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(rolelist_url, method='GET')
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'
% (clientid, realm, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain list of roles for client %s in realm %s: %s'
- % (clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not obtain list of roles for client %s in realm %s: %s'
+ % (clientid, realm, str(e)))
def get_client_role(self, name, clientid, realm='master'):
""" Fetch a keycloak client role from the provided realm using the role's name.
@@ -1973,14 +1994,13 @@ class KeycloakAPI(object):
% (clientid, realm))
role_url = URL_CLIENT_ROLE.format(url=self.baseurl, realm=realm, id=cid, name=quote(name, safe=''))
try:
- return json.loads(to_native(open_url(role_url, method="GET", http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(role_url, method="GET")
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not fetch role %s in client %s of realm %s: %s'
- % (name, clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not fetch role %s in client %s of realm %s: %s'
+ % (name, clientid, realm, str(e)))
except Exception as e:
self.module.fail_json(msg='Could not fetch role %s for client %s in realm %s: %s'
% (name, clientid, realm, str(e)))
@@ -2002,11 +2022,10 @@ class KeycloakAPI(object):
if "composites" in rolerep:
keycloak_compatible_composites = self.convert_role_composites(rolerep["composites"])
rolerep["composites"] = keycloak_compatible_composites
- return open_url(roles_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(rolerep), validate_certs=self.validate_certs)
+ return self._request(roles_url, method='POST', data=json.dumps(rolerep))
except Exception as e:
- self.fail_open_url(e, msg='Could not create role %s for client %s in realm %s: %s'
- % (rolerep['name'], clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not create role %s for client %s in realm %s: %s'
+ % (rolerep['name'], clientid, realm, str(e)))
def convert_role_composites(self, composites):
keycloak_compatible_composites = {
@@ -2041,14 +2060,13 @@ class KeycloakAPI(object):
if "composites" in rolerep:
composites = copy.deepcopy(rolerep["composites"])
del rolerep['composites']
- update_role_response = open_url(role_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(rolerep), validate_certs=self.validate_certs)
+ update_role_response = self._request(role_url, method='PUT', data=json.dumps(rolerep))
if composites is not None:
self.update_role_composites(rolerep=rolerep, clientid=clientid, composites=composites, realm=realm)
return update_role_response
except Exception as e:
- self.fail_open_url(e, msg='Could not update role %s for client %s in realm %s: %s'
- % (rolerep['name'], clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not update role %s for client %s in realm %s: %s'
+ % (rolerep['name'], clientid, realm, str(e)))
def delete_client_role(self, name, clientid, realm="master"):
""" Delete a role. One of name or roleid must be provided.
@@ -2063,15 +2081,14 @@ class KeycloakAPI(object):
% (clientid, realm))
role_url = URL_CLIENT_ROLE.format(url=self.baseurl, realm=realm, id=cid, name=quote(name, safe=''))
try:
- return open_url(role_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(role_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Unable to delete role %s for client %s in realm %s: %s'
- % (name, clientid, realm, str(e)))
+ self.fail_request(e, msg='Unable to delete role %s for client %s in realm %s: %s'
+ % (name, clientid, realm, str(e)))
def get_authentication_flow_by_alias(self, alias, realm='master'):
"""
- Get an authentication flow by it's alias
+ Get an authentication flow by its alias
:param alias: Alias of the authentication flow to get.
:param realm: Realm.
:return: Authentication flow representation.
@@ -2079,16 +2096,14 @@ 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',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout, validate_certs=self.validate_certs))
+ authentications = json.load(self._request(URL_AUTHENTICATION_FLOWS.format(url=self.baseurl, realm=realm), method='GET'))
for authentication in authentications:
if authentication["alias"] == alias:
authentication_flow = authentication
break
return authentication_flow
except Exception as e:
- self.fail_open_url(e, msg="Unable get authentication flow %s: %s" % (alias, str(e)))
+ self.fail_request(e, msg="Unable get authentication flow %s: %s" % (alias, str(e)))
def delete_authentication_flow_by_id(self, id, realm='master'):
"""
@@ -2100,11 +2115,10 @@ class KeycloakAPI(object):
flow_url = URL_AUTHENTICATION_FLOW.format(url=self.baseurl, realm=realm, id=id)
try:
- return open_url(flow_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(flow_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Could not delete authentication flow %s in realm %s: %s'
- % (id, realm, str(e)))
+ self.fail_request(e, msg='Could not delete authentication flow %s in realm %s: %s'
+ % (id, realm, str(e)))
def copy_auth_flow(self, config, realm='master'):
"""
@@ -2117,31 +2131,25 @@ class KeycloakAPI(object):
new_name = dict(
newName=config["alias"]
)
- open_url(
+ self._request(
URL_AUTHENTICATION_FLOW_COPY.format(
url=self.baseurl,
realm=realm,
copyfrom=quote(config["copyFrom"], safe='')),
method='POST',
- http_agent=self.http_agent, headers=self.restheaders,
- data=json.dumps(new_name),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ data=json.dumps(new_name))
flow_list = json.load(
- open_url(
+ self._request(
URL_AUTHENTICATION_FLOWS.format(url=self.baseurl,
realm=realm),
- method='GET',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs))
+ method='GET'))
for flow in flow_list:
if flow["alias"] == config["alias"]:
return flow
return None
except Exception as e:
- self.fail_open_url(e, msg='Could not copy authentication flow %s in realm %s: %s'
- % (config["alias"], realm, str(e)))
+ self.fail_request(e, msg='Could not copy authentication flow %s in realm %s: %s'
+ % (config["alias"], realm, str(e)))
def create_empty_auth_flow(self, config, realm='master'):
"""
@@ -2157,31 +2165,25 @@ class KeycloakAPI(object):
description=config["description"],
topLevel=True
)
- open_url(
+ self._request(
URL_AUTHENTICATION_FLOWS.format(
url=self.baseurl,
realm=realm),
method='POST',
- http_agent=self.http_agent, headers=self.restheaders,
- data=json.dumps(new_flow),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ data=json.dumps(new_flow))
flow_list = json.load(
- open_url(
+ self._request(
URL_AUTHENTICATION_FLOWS.format(
url=self.baseurl,
realm=realm),
- method='GET',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs))
+ method='GET'))
for flow in flow_list:
if flow["alias"] == config["alias"]:
return flow
return None
except Exception as e:
- self.fail_open_url(e, msg='Could not create empty authentication flow %s in realm %s: %s'
- % (config["alias"], realm, str(e)))
+ self.fail_request(e, msg='Could not create empty authentication flow %s in realm %s: %s'
+ % (config["alias"], realm, str(e)))
def update_authentication_executions(self, flowAlias, updatedExec, realm='master'):
""" Update authentication executions
@@ -2191,19 +2193,16 @@ class KeycloakAPI(object):
:return: HTTPResponse object on success
"""
try:
- open_url(
+ self._request(
URL_AUTHENTICATION_FLOW_EXECUTIONS.format(
url=self.baseurl,
realm=realm,
flowalias=quote(flowAlias, safe='')),
method='PUT',
- http_agent=self.http_agent, headers=self.restheaders,
- data=json.dumps(updatedExec),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ data=json.dumps(updatedExec))
except HTTPError as e:
- self.fail_open_url(e, msg="Unable to update execution '%s': %s: %s %s"
- % (flowAlias, repr(e), ";".join([e.url, e.msg, str(e.code), str(e.hdrs)]), str(updatedExec)))
+ self.fail_request(e, msg="Unable to update execution '%s': %s: %s %s"
+ % (flowAlias, repr(e), ";".join([e.url, e.msg, str(e.code), str(e.hdrs)]), str(updatedExec)))
except Exception as e:
self.module.fail_json(msg="Unable to update executions %s: %s" % (updatedExec, str(e)))
@@ -2215,18 +2214,15 @@ class KeycloakAPI(object):
:return: HTTPResponse object on success
"""
try:
- open_url(
+ self._request(
URL_AUTHENTICATION_EXECUTION_CONFIG.format(
url=self.baseurl,
realm=realm,
id=executionId),
method='POST',
- http_agent=self.http_agent, headers=self.restheaders,
- data=json.dumps(authenticationConfig),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ data=json.dumps(authenticationConfig))
except Exception as e:
- self.fail_open_url(e, msg="Unable to add authenticationConfig %s: %s" % (executionId, str(e)))
+ self.fail_request(e, msg="Unable to add authenticationConfig %s: %s" % (executionId, str(e)))
def create_subflow(self, subflowName, flowAlias, realm='master', flowType='basic-flow'):
""" Create new sublow on the flow
@@ -2240,18 +2236,15 @@ class KeycloakAPI(object):
newSubFlow["alias"] = subflowName
newSubFlow["provider"] = "registration-page-form"
newSubFlow["type"] = flowType
- open_url(
+ self._request(
URL_AUTHENTICATION_FLOW_EXECUTIONS_FLOW.format(
url=self.baseurl,
realm=realm,
flowalias=quote(flowAlias, safe='')),
method='POST',
- http_agent=self.http_agent, headers=self.restheaders,
- data=json.dumps(newSubFlow),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ data=json.dumps(newSubFlow))
except Exception as e:
- self.fail_open_url(e, msg="Unable to create new subflow %s: %s" % (subflowName, str(e)))
+ self.fail_request(e, msg="Unable to create new subflow %s: %s" % (subflowName, str(e)))
def create_execution(self, execution, flowAlias, realm='master'):
""" Create new execution on the flow
@@ -2264,19 +2257,16 @@ class KeycloakAPI(object):
newExec = {}
newExec["provider"] = execution["providerId"]
newExec["requirement"] = execution["requirement"]
- open_url(
+ self._request(
URL_AUTHENTICATION_FLOW_EXECUTIONS_EXECUTION.format(
url=self.baseurl,
realm=realm,
flowalias=quote(flowAlias, safe='')),
method='POST',
- http_agent=self.http_agent, headers=self.restheaders,
- data=json.dumps(newExec),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ data=json.dumps(newExec))
except HTTPError as e:
- self.fail_open_url(e, msg="Unable to create new execution '%s' %s: %s: %s %s"
- % (flowAlias, execution["providerId"], repr(e), ";".join([e.url, e.msg, str(e.code), str(e.hdrs)]), str(newExec)))
+ self.fail_request(e, msg="Unable to create new execution '%s' %s: %s: %s %s"
+ % (flowAlias, execution["providerId"], repr(e), ";".join([e.url, e.msg, str(e.code), str(e.hdrs)]), str(newExec)))
except Exception as e:
self.module.fail_json(msg="Unable to create new execution '%s' %s: %s" % (flowAlias, execution["providerId"], repr(e)))
@@ -2291,28 +2281,22 @@ class KeycloakAPI(object):
try:
if diff > 0:
for i in range(diff):
- open_url(
+ self._request(
URL_AUTHENTICATION_EXECUTION_RAISE_PRIORITY.format(
url=self.baseurl,
realm=realm,
id=executionId),
- method='POST',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ method='POST')
elif diff < 0:
for i in range(-diff):
- open_url(
+ self._request(
URL_AUTHENTICATION_EXECUTION_LOWER_PRIORITY.format(
url=self.baseurl,
realm=realm,
id=executionId),
- method='POST',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ method='POST')
except Exception as e:
- self.fail_open_url(e, msg="Unable to change execution priority %s: %s" % (executionId, str(e)))
+ self.fail_request(e, msg="Unable to change execution priority %s: %s" % (executionId, str(e)))
def get_executions_representation(self, config, realm='master'):
"""
@@ -2324,33 +2308,27 @@ class KeycloakAPI(object):
try:
# Get executions created
executions = json.load(
- open_url(
+ self._request(
URL_AUTHENTICATION_FLOW_EXECUTIONS.format(
url=self.baseurl,
realm=realm,
flowalias=quote(config["alias"], safe='')),
- method='GET',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs))
+ method='GET'))
for execution in executions:
if "authenticationConfig" in execution:
execConfigId = execution["authenticationConfig"]
execConfig = json.load(
- open_url(
+ self._request(
URL_AUTHENTICATION_CONFIG.format(
url=self.baseurl,
realm=realm,
id=execConfigId),
- method='GET',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs))
+ method='GET'))
execution["authenticationConfig"] = execConfig
return executions
except Exception as e:
- self.fail_open_url(e, msg='Could not get executions for authentication flow %s in realm %s: %s'
- % (config["alias"], realm, str(e)))
+ self.fail_request(e, msg='Could not get executions for authentication flow %s in realm %s: %s'
+ % (config["alias"], realm, str(e)))
def get_required_actions(self, realm='master'):
"""
@@ -2361,15 +2339,12 @@ class KeycloakAPI(object):
try:
required_actions = json.load(
- open_url(
+ self._request(
URL_AUTHENTICATION_REQUIRED_ACTIONS.format(
url=self.baseurl,
realm=realm
),
- method='GET',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs
+ method='GET'
)
)
@@ -2391,19 +2366,16 @@ class KeycloakAPI(object):
}
try:
- return open_url(
+ return self._request(
URL_AUTHENTICATION_REGISTER_REQUIRED_ACTION.format(
url=self.baseurl,
realm=realm
),
method='POST',
- http_agent=self.http_agent, headers=self.restheaders,
data=json.dumps(data),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs
)
except Exception as e:
- self.fail_open_url(
+ self.fail_request(
e,
msg='Unable to register required action %s in realm %s: %s'
% (rep["name"], realm, str(e))
@@ -2419,20 +2391,17 @@ class KeycloakAPI(object):
"""
try:
- return open_url(
+ return self._request(
URL_AUTHENTICATION_REQUIRED_ACTIONS_ALIAS.format(
url=self.baseurl,
alias=quote(alias, safe=''),
realm=realm
),
method='PUT',
- http_agent=self.http_agent, headers=self.restheaders,
data=json.dumps(rep),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs
)
except Exception as e:
- self.fail_open_url(
+ self.fail_request(
e,
msg='Unable to update required action %s in realm %s: %s'
% (alias, realm, str(e))
@@ -2447,19 +2416,16 @@ class KeycloakAPI(object):
"""
try:
- return open_url(
+ return self._request(
URL_AUTHENTICATION_REQUIRED_ACTIONS_ALIAS.format(
url=self.baseurl,
alias=quote(alias, safe=''),
realm=realm
),
method='DELETE',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs
)
except Exception as e:
- self.fail_open_url(
+ self.fail_request(
e,
msg='Unable to delete required action %s in realm %s: %s'
% (alias, realm, str(e))
@@ -2472,14 +2438,13 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(idps_url, method='GET')
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'
% (realm, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain list of identity providers for realm %s: %s'
- % (realm, str(e)))
+ self.fail_request(e, msg='Could not obtain list of identity providers for realm %s: %s'
+ % (realm, str(e)))
def get_identity_provider(self, alias, realm='master'):
""" Fetch identity provider representation from a realm using the idp's alias.
@@ -2489,14 +2454,13 @@ 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", http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(idp_url, method="GET")
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not fetch identity provider %s in realm %s: %s'
- % (alias, realm, str(e)))
+ self.fail_request(e, msg='Could not fetch identity provider %s in realm %s: %s'
+ % (alias, realm, str(e)))
except Exception as e:
self.module.fail_json(msg='Could not fetch identity provider %s in realm %s: %s'
% (alias, realm, str(e)))
@@ -2509,11 +2473,10 @@ class KeycloakAPI(object):
"""
idps_url = URL_IDENTITY_PROVIDERS.format(url=self.baseurl, realm=realm)
try:
- return open_url(idps_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(idprep), validate_certs=self.validate_certs)
+ return self._request(idps_url, method='POST', data=json.dumps(idprep))
except Exception as e:
- self.fail_open_url(e, msg='Could not create identity provider %s in realm %s: %s'
- % (idprep['alias'], realm, str(e)))
+ self.fail_request(e, msg='Could not create identity provider %s in realm %s: %s'
+ % (idprep['alias'], realm, str(e)))
def update_identity_provider(self, idprep, realm='master'):
""" Update an existing identity provider.
@@ -2523,11 +2486,10 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(idprep), validate_certs=self.validate_certs)
+ return self._request(idp_url, method='PUT', data=json.dumps(idprep))
except Exception as e:
- self.fail_open_url(e, msg='Could not update identity provider %s in realm %s: %s'
- % (idprep['alias'], realm, str(e)))
+ self.fail_request(e, msg='Could not update identity provider %s in realm %s: %s'
+ % (idprep['alias'], realm, str(e)))
def delete_identity_provider(self, alias, realm='master'):
""" Delete an identity provider.
@@ -2536,11 +2498,10 @@ class KeycloakAPI(object):
"""
idp_url = URL_IDENTITY_PROVIDER.format(url=self.baseurl, realm=realm, alias=alias)
try:
- return open_url(idp_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(idp_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Unable to delete identity provider %s in realm %s: %s'
- % (alias, realm, str(e)))
+ self.fail_request(e, msg='Unable to delete identity provider %s in realm %s: %s'
+ % (alias, realm, str(e)))
def get_identity_provider_mappers(self, alias, realm='master'):
""" Fetch representations for identity provider mappers
@@ -2550,15 +2511,13 @@ 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', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(mappers_url, method='GET')
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'
% (alias, realm, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain list of identity provider mappers for idp %s in realm %s: %s'
- % (alias, realm, str(e)))
+ self.fail_request(e, msg='Could not obtain list of identity provider mappers for idp %s in realm %s: %s'
+ % (alias, realm, str(e)))
def get_identity_provider_mapper(self, mid, alias, realm='master'):
""" Fetch identity provider representation from a realm using the idp's alias.
@@ -2569,15 +2528,13 @@ 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", http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(mapper_url, method="GET")
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not fetch mapper %s for identity provider %s in realm %s: %s'
- % (mid, alias, realm, str(e)))
+ self.fail_request(e, msg='Could not fetch mapper %s for identity provider %s in realm %s: %s'
+ % (mid, alias, realm, str(e)))
except Exception as e:
self.module.fail_json(msg='Could not fetch mapper %s for identity provider %s in realm %s: %s'
% (mid, alias, realm, str(e)))
@@ -2591,11 +2548,10 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(mapper), validate_certs=self.validate_certs)
+ return self._request(mappers_url, method='POST', data=json.dumps(mapper))
except Exception as e:
- self.fail_open_url(e, msg='Could not create identity provider mapper %s for idp %s in realm %s: %s'
- % (mapper['name'], alias, realm, str(e)))
+ self.fail_request(e, msg='Could not create identity provider mapper %s for idp %s in realm %s: %s'
+ % (mapper['name'], alias, realm, str(e)))
def update_identity_provider_mapper(self, mapper, alias, realm='master'):
""" Update an existing identity provider.
@@ -2606,11 +2562,10 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(mapper), validate_certs=self.validate_certs)
+ return self._request(mapper_url, method='PUT', data=json.dumps(mapper))
except Exception as e:
- self.fail_open_url(e, msg='Could not update mapper %s for identity provider %s in realm %s: %s'
- % (mapper['id'], alias, realm, str(e)))
+ self.fail_request(e, msg='Could not update mapper %s for identity provider %s in realm %s: %s'
+ % (mapper['id'], alias, realm, str(e)))
def delete_identity_provider_mapper(self, mid, alias, realm='master'):
""" Delete an identity provider.
@@ -2620,11 +2575,10 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(mapper_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Unable to delete mapper %s for identity provider %s in realm %s: %s'
- % (mid, alias, realm, str(e)))
+ self.fail_request(e, msg='Unable to delete mapper %s for identity provider %s in realm %s: %s'
+ % (mid, alias, realm, str(e)))
def get_components(self, filter=None, realm='master'):
""" Fetch representations for components in a realm
@@ -2637,14 +2591,13 @@ class KeycloakAPI(object):
comps_url += '?%s' % filter
try:
- return json.loads(to_native(open_url(comps_url, method='GET', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(comps_url, method='GET')
except ValueError as e:
self.module.fail_json(msg='API returned incorrect JSON when trying to obtain list of components for realm %s: %s'
% (realm, str(e)))
except Exception as e:
- self.fail_open_url(e, msg='Could not obtain list of components for realm %s: %s'
- % (realm, str(e)))
+ self.fail_request(e, msg='Could not obtain list of components for realm %s: %s'
+ % (realm, str(e)))
def get_component(self, cid, realm='master'):
""" Fetch component representation from a realm using its cid.
@@ -2654,14 +2607,13 @@ 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", http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(comp_url, method="GET")
except HTTPError as e:
if e.code == 404:
return None
else:
- self.fail_open_url(e, msg='Could not fetch component %s in realm %s: %s'
- % (cid, realm, str(e)))
+ self.fail_request(e, msg='Could not fetch component %s in realm %s: %s'
+ % (cid, realm, str(e)))
except Exception as e:
self.module.fail_json(msg='Could not fetch component %s in realm %s: %s'
% (cid, realm, str(e)))
@@ -2674,17 +2626,15 @@ class KeycloakAPI(object):
"""
comps_url = URL_COMPONENTS.format(url=self.baseurl, realm=realm)
try:
- resp = open_url(comps_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(comprep), validate_certs=self.validate_certs)
+ resp = self._request(comps_url, method='POST', data=json.dumps(comprep))
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", http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(comp_url, method="GET")
except Exception as e:
- self.fail_open_url(e, msg='Could not create component in realm %s: %s'
- % (realm, str(e)))
+ self.fail_request(e, msg='Could not create component in realm %s: %s'
+ % (realm, str(e)))
def update_component(self, comprep, realm='master'):
""" Update an existing component.
@@ -2697,11 +2647,10 @@ 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', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(comprep), validate_certs=self.validate_certs)
+ return self._request(comp_url, method='PUT', data=json.dumps(comprep))
except Exception as e:
- self.fail_open_url(e, msg='Could not update component %s in realm %s: %s'
- % (cid, realm, str(e)))
+ self.fail_request(e, msg='Could not update component %s in realm %s: %s'
+ % (cid, realm, str(e)))
def delete_component(self, cid, realm='master'):
""" Delete an component.
@@ -2710,20 +2659,17 @@ class KeycloakAPI(object):
"""
comp_url = URL_COMPONENT.format(url=self.baseurl, realm=realm, id=cid)
try:
- return open_url(comp_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(comp_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Unable to delete component %s in realm %s: %s'
- % (cid, realm, str(e)))
+ self.fail_request(e, msg='Unable to delete component %s in realm %s: %s'
+ % (cid, realm, str(e)))
def get_authz_authorization_scope_by_name(self, name, client_id, realm):
url = URL_AUTHZ_AUTHORIZATION_SCOPES.format(url=self.baseurl, client_id=client_id, realm=realm)
search_url = "%s/search?name=%s" % (url, quote(name, safe=''))
try:
- return json.loads(to_native(open_url(search_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(search_url, method='GET')
except Exception:
return False
@@ -2732,30 +2678,27 @@ class KeycloakAPI(object):
url = URL_AUTHZ_AUTHORIZATION_SCOPES.format(url=self.baseurl, client_id=client_id, realm=realm)
try:
- return open_url(url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(payload), validate_certs=self.validate_certs)
+ return self._request(url, method='POST', data=json.dumps(payload))
except Exception as e:
- self.fail_open_url(e, msg='Could not create authorization scope %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
+ self.fail_request(e, msg='Could not create authorization scope %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
def update_authz_authorization_scope(self, payload, id, client_id, realm):
"""Update an authorization scope for a Keycloak client"""
url = URL_AUTHZ_AUTHORIZATION_SCOPE.format(url=self.baseurl, id=id, client_id=client_id, realm=realm)
try:
- return open_url(url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(payload), validate_certs=self.validate_certs)
+ return self._request(url, method='PUT', data=json.dumps(payload))
except Exception as e:
- self.fail_open_url(e, msg='Could not create update scope %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
+ self.fail_request(e, msg='Could not create update scope %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
def remove_authz_authorization_scope(self, id, client_id, realm):
"""Remove an authorization scope from a Keycloak client"""
url = URL_AUTHZ_AUTHORIZATION_SCOPE.format(url=self.baseurl, id=id, client_id=client_id, realm=realm)
try:
- return open_url(url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Could not delete scope %s for client %s in realm %s: %s' % (id, client_id, realm, str(e)))
+ self.fail_request(e, msg='Could not delete scope %s for client %s in realm %s: %s' % (id, client_id, realm, str(e)))
def get_user_by_id(self, user_id, realm='master'):
"""
@@ -2770,16 +2713,13 @@ class KeycloakAPI(object):
realm=realm,
id=user_id)
userrep = json.load(
- open_url(
+ self._request(
user_url,
- method='GET',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs))
+ method='GET'))
return userrep
except Exception as e:
- self.fail_open_url(e, msg='Could not get user %s in realm %s: %s'
- % (user_id, realm, str(e)))
+ self.fail_request(e, msg='Could not get user %s in realm %s: %s'
+ % (user_id, realm, str(e)))
def create_user(self, userrep, realm='master'):
"""
@@ -2795,19 +2735,16 @@ class KeycloakAPI(object):
users_url = URL_USERS.format(
url=self.baseurl,
realm=realm)
- open_url(users_url,
- method='POST',
- http_agent=self.http_agent, headers=self.restheaders,
- data=json.dumps(userrep),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ self._request(users_url,
+ method='POST',
+ data=json.dumps(userrep))
created_user = self.get_user_by_username(
username=userrep['username'],
realm=realm)
return created_user
except Exception as e:
- self.fail_open_url(e, msg='Could not create user %s in realm %s: %s'
- % (userrep['username'], realm, str(e)))
+ self.fail_request(e, msg='Could not create user %s in realm %s: %s'
+ % (userrep['username'], realm, str(e)))
def convert_user_attributes_to_keycloak_dict(self, attributes):
keycloak_user_attributes_dict = {}
@@ -2840,20 +2777,17 @@ class KeycloakAPI(object):
url=self.baseurl,
realm=realm,
id=userrep["id"])
- open_url(
+ self._request(
user_url,
method='PUT',
- http_agent=self.http_agent, headers=self.restheaders,
- data=json.dumps(userrep),
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ data=json.dumps(userrep))
updated_user = self.get_user_by_id(
user_id=userrep['id'],
realm=realm)
return updated_user
except Exception as e:
- self.fail_open_url(e, msg='Could not update user %s in realm %s: %s'
- % (userrep['username'], realm, str(e)))
+ self.fail_request(e, msg='Could not update user %s in realm %s: %s'
+ % (userrep['username'], realm, str(e)))
def delete_user(self, user_id, realm='master'):
"""
@@ -2867,15 +2801,12 @@ class KeycloakAPI(object):
url=self.baseurl,
realm=realm,
id=user_id)
- return open_url(
+ return self._request(
user_url,
- method='DELETE',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Could not delete user %s in realm %s: %s'
- % (user_id, realm, str(e)))
+ self.fail_request(e, msg='Could not delete user %s in realm %s: %s'
+ % (user_id, realm, str(e)))
def get_user_groups(self, user_id, realm='master'):
"""
@@ -2891,18 +2822,15 @@ class KeycloakAPI(object):
realm=realm,
id=user_id)
user_groups = json.load(
- open_url(
+ self._request(
user_groups_url,
- method='GET',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs))
+ method='GET'))
for user_group in user_groups:
groups.append(user_group["name"])
return groups
except Exception as e:
- self.fail_open_url(e, msg='Could not get groups for user %s in realm %s: %s'
- % (user_id, realm, str(e)))
+ self.fail_request(e, msg='Could not get groups for user %s in realm %s: %s'
+ % (user_id, realm, str(e)))
def add_user_in_group(self, user_id, group_id, realm='master'):
"""
@@ -2918,15 +2846,12 @@ class KeycloakAPI(object):
realm=realm,
id=user_id,
group_id=group_id)
- return open_url(
+ return self._request(
user_group_url,
- method='PUT',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ method='PUT')
except Exception as e:
- self.fail_open_url(e, msg='Could not add user %s in group %s in realm %s: %s'
- % (user_id, group_id, realm, str(e)))
+ self.fail_request(e, msg='Could not add user %s in group %s in realm %s: %s'
+ % (user_id, group_id, realm, str(e)))
def remove_user_from_group(self, user_id, group_id, realm='master'):
"""
@@ -2942,15 +2867,12 @@ class KeycloakAPI(object):
realm=realm,
id=user_id,
group_id=group_id)
- return open_url(
+ return self._request(
user_group_url,
- method='DELETE',
- http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Could not remove user %s from group %s in realm %s: %s'
- % (user_id, group_id, realm, str(e)))
+ self.fail_request(e, msg='Could not remove user %s from group %s in realm %s: %s'
+ % (user_id, group_id, realm, str(e)))
def update_user_groups_membership(self, userrep, groups, realm='master'):
"""
@@ -3018,10 +2940,9 @@ class KeycloakAPI(object):
url = URL_AUTHZ_CUSTOM_POLICY.format(url=self.baseurl, policy_type=policy_type, client_id=client_id, realm=realm)
try:
- return open_url(url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(payload), validate_certs=self.validate_certs)
+ return self._request(url, method='POST', data=json.dumps(payload))
except Exception as e:
- self.fail_open_url(e, msg='Could not create permission %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
+ self.fail_request(e, msg='Could not create permission %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
def remove_authz_custom_policy(self, policy_id, client_id, realm):
"""Remove a custom policy from a Keycloak client"""
@@ -3029,10 +2950,9 @@ class KeycloakAPI(object):
delete_url = "%s/%s" % (url, policy_id)
try:
- return open_url(delete_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(delete_url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Could not delete custom policy %s for client %s in realm %s: %s' % (id, client_id, realm, str(e)))
+ self.fail_request(e, msg='Could not delete custom policy %s for client %s in realm %s: %s' % (id, client_id, realm, str(e)))
def get_authz_permission_by_name(self, name, client_id, realm):
"""Get authorization permission by name"""
@@ -3040,9 +2960,7 @@ class KeycloakAPI(object):
search_url = "%s/search?name=%s" % (url, name.replace(' ', '%20'))
try:
- return json.loads(to_native(open_url(search_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(search_url, method='GET')
except Exception:
return False
@@ -3051,30 +2969,27 @@ class KeycloakAPI(object):
url = URL_AUTHZ_PERMISSIONS.format(url=self.baseurl, permission_type=permission_type, client_id=client_id, realm=realm)
try:
- return open_url(url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(payload), validate_certs=self.validate_certs)
+ return self._request(url, method='POST', data=json.dumps(payload))
except Exception as e:
- self.fail_open_url(e, msg='Could not create permission %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
+ self.fail_request(e, msg='Could not create permission %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
def remove_authz_permission(self, id, client_id, realm):
"""Create an authorization permission for a Keycloak client"""
url = URL_AUTHZ_POLICY.format(url=self.baseurl, id=id, client_id=client_id, realm=realm)
try:
- return open_url(url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- validate_certs=self.validate_certs)
+ return self._request(url, method='DELETE')
except Exception as e:
- self.fail_open_url(e, msg='Could not delete permission %s for client %s in realm %s: %s' % (id, client_id, realm, str(e)))
+ self.fail_request(e, msg='Could not delete permission %s for client %s in realm %s: %s' % (id, client_id, realm, str(e)))
def update_authz_permission(self, payload, permission_type, id, client_id, realm):
"""Update a permission for a Keycloak client"""
url = URL_AUTHZ_PERMISSION.format(url=self.baseurl, permission_type=permission_type, id=id, client_id=client_id, realm=realm)
try:
- return open_url(url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(payload), validate_certs=self.validate_certs)
+ return self._request(url, method='PUT', data=json.dumps(payload))
except Exception as e:
- self.fail_open_url(e, msg='Could not create update permission %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
+ self.fail_request(e, msg='Could not create update permission %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
def get_authz_resource_by_name(self, name, client_id, realm):
"""Get authorization resource by name"""
@@ -3082,9 +2997,7 @@ class KeycloakAPI(object):
search_url = "%s/search?name=%s" % (url, name.replace(' ', '%20'))
try:
- return json.loads(to_native(open_url(search_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(search_url, method='GET')
except Exception:
return False
@@ -3094,9 +3007,7 @@ class KeycloakAPI(object):
search_url = "%s/search?name=%s&permission=false" % (url, name.replace(' ', '%20'))
try:
- return json.loads(to_native(open_url(search_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(search_url, method='GET')
except Exception:
return False
@@ -3109,11 +3020,9 @@ class KeycloakAPI(object):
"""
client_role_scope_url = URL_CLIENT_ROLE_SCOPE_CLIENTS.format(url=self.baseurl, realm=realm, id=clientid, scopeid=clientscopeid)
try:
- return json.loads(to_native(open_url(client_role_scope_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(client_role_scope_url, method='GET')
except Exception as e:
- self.fail_open_url(e, msg='Could not fetch roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not fetch roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
def update_client_role_scope_from_client(self, payload, clientid, clientscopeid, realm="master"):
""" Update and fetch the roles associated with the client's scope on the Keycloak server.
@@ -3125,11 +3034,10 @@ class KeycloakAPI(object):
"""
client_role_scope_url = URL_CLIENT_ROLE_SCOPE_CLIENTS.format(url=self.baseurl, realm=realm, id=clientid, scopeid=clientscopeid)
try:
- open_url(client_role_scope_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(payload), validate_certs=self.validate_certs)
+ self._request(client_role_scope_url, method='POST', data=json.dumps(payload))
except Exception as e:
- self.fail_open_url(e, msg='Could not update roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not update roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
return self.get_client_role_scope_from_client(clientid, clientscopeid, realm)
@@ -3143,11 +3051,10 @@ class KeycloakAPI(object):
"""
client_role_scope_url = URL_CLIENT_ROLE_SCOPE_CLIENTS.format(url=self.baseurl, realm=realm, id=clientid, scopeid=clientscopeid)
try:
- open_url(client_role_scope_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(payload), validate_certs=self.validate_certs)
+ self._request(client_role_scope_url, method='DELETE', data=json.dumps(payload))
except Exception as e:
- self.fail_open_url(e, msg='Could not delete roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not delete roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
return self.get_client_role_scope_from_client(clientid, clientscopeid, realm)
@@ -3159,11 +3066,9 @@ class KeycloakAPI(object):
"""
client_role_scope_url = URL_CLIENT_ROLE_SCOPE_REALM.format(url=self.baseurl, realm=realm, id=clientid)
try:
- return json.loads(to_native(open_url(client_role_scope_url, method='GET', http_agent=self.http_agent, headers=self.restheaders,
- timeout=self.connection_timeout,
- validate_certs=self.validate_certs).read()))
+ return self._request_and_deserialize(client_role_scope_url, method='GET')
except Exception as e:
- self.fail_open_url(e, msg='Could not fetch roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not fetch roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
def update_client_role_scope_from_realm(self, payload, clientid, realm="master"):
""" Update and fetch the realm roles from the client's scope on the Keycloak server.
@@ -3174,11 +3079,10 @@ class KeycloakAPI(object):
"""
client_role_scope_url = URL_CLIENT_ROLE_SCOPE_REALM.format(url=self.baseurl, realm=realm, id=clientid)
try:
- open_url(client_role_scope_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(payload), validate_certs=self.validate_certs)
+ self._request(client_role_scope_url, method='POST', data=json.dumps(payload))
except Exception as e:
- self.fail_open_url(e, msg='Could not update roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not update roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
return self.get_client_role_scope_from_realm(clientid, realm)
@@ -3191,18 +3095,42 @@ class KeycloakAPI(object):
"""
client_role_scope_url = URL_CLIENT_ROLE_SCOPE_REALM.format(url=self.baseurl, realm=realm, id=clientid)
try:
- open_url(client_role_scope_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
- data=json.dumps(payload), validate_certs=self.validate_certs)
+ self._request(client_role_scope_url, method='DELETE', data=json.dumps(payload))
except Exception as e:
- self.fail_open_url(e, msg='Could not delete roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
+ self.fail_request(e, msg='Could not delete roles scope for client %s in realm %s: %s' % (clientid, realm, str(e)))
return self.get_client_role_scope_from_realm(clientid, realm)
- def fail_open_url(self, e, msg, **kwargs):
+ def fail_request(self, e, msg, **kwargs):
+ """ Triggers a module failure. This should be called
+ when an exception occurs during/after a request.
+ Attempts to parse the exception e as an HTTP error
+ and append it to msg.
+
+ :param e: exception which triggered the failure
+ :param msg: error message to display to the user
+ :param kwargs: additional arguments to pass to module.fail_json
+ :return: None
+ """
try:
if isinstance(e, HTTPError):
msg = "%s: %s" % (msg, to_native(e.read()))
- except Exception as ingore:
+ except Exception:
pass
self.module.fail_json(msg, **kwargs)
+
+ def fail_open_url(self, e, msg, **kwargs):
+ """ DEPRECATED: Use fail_request instead.
+
+ Triggers a module failure. This should be called
+ when an exception occurs during/after a request.
+ Attempts to parse the exception e as an HTTP error
+ and append it to msg.
+
+ :param e: exception which triggered the failure
+ :param msg: error message to display to the user
+ :param kwargs: additional arguments to pass to module.fail_json
+ :return: None
+ """
+ return self.fail_request(e, msg, **kwargs)
diff --git a/plugins/module_utils/identity/keycloak/keycloak_clientsecret.py b/plugins/module_utils/identity/keycloak/keycloak_clientsecret.py
index 85caa8e16b..366322c9df 100644
--- a/plugins/module_utils/identity/keycloak/keycloak_clientsecret.py
+++ b/plugins/module_utils/identity/keycloak/keycloak_clientsecret.py
@@ -61,7 +61,7 @@ def keycloak_clientsecret_module_resolve_params(module, kc):
client_id = module.params.get('client_id')
# only lookup the client_id if id isn't provided.
- # in the case that both are provided, prefer the ID, since it's one
+ # in the case that both are provided, prefer the ID, since it is one
# less lookup.
if id is None:
# Due to the required_one_of spec, client_id is guaranteed to not be None
diff --git a/plugins/module_utils/known_hosts.py b/plugins/module_utils/known_hosts.py
index 25dd3e174e..9a17355b4e 100644
--- a/plugins/module_utils/known_hosts.py
+++ b/plugins/module_utils/known_hosts.py
@@ -103,13 +103,11 @@ def not_in_host_file(self, host):
continue
try:
- host_fh = open(hf)
+ with open(hf) as host_fh:
+ data = host_fh.read()
except IOError:
hfiles_not_found += 1
continue
- else:
- data = host_fh.read()
- host_fh.close()
for line in data.split("\n"):
if line is None or " " not in line:
diff --git a/plugins/module_utils/mh/base.py b/plugins/module_utils/mh/base.py
index b10762eaba..cf054f59fd 100644
--- a/plugins/module_utils/mh/base.py
+++ b/plugins/module_utils/mh/base.py
@@ -15,6 +15,7 @@ from ansible_collections.community.general.plugins.module_utils.mh.deco import m
class ModuleHelperBase(object):
module = None
ModuleHelperException = _MHE
+ # in 12.0.0 add 'debug' to the tuple
_delegated_to_module = (
'check_mode', 'get_bin_path', 'warn', 'deprecate',
)
@@ -28,6 +29,18 @@ class ModuleHelperBase(object):
if not isinstance(self.module, AnsibleModule):
self.module = AnsibleModule(**self.module)
+ # in 12.0.0 remove this if statement entirely
+ if hasattr(self, 'debug'):
+ msg = (
+ "This class ({cls}) has an attribute 'debug' defined and that is deprecated. "
+ "Method 'debug' will be an integral part of ModuleHelper in community.general "
+ "12.0.0, delegated to the underlying AnsibleModule object. "
+ "Please rename the existing attribute to prevent this message from showing.".format(cls=self.__class__.__name__)
+ )
+ self.deprecate(msg, version="12.0.0", collection_name="community.general")
+ else:
+ self._delegated_to_module = self._delegated_to_module + ('debug',)
+
@property
def diff_mode(self):
return self.module._diff
diff --git a/plugins/module_utils/pacemaker.py b/plugins/module_utils/pacemaker.py
new file mode 100644
index 0000000000..9f1456e75c
--- /dev/null
+++ b/plugins/module_utils/pacemaker.py
@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2025, Dexter Le
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt
+
+
+_state_map = {
+ "present": "create",
+ "absent": "remove",
+ "status": "status",
+ "enabled": "enable",
+ "disabled": "disable"
+}
+
+
+def fmt_resource_type(value):
+ return [value[k] for k in ['resource_standard', 'resource_provider', 'resource_name'] if value.get(k) is not None]
+
+
+def fmt_resource_operation(value):
+ cmd = []
+ for op in value:
+ cmd.append("op")
+ cmd.append(op.get('operation_action'))
+ for operation_option in op.get('operation_option'):
+ cmd.append(operation_option)
+
+ return cmd
+
+
+def fmt_resource_argument(value):
+ return ['--group' if value['argument_action'] == 'group' else value['argument_action']] + value['argument_option']
+
+
+def pacemaker_runner(module, cli_action, **kwargs):
+ runner = CmdRunner(
+ module,
+ command=['pcs', cli_action],
+ arg_formats=dict(
+ state=cmd_runner_fmt.as_map(_state_map),
+ name=cmd_runner_fmt.as_list(),
+ resource_type=cmd_runner_fmt.as_func(fmt_resource_type),
+ resource_option=cmd_runner_fmt.as_list(),
+ resource_operation=cmd_runner_fmt.as_func(fmt_resource_operation),
+ resource_meta=cmd_runner_fmt.stack(cmd_runner_fmt.as_opt_val)("meta"),
+ resource_argument=cmd_runner_fmt.as_func(fmt_resource_argument),
+ wait=cmd_runner_fmt.as_opt_eq_val("--wait"),
+ ),
+ **kwargs
+ )
+ return runner
diff --git a/plugins/module_utils/pipx.py b/plugins/module_utils/pipx.py
index 75b6621c1b..de43f80b40 100644
--- a/plugins/module_utils/pipx.py
+++ b/plugins/module_utils/pipx.py
@@ -10,7 +10,7 @@ __metaclass__ = type
import json
-from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt as fmt
+from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt
pipx_common_argspec = {
@@ -40,24 +40,25 @@ _state_map = dict(
def pipx_runner(module, command, **kwargs):
arg_formats = dict(
- state=fmt.as_map(_state_map),
- name=fmt.as_list(),
- name_source=fmt.as_func(fmt.unpack_args(lambda n, s: [s] if s else [n])),
- install_apps=fmt.as_bool("--include-apps"),
- install_deps=fmt.as_bool("--include-deps"),
- inject_packages=fmt.as_list(),
- force=fmt.as_bool("--force"),
- include_injected=fmt.as_bool("--include-injected"),
- index_url=fmt.as_opt_val('--index-url'),
- python=fmt.as_opt_val('--python'),
- system_site_packages=fmt.as_bool("--system-site-packages"),
- _list=fmt.as_fixed(['list', '--include-injected', '--json']),
- editable=fmt.as_bool("--editable"),
- pip_args=fmt.as_opt_eq_val('--pip-args'),
- suffix=fmt.as_opt_val('--suffix'),
- spec_metadata=fmt.as_list(),
+ state=cmd_runner_fmt.as_map(_state_map),
+ name=cmd_runner_fmt.as_list(),
+ name_source=cmd_runner_fmt.as_func(cmd_runner_fmt.unpack_args(lambda n, s: [s] if s else [n])),
+ install_apps=cmd_runner_fmt.as_bool("--include-apps"),
+ install_deps=cmd_runner_fmt.as_bool("--include-deps"),
+ inject_packages=cmd_runner_fmt.as_list(),
+ force=cmd_runner_fmt.as_bool("--force"),
+ include_injected=cmd_runner_fmt.as_bool("--include-injected"),
+ index_url=cmd_runner_fmt.as_opt_val('--index-url'),
+ python=cmd_runner_fmt.as_opt_val('--python'),
+ system_site_packages=cmd_runner_fmt.as_bool("--system-site-packages"),
+ _list=cmd_runner_fmt.as_fixed(['list', '--include-injected', '--json']),
+ editable=cmd_runner_fmt.as_bool("--editable"),
+ pip_args=cmd_runner_fmt.as_opt_eq_val('--pip-args'),
+ suffix=cmd_runner_fmt.as_opt_val('--suffix'),
+ spec_metadata=cmd_runner_fmt.as_list(),
+ version=cmd_runner_fmt.as_fixed('--version'),
)
- arg_formats["global"] = fmt.as_bool("--global")
+ arg_formats["global"] = cmd_runner_fmt.as_bool("--global")
runner = CmdRunner(
module,
diff --git a/plugins/module_utils/proxmox.py b/plugins/module_utils/proxmox.py
index 05bf1874b3..bdd575ac26 100644
--- a/plugins/module_utils/proxmox.py
+++ b/plugins/module_utils/proxmox.py
@@ -8,6 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
import traceback
+from time import sleep
PROXMOXER_IMP_ERR = None
try:
@@ -70,6 +71,8 @@ def ansible_to_proxmox_bool(value):
class ProxmoxAnsible(object):
"""Base class for Proxmox modules"""
+ TASK_TIMED_OUT = 'timeout expired'
+
def __init__(self, module):
if not HAS_PROXMOXER:
module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
@@ -141,7 +144,7 @@ class ProxmoxAnsible(object):
return None
self.module.fail_json(msg='No VM with name %s found' % name)
- elif len(vms) > 1:
+ elif len(vms) > 1 and not choose_first_if_multiple:
self.module.fail_json(msg='Multiple VMs with name %s found, provide vmid instead' % name)
return vms[0]
@@ -167,6 +170,41 @@ class ProxmoxAnsible(object):
except Exception as e:
self.module.fail_json(msg='Unable to retrieve API task ID from node %s: %s' % (node, e))
+ def api_task_failed(self, node, taskid):
+ """ Explicitly check if the task stops but exits with a failed status
+ """
+ try:
+ status = self.proxmox_api.nodes(node).tasks(taskid).status.get()
+ return status['status'] == 'stopped' and status['exitstatus'] != 'OK'
+ except Exception as e:
+ self.module.fail_json(msg='Unable to retrieve API task ID from node %s: %s' % (node, e))
+
+ def api_task_complete(self, node_name, task_id, timeout):
+ """Wait until the task stops or times out.
+
+ :param node_name: Proxmox node name where the task is running.
+ :param task_id: ID of the running task.
+ :param timeout: Timeout in seconds to wait for the task to complete.
+ :return: Task completion status (True/False) and ``exitstatus`` message when status=False.
+ """
+ status = {}
+ while timeout:
+ try:
+ status = self.proxmox_api.nodes(node_name).tasks(task_id).status.get()
+ except Exception as e:
+ self.module.fail_json(msg='Unable to retrieve API task ID from node %s: %s' % (node_name, e))
+
+ if status['status'] == 'stopped':
+ if status['exitstatus'] == 'OK':
+ return True, None
+ else:
+ return False, status['exitstatus']
+ else:
+ timeout -= 1
+ if timeout <= 0:
+ return False, ProxmoxAnsible.TASK_TIMED_OUT
+ sleep(1)
+
def get_pool(self, poolid):
"""Retrieve pool information
diff --git a/plugins/module_utils/redfish_utils.py b/plugins/module_utils/redfish_utils.py
index f795eac6cd..f4e8cd5a36 100644
--- a/plugins/module_utils/redfish_utils.py
+++ b/plugins/module_utils/redfish_utils.py
@@ -55,7 +55,6 @@ class RedfishUtils(object):
self.strip_etag_quotes = strip_etag_quotes
self.ciphers = ciphers
self._vendor = None
- self._init_session()
def _auth_params(self, headers):
"""
@@ -120,7 +119,7 @@ class RedfishUtils(object):
# Note: This is also a fallthrough for properties that are
# arrays of objects. Some services erroneously omit properties
- # within arrays of objects when not configured, and it's
+ # within arrays of objects when not configured, and it is
# expecting the client to provide them anyway.
if req_pyld[prop] != cur_pyld[prop]:
@@ -411,7 +410,7 @@ class RedfishUtils(object):
return msg, data
def _init_session(self):
- pass
+ self.module.deprecate("Method _init_session is deprecated and will be removed.", version="11.0.0", collection_name="community.general")
def _get_vendor(self):
# If we got the vendor info once, don't get it again
@@ -1120,7 +1119,8 @@ class RedfishUtils(object):
key = "Actions"
reset_type_values = ['On', 'ForceOff', 'GracefulShutdown',
'GracefulRestart', 'ForceRestart', 'Nmi',
- 'ForceOn', 'PushPowerButton', 'PowerCycle']
+ 'ForceOn', 'PushPowerButton', 'PowerCycle',
+ 'FullPowerCycle']
# command should be PowerOn, PowerForceOff, etc.
if not command.startswith('Power'):
@@ -1178,7 +1178,7 @@ class RedfishUtils(object):
return response
# If requested to wait for the service to be available again, block
- # until it's ready
+ # until it is ready
if wait:
elapsed_time = 0
start_time = time.time()
@@ -1191,7 +1191,7 @@ class RedfishUtils(object):
while elapsed_time <= wait_timeout:
status = self.check_service_availability()
if status['available']:
- # It's available; we're done
+ # It is available; we are done
break
time.sleep(5)
elapsed_time = time.time() - start_time
@@ -1814,7 +1814,7 @@ class RedfishUtils(object):
operation_results['status'] = data.get('TaskState', data.get('JobState'))
operation_results['messages'] = data.get('Messages', [])
else:
- # Error response body, which is a bit of a misnomer since it's used in successful action responses
+ # Error response body, which is a bit of a misnomer since it is used in successful action responses
operation_results['status'] = 'Completed'
if response.status >= 400:
operation_results['status'] = 'Exception'
@@ -1933,6 +1933,9 @@ class RedfishUtils(object):
targets = update_opts.get('update_targets')
apply_time = update_opts.get('update_apply_time')
oem_params = update_opts.get('update_oem_params')
+ custom_oem_header = update_opts.get('update_custom_oem_header')
+ custom_oem_mime_type = update_opts.get('update_custom_oem_mime_type')
+ custom_oem_params = update_opts.get('update_custom_oem_params')
# Ensure the image file is provided
if not image_file:
@@ -1958,7 +1961,7 @@ class RedfishUtils(object):
update_uri = data['MultipartHttpPushUri']
# Assemble the JSON payload portion of the request
- payload = {"@Redfish.OperationApplyTime": "Immediate"}
+ payload = {}
if targets:
payload["Targets"] = targets
if apply_time:
@@ -1969,6 +1972,11 @@ class RedfishUtils(object):
'UpdateParameters': {'content': json.dumps(payload), 'mime_type': 'application/json'},
'UpdateFile': {'filename': image_file, 'content': image_payload, 'mime_type': 'application/octet-stream'}
}
+ if custom_oem_params:
+ multipart_payload[custom_oem_header] = {'content': custom_oem_params}
+ if custom_oem_mime_type:
+ multipart_payload[custom_oem_header]['mime_type'] = custom_oem_mime_type
+
response = self.post_request(self.root_uri + update_uri, multipart_payload, multipart=True)
if response['ret'] is False:
return response
@@ -3609,7 +3617,7 @@ class RedfishUtils(object):
def verify_bios_attributes(self, bios_attributes):
# This method verifies BIOS attributes against the provided input
- server_bios = self.get_multi_bios_attributes()
+ server_bios = self.get_bios_attributes(self.systems_uri)
if server_bios["ret"] is False:
return server_bios
@@ -3618,8 +3626,8 @@ class RedfishUtils(object):
# Verify bios_attributes with BIOS settings available in the server
for key, value in bios_attributes.items():
- if key in server_bios["entries"][0][1]:
- if server_bios["entries"][0][1][key] != value:
+ if key in server_bios["entries"]:
+ if server_bios["entries"][key] != value:
bios_dict.update({key: value})
else:
wrong_param.update({key: value})
@@ -3944,3 +3952,38 @@ class RedfishUtils(object):
"rsp_uri": rsp_uri
}
return res
+
+ def get_accountservice_properties(self):
+ # Find the AccountService resource
+ response = self.get_request(self.root_uri + self.service_root)
+ if response['ret'] is False:
+ return response
+ data = response['data']
+ accountservice_uri = data.get("AccountService", {}).get("@odata.id")
+ if accountservice_uri is None:
+ return {'ret': False, 'msg': "AccountService resource not found"}
+
+ response = self.get_request(self.root_uri + accountservice_uri)
+ if response['ret'] is False:
+ return response
+ return {
+ 'ret': True,
+ 'entries': response['data']
+ }
+
+ def get_power_restore_policy(self, systems_uri):
+ # Retrieve System resource
+ response = self.get_request(self.root_uri + systems_uri)
+ if response['ret'] is False:
+ return response
+ return {
+ 'ret': True,
+ 'entries': response['data']['PowerRestorePolicy']
+ }
+
+ def get_multi_power_restore_policy(self):
+ return self.aggregate_systems(self.get_power_restore_policy)
+
+ def set_power_restore_policy(self, policy):
+ body = {'PowerRestorePolicy': policy}
+ return self.patch_request(self.root_uri + self.systems_uri, body, check_pyld=True)
diff --git a/plugins/module_utils/snap.py b/plugins/module_utils/snap.py
index 253269b9a9..e55a3a13a5 100644
--- a/plugins/module_utils/snap.py
+++ b/plugins/module_utils/snap.py
@@ -41,8 +41,15 @@ def snap_runner(module, **kwargs):
options=cmd_runner_fmt.as_list(),
info=cmd_runner_fmt.as_fixed("info"),
dangerous=cmd_runner_fmt.as_bool("--dangerous"),
+ version=cmd_runner_fmt.as_fixed("version"),
),
check_rc=False,
**kwargs
)
return runner
+
+
+def get_version(runner):
+ with runner("version") as ctx:
+ rc, out, err = ctx.run()
+ return dict(x.split() for x in out.splitlines() if len(x.split()) == 2)
diff --git a/plugins/module_utils/systemd.py b/plugins/module_utils/systemd.py
new file mode 100644
index 0000000000..5d74118d12
--- /dev/null
+++ b/plugins/module_utils/systemd.py
@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2025, Marco Noce
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt
+
+
+def systemd_runner(module, command, **kwargs):
+ arg_formats = dict(
+ version=cmd_runner_fmt.as_fixed("--version"),
+ list_units=cmd_runner_fmt.as_fixed(["list-units", "--no-pager"]),
+ types=cmd_runner_fmt.as_func(lambda v: [] if not v else ["--type", ",".join(v)]),
+ all=cmd_runner_fmt.as_fixed("--all"),
+ plain=cmd_runner_fmt.as_fixed("--plain"),
+ no_legend=cmd_runner_fmt.as_fixed("--no-legend"),
+ show=cmd_runner_fmt.as_fixed("show"),
+ props=cmd_runner_fmt.as_func(lambda v: [] if not v else ["-p", ",".join(v)]),
+ dashdash=cmd_runner_fmt.as_fixed("--"),
+ unit=cmd_runner_fmt.as_list(),
+ )
+
+ runner = CmdRunner(
+ module,
+ command=command,
+ arg_formats=arg_formats,
+ check_rc=True,
+ **kwargs
+ )
+ return runner
diff --git a/plugins/module_utils/xfconf.py b/plugins/module_utils/xfconf.py
index b63518d0c4..344bd1f3c9 100644
--- a/plugins/module_utils/xfconf.py
+++ b/plugins/module_utils/xfconf.py
@@ -7,10 +7,10 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
from ansible.module_utils.parsing.convert_bool import boolean
-from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt as fmt
+from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt
-@fmt.unpack_args
+@cmd_runner_fmt.unpack_args
def _values_fmt(values, value_types):
result = []
for value, value_type in zip(values, value_types):
@@ -25,14 +25,21 @@ def xfconf_runner(module, **kwargs):
module,
command='xfconf-query',
arg_formats=dict(
- channel=fmt.as_opt_val("--channel"),
- property=fmt.as_opt_val("--property"),
- force_array=fmt.as_bool("--force-array"),
- reset=fmt.as_bool("--reset"),
- create=fmt.as_bool("--create"),
- list_arg=fmt.as_bool("--list"),
- values_and_types=fmt.as_func(_values_fmt),
+ channel=cmd_runner_fmt.as_opt_val("--channel"),
+ property=cmd_runner_fmt.as_opt_val("--property"),
+ force_array=cmd_runner_fmt.as_bool("--force-array"),
+ reset=cmd_runner_fmt.as_bool("--reset"),
+ create=cmd_runner_fmt.as_bool("--create"),
+ list_arg=cmd_runner_fmt.as_bool("--list"),
+ values_and_types=_values_fmt,
+ version=cmd_runner_fmt.as_fixed("--version"),
),
**kwargs
)
return runner
+
+
+def get_xfconf_version(runner):
+ with runner("version") as ctx:
+ rc, out, err = ctx.run()
+ return out.splitlines()[0].split()[1]
diff --git a/plugins/modules/aerospike_migrations.py b/plugins/modules/aerospike_migrations.py
index 1eee5b1a2f..9a6084a6a1 100644
--- a/plugins/modules/aerospike_migrations.py
+++ b/plugins/modules/aerospike_migrations.py
@@ -9,15 +9,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: aerospike_migrations
short_description: Check or wait for migrations between nodes
description:
- - This can be used to check for migrations in a cluster.
- This makes it easy to do a rolling upgrade/update on Aerospike nodes.
- - If waiting for migrations is not desired, simply just poll until
- port 3000 if available or asinfo -v status returns ok
+ - This can be used to check for migrations in a cluster. This makes it easy to do a rolling upgrade/update on Aerospike
+ nodes.
+ - If waiting for migrations is not desired, simply just poll until port 3000 if available or C(asinfo -v status) returns
+ ok.
author: "Albert Autin (@Alb0t)"
extends_documentation_fragment:
- community.general.attributes
@@ -27,92 +26,84 @@ attributes:
diff_mode:
support: none
options:
- host:
- description:
- - Which host do we use as seed for info connection
- required: false
- type: str
- default: localhost
- port:
- description:
- - Which port to connect to Aerospike on (service port)
- required: false
- type: int
- default: 3000
- connect_timeout:
- description:
- - How long to try to connect before giving up (milliseconds)
- required: false
- type: int
- default: 1000
- consecutive_good_checks:
- description:
- - How many times should the cluster report "no migrations"
- consecutively before returning OK back to ansible?
- required: false
- type: int
- default: 3
- sleep_between_checks:
- description:
- - How long to sleep between each check (seconds).
- required: false
- type: int
- default: 60
- tries_limit:
- description:
- - How many times do we poll before giving up and failing?
- default: 300
- required: false
- type: int
- local_only:
- description:
- - Do you wish to only check for migrations on the local node
- before returning, or do you want all nodes in the cluster
- to finish before returning?
- required: true
- type: bool
- min_cluster_size:
- description:
- - Check will return bad until cluster size is met
- or until tries is exhausted
- required: false
- type: int
- default: 1
- fail_on_cluster_change:
- description:
- - Fail if the cluster key changes
- if something else is changing the cluster, we may want to fail
- required: false
- type: bool
- default: true
- migrate_tx_key:
- description:
- - The metric key used to determine if we have tx migrations
- remaining. Changeable due to backwards compatibility.
- required: false
- type: str
- default: migrate_tx_partitions_remaining
- migrate_rx_key:
- description:
- - The metric key used to determine if we have rx migrations
- remaining. Changeable due to backwards compatibility.
- required: false
- type: str
- default: migrate_rx_partitions_remaining
- target_cluster_size:
- description:
- - When all aerospike builds in the cluster are greater than
- version 4.3, then the C(cluster-stable) info command will be used.
- Inside this command, you can optionally specify what the target
- cluster size is - but it is not necessary. You can still rely on
- min_cluster_size if you don't want to use this option.
- - If this option is specified on a cluster that has at least 1
- host <4.3 then it will be ignored until the min version reaches
- 4.3.
- required: false
- type: int
-'''
-EXAMPLES = '''
+ host:
+ description:
+ - Which host do we use as seed for info connection.
+ required: false
+ type: str
+ default: localhost
+ port:
+ description:
+ - Which port to connect to Aerospike on (service port).
+ required: false
+ type: int
+ default: 3000
+ connect_timeout:
+ description:
+ - How long to try to connect before giving up (milliseconds).
+ required: false
+ type: int
+ default: 1000
+ consecutive_good_checks:
+ description:
+ - How many times should the cluster report "no migrations" consecutively before returning OK back to ansible?
+ required: false
+ type: int
+ default: 3
+ sleep_between_checks:
+ description:
+ - How long to sleep between each check (seconds).
+ required: false
+ type: int
+ default: 60
+ tries_limit:
+ description:
+ - How many times do we poll before giving up and failing?
+ default: 300
+ required: false
+ type: int
+ local_only:
+ description:
+ - Do you wish to only check for migrations on the local node before returning, or do you want all nodes in the cluster
+ to finish before returning?
+ required: true
+ type: bool
+ min_cluster_size:
+ description:
+ - Check will return bad until cluster size is met or until tries is exhausted.
+ required: false
+ type: int
+ default: 1
+ fail_on_cluster_change:
+ description:
+ - Fail if the cluster key changes if something else is changing the cluster, we may want to fail.
+ required: false
+ type: bool
+ default: true
+ migrate_tx_key:
+ description:
+ - The metric key used to determine if we have tx migrations remaining. Changeable due to backwards compatibility.
+ required: false
+ type: str
+ default: migrate_tx_partitions_remaining
+ migrate_rx_key:
+ description:
+ - The metric key used to determine if we have rx migrations remaining. Changeable due to backwards compatibility.
+ required: false
+ type: str
+ default: migrate_rx_partitions_remaining
+ target_cluster_size:
+ description:
+ - When all aerospike builds in the cluster are greater than version 4.3, then the C(cluster-stable) info command will
+ be used. Inside this command, you can optionally specify what the target cluster size is - but it is not necessary.
+ You can still rely on O(min_cluster_size) if you do not want to use this option.
+ - If this option is specified on a cluster that has at least one host <4.3 then it will be ignored until the min version
+ reaches 4.3.
+ required: false
+ type: int
+"""
+
+EXAMPLES = r"""
# check for migrations on local node
- name: Wait for migrations on local node before proceeding
community.general.aerospike_migrations:
@@ -132,13 +123,13 @@ EXAMPLES = '''
- name: Install dependencies
ansible.builtin.apt:
name:
- - python
- - python-pip
- - python-setuptools
+ - python
+ - python-pip
+ - python-setuptools
state: latest
- name: Setup aerospike
ansible.builtin.pip:
- name: aerospike
+ name: aerospike
# check for migrations every (sleep_between_checks)
# If at least (consecutive_good_checks) checks come back OK in a row, then return OK.
# Will exit if any exception, which can be caused by bad nodes,
@@ -147,13 +138,13 @@ EXAMPLES = '''
# Tries Limit * Sleep Between Checks * delay * retries
- name: Wait for aerospike migrations
community.general.aerospike_migrations:
- local_only: true
- sleep_between_checks: 1
- tries_limit: 5
- consecutive_good_checks: 3
- fail_on_cluster_change: true
- min_cluster_size: 3
- target_cluster_size: 4
+ local_only: true
+ sleep_between_checks: 1
+ tries_limit: 5
+ consecutive_good_checks: 3
+ fail_on_cluster_change: true
+ min_cluster_size: 3
+ target_cluster_size: 4
register: migrations_check
until: migrations_check is succeeded
changed_when: false
@@ -161,14 +152,14 @@ EXAMPLES = '''
retries: 120
- name: Another thing
ansible.builtin.shell: |
- echo foo
+ echo foo
- name: Reboot
ansible.builtin.reboot:
-'''
+"""
-RETURN = '''
+RETURN = r"""
# Returns only a success/failure result. Changed is always false.
-'''
+"""
import traceback
diff --git a/plugins/modules/airbrake_deployment.py b/plugins/modules/airbrake_deployment.py
index bad1b2c9d4..d772062da4 100644
--- a/plugins/modules/airbrake_deployment.py
+++ b/plugins/modules/airbrake_deployment.py
@@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: airbrake_deployment
author:
-- "Bruce Pennypacker (@bpennypacker)"
-- "Patrick Humpal (@phumpal)"
+ - "Bruce Pennypacker (@bpennypacker)"
+ - "Patrick Humpal (@phumpal)"
short_description: Notify airbrake about app deployments
description:
- - Notify airbrake about app deployments (see U(https://airbrake.io/docs/api/#deploys-v4)).
+ - Notify airbrake about app deployments (see U(https://airbrake.io/docs/api/#deploys-v4)).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -28,7 +27,7 @@ attributes:
options:
project_id:
description:
- - Airbrake PROJECT_ID
+ - Airbrake PROJECT_ID.
required: true
type: str
version_added: '0.2.0'
@@ -40,27 +39,27 @@ options:
version_added: '0.2.0'
environment:
description:
- - The airbrake environment name, typically 'production', 'staging', etc.
+ - The airbrake environment name, typically v(production), V(staging), and so on.
required: true
type: str
user:
description:
- - The username of the person doing the deployment
+ - The username of the person doing the deployment.
required: false
type: str
repo:
description:
- - URL of the project repository
+ - URL of the project repository.
required: false
type: str
revision:
description:
- - A hash, number, tag, or other identifier showing what revision from version control was deployed
+ - A hash, number, tag, or other identifier showing what revision from version control was deployed.
required: false
type: str
version:
description:
- - A string identifying what version was deployed
+ - A string identifying what version was deployed.
required: false
type: str
version_added: '1.0.0'
@@ -72,16 +71,16 @@ options:
type: str
validate_certs:
description:
- - If V(false), SSL certificates for the target url will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates for the target URL will not be validated. This should only be used on personally controlled
+ sites using self-signed certificates.
required: false
default: true
type: bool
requirements: []
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Notify airbrake about an app deployment
community.general.airbrake_deployment:
project_id: '12345'
@@ -98,7 +97,7 @@ EXAMPLES = '''
user: ansible
revision: 'e54dd3a01f2c421b558ef33b5f79db936e2dcf15'
version: '0.2.0'
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url
diff --git a/plugins/modules/aix_devices.py b/plugins/modules/aix_devices.py
index a0f3cf48d9..68dbfb72d2 100644
--- a/plugins/modules/aix_devices.py
+++ b/plugins/modules/aix_devices.py
@@ -8,14 +8,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
-- Kairo Araujo (@kairoaraujo)
+ - Kairo Araujo (@kairoaraujo)
module: aix_devices
short_description: Manages AIX devices
description:
-- This module discovers, defines, removes and modifies attributes of AIX devices.
+ - This module discovers, defines, removes and modifies attributes of AIX devices.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -26,35 +25,35 @@ attributes:
options:
attributes:
description:
- - A list of device attributes.
+ - A list of device attributes.
type: dict
device:
description:
- - The name of the device.
- - V(all) is valid to rescan C(available) all devices (AIX cfgmgr command).
+ - The name of the device.
+ - V(all) is valid to rescan C(available) all devices (AIX C(cfgmgr) command).
type: str
force:
description:
- - Forces action.
+ - Forces action.
type: bool
default: false
recursive:
description:
- - Removes or defines a device and children devices.
+ - Removes or defines a device and children devices.
type: bool
default: false
state:
description:
- - Controls the device state.
- - V(available) (alias V(present)) rescan a specific device or all devices (when O(device) is not specified).
- - V(removed) (alias V(absent) removes a device.
- - V(defined) changes device to Defined state.
+ - Controls the device state.
+ - V(available) (alias V(present)) rescan a specific device or all devices (when O(device) is not specified).
+ - V(removed) (alias V(absent) removes a device.
+ - V(defined) changes device to Defined state.
type: str
- choices: [ available, defined, removed ]
+ choices: [available, defined, removed]
default: available
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Scan new devices
community.general.aix_devices:
device: all
@@ -126,9 +125,9 @@ EXAMPLES = r'''
attributes:
alias4: 10.0.0.100,255.255.255.0
state: available
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/aix_filesystem.py b/plugins/modules/aix_filesystem.py
index 4a3775c672..8934d583ff 100644
--- a/plugins/modules/aix_filesystem.py
+++ b/plugins/modules/aix_filesystem.py
@@ -9,15 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
- Kairo Araujo (@kairoaraujo)
module: aix_filesystem
short_description: Configure LVM and NFS file systems for AIX
description:
- - This module creates, removes, mount and unmount LVM and NFS file system for
- AIX using C(/etc/filesystems).
+ - This module creates, removes, mount and unmount LVM and NFS file system for AIX using C(/etc/filesystems).
- For LVM file systems is possible to resize a file system.
extends_documentation_fragment:
- community.general.attributes
@@ -60,7 +58,7 @@ options:
description:
- Set file system permissions. V(rw) (read-write) or V(ro) (read-only).
type: str
- choices: [ ro, rw ]
+ choices: [ro, rw]
default: rw
mount_group:
description:
@@ -84,9 +82,8 @@ options:
description:
- Specifies the file system size.
- For already V(present) it will be resized.
- - 512-byte blocks, Megabytes or Gigabytes. If the value has M specified
- it will be in Megabytes. If the value has G specified it will be in
- Gigabytes.
+ - 512-byte blocks, Megabytes or Gigabytes. If the value has M specified it will be in Megabytes. If the value has G
+ specified it will be in Gigabytes.
- If no M or G the value will be 512-byte blocks.
- If "+" is specified in begin of value, the value will be added.
- If "-" is specified in begin of value, the value will be removed.
@@ -101,7 +98,7 @@ options:
- V(mounted) checks if the file system is mounted or mount the file system.
- V(unmounted) check if the file system is unmounted or unmount the file system.
type: str
- choices: [ absent, mounted, present, unmounted ]
+ choices: [absent, mounted, present, unmounted]
default: present
vg:
description:
@@ -109,9 +106,9 @@ options:
type: str
notes:
- For more O(attributes), please check "crfs" AIX manual.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create filesystem in a previously defined logical volume.
community.general.aix_filesystem:
device: testlv
@@ -166,9 +163,9 @@ EXAMPLES = r'''
filesystem: /newfs
rm_mount_point: true
state: absent
-'''
+"""
-RETURN = r'''
+RETURN = r"""
changed:
description: Return changed for aix_filesystems actions as true or false.
returned: always
@@ -177,7 +174,7 @@ msg:
description: Return message regarding the action.
returned: always
type: str
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils._mount import ismount
diff --git a/plugins/modules/aix_inittab.py b/plugins/modules/aix_inittab.py
index 79336bab8d..0c32f91e7f 100644
--- a/plugins/modules/aix_inittab.py
+++ b/plugins/modules/aix_inittab.py
@@ -8,16 +8,15 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
- - Joris Weijters (@molekuul)
+ - Joris Weijters (@molekuul)
module: aix_inittab
-short_description: Manages the inittab on AIX
+short_description: Manages the C(inittab) on AIX
description:
- - Manages the inittab on AIX.
+ - Manages the C(inittab) on AIX.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -26,56 +25,56 @@ attributes:
options:
name:
description:
- - Name of the inittab entry.
+ - Name of the C(inittab) entry.
type: str
required: true
- aliases: [ service ]
+ aliases: [service]
runlevel:
description:
- - Runlevel of the entry.
+ - Runlevel of the entry.
type: str
required: true
action:
description:
- - Action what the init has to do with this entry.
+ - Action what the init has to do with this entry.
type: str
choices:
- - boot
- - bootwait
- - hold
- - initdefault
- - 'off'
- - once
- - ondemand
- - powerfail
- - powerwait
- - respawn
- - sysinit
- - wait
+ - boot
+ - bootwait
+ - hold
+ - initdefault
+ - 'off'
+ - once
+ - ondemand
+ - powerfail
+ - powerwait
+ - respawn
+ - sysinit
+ - wait
command:
description:
- - What command has to run.
+ - What command has to run.
type: str
required: true
insertafter:
description:
- - After which inittabline should the new entry inserted.
+ - After which inittabline should the new entry inserted.
type: str
state:
description:
- - Whether the entry should be present or absent in the inittab file.
+ - Whether the entry should be present or absent in the inittab file.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
notes:
- The changes are persistent across reboots.
- You need root rights to read or adjust the inittab with the C(lsitab), C(chitab), C(mkitab) or C(rmitab) commands.
- Tested on AIX 7.1.
requirements:
-- itertools
-'''
+ - itertools
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Add service startmyservice to the inittab, directly after service existingservice.
- name: Add startmyservice to inittab
community.general.aix_inittab:
@@ -105,25 +104,25 @@ EXAMPLES = '''
command: echo hello
state: absent
become: true
-'''
+"""
-RETURN = '''
+RETURN = r"""
name:
- description: Name of the adjusted inittab entry
- returned: always
- type: str
- sample: startmyservice
+ description: Name of the adjusted C(inittab) entry.
+ returned: always
+ type: str
+ sample: startmyservice
msg:
- description: Action done with the inittab entry
- returned: changed
- type: str
- sample: changed inittab entry startmyservice
+ description: Action done with the C(inittab) entry.
+ returned: changed
+ type: str
+ sample: changed inittab entry startmyservice
changed:
- description: Whether the inittab changed or not
- returned: always
- type: bool
- sample: true
-'''
+ description: Whether the C(inittab) changed or not.
+ returned: always
+ type: bool
+ sample: true
+"""
# Import necessary libraries
try:
diff --git a/plugins/modules/aix_lvg.py b/plugins/modules/aix_lvg.py
index 2892a68ad9..29c0b7d3f9 100644
--- a/plugins/modules/aix_lvg.py
+++ b/plugins/modules/aix_lvg.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
- Kairo Araujo (@kairoaraujo)
module: aix_lvg
@@ -26,43 +25,43 @@ attributes:
options:
force:
description:
- - Force volume group creation.
+ - Force volume group creation.
type: bool
default: false
pp_size:
description:
- - The size of the physical partition in megabytes.
+ - The size of the physical partition in megabytes.
type: int
pvs:
description:
- - List of comma-separated devices to use as physical devices in this volume group.
- - Required when creating or extending (V(present) state) the volume group.
- - If not informed reducing (V(absent) state) the volume group will be removed.
+ - List of comma-separated devices to use as physical devices in this volume group.
+ - Required when creating or extending (V(present) state) the volume group.
+ - If not informed reducing (V(absent) state) the volume group will be removed.
type: list
elements: str
state:
description:
- - Control if the volume group exists and volume group AIX state varyonvg V(varyon) or varyoffvg V(varyoff).
+ - Control if the volume group exists and volume group AIX state varyonvg V(varyon) or varyoffvg V(varyoff).
type: str
- choices: [ absent, present, varyoff, varyon ]
+ choices: [absent, present, varyoff, varyon]
default: present
vg:
description:
- - The name of the volume group.
+ - The name of the volume group.
type: str
required: true
vg_type:
description:
- - The type of the volume group.
+ - The type of the volume group.
type: str
- choices: [ big, normal, scalable ]
+ choices: [big, normal, scalable]
default: normal
notes:
-- AIX will permit remove VG only if all LV/Filesystems are not busy.
-- Module does not modify PP size for already present volume group.
-'''
+ - AIX will permit remove VG only if all LV/Filesystems are not busy.
+ - Module does not modify PP size for already present volume group.
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a volume group datavg
community.general.aix_lvg:
vg: datavg
@@ -86,9 +85,9 @@ EXAMPLES = r'''
vg: rootvg
pvs: hdisk1
state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/aix_lvol.py b/plugins/modules/aix_lvol.py
index 7d0fb1ee09..5e34d0697b 100644
--- a/plugins/modules/aix_lvol.py
+++ b/plugins/modules/aix_lvol.py
@@ -9,10 +9,9 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
- - Alain Dejoux (@adejoux)
+ - Alain Dejoux (@adejoux)
module: aix_lvol
short_description: Configure AIX LVM logical volumes
description:
@@ -27,58 +26,58 @@ attributes:
options:
vg:
description:
- - The volume group this logical volume is part of.
+ - The volume group this logical volume is part of.
type: str
required: true
lv:
description:
- - The name of the logical volume.
+ - The name of the logical volume.
type: str
required: true
lv_type:
description:
- - The type of the logical volume.
+ - The type of the logical volume.
type: str
default: jfs2
size:
description:
- - The size of the logical volume with one of the [MGT] units.
+ - The size of the logical volume with one of the [MGT] units.
type: str
copies:
description:
- - The number of copies of the logical volume.
- - Maximum copies are 3.
+ - The number of copies of the logical volume.
+ - Maximum copies are 3.
type: int
default: 1
policy:
description:
- - Sets the interphysical volume allocation policy.
- - V(maximum) allocates logical partitions across the maximum number of physical volumes.
- - V(minimum) allocates logical partitions across the minimum number of physical volumes.
+ - Sets the interphysical volume allocation policy.
+ - V(maximum) allocates logical partitions across the maximum number of physical volumes.
+ - V(minimum) allocates logical partitions across the minimum number of physical volumes.
type: str
- choices: [ maximum, minimum ]
+ choices: [maximum, minimum]
default: maximum
state:
description:
- - Control if the logical volume exists. If V(present) and the
- volume does not already exist then the O(size) option is required.
+ - Control if the logical volume exists. If V(present) and the volume does not already exist then the O(size) option
+ is required.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
opts:
description:
- - Free-form options to be passed to the mklv command.
+ - Free-form options to be passed to the mklv command.
type: str
default: ''
pvs:
description:
- - A list of physical volumes, for example V(hdisk1,hdisk2).
+ - A list of physical volumes, for example V(hdisk1,hdisk2).
type: list
elements: str
default: []
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a logical volume of 512M
community.general.aix_lvol:
vg: testvg
@@ -90,7 +89,7 @@ EXAMPLES = r'''
vg: testvg
lv: test2lv
size: 512M
- pvs: [ hdisk1, hdisk2 ]
+ pvs: [hdisk1, hdisk2]
- name: Create a logical volume of 512M mirrored
community.general.aix_lvol:
@@ -124,15 +123,15 @@ EXAMPLES = r'''
vg: testvg
lv: testlv
state: absent
-'''
+"""
-RETURN = r'''
+RETURN = r"""
msg:
type: str
description: A friendly message describing the task result.
returned: always
sample: Logical volume testlv created.
-'''
+"""
import re
diff --git a/plugins/modules/alerta_customer.py b/plugins/modules/alerta_customer.py
index 5e1a5f86c4..fc5ce32d5c 100644
--- a/plugins/modules/alerta_customer.py
+++ b/plugins/modules/alerta_customer.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: alerta_customer
short_description: Manage customers in Alerta
version_added: 4.8.0
@@ -18,7 +17,7 @@ description:
author: Christian Wollinger (@cwollinger)
seealso:
- name: API documentation
- description: Documentation for Alerta API
+ description: Documentation for Alerta API.
link: https://docs.alerta.io/api/reference.html#customers
extends_documentation_fragment:
- community.general.attributes
@@ -60,11 +59,11 @@ options:
- Whether the customer should exist or not.
- Both O(customer) and O(match) identify a customer that should be added or removed.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create customer
community.general.alerta_customer:
alerta_url: https://alerta.example.com
@@ -83,7 +82,7 @@ EXAMPLES = """
state: absent
"""
-RETURN = """
+RETURN = r"""
msg:
description:
- Success or failure message.
diff --git a/plugins/modules/ali_instance.py b/plugins/modules/ali_instance.py
index 087dc64b6d..1a66850e14 100644
--- a/plugins/modules/ali_instance.py
+++ b/plugins/modules/ali_instance.py
@@ -24,243 +24,240 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ali_instance
-short_description: Create, Start, Stop, Restart or Terminate an Instance in ECS; Add or Remove Instance to/from a Security Group
+short_description: Create, Start, Stop, Restart or Terminate an Instance in ECS; Add or Remove Instance to/from a Security
+ Group
description:
- - Create, start, stop, restart, modify or terminate ecs instances.
- - Add or remove ecs instances to/from security group.
+ - Create, start, stop, restart, modify or terminate ECS instances.
+ - Add or remove ecs instances to/from security group.
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- description:
- - The state of the instance after operating.
- default: 'present'
- choices: ['present', 'running', 'stopped', 'restarted', 'absent']
- type: str
- availability_zone:
- description:
- - Aliyun availability zone ID in which to launch the instance.
- If it is not specified, it will be allocated by system automatically.
- aliases: ['alicloud_zone', 'zone_id']
- type: str
- image_id:
- description:
- - Image ID used to launch instances. Required when O(state=present) and creating new ECS instances.
- aliases: ['image']
- type: str
- instance_type:
- description:
- - Instance type used to launch instances. Required when O(state=present) and creating new ECS instances.
- aliases: ['type']
- type: str
- security_groups:
- description:
- - A list of security group IDs.
- aliases: ['group_ids']
- type: list
- elements: str
- vswitch_id:
- description:
- - The subnet ID in which to launch the instances (VPC).
- aliases: ['subnet_id']
- type: str
- instance_name:
- description:
- - The name of ECS instance, which is a string of 2 to 128 Chinese or English characters. It must begin with an
- uppercase/lowercase letter or a Chinese character and can contain numerals, ".", "_" or "-".
- It cannot begin with http:// or https://.
- aliases: ['name']
- type: str
+ state:
description:
- description:
- - The description of ECS instance, which is a string of 2 to 256 characters. It cannot begin with http:// or https://.
- type: str
- internet_charge_type:
- description:
- - Internet charge type of ECS instance.
- default: 'PayByBandwidth'
- choices: ['PayByBandwidth', 'PayByTraffic']
- type: str
- max_bandwidth_in:
- description:
- - Maximum incoming bandwidth from the public network, measured in Mbps (Megabits per second).
- default: 200
- type: int
- max_bandwidth_out:
- description:
- - Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second).
- Required when O(allocate_public_ip=true). Ignored when O(allocate_public_ip=false).
- default: 0
- type: int
- host_name:
- description:
- - Instance host name. Ordered hostname is not supported.
- type: str
- unique_suffix:
- description:
- - Specifies whether to add sequential suffixes to the host_name.
- The sequential suffix ranges from 001 to 999.
- default: false
- type: bool
- version_added: '0.2.0'
- password:
- description:
- - The password to login instance. After rebooting instances, modified password will take effect.
- type: str
- system_disk_category:
- description:
- - Category of the system disk.
- default: 'cloud_efficiency'
- choices: ['cloud_efficiency', 'cloud_ssd']
- type: str
- system_disk_size:
- description:
- - Size of the system disk, in GB. The valid values are 40~500.
- default: 40
- type: int
- system_disk_name:
- description:
- - Name of the system disk.
- type: str
- system_disk_description:
- description:
- - Description of the system disk.
- type: str
- count:
- description:
- - The number of the new instance. An integer value which indicates how many instances that match O(count_tag)
- should be running. Instances are either created or terminated based on this value.
- default: 1
- type: int
- count_tag:
- description:
- - O(count) determines how many instances based on a specific tag criteria should be present.
- This can be expressed in multiple ways and is shown in the EXAMPLES section.
- The specified count_tag must already exist or be passed in as the O(tags) option.
- If it is not specified, it will be replaced by O(instance_name).
- type: str
- allocate_public_ip:
- description:
- - Whether allocate a public ip for the new instance.
- default: false
- aliases: [ 'assign_public_ip' ]
- type: bool
- instance_charge_type:
- description:
- - The charge type of the instance.
- choices: ['PrePaid', 'PostPaid']
- default: 'PostPaid'
- type: str
- period:
- description:
- - The charge duration of the instance, in months. Required when O(instance_charge_type=PrePaid).
- - The valid value are [1-9, 12, 24, 36].
- default: 1
- type: int
- auto_renew:
- description:
- - Whether automate renew the charge of the instance.
- type: bool
- default: false
- auto_renew_period:
- description:
- - The duration of the automatic renew the charge of the instance. Required when O(auto_renew=true).
- choices: [1, 2, 3, 6, 12]
- type: int
- instance_ids:
- description:
- - A list of instance ids. It is required when need to operate existing instances.
- If it is specified, O(count) will lose efficacy.
- type: list
- elements: str
- force:
- description:
- - Whether the current operation needs to be execute forcibly.
- default: false
- type: bool
- tags:
- description:
- - A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. V({"key":"value"})
- aliases: ["instance_tags"]
- type: dict
- version_added: '0.2.0'
- purge_tags:
- description:
- - Delete any tags not specified in the task that are on the instance.
- If True, it means you have to specify all the desired tags on each task affecting an instance.
- default: false
- type: bool
- version_added: '0.2.0'
- key_name:
- description:
- - The name of key pair which is used to access ECS instance in SSH.
- required: false
- type: str
- aliases: ['keypair']
- user_data:
- description:
- - User-defined data to customize the startup behaviors of an ECS instance and to pass data into an ECS instance.
- It only will take effect when launching the new ECS instances.
- required: false
- type: str
- ram_role_name:
- description:
- - The name of the instance RAM role.
- type: str
- version_added: '0.2.0'
- spot_price_limit:
- description:
- - The maximum hourly price for the preemptible instance. This parameter supports a maximum of three decimal
- places and takes effect when the SpotStrategy parameter is set to SpotWithPriceLimit.
- type: float
- version_added: '0.2.0'
- spot_strategy:
- description:
- - The bidding mode of the pay-as-you-go instance. This parameter is valid when InstanceChargeType is set to PostPaid.
- choices: ['NoSpot', 'SpotWithPriceLimit', 'SpotAsPriceGo']
- default: 'NoSpot'
- type: str
- version_added: '0.2.0'
- period_unit:
- description:
- - The duration unit that you will buy the resource. It is valid when O(instance_charge_type=PrePaid).
- choices: ['Month', 'Week']
- default: 'Month'
- type: str
- version_added: '0.2.0'
- dry_run:
- description:
- - Specifies whether to send a dry-run request.
- - If O(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the
- required parameters are set, and validates the request format, service permissions, and available ECS instances.
- If the validation fails, the corresponding error code is returned. If the validation succeeds, the DryRunOperation error code is returned.
- - If O(dry_run=false), A request is sent. If the validation succeeds, the instance is created.
- default: false
- type: bool
- version_added: '0.2.0'
- include_data_disks:
- description:
- - Whether to change instance disks charge type when changing instance charge type.
- default: true
- type: bool
- version_added: '0.2.0'
+ - The state of the instance after operating.
+ default: 'present'
+ choices: ['present', 'running', 'stopped', 'restarted', 'absent']
+ type: str
+ availability_zone:
+ description:
+ - Aliyun availability zone ID in which to launch the instance. If it is not specified, it will be allocated by system
+ automatically.
+ aliases: ['alicloud_zone', 'zone_id']
+ type: str
+ image_id:
+ description:
+ - Image ID used to launch instances. Required when O(state=present) and creating new ECS instances.
+ aliases: ['image']
+ type: str
+ instance_type:
+ description:
+ - Instance type used to launch instances. Required when O(state=present) and creating new ECS instances.
+ aliases: ['type']
+ type: str
+ security_groups:
+ description:
+ - A list of security group IDs.
+ aliases: ['group_ids']
+ type: list
+ elements: str
+ vswitch_id:
+ description:
+ - The subnet ID in which to launch the instances (VPC).
+ aliases: ['subnet_id']
+ type: str
+ instance_name:
+ description:
+ - The name of ECS instance, which is a string of 2 to 128 Chinese or English characters. It must begin with an uppercase/lowercase
+ letter or a Chinese character and can contain numerals, V(.), V(_) or V(-). It cannot begin with V(http://) or V(https://).
+ aliases: ['name']
+ type: str
+ description:
+ description:
+ - The description of ECS instance, which is a string of 2 to 256 characters. It cannot begin with V(http://) or V(https://).
+ type: str
+ internet_charge_type:
+ description:
+ - Internet charge type of ECS instance.
+ default: 'PayByBandwidth'
+ choices: ['PayByBandwidth', 'PayByTraffic']
+ type: str
+ max_bandwidth_in:
+ description:
+ - Maximum incoming bandwidth from the public network, measured in Mbps (Megabits per second).
+ default: 200
+ type: int
+ max_bandwidth_out:
+ description:
+ - Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second). Required when O(allocate_public_ip=true).
+ Ignored when O(allocate_public_ip=false).
+ default: 0
+ type: int
+ host_name:
+ description:
+ - Instance host name. Ordered hostname is not supported.
+ type: str
+ unique_suffix:
+ description:
+ - Specifies whether to add sequential suffixes to the host_name. The sequential suffix ranges from 001 to 999.
+ default: false
+ type: bool
+ version_added: '0.2.0'
+ password:
+ description:
+ - The password to login instance. After rebooting instances, modified password will take effect.
+ type: str
+ system_disk_category:
+ description:
+ - Category of the system disk.
+ default: 'cloud_efficiency'
+ choices: ['cloud_efficiency', 'cloud_ssd']
+ type: str
+ system_disk_size:
+ description:
+ - Size of the system disk, in GB. The valid values are V(40)~V(500).
+ default: 40
+ type: int
+ system_disk_name:
+ description:
+ - Name of the system disk.
+ type: str
+ system_disk_description:
+ description:
+ - Description of the system disk.
+ type: str
+ count:
+ description:
+ - The number of the new instance. An integer value which indicates how many instances that match O(count_tag) should
+ be running. Instances are either created or terminated based on this value.
+ default: 1
+ type: int
+ count_tag:
+ description:
+ - O(count) determines how many instances based on a specific tag criteria should be present. This can be expressed in
+ multiple ways and is shown in the EXAMPLES section. The specified count_tag must already exist or be passed in as
+ the O(tags) option. If it is not specified, it will be replaced by O(instance_name).
+ type: str
+ allocate_public_ip:
+ description:
+ - Whether allocate a public IP for the new instance.
+ default: false
+ aliases: ['assign_public_ip']
+ type: bool
+ instance_charge_type:
+ description:
+ - The charge type of the instance.
+ choices: ['PrePaid', 'PostPaid']
+ default: 'PostPaid'
+ type: str
+ period:
+ description:
+ - The charge duration of the instance, in months. Required when O(instance_charge_type=PrePaid).
+ - The valid value are [V(1-9), V(12), V(24), V(36)].
+ default: 1
+ type: int
+ auto_renew:
+ description:
+ - Whether automate renew the charge of the instance.
+ type: bool
+ default: false
+ auto_renew_period:
+ description:
+ - The duration of the automatic renew the charge of the instance. Required when O(auto_renew=true).
+ choices: [1, 2, 3, 6, 12]
+ type: int
+ instance_ids:
+ description:
+ - A list of instance IDs. It is required when need to operate existing instances. If it is specified, O(count) will
+ lose efficacy.
+ type: list
+ elements: str
+ force:
+ description:
+ - Whether the current operation needs to be execute forcibly.
+ default: false
+ type: bool
+ tags:
+ description:
+ - A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. V({"key":"value"}).
+ aliases: ["instance_tags"]
+ type: dict
+ version_added: '0.2.0'
+ purge_tags:
+ description:
+ - Delete any tags not specified in the task that are on the instance. If V(true), it means you have to specify all the
+ desired tags on each task affecting an instance.
+ default: false
+ type: bool
+ version_added: '0.2.0'
+ key_name:
+ description:
+ - The name of key pair which is used to access ECS instance in SSH.
+ required: false
+ type: str
+ aliases: ['keypair']
+ user_data:
+ description:
+ - User-defined data to customize the startup behaviors of an ECS instance and to pass data into an ECS instance. It
+ only will take effect when launching the new ECS instances.
+ required: false
+ type: str
+ ram_role_name:
+ description:
+ - The name of the instance RAM role.
+ type: str
+ version_added: '0.2.0'
+ spot_price_limit:
+ description:
+ - The maximum hourly price for the preemptible instance. This parameter supports a maximum of three decimal places and
+ takes effect when the SpotStrategy parameter is set to SpotWithPriceLimit.
+ type: float
+ version_added: '0.2.0'
+ spot_strategy:
+ description:
+ - The bidding mode of the pay-as-you-go instance. This parameter is valid when O(instance_charge_type=PostPaid).
+ choices: ['NoSpot', 'SpotWithPriceLimit', 'SpotAsPriceGo']
+ default: 'NoSpot'
+ type: str
+ version_added: '0.2.0'
+ period_unit:
+ description:
+ - The duration unit that you will buy the resource. It is valid when O(instance_charge_type=PrePaid).
+ choices: ['Month', 'Week']
+ default: 'Month'
+ type: str
+ version_added: '0.2.0'
+ dry_run:
+ description:
+ - Specifies whether to send a dry-run request.
+ - If O(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the required
+ parameters are set, and validates the request format, service permissions, and available ECS instances. If the validation
+ fails, the corresponding error code is returned. If the validation succeeds, the DryRunOperation error code is returned.
+ - If O(dry_run=false), a request is sent. If the validation succeeds, the instance is created.
+ default: false
+ type: bool
+ version_added: '0.2.0'
+ include_data_disks:
+ description:
+ - Whether to change instance disks charge type when changing instance charge type.
+ default: true
+ type: bool
+ version_added: '0.2.0'
author:
- - "He Guimin (@xiaozhu36)"
+ - "He Guimin (@xiaozhu36)"
requirements:
- - "Python >= 3.6"
- - "footmark >= 1.19.0"
+ - "Python >= 3.6"
+ - "footmark >= 1.19.0"
extends_documentation_fragment:
- - community.general.alicloud
- - community.general.attributes
-'''
+ - community.general.alicloud
+ - community.general.attributes
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# basic provisioning example vpc network
- name: Basic provisioning example
hosts: localhost
@@ -298,7 +295,7 @@ EXAMPLES = '''
internet_charge_type: '{{ internet_charge_type }}'
max_bandwidth_out: '{{ max_bandwidth_out }}'
tags:
- Name: created_one
+ Name: created_one
host_name: '{{ host_name }}'
password: '{{ password }}'
@@ -316,11 +313,11 @@ EXAMPLES = '''
internet_charge_type: '{{ internet_charge_type }}'
max_bandwidth_out: '{{ max_bandwidth_out }}'
tags:
- Name: created_one
- Version: 0.1
+ Name: created_one
+ Version: 0.1
count: 2
count_tag:
- Name: created_one
+ Name: created_one
host_name: '{{ host_name }}'
password: '{{ password }}'
@@ -348,278 +345,278 @@ EXAMPLES = '''
alicloud_region: '{{ alicloud_region }}'
instance_ids: '{{ instance_ids }}'
security_groups: '{{ security_groups }}'
-'''
+"""
-RETURN = '''
+RETURN = r"""
instances:
- description: List of ECS instances
- returned: always
- type: complex
- contains:
- availability_zone:
- description: The availability zone of the instance is in.
- returned: always
- type: str
- sample: cn-beijing-a
- block_device_mappings:
- description: Any block device mapping entries for the instance.
- returned: always
- type: complex
- contains:
- device_name:
- description: The device name exposed to the instance (for example, /dev/xvda).
- returned: always
- type: str
- sample: /dev/xvda
- attach_time:
- description: The time stamp when the attachment initiated.
- returned: always
- type: str
- sample: "2018-06-25T04:08:26Z"
- delete_on_termination:
- description: Indicates whether the volume is deleted on instance termination.
- returned: always
- type: bool
- sample: true
- status:
- description: The attachment state.
- returned: always
- type: str
- sample: in_use
- volume_id:
- description: The ID of the cloud disk.
- returned: always
- type: str
- sample: d-2zei53pjsi117y6gf9t6
- cpu:
- description: The CPU core count of the instance.
- returned: always
- type: int
- sample: 4
- creation_time:
- description: The time the instance was created.
- returned: always
- type: str
- sample: "2018-06-25T04:08Z"
- description:
- description: The instance description.
- returned: always
- type: str
- sample: "my ansible instance"
- eip:
- description: The attribution of EIP associated with the instance.
- returned: always
- type: complex
- contains:
- allocation_id:
- description: The ID of the EIP.
- returned: always
- type: str
- sample: eip-12345
- internet_charge_type:
- description: The internet charge type of the EIP.
- returned: always
- type: str
- sample: "paybybandwidth"
- ip_address:
- description: EIP address.
- returned: always
- type: str
- sample: 42.10.2.2
- expired_time:
- description: The time the instance will expire.
- returned: always
- type: str
- sample: "2099-12-31T15:59Z"
- gpu:
- description: The attribution of instance GPU.
- returned: always
- type: complex
- contains:
- amount:
- description: The count of the GPU.
- returned: always
- type: int
- sample: 0
- spec:
- description: The specification of the GPU.
- returned: always
- type: str
- sample: ""
- host_name:
- description: The host name of the instance.
- returned: always
- type: str
- sample: iZ2zewaoZ
- id:
- description: Alias of instance_id.
- returned: always
- type: str
- sample: i-abc12345
- instance_id:
- description: ECS instance resource ID.
- returned: always
- type: str
- sample: i-abc12345
- image_id:
- description: The ID of the image used to launch the instance.
- returned: always
- type: str
- sample: m-0011223344
- inner_ip_address:
- description: The inner IPv4 address of the classic instance.
- returned: always
- type: str
- sample: 10.0.0.2
- instance_charge_type:
- description: The instance charge type.
- returned: always
- type: str
- sample: PostPaid
- instance_name:
- description: The name of the instance.
- returned: always
- type: str
- sample: my-ecs
- instance_type:
- description: The instance type of the running instance.
- returned: always
- type: str
- sample: ecs.sn1ne.xlarge
- instance_type_family:
- description: The instance type family of the instance belongs.
- returned: always
- type: str
- sample: ecs.sn1ne
- internet_charge_type:
- description: The billing method of the network bandwidth.
- returned: always
- type: str
- sample: PayByBandwidth
- internet_max_bandwidth_in:
- description: Maximum incoming bandwidth from the internet network.
- returned: always
- type: int
- sample: 200
- internet_max_bandwidth_out:
- description: Maximum incoming bandwidth from the internet network.
- returned: always
- type: int
- sample: 20
- io_optimized:
- description: Indicates whether the instance is optimized for EBS I/O.
- returned: always
- type: bool
- sample: false
- memory:
- description: Memory size of the instance.
- returned: always
- type: int
- sample: 8192
- network_interfaces:
- description: One or more network interfaces for the instance.
- returned: always
- type: complex
- contains:
- mac_address:
- description: The MAC address.
- returned: always
- type: str
- sample: "00:11:22:33:44:55"
- network_interface_id:
- description: The ID of the network interface.
- returned: always
- type: str
- sample: eni-01234567
- primary_ip_address:
- description: The primary IPv4 address of the network interface within the vswitch.
- returned: always
- type: str
- sample: 10.0.0.1
- osname:
- description: The operation system name of the instance owned.
- returned: always
- type: str
- sample: CentOS
- ostype:
- description: The operation system type of the instance owned.
- returned: always
- type: str
- sample: linux
- private_ip_address:
- description: The IPv4 address of the network interface within the subnet.
- returned: always
- type: str
- sample: 10.0.0.1
- public_ip_address:
- description: The public IPv4 address assigned to the instance or eip address
- returned: always
- type: str
- sample: 43.0.0.1
- resource_group_id:
- description: The id of the resource group to which the instance belongs.
- returned: always
- type: str
- sample: my-ecs-group
- security_groups:
- description: One or more security groups for the instance.
- returned: always
- type: list
- elements: dict
- contains:
- group_id:
- description: The ID of the security group.
- returned: always
- type: str
- sample: sg-0123456
- group_name:
- description: The name of the security group.
- returned: always
- type: str
- sample: my-security-group
- status:
- description: The current status of the instance.
- returned: always
- type: str
- sample: running
- tags:
- description: Any tags assigned to the instance.
- returned: always
- type: dict
- sample:
- user_data:
- description: User-defined data.
- returned: always
- type: dict
- sample:
- vswitch_id:
- description: The ID of the vswitch in which the instance is running.
- returned: always
- type: str
- sample: vsw-dew00abcdef
- vpc_id:
- description: The ID of the VPC the instance is in.
- returned: always
- type: str
- sample: vpc-0011223344
- spot_price_limit:
- description:
- - The maximum hourly price for the preemptible instance.
- returned: always
- type: float
- sample: 0.97
- spot_strategy:
- description:
- - The bidding mode of the pay-as-you-go instance.
+ description: List of ECS instances.
+ returned: always
+ type: complex
+ contains:
+ availability_zone:
+ description: The availability zone of the instance is in.
+ returned: always
+ type: str
+ sample: cn-beijing-a
+ block_device_mappings:
+ description: Any block device mapping entries for the instance.
+ returned: always
+ type: complex
+ contains:
+ device_name:
+ description: The device name exposed to the instance.
returned: always
type: str
- sample: NoSpot
+ sample: /dev/xvda
+ attach_time:
+ description: The time stamp when the attachment initiated.
+ returned: always
+ type: str
+ sample: "2018-06-25T04:08:26Z"
+ delete_on_termination:
+ description: Indicates whether the volume is deleted on instance termination.
+ returned: always
+ type: bool
+ sample: true
+ status:
+ description: The attachment state.
+ returned: always
+ type: str
+ sample: in_use
+ volume_id:
+ description: The ID of the cloud disk.
+ returned: always
+ type: str
+ sample: d-2zei53pjsi117y6gf9t6
+ cpu:
+ description: The CPU core count of the instance.
+ returned: always
+ type: int
+ sample: 4
+ creation_time:
+ description: The time the instance was created.
+ returned: always
+ type: str
+ sample: "2018-06-25T04:08Z"
+ description:
+ description: The instance description.
+ returned: always
+ type: str
+ sample: "my ansible instance"
+ eip:
+ description: The attribution of EIP associated with the instance.
+ returned: always
+ type: complex
+ contains:
+ allocation_id:
+ description: The ID of the EIP.
+ returned: always
+ type: str
+ sample: eip-12345
+ internet_charge_type:
+ description: The internet charge type of the EIP.
+ returned: always
+ type: str
+ sample: "paybybandwidth"
+ ip_address:
+ description: EIP address.
+ returned: always
+ type: str
+ sample: 42.10.2.2
+ expired_time:
+ description: The time the instance will expire.
+ returned: always
+ type: str
+ sample: "2099-12-31T15:59Z"
+ gpu:
+ description: The attribution of instance GPU.
+ returned: always
+ type: complex
+ contains:
+ amount:
+ description: The count of the GPU.
+ returned: always
+ type: int
+ sample: 0
+ spec:
+ description: The specification of the GPU.
+ returned: always
+ type: str
+ sample: ""
+ host_name:
+ description: The host name of the instance.
+ returned: always
+ type: str
+ sample: iZ2zewaoZ
+ id:
+ description: Alias of instance_id.
+ returned: always
+ type: str
+ sample: i-abc12345
+ instance_id:
+ description: ECS instance resource ID.
+ returned: always
+ type: str
+ sample: i-abc12345
+ image_id:
+ description: The ID of the image used to launch the instance.
+ returned: always
+ type: str
+ sample: m-0011223344
+ inner_ip_address:
+ description: The inner IPv4 address of the classic instance.
+ returned: always
+ type: str
+ sample: 10.0.0.2
+ instance_charge_type:
+ description: The instance charge type.
+ returned: always
+ type: str
+ sample: PostPaid
+ instance_name:
+ description: The name of the instance.
+ returned: always
+ type: str
+ sample: my-ecs
+ instance_type:
+ description: The instance type of the running instance.
+ returned: always
+ type: str
+ sample: ecs.sn1ne.xlarge
+ instance_type_family:
+ description: The instance type family of the instance belongs.
+ returned: always
+ type: str
+ sample: ecs.sn1ne
+ internet_charge_type:
+ description: The billing method of the network bandwidth.
+ returned: always
+ type: str
+ sample: PayByBandwidth
+ internet_max_bandwidth_in:
+ description: Maximum incoming bandwidth from the internet network.
+ returned: always
+ type: int
+ sample: 200
+ internet_max_bandwidth_out:
+ description: Maximum incoming bandwidth from the internet network.
+ returned: always
+ type: int
+ sample: 20
+ io_optimized:
+ description: Indicates whether the instance is optimized for EBS I/O.
+ returned: always
+ type: bool
+ sample: false
+ memory:
+ description: Memory size of the instance.
+ returned: always
+ type: int
+ sample: 8192
+ network_interfaces:
+ description: One or more network interfaces for the instance.
+ returned: always
+ type: complex
+ contains:
+ mac_address:
+ description: The MAC address.
+ returned: always
+ type: str
+ sample: "00:11:22:33:44:55"
+ network_interface_id:
+ description: The ID of the network interface.
+ returned: always
+ type: str
+ sample: eni-01234567
+ primary_ip_address:
+ description: The primary IPv4 address of the network interface within the vswitch.
+ returned: always
+ type: str
+ sample: 10.0.0.1
+ osname:
+ description: The operation system name of the instance owned.
+ returned: always
+ type: str
+ sample: CentOS
+ ostype:
+ description: The operation system type of the instance owned.
+ returned: always
+ type: str
+ sample: linux
+ private_ip_address:
+ description: The IPv4 address of the network interface within the subnet.
+ returned: always
+ type: str
+ sample: 10.0.0.1
+ public_ip_address:
+ description: The public IPv4 address assigned to the instance or eip address.
+ returned: always
+ type: str
+ sample: 43.0.0.1
+ resource_group_id:
+ description: The ID of the resource group to which the instance belongs.
+ returned: always
+ type: str
+ sample: my-ecs-group
+ security_groups:
+ description: One or more security groups for the instance.
+ returned: always
+ type: list
+ elements: dict
+ contains:
+ group_id:
+ description: The ID of the security group.
+ returned: always
+ type: str
+ sample: sg-0123456
+ group_name:
+ description: The name of the security group.
+ returned: always
+ type: str
+ sample: my-security-group
+ status:
+ description: The current status of the instance.
+ returned: always
+ type: str
+ sample: running
+ tags:
+ description: Any tags assigned to the instance.
+ returned: always
+ type: dict
+ sample:
+ user_data:
+ description: User-defined data.
+ returned: always
+ type: dict
+ sample:
+ vswitch_id:
+ description: The ID of the vswitch in which the instance is running.
+ returned: always
+ type: str
+ sample: vsw-dew00abcdef
+ vpc_id:
+ description: The ID of the VPC the instance is in.
+ returned: always
+ type: str
+ sample: vpc-0011223344
+ spot_price_limit:
+ description:
+ - The maximum hourly price for the preemptible instance.
+ returned: always
+ type: float
+ sample: 0.97
+ spot_strategy:
+ description:
+ - The bidding mode of the pay-as-you-go instance.
+ returned: always
+ type: str
+ sample: NoSpot
ids:
- description: List of ECS instance IDs
- returned: always
- type: list
- sample: [i-12345er, i-3245fs]
-'''
+ description: List of ECS instance IDs.
+ returned: always
+ type: list
+ sample: [i-12345er, i-3245fs]
+"""
import re
import time
diff --git a/plugins/modules/ali_instance_info.py b/plugins/modules/ali_instance_info.py
index d6a7873742..00e77b1ab2 100644
--- a/plugins/modules/ali_instance_info.py
+++ b/plugins/modules/ali_instance_info.py
@@ -24,51 +24,48 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ali_instance_info
short_description: Gather information on instances of Alibaba Cloud ECS
description:
- - This module fetches data from the Open API in Alicloud.
- The module must be called from within the ECS instance itself.
-
+ - This module fetches data from the Open API in Alicloud. The module must be called from within the ECS instance itself.
attributes:
- check_mode:
- version_added: 3.3.0
+ check_mode:
+ version_added: 3.3.0
# This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- name_prefix:
- description:
- - Use a instance name prefix to filter ecs instances.
- type: str
- version_added: '0.2.0'
- tags:
- description:
- - A hash/dictionaries of instance tags. C({"key":"value"})
- aliases: ["instance_tags"]
- type: dict
- filters:
- description:
- - A dict of filters to apply. Each dict item consists of a filter key and a filter value. The filter keys can be
- all of request parameters. See U(https://www.alibabacloud.com/help/doc-detail/25506.htm) for parameter details.
- Filter keys can be same as request parameter name or be lower case and use underscore (V("_")) or dash (V("-")) to
- connect different words in one parameter. C(InstanceIds) should be a list.
- C(Tag.n.Key) and C(Tag.n.Value) should be a dict and using O(tags) instead.
- type: dict
- version_added: '0.2.0'
+ name_prefix:
+ description:
+ - Use a instance name prefix to filter ECS instances.
+ type: str
+ version_added: '0.2.0'
+ tags:
+ description:
+ - A hash/dictionaries of instance tags. C({"key":"value"}).
+ aliases: ["instance_tags"]
+ type: dict
+ filters:
+ description:
+ - A dict of filters to apply. Each dict item consists of a filter key and a filter value. The filter keys can be all
+ of request parameters. See U(https://www.alibabacloud.com/help/doc-detail/25506.htm) for parameter details. Filter
+ keys can be same as request parameter name or be lower case and use underscore (V("_")) or dash (V("-")) to connect
+ different words in one parameter. C(InstanceIds) should be a list. C(Tag.n.Key) and C(Tag.n.Value) should be a dict
+ and using O(tags) instead.
+ type: dict
+ version_added: '0.2.0'
author:
- - "He Guimin (@xiaozhu36)"
+ - "He Guimin (@xiaozhu36)"
requirements:
- - "Python >= 3.6"
- - "footmark >= 1.13.0"
+ - "Python >= 3.6"
+ - "footmark >= 1.13.0"
extends_documentation_fragment:
- - community.general.alicloud
- - community.general.attributes
- - community.general.attributes.info_module
-'''
+ - community.general.alicloud
+ - community.general.attributes
+ - community.general.attributes.info_module
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Fetch instances details according to setting different filters
- name: Find all instances in the specified region
@@ -91,261 +88,261 @@ EXAMPLES = '''
community.general.ali_instance_info:
tags:
Test: "add"
-'''
+"""
-RETURN = '''
+RETURN = r"""
instances:
- description: List of ECS instances
- returned: always
- type: complex
- contains:
- availability_zone:
- description: The availability zone of the instance is in.
- returned: always
- type: str
- sample: cn-beijing-a
- block_device_mappings:
- description: Any block device mapping entries for the instance.
- returned: always
- type: complex
- contains:
- device_name:
- description: The device name exposed to the instance (for example, /dev/xvda).
- returned: always
- type: str
- sample: /dev/xvda
- attach_time:
- description: The time stamp when the attachment initiated.
- returned: always
- type: str
- sample: "2018-06-25T04:08:26Z"
- delete_on_termination:
- description: Indicates whether the volume is deleted on instance termination.
- returned: always
- type: bool
- sample: true
- status:
- description: The attachment state.
- returned: always
- type: str
- sample: in_use
- volume_id:
- description: The ID of the cloud disk.
- returned: always
- type: str
- sample: d-2zei53pjsi117y6gf9t6
- cpu:
- description: The CPU core count of the instance.
- returned: always
- type: int
- sample: 4
- creation_time:
- description: The time the instance was created.
- returned: always
- type: str
- sample: "2018-06-25T04:08Z"
- description:
- description: The instance description.
- returned: always
- type: str
- sample: "my ansible instance"
- eip:
- description: The attribution of EIP associated with the instance.
- returned: always
- type: complex
- contains:
- allocation_id:
- description: The ID of the EIP.
- returned: always
- type: str
- sample: eip-12345
- internet_charge_type:
- description: The internet charge type of the EIP.
- returned: always
- type: str
- sample: "paybybandwidth"
- ip_address:
- description: EIP address.
- returned: always
- type: str
- sample: 42.10.2.2
- expired_time:
- description: The time the instance will expire.
- returned: always
- type: str
- sample: "2099-12-31T15:59Z"
- gpu:
- description: The attribution of instance GPU.
- returned: always
- type: complex
- contains:
- amount:
- description: The count of the GPU.
- returned: always
- type: int
- sample: 0
- spec:
- description: The specification of the GPU.
- returned: always
- type: str
- sample: ""
- host_name:
- description: The host name of the instance.
- returned: always
- type: str
- sample: iZ2zewaoZ
- id:
- description: Alias of instance_id.
- returned: always
- type: str
- sample: i-abc12345
- instance_id:
- description: ECS instance resource ID.
- returned: always
- type: str
- sample: i-abc12345
- image_id:
- description: The ID of the image used to launch the instance.
- returned: always
- type: str
- sample: m-0011223344
- inner_ip_address:
- description: The inner IPv4 address of the classic instance.
- returned: always
- type: str
- sample: 10.0.0.2
- instance_charge_type:
- description: The instance charge type.
- returned: always
- type: str
- sample: PostPaid
- instance_name:
- description: The name of the instance.
- returned: always
- type: str
- sample: my-ecs
- instance_type_family:
- description: The instance type family of the instance belongs.
- returned: always
- type: str
- sample: ecs.sn1ne
- instance_type:
- description: The instance type of the running instance.
- returned: always
- type: str
- sample: ecs.sn1ne.xlarge
- internet_charge_type:
- description: The billing method of the network bandwidth.
- returned: always
- type: str
- sample: PayByBandwidth
- internet_max_bandwidth_in:
- description: Maximum incoming bandwidth from the internet network.
- returned: always
- type: int
- sample: 200
- internet_max_bandwidth_out:
- description: Maximum incoming bandwidth from the internet network.
- returned: always
- type: int
- sample: 20
- io_optimized:
- description: Indicates whether the instance is optimized for EBS I/O.
- returned: always
- type: bool
- sample: false
- memory:
- description: Memory size of the instance.
- returned: always
- type: int
- sample: 8192
- network_interfaces:
- description: One or more network interfaces for the instance.
- returned: always
- type: complex
- contains:
- mac_address:
- description: The MAC address.
- returned: always
- type: str
- sample: "00:11:22:33:44:55"
- network_interface_id:
- description: The ID of the network interface.
- returned: always
- type: str
- sample: eni-01234567
- primary_ip_address:
- description: The primary IPv4 address of the network interface within the vswitch.
- returned: always
- type: str
- sample: 10.0.0.1
- osname:
- description: The operation system name of the instance owned.
- returned: always
- type: str
- sample: CentOS
- ostype:
- description: The operation system type of the instance owned.
- returned: always
- type: str
- sample: linux
- private_ip_address:
- description: The IPv4 address of the network interface within the subnet.
- returned: always
- type: str
- sample: 10.0.0.1
- public_ip_address:
- description: The public IPv4 address assigned to the instance or eip address
- returned: always
- type: str
- sample: 43.0.0.1
- resource_group_id:
- description: The id of the resource group to which the instance belongs.
- returned: always
- type: str
- sample: my-ecs-group
- security_groups:
- description: One or more security groups for the instance.
- returned: always
- type: list
- elements: dict
- contains:
- group_id:
- description: The ID of the security group.
- returned: always
- type: str
- sample: sg-0123456
- group_name:
- description: The name of the security group.
- returned: always
- type: str
- sample: my-security-group
+ description: List of ECS instances.
+ returned: always
+ type: complex
+ contains:
+ availability_zone:
+ description: The availability zone of the instance is in.
+ returned: always
+ type: str
+ sample: cn-beijing-a
+ block_device_mappings:
+ description: Any block device mapping entries for the instance.
+ returned: always
+ type: complex
+ contains:
+ device_name:
+ description: The device name exposed to the instance (for example, /dev/xvda).
+ returned: always
+ type: str
+ sample: /dev/xvda
+ attach_time:
+ description: The time stamp when the attachment initiated.
+ returned: always
+ type: str
+ sample: "2018-06-25T04:08:26Z"
+ delete_on_termination:
+ description: Indicates whether the volume is deleted on instance termination.
+ returned: always
+ type: bool
+ sample: true
status:
- description: The current status of the instance.
- returned: always
- type: str
- sample: running
- tags:
- description: Any tags assigned to the instance.
- returned: always
- type: dict
- sample:
- vswitch_id:
- description: The ID of the vswitch in which the instance is running.
- returned: always
- type: str
- sample: vsw-dew00abcdef
- vpc_id:
- description: The ID of the VPC the instance is in.
- returned: always
- type: str
- sample: vpc-0011223344
+ description: The attachment state.
+ returned: always
+ type: str
+ sample: in_use
+ volume_id:
+ description: The ID of the cloud disk.
+ returned: always
+ type: str
+ sample: d-2zei53pjsi117y6gf9t6
+ cpu:
+ description: The CPU core count of the instance.
+ returned: always
+ type: int
+ sample: 4
+ creation_time:
+ description: The time the instance was created.
+ returned: always
+ type: str
+ sample: "2018-06-25T04:08Z"
+ description:
+ description: The instance description.
+ returned: always
+ type: str
+ sample: "my ansible instance"
+ eip:
+ description: The attribution of EIP associated with the instance.
+ returned: always
+ type: complex
+ contains:
+ allocation_id:
+ description: The ID of the EIP.
+ returned: always
+ type: str
+ sample: eip-12345
+ internet_charge_type:
+ description: The internet charge type of the EIP.
+ returned: always
+ type: str
+ sample: "paybybandwidth"
+ ip_address:
+ description: EIP address.
+ returned: always
+ type: str
+ sample: 42.10.2.2
+ expired_time:
+ description: The time the instance will expire.
+ returned: always
+ type: str
+ sample: "2099-12-31T15:59Z"
+ gpu:
+ description: The attribution of instance GPU.
+ returned: always
+ type: complex
+ contains:
+ amount:
+ description: The count of the GPU.
+ returned: always
+ type: int
+ sample: 0
+ spec:
+ description: The specification of the GPU.
+ returned: always
+ type: str
+ sample: ""
+ host_name:
+ description: The host name of the instance.
+ returned: always
+ type: str
+ sample: iZ2zewaoZ
+ id:
+ description: Alias of instance_id.
+ returned: always
+ type: str
+ sample: i-abc12345
+ instance_id:
+ description: ECS instance resource ID.
+ returned: always
+ type: str
+ sample: i-abc12345
+ image_id:
+ description: The ID of the image used to launch the instance.
+ returned: always
+ type: str
+ sample: m-0011223344
+ inner_ip_address:
+ description: The inner IPv4 address of the classic instance.
+ returned: always
+ type: str
+ sample: 10.0.0.2
+ instance_charge_type:
+ description: The instance charge type.
+ returned: always
+ type: str
+ sample: PostPaid
+ instance_name:
+ description: The name of the instance.
+ returned: always
+ type: str
+ sample: my-ecs
+ instance_type_family:
+ description: The instance type family of the instance belongs.
+ returned: always
+ type: str
+ sample: ecs.sn1ne
+ instance_type:
+ description: The instance type of the running instance.
+ returned: always
+ type: str
+ sample: ecs.sn1ne.xlarge
+ internet_charge_type:
+ description: The billing method of the network bandwidth.
+ returned: always
+ type: str
+ sample: PayByBandwidth
+ internet_max_bandwidth_in:
+ description: Maximum incoming bandwidth from the internet network.
+ returned: always
+ type: int
+ sample: 200
+ internet_max_bandwidth_out:
+ description: Maximum incoming bandwidth from the internet network.
+ returned: always
+ type: int
+ sample: 20
+ io_optimized:
+ description: Indicates whether the instance is optimized for EBS I/O.
+ returned: always
+ type: bool
+ sample: false
+ memory:
+ description: Memory size of the instance.
+ returned: always
+ type: int
+ sample: 8192
+ network_interfaces:
+ description: One or more network interfaces for the instance.
+ returned: always
+ type: complex
+ contains:
+ mac_address:
+ description: The MAC address.
+ returned: always
+ type: str
+ sample: "00:11:22:33:44:55"
+ network_interface_id:
+ description: The ID of the network interface.
+ returned: always
+ type: str
+ sample: eni-01234567
+ primary_ip_address:
+ description: The primary IPv4 address of the network interface within the vswitch.
+ returned: always
+ type: str
+ sample: 10.0.0.1
+ osname:
+ description: The operation system name of the instance owned.
+ returned: always
+ type: str
+ sample: CentOS
+ ostype:
+ description: The operation system type of the instance owned.
+ returned: always
+ type: str
+ sample: linux
+ private_ip_address:
+ description: The IPv4 address of the network interface within the subnet.
+ returned: always
+ type: str
+ sample: 10.0.0.1
+ public_ip_address:
+ description: The public IPv4 address assigned to the instance or EIP address.
+ returned: always
+ type: str
+ sample: 43.0.0.1
+ resource_group_id:
+ description: The ID of the resource group to which the instance belongs.
+ returned: always
+ type: str
+ sample: my-ecs-group
+ security_groups:
+ description: One or more security groups for the instance.
+ returned: always
+ type: list
+ elements: dict
+ contains:
+ group_id:
+ description: The ID of the security group.
+ returned: always
+ type: str
+ sample: sg-0123456
+ group_name:
+ description: The name of the security group.
+ returned: always
+ type: str
+ sample: my-security-group
+ status:
+ description: The current status of the instance.
+ returned: always
+ type: str
+ sample: running
+ tags:
+ description: Any tags assigned to the instance.
+ returned: always
+ type: dict
+ sample:
+ vswitch_id:
+ description: The ID of the vswitch in which the instance is running.
+ returned: always
+ type: str
+ sample: vsw-dew00abcdef
+ vpc_id:
+ description: The ID of the VPC the instance is in.
+ returned: always
+ type: str
+ sample: vpc-0011223344
ids:
- description: List of ECS instance IDs
- returned: always
- type: list
- sample: [i-12345er, i-3245fs]
-'''
+ description: List of ECS instance IDs.
+ returned: always
+ type: list
+ sample: [i-12345er, i-3245fs]
+"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible_collections.community.general.plugins.module_utils.alicloud_ecs import (
diff --git a/plugins/modules/alternatives.py b/plugins/modules/alternatives.py
index da578276fa..c96aede225 100644
--- a/plugins/modules/alternatives.py
+++ b/plugins/modules/alternatives.py
@@ -11,19 +11,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: alternatives
short_description: Manages alternative programs for common commands
description:
- - Manages symbolic links using the 'update-alternatives' tool.
- - Useful when multiple programs are installed but provide similar functionality (e.g. different editors).
+ - Manages symbolic links using the C(update-alternatives) tool.
+ - Useful when multiple programs are installed but provide similar functionality (for example, different editors).
author:
- - Marius Rieder (@jiuka)
- - David Wittman (@DavidWittman)
- - Gabe Mulley (@mulby)
+ - Marius Rieder (@jiuka)
+ - David Wittman (@DavidWittman)
+ - Gabe Mulley (@mulby)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -39,12 +38,16 @@ options:
description:
- The path to the real executable that the link should point to.
type: path
- required: true
+ family:
+ description:
+ - The family groups similar alternatives. This option is available only on RHEL-based distributions.
+ type: str
+ version_added: 10.1.0
link:
description:
- The path to the symbolic link that should point to the real executable.
- - This option is always required on RHEL-based distributions. On Debian-based distributions this option is
- required when the alternative O(name) is unknown to the system.
+ - This option is always required on RHEL-based distributions. On Debian-based distributions this option is required
+ when the alternative O(name) is unknown to the system.
type: path
priority:
description:
@@ -52,14 +55,14 @@ options:
type: int
state:
description:
- - V(present) - install the alternative (if not already installed), but do
- not set it as the currently selected alternative for the group.
- - V(selected) - install the alternative (if not already installed), and
- set it as the currently selected alternative for the group.
- - V(auto) - install the alternative (if not already installed), and
- set the group to auto mode. Added in community.general 5.1.0.
+ - V(present) - install the alternative (if not already installed), but do not set it as the currently selected alternative
+ for the group.
+ - V(selected) - install the alternative (if not already installed), and set it as the currently selected alternative
+ for the group.
+ - V(auto) - install the alternative (if not already installed), and set the group to auto mode. Added in community.general
+ 5.1.0.
- V(absent) - removes the alternative. Added in community.general 5.1.0.
- choices: [ present, selected, auto, absent ]
+ choices: [present, selected, auto, absent]
default: selected
type: str
version_added: 4.8.0
@@ -67,8 +70,7 @@ options:
description:
- A list of subcommands.
- Each subcommand needs a name, a link and a path parameter.
- - Subcommands are also named 'slaves' or 'followers', depending on the version
- of alternatives.
+ - Subcommands are also named C(slaves) or C(followers), depending on the version of C(alternatives).
type: list
elements: dict
aliases: ['slaves']
@@ -89,15 +91,21 @@ options:
type: path
required: true
version_added: 5.1.0
-requirements: [ update-alternatives ]
-'''
+requirements: [update-alternatives]
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Correct java version selected
community.general.alternatives:
name: java
path: /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java
+- name: Select java-11-openjdk.x86_64 family
+ community.general.alternatives:
+ name: java
+ family: java-11-openjdk.x86_64
+ when: ansible_os_family == 'RedHat'
+
- name: Alternatives link created
community.general.alternatives:
name: hadoop-conf
@@ -133,7 +141,7 @@ EXAMPLES = r'''
- name: keytool
link: /usr/bin/keytool
path: /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/keytool
-'''
+"""
import os
import re
@@ -182,17 +190,25 @@ class AlternativesModule(object):
subcommands_parameter = self.module.params['subcommands']
priority_parameter = self.module.params['priority']
if (
- self.path not in self.current_alternatives or
- (priority_parameter is not None and self.current_alternatives[self.path].get('priority') != priority_parameter) or
- (subcommands_parameter is not None and (
- not all(s in subcommands_parameter for s in self.current_alternatives[self.path].get('subcommands')) or
- not all(s in self.current_alternatives[self.path].get('subcommands') for s in subcommands_parameter)
- ))
+ self.path is not None and (
+ self.path not in self.current_alternatives or
+ (priority_parameter is not None and self.current_alternatives[self.path].get('priority') != priority_parameter) or
+ (subcommands_parameter is not None and (
+ not all(s in subcommands_parameter for s in self.current_alternatives[self.path].get('subcommands')) or
+ not all(s in self.current_alternatives[self.path].get('subcommands') for s in subcommands_parameter)
+ ))
+ )
):
self.install()
# Check if we need to set the preference
- if self.mode_selected and self.current_path != self.path:
+ is_same_path = self.path is not None and self.current_path == self.path
+ is_same_family = False
+ if self.current_path is not None and self.current_path in self.current_alternatives:
+ current_alternative = self.current_alternatives[self.current_path]
+ is_same_family = current_alternative.get('family') == self.family
+
+ if self.mode_selected and not (is_same_path or is_same_family):
self.set()
# Check if we need to reset to auto
@@ -213,6 +229,8 @@ class AlternativesModule(object):
self.module.fail_json(msg='Needed to install the alternative, but unable to do so as we are missing the link')
cmd = [self.UPDATE_ALTERNATIVES, '--install', self.link, self.name, self.path, str(self.priority)]
+ if self.family is not None:
+ cmd.extend(["--family", self.family])
if self.module.params['subcommands'] is not None:
subcommands = [['--slave', subcmd['link'], subcmd['name'], subcmd['path']] for subcmd in self.subcommands]
@@ -228,6 +246,7 @@ class AlternativesModule(object):
self.result['diff']['after'] = dict(
state=AlternativeState.PRESENT,
path=self.path,
+ family=self.family,
priority=self.priority,
link=self.link,
)
@@ -248,9 +267,15 @@ class AlternativesModule(object):
self.result['diff']['after'] = dict(state=AlternativeState.ABSENT)
def set(self):
- cmd = [self.UPDATE_ALTERNATIVES, '--set', self.name, self.path]
+ # Path takes precedence over family as it is more specific
+ if self.path is None:
+ arg = self.family
+ else:
+ arg = self.path
+
+ cmd = [self.UPDATE_ALTERNATIVES, '--set', self.name, arg]
self.result['changed'] = True
- self.messages.append("Set alternative '%s' for '%s'." % (self.path, self.name))
+ self.messages.append("Set alternative '%s' for '%s'." % (arg, self.name))
if not self.module.check_mode:
self.module.run_command(cmd, check_rc=True)
@@ -277,6 +302,10 @@ class AlternativesModule(object):
def path(self):
return self.module.params.get('path')
+ @property
+ def family(self):
+ return self.module.params.get('family')
+
@property
def link(self):
return self.module.params.get('link') or self.current_link
@@ -321,7 +350,7 @@ class AlternativesModule(object):
current_link_regex = re.compile(r'^\s*link \w+ is (.*)$', re.MULTILINE)
subcmd_path_link_regex = re.compile(r'^\s*(?:slave|follower) (\S+) is (.*)$', re.MULTILINE)
- alternative_regex = re.compile(r'^(\/.*)\s-\s(?:family\s\S+\s)?priority\s(\d+)((?:\s+(?:slave|follower).*)*)', re.MULTILINE)
+ alternative_regex = re.compile(r'^(\/.*)\s-\s(?:family\s(\S+)\s)?priority\s(\d+)((?:\s+(?:slave|follower).*)*)', re.MULTILINE)
subcmd_regex = re.compile(r'^\s+(?:slave|follower) (.*): (.*)$', re.MULTILINE)
match = current_mode_regex.search(display_output)
@@ -346,9 +375,10 @@ class AlternativesModule(object):
if not subcmd_path_map and self.subcommands:
subcmd_path_map = {s['name']: s['link'] for s in self.subcommands}
- for path, prio, subcmd in alternative_regex.findall(display_output):
+ for path, family, prio, subcmd in alternative_regex.findall(display_output):
self.current_alternatives[path] = dict(
priority=int(prio),
+ family=family,
subcommands=[dict(
name=name,
path=spath,
@@ -383,7 +413,8 @@ def main():
module = AnsibleModule(
argument_spec=dict(
name=dict(type='str', required=True),
- path=dict(type='path', required=True),
+ path=dict(type='path'),
+ family=dict(type='str'),
link=dict(type='path'),
priority=dict(type='int'),
state=dict(
@@ -398,6 +429,7 @@ def main():
)),
),
supports_check_mode=True,
+ required_one_of=[('path', 'family')]
)
AlternativesModule(module)
diff --git a/plugins/modules/android_sdk.py b/plugins/modules/android_sdk.py
new file mode 100644
index 0000000000..a604a510ed
--- /dev/null
+++ b/plugins/modules/android_sdk.py
@@ -0,0 +1,210 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024, Stanislav Shamilov
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+module: android_sdk
+short_description: Manages Android SDK packages
+description:
+ - Manages Android SDK packages.
+ - Allows installation from different channels (stable, beta, dev, canary).
+ - Allows installation of packages to a non-default SDK root directory.
+author: Stanislav Shamilov (@shamilovstas)
+extends_documentation_fragment:
+ - community.general.attributes
+attributes:
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
+version_added: 10.2.0
+options:
+ accept_licenses:
+ description:
+ - If this is set to V(true), the module will try to accept license prompts generated by C(sdkmanager) during package
+ installation. Otherwise, every license prompt will be rejected.
+ type: bool
+ default: false
+ name:
+ description:
+ - A name of an Android SDK package (for instance, V(build-tools;34.0.0)).
+ aliases: ['package', 'pkg']
+ type: list
+ elements: str
+ state:
+ description:
+ - Indicates the desired package(s) state.
+ - V(present) ensures that package(s) is/are present.
+ - V(absent) ensures that package(s) is/are absent.
+ - V(latest) ensures that package(s) is/are installed and updated to the latest version(s).
+ choices: ['present', 'absent', 'latest']
+ default: present
+ type: str
+ sdk_root:
+ description:
+ - Provides path for an alternative directory to install Android SDK packages to. By default, all packages are installed
+ to the directory where C(sdkmanager) is installed.
+ type: path
+ channel:
+ description:
+ - Indicates what channel must C(sdkmanager) use for installation of packages.
+ choices: ['stable', 'beta', 'dev', 'canary']
+ default: stable
+ type: str
+requirements:
+ - C(java) >= 17
+ - C(sdkmanager) Command line tool for installing Android SDK packages.
+notes:
+ - For some of the packages installed by C(sdkmanager) is it necessary to accept licenses. Usually it is done through command
+ line prompt in a form of a Y/N question when a licensed package is requested to be installed. If there are several packages
+ requested for installation and at least two of them belong to different licenses, the C(sdkmanager) tool will prompt for
+ these licenses in a loop. In order to install packages, the module must be able to answer these license prompts. Currently,
+ it is only possible to answer one license prompt at a time, meaning that instead of installing multiple packages as a
+ single invocation of the C(sdkmanager --install) command, it will be done by executing the command independently for each
+ package. This makes sure that at most only one license prompt will need to be answered. At the time of writing this module,
+ a C(sdkmanager)'s package may belong to at most one license type that needs to be accepted. However, if this changes in
+ the future, the module may hang as there might be more prompts generated by the C(sdkmanager) tool which the module will
+ not be able to answer. If this becomes the case, file an issue and in the meantime, consider accepting all the licenses
+ in advance, as it is described in the C(sdkmanager) L(documentation,https://developer.android.com/tools/sdkmanager#accept-licenses),
+ for instance, using the M(ansible.builtin.command) module.
+seealso:
+ - name: sdkmanager tool documentation
+ description: Detailed information of how to install and use sdkmanager command line tool.
+ link: https://developer.android.com/tools/sdkmanager
+"""
+
+EXAMPLES = r"""
+- name: Install build-tools;34.0.0
+ community.general.android_sdk:
+ name: build-tools;34.0.0
+ accept_licenses: true
+ state: present
+
+- name: Install build-tools;34.0.0 and platform-tools
+ community.general.android_sdk:
+ name:
+ - build-tools;34.0.0
+ - platform-tools
+ accept_licenses: true
+ state: present
+
+- name: Delete build-tools;34.0.0
+ community.general.android_sdk:
+ name: build-tools;34.0.0
+ state: absent
+
+- name: Install platform-tools or update if installed
+ community.general.android_sdk:
+ name: platform-tools
+ accept_licenses: true
+ state: latest
+
+- name: Install build-tools;34.0.0 to a different SDK root
+ community.general.android_sdk:
+ name: build-tools;34.0.0
+ accept_licenses: true
+ state: present
+ sdk_root: "/path/to/new/root"
+
+- name: Install a package from another channel
+ community.general.android_sdk:
+ name: some-package-present-in-canary-channel
+ accept_licenses: true
+ state: present
+ channel: canary
+"""
+
+RETURN = r"""
+installed:
+ description: A list of packages that have been installed.
+ returned: when packages have changed
+ type: list
+ sample: ['build-tools;34.0.0', 'platform-tools']
+
+removed:
+ description: A list of packages that have been removed.
+ returned: when packages have changed
+ type: list
+ sample: ['build-tools;34.0.0', 'platform-tools']
+"""
+
+from ansible_collections.community.general.plugins.module_utils.mh.module_helper import StateModuleHelper
+from ansible_collections.community.general.plugins.module_utils.android_sdkmanager import Package, AndroidSdkManager
+
+
+class AndroidSdk(StateModuleHelper):
+ module = dict(
+ argument_spec=dict(
+ state=dict(type='str', default='present', choices=['present', 'absent', 'latest']),
+ package=dict(type='list', elements='str', aliases=['pkg', 'name']),
+ sdk_root=dict(type='path'),
+ channel=dict(type='str', default='stable', choices=['stable', 'beta', 'dev', 'canary']),
+ accept_licenses=dict(type='bool', default=False)
+ ),
+ supports_check_mode=True
+ )
+ use_old_vardict = False
+
+ def __init_module__(self):
+ self.sdkmanager = AndroidSdkManager(self.module)
+ self.vars.set('installed', [], change=True)
+ self.vars.set('removed', [], change=True)
+
+ def _parse_packages(self):
+ arg_pkgs = set(self.vars.package)
+ if len(arg_pkgs) < len(self.vars.package):
+ self.do_raise("Packages may not repeat")
+ return set([Package(p) for p in arg_pkgs])
+
+ def state_present(self):
+ packages = self._parse_packages()
+ installed = self.sdkmanager.get_installed_packages()
+ pending_installation = packages.difference(installed)
+
+ self.vars.installed = AndroidSdk._map_packages_to_names(pending_installation)
+ if not self.check_mode:
+ rc, stdout, stderr = self.sdkmanager.apply_packages_changes(pending_installation, self.vars.accept_licenses)
+ if rc != 0:
+ self.do_raise("Could not install packages: %s" % stderr)
+
+ def state_absent(self):
+ packages = self._parse_packages()
+ installed = self.sdkmanager.get_installed_packages()
+ to_be_deleted = packages.intersection(installed)
+ self.vars.removed = AndroidSdk._map_packages_to_names(to_be_deleted)
+ if not self.check_mode:
+ rc, stdout, stderr = self.sdkmanager.apply_packages_changes(to_be_deleted)
+ if rc != 0:
+ self.do_raise("Could not uninstall packages: %s" % stderr)
+
+ def state_latest(self):
+ packages = self._parse_packages()
+ installed = self.sdkmanager.get_installed_packages()
+ updatable = self.sdkmanager.get_updatable_packages()
+ not_installed = packages.difference(installed)
+ to_be_installed = not_installed.union(updatable)
+ self.vars.installed = AndroidSdk._map_packages_to_names(to_be_installed)
+
+ if not self.check_mode:
+ rc, stdout, stderr = self.sdkmanager.apply_packages_changes(to_be_installed, self.vars.accept_licenses)
+ if rc != 0:
+ self.do_raise("Could not install packages: %s" % stderr)
+
+ @staticmethod
+ def _map_packages_to_names(packages):
+ return [x.name for x in packages]
+
+
+def main():
+ AndroidSdk.execute()
+
+
+if __name__ == '__main__':
+ main()
diff --git a/plugins/modules/ansible_galaxy_install.py b/plugins/modules/ansible_galaxy_install.py
index ea35b3afc0..ad055dfa14 100644
--- a/plugins/modules/ansible_galaxy_install.py
+++ b/plugins/modules/ansible_galaxy_install.py
@@ -8,30 +8,27 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: ansible_galaxy_install
author:
-- "Alexei Znamensky (@russoz)"
+ - "Alexei Znamensky (@russoz)"
short_description: Install Ansible roles or collections using ansible-galaxy
version_added: 3.5.0
description:
-- This module allows the installation of Ansible collections or roles using C(ansible-galaxy).
+ - This module allows the installation of Ansible collections or roles using C(ansible-galaxy).
notes:
-- Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0.
-- >
- The module will try and run using the C(C.UTF-8) locale.
- If that fails, it will try C(en_US.UTF-8).
- If that one also fails, the module will fail.
+ - Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0.
+ - The module will try and run using the C(C.UTF-8) locale. If that fails, it will try C(en_US.UTF-8). If that one also fails,
+ the module will fail.
seealso:
-- name: C(ansible-galaxy) command manual page
- description: Manual page for the command.
- link: https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html
+ - name: C(ansible-galaxy) command manual page
+ description: Manual page for the command.
+ link: https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html
requirements:
-- ansible-core 2.11 or newer
+ - ansible-core 2.11 or newer
extends_documentation_fragment:
-- community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
@@ -40,63 +37,59 @@ attributes:
options:
state:
description:
- - >
- If O(state=present) then the collection or role will be installed.
- Note that the collections and roles are not updated with this option.
- - >
- Currently the O(state=latest) is ignored unless O(type=collection), and it will
- ensure the collection is installed and updated to the latest available version.
- - Please note that O(force=true) can be used to perform upgrade regardless of O(type).
+ - If O(state=present) then the collection or role will be installed. Note that the collections and roles are not updated
+ with this option.
+ - Currently the O(state=latest) is ignored unless O(type=collection), and it will ensure the collection is installed
+ and updated to the latest available version.
+ - Please note that O(force=true) can be used to perform upgrade regardless of O(type).
type: str
choices: [present, latest]
default: present
version_added: 9.1.0
type:
description:
- - The type of installation performed by C(ansible-galaxy).
- - If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections.
- - "Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three choices."
+ - The type of installation performed by C(ansible-galaxy).
+ - If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections.
+ - 'Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three
+ choices.'
type: str
choices: [collection, role, both]
required: true
name:
description:
- - Name of the collection or role being installed.
- - >
- Versions can be specified with C(ansible-galaxy) usual formats.
- For example, the collection V(community.docker:1.6.1) or the role V(ansistrano.deploy,3.8.0).
- - O(name) and O(requirements_file) are mutually exclusive.
+ - Name of the collection or role being installed.
+ - Versions can be specified with C(ansible-galaxy) usual formats. For example, the collection V(community.docker:1.6.1)
+ or the role V(ansistrano.deploy,3.8.0).
+ - O(name) and O(requirements_file) are mutually exclusive.
type: str
requirements_file:
description:
- - Path to a file containing a list of requirements to be installed.
- - It works for O(type) equals to V(collection) and V(role).
- - O(name) and O(requirements_file) are mutually exclusive.
+ - Path to a file containing a list of requirements to be installed.
+ - It works for O(type) equals to V(collection) and V(role).
+ - O(name) and O(requirements_file) are mutually exclusive.
type: path
dest:
description:
- - The path to the directory containing your collections or roles, according to the value of O(type).
- - >
- Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file)
- contains both roles and collections and O(dest) is specified.
+ - The path to the directory containing your collections or roles, according to the value of O(type).
+ - Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file) contains
+ both roles and collections and O(dest) is specified.
type: path
no_deps:
description:
- - Refrain from installing dependencies.
+ - Refrain from installing dependencies.
version_added: 4.5.0
type: bool
default: false
force:
description:
- - Force overwriting existing roles and/or collections.
- - It can be used for upgrading, but the module output will always report C(changed=true).
- - Using O(force=true) is mandatory when downgrading.
+ - Force overwriting existing roles and/or collections.
+ - It can be used for upgrading, but the module output will always report C(changed=true).
+ - Using O(force=true) is mandatory when downgrading.
type: bool
default: false
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Install collection community.network
community.general.ansible_galaxy_install:
type: collection
@@ -120,8 +113,7 @@ EXAMPLES = """
force: true
"""
-RETURN = """
----
+RETURN = r"""
type:
description: The value of the O(type) parameter.
type: str
@@ -144,8 +136,8 @@ force:
returned: always
installed_roles:
description:
- - If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path.
- - If O(name) is specified, returns that role name and the version installed per path.
+ - If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path.
+ - If O(name) is specified, returns that role name and the version installed per path.
type: dict
returned: always when installing roles
contains:
@@ -160,13 +152,13 @@ installed_roles:
ansistrano.deploy: 3.8.0
installed_collections:
description:
- - If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path.
- - If O(name) is specified, returns that collection name and the version installed per path.
+ - If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path.
+ - If O(name) is specified, returns that collection name and the version installed per path.
type: dict
returned: always when installing collections
contains:
"":
- description: Collections and versions for that path
+ description: Collections and versions for that path.
type: dict
sample:
/home/az/.ansible/collections/ansible_collections:
diff --git a/plugins/modules/apache2_mod_proxy.py b/plugins/modules/apache2_mod_proxy.py
index 786089d13c..73712d6efc 100644
--- a/plugins/modules/apache2_mod_proxy.py
+++ b/plugins/modules/apache2_mod_proxy.py
@@ -9,19 +9,17 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: apache2_mod_proxy
author: Olivier Boukili (@oboukili)
short_description: Set and/or get members' attributes of an Apache httpd 2.4 mod_proxy balancer pool
description:
- - Set and/or get members' attributes of an Apache httpd 2.4 mod_proxy balancer
- pool, using HTTP POST and GET requests. The httpd mod_proxy balancer-member
- status page has to be enabled and accessible, as this module relies on parsing
- this page. This module supports ansible check_mode, and requires BeautifulSoup
- python module.
+ - Set and/or get members' attributes of an Apache httpd 2.4 mod_proxy balancer pool, using HTTP POST and GET requests. The
+ httpd mod_proxy balancer-member status page has to be enabled and accessible, as this module relies on parsing this page.
extends_documentation_fragment:
- community.general.attributes
+requirements:
+ - Python package C(BeautifulSoup) on Python 2, C(beautifulsoup4) on Python 3.
attributes:
check_mode:
support: full
@@ -31,28 +29,29 @@ options:
balancer_url_suffix:
type: str
description:
- - Suffix of the balancer pool url required to access the balancer pool
- status page (e.g. balancer_vhost[:port]/balancer_url_suffix).
+ - Suffix of the balancer pool URL required to access the balancer pool status page (for example V(balancer_vhost[:port]/balancer_url_suffix)).
default: /balancer-manager/
balancer_vhost:
type: str
description:
- - (ipv4|ipv6|fqdn):port of the Apache httpd 2.4 mod_proxy balancer pool.
+ - (IPv4|IPv6|FQDN):port of the Apache httpd 2.4 mod_proxy balancer pool.
required: true
member_host:
type: str
description:
- - (ipv4|ipv6|fqdn) of the balancer member to get or to set attributes to.
- Port number is autodetected and should not be specified here.
- If undefined, apache2_mod_proxy module will return a members list of
- dictionaries of all the current balancer pool members' attributes.
+ - (IPv4|IPv6|FQDN) of the balancer member to get or to set attributes to. Port number is autodetected and should not
+ be specified here.
+ - If undefined, the M(community.general.apache2_mod_proxy) module will return a members list of dictionaries of all the current
+ balancer pool members' attributes.
state:
- type: str
+ type: list
+ elements: str
+ choices: [present, absent, enabled, disabled, drained, hot_standby, ignore_errors]
description:
- Desired state of the member host.
- (absent|disabled),drained,hot_standby,ignore_errors can be
- simultaneously invoked by separating them with a comma (e.g. state=drained,ignore_errors).
- - 'Accepted state values: ["present", "absent", "enabled", "disabled", "drained", "hot_standby", "ignore_errors"]'
+ - States can be simultaneously invoked by separating them with a comma (for example V(state=drained,ignore_errors)),
+ but it is recommended to specify them as a proper YAML list.
+ - States V(present) and V(absent) must be used without any other state.
tls:
description:
- Use https to access balancer management page.
@@ -63,9 +62,9 @@ options:
- Validate ssl/tls certificates.
type: bool
default: true
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get all current balancer pool members attributes
community.general.apache2_mod_proxy:
balancer_vhost: 10.0.0.2
@@ -110,127 +109,134 @@ EXAMPLES = '''
member_host: '{{ member.host }}'
state: absent
delegate_to: myloadbalancernode
-'''
+"""
-RETURN = '''
+RETURN = r"""
member:
- description: specific balancer member information dictionary, returned when apache2_mod_proxy module is invoked with member_host parameter.
- type: dict
- returned: success
- sample:
- {"attributes":
- {"Busy": "0",
- "Elected": "42",
- "Factor": "1",
- "From": "136K",
- "Load": "0",
- "Route": null,
- "RouteRedir": null,
- "Set": "0",
- "Status": "Init Ok ",
- "To": " 47K",
- "Worker URL": null
- },
- "balancer_url": "http://10.10.0.2/balancer-manager/",
- "host": "10.10.0.20",
- "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.20:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b",
- "path": "/ws",
- "port": 8080,
- "protocol": "http",
- "status": {
- "disabled": false,
- "drained": false,
- "hot_standby": false,
- "ignore_errors": false
- }
+ description: Specific balancer member information dictionary, returned when the module is invoked with O(member_host) parameter.
+ type: dict
+ returned: success
+ sample:
+ {"attributes":
+ {"Busy": "0",
+ "Elected": "42",
+ "Factor": "1",
+ "From": "136K",
+ "Load": "0",
+ "Route": null,
+ "RouteRedir": null,
+ "Set": "0",
+ "Status": "Init Ok ",
+ "To": " 47K",
+ "Worker URL": null
+ },
+ "balancer_url": "http://10.10.0.2/balancer-manager/",
+ "host": "10.10.0.20",
+ "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.20:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b",
+ "path": "/ws",
+ "port": 8080,
+ "protocol": "http",
+ "status": {
+ "disabled": false,
+ "drained": false,
+ "hot_standby": false,
+ "ignore_errors": false
}
+ }
members:
- description: list of member (defined above) dictionaries, returned when apache2_mod_proxy is invoked with no member_host and state args.
- returned: success
- type: list
- sample:
- [{"attributes": {
- "Busy": "0",
- "Elected": "42",
- "Factor": "1",
- "From": "136K",
- "Load": "0",
- "Route": null,
- "RouteRedir": null,
- "Set": "0",
- "Status": "Init Ok ",
- "To": " 47K",
- "Worker URL": null
- },
- "balancer_url": "http://10.10.0.2/balancer-manager/",
- "host": "10.10.0.20",
- "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.20:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b",
- "path": "/ws",
- "port": 8080,
- "protocol": "http",
- "status": {
- "disabled": false,
- "drained": false,
- "hot_standby": false,
- "ignore_errors": false
- }
- },
- {"attributes": {
- "Busy": "0",
- "Elected": "42",
- "Factor": "1",
- "From": "136K",
- "Load": "0",
- "Route": null,
- "RouteRedir": null,
- "Set": "0",
- "Status": "Init Ok ",
- "To": " 47K",
- "Worker URL": null
- },
- "balancer_url": "http://10.10.0.2/balancer-manager/",
- "host": "10.10.0.21",
- "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.21:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b",
- "path": "/ws",
- "port": 8080,
- "protocol": "http",
- "status": {
- "disabled": false,
- "drained": false,
- "hot_standby": false,
- "ignore_errors": false}
- }
- ]
-'''
+ description: List of member (defined above) dictionaries, returned when the module is invoked with no O(member_host) and
+ O(state) args.
+ returned: success
+ type: list
+ sample:
+ [{"attributes": {
+ "Busy": "0",
+ "Elected": "42",
+ "Factor": "1",
+ "From": "136K",
+ "Load": "0",
+ "Route": null,
+ "RouteRedir": null,
+ "Set": "0",
+ "Status": "Init Ok ",
+ "To": " 47K",
+ "Worker URL": null
+ },
+ "balancer_url": "http://10.10.0.2/balancer-manager/",
+ "host": "10.10.0.20",
+ "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.20:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b",
+ "path": "/ws",
+ "port": 8080,
+ "protocol": "http",
+ "status": {
+ "disabled": false,
+ "drained": false,
+ "hot_standby": false,
+ "ignore_errors": false
+ }
+ },
+ {"attributes": {
+ "Busy": "0",
+ "Elected": "42",
+ "Factor": "1",
+ "From": "136K",
+ "Load": "0",
+ "Route": null,
+ "RouteRedir": null,
+ "Set": "0",
+ "Status": "Init Ok ",
+ "To": " 47K",
+ "Worker URL": null
+ },
+ "balancer_url": "http://10.10.0.2/balancer-manager/",
+ "host": "10.10.0.21",
+ "management_url": "http://10.10.0.2/lb/?b=mywsbalancer&w=http://10.10.0.21:8080/ws&nonce=8925436c-79c6-4841-8936-e7d13b79239b",
+ "path": "/ws",
+ "port": 8080,
+ "protocol": "http",
+ "status": {
+ "disabled": false,
+ "drained": false,
+ "hot_standby": false,
+ "ignore_errors": false}
+ }
+ ]
+"""
import re
-import traceback
-from ansible.module_utils.basic import AnsibleModule, missing_required_lib
+from ansible_collections.community.general.plugins.module_utils import deps
+from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper, ModuleHelperException
+
+from ansible.module_utils.common.text.converters import to_text
from ansible.module_utils.urls import fetch_url
-from ansible.module_utils.six import iteritems
+from ansible.module_utils.six import raise_from, PY2
-BEAUTIFUL_SOUP_IMP_ERR = None
-try:
- from BeautifulSoup import BeautifulSoup
-except ImportError:
- BEAUTIFUL_SOUP_IMP_ERR = traceback.format_exc()
- HAS_BEAUTIFULSOUP = False
+if PY2:
+ with deps.declare("BeautifulSoup"):
+ from BeautifulSoup import BeautifulSoup
else:
- HAS_BEAUTIFULSOUP = True
+ with deps.declare("beautifulsoup4"):
+ from bs4 import BeautifulSoup
# balancer member attributes extraction regexp:
-EXPRESSION = r"(b=([\w\.\-]+)&w=(https?|ajp|wss?|ftp|[sf]cgi)://([\w\.\-]+):?(\d*)([/\w\.\-]*)&?[\w\-\=]*)"
+EXPRESSION = re.compile(to_text(r"(b=([\w\.\-]+)&w=(https?|ajp|wss?|ftp|[sf]cgi)://([\w\.\-]+):?(\d*)([/\w\.\-]*)&?[\w\-\=]*)"))
# Apache2 server version extraction regexp:
-APACHE_VERSION_EXPRESSION = r"SERVER VERSION: APACHE/([\d.]+)"
+APACHE_VERSION_EXPRESSION = re.compile(to_text(r"SERVER VERSION: APACHE/([\d.]+)"))
+
+
+def find_all(where, what):
+ if PY2:
+ return where.findAll(what)
+ return where.find_all(what)
def regexp_extraction(string, _regexp, groups=1):
""" Returns the capture group (default=1) specified in the regexp, applied to the string """
- regexp_search = re.search(string=str(string), pattern=str(_regexp))
+ regexp_search = _regexp.search(string)
if regexp_search:
if regexp_search.group(groups) != '':
- return str(regexp_search.group(groups))
+ return regexp_search.group(groups)
return None
@@ -251,33 +257,33 @@ class BalancerMember(object):
"""
def __init__(self, management_url, balancer_url, module):
- self.host = regexp_extraction(management_url, str(EXPRESSION), 4)
- self.management_url = str(management_url)
+ self.host = regexp_extraction(management_url, EXPRESSION, 4)
+ self.management_url = management_url
self.protocol = regexp_extraction(management_url, EXPRESSION, 3)
self.port = regexp_extraction(management_url, EXPRESSION, 5)
self.path = regexp_extraction(management_url, EXPRESSION, 6)
- self.balancer_url = str(balancer_url)
+ self.balancer_url = balancer_url
self.module = module
def get_member_attributes(self):
""" Returns a dictionary of a balancer member's attributes."""
- balancer_member_page = fetch_url(self.module, self.management_url)
+ resp, info = fetch_url(self.module, self.management_url, headers={'Referer': self.management_url})
- if balancer_member_page[1]['status'] != 200:
- self.module.fail_json(msg="Could not get balancer_member_page, check for connectivity! " + balancer_member_page[1])
- else:
- try:
- soup = BeautifulSoup(balancer_member_page[0])
- except TypeError as exc:
- self.module.fail_json(msg="Cannot parse balancer_member_page HTML! " + str(exc))
- else:
- subsoup = soup.findAll('table')[1].findAll('tr')
- keys = subsoup[0].findAll('th')
- for valuesset in subsoup[1::1]:
- if re.search(pattern=self.host, string=str(valuesset)):
- values = valuesset.findAll('td')
- return {keys[x].string: values[x].string for x in range(0, len(keys))}
+ if info['status'] != 200:
+ raise ModuleHelperException("Could not get balancer_member_page, check for connectivity! {0}".format(info))
+
+ try:
+ soup = BeautifulSoup(resp)
+ except TypeError as exc:
+ raise_from(ModuleHelperException("Cannot parse balancer_member_page HTML! {0}".format(exc)), exc)
+
+ subsoup = find_all(find_all(soup, 'table')[1], 'tr')
+ keys = find_all(subsoup[0], 'th')
+ for valuesset in subsoup[1::1]:
+ if re.search(pattern=self.host, string=str(valuesset)):
+ values = find_all(valuesset, 'td')
+ return {keys[x].string: values[x].string for x in range(0, len(keys))}
def get_member_status(self):
""" Returns a dictionary of a balancer member's status attributes."""
@@ -285,8 +291,8 @@ class BalancerMember(object):
'drained': 'Drn',
'hot_standby': 'Stby',
'ignore_errors': 'Ign'}
- actual_status = str(self.attributes['Status'])
- status = {mode: patt in actual_status for mode, patt in iteritems(status_mapping)}
+ actual_status = self.attributes['Status']
+ status = {mode: patt in actual_status for mode, patt in status_mapping.items()}
return status
def set_member_status(self, values):
@@ -297,155 +303,126 @@ class BalancerMember(object):
'ignore_errors': '&w_status_I'}
request_body = regexp_extraction(self.management_url, EXPRESSION, 1)
- values_url = "".join("{0}={1}".format(url_param, 1 if values[mode] else 0) for mode, url_param in iteritems(values_mapping))
+ values_url = "".join("{0}={1}".format(url_param, 1 if values[mode] else 0) for mode, url_param in values_mapping.items())
request_body = "{0}{1}".format(request_body, values_url)
- response = fetch_url(self.module, self.management_url, data=request_body)
- if response[1]['status'] != 200:
- self.module.fail_json(msg="Could not set the member status! " + self.host + " " + response[1]['status'])
+ response, info = fetch_url(self.module, self.management_url, data=request_body, headers={'Referer': self.management_url})
+ if info['status'] != 200:
+ raise ModuleHelperException("Could not set the member status! {0} {1}".format(self.host, info['status']))
attributes = property(get_member_attributes)
status = property(get_member_status, set_member_status)
+ def as_dict(self):
+ return {
+ "host": self.host,
+ "status": self.status,
+ "protocol": self.protocol,
+ "port": self.port,
+ "path": self.path,
+ "attributes": self.attributes,
+ "management_url": self.management_url,
+ "balancer_url": self.balancer_url
+ }
+
class Balancer(object):
""" Apache httpd 2.4 mod_proxy balancer object"""
- def __init__(self, host, suffix, module, members=None, tls=False):
- if tls:
- self.base_url = 'https://' + str(host)
- self.url = 'https://' + str(host) + str(suffix)
- else:
- self.base_url = 'http://' + str(host)
- self.url = 'http://' + str(host) + str(suffix)
+ def __init__(self, module, host, suffix, tls=False):
+ proto = "https" if tls else "http"
+ self.base_url = '{0}://{1}'.format(proto, host)
+ self.url = '{0}://{1}{2}'.format(proto, host, suffix)
self.module = module
self.page = self.fetch_balancer_page()
- if members is None:
- self._members = []
def fetch_balancer_page(self):
""" Returns the balancer management html page as a string for later parsing."""
- page = fetch_url(self.module, str(self.url))
- if page[1]['status'] != 200:
- self.module.fail_json(msg="Could not get balancer page! HTTP status response: " + str(page[1]['status']))
- else:
- content = page[0].read()
- apache_version = regexp_extraction(content.upper(), APACHE_VERSION_EXPRESSION, 1)
- if apache_version:
- if not re.search(pattern=r"2\.4\.[\d]*", string=apache_version):
- self.module.fail_json(msg="This module only acts on an Apache2 2.4+ instance, current Apache2 version: " + str(apache_version))
- return content
- else:
- self.module.fail_json(msg="Could not get the Apache server version from the balancer-manager")
+ resp, info = fetch_url(self.module, self.url)
+ if info['status'] != 200:
+ raise ModuleHelperException("Could not get balancer page! HTTP status response: {0}".format(info['status']))
+
+ content = to_text(resp.read())
+ apache_version = regexp_extraction(content.upper(), APACHE_VERSION_EXPRESSION, 1)
+ if not apache_version:
+ raise ModuleHelperException("Could not get the Apache server version from the balancer-manager")
+
+ if not re.search(pattern=r"2\.4\.[\d]*", string=apache_version):
+ raise ModuleHelperException("This module only acts on an Apache2 2.4+ instance, current Apache2 version: {0}".format(apache_version))
+ return content
def get_balancer_members(self):
""" Returns members of the balancer as a generator object for later iteration."""
try:
soup = BeautifulSoup(self.page)
- except TypeError:
- self.module.fail_json(msg="Cannot parse balancer page HTML! " + str(self.page))
- else:
- for element in soup.findAll('a')[1::1]:
- balancer_member_suffix = str(element.get('href'))
- if not balancer_member_suffix:
- self.module.fail_json(msg="Argument 'balancer_member_suffix' is empty!")
- else:
- yield BalancerMember(str(self.base_url + balancer_member_suffix), str(self.url), self.module)
+ except TypeError as e:
+ raise_from(ModuleHelperException("Cannot parse balancer page HTML! {0}".format(self.page)), e)
+
+ elements = find_all(soup, 'a')
+ for element in elements[1::1]:
+ balancer_member_suffix = element.get('href')
+ if not balancer_member_suffix:
+ raise ModuleHelperException("Argument 'balancer_member_suffix' is empty!")
+
+ yield BalancerMember(self.base_url + balancer_member_suffix, self.url, self.module)
members = property(get_balancer_members)
-def main():
+class ApacheModProxy(ModuleHelper):
""" Initiates module."""
- module = AnsibleModule(
+ module = dict(
argument_spec=dict(
balancer_vhost=dict(required=True, type='str'),
balancer_url_suffix=dict(default="/balancer-manager/", type='str'),
member_host=dict(type='str'),
- state=dict(type='str'),
+ state=dict(type='list', elements='str', choices=['present', 'absent', 'enabled', 'disabled', 'drained', 'hot_standby', 'ignore_errors']),
tls=dict(default=False, type='bool'),
validate_certs=dict(default=True, type='bool')
),
supports_check_mode=True
)
+ use_old_vardict = False
- if HAS_BEAUTIFULSOUP is False:
- module.fail_json(msg=missing_required_lib('BeautifulSoup'), exception=BEAUTIFUL_SOUP_IMP_ERR)
+ def __init_module__(self):
+ deps.validate(self.module)
- if module.params['state'] is not None:
- states = module.params['state'].split(',')
- if (len(states) > 1) and (("present" in states) or ("enabled" in states)):
- module.fail_json(msg="state present/enabled is mutually exclusive with other states!")
+ if len(self.vars.state or []) > 1 and ("present" in self.vars.state or "enabled" in self.vars.state):
+ self.do_raise(msg="states present/enabled are mutually exclusive with other states!")
+
+ self.mybalancer = Balancer(self.module, self.vars.balancer_vhost, self.vars.balancer_url_suffix, tls=self.vars.tls)
+
+ def __run__(self):
+ if self.vars.member_host is None:
+ self.vars.members = [member.as_dict() for member in self.mybalancer.members]
else:
- for _state in states:
- if _state not in ['present', 'absent', 'enabled', 'disabled', 'drained', 'hot_standby', 'ignore_errors']:
- module.fail_json(
- msg="State can only take values amongst 'present', 'absent', 'enabled', 'disabled', 'drained', 'hot_standby', 'ignore_errors'."
- )
- else:
- states = ['None']
+ member_exists = False
+ member_status = {'disabled': False, 'drained': False, 'hot_standby': False, 'ignore_errors': False}
+ for mode in member_status:
+ for state in self.vars.state or []:
+ if mode == state:
+ member_status[mode] = True
+ elif mode == 'disabled' and state == 'absent':
+ member_status[mode] = True
- mybalancer = Balancer(module.params['balancer_vhost'],
- module.params['balancer_url_suffix'],
- module=module,
- tls=module.params['tls'])
+ for member in self.mybalancer.members:
+ if str(member.host) == self.vars.member_host:
+ member_exists = True
+ if self.vars.state is not None:
+ member_status_before = member.status
+ if not self.check_mode:
+ member_status_after = member.status = member_status
+ else:
+ member_status_after = member_status
+ self.changed |= (member_status_before != member_status_after)
+ self.vars.member = member.as_dict()
- if module.params['member_host'] is None:
- json_output_list = []
- for member in mybalancer.members:
- json_output_list.append({
- "host": member.host,
- "status": member.status,
- "protocol": member.protocol,
- "port": member.port,
- "path": member.path,
- "attributes": member.attributes,
- "management_url": member.management_url,
- "balancer_url": member.balancer_url
- })
- module.exit_json(
- changed=False,
- members=json_output_list
- )
- else:
- changed = False
- member_exists = False
- member_status = {'disabled': False, 'drained': False, 'hot_standby': False, 'ignore_errors': False}
- for mode in member_status.keys():
- for state in states:
- if mode == state:
- member_status[mode] = True
- elif mode == 'disabled' and state == 'absent':
- member_status[mode] = True
+ if not member_exists:
+ self.do_raise(msg='{0} is not a member of the balancer {1}!'.format(self.vars.member_host, self.vars.balancer_vhost))
- for member in mybalancer.members:
- if str(member.host) == str(module.params['member_host']):
- member_exists = True
- if module.params['state'] is not None:
- member_status_before = member.status
- if not module.check_mode:
- member_status_after = member.status = member_status
- else:
- member_status_after = member_status
- if member_status_before != member_status_after:
- changed = True
- json_output = {
- "host": member.host,
- "status": member.status,
- "protocol": member.protocol,
- "port": member.port,
- "path": member.path,
- "attributes": member.attributes,
- "management_url": member.management_url,
- "balancer_url": member.balancer_url
- }
- if member_exists:
- module.exit_json(
- changed=changed,
- member=json_output
- )
- else:
- module.fail_json(msg=str(module.params['member_host']) + ' is not a member of the balancer ' + str(module.params['balancer_vhost']) + '!')
+
+def main():
+ ApacheModProxy.execute()
if __name__ == '__main__':
diff --git a/plugins/modules/apache2_module.py b/plugins/modules/apache2_module.py
index a9fd72b24f..cacb870ee0 100644
--- a/plugins/modules/apache2_module.py
+++ b/plugins/modules/apache2_module.py
@@ -9,66 +9,64 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: apache2_module
author:
- - Christian Berendt (@berendt)
- - Ralf Hertel (@n0trax)
- - Robin Roth (@robinro)
+ - Christian Berendt (@berendt)
+ - Ralf Hertel (@n0trax)
+ - Robin Roth (@robinro)
short_description: Enables/disables a module of the Apache2 webserver
description:
- - Enables or disables a specified module of the Apache2 webserver.
+ - Enables or disables a specified module of the Apache2 webserver.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- type: str
- description:
- - Name of the module to enable/disable as given to C(a2enmod/a2dismod).
- required: true
- identifier:
- type: str
- description:
- - Identifier of the module as listed by C(apache2ctl -M).
- This is optional and usually determined automatically by the common convention of
- appending V(_module) to O(name) as well as custom exception for popular modules.
- required: false
- force:
- description:
- - Force disabling of default modules and override Debian warnings.
- required: false
- type: bool
- default: false
- state:
- type: str
- description:
- - Desired state of the module.
- choices: ['present', 'absent']
- default: present
- ignore_configcheck:
- description:
- - Ignore configuration checks about inconsistent module configuration. Especially for mpm_* modules.
- type: bool
- default: false
- warn_mpm_absent:
- description:
- - Control the behavior of the warning process for MPM modules.
- type: bool
- default: true
- version_added: 6.3.0
-requirements: ["a2enmod","a2dismod"]
+ name:
+ type: str
+ description:
+ - Name of the module to enable/disable as given to C(a2enmod)/C(a2dismod).
+ required: true
+ identifier:
+ type: str
+ description:
+ - Identifier of the module as listed by C(apache2ctl -M). This is optional and usually determined automatically by the
+ common convention of appending V(_module) to O(name) as well as custom exception for popular modules.
+ required: false
+ force:
+ description:
+ - Force disabling of default modules and override Debian warnings.
+ required: false
+ type: bool
+ default: false
+ state:
+ type: str
+ description:
+ - Desired state of the module.
+ choices: ['present', 'absent']
+ default: present
+ ignore_configcheck:
+ description:
+ - Ignore configuration checks about inconsistent module configuration. Especially for mpm_* modules.
+ type: bool
+ default: false
+ warn_mpm_absent:
+ description:
+ - Control the behavior of the warning process for MPM modules.
+ type: bool
+ default: true
+ version_added: 6.3.0
+requirements: ["a2enmod", "a2dismod"]
notes:
- - This does not work on RedHat-based distributions. It does work on Debian- and SuSE-based distributions.
- Whether it works on others depend on whether the C(a2enmod) and C(a2dismod) tools are available or not.
-'''
+ - This does not work on RedHat-based distributions. It does work on Debian- and SuSE-based distributions. Whether it works
+ on others depend on whether the C(a2enmod) and C(a2dismod) tools are available or not.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Enable the Apache2 module wsgi
community.general.apache2_module:
state: present
@@ -98,40 +96,40 @@ EXAMPLES = '''
warn_mpm_absent: false
ignore_configcheck: true
loop:
- - module: mpm_event
- state: absent
- - module: mpm_prefork
- state: present
+ - module: mpm_event
+ state: absent
+ - module: mpm_prefork
+ state: present
- name: Enable dump_io module, which is identified as dumpio_module inside apache2
community.general.apache2_module:
state: present
name: dump_io
identifier: dumpio_module
-'''
+"""
-RETURN = '''
+RETURN = r"""
result:
- description: message about action taken
- returned: always
- type: str
+ description: Message about action taken.
+ returned: always
+ type: str
warnings:
- description: list of warning messages
- returned: when needed
- type: list
+ description: List of warning messages.
+ returned: when needed
+ type: list
rc:
- description: return code of underlying command
- returned: failed
- type: int
+ description: Return code of underlying command.
+ returned: failed
+ type: int
stdout:
- description: stdout of underlying command
- returned: failed
- type: str
+ description: The stdout of underlying command.
+ returned: failed
+ type: str
stderr:
- description: stderr of underlying command
- returned: failed
- type: str
-'''
+ description: The stderr of underlying command.
+ returned: failed
+ type: str
+"""
import re
diff --git a/plugins/modules/apk.py b/plugins/modules/apk.py
index 7caefd1357..7f1f83ce56 100644
--- a/plugins/modules/apk.py
+++ b/plugins/modules/apk.py
@@ -12,8 +12,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: apk
short_description: Manages apk packages
description:
@@ -29,15 +28,15 @@ attributes:
options:
available:
description:
- - During upgrade, reset versioned world dependencies and change logic to prefer replacing or downgrading packages (instead of holding them)
- if the currently installed package is no longer available from any repository.
+ - During upgrade, reset versioned world dependencies and change logic to prefer replacing or downgrading packages (instead
+ of holding them) if the currently installed package is no longer available from any repository.
type: bool
default: false
name:
description:
- A package name, like V(foo), or multiple packages, like V(foo,bar).
- - Do not include additional whitespace when specifying multiple packages as a string.
- Prefer YAML lists over comma-separating multiple package names.
+ - Do not include additional whitespace when specifying multiple packages as a string. Prefer YAML lists over comma-separating
+ multiple package names.
type: list
elements: str
no_cache:
@@ -48,8 +47,8 @@ options:
version_added: 1.0.0
repository:
description:
- - A package repository or multiple repositories.
- Unlike with the underlying apk command, this list will override the system repositories rather than supplement them.
+ - A package repository or multiple repositories. Unlike with the underlying apk command, this list will override the
+ system repositories rather than supplement them.
type: list
elements: str
state:
@@ -59,7 +58,7 @@ options:
- V(absent) ensures the package(s) is/are absent. V(removed) can be used as an alias.
- V(latest) ensures the package(s) is/are present and the latest version(s).
default: present
- choices: [ "present", "absent", "latest", "installed", "removed" ]
+ choices: ["present", "absent", "latest", "installed", "removed"]
type: str
update_cache:
description:
@@ -73,17 +72,18 @@ options:
default: false
world:
description:
- - Use a custom world file when checking for explicitly installed packages.
- The file is used only when a value is provided for O(name), and O(state) is set to V(present) or V(latest).
+ - Use a custom world file when checking for explicitly installed packages. The file is used only when a value is provided
+ for O(name), and O(state) is set to V(present) or V(latest).
type: str
default: /etc/apk/world
version_added: 5.4.0
notes:
- - 'O(name) and O(upgrade) are mutually exclusive.'
- - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option.
-'''
+ - O(name) and O(upgrade) are mutually exclusive.
+ - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly
+ to the O(name) option.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Update repositories and install foo package
community.general.apk:
name: foo
@@ -157,15 +157,15 @@ EXAMPLES = '''
name: foo
state: latest
world: /etc/apk/world.custom
-'''
+"""
-RETURN = '''
+RETURN = r"""
packages:
- description: a list of packages that have been changed
- returned: when packages have changed
- type: list
- sample: ['package', 'other-package']
-'''
+ description: A list of packages that have been changed.
+ returned: when packages have changed
+ type: list
+ sample: ['package', 'other-package']
+"""
import re
# Import module snippets.
diff --git a/plugins/modules/apt_repo.py b/plugins/modules/apt_repo.py
index 4c82587d03..87df0064ca 100644
--- a/plugins/modules/apt_repo.py
+++ b/plugins/modules/apt_repo.py
@@ -9,16 +9,15 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: apt_repo
-short_description: Manage APT repositories via apt-repo
+short_description: Manage APT repositories using C(apt-repo)
description:
- - Manages APT repositories using apt-repo tool.
- - See U(https://www.altlinux.org/Apt-repo) for details about apt-repo
+ - Manages APT repositories using C(apt-repo) tool.
+ - See U(https://www.altlinux.org/Apt-repo) for details about C(apt-repo).
notes:
- - This module works on ALT based distros.
- - Does NOT support checkmode, due to a limitation in apt-repo tool.
+ - This module works on ALT based distros.
+ - Does NOT support checkmode, due to a limitation in C(apt-repo) tool.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -35,13 +34,13 @@ options:
state:
description:
- Indicates the desired repository state.
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
type: str
remove_others:
description:
- - Remove other then added repositories
- - Used if O(state=present)
+ - Remove other then added repositories.
+ - Used if O(state=present).
type: bool
default: false
update:
@@ -50,10 +49,10 @@ options:
type: bool
default: false
author:
-- Mikhail Gordeev (@obirvalger)
-'''
+ - Mikhail Gordeev (@obirvalger)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Remove all repositories
community.general.apt_repo:
repo: all
@@ -70,9 +69,9 @@ EXAMPLES = '''
repo: copy:///space/ALT/Sisyphus
state: present
update: true
-'''
+"""
-RETURN = ''' # '''
+RETURN = """ # """
import os
diff --git a/plugins/modules/apt_rpm.py b/plugins/modules/apt_rpm.py
index 3a0b6d805f..5a5ba57faf 100644
--- a/plugins/modules/apt_rpm.py
+++ b/plugins/modules/apt_rpm.py
@@ -11,8 +11,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: apt_rpm
short_description: APT-RPM package manager
description:
@@ -28,18 +27,16 @@ options:
package:
description:
- List of packages to install, upgrade, or remove.
- - Since community.general 8.0.0, may include paths to local C(.rpm) files
- if O(state=installed) or O(state=present), requires C(rpm) python
- module.
- aliases: [ name, pkg ]
+ - Since community.general 8.0.0, may include paths to local C(.rpm) files if O(state=installed) or O(state=present),
+ requires C(rpm) Python module.
+ aliases: [name, pkg]
type: list
elements: str
state:
description:
- Indicates the desired package state.
- - Please note that V(present) and V(installed) are equivalent to V(latest) right now.
- This will change in the future. To simply ensure that a package is installed, without upgrading
- it, use the V(present_not_latest) state.
+ - Please note that V(present) and V(installed) are equivalent to V(latest) right now. This will change in the future.
+ To simply ensure that a package is installed, without upgrading it, use the V(present_not_latest) state.
- The states V(latest) and V(present_not_latest) have been added in community.general 8.6.0.
choices:
- absent
@@ -52,14 +49,15 @@ options:
type: str
update_cache:
description:
- - Run the equivalent of C(apt-get update) before the operation. Can be run as part of the package installation or as a separate step.
+ - Run the equivalent of C(apt-get update) before the operation. Can be run as part of the package installation or as
+ a separate step.
- Default is not to update the cache.
type: bool
default: false
clean:
description:
- - Run the equivalent of C(apt-get clean) to clear out the local repository of retrieved package files. It removes everything but
- the lock file from C(/var/cache/apt/archives/) and C(/var/cache/apt/archives/partial/).
+ - Run the equivalent of C(apt-get clean) to clear out the local repository of retrieved package files. It removes everything
+ but the lock file from C(/var/cache/apt/archives/) and C(/var/cache/apt/archives/partial/).
- Can be run as part of the package installation (clean runs before install) or as a separate step.
type: bool
default: false
@@ -77,13 +75,12 @@ options:
default: false
version_added: 6.5.0
requirements:
- - C(rpm) python package (rpm bindings), optional. Required if O(package)
- option includes local files.
+ - C(rpm) Python package (rpm bindings), optional. Required if O(package) option includes local files.
author:
-- Evgenii Terechkov (@evgkrsk)
-'''
+ - Evgenii Terechkov (@evgkrsk)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install package foo
community.general.apt_rpm:
pkg: foo
@@ -122,7 +119,7 @@ EXAMPLES = '''
update_cache: true
dist_upgrade: true
update_kernel: true
-'''
+"""
import os
import re
diff --git a/plugins/modules/archive.py b/plugins/modules/archive.py
index 6784aa1ac3..4e4b6368ce 100644
--- a/plugins/modules/archive.py
+++ b/plugins/modules/archive.py
@@ -10,17 +10,16 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: archive
short_description: Creates a compressed archive of one or more files or trees
extends_documentation_fragment:
- - files
- - community.general.attributes
+ - files
+ - community.general.attributes
description:
- - Creates or extends an archive.
- - The source and archive are on the remote host, and the archive I(is not) copied to the local host.
- - Source files can be deleted after archival by specifying O(remove=True).
+ - Creates or extends an archive.
+ - The source and archive are on the target host, and the archive I(is not) copied to the controller host.
+ - Source files can be deleted after archival by specifying O(remove=True).
attributes:
check_mode:
support: full
@@ -37,17 +36,19 @@ options:
description:
- The type of compression to use.
type: str
- choices: [ bz2, gz, tar, xz, zip ]
+ choices: [bz2, gz, tar, xz, zip]
default: gz
dest:
description:
- The file name of the destination archive. The parent directory must exists on the remote host.
- - This is required when O(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list.
+ - This is required when O(path) refers to multiple files by either specifying a glob, a directory or multiple paths
+ in a list.
- If the destination archive already exists, it will be truncated and overwritten.
type: path
exclude_path:
description:
- - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from O(path) list and glob expansion.
+ - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from O(path) list and glob
+ expansion.
- Use O(exclusion_patterns) to instead exclude files or subdirectories below any of the paths from the O(path) list.
type: list
elements: path
@@ -72,18 +73,19 @@ options:
type: bool
default: false
notes:
- - Can produce C(gzip), C(bzip2), C(lzma), and C(zip) compressed files or archives.
- - This module uses C(tarfile), C(zipfile), C(gzip), and C(bz2) packages on the target host to create archives.
- These are part of the Python standard library for Python 2 and 3.
+ - Can produce C(gzip), C(bzip2), C(lzma), and C(zip) compressed files or archives.
+ - This module uses C(tarfile), C(zipfile), C(gzip), and C(bz2) packages on the target host to create archives. These are
+ part of the Python standard library for Python 2 and 3.
requirements:
- - Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python 2) if using C(xz) format.
+ - Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python
+ 2) if using C(xz) format.
seealso:
- - module: ansible.builtin.unarchive
+ - module: ansible.builtin.unarchive
author:
- - Ben Doherty (@bendoh)
-'''
+ - Ben Doherty (@bendoh)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Compress directory /path/to/foo/ into /path/to/foo.tgz
community.general.archive:
path: /path/to/foo
@@ -102,28 +104,28 @@ EXAMPLES = r'''
- name: Create a bz2 archive of multiple files, rooted at /path
community.general.archive:
path:
- - /path/to/foo
- - /path/wong/foo
+ - /path/to/foo
+ - /path/wong/foo
dest: /path/file.tar.bz2
format: bz2
- name: Create a bz2 archive of a globbed path, while excluding specific dirnames
community.general.archive:
path:
- - /path/to/foo/*
+ - /path/to/foo/*
dest: /path/file.tar.bz2
exclude_path:
- - /path/to/foo/bar
- - /path/to/foo/baz
+ - /path/to/foo/bar
+ - /path/to/foo/baz
format: bz2
- name: Create a bz2 archive of a globbed path, while excluding a glob of dirnames
community.general.archive:
path:
- - /path/to/foo/*
+ - /path/to/foo/*
dest: /path/file.tar.bz2
exclude_path:
- - /path/to/foo/ba*
+ - /path/to/foo/ba*
format: bz2
- name: Use gzip to compress a single archive (i.e don't archive it first with tar)
@@ -138,45 +140,44 @@ EXAMPLES = r'''
dest: /path/file.tar.gz
format: gz
force_archive: true
-'''
+"""
-RETURN = r'''
+RETURN = r"""
state:
- description:
- The state of the input O(path).
- type: str
- returned: always
+ description: The state of the input O(path).
+ type: str
+ returned: always
dest_state:
- description:
- - The state of the O(dest) file.
- - V(absent) when the file does not exist.
- - V(archive) when the file is an archive.
- - V(compress) when the file is compressed, but not an archive.
- - V(incomplete) when the file is an archive, but some files under O(path) were not found.
- type: str
- returned: success
- version_added: 3.4.0
+ description:
+ - The state of the O(dest) file.
+ - V(absent) when the file does not exist.
+ - V(archive) when the file is an archive.
+ - V(compress) when the file is compressed, but not an archive.
+ - V(incomplete) when the file is an archive, but some files under O(path) were not found.
+ type: str
+ returned: success
+ version_added: 3.4.0
missing:
- description: Any files that were missing from the source.
- type: list
- returned: success
+ description: Any files that were missing from the source.
+ type: list
+ returned: success
archived:
- description: Any files that were compressed or added to the archive.
- type: list
- returned: success
+ description: Any files that were compressed or added to the archive.
+ type: list
+ returned: success
arcroot:
- description: The archive root.
- type: str
- returned: always
+ description: The archive root.
+ type: str
+ returned: always
expanded_paths:
- description: The list of matching paths from paths argument.
- type: list
- returned: always
+ description: The list of matching paths from paths argument.
+ type: list
+ returned: always
expanded_exclude_paths:
- description: The list of matching exclude paths from the exclude_path argument.
- type: list
- returned: always
-'''
+ description: The list of matching exclude paths from the exclude_path argument.
+ type: list
+ returned: always
+"""
import abc
import bz2
diff --git a/plugins/modules/atomic_container.py b/plugins/modules/atomic_container.py
index d1567c8923..aba3827ea0 100644
--- a/plugins/modules/atomic_container.py
+++ b/plugins/modules/atomic_container.py
@@ -9,69 +9,71 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: atomic_container
short_description: Manage the containers on the atomic host platform
description:
- - Manage the containers on the atomic host platform.
- - Allows to manage the lifecycle of a container on the atomic host platform.
+ - Manage the containers on the atomic host platform.
+ - Allows to manage the lifecycle of a container on the atomic host platform.
+deprecated:
+ removed_in: 13.0.0
+ why: Project Atomic was sunset by the end of 2019.
+ alternative: There is none.
author: "Giuseppe Scrivano (@giuseppe)"
-notes:
- - Host should support C(atomic) command
requirements:
- - atomic
+ - atomic
+notes:
+ - According to U(https://projectatomic.io/) the project has been sunset around 2019/2020, in favor of C(podman) and Fedora CoreOS.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
diff_mode:
support: none
options:
- backend:
- description:
- - Define the backend to use for the container.
- required: true
- choices: ["docker", "ostree"]
- type: str
- name:
- description:
- - Name of the container.
- required: true
- type: str
- image:
- description:
- - The image to use to install the container.
- required: true
- type: str
- rootfs:
- description:
- - Define the rootfs of the image.
- type: str
- state:
- description:
- - State of the container.
- choices: ["absent", "latest", "present", "rollback"]
- default: "latest"
- type: str
- mode:
- description:
- - Define if it is an user or a system container.
- choices: ["user", "system"]
- type: str
- values:
- description:
- - Values for the installation of the container.
- - This option is permitted only with mode 'user' or 'system'.
- - The values specified here will be used at installation time as --set arguments for atomic install.
- type: list
- elements: str
- default: []
-'''
-
-EXAMPLES = r'''
+ backend:
+ description:
+ - Define the backend to use for the container.
+ required: true
+ choices: ["docker", "ostree"]
+ type: str
+ name:
+ description:
+ - Name of the container.
+ required: true
+ type: str
+ image:
+ description:
+ - The image to use to install the container.
+ required: true
+ type: str
+ rootfs:
+ description:
+ - Define the rootfs of the image.
+ type: str
+ state:
+ description:
+ - State of the container.
+ choices: ["absent", "latest", "present", "rollback"]
+ default: "latest"
+ type: str
+ mode:
+ description:
+ - Define if it is an user or a system container.
+ choices: ["user", "system"]
+ type: str
+ values:
+ description:
+ - Values for the installation of the container.
+ - This option is permitted only with mode 'user' or 'system'.
+ - The values specified here will be used at installation time as --set arguments for atomic install.
+ type: list
+ elements: str
+ default: []
+"""
+EXAMPLES = r"""
- name: Install the etcd system container
community.general.atomic_container:
name: etcd
@@ -80,7 +82,7 @@ EXAMPLES = r'''
state: latest
mode: system
values:
- - ETCD_NAME=etcd.server
+ - ETCD_NAME=etcd.server
- name: Uninstall the etcd system container
community.general.atomic_container:
@@ -89,15 +91,15 @@ EXAMPLES = r'''
backend: ostree
state: absent
mode: system
-'''
+"""
-RETURN = r'''
+RETURN = r"""
msg:
- description: The command standard output
- returned: always
- type: str
- sample: 'Using default tag: latest ...'
-'''
+ description: The command standard output.
+ returned: always
+ type: str
+ sample: 'Using default tag: latest ...'
+"""
# import module snippets
import traceback
diff --git a/plugins/modules/atomic_host.py b/plugins/modules/atomic_host.py
index ebb74caf16..fb9bfb2e6a 100644
--- a/plugins/modules/atomic_host.py
+++ b/plugins/modules/atomic_host.py
@@ -8,37 +8,41 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: atomic_host
short_description: Manage the atomic host platform
description:
- - Manage the atomic host platform.
- - Rebooting of Atomic host platform should be done outside this module.
+ - Manage the atomic host platform.
+ - Rebooting of Atomic host platform should be done outside this module.
+deprecated:
+ removed_in: 13.0.0
+ why: Project Atomic was sunset by the end of 2019.
+ alternative: There is none.
author:
-- Saravanan KR (@krsacme)
+ - Saravanan KR (@krsacme)
notes:
- - Host should be an atomic platform (verified by existence of '/run/ostree-booted' file).
+ - Host should be an atomic platform (verified by existence of '/run/ostree-booted' file).
+ - According to U(https://projectatomic.io/) the project has been sunset around 2019/2020, in favor of C(podman) and Fedora CoreOS.
requirements:
- atomic
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- revision:
- description:
- - The version number of the atomic host to be deployed.
- - Providing V(latest) will upgrade to the latest available version.
- default: 'latest'
- aliases: [ version ]
- type: str
-'''
+ revision:
+ description:
+ - The version number of the atomic host to be deployed.
+ - Providing V(latest) will upgrade to the latest available version.
+ default: 'latest'
+ aliases: [version]
+ type: str
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Upgrade the atomic host platform to the latest version (atomic host upgrade)
community.general.atomic_host:
revision: latest
@@ -46,15 +50,15 @@ EXAMPLES = r'''
- name: Deploy a specific revision as the atomic host (atomic host deploy 23.130)
community.general.atomic_host:
revision: 23.130
-'''
+"""
-RETURN = r'''
+RETURN = r"""
msg:
- description: The command standard output
- returned: always
- type: str
- sample: 'Already on latest'
-'''
+ description: The command standard output.
+ returned: always
+ type: str
+ sample: 'Already on latest'
+"""
import os
import traceback
diff --git a/plugins/modules/atomic_image.py b/plugins/modules/atomic_image.py
index 4bd15e27ab..28011676af 100644
--- a/plugins/modules/atomic_image.py
+++ b/plugins/modules/atomic_image.py
@@ -8,52 +8,56 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: atomic_image
short_description: Manage the container images on the atomic host platform
description:
- - Manage the container images on the atomic host platform.
- - Allows to execute the commands specified by the RUN label in the container image when present.
+ - Manage the container images on the atomic host platform.
+ - Allows to execute the commands specified by the RUN label in the container image when present.
+deprecated:
+ removed_in: 13.0.0
+ why: Project Atomic was sunset by the end of 2019.
+ alternative: There is none.
author:
-- Saravanan KR (@krsacme)
+ - Saravanan KR (@krsacme)
notes:
- - Host should support C(atomic) command.
+ - According to U(https://projectatomic.io/) the project has been sunset around 2019/2020, in favor of C(podman) and Fedora CoreOS.
requirements:
- atomic
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- backend:
- description:
- - Define the backend where the image is pulled.
- choices: [ 'docker', 'ostree' ]
- type: str
- name:
- description:
- - Name of the container image.
- required: true
- type: str
- state:
- description:
- - The state of the container image.
- - The state V(latest) will ensure container image is upgraded to the latest version and forcefully restart container, if running.
- choices: [ 'absent', 'latest', 'present' ]
- default: 'latest'
- type: str
- started:
- description:
- - Start or Stop the container.
- type: bool
- default: true
-'''
+ backend:
+ description:
+ - Define the backend where the image is pulled.
+ choices: ['docker', 'ostree']
+ type: str
+ name:
+ description:
+ - Name of the container image.
+ required: true
+ type: str
+ state:
+ description:
+ - The state of the container image.
+ - The state V(latest) will ensure container image is upgraded to the latest version and forcefully restart container,
+ if running.
+ choices: ['absent', 'latest', 'present']
+ default: 'latest'
+ type: str
+ started:
+ description:
+ - Start or stop the container.
+ type: bool
+ default: true
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Execute the run command on rsyslog container image (atomic run rhel7/rsyslog)
community.general.atomic_image:
name: rhel7/rsyslog
@@ -64,15 +68,15 @@ EXAMPLES = r'''
name: busybox
state: latest
backend: ostree
-'''
+"""
-RETURN = r'''
+RETURN = r"""
msg:
- description: The command standard output
- returned: always
- type: str
- sample: 'Using default tag: latest ...'
-'''
+ description: The command standard output.
+ returned: always
+ type: str
+ sample: 'Using default tag: latest ...'
+"""
import traceback
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/awall.py b/plugins/modules/awall.py
index f3c2384b5b..b95f36ea8d 100644
--- a/plugins/modules/awall.py
+++ b/plugins/modules/awall.py
@@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: awall
short_description: Manage awall policies
author: Ted Trask (@tdtrask)
description:
- This modules allows for enable/disable/activate of C(awall) policies.
- - Alpine Wall (C(awall)) generates a firewall configuration from the enabled policy files
- and activates the configuration on the system.
+ - Alpine Wall (C(awall)) generates a firewall configuration from the enabled policy files and activates the configuration
+ on the system.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -35,7 +34,7 @@ options:
description:
- Whether the policies should be enabled or disabled.
type: str
- choices: [ disabled, enabled ]
+ choices: [disabled, enabled]
default: enabled
activate:
description:
@@ -45,29 +44,29 @@ options:
type: bool
default: false
notes:
- - At least one of O(name) and O(activate) is required.
-'''
+ - At least one of O(name) and O(activate) is required.
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Enable "foo" and "bar" policy
community.general.awall:
- name: [ foo bar ]
+ name: [foo bar]
state: enabled
- name: Disable "foo" and "bar" policy and activate new rules
community.general.awall:
name:
- - foo
- - bar
+ - foo
+ - bar
state: disabled
activate: false
- name: Activate currently enabled firewall rules
community.general.awall:
activate: true
-'''
+"""
-RETURN = ''' # '''
+RETURN = """ # """
import re
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/beadm.py b/plugins/modules/beadm.py
index 8857fd8464..3d9d8ca651 100644
--- a/plugins/modules/beadm.py
+++ b/plugins/modules/beadm.py
@@ -9,62 +9,59 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: beadm
short_description: Manage ZFS boot environments on FreeBSD/Solaris/illumos systems
description:
- - Create, delete or activate ZFS boot environments.
- - Mount and unmount ZFS boot environments.
+ - Create, delete or activate ZFS boot environments.
+ - Mount and unmount ZFS boot environments.
author: Adam Števko (@xen0l)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - ZFS boot environment name.
- type: str
- required: true
- aliases: [ "be" ]
- snapshot:
- description:
- - If specified, the new boot environment will be cloned from the given
- snapshot or inactive boot environment.
- type: str
+ name:
description:
- description:
- - Associate a description with a new boot environment. This option is
- available only on Solarish platforms.
- type: str
- options:
- description:
- - Create the datasets for new BE with specific ZFS properties.
- - Multiple options can be specified.
- - This option is available only on Solarish platforms.
- type: str
- mountpoint:
- description:
- - Path where to mount the ZFS boot environment.
- type: path
- state:
- description:
- - Create or delete ZFS boot environment.
- type: str
- choices: [ absent, activated, mounted, present, unmounted ]
- default: present
- force:
- description:
- - Specifies if the unmount should be forced.
- type: bool
- default: false
-'''
+ - ZFS boot environment name.
+ type: str
+ required: true
+ aliases: ["be"]
+ snapshot:
+ description:
+ - If specified, the new boot environment will be cloned from the given snapshot or inactive boot environment.
+ type: str
+ description:
+ description:
+ - Associate a description with a new boot environment. This option is available only on Solarish platforms.
+ type: str
+ options:
+ description:
+ - Create the datasets for new BE with specific ZFS properties.
+ - Multiple options can be specified.
+ - This option is available only on Solarish platforms.
+ type: str
+ mountpoint:
+ description:
+ - Path where to mount the ZFS boot environment.
+ type: path
+ state:
+ description:
+ - Create or delete ZFS boot environment.
+ type: str
+ choices: [absent, activated, mounted, present, unmounted]
+ default: present
+ force:
+ description:
+ - Specifies if the unmount should be forced.
+ type: bool
+ default: false
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create ZFS boot environment
community.general.beadm:
name: upgrade-be
@@ -103,45 +100,45 @@ EXAMPLES = r'''
community.general.beadm:
name: upgrade-be
state: activated
-'''
+"""
-RETURN = r'''
+RETURN = r"""
name:
- description: BE name
- returned: always
- type: str
- sample: pre-upgrade
+ description: BE name.
+ returned: always
+ type: str
+ sample: pre-upgrade
snapshot:
- description: ZFS snapshot to create BE from
- returned: always
- type: str
- sample: rpool/ROOT/oi-hipster@fresh
+ description: ZFS snapshot to create BE from.
+ returned: always
+ type: str
+ sample: rpool/ROOT/oi-hipster@fresh
description:
- description: BE description
- returned: always
- type: str
- sample: Upgrade from 9.0 to 10.0
+ description: BE description.
+ returned: always
+ type: str
+ sample: Upgrade from 9.0 to 10.0
options:
- description: BE additional options
- returned: always
- type: str
- sample: compression=on
+ description: BE additional options.
+ returned: always
+ type: str
+ sample: compression=on
mountpoint:
- description: BE mountpoint
- returned: always
- type: str
- sample: /mnt/be
+ description: BE mountpoint.
+ returned: always
+ type: str
+ sample: /mnt/be
state:
- description: state of the target
- returned: always
- type: str
- sample: present
+ description: State of the target.
+ returned: always
+ type: str
+ sample: present
force:
- description: If forced action is wanted
- returned: always
- type: bool
- sample: false
-'''
+ description: If forced action is wanted.
+ returned: always
+ type: bool
+ sample: false
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/bearychat.py b/plugins/modules/bearychat.py
index f52737facd..1dec1bce68 100644
--- a/plugins/modules/bearychat.py
+++ b/plugins/modules/bearychat.py
@@ -7,12 +7,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: bearychat
short_description: Send BearyChat notifications
description:
- - The M(community.general.bearychat) module sends notifications to U(https://bearychat.com)
- via the Incoming Robot integration.
+ - The M(community.general.bearychat) module sends notifications to U(https://bearychat.com) using the Incoming Robot integration.
author: "Jiangge Zhang (@tonyseek)"
extends_documentation_fragment:
- community.general.attributes
@@ -25,8 +24,7 @@ options:
url:
type: str
description:
- - BearyChat WebHook URL. This authenticates you to the bearychat
- service. It looks like
+ - BearyChat WebHook URL. This authenticates you to the bearychat service. It looks like
V(https://hook.bearychat.com/=ae2CF/incoming/e61bd5c57b164e04b11ac02e66f47f60).
required: true
text:
@@ -41,17 +39,16 @@ options:
channel:
type: str
description:
- - Channel to send the message to. If absent, the message goes to the
- default channel selected by the O(url).
+ - Channel to send the message to. If absent, the message goes to the default channel selected by the O(url).
attachments:
type: list
elements: dict
description:
- Define a list of attachments. For more information, see
- https://github.com/bearyinnovative/bearychat-tutorial/blob/master/robots/incoming.md#attachments
-'''
+ U(https://github.com/bearyinnovative/bearychat-tutorial/blob/master/robots/incoming.md#attachments).
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Send notification message via BearyChat
local_action:
module: bearychat
@@ -75,12 +72,12 @@ EXAMPLES = """
- http://example.com/index.png
"""
-RETURN = """
+RETURN = r"""
msg:
- description: execution result
- returned: success
- type: str
- sample: "OK"
+ description: Execution result.
+ returned: success
+ type: str
+ sample: "OK"
"""
try:
diff --git a/plugins/modules/bigpanda.py b/plugins/modules/bigpanda.py
index 7bde5fc1d8..aef9c15c92 100644
--- a/plugins/modules/bigpanda.py
+++ b/plugins/modules/bigpanda.py
@@ -8,13 +8,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: bigpanda
author: "Hagai Kariti (@hkariti)"
short_description: Notify BigPanda about deployments
description:
- - Notify BigPanda when deployments start and end (successfully or not). Returns a deployment object containing all the parameters for future module calls.
+ - Notify BigPanda when deployments start and end (successfully or not). Returns a deployment object containing all the parameters
+ for future module calls.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -26,7 +26,7 @@ options:
component:
type: str
description:
- - "The name of the component being deployed. Ex: billing"
+ - 'The name of the component being deployed. Ex: V(billing).'
required: true
aliases: ['name']
version:
@@ -55,7 +55,7 @@ options:
env:
type: str
description:
- - The environment name, typically 'production', 'staging', etc.
+ - The environment name, typically V(production), V(staging), and so on.
required: false
owner:
type: str
@@ -75,27 +75,27 @@ options:
default: "https://api.bigpanda.io"
validate_certs:
description:
- - If V(false), SSL certificates for the target url will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates for the target URL will not be validated. This should only be used on personally controlled
+ sites using self-signed certificates.
required: false
default: true
type: bool
deployment_message:
type: str
description:
- - Message about the deployment.
+ - Message about the deployment.
version_added: '0.2.0'
source_system:
type: str
description:
- - Source system used in the requests to the API
+ - Source system used in the requests to the API.
default: ansible
# informational: requirements for nodes
-requirements: [ ]
-'''
+requirements: []
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Notify BigPanda about a deployment
community.general.bigpanda:
component: myapp
@@ -128,7 +128,7 @@ EXAMPLES = '''
token: '{{ deployment.token }}'
state: finished
delegate_to: localhost
-'''
+"""
# ===========================================
# Module execution.
diff --git a/plugins/modules/bitbucket_access_key.py b/plugins/modules/bitbucket_access_key.py
index 29c19b8b3d..f78f55d3bb 100644
--- a/plugins/modules/bitbucket_access_key.py
+++ b/plugins/modules/bitbucket_access_key.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: bitbucket_access_key
short_description: Manages Bitbucket repository access keys
description:
@@ -33,7 +32,7 @@ options:
workspace:
description:
- The repository owner.
- - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
+ - B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user).
type: str
required: true
key:
@@ -50,13 +49,13 @@ options:
- Indicates desired state of the access key.
type: str
required: true
- choices: [ absent, present ]
+ choices: [absent, present]
notes:
- Bitbucket OAuth consumer or App password should have permissions to read and administrate account repositories.
- Check mode is supported.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create access key
community.general.bitbucket_access_key:
repository: 'bitbucket-repo'
@@ -71,9 +70,9 @@ EXAMPLES = r'''
workspace: bitbucket_workspace
label: Bitbucket
state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.source_control.bitbucket import BitbucketHelper
diff --git a/plugins/modules/bitbucket_pipeline_key_pair.py b/plugins/modules/bitbucket_pipeline_key_pair.py
index 3bc41c2987..e16af96867 100644
--- a/plugins/modules/bitbucket_pipeline_key_pair.py
+++ b/plugins/modules/bitbucket_pipeline_key_pair.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: bitbucket_pipeline_key_pair
short_description: Manages Bitbucket pipeline SSH key pair
description:
@@ -33,7 +32,7 @@ options:
workspace:
description:
- The repository owner.
- - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
+ - B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user).
type: str
required: true
public_key:
@@ -49,12 +48,12 @@ options:
- Indicates desired state of the key pair.
type: str
required: true
- choices: [ absent, present ]
+ choices: [absent, present]
notes:
- Check mode is supported.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create or update SSH key pair
community.general.bitbucket_pipeline_key_pair:
repository: 'bitbucket-repo'
@@ -68,9 +67,9 @@ EXAMPLES = r'''
repository: bitbucket-repo
workspace: bitbucket_workspace
state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.source_control.bitbucket import BitbucketHelper
diff --git a/plugins/modules/bitbucket_pipeline_known_host.py b/plugins/modules/bitbucket_pipeline_known_host.py
index 3e6c4bfbf1..f5594dc8ac 100644
--- a/plugins/modules/bitbucket_pipeline_known_host.py
+++ b/plugins/modules/bitbucket_pipeline_known_host.py
@@ -8,13 +8,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: bitbucket_pipeline_known_host
short_description: Manages Bitbucket pipeline known hosts
description:
- Manages Bitbucket pipeline known hosts under the "SSH Keys" menu.
- - The host fingerprint will be retrieved automatically, but in case of an error, one can use O(key) field to specify it manually.
+ - The host fingerprint will be retrieved automatically, but in case of an error, one can use O(key) field to specify it
+ manually.
author:
- Evgeniy Krysanov (@catcombo)
extends_documentation_fragment:
@@ -36,7 +36,7 @@ options:
workspace:
description:
- The repository owner.
- - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
+ - B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user).
type: str
required: true
name:
@@ -53,12 +53,12 @@ options:
- Indicates desired state of the record.
type: str
required: true
- choices: [ absent, present ]
+ choices: [absent, present]
notes:
- Check mode is supported.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create known hosts from the list
community.general.bitbucket_pipeline_known_host:
repository: 'bitbucket-repo'
@@ -83,9 +83,9 @@ EXAMPLES = r'''
name: bitbucket.org
key: '{{lookup("file", "bitbucket.pub") }}'
state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
import socket
diff --git a/plugins/modules/bitbucket_pipeline_variable.py b/plugins/modules/bitbucket_pipeline_variable.py
index 1ff8e43753..08a1d3f1e8 100644
--- a/plugins/modules/bitbucket_pipeline_variable.py
+++ b/plugins/modules/bitbucket_pipeline_variable.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: bitbucket_pipeline_variable
short_description: Manages Bitbucket pipeline variables
description:
@@ -33,7 +32,7 @@ options:
workspace:
description:
- The repository owner.
- - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
+ - B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user).
type: str
required: true
name:
@@ -55,13 +54,13 @@ options:
- Indicates desired state of the variable.
type: str
required: true
- choices: [ absent, present ]
+ choices: [absent, present]
notes:
- Check mode is supported.
- For secured values return parameter C(changed) is always V(true).
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create or update pipeline variables from the list
community.general.bitbucket_pipeline_variable:
repository: 'bitbucket-repo'
@@ -71,8 +70,8 @@ EXAMPLES = r'''
secured: '{{ item.secured }}'
state: present
with_items:
- - { name: AWS_ACCESS_KEY, value: ABCD1234, secured: false }
- - { name: AWS_SECRET, value: qwe789poi123vbn0, secured: true }
+ - {name: AWS_ACCESS_KEY, value: ABCD1234, secured: false}
+ - {name: AWS_SECRET, value: qwe789poi123vbn0, secured: true}
- name: Remove pipeline variable
community.general.bitbucket_pipeline_variable:
@@ -80,9 +79,9 @@ EXAMPLES = r'''
workspace: bitbucket_workspace
name: AWS_ACCESS_KEY
state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from ansible.module_utils.basic import AnsibleModule, _load_params
from ansible_collections.community.general.plugins.module_utils.source_control.bitbucket import BitbucketHelper
diff --git a/plugins/modules/bootc_manage.py b/plugins/modules/bootc_manage.py
index 5628ffcca0..44444960df 100644
--- a/plugins/modules/bootc_manage.py
+++ b/plugins/modules/bootc_manage.py
@@ -8,34 +8,32 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: bootc_manage
version_added: 9.3.0
author:
-- Ryan Cook (@cooktheryan)
+ - Ryan Cook (@cooktheryan)
short_description: Bootc Switch and Upgrade
description:
- - This module manages the switching and upgrading of C(bootc).
+ - This module manages the switching and upgrading of C(bootc).
options:
- state:
- description:
- - 'Control to apply the latest image or switch the image.'
- - 'B(Note:) This will not reboot the system.'
- - 'Please use M(ansible.builtin.reboot) to reboot the system.'
- required: true
- type: str
- choices: ['switch', 'latest']
- image:
- description:
- - 'The image to switch to.'
- - 'This is required when O(state=switch).'
- required: false
- type: str
+ state:
+ description:
+ - Control whether to apply the latest image or switch the image.
+ - B(Note:) This will not reboot the system.
+ - Please use M(ansible.builtin.reboot) to reboot the system.
+ required: true
+ type: str
+ choices: ['switch', 'latest']
+ image:
+ description:
+ - The image to switch to.
+ - This is required when O(state=switch).
+ required: false
+ type: str
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# Switch to a different image
- name: Provide image to switch to a different image and retain the current running image
community.general.bootc_manage:
@@ -46,10 +44,10 @@ EXAMPLES = '''
- name: Apply updates of the current running image
community.general.bootc_manage:
state: latest
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/bower.py b/plugins/modules/bower.py
index 1824e68bb8..3e7ebdaecc 100644
--- a/plugins/modules/bower.py
+++ b/plugins/modules/bower.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: bower
-short_description: Manage bower packages with bower
+short_description: Manage bower packages with C(bower)
description:
- - Manage bower packages with bower
+ - Manage bower packages with C(bower).
author: "Michael Warkentin (@mwarkentin)"
extends_documentation_fragment:
- community.general.attributes
@@ -27,39 +26,39 @@ options:
name:
type: str
description:
- - The name of a bower package to install
+ - The name of a bower package to install.
offline:
description:
- - Install packages from local cache, if the packages were installed before
+ - Install packages from local cache, if the packages were installed before.
type: bool
default: false
production:
description:
- - Install with --production flag
+ - Install with C(--production) flag.
type: bool
default: false
path:
type: path
description:
- - The base path where to install the bower packages
+ - The base path where to install the bower packages.
required: true
relative_execpath:
type: path
description:
- - Relative path to bower executable from install path
+ - Relative path to bower executable from install path.
state:
type: str
description:
- - The state of the bower package
+ - The state of the bower package.
default: present
- choices: [ "present", "absent", "latest" ]
+ choices: ["present", "absent", "latest"]
version:
type: str
description:
- - The version to be installed
-'''
+ - The version to be installed.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install "bootstrap" bower package.
community.general.bower:
name: bootstrap
@@ -91,7 +90,8 @@ EXAMPLES = '''
- community.general.bower:
path: /app/location
relative_execpath: node_modules/.bin
-'''
+"""
+
import json
import os
diff --git a/plugins/modules/btrfs_info.py b/plugins/modules/btrfs_info.py
index c367b9ed10..0e432dfaff 100644
--- a/plugins/modules/btrfs_info.py
+++ b/plugins/modules/btrfs_info.py
@@ -7,78 +7,73 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: btrfs_info
short_description: Query btrfs filesystem info
version_added: "6.6.0"
-description: Query status of available btrfs filesystems, including uuid, label, subvolumes and mountpoints.
+description: Query status of available btrfs filesystems, including UUID, label, subvolumes and mountpoints.
author:
- - Gregory Furlong (@gnfzdz)
+ - Gregory Furlong (@gnfzdz)
extends_documentation_fragment:
- - community.general.attributes
- - community.general.attributes.info_module
-'''
-
-EXAMPLES = r'''
+ - community.general.attributes
+ - community.general.attributes.info_module
+"""
+EXAMPLES = r"""
- name: Query information about mounted btrfs filesystems
community.general.btrfs_info:
register: my_btrfs_info
+"""
-'''
-
-RETURN = r'''
-
+RETURN = r"""
filesystems:
- description: Summaries of the current state for all btrfs filesystems found on the target host.
- type: list
- elements: dict
- returned: success
- contains:
- uuid:
- description: A unique identifier assigned to the filesystem.
- type: str
- sample: 96c9c605-1454-49b8-a63a-15e2584c208e
- label:
- description: An optional label assigned to the filesystem.
- type: str
- sample: Tank
- devices:
- description: A list of devices assigned to the filesystem.
- type: list
- sample:
- - /dev/sda1
- - /dev/sdb1
- default_subvolume:
- description: The id of the filesystem's default subvolume.
- type: int
- sample: 5
- subvolumes:
- description: A list of dicts containing metadata for all of the filesystem's subvolumes.
- type: list
- elements: dict
- contains:
- id:
- description: An identifier assigned to the subvolume, unique within the containing filesystem.
- type: int
- sample: 256
- mountpoints:
- description: Paths where the subvolume is mounted on the targeted host.
- type: list
- sample: ['/home']
- parent:
- description: The identifier of this subvolume's parent.
- type: int
- sample: 5
- path:
- description: The full path of the subvolume relative to the btrfs fileystem's root.
- type: str
- sample: /@home
-
-'''
+ description: Summaries of the current state for all btrfs filesystems found on the target host.
+ type: list
+ elements: dict
+ returned: success
+ contains:
+ uuid:
+ description: A unique identifier assigned to the filesystem.
+ type: str
+ sample: 96c9c605-1454-49b8-a63a-15e2584c208e
+ label:
+ description: An optional label assigned to the filesystem.
+ type: str
+ sample: Tank
+ devices:
+ description: A list of devices assigned to the filesystem.
+ type: list
+ sample:
+ - /dev/sda1
+ - /dev/sdb1
+ default_subvolume:
+ description: The ID of the filesystem's default subvolume.
+ type: int
+ sample: 5
+ subvolumes:
+ description: A list of dicts containing metadata for all of the filesystem's subvolumes.
+ type: list
+ elements: dict
+ contains:
+ id:
+ description: An identifier assigned to the subvolume, unique within the containing filesystem.
+ type: int
+ sample: 256
+ mountpoints:
+ description: Paths where the subvolume is mounted on the targeted host.
+ type: list
+ sample: ['/home']
+ parent:
+ description: The identifier of this subvolume's parent.
+ type: int
+ sample: 5
+ path:
+ description: The full path of the subvolume relative to the btrfs fileystem's root.
+ type: str
+ sample: /@home
+"""
from ansible_collections.community.general.plugins.module_utils.btrfs import BtrfsFilesystemsProvider
diff --git a/plugins/modules/btrfs_subvolume.py b/plugins/modules/btrfs_subvolume.py
index 0aa38bf0e4..b1593a8ecd 100644
--- a/plugins/modules/btrfs_subvolume.py
+++ b/plugins/modules/btrfs_subvolume.py
@@ -7,8 +7,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: btrfs_subvolume
short_description: Manage btrfs subvolumes
version_added: "6.6.0"
@@ -16,71 +15,73 @@ version_added: "6.6.0"
description: Creates, updates and deletes btrfs subvolumes and snapshots.
options:
- automount:
- description:
- - Allow the module to temporarily mount the targeted btrfs filesystem in order to validate the current state and make any required changes.
- type: bool
- default: false
- default:
- description:
- - Make the subvolume specified by O(name) the filesystem's default subvolume.
- type: bool
- default: false
- filesystem_device:
- description:
- - A block device contained within the btrfs filesystem to be targeted.
- - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted.
- type: path
- filesystem_label:
- description:
- - A descriptive label assigned to the btrfs filesystem to be targeted.
- - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted.
- type: str
- filesystem_uuid:
- description:
- - A unique identifier assigned to the btrfs filesystem to be targeted.
- - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted.
- type: str
- name:
- description:
- - Name of the subvolume/snapshot to be targeted.
- required: true
- type: str
- recursive:
- description:
- - When true, indicates that parent/child subvolumes should be created/removedas necessary
- to complete the operation (for O(state=present) and O(state=absent) respectively).
- type: bool
- default: false
- snapshot_source:
- description:
- - Identifies the source subvolume for the created snapshot.
- - Infers that the created subvolume is a snapshot.
- type: str
- snapshot_conflict:
- description:
- - Policy defining behavior when a subvolume already exists at the path of the requested snapshot.
- - V(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that no change is required.
- Warning, this option does not yet verify that the target subvolume was generated from a snapshot of the requested source.
- - V(clobber) - If a subvolume already exists at the requested location, delete it first.
- This option is not idempotent and will result in a new snapshot being generated on every execution.
- - V(error) - If a subvolume already exists at the requested location, return an error.
- This option is not idempotent and will result in an error on replay of the module.
- type: str
- choices: [ skip, clobber, error ]
- default: skip
- state:
- description:
- - Indicates the current state of the targeted subvolume.
- type: str
- choices: [ absent, present ]
- default: present
+ automount:
+ description:
+ - Allow the module to temporarily mount the targeted btrfs filesystem in order to validate the current state and make
+ any required changes.
+ type: bool
+ default: false
+ default:
+ description:
+ - Make the subvolume specified by O(name) the filesystem's default subvolume.
+ type: bool
+ default: false
+ filesystem_device:
+ description:
+ - A block device contained within the btrfs filesystem to be targeted.
+ - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted.
+ type: path
+ filesystem_label:
+ description:
+ - A descriptive label assigned to the btrfs filesystem to be targeted.
+ - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted.
+ type: str
+ filesystem_uuid:
+ description:
+ - A unique identifier assigned to the btrfs filesystem to be targeted.
+ - Useful when multiple btrfs filesystems are present to specify which filesystem should be targeted.
+ type: str
+ name:
+ description:
+ - Name of the subvolume/snapshot to be targeted.
+ required: true
+ type: str
+ recursive:
+ description:
+ - When true, indicates that parent/child subvolumes should be created/removedas necessary to complete the operation
+ (for O(state=present) and O(state=absent) respectively).
+ type: bool
+ default: false
+ snapshot_source:
+ description:
+ - Identifies the source subvolume for the created snapshot.
+ - Infers that the created subvolume is a snapshot.
+ type: str
+ snapshot_conflict:
+ description:
+ - Policy defining behavior when a subvolume already exists at the path of the requested snapshot.
+ - V(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that
+ no change is required. Warning, this option does not yet verify that the target subvolume was generated from a snapshot
+ of the requested source.
+ - V(clobber) - If a subvolume already exists at the requested location, delete it first. This option is not idempotent
+ and will result in a new snapshot being generated on every execution.
+ - V(error) - If a subvolume already exists at the requested location, return an error. This option is not idempotent
+ and will result in an error on replay of the module.
+ type: str
+ choices: [skip, clobber, error]
+ default: skip
+ state:
+ description:
+ - Indicates the current state of the targeted subvolume.
+ type: str
+ choices: [absent, present]
+ default: present
notes:
- - If any or all of the options O(filesystem_device), O(filesystem_label) or O(filesystem_uuid) parameters are provided, there is expected
- to be a matching btrfs filesystem. If none are provided and only a single btrfs filesystem exists or only a single
- btrfs filesystem is mounted, that filesystem will be used; otherwise, the module will take no action and return an error.
-
+ - If any or all of the options O(filesystem_device), O(filesystem_label) or O(filesystem_uuid) parameters are provided,
+ there is expected to be a matching btrfs filesystem. If none are provided and only a single btrfs filesystem exists or
+ only a single btrfs filesystem is mounted, that filesystem will be used; otherwise, the module will take no action and
+ return an error.
extends_documentation_fragment:
- community.general.attributes
@@ -88,17 +89,16 @@ attributes:
check_mode:
support: partial
details:
- - In some scenarios it may erroneously report intermediate subvolumes being created.
- After mounting, if a directory like file is found where the subvolume would have been created, the operation is skipped.
+ - In some scenarios it may erroneously report intermediate subvolumes being created. After mounting, if a directory
+ like file is found where the subvolume would have been created, the operation is skipped.
diff_mode:
support: none
author:
- - Gregory Furlong (@gnfzdz)
-'''
-
-EXAMPLES = r'''
+ - Gregory Furlong (@gnfzdz)
+"""
+EXAMPLES = r"""
- name: Create a @home subvolume under the root subvolume
community.general.btrfs_subvolume:
name: /@home
@@ -127,85 +127,83 @@ EXAMPLES = r'''
community.general.btrfs_subvolume:
name: /@snapshots/@2022_06_09
snapshot_source: /@
- recursive: True
+ recursive: true
filesystem_device: /dev/vda2
- name: Remove the /@ subvolume and recursively delete child subvolumes as required
community.general.btrfs_subvolume:
name: /@snapshots/@2022_06_09
snapshot_source: /@
- recursive: True
+ recursive: true
filesystem_device: /dev/vda2
+"""
-'''
-
-RETURN = r'''
-
+RETURN = r"""
filesystem:
- description:
+ description:
- A summary of the final state of the targeted btrfs filesystem.
- type: dict
- returned: success
- contains:
- uuid:
- description: A unique identifier assigned to the filesystem.
- returned: success
- type: str
- sample: 96c9c605-1454-49b8-a63a-15e2584c208e
- label:
- description: An optional label assigned to the filesystem.
- returned: success
- type: str
- sample: Tank
- devices:
- description: A list of devices assigned to the filesystem.
- returned: success
- type: list
- sample:
- - /dev/sda1
- - /dev/sdb1
- default_subvolume:
- description: The ID of the filesystem's default subvolume.
- returned: success and if filesystem is mounted
- type: int
- sample: 5
- subvolumes:
- description: A list of dicts containing metadata for all of the filesystem's subvolumes.
- returned: success and if filesystem is mounted
- type: list
- elements: dict
- contains:
- id:
- description: An identifier assigned to the subvolume, unique within the containing filesystem.
- type: int
- sample: 256
- mountpoints:
- description: Paths where the subvolume is mounted on the targeted host.
- type: list
- sample: ['/home']
- parent:
- description: The identifier of this subvolume's parent.
- type: int
- sample: 5
- path:
- description: The full path of the subvolume relative to the btrfs fileystem's root.
- type: str
- sample: /@home
+ type: dict
+ returned: success
+ contains:
+ uuid:
+ description: A unique identifier assigned to the filesystem.
+ returned: success
+ type: str
+ sample: 96c9c605-1454-49b8-a63a-15e2584c208e
+ label:
+ description: An optional label assigned to the filesystem.
+ returned: success
+ type: str
+ sample: Tank
+ devices:
+ description: A list of devices assigned to the filesystem.
+ returned: success
+ type: list
+ sample:
+ - /dev/sda1
+ - /dev/sdb1
+ default_subvolume:
+ description: The ID of the filesystem's default subvolume.
+ returned: success and if filesystem is mounted
+ type: int
+ sample: 5
+ subvolumes:
+ description: A list of dicts containing metadata for all of the filesystem's subvolumes.
+ returned: success and if filesystem is mounted
+ type: list
+ elements: dict
+ contains:
+ id:
+ description: An identifier assigned to the subvolume, unique within the containing filesystem.
+ type: int
+ sample: 256
+ mountpoints:
+ description: Paths where the subvolume is mounted on the targeted host.
+ type: list
+ sample: ['/home']
+ parent:
+ description: The identifier of this subvolume's parent.
+ type: int
+ sample: 5
+ path:
+ description: The full path of the subvolume relative to the btrfs fileystem's root.
+ type: str
+ sample: /@home
modifications:
- description:
+ description:
- A list where each element describes a change made to the target btrfs filesystem.
- type: list
- returned: Success
- elements: str
+ type: list
+ returned: Success
+ elements: str
target_subvolume_id:
- description:
+ description:
- The ID of the subvolume specified with the O(name) parameter, either pre-existing or created as part of module execution.
- type: int
- sample: 257
- returned: Success and subvolume exists after module execution
-'''
+ type: int
+ sample: 257
+ returned: Success and subvolume exists after module execution
+"""
from ansible_collections.community.general.plugins.module_utils.btrfs import BtrfsFilesystemsProvider, BtrfsCommands, BtrfsModuleException
from ansible_collections.community.general.plugins.module_utils.btrfs import normalize_subvolume_path
diff --git a/plugins/modules/bundler.py b/plugins/modules/bundler.py
index 59f10800c1..bfd7fe7ec1 100644
--- a/plugins/modules/bundler.py
+++ b/plugins/modules/bundler.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: bundler
short_description: Manage Ruby Gem dependencies with Bundler
description:
- - Manage installation and Gem version dependencies for Ruby using the Bundler gem
+ - Manage installation and Gem version dependencies for Ruby using the Bundler gem.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -26,80 +25,72 @@ options:
executable:
type: str
description:
- - The path to the bundler executable
+ - The path to the bundler executable.
state:
type: str
description:
- - The desired state of the Gem bundle. V(latest) updates gems to the most recent, acceptable version
+ - The desired state of the Gem bundle. V(latest) updates gems to the most recent, acceptable version.
choices: [present, latest]
default: present
chdir:
type: path
description:
- - The directory to execute the bundler commands from. This directory
- needs to contain a valid Gemfile or .bundle/ directory
- - If not specified, it will default to the temporary working directory
+ - The directory to execute the bundler commands from. This directory needs to contain a valid Gemfile or .bundle/ directory.
+ - If not specified, it will default to the temporary working directory.
exclude_groups:
type: list
elements: str
description:
- - A list of Gemfile groups to exclude during operations. This only
- applies when O(state=present). Bundler considers this
- a 'remembered' property for the Gemfile and will automatically exclude
- groups in future operations even if O(exclude_groups) is not set
+ - A list of Gemfile groups to exclude during operations. This only applies when O(state=present). Bundler considers
+ this a 'remembered' property for the Gemfile and will automatically exclude groups in future operations even if O(exclude_groups)
+ is not set.
clean:
description:
- - Only applies if O(state=present). If set removes any gems on the
- target host that are not in the gemfile
+ - Only applies if O(state=present). If set removes any gems on the target host that are not in the gemfile.
type: bool
default: false
gemfile:
type: path
description:
- Only applies if O(state=present). The path to the gemfile to use to install gems.
- - If not specified it will default to the Gemfile in current directory
+ - If not specified it will default to the Gemfile in current directory.
local:
description:
- - If set only installs gems from the cache on the target host
+ - If set only installs gems from the cache on the target host.
type: bool
default: false
deployment_mode:
description:
- - Only applies if O(state=present). If set it will install gems in
- ./vendor/bundle instead of the default location. Requires a Gemfile.lock
- file to have been created prior
+ - Only applies if O(state=present). If set it will install gems in C(./vendor/bundle) instead of the default location.
+ Requires a C(Gemfile.lock) file to have been created prior.
type: bool
default: false
user_install:
description:
- - Only applies if O(state=present). Installs gems in the local user's cache or for all users
+ - Only applies if O(state=present). Installs gems in the local user's cache or for all users.
type: bool
default: true
gem_path:
type: path
description:
- - Only applies if O(state=present). Specifies the directory to
- install the gems into. If O(chdir) is set then this path is relative to
- O(chdir)
+ - Only applies if O(state=present). Specifies the directory to install the gems into. If O(chdir) is set then this path
+ is relative to O(chdir).
- If not specified the default RubyGems gem paths will be used.
binstub_directory:
type: path
description:
- - Only applies if O(state=present). Specifies the directory to
- install any gem bins files to. When executed the bin files will run
- within the context of the Gemfile and fail if any required gem
- dependencies are not installed. If O(chdir) is set then this path is
- relative to O(chdir)
+ - Only applies if O(state=present). Specifies the directory to install any gem bins files to. When executed the bin
+ files will run within the context of the Gemfile and fail if any required gem dependencies are not installed. If O(chdir)
+ is set then this path is relative to O(chdir).
extra_args:
type: str
description:
- - A space separated string of additional commands that can be applied to
- the Bundler command. Refer to the Bundler documentation for more
- information
+ - A space separated string of additional commands that can be applied to the Bundler command. Refer to the Bundler documentation
+ for more information.
author: "Tim Hoiberg (@thoiberg)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install gems from a Gemfile in the current directory
community.general.bundler:
state: present
@@ -124,7 +115,7 @@ EXAMPLES = '''
community.general.bundler:
state: latest
chdir: ~/rails_project
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/bzr.py b/plugins/modules/bzr.py
index 5a60d765c7..7a4512a5dd 100644
--- a/plugins/modules/bzr.py
+++ b/plugins/modules/bzr.py
@@ -9,59 +9,55 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: bzr
author:
-- André Paramés (@andreparames)
+ - André Paramés (@andreparames)
short_description: Deploy software (or files) from bzr branches
description:
- - Manage C(bzr) branches to deploy files or software.
+ - Manage C(bzr) branches to deploy files or software.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
diff_mode:
support: none
options:
- name:
- description:
- - SSH or HTTP protocol address of the parent branch.
- aliases: [ parent ]
- required: true
- type: str
- dest:
- description:
- - Absolute path of where the branch should be cloned to.
- required: true
- type: path
- version:
- description:
- - What version of the branch to clone. This can be the
- bzr revno or revid.
- default: head
- type: str
- force:
- description:
- - If V(true), any modified files in the working
- tree will be discarded.
- type: bool
- default: false
- executable:
- description:
- - Path to bzr executable to use. If not supplied,
- the normal mechanism for resolving binary paths will be used.
- type: str
-'''
+ name:
+ description:
+ - SSH or HTTP protocol address of the parent branch.
+ aliases: [parent]
+ required: true
+ type: str
+ dest:
+ description:
+ - Absolute path of where the branch should be cloned to.
+ required: true
+ type: path
+ version:
+ description:
+ - What version of the branch to clone. This can be the bzr revno or revid.
+ default: head
+ type: str
+ force:
+ description:
+ - If V(true), any modified files in the working tree will be discarded.
+ type: bool
+ default: false
+ executable:
+ description:
+ - Path to bzr executable to use. If not supplied, the normal mechanism for resolving binary paths will be used.
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Checkout
community.general.bzr:
name: bzr+ssh://foosball.example.org/path/to/branch
dest: /srv/checkout
version: 22
-'''
+"""
import os
import re
diff --git a/plugins/modules/campfire.py b/plugins/modules/campfire.py
index 1e0f1ecea4..91e83fc7d1 100644
--- a/plugins/modules/campfire.py
+++ b/plugins/modules/campfire.py
@@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: campfire
short_description: Send a message to Campfire
description:
- - Send a message to Campfire.
- - Messages with newlines will result in a "Paste" message being sent.
+ - Send a message to Campfire.
+ - Messages with newlines will result in a "Paste" message being sent.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
@@ -49,22 +48,17 @@ options:
description:
- Send a notification sound before the message.
required: false
- choices: ["56k", "bell", "bezos", "bueller", "clowntown",
- "cottoneyejoe", "crickets", "dadgummit", "dangerzone",
- "danielsan", "deeper", "drama", "greatjob", "greyjoy",
- "guarantee", "heygirl", "horn", "horror",
- "inconceivable", "live", "loggins", "makeitso", "noooo",
- "nyan", "ohmy", "ohyeah", "pushit", "rimshot",
- "rollout", "rumble", "sax", "secret", "sexyback",
- "story", "tada", "tmyk", "trololo", "trombone", "unix",
- "vuvuzela", "what", "whoomp", "yeah", "yodel"]
+ choices: ["56k", "bell", "bezos", "bueller", "clowntown", "cottoneyejoe", "crickets", "dadgummit", "dangerzone", "danielsan",
+ "deeper", "drama", "greatjob", "greyjoy", "guarantee", "heygirl", "horn", "horror", "inconceivable", "live", "loggins",
+ "makeitso", "noooo", "nyan", "ohmy", "ohyeah", "pushit", "rimshot", "rollout", "rumble", "sax", "secret", "sexyback",
+ "story", "tada", "tmyk", "trololo", "trombone", "unix", "vuvuzela", "what", "whoomp", "yeah", "yodel"]
# informational: requirements for nodes
-requirements: [ ]
+requirements: []
author: "Adam Garside (@fabulops)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Send a message to Campfire
community.general.campfire:
subscription: foo
@@ -79,7 +73,7 @@ EXAMPLES = '''
room: 123
notify: loggins
msg: Task completed ... with feeling.
-'''
+"""
try:
from html import escape as html_escape
diff --git a/plugins/modules/capabilities.py b/plugins/modules/capabilities.py
index a0b6d52223..088c15e4f6 100644
--- a/plugins/modules/capabilities.py
+++ b/plugins/modules/capabilities.py
@@ -8,48 +8,47 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: capabilities
short_description: Manage Linux capabilities
description:
- - This module manipulates files privileges using the Linux capabilities(7) system.
+ - This module manipulates files privileges using the Linux capabilities(7) system.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- path:
- description:
- - Specifies the path to the file to be managed.
- type: str
- required: true
- aliases: [ key ]
- capability:
- description:
- - Desired capability to set (with operator and flags, if O(state=present)) or remove (if O(state=absent))
- type: str
- required: true
- aliases: [ cap ]
- state:
- description:
- - Whether the entry should be present or absent in the file's capabilities.
- type: str
- choices: [ absent, present ]
- default: present
+ path:
+ description:
+ - Specifies the path to the file to be managed.
+ type: str
+ required: true
+ aliases: [key]
+ capability:
+ description:
+ - Desired capability to set (with operator and flags, if O(state=present)) or remove (if O(state=absent)).
+ type: str
+ required: true
+ aliases: [cap]
+ state:
+ description:
+ - Whether the entry should be present or absent in the file's capabilities.
+ type: str
+ choices: [absent, present]
+ default: present
notes:
- - The capabilities system will automatically transform operators and flags into the effective set,
- so for example, C(cap_foo=ep) will probably become C(cap_foo+ep).
- - This module does not attempt to determine the final operator and flags to compare,
- so you will want to ensure that your capabilities argument matches the final capabilities.
+ - The capabilities system will automatically transform operators and flags into the effective set, so for example, C(cap_foo=ep)
+ will probably become C(cap_foo+ep).
+ - This module does not attempt to determine the final operator and flags to compare, so you will want to ensure that your
+ capabilities argument matches the final capabilities.
author:
-- Nate Coraor (@natefoo)
-'''
+ - Nate Coraor (@natefoo)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Set cap_sys_chroot+ep on /foo
community.general.capabilities:
path: /foo
@@ -61,7 +60,7 @@ EXAMPLES = r'''
path: /bar
capability: cap_net_bind_service
state: absent
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
@@ -93,7 +92,7 @@ class CapabilitiesModule(object):
if self.module.check_mode:
self.module.exit_json(changed=True, msg='capabilities changed')
else:
- # remove from current cap list if it's already set (but op/flags differ)
+ # remove from current cap list if it is already set (but op/flags differ)
current = list(filter(lambda x: x[0] != self.capability_tup[0], current))
# add new cap with correct op/flags
current.append(self.capability_tup)
diff --git a/plugins/modules/cargo.py b/plugins/modules/cargo.py
index 2fc729da20..94a1102725 100644
--- a/plugins/modules/cargo.py
+++ b/plugins/modules/cargo.py
@@ -11,7 +11,6 @@ __metaclass__ = type
DOCUMENTATION = r"""
----
module: cargo
short_description: Manage Rust packages with cargo
version_added: 4.3.0
@@ -39,16 +38,12 @@ options:
elements: str
required: true
path:
- description:
- ->
- The base path where to install the Rust packages. Cargo automatically appends
- V(/bin). In other words, V(/usr/local) will become V(/usr/local/bin).
+ description: The base path where to install the Rust packages. Cargo automatically appends V(/bin). In other words, V(/usr/local)
+ will become V(/usr/local/bin).
type: path
version:
- description:
- ->
- The version to install. If O(name) contains multiple values, the module will
- try to install all of them in this version.
+ description: The version to install. If O(name) contains multiple values, the module will try to install all of them in
+ this version.
type: str
required: false
locked:
@@ -65,7 +60,7 @@ options:
required: false
type: str
default: present
- choices: [ "present", "absent", "latest" ]
+ choices: ["present", "absent", "latest"]
directory:
description:
- Path to the source directory to install the Rust package from.
@@ -74,7 +69,7 @@ options:
required: false
version_added: 9.1.0
requirements:
- - cargo installed
+ - cargo installed
"""
EXAMPLES = r"""
diff --git a/plugins/modules/catapult.py b/plugins/modules/catapult.py
index acd8398512..5329c90f54 100644
--- a/plugins/modules/catapult.py
+++ b/plugins/modules/catapult.py
@@ -11,14 +11,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: catapult
-short_description: Send a sms / mms using the catapult bandwidth api
+short_description: Send a sms / mms using the catapult bandwidth API
description:
- - Allows notifications to be sent using sms / mms via the catapult bandwidth api.
+ - Allows notifications to be sent using SMS / MMS using the catapult bandwidth API.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
@@ -44,31 +43,30 @@ options:
media:
type: str
description:
- - For MMS messages, a media url to the location of the media to be sent with the message.
+ - For MMS messages, a media URL to the location of the media to be sent with the message.
user_id:
type: str
description:
- - User Id from Api account page.
+ - User ID from API account page.
required: true
api_token:
type: str
description:
- - Api Token from Api account page.
+ - API Token from API account page.
required: true
api_secret:
type: str
description:
- - Api Secret from Api account page.
+ - API Secret from API account page.
required: true
author: "Jonathan Mainguy (@Jmainguy)"
notes:
- - Will return changed even if the media url is wrong.
- - Will return changed if the destination number is invalid.
+ - Will return changed even if the media URL is wrong.
+ - Will return changed if the destination number is invalid.
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Send a mms to multiple users
community.general.catapult:
src: "+15035555555"
@@ -89,16 +87,15 @@ EXAMPLES = '''
user_id: "{{ user_id }}"
api_token: "{{ api_token }}"
api_secret: "{{ api_secret }}"
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
changed:
- description: Whether the api accepted the message.
- returned: always
- type: bool
- sample: true
-'''
+ description: Whether the API accepted the message.
+ returned: always
+ type: bool
+ sample: true
+"""
import json
diff --git a/plugins/modules/circonus_annotation.py b/plugins/modules/circonus_annotation.py
index f3b94a0524..9e563171cd 100644
--- a/plugins/modules/circonus_annotation.py
+++ b/plugins/modules/circonus_annotation.py
@@ -9,62 +9,59 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: circonus_annotation
-short_description: Create an annotation in circonus
+short_description: Create an annotation in Circonus
description:
- - Create an annotation event with a given category, title and description. Optionally start, end or durations can be provided
+ - Create an annotation event with a given category, title and description. Optionally start, end or durations can be provided.
author: "Nick Harring (@NickatEpic)"
requirements:
- - requests (either >= 2.0.0 for Python 3, or >= 1.0.0 for Python 2)
-notes:
- - Check mode isn't supported.
+ - requests (either >= 2.0.0 for Python 3, or >= 1.0.0 for Python 2)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- api_key:
- type: str
- description:
- - Circonus API key
- required: true
- category:
- type: str
- description:
- - Annotation Category
- required: true
+ api_key:
+ type: str
description:
- type: str
- description:
- - Description of annotation
- required: true
- title:
- type: str
- description:
- - Title of annotation
- required: true
- start:
- type: int
- description:
- - Unix timestamp of event start
- - If not specified, it defaults to "now".
- stop:
- type: int
- description:
- - Unix timestamp of event end
- - If not specified, it defaults to "now" + O(duration).
- duration:
- type: int
- description:
- - Duration in seconds of annotation
- default: 0
-'''
-EXAMPLES = '''
+ - Circonus API key.
+ required: true
+ category:
+ type: str
+ description:
+ - Annotation Category.
+ required: true
+ description:
+ type: str
+ description:
+ - Description of annotation.
+ required: true
+ title:
+ type: str
+ description:
+ - Title of annotation.
+ required: true
+ start:
+ type: int
+ description:
+ - Unix timestamp of event start.
+ - If not specified, it defaults to "now".
+ stop:
+ type: int
+ description:
+ - Unix timestamp of event end.
+ - If not specified, it defaults to "now" + O(duration).
+ duration:
+ type: int
+ description:
+ - Duration in seconds of annotation.
+ default: 0
+"""
+EXAMPLES = r"""
- name: Create a simple annotation event with a source, defaults to start and end time of now
community.general.circonus_annotation:
api_key: XXXXXXXXXXXXXXXXX
@@ -88,66 +85,67 @@ EXAMPLES = '''
category: This category groups like annotations
start_time: 1395940006
end_time: 1395954407
-'''
+"""
-RETURN = '''
+RETURN = r"""
annotation:
- description: details about the created annotation
- returned: success
- type: complex
- contains:
- _cid:
- description: annotation identifier
- returned: success
- type: str
- sample: /annotation/100000
- _created:
- description: creation timestamp
- returned: success
- type: int
- sample: 1502236928
- _last_modified:
- description: last modification timestamp
- returned: success
- type: int
- sample: 1502236928
- _last_modified_by:
- description: last modified by
- returned: success
- type: str
- sample: /user/1000
- category:
- description: category of the created annotation
- returned: success
- type: str
- sample: alerts
- title:
- description: title of the created annotation
- returned: success
- type: str
- sample: WARNING
- description:
- description: description of the created annotation
- returned: success
- type: str
- sample: Host is down.
- start:
- description: timestamp, since annotation applies
- returned: success
- type: int
- sample: Host is down.
- stop:
- description: timestamp, since annotation ends
- returned: success
- type: str
- sample: Host is down.
- rel_metrics:
- description: Array of metrics related to this annotation, each metrics is a string.
- returned: success
- type: list
- sample:
- - 54321_kbps
-'''
+ description: Details about the created annotation.
+ returned: success
+ type: complex
+ contains:
+ _cid:
+ description: Annotation identifier.
+ returned: success
+ type: str
+ sample: /annotation/100000
+ _created:
+ description: Creation timestamp.
+ returned: success
+ type: int
+ sample: 1502236928
+ _last_modified:
+ description: Last modification timestamp.
+ returned: success
+ type: int
+ sample: 1502236928
+ _last_modified_by:
+ description: Last modified by.
+ returned: success
+ type: str
+ sample: /user/1000
+ category:
+ description: Category of the created annotation.
+ returned: success
+ type: str
+ sample: alerts
+ title:
+ description: Title of the created annotation.
+ returned: success
+ type: str
+ sample: WARNING
+ description:
+ description: Description of the created annotation.
+ returned: success
+ type: str
+ sample: Host is down.
+ start:
+ description: Timestamp, since annotation applies.
+ returned: success
+ type: int
+ sample: Host is down.
+ stop:
+ description: Timestamp, since annotation ends.
+ returned: success
+ type: str
+ sample: Host is down.
+ rel_metrics:
+ description: Array of metrics related to this annotation, each metrics is a string.
+ returned: success
+ type: list
+ sample:
+ - 54321_kbps
+"""
+
import json
import time
import traceback
diff --git a/plugins/modules/cisco_webex.py b/plugins/modules/cisco_webex.py
index caa77f576d..14b8716846 100644
--- a/plugins/modules/cisco_webex.py
+++ b/plugins/modules/cisco_webex.py
@@ -9,17 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: cisco_webex
short_description: Send a message to a Cisco Webex Teams Room or Individual
description:
- - Send a message to a Cisco Webex Teams Room or Individual with options to control the formatting.
+ - Send a message to a Cisco Webex Teams Room or Individual with options to control the formatting.
author: Drew Rusell (@drew-russell)
notes:
- The O(recipient_type) must be valid for the supplied O(recipient_id).
- Full API documentation can be found at U(https://developer.webex.com/docs/api/basics).
-
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -32,8 +30,8 @@ options:
recipient_type:
description:
- - The request parameter you would like to send the message to.
- - Messages can be sent to either a room or individual (by ID or E-Mail).
+ - The request parameter you would like to send the message to.
+ - Messages can be sent to either a room or individual (by ID or E-Mail).
required: true
choices: ['roomId', 'toPersonEmail', 'toPersonId']
type: str
@@ -46,7 +44,7 @@ options:
msg_type:
description:
- - Specifies how you would like the message formatted.
+ - Specifies how you would like the message formatted.
default: text
choices: ['text', 'markdown']
type: str
@@ -64,9 +62,9 @@ options:
- The message you would like to send.
required: true
type: str
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
# Note: The following examples assume a variable file has been imported
# that contains the appropriate information.
@@ -101,10 +99,9 @@ EXAMPLES = """
msg_type: text
personal_token: "{{ token }}"
msg: "Cisco Webex Teams Ansible Module - Text Message to Individual by E-Mail"
-
"""
-RETURN = """
+RETURN = r"""
status_code:
description:
- The Response Code returned by the Webex Teams API.
@@ -114,12 +111,12 @@ status_code:
sample: 200
message:
- description:
- - The Response Message returned by the Webex Teams API.
- - Full Response Code explanations can be found at U(https://developer.webex.com/docs/api/basics).
- returned: always
- type: str
- sample: OK (585 bytes)
+ description:
+ - The Response Message returned by the Webex Teams API.
+ - Full Response Code explanations can be found at U(https://developer.webex.com/docs/api/basics).
+ returned: always
+ type: str
+ sample: OK (585 bytes)
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url
diff --git a/plugins/modules/clc_aa_policy.py b/plugins/modules/clc_aa_policy.py
index 05135bd957..eb8c57f60c 100644
--- a/plugins/modules/clc_aa_policy.py
+++ b/plugins/modules/clc_aa_policy.py
@@ -9,13 +9,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_aa_policy
-short_description: Create or Delete Anti Affinity Policies at CenturyLink Cloud
+short_description: Create or Delete Anti-Affinity Policies at CenturyLink Cloud
description:
- - An Ansible module to Create or Delete Anti Affinity Policies at CenturyLink Cloud.
+ - An Ansible module to Create or Delete Anti-Affinity Policies at CenturyLink Cloud.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -24,7 +27,7 @@ attributes:
options:
name:
description:
- - The name of the Anti Affinity Policy.
+ - The name of the Anti-Affinity Policy.
type: str
required: true
location:
@@ -38,28 +41,10 @@ options:
type: str
required: false
default: present
- choices: ['present','absent']
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
+ choices: ['present', 'absent']
+"""
-EXAMPLES = '''
-# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples
-
----
+EXAMPLES = r"""
- name: Create AA Policy
hosts: localhost
gather_facts: false
@@ -91,11 +76,11 @@ EXAMPLES = '''
- name: Debug
ansible.builtin.debug:
var: policy
-'''
+"""
-RETURN = '''
+RETURN = r"""
policy:
- description: The anti affinity policy information
+ description: The anti-affinity policy information.
returned: success
type: dict
sample:
@@ -121,7 +106,7 @@ policy:
}
]
}
-'''
+"""
__version__ = '${version}'
diff --git a/plugins/modules/clc_alert_policy.py b/plugins/modules/clc_alert_policy.py
index b77c83e3b7..8075a8436c 100644
--- a/plugins/modules/clc_alert_policy.py
+++ b/plugins/modules/clc_alert_policy.py
@@ -1,6 +1,5 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
-
#
# Copyright (c) 2015 CenturyLink
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
@@ -10,13 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_alert_policy
short_description: Create or Delete Alert Policies at CenturyLink Cloud
description:
- An Ansible module to Create or Delete Alert Policies at CenturyLink Cloud.
+deprecated:
+ removed_in: 11.0.0
+ why: >
+ Lumen Public Cloud (formerly known as CenturyLink Cloud) has gone End-of-Life in September 2023.
+ See more at U(https://www.ctl.io/knowledge-base/release-notes/2023/lumen-public-cloud-platform-end-of-life-notice/?).
+ alternative: There is none.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -25,67 +33,45 @@ attributes:
options:
alias:
description:
- - The alias of your CLC Account
+ - The alias of your CLC Account.
type: str
required: true
name:
description:
- - The name of the alert policy. This is mutually exclusive with id
+ - The name of the alert policy. This is mutually exclusive with O(id).
type: str
id:
description:
- - The alert policy id. This is mutually exclusive with name
+ - The alert policy ID. This is mutually exclusive with O(name).
type: str
alert_recipients:
description:
- - A list of recipient email ids to notify the alert.
- This is required for state 'present'
+ - A list of recipient email IDs to notify the alert. This is required for O(state=present).
type: list
elements: str
metric:
description:
- - The metric on which to measure the condition that will trigger the alert.
- This is required for state 'present'
+ - The metric on which to measure the condition that will trigger the alert. This is required for O(state=present).
type: str
- choices: ['cpu','memory','disk']
+ choices: ['cpu', 'memory', 'disk']
duration:
description:
- - The length of time in minutes that the condition must exceed the threshold.
- This is required for state 'present'
+ - The length of time in minutes that the condition must exceed the threshold. This is required for O(state=present).
type: str
threshold:
description:
- - The threshold that will trigger the alert when the metric equals or exceeds it.
- This is required for state 'present'
- This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0
+ - The threshold that will trigger the alert when the metric equals or exceeds it. This is required for O(state=present).
+ This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.
type: int
state:
description:
- Whether to create or delete the policy.
type: str
default: present
- choices: ['present','absent']
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
+ choices: ['present', 'absent']
+"""
-EXAMPLES = '''
-# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples
-
----
+EXAMPLES = r"""
- name: Create Alert Policy Example
hosts: localhost
gather_facts: false
@@ -96,8 +82,8 @@ EXAMPLES = '''
alias: wfad
name: 'alert for disk > 80%'
alert_recipients:
- - test1@centurylink.com
- - test2@centurylink.com
+ - test1@centurylink.com
+ - test2@centurylink.com
metric: 'disk'
duration: '00:05:00'
threshold: 80
@@ -121,11 +107,11 @@ EXAMPLES = '''
- name: Debug
ansible.builtin.debug: var=policy
-'''
+"""
-RETURN = '''
+RETURN = r"""
policy:
- description: The alert policy information
+ description: The alert policy information.
returned: success
type: dict
sample:
@@ -162,7 +148,7 @@ policy:
}
]
}
-'''
+"""
__version__ = '${version}'
diff --git a/plugins/modules/clc_blueprint_package.py b/plugins/modules/clc_blueprint_package.py
index 672e06780f..2012c0fba3 100644
--- a/plugins/modules/clc_blueprint_package.py
+++ b/plugins/modules/clc_blueprint_package.py
@@ -9,13 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_blueprint_package
short_description: Deploys a blue print package on a set of servers in CenturyLink Cloud
description:
- An Ansible module to deploy blue print package on a set of servers in CenturyLink Cloud.
+deprecated:
+ removed_in: 11.0.0
+ why: >
+ Lumen Public Cloud (formerly known as CenturyLink Cloud) has gone End-of-Life in September 2023.
+ See more at U(https://www.ctl.io/knowledge-base/release-notes/2023/lumen-public-cloud-platform-end-of-life-notice/?).
+ alternative: There is none.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -24,13 +33,13 @@ attributes:
options:
server_ids:
description:
- - A list of server Ids to deploy the blue print package.
+ - A list of server IDs to deploy the blue print package.
type: list
required: true
elements: str
package_id:
description:
- - The package id of the blue print.
+ - The package ID of the blue print.
type: str
required: true
package_params:
@@ -41,7 +50,7 @@ options:
required: false
state:
description:
- - Whether to install or uninstall the package. Currently it supports only "present" for install action.
+ - Whether to install or uninstall the package. Currently it supports only V(present) for install action.
type: str
required: false
default: present
@@ -52,46 +61,27 @@ options:
type: str
default: 'True'
required: false
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples
- name: Deploy package
community.general.clc_blueprint_package:
- server_ids:
- - UC1TEST-SERVER1
- - UC1TEST-SERVER2
- package_id: 77abb844-579d-478d-3955-c69ab4a7ba1a
- package_params: {}
-'''
+ server_ids:
+ - UC1TEST-SERVER1
+ - UC1TEST-SERVER2
+ package_id: 77abb844-579d-478d-3955-c69ab4a7ba1a
+ package_params: {}
+"""
-RETURN = '''
+RETURN = r"""
server_ids:
- description: The list of server ids that are changed
- returned: success
- type: list
- sample:
- [
- "UC1TEST-SERVER1",
- "UC1TEST-SERVER2"
- ]
-'''
+ description: The list of server IDs that are changed.
+ returned: success
+ type: list
+ sample: ["UC1TEST-SERVER1", "UC1TEST-SERVER2"]
+"""
__version__ = '${version}'
diff --git a/plugins/modules/clc_firewall_policy.py b/plugins/modules/clc_firewall_policy.py
index b30037c6fe..37672df7f5 100644
--- a/plugins/modules/clc_firewall_policy.py
+++ b/plugins/modules/clc_firewall_policy.py
@@ -9,13 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_firewall_policy
short_description: Create/delete/update firewall policies
description:
- - Create or delete or update firewall policies on Centurylink Cloud
+ - Create or delete or update firewall policies on Centurylink Cloud.
+deprecated:
+ removed_in: 11.0.0
+ why: >
+ Lumen Public Cloud (formerly known as CenturyLink Cloud) has gone End-of-Life in September 2023.
+ See more at U(https://www.ctl.io/knowledge-base/release-notes/2023/lumen-public-cloud-platform-end-of-life-notice/?).
+ alternative: There is none.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -24,46 +33,43 @@ attributes:
options:
location:
description:
- - Target datacenter for the firewall policy
+ - Target datacenter for the firewall policy.
type: str
required: true
state:
description:
- - Whether to create or delete the firewall policy
+ - Whether to create or delete the firewall policy.
type: str
default: present
choices: ['present', 'absent']
source:
description:
- - The list of source addresses for traffic on the originating firewall.
- This is required when state is 'present'
+ - The list of source addresses for traffic on the originating firewall. This is required when O(state=present).
type: list
elements: str
destination:
description:
- - The list of destination addresses for traffic on the terminating firewall.
- This is required when state is 'present'
+ - The list of destination addresses for traffic on the terminating firewall. This is required when O(state=present).
type: list
elements: str
ports:
description:
- - The list of ports associated with the policy.
- TCP and UDP can take in single ports or port ranges.
+ - The list of ports associated with the policy. TCP and UDP can take in single ports or port ranges.
- "Example: V(['any', 'icmp', 'TCP/123', 'UDP/123', 'TCP/123-456', 'UDP/123-456'])."
type: list
elements: str
firewall_policy_id:
description:
- - Id of the firewall policy. This is required to update or delete an existing firewall policy
+ - ID of the firewall policy. This is required to update or delete an existing firewall policy.
type: str
source_account_alias:
description:
- - CLC alias for the source account
+ - CLC alias for the source account.
type: str
required: true
destination_account_alias:
description:
- - CLC alias for the destination account
+ - CLC alias for the destination account.
type: str
wait:
description:
@@ -72,29 +78,13 @@ options:
default: 'True'
enabled:
description:
- - Whether the firewall policy is enabled or disabled
+ - Whether the firewall policy is enabled or disabled.
type: str
choices: ['True', 'False']
default: 'True'
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
+"""
-EXAMPLES = '''
----
+EXAMPLES = r"""
- name: Create Firewall Policy
hosts: localhost
gather_facts: false
@@ -121,16 +111,16 @@ EXAMPLES = '''
location: VA1
state: absent
firewall_policy_id: c62105233d7a4231bd2e91b9c791e43e1
-'''
+"""
-RETURN = '''
+RETURN = r"""
firewall_policy_id:
- description: The fire wall policy id
- returned: success
- type: str
- sample: fc36f1bfd47242e488a9c44346438c05
+ description: The firewall policy ID.
+ returned: success
+ type: str
+ sample: fc36f1bfd47242e488a9c44346438c05
firewall_policy:
- description: The fire wall policy information
+ description: The firewall policy information.
returned: success
type: dict
sample:
@@ -162,7 +152,7 @@ firewall_policy:
],
"status":"active"
}
-'''
+"""
__version__ = '${version}'
diff --git a/plugins/modules/clc_group.py b/plugins/modules/clc_group.py
index 88aef2d63d..967596ed3e 100644
--- a/plugins/modules/clc_group.py
+++ b/plugins/modules/clc_group.py
@@ -1,6 +1,5 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
-
#
# Copyright (c) 2015 CenturyLink
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
@@ -10,13 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_group
short_description: Create/delete Server Groups at Centurylink Cloud
description:
- - Create or delete Server Groups at Centurylink Centurylink Cloud
+ - Create or delete Server Groups at Centurylink Centurylink Cloud.
+deprecated:
+ removed_in: 11.0.0
+ why: >
+ Lumen Public Cloud (formerly known as CenturyLink Cloud) has gone End-of-Life in September 2023.
+ See more at U(https://www.ctl.io/knowledge-base/release-notes/2023/lumen-public-cloud-platform-end-of-life-notice/?).
+ alternative: There is none.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -25,12 +33,12 @@ attributes:
options:
name:
description:
- - The name of the Server Group
+ - The name of the Server Group.
type: str
required: true
description:
description:
- - A description of the Server Group
+ - A description of the Server Group.
type: str
required: false
parent:
@@ -40,13 +48,13 @@ options:
required: false
location:
description:
- - Datacenter to create the group in. If location is not provided, the group gets created in the default datacenter
- associated with the account
+ - Datacenter to create the group in. If location is not provided, the group gets created in the default datacenter associated
+ with the account.
type: str
required: false
state:
description:
- - Whether to create or delete the group
+ - Whether to create or delete the group.
type: str
default: present
choices: ['present', 'absent']
@@ -56,28 +64,10 @@ options:
type: bool
default: true
required: false
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
-
-EXAMPLES = '''
+"""
+EXAMPLES = r"""
# Create a Server Group
-
----
- name: Create Server Group
hosts: localhost
gather_facts: false
@@ -110,11 +100,11 @@ EXAMPLES = '''
- name: Debug
ansible.builtin.debug:
var: clc
-'''
+"""
-RETURN = '''
+RETURN = r"""
group:
- description: The group information
+ description: The group information.
returned: success
type: dict
sample:
@@ -209,7 +199,7 @@ group:
"status":"active",
"type":"default"
}
-'''
+"""
__version__ = '${version}'
diff --git a/plugins/modules/clc_loadbalancer.py b/plugins/modules/clc_loadbalancer.py
index 675cc1100e..b7db65136d 100644
--- a/plugins/modules/clc_loadbalancer.py
+++ b/plugins/modules/clc_loadbalancer.py
@@ -2,7 +2,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (c) 2015 CenturyLink
-#
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
@@ -10,13 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_loadbalancer
short_description: Create, Delete shared loadbalancers in CenturyLink Cloud
description:
- An Ansible module to Create, Delete shared loadbalancers in CenturyLink Cloud.
+deprecated:
+ removed_in: 11.0.0
+ why: >
+ Lumen Public Cloud (formerly known as CenturyLink Cloud) has gone End-of-Life in September 2023.
+ See more at U(https://www.ctl.io/knowledge-base/release-notes/2023/lumen-public-cloud-platform-end-of-life-notice/?).
+ alternative: There is none.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -25,74 +33,59 @@ attributes:
options:
name:
description:
- - The name of the loadbalancer
+ - The name of the loadbalancer.
type: str
required: true
description:
description:
- - A description for the loadbalancer
+ - A description for the loadbalancer.
type: str
alias:
description:
- - The alias of your CLC Account
+ - The alias of your CLC Account.
type: str
required: true
location:
description:
- - The location of the datacenter where the load balancer resides in
+ - The location of the datacenter where the load balancer resides in.
type: str
required: true
method:
description:
- -The balancing method for the load balancer pool
+ - The balancing method for the load balancer pool.
type: str
choices: ['leastConnection', 'roundRobin']
persistence:
description:
- - The persistence method for the load balancer
+ - The persistence method for the load balancer.
type: str
choices: ['standard', 'sticky']
port:
description:
- - Port to configure on the public-facing side of the load balancer pool
+ - Port to configure on the public-facing side of the load balancer pool.
type: str
choices: ['80', '443']
nodes:
description:
- - A list of nodes that needs to be added to the load balancer pool
+ - A list of nodes that needs to be added to the load balancer pool.
type: list
default: []
elements: dict
status:
description:
- - The status of the loadbalancer
+ - The status of the loadbalancer.
type: str
default: enabled
choices: ['enabled', 'disabled']
state:
description:
- - Whether to create or delete the load balancer pool
+ - Whether to create or delete the load balancer pool.
type: str
default: present
choices: ['present', 'absent', 'port_absent', 'nodes_present', 'nodes_absent']
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples
- name: Create Loadbalancer
hosts: localhost
@@ -173,11 +166,11 @@ EXAMPLES = '''
- ipAddress: 10.11.22.123
privatePort: 80
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
loadbalancer:
- description: The load balancer result object from CLC
+ description: The load balancer result object from CLC.
returned: success
type: dict
sample:
@@ -210,7 +203,7 @@ loadbalancer:
],
"status":"enabled"
}
-'''
+"""
__version__ = '${version}'
diff --git a/plugins/modules/clc_modify_server.py b/plugins/modules/clc_modify_server.py
index b375d9d47a..f40379e748 100644
--- a/plugins/modules/clc_modify_server.py
+++ b/plugins/modules/clc_modify_server.py
@@ -9,13 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_modify_server
short_description: Modify servers in CenturyLink Cloud
description:
- An Ansible module to modify servers in CenturyLink Cloud.
+deprecated:
+ removed_in: 11.0.0
+ why: >
+ Lumen Public Cloud (formerly known as CenturyLink Cloud) has gone End-of-Life in September 2023.
+ See more at U(https://www.ctl.io/knowledge-base/release-notes/2023/lumen-public-cloud-platform-end-of-life-notice/?).
+ alternative: There is none.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -24,13 +33,13 @@ attributes:
options:
server_ids:
description:
- - A list of server Ids to modify.
+ - A list of server IDs to modify.
type: list
required: true
elements: str
cpu:
description:
- - How many CPUs to update on the server
+ - How many CPUs to update on the server.
type: str
memory:
description:
@@ -38,23 +47,19 @@ options:
type: str
anti_affinity_policy_id:
description:
- - The anti affinity policy id to be set for a hyper scale server.
- This is mutually exclusive with 'anti_affinity_policy_name'
+ - The anti affinity policy ID to be set for a hyper scale server. This is mutually exclusive with O(anti_affinity_policy_name).
type: str
anti_affinity_policy_name:
description:
- - The anti affinity policy name to be set for a hyper scale server.
- This is mutually exclusive with 'anti_affinity_policy_id'
+ - The anti affinity policy name to be set for a hyper scale server. This is mutually exclusive with O(anti_affinity_policy_id).
type: str
alert_policy_id:
description:
- - The alert policy id to be associated to the server.
- This is mutually exclusive with 'alert_policy_name'
+ - The alert policy ID to be associated to the server. This is mutually exclusive with O(alert_policy_name).
type: str
alert_policy_name:
description:
- - The alert policy name to be associated to the server.
- This is mutually exclusive with 'alert_policy_id'
+ - The alert policy name to be associated to the server. This is mutually exclusive with O(alert_policy_id).
type: str
state:
description:
@@ -67,96 +72,77 @@ options:
- Whether to wait for the provisioning tasks to finish before returning.
type: bool
default: true
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples
- name: Set the cpu count to 4 on a server
community.general.clc_modify_server:
server_ids:
- - UC1TESTSVR01
- - UC1TESTSVR02
+ - UC1TESTSVR01
+ - UC1TESTSVR02
cpu: 4
state: present
- name: Set the memory to 8GB on a server
community.general.clc_modify_server:
server_ids:
- - UC1TESTSVR01
- - UC1TESTSVR02
+ - UC1TESTSVR01
+ - UC1TESTSVR02
memory: 8
state: present
- name: Set the anti affinity policy on a server
community.general.clc_modify_server:
server_ids:
- - UC1TESTSVR01
- - UC1TESTSVR02
+ - UC1TESTSVR01
+ - UC1TESTSVR02
anti_affinity_policy_name: 'aa_policy'
state: present
- name: Remove the anti affinity policy on a server
community.general.clc_modify_server:
server_ids:
- - UC1TESTSVR01
- - UC1TESTSVR02
+ - UC1TESTSVR01
+ - UC1TESTSVR02
anti_affinity_policy_name: 'aa_policy'
state: absent
- name: Add the alert policy on a server
community.general.clc_modify_server:
server_ids:
- - UC1TESTSVR01
- - UC1TESTSVR02
+ - UC1TESTSVR01
+ - UC1TESTSVR02
alert_policy_name: 'alert_policy'
state: present
- name: Remove the alert policy on a server
community.general.clc_modify_server:
server_ids:
- - UC1TESTSVR01
- - UC1TESTSVR02
+ - UC1TESTSVR01
+ - UC1TESTSVR02
alert_policy_name: 'alert_policy'
state: absent
- name: Ret the memory to 16GB and cpu to 8 core on a lust if servers
community.general.clc_modify_server:
server_ids:
- - UC1TESTSVR01
- - UC1TESTSVR02
+ - UC1TESTSVR01
+ - UC1TESTSVR02
cpu: 8
memory: 16
state: present
-'''
+"""
-RETURN = '''
+RETURN = r"""
server_ids:
- description: The list of server ids that are changed
- returned: success
- type: list
- sample:
- [
- "UC1TEST-SVR01",
- "UC1TEST-SVR02"
- ]
+ description: The list of server IDs that are changed.
+ returned: success
+ type: list
+ sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"]
servers:
- description: The list of server objects that are changed
+ description: The list of server objects that are changed.
returned: success
type: list
sample:
@@ -312,7 +298,7 @@ servers:
"type":"standard"
}
]
-'''
+"""
__version__ = '${version}'
diff --git a/plugins/modules/clc_publicip.py b/plugins/modules/clc_publicip.py
index c1bffcea04..9053638447 100644
--- a/plugins/modules/clc_publicip.py
+++ b/plugins/modules/clc_publicip.py
@@ -9,13 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_publicip
-short_description: Add and Delete public ips on servers in CenturyLink Cloud
+short_description: Add and Delete public IPs on servers in CenturyLink Cloud
description:
- - An Ansible module to add or delete public ip addresses on an existing server or servers in CenturyLink Cloud.
+ - An Ansible module to add or delete public IP addresses on an existing server or servers in CenturyLink Cloud.
+deprecated:
+ removed_in: 11.0.0
+ why: >
+ Lumen Public Cloud (formerly known as CenturyLink Cloud) has gone End-of-Life in September 2023.
+ See more at U(https://www.ctl.io/knowledge-base/release-notes/2023/lumen-public-cloud-platform-end-of-life-notice/?).
+ alternative: There is none.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -30,19 +39,19 @@ options:
choices: ['TCP', 'UDP', 'ICMP']
ports:
description:
- - A list of ports to expose. This is required when state is 'present'
+ - A list of ports to expose. This is required when O(state=present).
type: list
elements: int
server_ids:
description:
- - A list of servers to create public ips on.
+ - A list of servers to create public IPs on.
type: list
required: true
elements: str
state:
description:
- - Determine whether to create or delete public IPs. If present module will not create a second public ip if one
- already exists.
+ - Determine whether to create or delete public IPs. If V(present) module will not create a second public IP if one already
+ exists.
type: str
default: present
choices: ['present', 'absent']
@@ -51,24 +60,9 @@ options:
- Whether to wait for the tasks to finish before returning.
type: bool
default: true
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples
- name: Add Public IP to Server
@@ -107,19 +101,15 @@ EXAMPLES = '''
- name: Debug
ansible.builtin.debug:
var: clc
-'''
+"""
-RETURN = '''
+RETURN = r"""
server_ids:
- description: The list of server ids that are changed
- returned: success
- type: list
- sample:
- [
- "UC1TEST-SVR01",
- "UC1TEST-SVR02"
- ]
-'''
+ description: The list of server IDs that are changed.
+ returned: success
+ type: list
+ sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"]
+"""
__version__ = '${version}'
diff --git a/plugins/modules/clc_server.py b/plugins/modules/clc_server.py
index 6bfe5a9b9e..a843032cec 100644
--- a/plugins/modules/clc_server.py
+++ b/plugins/modules/clc_server.py
@@ -9,13 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_server
short_description: Create, Delete, Start and Stop servers in CenturyLink Cloud
description:
- An Ansible module to Create, Delete, Start and Stop servers in CenturyLink Cloud.
+deprecated:
+ removed_in: 11.0.0
+ why: >
+ Lumen Public Cloud (formerly known as CenturyLink Cloud) has gone End-of-Life in September 2023.
+ See more at U(https://www.ctl.io/knowledge-base/release-notes/2023/lumen-public-cloud-platform-end-of-life-notice/?).
+ alternative: There is none.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -24,13 +33,13 @@ attributes:
options:
additional_disks:
description:
- - The list of additional disks for the server
+ - The list of additional disks for the server.
type: list
elements: dict
default: []
add_public_ip:
description:
- - Whether to add a public ip to the server
+ - Whether to add a public IP to the server.
type: bool
default: false
alias:
@@ -39,32 +48,32 @@ options:
type: str
anti_affinity_policy_id:
description:
- - The anti-affinity policy to assign to the server. This is mutually exclusive with 'anti_affinity_policy_name'.
+ - The anti-affinity policy to assign to the server. This is mutually exclusive with O(anti_affinity_policy_name).
type: str
anti_affinity_policy_name:
description:
- - The anti-affinity policy to assign to the server. This is mutually exclusive with 'anti_affinity_policy_id'.
+ - The anti-affinity policy to assign to the server. This is mutually exclusive with O(anti_affinity_policy_id).
type: str
alert_policy_id:
description:
- - The alert policy to assign to the server. This is mutually exclusive with 'alert_policy_name'.
+ - The alert policy to assign to the server. This is mutually exclusive with O(alert_policy_name).
type: str
alert_policy_name:
description:
- - The alert policy to assign to the server. This is mutually exclusive with 'alert_policy_id'.
+ - The alert policy to assign to the server. This is mutually exclusive with O(alert_policy_id).
type: str
count:
description:
- - The number of servers to build (mutually exclusive with exact_count)
+ - The number of servers to build (mutually exclusive with O(exact_count)).
default: 1
type: int
count_group:
description:
- - Required when exact_count is specified. The Server Group use to determine how many servers to deploy.
+ - Required when exact_count is specified. The Server Group use to determine how many servers to deploy.
type: str
cpu:
description:
- - How many CPUs to provision on the server
+ - How many CPUs to provision on the server.
default: 1
type: int
cpu_autoscale_policy_id:
@@ -83,8 +92,8 @@ options:
type: str
exact_count:
description:
- - Run in idempotent mode. Will insure that this exact number of servers are running in the provided group,
- creating and deleting them to reach that count. Requires count_group to be set.
+ - Run in idempotent mode. Will insure that this exact number of servers are running in the provided group, creating
+ and deleting them to reach that count. Requires O(count_group) to be set.
type: int
group:
description:
@@ -112,7 +121,7 @@ options:
default: 1
name:
description:
- - A 1 to 6 character identifier to use for the server. This is required when state is 'present'
+ - A 1 to 6 character identifier to use for the server. This is required when O(state=present).
type: str
network_id:
description:
@@ -126,7 +135,7 @@ options:
default: []
password:
description:
- - Password for the administrator / root user
+ - Password for the administrator / root user.
type: str
primary_dns:
description:
@@ -134,13 +143,13 @@ options:
type: str
public_ip_protocol:
description:
- - The protocol to use for the public ip if add_public_ip is set to True.
+ - The protocol to use for the public IP if O(add_public_ip=true).
type: str
default: 'TCP'
choices: ['TCP', 'UDP', 'ICMP']
public_ip_ports:
description:
- - A list of ports to allow on the firewall to the servers public ip, if add_public_ip is set to True.
+ - A list of ports to allow on the firewall to the servers public IP, if O(add_public_ip=true).
type: list
elements: dict
default: []
@@ -150,8 +159,7 @@ options:
type: str
server_ids:
description:
- - Required for started, stopped, and absent states.
- A list of server Ids to insure are started, stopped, or absent.
+ - Required for started, stopped, and absent states. A list of server IDs to ensure are started, stopped, or absent.
type: list
default: []
elements: str
@@ -173,12 +181,12 @@ options:
choices: ['standard', 'hyperscale']
template:
description:
- - The template to use for server creation. Will search for a template if a partial string is provided.
- This is required when state is 'present'
+ - The template to use for server creation. Will search for a template if a partial string is provided. This is required
+ when O(state=present).
type: str
ttl:
description:
- - The time to live for the server in seconds. The server will be deleted when this time expires.
+ - The time to live for the server in seconds. The server will be deleted when this time expires.
type: str
type:
description:
@@ -188,13 +196,12 @@ options:
choices: ['standard', 'hyperscale', 'bareMetal']
configuration_id:
description:
- - Only required for bare metal servers.
- Specifies the identifier for the specific configuration type of bare metal server to deploy.
+ - Only required for bare metal servers. Specifies the identifier for the specific configuration type of bare metal server
+ to deploy.
type: str
os_type:
description:
- - Only required for bare metal servers.
- Specifies the OS to provision with the bare metal server.
+ - Only required for bare metal servers. Specifies the OS to provision with the bare metal server.
type: str
choices: ['redHat6_64Bit', 'centOS6_64Bit', 'windows2012R2Standard_64Bit', 'ubuntu14_64Bit']
wait:
@@ -202,24 +209,9 @@ options:
- Whether to wait for the provisioning tasks to finish before returning.
type: bool
default: true
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples
- name: Provision a single Ubuntu Server
@@ -255,185 +247,177 @@ EXAMPLES = '''
server_ids:
- UC1ACCT-TEST01
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
server_ids:
- description: The list of server ids that are created
- returned: success
- type: list
- sample:
- [
- "UC1TEST-SVR01",
- "UC1TEST-SVR02"
- ]
+ description: The list of server IDs that are created.
+ returned: success
+ type: list
+ sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"]
partially_created_server_ids:
- description: The list of server ids that are partially created
- returned: success
- type: list
- sample:
- [
- "UC1TEST-SVR01",
- "UC1TEST-SVR02"
- ]
+ description: The list of server IDs that are partially created.
+ returned: success
+ type: list
+ sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"]
servers:
- description: The list of server objects returned from CLC
- returned: success
- type: list
- sample:
- [
- {
- "changeInfo":{
- "createdBy":"service.wfad",
- "createdDate":1438196820,
- "modifiedBy":"service.wfad",
- "modifiedDate":1438196820
- },
- "description":"test-server",
- "details":{
- "alertPolicies":[
+ description: The list of server objects returned from CLC.
+ returned: success
+ type: list
+ sample:
+ [
+ {
+ "changeInfo":{
+ "createdBy":"service.wfad",
+ "createdDate":1438196820,
+ "modifiedBy":"service.wfad",
+ "modifiedDate":1438196820
+ },
+ "description":"test-server",
+ "details":{
+ "alertPolicies":[
- ],
- "cpu":1,
- "customFields":[
+ ],
+ "cpu":1,
+ "customFields":[
- ],
- "diskCount":3,
- "disks":[
- {
- "id":"0:0",
- "partitionPaths":[
+ ],
+ "diskCount":3,
+ "disks":[
+ {
+ "id":"0:0",
+ "partitionPaths":[
- ],
- "sizeGB":1
- },
- {
- "id":"0:1",
- "partitionPaths":[
+ ],
+ "sizeGB":1
+ },
+ {
+ "id":"0:1",
+ "partitionPaths":[
- ],
- "sizeGB":2
- },
- {
- "id":"0:2",
- "partitionPaths":[
+ ],
+ "sizeGB":2
+ },
+ {
+ "id":"0:2",
+ "partitionPaths":[
- ],
- "sizeGB":14
- }
- ],
- "hostName":"",
- "inMaintenanceMode":false,
- "ipAddresses":[
- {
- "internal":"10.1.1.1"
- }
- ],
- "memoryGB":1,
- "memoryMB":1024,
- "partitions":[
+ ],
+ "sizeGB":14
+ }
+ ],
+ "hostName":"",
+ "inMaintenanceMode":false,
+ "ipAddresses":[
+ {
+ "internal":"10.1.1.1"
+ }
+ ],
+ "memoryGB":1,
+ "memoryMB":1024,
+ "partitions":[
- ],
- "powerState":"started",
- "snapshots":[
+ ],
+ "powerState":"started",
+ "snapshots":[
- ],
- "storageGB":17
- },
- "groupId":"086ac1dfe0b6411989e8d1b77c4065f0",
- "id":"test-server",
- "ipaddress":"10.120.45.23",
- "isTemplate":false,
- "links":[
- {
- "href":"/v2/servers/wfad/test-server",
- "id":"test-server",
- "rel":"self",
- "verbs":[
- "GET",
- "PATCH",
- "DELETE"
- ]
- },
- {
- "href":"/v2/groups/wfad/086ac1dfe0b6411989e8d1b77c4065f0",
- "id":"086ac1dfe0b6411989e8d1b77c4065f0",
- "rel":"group"
- },
- {
- "href":"/v2/accounts/wfad",
- "id":"wfad",
- "rel":"account"
- },
- {
- "href":"/v2/billing/wfad/serverPricing/test-server",
- "rel":"billing"
- },
- {
- "href":"/v2/servers/wfad/test-server/publicIPAddresses",
- "rel":"publicIPAddresses",
- "verbs":[
- "POST"
- ]
- },
- {
- "href":"/v2/servers/wfad/test-server/credentials",
- "rel":"credentials"
- },
- {
- "href":"/v2/servers/wfad/test-server/statistics",
- "rel":"statistics"
- },
- {
- "href":"/v2/servers/wfad/510ec21ae82d4dc89d28479753bf736a/upcomingScheduledActivities",
- "rel":"upcomingScheduledActivities"
- },
- {
- "href":"/v2/servers/wfad/510ec21ae82d4dc89d28479753bf736a/scheduledActivities",
- "rel":"scheduledActivities",
- "verbs":[
- "GET",
- "POST"
- ]
- },
- {
- "href":"/v2/servers/wfad/test-server/capabilities",
- "rel":"capabilities"
- },
- {
- "href":"/v2/servers/wfad/test-server/alertPolicies",
- "rel":"alertPolicyMappings",
- "verbs":[
- "POST"
- ]
- },
- {
- "href":"/v2/servers/wfad/test-server/antiAffinityPolicy",
- "rel":"antiAffinityPolicyMapping",
- "verbs":[
- "PUT",
- "DELETE"
- ]
- },
- {
- "href":"/v2/servers/wfad/test-server/cpuAutoscalePolicy",
- "rel":"cpuAutoscalePolicyMapping",
- "verbs":[
- "PUT",
- "DELETE"
- ]
- }
- ],
- "locationId":"UC1",
- "name":"test-server",
- "os":"ubuntu14_64Bit",
- "osType":"Ubuntu 14 64-bit",
- "status":"active",
- "storageType":"standard",
- "type":"standard"
- }
- ]
-'''
+ ],
+ "storageGB":17
+ },
+ "groupId":"086ac1dfe0b6411989e8d1b77c4065f0",
+ "id":"test-server",
+ "ipaddress":"10.120.45.23",
+ "isTemplate":false,
+ "links":[
+ {
+ "href":"/v2/servers/wfad/test-server",
+ "id":"test-server",
+ "rel":"self",
+ "verbs":[
+ "GET",
+ "PATCH",
+ "DELETE"
+ ]
+ },
+ {
+ "href":"/v2/groups/wfad/086ac1dfe0b6411989e8d1b77c4065f0",
+ "id":"086ac1dfe0b6411989e8d1b77c4065f0",
+ "rel":"group"
+ },
+ {
+ "href":"/v2/accounts/wfad",
+ "id":"wfad",
+ "rel":"account"
+ },
+ {
+ "href":"/v2/billing/wfad/serverPricing/test-server",
+ "rel":"billing"
+ },
+ {
+ "href":"/v2/servers/wfad/test-server/publicIPAddresses",
+ "rel":"publicIPAddresses",
+ "verbs":[
+ "POST"
+ ]
+ },
+ {
+ "href":"/v2/servers/wfad/test-server/credentials",
+ "rel":"credentials"
+ },
+ {
+ "href":"/v2/servers/wfad/test-server/statistics",
+ "rel":"statistics"
+ },
+ {
+ "href":"/v2/servers/wfad/510ec21ae82d4dc89d28479753bf736a/upcomingScheduledActivities",
+ "rel":"upcomingScheduledActivities"
+ },
+ {
+ "href":"/v2/servers/wfad/510ec21ae82d4dc89d28479753bf736a/scheduledActivities",
+ "rel":"scheduledActivities",
+ "verbs":[
+ "GET",
+ "POST"
+ ]
+ },
+ {
+ "href":"/v2/servers/wfad/test-server/capabilities",
+ "rel":"capabilities"
+ },
+ {
+ "href":"/v2/servers/wfad/test-server/alertPolicies",
+ "rel":"alertPolicyMappings",
+ "verbs":[
+ "POST"
+ ]
+ },
+ {
+ "href":"/v2/servers/wfad/test-server/antiAffinityPolicy",
+ "rel":"antiAffinityPolicyMapping",
+ "verbs":[
+ "PUT",
+ "DELETE"
+ ]
+ },
+ {
+ "href":"/v2/servers/wfad/test-server/cpuAutoscalePolicy",
+ "rel":"cpuAutoscalePolicyMapping",
+ "verbs":[
+ "PUT",
+ "DELETE"
+ ]
+ }
+ ],
+ "locationId":"UC1",
+ "name":"test-server",
+ "os":"ubuntu14_64Bit",
+ "osType":"Ubuntu 14 64-bit",
+ "status":"active",
+ "storageType":"standard",
+ "type":"standard"
+ }
+ ]
+"""
__version__ = '${version}'
@@ -816,7 +800,7 @@ class ClcServer:
@staticmethod
def _validate_name(module):
"""
- Validate that name is the correct length if provided, fail if it's not
+ Validate that name is the correct length if provided, fail if it is not
:param module: the module to validate
:return: none
"""
diff --git a/plugins/modules/clc_server_snapshot.py b/plugins/modules/clc_server_snapshot.py
index 82b2a99568..2550d0d936 100644
--- a/plugins/modules/clc_server_snapshot.py
+++ b/plugins/modules/clc_server_snapshot.py
@@ -9,13 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: clc_server_snapshot
short_description: Create, Delete and Restore server snapshots in CenturyLink Cloud
description:
- An Ansible module to Create, Delete and Restore server snapshots in CenturyLink Cloud.
+deprecated:
+ removed_in: 11.0.0
+ why: >
+ Lumen Public Cloud (formerly known as CenturyLink Cloud) has gone End-of-Life in September 2023.
+ See more at U(https://www.ctl.io/knowledge-base/release-notes/2023/lumen-public-cloud-platform-end-of-life-notice/?).
+ alternative: There is none.
extends_documentation_fragment:
- community.general.attributes
+ - community.general.clc
+author:
+ - "CLC Runner (@clc-runner)"
attributes:
check_mode:
support: full
@@ -24,7 +33,7 @@ attributes:
options:
server_ids:
description:
- - The list of CLC server Ids.
+ - The list of CLC server IDs.
type: list
required: true
elements: str
@@ -47,31 +56,16 @@ options:
default: 'True'
required: false
type: str
-requirements:
- - python = 2.7
- - requests >= 2.5.0
- - clc-sdk
-author: "CLC Runner (@clc-runner)"
-notes:
- - To use this module, it is required to set the below environment variables which enables access to the
- Centurylink Cloud
- - CLC_V2_API_USERNAME, the account login id for the centurylink cloud
- - CLC_V2_API_PASSWORD, the account password for the centurylink cloud
- - Alternatively, the module accepts the API token and account alias. The API token can be generated using the
- CLC account login and password via the HTTP api call @ https://api.ctl.io/v2/authentication/login
- - CLC_V2_API_TOKEN, the API token generated from https://api.ctl.io/v2/authentication/login
- - CLC_ACCT_ALIAS, the account alias associated with the centurylink cloud
- - Users can set CLC_V2_API_URL to specify an endpoint for pointing to a different CLC environment.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Note - You must set the CLC_V2_API_USERNAME And CLC_V2_API_PASSWD Environment variables before running these examples
- name: Create server snapshot
community.general.clc_server_snapshot:
server_ids:
- - UC1TEST-SVR01
- - UC1TEST-SVR02
+ - UC1TEST-SVR01
+ - UC1TEST-SVR02
expiration_days: 10
wait: true
state: present
@@ -79,31 +73,27 @@ EXAMPLES = '''
- name: Restore server snapshot
community.general.clc_server_snapshot:
server_ids:
- - UC1TEST-SVR01
- - UC1TEST-SVR02
+ - UC1TEST-SVR01
+ - UC1TEST-SVR02
wait: true
state: restore
- name: Delete server snapshot
community.general.clc_server_snapshot:
server_ids:
- - UC1TEST-SVR01
- - UC1TEST-SVR02
+ - UC1TEST-SVR01
+ - UC1TEST-SVR02
wait: true
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
server_ids:
- description: The list of server ids that are changed
- returned: success
- type: list
- sample:
- [
- "UC1TEST-SVR01",
- "UC1TEST-SVR02"
- ]
-'''
+ description: The list of server IDs that are changed.
+ returned: success
+ type: list
+ sample: ["UC1TEST-SVR01", "UC1TEST-SVR02"]
+"""
__version__ = '${version}'
diff --git a/plugins/modules/cloud_init_data_facts.py b/plugins/modules/cloud_init_data_facts.py
index d8209cc61a..dd9825858e 100644
--- a/plugins/modules/cloud_init_data_facts.py
+++ b/plugins/modules/cloud_init_data_facts.py
@@ -8,12 +8,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: cloud_init_data_facts
short_description: Retrieve facts of cloud-init
description:
- - Gathers facts by reading the status.json and result.json of cloud-init.
+ - Gathers facts by reading the C(status.json) and C(result.json) of cloud-init.
author: René Moser (@resmo)
extends_documentation_fragment:
- community.general.attributes
@@ -22,14 +21,14 @@ extends_documentation_fragment:
options:
filter:
description:
- - Filter facts
+ - Filter facts.
type: str
- choices: [ status, result ]
+ choices: [status, result]
notes:
- See http://cloudinit.readthedocs.io/ for more information about cloud-init.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather all facts of cloud init
community.general.cloud_init_data_facts:
register: result
@@ -44,10 +43,9 @@ EXAMPLES = '''
until: "res.cloud_init_data_facts.status.v1.stage is defined and not res.cloud_init_data_facts.status.v1.stage"
retries: 50
delay: 5
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
cloud_init_data_facts:
description: Facts of result and status.
returned: success
@@ -84,7 +82,7 @@ cloud_init_data_facts:
"stage": null
}
}'
-'''
+"""
import os
@@ -107,9 +105,8 @@ def gather_cloud_init_data_facts(module):
json_file = os.path.join(CLOUD_INIT_PATH, i + '.json')
if os.path.exists(json_file):
- f = open(json_file, 'rb')
- contents = to_text(f.read(), errors='surrogate_or_strict')
- f.close()
+ with open(json_file, 'rb') as f:
+ contents = to_text(f.read(), errors='surrogate_or_strict')
if contents:
res['cloud_init_data_facts'][i] = module.from_json(contents)
diff --git a/plugins/modules/cloudflare_dns.py b/plugins/modules/cloudflare_dns.py
index 86550966be..e1b75e30ca 100644
--- a/plugins/modules/cloudflare_dns.py
+++ b/plugins/modules/cloudflare_dns.py
@@ -8,16 +8,15 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: cloudflare_dns
author:
-- Michael Gruener (@mgruener)
+ - Michael Gruener (@mgruener)
short_description: Manage Cloudflare DNS records
description:
- - "Manages dns records via the Cloudflare API, see the docs: U(https://api.cloudflare.com/)."
+ - 'Manages DNS records using the Cloudflare API, see the docs: U(https://api.cloudflare.com/).'
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -26,153 +25,162 @@ attributes:
options:
api_token:
description:
- - API token.
- - Required for api token authentication.
- - "You can obtain your API token from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)."
- - Can be specified in E(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0.
+ - API token.
+ - Required for API token authentication.
+ - "You can obtain your API token from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)."
+ - Can be specified in E(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0.
type: str
- required: false
version_added: '0.2.0'
account_api_key:
description:
- - Account API key.
- - Required for api keys authentication.
- - "You can obtain your API key from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)."
+ - Account API key.
+ - Required for API keys authentication.
+ - "You can obtain your API key from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)."
type: str
- required: false
- aliases: [ account_api_token ]
+ aliases: [account_api_token]
account_email:
description:
- - Account email. Required for API keys authentication.
+ - Account email. Required for API keys authentication.
type: str
- required: false
algorithm:
description:
- - Algorithm number.
- - Required for O(type=DS) and O(type=SSHFP) when O(state=present).
+ - Algorithm number.
+ - Required for O(type=DS) and O(type=SSHFP) when O(state=present).
type: int
cert_usage:
description:
- - Certificate usage number.
- - Required for O(type=TLSA) when O(state=present).
+ - Certificate usage number.
+ - Required for O(type=TLSA) when O(state=present).
type: int
- choices: [ 0, 1, 2, 3 ]
+ choices: [0, 1, 2, 3]
+ comment:
+ description:
+ - Comments or notes about the DNS record.
+ type: str
+ version_added: 10.1.0
flag:
description:
- - Issuer Critical Flag.
- - Required for O(type=CAA) when O(state=present).
+ - Issuer Critical Flag.
+ - Required for O(type=CAA) when O(state=present).
type: int
- choices: [ 0, 1 ]
+ choices: [0, 1]
version_added: 8.0.0
tag:
description:
- - CAA issue restriction.
- - Required for O(type=CAA) when O(state=present).
+ - CAA issue restriction.
+ - Required for O(type=CAA) when O(state=present).
type: str
- choices: [ issue, issuewild, iodef ]
+ choices: [issue, issuewild, iodef]
version_added: 8.0.0
hash_type:
description:
- - Hash type number.
- - Required for O(type=DS), O(type=SSHFP) and O(type=TLSA) when O(state=present).
+ - Hash type number.
+ - Required for O(type=DS), O(type=SSHFP) and O(type=TLSA) when O(state=present).
type: int
- choices: [ 1, 2 ]
+ choices: [1, 2]
key_tag:
description:
- - DNSSEC key tag.
- - Needed for O(type=DS) when O(state=present).
+ - DNSSEC key tag.
+ - Needed for O(type=DS) when O(state=present).
type: int
port:
description:
- - Service port.
- - Required for O(type=SRV) and O(type=TLSA).
+ - Service port.
+ - Required for O(type=SRV) and O(type=TLSA).
type: int
priority:
description:
- - Record priority.
- - Required for O(type=MX) and O(type=SRV)
+ - Record priority.
+ - Required for O(type=MX) and O(type=SRV).
default: 1
type: int
proto:
description:
- - Service protocol. Required for O(type=SRV) and O(type=TLSA).
- - Common values are TCP and UDP.
+ - Service protocol. Required for O(type=SRV) and O(type=TLSA).
+ - Common values are TCP and UDP.
type: str
proxied:
description:
- - Proxy through Cloudflare network or just use DNS.
+ - Proxy through Cloudflare network or just use DNS.
type: bool
default: false
record:
description:
- - Record to add.
- - Required if O(state=present).
- - Default is V(@) (that is, the zone name).
+ - Record to add.
+ - Required if O(state=present).
+ - Default is V(@) (that is, the zone name).
type: str
default: '@'
- aliases: [ name ]
+ aliases: [name]
selector:
description:
- - Selector number.
- - Required for O(type=TLSA) when O(state=present).
- choices: [ 0, 1 ]
+ - Selector number.
+ - Required for O(type=TLSA) when O(state=present).
+ choices: [0, 1]
type: int
service:
description:
- - Record service.
- - Required for O(type=SRV).
+ - Record service.
+ - Required for O(type=SRV).
type: str
solo:
description:
- - Whether the record should be the only one for that record type and record name.
- - Only use with O(state=present).
- - This will delete all other records with the same record name and type.
+ - Whether the record should be the only one for that record type and record name.
+ - Only use with O(state=present).
+ - This will delete all other records with the same record name and type.
type: bool
state:
description:
- - Whether the record(s) should exist or not.
+ - Whether the record(s) should exist or not.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
+ tags:
+ description:
+ - Custom tags for the DNS record.
+ type: list
+ elements: str
+ version_added: 10.1.0
timeout:
description:
- - Timeout for Cloudflare API calls.
+ - Timeout for Cloudflare API calls.
type: int
default: 30
ttl:
description:
- - The TTL to give the new record.
- - Must be between 120 and 2,147,483,647 seconds, or 1 for automatic.
+ - The TTL to give the new record.
+ - Must be between V(120) and V(2,147,483,647) seconds, or V(1) for automatic.
type: int
default: 1
type:
description:
- The type of DNS record to create. Required if O(state=present).
- - Support for V(SPF) has been removed from community.general 9.0.0 since that record type is no longer supported by CloudFlare.
+ - Support for V(SPF) has been removed from community.general 9.0.0 since that record type is no longer supported by
+ CloudFlare.
type: str
- choices: [ A, AAAA, CNAME, DS, MX, NS, SRV, SSHFP, TLSA, CAA, TXT ]
+ choices: [A, AAAA, CNAME, DS, MX, NS, SRV, SSHFP, TLSA, CAA, TXT]
value:
description:
- - The record value.
- - Required for O(state=present).
+ - The record value.
+ - Required for O(state=present).
type: str
- aliases: [ content ]
+ aliases: [content]
weight:
description:
- - Service weight.
- - Required for O(type=SRV).
+ - Service weight.
+ - Required for O(type=SRV).
type: int
default: 1
zone:
description:
- - The name of the Zone to work with (e.g. "example.com").
- - The Zone must already exist.
+ - The name of the Zone to work with (for example V(example.com)).
+ - The Zone must already exist.
type: str
required: true
- aliases: [ domain ]
-'''
+ aliases: [domain]
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a test.example.net A record to point to 127.0.0.1
community.general.cloudflare_dns:
zone: example.net
@@ -191,6 +199,18 @@ EXAMPLES = r'''
value: 127.0.0.1
api_token: dummyapitoken
+- name: Create a record with comment and tags
+ community.general.cloudflare_dns:
+ zone: example.net
+ record: test
+ type: A
+ value: 127.0.0.1
+ comment: Local test website
+ tags:
+ - test
+ - local
+ api_token: dummyapitoken
+
- name: Create a example.net CNAME record to example.com
community.general.cloudflare_dns:
zone: example.net
@@ -291,98 +311,116 @@ EXAMPLES = r'''
algorithm: 8
hash_type: 2
value: B4EB5AC4467D2DFB3BAF9FB9961DC1B6FED54A58CDFAA3E465081EC86F89BFAB
-'''
+"""
-RETURN = r'''
+RETURN = r"""
record:
- description: A dictionary containing the record data.
- returned: success, except on record deletion
- type: complex
- contains:
- content:
- description: The record content (details depend on record type).
- returned: success
- type: str
- sample: 192.0.2.91
- created_on:
- description: The record creation date.
- returned: success
- type: str
- sample: "2016-03-25T19:09:42.516553Z"
- data:
- description: Additional record data.
- returned: success, if type is SRV, DS, SSHFP TLSA or CAA
- type: dict
- sample: {
- name: "jabber",
- port: 8080,
- priority: 10,
- proto: "_tcp",
- service: "_xmpp",
- target: "jabberhost.sample.com",
- weight: 5,
- }
- id:
- description: The record ID.
- returned: success
- type: str
- sample: f9efb0549e96abcb750de63b38c9576e
- locked:
- description: No documentation available.
- returned: success
- type: bool
- sample: false
- meta:
- description: No documentation available.
- returned: success
- type: dict
- sample: { auto_added: false }
- modified_on:
- description: Record modification date.
- returned: success
- type: str
- sample: "2016-03-25T19:09:42.516553Z"
- name:
- description: The record name as FQDN (including _service and _proto for SRV).
- returned: success
- type: str
- sample: www.sample.com
- priority:
- description: Priority of the MX record.
- returned: success, if type is MX
- type: int
- sample: 10
- proxiable:
- description: Whether this record can be proxied through Cloudflare.
- returned: success
- type: bool
- sample: false
- proxied:
- description: Whether the record is proxied through Cloudflare.
- returned: success
- type: bool
- sample: false
- ttl:
- description: The time-to-live for the record.
- returned: success
- type: int
- sample: 300
- type:
- description: The record type.
- returned: success
- type: str
- sample: A
- zone_id:
- description: The ID of the zone containing the record.
- returned: success
- type: str
- sample: abcede0bf9f0066f94029d2e6b73856a
- zone_name:
- description: The name of the zone containing the record.
- returned: success
- type: str
- sample: sample.com
-'''
+ description: A dictionary containing the record data.
+ returned: success, except on record deletion
+ type: complex
+ contains:
+ comment:
+ description: Comments or notes about the DNS record.
+ returned: success
+ type: str
+ sample: Domain verification record
+ version_added: 10.1.0
+ comment_modified_on:
+ description: When the record comment was last modified. Omitted if there is no comment.
+ returned: success
+ type: str
+ sample: "2024-01-01T05:20:00.12345Z"
+ version_added: 10.1.0
+ content:
+ description: The record content (details depend on record type).
+ returned: success
+ type: str
+ sample: 192.0.2.91
+ created_on:
+ description: The record creation date.
+ returned: success
+ type: str
+ sample: "2016-03-25T19:09:42.516553Z"
+ data:
+ description: Additional record data.
+ returned: success, if type is SRV, DS, SSHFP TLSA or CAA
+ type: dict
+ sample: {name: "jabber", port: 8080, priority: 10, proto: "_tcp", service: "_xmpp", target: "jabberhost.sample.com",
+ weight: 5}
+ id:
+ description: The record ID.
+ returned: success
+ type: str
+ sample: f9efb0549e96abcb750de63b38c9576e
+ locked:
+ description: No documentation available.
+ returned: success
+ type: bool
+ sample: false
+ meta:
+ description: Extra Cloudflare-specific information about the record.
+ returned: success
+ type: dict
+ sample: {auto_added: false}
+ modified_on:
+ description: Record modification date.
+ returned: success
+ type: str
+ sample: "2016-03-25T19:09:42.516553Z"
+ name:
+ description: The record name as FQDN (including _service and _proto for SRV).
+ returned: success
+ type: str
+ sample: www.sample.com
+ priority:
+ description: Priority of the MX record.
+ returned: success, if type is MX
+ type: int
+ sample: 10
+ proxiable:
+ description: Whether this record can be proxied through Cloudflare.
+ returned: success
+ type: bool
+ sample: false
+ proxied:
+ description: Whether the record is proxied through Cloudflare.
+ returned: success
+ type: bool
+ sample: false
+ tags:
+ description: Custom tags for the DNS record.
+ returned: success
+ type: list
+ elements: str
+ sample: ['production', 'app']
+ version_added: 10.1.0
+ tags_modified_on:
+ description: When the record tags were last modified. Omitted if there are no tags.
+ returned: success
+ type: str
+ sample: "2025-01-01T05:20:00.12345Z"
+ version_added: 10.1.0
+ ttl:
+ description: The time-to-live for the record.
+ returned: success
+ type: int
+ sample: 300
+ type:
+ description: The record type.
+ returned: success
+ type: str
+ sample: A
+ zone_id:
+ description: The ID of the zone containing the record.
+ returned: success
+ type: str
+ sample: abcede0bf9f0066f94029d2e6b73856a
+ zone_name:
+ description: The name of the zone containing the record.
+ returned: success
+ type: str
+ sample: sample.com
+"""
import json
@@ -410,9 +448,11 @@ class CloudflareAPI(object):
self.account_email = module.params['account_email']
self.algorithm = module.params['algorithm']
self.cert_usage = module.params['cert_usage']
+ self.comment = module.params['comment']
self.hash_type = module.params['hash_type']
self.flag = module.params['flag']
self.tag = module.params['tag']
+ self.tags = module.params['tags']
self.key_tag = module.params['key_tag']
self.port = module.params['port']
self.priority = module.params['priority']
@@ -511,6 +551,9 @@ class CloudflareAPI(object):
try:
content = resp.read()
except AttributeError:
+ content = None
+
+ if not content:
if info['body']:
content = info['body']
else:
@@ -645,6 +688,7 @@ class CloudflareAPI(object):
else:
search_value = content
+ zone_id = self._get_zone_id(params['zone'])
records = self.get_dns_records(params['zone'], params['type'], search_record, search_value)
for rr in records:
@@ -652,17 +696,17 @@ class CloudflareAPI(object):
if not ((rr['type'] == params['type']) and (rr['name'] == search_record) and (rr['content'] == content)):
self.changed = True
if not self.module.check_mode:
- result, info = self._cf_api_call('/zones/{0}/dns_records/{1}'.format(rr['zone_id'], rr['id']), 'DELETE')
+ result, info = self._cf_api_call('/zones/{0}/dns_records/{1}'.format(zone_id, rr['id']), 'DELETE')
else:
self.changed = True
if not self.module.check_mode:
- result, info = self._cf_api_call('/zones/{0}/dns_records/{1}'.format(rr['zone_id'], rr['id']), 'DELETE')
+ result, info = self._cf_api_call('/zones/{0}/dns_records/{1}'.format(zone_id, rr['id']), 'DELETE')
return self.changed
def ensure_dns_record(self, **kwargs):
params = {}
for param in ['port', 'priority', 'proto', 'proxied', 'service', 'ttl', 'type', 'record', 'value', 'weight', 'zone',
- 'algorithm', 'cert_usage', 'hash_type', 'selector', 'key_tag', 'flag', 'tag']:
+ 'algorithm', 'cert_usage', 'hash_type', 'selector', 'key_tag', 'flag', 'tag', 'tags', 'comment']:
if param in kwargs:
params[param] = kwargs[param]
else:
@@ -798,6 +842,9 @@ class CloudflareAPI(object):
}
search_value = None
+ new_record['comment'] = params['comment'] or None
+ new_record['tags'] = params['tags'] or []
+
zone_id = self._get_zone_id(params['zone'])
records = self.get_dns_records(params['zone'], params['type'], search_record, search_value)
# in theory this should be impossible as cloudflare does not allow
@@ -826,6 +873,10 @@ class CloudflareAPI(object):
do_update = True
if (params['type'] == 'CNAME') and (cur_record['content'] != new_record['content']):
do_update = True
+ if cur_record['comment'] != new_record['comment']:
+ do_update = True
+ if sorted(cur_record['tags']) != sorted(new_record['tags']):
+ do_update = True
if do_update:
if self.module.check_mode:
result = new_record
@@ -856,11 +907,13 @@ def main():
account_email=dict(type='str', required=False),
algorithm=dict(type='int'),
cert_usage=dict(type='int', choices=[0, 1, 2, 3]),
+ comment=dict(type='str'),
hash_type=dict(type='int', choices=[1, 2]),
key_tag=dict(type='int', no_log=False),
port=dict(type='int'),
flag=dict(type='int', choices=[0, 1]),
tag=dict(type='str', choices=['issue', 'issuewild', 'iodef']),
+ tags=dict(type='list', elements='str'),
priority=dict(type='int', default=1),
proto=dict(type='str'),
proxied=dict(type='bool', default=False),
diff --git a/plugins/modules/cobbler_sync.py b/plugins/modules/cobbler_sync.py
index 27f57028be..95a3241b98 100644
--- a/plugins/modules/cobbler_sync.py
+++ b/plugins/modules/cobbler_sync.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: cobbler_sync
short_description: Sync Cobbler
description:
@@ -24,44 +23,44 @@ attributes:
options:
host:
description:
- - The name or IP address of the Cobbler system.
+ - The name or IP address of the Cobbler system.
default: 127.0.0.1
type: str
port:
description:
- - Port number to be used for REST connection.
- - The default value depends on parameter O(use_ssl).
+ - Port number to be used for REST connection.
+ - The default value depends on parameter O(use_ssl).
type: int
username:
description:
- - The username to log in to Cobbler.
+ - The username to log in to Cobbler.
default: cobbler
type: str
password:
description:
- - The password to log in to Cobbler.
+ - The password to log in to Cobbler.
type: str
use_ssl:
description:
- - If V(false), an HTTP connection will be used instead of the default HTTPS connection.
+ - If V(false), an HTTP connection will be used instead of the default HTTPS connection.
type: bool
default: true
validate_certs:
description:
- - If V(false), SSL certificates will not be validated.
- - This should only set to V(false) when used on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated.
+ - This should only set to V(false) when used on personally controlled sites using self-signed certificates.
type: bool
default: true
author:
-- Dag Wieers (@dagwieers)
+ - Dag Wieers (@dagwieers)
todo:
notes:
-- Concurrently syncing Cobbler is bound to fail with weird errors.
-- On python 2.7.8 and older (i.e. on RHEL7) you may need to tweak the python behaviour to disable certificate validation.
- More information at L(Certificate verification in Python standard library HTTP clients,https://access.redhat.com/articles/2039753).
-'''
+ - Concurrently syncing Cobbler is bound to fail with weird errors.
+ - On Python 2.7.8 and older (such as RHEL7) you may need to tweak the Python behaviour to disable certificate validation.
+ More information at L(Certificate verification in Python standard library HTTP clients,https://access.redhat.com/articles/2039753).
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Commit Cobbler changes
community.general.cobbler_sync:
host: cobbler01
@@ -69,11 +68,11 @@ EXAMPLES = r'''
password: MySuperSecureP4sswOrd
run_once: true
delegate_to: localhost
-'''
+"""
-RETURN = r'''
+RETURN = r"""
# Default return values
-'''
+"""
import ssl
diff --git a/plugins/modules/cobbler_system.py b/plugins/modules/cobbler_system.py
index a327ede84b..fd1db6bf3e 100644
--- a/plugins/modules/cobbler_system.py
+++ b/plugins/modules/cobbler_system.py
@@ -8,12 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: cobbler_system
short_description: Manage system objects in Cobbler
description:
- - Add, modify or remove systems in Cobbler
+ - Add, modify or remove systems in Cobbler.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -24,67 +23,67 @@ attributes:
options:
host:
description:
- - The name or IP address of the Cobbler system.
+ - The name or IP address of the Cobbler system.
default: 127.0.0.1
type: str
port:
description:
- - Port number to be used for REST connection.
- - The default value depends on parameter O(use_ssl).
+ - Port number to be used for REST connection.
+ - The default value depends on parameter O(use_ssl).
type: int
username:
description:
- - The username to log in to Cobbler.
+ - The username to log in to Cobbler.
default: cobbler
type: str
password:
description:
- - The password to log in to Cobbler.
+ - The password to log in to Cobbler.
type: str
use_ssl:
description:
- - If V(false), an HTTP connection will be used instead of the default HTTPS connection.
+ - If V(false), an HTTP connection will be used instead of the default HTTPS connection.
type: bool
default: true
validate_certs:
description:
- - If V(false), SSL certificates will not be validated.
- - This should only set to V(false) when used on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated.
+ - This should only set to V(false) when used on personally controlled sites using self-signed certificates.
type: bool
default: true
name:
description:
- - The system name to manage.
+ - The system name to manage.
type: str
properties:
description:
- - A dictionary with system properties.
+ - A dictionary with system properties.
type: dict
interfaces:
description:
- - A list of dictionaries containing interface options.
+ - A list of dictionaries containing interface options.
type: dict
sync:
description:
- - Sync on changes.
- - Concurrently syncing Cobbler is bound to fail.
+ - Sync on changes.
+ - Concurrently syncing Cobbler is bound to fail.
type: bool
default: false
state:
description:
- - Whether the system should be present, absent or a query is made.
- choices: [ absent, present, query ]
+ - Whether the system should be present, absent or a query is made.
+ choices: [absent, present, query]
default: present
type: str
author:
-- Dag Wieers (@dagwieers)
+ - Dag Wieers (@dagwieers)
notes:
-- Concurrently syncing Cobbler is bound to fail with weird errors.
-- On python 2.7.8 and older (i.e. on RHEL7) you may need to tweak the python behaviour to disable certificate validation.
- More information at L(Certificate verification in Python standard library HTTP clients,https://access.redhat.com/articles/2039753).
-'''
+ - Concurrently syncing Cobbler is bound to fail with weird errors.
+ - On Python 2.7.8 and older (such as RHEL7) you may need to tweak the Python behaviour to disable certificate validation.
+ More information at L(Certificate verification in Python standard library HTTP clients,https://access.redhat.com/articles/2039753).
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure the system exists in Cobbler
community.general.cobbler_system:
host: cobbler01
@@ -93,7 +92,7 @@ EXAMPLES = r'''
name: myhost
properties:
profile: CentOS6-x86_64
- name_servers: [ 2.3.4.5, 3.4.5.6 ]
+ name_servers: [2.3.4.5, 3.4.5.6]
name_servers_search: foo.com, bar.com
interfaces:
eth0:
@@ -139,18 +138,18 @@ EXAMPLES = r'''
name: myhost
state: absent
delegate_to: localhost
-'''
+"""
-RETURN = r'''
+RETURN = r"""
systems:
- description: List of systems
+ description: List of systems.
returned: O(state=query) and O(name) is not provided
type: list
system:
- description: (Resulting) information about the system we are working with
+ description: (Resulting) information about the system we are working with.
returned: when O(name) is provided
type: dict
-'''
+"""
import ssl
diff --git a/plugins/modules/composer.py b/plugins/modules/composer.py
index 3d1c4a3465..6c935bfe75 100644
--- a/plugins/modules/composer.py
+++ b/plugins/modules/composer.py
@@ -9,115 +9,114 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: composer
author:
- - "Dimitrios Tydeas Mengidis (@dmtrs)"
- - "René Moser (@resmo)"
+ - "Dimitrios Tydeas Mengidis (@dmtrs)"
+ - "René Moser (@resmo)"
short_description: Dependency Manager for PHP
description:
- - >
- Composer is a tool for dependency management in PHP. It allows you to
- declare the dependent libraries your project needs and it will install
- them in your project for you.
+ - Composer is a tool for dependency management in PHP. It allows you to declare the dependent libraries your project needs
+ and it will install them in your project for you.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- command:
- type: str
- description:
- - Composer command like "install", "update" and so on.
- default: install
- arguments:
- type: str
- description:
- - Composer arguments like required package, version and so on.
- default: ''
- executable:
- type: path
- description:
- - Path to PHP Executable on the remote host, if PHP is not in PATH.
- aliases: [ php_path ]
- working_dir:
- type: path
- description:
- - Directory of your project (see --working-dir). This is required when
- the command is not run globally.
- - Will be ignored if O(global_command=true).
- global_command:
- description:
- - Runs the specified command globally.
- type: bool
- default: false
- prefer_source:
- description:
- - Forces installation from package sources when possible (see --prefer-source).
- default: false
- type: bool
- prefer_dist:
- description:
- - Forces installation from package dist even for dev versions (see --prefer-dist).
- default: false
- type: bool
- no_dev:
- description:
- - Disables installation of require-dev packages (see --no-dev).
- default: true
- type: bool
- no_scripts:
- description:
- - Skips the execution of all scripts defined in composer.json (see --no-scripts).
- default: false
- type: bool
- no_plugins:
- description:
- - Disables all plugins (see --no-plugins).
- default: false
- type: bool
- optimize_autoloader:
- description:
- - Optimize autoloader during autoloader dump (see --optimize-autoloader).
- - Convert PSR-0/4 autoloading to classmap to get a faster autoloader.
- - Recommended especially for production, but can take a bit of time to run.
- default: true
- type: bool
- classmap_authoritative:
- description:
- - Autoload classes from classmap only.
- - Implicitly enable optimize_autoloader.
- - Recommended especially for production, but can take a bit of time to run.
- default: false
- type: bool
- apcu_autoloader:
- description:
- - Uses APCu to cache found/not-found classes
- default: false
- type: bool
- ignore_platform_reqs:
- description:
- - Ignore php, hhvm, lib-* and ext-* requirements and force the installation even if the local machine does not fulfill these.
- default: false
- type: bool
- composer_executable:
- type: path
- description:
- - Path to composer executable on the remote host, if composer is not in E(PATH) or a custom composer is needed.
- version_added: 3.2.0
+ command:
+ type: str
+ description:
+ - Composer command like V(install), V(update) and so on.
+ default: install
+ arguments:
+ type: str
+ description:
+ - Composer arguments like required package, version and so on.
+ default: ''
+ executable:
+ type: path
+ description:
+ - Path to PHP executable on the remote host, if PHP is not in E(PATH).
+ aliases: [php_path]
+ working_dir:
+ type: path
+ description:
+ - Directory of your project (see C(--working-dir)). This is required when the command is not run globally.
+ - Will be ignored if O(global_command=true).
+ global_command:
+ description:
+ - Runs the specified command globally.
+ type: bool
+ default: false
+ prefer_source:
+ description:
+ - Forces installation from package sources when possible (see C(--prefer-source)).
+ default: false
+ type: bool
+ prefer_dist:
+ description:
+ - Forces installation from package dist even for dev versions (see C(--prefer-dist)).
+ default: false
+ type: bool
+ no_dev:
+ description:
+ - Disables installation of require-dev packages (see C(--no-dev)).
+ default: true
+ type: bool
+ no_scripts:
+ description:
+ - Skips the execution of all scripts defined in composer.json (see C(--no-scripts)).
+ default: false
+ type: bool
+ no_plugins:
+ description:
+ - Disables all plugins (see C(--no-plugins)).
+ default: false
+ type: bool
+ optimize_autoloader:
+ description:
+ - Optimize autoloader during autoloader dump (see C(--optimize-autoloader)).
+ - Convert PSR-0/4 autoloading to classmap to get a faster autoloader.
+ - Recommended especially for production, but can take a bit of time to run.
+ default: true
+ type: bool
+ classmap_authoritative:
+ description:
+ - Autoload classes from classmap only.
+ - Implicitly enable optimize_autoloader.
+ - Recommended especially for production, but can take a bit of time to run.
+ default: false
+ type: bool
+ apcu_autoloader:
+ description:
+ - Uses APCu to cache found/not-found classes.
+ default: false
+ type: bool
+ ignore_platform_reqs:
+ description:
+ - Ignore php, hhvm, lib-* and ext-* requirements and force the installation even if the local machine does not fulfill
+ these.
+ default: false
+ type: bool
+ composer_executable:
+ type: path
+ description:
+ - Path to composer executable on the remote host, if composer is not in E(PATH) or a custom composer is needed.
+ version_added: 3.2.0
requirements:
- - php
- - composer installed in bin path (recommended /usr/local/bin) or specified in O(composer_executable)
+ - php
+ - composer installed in bin path (recommended C(/usr/local/bin)) or specified in O(composer_executable)
notes:
- - Default options that are always appended in each execution are --no-ansi, --no-interaction and --no-progress if available.
- - We received reports about issues on macOS if composer was installed by Homebrew. Please use the official install method to avoid issues.
-'''
+ - Default options that are always appended in each execution are C(--no-ansi), C(--no-interaction) and C(--no-progress)
+ if available.
+ - We received reports about issues on macOS if composer was installed by Homebrew. Please use the official install method
+ to avoid issues.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Download and installs all libs and dependencies outlined in the /path/to/project/composer.lock
community.general.composer:
command: install
@@ -141,7 +140,7 @@ EXAMPLES = '''
command: require
global_command: true
arguments: my/package
-'''
+"""
import re
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/consul.py b/plugins/modules/consul.py
index 28beeec52d..645ffe5bbd 100644
--- a/plugins/modules/consul.py
+++ b/plugins/modules/consul.py
@@ -9,26 +9,21 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: consul
-short_description: Add, modify & delete services within a consul cluster
+short_description: Add, modify & delete services within a Consul cluster
description:
- - Registers services and checks for an agent with a consul cluster.
- A service is some process running on the agent node that should be advertised by
- consul's discovery mechanism. It may optionally supply a check definition,
- a periodic service test to notify the consul cluster of service's health.
- - "Checks may also be registered per node e.g. disk usage, or cpu usage and
- notify the health of the entire node to the cluster.
- Service level checks do not require a check name or id as these are derived
- by Consul from the Service name and id respectively by appending 'service:'
- Node level checks require a O(check_name) and optionally a O(check_id)."
- - Currently, there is no complete way to retrieve the script, interval or TTL
- metadata for a registered check. Without this metadata it is not possible to
- tell if the data supplied with ansible represents a change to a check. As a
- result this does not attempt to determine changes and will always report a
- changed occurred. An API method is planned to supply this metadata so at that
- stage change management will be added.
- - "See U(http://consul.io) for more details."
+ - Registers services and checks for an agent with a Consul cluster. A service is some process running on the agent node
+ that should be advertised by Consul's discovery mechanism. It may optionally supply a check definition, a periodic service
+ test to notify the Consul cluster of service's health.
+ - Checks may also be registered per node, for example disk usage, or cpu usage and notify the health of the entire node
+ to the cluster. Service level checks do not require a check name or ID as these are derived by Consul from the Service
+ name and ID respectively by appending V(service:) Node level checks require a O(check_name) and optionally a O(check_id).
+ - Currently, there is no complete way to retrieve the script, interval or TTL metadata for a registered check. Without this
+ metadata it is not possible to tell if the data supplied with ansible represents a change to a check. As a result this
+ does not attempt to determine changes and will always report a changed occurred. An API method is planned to supply this
+ metadata so at that stage change management will be added.
+ - See U(http://consul.io) for more details.
requirements:
- python-consul
- requests
@@ -41,139 +36,127 @@ attributes:
diff_mode:
support: none
options:
- state:
- type: str
- description:
- - Register or deregister the consul service, defaults to present.
- default: present
- choices: ['present', 'absent']
- service_name:
- type: str
- description:
- - Unique name for the service on a node, must be unique per node,
- required if registering a service. May be omitted if registering
- a node level check.
- service_id:
- type: str
- description:
- - The ID for the service, must be unique per node. If O(state=absent),
- defaults to the service name if supplied.
- host:
- type: str
- description:
- - Host of the consul agent defaults to localhost.
- default: localhost
- port:
- type: int
- description:
- - The port on which the consul agent is running.
- default: 8500
- scheme:
- type: str
- description:
- - The protocol scheme on which the consul agent is running.
- default: http
- validate_certs:
- description:
- - Whether to verify the TLS certificate of the consul agent.
- type: bool
- default: true
- notes:
- type: str
- description:
- - Notes to attach to check when registering it.
- service_port:
- type: int
- description:
- - The port on which the service is listening. Can optionally be supplied for
- registration of a service, that is if O(service_name) or O(service_id) is set.
- service_address:
- type: str
- description:
- - The address to advertise that the service will be listening on.
- This value will be passed as the C(address) parameter to Consul's
- C(/v1/agent/service/register) API method, so refer to the Consul API
- documentation for further details.
- tags:
- type: list
- elements: str
- description:
- - Tags that will be attached to the service registration.
- script:
- type: str
- description:
- - The script/command that will be run periodically to check the health of the service.
- - Requires O(interval) to be provided.
- - Mutually exclusive with O(ttl), O(tcp) and O(http).
- interval:
- type: str
- description:
- - The interval at which the service check will be run.
- This is a number with a V(s) or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m).
- If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
- - Required if one of the parameters O(script), O(http), or O(tcp) is specified.
- check_id:
- type: str
- description:
- - An ID for the service check. If O(state=absent), defaults to
- O(check_name). Ignored if part of a service definition.
- check_name:
- type: str
- description:
- - Name for the service check. Required if standalone, ignored if
- part of service definition.
- check_node:
- description:
- - Node name.
- # TODO: properly document!
- type: str
- check_host:
- description:
- - Host name.
- # TODO: properly document!
- type: str
- ttl:
- type: str
- description:
- - Checks can be registered with a TTL instead of a O(script) and O(interval)
- this means that the service will check in with the agent before the
- TTL expires. If it doesn't the check will be considered failed.
- Required if registering a check and the script an interval are missing
- Similar to the interval this is a number with a V(s) or V(m) suffix to
- signify the units of seconds or minutes, for example V(15s) or V(1m).
- If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
- - Mutually exclusive with O(script), O(tcp) and O(http).
- tcp:
- type: str
- description:
- - Checks can be registered with a TCP port. This means that consul
- will check if the connection attempt to that port is successful (that is, the port is currently accepting connections).
- The format is V(host:port), for example V(localhost:80).
- - Requires O(interval) to be provided.
- - Mutually exclusive with O(script), O(ttl) and O(http).
- version_added: '1.3.0'
- http:
- type: str
- description:
- - Checks can be registered with an HTTP endpoint. This means that consul
- will check that the http endpoint returns a successful HTTP status.
- - Requires O(interval) to be provided.
- - Mutually exclusive with O(script), O(ttl) and O(tcp).
- timeout:
- type: str
- description:
- - A custom HTTP check timeout. The consul default is 10 seconds.
- Similar to the interval this is a number with a V(s) or V(m) suffix to
- signify the units of seconds or minutes, for example V(15s) or V(1m).
- If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
- token:
- type: str
- description:
- - The token key identifying an ACL rule set. May be required to register services.
-'''
+ state:
+ type: str
+ description:
+ - Register or deregister the Consul service, defaults to present.
+ default: present
+ choices: ['present', 'absent']
+ service_name:
+ type: str
+ description:
+ - Unique name for the service on a node, must be unique per node, required if registering a service. May be omitted
+ if registering a node level check.
+ service_id:
+ type: str
+ description:
+ - The ID for the service, must be unique per node. If O(state=absent), defaults to the service name if supplied.
+ host:
+ type: str
+ description:
+ - Host of the Consul agent defaults to localhost.
+ default: localhost
+ port:
+ type: int
+ description:
+ - The port on which the Consul agent is running.
+ default: 8500
+ scheme:
+ type: str
+ description:
+ - The protocol scheme on which the Consul agent is running.
+ default: http
+ validate_certs:
+ description:
+ - Whether to verify the TLS certificate of the Consul agent.
+ type: bool
+ default: true
+ notes:
+ type: str
+ description:
+ - Notes to attach to check when registering it.
+ service_port:
+ type: int
+ description:
+ - The port on which the service is listening. Can optionally be supplied for registration of a service, that is if O(service_name)
+ or O(service_id) is set.
+ service_address:
+ type: str
+ description:
+ - The address to advertise that the service will be listening on. This value will be passed as the C(address) parameter
+ to Consul's C(/v1/agent/service/register) API method, so refer to the Consul API documentation for further details.
+ tags:
+ type: list
+ elements: str
+ description:
+ - Tags that will be attached to the service registration.
+ script:
+ type: str
+ description:
+ - The script/command that will be run periodically to check the health of the service.
+ - Requires O(interval) to be provided.
+ - Mutually exclusive with O(ttl), O(tcp) and O(http).
+ interval:
+ type: str
+ description:
+ - The interval at which the service check will be run. This is a number with a V(s) or V(m) suffix to signify the units
+ of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used by default, for example
+ V(10) will be V(10s).
+ - Required if one of the parameters O(script), O(http), or O(tcp) is specified.
+ check_id:
+ type: str
+ description:
+ - An ID for the service check. If O(state=absent), defaults to O(check_name). Ignored if part of a service definition.
+ check_name:
+ type: str
+ description:
+ - Name for the service check. Required if standalone, ignored if part of service definition.
+ check_node:
+ description:
+ - Node name.
+ type: str
+ check_host:
+ description:
+ - Host name.
+ type: str
+ ttl:
+ type: str
+ description:
+ - Checks can be registered with a TTL instead of a O(script) and O(interval) this means that the service will check
+ in with the agent before the TTL expires. If it does not the check will be considered failed. Required if registering
+ a check and the script an interval are missing Similar to the interval this is a number with a V(s) or V(m) suffix
+ to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used
+ by default, for example V(10) will be V(10s).
+ - Mutually exclusive with O(script), O(tcp) and O(http).
+ tcp:
+ type: str
+ description:
+ - Checks can be registered with a TCP port. This means that Consul will check if the connection attempt to that port
+ is successful (that is, the port is currently accepting connections). The format is V(host:port), for example V(localhost:80).
+ - Requires O(interval) to be provided.
+ - Mutually exclusive with O(script), O(ttl) and O(http).
+ version_added: '1.3.0'
+ http:
+ type: str
+ description:
+ - Checks can be registered with an HTTP endpoint. This means that Consul will check that the http endpoint returns a
+ successful HTTP status.
+ - Requires O(interval) to be provided.
+ - Mutually exclusive with O(script), O(ttl) and O(tcp).
+ timeout:
+ type: str
+ description:
+ - A custom HTTP check timeout. The Consul default is 10 seconds. Similar to the interval this is a number with a V(s)
+ or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s)
+ will be used by default, for example V(10) will be V(10s).
+ token:
+ type: str
+ description:
+ - The token key identifying an ACL rule set. May be required to register services.
+"""
-EXAMPLES = '''
-- name: Register nginx service with the local consul agent
+EXAMPLES = r"""
+- name: Register nginx service with the local Consul agent
community.general.consul:
service_name: nginx
service_port: 80
@@ -239,7 +222,7 @@ EXAMPLES = '''
service_id: nginx
interval: 60s
http: http://localhost:80/morestatus
-'''
+"""
try:
import consul
diff --git a/plugins/modules/consul_acl_bootstrap.py b/plugins/modules/consul_acl_bootstrap.py
index bf1da110bf..7002c3d549 100644
--- a/plugins/modules/consul_acl_bootstrap.py
+++ b/plugins/modules/consul_acl_bootstrap.py
@@ -9,13 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
+DOCUMENTATION = r"""
module: consul_acl_bootstrap
short_description: Bootstrap ACLs in Consul
version_added: 8.3.0
description:
- - Allows bootstrapping of ACLs in a Consul cluster, see
- U(https://developer.hashicorp.com/consul/api-docs/acl#bootstrap-acls) for details.
+ - Allows bootstrapping of ACLs in a Consul cluster, see U(https://developer.hashicorp.com/consul/api-docs/acl#bootstrap-acls)
+ for details.
author:
- Florian Apolloner (@apollo13)
extends_documentation_fragment:
@@ -40,35 +40,33 @@ options:
type: str
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Bootstrap the ACL system
community.general.consul_acl_bootstrap:
bootstrap_secret: 22eaeed1-bdbd-4651-724e-42ae6c43e387
"""
-RETURN = """
+RETURN = r"""
result:
- description:
- - The bootstrap result as returned by the consul HTTP API.
- - "B(Note:) If O(bootstrap_secret) has been specified the C(SecretID) and
- C(ID) will not contain the secret but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER).
- If you pass O(bootstrap_secret), make sure your playbook/role does not depend
- on this return value!"
- returned: changed
- type: dict
- sample:
- AccessorID: 834a5881-10a9-a45b-f63c-490e28743557
- CreateIndex: 25
- CreateTime: '2024-01-21T20:26:27.114612038+01:00'
- Description: Bootstrap Token (Global Management)
- Hash: X2AgaFhnQGRhSSF/h0m6qpX1wj/HJWbyXcxkEM/5GrY=
- ID: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER
- Local: false
- ModifyIndex: 25
- Policies:
+ description:
+ - The bootstrap result as returned by the Consul HTTP API.
+ - B(Note:) If O(bootstrap_secret) has been specified the C(SecretID) and C(ID) will not contain the secret but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER).
+ If you pass O(bootstrap_secret), make sure your playbook/role does not depend on this return value!
+ returned: changed
+ type: dict
+ sample:
+ AccessorID: 834a5881-10a9-a45b-f63c-490e28743557
+ CreateIndex: 25
+ CreateTime: '2024-01-21T20:26:27.114612038+01:00'
+ Description: Bootstrap Token (Global Management)
+ Hash: X2AgaFhnQGRhSSF/h0m6qpX1wj/HJWbyXcxkEM/5GrY=
+ ID: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER
+ Local: false
+ ModifyIndex: 25
+ Policies:
- ID: 00000000-0000-0000-0000-000000000001
Name: global-management
- SecretID: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER
+ SecretID: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER
"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/consul_agent_check.py b/plugins/modules/consul_agent_check.py
index 3739260049..ca1639063c 100644
--- a/plugins/modules/consul_agent_check.py
+++ b/plugins/modules/consul_agent_check.py
@@ -9,20 +9,17 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: consul_agent_check
-short_description: Add, modify, and delete checks within a consul cluster
+short_description: Add, modify, and delete checks within a Consul cluster
version_added: 9.1.0
description:
- - Allows the addition, modification and deletion of checks in a consul
- cluster via the agent. For more details on using and configuring Checks,
- see U(https://developer.hashicorp.com/consul/api-docs/agent/check).
- - Currently, there is no complete way to retrieve the script, interval or TTL
- metadata for a registered check. Without this metadata it is not possible to
- tell if the data supplied with ansible represents a change to a check. As a
- result this does not attempt to determine changes and will always report a
- changed occurred. An API method is planned to supply this metadata so at that
- stage change management will be added.
+ - Allows the addition, modification and deletion of checks in a Consul cluster using the agent. For more details on using
+ and configuring Checks, see U(https://developer.hashicorp.com/consul/api-docs/agent/check).
+ - Currently, there is no complete way to retrieve the script, interval or TTL metadata for a registered check. Without this
+ metadata it is not possible to tell if the data supplied with ansible represents a change to a check. As a result this
+ does not attempt to determine changes and will always report a changed occurred. An API method is planned to supply this
+ metadata so at that stage change management will be added.
author:
- Michael Ilg (@Ilgmi)
extends_documentation_fragment:
@@ -34,13 +31,13 @@ attributes:
check_mode:
support: full
details:
- - The result is the object as it is defined in the module options and not the object structure of the consul API.
- For a better overview of what the object structure looks like,
- take a look at U(https://developer.hashicorp.com/consul/api-docs/agent/check#list-checks).
+ - The result is the object as it is defined in the module options and not the object structure of the Consul API. For
+ a better overview of what the object structure looks like, take a look at U(https://developer.hashicorp.com/consul/api-docs/agent/check#list-checks).
diff_mode:
support: partial
details:
- - In check mode the diff will show the object as it is defined in the module options and not the object structure of the consul API.
+ - In check mode the diff will show the object as it is defined in the module options and not the object structure of
+ the Consul API.
options:
state:
description:
@@ -50,18 +47,18 @@ options:
type: str
name:
description:
- - Required name for the service check.
+ - Required name for the service check.
type: str
id:
description:
- - Specifies a unique ID for this check on the node. This defaults to the O(name) parameter, but it may be necessary to provide
- an ID for uniqueness. This value will return in the response as "CheckId".
+ - Specifies a unique ID for this check on the node. This defaults to the O(name) parameter, but it may be necessary
+ to provide an ID for uniqueness. This value will return in the response as "CheckId".
type: str
interval:
description:
- - The interval at which the service check will be run.
- This is a number with a V(s) or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m).
- If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
+ - The interval at which the service check will be run. This is a number with a V(s) or V(m) suffix to signify the units
+ of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used by default, for example
+ V(10) will be V(10s).
- Required if one of the parameters O(args), O(http), or O(tcp) is specified.
type: str
notes:
@@ -77,46 +74,41 @@ options:
elements: str
ttl:
description:
- - Checks can be registered with a TTL instead of a O(args) and O(interval)
- this means that the service will check in with the agent before the
- TTL expires. If it doesn't the check will be considered failed.
- Required if registering a check and the script an interval are missing
- Similar to the interval this is a number with a V(s) or V(m) suffix to
- signify the units of seconds or minutes, for example V(15s) or V(1m).
- If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
+ - Checks can be registered with a TTL instead of a O(args) and O(interval) this means that the service will check in
+ with the agent before the TTL expires. If it does not the check will be considered failed. Required if registering
+ a check and the script an interval are missing Similar to the interval this is a number with a V(s) or V(m) suffix
+ to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used
+ by default, for example V(10) will be V(10s).
- Mutually exclusive with O(args), O(tcp) and O(http).
type: str
tcp:
description:
- - Checks can be registered with a TCP port. This means that consul
- will check if the connection attempt to that port is successful (that is, the port is currently accepting connections).
- The format is V(host:port), for example V(localhost:80).
+ - Checks can be registered with a TCP port. This means that Consul will check if the connection attempt to that port
+ is successful (that is, the port is currently accepting connections). The format is V(host:port), for example V(localhost:80).
- Requires O(interval) to be provided.
- Mutually exclusive with O(args), O(ttl) and O(http).
type: str
version_added: '1.3.0'
http:
description:
- - Checks can be registered with an HTTP endpoint. This means that consul
- will check that the http endpoint returns a successful HTTP status.
+ - Checks can be registered with an HTTP endpoint. This means that Consul will check that the http endpoint returns a
+ successful HTTP status.
- Requires O(interval) to be provided.
- Mutually exclusive with O(args), O(ttl) and O(tcp).
type: str
timeout:
description:
- - A custom HTTP check timeout. The consul default is 10 seconds.
- Similar to the interval this is a number with a V(s) or V(m) suffix to
- signify the units of seconds or minutes, for example V(15s) or V(1m).
- If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
+ - A custom HTTP check timeout. The Consul default is 10 seconds. Similar to the interval this is a number with a V(s)
+ or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s)
+ will be used by default, for example V(10) will be V(10s).
type: str
service_id:
description:
- - The ID for the service, must be unique per node. If O(state=absent),
- defaults to the service name if supplied.
+ - The ID for the service, must be unique per node. If O(state=absent), defaults to the service name if supplied.
type: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Register tcp check for service 'nginx'
community.general.consul_agent_check:
name: nginx_tcp_check
@@ -138,24 +130,24 @@ EXAMPLES = '''
state: absent
id: nginx_http_check
service_id: "{{ nginx_service.ID }}"
-'''
+"""
-RETURN = """
+RETURN = r"""
check:
- description: The check as returned by the consul HTTP API.
- returned: always
- type: dict
- sample:
- CheckID: nginx_check
- ServiceID: nginx
- Interval: 30s
- Type: http
- Notes: Nginx Check
+ description: The check as returned by the Consul HTTP API.
+ returned: always
+ type: dict
+ sample:
+ CheckID: nginx_check
+ ServiceID: nginx
+ Interval: 30s
+ Type: http
+ Notes: Nginx Check
operation:
- description: The operation performed.
- returned: changed
- type: str
- sample: update
+ description: The operation performed.
+ returned: changed
+ type: str
+ sample: update
"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/consul_agent_service.py b/plugins/modules/consul_agent_service.py
index a8ef098970..bd28dfd2c3 100644
--- a/plugins/modules/consul_agent_service.py
+++ b/plugins/modules/consul_agent_service.py
@@ -9,17 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: consul_agent_service
-short_description: Add, modify and delete services within a consul cluster
+short_description: Add, modify and delete services within a Consul cluster
version_added: 9.1.0
description:
- - Allows the addition, modification and deletion of services in a consul
- cluster via the agent.
- - There are currently no plans to create services and checks in one.
- This is because the Consul API does not provide checks for a service and
- the checks themselves do not match the module parameters.
- Therefore, only a service without checks can be created in this module.
+ - Allows the addition, modification and deletion of services in a Consul cluster using the agent.
+ - There are currently no plans to create services and checks in one. This is because the Consul API does not provide checks
+ for a service and the checks themselves do not match the module parameters. Therefore, only a service without checks can
+ be created in this module.
author:
- Michael Ilg (@Ilgmi)
extends_documentation_fragment:
@@ -43,13 +41,12 @@ options:
type: str
name:
description:
- - Unique name for the service on a node, must be unique per node,
- required if registering a service.
+ - Unique name for the service on a node, must be unique per node, required if registering a service.
type: str
id:
description:
- - Specifies a unique ID for this service. This must be unique per agent. This defaults to the O(name) parameter if not provided.
- If O(state=absent), defaults to the service name if supplied.
+ - Specifies a unique ID for this service. This must be unique per agent. This defaults to the O(name) parameter if not
+ provided. If O(state=absent), defaults to the service name if supplied.
type: str
tags:
description:
@@ -58,36 +55,33 @@ options:
elements: str
address:
description:
- - The address to advertise that the service will be listening on.
- This value will be passed as the C(address) parameter to Consul's
- C(/v1/agent/service/register) API method, so refer to the Consul API
- documentation for further details.
+ - The address to advertise that the service will be listening on. This value will be passed as the C(address) parameter
+ to Consul's C(/v1/agent/service/register) API method, so refer to the Consul API documentation for further details.
type: str
meta:
description:
- - Optional meta data used for filtering.
- For keys, the characters C(A-Z), C(a-z), C(0-9), C(_), C(-) are allowed.
- Not allowed characters are replaced with underscores.
+ - Optional meta data used for filtering. For keys, the characters C(A-Z), C(a-z), C(0-9), C(_), C(-) are allowed. Not
+ allowed characters are replaced with underscores.
type: dict
service_port:
description:
- - The port on which the service is listening. Can optionally be supplied for
- registration of a service, that is if O(name) or O(id) is set.
+ - The port on which the service is listening. Can optionally be supplied for registration of a service, that is if O(name)
+ or O(id) is set.
type: int
enable_tag_override:
description:
- - Specifies to disable the anti-entropy feature for this service's tags.
- If EnableTagOverride is set to true then external agents can update this service in the catalog and modify the tags.
+ - Specifies to disable the anti-entropy feature for this service's tags. If C(EnableTagOverride) is set to true then
+ external agents can update this service in the catalog and modify the tags.
type: bool
- default: False
+ default: false
weights:
description:
- - Specifies weights for the service
+ - Specifies weights for the service.
type: dict
suboptions:
passing:
description:
- - Weights for passing.
+ - Weights for passing.
type: int
default: 1
warning:
@@ -96,10 +90,10 @@ options:
type: int
default: 1
default: {"passing": 1, "warning": 1}
-'''
+"""
-EXAMPLES = '''
-- name: Register nginx service with the local consul agent
+EXAMPLES = r"""
+- name: Register nginx service with the local Consul agent
community.general.consul_agent_service:
host: consul1.example.com
token: some_management_acl
@@ -162,33 +156,33 @@ EXAMPLES = '''
tags:
- prod
- worker
-'''
+"""
-RETURN = """
+RETURN = r"""
service:
- description: The service as returned by the consul HTTP API.
- returned: always
- type: dict
- sample:
- ID: nginx
- Service: nginx
- Address: localhost
- Port: 80
- Tags:
- - http
- Meta:
- - nginx_version: 1.23.3
- Datacenter: dc1
- Weights:
- Passing: 1
- Warning: 1
- ContentHash: 61a245cd985261ac
- EnableTagOverride: false
+ description: The service as returned by the Consul HTTP API.
+ returned: always
+ type: dict
+ sample:
+ ID: nginx
+ Service: nginx
+ Address: localhost
+ Port: 80
+ Tags:
+ - http
+ Meta:
+ - nginx_version: 1.23.3
+ Datacenter: dc1
+ Weights:
+ Passing: 1
+ Warning: 1
+ ContentHash: 61a245cd985261ac
+ EnableTagOverride: false
operation:
- description: The operation performed.
- returned: changed
- type: str
- sample: update
+ description: The operation performed.
+ returned: changed
+ type: str
+ sample: update
"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/consul_auth_method.py b/plugins/modules/consul_auth_method.py
index e28474c313..a5cfd3b305 100644
--- a/plugins/modules/consul_auth_method.py
+++ b/plugins/modules/consul_auth_method.py
@@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
+DOCUMENTATION = r"""
module: consul_auth_method
short_description: Manipulate Consul auth methods
version_added: 8.3.0
description:
- - Allows the addition, modification and deletion of auth methods in a consul
- cluster via the agent. For more details on using and configuring ACLs,
- see U(https://www.consul.io/docs/guides/acl.html).
+ - Allows the addition, modification and deletion of auth methods in a Consul cluster using the agent. For more details on
+ using and configuring ACLs, see U(https://www.consul.io/docs/guides/acl.html).
author:
- Florian Apolloner (@apollo13)
extends_documentation_fragment:
@@ -77,7 +76,7 @@ options:
type: dict
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create an auth method
community.general.consul_auth_method:
name: test
@@ -103,9 +102,9 @@ EXAMPLES = """
token: "{{ consul_management_token }}"
"""
-RETURN = """
+RETURN = r"""
auth_method:
- description: The auth method as returned by the consul HTTP API.
+ description: The auth method as returned by the Consul HTTP API.
returned: always
type: dict
sample:
@@ -126,10 +125,10 @@ auth_method:
Name: test
Type: jwt
operation:
- description: The operation performed.
- returned: changed
- type: str
- sample: update
+ description: The operation performed.
+ returned: changed
+ type: str
+ sample: update
"""
import re
diff --git a/plugins/modules/consul_binding_rule.py b/plugins/modules/consul_binding_rule.py
index 6a2882cee2..698ba5913f 100644
--- a/plugins/modules/consul_binding_rule.py
+++ b/plugins/modules/consul_binding_rule.py
@@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
+DOCUMENTATION = r"""
module: consul_binding_rule
short_description: Manipulate Consul binding rules
version_added: 8.3.0
description:
- - Allows the addition, modification and deletion of binding rules in a consul
- cluster via the agent. For more details on using and configuring binding rules,
- see U(https://developer.hashicorp.com/consul/api-docs/acl/binding-rules).
+ - Allows the addition, modification and deletion of binding rules in a Consul cluster using the agent. For more details
+ on using and configuring binding rules, see U(https://developer.hashicorp.com/consul/api-docs/acl/binding-rules).
author:
- Florian Apolloner (@apollo13)
extends_documentation_fragment:
@@ -41,7 +40,8 @@ options:
name:
description:
- Specifies a name for the binding rule.
- - 'Note: This is used to identify the binding rule. But since the API does not support a name, it is prefixed to the description.'
+ - 'Note: This is used to identify the binding rule. But since the API does not support a name, it is prefixed to the
+ description.'
type: str
required: true
description:
@@ -74,7 +74,7 @@ options:
type: dict
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create a binding rule
community.general.consul_binding_rule:
name: my_name
@@ -91,9 +91,9 @@ EXAMPLES = """
state: absent
"""
-RETURN = """
+RETURN = r"""
binding_rule:
- description: The binding rule as returned by the consul HTTP API.
+ description: The binding rule as returned by the Consul HTTP API.
returned: always
type: dict
sample:
diff --git a/plugins/modules/consul_kv.py b/plugins/modules/consul_kv.py
index fd3a1fce06..8152dd5c25 100644
--- a/plugins/modules/consul_kv.py
+++ b/plugins/modules/consul_kv.py
@@ -10,15 +10,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: consul_kv
-short_description: Manipulate entries in the key/value store of a consul cluster
+short_description: Manipulate entries in the key/value store of a Consul cluster
description:
- - Allows the retrieval, addition, modification and deletion of key/value entries in a
- consul cluster via the agent. The entire contents of the record, including
- the indices, flags and session are returned as C(value).
- - If the O(key) represents a prefix then note that when a value is removed, the existing
- value if any is returned as part of the results.
+ - Allows the retrieval, addition, modification and deletion of key/value entries in a Consul cluster using the agent. The
+ entire contents of the record, including the indices, flags and session are returned as C(value).
+ - If the O(key) represents a prefix then note that when a value is removed, the existing value if any is returned as part
+ of the results.
- See http://www.consul.io/docs/agent/http.html#kv for more details.
requirements:
- python-consul
@@ -29,98 +28,89 @@ author:
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - The action to take with the supplied key and value. If the state is V(present) and O(value) is set, the key
- contents will be set to the value supplied and C(changed) will be set to V(true) only if the value was
- different to the current contents. If the state is V(present) and O(value) is not set, the existing value
- associated to the key will be returned. The state V(absent) will remove the key/value pair,
- again C(changed) will be set to V(true) only if the key actually existed
- prior to the removal. An attempt can be made to obtain or free the
- lock associated with a key/value pair with the states V(acquire) or
- V(release) respectively. a valid session must be supplied to make the
- attempt changed will be true if the attempt is successful, false
- otherwise.
- type: str
- choices: [ absent, acquire, present, release ]
- default: present
- key:
- description:
- - The key at which the value should be stored.
- type: str
- required: true
- value:
- description:
- - The value should be associated with the given key, required if O(state)
- is V(present).
- type: str
- recurse:
- description:
- - If the key represents a prefix, each entry with the prefix can be
- retrieved by setting this to V(true).
- type: bool
- retrieve:
- description:
- - If the O(state) is V(present) and O(value) is set, perform a
- read after setting the value and return this value.
- default: true
- type: bool
- session:
- description:
- - The session that should be used to acquire or release a lock
- associated with a key/value pair.
- type: str
- token:
- description:
- - The token key identifying an ACL rule set that controls access to
- the key value pair
- type: str
- cas:
- description:
- - Used when acquiring a lock with a session. If the O(cas) is V(0), then
- Consul will only put the key if it does not already exist. If the
- O(cas) value is non-zero, then the key is only set if the index matches
- the ModifyIndex of that key.
- type: str
- flags:
- description:
- - Opaque positive integer value that can be passed when setting a value.
- type: str
- host:
- description:
- - Host of the consul agent.
- type: str
- default: localhost
- port:
- description:
- - The port on which the consul agent is running.
- type: int
- default: 8500
- scheme:
- description:
- - The protocol scheme on which the consul agent is running.
- type: str
- default: http
- validate_certs:
- description:
- - Whether to verify the tls certificate of the consul agent.
- type: bool
- default: true
- datacenter:
- description:
- - The name of the datacenter to query. If unspecified, the query will default
- to the datacenter of the Consul agent on O(host).
- type: str
- version_added: 10.0.0
-'''
+ state:
+ description:
+ - The action to take with the supplied key and value. If the state is V(present) and O(value) is set, the key contents
+ will be set to the value supplied and C(changed) will be set to V(true) only if the value was different to the current
+ contents. If the state is V(present) and O(value) is not set, the existing value associated to the key will be returned.
+ The state V(absent) will remove the key/value pair, again C(changed) will be set to V(true) only if the key actually
+ existed prior to the removal. An attempt can be made to obtain or free the lock associated with a key/value pair with
+ the states V(acquire) or V(release) respectively. A valid session must be supplied to make the attempt C(changed)
+ will be V(true) if the attempt is successful, V(false) otherwise.
+ type: str
+ choices: [absent, acquire, present, release]
+ default: present
+ key:
+ description:
+ - The key at which the value should be stored.
+ type: str
+ required: true
+ value:
+ description:
+ - The value should be associated with the given key, required if O(state) is V(present).
+ type: str
+ recurse:
+ description:
+ - If the key represents a prefix, each entry with the prefix can be retrieved by setting this to V(true).
+ type: bool
+ retrieve:
+ description:
+ - If the O(state) is V(present) and O(value) is set, perform a read after setting the value and return this value.
+ default: true
+ type: bool
+ session:
+ description:
+ - The session that should be used to acquire or release a lock associated with a key/value pair.
+ type: str
+ token:
+ description:
+ - The token key identifying an ACL rule set that controls access to the key value pair.
+ type: str
+ cas:
+ description:
+ - Used when acquiring a lock with a session. If the O(cas) is V(0), then Consul will only put the key if it does not
+ already exist. If the O(cas) value is non-zero, then the key is only set if the index matches the ModifyIndex of that
+ key.
+ type: str
+ flags:
+ description:
+ - Opaque positive integer value that can be passed when setting a value.
+ type: str
+ host:
+ description:
+ - Host of the Consul agent.
+ type: str
+ default: localhost
+ port:
+ description:
+ - The port on which the Consul agent is running.
+ type: int
+ default: 8500
+ scheme:
+ description:
+ - The protocol scheme on which the Consul agent is running.
+ type: str
+ default: http
+ validate_certs:
+ description:
+ - Whether to verify the tls certificate of the Consul agent.
+ type: bool
+ default: true
+ datacenter:
+ description:
+ - The name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent
+ on O(host).
+ type: str
+ version_added: 10.0.0
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# If the key does not exist, the value associated to the "data" property in `retrieved_key` will be `None`
# If the key value is empty string, `retrieved_key["data"]["Value"]` will be `None`
- name: Retrieve a value from the key/value store
@@ -138,7 +128,7 @@ EXAMPLES = '''
key: somekey
state: absent
-- name: Add a node to an arbitrary group via consul inventory (see consul.ini)
+- name: Add a node to an arbitrary group using Consul inventory (see consul.ini)
community.general.consul_kv:
key: ansible/groups/dc1/somenode
value: top_secret
@@ -149,7 +139,7 @@ EXAMPLES = '''
value: 20160509
session: "{{ sessionid }}"
state: acquire
-'''
+"""
from ansible.module_utils.common.text.converters import to_text
diff --git a/plugins/modules/consul_policy.py b/plugins/modules/consul_policy.py
index 36139ac097..c9758780b2 100644
--- a/plugins/modules/consul_policy.py
+++ b/plugins/modules/consul_policy.py
@@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
+DOCUMENTATION = r"""
module: consul_policy
short_description: Manipulate Consul policies
version_added: 7.2.0
description:
- - Allows the addition, modification and deletion of policies in a consul
- cluster via the agent. For more details on using and configuring ACLs,
- see U(https://www.consul.io/docs/guides/acl.html).
+ - Allows the addition, modification and deletion of policies in a Consul cluster using the agent. For more details on using
+ and configuring ACLs, see U(https://www.consul.io/docs/guides/acl.html).
author:
- Håkon Lerring (@Hakon)
extends_documentation_fragment:
@@ -49,8 +48,7 @@ options:
elements: str
name:
description:
- - The name that should be associated with the policy, this is opaque
- to Consul.
+ - The name that should be associated with the policy, this is opaque to Consul.
required: true
type: str
description:
@@ -63,19 +61,19 @@ options:
- Rule document that should be associated with the current policy.
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create a policy with rules
community.general.consul_policy:
host: consul1.example.com
token: some_management_acl
name: foo-access
rules: |
- key "foo" {
- policy = "read"
- }
- key "private/foo" {
- policy = "deny"
- }
+ key "foo" {
+ policy = "read"
+ }
+ key "private/foo" {
+ policy = "deny"
+ }
- name: Update the rules associated to a policy
community.general.consul_policy:
@@ -83,15 +81,15 @@ EXAMPLES = """
token: some_management_acl
name: foo-access
rules: |
- key "foo" {
- policy = "read"
- }
- key "private/foo" {
- policy = "deny"
- }
- event "bbq" {
- policy = "write"
- }
+ key "foo" {
+ policy = "read"
+ }
+ key "private/foo" {
+ policy = "deny"
+ }
+ event "bbq" {
+ policy = "write"
+ }
- name: Remove a policy
community.general.consul_policy:
@@ -101,28 +99,28 @@ EXAMPLES = """
state: absent
"""
-RETURN = """
+RETURN = r"""
policy:
- description: The policy as returned by the consul HTTP API.
- returned: always
- type: dict
- sample:
- CreateIndex: 632
- Description: Testing
- Hash: rj5PeDHddHslkpW7Ij4OD6N4bbSXiecXFmiw2SYXg2A=
- Name: foo-access
- Rules: |-
- key "foo" {
- policy = "read"
- }
- key "private/foo" {
- policy = "deny"
- }
+ description: The policy as returned by the Consul HTTP API.
+ returned: always
+ type: dict
+ sample:
+ CreateIndex: 632
+ Description: Testing
+ Hash: rj5PeDHddHslkpW7Ij4OD6N4bbSXiecXFmiw2SYXg2A=
+ Name: foo-access
+ Rules: |-
+ key "foo" {
+ policy = "read"
+ }
+ key "private/foo" {
+ policy = "deny"
+ }
operation:
- description: The operation performed.
- returned: changed
- type: str
- sample: update
+ description: The operation performed.
+ returned: changed
+ type: str
+ sample: update
"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/consul_role.py b/plugins/modules/consul_role.py
index d6c4e4dd92..9ba9856744 100644
--- a/plugins/modules/consul_role.py
+++ b/plugins/modules/consul_role.py
@@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
+DOCUMENTATION = r"""
module: consul_role
short_description: Manipulate Consul roles
version_added: 7.5.0
description:
- - Allows the addition, modification and deletion of roles in a consul
- cluster via the agent. For more details on using and configuring ACLs,
- see U(https://www.consul.io/docs/guides/acl.html).
+ - Allows the addition, modification and deletion of roles in a Consul cluster using the agent. For more details on using
+ and configuring ACLs, see U(https://www.consul.io/docs/guides/acl.html).
author:
- Håkon Lerring (@Hakon)
extends_documentation_fragment:
@@ -42,7 +41,7 @@ options:
type: str
state:
description:
- - whether the role should be present or absent.
+ - Whether the role should be present or absent.
choices: ['present', 'absent']
default: present
type: str
@@ -98,9 +97,9 @@ options:
description:
- The name of the node.
- Must not be longer than 256 characters, must start and end with a lowercase alphanumeric character.
- - May only contain lowercase alphanumeric characters as well as - and _.
- - This suboption has been renamed from O(service_identities[].name) to O(service_identities[].service_name)
- in community.general 8.3.0. The old name can still be used.
+ - May only contain lowercase alphanumeric characters as well as V(-) and V(_).
+ - This suboption has been renamed from O(service_identities[].name) to O(service_identities[].service_name) in community.general
+ 8.3.0. The old name can still be used.
type: str
required: true
aliases:
@@ -110,7 +109,7 @@ options:
- The datacenters the policies will be effective.
- This will result in effective policy only being valid in this datacenter.
- If an empty array (V([])) is specified, the policies will valid in all datacenters.
- - including those which do not yet exist but may in the future.
+ - Including those which do not yet exist but may in the future.
type: list
elements: str
node_identities:
@@ -125,9 +124,9 @@ options:
description:
- The name of the node.
- Must not be longer than 256 characters, must start and end with a lowercase alphanumeric character.
- - May only contain lowercase alphanumeric characters as well as - and _.
- - This suboption has been renamed from O(node_identities[].name) to O(node_identities[].node_name)
- in community.general 8.3.0. The old name can still be used.
+ - May only contain lowercase alphanumeric characters as well as V(-) and V(_).
+ - This suboption has been renamed from O(node_identities[].name) to O(node_identities[].node_name) in community.general
+ 8.3.0. The old name can still be used.
type: str
required: true
aliases:
@@ -140,7 +139,7 @@ options:
required: true
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create a role with 2 policies
community.general.consul_role:
host: consul1.example.com
@@ -177,28 +176,28 @@ EXAMPLES = """
state: absent
"""
-RETURN = """
+RETURN = r"""
role:
- description: The role object.
- returned: success
- type: dict
- sample:
- {
- "CreateIndex": 39,
- "Description": "",
- "Hash": "Trt0QJtxVEfvTTIcdTUbIJRr6Dsi6E4EcwSFxx9tCYM=",
- "ID": "9a300b8d-48db-b720-8544-a37c0f5dafb5",
- "ModifyIndex": 39,
- "Name": "foo-role",
- "Policies": [
- {"ID": "b1a00172-d7a1-0e66-a12e-7a4045c4b774", "Name": "foo-access"}
- ]
- }
+ description: The role object.
+ returned: success
+ type: dict
+ sample:
+ {
+ "CreateIndex": 39,
+ "Description": "",
+ "Hash": "Trt0QJtxVEfvTTIcdTUbIJRr6Dsi6E4EcwSFxx9tCYM=",
+ "ID": "9a300b8d-48db-b720-8544-a37c0f5dafb5",
+ "ModifyIndex": 39,
+ "Name": "foo-role",
+ "Policies": [
+ {"ID": "b1a00172-d7a1-0e66-a12e-7a4045c4b774", "Name": "foo-access"}
+ ]
+ }
operation:
- description: The operation performed on the role.
- returned: changed
- type: str
- sample: update
+ description: The operation performed on the role.
+ returned: changed
+ type: str
+ sample: update
"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/consul_session.py b/plugins/modules/consul_session.py
index 87a5f19143..a72136ad66 100644
--- a/plugins/modules/consul_session.py
+++ b/plugins/modules/consul_session.py
@@ -8,14 +8,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: consul_session
-short_description: Manipulate consul sessions
+short_description: Manipulate Consul sessions
description:
- - Allows the addition, modification and deletion of sessions in a consul
- cluster. These sessions can then be used in conjunction with key value pairs
- to implement distributed locks. In depth documentation for working with
- sessions can be found at http://www.consul.io/docs/internals/sessions.html
+ - Allows the addition, modification and deletion of sessions in a Consul cluster. These sessions can then be used in conjunction
+ with key value pairs to implement distributed locks. In depth documentation for working with sessions can be found at
+ U(http://www.consul.io/docs/internals/sessions.html).
author:
- Steve Gargan (@sgargan)
- Håkon Lerring (@Hakon)
@@ -25,78 +24,69 @@ extends_documentation_fragment:
- community.general.consul.token
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
- action_group:
- version_added: 8.3.0
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
+ action_group:
+ version_added: 8.3.0
options:
- id:
- description:
- - ID of the session, required when O(state) is either V(info) or
- V(remove).
- type: str
- state:
- description:
- - Whether the session should be present i.e. created if it doesn't
- exist, or absent, removed if present. If created, the O(id) for the
- session is returned in the output. If V(absent), O(id) is
- required to remove the session. Info for a single session, all the
- sessions for a node or all available sessions can be retrieved by
- specifying V(info), V(node) or V(list) for the O(state); for V(node)
- or V(info), the node O(name) or session O(id) is required as parameter.
- choices: [ absent, info, list, node, present ]
- type: str
- default: present
- name:
- description:
- - The name that should be associated with the session. Required when
- O(state=node) is used.
- type: str
- delay:
- description:
- - The optional lock delay that can be attached to the session when it
- is created. Locks for invalidated sessions ar blocked from being
- acquired until this delay has expired. Durations are in seconds.
- type: int
- default: 15
- node:
- description:
- - The name of the node that with which the session will be associated.
- by default this is the name of the agent.
- type: str
- datacenter:
- description:
- - The name of the datacenter in which the session exists or should be
- created.
- type: str
- checks:
- description:
- - Checks that will be used to verify the session health. If
- all the checks fail, the session will be invalidated and any locks
- associated with the session will be release and can be acquired once
- the associated lock delay has expired.
- type: list
- elements: str
- behavior:
- description:
- - The optional behavior that can be attached to the session when it
- is created. This controls the behavior when a session is invalidated.
- choices: [ delete, release ]
- type: str
- default: release
- ttl:
- description:
- - Specifies the duration of a session in seconds (between 10 and 86400).
- type: int
- version_added: 5.4.0
- token:
- version_added: 5.6.0
-'''
+ id:
+ description:
+ - ID of the session, required when O(state) is either V(info) or V(remove).
+ type: str
+ state:
+ description:
+ - Whether the session should be present, in other words it should be created if it does not exist, or absent, removed
+ if present. If created, the O(id) for the session is returned in the output. If V(absent), O(id) is required to remove
+ the session. Info for a single session, all the sessions for a node or all available sessions can be retrieved by
+ specifying V(info), V(node) or V(list) for the O(state); for V(node) or V(info), the node O(name) or session O(id)
+ is required as parameter.
+ choices: [absent, info, list, node, present]
+ type: str
+ default: present
+ name:
+ description:
+ - The name that should be associated with the session. Required when O(state=node) is used.
+ type: str
+ delay:
+ description:
+ - The optional lock delay that can be attached to the session when it is created. Locks for invalidated sessions ar
+ blocked from being acquired until this delay has expired. Durations are in seconds.
+ type: int
+ default: 15
+ node:
+ description:
+ - The name of the node that with which the session will be associated. By default this is the name of the agent.
+ type: str
+ datacenter:
+ description:
+ - The name of the datacenter in which the session exists or should be created.
+ type: str
+ checks:
+ description:
+ - Checks that will be used to verify the session health. If all the checks fail, the session will be invalidated and
+ any locks associated with the session will be release and can be acquired once the associated lock delay has expired.
+ type: list
+ elements: str
+ behavior:
+ description:
+ - The optional behavior that can be attached to the session when it is created. This controls the behavior when a session
+ is invalidated.
+ choices: [delete, release]
+ type: str
+ default: release
+ ttl:
+ description:
+ - Specifies the duration of a session in seconds (between 10 and 86400).
+ type: int
+ version_added: 5.4.0
+ token:
+ version_added: 5.6.0
+"""
-EXAMPLES = '''
-- name: Register basic session with consul
+EXAMPLES = r"""
+- name: Register basic session with Consul
community.general.consul_session:
name: session1
@@ -123,8 +113,8 @@ EXAMPLES = '''
- name: Register session with a ttl
community.general.consul_session:
name: session-with-ttl
- ttl: 600 # sec
-'''
+ ttl: 600 # sec
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.consul import (
diff --git a/plugins/modules/consul_token.py b/plugins/modules/consul_token.py
index c8bc8bc279..b525b2dc2a 100644
--- a/plugins/modules/consul_token.py
+++ b/plugins/modules/consul_token.py
@@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
+DOCUMENTATION = r"""
module: consul_token
short_description: Manipulate Consul tokens
version_added: 8.3.0
description:
- - Allows the addition, modification and deletion of tokens in a consul
- cluster via the agent. For more details on using and configuring ACLs,
- see U(https://www.consul.io/docs/guides/acl.html).
+ - Allows the addition, modification and deletion of tokens in a Consul cluster using the agent. For more details on using
+ and configuring ACLs, see U(https://www.consul.io/docs/guides/acl.html).
author:
- Florian Apolloner (@apollo13)
extends_documentation_fragment:
@@ -42,13 +41,11 @@ options:
type: str
accessor_id:
description:
- - Specifies a UUID to use as the token's Accessor ID.
- If not specified a UUID will be generated for this field.
+ - Specifies a UUID to use as the token's Accessor ID. If not specified a UUID will be generated for this field.
type: str
secret_id:
description:
- - Specifies a UUID to use as the token's Secret ID.
- If not specified a UUID will be generated for this field.
+ - Specifies a UUID to use as the token's Secret ID. If not specified a UUID will be generated for this field.
type: str
description:
description:
@@ -125,7 +122,7 @@ options:
description:
- The datacenters the token will be effective.
- If an empty array (V([])) is specified, the token will valid in all datacenters.
- - including those which do not yet exist but may in the future.
+ - Including those which do not yet exist but may in the future.
type: list
elements: str
node_identities:
@@ -151,18 +148,16 @@ options:
required: true
local:
description:
- - If true, indicates that the token should not be replicated globally
- and instead be local to the current datacenter.
+ - If true, indicates that the token should not be replicated globally and instead be local to the current datacenter.
type: bool
expiration_ttl:
description:
- - This is a convenience field and if set will initialize the C(expiration_time).
- Can be specified in the form of V(60s) or V(5m) (that is, 60 seconds or 5 minutes,
- respectively). Ingored when the token is updated!
+ - This is a convenience field and if set will initialize the C(expiration_time). Can be specified in the form of V(60s)
+ or V(5m) (that is, 60 seconds or 5 minutes, respectively). Ingored when the token is updated!
type: str
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create / Update a token by accessor_id
community.general.consul_token:
state: present
@@ -186,26 +181,26 @@ EXAMPLES = """
token: 8adddd91-0bd6-d41d-ae1a-3b49cfa9a0e8
"""
-RETURN = """
+RETURN = r"""
token:
- description: The token as returned by the consul HTTP API.
- returned: always
- type: dict
- sample:
- AccessorID: 07a7de84-c9c7-448a-99cc-beaf682efd21
- CreateIndex: 632
- CreateTime: "2024-01-14T21:53:01.402749174+01:00"
- Description: Testing
- Hash: rj5PeDHddHslkpW7Ij4OD6N4bbSXiecXFmiw2SYXg2A=
- Local: false
- ModifyIndex: 633
- SecretID: bd380fba-da17-7cee-8576-8d6427c6c930
- ServiceIdentities: [{"ServiceName": "test"}]
+ description: The token as returned by the Consul HTTP API.
+ returned: always
+ type: dict
+ sample:
+ AccessorID: 07a7de84-c9c7-448a-99cc-beaf682efd21
+ CreateIndex: 632
+ CreateTime: "2024-01-14T21:53:01.402749174+01:00"
+ Description: Testing
+ Hash: rj5PeDHddHslkpW7Ij4OD6N4bbSXiecXFmiw2SYXg2A=
+ Local: false
+ ModifyIndex: 633
+ SecretID: bd380fba-da17-7cee-8576-8d6427c6c930
+ ServiceIdentities: ["ServiceName": "test"]
operation:
- description: The operation performed.
- returned: changed
- type: str
- sample: update
+ description: The operation performed.
+ returned: changed
+ type: str
+ sample: update
"""
from ansible.module_utils.basic import AnsibleModule
@@ -225,7 +220,7 @@ def normalize_link_obj(api_obj, module_obj, key):
for obj in module_objs:
identifier = obj.get("ID")
- name = obj.get("Name)")
+ name = obj.get("Name")
if identifier and not name and identifier in id_to_name:
obj["Name"] = id_to_name[identifier]
if not identifier and name and name in name_to_id:
diff --git a/plugins/modules/copr.py b/plugins/modules/copr.py
index 809064114a..739092b8af 100644
--- a/plugins/modules/copr.py
+++ b/plugins/modules/copr.py
@@ -9,61 +9,60 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r"""
----
module: copr
short_description: Manage one of the Copr repositories
version_added: 2.0.0
description: This module can enable, disable or remove the specified repository.
author: Silvie Chlupova (@schlupov)
requirements:
- - dnf
- - dnf-plugins-core
+ - dnf
+ - dnf-plugins-core
notes:
- - Supports C(check_mode).
+ - Supports C(check_mode).
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- host:
- description: The Copr host to work with.
- default: copr.fedorainfracloud.org
- type: str
- protocol:
- description: This indicate which protocol to use with the host.
- default: https
- type: str
- name:
- description: Copr directory name, for example C(@copr/copr-dev).
- required: true
- type: str
- state:
- description:
- - Whether to set this project as V(enabled), V(disabled), or V(absent).
- default: enabled
- type: str
- choices: [absent, enabled, disabled]
- chroot:
- description:
- - The name of the chroot that you want to enable/disable/remove in the project,
- for example V(epel-7-x86_64). Default chroot is determined by the operating system,
- version of the operating system, and architecture on which the module is run.
- type: str
- includepkgs:
- description: List of packages to include.
- required: false
- type: list
- elements: str
- version_added: 9.4.0
- excludepkgs:
- description: List of packages to exclude.
- required: false
- type: list
- elements: str
- version_added: 9.4.0
+ host:
+ description: The Copr host to work with.
+ default: copr.fedorainfracloud.org
+ type: str
+ protocol:
+ description: This indicate which protocol to use with the host.
+ default: https
+ type: str
+ name:
+ description: Copr directory name, for example C(@copr/copr-dev).
+ required: true
+ type: str
+ state:
+ description:
+ - Whether to set this project as V(enabled), V(disabled), or V(absent).
+ default: enabled
+ type: str
+ choices: [absent, enabled, disabled]
+ chroot:
+ description:
+ - The name of the chroot that you want to enable/disable/remove in the project, for example V(epel-7-x86_64). Default
+ chroot is determined by the operating system, version of the operating system, and architecture on which the module
+ is run.
+ type: str
+ includepkgs:
+ description: List of packages to include.
+ required: false
+ type: list
+ elements: str
+ version_added: 9.4.0
+ excludepkgs:
+ description: List of packages to exclude.
+ required: false
+ type: list
+ elements: str
+ version_added: 9.4.0
"""
EXAMPLES = r"""
@@ -78,6 +77,13 @@ EXAMPLES = r"""
community.general.copr:
state: absent
name: '@copr/integration_tests'
+
+- name: Install Caddy
+ community.general.copr:
+ name: '@caddy/caddy'
+ chroot: fedora-rawhide-{{ ansible_facts.architecture }}
+ includepkgs:
+ - caddy
"""
RETURN = r"""
diff --git a/plugins/modules/cpanm.py b/plugins/modules/cpanm.py
index 04b3b06b7f..356cbbb215 100644
--- a/plugins/modules/cpanm.py
+++ b/plugins/modules/cpanm.py
@@ -10,14 +10,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: cpanm
short_description: Manages Perl library dependencies
description:
-- Manage Perl library dependencies using cpanminus.
+ - Manage Perl library dependencies using cpanminus.
extends_documentation_fragment:
-- community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
@@ -27,82 +26,95 @@ options:
name:
type: str
description:
- - The Perl library to install. Valid values change according to the O(mode), see notes for more details.
- - Note that for installing from a local path the parameter O(from_path) should be used.
+ - The Perl library to install. Valid values change according to the O(mode), see notes for more details.
+ - Note that for installing from a local path the parameter O(from_path) should be used.
aliases: [pkg]
from_path:
type: path
description:
- - The local directory or C(tar.gz) file to install from.
+ - The local directory or C(tar.gz) file to install from.
notest:
description:
- - Do not run unit tests.
+ - Do not run unit tests.
type: bool
default: false
locallib:
description:
- - Specify the install base to install modules.
+ - Specify the install base to install modules.
type: path
mirror:
description:
- - Specifies the base URL for the CPAN mirror to use.
+ - Specifies the base URL for the CPAN mirror to use.
type: str
mirror_only:
description:
- - Use the mirror's index file instead of the CPAN Meta DB.
+ - Use the mirror's index file instead of the CPAN Meta DB.
type: bool
default: false
installdeps:
description:
- - Only install dependencies.
+ - Only install dependencies.
type: bool
default: false
+ install_recommendations:
+ description:
+ - If V(true), installs dependencies declared as recommends per META spec.
+ - If V(false), it ensures the dependencies declared as recommends are not installed, overriding any decision made earlier in E(PERL_CPANM_OPT).
+ - If parameter is not set, C(cpanm) will use its existing defaults.
+ - When these dependencies fail to install, cpanm continues the installation, since they are just recommendation.
+ type: bool
+ version_added: 10.3.0
+ install_suggestions:
+ description:
+ - If V(true), installs dependencies declared as suggests per META spec.
+ - If V(false), it ensures the dependencies declared as suggests are not installed, overriding any decision made earlier in E(PERL_CPANM_OPT).
+ - If parameter is not set, C(cpanm) will use its existing defaults.
+ - When these dependencies fail to install, cpanm continues the installation, since they are just suggestion.
+ type: bool
+ version_added: 10.3.0
version:
description:
- - Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted.
+ - Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted.
type: str
executable:
description:
- - Override the path to the cpanm executable.
+ - Override the path to the cpanm executable.
type: path
mode:
description:
- - Controls the module behavior. See notes below for more details.
- - The default changed from V(compatibility) to V(new) in community.general 9.0.0.
+ - Controls the module behavior. See notes below for more details.
+ - The default changed from V(compatibility) to V(new) in community.general 9.0.0.
type: str
choices: [compatibility, new]
default: new
version_added: 3.0.0
name_check:
description:
- - When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when specified).
+ - When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when
+ specified).
type: str
version_added: 3.0.0
notes:
-- Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host.
-- "This module now comes with a choice of execution O(mode): V(compatibility) or V(new)."
-- >
- O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility.
- This was the default mode before community.general 9.0.0.
- O(name) must be either a module name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version)
- when specified), then nothing happens. Otherwise, it will be installed using the C(cpanm) executable. O(name) cannot be an URL, or a git URL.
- C(cpanm) version specifiers do not work in this mode.
-- >
- O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module name, a distribution file,
- a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized.
- This is the default mode from community.general 9.0.0 onwards.
-
+ - Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host.
+ - 'This module now comes with a choice of execution O(mode): V(compatibility) or V(new).'
+ - 'O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility. This was the default
+ mode before community.general 9.0.0. O(name) must be either a module name or a distribution file. If the perl module given
+ by O(name) is installed (at the exact O(version) when specified), then nothing happens. Otherwise, it will be installed
+ using the C(cpanm) executable. O(name) cannot be an URL, or a git URL. C(cpanm) version specifiers do not work in this
+ mode.'
+ - 'O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module
+ name, a distribution file, a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version
+ specifiers are recognized. This is the default mode from community.general 9.0.0 onwards.'
seealso:
-- name: C(cpanm) command manual page
- description: Manual page for the command.
- link: https://metacpan.org/dist/App-cpanminus/view/bin/cpanm
+ - name: C(cpanm) command manual page
+ description: Manual page for the command.
+ link: https://metacpan.org/dist/App-cpanminus/view/bin/cpanm
author:
-- "Franck Cuny (@fcuny)"
-- "Alexei Znamensky (@russoz)"
+ - "Franck Cuny (@fcuny)"
+ - "Alexei Znamensky (@russoz)"
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Install Dancer perl package
community.general.cpanm:
name: Dancer
@@ -142,8 +154,7 @@ EXAMPLES = """
version: '1.0'
"""
-RETURN = """
----
+RETURN = r"""
cpanm_version:
description: Version of CPANMinus.
type: str
@@ -172,6 +183,8 @@ class CPANMinus(ModuleHelper):
mirror=dict(type='str'),
mirror_only=dict(type='bool', default=False),
installdeps=dict(type='bool', default=False),
+ install_recommendations=dict(type='bool'),
+ install_suggestions=dict(type='bool'),
executable=dict(type='path'),
mode=dict(type='str', default='new', choices=['compatibility', 'new']),
name_check=dict(type='str')
@@ -186,6 +199,8 @@ class CPANMinus(ModuleHelper):
mirror=cmd_runner_fmt.as_opt_val('--mirror'),
mirror_only=cmd_runner_fmt.as_bool("--mirror-only"),
installdeps=cmd_runner_fmt.as_bool("--installdeps"),
+ install_recommendations=cmd_runner_fmt.as_bool("--with-recommends", "--without-recommends", ignore_none=True),
+ install_suggestions=cmd_runner_fmt.as_bool("--with-suggests", "--without-suggests", ignore_none=True),
pkg_spec=cmd_runner_fmt.as_list(),
cpanm_version=cmd_runner_fmt.as_fixed("--version"),
)
@@ -259,7 +274,16 @@ class CPANMinus(ModuleHelper):
return
pkg_spec = self.sanitize_pkg_spec_version(v[pkg_param], v.version)
- with self.runner(['notest', 'locallib', 'mirror', 'mirror_only', 'installdeps', 'pkg_spec'], output_process=process) as ctx:
+ with self.runner([
+ 'notest',
+ 'locallib',
+ 'mirror',
+ 'mirror_only',
+ 'installdeps',
+ 'install_recommendations',
+ 'install_suggestions',
+ 'pkg_spec'
+ ], output_process=process) as ctx:
self.changed = ctx.run(pkg_spec=pkg_spec)
diff --git a/plugins/modules/cronvar.py b/plugins/modules/cronvar.py
index 66fa175498..4f00aef07c 100644
--- a/plugins/modules/cronvar.py
+++ b/plugins/modules/cronvar.py
@@ -17,8 +17,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: cronvar
short_description: Manage variables in crontabs
description:
@@ -49,14 +48,13 @@ options:
type: str
insertbefore:
description:
- - Used with O(state=present). If specified, the variable will be inserted
- just before the variable specified.
+ - Used with O(state=present). If specified, the variable will be inserted just before the variable specified.
type: str
state:
description:
- Whether to ensure that the variable is present or absent.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
user:
description:
@@ -71,18 +69,17 @@ options:
type: str
backup:
description:
- - If set, create a backup of the crontab before it is modified.
- The location of the backup is returned in the C(backup) variable by this module.
- # TODO: C() above should be RV(), but return values have not been documented!
+ - If set, create a backup of the crontab before it is modified. The location of the backup is returned in the C(backup)
+ variable by this module.
type: bool
default: false
requirements:
- cron
author:
-- Doug Luce (@dougluce)
-'''
+ - Doug Luce (@dougluce)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure entry like "EMAIL=doug@ansibmod.con.com" exists
community.general.cronvar:
name: EMAIL
@@ -99,7 +96,7 @@ EXAMPLES = r'''
value: /var/log/yum-autoupdate.log
user: root
cron_file: ansible_yum-autoupdate
-'''
+"""
import os
import platform
@@ -149,9 +146,8 @@ class CronVar(object):
if self.cron_file:
# read the cronfile
try:
- f = open(self.cron_file, 'r')
- self.lines = f.read().splitlines()
- f.close()
+ with open(self.cron_file, 'r') as f:
+ self.lines = f.read().splitlines()
except IOError:
# cron file does not exist
return
diff --git a/plugins/modules/crypttab.py b/plugins/modules/crypttab.py
index 931a0c930b..f728e39ade 100644
--- a/plugins/modules/crypttab.py
+++ b/plugins/modules/crypttab.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: crypttab
short_description: Encrypted Linux block devices
description:
@@ -24,31 +23,27 @@ attributes:
options:
name:
description:
- - Name of the encrypted block device as it appears in the C(/etc/crypttab) file, or
- optionally prefixed with V(/dev/mapper/), as it appears in the filesystem. V(/dev/mapper/)
- will be stripped from O(name).
+ - Name of the encrypted block device as it appears in the C(/etc/crypttab) file, or optionally prefixed with V(/dev/mapper/),
+ as it appears in the filesystem. V(/dev/mapper/) will be stripped from O(name).
type: str
required: true
state:
description:
- - Use V(present) to add a line to C(/etc/crypttab) or update its definition
- if already present.
+ - Use V(present) to add a line to C(/etc/crypttab) or update its definition if already present.
- Use V(absent) to remove a line with matching O(name).
- - Use V(opts_present) to add options to those already present; options with
- different values will be updated.
+ - Use V(opts_present) to add options to those already present; options with different values will be updated.
- Use V(opts_absent) to remove options from the existing set.
type: str
required: true
- choices: [ absent, opts_absent, opts_present, present ]
+ choices: [absent, opts_absent, opts_present, present]
backing_device:
description:
- - Path to the underlying block device or file, or the UUID of a block-device
- prefixed with V(UUID=).
+ - Path to the underlying block device or file, or the UUID of a block-device prefixed with V(UUID=).
type: str
password:
description:
- - Encryption password, the path to a file containing the password, or
- V(-) or unset if the password should be entered at boot.
+ - Encryption password, the path to a file containing the password, or V(-) or unset if the password should be entered
+ at boot.
type: path
opts:
description:
@@ -61,10 +56,10 @@ options:
type: path
default: /etc/crypttab
author:
-- Steve (@groks)
-'''
+ - Steve (@groks)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Set the options explicitly a device which must already exist
community.general.crypttab:
name: luks-home
@@ -78,7 +73,7 @@ EXAMPLES = r'''
opts: discard
loop: '{{ ansible_mounts }}'
when: "'/dev/mapper/luks-' in {{ item.device }}"
-'''
+"""
import os
import traceback
@@ -159,11 +154,8 @@ def main():
changed, reason = existing_line.opts.remove(opts)
if changed and not module.check_mode:
- try:
- f = open(path, 'wb')
+ with open(path, 'wb') as f:
f.write(to_bytes(crypttab, errors='surrogate_or_strict'))
- finally:
- f.close()
module.exit_json(changed=changed, msg=reason, **module.params)
@@ -178,12 +170,9 @@ class Crypttab(object):
os.makedirs(os.path.dirname(path))
open(path, 'a').close()
- try:
- f = open(path, 'r')
+ with open(path, 'r') as f:
for line in f.readlines():
self._lines.append(Line(line))
- finally:
- f.close()
def add(self, line):
self._lines.append(line)
diff --git a/plugins/modules/datadog_downtime.py b/plugins/modules/datadog_downtime.py
index a3a6a660f0..f693ba3c2d 100644
--- a/plugins/modules/datadog_downtime.py
+++ b/plugins/modules/datadog_downtime.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: datadog_downtime
short_description: Manages Datadog downtimes
version_added: 2.0.0
@@ -25,105 +24,105 @@ requirements:
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- api_key:
- description:
- - Your Datadog API key.
- required: true
- type: str
- api_host:
- description:
- - The URL to the Datadog API.
- - This value can also be set with the E(DATADOG_HOST) environment variable.
- required: false
- default: https://api.datadoghq.com
- type: str
- app_key:
- description:
- - Your Datadog app key.
- required: true
- type: str
- state:
- description:
- - The designated state of the downtime.
- required: false
- choices: ["present", "absent"]
- default: present
- type: str
- id:
- description:
- - The identifier of the downtime.
- - If empty, a new downtime gets created, otherwise it is either updated or deleted depending of the O(state).
- - To keep your playbook idempotent, you should save the identifier in a file and read it in a lookup.
- type: int
+ api_key:
+ description:
+ - Your Datadog API key.
+ required: true
+ type: str
+ api_host:
+ description:
+ - The URL to the Datadog API.
+ - This value can also be set with the E(DATADOG_HOST) environment variable.
+ required: false
+ default: https://api.datadoghq.com
+ type: str
+ app_key:
+ description:
+ - Your Datadog app key.
+ required: true
+ type: str
+ state:
+ description:
+ - The designated state of the downtime.
+ required: false
+ choices: ["present", "absent"]
+ default: present
+ type: str
+ id:
+ description:
+ - The identifier of the downtime.
+ - If empty, a new downtime gets created, otherwise it is either updated or deleted depending of the O(state).
+ - To keep your playbook idempotent, you should save the identifier in a file and read it in a lookup.
+ type: int
+ monitor_tags:
+ description:
+ - A list of monitor tags to which the downtime applies.
+ - The resulting downtime applies to monitors that match ALL provided monitor tags.
+ type: list
+ elements: str
+ scope:
+ description:
+ - A list of scopes to which the downtime applies.
+ - The resulting downtime applies to sources that matches ALL provided scopes.
+ type: list
+ elements: str
+ monitor_id:
+ description:
+ - The ID of the monitor to mute. If not provided, the downtime applies to all monitors.
+ type: int
+ downtime_message:
+ description:
+ - A message to include with notifications for this downtime.
+ - Email notifications can be sent to specific users by using the same "@username" notation as events.
+ type: str
+ start:
+ type: int
+ description:
+ - POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.
+ end:
+ type: int
+ description:
+ - POSIX timestamp to end the downtime. If not provided, the downtime is in effect until you cancel it.
+ timezone:
+ description:
+ - The timezone for the downtime.
+ type: str
+ rrule:
+ description:
+ - The C(RRULE) standard for defining recurring events.
+ - For example, to have a recurring event on the first day of each month, select a type of rrule and set the C(FREQ)
+ to C(MONTHLY) and C(BYMONTHDAY) to C(1).
+ - Most common rrule options from the iCalendar Spec are supported.
+ - Attributes specifying the duration in C(RRULE) are not supported (for example C(DTSTART), C(DTEND), C(DURATION)).
+ type: str
+"""
+
+EXAMPLES = r"""
+- name: Create a downtime
+ register: downtime_var
+ community.general.datadog_downtime:
+ state: present
monitor_tags:
- description:
- - A list of monitor tags to which the downtime applies.
- - The resulting downtime applies to monitors that match ALL provided monitor tags.
- type: list
- elements: str
- scope:
- description:
- - A list of scopes to which the downtime applies.
- - The resulting downtime applies to sources that matches ALL provided scopes.
- type: list
- elements: str
- monitor_id:
- description:
- - The ID of the monitor to mute. If not provided, the downtime applies to all monitors.
- type: int
- downtime_message:
- description:
- - A message to include with notifications for this downtime.
- - Email notifications can be sent to specific users by using the same "@username" notation as events.
- type: str
- start:
- type: int
- description:
- - POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.
- end:
- type: int
- description:
- - POSIX timestamp to end the downtime. If not provided, the downtime is in effect until you cancel it.
- timezone:
- description:
- - The timezone for the downtime.
- type: str
- rrule:
- description:
- - The C(RRULE) standard for defining recurring events.
- - For example, to have a recurring event on the first day of each month,
- select a type of rrule and set the C(FREQ) to C(MONTHLY) and C(BYMONTHDAY) to C(1).
- - Most common rrule options from the iCalendar Spec are supported.
- - Attributes specifying the duration in C(RRULE) are not supported (for example C(DTSTART), C(DTEND), C(DURATION)).
- type: str
+ - "foo:bar"
+ downtime_message: "Downtime for foo:bar"
+ scope: "test"
+ api_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+ app_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+ # Lookup the id in the file and ignore errors if the file doesn't exits, so downtime gets created
+ id: "{{ lookup('file', inventory_hostname ~ '_downtime_id.txt', errors='ignore') }}"
+- name: Save downtime id to file for later updates and idempotence
+ delegate_to: localhost
+ copy:
+ content: "{{ downtime.downtime.id }}"
+ dest: "{{ inventory_hostname ~ '_downtime_id.txt' }}"
"""
-EXAMPLES = """
- - name: Create a downtime
- register: downtime_var
- community.general.datadog_downtime:
- state: present
- monitor_tags:
- - "foo:bar"
- downtime_message: "Downtime for foo:bar"
- scope: "test"
- api_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
- app_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
- # Lookup the id in the file and ignore errors if the file doesn't exits, so downtime gets created
- id: "{{ lookup('file', inventory_hostname ~ '_downtime_id.txt', errors='ignore') }}"
- - name: Save downtime id to file for later updates and idempotence
- delegate_to: localhost
- copy:
- content: "{{ downtime.downtime.id }}"
- dest: "{{ inventory_hostname ~ '_downtime_id.txt' }}"
-"""
-
-RETURN = """
+RETURN = r"""
# Returns the downtime JSON dictionary from the API response under the C(downtime) key.
# See https://docs.datadoghq.com/api/v1/downtimes/#schedule-a-downtime for more details.
downtime:
diff --git a/plugins/modules/datadog_event.py b/plugins/modules/datadog_event.py
index 6008b565b3..97be0c9b16 100644
--- a/plugins/modules/datadog_event.py
+++ b/plugins/modules/datadog_event.py
@@ -14,81 +14,88 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: datadog_event
short_description: Posts events to Datadog service
description:
- - "Allows to post events to Datadog (www.datadoghq.com) service."
- - "Uses http://docs.datadoghq.com/api/#events API."
+ - Allows to post events to Datadog (www.datadoghq.com) service.
+ - Uses http://docs.datadoghq.com/api/#events API.
author:
- "Artūras 'arturaz' Šlajus (@arturaz)"
- "Naoya Nakazawa (@n0ts)"
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- api_key:
- type: str
- description: ["Your DataDog API key."]
- required: true
- app_key:
- type: str
- description: ["Your DataDog app key."]
- required: true
- title:
- type: str
- description: ["The event title."]
- required: true
- text:
- type: str
- description: ["The body of the event."]
- required: true
- date_happened:
- type: int
- description:
- - POSIX timestamp of the event.
- - Default value is now.
- priority:
- type: str
- description: ["The priority of the event."]
- default: normal
- choices: [normal, low]
- host:
- type: str
- description:
- - Host name to associate with the event.
- - If not specified, it defaults to the remote system's hostname.
- api_host:
- type: str
- description:
- - DataDog API endpoint URL.
- version_added: '3.3.0'
- tags:
- type: list
- elements: str
- description: ["Comma separated list of tags to apply to the event."]
- alert_type:
- type: str
- description: ["Type of alert."]
- default: info
- choices: ['error', 'warning', 'info', 'success']
- aggregation_key:
- type: str
- description: ["An arbitrary string to use for aggregation."]
- validate_certs:
- description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
- type: bool
- default: true
-'''
+ api_key:
+ type: str
+ description:
+ - Your DataDog API key.
+ required: true
+ app_key:
+ type: str
+ description:
+ - Your DataDog app key.
+ required: true
+ title:
+ type: str
+ description:
+ - The event title.
+ required: true
+ text:
+ type: str
+ description:
+ - The body of the event.
+ required: true
+ date_happened:
+ type: int
+ description:
+ - POSIX timestamp of the event.
+ - Default value is now.
+ priority:
+ type: str
+ description:
+ - The priority of the event.
+ default: normal
+ choices: [normal, low]
+ host:
+ type: str
+ description:
+ - Host name to associate with the event.
+ - If not specified, it defaults to the remote system's hostname.
+ api_host:
+ type: str
+ description:
+ - DataDog API endpoint URL.
+ version_added: '3.3.0'
+ tags:
+ type: list
+ elements: str
+ description:
+ - Comma separated list of tags to apply to the event.
+ alert_type:
+ type: str
+ description:
+ - Type of alert.
+ default: info
+ choices: ['error', 'warning', 'info', 'success']
+ aggregation_key:
+ type: str
+ description:
+ - An arbitrary string to use for aggregation.
+ validate_certs:
+ description:
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
+ type: bool
+ default: true
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Post an event with low priority
community.general.datadog_event:
title: Testing from ansible
@@ -116,8 +123,7 @@ EXAMPLES = '''
- aa
- b
- '#host:{{ inventory_hostname }}'
-
-'''
+"""
import platform
import traceback
diff --git a/plugins/modules/datadog_monitor.py b/plugins/modules/datadog_monitor.py
index 75ae8c2332..eec0db0d32 100644
--- a/plugins/modules/datadog_monitor.py
+++ b/plugins/modules/datadog_monitor.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: datadog_monitor
short_description: Manages Datadog monitors
description:
@@ -21,181 +20,181 @@ requirements: [datadog]
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- api_key:
- description:
- - Your Datadog API key.
- required: true
- type: str
- api_host:
- description:
- - The URL to the Datadog API. Default value is V(https://api.datadoghq.com).
- - This value can also be set with the E(DATADOG_HOST) environment variable.
- required: false
- type: str
- version_added: '0.2.0'
- app_key:
- description:
- - Your Datadog app key.
- required: true
- type: str
- state:
- description:
- - The designated state of the monitor.
- required: true
- choices: ['present', 'absent', 'mute', 'unmute']
- type: str
- tags:
- description:
- - A list of tags to associate with your monitor when creating or updating.
- - This can help you categorize and filter monitors.
- type: list
- elements: str
- type:
- description:
- - The type of the monitor.
- - The types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0.
- - The type V(composite) was added in community.general 3.4.0.
- - The type V(event-v2 alert) was added in community.general 4.8.0.
- choices:
- - metric alert
- - service check
- - event alert
- - event-v2 alert
- - process alert
- - log alert
- - query alert
- - trace-analytics alert
- - rum alert
- - composite
- type: str
- query:
- description:
- - The monitor query to notify on.
- - Syntax varies depending on what type of monitor you are creating.
- type: str
- name:
- description:
- - The name of the alert.
- required: true
- type: str
- notification_message:
- description:
- - A message to include with notifications for this monitor.
- - Email notifications can be sent to specific users by using the same '@username' notation as events.
- - Monitor message template variables can be accessed by using double square brackets, i.e '[[' and ']]'.
- type: str
- silenced:
- type: dict
- description:
- - Dictionary of scopes to silence, with timestamps or None.
- - Each scope will be muted until the given POSIX timestamp or forever if the value is None.
- notify_no_data:
- description:
- - Whether this monitor will notify when data stops reporting.
- type: bool
- default: false
- no_data_timeframe:
- description:
- - The number of minutes before a monitor will notify when data stops reporting.
- - Must be at least 2x the monitor timeframe for metric alerts or 2 minutes for service checks.
- - If not specified, it defaults to 2x timeframe for metric, 2 minutes for service.
- type: str
- timeout_h:
- description:
- - The number of hours of the monitor not reporting data before it will automatically resolve from a triggered state.
- type: str
- renotify_interval:
- description:
- - The number of minutes after the last notification before a monitor will re-notify on the current status.
- - It will only re-notify if it is not resolved.
- type: str
- escalation_message:
- description:
- - A message to include with a re-notification. Supports the '@username' notification we allow elsewhere.
- - Not applicable if O(renotify_interval=none).
- type: str
- notify_audit:
- description:
- - Whether tagged users will be notified on changes to this monitor.
- type: bool
- default: false
- thresholds:
- type: dict
- description:
- - A dictionary of thresholds by status.
- - Only available for service checks and metric alerts.
- - Because each of them can have multiple thresholds, we do not define them directly in the query.
- - "If not specified, it defaults to: V({'ok': 1, 'critical': 1, 'warning': 1})."
- locked:
- description:
- - Whether changes to this monitor should be restricted to the creator or admins.
- type: bool
- default: false
- require_full_window:
- description:
- - Whether this monitor needs a full window of data before it gets evaluated.
- - We highly recommend you set this to False for sparse metrics, otherwise some evaluations will be skipped.
- type: bool
- new_host_delay:
- description:
- - A positive integer representing the number of seconds to wait before evaluating the monitor for new hosts.
- - This gives the host time to fully initialize.
- type: str
- evaluation_delay:
- description:
- - Time to delay evaluation (in seconds).
- - Effective for sparse values.
- type: str
- id:
- description:
- - The ID of the alert.
- - If set, will be used instead of the name to locate the alert.
- type: str
- include_tags:
- description:
- - Whether notifications from this monitor automatically inserts its triggering tags into the title.
- type: bool
- default: true
- version_added: 1.3.0
- priority:
- description:
- - Integer from 1 (high) to 5 (low) indicating alert severity.
- type: int
- version_added: 4.6.0
- notification_preset_name:
- description:
- - Toggles the display of additional content sent in the monitor notification.
- choices:
- - show_all
- - hide_query
- - hide_handles
- - hide_all
- type: str
- version_added: 7.1.0
- renotify_occurrences:
- description:
- - The number of times re-notification messages should be sent on the current status at the provided re-notification interval.
- type: int
- version_added: 7.1.0
- renotify_statuses:
- description:
- - The types of monitor statuses for which re-notification messages are sent.
- choices:
- - alert
- - warn
- - no data
- type: list
- elements: str
- version_added: 7.1.0
+ api_key:
+ description:
+ - Your Datadog API key.
+ required: true
+ type: str
+ api_host:
+ description:
+ - The URL to the Datadog API. Default value is V(https://api.datadoghq.com).
+ - This value can also be set with the E(DATADOG_HOST) environment variable.
+ required: false
+ type: str
+ version_added: '0.2.0'
+ app_key:
+ description:
+ - Your Datadog app key.
+ required: true
+ type: str
+ state:
+ description:
+ - The designated state of the monitor.
+ required: true
+ choices: ['present', 'absent', 'mute', 'unmute']
+ type: str
+ tags:
+ description:
+ - A list of tags to associate with your monitor when creating or updating.
+ - This can help you categorize and filter monitors.
+ type: list
+ elements: str
+ type:
+ description:
+ - The type of the monitor.
+ - The types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0.
+ - The type V(composite) was added in community.general 3.4.0.
+ - The type V(event-v2 alert) was added in community.general 4.8.0.
+ choices:
+ - metric alert
+ - service check
+ - event alert
+ - event-v2 alert
+ - process alert
+ - log alert
+ - query alert
+ - trace-analytics alert
+ - rum alert
+ - composite
+ type: str
+ query:
+ description:
+ - The monitor query to notify on.
+ - Syntax varies depending on what type of monitor you are creating.
+ type: str
+ name:
+ description:
+ - The name of the alert.
+ required: true
+ type: str
+ notification_message:
+ description:
+ - A message to include with notifications for this monitor.
+ - Email notifications can be sent to specific users by using the same '@username' notation as events.
+ - Monitor message template variables can be accessed by using double square brackets, in other words C([[) and C(]]).
+ type: str
+ silenced:
+ type: dict
+ description:
+ - Dictionary of scopes to silence, with timestamps or None.
+ - Each scope will be muted until the given POSIX timestamp or forever if the value is None.
+ notify_no_data:
+ description:
+ - Whether this monitor will notify when data stops reporting.
+ type: bool
+ default: false
+ no_data_timeframe:
+ description:
+ - The number of minutes before a monitor will notify when data stops reporting.
+ - Must be at least 2x the monitor timeframe for metric alerts or 2 minutes for service checks.
+ - If not specified, it defaults to 2x timeframe for metric, 2 minutes for service.
+ type: str
+ timeout_h:
+ description:
+ - The number of hours of the monitor not reporting data before it will automatically resolve from a triggered state.
+ type: str
+ renotify_interval:
+ description:
+ - The number of minutes after the last notification before a monitor will re-notify on the current status.
+ - It will only re-notify if it is not resolved.
+ type: str
+ escalation_message:
+ description:
+ - A message to include with a re-notification. Supports the '@username' notification we allow elsewhere.
+ - Not applicable if O(renotify_interval=none).
+ type: str
+ notify_audit:
+ description:
+ - Whether tagged users will be notified on changes to this monitor.
+ type: bool
+ default: false
+ thresholds:
+ type: dict
+ description:
+ - A dictionary of thresholds by status.
+ - Only available for service checks and metric alerts.
+ - Because each of them can have multiple thresholds, we do not define them directly in the query.
+ - "If not specified, it defaults to: V({'ok': 1, 'critical': 1, 'warning': 1})."
+ locked:
+ description:
+ - Whether changes to this monitor should be restricted to the creator or admins.
+ type: bool
+ default: false
+ require_full_window:
+ description:
+ - Whether this monitor needs a full window of data before it gets evaluated.
+ - We highly recommend you set this to False for sparse metrics, otherwise some evaluations will be skipped.
+ type: bool
+ new_host_delay:
+ description:
+ - A positive integer representing the number of seconds to wait before evaluating the monitor for new hosts.
+ - This gives the host time to fully initialize.
+ type: str
+ evaluation_delay:
+ description:
+ - Time to delay evaluation (in seconds).
+ - Effective for sparse values.
+ type: str
+ id:
+ description:
+ - The ID of the alert.
+ - If set, will be used instead of the name to locate the alert.
+ type: str
+ include_tags:
+ description:
+ - Whether notifications from this monitor automatically inserts its triggering tags into the title.
+ type: bool
+ default: true
+ version_added: 1.3.0
+ priority:
+ description:
+ - Integer from V(1) (high) to V(5) (low) indicating alert severity.
+ type: int
+ version_added: 4.6.0
+ notification_preset_name:
+ description:
+ - Toggles the display of additional content sent in the monitor notification.
+ choices:
+ - show_all
+ - hide_query
+ - hide_handles
+ - hide_all
+ type: str
+ version_added: 7.1.0
+ renotify_occurrences:
+ description:
+ - The number of times re-notification messages should be sent on the current status at the provided re-notification
+ interval.
+ type: int
+ version_added: 7.1.0
+ renotify_statuses:
+ description:
+ - The types of monitor statuses for which re-notification messages are sent.
+ choices:
+ - alert
+ - warn
+ - no data
+ type: list
+ elements: str
+ version_added: 7.1.0
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a metric monitor
community.general.datadog_monitor:
type: "metric alert"
@@ -239,7 +238,8 @@ EXAMPLES = '''
api_host: https://api.datadoghq.eu
api_key: "9775a026f1ca7d1c6c5af9d94d9595a4"
app_key: "87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"
-'''
+"""
+
import traceback
# Import Datadog
diff --git a/plugins/modules/dconf.py b/plugins/modules/dconf.py
index 065cf1a6a7..319d6770f2 100644
--- a/plugins/modules/dconf.py
+++ b/plugins/modules/dconf.py
@@ -9,53 +9,39 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: dconf
author:
- - "Branko Majic (@azaghal)"
+ - "Branko Majic (@azaghal)"
short_description: Modify and read dconf database
description:
- - This module allows modifications and reading of C(dconf) database. The module
- is implemented as a wrapper around C(dconf) tool. Please see the dconf(1) man
- page for more details.
- - Since C(dconf) requires a running D-Bus session to change values, the module
- will try to detect an existing session and reuse it, or run the tool via
- C(dbus-run-session).
+ - This module allows modifications and reading of C(dconf) database. The module is implemented as a wrapper around C(dconf)
+ tool. Please see the dconf(1) man page for more details.
+ - Since C(dconf) requires a running D-Bus session to change values, the module will try to detect an existing session and
+ reuse it, or run the tool using C(dbus-run-session).
requirements:
- - Optionally the C(gi.repository) Python library (usually included in the OS
- on hosts which have C(dconf)); this will become a non-optional requirement
- in a future major release of community.general.
+ - Optionally the C(gi.repository) Python library (usually included in the OS on hosts which have C(dconf)); this will become
+ a non-optional requirement in a future major release of community.general.
notes:
- - This module depends on C(psutil) Python library (version 4.0.0 and upwards),
- C(dconf), C(dbus-send), and C(dbus-run-session) binaries. Depending on
- distribution you are using, you may need to install additional packages to
- have these available.
- - This module uses the C(gi.repository) Python library when available for
- accurate comparison of values in C(dconf) to values specified in Ansible
- code. C(gi.repository) is likely to be present on most systems which have
- C(dconf) but may not be present everywhere. When it is missing, a simple
- string comparison between values is used, and there may be false positives,
- that is, Ansible may think that a value is being changed when it is not.
- This fallback will be removed in a future version of this module, at which
- point the module will stop working on hosts without C(gi.repository).
- - Detection of existing, running D-Bus session, required to change settings
- via C(dconf), is not 100% reliable due to implementation details of D-Bus
- daemon itself. This might lead to running applications not picking-up
- changes on the fly if options are changed via Ansible and
- C(dbus-run-session).
- - Keep in mind that the C(dconf) CLI tool, which this module wraps around,
- utilises an unusual syntax for the values (GVariant). For example, if you
- wanted to provide a string value, the correct syntax would be
- O(value="'myvalue'") - with single quotes as part of the Ansible parameter
- value.
- - When using loops in combination with a value like
- V("[('xkb', 'us'\), ('xkb', 'se'\)]"), you need to be aware of possible
- type conversions. Applying a filter V({{ item.value | string }})
- to the parameter variable can avoid potential conversion problems.
- - The easiest way to figure out exact syntax/value you need to provide for a
- key is by making the configuration change in application affected by the
- key, and then having a look at value set via commands C(dconf dump
- /path/to/dir/) or C(dconf read /path/to/key).
+ - This module depends on C(psutil) Python library (version 4.0.0 and upwards), C(dconf), C(dbus-send), and C(dbus-run-session)
+ binaries. Depending on distribution you are using, you may need to install additional packages to have these available.
+ - This module uses the C(gi.repository) Python library when available for accurate comparison of values in C(dconf) to values
+ specified in Ansible code. C(gi.repository) is likely to be present on most systems which have C(dconf) but may not be
+ present everywhere. When it is missing, a simple string comparison between values is used, and there may be false positives,
+ that is, Ansible may think that a value is being changed when it is not. This fallback will be removed in a future version
+ of this module, at which point the module will stop working on hosts without C(gi.repository).
+ - Detection of existing, running D-Bus session, required to change settings using C(dconf), is not 100% reliable due to
+ implementation details of D-Bus daemon itself. This might lead to running applications not picking-up changes on-the-fly
+ if options are changed using Ansible and C(dbus-run-session).
+ - Keep in mind that the C(dconf) CLI tool, which this module wraps around, utilises an unusual syntax for the values (GVariant).
+ For example, if you wanted to provide a string value, the correct syntax would be O(value="'myvalue'") - with single quotes
+ as part of the Ansible parameter value.
+ - When using loops in combination with a value like V("[('xkb', 'us'\), ('xkb', 'se'\)]"), you need to be aware of possible
+ type conversions. Applying a filter V({{ item.value | string }}) to the parameter variable can avoid potential conversion
+ problems.
+ - The easiest way to figure out exact syntax/value you need to provide for a key is by making the configuration change in
+ application affected by the key, and then having a look at value set using commands C(dconf dump /path/to/dir/) or C(dconf
+ read /path/to/key).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -73,30 +59,27 @@ options:
type: raw
required: false
description:
- - Value to set for the specified dconf key. Value should be specified in
- GVariant format. Due to complexity of this format, it is best to have a
- look at existing values in the dconf database.
+ - Value to set for the specified dconf key. Value should be specified in GVariant format. Due to complexity of this
+ format, it is best to have a look at existing values in the dconf database.
- Required for O(state=present).
- - Although the type is specified as "raw", it should typically be
- specified as a string. However, boolean values in particular are
- handled properly even when specified as booleans rather than strings
- (in fact, handling booleans properly is why the type of this parameter
- is "raw").
+ - Although the type is specified as "raw", it should typically be specified as a string. However, boolean values in
+ particular are handled properly even when specified as booleans rather than strings (in fact, handling booleans properly
+ is why the type of this parameter is "raw").
state:
type: str
required: false
default: present
- choices: [ 'read', 'present', 'absent' ]
+ choices: ['read', 'present', 'absent']
description:
- The action to take upon the key/value.
-'''
+"""
RETURN = r"""
value:
- description: value associated with the requested key
- returned: success, state was "read"
- type: str
- sample: "'Default'"
+ description: Value associated with the requested key.
+ returned: success, state was "read"
+ type: str
+ sample: "'Default'"
"""
EXAMPLES = r"""
diff --git a/plugins/modules/decompress.py b/plugins/modules/decompress.py
new file mode 100644
index 0000000000..aa7a14aefb
--- /dev/null
+++ b/plugins/modules/decompress.py
@@ -0,0 +1,213 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024, Stanislav Shamilov
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import (absolute_import, division, print_function)
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+module: decompress
+short_description: Decompresses compressed files
+version_added: 10.1.0
+description:
+ - Decompresses compressed files.
+ - The source (compressed) file and destination (decompressed) files are on the remote host.
+ - Source file can be deleted after decompression.
+extends_documentation_fragment:
+ - ansible.builtin.files
+ - community.general.attributes
+attributes:
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
+options:
+ src:
+ description:
+ - Remote absolute path for the file to decompress.
+ type: path
+ required: true
+ dest:
+ description:
+ - The file name of the destination file where the compressed file will be decompressed.
+ - If the destination file exists, it will be truncated and overwritten.
+ - If not specified, the destination filename will be derived from O(src) by removing the compression format extension.
+ For example, if O(src) is V(/path/to/file.txt.gz) and O(format) is V(gz), O(dest) will be V(/path/to/file.txt). If
+ the O(src) file does not have an extension for the current O(format), the O(dest) filename will be made by appending
+ C(_decompressed) to the O(src) filename. For instance, if O(src) is V(/path/to/file.myextension), the (dest) filename
+ will be V(/path/to/file.myextension_decompressed).
+ type: path
+ format:
+ description:
+ - The type of compression to use to decompress.
+ type: str
+ choices: [gz, bz2, xz]
+ default: gz
+ remove:
+ description:
+ - Remove original compressed file after decompression.
+ type: bool
+ default: false
+requirements:
+ - Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python
+ 2) if using C(xz) format.
+author:
+ - Stanislav Shamilov (@shamilovstas)
+"""
+
+EXAMPLES = r"""
+- name: Decompress file /path/to/file.txt.gz into /path/to/file.txt (gz compression is used by default)
+ community.general.decompress:
+ src: /path/to/file.txt.gz
+ dest: /path/to/file.txt
+
+- name: Decompress file /path/to/file.txt.gz into /path/to/file.txt
+ community.general.decompress:
+ src: /path/to/file.txt.gz
+
+- name: Decompress file compressed with bzip2
+ community.general.decompress:
+ src: /path/to/file.txt.bz2
+ dest: /path/to/file.bz2
+ format: bz2
+
+- name: Decompress file and delete the compressed file afterwards
+ community.general.decompress:
+ src: /path/to/file.txt.gz
+ dest: /path/to/file.txt
+ remove: true
+"""
+
+RETURN = r"""
+dest:
+ description: Path to decompressed file.
+ type: str
+ returned: success
+ sample: /path/to/file.txt
+"""
+
+import bz2
+import filecmp
+import gzip
+import os
+import shutil
+import tempfile
+
+from ansible.module_utils import six
+from ansible_collections.community.general.plugins.module_utils.mh.module_helper import ModuleHelper
+from ansible.module_utils.common.text.converters import to_native, to_bytes
+from ansible_collections.community.general.plugins.module_utils import deps
+
+with deps.declare("lzma"):
+ if six.PY3:
+ import lzma
+ else:
+ from backports import lzma
+
+
+def lzma_decompress(src):
+ return lzma.open(src, "rb")
+
+
+def bz2_decompress(src):
+ if six.PY3:
+ return bz2.open(src, "rb")
+ else:
+ return bz2.BZ2File(src, "rb")
+
+
+def gzip_decompress(src):
+ return gzip.open(src, "rb")
+
+
+def decompress(b_src, b_dest, handler):
+ with handler(b_src) as src_file:
+ with open(b_dest, "wb") as dest_file:
+ shutil.copyfileobj(src_file, dest_file)
+
+
+class Decompress(ModuleHelper):
+ destination_filename_template = "%s_decompressed"
+ use_old_vardict = False
+ output_params = 'dest'
+
+ module = dict(
+ argument_spec=dict(
+ src=dict(type='path', required=True),
+ dest=dict(type='path'),
+ format=dict(type='str', default='gz', choices=['gz', 'bz2', 'xz']),
+ remove=dict(type='bool', default=False)
+ ),
+ add_file_common_args=True,
+ supports_check_mode=True
+ )
+
+ def __init_module__(self):
+ self.handlers = {"gz": gzip_decompress, "bz2": bz2_decompress, "xz": lzma_decompress}
+ if self.vars.dest is None:
+ self.vars.dest = self.get_destination_filename()
+ deps.validate(self.module)
+ self.configure()
+
+ def configure(self):
+ b_dest = to_bytes(self.vars.dest, errors='surrogate_or_strict')
+ b_src = to_bytes(self.vars.src, errors='surrogate_or_strict')
+ if not os.path.exists(b_src):
+ if self.vars.remove and os.path.exists(b_dest):
+ self.module.exit_json(changed=False)
+ else:
+ self.do_raise(msg="Path does not exist: '%s'" % b_src)
+ if os.path.isdir(b_src):
+ self.do_raise(msg="Cannot decompress directory '%s'" % b_src)
+ if os.path.isdir(b_dest):
+ self.do_raise(msg="Destination is a directory, cannot decompress: '%s'" % b_dest)
+
+ def __run__(self):
+ b_dest = to_bytes(self.vars.dest, errors='surrogate_or_strict')
+ b_src = to_bytes(self.vars.src, errors='surrogate_or_strict')
+
+ file_args = self.module.load_file_common_arguments(self.module.params, path=self.vars.dest)
+ handler = self.handlers[self.vars.format]
+ try:
+ tempfd, temppath = tempfile.mkstemp(dir=self.module.tmpdir)
+ self.module.add_cleanup_file(temppath)
+ b_temppath = to_bytes(temppath, errors='surrogate_or_strict')
+ decompress(b_src, b_temppath, handler)
+ except OSError as e:
+ self.do_raise(msg="Unable to create temporary file '%s'" % to_native(e))
+
+ if os.path.exists(b_dest):
+ self.changed = not filecmp.cmp(b_temppath, b_dest, shallow=False)
+ else:
+ self.changed = True
+
+ if self.changed and not self.module.check_mode:
+ try:
+ self.module.atomic_move(b_temppath, b_dest)
+ except OSError:
+ self.do_raise(msg="Unable to move temporary file '%s' to '%s'" % (b_temppath, self.vars.dest))
+
+ if self.vars.remove and not self.check_mode:
+ os.remove(b_src)
+ self.changed = self.module.set_fs_attributes_if_different(file_args, self.changed)
+
+ def get_destination_filename(self):
+ src = self.vars.src
+ fmt_extension = ".%s" % self.vars.format
+ if src.endswith(fmt_extension) and len(src) > len(fmt_extension):
+ filename = src[:-len(fmt_extension)]
+ else:
+ filename = Decompress.destination_filename_template % src
+ return filename
+
+
+def main():
+ Decompress.execute()
+
+
+if __name__ == '__main__':
+ main()
diff --git a/plugins/modules/deploy_helper.py b/plugins/modules/deploy_helper.py
index b47ed82540..14a7d4f8c7 100644
--- a/plugins/modules/deploy_helper.py
+++ b/plugins/modules/deploy_helper.py
@@ -11,27 +11,19 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: deploy_helper
author: "Ramon de la Fuente (@ramondelafuente)"
short_description: Manages some of the steps common in deploying projects
description:
- - The Deploy Helper manages some of the steps common in deploying software.
- It creates a folder structure, manages a symlink for the current release
- and cleans up old releases.
- # TODO: convert below to RETURN documentation!
- - "Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact.
- C(project_path), whatever you set in the O(path) parameter,
- C(current_path), the path to the symlink that points to the active release,
- C(releases_path), the path to the folder to keep releases in,
- C(shared_path), the path to the folder to keep shared resources in,
- C(unfinished_filename), the file to check for to recognize unfinished builds,
- C(previous_release), the release the 'current' symlink is pointing to,
- C(previous_release_path), the full path to the 'current' symlink target,
- C(new_release), either the 'release' parameter or a generated timestamp,
- C(new_release_path), the path to the new release folder (not created by the module)."
-
+ - The Deploy Helper manages some of the steps common in deploying software. It creates a folder structure, manages a symlink
+ for the current release and cleans up old releases.
+ - Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact. C(project_path), whatever
+ you set in the O(path) parameter, C(current_path), the path to the symlink that points to the active release, C(releases_path),
+ the path to the folder to keep releases in, C(shared_path), the path to the folder to keep shared resources in, C(unfinished_filename),
+ the file to check for to recognize unfinished builds, C(previous_release), the release the 'current' symlink is pointing
+ to, C(previous_release_path), the full path to the 'current' symlink target, C(new_release), either the O(release) parameter
+ or a generated timestamp, C(new_release_path), the path to the new release folder (not created by the module).
attributes:
check_mode:
support: full
@@ -44,42 +36,38 @@ options:
required: true
aliases: ['dest']
description:
- - The root path of the project.
- Returned in the C(deploy_helper.project_path) fact.
-
+ - The root path of the project. Returned in the C(deploy_helper.project_path) fact.
state:
type: str
description:
- The state of the project.
- V(query) will only gather facts.
- V(present) will create the project C(root) folder, and in it the C(releases) and C(shared) folders.
- - V(finalize) will remove the unfinished_filename file, create a symlink to the newly
- deployed release and optionally clean old releases.
+ - V(finalize) will remove the unfinished_filename file, create a symlink to the newly deployed release and optionally
+ clean old releases.
- V(clean) will remove failed & old releases.
- V(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with O(state=absent)).
- choices: [ present, finalize, absent, clean, query ]
+ choices: [present, finalize, absent, clean, query]
default: present
release:
type: str
description:
- The release version that is being deployed. Defaults to a timestamp format C(%Y%m%d%H%M%S) (for example V(20141119223359)).
- This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize).
- You can use the generated fact C(release={{ deploy_helper.new_release }}).
-
+ This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize). You can
+ use the generated fact C(release={{ deploy_helper.new_release }}).
releases_path:
type: str
description:
- - The name of the folder that will hold the releases. This can be relative to O(path) or absolute.
- Returned in the C(deploy_helper.releases_path) fact.
+ - The name of the folder that will hold the releases. This can be relative to O(path) or absolute. Returned in the C(deploy_helper.releases_path)
+ fact.
default: releases
shared_path:
type: path
description:
- - The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute.
- If this is set to an empty string, no shared folder will be created.
- Returned in the C(deploy_helper.shared_path) fact.
+ - The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute. If this is
+ set to an empty string, no shared folder will be created. Returned in the C(deploy_helper.shared_path) fact.
default: shared
current_path:
@@ -92,9 +80,9 @@ options:
unfinished_filename:
type: str
description:
- - The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that
- contain this file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is
- automatically deleted from the C(new_release_path) during O(state=finalize).
+ - The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that contain this
+ file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is automatically deleted
+ from the C(new_release_path) during O(state=finalize).
default: DEPLOY_UNFINISHED
clean:
@@ -111,20 +99,18 @@ options:
default: 5
notes:
- - Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden
- parameters to both calls, otherwise the second call will overwrite the facts of the first one.
- - When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a
- new naming strategy without problems.
- - Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent
- unless you pass your own release name with O(release). Due to the nature of deploying software, this should not
- be much of a problem.
+ - Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden parameters
+ to both calls, otherwise the second call will overwrite the facts of the first one.
+ - When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a new naming
+ strategy without problems.
+ - Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent unless you
+ pass your own release name with O(release). Due to the nature of deploying software, this should not be much of a problem.
extends_documentation_fragment:
- ansible.builtin.files
- community.general.attributes
-'''
-
-EXAMPLES = '''
+"""
+EXAMPLES = r"""
# General explanation, starting with an example folder structure for a project:
# root:
@@ -192,10 +178,10 @@ EXAMPLES = '''
src: '{{ deploy_helper.shared_path }}/{{ item.src }}'
state: link
with_items:
- - path: app/sessions
- src: sessions
- - path: web/uploads
- src: uploads
+ - path: app/sessions
+ src: sessions
+ - path: web/uploads
+ src: uploads
- name: Finalize the deploy, removing the unfinished file and switching the symlink
community.general.deploy_helper:
path: /path/to/root
@@ -277,7 +263,8 @@ EXAMPLES = '''
path: /path/to/root
- ansible.builtin.debug:
var: deploy_helper
-'''
+"""
+
import os
import shutil
import time
diff --git a/plugins/modules/dimensiondata_network.py b/plugins/modules/dimensiondata_network.py
index cfb7d61cd9..6617d6aef1 100644
--- a/plugins/modules/dimensiondata_network.py
+++ b/plugins/modules/dimensiondata_network.py
@@ -14,8 +14,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: dimensiondata_network
short_description: Create, update, and delete MCP 1.0 & 2.0 networks
extends_documentation_fragment:
@@ -24,7 +23,7 @@ extends_documentation_fragment:
- community.general.attributes
description:
- - Create, update, and delete MCP 1.0 & 2.0 networks
+ - Create, update, and delete MCP 1.0 & 2.0 networks.
author: 'Aimon Bustardo (@aimonb)'
attributes:
check_mode:
@@ -55,9 +54,9 @@ options:
choices: [present, absent]
default: present
type: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create an MCP 1.0 network
community.general.dimensiondata_network:
region: na
@@ -79,43 +78,43 @@ EXAMPLES = '''
location: NA1
name: mynet
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
network:
- description: Dictionary describing the network.
- returned: On success when O(state=present).
- type: complex
- contains:
- id:
- description: Network ID.
- type: str
- sample: "8c787000-a000-4050-a215-280893411a7d"
- name:
- description: Network name.
- type: str
- sample: "My network"
- description:
- description: Network description.
- type: str
- sample: "My network description"
- location:
- description: Datacenter location.
- type: str
- sample: NA3
- status:
- description: Network status. (MCP 2.0 only)
- type: str
- sample: NORMAL
- private_net:
- description: Private network subnet. (MCP 1.0 only)
- type: str
- sample: "10.2.3.0"
- multicast:
- description: Multicast enabled? (MCP 1.0 only)
- type: bool
- sample: false
-'''
+ description: Dictionary describing the network.
+ returned: On success when O(state=present).
+ type: complex
+ contains:
+ id:
+ description: Network ID.
+ type: str
+ sample: "8c787000-a000-4050-a215-280893411a7d"
+ name:
+ description: Network name.
+ type: str
+ sample: "My network"
+ description:
+ description: Network description.
+ type: str
+ sample: "My network description"
+ location:
+ description: Datacenter location.
+ type: str
+ sample: NA3
+ status:
+ description: Network status. (MCP 2.0 only).
+ type: str
+ sample: NORMAL
+ private_net:
+ description: Private network subnet. (MCP 1.0 only).
+ type: str
+ sample: "10.2.3.0"
+ multicast:
+ description: Multicast enabled? (MCP 1.0 only).
+ type: bool
+ sample: false
+"""
import traceback
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/dimensiondata_vlan.py b/plugins/modules/dimensiondata_vlan.py
index 9d129f3dea..2389d34333 100644
--- a/plugins/modules/dimensiondata_vlan.py
+++ b/plugins/modules/dimensiondata_vlan.py
@@ -10,8 +10,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: dimensiondata_vlan
short_description: Manage a VLAN in a Cloud Control network domain
extends_documentation_fragment:
@@ -40,37 +39,39 @@ options:
default: ''
network_domain:
description:
- - The Id or name of the target network domain.
+ - The ID or name of the target network domain.
required: true
type: str
private_ipv4_base_address:
description:
- - The base address for the VLAN's IPv4 network (e.g. 192.168.1.0).
+ - The base address for the VLAN's IPv4 network (for example V(192.168.1.0)).
type: str
default: ''
private_ipv4_prefix_size:
description:
- - The size of the IPv4 address space, e.g 24.
- - Required, if O(private_ipv4_base_address) is specified.
+ - The size of the IPv4 address space, for example V(24).
+ - Required, if O(private_ipv4_base_address) is specified.
type: int
default: 0
state:
description:
- The desired state for the target VLAN.
- - V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist).
+ - V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not
+ exist).
choices: [present, absent, readonly]
default: present
type: str
allow_expand:
description:
- - Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently possesses.
+ - Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently
+ possesses.
- If V(false), the module will fail under these conditions.
- This is intended to prevent accidental expansion of a VLAN's network (since this operation is not reversible).
type: bool
default: false
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add or update VLAN
community.general.dimensiondata_vlan:
region: na
@@ -100,59 +101,59 @@ EXAMPLES = '''
name: my_vlan_1
state: absent
wait: true
-'''
+"""
-RETURN = '''
+RETURN = r"""
vlan:
- description: Dictionary describing the VLAN.
- returned: On success when O(state=present)
- type: complex
- contains:
- id:
- description: VLAN ID.
- type: str
- sample: "aaaaa000-a000-4050-a215-2808934ccccc"
- name:
- description: VLAN name.
- type: str
- sample: "My VLAN"
- description:
- description: VLAN description.
- type: str
- sample: "My VLAN description"
- location:
- description: Datacenter location.
- type: str
- sample: NA3
- private_ipv4_base_address:
- description: The base address for the VLAN's private IPV4 network.
- type: str
- sample: 192.168.23.0
- private_ipv4_prefix_size:
- description: The prefix size for the VLAN's private IPV4 network.
- type: int
- sample: 24
- private_ipv4_gateway_address:
- description: The gateway address for the VLAN's private IPV4 network.
- type: str
- sample: 192.168.23.1
- private_ipv6_base_address:
- description: The base address for the VLAN's IPV6 network.
- type: str
- sample: 2402:9900:111:1195:0:0:0:0
- private_ipv6_prefix_size:
- description: The prefix size for the VLAN's IPV6 network.
- type: int
- sample: 64
- private_ipv6_gateway_address:
- description: The gateway address for the VLAN's IPV6 network.
- type: str
- sample: 2402:9900:111:1195:0:0:0:1
- status:
- description: VLAN status.
- type: str
- sample: NORMAL
-'''
+ description: Dictionary describing the VLAN.
+ returned: On success when O(state=present)
+ type: complex
+ contains:
+ id:
+ description: VLAN ID.
+ type: str
+ sample: "aaaaa000-a000-4050-a215-2808934ccccc"
+ name:
+ description: VLAN name.
+ type: str
+ sample: "My VLAN"
+ description:
+ description: VLAN description.
+ type: str
+ sample: "My VLAN description"
+ location:
+ description: Datacenter location.
+ type: str
+ sample: NA3
+ private_ipv4_base_address:
+ description: The base address for the VLAN's private IPV4 network.
+ type: str
+ sample: 192.168.23.0
+ private_ipv4_prefix_size:
+ description: The prefix size for the VLAN's private IPV4 network.
+ type: int
+ sample: 24
+ private_ipv4_gateway_address:
+ description: The gateway address for the VLAN's private IPV4 network.
+ type: str
+ sample: 192.168.23.1
+ private_ipv6_base_address:
+ description: The base address for the VLAN's IPV6 network.
+ type: str
+ sample: 2402:9900:111:1195:0:0:0:0
+ private_ipv6_prefix_size:
+ description: The prefix size for the VLAN's IPV6 network.
+ type: int
+ sample: 64
+ private_ipv6_gateway_address:
+ description: The gateway address for the VLAN's IPV6 network.
+ type: str
+ sample: 2402:9900:111:1195:0:0:0:1
+ status:
+ description: VLAN status.
+ type: str
+ sample: NORMAL
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.dimensiondata import DimensionDataModule, UnknownNetworkError
diff --git a/plugins/modules/discord.py b/plugins/modules/discord.py
index 130649f076..7cf05da0c1 100644
--- a/plugins/modules/discord.py
+++ b/plugins/modules/discord.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: discord
short_description: Send Discord messages
version_added: 3.1.0
@@ -18,7 +17,7 @@ description:
author: Christian Wollinger (@cwollinger)
seealso:
- name: API documentation
- description: Documentation for Discord API
+ description: Documentation for Discord API.
link: https://discord.com/developers/docs/resources/webhook#execute-webhook
extends_documentation_fragment:
- community.general.attributes
@@ -31,13 +30,13 @@ options:
webhook_id:
description:
- The webhook ID.
- - "Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token})."
+ - 'Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token}).'
required: true
type: str
webhook_token:
description:
- The webhook token.
- - "Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token})."
+ - 'Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token}).'
required: true
type: str
content:
@@ -62,13 +61,13 @@ options:
description:
- Send messages as Embeds to the Discord channel.
- Embeds can have a colored border, embedded images, text fields and more.
- - "Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object)"
+ - 'Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object).'
- At least one of O(content) and O(embeds) must be specified.
type: list
elements: dict
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Send a message to the Discord channel
community.general.discord:
webhook_id: "00000"
@@ -119,7 +118,7 @@ EXAMPLES = """
timestamp: "{{ ansible_date_time.iso8601 }}"
"""
-RETURN = """
+RETURN = r"""
http_code:
description:
- Response Code returned by Discord API.
diff --git a/plugins/modules/django_check.py b/plugins/modules/django_check.py
index 7a12ec94e2..9699428b9c 100644
--- a/plugins/modules/django_check.py
+++ b/plugins/modules/django_check.py
@@ -7,50 +7,49 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: django_check
author:
-- Alexei Znamensky (@russoz)
+ - Alexei Znamensky (@russoz)
short_description: Wrapper for C(django-admin check)
version_added: 9.1.0
description:
-- This module is a wrapper for the execution of C(django-admin check).
+ - This module is a wrapper for the execution of C(django-admin check).
extends_documentation_fragment:
-- community.general.attributes
-- community.general.django
+ - community.general.attributes
+ - community.general.django
options:
database:
description:
- - Specify databases to run checks against.
- - If not specified, Django will not run database tests.
+ - Specify databases to run checks against.
+ - If not specified, Django will not run database tests.
type: list
elements: str
deploy:
description:
- - Include additional checks relevant in a deployment setting.
+ - Include additional checks relevant in a deployment setting.
type: bool
default: false
fail_level:
description:
- - Message level that will trigger failure.
- - Default is the Django default value. Check the documentation for the version being used.
+ - Message level that will trigger failure.
+ - Default is the Django default value. Check the documentation for the version being used.
type: str
choices: [CRITICAL, ERROR, WARNING, INFO, DEBUG]
tags:
description:
- - Restrict checks to specific tags.
+ - Restrict checks to specific tags.
type: list
elements: str
apps:
description:
- - Restrict checks to specific applications.
- - Default is to check all applications.
+ - Restrict checks to specific applications.
+ - Default is to check all applications.
type: list
elements: str
notes:
-- The outcome of the module is found in the common return values RV(ignore:stdout), RV(ignore:stderr), RV(ignore:rc).
-- The module will fail if RV(ignore:rc) is not zero.
+ - The outcome of the module is found in the common return values RV(ignore:stdout), RV(ignore:stderr), RV(ignore:rc).
+ - The module will fail if RV(ignore:rc) is not zero.
attributes:
check_mode:
support: full
@@ -58,8 +57,7 @@ attributes:
support: none
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Check the entire project
community.general.django_check:
settings: myproject.settings
@@ -67,15 +65,14 @@ EXAMPLES = """
- name: Create the project using specific databases
community.general.django_check:
database:
- - somedb
- - myotherdb
+ - somedb
+ - myotherdb
settings: fancysite.settings
pythonpath: /home/joedoe/project/fancysite
venv: /home/joedoe/project/fancysite/venv
"""
-RETURN = """
----
+RETURN = r"""
run_info:
description: Command-line execution information.
type: dict
diff --git a/plugins/modules/django_command.py b/plugins/modules/django_command.py
index 2d6d36ad74..72cffb5c9c 100644
--- a/plugins/modules/django_command.py
+++ b/plugins/modules/django_command.py
@@ -7,18 +7,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: django_command
author:
-- Alexei Znamensky (@russoz)
+ - Alexei Znamensky (@russoz)
short_description: Run Django admin commands
version_added: 9.0.0
description:
-- This module allows the execution of arbitrary Django admin commands.
+ - This module allows the execution of arbitrary Django admin commands.
extends_documentation_fragment:
-- community.general.attributes
-- community.general.django
+ - community.general.attributes
+ - community.general.django
attributes:
check_mode:
support: none
@@ -27,18 +26,17 @@ attributes:
options:
command:
description:
- - Django admin command. It must be a valid command accepted by C(python -m django) at the target system.
+ - Django admin command. It must be a valid command accepted by C(python -m django) at the target system.
type: str
required: true
extra_args:
type: list
elements: str
description:
- - List of extra arguments passed to the django admin command.
+ - List of extra arguments passed to the django admin command.
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Check the project
community.general.django_command:
command: check
@@ -52,8 +50,7 @@ EXAMPLES = """
venv: /home/joedoe/project/fancysite/venv
"""
-RETURN = """
----
+RETURN = r"""
run_info:
description: Command-line execution information.
type: dict
diff --git a/plugins/modules/django_createcachetable.py b/plugins/modules/django_createcachetable.py
index 85f5774294..4d849624a9 100644
--- a/plugins/modules/django_createcachetable.py
+++ b/plugins/modules/django_createcachetable.py
@@ -7,19 +7,18 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: django_createcachetable
author:
-- Alexei Znamensky (@russoz)
+ - Alexei Znamensky (@russoz)
short_description: Wrapper for C(django-admin createcachetable)
version_added: 9.1.0
description:
-- This module is a wrapper for the execution of C(django-admin createcachetable).
+ - This module is a wrapper for the execution of C(django-admin createcachetable).
extends_documentation_fragment:
-- community.general.attributes
-- community.general.django
-- community.general.django.database
+ - community.general.attributes
+ - community.general.django
+ - community.general.django.database
attributes:
check_mode:
support: full
@@ -27,8 +26,7 @@ attributes:
support: none
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Create cache table in the default database
community.general.django_createcachetable:
settings: myproject.settings
@@ -41,8 +39,7 @@ EXAMPLES = """
venv: /home/joedoe/project/fancysite/venv
"""
-RETURN = """
----
+RETURN = r"""
run_info:
description: Command-line execution information.
type: dict
diff --git a/plugins/modules/django_manage.py b/plugins/modules/django_manage.py
index 352bfe4b50..dab544a29d 100644
--- a/plugins/modules/django_manage.py
+++ b/plugins/modules/django_manage.py
@@ -10,13 +10,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: django_manage
short_description: Manages a Django application
description:
- - Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the
- O(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation.
+ - Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the O(virtualenv) parameter,
+ all management commands will be executed by the given C(virtualenv) installation.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -27,17 +26,18 @@ attributes:
options:
command:
description:
- - The name of the Django management command to run. The commands listed below are built in this module and have some basic parameter validation.
+ - The name of the Django management command to run. The commands listed below are built in this module and have some
+ basic parameter validation.
- V(collectstatic) - Collects the static files into C(STATIC_ROOT).
- V(createcachetable) - Creates the cache tables for use with the database cache backend.
- V(flush) - Removes all data from the database.
- V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database.
- V(migrate) - Synchronizes the database state with models and migrations.
- V(test) - Runs tests for all installed apps.
- - Other commands can be entered, but will fail if they are unknown to Django. Other commands that may
- prompt for user input should be run with the C(--noinput) flag.
- - Support for the values V(cleanup), V(syncdb), V(validate) was removed in community.general 9.0.0.
- See note about supported versions of Django.
+ - Other commands can be entered, but will fail if they are unknown to Django. Other commands that may prompt for user
+ input should be run with the C(--noinput) flag.
+ - Support for the values V(cleanup), V(syncdb), V(validate) was removed in community.general 9.0.0. See note about supported
+ versions of Django.
type: str
required: true
project_path:
@@ -53,8 +53,8 @@ options:
required: false
pythonpath:
description:
- - A directory to add to the Python path. Typically used to include the settings module if it is located
- external to the application directory.
+ - A directory to add to the Python path. Typically used to include the settings module if it is located external to
+ the application directory.
- This would be equivalent to adding O(pythonpath)'s value to the E(PYTHONPATH) environment variable.
type: path
required: false
@@ -84,8 +84,7 @@ options:
type: bool
database:
description:
- - The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb),
- and V(migrate) commands.
+ - The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb), and V(migrate) commands.
type: str
required: false
failfast:
@@ -107,14 +106,13 @@ options:
type: bool
merge:
description:
- - Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this
- parameter with V(migrate) command.
+ - Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this parameter with
+ V(migrate) command.
required: false
type: bool
link:
description:
- - Will create links to the files instead of copying them, you can only use this parameter with
- V(collectstatic) command.
+ - Will create links to the files instead of copying them, you can only use this parameter with V(collectstatic) command.
required: false
type: bool
testrunner:
@@ -132,20 +130,17 @@ options:
version_added: 5.8.0
notes:
- - >
- B(ATTENTION): Support for Django releases older than 4.1 has been removed in
- community.general version 9.0.0. While the module allows for free-form commands
- does not verify the version of Django being used, it is B(strongly recommended)
- to use a more recent version of Django.
+ - 'B(ATTENTION): Support for Django releases older than 4.1 has been removed in community.general version 9.0.0. While the
+ module allows for free-form commands, not verifying the version of Django being used, it is B(strongly recommended) to
+ use a more recent version of the framework.'
- Please notice that Django 4.1 requires Python 3.8 or greater.
- - This module will not create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment
- does not already exist at the given location. This behavior changed in community.general version 9.0.0.
+ - This module will not create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment does not
+ already exist at the given location. This behavior changed in community.general version 9.0.0.
- The recommended way to create a virtual environment in Ansible is by using M(ansible.builtin.pip).
- - This module assumes English error messages for the V(createcachetable) command to detect table existence,
- unfortunately.
+ - This module assumes English error messages for the V(createcachetable) command to detect table existence, unfortunately.
- To be able to use the V(collectstatic) command, you must have enabled C(staticfiles) in your settings.
- - Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang,
- for example C(#!/usr/bin/env python), for invoking the appropriate Python interpreter.
+ - Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang, for example C(#!/usr/bin/env
+ python), for invoking the appropriate Python interpreter.
seealso:
- name: django-admin and manage.py Reference
description: Reference for C(django-admin) or C(manage.py) commands.
@@ -156,13 +151,13 @@ seealso:
- name: What Python version can I use with Django?
description: From the Django FAQ, the response to Python requirements for the framework.
link: https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django
-requirements: [ "django >= 4.1" ]
+requirements: ["django >= 4.1"]
author:
- Alexei Znamensky (@russoz)
- Scott Anderson (@tastychutney)
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Run cleanup on the application installed in django_dir
community.general.django_manage:
command: clearsessions
diff --git a/plugins/modules/dnf_config_manager.py b/plugins/modules/dnf_config_manager.py
index 069fd0ddc7..2d896f3742 100644
--- a/plugins/modules/dnf_config_manager.py
+++ b/plugins/modules/dnf_config_manager.py
@@ -7,8 +7,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: dnf_config_manager
short_description: Enable or disable dnf repositories using config-manager
version_added: 8.2.0
@@ -43,9 +42,9 @@ options:
seealso:
- module: ansible.builtin.dnf
- module: ansible.builtin.yum_repository
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure the crb repository is enabled
community.general.dnf_config_manager:
name: crb
@@ -57,9 +56,9 @@ EXAMPLES = r'''
- appstream
- zfs
state: disabled
-'''
+"""
-RETURN = r'''
+RETURN = r"""
repo_states_pre:
description: Repo IDs before action taken.
returned: success
@@ -115,12 +114,12 @@ repo_states_post:
- crb-debug
- crb-source
changed_repos:
- description: Repositories changed.
- returned: success
- type: list
- elements: str
- sample: [ 'crb' ]
-'''
+ description: Repositories changed.
+ returned: success
+ type: list
+ elements: str
+ sample: ['crb']
+"""
from ansible.module_utils.basic import AnsibleModule
import os
@@ -153,7 +152,7 @@ def get_repo_states(module):
def set_repo_states(module, repo_ids, state):
- module.run_command([DNF_BIN, 'config-manager', '--set-{0}'.format(state)] + repo_ids, check_rc=True)
+ module.run_command([DNF_BIN, 'config-manager', '--assumeyes', '--set-{0}'.format(state)] + repo_ids, check_rc=True)
def pack_repo_states_for_return(states):
@@ -186,6 +185,7 @@ def main():
argument_spec=module_args,
supports_check_mode=True
)
+ module.run_command_environ_update = dict(LANGUAGE='C', LC_ALL='C')
if not os.path.exists(DNF_BIN):
module.fail_json(msg="%s was not found" % DNF_BIN)
diff --git a/plugins/modules/dnf_versionlock.py b/plugins/modules/dnf_versionlock.py
index 3fcf132eaf..eec7f3013a 100644
--- a/plugins/modules/dnf_versionlock.py
+++ b/plugins/modules/dnf_versionlock.py
@@ -7,37 +7,32 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: dnf_versionlock
version_added: '4.0.0'
short_description: Locks package versions in C(dnf) based systems
description:
-- Locks package versions using the C(versionlock) plugin in C(dnf) based
- systems. This plugin takes a set of name and versions for packages and
- excludes all other versions of those packages. This allows you to for example
- protect packages from being updated by newer versions. The state of the
- plugin that reflects locking of packages is the C(locklist).
+ - Locks package versions using the C(versionlock) plugin in C(dnf) based systems. This plugin takes a set of name and versions
+ for packages and excludes all other versions of those packages. This allows you to for example protect packages from being
+ updated by newer versions. The state of the plugin that reflects locking of packages is the C(locklist).
extends_documentation_fragment:
- community.general.attributes
attributes:
check_mode:
support: partial
details:
- - The logics of the C(versionlock) plugin for corner cases could be
- confusing, so please take in account that this module will do its best to
- give a C(check_mode) prediction on what is going to happen. In case of
- doubt, check the documentation of the plugin.
- - Sometimes the module could predict changes in C(check_mode) that will not
- be such because C(versionlock) concludes that there is already a entry in
- C(locklist) that already matches.
+ - The logics of the C(versionlock) plugin for corner cases could be confusing, so please take in account that this module
+ will do its best to give a C(check_mode) prediction on what is going to happen. In case of doubt, check the documentation
+ of the plugin.
+ - Sometimes the module could predict changes in C(check_mode) that will not be such because C(versionlock) concludes
+ that there is already a entry in C(locklist) that already matches.
diff_mode:
support: none
options:
name:
description:
- - Package name spec to add or exclude to or delete from the C(locklist)
- using the format expected by the C(dnf repoquery) command.
+ - Package name spec to add or exclude to or delete from the C(locklist) using the format expected by the C(dnf repoquery)
+ command.
- This parameter is mutually exclusive with O(state=clean).
type: list
required: false
@@ -45,43 +40,34 @@ options:
default: []
raw:
description:
- - Do not resolve package name specs to NEVRAs to find specific version
- to lock to. Instead the package name specs are used as they are. This
- enables locking to not yet available versions of the package.
+ - Do not resolve package name specs to NEVRAs to find specific version to lock to. Instead the package name specs are
+ used as they are. This enables locking to not yet available versions of the package.
type: bool
default: false
state:
description:
- - Whether to add (V(present) or V(excluded)) to or remove (V(absent) or
- V(clean)) from the C(locklist).
- - V(present) will add a package name spec to the C(locklist). If there is a
- installed package that matches, then only that version will be added.
- Otherwise, all available package versions will be added.
- - V(excluded) will add a package name spec as excluded to the
- C(locklist). It means that packages represented by the package name
- spec will be excluded from transaction operations. All available
- package versions will be added.
- - V(absent) will delete entries in the C(locklist) that match the
- package name spec.
- - V(clean) will delete all entries in the C(locklist). This option is
- mutually exclusive with O(name).
- choices: [ 'absent', 'clean', 'excluded', 'present' ]
+ - Whether to add (V(present) or V(excluded)) to or remove (V(absent) or V(clean)) from the C(locklist).
+ - V(present) will add a package name spec to the C(locklist). If there is a installed package that matches, then only
+ that version will be added. Otherwise, all available package versions will be added.
+ - V(excluded) will add a package name spec as excluded to the C(locklist). It means that packages represented by the
+ package name spec will be excluded from transaction operations. All available package versions will be added.
+ - V(absent) will delete entries in the C(locklist) that match the package name spec.
+ - V(clean) will delete all entries in the C(locklist). This option is mutually exclusive with O(name).
+ choices: ['absent', 'clean', 'excluded', 'present']
type: str
default: present
notes:
- - In an ideal world, the C(versionlock) plugin would have a dry-run option to
- know for sure what is going to happen. So far we have to work with a best
- guess as close as possible to the behaviour inferred from its code.
- - For most of cases where you want to lock and unlock specific versions of a
- package, this works fairly well.
+ - In an ideal world, the C(versionlock) plugin would have a dry-run option to know for sure what is going to happen. So
+ far we have to work with a best guess as close as possible to the behaviour inferred from its code.
+ - For most of cases where you want to lock and unlock specific versions of a package, this works fairly well.
requirements:
- dnf
- dnf-plugin-versionlock
author:
- Roberto Moreda (@moreda)
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Prevent installed nginx from being updated
community.general.dnf_versionlock:
name: nginx
@@ -113,34 +99,34 @@ EXAMPLES = r'''
- name: Delete all entries in the locklist of versionlock
community.general.dnf_versionlock:
state: clean
-'''
+"""
-RETURN = r'''
+RETURN = r"""
locklist_pre:
- description: Locklist before module execution.
- returned: success
- type: list
- elements: str
- sample: [ 'bash-0:4.4.20-1.el8_4.*', '!bind-32:9.11.26-4.el8_4.*' ]
+ description: Locklist before module execution.
+ returned: success
+ type: list
+ elements: str
+ sample: ['bash-0:4.4.20-1.el8_4.*', '!bind-32:9.11.26-4.el8_4.*']
locklist_post:
- description: Locklist after module execution.
- returned: success and (not check mode or state is clean)
- type: list
- elements: str
- sample: [ 'bash-0:4.4.20-1.el8_4.*' ]
+ description: Locklist after module execution.
+ returned: success and (not check mode or state is clean)
+ type: list
+ elements: str
+ sample: ['bash-0:4.4.20-1.el8_4.*']
specs_toadd:
- description: Package name specs meant to be added by versionlock.
- returned: success
- type: list
- elements: str
- sample: [ 'bash' ]
+ description: Package name specs meant to be added by versionlock.
+ returned: success
+ type: list
+ elements: str
+ sample: ['bash']
specs_todelete:
- description: Package name specs meant to be deleted by versionlock.
- returned: success
- type: list
- elements: str
- sample: [ 'bind' ]
-'''
+ description: Package name specs meant to be deleted by versionlock.
+ returned: success
+ type: list
+ elements: str
+ sample: ['bind']
+"""
from ansible.module_utils.basic import AnsibleModule
import fnmatch
@@ -235,6 +221,43 @@ def get_packages(module, patterns, only_installed=False):
return packages_available_map_name_evrs
+def get_package_mgr():
+ for bin_path in (DNF_BIN,):
+ if os.path.exists(bin_path):
+ return "dnf5" if os.path.realpath(bin_path) == "/usr/bin/dnf5" else "dnf"
+ # fallback to dnf
+ return "dnf"
+
+
+def get_package_list(module, package_mgr="dnf"):
+ if package_mgr == "dnf":
+ return do_versionlock(module, "list").split()
+
+ package_list = []
+ if package_mgr == "dnf5":
+ stanza_start = False
+ package_name = None
+ for line in do_versionlock(module, "list").splitlines():
+ if line.startswith(("#", " ")):
+ continue
+ if line.startswith("Package name:"):
+ stanza_start = True
+ dummy, name = line.split(":", 1)
+ name = name.strip()
+ pkg_name = get_packages(module, patterns=[name])
+ package_name = "%s-%s.*" % (name, pkg_name[name].pop())
+ if package_name and package_name not in package_list:
+ package_list.append(package_name)
+ if line.startswith("evr"):
+ dummy, package_version = line.split("=", 1)
+ package_version = package_version.strip()
+ if stanza_start:
+ if package_name and package_name not in package_list:
+ package_list.append(package_name)
+ stanza_start = False
+ return package_list
+
+
def main():
module = AnsibleModule(
argument_spec=dict(
@@ -253,9 +276,10 @@ def main():
msg = ""
# Check module pre-requisites.
- if not os.path.exists(DNF_BIN):
- module.fail_json(msg="%s was not found" % DNF_BIN)
- if not os.path.exists(VERSIONLOCK_CONF):
+ global DNF_BIN
+ DNF_BIN = module.get_bin_path('dnf', True)
+ package_mgr = get_package_mgr()
+ if package_mgr == "dnf" and not os.path.exists(VERSIONLOCK_CONF):
module.fail_json(msg="plugin versionlock is required")
# Check incompatible options.
@@ -264,7 +288,7 @@ def main():
if state != "clean" and not patterns:
module.fail_json(msg="name list is required for %s state" % state)
- locklist_pre = do_versionlock(module, "list").split()
+ locklist_pre = get_package_list(module, package_mgr=package_mgr)
specs_toadd = []
specs_todelete = []
@@ -343,7 +367,7 @@ def main():
"specs_todelete": specs_todelete
}
if not module.check_mode:
- response["locklist_post"] = do_versionlock(module, "list").split()
+ response["locklist_post"] = get_package_list(module, package_mgr=package_mgr)
else:
if state == "clean":
response["locklist_post"] = []
diff --git a/plugins/modules/dnsimple.py b/plugins/modules/dnsimple.py
index c5829e36eb..ffa856f137 100644
--- a/plugins/modules/dnsimple.py
+++ b/plugins/modules/dnsimple.py
@@ -10,12 +10,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: dnsimple
short_description: Interface with dnsimple.com (a DNS hosting service)
description:
- - "Manages domains and records via the DNSimple API, see the docs: U(http://developer.dnsimple.com/)."
+ - 'Manages domains and records using the DNSimple API, see the docs: U(http://developer.dnsimple.com/).'
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -27,8 +26,8 @@ options:
account_email:
description:
- Account email. If omitted, the environment variables E(DNSIMPLE_EMAIL) and E(DNSIMPLE_API_TOKEN) will be looked for.
- - "If those aren't found, a C(.dnsimple) file will be looked for, see: U(https://github.com/mikemaccana/dnsimple-python#getting-started)."
- - "C(.dnsimple) config files are only supported in dnsimple-python<2.0.0"
+ - 'If those variables are not found, a C(.dnsimple) file will be looked for, see: U(https://github.com/mikemaccana/dnsimple-python#getting-started).'
+ - C(.dnsimple) config files are only supported in dnsimple-python<2.0.0.
type: str
account_api_token:
description:
@@ -36,9 +35,9 @@ options:
type: str
domain:
description:
- - Domain to work with. Can be the domain name (e.g. "mydomain.com") or the numeric ID of the domain in DNSimple.
+ - Domain to work with. Can be the domain name (for example V(mydomain.com)) or the numeric ID of the domain in DNSimple.
- If omitted, a list of domains will be returned.
- - If domain is present but the domain doesn't exist, it will be created.
+ - If domain is present but the domain does not exist, it will be created.
type: str
record:
description:
@@ -52,7 +51,8 @@ options:
type:
description:
- The type of DNS record to create.
- choices: [ 'A', 'ALIAS', 'CNAME', 'MX', 'SPF', 'URL', 'TXT', 'NS', 'SRV', 'NAPTR', 'PTR', 'AAAA', 'SSHFP', 'HINFO', 'POOL', 'CAA' ]
+ choices: ['A', 'ALIAS', 'CNAME', 'MX', 'SPF', 'URL', 'TXT', 'NS', 'SRV', 'NAPTR', 'PTR', 'AAAA', 'SSHFP', 'HINFO', 'POOL',
+ 'CAA']
type: str
ttl:
description:
@@ -70,8 +70,8 @@ options:
type: int
state:
description:
- - whether the record should exist or not.
- choices: [ 'present', 'absent' ]
+ - Whether the record should exist or not.
+ choices: ['present', 'absent']
default: present
type: str
solo:
@@ -91,9 +91,9 @@ options:
requirements:
- "dnsimple >= 2.0.0"
author: "Alex Coomans (@drcapulet)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Authenticate using email and API token and fetch all domains
community.general.dnsimple:
account_email: test@example.com
@@ -149,7 +149,7 @@ EXAMPLES = '''
value: example.com
state: absent
delegate_to: localhost
-'''
+"""
RETURN = r"""# """
diff --git a/plugins/modules/dnsimple_info.py b/plugins/modules/dnsimple_info.py
index 46c2877f73..c508525fac 100644
--- a/plugins/modules/dnsimple_info.py
+++ b/plugins/modules/dnsimple_info.py
@@ -9,8 +9,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: dnsimple_info
short_description: Pull basic info from DNSimple API
@@ -20,45 +19,45 @@ version_added: "4.2.0"
description: Retrieve existing records and domains from DNSimple API.
extends_documentation_fragment:
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.attributes
+ - community.general.attributes.info_module
options:
- name:
- description:
- - The domain name to retrieve info from.
- - Will return all associated records for this domain if specified.
- - If not specified, will return all domains associated with the account ID.
- type: str
+ name:
+ description:
+ - The domain name to retrieve info from.
+ - Will return all associated records for this domain if specified.
+ - If not specified, will return all domains associated with the account ID.
+ type: str
- account_id:
- description: The account ID to query.
- required: true
- type: str
+ account_id:
+ description: The account ID to query.
+ required: true
+ type: str
- api_key:
- description: The API key to use.
- required: true
- type: str
+ api_key:
+ description: The API key to use.
+ required: true
+ type: str
- record:
- description:
- - The record to find.
- - If specified, only this record will be returned instead of all records.
- required: false
- type: str
+ record:
+ description:
+ - The record to find.
+ - If specified, only this record will be returned instead of all records.
+ required: false
+ type: str
- sandbox:
- description: Whether or not to use sandbox environment.
- required: false
- default: false
- type: bool
+ sandbox:
+ description: Whether or not to use sandbox environment.
+ required: false
+ default: false
+ type: bool
author:
- - Edward Hilgendorf (@edhilgendorf)
-'''
+ - Edward Hilgendorf (@edhilgendorf)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Get all domains from an account
community.general.dnsimple_info:
account_id: "1234"
@@ -76,15 +75,15 @@ EXAMPLES = r'''
record: "subdomain"
account_id: "1234"
api_key: "1234"
-'''
+"""
-RETURN = r'''
+RETURN = r"""
dnsimple_domain_info:
- description: Returns a list of dictionaries of all domains associated with the supplied account ID.
- type: list
- elements: dict
- returned: success when O(name) is not specified
- sample:
+ description: Returns a list of dictionaries of all domains associated with the supplied account ID.
+ type: list
+ elements: dict
+ returned: success when O(name) is not specified
+ sample:
- account_id: 1234
created_at: '2021-10-16T21:25:42Z'
id: 123456
@@ -93,41 +92,41 @@ dnsimple_domain_info:
reverse: false
secondary: false
updated_at: '2021-11-10T20:22:50Z'
- contains:
- account_id:
- description: The account ID.
- type: int
- created_at:
- description: When the domain entry was created.
- type: str
- id:
- description: ID of the entry.
- type: int
- last_transferred_at:
- description: Date the domain was transferred, or empty if not.
- type: str
- name:
- description: Name of the record.
- type: str
- reverse:
- description: Whether or not it is a reverse zone record.
- type: bool
- updated_at:
- description: When the domain entry was updated.
- type: str
+ contains:
+ account_id:
+ description: The account ID.
+ type: int
+ created_at:
+ description: When the domain entry was created.
+ type: str
+ id:
+ description: ID of the entry.
+ type: int
+ last_transferred_at:
+ description: Date the domain was transferred, or empty if not.
+ type: str
+ name:
+ description: Name of the record.
+ type: str
+ reverse:
+ description: Whether or not it is a reverse zone record.
+ type: bool
+ updated_at:
+ description: When the domain entry was updated.
+ type: str
dnsimple_records_info:
- description: Returns a list of dictionaries with all records for the domain supplied.
- type: list
- elements: dict
- returned: success when O(name) is specified, but O(record) is not
- sample:
+ description: Returns a list of dictionaries with all records for the domain supplied.
+ type: list
+ elements: dict
+ returned: success when O(name) is specified, but O(record) is not
+ sample:
- content: ns1.dnsimple.com admin.dnsimple.com
created_at: '2021-10-16T19:07:34Z'
id: 12345
name: 'catheadbiscuit'
- parent_id: null
- priority: null
+ parent_id:
+ priority:
regions:
- global
system_record: true
@@ -135,55 +134,55 @@ dnsimple_records_info:
type: SOA
updated_at: '2021-11-15T23:55:51Z'
zone_id: example.com
- contains:
- content:
- description: Content of the returned record.
- type: str
- created_at:
- description: When the domain entry was created.
- type: str
- id:
- description: ID of the entry.
- type: int
- name:
- description: Name of the record.
- type: str
- parent_id:
- description: Parent record or null.
- type: int
- priority:
- description: Priority setting of the record.
- type: str
- regions:
- description: List of regions where the record is available.
- type: list
- system_record:
- description: Whether or not it is a system record.
- type: bool
- ttl:
- description: Record TTL.
- type: int
- type:
- description: Record type.
- type: str
- updated_at:
- description: When the domain entry was updated.
- type: str
- zone_id:
- description: ID of the zone that the record is associated with.
- type: str
+ contains:
+ content:
+ description: Content of the returned record.
+ type: str
+ created_at:
+ description: When the domain entry was created.
+ type: str
+ id:
+ description: ID of the entry.
+ type: int
+ name:
+ description: Name of the record.
+ type: str
+ parent_id:
+ description: Parent record or null.
+ type: int
+ priority:
+ description: Priority setting of the record.
+ type: str
+ regions:
+ description: List of regions where the record is available.
+ type: list
+ system_record:
+ description: Whether or not it is a system record.
+ type: bool
+ ttl:
+ description: Record TTL.
+ type: int
+ type:
+ description: Record type.
+ type: str
+ updated_at:
+ description: When the domain entry was updated.
+ type: str
+ zone_id:
+ description: ID of the zone that the record is associated with.
+ type: str
dnsimple_record_info:
- description: Returns a list of dictionaries that match the record supplied.
- returned: success when O(name) and O(record) are specified
- type: list
- elements: dict
- sample:
+ description: Returns a list of dictionaries that match the record supplied.
+ returned: success when O(name) and O(record) are specified
+ type: list
+ elements: dict
+ sample:
- content: 1.2.3.4
created_at: '2021-11-15T23:55:51Z'
id: 123456
name: catheadbiscuit
- parent_id: null
- priority: null
+ parent_id:
+ priority:
regions:
- global
system_record: false
@@ -191,44 +190,44 @@ dnsimple_record_info:
type: A
updated_at: '2021-11-15T23:55:51Z'
zone_id: example.com
- contains:
- content:
- description: Content of the returned record.
- type: str
- created_at:
- description: When the domain entry was created.
- type: str
- id:
- description: ID of the entry.
- type: int
- name:
- description: Name of the record.
- type: str
- parent_id:
- description: Parent record or null.
- type: int
- priority:
- description: Priority setting of the record.
- type: str
- regions:
- description: List of regions where the record is available.
- type: list
- system_record:
- description: Whether or not it is a system record.
- type: bool
- ttl:
- description: Record TTL.
- type: int
- type:
- description: Record type.
- type: str
- updated_at:
- description: When the domain entry was updated.
- type: str
- zone_id:
- description: ID of the zone that the record is associated with.
- type: str
-'''
+ contains:
+ content:
+ description: Content of the returned record.
+ type: str
+ created_at:
+ description: When the domain entry was created.
+ type: str
+ id:
+ description: ID of the entry.
+ type: int
+ name:
+ description: Name of the record.
+ type: str
+ parent_id:
+ description: Parent record or null.
+ type: int
+ priority:
+ description: Priority setting of the record.
+ type: str
+ regions:
+ description: List of regions where the record is available.
+ type: list
+ system_record:
+ description: Whether or not it is a system record.
+ type: bool
+ ttl:
+ description: Record TTL.
+ type: int
+ type:
+ description: Record type.
+ type: str
+ updated_at:
+ description: When the domain entry was updated.
+ type: str
+ zone_id:
+ description: ID of the zone that the record is associated with.
+ type: str
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils import deps
diff --git a/plugins/modules/dnsmadeeasy.py b/plugins/modules/dnsmadeeasy.py
index 47d9430e7b..83268af379 100644
--- a/plugins/modules/dnsmadeeasy.py
+++ b/plugins/modules/dnsmadeeasy.py
@@ -9,14 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: dnsmadeeasy
short_description: Interface with dnsmadeeasy.com (a DNS hosting service)
description:
- - >
- Manages DNS records via the v2 REST API of the DNS Made Easy service. It handles records only; there is no manipulation of domains or
- monitor/account support yet. See: U(https://www.dnsmadeeasy.com/integration/restapi/)
+ - 'Manages DNS records using the v2 REST API of the DNS Made Easy service. It handles records only; there is no manipulation
+ of domains or monitor/account support yet. See: U(https://www.dnsmadeeasy.com/integration/restapi/).'
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -39,8 +37,8 @@ options:
domain:
description:
- - Domain to work with. Can be the domain name (e.g. "mydomain.com") or the numeric ID of the domain in DNS Made Easy (e.g. "839989") for faster
- resolution
+ - Domain to work with. Can be the domain name (for example V(mydomain.com)) or the numeric ID of the domain in DNS Made
+ Easy (for example V(839989)) for faster resolution.
required: true
type: str
@@ -52,49 +50,47 @@ options:
record_name:
description:
- - Record name to get/create/delete/update. If record_name is not specified; all records for the domain will be returned in "result" regardless
- of the state argument.
+ - Record name to get/create/delete/update. If record_name is not specified; all records for the domain will be returned
+ in "result" regardless of the state argument.
type: str
record_type:
description:
- Record type.
- choices: [ 'A', 'AAAA', 'CNAME', 'ANAME', 'HTTPRED', 'MX', 'NS', 'PTR', 'SRV', 'TXT' ]
+ choices: ['A', 'AAAA', 'CNAME', 'ANAME', 'HTTPRED', 'MX', 'NS', 'PTR', 'SRV', 'TXT']
type: str
record_value:
description:
- - >
- Record value. HTTPRED: , MX: , NS: , PTR: ,
- SRV: , TXT: "
- - >
- If record_value is not specified; no changes will be made and the record will be returned in 'result'
- (in other words, this module can be used to fetch a record's current id, type, and ttl)
+ - 'Record value. HTTPRED: , MX: , NS: , PTR: , SRV:
+ , TXT: ".'
+ - If record_value is not specified; no changes will be made and the record will be returned in 'result' (in other words,
+ this module can be used to fetch a record's current ID, type, and ttl).
type: str
record_ttl:
description:
- - record's "Time to live". Number of seconds the record remains cached in DNS servers.
+ - Record's "Time-To-Live". Number of seconds the record remains cached in DNS servers.
default: 1800
type: int
state:
description:
- - whether the record should exist or not
+ - Whether the record should exist or not.
required: true
- choices: [ 'present', 'absent' ]
+ choices: ['present', 'absent']
type: str
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
type: bool
default: true
monitor:
description:
- - If V(true), add or change the monitor. This is applicable only for A records.
+ - If V(true), add or change the monitor. This is applicable only for A records.
type: bool
default: false
@@ -132,7 +128,7 @@ options:
contactList:
description:
- - Name or id of the contact list that the monitor will notify.
+ - Name or ID of the contact list that the monitor will notify.
- The default V('') means the Account Owner.
type: str
@@ -153,7 +149,7 @@ options:
failover:
description:
- - If V(true), add or change the failover. This is applicable only for A records.
+ - If V(true), add or change the failover. This is applicable only for A records.
type: bool
default: false
@@ -192,20 +188,19 @@ options:
type: str
notes:
- - The DNS Made Easy service requires that machines interacting with the API have the proper time and timezone set. Be sure you are within a few
- seconds of actual time by using NTP.
- - This module returns record(s) and monitor(s) in the "result" element when 'state' is set to 'present'.
- These values can be be registered and used in your playbooks.
- - Only A records can have a monitor or failover.
- - To add failover, the 'failover', 'autoFailover', 'port', 'protocol', 'ip1', and 'ip2' options are required.
- - To add monitor, the 'monitor', 'port', 'protocol', 'maxEmails', 'systemDescription', and 'ip1' options are required.
- - The monitor and the failover will share 'port', 'protocol', and 'ip1' options.
-
-requirements: [ hashlib, hmac ]
+ - The DNS Made Easy service requires that machines interacting with the API have the proper time and timezone set. Be sure
+ you are within a few seconds of actual time by using NTP.
+ - This module returns record(s) and monitor(s) in the RV(ignore:result) element when O(state=present). These values can
+ be be registered and used in your playbooks.
+ - Only A records can have a O(monitor) or O(failover).
+ - To add failover, the O(failover), O(autoFailover), O(port), O(protocol), O(ip1), and O(ip2) options are required.
+ - To add monitor, the O(monitor), O(port), O(protocol), O(maxEmails), O(systemDescription), and O(ip1) options are required.
+ - The monitor and the failover will share O(port), O(protocol), and O(ip1) options.
+requirements: [hashlib, hmac]
author: "Brice Burgess (@briceburg)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Fetch my.com domain records
community.general.dnsmadeeasy:
account_key: key
@@ -291,8 +286,8 @@ EXAMPLES = '''
record_value: 127.0.0.1
monitor: true
ip1: 127.0.0.2
- protocol: HTTP # default
- port: 80 # default
+ protocol: HTTP # default
+ port: 80 # default
maxEmails: 1
systemDescription: Monitor Test A record
contactList: my contact list
@@ -308,11 +303,11 @@ EXAMPLES = '''
record_value: 127.0.0.1
monitor: true
ip1: 127.0.0.2
- protocol: HTTP # default
- port: 80 # default
+ protocol: HTTP # default
+ port: 80 # default
maxEmails: 1
systemDescription: Monitor Test A record
- contactList: 1174 # contact list id
+ contactList: 1174 # contact list id
httpFqdn: http://my.com
httpFile: example
httpQueryString: some string
@@ -357,7 +352,7 @@ EXAMPLES = '''
record_type: A
record_value: 127.0.0.1
monitor: false
-'''
+"""
# ============================================
# DNSMadeEasy module specific support methods.
@@ -491,7 +486,7 @@ class DME2(object):
return self.query(self.record_url, 'GET')['data']
def _instMap(self, type):
- # @TODO cache this call so it's executed only once per ansible execution
+ # @TODO cache this call so it is executed only once per ansible execution
map = {}
results = {}
diff --git a/plugins/modules/dpkg_divert.py b/plugins/modules/dpkg_divert.py
index 5f0d924fe2..90ce464ccd 100644
--- a/plugins/modules/dpkg_divert.py
+++ b/plugins/modules/dpkg_divert.py
@@ -9,24 +9,20 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: dpkg_divert
short_description: Override a debian package's version of a file
version_added: '0.2.0'
author:
- quidame (@quidame)
description:
- - A diversion is for C(dpkg) the knowledge that only a given package
- (or the local administrator) is allowed to install a file at a given
- location. Other packages shipping their own version of this file will
- be forced to O(divert) it, that is to install it at another location. It
- allows one to keep changes in a file provided by a debian package by
- preventing its overwrite at package upgrade.
- - This module manages diversions of debian packages files using the
- C(dpkg-divert) commandline tool. It can either create or remove a
- diversion for a given file, but also update an existing diversion
- to modify its O(holder) and/or its O(divert) location.
+ - A diversion is for C(dpkg) the knowledge that only a given package (or the local administrator) is allowed to install
+ a file at a given location. Other packages shipping their own version of this file will be forced to O(divert) it, that
+ is to install it at another location. It allows one to keep changes in a file provided by a debian package by preventing
+ it being overwritten on package upgrade.
+ - This module manages diversions of debian packages files using the C(dpkg-divert) commandline tool. It can either create
+ or remove a diversion for a given file, but also update an existing diversion to modify its O(holder) and/or its O(divert)
+ location.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -37,28 +33,23 @@ attributes:
options:
path:
description:
- - The original and absolute path of the file to be diverted or
- undiverted. This path is unique, i.e. it is not possible to get
- two diversions for the same O(path).
+ - The original and absolute path of the file to be diverted or undiverted. This path is unique, in other words it is
+ not possible to get two diversions for the same O(path).
required: true
type: path
state:
description:
- - When O(state=absent), remove the diversion of the specified
- O(path); when O(state=present), create the diversion if it does
- not exist, or update its package O(holder) or O(divert) location,
- if it already exists.
+ - When O(state=absent), remove the diversion of the specified O(path); when O(state=present), create the diversion if
+ it does not exist, or update its package O(holder) or O(divert) location, if it already exists.
type: str
default: present
choices: [absent, present]
holder:
description:
- - The name of the package whose copy of file is not diverted, also
- known as the diversion holder or the package the diversion belongs
- to.
- - The actual package does not have to be installed or even to exist
- for its name to be valid. If not specified, the diversion is hold
- by 'LOCAL', that is reserved by/for dpkg for local diversions.
+ - The name of the package whose copy of file is not diverted, also known as the diversion holder or the package the
+ diversion belongs to.
+ - The actual package does not have to be installed or even to exist for its name to be valid. If not specified, the
+ diversion is hold by 'LOCAL', that is reserved by/for dpkg for local diversions.
- This parameter is ignored when O(state=absent).
type: str
divert:
@@ -69,28 +60,25 @@ options:
type: path
rename:
description:
- - Actually move the file aside (when O(state=present)) or back (when
- O(state=absent)), but only when changing the state of the diversion.
- This parameter has no effect when attempting to add a diversion that
- already exists or when removing an unexisting one.
- - Unless O(force=true), renaming fails if the destination file already
- exists (this lock being a dpkg-divert feature, and bypassing it being
- a module feature).
+ - Actually move the file aside (when O(state=present)) or back (when O(state=absent)), but only when changing the state
+ of the diversion. This parameter has no effect when attempting to add a diversion that already exists or when removing
+ an unexisting one.
+ - Unless O(force=true), renaming fails if the destination file already exists (this lock being a dpkg-divert feature,
+ and bypassing it being a module feature).
type: bool
default: false
force:
description:
- - When O(rename=true) and O(force=true), renaming is performed even if
- the target of the renaming exists, i.e. the existing contents of the
- file at this location will be lost.
+ - When O(rename=true) and O(force=true), renaming is performed even if the target of the renaming exists, in other words
+ the existing contents of the file at this location will be lost.
- This parameter is ignored when O(rename=false).
type: bool
default: false
requirements:
- dpkg-divert >= 1.15.0 (Debian family)
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Divert /usr/bin/busybox to /usr/bin/busybox.distrib and keep file in place
community.general.dpkg_divert:
path: /usr/bin/busybox
@@ -112,9 +100,9 @@ EXAMPLES = r'''
state: absent
rename: true
force: true
-'''
+"""
-RETURN = r'''
+RETURN = r"""
commands:
description: The dpkg-divert commands ran internally by the module.
type: list
@@ -144,14 +132,8 @@ diversion:
state:
description: The state of the diversion.
type: str
- sample:
- {
- "divert": "/etc/foobarrc.distrib",
- "holder": "LOCAL",
- "path": "/etc/foobarrc",
- "state": "present"
- }
-'''
+ sample: {"divert": "/etc/foobarrc.distrib", "holder": "LOCAL", "path": "/etc/foobarrc", "state": "present"}
+"""
import re
diff --git a/plugins/modules/easy_install.py b/plugins/modules/easy_install.py
index 2e8fc2f4f0..734f0dc4df 100644
--- a/plugins/modules/easy_install.py
+++ b/plugins/modules/easy_install.py
@@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: easy_install
short_description: Installs Python libraries
description:
- - Installs Python libraries, optionally in a C(virtualenv)
+ - Installs Python libraries, optionally in a C(virtualenv).
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -31,31 +30,25 @@ options:
virtualenv:
type: str
description:
- - An optional O(virtualenv) directory path to install into. If the
- O(virtualenv) does not exist, it is created automatically.
+ - An optional O(virtualenv) directory path to install into. If the O(virtualenv) does not exist, it is created automatically.
virtualenv_site_packages:
description:
- - Whether the virtual environment will inherit packages from the
- global site-packages directory. Note that if this setting is
- changed on an already existing virtual environment it will not
- have any effect, the environment must be deleted and newly
- created.
+ - Whether the virtual environment will inherit packages from the global site-packages directory. Note that if this setting
+ is changed on an already existing virtual environment it will not have any effect, the environment must be deleted
+ and newly created.
type: bool
default: false
virtualenv_command:
type: str
description:
- - The command to create the virtual environment with. For example
- V(pyvenv), V(virtualenv), V(virtualenv2).
+ - The command to create the virtual environment with. For example V(pyvenv), V(virtualenv), V(virtualenv2).
default: virtualenv
executable:
type: str
description:
- - The explicit executable or a pathname to the executable to be used to
- run easy_install for a specific version of Python installed in the
- system. For example V(easy_install-3.3), if there are both Python 2.7
- and 3.3 installations in the system and you want to run easy_install
- for the Python 3.3 installation.
+ - The explicit executable or a pathname to the executable to be used to run easy_install for a specific version of Python
+ installed in the system. For example V(easy_install-3.3), if there are both Python 2.7 and 3.3 installations in the
+ system and you want to run easy_install for the Python 3.3 installation.
default: easy_install
state:
type: str
@@ -64,17 +57,14 @@ options:
choices: [present, latest]
default: present
notes:
- - Please note that the C(easy_install) module can only install Python
- libraries. Thus this module is not able to remove libraries. It is
- generally recommended to use the M(ansible.builtin.pip) module which you can first install
- using M(community.general.easy_install).
- - Also note that C(virtualenv) must be installed on the remote host if the
- O(virtualenv) parameter is specified.
-requirements: [ "virtualenv" ]
+ - Please note that the C(easy_install) module can only install Python libraries. Thus this module is not able to remove
+ libraries. It is generally recommended to use the M(ansible.builtin.pip) module which you can first install using M(community.general.easy_install).
+ - Also note that C(virtualenv) must be installed on the remote host if the O(virtualenv) parameter is specified.
+requirements: ["virtualenv"]
author: "Matt Wright (@mattupstate)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install or update pip
community.general.easy_install:
name: pip
@@ -84,7 +74,7 @@ EXAMPLES = '''
community.general.easy_install:
name: bottle
virtualenv: /webapps/myapp/venv
-'''
+"""
import os
import os.path
diff --git a/plugins/modules/ejabberd_user.py b/plugins/modules/ejabberd_user.py
index b43e078a5d..f93612a516 100644
--- a/plugins/modules/ejabberd_user.py
+++ b/plugins/modules/ejabberd_user.py
@@ -9,51 +9,50 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ejabberd_user
author: "Peter Sprygada (@privateip)"
short_description: Manages users for ejabberd servers
requirements:
- - ejabberd with mod_admin_extra
+ - ejabberd with mod_admin_extra
description:
- - This module provides user management for ejabberd servers
+ - This module provides user management for ejabberd servers.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- username:
- type: str
- description:
- - the name of the user to manage
- required: true
- host:
- type: str
- description:
- - the ejabberd host associated with this username
- required: true
- password:
- type: str
- description:
- - the password to assign to the username
- required: false
- state:
- type: str
- description:
- - describe the desired state of the user to be managed
- required: false
- default: 'present'
- choices: [ 'present', 'absent' ]
+ username:
+ type: str
+ description:
+ - The name of the user to manage.
+ required: true
+ host:
+ type: str
+ description:
+ - The ejabberd host associated with this username.
+ required: true
+ password:
+ type: str
+ description:
+ - The password to assign to the username.
+ required: false
+ state:
+ type: str
+ description:
+ - Describe the desired state of the user to be managed.
+ required: false
+ default: 'present'
+ choices: ['present', 'absent']
notes:
- - Password parameter is required for state == present only
- - Passwords must be stored in clear text for this release
- - The ejabberd configuration file must include mod_admin_extra as a module.
-'''
-EXAMPLES = '''
+ - Password parameter is required for O(state=present) only.
+ - Passwords must be stored in clear text for this release.
+ - The ejabberd configuration file must include mod_admin_extra as a module.
+"""
+EXAMPLES = r"""
# Example playbook entries using the ejabberd_user module to manage users state.
- name: Create a user if it does not exist
@@ -67,7 +66,7 @@ EXAMPLES = '''
username: test
host: server
state: absent
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt
diff --git a/plugins/modules/elasticsearch_plugin.py b/plugins/modules/elasticsearch_plugin.py
index 92b628a740..3455691cd0 100644
--- a/plugins/modules/elasticsearch_plugin.py
+++ b/plugins/modules/elasticsearch_plugin.py
@@ -9,88 +9,85 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: elasticsearch_plugin
short_description: Manage Elasticsearch plugins
description:
- - Manages Elasticsearch plugins.
+ - Manages Elasticsearch plugins.
author:
- - Mathew Davies (@ThePixelDeveloper)
- - Sam Doran (@samdoran)
+ - Mathew Davies (@ThePixelDeveloper)
+ - Sam Doran (@samdoran)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of the plugin to install.
- required: true
- type: str
- state:
- description:
- - Desired state of a plugin.
- choices: ["present", "absent"]
- default: present
- type: str
- src:
- description:
- - Optionally set the source location to retrieve the plugin from. This can be a file://
- URL to install from a local file, or a remote URL. If this is not set, the plugin
- location is just based on the name.
- - The name parameter must match the descriptor in the plugin ZIP specified.
- - Is only used if the state would change, which is solely checked based on the name
- parameter. If, for example, the plugin is already installed, changing this has no
- effect.
- - For ES 1.x use url.
- required: false
- type: str
- url:
- description:
- - Set exact URL to download the plugin from (Only works for ES 1.x).
- - For ES 2.x and higher, use src.
- required: false
- type: str
- timeout:
- description:
- - "Timeout setting: 30s, 1m, 1h..."
- - Only valid for Elasticsearch < 5.0. This option is ignored for Elasticsearch > 5.0.
- default: 1m
- type: str
- force:
- description:
- - "Force batch mode when installing plugins. This is only necessary if a plugin requires additional permissions and console detection fails."
- default: false
- type: bool
- plugin_bin:
- description:
- - Location of the plugin binary. If this file is not found, the default plugin binaries will be used.
- type: path
- plugin_dir:
- description:
- - Your configured plugin directory specified in Elasticsearch
- default: /usr/share/elasticsearch/plugins/
- type: path
- proxy_host:
- description:
- - Proxy host to use during plugin installation
- type: str
- proxy_port:
- description:
- - Proxy port to use during plugin installation
- type: str
- version:
- description:
- - Version of the plugin to be installed.
- If plugin exists with previous version, it will NOT be updated
- type: str
-'''
+ name:
+ description:
+ - Name of the plugin to install.
+ required: true
+ type: str
+ state:
+ description:
+ - Desired state of a plugin.
+ choices: ["present", "absent"]
+ default: present
+ type: str
+ src:
+ description:
+ - Optionally set the source location to retrieve the plugin from. This can be a C(file://) URL to install from a local
+ file, or a remote URL. If this is not set, the plugin location is just based on the name.
+ - The name parameter must match the descriptor in the plugin ZIP specified.
+ - Is only used if the state would change, which is solely checked based on the name parameter. If, for example, the
+ plugin is already installed, changing this has no effect.
+ - For ES 1.x use O(url).
+ required: false
+ type: str
+ url:
+ description:
+ - Set exact URL to download the plugin from (Only works for ES 1.x).
+ - For ES 2.x and higher, use src.
+ required: false
+ type: str
+ timeout:
+ description:
+ - 'Timeout setting: V(30s), V(1m), V(1h)...'
+ - Only valid for Elasticsearch < 5.0. This option is ignored for Elasticsearch > 5.0.
+ default: 1m
+ type: str
+ force:
+ description:
+ - Force batch mode when installing plugins. This is only necessary if a plugin requires additional permissions and console
+ detection fails.
+ default: false
+ type: bool
+ plugin_bin:
+ description:
+ - Location of the plugin binary. If this file is not found, the default plugin binaries will be used.
+ type: path
+ plugin_dir:
+ description:
+ - Your configured plugin directory specified in Elasticsearch.
+ default: /usr/share/elasticsearch/plugins/
+ type: path
+ proxy_host:
+ description:
+ - Proxy host to use during plugin installation.
+ type: str
+ proxy_port:
+ description:
+ - Proxy port to use during plugin installation.
+ type: str
+ version:
+ description:
+ - Version of the plugin to be installed. If plugin exists with previous version, it will NOT be updated.
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install Elasticsearch Head plugin in Elasticsearch 2.x
community.general.elasticsearch_plugin:
name: mobz/elasticsearch-head
@@ -116,7 +113,7 @@ EXAMPLES = '''
name: ingest-geoip
state: present
force: true
-'''
+"""
import os
@@ -166,33 +163,38 @@ def parse_error(string):
def install_plugin(module, plugin_bin, plugin_name, version, src, url, proxy_host, proxy_port, timeout, force):
- cmd_args = [plugin_bin, PACKAGE_STATE_MAP["present"]]
+ cmd = [plugin_bin, PACKAGE_STATE_MAP["present"]]
is_old_command = (os.path.basename(plugin_bin) == 'plugin')
# Timeout and version are only valid for plugin, not elasticsearch-plugin
if is_old_command:
if timeout:
- cmd_args.append("--timeout %s" % timeout)
+ cmd.append("--timeout")
+ cmd.append(timeout)
if version:
plugin_name = plugin_name + '/' + version
- cmd_args[2] = plugin_name
+ cmd[2] = plugin_name
if proxy_host and proxy_port:
- cmd_args.append("-DproxyHost=%s -DproxyPort=%s" % (proxy_host, proxy_port))
+ java_opts = ["-Dhttp.proxyHost=%s" % proxy_host,
+ "-Dhttp.proxyPort=%s" % proxy_port,
+ "-Dhttps.proxyHost=%s" % proxy_host,
+ "-Dhttps.proxyPort=%s" % proxy_port]
+ module.run_command_environ_update = dict(CLI_JAVA_OPTS=" ".join(java_opts), # Elasticsearch 8.x
+ ES_JAVA_OPTS=" ".join(java_opts)) # Older Elasticsearch versions
# Legacy ES 1.x
if url:
- cmd_args.append("--url %s" % url)
+ cmd.append("--url")
+ cmd.append(url)
if force:
- cmd_args.append("--batch")
+ cmd.append("--batch")
if src:
- cmd_args.append(src)
+ cmd.append(src)
else:
- cmd_args.append(plugin_name)
-
- cmd = " ".join(cmd_args)
+ cmd.append(plugin_name)
if module.check_mode:
rc, out, err = 0, "check mode", ""
@@ -207,9 +209,7 @@ def install_plugin(module, plugin_bin, plugin_name, version, src, url, proxy_hos
def remove_plugin(module, plugin_bin, plugin_name):
- cmd_args = [plugin_bin, PACKAGE_STATE_MAP["absent"], parse_plugin_repo(plugin_name)]
-
- cmd = " ".join(cmd_args)
+ cmd = [plugin_bin, PACKAGE_STATE_MAP["absent"], parse_plugin_repo(plugin_name)]
if module.check_mode:
rc, out, err = 0, "check mode", ""
diff --git a/plugins/modules/emc_vnx_sg_member.py b/plugins/modules/emc_vnx_sg_member.py
index b06cd01de3..bdb86625d1 100644
--- a/plugins/modules/emc_vnx_sg_member.py
+++ b/plugins/modules/emc_vnx_sg_member.py
@@ -12,52 +12,50 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: emc_vnx_sg_member
short_description: Manage storage group member on EMC VNX
description:
- - "This module manages the members of an existing storage group."
-
+ - This module manages the members of an existing storage group.
extends_documentation_fragment:
- - community.general.emc.emc_vnx
- - community.general.attributes
+ - community.general.emc.emc_vnx
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of the Storage group to manage.
- required: true
- type: str
- lunid:
- description:
- - Lun id to be added.
- required: true
- type: int
- state:
- description:
- - Indicates the desired lunid state.
- - V(present) ensures specified lunid is present in the Storage Group.
- - V(absent) ensures specified lunid is absent from Storage Group.
- default: present
- choices: [ "present", "absent"]
- type: str
+ name:
+ description:
+ - Name of the Storage group to manage.
+ required: true
+ type: str
+ lunid:
+ description:
+ - LUN ID to be added.
+ required: true
+ type: int
+ state:
+ description:
+ - Indicates the desired lunid state.
+ - V(present) ensures specified O(lunid) is present in the Storage Group.
+ - V(absent) ensures specified O(lunid) is absent from Storage Group.
+ default: present
+ choices: ["present", "absent"]
+ type: str
author:
- - Luca 'remix_tj' Lorenzetto (@remixtj)
-'''
+ - Luca 'remix_tj' Lorenzetto (@remixtj)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add lun to storage group
community.general.emc_vnx_sg_member:
name: sg01
@@ -75,14 +73,14 @@ EXAMPLES = '''
sp_password: sysadmin
lunid: 100
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
hluid:
- description: LUNID that hosts attached to the storage group will see.
- type: int
- returned: success
-'''
+ description: LUNID that hosts attached to the storage group will see.
+ type: int
+ returned: success
+"""
import traceback
diff --git a/plugins/modules/etcd3.py b/plugins/modules/etcd3.py
index b1bb181cf4..ce3231d8e0 100644
--- a/plugins/modules/etcd3.py
+++ b/plugins/modules/etcd3.py
@@ -9,84 +9,83 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: etcd3
short_description: Set or delete key value pairs from an etcd3 cluster
requirements:
- etcd3
description:
- - Sets or deletes values in etcd3 cluster using its v3 api.
- - Needs python etcd3 lib to work
+ - Sets or deletes values in etcd3 cluster using its v3 API.
+ - Needs python etcd3 lib to work.
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- key:
- type: str
- description:
- - the key where the information is stored in the cluster
- required: true
- value:
- type: str
- description:
- - the information stored
- required: true
- host:
- type: str
- description:
- - the IP address of the cluster
- default: 'localhost'
- port:
- type: int
- description:
- - the port number used to connect to the cluster
- default: 2379
- state:
- type: str
- description:
- - the state of the value for the key.
- - can be present or absent
- required: true
- choices: [ present, absent ]
- user:
- type: str
- description:
- - The etcd user to authenticate with.
- password:
- type: str
- description:
- - The password to use for authentication.
- - Required if O(user) is defined.
- ca_cert:
- type: path
- description:
- - The Certificate Authority to use to verify the etcd host.
- - Required if O(client_cert) and O(client_key) are defined.
- client_cert:
- type: path
- description:
- - PEM formatted certificate chain file to be used for SSL client authentication.
- - Required if O(client_key) is defined.
- client_key:
- type: path
- description:
- - PEM formatted file that contains your private key to be used for SSL client authentication.
- - Required if O(client_cert) is defined.
- timeout:
- type: int
- description:
- - The socket level timeout in seconds.
+ key:
+ type: str
+ description:
+ - The key where the information is stored in the cluster.
+ required: true
+ value:
+ type: str
+ description:
+ - The information stored.
+ required: true
+ host:
+ type: str
+ description:
+ - The IP address of the cluster.
+ default: 'localhost'
+ port:
+ type: int
+ description:
+ - The port number used to connect to the cluster.
+ default: 2379
+ state:
+ type: str
+ description:
+ - The state of the value for the key.
+ - Can be present or absent.
+ required: true
+ choices: [present, absent]
+ user:
+ type: str
+ description:
+ - The etcd user to authenticate with.
+ password:
+ type: str
+ description:
+ - The password to use for authentication.
+ - Required if O(user) is defined.
+ ca_cert:
+ type: path
+ description:
+ - The Certificate Authority to use to verify the etcd host.
+ - Required if O(client_cert) and O(client_key) are defined.
+ client_cert:
+ type: path
+ description:
+ - PEM formatted certificate chain file to be used for SSL client authentication.
+ - Required if O(client_key) is defined.
+ client_key:
+ type: path
+ description:
+ - PEM formatted file that contains your private key to be used for SSL client authentication.
+ - Required if O(client_cert) is defined.
+ timeout:
+ type: int
+ description:
+ - The socket level timeout in seconds.
author:
- - Jean-Philippe Evrard (@evrardjp)
- - Victor Fauth (@vfauth)
-'''
+ - Jean-Philippe Evrard (@evrardjp)
+ - Victor Fauth (@vfauth)
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Store a value "bar" under the key "foo" for a cluster located "http://localhost:2379"
community.general.etcd3:
key: "foo"
@@ -114,16 +113,16 @@ EXAMPLES = """
client_key: "/etc/ssl/private/key.pem"
"""
-RETURN = '''
+RETURN = r"""
key:
- description: The key that was queried
- returned: always
- type: str
+ description: The key that was queried.
+ returned: always
+ type: str
old_value:
- description: The previous value in the cluster
- returned: always
- type: str
-'''
+ description: The previous value in the cluster.
+ returned: always
+ type: str
+"""
import traceback
diff --git a/plugins/modules/facter.py b/plugins/modules/facter.py
index 87017246ae..ce9320282d 100644
--- a/plugins/modules/facter.py
+++ b/plugins/modules/facter.py
@@ -8,36 +8,38 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: facter
short_description: Runs the discovery program C(facter) on the remote system
description:
- - Runs the C(facter) discovery program
- (U(https://github.com/puppetlabs/facter)) on the remote system, returning
- JSON data that can be useful for inventory purposes.
+ - Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning JSON data
+ that can be useful for inventory purposes.
+deprecated:
+ removed_in: 12.0.0
+ why: The module has been replaced by M(community.general.facter_facts).
+ alternative: Use M(community.general.facter_facts) instead.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- arguments:
- description:
- - Specifies arguments for facter.
- type: list
- elements: str
+ arguments:
+ description:
+ - Specifies arguments for facter.
+ type: list
+ elements: str
requirements:
- - facter
- - ruby-json
+ - facter
+ - ruby-json
author:
- - Ansible Core Team
- - Michael DeHaan
-'''
+ - Ansible Core Team
+ - Michael DeHaan
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Example command-line invocation
# ansible www.example.net -m facter
@@ -47,11 +49,11 @@ EXAMPLES = '''
- name: Execute facter with arguments
community.general.facter:
arguments:
- - -p
- - system_uptime
- - timezone
- - is_virtual
-'''
+ - -p
+ - system_uptime
+ - timezone
+ - is_virtual
+"""
import json
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/facter_facts.py b/plugins/modules/facter_facts.py
index abc3f87ebe..8f73b37644 100644
--- a/plugins/modules/facter_facts.py
+++ b/plugins/modules/facter_facts.py
@@ -9,47 +9,45 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: facter_facts
short_description: Runs the discovery program C(facter) on the remote system and return Ansible facts
version_added: 8.0.0
description:
- - Runs the C(facter) discovery program
- (U(https://github.com/puppetlabs/facter)) on the remote system, returning Ansible facts from the
- JSON data that can be useful for inventory purposes.
+ - Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning Ansible
+ facts from the JSON data that can be useful for inventory purposes.
extends_documentation_fragment:
- - community.general.attributes
- - community.general.attributes.facts
- - community.general.attributes.facts_module
+ - community.general.attributes
+ - community.general.attributes.facts
+ - community.general.attributes.facts_module
options:
- arguments:
- description:
- - Specifies arguments for facter.
- type: list
- elements: str
+ arguments:
+ description:
+ - Specifies arguments for facter.
+ type: list
+ elements: str
requirements:
- - facter
- - ruby-json
+ - facter
+ - ruby-json
author:
- - Ansible Core Team
- - Michael DeHaan
-'''
+ - Ansible Core Team
+ - Michael DeHaan
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Execute facter no arguments
community.general.facter_facts:
- name: Execute facter with arguments
community.general.facter_facts:
arguments:
- - -p
- - system_uptime
- - timezone
- - is_virtual
-'''
+ - -p
+ - system_uptime
+ - timezone
+ - is_virtual
+"""
-RETURN = r'''
+RETURN = r"""
ansible_facts:
description: Dictionary with one key C(facter).
returned: always
@@ -59,7 +57,7 @@ ansible_facts:
description: Dictionary containing facts discovered in the remote system.
returned: always
type: dict
-'''
+"""
import json
diff --git a/plugins/modules/filesize.py b/plugins/modules/filesize.py
index 83de682883..777c00711f 100644
--- a/plugins/modules/filesize.py
+++ b/plugins/modules/filesize.py
@@ -9,17 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: filesize
short_description: Create a file with a given size, or resize it if it exists
description:
- - This module is a simple wrapper around C(dd) to create, extend or truncate
- a file, given its size. It can be used to manage swap files (that require
- contiguous blocks) or alternatively, huge sparse files.
-
+ - This module is a simple wrapper around C(dd) to create, extend or truncate a file, given its size. It can be used to manage
+ swap files (that require contiguous blocks) or alternatively, huge sparse files.
author:
- quidame (@quidame)
@@ -40,36 +37,27 @@ options:
size:
description:
- Requested size of the file.
- - The value is a number (either C(int) or C(float)) optionally followed
- by a multiplicative suffix, that can be one of V(B) (bytes), V(KB) or
- V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB),
- and so on for V(T), V(P), V(E), V(Z) and V(Y); or alternatively one of
- V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB);
+ - The value is a number (either C(int) or C(float)) optionally followed by a multiplicative suffix, that can be one
+ of V(B) (bytes), V(KB) or V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB), and so on for V(T),
+ V(P), V(E), V(Z) and V(Y); or alternatively one of V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB);
V(G), V(g) or V(GiB) (= 1024MiB); and so on.
- - If the multiplicative suffix is not provided, the value is treated as
- an integer number of blocks of O(blocksize) bytes each (float values
- are rounded to the closest integer).
+ - If the multiplicative suffix is not provided, the value is treated as an integer number of blocks of O(blocksize)
+ bytes each (float values are rounded to the closest integer).
- When the O(size) value is equal to the current file size, does nothing.
- - When the O(size) value is bigger than the current file size, bytes from
- O(source) (if O(sparse) is not V(false)) are appended to the file
- without truncating it, in other words, without modifying the existing
- bytes of the file.
- - When the O(size) value is smaller than the current file size, it is
- truncated to the requested value without modifying bytes before this
- value.
- - That means that a file of any arbitrary size can be grown to any other
- arbitrary size, and then resized down to its initial size without
- modifying its initial content.
+ - When the O(size) value is bigger than the current file size, bytes from O(source) (if O(sparse) is not V(false)) are
+ appended to the file without truncating it, in other words, without modifying the existing bytes of the file.
+ - When the O(size) value is smaller than the current file size, it is truncated to the requested value without modifying
+ bytes before this value.
+ - That means that a file of any arbitrary size can be grown to any other arbitrary size, and then resized down to its
+ initial size without modifying its initial content.
type: raw
required: true
blocksize:
description:
- Size of blocks, in bytes if not followed by a multiplicative suffix.
- - The numeric value (before the unit) B(MUST) be an integer (or a C(float)
- if it equals an integer).
- - If not set, the size of blocks is guessed from the OS and commonly
- results in V(512) or V(4096) bytes, that is used internally by the
- module or when O(size) has no unit.
+ - The numeric value (before the unit) B(MUST) be an integer (or a C(float) if it equals an integer).
+ - If not set, the size of blocks is guessed from the OS and commonly results in V(512) or V(4096) bytes, that is used
+ internally by the module or when O(size) has no unit.
type: raw
source:
description:
@@ -79,26 +67,22 @@ options:
default: /dev/zero
force:
description:
- - Whether or not to overwrite the file if it exists, in other words, to
- truncate it from 0. When V(true), the module is not idempotent, that
- means it always reports C(changed=true).
+ - Whether or not to overwrite the file if it exists, in other words, to truncate it from 0. When V(true), the module
+ is not idempotent, that means it always reports C(changed=true).
- O(force=true) and O(sparse=true) are mutually exclusive.
type: bool
default: false
sparse:
description:
- Whether or not the file to create should be a sparse file.
- - This option is effective only on newly created files, or when growing a
- file, only for the bytes to append.
+ - This option is effective only on newly created files, or when growing a file, only for the bytes to append.
- This option is not supported on OSes or filesystems not supporting sparse files.
- O(force=true) and O(sparse=true) are mutually exclusive.
type: bool
default: false
unsafe_writes:
description:
- - This option is silently ignored. This module always modifies file
- size in-place.
-
+ - This option is silently ignored. This module always modifies file size in-place.
requirements:
- dd (Data Duplicator) in PATH
@@ -138,9 +122,9 @@ seealso:
- name: busybox(1) manpage for Linux
description: Manual page of the GNU/Linux's busybox, that provides its own dd implementation.
link: https://www.unix.com/man-page/linux/1/busybox
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a file of 1G filled with null bytes
community.general.filesize:
path: /var/bigfile
@@ -183,9 +167,9 @@ EXAMPLES = r'''
mode: u=rw,go=
owner: root
group: root
-'''
+"""
-RETURN = r'''
+RETURN = r"""
cmd:
description: Command executed to create or resize the file.
type: str
@@ -229,7 +213,7 @@ path:
type: str
sample: /var/swap0
returned: always
-'''
+"""
import re
diff --git a/plugins/modules/filesystem.py b/plugins/modules/filesystem.py
index 73e8c79c6a..2edc8be5ab 100644
--- a/plugins/modules/filesystem.py
+++ b/plugins/modules/filesystem.py
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
author:
- Alexander Bulimov (@abulimov)
- quidame (@quidame)
@@ -29,33 +28,29 @@ attributes:
options:
state:
description:
- - If O(state=present), the filesystem is created if it doesn't already
- exist, that is the default behaviour if O(state) is omitted.
- - If O(state=absent), filesystem signatures on O(dev) are wiped if it
- contains a filesystem (as known by C(blkid)).
- - When O(state=absent), all other options but O(dev) are ignored, and the
- module does not fail if the device O(dev) doesn't actually exist.
+ - If O(state=present), the filesystem is created if it does not already exist, that is the default behaviour if O(state)
+ is omitted.
+ - If O(state=absent), filesystem signatures on O(dev) are wiped if it contains a filesystem (as known by C(blkid)).
+ - When O(state=absent), all other options but O(dev) are ignored, and the module does not fail if the device O(dev)
+ does not actually exist.
type: str
- choices: [ present, absent ]
+ choices: [present, absent]
default: present
version_added: 1.3.0
fstype:
- choices: [ bcachefs, btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs ]
+ choices: [bcachefs, btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs]
description:
- - Filesystem type to be created. This option is required with
- O(state=present) (or if O(state) is omitted).
- - ufs support has been added in community.general 3.4.0.
- - bcachefs support has been added in community.general 8.6.0.
+ - Filesystem type to be created. This option is required with O(state=present) (or if O(state) is omitted).
+ - Ufs support has been added in community.general 3.4.0.
+ - Bcachefs support has been added in community.general 8.6.0.
type: str
aliases: [type]
dev:
description:
- - Target path to block device (Linux) or character device (FreeBSD) or
- regular file (both).
- - When setting Linux-specific filesystem types on FreeBSD, this module
- only works when applying to regular files, aka disk images.
- - Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support
- a regular file as their target O(dev).
+ - Target path to block device (Linux) or character device (FreeBSD) or regular file (both).
+ - When setting Linux-specific filesystem types on FreeBSD, this module only works when applying to regular files, aka
+ disk images.
+ - Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support a regular file as their target O(dev).
- Support for character devices on FreeBSD has been added in community.general 3.4.0.
type: path
required: true
@@ -68,12 +63,11 @@ options:
resizefs:
description:
- If V(true), if the block device and filesystem size differ, grow the filesystem into the space.
- - Supported for C(bcachefs), C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat) filesystems.
- Attempts to resize other filesystem types will fail.
- - XFS Will only grow if mounted. Currently, the module is based on commands
- from C(util-linux) package to perform operations, so resizing of XFS is
- not supported on FreeBSD systems.
- - vFAT will likely fail if C(fatresize < 1.04).
+ - Supported for C(bcachefs), C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat)
+ filesystems. Attempts to resize other filesystem types will fail.
+ - XFS Will only grow if mounted. Currently, the module is based on commands from C(util-linux) package to perform operations,
+ so resizing of XFS is not supported on FreeBSD systems.
+ - VFAT will likely fail if C(fatresize < 1.04).
- Mutually exclusive with O(uuid).
type: bool
default: false
@@ -93,32 +87,28 @@ options:
type: str
version_added: 7.1.0
requirements:
- - Uses specific tools related to the O(fstype) for creating or resizing a
- filesystem (from packages e2fsprogs, xfsprogs, dosfstools, and so on).
- - Uses generic tools mostly related to the Operating System (Linux or
- FreeBSD) or available on both, as C(blkid).
+ - Uses specific tools related to the O(fstype) for creating or resizing a filesystem (from packages e2fsprogs, xfsprogs,
+ dosfstools, and so on).
+ - Uses generic tools mostly related to the Operating System (Linux or FreeBSD) or available on both, as C(blkid).
- On FreeBSD, either C(util-linux) or C(e2fsprogs) package is required.
notes:
- - Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid)
- is unable to detect a filesystem (and in case C(fstyp) on FreeBSD is also
- unable to detect a filesystem), this filesystem is overwritten even if
- O(force) is V(false).
- - On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide
- a C(blkid) command that is compatible with this module. However, these
- packages conflict with each other, and only the C(util-linux) package
- provides the command required to not fail when O(state=absent).
+ - Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid) is unable to detect a filesystem (and in
+ case C(fstyp) on FreeBSD is also unable to detect a filesystem), this filesystem is overwritten even if O(force) is V(false).
+ - On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide a C(blkid) command that is compatible with this
+ module. However, these packages conflict with each other, and only the C(util-linux) package provides the command required
+ to not fail when O(state=absent).
seealso:
- module: community.general.filesize
- module: ansible.posix.mount
- name: xfs_admin(8) manpage for Linux
- description: Manual page of the GNU/Linux's xfs_admin implementation
+ description: Manual page of the GNU/Linux's xfs_admin implementation.
link: https://man7.org/linux/man-pages/man8/xfs_admin.8.html
- name: tune2fs(8) manpage for Linux
- description: Manual page of the GNU/Linux's tune2fs implementation
+ description: Manual page of the GNU/Linux's tune2fs implementation.
link: https://man7.org/linux/man-pages/man8/tune2fs.8.html
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a ext2 filesystem on /dev/sdb1
community.general.filesystem:
fstype: ext2
@@ -157,7 +147,7 @@ EXAMPLES = '''
fstype: lvm
dev: /dev/sdc
uuid: random
-'''
+"""
import os
import platform
diff --git a/plugins/modules/flatpak.py b/plugins/modules/flatpak.py
index 09e49e5575..13898c3349 100644
--- a/plugins/modules/flatpak.py
+++ b/plugins/modules/flatpak.py
@@ -10,8 +10,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: flatpak
short_description: Manage flatpaks
description:
@@ -34,66 +33,60 @@ attributes:
options:
executable:
description:
- - The path to the C(flatpak) executable to use.
- - By default, this module looks for the C(flatpak) executable on the path.
+ - The path to the C(flatpak) executable to use.
+ - By default, this module looks for the C(flatpak) executable on the path.
type: path
default: flatpak
method:
description:
- - The installation method to use.
- - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system)
- or only for the current V(user).
+ - The installation method to use.
+ - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) or only for the current V(user).
type: str
- choices: [ system, user ]
+ choices: [system, user]
default: system
name:
description:
- - The name of the flatpak to manage. To operate on several packages this
- can accept a list of packages.
- - When used with O(state=present), O(name) can be specified as a URL to a
- C(flatpakref) file or the unique reverse DNS name that identifies a flatpak.
- - Both C(https://) and C(http://) URLs are supported.
- - When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote
- to look for the flatpak. An example for a reverse DNS name is C(org.gnome.gedit).
- - When used with O(state=absent) or O(state=latest), it is recommended to specify the name in
- the reverse DNS format.
- - When supplying a URL with O(state=absent) or O(state=latest), the module will try to match the
- installed flatpak based on the name of the flatpakref to remove or update it. However, there
- is no guarantee that the names of the flatpakref file and the reverse DNS name of the
- installed flatpak do match.
+ - The name of the flatpak to manage. To operate on several packages this can accept a list of packages.
+ - When used with O(state=present), O(name) can be specified as a URL to a C(flatpakref) file or the unique reverse DNS
+ name that identifies a flatpak.
+ - Both C(https://) and C(http://) URLs are supported.
+ - When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote to look for the flatpak.
+ An example for a reverse DNS name is C(org.gnome.gedit).
+ - When used with O(state=absent) or O(state=latest), it is recommended to specify the name in the reverse DNS format.
+ - When supplying a URL with O(state=absent) or O(state=latest), the module will try to match the installed flatpak based
+ on the name of the flatpakref to remove or update it. However, there is no guarantee that the names of the flatpakref
+ file and the reverse DNS name of the installed flatpak do match.
type: list
elements: str
required: true
no_dependencies:
description:
- - If installing runtime dependencies should be omitted or not
- - This parameter is primarily implemented for integration testing this module.
- There might however be some use cases where you would want to have this, like when you are
- packaging your own flatpaks.
+ - If installing runtime dependencies should be omitted or not.
+ - This parameter is primarily implemented for integration testing this module. There might however be some use cases
+ where you would want to have this, like when you are packaging your own flatpaks.
type: bool
default: false
version_added: 3.2.0
remote:
description:
- - The flatpak remote (repository) to install the flatpak from.
- - By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before
- you can use this.
- - See the M(community.general.flatpak_remote) module for managing flatpak remotes.
+ - The flatpak remote (repository) to install the flatpak from.
+ - By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before you can use this.
+ - See the M(community.general.flatpak_remote) module for managing flatpak remotes.
type: str
default: flathub
state:
description:
- - Indicates the desired package state.
- - The value V(latest) is supported since community.general 8.6.0.
- choices: [ absent, present, latest ]
+ - Indicates the desired package state.
+ - The value V(latest) is supported since community.general 8.6.0.
+ choices: [absent, present, latest]
type: str
default: present
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Install the spotify flatpak
community.general.flatpak:
- name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref
+ name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref
state: present
- name: Install the gedit flatpak package without dependencies (not recommended)
@@ -123,7 +116,7 @@ EXAMPLES = r'''
- name: Update the spotify flatpak
community.general.flatpak:
- name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref
+ name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref
state: latest
- name: Update the gedit flatpak package without dependencies (not recommended)
@@ -164,35 +157,35 @@ EXAMPLES = r'''
- org.inkscape.Inkscape
- org.mozilla.firefox
state: absent
-'''
+"""
-RETURN = r'''
+RETURN = r"""
command:
- description: The exact flatpak command that was executed
+ description: The exact flatpak command that was executed.
returned: When a flatpak command has been executed
type: str
sample: "/usr/bin/flatpak install --user --nontinteractive flathub org.gnome.Calculator"
msg:
- description: Module error message
+ description: Module error message.
returned: failure
type: str
sample: "Executable '/usr/local/bin/flatpak' was not found on the system."
rc:
- description: Return code from flatpak binary
+ description: Return code from flatpak binary.
returned: When a flatpak command has been executed
type: int
sample: 0
stderr:
- description: Error output from flatpak binary
+ description: Error output from flatpak binary.
returned: When a flatpak command has been executed
type: str
sample: "error: Error searching remote flathub: Can't find ref org.gnome.KDE"
stdout:
- description: Output from flatpak binary
+ description: Output from flatpak binary.
returned: When a flatpak command has been executed
type: str
sample: "org.gnome.Calendar/x86_64/stable\tcurrent\norg.gnome.gitg/x86_64/stable\tcurrent\n"
-'''
+"""
from ansible.module_utils.six.moves.urllib.parse import urlparse
from ansible.module_utils.basic import AnsibleModule
@@ -419,6 +412,8 @@ def main():
if not binary:
module.fail_json(msg="Executable '%s' was not found on the system." % executable, **result)
+ module.run_command_environ_update = dict(LANGUAGE='C', LC_ALL='C')
+
installed, not_installed = flatpak_exists(module, binary, name, method)
if state == 'absent' and installed:
uninstall_flat(module, binary, installed, method)
diff --git a/plugins/modules/flatpak_remote.py b/plugins/modules/flatpak_remote.py
index a4eb3ea27c..ba202d3033 100644
--- a/plugins/modules/flatpak_remote.py
+++ b/plugins/modules/flatpak_remote.py
@@ -10,15 +10,13 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: flatpak_remote
short_description: Manage flatpak repository remotes
description:
- Allows users to add or remove flatpak remotes.
- - The flatpak remotes concept is comparable to what is called repositories in other packaging
- formats.
- - Currently, remote addition is only supported via C(flatpakrepo) file URLs.
+ - The flatpak remotes concept is comparable to what is called repositories in other packaging formats.
+ - Currently, remote addition is only supported using C(flatpakrepo) file URLs.
- Existing remotes will not be updated.
- See the M(community.general.flatpak) module for managing flatpaks.
author:
@@ -36,49 +34,47 @@ attributes:
options:
executable:
description:
- - The path to the C(flatpak) executable to use.
- - By default, this module looks for the C(flatpak) executable on the path.
+ - The path to the C(flatpak) executable to use.
+ - By default, this module looks for the C(flatpak) executable on the path.
type: str
default: flatpak
flatpakrepo_url:
description:
- - The URL to the C(flatpakrepo) file representing the repository remote to add.
- - When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url)
- is added using the specified installation O(method).
- - When used with O(state=absent), this is not required.
- - Required when O(state=present).
+ - The URL to the C(flatpakrepo) file representing the repository remote to add.
+ - When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url) is added using the specified
+ installation O(method).
+ - When used with O(state=absent), this is not required.
+ - Required when O(state=present).
type: str
method:
description:
- - The installation method to use.
- - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system)
- or only for the current V(user).
+ - The installation method to use.
+ - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) or only for the current V(user).
type: str
- choices: [ system, user ]
+ choices: [system, user]
default: system
name:
description:
- - The desired name for the flatpak remote to be registered under on the managed host.
- - When used with O(state=present), the remote will be added to the managed host under
- the specified O(name).
- - When used with O(state=absent) the remote with that name will be removed.
+ - The desired name for the flatpak remote to be registered under on the managed host.
+ - When used with O(state=present), the remote will be added to the managed host under the specified O(name).
+ - When used with O(state=absent) the remote with that name will be removed.
type: str
required: true
state:
description:
- - Indicates the desired package state.
+ - Indicates the desired package state.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
enabled:
description:
- - Indicates whether this remote is enabled.
+ - Indicates whether this remote is enabled.
type: bool
default: true
version_added: 6.4.0
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Add the Gnome flatpak remote to the system installation
community.general.flatpak_remote:
name: gnome
@@ -108,35 +104,35 @@ EXAMPLES = r'''
name: flathub
state: present
enabled: false
-'''
+"""
-RETURN = r'''
+RETURN = r"""
command:
- description: The exact flatpak command that was executed
+ description: The exact flatpak command that was executed.
returned: When a flatpak command has been executed
type: str
sample: "/usr/bin/flatpak remote-add --system flatpak-test https://dl.flathub.org/repo/flathub.flatpakrepo"
msg:
- description: Module error message
+ description: Module error message.
returned: failure
type: str
sample: "Executable '/usr/local/bin/flatpak' was not found on the system."
rc:
- description: Return code from flatpak binary
+ description: Return code from flatpak binary.
returned: When a flatpak command has been executed
type: int
sample: 0
stderr:
- description: Error output from flatpak binary
+ description: Error output from flatpak binary.
returned: When a flatpak command has been executed
type: str
sample: "error: GPG verification enabled, but no summary found (check that the configured URL in remote config is correct)\n"
stdout:
- description: Output from flatpak binary
+ description: Output from flatpak binary.
returned: When a flatpak command has been executed
type: str
sample: "flathub\tFlathub\thttps://dl.flathub.org/repo/\t1\t\n"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_bytes, to_native
diff --git a/plugins/modules/gandi_livedns.py b/plugins/modules/gandi_livedns.py
index ad2e96fd15..e90483a49d 100644
--- a/plugins/modules/gandi_livedns.py
+++ b/plugins/modules/gandi_livedns.py
@@ -8,15 +8,14 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: gandi_livedns
author:
- Gregory Thiemonge (@gthiemonge)
version_added: "2.3.0"
short_description: Manage Gandi LiveDNS records
description:
- - "Manages DNS records by the Gandi LiveDNS API, see the docs: U(https://doc.livedns.gandi.net/)."
+ - 'Manages DNS records by the Gandi LiveDNS API, see the docs: U(https://doc.livedns.gandi.net/).'
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -27,32 +26,31 @@ attributes:
options:
personal_access_token:
description:
- - Scoped API token.
- - One of O(personal_access_token) and O(api_key) must be specified.
+ - Scoped API token.
+ - One of O(personal_access_token) and O(api_key) must be specified.
type: str
version_added: 9.0.0
api_key:
description:
- - Account API token.
- - Note that these type of keys are deprecated and might stop working at some point.
- Use personal access tokens instead.
- - One of O(personal_access_token) and O(api_key) must be specified.
+ - Account API token.
+ - Note that these type of keys are deprecated and might stop working at some point. Use personal access tokens instead.
+ - One of O(personal_access_token) and O(api_key) must be specified.
type: str
record:
description:
- - Record to add.
+ - Record to add.
type: str
required: true
state:
description:
- - Whether the record(s) should exist or not.
+ - Whether the record(s) should exist or not.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
ttl:
description:
- - The TTL to give the new record.
- - Required when O(state=present).
+ - The TTL to give the new record.
+ - Required when O(state=present).
type: int
type:
description:
@@ -61,25 +59,25 @@ options:
required: true
values:
description:
- - The record values.
- - Required when O(state=present).
+ - The record values.
+ - Required when O(state=present).
type: list
elements: str
domain:
description:
- - The name of the Domain to work with (for example, "example.com").
+ - The name of the Domain to work with (for example, V(example.com)).
required: true
type: str
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a test A record to point to 127.0.0.1 in the my.com domain
community.general.gandi_livedns:
domain: my.com
record: test
type: A
values:
- - 127.0.0.1
+ - 127.0.0.1
ttl: 7200
personal_access_token: dummytoken
register: record
@@ -90,7 +88,7 @@ EXAMPLES = r'''
type: CNAME
record: mail
values:
- - www
+ - www
ttl: 7200
personal_access_token: dummytoken
state: present
@@ -101,7 +99,7 @@ EXAMPLES = r'''
type: CNAME
record: mail
values:
- - www
+ - www
ttl: 10800
personal_access_token: dummytoken
state: present
@@ -120,46 +118,46 @@ EXAMPLES = r'''
record: test
type: A
values:
- - 127.0.0.1
+ - 127.0.0.1
ttl: 7200
api_key: dummyapikey
-'''
+"""
-RETURN = r'''
+RETURN = r"""
record:
- description: A dictionary containing the record data.
- returned: success, except on record deletion
- type: dict
- contains:
- values:
- description: The record content (details depend on record type).
- returned: success
- type: list
- elements: str
- sample:
- - 192.0.2.91
- - 192.0.2.92
- record:
- description: The record name.
- returned: success
- type: str
- sample: www
- ttl:
- description: The time-to-live for the record.
- returned: success
- type: int
- sample: 300
- type:
- description: The record type.
- returned: success
- type: str
- sample: A
- domain:
- description: The domain associated with the record.
- returned: success
- type: str
- sample: my.com
-'''
+ description: A dictionary containing the record data.
+ returned: success, except on record deletion
+ type: dict
+ contains:
+ values:
+ description: The record content (details depend on record type).
+ returned: success
+ type: list
+ elements: str
+ sample:
+ - 192.0.2.91
+ - 192.0.2.92
+ record:
+ description: The record name.
+ returned: success
+ type: str
+ sample: www
+ ttl:
+ description: The time-to-live for the record.
+ returned: success
+ type: int
+ sample: 300
+ type:
+ description: The record type.
+ returned: success
+ type: str
+ sample: A
+ domain:
+ description: The domain associated with the record.
+ returned: success
+ type: str
+ sample: my.com
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/gconftool2.py b/plugins/modules/gconftool2.py
index 1759665294..86e878ed61 100644
--- a/plugins/modules/gconftool2.py
+++ b/plugins/modules/gconftool2.py
@@ -9,21 +9,21 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: gconftool2
author:
-- Kenneth D. Evensen (@kevensen)
+ - Kenneth D. Evensen (@kevensen)
short_description: Edit GNOME Configurations
description:
-- This module allows for the manipulation of GNOME 2 Configuration via gconftool-2. Please see the gconftool-2(1) man pages for more details.
+ - This module allows for the manipulation of GNOME 2 Configuration using C(gconftool-2). Please see the gconftool-2(1) man
+ pages for more details.
seealso:
-- name: C(gconftool-2) command manual page
- description: Manual page for the command.
- link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
+ - name: C(gconftool-2) command manual page
+ description: Manual page for the command.
+ link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
extends_documentation_fragment:
-- community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -33,36 +33,37 @@ options:
key:
type: str
description:
- - A GConf preference key is an element in the GConf repository that corresponds to an application preference.
+ - A GConf preference key is an element in the GConf repository that corresponds to an application preference.
required: true
value:
type: str
description:
- - Preference keys typically have simple values such as strings, integers, or lists of strings and integers. This is ignored unless O(state=present).
+ - Preference keys typically have simple values such as strings, integers, or lists of strings and integers. This is
+ ignored unless O(state=present).
value_type:
type: str
description:
- - The type of value being set. This is ignored unless O(state=present).
+ - The type of value being set. This is ignored unless O(state=present).
choices: [bool, float, int, string]
state:
type: str
description:
- - The action to take upon the key/value.
+ - The action to take upon the key/value.
required: true
choices: [absent, present]
config_source:
type: str
description:
- - Specify a configuration source to use rather than the default path.
+ - Specify a configuration source to use rather than the default path.
direct:
description:
- - Access the config database directly, bypassing server. If O(direct) is specified then the O(config_source) must be specified as well.
+ - Access the config database directly, bypassing server. If O(direct) is specified then the O(config_source) must be
+ specified as well.
type: bool
default: false
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Change the widget font to "Serif 12"
community.general.gconftool2:
key: "/desktop/gnome/interface/font_name"
@@ -70,8 +71,7 @@ EXAMPLES = """
value: "Serif 12"
"""
-RETURN = """
----
+RETURN = r"""
key:
description: The key specified in the module parameters.
returned: success
@@ -84,15 +84,15 @@ value_type:
sample: string
value:
description:
- - The value of the preference key after executing the module or V(null) if key is removed.
- - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
+ - The value of the preference key after executing the module or V(null) if key is removed.
+ - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"
previous_value:
description:
- - The value of the preference key before executing the module.
- - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
+ - The value of the preference key before executing the module.
+ - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"
diff --git a/plugins/modules/gconftool2_info.py b/plugins/modules/gconftool2_info.py
index 6fb274e038..29965be46b 100644
--- a/plugins/modules/gconftool2_info.py
+++ b/plugins/modules/gconftool2_info.py
@@ -7,46 +7,43 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: gconftool2_info
author:
-- "Alexei Znamensky (@russoz)"
+ - "Alexei Znamensky (@russoz)"
short_description: Retrieve GConf configurations
version_added: 5.1.0
description:
-- This module allows retrieving application preferences from the GConf database, with the help of C(gconftool-2).
+ - This module allows retrieving application preferences from the GConf database, with the help of C(gconftool-2).
extends_documentation_fragment:
-- community.general.attributes
-- community.general.attributes.info_module
+ - community.general.attributes
+ - community.general.attributes.info_module
options:
key:
description:
- - The key name for an element in the GConf database.
+ - The key name for an element in the GConf database.
type: str
required: true
seealso:
-- name: C(gconftool-2) command manual page
- description: Manual page for the command.
- link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
-- name: gconf repository (archived)
- description: Git repository for the project. It is an archived project, so the repository is read-only.
- link: https://gitlab.gnome.org/Archive/gconf
+ - name: C(gconftool-2) command manual page
+ description: Manual page for the command.
+ link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
+ - name: gconf repository (archived)
+ description: Git repository for the project. It is an archived project, so the repository is read-only.
+ link: https://gitlab.gnome.org/Archive/gconf
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Get value for a certain key in the database.
community.general.gconftool2_info:
key: /desktop/gnome/background/picture_filename
register: result
"""
-RETURN = """
----
+RETURN = r"""
value:
description:
- - The value of the property.
+ - The value of the property.
returned: success
type: str
sample: Monospace 10
diff --git a/plugins/modules/gem.py b/plugins/modules/gem.py
index f51e3350da..c01433cb90 100644
--- a/plugins/modules/gem.py
+++ b/plugins/modules/gem.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: gem
short_description: Manage Ruby gems
description:
@@ -49,38 +48,37 @@ options:
repository:
type: str
description:
- - The repository from which the gem will be installed
+ - The repository from which the gem will be installed.
required: false
aliases: [source]
user_install:
description:
- - Install gem in user's local gems cache or for all users
+ - Install gem in user's local gems cache or for all users.
required: false
type: bool
default: true
executable:
type: path
description:
- - Override the path to the gem executable
+ - Override the path to the gem executable.
required: false
install_dir:
type: path
description:
- - Install the gems into a specific directory.
- These gems will be independent from the global installed ones.
- Specifying this requires user_install to be false.
+ - Install the gems into a specific directory. These gems will be independent from the global installed ones. Specifying
+ this requires user_install to be false.
required: false
bindir:
type: path
description:
- - Install executables into a specific directory.
+ - Install executables into a specific directory.
version_added: 3.3.0
norc:
type: bool
default: true
description:
- - Avoid loading any C(.gemrc) file. Ignored for RubyGems prior to 2.5.2.
- - The default changed from V(false) to V(true) in community.general 6.0.0.
+ - Avoid loading any C(.gemrc) file. Ignored for RubyGems prior to 2.5.2.
+ - The default changed from V(false) to V(true) in community.general 6.0.0.
version_added: 3.3.0
env_shebang:
description:
@@ -108,7 +106,7 @@ options:
build_flags:
type: str
description:
- - Allow adding build flags for gem compilation
+ - Allow adding build flags for gem compilation.
required: false
force:
description:
@@ -117,11 +115,11 @@ options:
default: false
type: bool
author:
- - "Ansible Core Team"
- - "Johan Wiren (@johanwiren)"
-'''
+ - "Ansible Core Team"
+ - "Johan Wiren (@johanwiren)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install version 1.0 of vagrant
community.general.gem:
name: vagrant
@@ -138,7 +136,7 @@ EXAMPLES = '''
name: rake
gem_source: /path/to/gems/rake-1.0.gem
state: present
-'''
+"""
import re
diff --git a/plugins/modules/gio_mime.py b/plugins/modules/gio_mime.py
index 587aaec427..216b7faae0 100644
--- a/plugins/modules/gio_mime.py
+++ b/plugins/modules/gio_mime.py
@@ -7,17 +7,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: gio_mime
author:
-- "Alexei Znamensky (@russoz)"
+ - "Alexei Znamensky (@russoz)"
short_description: Set default handler for MIME type, for applications using Gnome GIO
version_added: 7.5.0
description:
-- This module allows configuring the default handler for a specific MIME type, to be used by applications built with th Gnome GIO API.
+ - This module allows configuring the default handler for a specific MIME type, to be used by applications built with the
+ Gnome GIO API.
extends_documentation_fragment:
-- community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -26,28 +26,27 @@ attributes:
options:
mime_type:
description:
- - MIME type for which a default handler will be set.
+ - MIME type for which a default handler will be set.
type: str
required: true
handler:
description:
- - Default handler will be set for the MIME type.
+ - Default handler will be set for the MIME type.
type: str
required: true
notes:
-- This module is a thin wrapper around the C(gio mime) command (and subcommand).
-- See man gio(1) for more details.
+ - This module is a thin wrapper around the C(gio mime) command (and subcommand).
+ - See man gio(1) for more details.
seealso:
-- name: C(gio) command manual page
- description: Manual page for the command.
- link: https://man.archlinux.org/man/gio.1
-- name: GIO Documentation
- description: Reference documentation for the GIO API..
- link: https://docs.gtk.org/gio/
+ - name: C(gio) command manual page
+ description: Manual page for the command.
+ link: https://man.archlinux.org/man/gio.1
+ - name: GIO Documentation
+ description: Reference documentation for the GIO API..
+ link: https://docs.gtk.org/gio/
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Set chrome as the default handler for https
community.general.gio_mime:
mime_type: x-scheme-handler/https
@@ -55,23 +54,22 @@ EXAMPLES = """
register: result
"""
-RETURN = """
----
+RETURN = r"""
handler:
description:
- - The handler set as default.
+ - The handler set as default.
returned: success
type: str
sample: google-chrome.desktop
stdout:
description:
- - The output of the C(gio) command.
+ - The output of the C(gio) command.
returned: success
type: str
sample: Set google-chrome.desktop as the default for x-scheme-handler/https
stderr:
description:
- - The error output of the C(gio) command.
+ - The error output of the C(gio) command.
returned: failure
type: str
sample: 'gio: Failed to load info for handler "never-existed.desktop"'
@@ -108,12 +106,11 @@ class GioMime(ModuleHelper):
def __run__(self):
check_mode_return = (0, 'Module executed in check mode', '')
if self.vars.has_changed:
- with self.runner.context(args_order=["mime_type", "handler"], check_mode_skip=True, check_mode_return=check_mode_return) as ctx:
+ with self.runner.context(args_order="mime mime_type handler", check_mode_skip=True, check_mode_return=check_mode_return) as ctx:
rc, out, err = ctx.run()
self.vars.stdout = out
self.vars.stderr = err
- if self.verbosity >= 4:
- self.vars.run_info = ctx.run_info
+ self.vars.set("run_info", ctx.run_info, verbosity=4)
def main():
diff --git a/plugins/modules/git_config.py b/plugins/modules/git_config.py
index 95969c1b38..6a6eff0be2 100644
--- a/plugins/modules/git_config.py
+++ b/plugins/modules/git_config.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: git_config
author:
- Matthew Gamble (@djmattyg007)
@@ -20,11 +19,10 @@ author:
requirements: ['git']
short_description: Update git configuration
description:
- - The M(community.general.git_config) module changes git configuration by invoking C(git config).
- This is needed if you do not want to use M(ansible.builtin.template) for the entire git
- config file (for example because you need to change just C(user.email) in
- /etc/.git/config). Solutions involving M(ansible.builtin.command) are cumbersome or
- do not work correctly in check mode.
+ - The M(community.general.git_config) module changes git configuration by invoking C(git config). This is needed if you
+ do not want to use M(ansible.builtin.template) for the entire git config file (for example because you need to change
+ just C(user.email) in C(/etc/.git/config)). Solutions involving M(ansible.builtin.command) are cumbersome or do not work
+ correctly in check mode.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -36,19 +34,17 @@ options:
list_all:
description:
- List all settings (optionally limited to a given O(scope)).
- - This option is B(deprecated) and will be removed from community.general 11.0.0.
- Please use M(community.general.git_config_info) instead.
+ - This option is B(deprecated) and will be removed from community.general 11.0.0. Please use M(community.general.git_config_info)
+ instead.
type: bool
default: false
name:
description:
- - The name of the setting. If no value is supplied, the value will
- be read from the config if it has been set.
+ - The name of the setting. If no value is supplied, the value will be read from the config if it has been set.
type: str
repo:
description:
- - Path to a git repository for reading and writing values from a
- specific repo.
+ - Path to a git repository for reading and writing values from a specific repo.
type: path
file:
description:
@@ -62,36 +58,34 @@ options:
- If this is set to V(local), you must also specify the O(repo) parameter.
- If this is set to V(file), you must also specify the O(file) parameter.
- It defaults to system only when not using O(list_all=true).
- choices: [ "file", "local", "global", "system" ]
+ choices: ["file", "local", "global", "system"]
type: str
state:
description:
- - "Indicates the setting should be set/unset.
- This parameter has higher precedence than O(value) parameter:
- when O(state=absent) and O(value) is defined, O(value) is discarded."
- choices: [ 'present', 'absent' ]
+ - 'Indicates the setting should be set/unset. This parameter has higher precedence than O(value) parameter: when O(state=absent)
+ and O(value) is defined, O(value) is discarded.'
+ choices: ['present', 'absent']
default: 'present'
type: str
value:
description:
- - When specifying the name of a single setting, supply a value to
- set that setting to the given value.
- - From community.general 11.0.0 on, O(value) will be required if O(state=present).
- To read values, use the M(community.general.git_config_info) module instead.
+ - When specifying the name of a single setting, supply a value to set that setting to the given value.
+ - From community.general 11.0.0 on, O(value) will be required if O(state=present). To read values, use the M(community.general.git_config_info)
+ module instead.
type: str
add_mode:
description:
- - Specify if a value should replace the existing value(s) or if the new
- value should be added alongside other values with the same name.
- - This option is only relevant when adding/replacing values. If O(state=absent) or
- values are just read out, this option is not considered.
- choices: [ "add", "replace-all" ]
+ - Specify if a value should replace the existing value(s) or if the new value should be added alongside other values
+ with the same name.
+ - This option is only relevant when adding/replacing values. If O(state=absent) or values are just read out, this option
+ is not considered.
+ choices: ["add", "replace-all"]
type: str
default: "replace-all"
version_added: 8.1.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add a setting to ~/.gitconfig
community.general.git_config:
name: alias.ci
@@ -147,18 +141,17 @@ EXAMPLES = '''
repo: /etc
scope: local
value: 'root@{{ ansible_fqdn }}'
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
config_value:
- description: When O(list_all=false) and value is not set, a string containing the value of the setting in name
+ description: When O(list_all=false) and value is not set, a string containing the value of the setting in name.
returned: success
type: str
sample: "vim"
config_values:
- description: When O(list_all=true), a dict containing key/value pairs of multiple configuration settings
+ description: When O(list_all=true), a dict containing key/value pairs of multiple configuration settings.
returned: success
type: dict
sample:
@@ -166,7 +159,7 @@ config_values:
color.ui: "auto"
alias.diffc: "diff --cached"
alias.remotev: "remote -v"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/git_config_info.py b/plugins/modules/git_config_info.py
index 147201fff3..c8152cfa42 100644
--- a/plugins/modules/git_config_info.py
+++ b/plugins/modules/git_config_info.py
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: git_config_info
author:
- Guenther Grill (@guenhter)
@@ -19,8 +18,7 @@ version_added: 8.1.0
requirements: ['git']
short_description: Read git configuration
description:
- - The M(community.general.git_config_info) module reads the git configuration
- by invoking C(git config).
+ - The M(community.general.git_config_info) module reads the git configuration by invoking C(git config).
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.info_module
@@ -44,12 +42,12 @@ options:
- If set to V(system), the system git config is used. O(path) is ignored.
- If set to V(local), O(path) must be set to the repo to read from.
- If set to V(file), O(path) must be set to the config file to read from.
- choices: [ "global", "system", "local", "file" ]
+ choices: ["global", "system", "local", "file"]
default: "system"
type: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Read a system wide config
community.general.git_config_info:
name: core.editor
@@ -81,14 +79,13 @@ EXAMPLES = '''
community.general.git_config_info:
scope: file
path: /etc/gitconfig
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
config_value:
- description: >
- When O(name) is set, a string containing the value of the setting in name. If O(name) is not set, empty.
- If a config key such as V(push.pushoption) has more then one entry, just the first one is returned here.
+ description: >-
+ When O(name) is set, a string containing the value of the setting in name. If O(name) is not set, empty. If a config key
+ such as V(push.pushoption) has more then one entry, just the first one is returned here.
returned: success if O(name) is set
type: str
sample: "vim"
@@ -97,8 +94,8 @@ config_values:
description:
- This is a dictionary mapping a git configuration setting to a list of its values.
- When O(name) is not set, all configuration settings are returned here.
- - When O(name) is set, only the setting specified in O(name) is returned here.
- If that setting is not set, the key will still be present, and its value will be an empty list.
+ - When O(name) is set, only the setting specified in O(name) is returned here. If that setting is not set, the key will
+ still be present, and its value will be an empty list.
returned: success
type: dict
sample:
@@ -106,7 +103,7 @@ config_values:
color.ui: ["auto"]
push.pushoption: ["merge_request.create", "merge_request.draft"]
alias.remotev: ["remote -v"]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/github_deploy_key.py b/plugins/modules/github_deploy_key.py
index ae90e04c91..509a67c491 100644
--- a/plugins/modules/github_deploy_key.py
+++ b/plugins/modules/github_deploy_key.py
@@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: github_deploy_key
author: "Ali (@bincyber)"
short_description: Manages deploy keys for GitHub repositories
description:
- - "Adds or removes deploy keys for GitHub repositories. Supports authentication using username and password,
- username and password and 2-factor authentication code (OTP), OAuth2 token, or personal access token. Admin
- rights on the repository are required."
+ - Adds or removes deploy keys for GitHub repositories. Supports authentication using username and password, username and
+ password and 2-factor authentication code (OTP), OAuth2 token, or personal access token. Admin rights on the repository
+ are required.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -28,7 +27,7 @@ attributes:
options:
github_url:
description:
- - The base URL of the GitHub API
+ - The base URL of the GitHub API.
required: false
type: str
version_added: '0.2.0'
@@ -37,19 +36,19 @@ options:
description:
- The name of the individual account or organization that owns the GitHub repository.
required: true
- aliases: [ 'account', 'organization' ]
+ aliases: ['account', 'organization']
type: str
repo:
description:
- The name of the GitHub repository.
required: true
- aliases: [ 'repository' ]
+ aliases: ['repository']
type: str
name:
description:
- The name for the deploy key.
required: true
- aliases: [ 'title', 'label' ]
+ aliases: ['title', 'label']
type: str
key:
description:
@@ -58,14 +57,15 @@ options:
type: str
read_only:
description:
- - If V(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write.
+ - If V(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to
+ read and write.
type: bool
default: true
state:
description:
- The state of the deploy key.
default: "present"
- choices: [ "present", "absent" ]
+ choices: ["present", "absent"]
type: str
force:
description:
@@ -74,11 +74,12 @@ options:
default: false
username:
description:
- - The username to authenticate with. Should not be set when using personal access token
+ - The username to authenticate with. Should not be set when using personal access token.
type: str
password:
description:
- - The password to authenticate with. Alternatively, a personal access token can be used instead of O(username) and O(password) combination.
+ - The password to authenticate with. Alternatively, a personal access token can be used instead of O(username) and O(password)
+ combination.
type: str
token:
description:
@@ -89,10 +90,10 @@ options:
- The 6 digit One Time Password for 2-Factor Authentication. Required together with O(username) and O(password).
type: int
notes:
- - "Refer to GitHub's API documentation here: https://developer.github.com/v3/repos/keys/."
-'''
+ - "Refer to GitHub's API documentation here: https://developer.github.com/v3/repos/keys/."
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add a new read-only deploy key to a GitHub repository using basic authentication
community.general.github_deploy_key:
owner: "johndoe"
@@ -152,33 +153,33 @@ EXAMPLES = '''
read_only: true
username: "janedoe"
password: "supersecretpassword"
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: the status message describing what occurred
- returned: always
- type: str
- sample: "Deploy key added successfully"
+ description: The status message describing what occurred.
+ returned: always
+ type: str
+ sample: "Deploy key added successfully"
http_status_code:
- description: the HTTP status code returned by the GitHub API
- returned: failed
- type: int
- sample: 400
+ description: The HTTP status code returned by the GitHub API.
+ returned: failed
+ type: int
+ sample: 400
error:
- description: the error message returned by the GitHub API
- returned: failed
- type: str
- sample: "key is already in use"
+ description: The error message returned by the GitHub API.
+ returned: failed
+ type: str
+ sample: "key is already in use"
id:
- description: the key identifier assigned by GitHub for the deploy key
- returned: changed
- type: int
- sample: 24381901
-'''
+ description: The key identifier assigned by GitHub for the deploy key.
+ returned: changed
+ type: int
+ sample: 24381901
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url
diff --git a/plugins/modules/github_issue.py b/plugins/modules/github_issue.py
index 4e10e9f925..86e81d38ef 100644
--- a/plugins/modules/github_issue.py
+++ b/plugins/modules/github_issue.py
@@ -10,7 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: github_issue
short_description: View GitHub issue
description:
@@ -40,24 +40,24 @@ options:
type: int
action:
description:
- - Get various details about issue depending upon action specified.
+ - Get various details about issue depending upon action specified.
default: 'get_status'
choices:
- - 'get_status'
+ - get_status
type: str
author:
- - Abhijeet Kasurde (@Akasurde)
-'''
+ - Abhijeet Kasurde (@Akasurde)
+"""
-RETURN = '''
+RETURN = r"""
issue_status:
- description: State of the GitHub issue
- type: str
- returned: success
- sample: open, closed
-'''
+ description: State of the GitHub issue.
+ type: str
+ returned: success
+ sample: open, closed
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Check if GitHub issue is closed or not
community.general.github_issue:
organization: ansible
@@ -70,7 +70,7 @@ EXAMPLES = '''
ansible.builtin.debug:
msg: Do something when issue 23642 is open
when: r.issue_status == 'open'
-'''
+"""
import json
diff --git a/plugins/modules/github_key.py b/plugins/modules/github_key.py
index a74ead9848..f3d5863d54 100644
--- a/plugins/modules/github_key.py
+++ b/plugins/modules/github_key.py
@@ -9,7 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: github_key
short_description: Manage GitHub access keys
description:
@@ -29,7 +29,7 @@ options:
type: str
name:
description:
- - SSH key name
+ - SSH key name.
required: true
type: str
pubkey:
@@ -44,34 +44,36 @@ options:
type: str
force:
description:
- - The default is V(true), which will replace the existing remote key
- if it is different than O(pubkey). If V(false), the key will only be
- set if no key with the given O(name) exists.
+ - The default is V(true), which will replace the existing remote key if it is different than O(pubkey). If V(false),
+ the key will only be set if no key with the given O(name) exists.
type: bool
default: true
author: Robert Estelle (@erydo)
-'''
+"""
-RETURN = '''
+RETURN = r"""
deleted_keys:
- description: An array of key objects that were deleted. Only present on state=absent
- type: list
- returned: When state=absent
- sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': false}]
+ description: An array of key objects that were deleted. Only present on state=absent.
+ type: list
+ returned: When state=absent
+ sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ',
+ 'read_only': false}]
matching_keys:
- description: An array of keys matching the specified name. Only present on state=present
- type: list
- returned: When state=present
- sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': false}]
+ description: An array of keys matching the specified name. Only present on state=present.
+ type: list
+ returned: When state=present
+ sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ',
+ 'read_only': false}]
key:
- description: Metadata about the key just created. Only present on state=present
- type: dict
- returned: success
- sample: {'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': false}
-'''
+ description: Metadata about the key just created. Only present on state=present.
+ type: dict
+ returned: success
+ sample: {'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ',
+ 'read_only': false}
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Read SSH public key to authorize
ansible.builtin.shell: cat /home/foo/.ssh/id_rsa.pub
register: ssh_pub_key
@@ -89,7 +91,7 @@ EXAMPLES = '''
name: Access Key for Some Machine
token: '{{ github_access_token }}'
pubkey: "{{ lookup('ansible.builtin.file', '/home/foo/.ssh/id_rsa.pub') }}"
-'''
+"""
import datetime
import json
@@ -162,7 +164,7 @@ def create_key(session, name, pubkey, check_mode):
'key': pubkey,
'title': name,
'url': 'http://example.com/CHECK_MODE_GITHUB_KEY',
- 'created_at': datetime.strftime(now_t, '%Y-%m-%dT%H:%M:%SZ'),
+ 'created_at': datetime.datetime.strftime(now_t, '%Y-%m-%dT%H:%M:%SZ'),
'read_only': False,
'verified': False
}
diff --git a/plugins/modules/github_release.py b/plugins/modules/github_release.py
index d8ee155b81..1376bf4f3d 100644
--- a/plugins/modules/github_release.py
+++ b/plugins/modules/github_release.py
@@ -9,78 +9,77 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: github_release
short_description: Interact with GitHub Releases
description:
- - Fetch metadata about GitHub Releases
+ - Fetch metadata about GitHub Releases.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- token:
- description:
- - GitHub Personal Access Token for authenticating. Mutually exclusive with O(password).
- type: str
- user:
- description:
- - The GitHub account that owns the repository
- type: str
- required: true
- password:
- description:
- - The GitHub account password for the user. Mutually exclusive with O(token).
- type: str
- repo:
- description:
- - Repository name
- type: str
- required: true
- action:
- description:
- - Action to perform
- type: str
- required: true
- choices: [ 'latest_release', 'create_release' ]
- tag:
- description:
- - Tag name when creating a release. Required when using O(action=create_release).
- type: str
- target:
- description:
- - Target of release when creating a release
- type: str
- name:
- description:
- - Name of release when creating a release
- type: str
- body:
- description:
- - Description of the release when creating a release
- type: str
- draft:
- description:
- - Sets if the release is a draft or not. (boolean)
- type: bool
- default: false
- prerelease:
- description:
- - Sets if the release is a prerelease or not. (boolean)
- type: bool
- default: false
+ token:
+ description:
+ - GitHub Personal Access Token for authenticating. Mutually exclusive with O(password).
+ type: str
+ user:
+ description:
+ - The GitHub account that owns the repository.
+ type: str
+ required: true
+ password:
+ description:
+ - The GitHub account password for the user. Mutually exclusive with O(token).
+ type: str
+ repo:
+ description:
+ - Repository name.
+ type: str
+ required: true
+ action:
+ description:
+ - Action to perform.
+ type: str
+ required: true
+ choices: ['latest_release', 'create_release']
+ tag:
+ description:
+ - Tag name when creating a release. Required when using O(action=create_release).
+ type: str
+ target:
+ description:
+ - Target of release when creating a release.
+ type: str
+ name:
+ description:
+ - Name of release when creating a release.
+ type: str
+ body:
+ description:
+ - Description of the release when creating a release.
+ type: str
+ draft:
+ description:
+ - Sets if the release is a draft or not. (boolean).
+ type: bool
+ default: false
+ prerelease:
+ description:
+ - Sets if the release is a prerelease or not. (boolean).
+ type: bool
+ default: false
author:
- - "Adrian Moisey (@adrianmoisey)"
+ - "Adrian Moisey (@adrianmoisey)"
requirements:
- - "github3.py >= 1.0.0a3"
-'''
+ - "github3.py >= 1.0.0a3"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get latest release of a public repository
community.general.github_release:
user: ansible
@@ -111,16 +110,15 @@ EXAMPLES = '''
target: master
name: My Release
body: Some description
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
tag:
- description: Version of the created/latest release.
- type: str
- returned: success
- sample: 1.1.0
-'''
+ description: Version of the created/latest release.
+ type: str
+ returned: success
+ sample: 1.1.0
+"""
import traceback
diff --git a/plugins/modules/github_repo.py b/plugins/modules/github_repo.py
index f02ad30ac3..2d2c6f8588 100644
--- a/plugins/modules/github_repo.py
+++ b/plugins/modules/github_repo.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: github_repo
short_description: Manage your repositories on Github
version_added: 2.2.0
@@ -26,81 +25,82 @@ attributes:
options:
username:
description:
- - Username used for authentication.
- - This is only needed when not using O(access_token).
+ - Username used for authentication.
+ - This is only needed when not using O(access_token).
type: str
required: false
password:
description:
- - Password used for authentication.
- - This is only needed when not using O(access_token).
+ - Password used for authentication.
+ - This is only needed when not using O(access_token).
type: str
required: false
access_token:
description:
- - Token parameter for authentication.
- - This is only needed when not using O(username) and O(password).
+ - Token parameter for authentication.
+ - This is only needed when not using O(username) and O(password).
type: str
required: false
name:
description:
- - Repository name.
+ - Repository name.
type: str
required: true
description:
description:
- - Description for the repository.
- - Defaults to empty if O(force_defaults=true), which is the default in this module.
- - Defaults to empty if O(force_defaults=false) when creating a new repository.
- - This is only used when O(state) is V(present).
+ - Description for the repository.
+ - Defaults to empty if O(force_defaults=true), which is the default in this module.
+ - Defaults to empty if O(force_defaults=false) when creating a new repository.
+ - This is only used when O(state) is V(present).
type: str
required: false
private:
description:
- - Whether the repository should be private or not.
- - Defaults to V(false) if O(force_defaults=true), which is the default in this module.
- - Defaults to V(false) if O(force_defaults=false) when creating a new repository.
- - This is only used when O(state=present).
+ - Whether the repository should be private or not.
+ - Defaults to V(false) if O(force_defaults=true), which is the default in this module.
+ - Defaults to V(false) if O(force_defaults=false) when creating a new repository.
+ - This is only used when O(state=present).
type: bool
required: false
state:
description:
- - Whether the repository should exist or not.
+ - Whether the repository should exist or not.
type: str
default: present
- choices: [ absent, present ]
+ choices: [absent, present]
required: false
organization:
description:
- - Organization for the repository.
- - When O(state=present), the repository will be created in the current user profile.
+ - Organization for the repository.
+ - When O(state=present), the repository will be created in the current user profile.
type: str
required: false
api_url:
description:
- - URL to the GitHub API if not using github.com but you own instance.
+ - URL to the GitHub API if not using github.com but you own instance.
type: str
default: 'https://api.github.com'
version_added: "3.5.0"
force_defaults:
description:
- - Overwrite current O(description) and O(private) attributes with defaults if set to V(true), which currently is the default.
- - The default for this option will be deprecated in a future version of this collection, and eventually change to V(false).
+ - Overwrite current O(description) and O(private) attributes with defaults if set to V(true), which currently is the
+ default.
+ - The default for this option will be deprecated in a future version of this collection, and eventually change to V(false).
type: bool
default: true
required: false
version_added: 4.1.0
requirements:
-- PyGithub>=1.54
+ - PyGithub>=1.54
notes:
-- For Python 3, PyGithub>=1.54 should be used.
-- "For Python 3.5, PyGithub==1.54 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-54-november-30-2020)."
-- "For Python 2.7, PyGithub==1.45 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-45-december-29-2019)."
+ - For Python 3, PyGithub>=1.54 should be used.
+ - 'For Python 3.5, PyGithub==1.54 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-54-november-30-2020).'
+ - 'For Python 2.7, PyGithub==1.45 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-45-december-29-2019).'
author:
-- Álvaro Torres Cogollo (@atorrescogollo)
-'''
+ - Álvaro Torres Cogollo (@atorrescogollo)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a Github repository
community.general.github_repo:
access_token: mytoken
@@ -120,14 +120,14 @@ EXAMPLES = '''
name: myrepo
state: absent
register: result
-'''
+"""
-RETURN = '''
+RETURN = r"""
repo:
description: Repository information as JSON. See U(https://docs.github.com/en/rest/reference/repos#get-a-repository).
returned: success and O(state=present)
type: dict
-'''
+"""
import traceback
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
diff --git a/plugins/modules/github_webhook.py b/plugins/modules/github_webhook.py
index 11b115750b..8608c90bc9 100644
--- a/plugins/modules/github_webhook.py
+++ b/plugins/modules/github_webhook.py
@@ -8,12 +8,11 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: github_webhook
short_description: Manage GitHub webhooks
description:
- - "Create and delete GitHub webhooks"
+ - Create and delete GitHub webhooks.
requirements:
- "PyGithub >= 1.3.5"
extends_documentation_fragment:
@@ -26,22 +25,22 @@ attributes:
options:
repository:
description:
- - Full name of the repository to configure a hook for
+ - Full name of the repository to configure a hook for.
type: str
required: true
aliases:
- repo
url:
description:
- - URL to which payloads will be delivered
+ - URL to which payloads will be delivered.
type: str
required: true
content_type:
description:
- - The media type used to serialize the payloads
+ - The media type used to serialize the payloads.
type: str
required: false
- choices: [ form, json ]
+ choices: [form, json]
default: form
secret:
description:
@@ -50,61 +49,57 @@ options:
required: false
insecure_ssl:
description:
- - >
- Flag to indicate that GitHub should skip SSL verification when calling
- the hook.
+ - Flag to indicate that GitHub should skip SSL verification when calling the hook.
required: false
type: bool
default: false
events:
description:
- - >
- A list of GitHub events the hook is triggered for. Events are listed at
- U(https://developer.github.com/v3/activity/events/types/). Required
- unless O(state=absent)
+ - A list of GitHub events the hook is triggered for. Events are listed at U(https://developer.github.com/v3/activity/events/types/).
+ Required unless O(state=absent).
required: false
type: list
elements: str
active:
description:
- - Whether or not the hook is active
+ - Whether or not the hook is active.
required: false
type: bool
default: true
state:
description:
- - Whether the hook should be present or absent
+ - Whether the hook should be present or absent.
type: str
required: false
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
user:
description:
- - User to authenticate to GitHub as
+ - User to authenticate to GitHub as.
type: str
required: true
password:
description:
- - Password to authenticate to GitHub with
+ - Password to authenticate to GitHub with.
type: str
required: false
token:
description:
- - Token to authenticate to GitHub with
+ - Token to authenticate to GitHub with.
type: str
required: false
github_url:
description:
- - Base URL of the GitHub API
+ - Base URL of the GitHub API.
type: str
required: false
default: https://api.github.com
author:
- "Chris St. Pierre (@stpierre)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a new webhook that triggers on push (password auth)
community.general.github_webhook:
repository: ansible/ansible
@@ -135,16 +130,15 @@ EXAMPLES = '''
state: absent
user: "{{ github_user }}"
password: "{{ github_password }}"
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
hook_id:
- description: The GitHub ID of the hook created/updated
+ description: The GitHub ID of the hook created/updated.
returned: when state is 'present'
type: int
sample: 6206
-'''
+"""
import traceback
diff --git a/plugins/modules/github_webhook_info.py b/plugins/modules/github_webhook_info.py
index dcad02a369..440a373f1d 100644
--- a/plugins/modules/github_webhook_info.py
+++ b/plugins/modules/github_webhook_info.py
@@ -8,12 +8,11 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: github_webhook_info
short_description: Query information about GitHub webhooks
description:
- - "Query information about GitHub webhooks"
+ - Query information about GitHub webhooks.
requirements:
- "PyGithub >= 1.3.5"
extends_documentation_fragment:
@@ -22,38 +21,38 @@ extends_documentation_fragment:
options:
repository:
description:
- - Full name of the repository to configure a hook for
+ - Full name of the repository to configure a hook for.
type: str
required: true
aliases:
- repo
user:
description:
- - User to authenticate to GitHub as
+ - User to authenticate to GitHub as.
type: str
required: true
password:
description:
- - Password to authenticate to GitHub with
+ - Password to authenticate to GitHub with.
type: str
required: false
token:
description:
- - Token to authenticate to GitHub with
+ - Token to authenticate to GitHub with.
type: str
required: false
github_url:
description:
- - Base URL of the github api
+ - Base URL of the GitHub API.
type: str
required: false
default: https://api.github.com
author:
- "Chris St. Pierre (@stpierre)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List hooks for a repository (password auth)
community.general.github_webhook_info:
repository: ansible/ansible
@@ -68,12 +67,11 @@ EXAMPLES = '''
token: "{{ github_user_api_token }}"
github_url: https://github.example.com/api/v3/
register: myrepo_webhooks
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
hooks:
- description: A list of hooks that exist for the repo
+ description: A list of hooks that exist for the repo.
returned: always
type: list
elements: dict
@@ -88,7 +86,7 @@ hooks:
"id": 6206,
"last_response": {"status": "active", "message": "OK", "code": 200}
}
-'''
+"""
import traceback
diff --git a/plugins/modules/gitlab_branch.py b/plugins/modules/gitlab_branch.py
index 623c25644e..b32169ef5a 100644
--- a/plugins/modules/gitlab_branch.py
+++ b/plugins/modules/gitlab_branch.py
@@ -7,7 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: gitlab_branch
short_description: Create or delete a branch
version_added: 4.2.0
@@ -50,10 +50,10 @@ options:
- Reference branch to create from.
- This must be specified if O(state=present).
type: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create branch branch2 from main
community.general.gitlab_branch:
api_url: https://gitlab.com
@@ -70,11 +70,10 @@ EXAMPLES = '''
project: "group1/project1"
branch: branch2
state: absent
+"""
-'''
-
-RETURN = '''
-'''
+RETURN = r"""
+"""
import traceback
diff --git a/plugins/modules/gitlab_deploy_key.py b/plugins/modules/gitlab_deploy_key.py
index ab89520248..f5ae130324 100644
--- a/plugins/modules/gitlab_deploy_key.py
+++ b/plugins/modules/gitlab_deploy_key.py
@@ -11,11 +11,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: gitlab_deploy_key
short_description: Manages GitLab project deploy keys
description:
- - Adds, updates and removes project deploy keys
+ - Adds, updates and removes project deploy keys.
author:
- Marcus Watkins (@marwatk)
- Guillaume Martinez (@Lunik)
@@ -35,7 +35,7 @@ attributes:
options:
project:
description:
- - Id or Full path of project in the form of group/name.
+ - ID or Full path of project in the form of group/name.
required: true
type: str
title:
@@ -45,7 +45,7 @@ options:
type: str
key:
description:
- - Deploy key
+ - Deploy key.
required: true
type: str
can_push:
@@ -55,14 +55,14 @@ options:
default: false
state:
description:
- - When V(present) the deploy key added to the project if it doesn't exist.
+ - When V(present) the deploy key added to the project if it does not exist.
- When V(absent) it will be removed from the project if it exists.
default: present
type: str
- choices: [ "present", "absent" ]
-'''
+ choices: ["present", "absent"]
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: "Adding a project deploy key"
community.general.gitlab_deploy_key:
api_url: https://gitlab.example.com/
@@ -88,32 +88,31 @@ EXAMPLES = '''
project: "my_group/my_project"
state: absent
key: "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9w..."
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
msg:
- description: Success or failure message
+ description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
- description: json parsed response from the server
+ description: JSON-parsed response from the server.
returned: always
type: dict
error:
- description: the error message returned by the GitLab API
+ description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: key is already in use"
deploy_key:
- description: API object
+ description: API object.
returned: always
type: dict
-'''
+"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/gitlab_group.py b/plugins/modules/gitlab_group.py
index f8db33360c..6d03476092 100644
--- a/plugins/modules/gitlab_group.py
+++ b/plugins/modules/gitlab_group.py
@@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: gitlab_group
short_description: Creates/updates/deletes GitLab Groups
description:
@@ -97,12 +96,12 @@ options:
type: str
parent:
description:
- - Allow to create subgroups
- - Id or Full path of parent group in the form of group/name
+ - Allow to create subgroups.
+ - ID or Full path of parent group in the form of group/name.
type: str
path:
description:
- - The path of the group you want to create, this will be api_url/group_path
+ - The path of the group you want to create, this will be api_url/group_path.
- If not supplied, the group_name will be used.
type: str
prevent_forking_outside_group:
@@ -146,7 +145,7 @@ options:
version_added: 3.7.0
state:
description:
- - create or delete group.
+ - Create or delete group.
- Possible values are present and absent.
default: present
type: str
@@ -164,7 +163,7 @@ options:
version_added: 9.5.0
visibility:
description:
- - Default visibility of the group
+ - Default visibility of the group.
choices: ["private", "internal", "public"]
default: private
type: str
@@ -176,9 +175,9 @@ options:
choices: ["enabled", "private", "disabled"]
type: str
version_added: 9.5.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: "Delete GitLab Group"
community.general.gitlab_group:
api_url: https://gitlab.example.com/
@@ -221,31 +220,31 @@ EXAMPLES = '''
project_creation_level: noone
auto_devops_enabled: false
subgroup_creation_level: maintainer
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Success or failure message
+ description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
- description: json parsed response from the server
+ description: JSON-parsed response from the server.
returned: always
type: dict
error:
- description: the error message returned by the GitLab API
+ description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
group:
- description: API object
+ description: API object.
returned: always
type: dict
-'''
+"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/gitlab_group_access_token.py b/plugins/modules/gitlab_group_access_token.py
index 1db7414081..bcf75e056b 100644
--- a/plugins/modules/gitlab_group_access_token.py
+++ b/plugins/modules/gitlab_group_access_token.py
@@ -12,7 +12,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: gitlab_group_access_token
short_description: Manages GitLab group access tokens
version_added: 8.4.0
@@ -27,11 +27,10 @@ extends_documentation_fragment:
- community.general.gitlab
- community.general.attributes
notes:
- - Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated.
- Whether tokens will be recreated is controlled by the O(recreate) option, which defaults to V(never).
+ - Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated. Whether tokens
+ will be recreated is controlled by the O(recreate) option, which defaults to V(never).
- Token string is contained in the result only when access token is created or recreated. It can not be fetched afterwards.
- Token matching is done by comparing O(name) option.
-
attributes:
check_mode:
support: full
@@ -56,7 +55,8 @@ options:
type: list
elements: str
aliases: ["scope"]
- choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner", "ai_features", "k8s_proxy"]
+ choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner",
+ "ai_features", "k8s_proxy"]
access_level:
description:
- Access level of the access token.
@@ -84,10 +84,10 @@ options:
- When V(absent) it will be removed from the group if it exists.
default: present
type: str
- choices: [ "present", "absent" ]
-'''
+ choices: ["present", "absent"]
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: "Creating a group access token"
community.general.gitlab_group_access_token:
api_url: https://gitlab.example.com/
@@ -131,16 +131,16 @@ EXAMPLES = r'''
- write_repository
recreate: state_change
state: present
-'''
+"""
-RETURN = r'''
+RETURN = r"""
access_token:
description:
- API object.
- Only contains the value of the token if the token was created or recreated.
returned: success and O(state=present)
type: dict
-'''
+"""
from datetime import datetime
diff --git a/plugins/modules/gitlab_group_members.py b/plugins/modules/gitlab_group_members.py
index ca82891e30..86e9e6474a 100644
--- a/plugins/modules/gitlab_group_members.py
+++ b/plugins/modules/gitlab_group_members.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: gitlab_group_members
short_description: Manage group members on GitLab Server
description:
@@ -81,16 +80,16 @@ options:
type: str
purge_users:
description:
- - Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list.
- If omitted do not purge orphaned members.
+ - Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list. If omitted
+ do not purge orphaned members.
- Is only used when O(state=present).
type: list
elements: str
choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
version_added: 3.6.0
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Add a user to a GitLab Group
community.general.gitlab_group_members:
api_url: 'https://gitlab.example.com'
@@ -152,9 +151,9 @@ EXAMPLES = r'''
- name: user2
access_level: maintainer
state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/gitlab_group_variable.py b/plugins/modules/gitlab_group_variable.py
index 32e5aaa904..926f4fe20a 100644
--- a/plugins/modules/gitlab_group_variable.py
+++ b/plugins/modules/gitlab_group_variable.py
@@ -9,15 +9,15 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: gitlab_group_variable
short_description: Creates, updates, or deletes GitLab groups variables
version_added: 1.2.0
description:
- Creates a group variable if it does not exist.
- When a group variable does exist, its value will be updated when the values are different.
- - Variables which are untouched in the playbook, but are not untouched in the GitLab group,
- they stay untouched (O(purge=false)) or will be deleted (O(purge=true)).
+ - Variables which are untouched in the playbook, but are not untouched in the GitLab group, they stay untouched (O(purge=false))
+ or will be deleted (O(purge=true)).
author:
- Florent Madiot (@scodeman)
requirements:
@@ -53,8 +53,8 @@ options:
vars:
description:
- When the list element is a simple key-value pair, masked, raw and protected will be set to false.
- - When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can
- have full control about whether a value should be masked, raw, protected or both.
+ - When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can have full
+ control about whether a value should be masked, raw, protected or both.
- Support for group variables requires GitLab >= 9.5.
- Support for environment_scope requires GitLab Premium >= 13.11.
- Support for protected values requires GitLab >= 9.3.
@@ -62,8 +62,8 @@ options:
- Support for raw values requires GitLab >= 15.7.
- A C(value) must be a string or a number.
- Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file).
- - When a value is masked, it must be in Base64 and have a length of at least 8 characters.
- See GitLab documentation on acceptable values for a masked variable (U(https://docs.gitlab.com/ce/ci/variables/#masked-variables)).
+ - When a value is masked, it must be in Base64 and have a length of at least 8 characters. See GitLab documentation
+ on acceptable values for a masked variable (U(https://docs.gitlab.com/ce/ci/variables/#masked-variables)).
default: {}
type: dict
variables:
@@ -106,17 +106,17 @@ options:
description:
- Whether a variable is an environment variable (V(env_var)) or a file (V(file)).
type: str
- choices: [ "env_var", "file" ]
+ choices: ["env_var", "file"]
default: env_var
environment_scope:
description:
- The scope for the variable.
type: str
default: '*'
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Set or update some CI/CD variables
community.general.gitlab_group_variable:
api_url: https://gitlab.com
@@ -173,9 +173,9 @@ EXAMPLES = r'''
state: absent
vars:
ACCESS_KEY_ID: abc123
-'''
+"""
-RETURN = r'''
+RETURN = r"""
group_variable:
description: Four lists of the variablenames which were added, updated, removed or exist.
returned: always
@@ -201,7 +201,7 @@ group_variable:
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec
diff --git a/plugins/modules/gitlab_hook.py b/plugins/modules/gitlab_hook.py
index 58781d182b..cb132c8aaa 100644
--- a/plugins/modules/gitlab_hook.py
+++ b/plugins/modules/gitlab_hook.py
@@ -11,12 +11,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: gitlab_hook
short_description: Manages GitLab project hooks
description:
- - Adds, updates and removes project hook
+ - Adds, updates and removes project hook.
author:
- Marcus Watkins (@marwatk)
- Guillaume Martinez (@Lunik)
@@ -36,21 +35,21 @@ attributes:
options:
project:
description:
- - Id or Full path of the project in the form of group/name.
+ - ID or Full path of the project in the form of group/name.
required: true
type: str
hook_url:
description:
- - The url that you want GitLab to post to, this is used as the primary key for updates and deletion.
+ - The URL that you want GitLab to post to, this is used as the primary key for updates and deletion.
required: true
type: str
state:
description:
- - When V(present) the hook will be updated to match the input or created if it doesn't exist.
+ - When V(present) the hook will be updated to match the input or created if it does not exist.
- When V(absent) hook will be deleted if it exists.
default: present
type: str
- choices: [ "present", "absent" ]
+ choices: ["present", "absent"]
push_events:
description:
- Trigger hook on push events.
@@ -58,7 +57,7 @@ options:
default: true
push_events_branch_filter:
description:
- - Branch name of wildcard to trigger hook on push events
+ - Branch name of wildcard to trigger hook on push events.
type: str
version_added: '0.2.0'
default: ''
@@ -107,7 +106,7 @@ options:
- Whether GitLab will do SSL verification when triggering the hook.
type: bool
default: false
- aliases: [ enable_ssl_verification ]
+ aliases: [enable_ssl_verification]
token:
description:
- Secret token to validate hook messages at the receiver.
@@ -115,9 +114,9 @@ options:
- Will show up in the X-GitLab-Token HTTP request header.
required: false
type: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: "Adding a project hook"
community.general.gitlab_hook:
api_url: https://gitlab.example.com/
@@ -144,31 +143,31 @@ EXAMPLES = '''
project: 10
hook_url: "https://my-ci-server.example.com/gitlab-hook"
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Success or failure message
+ description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
- description: json parsed response from the server
+ description: JSON parsed response from the server.
returned: always
type: dict
error:
- description: the error message returned by the GitLab API
+ description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
hook:
- description: API object
+ description: API object.
returned: always
type: dict
-'''
+"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/gitlab_instance_variable.py b/plugins/modules/gitlab_instance_variable.py
index cc2d812ca3..2023b0ad7d 100644
--- a/plugins/modules/gitlab_instance_variable.py
+++ b/plugins/modules/gitlab_instance_variable.py
@@ -10,7 +10,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: gitlab_instance_variable
short_description: Creates, updates, or deletes GitLab instance variables
version_added: 7.1.0
@@ -18,8 +18,8 @@ description:
- Creates a instance variable if it does not exist.
- When a instance variable does exist, its value will be updated if the values are different.
- Support for instance variables requires GitLab >= 13.0.
- - Variables which are not mentioned in the modules options, but are present on the GitLab instance,
- will either stay (O(purge=false)) or will be deleted (O(purge=true)).
+ - Variables which are not mentioned in the modules options, but are present on the GitLab instance, will either stay (O(purge=false))
+ or will be deleted (O(purge=true)).
author:
- Benedikt Braunger (@benibr)
requirements:
@@ -74,16 +74,23 @@ options:
- Whether variable value is protected or not.
type: bool
default: false
+ raw:
+ description:
+ - Whether variable value is raw or not.
+ - Support for raw values requires GitLab >= 15.7.
+ type: bool
+ default: false
+ version_added: 10.2.0
variable_type:
description:
- Whether a variable is an environment variable (V(env_var)) or a file (V(file)).
type: str
- choices: [ "env_var", "file" ]
+ choices: ["env_var", "file"]
default: env_var
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Set or update some CI/CD variables
community.general.gitlab_instance_variable:
api_url: https://gitlab.com
@@ -105,9 +112,9 @@ EXAMPLES = r'''
state: absent
variables:
- name: ACCESS_KEY_ID
-'''
+"""
-RETURN = r'''
+RETURN = r"""
instance_variable:
description: Four lists of the variablenames which were added, updated, removed or exist.
returned: always
@@ -133,7 +140,7 @@ instance_variable:
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec
@@ -160,6 +167,7 @@ class GitlabInstanceVariables(object):
"value": var_obj.get('value'),
"masked": var_obj.get('masked'),
"protected": var_obj.get('protected'),
+ "raw": var_obj.get('raw'),
"variable_type": var_obj.get('variable_type'),
}
@@ -227,6 +235,8 @@ def native_python_main(this_gitlab, purge, requested_variables, state, module):
item['protected'] = False
if item.get('masked') is None:
item['masked'] = False
+ if item.get('raw') is None:
+ item['raw'] = False
if item.get('variable_type') is None:
item['variable_type'] = 'env_var'
@@ -297,6 +307,7 @@ def main():
value=dict(type='str', no_log=True),
masked=dict(type='bool', default=False),
protected=dict(type='bool', default=False),
+ raw=dict(type='bool', default=False),
variable_type=dict(type='str', default='env_var', choices=["env_var", "file"])
)),
state=dict(type='str', default="present", choices=["absent", "present"]),
diff --git a/plugins/modules/gitlab_issue.py b/plugins/modules/gitlab_issue.py
index 1ad7d04822..47b6f072e8 100644
--- a/plugins/modules/gitlab_issue.py
+++ b/plugins/modules/gitlab_issue.py
@@ -12,7 +12,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: gitlab_issue
short_description: Create, update, or delete GitLab issues
version_added: '8.1.0'
@@ -97,10 +97,10 @@ options:
- A title for the issue. The title is used as a unique identifier to ensure idempotency.
type: str
required: true
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create Issue
community.general.gitlab_issue:
api_url: https://gitlab.com
@@ -109,10 +109,10 @@ EXAMPLES = '''
title: "Ansible demo Issue"
description: "Demo Issue description"
labels:
- - Ansible
- - Demo
+ - Ansible
+ - Demo
assignee_ids:
- - testassignee
+ - testassignee
state_filter: "opened"
state: present
@@ -124,9 +124,9 @@ EXAMPLES = '''
title: "Ansible demo Issue"
state_filter: "opened"
state: absent
-'''
+"""
-RETURN = r'''
+RETURN = r"""
msg:
description: Success or failure message.
returned: always
@@ -137,7 +137,7 @@ issue:
description: API object.
returned: success
type: dict
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec
diff --git a/plugins/modules/gitlab_label.py b/plugins/modules/gitlab_label.py
index f6e9172eb3..8b9503e325 100644
--- a/plugins/modules/gitlab_label.py
+++ b/plugins/modules/gitlab_label.py
@@ -7,9 +7,9 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: gitlab_label
-short_description: Creates/updates/deletes GitLab Labels belonging to project or group.
+short_description: Creates/updates/deletes GitLab Labels belonging to project or group
version_added: 8.3.0
description:
- When a label does not exist, it will be created.
@@ -45,12 +45,12 @@ options:
required: false
project:
description:
- - The path and name of the project. Either this or O(group) is required.
+ - The path and name of the project. Either this or O(group) is required.
required: false
type: str
group:
description:
- - The path of the group. Either this or O(project) is required.
+ - The path of the group. Either this or O(project) is required.
required: false
type: str
labels:
@@ -76,21 +76,21 @@ options:
- Integer value to give priority to the label.
type: int
required: false
- default: null
+ default:
description:
description:
- Label's description.
type: str
- default: null
+ default:
new_name:
description:
- Optional field to change label's name.
type: str
- default: null
-'''
+ default:
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# same project's task can be executed for group
- name: Create one Label
community.general.gitlab_label:
@@ -185,9 +185,9 @@ EXAMPLES = '''
labels:
- name: label-abc123
- name: label-two
-'''
+"""
-RETURN = '''
+RETURN = r"""
labels:
description: Four lists of the labels which were added, updated, removed or exist.
returned: success
@@ -217,7 +217,7 @@ labels_obj:
description: API object.
returned: success
type: dict
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec
@@ -348,7 +348,7 @@ def native_python_main(this_gitlab, purge, requested_labels, state, module):
item.pop('description_html')
item.pop('text_color')
item.pop('subscribed')
- # field present only when it's a project's label
+ # field present only when it is a project's label
if 'is_project_label' in item:
item.pop('is_project_label')
item['new_name'] = None
@@ -472,7 +472,7 @@ def main():
if state == 'present':
_existing_labels = [x.asdict()['name'] for x in this_gitlab.list_all_labels()]
- # color is mandatory when creating label, but it's optional when changing name or updating other fields
+ # color is mandatory when creating label, but it is optional when changing name or updating other fields
if any(x['color'] is None and x['new_name'] is None and x['name'] not in _existing_labels for x in label_list):
module.fail_json(msg='color parameter is required for new labels')
diff --git a/plugins/modules/gitlab_merge_request.py b/plugins/modules/gitlab_merge_request.py
index 8e14f0a181..fd6068980a 100644
--- a/plugins/modules/gitlab_merge_request.py
+++ b/plugins/modules/gitlab_merge_request.py
@@ -12,7 +12,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: gitlab_merge_request
short_description: Create, update, or delete GitLab merge requests
version_added: 7.1.0
@@ -21,8 +21,7 @@ description:
- When a single merge request does exist, it will be updated if the provided parameters are different.
- When a single merge request does exist and O(state=absent), the merge request will be deleted.
- When multiple merge requests are detected, the task fails.
- - Existing merge requests are matched based on O(title), O(source_branch), O(target_branch),
- and O(state_filter) filters.
+ - Existing merge requests are matched based on O(title), O(source_branch), O(target_branch), and O(state_filter) filters.
author:
- zvaraondrej (@zvaraondrej)
requirements:
@@ -102,10 +101,10 @@ options:
- Comma separated list of reviewers usernames omitting V(@) character.
- Set to empty string to unassign all reviewers.
type: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create Merge Request from branch1 to branch2
community.general.gitlab_merge_request:
api_url: https://gitlab.com
@@ -117,7 +116,7 @@ EXAMPLES = '''
description: "Demo MR description"
labels: "Ansible,Demo"
state_filter: "opened"
- remove_source_branch: True
+ remove_source_branch: true
state: present
- name: Delete Merge Request from branch1 to branch2
@@ -130,9 +129,9 @@ EXAMPLES = '''
title: "Ansible demo MR"
state_filter: "opened"
state: absent
-'''
+"""
-RETURN = r'''
+RETURN = r"""
msg:
description: Success or failure message.
returned: always
@@ -143,7 +142,7 @@ mr:
description: API object.
returned: success
type: dict
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec
diff --git a/plugins/modules/gitlab_milestone.py b/plugins/modules/gitlab_milestone.py
index 4b8b933cc0..99b922c4dd 100644
--- a/plugins/modules/gitlab_milestone.py
+++ b/plugins/modules/gitlab_milestone.py
@@ -7,7 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: gitlab_milestone
short_description: Creates/updates/deletes GitLab Milestones belonging to project or group
version_added: 8.3.0
@@ -83,10 +83,10 @@ options:
- Milestone's description.
type: str
default: null
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# same project's task can be executed for group
- name: Create one milestone
community.general.gitlab_milestone:
@@ -169,9 +169,9 @@ EXAMPLES = '''
milestones:
- title: milestone-abc123
- title: milestone-two
-'''
+"""
-RETURN = '''
+RETURN = r"""
milestones:
description: Four lists of the milestones which were added, updated, removed or exist.
returned: success
@@ -201,7 +201,7 @@ milestones_obj:
description: API object.
returned: success
type: dict
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec
diff --git a/plugins/modules/gitlab_project.py b/plugins/modules/gitlab_project.py
index c5bfb4f21d..8ef73de1fd 100644
--- a/plugins/modules/gitlab_project.py
+++ b/plugins/modules/gitlab_project.py
@@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: gitlab_project
short_description: Creates/updates/deletes GitLab Projects
description:
@@ -139,7 +138,7 @@ options:
version_added: "6.2.0"
group:
description:
- - Id or the full path of the group of which this projects belongs to.
+ - ID or the full path of the group of which this projects belongs to.
type: str
import_url:
description:
@@ -179,8 +178,7 @@ options:
default: true
lfs_enabled:
description:
- - Enable Git large file systems to manages large files such
- as audio, video, and graphics files.
+ - Enable Git large file systems to manages large files such as audio, video, and graphics files.
type: bool
required: false
default: false
@@ -331,9 +329,9 @@ options:
- If an wiki for this project should be available or not.
type: bool
default: true
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create GitLab Project
community.general.gitlab_project:
api_url: https://gitlab.example.com/
@@ -378,9 +376,9 @@ EXAMPLES = r'''
api_password: "{{ initial_root_password }}"
name: my_second_project
group: "10481470"
-'''
+"""
-RETURN = r'''
+RETURN = r"""
msg:
description: Success or failure message.
returned: always
@@ -388,12 +386,12 @@ msg:
sample: "Success"
result:
- description: json parsed response from the server.
+ description: JSON-parsed response from the server.
returned: always
type: dict
error:
- description: the error message returned by the GitLab API.
+ description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
@@ -402,7 +400,7 @@ project:
description: API object.
returned: always
type: dict
-'''
+"""
from ansible.module_utils.api import basic_auth_argument_spec
diff --git a/plugins/modules/gitlab_project_access_token.py b/plugins/modules/gitlab_project_access_token.py
index 9bfbc51cc7..a93d5531bf 100644
--- a/plugins/modules/gitlab_project_access_token.py
+++ b/plugins/modules/gitlab_project_access_token.py
@@ -12,7 +12,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: gitlab_project_access_token
short_description: Manages GitLab project access tokens
version_added: 8.4.0
@@ -27,11 +27,10 @@ extends_documentation_fragment:
- community.general.gitlab
- community.general.attributes
notes:
- - Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated.
- Whether tokens will be recreated is controlled by the O(recreate) option, which defaults to V(never).
+ - Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated. Whether tokens
+ will be recreated is controlled by the O(recreate) option, which defaults to V(never).
- Token string is contained in the result only when access token is created or recreated. It can not be fetched afterwards.
- Token matching is done by comparing O(name) option.
-
attributes:
check_mode:
support: full
@@ -56,7 +55,8 @@ options:
type: list
elements: str
aliases: ["scope"]
- choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner", "ai_features", "k8s_proxy"]
+ choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner",
+ "ai_features", "k8s_proxy"]
access_level:
description:
- Access level of the access token.
@@ -84,10 +84,10 @@ options:
- When V(absent) it will be removed from the project if it exists.
default: present
type: str
- choices: [ "present", "absent" ]
-'''
+ choices: ["present", "absent"]
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: "Creating a project access token"
community.general.gitlab_project_access_token:
api_url: https://gitlab.example.com/
@@ -131,16 +131,16 @@ EXAMPLES = r'''
- write_repository
recreate: state_change
state: present
-'''
+"""
-RETURN = r'''
+RETURN = r"""
access_token:
description:
- API object.
- Only contains the value of the token if the token was created or recreated.
returned: success and O(state=present)
type: dict
-'''
+"""
from datetime import datetime
diff --git a/plugins/modules/gitlab_project_badge.py b/plugins/modules/gitlab_project_badge.py
index fee9389492..b62d651c7c 100644
--- a/plugins/modules/gitlab_project_badge.py
+++ b/plugins/modules/gitlab_project_badge.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: gitlab_project_badge
short_description: Manage project badges on GitLab Server
version_added: 6.1.0
@@ -57,9 +56,9 @@ options:
- A badge is identified by this URL.
required: true
type: str
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Add a badge to a GitLab Project
community.general.gitlab_project_badge:
api_url: 'https://example.gitlab.com'
@@ -77,9 +76,9 @@ EXAMPLES = r'''
state: absent
link_url: 'https://example.gitlab.com/%{project_path}'
image_url: 'https://example.gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg'
-'''
+"""
-RETURN = '''
+RETURN = r"""
badge:
description: The badge information.
returned: when O(state=present)
@@ -91,7 +90,7 @@ badge:
rendered_link_url: 'http://example.com/ci_status.svg?project=example-org/example-project&ref=master'
rendered_image_url: 'https://shields.io/my/badge'
kind: project
-'''
+"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/gitlab_project_members.py b/plugins/modules/gitlab_project_members.py
index 2ce277f688..228af9a062 100644
--- a/plugins/modules/gitlab_project_members.py
+++ b/plugins/modules/gitlab_project_members.py
@@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: gitlab_project_members
short_description: Manage project members on GitLab Server
version_added: 2.2.0
@@ -82,16 +81,16 @@ options:
type: str
purge_users:
description:
- - Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list.
- If omitted do not purge orphaned members.
+ - Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list. If omitted
+ do not purge orphaned members.
- Is only used when O(state=present).
type: list
elements: str
choices: ['guest', 'reporter', 'developer', 'maintainer']
version_added: 3.7.0
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Add a user to a GitLab Project
community.general.gitlab_project_members:
api_url: 'https://gitlab.example.com'
@@ -154,9 +153,9 @@ EXAMPLES = r'''
- name: user2
access_level: maintainer
state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/gitlab_project_variable.py b/plugins/modules/gitlab_project_variable.py
index 329e7a414b..5903c9b5c4 100644
--- a/plugins/modules/gitlab_project_variable.py
+++ b/plugins/modules/gitlab_project_variable.py
@@ -7,14 +7,14 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: gitlab_project_variable
short_description: Creates/updates/deletes GitLab Projects Variables
description:
- When a project variable does not exist, it will be created.
- When a project variable does exist, its value will be updated when the values are different.
- - Variables which are untouched in the playbook, but are not untouched in the GitLab project,
- they stay untouched (O(purge=false)) or will be deleted (O(purge=true)).
+ - Variables which are untouched in the playbook, but are not untouched in the GitLab project, they stay untouched (O(purge=false))
+ or will be deleted (O(purge=true)).
author:
- "Markus Bergholz (@markuman)"
requirements:
@@ -51,8 +51,8 @@ options:
vars:
description:
- When the list element is a simple key-value pair, masked, raw and protected will be set to false.
- - When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can
- have full control about whether a value should be masked, raw, protected or both.
+ - When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can have full
+ control about whether a value should be masked, raw, protected or both.
- Support for protected values requires GitLab >= 9.3.
- Support for masked values requires GitLab >= 11.10.
- Support for raw values requires GitLab >= 15.7.
@@ -61,8 +61,8 @@ options:
- A C(value) must be a string or a number.
- Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file).
- Field C(environment_scope) must be a string defined by scope environment.
- - When a value is masked, it must be in Base64 and have a length of at least 8 characters.
- See GitLab documentation on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables).
+ - When a value is masked, it must be in Base64 and have a length of at least 8 characters. See GitLab documentation
+ on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables).
default: {}
type: dict
variables:
@@ -116,10 +116,10 @@ options:
- Support for O(variables[].environment_scope) requires GitLab Premium >= 13.11.
type: str
default: '*'
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Set or update some CI/CD variables
community.general.gitlab_project_variable:
api_url: https://gitlab.com
@@ -190,9 +190,9 @@ EXAMPLES = '''
state: absent
vars:
ACCESS_KEY_ID: abc123
-'''
+"""
-RETURN = '''
+RETURN = r"""
project_variable:
description: Four lists of the variablenames which were added, updated, removed or exist.
returned: always
@@ -218,7 +218,7 @@ project_variable:
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec
diff --git a/plugins/modules/gitlab_protected_branch.py b/plugins/modules/gitlab_protected_branch.py
index 8d2d75736b..4a3b7177ee 100644
--- a/plugins/modules/gitlab_protected_branch.py
+++ b/plugins/modules/gitlab_protected_branch.py
@@ -7,7 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: gitlab_protected_branch
short_description: Manage protection of existing branches
version_added: 3.4.0
@@ -58,10 +58,10 @@ options:
default: maintainer
type: str
choices: ["maintainer", "developer", "nobody"]
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create protected branch on main
community.general.gitlab_protected_branch:
api_url: https://gitlab.com
@@ -70,11 +70,10 @@ EXAMPLES = '''
name: main
merge_access_levels: maintainer
push_access_level: nobody
+"""
-'''
-
-RETURN = '''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec
diff --git a/plugins/modules/gitlab_runner.py b/plugins/modules/gitlab_runner.py
index 68e50f05ec..62875c552a 100644
--- a/plugins/modules/gitlab_runner.py
+++ b/plugins/modules/gitlab_runner.py
@@ -10,33 +10,31 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: gitlab_runner
short_description: Create, modify and delete GitLab Runners
description:
- Register, update and delete runners on GitLab Server side with the GitLab API.
- All operations are performed using the GitLab API v4.
- - For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html)
- and U(https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user).
- - A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web interface at
- U(https://$GITLAB_URL/profile/personal_access_tokens).
- - A valid registration token is required for registering a new runner.
- To create shared runners, you need to ask your administrator to give you this token.
- It can be found at U(https://$GITLAB_URL/admin/runners/).
- - This module does not handle the C(gitlab-runner) process part, but only manages the runner on GitLab Server side through its API.
- Once the module has created the runner, you may use the generated token to run C(gitlab-runner register) command
+ - For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html) and
+ U(https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user).
+ - A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web
+ interface at U(https://$GITLAB_URL/profile/personal_access_tokens).
+ - A valid registration token is required for registering a new runner. To create shared runners, you need to ask your administrator
+ to give you this token. It can be found at U(https://$GITLAB_URL/admin/runners/).
+ - This module does not handle the C(gitlab-runner) process part, but only manages the runner on GitLab Server side through
+ its API. Once the module has created the runner, you may use the generated token to run C(gitlab-runner register) command.
notes:
- To create a new runner at least the O(api_token), O(description) and O(api_url) options are required.
- - Runners need to have unique descriptions, since this attribute is used as key for idempotency
+ - Runners need to have unique descriptions, since this attribute is used as key for idempotency.
author:
- Samy Coenen (@SamyCoenen)
- Guillaume Martinez (@Lunik)
requirements:
- - python-gitlab >= 1.5.0 for legacy runner registration workflow
- (runner registration token - U(https://docs.gitlab.com/runner/register/#register-with-a-runner-registration-token-deprecated))
- - python-gitlab >= 4.0.0 for new runner registration workflow
- (runner authentication token - U(https://docs.gitlab.com/runner/register/#register-with-a-runner-authentication-token))
+ - python-gitlab >= 1.5.0 for legacy runner registration workflow (runner registration token -
+ U(https://docs.gitlab.com/runner/register/#register-with-a-runner-registration-token-deprecated))
+ - python-gitlab >= 4.0.0 for new runner registration workflow (runner authentication token -
+ U(https://docs.gitlab.com/runner/register/#register-with-a-runner-authentication-token))
extends_documentation_fragment:
- community.general.auth_basic
- community.general.gitlab
@@ -73,7 +71,8 @@ options:
- name
state:
description:
- - Make sure that the runner with the same name exists with the same configuration or delete the runner with the same name.
+ - Make sure that the runner with the same name exists with the same configuration or delete the runner with the same
+ name.
required: false
default: present
choices: ["present", "absent"]
@@ -118,12 +117,12 @@ options:
access_level:
description:
- Determines if a runner can pick up jobs only from protected branches.
- - If O(access_level_on_creation) is not explicitly set to V(true), this option is ignored on registration and
- is only applied on updates.
+ - If O(access_level_on_creation) is not explicitly set to V(true), this option is ignored on registration and is only
+ applied on updates.
- If set to V(not_protected), runner can pick up jobs from both protected and unprotected branches.
- If set to V(ref_protected), runner can pick up jobs only from protected branches.
- - Before community.general 8.0.0 the default was V(ref_protected). This was changed to no default in community.general 8.0.0.
- If this option is not specified explicitly, GitLab will use V(not_protected) on creation, and the value set
+ - Before community.general 8.0.0 the default was V(ref_protected). This was changed to no default in community.general
+ 8.0.0. If this option is not specified explicitly, GitLab will use V(not_protected) on creation, and the value set
will not be changed on any updates.
required: false
choices: ["not_protected", "ref_protected"]
@@ -156,9 +155,9 @@ options:
default: []
type: list
elements: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create an instance-level runner
community.general.gitlab_runner:
api_url: https://gitlab.example.com/
@@ -234,31 +233,31 @@ EXAMPLES = '''
state: present
project: mygroup/mysubgroup/myproject
register: runner # Register module output to run C(gitlab-runner register) command in another task
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Success or failure message
+ description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
- description: json parsed response from the server
+ description: JSON-parsed response from the server.
returned: always
type: dict
error:
- description: the error message returned by the GitLab API
+ description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
runner:
- description: API object
+ description: API object.
returned: always
type: dict
-'''
+"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/gitlab_user.py b/plugins/modules/gitlab_user.py
index 6e5ab4ece0..3be684b1e9 100644
--- a/plugins/modules/gitlab_user.py
+++ b/plugins/modules/gitlab_user.py
@@ -10,8 +10,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: gitlab_user
short_description: Creates/updates/deletes/blocks/unblocks GitLab Users
description:
@@ -83,18 +82,13 @@ options:
version_added: 3.1.0
group:
description:
- - Id or Full path of parent group in the form of group/name.
+ - ID or Full path of parent group in the form of group/name.
- Add user as a member to this group.
type: str
access_level:
description:
- - The access level to the group. One of the following can be used.
- - guest
- - reporter
- - developer
- - master (alias for maintainer)
- - maintainer
- - owner
+ - The access level to the group.
+ - The value V(master) is an alias for V(maintainer).
default: guest
type: str
choices: ["guest", "reporter", "developer", "master", "maintainer", "owner"]
@@ -128,7 +122,7 @@ options:
suboptions:
provider:
description:
- - The name of the external identity provider
+ - The name of the external identity provider.
type: str
extern_uid:
description:
@@ -143,9 +137,9 @@ options:
type: bool
default: false
version_added: 3.3.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: "Delete GitLab User"
community.general.gitlab_user:
api_url: https://gitlab.example.com/
@@ -179,8 +173,8 @@ EXAMPLES = '''
password: mysecretpassword
email: me@example.com
identities:
- - provider: Keycloak
- extern_uid: f278f95c-12c7-4d51-996f-758cc2eb11bc
+ - provider: Keycloak
+ extern_uid: f278f95c-12c7-4d51-996f-758cc2eb11bc
state: present
group: super_group/mon_group
access_level: owner
@@ -198,31 +192,31 @@ EXAMPLES = '''
api_token: "{{ access_token }}"
username: myusername
state: unblocked
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Success or failure message
+ description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
- description: json parsed response from the server
+ description: JSON-parsed response from the server.
returned: always
type: dict
error:
- description: the error message returned by the GitLab API
+ description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
user:
- description: API object
+ description: API object.
returned: always
type: dict
-'''
+"""
from ansible.module_utils.api import basic_auth_argument_spec
diff --git a/plugins/modules/grove.py b/plugins/modules/grove.py
index b50546b4da..abdc303f90 100644
--- a/plugins/modules/grove.py
+++ b/plugins/modules/grove.py
@@ -9,13 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: grove
short_description: Sends a notification to a grove.io channel
description:
- - The C(grove) module sends a message for a service to a Grove.io
- channel.
+ - The C(grove) module sends a message for a service to a Grove.io channel.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -32,7 +30,7 @@ options:
service:
type: str
description:
- - Name of the service (displayed as the "user" in the message)
+ - Name of the service (displayed as the "user" in the message).
required: false
default: ansible
message_content:
@@ -44,29 +42,29 @@ options:
url:
type: str
description:
- - Service URL for the web client
+ - Service URL for the web client.
required: false
icon_url:
type: str
description:
- - Icon for the service
+ - Icon for the service.
required: false
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
default: true
type: bool
author: "Jonas Pfenniger (@zimbatm)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Sends a notification to a grove.io channel
community.general.grove:
channel_token: 6Ph62VBBJOccmtTPZbubiPzdrhipZXtg
service: my-app
message: 'deployed {{ target }}'
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.six.moves.urllib.parse import urlencode
diff --git a/plugins/modules/gunicorn.py b/plugins/modules/gunicorn.py
index 2b2abcf8e6..8118e0f60d 100644
--- a/plugins/modules/gunicorn.py
+++ b/plugins/modules/gunicorn.py
@@ -9,21 +9,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: gunicorn
short_description: Run gunicorn with various settings
description:
- - Starts gunicorn with the parameters specified. Common settings for gunicorn
- configuration are supported. For additional configuration use a config file
- See U(https://gunicorn-docs.readthedocs.io/en/latest/settings.html) for more
- options. It's recommended to always use the chdir option to avoid problems
- with the location of the app.
+ - Starts gunicorn with the parameters specified. Common settings for gunicorn configuration are supported. For additional
+ configuration use a config file See U(https://gunicorn-docs.readthedocs.io/en/latest/settings.html) for more options.
+ It's recommended to always use the chdir option to avoid problems with the location of the app.
requirements: [gunicorn]
author:
- - "Alejandro Gomez (@agmezr)"
+ - "Alejandro Gomez (@agmezr)"
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
@@ -40,37 +37,36 @@ options:
type: path
aliases: ['virtualenv']
description:
- - 'Path to the virtualenv directory.'
+ - Path to the virtualenv directory.
config:
type: path
description:
- - 'Path to the gunicorn configuration file.'
+ - Path to the gunicorn configuration file.
aliases: ['conf']
chdir:
type: path
description:
- - 'Chdir to specified directory before apps loading.'
+ - Chdir to specified directory before apps loading.
pid:
type: path
description:
- - 'A filename to use for the PID file. If not set and not found on the configuration file a tmp
- pid file will be created to check a successful run of gunicorn.'
+ - A filename to use for the PID file. If not set and not found on the configuration file a tmp pid file will be created
+ to check a successful run of gunicorn.
worker:
type: str
choices: ['sync', 'eventlet', 'gevent', 'tornado ', 'gthread', 'gaiohttp']
description:
- - 'The type of workers to use. The default class (sync) should handle most "normal" types of workloads.'
+ - The type of workers to use. The default class (sync) should handle most "normal" types of workloads.
user:
type: str
description:
- - 'Switch worker processes to run as this user.'
+ - Switch worker processes to run as this user.
notes:
- - If not specified on config file, a temporary error log will be created on /tmp dir.
- Please make sure you have write access in /tmp dir. Not needed but will help you to
- identify any problem with configuration.
-'''
+ - If not specified on config file, a temporary error log will be created on /tmp dir. Please make sure you have write access
+ in /tmp dir. Not needed but will help you to identify any problem with configuration.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Simple gunicorn run example
community.general.gunicorn:
app: 'wsgi'
@@ -96,15 +92,15 @@ EXAMPLES = '''
venv: '/workspace/example/venv'
pid: '/workspace/example/gunicorn.pid'
user: 'ansible'
-'''
+"""
-RETURN = '''
+RETURN = r"""
gunicorn:
- description: process id of gunicorn
- returned: changed
- type: str
- sample: "1234"
-'''
+ description: Process ID of gunicorn.
+ returned: changed
+ type: str
+ sample: "1234"
+"""
import os
import time
diff --git a/plugins/modules/haproxy.py b/plugins/modules/haproxy.py
index 320c77e7a1..9c60e59040 100644
--- a/plugins/modules/haproxy.py
+++ b/plugins/modules/haproxy.py
@@ -8,23 +8,21 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: haproxy
short_description: Enable, disable, and set weights for HAProxy backend servers using socket commands
author:
- - Ravi Bhure (@ravibhure)
+ - Ravi Bhure (@ravibhure)
description:
- - Enable, disable, drain and set weights for HAProxy backend servers using socket commands.
+ - Enable, disable, drain and set weights for HAProxy backend servers using socket commands.
notes:
- - Enable, disable and drain commands are restricted and can only be issued on
- sockets configured for level 'admin'. For example, you can add the line
- 'stats socket /var/run/haproxy.sock level admin' to the general section of
- haproxy.cfg. See U(http://haproxy.1wt.eu/download/1.5/doc/configuration.txt).
- - Depends on netcat (C(nc)) being available; you need to install the appropriate
- package for your operating system before this module can be used.
+ - Enable, disable and drain commands are restricted and can only be issued on sockets configured for level C(admin). For
+ example, you can add the line C(stats socket /var/run/haproxy.sock level admin) to the general section of C(haproxy.cfg).
+ See U(http://haproxy.1wt.eu/download/1.5/doc/configuration.txt).
+ - Depends on netcat (C(nc)) being available; you need to install the appropriate package for your operating system before
+ this module can be used.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
@@ -38,8 +36,8 @@ options:
type: str
drain:
description:
- - Wait until the server has no active connections or until the timeout
- determined by wait_interval and wait_retries is reached.
+ - Wait until the server has no active connections or until the timeout determined by O(wait_interval) and O(wait_retries)
+ is reached.
- Continue only after the status changes to C(MAINT).
- This overrides the shutdown_sessions option.
type: bool
@@ -51,10 +49,9 @@ options:
required: true
shutdown_sessions:
description:
- - When disabling a server, immediately terminate all the sessions attached
- to the specified server.
- - This can be used to terminate long-running sessions after a server is put
- into maintenance mode. Overridden by the drain option.
+ - When disabling a server, immediately terminate all the sessions attached to the specified server.
+ - This can be used to terminate long-running sessions after a server is put into maintenance mode. Overridden by the
+ drain option.
type: bool
default: false
socket:
@@ -65,11 +62,11 @@ options:
state:
description:
- Desired state of the provided backend host.
- - Note that V(drain) state is supported only by HAProxy version 1.5 or later.
- When used on versions < 1.5, it will be ignored.
+ - Note that V(drain) state is supported only by HAProxy version 1.5 or later. When used on versions < 1.5, it will be
+ ignored.
type: str
required: true
- choices: [ disabled, drain, enabled ]
+ choices: [disabled, drain, enabled]
agent:
description:
- Disable/enable agent checks (depending on O(state) value).
@@ -89,8 +86,8 @@ options:
default: false
wait:
description:
- - Wait until the server reports a status of C(UP) when O(state=enabled),
- status of C(MAINT) when O(state=disabled) or status of C(DRAIN) when O(state=drain).
+ - Wait until the server reports a status of C(UP) when O(state=enabled), status of C(MAINT) when O(state=disabled) or
+ status of C(DRAIN) when O(state=drain).
type: bool
default: false
wait_interval:
@@ -106,14 +103,12 @@ options:
weight:
description:
- The value passed in argument.
- - If the value ends with the V(%) sign, then the new weight will be
- relative to the initially configured weight.
- - Relative weights are only permitted between 0 and 100% and absolute
- weights are permitted between 0 and 256.
+ - If the value ends with the V(%) sign, then the new weight will be relative to the initially configured weight.
+ - Relative weights are only permitted between 0 and 100% and absolute weights are permitted between 0 and 256.
type: str
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Disable server in 'www' backend pool
community.general.haproxy:
state: disabled
@@ -168,7 +163,8 @@ EXAMPLES = r'''
socket: /var/run/haproxy.sock
shutdown_sessions: true
-- name: Disable server without backend pool name (apply to all available backend pool) but fail when the backend host is not found
+- name: Disable server without backend pool name (apply to all available backend pool) but fail when the backend host is
+ not found
community.general.haproxy:
state: disabled
host: '{{ inventory_hostname }}'
@@ -187,7 +183,8 @@ EXAMPLES = r'''
backend: www
wait: true
-- name: Enable server in 'www' backend pool wait until healthy. Retry 10 times with intervals of 5 seconds to retrieve the health
+- name: Enable server in 'www' backend pool wait until healthy. Retry 10 times with intervals of 5 seconds to retrieve the
+ health
community.general.haproxy:
state: enabled
host: '{{ inventory_hostname }}'
@@ -210,7 +207,7 @@ EXAMPLES = r'''
host: '{{ inventory_hostname }}'
socket: /var/run/haproxy.sock
backend: www
-'''
+"""
import csv
import socket
diff --git a/plugins/modules/heroku_collaborator.py b/plugins/modules/heroku_collaborator.py
index e07ae333dd..1d278339e4 100644
--- a/plugins/modules/heroku_collaborator.py
+++ b/plugins/modules/heroku_collaborator.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: heroku_collaborator
short_description: Add or delete app collaborators on Heroku
description:
@@ -32,35 +31,35 @@ options:
api_key:
type: str
description:
- - Heroku API key
+ - Heroku API key.
apps:
type: list
elements: str
description:
- - List of Heroku App names
+ - List of Heroku App names.
required: true
suppress_invitation:
description:
- - Suppress email invitation when creating collaborator
+ - Suppress email invitation when creating collaborator.
type: bool
default: false
user:
type: str
description:
- - User ID or e-mail
+ - User ID or e-mail.
required: true
state:
type: str
description:
- - Create or remove the heroku collaborator
+ - Create or remove the heroku collaborator.
choices: ["present", "absent"]
default: "present"
notes:
- E(HEROKU_API_KEY) and E(TF_VAR_HEROKU_API_KEY) environment variables can be used instead setting O(api_key).
- - If you use C(check_mode), you can also pass the C(-v) flag to see affected apps in C(msg), e.g. ["heroku-example-app"].
-'''
+ - If you use C(check_mode), you can also pass the C(-v) flag to see affected apps in C(msg), for example C(["heroku-example-app"]).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a heroku collaborator
community.general.heroku_collaborator:
api_key: YOUR_API_KEY
@@ -76,12 +75,12 @@ EXAMPLES = '''
suppress_invitation: '{{ item.suppress_invitation | default(suppress_invitation) }}'
state: '{{ item.state | default("present") }}'
with_items:
- - { user: 'a.b@example.com' }
- - { state: 'absent', user: 'b.c@example.com', suppress_invitation: false }
- - { user: 'x.y@example.com', apps: ["heroku-example-app"] }
-'''
+ - {user: 'a.b@example.com'}
+ - {state: 'absent', user: 'b.c@example.com', suppress_invitation: false}
+ - {user: 'x.y@example.com', apps: ["heroku-example-app"]}
+"""
-RETURN = ''' # '''
+RETURN = """ # """
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.heroku import HerokuHelper
diff --git a/plugins/modules/hg.py b/plugins/modules/hg.py
index 4b6b7c4330..f269628abb 100644
--- a/plugins/modules/hg.py
+++ b/plugins/modules/hg.py
@@ -9,75 +9,71 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hg
short_description: Manages Mercurial (hg) repositories
description:
- - Manages Mercurial (hg) repositories. Supports SSH, HTTP/S and local address.
+ - Manages Mercurial (hg) repositories. Supports SSH, HTTP/S and local address.
author: "Yeukhon Wong (@yeukhon)"
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- repo:
- description:
- - The repository address.
- required: true
- aliases: [ name ]
- type: str
- dest:
- description:
- - Absolute path of where the repository should be cloned to.
- This parameter is required, unless clone and update are set to no
- type: path
- revision:
- description:
- - Equivalent C(-r) option in hg command which could be the changeset, revision number,
- branch name or even tag.
- aliases: [ version ]
- type: str
- force:
- description:
- - Discards uncommitted changes. Runs C(hg update -C).
- type: bool
- default: false
- purge:
- description:
- - Deletes untracked files. Runs C(hg purge).
- type: bool
- default: false
- update:
- description:
- - If V(false), do not retrieve new revisions from the origin repository
- type: bool
- default: true
- clone:
- description:
- - If V(false), do not clone the repository if it does not exist locally.
- type: bool
- default: true
- executable:
- description:
- - Path to hg executable to use. If not supplied,
- the normal mechanism for resolving binary paths will be used.
- type: str
+ repo:
+ description:
+ - The repository address.
+ required: true
+ aliases: [name]
+ type: str
+ dest:
+ description:
+ - Absolute path of where the repository should be cloned to. This parameter is required, unless clone and update are
+ set to no.
+ type: path
+ revision:
+ description:
+ - Equivalent C(-r) option in hg command which could be the changeset, revision number, branch name or even tag.
+ aliases: [version]
+ type: str
+ force:
+ description:
+ - Discards uncommitted changes. Runs C(hg update -C).
+ type: bool
+ default: false
+ purge:
+ description:
+ - Deletes untracked files. Runs C(hg purge).
+ type: bool
+ default: false
+ update:
+ description:
+ - If V(false), do not retrieve new revisions from the origin repository.
+ type: bool
+ default: true
+ clone:
+ description:
+ - If V(false), do not clone the repository if it does not exist locally.
+ type: bool
+ default: true
+ executable:
+ description:
+ - Path to hg executable to use. If not supplied, the normal mechanism for resolving binary paths will be used.
+ type: str
notes:
- - This module does not support push capability. See U(https://github.com/ansible/ansible/issues/31156).
- - "If the task seems to be hanging, first verify remote host is in C(known_hosts).
- SSH will prompt user to authorize the first contact with a remote host. To avoid this prompt,
- one solution is to add the remote host public key in C(/etc/ssh/ssh_known_hosts) before calling
- the hg module, with the following command: ssh-keyscan remote_host.com >> /etc/ssh/ssh_known_hosts."
- - As per 01 Dec 2018, Bitbucket has dropped support for TLSv1 and TLSv1.1 connections. As such,
- if the underlying system still uses a Python version below 2.7.9, you will have issues checking out
- bitbucket repositories. See U(https://bitbucket.org/blog/deprecating-tlsv1-tlsv1-1-2018-12-01).
-'''
+ - This module does not support push capability. See U(https://github.com/ansible/ansible/issues/31156).
+ - 'If the task seems to be hanging, first verify remote host is in C(known_hosts). SSH will prompt user to authorize the
+ first contact with a remote host. To avoid this prompt, one solution is to add the remote host public key in C(/etc/ssh/ssh_known_hosts)
+ before calling the hg module, with the following command: C(ssh-keyscan remote_host.com >> /etc/ssh/ssh_known_hosts).'
+ - As per 01 Dec 2018, Bitbucket has dropped support for TLSv1 and TLSv1.1 connections. As such, if the underlying system
+ still uses a Python version below 2.7.9, you will have issues checking out bitbucket repositories. See
+ U(https://bitbucket.org/blog/deprecating-tlsv1-tlsv1-1-2018-12-01).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Ensure the current working copy is inside the stable branch and deletes untracked files if any.
community.general.hg:
repo: https://bitbucket.org/user/repo1
@@ -91,7 +87,7 @@ EXAMPLES = '''
dest: /srv/checkout
clone: false
update: false
-'''
+"""
import os
@@ -209,7 +205,7 @@ class Hg(object):
if the desired changeset is already the current changeset.
"""
if self.revision is None or len(self.revision) < 7:
- # Assume it's a rev number, tag, or branch
+ # Assume it is a rev number, tag, or branch
return False
(rc, out, err) = self._command(['--debug', 'id', '-i', '-R', self.dest])
if rc != 0:
diff --git a/plugins/modules/hipchat.py b/plugins/modules/hipchat.py
index 399d5c3bef..14b8bb2cb4 100644
--- a/plugins/modules/hipchat.py
+++ b/plugins/modules/hipchat.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hipchat
short_description: Send a message to Hipchat
description:
- - Send a message to a Hipchat room, with options to control the formatting.
+ - Send a message to a Hipchat room, with options to control the formatting.
extends_documentation_fragment:
- community.general.attributes
deprecated:
@@ -40,8 +39,7 @@ options:
msg_from:
type: str
description:
- - Name the message will appear to be sent from. Max length is 15
- characters - above this it will be truncated.
+ - Name the message will appear to be sent from. Max length is 15 characters - above this it will be truncated.
default: Ansible
aliases: [from]
msg:
@@ -54,13 +52,13 @@ options:
description:
- Background color for the message.
default: yellow
- choices: [ "yellow", "red", "green", "purple", "gray", "random" ]
+ choices: ["yellow", "red", "green", "purple", "gray", "random"]
msg_format:
type: str
description:
- Message format.
default: text
- choices: [ "text", "html" ]
+ choices: ["text", "html"]
notify:
description:
- If true, a notification will be triggered for users in the room.
@@ -68,23 +66,23 @@ options:
default: true
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
type: bool
default: true
api:
type: str
description:
- - API url if using a self-hosted hipchat server. For Hipchat API version
- 2 use the default URI with C(/v2) instead of C(/v1).
+ - API URL if using a self-hosted hipchat server. For Hipchat API version 2 use the default URI with C(/v2) instead of
+ C(/v1).
default: 'https://api.hipchat.com/v1'
author:
-- Shirou Wakayama (@shirou)
-- Paul Bourdel (@pb8226)
-'''
+ - Shirou Wakayama (@shirou)
+ - Paul Bourdel (@pb8226)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Send a message to a Hipchat room
community.general.hipchat:
room: notif
@@ -96,7 +94,7 @@ EXAMPLES = '''
token: OAUTH2_TOKEN
room: notify
msg: Ansible task finished
-'''
+"""
# ===========================================
# HipChat module specific support methods.
diff --git a/plugins/modules/homebrew.py b/plugins/modules/homebrew.py
index 58b13f83d4..bdc6f65724 100644
--- a/plugins/modules/homebrew.py
+++ b/plugins/modules/homebrew.py
@@ -14,81 +14,80 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: homebrew
author:
- - "Indrajit Raychaudhuri (@indrajitr)"
- - "Daniel Jaouen (@danieljaouen)"
- - "Andrew Dunham (@andrew-d)"
+ - "Indrajit Raychaudhuri (@indrajitr)"
+ - "Daniel Jaouen (@danieljaouen)"
+ - "Andrew Dunham (@andrew-d)"
requirements:
- - homebrew must already be installed on the target system
+ - homebrew must already be installed on the target system
short_description: Package manager for Homebrew
description:
- - Manages Homebrew packages
+ - Manages Homebrew packages.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - A list of names of packages to install/remove.
- aliases: [ 'formula', 'package', 'pkg' ]
- type: list
- elements: str
- path:
- description:
- - "A V(:) separated list of paths to search for C(brew) executable.
- Since a package (I(formula) in homebrew parlance) location is prefixed relative to the actual path of C(brew) command,
- providing an alternative C(brew) path enables managing different set of packages in an alternative location in the system."
- default: '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin'
- type: path
- state:
- description:
- - state of the package.
- choices: [ 'absent', 'head', 'installed', 'latest', 'linked', 'present', 'removed', 'uninstalled', 'unlinked', 'upgraded' ]
- default: present
- type: str
- update_homebrew:
- description:
- - update homebrew itself first.
- type: bool
- default: false
- upgrade_all:
- description:
- - upgrade all homebrew packages.
- type: bool
- default: false
- aliases: ['upgrade']
- install_options:
- description:
- - options flags to install a package.
- aliases: ['options']
- type: list
- elements: str
- upgrade_options:
- description:
- - Option flags to upgrade.
- type: list
- elements: str
- version_added: '0.2.0'
- force_formula:
- description:
- - Force the package(s) to be treated as a formula (equivalent to C(brew --formula)).
- - To install a cask, use the M(community.general.homebrew_cask) module.
- type: bool
- default: false
- version_added: 9.0.0
+ name:
+ description:
+ - A list of names of packages to install/remove.
+ aliases: ['formula', 'package', 'pkg']
+ type: list
+ elements: str
+ path:
+ description:
+ - A V(:) separated list of paths to search for C(brew) executable. Since a package (I(formula) in homebrew parlance)
+ location is prefixed relative to the actual path of C(brew) command, providing an alternative C(brew) path enables
+ managing different set of packages in an alternative location in the system.
+ default: '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin'
+ type: path
+ state:
+ description:
+ - State of the package.
+ choices: ['absent', 'head', 'installed', 'latest', 'linked', 'present', 'removed', 'uninstalled', 'unlinked', 'upgraded']
+ default: present
+ type: str
+ update_homebrew:
+ description:
+ - Update homebrew itself first.
+ type: bool
+ default: false
+ upgrade_all:
+ description:
+ - Upgrade all homebrew packages.
+ type: bool
+ default: false
+ aliases: ['upgrade']
+ install_options:
+ description:
+ - Options flags to install a package.
+ aliases: ['options']
+ type: list
+ elements: str
+ upgrade_options:
+ description:
+ - Option flags to upgrade.
+ type: list
+ elements: str
+ version_added: '0.2.0'
+ force_formula:
+ description:
+ - Force the package(s) to be treated as a formula (equivalent to C(brew --formula)).
+ - To install a cask, use the M(community.general.homebrew_cask) module.
+ type: bool
+ default: false
+ version_added: 9.0.0
notes:
- - When used with a C(loop:) each package will be processed individually,
- it is much more efficient to pass the list directly to the O(name) option.
-'''
+ - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly
+ to the O(name) option.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Install formula foo with 'brew' in default path
- community.general.homebrew:
name: foo
@@ -154,29 +153,29 @@ EXAMPLES = '''
name: ambiguous_formula
state: present
force_formula: true
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: if the cache was updated or not
- returned: always
- type: str
- sample: "Changed: 0, Unchanged: 2"
+ description: If the cache was updated or not.
+ returned: always
+ type: str
+ sample: "Changed: 0, Unchanged: 2"
unchanged_pkgs:
- description:
- - List of package names which are unchanged after module run
- returned: success
- type: list
- sample: ["awscli", "ag"]
- version_added: '0.2.0'
+ description:
+ - List of package names which are unchanged after module run.
+ returned: success
+ type: list
+ sample: ["awscli", "ag"]
+ version_added: '0.2.0'
changed_pkgs:
- description:
- - List of package names which are changed after module run
- returned: success
- type: list
- sample: ['git', 'git-cola']
- version_added: '0.2.0'
-'''
+ description:
+ - List of package names which are changed after module run.
+ returned: success
+ type: list
+ sample: ['git', 'git-cola']
+ version_added: '0.2.0'
+"""
import json
import re
@@ -308,21 +307,6 @@ class Homebrew(object):
self._params = self.module.params
return self._params
- @property
- def current_package(self):
- return self._current_package
-
- @current_package.setter
- def current_package(self, package):
- if not HomebrewValidate.valid_package(package):
- self._current_package = None
- self.failed = True
- self.message = 'Invalid package: {0}.'.format(package)
- raise HomebrewException(self.message)
-
- else:
- self._current_package = package
- return package
# /class properties -------------------------------------------- }}}
def __init__(self, module, path, packages=None, state=None,
@@ -347,13 +331,13 @@ class Homebrew(object):
def _setup_status_vars(self):
self.failed = False
self.changed = False
- self.changed_count = 0
- self.unchanged_count = 0
self.changed_pkgs = []
self.unchanged_pkgs = []
self.message = ''
def _setup_instance_vars(self, **kwargs):
+ self.installed_packages = set()
+ self.outdated_packages = set()
for key, val in iteritems(kwargs):
setattr(self, key, val)
@@ -380,8 +364,81 @@ class Homebrew(object):
return self.brew_path
- def _status(self):
- return (self.failed, self.changed, self.message)
+ def _validate_packages_names(self):
+ invalid_packages = []
+ for package in self.packages:
+ if not HomebrewValidate.valid_package(package):
+ invalid_packages.append(package)
+
+ if invalid_packages:
+ self.failed = True
+ self.message = 'Invalid package{0}: {1}'.format(
+ "s" if len(invalid_packages) > 1 else "",
+ ", ".join(invalid_packages),
+ )
+ raise HomebrewException(self.message)
+
+ def _save_package_info(self, package_detail, package_name):
+ if bool(package_detail.get("installed")):
+ self.installed_packages.add(package_name)
+ if bool(package_detail.get("outdated")):
+ self.outdated_packages.add(package_name)
+
+ def _extract_package_name(self, package_detail, is_cask):
+ # "brew info" can lookup by name, full_name, token, full_token, or aliases
+ # In addition, any name can be prefixed by the tap.
+ # Any of these can be supplied by the user as the package name. In case
+ # of ambiguity, where a given name might match multiple packages,
+ # formulae are preferred over casks. For all other ambiguities, the
+ # results are an error. Note that in the homebrew/core and
+ # homebrew/cask taps, there are no "other" ambiguities.
+ if is_cask: # according to brew info
+ name = package_detail["token"]
+ full_name = package_detail["full_token"]
+ else:
+ name = package_detail["name"]
+ full_name = package_detail["full_name"]
+
+ tapped_name = package_detail["tap"] + "/" + name
+ aliases = package_detail.get("aliases", [])
+
+ package_names = set([name, full_name, tapped_name] + aliases)
+
+ # Finally, identify which of all those package names was the one supplied by the user.
+ package_names = package_names & set(self.packages)
+ if len(package_names) != 1:
+ self.failed = True
+ self.message = "Package names are missing or ambiguous: " + ", ".join(str(p) for p in package_names)
+ raise HomebrewException(self.message)
+
+ # Then make sure the user provided name resurface.
+ return package_names.pop()
+
+ def _get_packages_info(self):
+ cmd = [
+ "{brew_path}".format(brew_path=self.brew_path),
+ "info",
+ "--json=v2",
+ ]
+ cmd.extend(self.packages)
+ if self.force_formula:
+ cmd.append("--formula")
+
+ rc, out, err = self.module.run_command(cmd)
+ if rc != 0:
+ self.failed = True
+ self.message = err.strip() or ("Unknown failure with exit code %d" % rc)
+ raise HomebrewException(self.message)
+
+ data = json.loads(out)
+ for package_detail in data.get("formulae", []):
+ package_name = self._extract_package_name(package_detail, is_cask=False)
+ self._save_package_info(package_detail, package_name)
+
+ for package_detail in data.get("casks", []):
+ package_name = self._extract_package_name(package_detail, is_cask=True)
+ self._save_package_info(package_detail, package_name)
+
# /prep -------------------------------------------------------- }}}
def run(self):
@@ -390,70 +447,14 @@ class Homebrew(object):
except HomebrewException:
pass
- if not self.failed and (self.changed_count + self.unchanged_count > 1):
+ changed_count = len(self.changed_pkgs)
+ unchanged_count = len(self.unchanged_pkgs)
+ if not self.failed and (changed_count + unchanged_count > 1):
self.message = "Changed: %d, Unchanged: %d" % (
- self.changed_count,
- self.unchanged_count,
+ changed_count,
+ unchanged_count,
)
- (failed, changed, message) = self._status()
-
- return (failed, changed, message)
-
- # checks ------------------------------------------------------- {{{
- def _current_package_is_installed(self):
- if not HomebrewValidate.valid_package(self.current_package):
- self.failed = True
- self.message = 'Invalid package: {0}.'.format(self.current_package)
- raise HomebrewException(self.message)
-
- cmd = [
- "{brew_path}".format(brew_path=self.brew_path),
- "info",
- "--json=v2",
- self.current_package,
- ]
- if self.force_formula:
- cmd.append("--formula")
- rc, out, err = self.module.run_command(cmd)
- if rc != 0:
- self.failed = True
- self.message = err.strip() or ("Unknown failure with exit code %d" % rc)
- raise HomebrewException(self.message)
- data = json.loads(out)
-
- return _check_package_in_json(data, "formulae") or _check_package_in_json(data, "casks")
-
- def _current_package_is_outdated(self):
- if not HomebrewValidate.valid_package(self.current_package):
- return False
-
- rc, out, err = self.module.run_command([
- self.brew_path,
- 'outdated',
- self.current_package,
- ])
-
- return rc != 0
-
- def _current_package_is_installed_from_head(self):
- if not HomebrewValidate.valid_package(self.current_package):
- return False
- elif not self._current_package_is_installed():
- return False
-
- rc, out, err = self.module.run_command([
- self.brew_path,
- 'info',
- self.current_package,
- ])
-
- try:
- version_info = [line for line in out.split('\n') if line][0]
- except IndexError:
- return False
-
- return version_info.split(' ')[-1] == 'HEAD'
- # /checks ------------------------------------------------------ }}}
+ return (self.failed, self.changed, self.message)
# commands ----------------------------------------------------- {{{
def _run(self):
@@ -464,6 +465,8 @@ class Homebrew(object):
self._upgrade_all()
if self.packages:
+ self._validate_packages_names()
+ self._get_packages_info()
if self.state == 'installed':
return self._install_packages()
elif self.state == 'upgraded':
@@ -533,24 +536,22 @@ class Homebrew(object):
# /_upgrade_all -------------------------- }}}
# installed ------------------------------ {{{
- def _install_current_package(self):
- if not HomebrewValidate.valid_package(self.current_package):
- self.failed = True
- self.message = 'Invalid package: {0}.'.format(self.current_package)
- raise HomebrewException(self.message)
+ def _install_packages(self):
+ packages_to_install = set(self.packages) - self.installed_packages
- if self._current_package_is_installed():
- self.unchanged_count += 1
- self.unchanged_pkgs.append(self.current_package)
- self.message = 'Package already installed: {0}'.format(
- self.current_package,
+ if len(packages_to_install) == 0:
+ self.unchanged_pkgs.extend(self.packages)
+ self.message = 'Package{0} already installed: {1}'.format(
+ "s" if len(self.packages) > 1 else "",
+ ", ".join(self.packages),
)
return True
if self.module.check_mode:
self.changed = True
- self.message = 'Package would be installed: {0}'.format(
- self.current_package
+ self.message = 'Package{0} would be installed: {1}'.format(
+ "s" if len(packages_to_install) > 1 else "",
+ ", ".join(packages_to_install)
)
raise HomebrewException(self.message)
@@ -567,77 +568,28 @@ class Homebrew(object):
opts = (
[self.brew_path, 'install']
+ self.install_options
- + [self.current_package, head, formula]
+ + list(packages_to_install)
+ + [head, formula]
)
cmd = [opt for opt in opts if opt]
rc, out, err = self.module.run_command(cmd)
if rc == 0:
- self.changed_count += 1
- self.changed_pkgs.append(self.current_package)
+ self.changed_pkgs.extend(packages_to_install)
+ self.unchanged_pkgs.extend(self.installed_packages)
self.changed = True
- self.message = 'Package installed: {0}'.format(self.current_package)
+ self.message = 'Package{0} installed: {1}'.format(
+ "s" if len(packages_to_install) > 1 else "",
+ ", ".join(packages_to_install)
+ )
return True
else:
self.failed = True
self.message = err.strip()
raise HomebrewException(self.message)
-
- def _install_packages(self):
- for package in self.packages:
- self.current_package = package
- self._install_current_package()
-
- return True
# /installed ----------------------------- }}}
# upgraded ------------------------------- {{{
- def _upgrade_current_package(self):
- command = 'upgrade'
-
- if not HomebrewValidate.valid_package(self.current_package):
- self.failed = True
- self.message = 'Invalid package: {0}.'.format(self.current_package)
- raise HomebrewException(self.message)
-
- current_package_is_installed = self._current_package_is_installed()
- if not current_package_is_installed:
- command = 'install'
-
- if current_package_is_installed and not self._current_package_is_outdated():
- self.message = 'Package is already upgraded: {0}'.format(
- self.current_package,
- )
- self.unchanged_count += 1
- self.unchanged_pkgs.append(self.current_package)
- return True
-
- if self.module.check_mode:
- self.changed = True
- self.message = 'Package would be upgraded: {0}'.format(
- self.current_package
- )
- raise HomebrewException(self.message)
-
- opts = (
- [self.brew_path, command]
- + self.install_options
- + [self.current_package]
- )
- cmd = [opt for opt in opts if opt]
- rc, out, err = self.module.run_command(cmd)
-
- if rc == 0:
- self.changed_count += 1
- self.changed_pkgs.append(self.current_package)
- self.changed = True
- self.message = 'Package upgraded: {0}'.format(self.current_package)
- return True
- else:
- self.failed = True
- self.message = err.strip()
- raise HomebrewException(self.message)
-
def _upgrade_all_packages(self):
opts = (
[self.brew_path, 'upgrade']
@@ -659,153 +611,188 @@ class Homebrew(object):
if not self.packages:
self._upgrade_all_packages()
else:
- for package in self.packages:
- self.current_package = package
- self._upgrade_current_package()
- return True
+ # There are 3 action possible here depending on installed and outdated states:
+ # - not installed -> 'install'
+ # - installed and outdated -> 'upgrade'
+ # - installed and NOT outdated -> Nothing to do!
+ packages_to_install = set(self.packages) - self.installed_packages
+ packages_to_upgrade = self.installed_packages & self.outdated_packages
+ packages_to_install_or_upgrade = packages_to_install | packages_to_upgrade
+
+ if len(packages_to_install_or_upgrade) == 0:
+ self.unchanged_pkgs.extend(self.packages)
+ self.message = 'Package{0} already upgraded: {1}'.format(
+ "s" if len(self.packages) > 1 else "",
+ ", ".join(self.packages),
+ )
+ return True
+
+ if self.module.check_mode:
+ self.changed = True
+ self.message = 'Package{0} would be upgraded: {1}'.format(
+ "s" if len(packages_to_install_or_upgrade) > 1 else "",
+ ", ".join(packages_to_install_or_upgrade)
+ )
+ raise HomebrewException(self.message)
+
+ for command, packages in [
+ ("install", packages_to_install),
+ ("upgrade", packages_to_upgrade)
+ ]:
+ if not packages:
+ continue
+
+ opts = (
+ [self.brew_path, command]
+ + self.install_options
+ + list(packages)
+ )
+ cmd = [opt for opt in opts if opt]
+ rc, out, err = self.module.run_command(cmd)
+
+ if rc != 0:
+ self.failed = True
+ self.message = err.strip()
+ raise HomebrewException(self.message)
+
+ self.changed_pkgs.extend(packages_to_install_or_upgrade)
+ self.unchanged_pkgs.extend(set(self.packages) - packages_to_install_or_upgrade)
+ self.changed = True
+ self.message = 'Package{0} upgraded: {1}'.format(
+ "s" if len(packages_to_install_or_upgrade) > 1 else "",
+ ", ".join(packages_to_install_or_upgrade),
+ )
# /upgraded ------------------------------ }}}
# uninstalled ---------------------------- {{{
- def _uninstall_current_package(self):
- if not HomebrewValidate.valid_package(self.current_package):
- self.failed = True
- self.message = 'Invalid package: {0}.'.format(self.current_package)
- raise HomebrewException(self.message)
+ def _uninstall_packages(self):
+ packages_to_uninstall = self.installed_packages & set(self.packages)
- if not self._current_package_is_installed():
- self.unchanged_count += 1
- self.unchanged_pkgs.append(self.current_package)
- self.message = 'Package already uninstalled: {0}'.format(
- self.current_package,
+ if len(packages_to_uninstall) == 0:
+ self.unchanged_pkgs.extend(self.packages)
+ self.message = 'Package{0} already uninstalled: {1}'.format(
+ "s" if len(self.packages) > 1 else "",
+ ", ".join(self.packages),
)
return True
if self.module.check_mode:
self.changed = True
- self.message = 'Package would be uninstalled: {0}'.format(
- self.current_package
+ self.message = 'Package{0} would be uninstalled: {1}'.format(
+ "s" if len(packages_to_uninstall) > 1 else "",
+ ", ".join(packages_to_uninstall)
)
raise HomebrewException(self.message)
opts = (
[self.brew_path, 'uninstall', '--force']
+ self.install_options
- + [self.current_package]
+ + list(packages_to_uninstall)
)
cmd = [opt for opt in opts if opt]
rc, out, err = self.module.run_command(cmd)
- if not self._current_package_is_installed():
- self.changed_count += 1
- self.changed_pkgs.append(self.current_package)
+ if rc == 0:
+ self.changed_pkgs.extend(packages_to_uninstall)
+ self.unchanged_pkgs.extend(set(self.packages) - self.installed_packages)
self.changed = True
- self.message = 'Package uninstalled: {0}'.format(self.current_package)
+ self.message = 'Package{0} uninstalled: {1}'.format(
+ "s" if len(packages_to_uninstall) > 1 else "",
+ ", ".join(packages_to_uninstall)
+ )
return True
else:
self.failed = True
self.message = err.strip()
raise HomebrewException(self.message)
-
- def _uninstall_packages(self):
- for package in self.packages:
- self.current_package = package
- self._uninstall_current_package()
-
- return True
# /uninstalled ----------------------------- }}}
# linked --------------------------------- {{{
- def _link_current_package(self):
- if not HomebrewValidate.valid_package(self.current_package):
+ def _link_packages(self):
+ missing_packages = set(self.packages) - self.installed_packages
+ if missing_packages:
self.failed = True
- self.message = 'Invalid package: {0}.'.format(self.current_package)
- raise HomebrewException(self.message)
-
- if not self._current_package_is_installed():
- self.failed = True
- self.message = 'Package not installed: {0}.'.format(self.current_package)
+ self.message = 'Package{0} not installed: {1}.'.format(
+ "s" if len(missing_packages) > 1 else "",
+ ", ".join(missing_packages),
+ )
raise HomebrewException(self.message)
if self.module.check_mode:
self.changed = True
- self.message = 'Package would be linked: {0}'.format(
- self.current_package
+ self.message = 'Package{0} would be linked: {1}'.format(
+ "s" if len(self.packages) > 1 else "",
+ ", ".join(self.packages)
)
raise HomebrewException(self.message)
opts = (
[self.brew_path, 'link']
+ self.install_options
- + [self.current_package]
+ + self.packages
)
cmd = [opt for opt in opts if opt]
rc, out, err = self.module.run_command(cmd)
if rc == 0:
- self.changed_count += 1
- self.changed_pkgs.append(self.current_package)
+ self.changed_pkgs.extend(self.packages)
self.changed = True
- self.message = 'Package linked: {0}'.format(self.current_package)
-
+ self.message = 'Package{0} linked: {1}'.format(
+ "s" if len(self.packages) > 1 else "",
+ ", ".join(self.packages)
+ )
return True
else:
self.failed = True
- self.message = 'Package could not be linked: {0}.'.format(self.current_package)
+ self.message = 'Package{0} could not be linked: {1}.'.format(
+ "s" if len(self.packages) > 1 else "",
+ ", ".join(self.packages)
+ )
raise HomebrewException(self.message)
-
- def _link_packages(self):
- for package in self.packages:
- self.current_package = package
- self._link_current_package()
-
- return True
# /linked -------------------------------- }}}
# unlinked ------------------------------- {{{
- def _unlink_current_package(self):
- if not HomebrewValidate.valid_package(self.current_package):
+ def _unlink_packages(self):
+ missing_packages = set(self.packages) - self.installed_packages
+ if missing_packages:
self.failed = True
- self.message = 'Invalid package: {0}.'.format(self.current_package)
- raise HomebrewException(self.message)
-
- if not self._current_package_is_installed():
- self.failed = True
- self.message = 'Package not installed: {0}.'.format(self.current_package)
+ self.message = 'Package{0} not installed: {1}.'.format(
+ "s" if len(missing_packages) > 1 else "",
+ ", ".join(missing_packages),
+ )
raise HomebrewException(self.message)
if self.module.check_mode:
self.changed = True
- self.message = 'Package would be unlinked: {0}'.format(
- self.current_package
+ self.message = 'Package{0} would be unlinked: {1}'.format(
+ "s" if len(self.packages) > 1 else "",
+ ", ".join(self.packages)
)
raise HomebrewException(self.message)
opts = (
[self.brew_path, 'unlink']
+ self.install_options
- + [self.current_package]
+ + self.packages
)
cmd = [opt for opt in opts if opt]
rc, out, err = self.module.run_command(cmd)
if rc == 0:
- self.changed_count += 1
- self.changed_pkgs.append(self.current_package)
+ self.changed_pkgs.extend(self.packages)
self.changed = True
- self.message = 'Package unlinked: {0}'.format(self.current_package)
-
+ self.message = 'Package{0} unlinked: {1}'.format(
+ "s" if len(self.packages) > 1 else "",
+ ", ".join(self.packages)
+ )
return True
else:
self.failed = True
- self.message = 'Package could not be unlinked: {0}.'.format(self.current_package)
+ self.message = 'Package{0} could not be unlinked: {1}.'.format(
+ "s" if len(self.packages) > 1 else "",
+ ", ".join(self.packages)
+ )
raise HomebrewException(self.message)
-
- def _unlink_packages(self):
- for package in self.packages:
- self.current_package = package
- self._unlink_current_package()
-
- return True
# /unlinked ------------------------------ }}}
# /commands ---------------------------------------------------- }}}
@@ -866,7 +853,7 @@ def main():
p = module.params
if p['name']:
- packages = p['name']
+ packages = [package_name.lower() for package_name in p['name']]
else:
packages = None
diff --git a/plugins/modules/homebrew_cask.py b/plugins/modules/homebrew_cask.py
index 9902cb1373..7455a61d69 100644
--- a/plugins/modules/homebrew_cask.py
+++ b/plugins/modules/homebrew_cask.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: homebrew_cask
author:
- "Indrajit Raychaudhuri (@indrajitr)"
@@ -31,60 +30,59 @@ attributes:
options:
name:
description:
- - Name of cask to install or remove.
- aliases: [ 'cask', 'package', 'pkg' ]
+ - Name of cask to install or remove.
+ aliases: ['cask', 'package', 'pkg']
type: list
elements: str
path:
description:
- - "':' separated list of paths to search for 'brew' executable."
+ - "':' separated list of paths to search for 'brew' executable."
default: '/usr/local/bin:/opt/homebrew/bin'
type: path
state:
description:
- - State of the cask.
- choices: [ 'absent', 'installed', 'latest', 'present', 'removed', 'uninstalled', 'upgraded' ]
+ - State of the cask.
+ choices: ['absent', 'installed', 'latest', 'present', 'removed', 'uninstalled', 'upgraded']
default: present
type: str
sudo_password:
description:
- - The sudo password to be passed to SUDO_ASKPASS.
+ - The sudo password to be passed to E(SUDO_ASKPASS).
required: false
type: str
update_homebrew:
description:
- - Update homebrew itself first.
- - Note that C(brew cask update) is a synonym for C(brew update).
+ - Update homebrew itself first.
+ - Note that C(brew cask update) is a synonym for C(brew update).
type: bool
default: false
install_options:
description:
- - Options flags to install a package.
- aliases: [ 'options' ]
+ - Options flags to install a package.
+ aliases: ['options']
type: list
elements: str
accept_external_apps:
description:
- - Allow external apps.
+ - Allow external apps.
type: bool
default: false
upgrade_all:
description:
- - Upgrade all casks.
- - Mutually exclusive with C(upgraded) state.
+ - Upgrade all casks.
+ - Mutually exclusive with C(upgraded) state.
type: bool
default: false
- aliases: [ 'upgrade' ]
+ aliases: ['upgrade']
greedy:
description:
- - Upgrade casks that auto update.
- - Passes C(--greedy) to C(brew outdated --cask) when checking
- if an installed cask has a newer version available,
- or to C(brew upgrade --cask) when upgrading all casks.
+ - Upgrade casks that auto update.
+ - Passes C(--greedy) to C(brew outdated --cask) when checking if an installed cask has a newer version available, or
+ to C(brew upgrade --cask) when upgrading all casks.
type: bool
default: false
-'''
-EXAMPLES = '''
+"""
+EXAMPLES = r"""
- name: Install cask
community.general.homebrew_cask:
name: alfred
@@ -151,7 +149,7 @@ EXAMPLES = '''
name: wireshark
state: present
sudo_password: "{{ ansible_become_pass }}"
-'''
+"""
import os
import re
@@ -190,6 +188,7 @@ class HomebrewCask(object):
/ # slash (for taps)
\- # dashes
@ # at symbol
+ \+ # plus symbol
'''
INVALID_CASK_REGEX = _create_regex_group_complement(VALID_CASK_CHARS)
@@ -426,10 +425,7 @@ class HomebrewCask(object):
cmd = base_opts + [self.current_cask]
rc, out, err = self.module.run_command(cmd)
- if rc == 0:
- return True
- else:
- return False
+ return rc == 0
def _get_brew_version(self):
if self.brew_version:
@@ -437,11 +433,13 @@ class HomebrewCask(object):
cmd = [self.brew_path, '--version']
- rc, out, err = self.module.run_command(cmd, check_rc=True)
+ dummy, out, dummy = self.module.run_command(cmd, check_rc=True)
- # get version string from first line of "brew --version" output
- version = out.split('\n')[0].split(' ')[1]
- self.brew_version = version
+ pattern = r"Homebrew (.*)(\d+\.\d+\.\d+)(-dirty)?"
+ rematch = re.search(pattern, out)
+ if not rematch:
+ self.module.fail_json(msg="Failed to match regex to get brew version", stdout=out)
+ self.brew_version = rematch.groups()[1]
return self.brew_version
def _brew_cask_command_is_deprecated(self):
diff --git a/plugins/modules/homebrew_services.py b/plugins/modules/homebrew_services.py
index 96e81bea63..750e771fc3 100644
--- a/plugins/modules/homebrew_services.py
+++ b/plugins/modules/homebrew_services.py
@@ -14,47 +14,46 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: homebrew_services
author:
- - "Kit Ham (@kitizz)"
+ - "Kit Ham (@kitizz)"
requirements:
- - homebrew must already be installed on the target system
+ - homebrew must already be installed on the target system
short_description: Services manager for Homebrew
version_added: 9.3.0
description:
- - Manages daemons and services via Homebrew.
+ - Manages daemons and services using Homebrew.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - An installed homebrew package whose service is to be updated.
- aliases: [ 'formula' ]
- type: str
- required: true
- path:
- description:
- - "A V(:) separated list of paths to search for C(brew) executable.
- Since a package (I(formula) in homebrew parlance) location is prefixed relative to the actual path of C(brew) command,
- providing an alternative C(brew) path enables managing different set of packages in an alternative location in the system."
- default: '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin'
- type: path
- state:
- description:
- - State of the package's service.
- choices: [ 'present', 'absent', 'restarted' ]
- default: present
- type: str
+ name:
+ description:
+ - An installed homebrew package whose service is to be updated.
+ aliases: ['formula']
+ type: str
+ required: true
+ path:
+ description:
+ - A V(:) separated list of paths to search for C(brew) executable. Since a package (I(formula) in homebrew parlance)
+ location is prefixed relative to the actual path of C(brew) command, providing an alternative C(brew) path enables
+ managing different set of packages in an alternative location in the system.
+ default: '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin'
+ type: path
+ state:
+ description:
+ - State of the package's service.
+ choices: ['present', 'absent', 'restarted']
+ default: present
+ type: str
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Install foo package
community.general.homebrew:
name: foo
@@ -73,22 +72,22 @@ EXAMPLES = """
- name: Remove the foo service (equivalent to `brew services stop foo`)
community.general.homebrew_services:
name: foo
- service_state: absent
+ state: absent
"""
-RETURN = """
+RETURN = r"""
pid:
- description:
- - If the service is now running, this is the PID of the service, otherwise -1.
- returned: success
- type: int
- sample: 1234
+ description:
+ - If the service is now running, this is the PID of the service, otherwise -1.
+ returned: success
+ type: int
+ sample: 1234
running:
- description:
- - Whether the service is running after running this command.
- returned: success
- type: bool
- sample: true
+ description:
+ - Whether the service is running after running this command.
+ returned: success
+ type: bool
+ sample: true
"""
import json
diff --git a/plugins/modules/homebrew_tap.py b/plugins/modules/homebrew_tap.py
index 151d09d328..f070ccccc7 100644
--- a/plugins/modules/homebrew_tap.py
+++ b/plugins/modules/homebrew_tap.py
@@ -13,56 +13,53 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: homebrew_tap
author:
- - "Indrajit Raychaudhuri (@indrajitr)"
- - "Daniel Jaouen (@danieljaouen)"
+ - "Indrajit Raychaudhuri (@indrajitr)"
+ - "Daniel Jaouen (@danieljaouen)"
short_description: Tap a Homebrew repository
description:
- - Tap external Homebrew repositories.
+ - Tap external Homebrew repositories.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - The GitHub user/organization repository to tap.
- required: true
- aliases: ['tap']
- type: list
- elements: str
- url:
- description:
- - The optional git URL of the repository to tap. The URL is not
- assumed to be on GitHub, and the protocol doesn't have to be HTTP.
- Any location and protocol that git can handle is fine.
- - O(name) option may not be a list of multiple taps (but a single
- tap instead) when this option is provided.
- required: false
- type: str
- state:
- description:
- - state of the repository.
- choices: [ 'present', 'absent' ]
- required: false
- default: 'present'
- type: str
- path:
- description:
- - "A V(:) separated list of paths to search for C(brew) executable."
- default: '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin'
- type: path
- version_added: '2.1.0'
-requirements: [ homebrew ]
-'''
+ name:
+ description:
+ - The GitHub user/organization repository to tap.
+ required: true
+ aliases: ['tap']
+ type: list
+ elements: str
+ url:
+ description:
+ - The optional git URL of the repository to tap. The URL is not assumed to be on GitHub, and the protocol does not have
+ to be HTTP. Any location and protocol that git can handle is fine.
+ - O(name) option may not be a list of multiple taps (but a single tap instead) when this option is provided.
+ required: false
+ type: str
+ state:
+ description:
+ - State of the repository.
+ choices: ['present', 'absent']
+ required: false
+ default: 'present'
+ type: str
+ path:
+ description:
+ - A V(:) separated list of paths to search for C(brew) executable.
+ default: '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin'
+ type: path
+ version_added: '2.1.0'
+requirements: [homebrew]
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Tap a Homebrew repository, state present
community.general.homebrew_tap:
name: homebrew/dupes
@@ -81,7 +78,7 @@ EXAMPLES = r'''
community.general.homebrew_tap:
name: telemachus/brew
url: 'https://bitbucket.org/telemachus/brew'
-'''
+"""
import re
diff --git a/plugins/modules/homectl.py b/plugins/modules/homectl.py
index 58176f3389..72f1882dec 100644
--- a/plugins/modules/homectl.py
+++ b/plugins/modules/homectl.py
@@ -8,186 +8,185 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: homectl
author:
- - "James Livulpi (@jameslivulpi)"
+ - "James Livulpi (@jameslivulpi)"
short_description: Manage user accounts with systemd-homed
version_added: 4.4.0
description:
- - Manages a user's home directory managed by systemd-homed.
+ - Manages a user's home directory managed by systemd-homed.
notes:
- - This module requires the deprecated L(crypt Python module,
- https://docs.python.org/3.12/library/crypt.html) library which was removed from Python 3.13.
- For Python 3.13 or newer, you need to install L(legacycrypt, https://pypi.org/project/legacycrypt/).
+ - This module requires the deprecated L(crypt Python module, https://docs.python.org/3.12/library/crypt.html) library which
+ was removed from Python 3.13. For Python 3.13 or newer, you need to install L(legacycrypt, https://pypi.org/project/legacycrypt/).
requirements:
- - legacycrypt (on Python 3.13 or newer)
+ - legacycrypt (on Python 3.13 or newer)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - The user name to create, remove, or update.
- required: true
- aliases: [ 'user', 'username' ]
- type: str
- password:
- description:
- - Set the user's password to this.
- - Homed requires this value to be in cleartext on user creation and updating a user.
- - The module takes the password and generates a password hash in SHA-512 with 10000 rounds of salt generation using crypt.
- - See U(https://systemd.io/USER_RECORD/).
- - This is required for O(state=present). When an existing user is updated this is checked against the stored hash in homed.
- type: str
- state:
- description:
- - The operation to take on the user.
- choices: [ 'absent', 'present' ]
- default: present
- type: str
- storage:
- description:
- - Indicates the storage mechanism for the user's home directory.
- - If the storage type is not specified, ``homed.conf(5)`` defines which default storage to use.
- - Only used when a user is first created.
- choices: [ 'classic', 'luks', 'directory', 'subvolume', 'fscrypt', 'cifs' ]
- type: str
- disksize:
- description:
- - The intended home directory disk space.
- - Human readable value such as V(10G), V(10M), or V(10B).
- type: str
- resize:
- description:
- - When used with O(disksize) this will attempt to resize the home directory immediately.
- default: false
- type: bool
- realname:
- description:
- - The user's real ('human') name.
- - This can also be used to add a comment to maintain compatibility with C(useradd).
- aliases: [ 'comment' ]
- type: str
- realm:
- description:
- - The 'realm' a user is defined in.
- type: str
- email:
- description:
- - The email address of the user.
- type: str
- location:
- description:
- - A free-form location string describing the location of the user.
- type: str
- iconname:
- description:
- - The name of an icon picked by the user, for example for the purpose of an avatar.
- - Should follow the semantics defined in the Icon Naming Specification.
- - See U(https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html) for specifics.
- type: str
- homedir:
- description:
- - Path to use as home directory for the user.
- - This is the directory the user's home directory is mounted to while the user is logged in.
- - This is not where the user's data is actually stored, see O(imagepath) for that.
- - Only used when a user is first created.
- type: path
- imagepath:
- description:
- - Path to place the user's home directory.
- - See U(https://www.freedesktop.org/software/systemd/man/homectl.html#--image-path=PATH) for more information.
- - Only used when a user is first created.
- type: path
- uid:
- description:
- - Sets the UID of the user.
- - If using O(gid) homed requires the value to be the same.
- - Only used when a user is first created.
- type: int
- gid:
- description:
- - Sets the gid of the user.
- - If using O(uid) homed requires the value to be the same.
- - Only used when a user is first created.
- type: int
- mountopts:
- description:
- - String separated by comma each indicating mount options for a users home directory.
- - Valid options are V(nosuid), V(nodev) or V(noexec).
- - Homed by default uses V(nodev) and V(nosuid) while V(noexec) is off.
- type: str
- umask:
- description:
- - Sets the umask for the user's login sessions
- - Value from V(0000) to V(0777).
- type: int
- memberof:
- description:
- - String separated by comma each indicating a UNIX group this user shall be a member of.
- - Groups the user should be a member of should be supplied as comma separated list.
- aliases: [ 'groups' ]
- type: str
- skeleton:
- description:
- - The absolute path to the skeleton directory to populate a new home directory from.
- - This is only used when a home directory is first created.
- - If not specified homed by default uses V(/etc/skel).
- aliases: [ 'skel' ]
- type: path
- shell:
- description:
- - Shell binary to use for terminal logins of given user.
- - If not specified homed by default uses V(/bin/bash).
- type: str
- environment:
- description:
- - String separated by comma each containing an environment variable and its value to
- set for the user's login session, in a format compatible with ``putenv()``.
- - Any environment variable listed here is automatically set by pam_systemd for all
- login sessions of the user.
- aliases: [ 'setenv' ]
- type: str
- timezone:
- description:
- - Preferred timezone to use for the user.
- - Should be a tzdata compatible location string such as V(America/New_York).
- type: str
- locked:
- description:
- - Whether the user account should be locked or not.
- type: bool
- language:
- description:
- - The preferred language/locale for the user.
- - This should be in a format compatible with the E(LANG) environment variable.
- type: str
- passwordhint:
- description:
- - Password hint for the given user.
- type: str
- sshkeys:
- description:
- - String separated by comma each listing a SSH public key that is authorized to access the account.
- - The keys should follow the same format as the lines in a traditional C(~/.ssh/authorized_key) file.
- type: str
- notbefore:
- description:
- - A time since the UNIX epoch before which the record should be considered invalid for the purpose of logging in.
- type: int
- notafter:
- description:
- - A time since the UNIX epoch after which the record should be considered invalid for the purpose of logging in.
- type: int
-'''
+ name:
+ description:
+ - The user name to create, remove, or update.
+ required: true
+ aliases: ['user', 'username']
+ type: str
+ password:
+ description:
+ - Set the user's password to this.
+ - Homed requires this value to be in cleartext on user creation and updating a user.
+ - The module takes the password and generates a password hash in SHA-512 with 10000 rounds of salt generation using
+ crypt.
+ - See U(https://systemd.io/USER_RECORD/).
+ - This is required for O(state=present). When an existing user is updated this is checked against the stored hash in
+ homed.
+ type: str
+ state:
+ description:
+ - The operation to take on the user.
+ choices: ['absent', 'present']
+ default: present
+ type: str
+ storage:
+ description:
+ - Indicates the storage mechanism for the user's home directory.
+ - If the storage type is not specified, C(homed.conf(5\)) defines which default storage to use.
+ - Only used when a user is first created.
+ choices: ['classic', 'luks', 'directory', 'subvolume', 'fscrypt', 'cifs']
+ type: str
+ disksize:
+ description:
+ - The intended home directory disk space.
+ - Human readable value such as V(10G), V(10M), or V(10B).
+ type: str
+ resize:
+ description:
+ - When used with O(disksize) this will attempt to resize the home directory immediately.
+ default: false
+ type: bool
+ realname:
+ description:
+ - The user's real ('human') name.
+ - This can also be used to add a comment to maintain compatibility with C(useradd).
+ aliases: ['comment']
+ type: str
+ realm:
+ description:
+ - The 'realm' a user is defined in.
+ type: str
+ email:
+ description:
+ - The email address of the user.
+ type: str
+ location:
+ description:
+ - A free-form location string describing the location of the user.
+ type: str
+ iconname:
+ description:
+ - The name of an icon picked by the user, for example for the purpose of an avatar.
+ - Should follow the semantics defined in the Icon Naming Specification.
+ - See U(https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html) for specifics.
+ type: str
+ homedir:
+ description:
+ - Path to use as home directory for the user.
+ - This is the directory the user's home directory is mounted to while the user is logged in.
+ - This is not where the user's data is actually stored, see O(imagepath) for that.
+ - Only used when a user is first created.
+ type: path
+ imagepath:
+ description:
+ - Path to place the user's home directory.
+ - See U(https://www.freedesktop.org/software/systemd/man/homectl.html#--image-path=PATH) for more information.
+ - Only used when a user is first created.
+ type: path
+ uid:
+ description:
+ - Sets the UID of the user.
+ - If using O(gid) homed requires the value to be the same.
+ - Only used when a user is first created.
+ type: int
+ gid:
+ description:
+ - Sets the gid of the user.
+ - If using O(uid) homed requires the value to be the same.
+ - Only used when a user is first created.
+ type: int
+ mountopts:
+ description:
+ - String separated by comma each indicating mount options for a users home directory.
+ - Valid options are V(nosuid), V(nodev) or V(noexec).
+ - Homed by default uses V(nodev) and V(nosuid) while V(noexec) is off.
+ type: str
+ umask:
+ description:
+ - Sets the umask for the user's login sessions.
+ - Value from V(0000) to V(0777).
+ type: int
+ memberof:
+ description:
+ - String separated by comma each indicating a UNIX group this user shall be a member of.
+ - Groups the user should be a member of should be supplied as comma separated list.
+ aliases: ['groups']
+ type: str
+ skeleton:
+ description:
+ - The absolute path to the skeleton directory to populate a new home directory from.
+ - This is only used when a home directory is first created.
+ - If not specified homed by default uses V(/etc/skel).
+ aliases: ['skel']
+ type: path
+ shell:
+ description:
+ - Shell binary to use for terminal logins of given user.
+ - If not specified homed by default uses V(/bin/bash).
+ type: str
+ environment:
+ description:
+ - String separated by comma each containing an environment variable and its value to set for the user's login session,
+ in a format compatible with C(putenv(\)).
+ - Any environment variable listed here is automatically set by pam_systemd for all login sessions of the user.
+ aliases: ['setenv']
+ type: str
+ timezone:
+ description:
+ - Preferred timezone to use for the user.
+ - Should be a tzdata compatible location string such as V(America/New_York).
+ type: str
+ locked:
+ description:
+ - Whether the user account should be locked or not.
+ type: bool
+ language:
+ description:
+ - The preferred language/locale for the user.
+ - This should be in a format compatible with the E(LANG) environment variable.
+ type: str
+ passwordhint:
+ description:
+ - Password hint for the given user.
+ type: str
+ sshkeys:
+ description:
+ - String separated by comma each listing a SSH public key that is authorized to access the account.
+ - The keys should follow the same format as the lines in a traditional C(~/.ssh/authorized_key) file.
+ type: str
+ notbefore:
+ description:
+ - A time since the UNIX epoch before which the record should be considered invalid for the purpose of logging in.
+ type: int
+ notafter:
+ description:
+ - A time since the UNIX epoch after which the record should be considered invalid for the purpose of logging in.
+ type: int
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add the user 'james'
community.general.homectl:
name: johnd
@@ -215,11 +214,11 @@ EXAMPLES = '''
community.general.homectl:
name: janet
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
data:
- description: A json dictionary returned from C(homectl inspect -j).
+ description: Dictionary returned from C(homectl inspect -j).
returned: success
type: dict
sample: {
@@ -267,7 +266,7 @@ data:
"userName": "james",
}
}
-'''
+"""
import json
import traceback
diff --git a/plugins/modules/honeybadger_deployment.py b/plugins/modules/honeybadger_deployment.py
index cf52745ac7..b303313f70 100644
--- a/plugins/modules/honeybadger_deployment.py
+++ b/plugins/modules/honeybadger_deployment.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: honeybadger_deployment
author: "Benjamin Curtis (@stympy)"
short_description: Notify Honeybadger.io about app deployments
@@ -31,20 +30,20 @@ options:
environment:
type: str
description:
- - The environment name, typically 'production', 'staging', etc.
+ - The environment name, typically V(production), V(staging), and so on.
required: true
user:
type: str
description:
- - The username of the person doing the deployment
+ - The username of the person doing the deployment.
repo:
type: str
description:
- - URL of the project repository
+ - URL of the project repository.
revision:
type: str
description:
- - A hash, number, tag, or other identifier showing what revision was deployed
+ - A hash, number, tag, or other identifier showing what revision was deployed.
url:
type: str
description:
@@ -52,14 +51,13 @@ options:
default: "https://api.honeybadger.io/v1/deploys"
validate_certs:
description:
- - If V(false), SSL certificates for the target url will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates for the target URL will not be validated. This should only be used on personally controlled
+ sites using self-signed certificates.
type: bool
default: true
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Notify Honeybadger.io about an app deployment
community.general.honeybadger_deployment:
token: AAAAAA
@@ -67,9 +65,9 @@ EXAMPLES = '''
user: ansible
revision: b6826b8
repo: 'git@github.com:user/repo.git'
-'''
+"""
-RETURN = '''# '''
+RETURN = """# """
import traceback
diff --git a/plugins/modules/hpilo_boot.py b/plugins/modules/hpilo_boot.py
index ace79a493a..ecef60f66a 100644
--- a/plugins/modules/hpilo_boot.py
+++ b/plugins/modules/hpilo_boot.py
@@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hpilo_boot
author: Dag Wieers (@dagwieers)
short_description: Boot system using specific media through HP iLO interface
description:
- - "This module boots a system through its HP iLO interface. The boot media
- can be one of: cdrom, floppy, hdd, network or usb."
+ - 'This module boots a system through its HP iLO interface. The boot media can be one of: V(cdrom), V(floppy), V(hdd), V(network),
+ or V(usb).'
- This module requires the hpilo python module.
extends_documentation_fragment:
- community.general.attributes
@@ -43,33 +42,32 @@ options:
type: str
media:
description:
- - The boot media to boot the system from
- choices: [ "cdrom", "floppy", "rbsu", "hdd", "network", "normal", "usb" ]
+ - The boot media to boot the system from.
+ choices: ["cdrom", "floppy", "rbsu", "hdd", "network", "normal", "usb"]
type: str
image:
description:
- - The URL of a cdrom, floppy or usb boot media image.
- protocol://username:password@hostname:port/filename
- - protocol is either 'http' or 'https'
- - username:password is optional
- - port is optional
+ - The URL of a cdrom, floppy or usb boot media image in the form V(protocol://username:password@hostname:port/filename).
+ - V(protocol) is either V(http) or V(https).
+ - V(username:password) is optional.
+ - V(port) is optional.
type: str
state:
description:
- The state of the boot media.
- - "no_boot: Do not boot from the device"
- - "boot_once: Boot from the device once and then notthereafter"
- - "boot_always: Boot from the device each time the server is rebooted"
- - "connect: Connect the virtual media device and set to boot_always"
- - "disconnect: Disconnects the virtual media device and set to no_boot"
- - "poweroff: Power off the server"
+ - 'V(no_boot): Do not boot from the device.'
+ - 'V(boot_once): Boot from the device once and then notthereafter.'
+ - 'V(boot_always): Boot from the device each time the server is rebooted.'
+ - 'V(connect): Connect the virtual media device and set to boot_always.'
+ - 'V(disconnect): Disconnects the virtual media device and set to no_boot.'
+ - 'V(poweroff): Power off the server.'
default: boot_once
type: str
- choices: [ "boot_always", "boot_once", "connect", "disconnect", "no_boot", "poweroff" ]
+ choices: ["boot_always", "boot_once", "connect", "disconnect", "no_boot", "poweroff"]
force:
description:
- - Whether to force a reboot (even when the system is already booted).
- - As a safeguard, without force, hpilo_boot will refuse to reboot a server that is already running.
+ - Whether to force a reboot (even when the system is already booted).
+ - As a safeguard, without force, hpilo_boot will refuse to reboot a server that is already running.
default: false
type: bool
ssl_version:
@@ -77,16 +75,16 @@ options:
- Change the ssl_version used.
default: TLSv1
type: str
- choices: [ "SSLv3", "SSLv23", "TLSv1", "TLSv1_1", "TLSv1_2" ]
+ choices: ["SSLv3", "SSLv23", "TLSv1", "TLSv1_1", "TLSv1_2"]
requirements:
-- python-hpilo
+ - python-hpilo
notes:
-- To use a USB key image you need to specify floppy as boot media.
-- This module ought to be run from a system that can access the HP iLO
- interface directly, either by using C(local_action) or using C(delegate_to).
-'''
+ - To use a USB key image you need to specify floppy as boot media.
+ - This module ought to be run from a system that can access the HP iLO interface directly, either by using C(local_action)
+ or using C(delegate_to).
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Task to boot a system using an ISO from an HP iLO interface only if the system is an HP server
community.general.hpilo_boot:
host: YOUR_ILO_ADDRESS
@@ -104,11 +102,11 @@ EXAMPLES = r'''
password: YOUR_ILO_PASSWORD
state: poweroff
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
# Default return values
-'''
+"""
import time
import traceback
diff --git a/plugins/modules/hpilo_info.py b/plugins/modules/hpilo_info.py
index d329764b4c..70eecb8b0e 100644
--- a/plugins/modules/hpilo_info.py
+++ b/plugins/modules/hpilo_info.py
@@ -9,23 +9,21 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: hpilo_info
author: Dag Wieers (@dagwieers)
short_description: Gather information through an HP iLO interface
description:
-- This module gathers information on a specific system using its HP iLO interface.
- These information includes hardware and network related information useful
- for provisioning (e.g. macaddress, uuid).
-- This module requires the C(hpilo) python module.
+ - This module gathers information on a specific system using its HP iLO interface. These information includes hardware and
+ network related information useful for provisioning (for example macaddress, uuid).
+ - This module requires the C(hpilo) python module.
extends_documentation_fragment:
-- community.general.attributes
-- community.general.attributes.info_module
+ - community.general.attributes
+ - community.general.attributes.info_module
options:
host:
description:
- - The HP iLO hostname/address that is linked to the physical system.
+ - The HP iLO hostname/address that is linked to the physical system.
type: str
required: true
login:
@@ -43,15 +41,15 @@ options:
- Change the ssl_version used.
default: TLSv1
type: str
- choices: [ "SSLv3", "SSLv23", "TLSv1", "TLSv1_1", "TLSv1_2" ]
+ choices: ["SSLv3", "SSLv23", "TLSv1", "TLSv1_1", "TLSv1_2"]
requirements:
-- hpilo
+ - hpilo
notes:
-- This module ought to be run from a system that can access the HP iLO
- interface directly, either by using C(local_action) or using C(delegate_to).
-'''
+ - This module ought to be run from a system that can access the HP iLO interface directly, either by using C(local_action)
+ or using C(delegate_to).
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather facts from a HP iLO interface only if the system is an HP server
community.general.hpilo_info:
host: YOUR_ILO_ADDRESS
@@ -64,71 +62,71 @@ EXAMPLES = r'''
- ansible.builtin.fail:
msg: 'CMDB serial ({{ cmdb_serialno }}) does not match hardware serial ({{ results.hw_system_serial }}) !'
when: cmdb_serialno != results.hw_system_serial
-'''
+"""
-RETURN = r'''
+RETURN = r"""
# Typical output of HP iLO_info for a physical system
hw_bios_date:
- description: BIOS date
- returned: always
- type: str
- sample: 05/05/2011
+ description: BIOS date.
+ returned: always
+ type: str
+ sample: 05/05/2011
hw_bios_version:
- description: BIOS version
- returned: always
- type: str
- sample: P68
+ description: BIOS version.
+ returned: always
+ type: str
+ sample: P68
hw_ethX:
- description: Interface information (for each interface)
- returned: always
- type: dict
- sample:
- - macaddress: 00:11:22:33:44:55
- macaddress_dash: 00-11-22-33-44-55
+ description: Interface information (for each interface).
+ returned: always
+ type: dict
+ sample:
+ - macaddress: 00:11:22:33:44:55
+ macaddress_dash: 00-11-22-33-44-55
hw_eth_ilo:
- description: Interface information (for the iLO network interface)
- returned: always
- type: dict
- sample:
- - macaddress: 00:11:22:33:44:BA
- - macaddress_dash: 00-11-22-33-44-BA
+ description: Interface information (for the iLO network interface).
+ returned: always
+ type: dict
+ sample:
+ - macaddress: 00:11:22:33:44:BA
+ - macaddress_dash: 00-11-22-33-44-BA
hw_product_name:
- description: Product name
- returned: always
- type: str
- sample: ProLiant DL360 G7
+ description: Product name.
+ returned: always
+ type: str
+ sample: ProLiant DL360 G7
hw_product_uuid:
- description: Product UUID
- returned: always
- type: str
- sample: ef50bac8-2845-40ff-81d9-675315501dac
+ description: Product UUID.
+ returned: always
+ type: str
+ sample: ef50bac8-2845-40ff-81d9-675315501dac
hw_system_serial:
- description: System serial number
- returned: always
- type: str
- sample: ABC12345D6
+ description: System serial number.
+ returned: always
+ type: str
+ sample: ABC12345D6
hw_uuid:
- description: Hardware UUID
- returned: always
- type: str
- sample: 123456ABC78901D2
+ description: Hardware UUID.
+ returned: always
+ type: str
+ sample: 123456ABC78901D2
host_power_status:
- description:
- - Power status of host.
- - Will be one of V(ON), V(OFF) and V(UNKNOWN).
- returned: always
- type: str
- sample: "ON"
- version_added: 3.5.0
-'''
+ description:
+ - Power status of host.
+ - Will be one of V(ON), V(OFF) and V(UNKNOWN).
+ returned: always
+ type: str
+ sample: "ON"
+ version_added: 3.5.0
+"""
import re
import traceback
diff --git a/plugins/modules/hponcfg.py b/plugins/modules/hponcfg.py
index 206565a235..654ba2c710 100644
--- a/plugins/modules/hponcfg.py
+++ b/plugins/modules/hponcfg.py
@@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: hponcfg
author: Dag Wieers (@dagwieers)
-short_description: Configure HP iLO interface using hponcfg
+short_description: Configure HP iLO interface using C(hponcfg)
description:
- - This modules configures the HP iLO interface using hponcfg.
+ - This modules configures the HP iLO interface using C(hponcfg).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -26,32 +25,32 @@ attributes:
options:
path:
description:
- - The XML file as accepted by hponcfg.
+ - The XML file as accepted by C(hponcfg).
required: true
aliases: ['src']
type: path
minfw:
description:
- - The minimum firmware level needed.
+ - The minimum firmware level needed.
required: false
type: str
executable:
description:
- - Path to the hponcfg executable (C(hponcfg) which uses $PATH).
+ - Path to the hponcfg executable (C(hponcfg) which uses E(PATH)).
default: hponcfg
type: str
verbose:
description:
- - Run hponcfg in verbose mode (-v).
+ - Run C(hponcfg) in verbose mode (-v).
default: false
type: bool
requirements:
- - hponcfg tool
+ - hponcfg tool
notes:
- - You need a working hponcfg on the target system.
-'''
+ - You need a working C(hponcfg) on the target system.
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Example hponcfg configuration XML
ansible.builtin.copy:
content: |
@@ -78,7 +77,7 @@ EXAMPLES = r'''
community.general.hponcfg:
src: /tmp/enable-ssh.xml
executable: /opt/hp/tools/hponcfg
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt
from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper
diff --git a/plugins/modules/htpasswd.py b/plugins/modules/htpasswd.py
index 9633ce2fb5..de94765130 100644
--- a/plugins/modules/htpasswd.py
+++ b/plugins/modules/htpasswd.py
@@ -9,7 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: htpasswd
short_description: Manage user files for basic authentication
description:
@@ -24,13 +24,13 @@ options:
path:
type: path
required: true
- aliases: [ dest, destfile ]
+ aliases: [dest, destfile]
description:
- Path to the file that contains the usernames and passwords.
name:
type: str
required: true
- aliases: [ username ]
+ aliases: [username]
description:
- User name to add or remove.
password:
@@ -44,19 +44,17 @@ options:
required: false
default: "apr_md5_crypt"
description:
- - Hashing scheme to be used. As well as the four choices listed
- here, you can also use any other hash supported by passlib, such as
- V(portable_apache22) and V(host_apache24); or V(md5_crypt) and V(sha256_crypt),
- which are Linux passwd hashes. Only some schemes in addition to
- the four choices below will be compatible with Apache or Nginx, and
- supported schemes depend on passlib version and its dependencies.
+ - Hashing scheme to be used. As well as the four choices listed here, you can also use any other hash supported by passlib,
+ such as V(portable_apache22) and V(host_apache24); or V(md5_crypt) and V(sha256_crypt), which are Linux passwd hashes.
+ Only some schemes in addition to the four choices below will be compatible with Apache or Nginx, and supported schemes
+ depend on passlib version and its dependencies.
- See U(https://passlib.readthedocs.io/en/stable/lib/passlib.apache.html#passlib.apache.HtpasswdFile) parameter C(default_scheme).
- 'Some of the available choices might be: V(apr_md5_crypt), V(des_crypt), V(ldap_sha1), V(plaintext).'
aliases: [crypt_scheme]
state:
type: str
required: false
- choices: [ present, absent ]
+ choices: [present, absent]
default: "present"
description:
- Whether the user entry should be present or not.
@@ -65,22 +63,21 @@ options:
type: bool
default: true
description:
- - Used with O(state=present). If V(true), the file will be created
- if it does not exist. Conversely, if set to V(false) and the file
- does not exist it will fail.
+ - Used with O(state=present). If V(true), the file will be created if it does not exist. Conversely, if set to V(false)
+ and the file does not exist it will fail.
notes:
- - "This module depends on the C(passlib) Python library, which needs to be installed on all target systems."
- - "On Debian < 11, Ubuntu <= 20.04, or Fedora: install C(python-passlib)."
- - "On Debian, Ubuntu: install C(python3-passlib)."
- - "On RHEL or CentOS: Enable EPEL, then install C(python-passlib)."
-requirements: [ passlib>=1.6 ]
+ - This module depends on the C(passlib) Python library, which needs to be installed on all target systems.
+ - 'On Debian < 11, Ubuntu <= 20.04, or Fedora: install C(python-passlib).'
+ - 'On Debian, Ubuntu: install C(python3-passlib).'
+ - 'On RHEL or CentOS: Enable EPEL, then install C(python-passlib).'
+requirements: [passlib>=1.6]
author: "Ansible Core Team"
extends_documentation_fragment:
- files
- community.general.attributes
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Add a user to a password file and ensure permissions are set
community.general.htpasswd:
path: /etc/nginx/passwdfile
@@ -246,8 +243,9 @@ def main():
(msg, changed) = absent(path, username, check_mode)
else:
module.fail_json(msg="Invalid state: %s" % state)
+ return # needed to make pylint happy
- check_file_attrs(module, changed, msg)
+ (msg, changed) = check_file_attrs(module, changed, msg)
module.exit_json(msg=msg, changed=changed)
except Exception as e:
module.fail_json(msg=to_native(e))
diff --git a/plugins/modules/hwc_ecs_instance.py b/plugins/modules/hwc_ecs_instance.py
index cc6ef926dd..f01b7c48fd 100644
--- a/plugins/modules/hwc_ecs_instance.py
+++ b/plugins/modules/hwc_ecs_instance.py
@@ -12,230 +12,207 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_ecs_instance
description:
- - instance management.
+ - Instance management.
short_description: Creates a resource of Ecs/Instance in Huawei Cloud
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Whether the given object should exist in Huawei Cloud.
- type: str
- choices: ['present', 'absent']
- default: 'present'
- timeouts:
- description:
- - The timeouts for each operations.
- type: dict
- default: {}
- suboptions:
- create:
- description:
- - The timeouts for create operation.
- type: str
- default: '30m'
- update:
- description:
- - The timeouts for update operation.
- type: str
- default: '30m'
- delete:
- description:
- - The timeouts for delete operation.
- type: str
- default: '30m'
- availability_zone:
- description:
- - Specifies the name of the AZ where the ECS is located.
- type: str
- required: true
- flavor_name:
- description:
- - Specifies the name of the system flavor.
- type: str
- required: true
- image_id:
- description:
- - Specifies the ID of the system image.
- type: str
- required: true
- name:
- description:
- - Specifies the ECS name. Value requirements consists of 1 to 64
- characters, including letters, digits, underscores (V(_)), hyphens
- (V(-)), periods (V(.)).
- type: str
- required: true
- nics:
- description:
- - Specifies the NIC information of the ECS. Constraints the
- network of the NIC must belong to the VPC specified by vpc_id. A
- maximum of 12 NICs can be attached to an ECS.
- type: list
- elements: dict
- required: true
- suboptions:
- ip_address:
- description:
- - Specifies the IP address of the NIC. The value is an IPv4
- address. Its value must be an unused IP
- address in the network segment of the subnet.
- type: str
- required: true
- subnet_id:
- description:
- - Specifies the ID of subnet.
- type: str
- required: true
- root_volume:
- description:
- - Specifies the configuration of the ECS's system disks.
- type: dict
- required: true
- suboptions:
- volume_type:
- description:
- - Specifies the ECS system disk type.
- - SATA is common I/O disk type.
- - SAS is high I/O disk type.
- - SSD is ultra-high I/O disk type.
- - co-p1 is high I/O (performance-optimized I) disk type.
- - uh-l1 is ultra-high I/O (latency-optimized) disk type.
- - NOTE is For HANA, HL1, and HL2 ECSs, use co-p1 and uh-l1
- disks. For other ECSs, do not use co-p1 or uh-l1 disks.
- type: str
- required: true
- size:
- description:
- - Specifies the system disk size, in GB. The value range is
- 1 to 1024. The system disk size must be
- greater than or equal to the minimum system disk size
- supported by the image (min_disk attribute of the image).
- If this parameter is not specified or is set to 0, the
- default system disk size is the minimum value of the
- system disk in the image (min_disk attribute of the
- image).
- type: int
- required: false
- snapshot_id:
- description:
- - Specifies the snapshot ID or ID of the original data disk
- contained in the full-ECS image.
- type: str
- required: false
- vpc_id:
- description:
- - Specifies the ID of the VPC to which the ECS belongs.
- type: str
- required: true
- admin_pass:
- description:
- - Specifies the initial login password of the administrator account
- for logging in to an ECS using password authentication. The Linux
- administrator is root, and the Windows administrator is
- Administrator. Password complexity requirements, consists of 8 to
- 26 characters. The password must contain at least three of the
- following character types 'uppercase letters, lowercase letters,
- digits, and special characters (!@$%^-_=+[{}]:,./?)'. The password
- cannot contain the username or the username in reverse. The
- Windows ECS password cannot contain the username, the username in
- reverse, or more than two consecutive characters in the username.
- type: str
- required: false
- data_volumes:
- description:
- - Specifies the data disks of ECS instance.
- type: list
- elements: dict
- required: false
- suboptions:
- volume_id:
- description:
- - Specifies the disk ID.
- type: str
- required: true
- device:
- description:
- - Specifies the disk device name.
- type: str
- required: false
+ state:
description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ timeouts:
+ description:
+ - The timeouts for each operations.
+ type: dict
+ default: {}
+ suboptions:
+ create:
description:
- - Specifies the description of an ECS, which is a null string by
- default. Can contain a maximum of 85 characters. Cannot contain
- special characters, such as < and >.
+ - The timeouts for create operation.
+ type: str
+ default: '30m'
+ update:
+ description:
+ - The timeouts for update operation.
+ type: str
+ default: '30m'
+ delete:
+ description:
+ - The timeouts for delete operation.
+ type: str
+ default: '30m'
+ availability_zone:
+ description:
+ - Specifies the name of the AZ where the ECS is located.
+ type: str
+ required: true
+ flavor_name:
+ description:
+ - Specifies the name of the system flavor.
+ type: str
+ required: true
+ image_id:
+ description:
+ - Specifies the ID of the system image.
+ type: str
+ required: true
+ name:
+ description:
+ - Specifies the ECS name. Value requirements consists of 1 to 64 characters, including letters, digits, underscores
+ (V(_)), hyphens (V(-)), periods (V(.)).
+ type: str
+ required: true
+ nics:
+ description:
+ - Specifies the NIC information of the ECS. Constraints the network of the NIC must belong to the VPC specified by vpc_id.
+ A maximum of 12 NICs can be attached to an ECS.
+ type: list
+ elements: dict
+ required: true
+ suboptions:
+ ip_address:
+ description:
+ - Specifies the IP address of the NIC. The value is an IPv4 address. Its value must be an unused IP address in the
+ network segment of the subnet.
+ type: str
+ required: true
+ subnet_id:
+ description:
+ - Specifies the ID of subnet.
+ type: str
+ required: true
+ root_volume:
+ description:
+ - Specifies the configuration of the ECS's system disks.
+ type: dict
+ required: true
+ suboptions:
+ volume_type:
+ description:
+ - Specifies the ECS system disk type.
+ - SATA is common I/O disk type.
+ - SAS is high I/O disk type.
+ - SSD is ultra-high I/O disk type.
+ - Co-p1 is high I/O (performance-optimized I) disk type.
+ - Uh-l1 is ultra-high I/O (latency-optimized) disk type.
+ - NOTE is For HANA, HL1, and HL2 ECSs, use co-p1 and uh-l1 disks. For other ECSs, do not use co-p1 or uh-l1 disks.
+ type: str
+ required: true
+ size:
+ description:
+ - Specifies the system disk size, in GB. The value range is 1 to 1024. The system disk size must be greater than
+ or equal to the minimum system disk size supported by the image (min_disk attribute of the image). If this parameter
+ is not specified or is set to 0, the default system disk size is the minimum value of the system disk in the image
+ (min_disk attribute of the image).
+ type: int
+ required: false
+ snapshot_id:
+ description:
+ - Specifies the snapshot ID or ID of the original data disk contained in the full-ECS image.
type: str
required: false
- eip_id:
+ vpc_id:
+ description:
+ - Specifies the ID of the VPC to which the ECS belongs.
+ type: str
+ required: true
+ admin_pass:
+ description:
+ - Specifies the initial login password of the administrator account for logging in to an ECS using password authentication.
+ The Linux administrator is root, and the Windows administrator is Administrator. Password complexity requirements,
+ consists of 8 to 26 characters. The password must contain at least three of the following character types 'uppercase
+ letters, lowercase letters, digits, and special characters (V(!@$%^-_=+[{}]:,./?))'. The password cannot contain the
+ username or the username in reverse. The Windows ECS password cannot contain the username, the username in reverse,
+ or more than two consecutive characters in the username.
+ type: str
+ required: false
+ data_volumes:
+ description:
+ - Specifies the data disks of ECS instance.
+ type: list
+ elements: dict
+ required: false
+ suboptions:
+ volume_id:
description:
- - Specifies the ID of the elastic IP address assigned to the ECS.
- Only elastic IP addresses in the DOWN state can be
- assigned.
- type: str
- required: false
- enable_auto_recovery:
- description:
- - Specifies whether automatic recovery is enabled on the ECS.
- type: bool
- required: false
- enterprise_project_id:
- description:
- - Specifies the ID of the enterprise project to which the ECS
- belongs.
- type: str
- required: false
- security_groups:
- description:
- - Specifies the security groups of the ECS. If this
- parameter is left blank, the default security group is bound to
- the ECS by default.
- type: list
- elements: str
- required: false
- server_metadata:
- description:
- - Specifies the metadata of ECS to be created.
- type: dict
- required: false
- server_tags:
- description:
- - Specifies the tags of an ECS. When you create ECSs, one ECS
- supports up to 10 tags.
- type: dict
- required: false
- ssh_key_name:
- description:
- - Specifies the name of the SSH key used for logging in to the ECS.
- type: str
- required: false
- user_data:
- description:
- - Specifies the user data to be injected during the ECS creation
- process. Text, text files, and gzip files can be injected.
- The content to be injected must be encoded with
- base64. The maximum size of the content to be injected (before
- encoding) is 32 KB. For Linux ECSs, this parameter does not take
- effect when adminPass is used.
+ - Specifies the disk ID.
+ type: str
+ required: true
+ device:
+ description:
+ - Specifies the disk device name.
type: str
required: false
+ description:
+ description:
+ - Specifies the description of an ECS, which is a null string by default. Can contain a maximum of 85 characters. Cannot
+ contain special characters, such as V(<) and V(>).
+ type: str
+ required: false
+ eip_id:
+ description:
+ - Specifies the ID of the elastic IP address assigned to the ECS. Only elastic IP addresses in the DOWN state can be
+ assigned.
+ type: str
+ required: false
+ enable_auto_recovery:
+ description:
+ - Specifies whether automatic recovery is enabled on the ECS.
+ type: bool
+ required: false
+ enterprise_project_id:
+ description:
+ - Specifies the ID of the enterprise project to which the ECS belongs.
+ type: str
+ required: false
+ security_groups:
+ description:
+ - Specifies the security groups of the ECS. If this parameter is left blank, the default security group is bound to
+ the ECS by default.
+ type: list
+ elements: str
+ required: false
+ server_metadata:
+ description:
+ - Specifies the metadata of ECS to be created.
+ type: dict
+ required: false
+ server_tags:
+ description:
+ - Specifies the tags of an ECS. When you create ECSs, one ECS supports up to 10 tags.
+ type: dict
+ required: false
+ ssh_key_name:
+ description:
+ - Specifies the name of the SSH key used for logging in to the ECS.
+ type: str
+ required: false
+ user_data:
+ description:
+ - Specifies the user data to be injected during the ECS creation process. Text, text files, and gzip files can be injected.
+ The content to be injected must be encoded with base64. The maximum size of the content to be injected (before encoding)
+ is 32 KB. For Linux ECSs, this parameter does not take effect when adminPass is used.
+ type: str
+ required: false
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# create an ecs instance
- name: Create a vpc
hwc_network_vpc:
@@ -285,238 +262,216 @@ EXAMPLES = '''
vpc_id: "{{ vpc.id }}"
root_volume:
volume_type: "SAS"
-'''
+"""
-RETURN = '''
- availability_zone:
- description:
- - Specifies the name of the AZ where the ECS is located.
- type: str
- returned: success
- flavor_name:
- description:
- - Specifies the name of the system flavor.
- type: str
- returned: success
- image_id:
- description:
- - Specifies the ID of the system image.
- type: str
- returned: success
- name:
- description:
- - Specifies the ECS name. Value requirements "Consists of 1 to 64
- characters, including letters, digits, underscores (V(_)), hyphens
- (V(-)), periods (V(.)).".
- type: str
- returned: success
- nics:
- description:
- - Specifies the NIC information of the ECS. The
- network of the NIC must belong to the VPC specified by vpc_id. A
- maximum of 12 NICs can be attached to an ECS.
- type: list
- returned: success
- contains:
- ip_address:
- description:
- - Specifies the IP address of the NIC. The value is an IPv4
- address. Its value must be an unused IP
- address in the network segment of the subnet.
- type: str
- returned: success
- subnet_id:
- description:
- - Specifies the ID of subnet.
- type: str
- returned: success
- port_id:
- description:
- - Specifies the port ID corresponding to the IP address.
- type: str
- returned: success
- root_volume:
- description:
- - Specifies the configuration of the ECS's system disks.
- type: dict
- returned: success
- contains:
- volume_type:
- description:
- - Specifies the ECS system disk type.
- - SATA is common I/O disk type.
- - SAS is high I/O disk type.
- - SSD is ultra-high I/O disk type.
- - co-p1 is high I/O (performance-optimized I) disk type.
- - uh-l1 is ultra-high I/O (latency-optimized) disk type.
- - NOTE is For HANA, HL1, and HL2 ECSs, use co-p1 and uh-l1
- disks. For other ECSs, do not use co-p1 or uh-l1 disks.
- type: str
- returned: success
- size:
- description:
- - Specifies the system disk size, in GB. The value range is
- 1 to 1024. The system disk size must be
- greater than or equal to the minimum system disk size
- supported by the image (min_disk attribute of the image).
- If this parameter is not specified or is set to 0, the
- default system disk size is the minimum value of the
- system disk in the image (min_disk attribute of the
- image).
- type: int
- returned: success
- snapshot_id:
- description:
- - Specifies the snapshot ID or ID of the original data disk
- contained in the full-ECS image.
- type: str
- returned: success
- device:
- description:
- - Specifies the disk device name.
- type: str
- returned: success
- volume_id:
- description:
- - Specifies the disk ID.
- type: str
- returned: success
- vpc_id:
- description:
- - Specifies the ID of the VPC to which the ECS belongs.
- type: str
- returned: success
- admin_pass:
- description:
- - Specifies the initial login password of the administrator account
- for logging in to an ECS using password authentication. The Linux
- administrator is root, and the Windows administrator is
- Administrator. Password complexity requirements consists of 8 to
- 26 characters. The password must contain at least three of the
- following character types "uppercase letters, lowercase letters,
- digits, and special characters (!@$%^-_=+[{}]:,./?)". The password
- cannot contain the username or the username in reverse. The
- Windows ECS password cannot contain the username, the username in
- reverse, or more than two consecutive characters in the username.
- type: str
- returned: success
- data_volumes:
- description:
- - Specifies the data disks of ECS instance.
- type: list
- returned: success
- contains:
- volume_id:
- description:
- - Specifies the disk ID.
- type: str
- returned: success
- device:
- description:
- - Specifies the disk device name.
- type: str
- returned: success
- description:
- description:
- - Specifies the description of an ECS, which is a null string by
- default. Can contain a maximum of 85 characters. Cannot contain
- special characters, such as < and >.
- type: str
- returned: success
- eip_id:
- description:
- - Specifies the ID of the elastic IP address assigned to the ECS.
- Only elastic IP addresses in the DOWN state can be assigned.
- type: str
- returned: success
- enable_auto_recovery:
- description:
- - Specifies whether automatic recovery is enabled on the ECS.
- type: bool
- returned: success
- enterprise_project_id:
- description:
- - Specifies the ID of the enterprise project to which the ECS
- belongs.
- type: str
- returned: success
- security_groups:
- description:
- - Specifies the security groups of the ECS. If this parameter is left
- blank, the default security group is bound to the ECS by default.
- type: list
- returned: success
- server_metadata:
- description:
- - Specifies the metadata of ECS to be created.
- type: dict
- returned: success
- server_tags:
- description:
- - Specifies the tags of an ECS. When you create ECSs, one ECS
- supports up to 10 tags.
- type: dict
- returned: success
- ssh_key_name:
- description:
- - Specifies the name of the SSH key used for logging in to the ECS.
- type: str
- returned: success
- user_data:
- description:
- - Specifies the user data to be injected during the ECS creation
- process. Text, text files, and gzip files can be injected.
- The content to be injected must be encoded with base64. The maximum
- size of the content to be injected (before encoding) is 32 KB. For
- Linux ECSs, this parameter does not take effect when adminPass is
- used.
- type: str
- returned: success
- config_drive:
- description:
- - Specifies the configuration driver.
- type: str
- returned: success
- created:
- description:
- - Specifies the time when an ECS was created.
- type: str
- returned: success
- disk_config_type:
- description:
- - Specifies the disk configuration type. MANUAL is The image
- space is not expanded. AUTO is the image space of the system disk
- will be expanded to be as same as the flavor.
- type: str
- returned: success
- host_name:
- description:
- - Specifies the host name of the ECS.
- type: str
- returned: success
- image_name:
- description:
- - Specifies the image name of the ECS.
- type: str
- returned: success
- power_state:
- description:
- - Specifies the power status of the ECS.
- type: int
- returned: success
- server_alias:
- description:
- - Specifies the ECS alias.
- type: str
- returned: success
- status:
- description:
- - Specifies the ECS status. Options are ACTIVE, REBOOT, HARD_REBOOT,
- REBUILD, MIGRATING, BUILD, SHUTOFF, RESIZE, VERIFY_RESIZE, ERROR,
- and DELETED.
- type: str
- returned: success
-'''
+RETURN = r"""
+availability_zone:
+ description:
+ - Specifies the name of the AZ where the ECS is located.
+ type: str
+ returned: success
+flavor_name:
+ description:
+ - Specifies the name of the system flavor.
+ type: str
+ returned: success
+image_id:
+ description:
+ - Specifies the ID of the system image.
+ type: str
+ returned: success
+name:
+ description:
+ - Specifies the ECS name. Value requirements "Consists of 1 to 64 characters, including letters, digits, underscores (V(_)),
+ hyphens (V(-)), periods (V(.)).".
+ type: str
+ returned: success
+nics:
+ description:
+ - Specifies the NIC information of the ECS. The network of the NIC must belong to the VPC specified by vpc_id. A maximum
+ of 12 NICs can be attached to an ECS.
+ type: list
+ returned: success
+ contains:
+ ip_address:
+ description:
+ - Specifies the IP address of the NIC. The value is an IPv4 address. Its value must be an unused IP address in the
+ network segment of the subnet.
+ type: str
+ returned: success
+ subnet_id:
+ description:
+ - Specifies the ID of subnet.
+ type: str
+ returned: success
+ port_id:
+ description:
+ - Specifies the port ID corresponding to the IP address.
+ type: str
+ returned: success
+root_volume:
+ description:
+ - Specifies the configuration of the ECS's system disks.
+ type: dict
+ returned: success
+ contains:
+ volume_type:
+ description:
+ - Specifies the ECS system disk type.
+ - SATA is common I/O disk type.
+ - SAS is high I/O disk type.
+ - SSD is ultra-high I/O disk type.
+ - Co-p1 is high I/O (performance-optimized I) disk type.
+ - Uh-l1 is ultra-high I/O (latency-optimized) disk type.
+ - NOTE is For HANA, HL1, and HL2 ECSs, use co-p1 and uh-l1 disks. For other ECSs, do not use co-p1 or uh-l1 disks.
+ type: str
+ returned: success
+ size:
+ description:
+ - Specifies the system disk size, in GB. The value range is 1 to 1024. The system disk size must be greater than or
+ equal to the minimum system disk size supported by the image (min_disk attribute of the image). If this parameter
+ is not specified or is set to 0, the default system disk size is the minimum value of the system disk in the image
+ (min_disk attribute of the image).
+ type: int
+ returned: success
+ snapshot_id:
+ description:
+ - Specifies the snapshot ID or ID of the original data disk contained in the full-ECS image.
+ type: str
+ returned: success
+ device:
+ description:
+ - Specifies the disk device name.
+ type: str
+ returned: success
+ volume_id:
+ description:
+ - Specifies the disk ID.
+ type: str
+ returned: success
+vpc_id:
+ description:
+ - Specifies the ID of the VPC to which the ECS belongs.
+ type: str
+ returned: success
+admin_pass:
+ description:
+ - Specifies the initial login password of the administrator account for logging in to an ECS using password authentication.
+ The Linux administrator is root, and the Windows administrator is Administrator. Password complexity requirements consists
+ of 8 to 26 characters. The password must contain at least three of the following character types "uppercase letters,
+ lowercase letters, digits, and special characters (!@$%^-_=+[{}]:,./?)". The password cannot contain the username or
+ the username in reverse. The Windows ECS password cannot contain the username, the username in reverse, or more than
+ two consecutive characters in the username.
+ type: str
+ returned: success
+data_volumes:
+ description:
+ - Specifies the data disks of ECS instance.
+ type: list
+ returned: success
+ contains:
+ volume_id:
+ description:
+ - Specifies the disk ID.
+ type: str
+ returned: success
+ device:
+ description:
+ - Specifies the disk device name.
+ type: str
+ returned: success
+description:
+ description:
+ - Specifies the description of an ECS, which is a null string by default. Can contain a maximum of 85 characters. Cannot
+ contain special characters, such as < and >.
+ type: str
+ returned: success
+eip_id:
+ description:
+ - Specifies the ID of the elastic IP address assigned to the ECS. Only elastic IP addresses in the DOWN state can be assigned.
+ type: str
+ returned: success
+enable_auto_recovery:
+ description:
+ - Specifies whether automatic recovery is enabled on the ECS.
+ type: bool
+ returned: success
+enterprise_project_id:
+ description:
+ - Specifies the ID of the enterprise project to which the ECS belongs.
+ type: str
+ returned: success
+security_groups:
+ description:
+ - Specifies the security groups of the ECS. If this parameter is left blank, the default security group is bound to the
+ ECS by default.
+ type: list
+ returned: success
+server_metadata:
+ description:
+ - Specifies the metadata of ECS to be created.
+ type: dict
+ returned: success
+server_tags:
+ description:
+ - Specifies the tags of an ECS. When you create ECSs, one ECS supports up to 10 tags.
+ type: dict
+ returned: success
+ssh_key_name:
+ description:
+ - Specifies the name of the SSH key used for logging in to the ECS.
+ type: str
+ returned: success
+user_data:
+ description:
+ - Specifies the user data to be injected during the ECS creation process. Text, text files, and gzip files can be injected.
+ The content to be injected must be encoded with base64. The maximum size of the content to be injected (before encoding)
+ is 32 KB. For Linux ECSs, this parameter does not take effect when adminPass is used.
+ type: str
+ returned: success
+config_drive:
+ description:
+ - Specifies the configuration driver.
+ type: str
+ returned: success
+created:
+ description:
+ - Specifies the time when an ECS was created.
+ type: str
+ returned: success
+disk_config_type:
+ description:
+ - Specifies the disk configuration type. MANUAL is The image space is not expanded. AUTO is the image space of the system
+ disk will be expanded to be as same as the flavor.
+ type: str
+ returned: success
+host_name:
+ description:
+ - Specifies the host name of the ECS.
+ type: str
+ returned: success
+image_name:
+ description:
+ - Specifies the image name of the ECS.
+ type: str
+ returned: success
+power_state:
+ description:
+ - Specifies the power status of the ECS.
+ type: int
+ returned: success
+server_alias:
+ description:
+ - Specifies the ECS alias.
+ type: str
+ returned: success
+status:
+ description:
+ - Specifies the ECS status. Options are ACTIVE, REBOOT, HARD_REBOOT, REBUILD, MIGRATING, BUILD, SHUTOFF, RESIZE, VERIFY_RESIZE,
+ ERROR, and DELETED.
+ type: str
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcModule, are_different_dicts, build_path,
diff --git a/plugins/modules/hwc_evs_disk.py b/plugins/modules/hwc_evs_disk.py
index 5f0e40b196..0763c07b01 100644
--- a/plugins/modules/hwc_evs_disk.py
+++ b/plugins/modules/hwc_evs_disk.py
@@ -12,155 +12,135 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_evs_disk
description:
- - block storage management.
+ - Block storage management.
short_description: Creates a resource of Evs/Disk in Huawei Cloud
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Whether the given object should exist in Huaweicloud Cloud.
- type: str
- choices: ['present', 'absent']
- default: 'present'
- timeouts:
- description:
- - The timeouts for each operations.
- type: dict
- default: {}
- suboptions:
- create:
- description:
- - The timeouts for create operation.
- type: str
- default: '30m'
- update:
- description:
- - The timeouts for update operation.
- type: str
- default: '30m'
- delete:
- description:
- - The timeouts for delete operation.
- type: str
- default: '30m'
- availability_zone:
- description:
- - Specifies the AZ where you want to create the disk.
- type: str
- required: true
- name:
- description:
- - Specifies the disk name. The value can contain a maximum of 255
- bytes.
- type: str
- required: true
- volume_type:
- description:
- - Specifies the disk type. Currently, the value can be SSD, SAS, or
- SATA.
- - SSD specifies the ultra-high I/O disk type.
- - SAS specifies the high I/O disk type.
- - SATA specifies the common I/O disk type.
- - If the specified disk type is not available in the AZ, the
- disk will fail to create. If the EVS disk is created from a
- snapshot, the volume_type field must be the same as that of the
- snapshot's source disk.
- type: str
- required: true
- backup_id:
- description:
- - Specifies the ID of the backup that can be used to create a disk.
- This parameter is mandatory when you use a backup to create the
- disk.
- type: str
- required: false
+ state:
description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ timeouts:
+ description:
+ - The timeouts for each operations.
+ type: dict
+ default: {}
+ suboptions:
+ create:
description:
- - Specifies the disk description. The value can contain a maximum
- of 255 bytes.
+ - The timeouts for create operation.
type: str
- required: false
- enable_full_clone:
+ default: '30m'
+ update:
description:
- - If the disk is created from a snapshot and linked cloning needs
- to be used, set this parameter to True.
- type: bool
- required: false
- enable_scsi:
- description:
- - If this parameter is set to True, the disk device type will be
- SCSI, which allows ECS OSs to directly access underlying storage
- media. SCSI reservation command is supported. If this parameter
- is set to False, the disk device type will be VBD, which supports
- only simple SCSI read/write commands.
- - If parameter enable_share is set to True and this parameter
- is not specified, shared SCSI disks are created. SCSI EVS disks
- cannot be created from backups, which means that this parameter
- cannot be True if backup_id has been specified.
- type: bool
- required: false
- enable_share:
- description:
- - Specifies whether the disk is shareable. The default value is
- False.
- type: bool
- required: false
- encryption_id:
- description:
- - Specifies the encryption ID. The length of it fixes at 36 bytes.
+ - The timeouts for update operation.
type: str
- required: false
- enterprise_project_id:
+ default: '30m'
+ delete:
description:
- - Specifies the enterprise project ID. This ID is associated with
- the disk during the disk creation. If it is not specified, the
- disk is bound to the default enterprise project.
+ - The timeouts for delete operation.
type: str
- required: false
- image_id:
- description:
- - Specifies the image ID. If this parameter is specified, the disk
- is created from an image. BMS system disks cannot be
- created from BMS images.
- type: str
- required: false
- size:
- description:
- - Specifies the disk size, in GB. Its values are as follows, System
- disk 1 GB to 1024 GB, Data disk 10 GB to 32768 GB. This
- parameter is mandatory when you create an empty disk or use an
- image or a snapshot to create a disk. If you use an image or a
- snapshot to create a disk, the disk size must be greater than or
- equal to the image or snapshot size. This parameter is optional
- when you use a backup to create a disk. If this parameter is not
- specified, the disk size is equal to the backup size.
- type: int
- required: false
- snapshot_id:
- description:
- - Specifies the snapshot ID. If this parameter is specified, the
- disk is created from a snapshot.
- type: str
- required: false
+ default: '30m'
+ availability_zone:
+ description:
+ - Specifies the AZ where you want to create the disk.
+ type: str
+ required: true
+ name:
+ description:
+ - Specifies the disk name. The value can contain a maximum of 255 bytes.
+ type: str
+ required: true
+ volume_type:
+ description:
+ - Specifies the disk type. Currently, the value can be SSD, SAS, or SATA.
+ - SSD specifies the ultra-high I/O disk type.
+ - SAS specifies the high I/O disk type.
+ - SATA specifies the common I/O disk type.
+ - If the specified disk type is not available in the AZ, the disk will fail to create. If the EVS disk is created from
+ a snapshot, the volume_type field must be the same as that of the snapshot's source disk.
+ type: str
+ required: true
+ backup_id:
+ description:
+ - Specifies the ID of the backup that can be used to create a disk. This parameter is mandatory when you use a backup
+ to create the disk.
+ type: str
+ required: false
+ description:
+ description:
+ - Specifies the disk description. The value can contain a maximum of 255 bytes.
+ type: str
+ required: false
+ enable_full_clone:
+ description:
+ - If the disk is created from a snapshot and linked cloning needs to be used, set this parameter to True.
+ type: bool
+ required: false
+ enable_scsi:
+ description:
+ - If this parameter is set to True, the disk device type will be SCSI, which allows ECS OSs to directly access underlying
+ storage media. SCSI reservation command is supported. If this parameter is set to False, the disk device type will
+ be VBD, which supports only simple SCSI read/write commands.
+ - If parameter enable_share is set to True and this parameter is not specified, shared SCSI disks are created. SCSI
+ EVS disks cannot be created from backups, which means that this parameter cannot be True if backup_id has been specified.
+ type: bool
+ required: false
+ enable_share:
+ description:
+ - Specifies whether the disk is shareable. The default value is False.
+ type: bool
+ required: false
+ encryption_id:
+ description:
+ - Specifies the encryption ID. The length of it fixes at 36 bytes.
+ type: str
+ required: false
+ enterprise_project_id:
+ description:
+ - Specifies the enterprise project ID. This ID is associated with the disk during the disk creation. If it is not specified,
+ the disk is bound to the default enterprise project.
+ type: str
+ required: false
+ image_id:
+ description:
+ - Specifies the image ID. If this parameter is specified, the disk is created from an image. BMS system disks cannot
+ be created from BMS images.
+ type: str
+ required: false
+ size:
+ description:
+ - Specifies the disk size, in GB. Its values are as follows, System disk 1 GB to 1024 GB, Data disk 10 GB to 32768 GB.
+ This parameter is mandatory when you create an empty disk or use an image or a snapshot to create a disk. If you use
+ an image or a snapshot to create a disk, the disk size must be greater than or equal to the image or snapshot size.
+ This parameter is optional when you use a backup to create a disk. If this parameter is not specified, the disk size
+ is equal to the backup size.
+ type: int
+ required: false
+ snapshot_id:
+ description:
+ - Specifies the snapshot ID. If this parameter is specified, the disk is created from a snapshot.
+ type: str
+ required: false
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# test create disk
- name: Create a disk
community.general.hwc_evs_disk:
@@ -168,176 +148,153 @@ EXAMPLES = '''
name: "ansible_evs_disk_test"
volume_type: "SATA"
size: 10
-'''
+"""
-RETURN = '''
- availability_zone:
- description:
- - Specifies the AZ where you want to create the disk.
- type: str
- returned: success
- name:
- description:
- - Specifies the disk name. The value can contain a maximum of 255
- bytes.
- type: str
- returned: success
- volume_type:
- description:
- - Specifies the disk type. Currently, the value can be SSD, SAS, or
- SATA.
- - SSD specifies the ultra-high I/O disk type.
- - SAS specifies the high I/O disk type.
- - SATA specifies the common I/O disk type.
- - If the specified disk type is not available in the AZ, the
- disk will fail to create. If the EVS disk is created from a
- snapshot, the volume_type field must be the same as that of the
- snapshot's source disk.
- type: str
- returned: success
- backup_id:
- description:
- - Specifies the ID of the backup that can be used to create a disk.
- This parameter is mandatory when you use a backup to create the
- disk.
- type: str
- returned: success
- description:
- description:
- - Specifies the disk description. The value can contain a maximum
- of 255 bytes.
- type: str
- returned: success
- enable_full_clone:
- description:
- - If the disk is created from a snapshot and linked cloning needs
- to be used, set this parameter to True.
- type: bool
- returned: success
- enable_scsi:
- description:
- - If this parameter is set to True, the disk device type will be
- SCSI, which allows ECS OSs to directly access underlying storage
- media. SCSI reservation command is supported. If this parameter
- is set to False, the disk device type will be VBD, which supports
- only simple SCSI read/write commands.
- - If parameter enable_share is set to True and this parameter
- is not specified, shared SCSI disks are created. SCSI EVS disks
- cannot be created from backups, which means that this parameter
- cannot be True if backup_id has been specified.
- type: bool
- returned: success
- enable_share:
- description:
- - Specifies whether the disk is shareable. The default value is
- False.
- type: bool
- returned: success
- encryption_id:
- description:
- - Specifies the encryption ID. The length of it fixes at 36 bytes.
- type: str
- returned: success
- enterprise_project_id:
- description:
- - Specifies the enterprise project ID. This ID is associated with
- the disk during the disk creation. If it is not specified, the
- disk is bound to the default enterprise project.
- type: str
- returned: success
- image_id:
- description:
- - Specifies the image ID. If this parameter is specified, the disk
- is created from an image. BMS system disks cannot be
- created from BMS images.
- type: str
- returned: success
- size:
- description:
- - Specifies the disk size, in GB. Its values are as follows, System
- disk 1 GB to 1024 GB, Data disk 10 GB to 32768 GB. This
- parameter is mandatory when you create an empty disk or use an
- image or a snapshot to create a disk. If you use an image or a
- snapshot to create a disk, the disk size must be greater than or
- equal to the image or snapshot size. This parameter is optional
- when you use a backup to create a disk. If this parameter is not
- specified, the disk size is equal to the backup size.
- type: int
- returned: success
- snapshot_id:
- description:
- - Specifies the snapshot ID. If this parameter is specified, the
- disk is created from a snapshot.
- type: str
- returned: success
- attachments:
- description:
- - Specifies the disk attachment information.
- type: complex
- returned: success
- contains:
- attached_at:
- description:
- - Specifies the time when the disk was attached. Time
- format is 'UTC YYYY-MM-DDTHH:MM:SS'.
- type: str
- returned: success
- attachment_id:
- description:
- - Specifies the ID of the attachment information.
- type: str
- returned: success
- device:
- description:
- - Specifies the device name.
- type: str
- returned: success
- server_id:
- description:
- - Specifies the ID of the server to which the disk is
- attached.
- type: str
- returned: success
- backup_policy_id:
- description:
- - Specifies the backup policy ID.
- type: str
- returned: success
- created_at:
- description:
- - Specifies the time when the disk was created. Time format is 'UTC
- YYYY-MM-DDTHH:MM:SS'.
- type: str
- returned: success
- is_bootable:
- description:
- - Specifies whether the disk is bootable.
- type: bool
- returned: success
- is_readonly:
- description:
- - Specifies whether the disk is read-only or read/write. True
- indicates that the disk is read-only. False indicates that the
- disk is read/write.
- type: bool
- returned: success
- source_volume_id:
- description:
- - Specifies the source disk ID. This parameter has a value if the
- disk is created from a source disk.
- type: str
- returned: success
- status:
- description:
- - Specifies the disk status.
- type: str
- returned: success
- tags:
- description:
- - Specifies the disk tags.
- type: dict
- returned: success
-'''
+RETURN = r"""
+availability_zone:
+ description:
+ - Specifies the AZ where you want to create the disk.
+ type: str
+ returned: success
+name:
+ description:
+ - Specifies the disk name. The value can contain a maximum of 255 bytes.
+ type: str
+ returned: success
+volume_type:
+ description:
+ - Specifies the disk type. Currently, the value can be SSD, SAS, or SATA.
+ - SSD specifies the ultra-high I/O disk type.
+ - SAS specifies the high I/O disk type.
+ - SATA specifies the common I/O disk type.
+ - If the specified disk type is not available in the AZ, the disk will fail to create. If the EVS disk is created from
+ a snapshot, the volume_type field must be the same as that of the snapshot's source disk.
+ type: str
+ returned: success
+backup_id:
+ description:
+ - Specifies the ID of the backup that can be used to create a disk. This parameter is mandatory when you use a backup
+ to create the disk.
+ type: str
+ returned: success
+description:
+ description:
+ - Specifies the disk description. The value can contain a maximum of 255 bytes.
+ type: str
+ returned: success
+enable_full_clone:
+ description:
+ - If the disk is created from a snapshot and linked cloning needs to be used, set this parameter to True.
+ type: bool
+ returned: success
+enable_scsi:
+ description:
+ - If this parameter is set to True, the disk device type will be SCSI, which allows ECS OSs to directly access underlying
+ storage media. SCSI reservation command is supported. If this parameter is set to False, the disk device type will be
+ VBD, which supports only simple SCSI read/write commands.
+ - If parameter enable_share is set to True and this parameter is not specified, shared SCSI disks are created. SCSI EVS
+ disks cannot be created from backups, which means that this parameter cannot be True if backup_id has been specified.
+ type: bool
+ returned: success
+enable_share:
+ description:
+ - Specifies whether the disk is shareable. The default value is False.
+ type: bool
+ returned: success
+encryption_id:
+ description:
+ - Specifies the encryption ID. The length of it fixes at 36 bytes.
+ type: str
+ returned: success
+enterprise_project_id:
+ description:
+ - Specifies the enterprise project ID. This ID is associated with the disk during the disk creation. If it is not specified,
+ the disk is bound to the default enterprise project.
+ type: str
+ returned: success
+image_id:
+ description:
+ - Specifies the image ID. If this parameter is specified, the disk is created from an image. BMS system disks cannot be
+ created from BMS images.
+ type: str
+ returned: success
+size:
+ description:
+ - Specifies the disk size, in GB. Its values are as follows, System disk 1 GB to 1024 GB, Data disk 10 GB to 32768 GB.
+ This parameter is mandatory when you create an empty disk or use an image or a snapshot to create a disk. If you use
+ an image or a snapshot to create a disk, the disk size must be greater than or equal to the image or snapshot size.
+ This parameter is optional when you use a backup to create a disk. If this parameter is not specified, the disk size
+ is equal to the backup size.
+ type: int
+ returned: success
+snapshot_id:
+ description:
+ - Specifies the snapshot ID. If this parameter is specified, the disk is created from a snapshot.
+ type: str
+ returned: success
+attachments:
+ description:
+ - Specifies the disk attachment information.
+ type: complex
+ returned: success
+ contains:
+ attached_at:
+ description:
+ - Specifies the time when the disk was attached. Time format is 'UTC YYYY-MM-DDTHH:MM:SS'.
+ type: str
+ returned: success
+ attachment_id:
+ description:
+ - Specifies the ID of the attachment information.
+ type: str
+ returned: success
+ device:
+ description:
+ - Specifies the device name.
+ type: str
+ returned: success
+ server_id:
+ description:
+ - Specifies the ID of the server to which the disk is attached.
+ type: str
+ returned: success
+backup_policy_id:
+ description:
+ - Specifies the backup policy ID.
+ type: str
+ returned: success
+created_at:
+ description:
+ - Specifies the time when the disk was created. Time format is 'UTC YYYY-MM-DDTHH:MM:SS'.
+ type: str
+ returned: success
+is_bootable:
+ description:
+ - Specifies whether the disk is bootable.
+ type: bool
+ returned: success
+is_readonly:
+ description:
+ - Specifies whether the disk is read-only or read/write. True indicates that the disk is read-only. False indicates that
+ the disk is read/write.
+ type: bool
+ returned: success
+source_volume_id:
+ description:
+ - Specifies the source disk ID. This parameter has a value if the disk is created from a source disk.
+ type: str
+ returned: success
+status:
+ description:
+ - Specifies the disk status.
+ type: str
+ returned: success
+tags:
+ description:
+ - Specifies the disk tags.
+ type: dict
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcModule, are_different_dicts, build_path,
diff --git a/plugins/modules/hwc_network_vpc.py b/plugins/modules/hwc_network_vpc.py
index 357fd55204..3342280061 100644
--- a/plugins/modules/hwc_network_vpc.py
+++ b/plugins/modules/hwc_network_vpc.py
@@ -12,123 +12,120 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_network_vpc
description:
- - Represents an vpc resource.
+ - Represents an vpc resource.
short_description: Creates a Huawei Cloud VPC
author: Huawei Inc. (@huaweicloud)
requirements:
- - requests >= 2.18.4
- - keystoneauth1 >= 3.6.0
+ - requests >= 2.18.4
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
+ state:
+ description:
+ - Whether the given object should exist in VPC.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ timeouts:
+ description:
+ - The timeouts for each operations.
+ type: dict
+ default: {}
+ suboptions:
+ create:
description:
- - Whether the given object should exist in vpc.
+ - The timeout for create operation.
type: str
- choices: ['present', 'absent']
- default: 'present'
- timeouts:
+ default: '15m'
+ update:
description:
- - The timeouts for each operations.
- type: dict
- default: {}
- suboptions:
- create:
- description:
- - The timeout for create operation.
- type: str
- default: '15m'
- update:
- description:
- - The timeout for update operation.
- type: str
- default: '15m'
- delete:
- description:
- - The timeout for delete operation.
- type: str
- default: '15m'
- name:
- description:
- - The name of vpc.
+ - The timeout for update operation.
type: str
- required: true
- cidr:
+ default: '15m'
+ delete:
description:
- - The range of available subnets in the vpc.
+ - The timeout for delete operation.
type: str
- required: true
+ default: '15m'
+ name:
+ description:
+ - The name of vpc.
+ type: str
+ required: true
+ cidr:
+ description:
+ - The range of available subnets in the VPC.
+ type: str
+ required: true
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a vpc
community.general.hwc_network_vpc:
- identity_endpoint: "{{ identity_endpoint }}"
- user: "{{ user }}"
- password: "{{ password }}"
- domain: "{{ domain }}"
- project: "{{ project }}"
- region: "{{ region }}"
- name: "vpc_1"
- cidr: "192.168.100.0/24"
- state: present
-'''
+ identity_endpoint: "{{ identity_endpoint }}"
+ user: "{{ user }}"
+ password: "{{ password }}"
+ domain: "{{ domain }}"
+ project: "{{ project }}"
+ region: "{{ region }}"
+ name: "vpc_1"
+ cidr: "192.168.100.0/24"
+ state: present
+"""
-RETURN = '''
- id:
- description:
- - the id of vpc.
- type: str
- returned: success
- name:
- description:
- - the name of vpc.
- type: str
- returned: success
- cidr:
- description:
- - the range of available subnets in the vpc.
- type: str
- returned: success
- status:
- description:
- - the status of vpc.
- type: str
- returned: success
- routes:
- description:
- - the route information.
- type: complex
- returned: success
- contains:
- destination:
- description:
- - the destination network segment of a route.
- type: str
- returned: success
- next_hop:
- description:
- - the next hop of a route. If the route type is peering,
- it will provide VPC peering connection ID.
- type: str
- returned: success
- enable_shared_snat:
- description:
- - show whether the shared snat is enabled.
- type: bool
- returned: success
-'''
+RETURN = r"""
+id:
+ description:
+ - The ID of VPC.
+ type: str
+ returned: success
+name:
+ description:
+ - The name of VPC.
+ type: str
+ returned: success
+cidr:
+ description:
+ - The range of available subnets in the VPC.
+ type: str
+ returned: success
+status:
+ description:
+ - The status of VPC.
+ type: str
+ returned: success
+routes:
+ description:
+ - The route information.
+ type: complex
+ returned: success
+ contains:
+ destination:
+ description:
+ - The destination network segment of a route.
+ type: str
+ returned: success
+ next_hop:
+ description:
+ - The next hop of a route. If the route type is peering, it will provide VPC peering connection ID.
+ type: str
+ returned: success
+enable_shared_snat:
+ description:
+ - Show whether the shared SNAT is enabled.
+ type: bool
+ returned: success
+"""
###############################################################################
# Imports
diff --git a/plugins/modules/hwc_smn_topic.py b/plugins/modules/hwc_smn_topic.py
index bb983fba71..45923833e6 100644
--- a/plugins/modules/hwc_smn_topic.py
+++ b/plugins/modules/hwc_smn_topic.py
@@ -12,101 +12,92 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_smn_topic
description:
- - Represents a SMN notification topic resource.
-short_description: Creates a resource of SMNTopic in Huaweicloud Cloud
+ - Represents a SMN notification topic resource.
+short_description: Creates a resource of SMNTopic in Huawei Cloud
author: Huawei Inc. (@huaweicloud)
requirements:
- - requests >= 2.18.4
- - keystoneauth1 >= 3.6.0
+ - requests >= 2.18.4
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Whether the given object should exist in Huaweicloud Cloud.
- type: str
- choices: ['present', 'absent']
- default: 'present'
- display_name:
- description:
- - Topic display name, which is presented as the name of the email
- sender in an email message. The topic display name contains a
- maximum of 192 bytes.
- type: str
- required: false
- name:
- description:
- - Name of the topic to be created. The topic name is a string of 1
- to 256 characters. It must contain upper- or lower-case letters,
- digits, hyphens (V(-)), and underscores (V(_)), and must start with a
- letter or digit.
- type: str
- required: true
+ state:
+ description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ display_name:
+ description:
+ - Topic display name, which is presented as the name of the email sender in an email message. The topic display name
+ contains a maximum of 192 bytes.
+ type: str
+ required: false
+ name:
+ description:
+ - Name of the topic to be created. The topic name is a string of 1 to 256 characters. It must contain upper- or lower-case
+ letters, digits, hyphens (V(-)), and underscores (V(_)), and must start with a letter or digit.
+ type: str
+ required: true
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a smn topic
community.general.hwc_smn_topic:
- identity_endpoint: "{{ identity_endpoint }}"
- user_name: "{{ user_name }}"
- password: "{{ password }}"
- domain_name: "{{ domain_name }}"
- project_name: "{{ project_name }}"
- region: "{{ region }}"
- name: "ansible_smn_topic_test"
- state: present
-'''
+ identity_endpoint: "{{ identity_endpoint }}"
+ user_name: "{{ user_name }}"
+ password: "{{ password }}"
+ domain_name: "{{ domain_name }}"
+ project_name: "{{ project_name }}"
+ region: "{{ region }}"
+ name: "ansible_smn_topic_test"
+ state: present
+"""
-RETURN = '''
+RETURN = r"""
create_time:
- description:
- - Time when the topic was created.
- returned: success
- type: str
+ description:
+ - Time when the topic was created.
+ returned: success
+ type: str
display_name:
- description:
- - Topic display name, which is presented as the name of the email
- sender in an email message. The topic display name contains a
- maximum of 192 bytes.
- returned: success
- type: str
+ description:
+ - Topic display name, which is presented as the name of the email sender in an email message. The topic display name contains
+ a maximum of 192 bytes.
+ returned: success
+ type: str
name:
- description:
- - Name of the topic to be created. The topic name is a string of 1
- to 256 characters. It must contain upper- or lower-case letters,
- digits, hyphens (V(-)), and underscores (V(_)), and must start with a
- letter or digit.
- returned: success
- type: str
+ description:
+ - Name of the topic to be created. The topic name is a string of 1 to 256 characters. It must contain upper- or lower-case
+ letters, digits, hyphens (V(-)), and underscores (V(_)), and must start with a letter or digit.
+ returned: success
+ type: str
push_policy:
- description:
- - Message pushing policy. 0 indicates that the message sending
- fails and the message is cached in the queue. 1 indicates that
- the failed message is discarded.
- returned: success
- type: int
+ description:
+ - Message pushing policy. V(0) indicates that the message sending fails and the message is cached in the queue. V(1) indicates
+ that the failed message is discarded.
+ returned: success
+ type: int
topic_urn:
- description:
- - Resource identifier of a topic, which is unique.
- returned: success
- type: str
+ description:
+ - Resource identifier of a topic, which is unique.
+ returned: success
+ type: str
update_time:
- description:
- - Time when the topic was updated.
- returned: success
- type: str
-'''
+ description:
+ - Time when the topic was updated.
+ returned: success
+ type: str
+"""
###############################################################################
# Imports
diff --git a/plugins/modules/hwc_vpc_eip.py b/plugins/modules/hwc_vpc_eip.py
index c3039ca2e5..b818fe0d86 100644
--- a/plugins/modules/hwc_vpc_eip.py
+++ b/plugins/modules/hwc_vpc_eip.py
@@ -12,126 +12,110 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_vpc_eip
description:
- - elastic ip management.
-short_description: Creates a resource of Vpc/EIP in Huawei Cloud
+ - Elastic IP management.
+short_description: Creates a resource of VPC/EIP in Huawei Cloud
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
+ state:
+ description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ timeouts:
+ description:
+ - The timeouts for each operations.
+ type: dict
+ default: {}
+ suboptions:
+ create:
description:
- - Whether the given object should exist in Huawei Cloud.
+ - The timeouts for create operation.
type: str
- choices: ['present', 'absent']
- default: 'present'
- timeouts:
+ default: '5m'
+ update:
description:
- - The timeouts for each operations.
- type: dict
- default: {}
- suboptions:
- create:
- description:
- - The timeouts for create operation.
- type: str
- default: '5m'
- update:
- description:
- - The timeouts for update operation.
- type: str
- default: '5m'
- type:
+ - The timeouts for update operation.
+ type: str
+ default: '5m'
+ type:
+ description:
+ - Specifies the EIP type.
+ type: str
+ required: true
+ dedicated_bandwidth:
+ description:
+ - Specifies the dedicated bandwidth object.
+ type: dict
+ required: false
+ suboptions:
+ charge_mode:
description:
- - Specifies the EIP type.
+ - Specifies whether the bandwidth is billed by traffic or by bandwidth size. The value can be bandwidth or traffic.
+ If this parameter is left blank or is null character string, default value bandwidth is used. For IPv6 addresses,
+ the default parameter value is bandwidth outside China and is traffic in China.
type: str
required: true
- dedicated_bandwidth:
+ name:
description:
- - Specifies the dedicated bandwidth object.
- type: dict
- required: false
- suboptions:
- charge_mode:
- description:
- - Specifies whether the bandwidth is billed by traffic or
- by bandwidth size. The value can be bandwidth or traffic.
- If this parameter is left blank or is null character
- string, default value bandwidth is used. For IPv6
- addresses, the default parameter value is bandwidth
- outside China and is traffic in China.
- type: str
- required: true
- name:
- description:
- - Specifies the bandwidth name. The value is a string of 1
- to 64 characters that can contain letters, digits,
- underscores (V(_)), hyphens (V(-)), and periods (V(.)).
- type: str
- required: true
- size:
- description:
- - Specifies the bandwidth size. The value ranges from 1
- Mbit/s to 2000 Mbit/s by default. (The specific range may
- vary depending on the configuration in each region. You
- can see the bandwidth range of each region on the
- management console.) The minimum unit for bandwidth
- adjustment varies depending on the bandwidth range. The
- details are as follows.
- - The minimum unit is 1 Mbit/s if the allowed bandwidth
- size ranges from 0 to 300 Mbit/s (with 300 Mbit/s
- included).
- - The minimum unit is 50 Mbit/s if the allowed bandwidth
- size ranges 300 Mbit/s to 1000 Mbit/s (with 1000 Mbit/s
- included).
- - The minimum unit is 500 Mbit/s if the allowed bandwidth
- size is greater than 1000 Mbit/s.
- type: int
- required: true
- enterprise_project_id:
- description:
- - Specifies the enterprise project ID.
+ - Specifies the bandwidth name. The value is a string of 1 to 64 characters that can contain letters, digits, underscores
+ (V(_)), hyphens (V(-)), and periods (V(.)).
type: str
- required: false
- ip_version:
+ required: true
+ size:
description:
- - The value can be 4 (IPv4 address) or 6 (IPv6 address). If this
- parameter is left blank, an IPv4 address will be assigned.
+ - Specifies the bandwidth size. The value ranges from 1 Mbit/s to 2000 Mbit/s by default. (The specific range may
+ vary depending on the configuration in each region. You can see the bandwidth range of each region on the management
+ console.) The minimum unit for bandwidth adjustment varies depending on the bandwidth range. The details are as
+ follows.
+ - The minimum unit is 1 Mbit/s if the allowed bandwidth size ranges from 0 to 300 Mbit/s (with 300 Mbit/s included).
+ - The minimum unit is 50 Mbit/s if the allowed bandwidth size ranges 300 Mbit/s to 1000 Mbit/s (with 1000 Mbit/s
+ included).
+ - The minimum unit is 500 Mbit/s if the allowed bandwidth size is greater than 1000 Mbit/s.
type: int
- required: false
- ipv4_address:
- description:
- - Specifies the obtained IPv4 EIP. The system automatically assigns
- an EIP if you do not specify it.
- type: str
- required: false
- port_id:
- description:
- - Specifies the port ID. This parameter is returned only when a
- private IP address is bound with the EIP.
- type: str
- required: false
- shared_bandwidth_id:
- description:
- - Specifies the ID of shared bandwidth.
- type: str
- required: false
+ required: true
+ enterprise_project_id:
+ description:
+ - Specifies the enterprise project ID.
+ type: str
+ required: false
+ ip_version:
+ description:
+ - The value can be 4 (IPv4 address) or 6 (IPv6 address). If this parameter is left blank, an IPv4 address will be assigned.
+ type: int
+ required: false
+ ipv4_address:
+ description:
+ - Specifies the obtained IPv4 EIP. The system automatically assigns an EIP if you do not specify it.
+ type: str
+ required: false
+ port_id:
+ description:
+ - Specifies the port ID. This parameter is returned only when a private IP address is bound with the EIP.
+ type: str
+ required: false
+ shared_bandwidth_id:
+ description:
+ - Specifies the ID of shared bandwidth.
+ type: str
+ required: false
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# create an eip and bind it to a port
- name: Create vpc
hwc_network_vpc:
@@ -159,107 +143,91 @@ EXAMPLES = '''
name: "ansible_test_dedicated_bandwidth"
size: 1
port_id: "{{ port.id }}"
-'''
+"""
-RETURN = '''
- type:
- description:
- - Specifies the EIP type.
- type: str
- returned: success
- dedicated_bandwidth:
- description:
- - Specifies the dedicated bandwidth object.
- type: dict
- returned: success
- contains:
- charge_mode:
- description:
- - Specifies whether the bandwidth is billed by traffic or
- by bandwidth size. The value can be bandwidth or traffic.
- If this parameter is left blank or is null character
- string, default value bandwidth is used. For IPv6
- addresses, the default parameter value is bandwidth
- outside China and is traffic in China.
- type: str
- returned: success
- name:
- description:
- - Specifies the bandwidth name. The value is a string of 1
- to 64 characters that can contain letters, digits,
- underscores (V(_)), hyphens (V(-)), and periods (V(.)).
- type: str
- returned: success
- size:
- description:
- - Specifies the bandwidth size. The value ranges from 1
- Mbit/s to 2000 Mbit/s by default. (The specific range may
- vary depending on the configuration in each region. You
- can see the bandwidth range of each region on the
- management console.) The minimum unit for bandwidth
- adjustment varies depending on the bandwidth range. The
- details are as follows:.
- - The minimum unit is 1 Mbit/s if the allowed bandwidth
- size ranges from 0 to 300 Mbit/s (with 300 Mbit/s
- included).
- - The minimum unit is 50 Mbit/s if the allowed bandwidth
- size ranges 300 Mbit/s to 1000 Mbit/s (with 1000 Mbit/s
- included).
- - The minimum unit is 500 Mbit/s if the allowed bandwidth
- size is greater than 1000 Mbit/s.
- type: int
- returned: success
- id:
- description:
- - Specifies the ID of dedicated bandwidth.
- type: str
- returned: success
- enterprise_project_id:
- description:
- - Specifies the enterprise project ID.
- type: str
- returned: success
- ip_version:
- description:
- - The value can be 4 (IPv4 address) or 6 (IPv6 address). If this
- parameter is left blank, an IPv4 address will be assigned.
- type: int
- returned: success
- ipv4_address:
- description:
- - Specifies the obtained IPv4 EIP. The system automatically assigns
- an EIP if you do not specify it.
- type: str
- returned: success
- port_id:
- description:
- - Specifies the port ID. This parameter is returned only when a
- private IP address is bound with the EIP.
- type: str
- returned: success
- shared_bandwidth_id:
- description:
- - Specifies the ID of shared bandwidth.
- type: str
- returned: success
- create_time:
- description:
- - Specifies the time (UTC time) when the EIP was assigned.
- type: str
- returned: success
- ipv6_address:
- description:
- - Specifies the obtained IPv6 EIP.
- type: str
- returned: success
- private_ip_address:
- description:
- - Specifies the private IP address bound with the EIP. This
- parameter is returned only when a private IP address is bound
- with the EIP.
- type: str
- returned: success
-'''
+RETURN = r"""
+type:
+ description:
+ - Specifies the EIP type.
+ type: str
+ returned: success
+dedicated_bandwidth:
+ description:
+ - Specifies the dedicated bandwidth object.
+ type: dict
+ returned: success
+ contains:
+ charge_mode:
+ description:
+ - Specifies whether the bandwidth is billed by traffic or by bandwidth size. The value can be bandwidth or traffic.
+ If this parameter is left blank or is null character string, default value bandwidth is used. For IPv6 addresses,
+ the default parameter value is bandwidth outside China and is traffic in China.
+ type: str
+ returned: success
+ name:
+ description:
+ - Specifies the bandwidth name. The value is a string of 1 to 64 characters that can contain letters, digits, underscores
+ (V(_)), hyphens (V(-)), and periods (V(.)).
+ type: str
+ returned: success
+ size:
+ description:
+ - Specifies the bandwidth size. The value ranges from 1 Mbit/s to 2000 Mbit/s by default. (The specific range may
+ vary depending on the configuration in each region. You can see the bandwidth range of each region on the management
+ console.) The minimum unit for bandwidth adjustment varies depending on the bandwidth range. The details are as
+ follows:.
+ - The minimum unit is 1 Mbit/s if the allowed bandwidth size ranges from 0 to 300 Mbit/s (with 300 Mbit/s included).
+ - The minimum unit is 50 Mbit/s if the allowed bandwidth size ranges 300 Mbit/s to 1000 Mbit/s (with 1000 Mbit/s included).
+ - The minimum unit is 500 Mbit/s if the allowed bandwidth size is greater than 1000 Mbit/s.
+ type: int
+ returned: success
+ id:
+ description:
+ - Specifies the ID of dedicated bandwidth.
+ type: str
+ returned: success
+enterprise_project_id:
+ description:
+ - Specifies the enterprise project ID.
+ type: str
+ returned: success
+ip_version:
+ description:
+ - The value can be 4 (IPv4 address) or 6 (IPv6 address). If this parameter is left blank, an IPv4 address will be assigned.
+ type: int
+ returned: success
+ipv4_address:
+ description:
+ - Specifies the obtained IPv4 EIP. The system automatically assigns an EIP if you do not specify it.
+ type: str
+ returned: success
+port_id:
+ description:
+ - Specifies the port ID. This parameter is returned only when a private IP address is bound with the EIP.
+ type: str
+ returned: success
+shared_bandwidth_id:
+ description:
+ - Specifies the ID of shared bandwidth.
+ type: str
+ returned: success
+create_time:
+ description:
+ - Specifies the time (UTC time) when the EIP was assigned.
+ type: str
+ returned: success
+ipv6_address:
+ description:
+ - Specifies the obtained IPv6 EIP.
+ type: str
+ returned: success
+private_ip_address:
+ description:
+ - Specifies the private IP address bound with the EIP. This parameter is returned only when a private IP address is bound
+ with the EIP.
+ type: str
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcClientException404, HwcModule,
diff --git a/plugins/modules/hwc_vpc_peering_connect.py b/plugins/modules/hwc_vpc_peering_connect.py
index 854d89e76a..478b28a2c8 100644
--- a/plugins/modules/hwc_vpc_peering_connect.py
+++ b/plugins/modules/hwc_vpc_peering_connect.py
@@ -13,79 +13,75 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_vpc_peering_connect
description:
- - vpc peering management.
-short_description: Creates a resource of Vpc/PeeringConnect in Huawei Cloud
+ - VPC peering management.
+short_description: Creates a resource of VPC/PeeringConnect in Huawei Cloud
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Whether the given object should exist in Huawei Cloud.
- type: str
- choices: ['present', 'absent']
- default: 'present'
- timeouts:
- description:
- - The timeouts for each operations.
- type: dict
- default: {}
- suboptions:
- create:
- description:
- - The timeouts for create operation.
- type: str
- default: '15m'
- local_vpc_id:
- description:
- - Specifies the ID of local VPC.
- type: str
- required: true
- name:
- description:
- - Specifies the name of the VPC peering connection. The value can
- contain 1 to 64 characters.
- type: str
- required: true
- peering_vpc:
- description:
- - Specifies information about the peering VPC.
- type: dict
- required: true
- suboptions:
- vpc_id:
- description:
- - Specifies the ID of peering VPC.
- type: str
- required: true
- project_id:
- description:
- - Specifies the ID of the project which the peering vpc
- belongs to.
- type: str
- required: false
+ state:
description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ timeouts:
+ description:
+ - The timeouts for each operations.
+ type: dict
+ default: {}
+ suboptions:
+ create:
description:
- - The description of vpc peering connection.
+ - The timeouts for create operation.
+ type: str
+ default: '15m'
+ local_vpc_id:
+ description:
+ - Specifies the ID of local VPC.
+ type: str
+ required: true
+ name:
+ description:
+ - Specifies the name of the VPC peering connection. The value can contain 1 to 64 characters.
+ type: str
+ required: true
+ peering_vpc:
+ description:
+ - Specifies information about the peering VPC.
+ type: dict
+ required: true
+ suboptions:
+ vpc_id:
+ description:
+ - Specifies the ID of peering VPC.
+ type: str
+ required: true
+ project_id:
+ description:
+ - Specifies the ID of the project which the peering vpc belongs to.
type: str
required: false
+ description:
+ description:
+ - The description of vpc peering connection.
+ type: str
+ required: false
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# create a peering connect
- name: Create a local vpc
hwc_network_vpc:
@@ -103,43 +99,41 @@ EXAMPLES = '''
name: "ansible_network_peering_test"
peering_vpc:
vpc_id: "{{ vpc2.id }}"
-'''
+"""
-RETURN = '''
- local_vpc_id:
- description:
- - Specifies the ID of local VPC.
- type: str
- returned: success
- name:
- description:
- - Specifies the name of the VPC peering connection. The value can
- contain 1 to 64 characters.
- type: str
- returned: success
- peering_vpc:
- description:
- - Specifies information about the peering VPC.
- type: dict
- returned: success
- contains:
- vpc_id:
- description:
- - Specifies the ID of peering VPC.
- type: str
- returned: success
- project_id:
- description:
- - Specifies the ID of the project which the peering vpc
- belongs to.
- type: str
- returned: success
- description:
- description:
- - The description of vpc peering connection.
- type: str
- returned: success
-'''
+RETURN = r"""
+local_vpc_id:
+ description:
+ - Specifies the ID of local VPC.
+ type: str
+ returned: success
+name:
+ description:
+ - Specifies the name of the VPC peering connection. The value can contain 1 to 64 characters.
+ type: str
+ returned: success
+peering_vpc:
+ description:
+ - Specifies information about the peering VPC.
+ type: dict
+ returned: success
+ contains:
+ vpc_id:
+ description:
+ - Specifies the ID of peering VPC.
+ type: str
+ returned: success
+ project_id:
+ description:
+ - Specifies the ID of the project which the peering vpc belongs to.
+ type: str
+ returned: success
+description:
+ description:
+ - The description of vpc peering connection.
+ type: str
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcClientException404, HwcModule,
diff --git a/plugins/modules/hwc_vpc_port.py b/plugins/modules/hwc_vpc_port.py
index 08b1c0607d..47f911821e 100644
--- a/plugins/modules/hwc_vpc_port.py
+++ b/plugins/modules/hwc_vpc_port.py
@@ -12,110 +12,105 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_vpc_port
description:
- - vpc port management.
-short_description: Creates a resource of Vpc/Port in Huawei Cloud
+ - VPC port management.
+short_description: Creates a resource of VPC/Port in Huawei Cloud
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
+ state:
+ description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ timeouts:
+ description:
+ - The timeouts for each operations.
+ type: dict
+ default: {}
+ suboptions:
+ create:
description:
- - Whether the given object should exist in Huawei Cloud.
+ - The timeouts for create operation.
type: str
- choices: ['present', 'absent']
- default: 'present'
- timeouts:
+ default: '15m'
+ subnet_id:
+ description:
+ - Specifies the ID of the subnet to which the port belongs.
+ type: str
+ required: true
+ admin_state_up:
+ description:
+ - Specifies the administrative state of the port.
+ type: bool
+ required: false
+ allowed_address_pairs:
+ description:
+ - Specifies a set of zero or more allowed address pairs.
+ required: false
+ type: list
+ elements: dict
+ suboptions:
+ ip_address:
description:
- - The timeouts for each operations.
- type: dict
- default: {}
- suboptions:
- create:
- description:
- - The timeouts for create operation.
- type: str
- default: '15m'
- subnet_id:
- description:
- - Specifies the ID of the subnet to which the port belongs.
- type: str
- required: true
- admin_state_up:
- description:
- - Specifies the administrative state of the port.
- type: bool
- required: false
- allowed_address_pairs:
- description:
- - Specifies a set of zero or more allowed address pairs.
- required: false
- type: list
- elements: dict
- suboptions:
- ip_address:
- description:
- - Specifies the IP address. It cannot set it to 0.0.0.0.
- Configure an independent security group for the port if a
- large CIDR block (subnet mask less than 24) is configured
- for parameter allowed_address_pairs.
- type: str
- required: false
- mac_address:
- description:
- - Specifies the MAC address.
- type: str
- required: false
- extra_dhcp_opts:
- description:
- - Specifies the extended option of DHCP.
- type: list
- elements: dict
- required: false
- suboptions:
- name:
- description:
- - Specifies the option name.
- type: str
- required: false
- value:
- description:
- - Specifies the option value.
- type: str
- required: false
- ip_address:
- description:
- - Specifies the port IP address.
+ - Specifies the IP address. It cannot set it to 0.0.0.0. Configure an independent security group for the port if
+ a large CIDR block (subnet mask less than 24) is configured for parameter allowed_address_pairs.
type: str
required: false
- name:
+ mac_address:
description:
- - Specifies the port name. The value can contain no more than 255
- characters.
+ - Specifies the MAC address.
type: str
required: false
- security_groups:
+ extra_dhcp_opts:
+ description:
+ - Specifies the extended option of DHCP.
+ type: list
+ elements: dict
+ required: false
+ suboptions:
+ name:
description:
- - Specifies the ID of the security group.
- type: list
- elements: str
+ - Specifies the option name.
+ type: str
required: false
+ value:
+ description:
+ - Specifies the option value.
+ type: str
+ required: false
+ ip_address:
+ description:
+ - Specifies the port IP address.
+ type: str
+ required: false
+ name:
+ description:
+ - Specifies the port name. The value can contain no more than 255 characters.
+ type: str
+ required: false
+ security_groups:
+ description:
+ - Specifies the ID of the security group.
+ type: list
+ elements: str
+ required: false
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# create a port
- name: Create vpc
hwc_network_vpc:
@@ -134,76 +129,73 @@ EXAMPLES = '''
community.general.hwc_vpc_port:
subnet_id: "{{ subnet.id }}"
ip_address: "192.168.100.33"
-'''
+"""
-RETURN = '''
- subnet_id:
- description:
- - Specifies the ID of the subnet to which the port belongs.
- type: str
- returned: success
- admin_state_up:
- description:
- - Specifies the administrative state of the port.
- type: bool
- returned: success
- allowed_address_pairs:
- description:
- - Specifies a set of zero or more allowed address pairs.
- type: list
- returned: success
- contains:
- ip_address:
- description:
- - Specifies the IP address. It cannot set it to 0.0.0.0.
- Configure an independent security group for the port if a
- large CIDR block (subnet mask less than 24) is configured
- for parameter allowed_address_pairs.
- type: str
- returned: success
- mac_address:
- description:
- - Specifies the MAC address.
- type: str
- returned: success
- extra_dhcp_opts:
- description:
- - Specifies the extended option of DHCP.
- type: list
- returned: success
- contains:
- name:
- description:
- - Specifies the option name.
- type: str
- returned: success
- value:
- description:
- - Specifies the option value.
- type: str
- returned: success
+RETURN = r"""
+subnet_id:
+ description:
+ - Specifies the ID of the subnet to which the port belongs.
+ type: str
+ returned: success
+admin_state_up:
+ description:
+ - Specifies the administrative state of the port.
+ type: bool
+ returned: success
+allowed_address_pairs:
+ description:
+ - Specifies a set of zero or more allowed address pairs.
+ type: list
+ returned: success
+ contains:
ip_address:
- description:
- - Specifies the port IP address.
- type: str
- returned: success
- name:
- description:
- - Specifies the port name. The value can contain no more than 255
- characters.
- type: str
- returned: success
- security_groups:
- description:
- - Specifies the ID of the security group.
- type: list
- returned: success
+ description:
+ - Specifies the IP address. It cannot set it to 0.0.0.0. Configure an independent security group for the port if a
+ large CIDR block (subnet mask less than 24) is configured for parameter allowed_address_pairs.
+ type: str
+ returned: success
mac_address:
- description:
- - Specifies the port MAC address.
- type: str
- returned: success
-'''
+ description:
+ - Specifies the MAC address.
+ type: str
+ returned: success
+extra_dhcp_opts:
+ description:
+ - Specifies the extended option of DHCP.
+ type: list
+ returned: success
+ contains:
+ name:
+ description:
+ - Specifies the option name.
+ type: str
+ returned: success
+ value:
+ description:
+ - Specifies the option value.
+ type: str
+ returned: success
+ip_address:
+ description:
+ - Specifies the port IP address.
+ type: str
+ returned: success
+name:
+ description:
+ - Specifies the port name. The value can contain no more than 255 characters.
+ type: str
+ returned: success
+security_groups:
+ description:
+ - Specifies the ID of the security group.
+ type: list
+ returned: success
+mac_address:
+ description:
+ - Specifies the port MAC address.
+ type: str
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcClientException404, HwcModule,
diff --git a/plugins/modules/hwc_vpc_private_ip.py b/plugins/modules/hwc_vpc_private_ip.py
index 95e759f6f2..695c644cb9 100644
--- a/plugins/modules/hwc_vpc_private_ip.py
+++ b/plugins/modules/hwc_vpc_private_ip.py
@@ -12,54 +12,51 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_vpc_private_ip
description:
- - vpc private ip management.
-short_description: Creates a resource of Vpc/PrivateIP in Huawei Cloud
+ - VPC private IP management.
+short_description: Creates a resource of VPC/PrivateIP in Huawei Cloud
notes:
- - If O(id) option is provided, it takes precedence over O(subnet_id), O(ip_address) for private ip selection.
- - O(subnet_id), O(ip_address) are used for private ip selection. If more than one private ip with this options exists, execution is aborted.
- - No parameter support updating. If one of option is changed, the module will create a new resource.
+ - If O(id) option is provided, it takes precedence over O(subnet_id), O(ip_address) for private IP selection.
+ - O(subnet_id), O(ip_address) are used for private IP selection. If more than one private IP with this options exists, execution
+ is aborted.
+ - No parameter support updating. If one of option is changed, the module will create a new resource.
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Whether the given object should exist in Huawei Cloud.
- type: str
- choices: ['present', 'absent']
- default: 'present'
- subnet_id:
- description:
- - Specifies the ID of the subnet from which IP addresses are
- assigned. Cannot be changed after creating the private ip.
- type: str
- required: true
- ip_address:
- description:
- - Specifies the target IP address. The value can be an available IP
- address in the subnet. If it is not specified, the system
- automatically assigns an IP address. Cannot be changed after
- creating the private ip.
- type: str
- required: false
+ state:
+ description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ subnet_id:
+ description:
+ - Specifies the ID of the subnet from which IP addresses are assigned. Cannot be changed after creating the private
+ IP.
+ type: str
+ required: true
+ ip_address:
+ description:
+ - Specifies the target IP address. The value can be an available IP address in the subnet. If it is not specified, the
+ system automatically assigns an IP address. Cannot be changed after creating the private IP.
+ type: str
+ required: false
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
-# create a private ip
+EXAMPLES = r"""
+# create a private IP
- name: Create vpc
hwc_network_vpc:
cidr: "192.168.100.0/24"
@@ -73,27 +70,25 @@ EXAMPLES = '''
vpc_id: "{{ vpc.id }}"
cidr: "192.168.100.0/26"
register: subnet
-- name: Create a private ip
+- name: Create a private IP
community.general.hwc_vpc_private_ip:
subnet_id: "{{ subnet.id }}"
ip_address: "192.168.100.33"
-'''
+"""
-RETURN = '''
- subnet_id:
- description:
- - Specifies the ID of the subnet from which IP addresses are
- assigned.
- type: str
- returned: success
- ip_address:
- description:
- - Specifies the target IP address. The value can be an available IP
- address in the subnet. If it is not specified, the system
- automatically assigns an IP address.
- type: str
- returned: success
-'''
+RETURN = r"""
+subnet_id:
+ description:
+ - Specifies the ID of the subnet from which IP addresses are assigned.
+ type: str
+ returned: success
+ip_address:
+ description:
+ - Specifies the target IP address. The value can be an available IP address in the subnet. If it is not specified, the
+ system automatically assigns an IP address.
+ type: str
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcModule, are_different_dicts, build_path,
diff --git a/plugins/modules/hwc_vpc_route.py b/plugins/modules/hwc_vpc_route.py
index 091b49b0c8..85224fd4c8 100644
--- a/plugins/modules/hwc_vpc_route.py
+++ b/plugins/modules/hwc_vpc_route.py
@@ -12,60 +12,59 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_vpc_route
description:
- - vpc route management.
-short_description: Creates a resource of Vpc/Route in Huawei Cloud
+ - VPC route management.
+short_description: Creates a resource of VPC/Route in Huawei Cloud
notes:
- - If O(id) option is provided, it takes precedence over O(destination), O(vpc_id), O(type), and O(next_hop) for route selection.
- - O(destination), O(vpc_id), O(type) and O(next_hop) are used for route selection. If more than one route with this options exists, execution is aborted.
- - No parameter support updating. If one of option is changed, the module will create a new resource.
+ - If O(id) option is provided, it takes precedence over O(destination), O(vpc_id), O(type), and O(next_hop) for route selection.
+ - O(destination), O(vpc_id), O(type) and O(next_hop) are used for route selection. If more than one route with this options
+ exists, execution is aborted.
+ - No parameter support updating. If one of option is changed, the module will create a new resource.
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Whether the given object should exist in Huawei Cloud.
- type: str
- choices: ['present', 'absent']
- default: 'present'
- destination:
- description:
- - Specifies the destination IP address or CIDR block.
- type: str
- required: true
- next_hop:
- description:
- - Specifies the next hop. The value is VPC peering connection ID.
- type: str
- required: true
- vpc_id:
- description:
- - Specifies the VPC ID to which route is added.
- type: str
- required: true
- type:
- description:
- - Specifies the type of route.
- type: str
- required: false
- default: 'peering'
+ state:
+ description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ destination:
+ description:
+ - Specifies the destination IP address or CIDR block.
+ type: str
+ required: true
+ next_hop:
+ description:
+ - Specifies the next hop. The value is VPC peering connection ID.
+ type: str
+ required: true
+ vpc_id:
+ description:
+ - Specifies the VPC ID to which route is added.
+ type: str
+ required: true
+ type:
+ description:
+ - Specifies the type of route.
+ type: str
+ required: false
+ default: 'peering'
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# create a peering connect
- name: Create a local vpc
hwc_network_vpc:
@@ -91,35 +90,35 @@ EXAMPLES = '''
vpc_id: "{{ vpc1.id }}"
destination: "192.168.0.0/16"
next_hop: "{{ connect.id }}"
-'''
+"""
-RETURN = '''
- id:
- description:
- - UUID of the route.
- type: str
- returned: success
- destination:
- description:
- - Specifies the destination IP address or CIDR block.
- type: str
- returned: success
- next_hop:
- description:
- - Specifies the next hop. The value is VPC peering connection ID.
- type: str
- returned: success
- vpc_id:
- description:
- - Specifies the VPC ID to which route is added.
- type: str
- returned: success
- type:
- description:
- - Specifies the type of route.
- type: str
- returned: success
-'''
+RETURN = r"""
+id:
+ description:
+ - UUID of the route.
+ type: str
+ returned: success
+destination:
+ description:
+ - Specifies the destination IP address or CIDR block.
+ type: str
+ returned: success
+next_hop:
+ description:
+ - Specifies the next hop. The value is VPC peering connection ID.
+ type: str
+ returned: success
+vpc_id:
+ description:
+ - Specifies the VPC ID to which route is added.
+ type: str
+ returned: success
+type:
+ description:
+ - Specifies the type of route.
+ type: str
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcModule, are_different_dicts, build_path,
diff --git a/plugins/modules/hwc_vpc_security_group.py b/plugins/modules/hwc_vpc_security_group.py
index aa65e801c4..9f53b49c0d 100644
--- a/plugins/modules/hwc_vpc_security_group.py
+++ b/plugins/modules/hwc_vpc_security_group.py
@@ -12,162 +12,141 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_vpc_security_group
description:
- - vpc security group management.
-short_description: Creates a resource of Vpc/SecurityGroup in Huawei Cloud
+ - VPC security group management.
+short_description: Creates a resource of VPC/SecurityGroup in Huawei Cloud
notes:
- - If O(id) option is provided, it takes precedence over O(name),
- O(enterprise_project_id), and O(vpc_id) for security group selection.
- - O(name), O(enterprise_project_id) and O(vpc_id) are used for security
- group selection. If more than one security group with this options exists,
- execution is aborted.
- - No parameter support updating. If one of option is changed, the module
- will create a new resource.
+ - If O(id) option is provided, it takes precedence over O(name), O(enterprise_project_id), and O(vpc_id) for security group
+ selection.
+ - O(name), O(enterprise_project_id) and O(vpc_id) are used for security group selection. If more than one security group
+ with this options exists, execution is aborted.
+ - No parameter support updating. If one of option is changed, the module will create a new resource.
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Whether the given object should exist in Huawei Cloud.
- type: str
- choices: ['present', 'absent']
- default: 'present'
- name:
- description:
- - Specifies the security group name. The value is a string of 1 to
- 64 characters that can contain letters, digits, underscores (V(_)),
- hyphens (V(-)), and periods (V(.)).
- type: str
- required: true
- enterprise_project_id:
- description:
- - Specifies the enterprise project ID. When creating a security
- group, associate the enterprise project ID with the security
- group.s
- type: str
- required: false
- vpc_id:
- description:
- - Specifies the resource ID of the VPC to which the security group
- belongs.
- type: str
- required: false
+ state:
+ description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ name:
+ description:
+ - Specifies the security group name. The value is a string of 1 to 64 characters that can contain letters, digits, underscores
+ (V(_)), hyphens (V(-)), and periods (V(.)).
+ type: str
+ required: true
+ enterprise_project_id:
+ description:
+ - Specifies the enterprise project ID. When creating a security group, associate the enterprise project ID with the
+ security group.s.
+ type: str
+ required: false
+ vpc_id:
+ description:
+ - Specifies the resource ID of the VPC to which the security group belongs.
+ type: str
+ required: false
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# create a security group
- name: Create a security group
community.general.hwc_vpc_security_group:
name: "ansible_network_security_group_test"
-'''
+"""
-RETURN = '''
- name:
- description:
- - Specifies the security group name. The value is a string of 1 to
- 64 characters that can contain letters, digits, underscores (V(_)),
- hyphens (V(-)), and periods (V(.)).
- type: str
- returned: success
- enterprise_project_id:
- description:
- - Specifies the enterprise project ID. When creating a security
- group, associate the enterprise project ID with the security
- group.
- type: str
- returned: success
- vpc_id:
- description:
- - Specifies the resource ID of the VPC to which the security group
- belongs.
- type: str
- returned: success
- rules:
- description:
- - Specifies the security group rule, which ensures that resources
- in the security group can communicate with one another.
- type: complex
- returned: success
- contains:
- description:
- description:
- - Provides supplementary information about the security
- group rule.
- type: str
- returned: success
- direction:
- description:
- - Specifies the direction of access control. The value can
- be egress or ingress.
- type: str
- returned: success
- ethertype:
- description:
- - Specifies the IP protocol version. The value can be IPv4
- or IPv6.
- type: str
- returned: success
- id:
- description:
- - Specifies the security group rule ID.
- type: str
- returned: success
- port_range_max:
- description:
- - Specifies the end port number. The value ranges from 1 to
- 65535. If the protocol is not icmp, the value cannot be
- smaller than the port_range_min value. An empty value
- indicates all ports.
- type: int
- returned: success
- port_range_min:
- description:
- - Specifies the start port number. The value ranges from 1
- to 65535. The value cannot be greater than the
- port_range_max value. An empty value indicates all ports.
- type: int
- returned: success
- protocol:
- description:
- - Specifies the protocol type. The value can be icmp, tcp,
- udp, or others. If the parameter is left blank, the
- security group supports all protocols.
- type: str
- returned: success
- remote_address_group_id:
- description:
- - Specifies the ID of remote IP address group.
- type: str
- returned: success
- remote_group_id:
- description:
- - Specifies the ID of the peer security group.
- type: str
- returned: success
- remote_ip_prefix:
- description:
- - Specifies the remote IP address. If the access control
- direction is set to egress, the parameter specifies the
- source IP address. If the access control direction is set
- to ingress, the parameter specifies the destination IP
- address.
- type: str
- returned: success
-'''
+RETURN = r"""
+name:
+ description:
+ - Specifies the security group name. The value is a string of 1 to 64 characters that can contain letters, digits, underscores
+ (V(_)), hyphens (V(-)), and periods (V(.)).
+ type: str
+ returned: success
+enterprise_project_id:
+ description:
+ - Specifies the enterprise project ID. When creating a security group, associate the enterprise project ID with the security
+ group.
+ type: str
+ returned: success
+vpc_id:
+ description:
+ - Specifies the resource ID of the VPC to which the security group belongs.
+ type: str
+ returned: success
+rules:
+ description:
+ - Specifies the security group rule, which ensures that resources in the security group can communicate with one another.
+ type: complex
+ returned: success
+ contains:
+ description:
+ description:
+ - Provides supplementary information about the security group rule.
+ type: str
+ returned: success
+ direction:
+ description:
+ - Specifies the direction of access control. The value can be egress or ingress.
+ type: str
+ returned: success
+ ethertype:
+ description:
+ - Specifies the IP protocol version. The value can be IPv4 or IPv6.
+ type: str
+ returned: success
+ id:
+ description:
+ - Specifies the security group rule ID.
+ type: str
+ returned: success
+ port_range_max:
+ description:
+ - Specifies the end port number. The value ranges from 1 to 65535. If the protocol is not icmp, the value cannot be
+ smaller than the port_range_min value. An empty value indicates all ports.
+ type: int
+ returned: success
+ port_range_min:
+ description:
+ - Specifies the start port number. The value ranges from 1 to 65535. The value cannot be greater than the port_range_max
+ value. An empty value indicates all ports.
+ type: int
+ returned: success
+ protocol:
+ description:
+ - Specifies the protocol type. The value can be icmp, tcp, udp, or others. If the parameter is left blank, the security
+ group supports all protocols.
+ type: str
+ returned: success
+ remote_address_group_id:
+ description:
+ - Specifies the ID of remote IP address group.
+ type: str
+ returned: success
+ remote_group_id:
+ description:
+ - Specifies the ID of the peer security group.
+ type: str
+ returned: success
+ remote_ip_prefix:
+ description:
+ - Specifies the remote IP address. If the access control direction is set to egress, the parameter specifies the source
+ IP address. If the access control direction is set to ingress, the parameter specifies the destination IP address.
+ type: str
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcModule, are_different_dicts, build_path,
diff --git a/plugins/modules/hwc_vpc_security_group_rule.py b/plugins/modules/hwc_vpc_security_group_rule.py
index 899647e8ce..0848901cd5 100644
--- a/plugins/modules/hwc_vpc_security_group_rule.py
+++ b/plugins/modules/hwc_vpc_security_group_rule.py
@@ -12,105 +12,90 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_vpc_security_group_rule
description:
- - vpc security group management.
-short_description: Creates a resource of Vpc/SecurityGroupRule in Huawei Cloud
+ - VPC security group management.
+short_description: Creates a resource of VPC/SecurityGroupRule in Huawei Cloud
notes:
- - If O(id) option is provided, it takes precedence over
- O(security_group_id) for security group rule selection.
- - O(security_group_id) is used for security group rule selection. If more
- than one security group rule with this options exists, execution is
- aborted.
- - No parameter support updating. If one of option is changed, the module
- will create a new resource.
+ - If O(id) option is provided, it takes precedence over O(security_group_id) for security group rule selection.
+ - O(security_group_id) is used for security group rule selection. If more than one security group rule with this options
+ exists, execution is aborted.
+ - No parameter support updating. If one of option is changed, the module will create a new resource.
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Whether the given object should exist in Huawei Cloud.
- type: str
- choices: ['present', 'absent']
- default: 'present'
- direction:
- description:
- - Specifies the direction of access control. The value can be
- egress or ingress.
- type: str
- required: true
- security_group_id:
- description:
- - Specifies the security group rule ID, which uniquely identifies
- the security group rule.
- type: str
- required: true
+ state:
description:
- description:
- - Provides supplementary information about the security group rule.
- The value is a string of no more than 255 characters that can
- contain letters and digits.
- type: str
- required: false
- ethertype:
- description:
- - Specifies the IP protocol version. The value can be IPv4 or IPv6.
- If you do not set this parameter, IPv4 is used by default.
- type: str
- required: false
- port_range_max:
- description:
- - Specifies the end port number. The value ranges from 1 to 65535.
- If the protocol is not icmp, the value cannot be smaller than the
- port_range_min value. An empty value indicates all ports.
- type: int
- required: false
- port_range_min:
- description:
- - Specifies the start port number. The value ranges from 1 to
- 65535. The value cannot be greater than the port_range_max value.
- An empty value indicates all ports.
- type: int
- required: false
- protocol:
- description:
- - Specifies the protocol type. The value can be icmp, tcp, or udp.
- If the parameter is left blank, the security group supports all
- protocols.
- type: str
- required: false
- remote_group_id:
- description:
- - Specifies the ID of the peer security group. The value is
- exclusive with parameter remote_ip_prefix.
- type: str
- required: false
- remote_ip_prefix:
- description:
- - Specifies the remote IP address. If the access control direction
- is set to egress, the parameter specifies the source IP address.
- If the access control direction is set to ingress, the parameter
- specifies the destination IP address. The value can be in the
- CIDR format or IP addresses. The parameter is exclusive with
- parameter remote_group_id.
- type: str
- required: false
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ direction:
+ description:
+ - Specifies the direction of access control. The value can be egress or ingress.
+ type: str
+ required: true
+ security_group_id:
+ description:
+ - Specifies the security group rule ID, which uniquely identifies the security group rule.
+ type: str
+ required: true
+ description:
+ description:
+ - Provides supplementary information about the security group rule. The value is a string of no more than 255 characters
+ that can contain letters and digits.
+ type: str
+ required: false
+ ethertype:
+ description:
+ - Specifies the IP protocol version. The value can be IPv4 or IPv6. If you do not set this parameter, IPv4 is used by
+ default.
+ type: str
+ required: false
+ port_range_max:
+ description:
+ - Specifies the end port number. The value ranges from 1 to 65535. If the protocol is not icmp, the value cannot be
+ smaller than the port_range_min value. An empty value indicates all ports.
+ type: int
+ required: false
+ port_range_min:
+ description:
+ - Specifies the start port number. The value ranges from 1 to 65535. The value cannot be greater than the port_range_max
+ value. An empty value indicates all ports.
+ type: int
+ required: false
+ protocol:
+ description:
+ - Specifies the protocol type. The value can be icmp, tcp, or udp. If the parameter is left blank, the security group
+ supports all protocols.
+ type: str
+ required: false
+ remote_group_id:
+ description:
+ - Specifies the ID of the peer security group. The value is exclusive with parameter remote_ip_prefix.
+ type: str
+ required: false
+ remote_ip_prefix:
+ description:
+ - Specifies the remote IP address. If the access control direction is set to egress, the parameter specifies the source
+ IP address. If the access control direction is set to ingress, the parameter specifies the destination IP address.
+ The value can be in the CIDR format or IP addresses. The parameter is exclusive with parameter remote_group_id.
+ type: str
+ required: false
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# create a security group rule
- name: Create a security group
hwc_vpc_security_group:
@@ -125,72 +110,62 @@ EXAMPLES = '''
security_group_id: "{{ sg.id }}"
port_range_min: 22
remote_ip_prefix: "0.0.0.0/0"
-'''
+"""
-RETURN = '''
- direction:
- description:
- - Specifies the direction of access control. The value can be
- egress or ingress.
- type: str
- returned: success
- security_group_id:
- description:
- - Specifies the security group rule ID, which uniquely identifies
- the security group rule.
- type: str
- returned: success
- description:
- description:
- - Provides supplementary information about the security group rule.
- The value is a string of no more than 255 characters that can
- contain letters and digits.
- type: str
- returned: success
- ethertype:
- description:
- - Specifies the IP protocol version. The value can be IPv4 or IPv6.
- If you do not set this parameter, IPv4 is used by default.
- type: str
- returned: success
- port_range_max:
- description:
- - Specifies the end port number. The value ranges from 1 to 65535.
- If the protocol is not icmp, the value cannot be smaller than the
- port_range_min value. An empty value indicates all ports.
- type: int
- returned: success
- port_range_min:
- description:
- - Specifies the start port number. The value ranges from 1 to
- 65535. The value cannot be greater than the port_range_max value.
- An empty value indicates all ports.
- type: int
- returned: success
- protocol:
- description:
- - Specifies the protocol type. The value can be icmp, tcp, or udp.
- If the parameter is left blank, the security group supports all
- protocols.
- type: str
- returned: success
- remote_group_id:
- description:
- - Specifies the ID of the peer security group. The value is
- exclusive with parameter remote_ip_prefix.
- type: str
- returned: success
- remote_ip_prefix:
- description:
- - Specifies the remote IP address. If the access control direction
- is set to egress, the parameter specifies the source IP address.
- If the access control direction is set to ingress, the parameter
- specifies the destination IP address. The value can be in the
- CIDR format or IP addresses. The parameter is exclusive with
- parameter remote_group_id.
- type: str
- returned: success
-'''
+RETURN = r"""
+direction:
+ description:
+ - Specifies the direction of access control. The value can be egress or ingress.
+ type: str
+ returned: success
+security_group_id:
+ description:
+ - Specifies the security group rule ID, which uniquely identifies the security group rule.
+ type: str
+ returned: success
+description:
+ description:
+ - Provides supplementary information about the security group rule. The value is a string of no more than 255 characters
+ that can contain letters and digits.
+ type: str
+ returned: success
+ethertype:
+ description:
+ - Specifies the IP protocol version. The value can be IPv4 or IPv6. If you do not set this parameter, IPv4 is used by
+ default.
+ type: str
+ returned: success
+port_range_max:
+ description:
+ - Specifies the end port number. The value ranges from 1 to 65535. If the protocol is not icmp, the value cannot be smaller
+ than the port_range_min value. An empty value indicates all ports.
+ type: int
+ returned: success
+port_range_min:
+ description:
+ - Specifies the start port number. The value ranges from 1 to 65535. The value cannot be greater than the port_range_max
+ value. An empty value indicates all ports.
+ type: int
+ returned: success
+protocol:
+ description:
+ - Specifies the protocol type. The value can be icmp, tcp, or udp. If the parameter is left blank, the security group
+ supports all protocols.
+ type: str
+ returned: success
+remote_group_id:
+ description:
+ - Specifies the ID of the peer security group. The value is exclusive with parameter remote_ip_prefix.
+ type: str
+ returned: success
+remote_ip_prefix:
+ description:
+ - Specifies the remote IP address. If the access control direction is set to egress, the parameter specifies the source
+ IP address. If the access control direction is set to ingress, the parameter specifies the destination IP address. The
+ value can be in the CIDR format or IP addresses. The parameter is exclusive with parameter remote_group_id.
+ type: str
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcModule, are_different_dicts, build_path,
diff --git a/plugins/modules/hwc_vpc_subnet.py b/plugins/modules/hwc_vpc_subnet.py
index ff6e425ca9..84a9219370 100644
--- a/plugins/modules/hwc_vpc_subnet.py
+++ b/plugins/modules/hwc_vpc_subnet.py
@@ -12,99 +12,90 @@ __metaclass__ = type
# Documentation
###############################################################################
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: hwc_vpc_subnet
description:
- - subnet management.
-short_description: Creates a resource of Vpc/Subnet in Huawei Cloud
+ - Subnet management.
+short_description: Creates a resource of VPC/Subnet in Huawei Cloud
version_added: '0.2.0'
author: Huawei Inc. (@huaweicloud)
requirements:
- - keystoneauth1 >= 3.6.0
+ - keystoneauth1 >= 3.6.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
+ state:
+ description:
+ - Whether the given object should exist in Huawei Cloud.
+ type: str
+ choices: ['present', 'absent']
+ default: 'present'
+ timeouts:
+ description:
+ - The timeouts for each operations.
+ type: dict
+ default: {}
+ suboptions:
+ create:
description:
- - Whether the given object should exist in Huawei Cloud.
+ - The timeouts for create operation.
type: str
- choices: ['present', 'absent']
- default: 'present'
- timeouts:
+ default: '15m'
+ update:
description:
- - The timeouts for each operations.
- type: dict
- default: {}
- suboptions:
- create:
- description:
- - The timeouts for create operation.
- type: str
- default: '15m'
- update:
- description:
- - The timeouts for update operation.
- type: str
- default: '15m'
- cidr:
- description:
- - Specifies the subnet CIDR block. The value must be within the VPC
- CIDR block and be in CIDR format. The subnet mask cannot be
- greater than 28. Cannot be changed after creating the subnet.
+ - The timeouts for update operation.
type: str
- required: true
- gateway_ip:
- description:
- - Specifies the gateway of the subnet. The value must be an IP
- address in the subnet. Cannot be changed after creating the subnet.
- type: str
- required: true
- name:
- description:
- - Specifies the subnet name. The value is a string of 1 to 64
- characters that can contain letters, digits, underscores (V(_)),
- hyphens (V(-)), and periods (V(.)).
- type: str
- required: true
- vpc_id:
- description:
- - Specifies the ID of the VPC to which the subnet belongs. Cannot
- be changed after creating the subnet.
- type: str
- required: true
- availability_zone:
- description:
- - Specifies the AZ to which the subnet belongs. Cannot be changed
- after creating the subnet.
- type: str
- required: false
- dhcp_enable:
- description:
- - Specifies whether DHCP is enabled for the subnet. The value can
- be true (enabled) or false(disabled), and default value is true.
- If this parameter is set to false, newly created ECSs cannot
- obtain IP addresses, and usernames and passwords cannot be
- injected using Cloud-init.
- type: bool
- required: false
- dns_address:
- description:
- - Specifies the DNS server addresses for subnet. The address
- in the head will be used first.
- type: list
- elements: str
- required: false
+ default: '15m'
+ cidr:
+ description:
+ - Specifies the subnet CIDR block. The value must be within the VPC CIDR block and be in CIDR format. The subnet mask
+ cannot be greater than 28. Cannot be changed after creating the subnet.
+ type: str
+ required: true
+ gateway_ip:
+ description:
+ - Specifies the gateway of the subnet. The value must be an IP address in the subnet. Cannot be changed after creating
+ the subnet.
+ type: str
+ required: true
+ name:
+ description:
+ - Specifies the subnet name. The value is a string of 1 to 64 characters that can contain letters, digits, underscores
+ (V(_)), hyphens (V(-)), and periods (V(.)).
+ type: str
+ required: true
+ vpc_id:
+ description:
+ - Specifies the ID of the VPC to which the subnet belongs. Cannot be changed after creating the subnet.
+ type: str
+ required: true
+ availability_zone:
+ description:
+ - Specifies the AZ to which the subnet belongs. Cannot be changed after creating the subnet.
+ type: str
+ required: false
+ dhcp_enable:
+ description:
+ - Specifies whether DHCP is enabled for the subnet. The value can be true (enabled) or false(disabled), and default
+ value is true. If this parameter is set to false, newly created ECSs cannot obtain IP addresses, and usernames and
+ passwords cannot be injected using Cloud-init.
+ type: bool
+ required: false
+ dns_address:
+ description:
+ - Specifies the DNS server addresses for subnet. The address in the head will be used first.
+ type: list
+ elements: str
+ required: false
extends_documentation_fragment:
- community.general.hwc
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# create subnet
- name: Create vpc
hwc_network_vpc:
@@ -118,55 +109,49 @@ EXAMPLES = '''
gateway_ip: "192.168.100.32"
name: "ansible_network_subnet_test"
dhcp_enable: true
-'''
+"""
-RETURN = '''
- cidr:
- description:
- - Specifies the subnet CIDR block. The value must be within the VPC
- CIDR block and be in CIDR format. The subnet mask cannot be
- greater than 28.
- type: str
- returned: success
- gateway_ip:
- description:
- - Specifies the gateway of the subnet. The value must be an IP
- address in the subnet.
- type: str
- returned: success
- name:
- description:
- - Specifies the subnet name. The value is a string of 1 to 64
- characters that can contain letters, digits, underscores (V(_)),
- hyphens (V(-)), and periods (V(.)).
- type: str
- returned: success
- vpc_id:
- description:
- - Specifies the ID of the VPC to which the subnet belongs.
- type: str
- returned: success
- availability_zone:
- description:
- - Specifies the AZ to which the subnet belongs.
- type: str
- returned: success
- dhcp_enable:
- description:
- - Specifies whether DHCP is enabled for the subnet. The value can
- be true (enabled) or false(disabled), and default value is true.
- If this parameter is set to false, newly created ECSs cannot
- obtain IP addresses, and usernames and passwords cannot be
- injected using Cloud-init.
- type: bool
- returned: success
- dns_address:
- description:
- - Specifies the DNS server addresses for subnet. The address
- in the head will be used first.
- type: list
- returned: success
-'''
+RETURN = r"""
+cidr:
+ description:
+ - Specifies the subnet CIDR block. The value must be within the VPC CIDR block and be in CIDR format. The subnet mask
+ cannot be greater than 28.
+ type: str
+ returned: success
+gateway_ip:
+ description:
+ - Specifies the gateway of the subnet. The value must be an IP address in the subnet.
+ type: str
+ returned: success
+name:
+ description:
+ - Specifies the subnet name. The value is a string of 1 to 64 characters that can contain letters, digits, underscores
+ (V(_)), hyphens (V(-)), and periods (V(.)).
+ type: str
+ returned: success
+vpc_id:
+ description:
+ - Specifies the ID of the VPC to which the subnet belongs.
+ type: str
+ returned: success
+availability_zone:
+ description:
+ - Specifies the AZ to which the subnet belongs.
+ type: str
+ returned: success
+dhcp_enable:
+ description:
+ - Specifies whether DHCP is enabled for the subnet. The value can be true (enabled) or false(disabled), and default value
+ is true. If this parameter is set to false, newly created ECSs cannot obtain IP addresses, and usernames and passwords
+ cannot be injected using Cloud-init.
+ type: bool
+ returned: success
+dns_address:
+ description:
+ - Specifies the DNS server addresses for subnet. The address in the head will be used first.
+ type: list
+ returned: success
+"""
from ansible_collections.community.general.plugins.module_utils.hwc_utils import (
Config, HwcClientException, HwcClientException404, HwcModule,
diff --git a/plugins/modules/ibm_sa_domain.py b/plugins/modules/ibm_sa_domain.py
index 774f29134c..d34474b551 100644
--- a/plugins/modules/ibm_sa_domain.py
+++ b/plugins/modules/ibm_sa_domain.py
@@ -10,92 +10,90 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ibm_sa_domain
short_description: Manages domains on IBM Spectrum Accelerate Family storage systems
description:
- - "This module can be used to add domains to or removes them from IBM Spectrum Accelerate Family storage systems."
-
+ - This module can be used to add domains to or removes them from IBM Spectrum Accelerate Family storage systems.
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- domain:
- description:
- - Name of the domain to be managed.
- required: true
- type: str
- state:
- description:
- - The desired state of the domain.
- default: "present"
- choices: [ "present", "absent" ]
- type: str
- ldap_id:
- description:
- - ldap id to add to the domain.
- required: false
- type: str
- size:
- description:
- - Size of the domain.
- required: false
- type: str
- hard_capacity:
- description:
- - Hard capacity of the domain.
- required: false
- type: str
- soft_capacity:
- description:
- - Soft capacity of the domain.
- required: false
- type: str
- max_cgs:
- description:
- - Number of max cgs.
- required: false
- type: str
- max_dms:
- description:
- - Number of max dms.
- required: false
- type: str
- max_mirrors:
- description:
- - Number of max_mirrors.
- required: false
- type: str
- max_pools:
- description:
- - Number of max_pools.
- required: false
- type: str
- max_volumes:
- description:
- - Number of max_volumes.
- required: false
- type: str
- perf_class:
- description:
- - Add the domain to a performance class.
- required: false
- type: str
+ domain:
+ description:
+ - Name of the domain to be managed.
+ required: true
+ type: str
+ state:
+ description:
+ - The desired state of the domain.
+ default: "present"
+ choices: ["present", "absent"]
+ type: str
+ ldap_id:
+ description:
+ - LDAP ID to add to the domain.
+ required: false
+ type: str
+ size:
+ description:
+ - Size of the domain.
+ required: false
+ type: str
+ hard_capacity:
+ description:
+ - Hard capacity of the domain.
+ required: false
+ type: str
+ soft_capacity:
+ description:
+ - Soft capacity of the domain.
+ required: false
+ type: str
+ max_cgs:
+ description:
+ - Number of max cgs.
+ required: false
+ type: str
+ max_dms:
+ description:
+ - Number of max dms.
+ required: false
+ type: str
+ max_mirrors:
+ description:
+ - Number of max_mirrors.
+ required: false
+ type: str
+ max_pools:
+ description:
+ - Number of max_pools.
+ required: false
+ type: str
+ max_volumes:
+ description:
+ - Number of max_volumes.
+ required: false
+ type: str
+ perf_class:
+ description:
+ - Add the domain to a performance class.
+ required: false
+ type: str
extends_documentation_fragment:
- community.general.ibm_storage
- community.general.attributes
author:
- - Tzur Eliyahu (@tzure)
-'''
+ - Tzur Eliyahu (@tzure)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Define new domain.
community.general.ibm_sa_domain:
domain: domain_name
@@ -112,14 +110,14 @@ EXAMPLES = '''
username: admin
password: secret
endpoints: hostdev-system
-'''
-RETURN = '''
+"""
+RETURN = r"""
msg:
- description: module return status.
- returned: as needed
- type: str
- sample: "domain 'domain_name' created successfully."
-'''
+ description: Module return status.
+ returned: as needed
+ type: str
+ sample: "domain 'domain_name' created successfully."
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ibm_sa_utils import execute_pyxcli_command, \
diff --git a/plugins/modules/ibm_sa_host.py b/plugins/modules/ibm_sa_host.py
index 614865ae01..f6613b3b29 100644
--- a/plugins/modules/ibm_sa_host.py
+++ b/plugins/modules/ibm_sa_host.py
@@ -10,66 +10,61 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ibm_sa_host
short_description: Adds hosts to or removes them from IBM Spectrum Accelerate Family storage systems
description:
- - "This module adds hosts to or removes them from IBM Spectrum Accelerate Family storage systems."
-
+ - This module adds hosts to or removes them from IBM Spectrum Accelerate Family storage systems.
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- host:
- description:
- - Host name.
- required: true
- type: str
- state:
- description:
- - Host state.
- default: "present"
- choices: [ "present", "absent" ]
- type: str
- cluster:
- description:
- - The name of the cluster to include the host.
- required: false
- type: str
- domain:
- description:
- - The domains the cluster will be attached to.
- To include more than one domain,
- separate domain names with commas.
- To include all existing domains, use an asterisk ("*").
- required: false
- type: str
- iscsi_chap_name:
- description:
- - The host's CHAP name identifier
- required: false
- type: str
- iscsi_chap_secret:
- description:
- - The password of the initiator used to
- authenticate to the system when CHAP is enable
- required: false
- type: str
+ host:
+ description:
+ - Host name.
+ required: true
+ type: str
+ state:
+ description:
+ - Host state.
+ default: "present"
+ choices: ["present", "absent"]
+ type: str
+ cluster:
+ description:
+ - The name of the cluster to include the host.
+ required: false
+ type: str
+ domain:
+ description:
+ - The domains the cluster will be attached to. To include more than one domain, separate domain names with commas. To
+ include all existing domains, use an asterisk (V(*)).
+ required: false
+ type: str
+ iscsi_chap_name:
+ description:
+ - The host's CHAP name identifier.
+ required: false
+ type: str
+ iscsi_chap_secret:
+ description:
+ - The password of the initiator used to authenticate to the system when CHAP is enable.
+ required: false
+ type: str
extends_documentation_fragment:
- community.general.ibm_storage
- community.general.attributes
author:
- - Tzur Eliyahu (@tzure)
-'''
+ - Tzur Eliyahu (@tzure)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Define new host.
community.general.ibm_sa_host:
host: host_name
@@ -85,9 +80,9 @@ EXAMPLES = '''
username: admin
password: secret
endpoints: hostdev-system
-'''
-RETURN = '''
-'''
+"""
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ibm_sa_utils import execute_pyxcli_command, \
diff --git a/plugins/modules/ibm_sa_host_ports.py b/plugins/modules/ibm_sa_host_ports.py
index fdb27f85a2..25342eb62e 100644
--- a/plugins/modules/ibm_sa_host_ports.py
+++ b/plugins/modules/ibm_sa_host_ports.py
@@ -10,58 +10,55 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ibm_sa_host_ports
short_description: Add host ports on IBM Spectrum Accelerate Family storage systems
description:
- - "This module adds ports to or removes them from the hosts
- on IBM Spectrum Accelerate Family storage systems."
-
+ - This module adds ports to or removes them from the hosts on IBM Spectrum Accelerate Family storage systems.
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- host:
- description:
- - Host name.
- required: true
- type: str
- state:
- description:
- - Host ports state.
- default: "present"
- choices: [ "present", "absent" ]
- type: str
- iscsi_name:
- description:
- - iSCSI initiator name.
- required: false
- type: str
- fcaddress:
- description:
- - Fiber channel address.
- required: false
- type: str
- num_of_visible_targets:
- description:
- - Number of visible targets.
- required: false
- type: str
+ host:
+ description:
+ - Host name.
+ required: true
+ type: str
+ state:
+ description:
+ - Host ports state.
+ default: "present"
+ choices: ["present", "absent"]
+ type: str
+ iscsi_name:
+ description:
+ - The iSCSI initiator name.
+ required: false
+ type: str
+ fcaddress:
+ description:
+ - Fiber channel address.
+ required: false
+ type: str
+ num_of_visible_targets:
+ description:
+ - Number of visible targets.
+ required: false
+ type: str
extends_documentation_fragment:
- community.general.ibm_storage
- community.general.attributes
author:
- - Tzur Eliyahu (@tzure)
-'''
+ - Tzur Eliyahu (@tzure)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add ports for host.
community.general.ibm_sa_host_ports:
host: test_host
@@ -79,10 +76,9 @@ EXAMPLES = '''
password: secret
endpoints: hostdev-system
state: absent
-
-'''
-RETURN = '''
-'''
+"""
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ibm_sa_utils import (execute_pyxcli_command, connect_ssl,
diff --git a/plugins/modules/ibm_sa_pool.py b/plugins/modules/ibm_sa_pool.py
index 88065aa4ec..38f3820435 100644
--- a/plugins/modules/ibm_sa_pool.py
+++ b/plugins/modules/ibm_sa_pool.py
@@ -10,62 +10,60 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ibm_sa_pool
short_description: Handles pools on IBM Spectrum Accelerate Family storage systems
description:
- - "This module creates or deletes pools to be used on IBM Spectrum Accelerate Family storage systems"
-
+ - This module creates or deletes pools to be used on IBM Spectrum Accelerate Family storage systems.
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- pool:
- description:
- - Pool name.
- required: true
- type: str
- state:
- description:
- - Pool state.
- default: "present"
- choices: [ "present", "absent" ]
- type: str
- size:
- description:
- - Pool size in GB
- required: false
- type: str
- snapshot_size:
- description:
- - Pool snapshot size in GB
- required: false
- type: str
- domain:
- description:
- - Adds the pool to the specified domain.
- required: false
- type: str
- perf_class:
- description:
- - Assigns a perf_class to the pool.
- required: false
- type: str
+ pool:
+ description:
+ - Pool name.
+ required: true
+ type: str
+ state:
+ description:
+ - Pool state.
+ default: "present"
+ choices: ["present", "absent"]
+ type: str
+ size:
+ description:
+ - Pool size in GB.
+ required: false
+ type: str
+ snapshot_size:
+ description:
+ - Pool snapshot size in GB.
+ required: false
+ type: str
+ domain:
+ description:
+ - Adds the pool to the specified domain.
+ required: false
+ type: str
+ perf_class:
+ description:
+ - Assigns a perf_class to the pool.
+ required: false
+ type: str
extends_documentation_fragment:
- community.general.ibm_storage
- community.general.attributes
author:
- - Tzur Eliyahu (@tzure)
-'''
+ - Tzur Eliyahu (@tzure)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create new pool.
community.general.ibm_sa_pool:
name: pool_name
@@ -82,9 +80,9 @@ EXAMPLES = '''
username: admin
password: secret
endpoints: hostdev-system
-'''
-RETURN = '''
-'''
+"""
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ibm_sa_utils import execute_pyxcli_command, \
diff --git a/plugins/modules/ibm_sa_vol.py b/plugins/modules/ibm_sa_vol.py
index bc5f81b32f..f9d0837b17 100644
--- a/plugins/modules/ibm_sa_vol.py
+++ b/plugins/modules/ibm_sa_vol.py
@@ -10,52 +10,50 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ibm_sa_vol
short_description: Handle volumes on IBM Spectrum Accelerate Family storage systems
description:
- - "This module creates or deletes volumes to be used on IBM Spectrum Accelerate Family storage systems."
-
+ - This module creates or deletes volumes to be used on IBM Spectrum Accelerate Family storage systems.
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- vol:
- description:
- - Volume name.
- required: true
- type: str
- pool:
- description:
- - Volume pool.
- required: false
- type: str
- state:
- description:
- - Volume state.
- default: "present"
- choices: [ "present", "absent" ]
- type: str
- size:
- description:
- - Volume size.
- required: false
- type: str
+ vol:
+ description:
+ - Volume name.
+ required: true
+ type: str
+ pool:
+ description:
+ - Volume pool.
+ required: false
+ type: str
+ state:
+ description:
+ - Volume state.
+ default: "present"
+ choices: ["present", "absent"]
+ type: str
+ size:
+ description:
+ - Volume size.
+ required: false
+ type: str
extends_documentation_fragment:
- community.general.ibm_storage
- community.general.attributes
author:
- - Tzur Eliyahu (@tzure)
-'''
+ - Tzur Eliyahu (@tzure)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a new volume.
community.general.ibm_sa_vol:
vol: volume_name
@@ -73,9 +71,9 @@ EXAMPLES = '''
username: admin
password: secret
endpoints: hostdev-system
-'''
-RETURN = '''
-'''
+"""
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ibm_sa_utils import execute_pyxcli_command, \
diff --git a/plugins/modules/ibm_sa_vol_map.py b/plugins/modules/ibm_sa_vol_map.py
index ea8b485ef1..7f5edf83ba 100644
--- a/plugins/modules/ibm_sa_vol_map.py
+++ b/plugins/modules/ibm_sa_vol_map.py
@@ -10,65 +10,61 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ibm_sa_vol_map
short_description: Handles volume mapping on IBM Spectrum Accelerate Family storage systems
description:
- - "This module maps volumes to or unmaps them from the hosts on
- IBM Spectrum Accelerate Family storage systems."
-
+ - This module maps volumes to or unmaps them from the hosts on IBM Spectrum Accelerate Family storage systems.
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- vol:
- description:
- - Volume name.
- required: true
- type: str
- state:
- default: "present"
- choices: [ "present", "absent" ]
- description:
- - When the state is present the volume is mapped.
- When the state is absent, the volume is meant to be unmapped.
- type: str
+ vol:
+ description:
+ - Volume name.
+ required: true
+ type: str
+ state:
+ default: "present"
+ choices: ["present", "absent"]
+ description:
+ - When the state is present the volume is mapped. When the state is absent, the volume is meant to be unmapped.
+ type: str
- cluster:
- description:
- - Maps the volume to a cluster.
- required: false
- type: str
- host:
- description:
- - Maps the volume to a host.
- required: false
- type: str
- lun:
- description:
- - The LUN identifier.
- required: false
- type: str
- override:
- description:
- - Overrides the existing volume mapping.
- required: false
- type: str
+ cluster:
+ description:
+ - Maps the volume to a cluster.
+ required: false
+ type: str
+ host:
+ description:
+ - Maps the volume to a host.
+ required: false
+ type: str
+ lun:
+ description:
+ - The LUN identifier.
+ required: false
+ type: str
+ override:
+ description:
+ - Overrides the existing volume mapping.
+ required: false
+ type: str
extends_documentation_fragment:
- community.general.ibm_storage
- community.general.attributes
author:
- - Tzur Eliyahu (@tzure)
-'''
+ - Tzur Eliyahu (@tzure)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Map volume to host.
community.general.ibm_sa_vol_map:
vol: volume_name
@@ -96,9 +92,9 @@ EXAMPLES = '''
password: secret
endpoints: hostdev-system
state: absent
-'''
-RETURN = '''
-'''
+"""
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ibm_sa_utils import (execute_pyxcli_command,
diff --git a/plugins/modules/icinga2_feature.py b/plugins/modules/icinga2_feature.py
index 0c79f6cba9..1b39a857e4 100644
--- a/plugins/modules/icinga2_feature.py
+++ b/plugins/modules/icinga2_feature.py
@@ -13,39 +13,38 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: icinga2_feature
short_description: Manage Icinga2 feature
description:
- - This module can be used to enable or disable an Icinga2 feature.
+ - This module can be used to enable or disable an Icinga2 feature.
author: "Loic Blot (@nerzhul)"
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- type: str
- description:
+ name:
+ type: str
+ description:
- This is the feature name to enable or disable.
- required: true
- state:
- type: str
- description:
+ required: true
+ state:
+ type: str
+ description:
- If set to V(present) and feature is disabled, then feature is enabled.
- If set to V(present) and feature is already enabled, then nothing is changed.
- If set to V(absent) and feature is enabled, then feature is disabled.
- If set to V(absent) and feature is already disabled, then nothing is changed.
- choices: [ "present", "absent" ]
- default: present
-'''
+ choices: ["present", "absent"]
+ default: present
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Enable ido-pgsql feature
community.general.icinga2_feature:
name: ido-pgsql
@@ -55,11 +54,11 @@ EXAMPLES = '''
community.general.icinga2_feature:
name: api
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
#
-'''
+"""
import re
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/icinga2_host.py b/plugins/modules/icinga2_host.py
index 5abbc43687..8d0a3b554b 100644
--- a/plugins/modules/icinga2_host.py
+++ b/plugins/modules/icinga2_host.py
@@ -11,13 +11,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: icinga2_host
short_description: Manage a host in Icinga2
description:
- - "Add or remove a host to Icinga2 through the API."
- - "See U(https://www.icinga.com/docs/icinga2/latest/doc/12-icinga2-api/)"
+ - Add or remove a host to Icinga2 through the API.
+ - See U(https://www.icinga.com/docs/icinga2/latest/doc/12-icinga2-api/).
author: "Jurgen Brand (@t794104)"
attributes:
check_mode:
@@ -28,17 +27,16 @@ options:
url:
type: str
description:
- - HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path
+ - HTTP, HTTPS, or FTP URL in the form V((http|https|ftp\)://[user[:pass]]@host.domain[:port]/path).
use_proxy:
description:
- - If V(false), it will not use a proxy, even if one is defined in
- an environment variable on the target hosts.
+ - If V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
type: bool
default: true
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
type: bool
default: true
url_username:
@@ -49,33 +47,30 @@ options:
url_password:
type: str
description:
- - The password for use in HTTP basic authentication.
- - If the O(url_username) parameter is not specified, the O(url_password) parameter will not be used.
+ - The password for use in HTTP basic authentication.
+ - If the O(url_username) parameter is not specified, the O(url_password) parameter will not be used.
force_basic_auth:
description:
- - httplib2, the library used by the uri module only sends authentication information when a webservice
- responds to an initial request with a 401 status. Since some basic auth services do not properly
- send a 401, logins will fail. This option forces the sending of the Basic authentication header
- upon initial request.
+ - C(httplib2), the library used by Ansible's HTTP request code only sends authentication information when a webservice responds to
+ an initial request with a 401 status. Since some basic auth services do not properly send a 401, logins will fail.
+ This option forces the sending of the Basic authentication header upon initial request.
type: bool
default: false
client_cert:
type: path
description:
- - PEM formatted certificate chain file to be used for SSL client
- authentication. This file can also include the key as well, and if
- the key is included, O(client_key) is not required.
+ - PEM formatted certificate chain file to be used for SSL client authentication. This file can also include the key
+ as well, and if the key is included, O(client_key) is not required.
client_key:
type: path
description:
- - PEM formatted file that contains your private key to be used for SSL
- client authentication. If O(client_cert) contains both the certificate
- and key, this option is not required.
+ - PEM formatted file that contains your private key to be used for SSL client authentication. If O(client_cert) contains
+ both the certificate and key, this option is not required.
state:
type: str
description:
- Apply feature state.
- choices: [ "present", "absent" ]
+ choices: ["present", "absent"]
default: present
name:
type: str
@@ -114,9 +109,9 @@ options:
extends_documentation_fragment:
- ansible.builtin.url
- community.general.attributes
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add host to icinga
community.general.icinga2_host:
url: "https://icinga2.example.com"
@@ -128,18 +123,18 @@ EXAMPLES = '''
variables:
foo: "bar"
delegate_to: 127.0.0.1
-'''
+"""
-RETURN = '''
+RETURN = r"""
name:
- description: The name used to create, modify or delete the host
- type: str
- returned: always
+ description: The name used to create, modify or delete the host.
+ type: str
+ returned: always
data:
- description: The data structure used for create, modify or delete of the host
- type: dict
- returned: always
-'''
+ description: The data structure used for create, modify or delete of the host.
+ type: dict
+ returned: always
+"""
import json
diff --git a/plugins/modules/idrac_redfish_command.py b/plugins/modules/idrac_redfish_command.py
index d760a2c3a3..531da53162 100644
--- a/plugins/modules/idrac_redfish_command.py
+++ b/plugins/modules/idrac_redfish_command.py
@@ -8,13 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: idrac_redfish_command
short_description: Manages Out-Of-Band controllers using iDRAC OEM Redfish APIs
description:
- - Builds Redfish URIs locally and sends them to remote OOB controllers to
- perform an action.
+ - Builds Redfish URIs locally and sends them to remote OOB controllers to perform an action.
- For use with Dell iDRAC operations that require Redfish OEM extensions.
extends_documentation_fragment:
- community.general.attributes
@@ -66,34 +64,32 @@ options:
version_added: '0.2.0'
author: "Jose Delarosa (@jose-delarosa)"
-'''
+"""
-EXAMPLES = '''
- - name: Create BIOS configuration job (schedule BIOS setting update)
- community.general.idrac_redfish_command:
- category: Systems
- command: CreateBiosConfigJob
- resource_id: System.Embedded.1
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
-'''
+EXAMPLES = r"""
+- name: Create BIOS configuration job (schedule BIOS setting update)
+ community.general.idrac_redfish_command:
+ category: Systems
+ command: CreateBiosConfigJob
+ resource_id: System.Embedded.1
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message with action result or error description
- returned: always
- type: str
- sample: "Action was successful"
+ description: Message with action result or error description.
+ returned: always
+ type: str
+ sample: "Action was successful"
return_values:
- description: Dictionary containing command-specific response data from the action.
- returned: on success
- type: dict
- version_added: 6.6.0
- sample: {
- "job_id": "/redfish/v1/Managers/iDRAC.Embedded.1/Jobs/JID_471269252011"
- }
-'''
+ description: Dictionary containing command-specific response data from the action.
+ returned: on success
+ type: dict
+ version_added: 6.6.0
+ sample: {"job_id": "/redfish/v1/Managers/iDRAC.Embedded.1/Jobs/JID_471269252011"}
+"""
import re
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/idrac_redfish_config.py b/plugins/modules/idrac_redfish_config.py
index 0388bf00fb..97d7a62d04 100644
--- a/plugins/modules/idrac_redfish_config.py
+++ b/plugins/modules/idrac_redfish_config.py
@@ -8,14 +8,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: idrac_redfish_config
short_description: Manages servers through iDRAC using Dell Redfish APIs
description:
- - For use with Dell iDRAC operations that require Redfish OEM extensions
- - Builds Redfish URIs locally and sends them to remote iDRAC controllers to
- set or update a configuration attribute.
+ - For use with Dell iDRAC operations that require Redfish OEM extensions.
+ - Builds Redfish URIs locally and sends them to remote iDRAC controllers to set or update a configuration attribute.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -33,9 +31,8 @@ options:
required: true
description:
- List of commands to execute on iDRAC.
- - V(SetManagerAttributes), V(SetLifecycleControllerAttributes) and
- V(SetSystemAttributes) are mutually exclusive commands when O(category)
- is V(Manager).
+ - V(SetManagerAttributes), V(SetLifecycleControllerAttributes) and V(SetSystemAttributes) are mutually exclusive commands
+ when O(category) is V(Manager).
type: list
elements: str
baseuri:
@@ -76,81 +73,81 @@ options:
version_added: '0.2.0'
author: "Jose Delarosa (@jose-delarosa)"
-'''
+"""
-EXAMPLES = '''
- - name: Enable NTP and set NTP server and Time zone attributes in iDRAC
- community.general.idrac_redfish_config:
- category: Manager
- command: SetManagerAttributes
- resource_id: iDRAC.Embedded.1
- manager_attributes:
- NTPConfigGroup.1.NTPEnable: "Enabled"
- NTPConfigGroup.1.NTP1: "{{ ntpserver1 }}"
- Time.1.Timezone: "{{ timezone }}"
- baseuri: "{{ baseuri }}"
- username: "{{ username}}"
- password: "{{ password }}"
+EXAMPLES = r"""
+- name: Enable NTP and set NTP server and Time zone attributes in iDRAC
+ community.general.idrac_redfish_config:
+ category: Manager
+ command: SetManagerAttributes
+ resource_id: iDRAC.Embedded.1
+ manager_attributes:
+ NTPConfigGroup.1.NTPEnable: "Enabled"
+ NTPConfigGroup.1.NTP1: "{{ ntpserver1 }}"
+ Time.1.Timezone: "{{ timezone }}"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username}}"
+ password: "{{ password }}"
- - name: Enable Syslog and set Syslog servers in iDRAC
- community.general.idrac_redfish_config:
- category: Manager
- command: SetManagerAttributes
- resource_id: iDRAC.Embedded.1
- manager_attributes:
- SysLog.1.SysLogEnable: "Enabled"
- SysLog.1.Server1: "{{ syslog_server1 }}"
- SysLog.1.Server2: "{{ syslog_server2 }}"
- baseuri: "{{ baseuri }}"
- username: "{{ username}}"
- password: "{{ password }}"
+- name: Enable Syslog and set Syslog servers in iDRAC
+ community.general.idrac_redfish_config:
+ category: Manager
+ command: SetManagerAttributes
+ resource_id: iDRAC.Embedded.1
+ manager_attributes:
+ SysLog.1.SysLogEnable: "Enabled"
+ SysLog.1.Server1: "{{ syslog_server1 }}"
+ SysLog.1.Server2: "{{ syslog_server2 }}"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username}}"
+ password: "{{ password }}"
- - name: Configure SNMP community string, port, protocol and trap format
- community.general.idrac_redfish_config:
- category: Manager
- command: SetManagerAttributes
- resource_id: iDRAC.Embedded.1
- manager_attributes:
- SNMP.1.AgentEnable: "Enabled"
- SNMP.1.AgentCommunity: "public_community_string"
- SNMP.1.TrapFormat: "SNMPv1"
- SNMP.1.SNMPProtocol: "All"
- SNMP.1.DiscoveryPort: 161
- SNMP.1.AlertPort: 162
- baseuri: "{{ baseuri }}"
- username: "{{ username}}"
- password: "{{ password }}"
+- name: Configure SNMP community string, port, protocol and trap format
+ community.general.idrac_redfish_config:
+ category: Manager
+ command: SetManagerAttributes
+ resource_id: iDRAC.Embedded.1
+ manager_attributes:
+ SNMP.1.AgentEnable: "Enabled"
+ SNMP.1.AgentCommunity: "public_community_string"
+ SNMP.1.TrapFormat: "SNMPv1"
+ SNMP.1.SNMPProtocol: "All"
+ SNMP.1.DiscoveryPort: 161
+ SNMP.1.AlertPort: 162
+ baseuri: "{{ baseuri }}"
+ username: "{{ username}}"
+ password: "{{ password }}"
- - name: Enable CSIOR
- community.general.idrac_redfish_config:
- category: Manager
- command: SetLifecycleControllerAttributes
- resource_id: iDRAC.Embedded.1
- manager_attributes:
- LCAttributes.1.CollectSystemInventoryOnRestart: "Enabled"
- baseuri: "{{ baseuri }}"
- username: "{{ username}}"
- password: "{{ password }}"
+- name: Enable CSIOR
+ community.general.idrac_redfish_config:
+ category: Manager
+ command: SetLifecycleControllerAttributes
+ resource_id: iDRAC.Embedded.1
+ manager_attributes:
+ LCAttributes.1.CollectSystemInventoryOnRestart: "Enabled"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username}}"
+ password: "{{ password }}"
- - name: Set Power Supply Redundancy Policy to A/B Grid Redundant
- community.general.idrac_redfish_config:
- category: Manager
- command: SetSystemAttributes
- resource_id: iDRAC.Embedded.1
- manager_attributes:
- ServerPwr.1.PSRedPolicy: "A/B Grid Redundant"
- baseuri: "{{ baseuri }}"
- username: "{{ username}}"
- password: "{{ password }}"
-'''
+- name: Set Power Supply Redundancy Policy to A/B Grid Redundant
+ community.general.idrac_redfish_config:
+ category: Manager
+ command: SetSystemAttributes
+ resource_id: iDRAC.Embedded.1
+ manager_attributes:
+ ServerPwr.1.PSRedPolicy: "A/B Grid Redundant"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username}}"
+ password: "{{ password }}"
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message with action result or error description
- returned: always
- type: str
- sample: "Action was successful"
-'''
+ description: Message with action result or error description.
+ returned: always
+ type: str
+ sample: "Action was successful"
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.validation import (
diff --git a/plugins/modules/idrac_redfish_info.py b/plugins/modules/idrac_redfish_info.py
index 90b355d13b..3a8ea8103f 100644
--- a/plugins/modules/idrac_redfish_info.py
+++ b/plugins/modules/idrac_redfish_info.py
@@ -8,13 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: idrac_redfish_info
short_description: Gather PowerEdge server information through iDRAC using Redfish APIs
description:
- - Builds Redfish URIs locally and sends them to remote iDRAC controllers to
- get information back.
+ - Builds Redfish URIs locally and sends them to remote iDRAC controllers to get information back.
- For use with Dell EMC iDRAC operations that require Redfish OEM extensions.
extends_documentation_fragment:
- community.general.attributes
@@ -33,8 +31,7 @@ options:
required: true
description:
- List of commands to execute on iDRAC.
- - V(GetManagerAttributes) returns the list of dicts containing iDRAC,
- LifecycleController and System attributes.
+ - V(GetManagerAttributes) returns the list of dicts containing iDRAC, LifecycleController and System attributes.
type: list
elements: str
baseuri:
@@ -62,67 +59,69 @@ options:
type: int
author: "Jose Delarosa (@jose-delarosa)"
-'''
+"""
-EXAMPLES = '''
- - name: Get Manager attributes with a default of 20 seconds
- community.general.idrac_redfish_info:
- category: Manager
- command: GetManagerAttributes
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- timeout: 20
- register: result
+EXAMPLES = r"""
+- name: Get Manager attributes with a default of 20 seconds
+ community.general.idrac_redfish_info:
+ category: Manager
+ command: GetManagerAttributes
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ timeout: 20
+ register: result
- # Examples to display the value of all or a single iDRAC attribute
- - name: Store iDRAC attributes as a fact variable
- ansible.builtin.set_fact:
- idrac_attributes: "{{ result.redfish_facts.entries | selectattr('Id', 'defined') | selectattr('Id', 'equalto', 'iDRACAttributes') | list | first }}"
+# Examples to display the value of all or a single iDRAC attribute
+- name: Store iDRAC attributes as a fact variable
+ ansible.builtin.set_fact:
+ idrac_attributes: "{{ result.redfish_facts.entries | selectattr('Id', 'defined') | selectattr('Id', 'equalto', 'iDRACAttributes')
+ | list | first }}"
- - name: Display all iDRAC attributes
- ansible.builtin.debug:
- var: idrac_attributes
+- name: Display all iDRAC attributes
+ ansible.builtin.debug:
+ var: idrac_attributes
- - name: Display the value of 'Syslog.1.SysLogEnable' iDRAC attribute
- ansible.builtin.debug:
- var: idrac_attributes['Syslog.1.SysLogEnable']
+- name: Display the value of 'Syslog.1.SysLogEnable' iDRAC attribute
+ ansible.builtin.debug:
+ var: idrac_attributes['Syslog.1.SysLogEnable']
- # Examples to display the value of all or a single LifecycleController attribute
- - name: Store LifecycleController attributes as a fact variable
- ansible.builtin.set_fact:
- lc_attributes: "{{ result.redfish_facts.entries | selectattr('Id', 'defined') | selectattr('Id', 'equalto', 'LCAttributes') | list | first }}"
+# Examples to display the value of all or a single LifecycleController attribute
+- name: Store LifecycleController attributes as a fact variable
+ ansible.builtin.set_fact:
+ lc_attributes: "{{ result.redfish_facts.entries | selectattr('Id', 'defined') | selectattr('Id', 'equalto', 'LCAttributes')
+ | list | first }}"
- - name: Display LifecycleController attributes
- ansible.builtin.debug:
- var: lc_attributes
+- name: Display LifecycleController attributes
+ ansible.builtin.debug:
+ var: lc_attributes
- - name: Display the value of 'CollectSystemInventoryOnRestart' attribute
- ansible.builtin.debug:
- var: lc_attributes['LCAttributes.1.CollectSystemInventoryOnRestart']
+- name: Display the value of 'CollectSystemInventoryOnRestart' attribute
+ ansible.builtin.debug:
+ var: lc_attributes['LCAttributes.1.CollectSystemInventoryOnRestart']
- # Examples to display the value of all or a single System attribute
- - name: Store System attributes as a fact variable
- ansible.builtin.set_fact:
- system_attributes: "{{ result.redfish_facts.entries | selectattr('Id', 'defined') | selectattr('Id', 'equalto', 'SystemAttributes') | list | first }}"
+# Examples to display the value of all or a single System attribute
+- name: Store System attributes as a fact variable
+ ansible.builtin.set_fact:
+ system_attributes: "{{ result.redfish_facts.entries | selectattr('Id', 'defined') | selectattr('Id', 'equalto', 'SystemAttributes')
+ | list | first }}"
- - name: Display System attributes
- ansible.builtin.debug:
- var: system_attributes
+- name: Display System attributes
+ ansible.builtin.debug:
+ var: system_attributes
- - name: Display the value of 'PSRedPolicy'
- ansible.builtin.debug:
- var: system_attributes['ServerPwr.1.PSRedPolicy']
+- name: Display the value of 'PSRedPolicy'
+ ansible.builtin.debug:
+ var: system_attributes['ServerPwr.1.PSRedPolicy']
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
msg:
- description: different results depending on task
- returned: always
- type: dict
- sample: List of Manager attributes
-'''
+ description: Different results depending on task.
+ returned: always
+ type: dict
+ sample: List of Manager attributes
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.redfish_utils import RedfishUtils
diff --git a/plugins/modules/ilo_redfish_command.py b/plugins/modules/ilo_redfish_command.py
index e0e28f855d..3e698fc049 100644
--- a/plugins/modules/ilo_redfish_command.py
+++ b/plugins/modules/ilo_redfish_command.py
@@ -6,14 +6,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ilo_redfish_command
short_description: Manages Out-Of-Band controllers using Redfish APIs
version_added: 6.6.0
description:
- - Builds Redfish URIs locally and sends them to remote OOB controllers to
- perform an action.
+ - Builds Redfish URIs locally and sends them to remote OOB controllers to perform an action.
attributes:
check_mode:
support: none
@@ -62,35 +60,35 @@ options:
type: int
author:
- Varni H P (@varini-hp)
-'''
+"""
-EXAMPLES = '''
- - name: Wait for iLO Reboot Completion
- community.general.ilo_redfish_command:
- category: Systems
- command: WaitforiLORebootCompletion
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
-'''
+EXAMPLES = r"""
+- name: Wait for iLO Reboot Completion
+ community.general.ilo_redfish_command:
+ category: Systems
+ command: WaitforiLORebootCompletion
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+"""
-RETURN = '''
+RETURN = r"""
ilo_redfish_command:
- description: Returns the status of the operation performed on the iLO.
- type: dict
- contains:
- WaitforiLORebootCompletion:
- description: Returns the output msg and whether the function executed successfully.
- type: dict
- contains:
- ret:
- description: Return True/False based on whether the operation was performed successfully.
- type: bool
- msg:
- description: Status of the operation performed on the iLO.
- type: str
- returned: always
-'''
+ description: Returns the status of the operation performed on the iLO.
+ type: dict
+ contains:
+ WaitforiLORebootCompletion:
+ description: Returns the output msg and whether the function executed successfully.
+ type: dict
+ contains:
+ ret:
+ description: Return V(true)/V(false) based on whether the operation was performed successfully.
+ type: bool
+ msg:
+ description: Status of the operation performed on the iLO.
+ type: str
+ returned: always
+"""
# More will be added as module features are expanded
CATEGORY_COMMANDS_ALL = {
diff --git a/plugins/modules/ilo_redfish_config.py b/plugins/modules/ilo_redfish_config.py
index 1f021895dc..fdda339ab3 100644
--- a/plugins/modules/ilo_redfish_config.py
+++ b/plugins/modules/ilo_redfish_config.py
@@ -6,14 +6,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ilo_redfish_config
short_description: Sets or updates configuration attributes on HPE iLO with Redfish OEM extensions
version_added: 4.2.0
description:
- - Builds Redfish URIs locally and sends them to iLO to
- set or update a configuration attribute.
+ - Builds Redfish URIs locally and sends them to iLO to set or update a configuration attribute.
- For use with HPE iLO operations that require Redfish OEM extensions.
extends_documentation_fragment:
- community.general.attributes
@@ -68,48 +66,47 @@ options:
- Value of the attribute to be configured.
type: str
author:
- - "Bhavya B (@bhavya06)"
-'''
+ - "Bhavya B (@bhavya06)"
+"""
-EXAMPLES = '''
- - name: Disable WINS Registration
- community.general.ilo_redfish_config:
- category: Manager
- command: SetWINSReg
- baseuri: 15.X.X.X
- username: Admin
- password: Testpass123
- attribute_name: WINSRegistration
+EXAMPLES = r"""
+- name: Disable WINS Registration
+ community.general.ilo_redfish_config:
+ category: Manager
+ command: SetWINSReg
+ baseuri: 15.X.X.X
+ username: Admin
+ password: Testpass123
+ attribute_name: WINSRegistration
- - name: Set Time Zone
- community.general.ilo_redfish_config:
- category: Manager
- command: SetTimeZone
- baseuri: 15.X.X.X
- username: Admin
- password: Testpass123
- attribute_name: TimeZone
- attribute_value: Chennai
+- name: Set Time Zone
+ community.general.ilo_redfish_config:
+ category: Manager
+ command: SetTimeZone
+ baseuri: 15.X.X.X
+ username: Admin
+ password: Testpass123
+ attribute_name: TimeZone
+ attribute_value: Chennai
- - name: Set NTP Servers
- community.general.ilo_redfish_config:
- category: Manager
- command: SetNTPServers
- baseuri: 15.X.X.X
- username: Admin
- password: Testpass123
- attribute_name: StaticNTPServers
- attribute_value: X.X.X.X
+- name: Set NTP Servers
+ community.general.ilo_redfish_config:
+ category: Manager
+ command: SetNTPServers
+ baseuri: 15.X.X.X
+ username: Admin
+ password: Testpass123
+ attribute_name: StaticNTPServers
+ attribute_value: X.X.X.X
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
msg:
- description: Message with action result or error description
- returned: always
- type: str
- sample: "Action was successful"
-'''
+ description: Message with action result or error description.
+ returned: always
+ type: str
+ sample: "Action was successful"
+"""
CATEGORY_COMMANDS_ALL = {
"Manager": ["SetTimeZone", "SetDNSserver", "SetDomainName", "SetNTPServers", "SetWINSReg"]
diff --git a/plugins/modules/ilo_redfish_info.py b/plugins/modules/ilo_redfish_info.py
index 90cafb8ec6..3bd379e80a 100644
--- a/plugins/modules/ilo_redfish_info.py
+++ b/plugins/modules/ilo_redfish_info.py
@@ -6,14 +6,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ilo_redfish_info
short_description: Gathers server information through iLO using Redfish APIs
version_added: 4.2.0
description:
- - Builds Redfish URIs locally and sends them to iLO to
- get information back.
+ - Builds Redfish URIs locally and sends them to iLO to get information back.
- For use with HPE iLO operations that require Redfish OEM extensions.
extends_documentation_fragment:
- community.general.attributes
@@ -54,51 +52,51 @@ options:
default: 10
type: int
author:
- - "Bhavya B (@bhavya06)"
-'''
+ - "Bhavya B (@bhavya06)"
+"""
-EXAMPLES = '''
- - name: Get iLO Sessions
- community.general.ilo_redfish_info:
- category: Sessions
- command: GetiLOSessions
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result_sessions
-'''
+EXAMPLES = r"""
+- name: Get iLO Sessions
+ community.general.ilo_redfish_info:
+ category: Sessions
+ command: GetiLOSessions
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result_sessions
+"""
-RETURN = '''
+RETURN = r"""
ilo_redfish_info:
- description: Returns iLO sessions.
- type: dict
- contains:
- GetiLOSessions:
- description: Returns the iLO session msg and whether the function executed successfully.
- type: dict
- contains:
- ret:
- description: Check variable to see if the information was successfully retrieved.
- type: bool
- msg:
- description: Information of all active iLO sessions.
- type: list
- elements: dict
- contains:
- Description:
- description: Provides a description of the resource.
- type: str
- Id:
- description: The sessionId.
- type: str
- Name:
- description: The name of the resource.
- type: str
- UserName:
- description: Name to use to log in to the management processor.
- type: str
- returned: always
-'''
+ description: Returns iLO sessions.
+ type: dict
+ contains:
+ GetiLOSessions:
+ description: Returns the iLO session msg and whether the function executed successfully.
+ type: dict
+ contains:
+ ret:
+ description: Check variable to see if the information was successfully retrieved.
+ type: bool
+ msg:
+ description: Information of all active iLO sessions.
+ type: list
+ elements: dict
+ contains:
+ Description:
+ description: Provides a description of the resource.
+ type: str
+ Id:
+ description: The sessionId.
+ type: str
+ Name:
+ description: The name of the resource.
+ type: str
+ UserName:
+ description: Name to use to log in to the management processor.
+ type: str
+ returned: always
+"""
CATEGORY_COMMANDS_ALL = {
"Sessions": ["GetiLOSessions"]
diff --git a/plugins/modules/imc_rest.py b/plugins/modules/imc_rest.py
index 946dfe7f10..8a0b63cd78 100644
--- a/plugins/modules/imc_rest.py
+++ b/plugins/modules/imc_rest.py
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: imc_rest
short_description: Manage Cisco IMC hardware through its REST API
description:
@@ -32,75 +31,74 @@ attributes:
options:
hostname:
description:
- - IP Address or hostname of Cisco IMC, resolvable by Ansible control host.
+ - IP Address or hostname of Cisco IMC, resolvable by Ansible control host.
required: true
- aliases: [ host, ip ]
+ aliases: [host, ip]
type: str
username:
description:
- - Username used to login to the switch.
+ - Username used to login to the switch.
default: admin
- aliases: [ user ]
+ aliases: [user]
type: str
password:
description:
- - The password to use for authentication.
+ - The password to use for authentication.
default: password
type: str
path:
description:
- - Name of the absolute path of the filename that includes the body
- of the http request being sent to the Cisco IMC REST API.
- - Parameter O(path) is mutual exclusive with parameter O(content).
- aliases: [ 'src', 'config_file' ]
+ - Name of the absolute path of the filename that includes the body of the http request being sent to the Cisco IMC REST
+ API.
+ - Parameter O(path) is mutual exclusive with parameter O(content).
+ aliases: ['src', 'config_file']
type: path
content:
description:
- - When used instead of O(path), sets the content of the API requests directly.
- - This may be convenient to template simple requests, for anything complex use the M(ansible.builtin.template) module.
- - You can collate multiple IMC XML fragments and they will be processed sequentially in a single stream,
- the Cisco IMC output is subsequently merged.
- - Parameter O(content) is mutual exclusive with parameter O(path).
+ - When used instead of O(path), sets the content of the API requests directly.
+ - This may be convenient to template simple requests, for anything complex use the M(ansible.builtin.template) module.
+ - You can collate multiple IMC XML fragments and they will be processed sequentially in a single stream, the Cisco IMC
+ output is subsequently merged.
+ - Parameter O(content) is mutual exclusive with parameter O(path).
type: str
protocol:
description:
- - Connection protocol to use.
+ - Connection protocol to use.
default: https
- choices: [ http, https ]
+ choices: [http, https]
type: str
timeout:
description:
- - The socket level timeout in seconds.
- - This is the time that every single connection (every fragment) can spend.
- If this O(timeout) is reached, the module will fail with a
- C(Connection failure) indicating that C(The read operation timed out).
+ - The socket level timeout in seconds.
+ - This is the time that every single connection (every fragment) can spend. If this O(timeout) is reached, the module
+ will fail with a C(Connection failure) indicating that C(The read operation timed out).
default: 60
type: int
validate_certs:
description:
- - If V(false), SSL certificates will not be validated.
- - This should only set to V(false) used on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated.
+ - This should only set to V(false) used on personally controlled sites using self-signed certificates.
type: bool
default: true
notes:
-- The XML fragments don't need an authentication cookie, this is injected by the module automatically.
-- The Cisco IMC XML output is being translated to JSON using the Cobra convention.
-- Any configConfMo change requested has a return status of 'modified', even if there was no actual change
- from the previous configuration. As a result, this module will always report a change on subsequent runs.
- In case this behaviour is fixed in a future update to Cisco IMC, this module will automatically adapt.
-- If you get a C(Connection failure) related to C(The read operation timed out) increase the O(timeout)
- parameter. Some XML fragments can take longer than the default timeout.
-- More information about the IMC REST API is available from
- U(http://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/c/sw/api/3_0/b_Cisco_IMC_api_301.html)
-'''
+ - The XML fragments do not need an authentication cookie, this is injected by the module automatically.
+ - The Cisco IMC XML output is being translated to JSON using the Cobra convention.
+ - Any configConfMo change requested has a return status of C(modified), even if there was no actual change from the previous
+ configuration. As a result, this module will always report a change on subsequent runs. In case this behaviour is fixed
+ in a future update to Cisco IMC, this module will automatically adapt.
+ - If you get a C(Connection failure) related to C(The read operation timed out) increase the O(timeout) parameter. Some
+ XML fragments can take longer than the default timeout.
+ - More information about the IMC REST API is available from
+ U(http://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/c/sw/api/3_0/b_Cisco_IMC_api_301.html).
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Power down server
community.general.imc_rest:
hostname: '{{ imc_hostname }}'
username: '{{ imc_username }}'
password: '{{ imc_password }}'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
content: |
@@ -112,7 +110,7 @@ EXAMPLES = r'''
hostname: '{{ imc_hostname }}'
username: '{{ imc_username }}'
password: '{{ imc_password }}'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
timeout: 120
content: |
@@ -137,7 +135,7 @@ EXAMPLES = r'''
hostname: '{{ imc_hostname }}'
username: '{{ imc_username }}'
password: '{{ imc_password }}'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
content: |
@@ -155,7 +153,7 @@ EXAMPLES = r'''
hostname: '{{ imc_host }}'
username: '{{ imc_username }}'
password: '{{ imc_password }}'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
content: |
@@ -167,11 +165,11 @@ EXAMPLES = r'''
hostname: '{{ imc_host }}'
username: '{{ imc_username }}'
password: '{{ imc_password }}'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
content: |
-
-
-
+
+
+
delegate_to: localhost
- name: Disable HTTP and increase session timeout to max value 10800 secs
@@ -179,22 +177,22 @@ EXAMPLES = r'''
hostname: '{{ imc_host }}'
username: '{{ imc_username }}'
password: '{{ imc_password }}'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
timeout: 120
content: |
-
-
-
+
+
+
-
-
-
+
+
+
delegate_to: localhost
-'''
+"""
-RETURN = r'''
+RETURN = r"""
aaLogin:
- description: Cisco IMC XML output for the login, translated to JSON using Cobra convention
+ description: Cisco IMC XML output for the login, translated to JSON using Cobra convention.
returned: success
type: dict
sample: |
@@ -208,27 +206,27 @@ aaLogin:
"response": "yes"
}
configConfMo:
- description: Cisco IMC XML output for any configConfMo XML fragments, translated to JSON using Cobra convention
+ description: Cisco IMC XML output for any configConfMo XML fragments, translated to JSON using Cobra convention.
returned: success
type: dict
sample: |
elapsed:
- description: Elapsed time in seconds
+ description: Elapsed time in seconds.
returned: always
type: int
sample: 31
response:
- description: HTTP response message, including content length
+ description: HTTP response message, including content length.
returned: always
type: str
sample: OK (729 bytes)
status:
- description: The HTTP response status code
+ description: The HTTP response status code.
returned: always
type: dict
sample: 200
error:
- description: Cisco IMC XML error output for last request, translated to JSON using Cobra convention
+ description: Cisco IMC XML error output for last request, translated to JSON using Cobra convention.
returned: failed
type: dict
sample: |
@@ -240,24 +238,24 @@ error:
"response": "yes"
}
error_code:
- description: Cisco IMC error code
+ description: Cisco IMC error code.
returned: failed
type: str
sample: ERR-xml-parse-error
error_text:
- description: Cisco IMC error message
+ description: Cisco IMC error message.
returned: failed
type: str
sample: |
XML PARSING ERROR: Element 'computeRackUnit', attribute 'admin_Power': The attribute 'admin_Power' is not allowed.
input:
- description: RAW XML input sent to the Cisco IMC, causing the error
+ description: RAW XML input sent to the Cisco IMC, causing the error.
returned: failed
type: str
sample: |
output:
- description: RAW XML output received from the Cisco IMC, with error details
+ description: RAW XML output received from the Cisco IMC, with error details.
returned: failed
type: str
sample: >
@@ -265,8 +263,8 @@ output:
response="yes"
errorCode="ERR-xml-parse-error"
invocationResult="594"
- errorDescr="XML PARSING ERROR: Element 'computeRackUnit', attribute 'admin_Power': The attribute 'admin_Power' is not allowed.\n"/>
-'''
+ errorDescr="XML PARSING ERROR: Element 'computeRackUnit', attribute 'admin_Power': The attribute 'admin_Power' is not allowed.\n" />
+"""
import os
import traceback
diff --git a/plugins/modules/imgadm.py b/plugins/modules/imgadm.py
index a247547fc7..344bf9cc56 100644
--- a/plugins/modules/imgadm.py
+++ b/plugins/modules/imgadm.py
@@ -9,62 +9,60 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: imgadm
short_description: Manage SmartOS images
description:
- - Manage SmartOS virtual machine images through imgadm(1M)
+ - Manage SmartOS virtual machine images through imgadm(1M).
author: Jasper Lievisse Adriaanse (@jasperla)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- force:
- required: false
- type: bool
- description:
- - Force a given operation (where supported by imgadm(1M)).
- pool:
- required: false
- default: zones
- description:
- - zpool to import to or delete images from.
- type: str
- source:
- required: false
- description:
- - URI for the image source.
- type: str
- state:
- required: true
- choices: [ present, absent, deleted, imported, updated, vacuumed ]
- description:
- - State the object operated on should be in. V(imported) is an alias for
- for V(present) and V(deleted) for V(absent). When set to V(vacuumed)
- and O(uuid=*), it will remove all unused images.
- type: str
+ force:
+ required: false
+ type: bool
+ description:
+ - Force a given operation (where supported by imgadm(1M)).
+ pool:
+ required: false
+ default: zones
+ description:
+ - The zpool to import to or delete images from.
+ type: str
+ source:
+ required: false
+ description:
+ - URI for the image source.
+ type: str
+ state:
+ required: true
+ choices: [present, absent, deleted, imported, updated, vacuumed]
+ description:
+ - State the object operated on should be in. V(imported) is an alias for for V(present) and V(deleted) for V(absent).
+ When set to V(vacuumed) and O(uuid=*), it will remove all unused images.
+ type: str
- type:
- required: false
- choices: [ imgapi, docker, dsapi ]
- default: imgapi
- description:
- - Type for image sources.
- type: str
+ type:
+ required: false
+ choices: [imgapi, docker, dsapi]
+ default: imgapi
+ description:
+ - Type for image sources.
+ type: str
- uuid:
- required: false
- description:
- - Image UUID. Can either be a full UUID or V(*) for all images.
- type: str
-'''
+ uuid:
+ required: false
+ description:
+ - Image UUID. Can either be a full UUID or V(*) for all images.
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Import an image
community.general.imgadm:
uuid: '70e3ae72-96b6-11e6-9056-9737fd4d0764'
@@ -100,25 +98,25 @@ EXAMPLES = '''
community.general.imgadm:
source: 'https://docker.io'
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
source:
- description: Source that is managed.
- returned: When not managing an image.
- type: str
- sample: https://datasets.project-fifo.net
+ description: Source that is managed.
+ returned: When not managing an image.
+ type: str
+ sample: https://datasets.project-fifo.net
uuid:
- description: UUID for an image operated on.
- returned: When not managing an image source.
- type: str
- sample: 70e3ae72-96b6-11e6-9056-9737fd4d0764
+ description: UUID for an image operated on.
+ returned: When not managing an image source.
+ type: str
+ sample: 70e3ae72-96b6-11e6-9056-9737fd4d0764
state:
- description: State of the target, after execution.
- returned: success
- type: str
- sample: 'present'
-'''
+ description: State of the target, after execution.
+ returned: success
+ type: str
+ sample: 'present'
+"""
import re
diff --git a/plugins/modules/infinity.py b/plugins/modules/infinity.py
index 65aa591f4c..3bcb5aceda 100644
--- a/plugins/modules/infinity.py
+++ b/plugins/modules/infinity.py
@@ -8,7 +8,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: infinity
short_description: Manage Infinity IPAM using Rest API
description:
@@ -41,10 +41,10 @@ options:
required: true
action:
description:
- - Action to perform
+ - Action to perform.
type: str
required: true
- choices: [add_network, delete_network, get_network, get_network_id, release_ip, release_network, reserve_network, reserve_next_available_ip ]
+ choices: [add_network, delete_network, get_network, get_network_id, release_ip, release_network, reserve_network, reserve_next_available_ip]
network_id:
description:
- Network ID.
@@ -55,11 +55,11 @@ options:
type: str
network_address:
description:
- - Network address with CIDR format (e.g., 192.168.310.0).
+ - Network address with CIDR format (for example V(192.168.310.0)).
type: str
network_size:
description:
- - Network bitmask (e.g. 255.255.255.220) or CIDR format (e.g., /26).
+ - Network bitmask (for example V(255.255.255.220) or CIDR format V(/26)).
type: str
network_name:
description:
@@ -67,25 +67,24 @@ options:
type: str
network_location:
description:
- - The parent network id for a given network.
+ - The parent network ID for a given network.
type: int
default: -1
network_type:
description:
- - Network type defined by Infinity
+ - Network type defined by Infinity.
type: str
- choices: [ lan, shared_lan, supernet ]
+ choices: [lan, shared_lan, supernet]
default: lan
network_family:
description:
- - Network family defined by Infinity, e.g. IPv4, IPv6 and Dual stack
+ - Network family defined by Infinity, for example V(IPv4), V(IPv6) and V(Dual stack).
type: str
- choices: [ '4', '6', dual ]
+ choices: ['4', '6', dual]
default: '4'
-'''
+"""
-EXAMPLES = r'''
----
+EXAMPLES = r"""
- hosts: localhost
connection: local
strategy: debug
@@ -102,35 +101,36 @@ EXAMPLES = r'''
network_id: 1201
network_size: /28
register: infinity
-'''
+"""
-RETURN = r'''
+RETURN = r"""
network_id:
- description: id for a given network
- returned: success
- type: str
- sample: '1501'
+ description: ID for a given network.
+ returned: success
+ type: str
+ sample: '1501'
ip_info:
- description: when reserve next available ip address from a network, the ip address info ) is returned.
- returned: success
- type: str
- sample: '{"address": "192.168.10.3", "hostname": "", "FQDN": "", "domainname": "", "id": 3229}'
+ description: When reserve next available IP address from a network, the IP address info is returned.
+ returned: success
+ type: str
+ sample: '{"address": "192.168.10.3", "hostname": "", "FQDN": "", "domainname": "", "id": 3229}'
network_info:
- description: when reserving a LAN network from a Infinity supernet by providing network_size, the information about the reserved network is returned.
- returned: success
- type: str
- sample: {
- "network_address": "192.168.10.32/28",
- "network_family": "4",
- "network_id": 3102,
- "network_size": null,
- "description": null,
- "network_location": "3085",
- "ranges": { "id": 0, "name": null,"first_ip": null,"type": null,"last_ip": null},
- "network_type": "lan",
- "network_name": "'reserve_new_ansible_network'"
- }
-'''
+ description: When reserving a LAN network from a Infinity supernet by providing network_size, the information about the
+ reserved network is returned.
+ returned: success
+ type: str
+ sample: {
+ "network_address": "192.168.10.32/28",
+ "network_family": "4",
+ "network_id": 3102,
+ "network_size": null,
+ "description": null,
+ "network_location": "3085",
+ "ranges": { "id": 0, "name": null,"first_ip": null,"type": null,"last_ip": null},
+ "network_type": "lan",
+ "network_name": "'reserve_new_ansible_network'"
+ }
+"""
from ansible.module_utils.basic import AnsibleModule, json
diff --git a/plugins/modules/influxdb_database.py b/plugins/modules/influxdb_database.py
index a12326da52..e5246ebfe6 100644
--- a/plugins/modules/influxdb_database.py
+++ b/plugins/modules/influxdb_database.py
@@ -9,65 +9,63 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: influxdb_database
short_description: Manage InfluxDB databases
description:
- - Manage InfluxDB databases.
+ - Manage InfluxDB databases.
author: "Kamil Szczygiel (@kamsz)"
requirements:
- - "influxdb >= 0.9"
- - requests
+ - "influxdb >= 0.9"
+ - requests
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- database_name:
- description:
- - Name of the database.
- required: true
- type: str
- state:
- description:
- - Determines if the database should be created or destroyed.
- choices: [ absent, present ]
- default: present
- type: str
+ database_name:
+ description:
+ - Name of the database.
+ required: true
+ type: str
+ state:
+ description:
+ - Determines if the database should be created or destroyed.
+ choices: [absent, present]
+ default: present
+ type: str
extends_documentation_fragment:
- community.general.influxdb
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
# Example influxdb_database command from Ansible Playbooks
- name: Create database
community.general.influxdb_database:
- hostname: "{{influxdb_ip_address}}"
- database_name: "{{influxdb_database_name}}"
+ hostname: "{{influxdb_ip_address}}"
+ database_name: "{{influxdb_database_name}}"
- name: Destroy database
community.general.influxdb_database:
- hostname: "{{influxdb_ip_address}}"
- database_name: "{{influxdb_database_name}}"
- state: absent
+ hostname: "{{influxdb_ip_address}}"
+ database_name: "{{influxdb_database_name}}"
+ state: absent
- name: Create database using custom credentials
community.general.influxdb_database:
- hostname: "{{influxdb_ip_address}}"
- username: "{{influxdb_username}}"
- password: "{{influxdb_password}}"
- database_name: "{{influxdb_database_name}}"
- ssl: true
- validate_certs: true
-'''
+ hostname: "{{influxdb_ip_address}}"
+ username: "{{influxdb_username}}"
+ password: "{{influxdb_password}}"
+ database_name: "{{influxdb_database_name}}"
+ ssl: true
+ validate_certs: true
+"""
-RETURN = r'''
+RETURN = r"""
# only defaults
-'''
+"""
try:
import requests.exceptions
diff --git a/plugins/modules/influxdb_query.py b/plugins/modules/influxdb_query.py
index fda98d1843..98b8066b67 100644
--- a/plugins/modules/influxdb_query.py
+++ b/plugins/modules/influxdb_query.py
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: influxdb_query
short_description: Query data points from InfluxDB
description:
@@ -36,10 +35,9 @@ options:
extends_documentation_fragment:
- community.general.influxdb
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Query connections
community.general.influxdb_query:
hostname: "{{ influxdb_ip_address }}"
@@ -57,17 +55,17 @@ EXAMPLES = r'''
- name: Print results from the query
ansible.builtin.debug:
var: connection.query_results
-'''
+"""
-RETURN = r'''
+RETURN = r"""
query_results:
- description: Result from the query
+ description: Result from the query.
returned: success
type: list
sample:
- mean: 1245.5333333333333
time: "1970-01-01T00:00:00Z"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native
diff --git a/plugins/modules/influxdb_retention_policy.py b/plugins/modules/influxdb_retention_policy.py
index f1c13a8111..824c34bb7d 100644
--- a/plugins/modules/influxdb_retention_policy.py
+++ b/plugins/modules/influxdb_retention_policy.py
@@ -9,136 +9,132 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: influxdb_retention_policy
short_description: Manage InfluxDB retention policies
description:
- - Manage InfluxDB retention policies.
+ - Manage InfluxDB retention policies.
author: "Kamil Szczygiel (@kamsz)"
requirements:
- - "influxdb >= 0.9"
- - requests
+ - "influxdb >= 0.9"
+ - requests
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- database_name:
- description:
- - Name of the database.
- required: true
- type: str
- policy_name:
- description:
- - Name of the retention policy.
- required: true
- type: str
- state:
- description:
- - State of the retention policy.
- choices: [ absent, present ]
- default: present
- type: str
- version_added: 3.1.0
- duration:
- description:
- - Determines how long InfluxDB should keep the data. If specified, it
- should be V(INF) or at least one hour. If not specified, V(INF) is
- assumed. Supports complex duration expressions with multiple units.
- - Required only if O(state) is set to V(present).
- type: str
- replication:
- description:
- - Determines how many independent copies of each point are stored in the cluster.
- - Required only if O(state) is set to V(present).
- type: int
- default:
- description:
- - Sets the retention policy as default retention policy.
- type: bool
- default: false
- shard_group_duration:
- description:
- - Determines the time range covered by a shard group. If specified it
- must be at least one hour. If none, it's determined by InfluxDB by
- the rentention policy's duration. Supports complex duration expressions
- with multiple units.
- type: str
- version_added: '2.0.0'
+ database_name:
+ description:
+ - Name of the database.
+ required: true
+ type: str
+ policy_name:
+ description:
+ - Name of the retention policy.
+ required: true
+ type: str
+ state:
+ description:
+ - State of the retention policy.
+ choices: [absent, present]
+ default: present
+ type: str
+ version_added: 3.1.0
+ duration:
+ description:
+ - Determines how long InfluxDB should keep the data. If specified, it should be V(INF) or at least one hour. If not
+ specified, V(INF) is assumed. Supports complex duration expressions with multiple units.
+ - Required only if O(state) is set to V(present).
+ type: str
+ replication:
+ description:
+ - Determines how many independent copies of each point are stored in the cluster.
+ - Required only if O(state) is set to V(present).
+ type: int
+ default:
+ description:
+ - Sets the retention policy as default retention policy.
+ type: bool
+ default: false
+ shard_group_duration:
+ description:
+ - Determines the time range covered by a shard group. If specified it must be at least one hour. If not provided, it
+ is determined by InfluxDB by the rentention policy's duration. Supports complex duration expressions with multiple
+ units.
+ type: str
+ version_added: '2.0.0'
extends_documentation_fragment:
- community.general.influxdb
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
# Example influxdb_retention_policy command from Ansible Playbooks
- name: Create 1 hour retention policy
community.general.influxdb_retention_policy:
- hostname: "{{ influxdb_ip_address }}"
- database_name: "{{ influxdb_database_name }}"
- policy_name: test
- duration: 1h
- replication: 1
- ssl: true
- validate_certs: true
- state: present
+ hostname: "{{ influxdb_ip_address }}"
+ database_name: "{{ influxdb_database_name }}"
+ policy_name: test
+ duration: 1h
+ replication: 1
+ ssl: true
+ validate_certs: true
+ state: present
- name: Create 1 day retention policy with 1 hour shard group duration
community.general.influxdb_retention_policy:
- hostname: "{{ influxdb_ip_address }}"
- database_name: "{{ influxdb_database_name }}"
- policy_name: test
- duration: 1d
- replication: 1
- shard_group_duration: 1h
- state: present
+ hostname: "{{ influxdb_ip_address }}"
+ database_name: "{{ influxdb_database_name }}"
+ policy_name: test
+ duration: 1d
+ replication: 1
+ shard_group_duration: 1h
+ state: present
- name: Create 1 week retention policy with 1 day shard group duration
community.general.influxdb_retention_policy:
- hostname: "{{ influxdb_ip_address }}"
- database_name: "{{ influxdb_database_name }}"
- policy_name: test
- duration: 1w
- replication: 1
- shard_group_duration: 1d
- state: present
+ hostname: "{{ influxdb_ip_address }}"
+ database_name: "{{ influxdb_database_name }}"
+ policy_name: test
+ duration: 1w
+ replication: 1
+ shard_group_duration: 1d
+ state: present
- name: Create infinite retention policy with 1 week of shard group duration
community.general.influxdb_retention_policy:
- hostname: "{{ influxdb_ip_address }}"
- database_name: "{{ influxdb_database_name }}"
- policy_name: test
- duration: INF
- replication: 1
- ssl: false
- shard_group_duration: 1w
- state: present
+ hostname: "{{ influxdb_ip_address }}"
+ database_name: "{{ influxdb_database_name }}"
+ policy_name: test
+ duration: INF
+ replication: 1
+ ssl: false
+ shard_group_duration: 1w
+ state: present
- name: Create retention policy with complex durations
community.general.influxdb_retention_policy:
- hostname: "{{ influxdb_ip_address }}"
- database_name: "{{ influxdb_database_name }}"
- policy_name: test
- duration: 5d1h30m
- replication: 1
- ssl: false
- shard_group_duration: 1d10h30m
- state: present
+ hostname: "{{ influxdb_ip_address }}"
+ database_name: "{{ influxdb_database_name }}"
+ policy_name: test
+ duration: 5d1h30m
+ replication: 1
+ ssl: false
+ shard_group_duration: 1d10h30m
+ state: present
- name: Drop retention policy
community.general.influxdb_retention_policy:
- hostname: "{{ influxdb_ip_address }}"
- database_name: "{{ influxdb_database_name }}"
- policy_name: test
- state: absent
-'''
+ hostname: "{{ influxdb_ip_address }}"
+ database_name: "{{ influxdb_database_name }}"
+ policy_name: test
+ state: absent
+"""
-RETURN = r'''
+RETURN = r"""
# only defaults
-'''
+"""
import re
diff --git a/plugins/modules/influxdb_user.py b/plugins/modules/influxdb_user.py
index ca4201db1b..bc66ff693d 100644
--- a/plugins/modules/influxdb_user.py
+++ b/plugins/modules/influxdb_user.py
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: influxdb_user
short_description: Manage InfluxDB users
description:
@@ -44,7 +43,7 @@ options:
state:
description:
- State of the user.
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
type: str
grants:
@@ -58,10 +57,9 @@ options:
extends_documentation_fragment:
- community.general.influxdb
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a user on localhost using default login credentials
community.general.influxdb_user:
user_name: john
@@ -101,11 +99,11 @@ EXAMPLES = r'''
login_username: "{{ influxdb_username }}"
login_password: "{{ influxdb_password }}"
state: absent
-'''
+"""
-RETURN = r'''
+RETURN = r"""
#only defaults
-'''
+"""
import json
diff --git a/plugins/modules/influxdb_write.py b/plugins/modules/influxdb_write.py
index 76e6449bb0..c67e57699b 100644
--- a/plugins/modules/influxdb_write.py
+++ b/plugins/modules/influxdb_write.py
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: influxdb_write
short_description: Write data points into InfluxDB
description:
@@ -37,34 +36,33 @@ options:
extends_documentation_fragment:
- community.general.influxdb
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Write points into database
community.general.influxdb_write:
- hostname: "{{influxdb_ip_address}}"
- database_name: "{{influxdb_database_name}}"
- data_points:
- - measurement: connections
- tags:
- host: server01
- region: us-west
- time: "{{ ansible_date_time.iso8601 }}"
- fields:
- value: 2000
- - measurement: connections
- tags:
- host: server02
- region: us-east
- time: "{{ ansible_date_time.iso8601 }}"
- fields:
- value: 3000
-'''
+ hostname: "{{influxdb_ip_address}}"
+ database_name: "{{influxdb_database_name}}"
+ data_points:
+ - measurement: connections
+ tags:
+ host: server01
+ region: us-west
+ time: "{{ ansible_date_time.iso8601 }}"
+ fields:
+ value: 2000
+ - measurement: connections
+ tags:
+ host: server02
+ region: us-east
+ time: "{{ ansible_date_time.iso8601 }}"
+ fields:
+ value: 3000
+"""
-RETURN = r'''
+RETURN = r"""
# only defaults
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native
diff --git a/plugins/modules/ini_file.py b/plugins/modules/ini_file.py
index 18a79ce122..61e6662d95 100644
--- a/plugins/modules/ini_file.py
+++ b/plugins/modules/ini_file.py
@@ -12,19 +12,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ini_file
short_description: Tweak settings in INI files
extends_documentation_fragment:
- files
- community.general.attributes
description:
- - Manage (add, remove, change) individual settings in an INI-style file without having
- to manage the file as a whole with, say, M(ansible.builtin.template) or M(ansible.builtin.assemble).
- - Adds missing sections if they don't exist.
- - This module adds missing ending newlines to files to keep in line with the POSIX standard, even when
- no other modifications need to be applied.
+ - Manage (add, remove, change) individual settings in an INI-style file without having to manage the file as a whole with,
+ say, M(ansible.builtin.template) or M(ansible.builtin.assemble).
+ - Adds missing sections if they do not exist.
+ - This module adds missing ending newlines to files to keep in line with the POSIX standard, even when no other modifications
+ need to be applied.
attributes:
check_mode:
support: full
@@ -36,11 +35,10 @@ options:
- Path to the INI-style file; this file is created if required.
type: path
required: true
- aliases: [ dest ]
+ aliases: [dest]
section:
description:
- - Section name in INI file. This is added if O(state=present) automatically when
- a single value is being set.
+ - Section name in INI file. This is added if O(state=present) automatically when a single value is being set.
- If being omitted, the O(option) will be placed before the first O(section).
- Omitting O(section) is also required if the config format does not support sections.
type: str
@@ -91,28 +89,27 @@ options:
version_added: 3.6.0
backup:
description:
- - Create a backup file including the timestamp information so you can get
- the original file back if you somehow clobbered it incorrectly.
+ - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered
+ it incorrectly.
type: bool
default: false
state:
description:
- If set to V(absent) and O(exclusive) set to V(true) all matching O(option) lines are removed.
- - If set to V(absent) and O(exclusive) set to V(false) the specified O(option=value) lines are removed,
- but the other O(option)s with the same name are not touched.
- - If set to V(present) and O(exclusive) set to V(false) the specified O(option=values) lines are added,
- but the other O(option)s with the same name are not touched.
- - If set to V(present) and O(exclusive) set to V(true) all given O(option=values) lines will be
- added and the other O(option)s with the same name are removed.
+ - If set to V(absent) and O(exclusive) set to V(false) the specified O(option=value) lines are removed, but the other
+ O(option)s with the same name are not touched.
+ - If set to V(present) and O(exclusive) set to V(false) the specified O(option=values) lines are added, but the other
+ O(option)s with the same name are not touched.
+ - If set to V(present) and O(exclusive) set to V(true) all given O(option=values) lines will be added and the other
+ O(option)s with the same name are removed.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
exclusive:
description:
- - If set to V(true) (default), all matching O(option) lines are removed when O(state=absent),
- or replaced when O(state=present).
- - If set to V(false), only the specified O(value)/O(values) are added when O(state=present),
- or removed when O(state=absent), and existing ones are not modified.
+ - If set to V(true) (default), all matching O(option) lines are removed when O(state=absent), or replaced when O(state=present).
+ - If set to V(false), only the specified O(value)/O(values) are added when O(state=present), or removed when O(state=absent),
+ and existing ones are not modified.
type: bool
default: true
version_added: 3.6.0
@@ -141,27 +138,27 @@ options:
modify_inactive_option:
description:
- By default the module replaces a commented line that matches the given option.
- - Set this option to V(false) to avoid this. This is useful when you want to keep commented example
- C(key=value) pairs for documentation purposes.
+ - Set this option to V(false) to avoid this. This is useful when you want to keep commented example C(key=value) pairs
+ for documentation purposes.
type: bool
default: true
version_added: 8.0.0
follow:
description:
- - This flag indicates that filesystem links, if they exist, should be followed.
- - O(follow=true) can modify O(path) when combined with parameters such as O(mode).
+ - This flag indicates that filesystem links, if they exist, should be followed.
+ - O(follow=true) can modify O(path) when combined with parameters such as O(mode).
type: bool
default: false
version_added: 7.1.0
notes:
- - While it is possible to add an O(option) without specifying a O(value), this makes no sense.
- - As of community.general 3.2.0, UTF-8 BOM markers are discarded when reading files.
+ - While it is possible to add an O(option) without specifying a O(value), this makes no sense.
+ - As of community.general 3.2.0, UTF-8 BOM markers are discarded when reading files.
author:
- - Jan-Piet Mens (@jpmens)
- - Ales Nosek (@noseka1)
-'''
+ - Jan-Piet Mens (@jpmens)
+ - Ales Nosek (@noseka1)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure "fav=lemonade is in section "[drinks]" in specified file
community.general.ini_file:
path: /etc/conf
@@ -257,7 +254,7 @@ EXAMPLES = r'''
value: xxxxxxxxxxxxxxxxxxxx
mode: '0600'
state: present
-'''
+"""
import io
import os
diff --git a/plugins/modules/installp.py b/plugins/modules/installp.py
index 1531d2cad2..e54a56949f 100644
--- a/plugins/modules/installp.py
+++ b/plugins/modules/installp.py
@@ -8,14 +8,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: installp
author:
- Kairo Araujo (@kairoaraujo)
short_description: Manage packages on AIX
description:
- - Manage packages using 'installp' on AIX
+ - Manage packages using 'installp' on AIX.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -26,32 +25,32 @@ attributes:
options:
accept_license:
description:
- - Whether to accept the license for the package(s).
+ - Whether to accept the license for the package(s).
type: bool
default: false
name:
description:
- - One or more packages to install or remove.
- - Use V(all) to install all packages available on informed O(repository_path).
+ - One or more packages to install or remove.
+ - Use V(all) to install all packages available on informed O(repository_path).
type: list
elements: str
required: true
- aliases: [ pkg ]
+ aliases: [pkg]
repository_path:
description:
- - Path with AIX packages (required to install).
+ - Path with AIX packages (required to install).
type: path
state:
description:
- - Whether the package needs to be present on or absent from the system.
+ - Whether the package needs to be present on or absent from the system.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
notes:
-- If the package is already installed, even the package/fileset is new, the module will not install it.
-'''
+ - If the package is already installed, even the package/fileset is new, the module will not install it.
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Install package foo
community.general.installp:
name: foo
@@ -84,9 +83,9 @@ EXAMPLES = r'''
community.general.installp:
name: bos.sysmgt.nim.master
state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
import os
import re
diff --git a/plugins/modules/interfaces_file.py b/plugins/modules/interfaces_file.py
index 98103082ec..23bfd78790 100644
--- a/plugins/modules/interfaces_file.py
+++ b/plugins/modules/interfaces_file.py
@@ -9,16 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: interfaces_file
short_description: Tweak settings in C(/etc/network/interfaces) files
extends_documentation_fragment:
- ansible.builtin.files
- community.general.attributes
description:
- - Manage (add, remove, change) individual interface options in an interfaces-style file without having
- to manage the file as a whole with, say, M(ansible.builtin.template) or M(ansible.builtin.assemble). Interface has to be presented in a file.
+ - Manage (add, remove, change) individual interface options in an interfaces-style file without having to manage the file
+ as a whole with, say, M(ansible.builtin.template) or M(ansible.builtin.assemble). Interface has to be presented in a file.
- Read information about interfaces from interfaces-styled files.
attributes:
check_mode:
@@ -46,14 +45,14 @@ options:
value:
type: str
description:
- - If O(option) is not presented for the O(iface) and O(state) is V(present) option will be added.
- If O(option) already exists and is not V(pre-up), V(up), V(post-up) or V(down), it's value will be updated.
- V(pre-up), V(up), V(post-up) and V(down) options cannot be updated, only adding new options, removing existing
- ones or cleaning the whole option set are supported.
+ - If O(option) is not presented for the O(iface) and O(state) is V(present) option will be added. If O(option) already
+ exists and is not V(pre-up), V(up), V(post-up) or V(down), its value will be updated. V(pre-up), V(up), V(post-up)
+ and V(down) options cannot be updated, only adding new options, removing existing ones or cleaning the whole option
+ set are supported.
backup:
description:
- - Create a backup file including the timestamp information so you can get
- the original file back if you somehow clobbered it incorrectly.
+ - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered
+ it incorrectly.
type: bool
default: false
state:
@@ -61,86 +60,85 @@ options:
description:
- If set to V(absent) the option or section will be removed if present instead of created.
default: "present"
- choices: [ "present", "absent" ]
+ choices: ["present", "absent"]
notes:
- - If option is defined multiple times last one will be updated but all will be deleted in case of an absent state.
+ - If option is defined multiple times last one will be updated but all will be deleted in case of an absent state.
requirements: []
author: "Roman Belyakovsky (@hryamzik)"
-'''
+"""
-RETURN = '''
+RETURN = r"""
dest:
- description: Destination file/path.
- returned: success
- type: str
- sample: "/etc/network/interfaces"
+ description: Destination file/path.
+ returned: success
+ type: str
+ sample: "/etc/network/interfaces"
ifaces:
- description: Interfaces dictionary.
- returned: success
- type: dict
- contains:
- ifaces:
- description: Interface dictionary.
- returned: success
- type: dict
- contains:
- eth0:
- description: Name of the interface.
- returned: success
- type: dict
- contains:
- address_family:
- description: Interface address family.
- returned: success
- type: str
- sample: "inet"
- method:
- description: Interface method.
- returned: success
- type: str
- sample: "manual"
- mtu:
- description: Other options, all values returned as strings.
- returned: success
- type: str
- sample: "1500"
- pre-up:
- description: List of C(pre-up) scripts.
- returned: success
- type: list
- elements: str
- sample:
- - "route add -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
- - "route add -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
- up:
- description: List of C(up) scripts.
- returned: success
- type: list
- elements: str
- sample:
- - "route add -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
- - "route add -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
- post-up:
- description: List of C(post-up) scripts.
- returned: success
- type: list
- elements: str
- sample:
- - "route add -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
- - "route add -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
- down:
- description: List of C(down) scripts.
- returned: success
- type: list
- elements: str
- sample:
- - "route del -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
- - "route del -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
-...
-'''
+ description: Interfaces dictionary.
+ returned: success
+ type: dict
+ contains:
+ ifaces:
+ description: Interface dictionary.
+ returned: success
+ type: dict
+ contains:
+ eth0:
+ description: Name of the interface.
+ returned: success
+ type: dict
+ contains:
+ address_family:
+ description: Interface address family.
+ returned: success
+ type: str
+ sample: "inet"
+ method:
+ description: Interface method.
+ returned: success
+ type: str
+ sample: "manual"
+ mtu:
+ description: Other options, all values returned as strings.
+ returned: success
+ type: str
+ sample: "1500"
+ pre-up:
+ description: List of C(pre-up) scripts.
+ returned: success
+ type: list
+ elements: str
+ sample:
+ - "route add -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
+ - "route add -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
+ up:
+ description: List of C(up) scripts.
+ returned: success
+ type: list
+ elements: str
+ sample:
+ - "route add -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
+ - "route add -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
+ post-up:
+ description: List of C(post-up) scripts.
+ returned: success
+ type: list
+ elements: str
+ sample:
+ - "route add -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
+ - "route add -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
+ down:
+ description: List of C(down) scripts.
+ returned: success
+ type: list
+ elements: str
+ sample:
+ - "route del -net 10.10.10.0/24 gw 10.10.10.1 dev eth1"
+ - "route del -net 10.10.11.0/24 gw 10.10.11.1 dev eth2"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Set eth1 mtu configuration value to 8000
community.general.interfaces_file:
dest: /etc/network/interfaces.d/eth1.cfg
@@ -150,7 +148,7 @@ EXAMPLES = '''
backup: true
state: present
register: eth1_cfg
-'''
+"""
import os
import re
diff --git a/plugins/modules/ip_netns.py b/plugins/modules/ip_netns.py
index 69534c810d..6bcae8e5f2 100644
--- a/plugins/modules/ip_netns.py
+++ b/plugins/modules/ip_netns.py
@@ -7,37 +7,36 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ip_netns
author: "Arie Bregman (@bregman-arie)"
short_description: Manage network namespaces
-requirements: [ ip ]
+requirements: [ip]
description:
- - Create or delete network namespaces using the ip command.
+ - Create or delete network namespaces using the C(ip) command.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- required: false
- description:
- - Name of the namespace
- type: str
- state:
- required: false
- default: "present"
- choices: [ present, absent ]
- description:
- - Whether the namespace should exist
- type: str
-'''
+ name:
+ required: false
+ description:
+ - Name of the namespace.
+ type: str
+ state:
+ required: false
+ default: "present"
+ choices: [present, absent]
+ description:
+ - Whether the namespace should exist.
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a namespace named mario
community.general.ip_netns:
name: mario
@@ -47,11 +46,11 @@ EXAMPLES = '''
community.general.ip_netns:
name: luigi
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
# Default return values
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_text
diff --git a/plugins/modules/ipa_config.py b/plugins/modules/ipa_config.py
index 871643fd7b..ea08f8f8ba 100644
--- a/plugins/modules/ipa_config.py
+++ b/plugins/modules/ipa_config.py
@@ -7,8 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_config
author: Fran Fitzpatrick (@fxfitz)
short_description: Manage Global FreeIPA Configuration Settings
@@ -115,10 +114,9 @@ options:
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure password plugin features DC:Disable Last Success and KDC:Disable Lockout are enabled
community.general.ipa_config:
ipaconfigstring: ["KDC:Disable Last Success", "KDC:Disable Lockout"]
@@ -221,14 +219,14 @@ EXAMPLES = r'''
ipa_host: localhost
ipa_user: admin
ipa_pass: supersecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
config:
description: Configuration as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_dnsrecord.py b/plugins/modules/ipa_dnsrecord.py
index 1dad138377..d92e2c4f66 100644
--- a/plugins/modules/ipa_dnsrecord.py
+++ b/plugins/modules/ipa_dnsrecord.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_dnsrecord
author: Abhijeet Kasurde (@Akasurde)
short_description: Manage FreeIPA DNS records
@@ -23,64 +22,66 @@ attributes:
options:
zone_name:
description:
- - The DNS zone name to which DNS record needs to be managed.
+ - The DNS zone name to which DNS record needs to be managed.
required: true
type: str
record_name:
description:
- - The DNS record name to manage.
+ - The DNS record name to manage.
required: true
aliases: ["name"]
type: str
record_type:
description:
- - The type of DNS record name.
- - Support for V(NS) was added in comunity.general 8.2.0.
- - Support for V(SSHFP) was added in community.general 9.1.0.
+ - The type of DNS record name.
+ - Support for V(NS) was added in comunity.general 8.2.0.
+ - Support for V(SSHFP) was added in community.general 9.1.0.
required: false
default: 'A'
choices: ['A', 'AAAA', 'A6', 'CNAME', 'DNAME', 'MX', 'NS', 'PTR', 'SRV', 'TXT', 'SSHFP']
type: str
record_value:
description:
- - Manage DNS record name with this value.
- - Mutually exclusive with O(record_values), and exactly one of O(record_value) and O(record_values) has to be specified.
- - Use O(record_values) if you need to specify multiple values.
- - In the case of V(A) or V(AAAA) record types, this will be the IP address.
- - In the case of V(A6) record type, this will be the A6 Record data.
- - In the case of V(CNAME) record type, this will be the hostname.
- - In the case of V(DNAME) record type, this will be the DNAME target.
- - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA record.
- - In the case of V(PTR) record type, this will be the hostname.
- - In the case of V(TXT) record type, this will be a text.
- - In the case of V(SRV) record type, this will be a service record.
- - In the case of V(MX) record type, this will be a mail exchanger record.
- - In the case of V(SSHFP) record type, this will be an SSH fingerprint record.
+ - Manage DNS record name with this value.
+ - Mutually exclusive with O(record_values), and exactly one of O(record_value) and O(record_values) has to be specified.
+ - Use O(record_values) if you need to specify multiple values.
+ - In the case of V(A) or V(AAAA) record types, this will be the IP address.
+ - In the case of V(A6) record type, this will be the A6 Record data.
+ - In the case of V(CNAME) record type, this will be the hostname.
+ - In the case of V(DNAME) record type, this will be the DNAME target.
+ - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA
+ record.
+ - In the case of V(PTR) record type, this will be the hostname.
+ - In the case of V(TXT) record type, this will be a text.
+ - In the case of V(SRV) record type, this will be a service record.
+ - In the case of V(MX) record type, this will be a mail exchanger record.
+ - In the case of V(SSHFP) record type, this will be an SSH fingerprint record.
type: str
record_values:
description:
- - Manage DNS record name with this value.
- - Mutually exclusive with O(record_value), and exactly one of O(record_value) and O(record_values) has to be specified.
- - In the case of V(A) or V(AAAA) record types, this will be the IP address.
- - In the case of V(A6) record type, this will be the A6 Record data.
- - In the case of V(CNAME) record type, this will be the hostname.
- - In the case of V(DNAME) record type, this will be the DNAME target.
- - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA record.
- - In the case of V(PTR) record type, this will be the hostname.
- - In the case of V(TXT) record type, this will be a text.
- - In the case of V(SRV) record type, this will be a service record.
- - In the case of V(MX) record type, this will be a mail exchanger record.
- - In the case of V(SSHFP) record type, this will be an SSH fingerprint record.
+ - Manage DNS record name with this value.
+ - Mutually exclusive with O(record_value), and exactly one of O(record_value) and O(record_values) has to be specified.
+ - In the case of V(A) or V(AAAA) record types, this will be the IP address.
+ - In the case of V(A6) record type, this will be the A6 Record data.
+ - In the case of V(CNAME) record type, this will be the hostname.
+ - In the case of V(DNAME) record type, this will be the DNAME target.
+ - In the case of V(NS) record type, this will be the name server hostname. Hostname must already have a valid A or AAAA
+ record.
+ - In the case of V(PTR) record type, this will be the hostname.
+ - In the case of V(TXT) record type, this will be a text.
+ - In the case of V(SRV) record type, this will be a service record.
+ - In the case of V(MX) record type, this will be a mail exchanger record.
+ - In the case of V(SSHFP) record type, this will be an SSH fingerprint record.
type: list
elements: str
record_ttl:
description:
- - Set the TTL for the record.
- - Applies only when adding a new or changing the value of O(record_value) or O(record_values).
+ - Set the TTL for the record.
+ - Applies only when adding a new or changing the value of O(record_value) or O(record_values).
required: false
type: int
state:
- description: State to ensure
+ description: State to ensure.
required: false
default: present
choices: ["absent", "present"]
@@ -88,10 +89,9 @@ options:
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure dns record is present
community.general.ipa_dnsrecord:
ipa_host: spider.example.com
@@ -189,14 +189,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: ChangeMe!
-'''
+"""
-RETURN = r'''
+RETURN = r"""
dnsrecord:
description: DNS record as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_dnszone.py b/plugins/modules/ipa_dnszone.py
index 6699b0525b..b536c258d2 100644
--- a/plugins/modules/ipa_dnszone.py
+++ b/plugins/modules/ipa_dnszone.py
@@ -8,13 +8,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_dnszone
author: Fran Fitzpatrick (@fxfitz)
short_description: Manage FreeIPA DNS Zones
description:
- - Add and delete an IPA DNS Zones using IPA API
+ - Add and delete an IPA DNS Zones using IPA API.
attributes:
check_mode:
support: full
@@ -23,11 +22,11 @@ attributes:
options:
zone_name:
description:
- - The DNS zone name to which needs to be managed.
+ - The DNS zone name to which needs to be managed.
required: true
type: str
state:
- description: State to ensure
+ description: State to ensure.
required: false
default: present
choices: ["absent", "present"]
@@ -44,10 +43,9 @@ options:
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure dns zone is present
community.general.ipa_dnszone:
ipa_host: spider.example.com
@@ -78,14 +76,14 @@ EXAMPLES = r'''
state: present
zone_name: example.com
allowsyncptr: true
-'''
+"""
-RETURN = r'''
+RETURN = r"""
zone:
description: DNS zone as returned by IPA API.
returned: always
type: dict
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ipa import IPAClient, ipa_argument_spec
diff --git a/plugins/modules/ipa_getkeytab.py b/plugins/modules/ipa_getkeytab.py
index 3d4f81d5b1..dfd612564b 100644
--- a/plugins/modules/ipa_getkeytab.py
+++ b/plugins/modules/ipa_getkeytab.py
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_getkeytab
short_description: Manage keytab file in FreeIPA
version_added: 9.5.0
@@ -82,7 +81,8 @@ options:
state:
description:
- The state of the keytab file.
- - V(present) only check for existence of a file, if you want to recreate keytab with other parameters you should set O(force=true).
+ - V(present) only check for existence of a file, if you want to recreate keytab with other parameters you should set
+ O(force=true).
type: str
default: present
choices: ["present", "absent"]
@@ -95,14 +95,12 @@ requirements:
- Managed host is FreeIPA client
extends_documentation_fragment:
- community.general.attributes
-'''
+"""
-EXAMPLES = r'''
-- name: Get kerberos ticket
- ansible.builtin.shell: kinit admin
- args:
- stdin: "{{ aldpro_admin_password }}"
- changed_when: true
+EXAMPLES = r"""
+- name: Get Kerberos ticket using default principal
+ community.general.krb_ticket:
+ password: "{{ aldpro_admin_password }}"
- name: Create keytab
community.general.ipa_getkeytab:
@@ -123,7 +121,7 @@ EXAMPLES = r'''
principal: HTTP/freeipa-dc02.ipa.test
ipa_host: freeipa-dc01.ipa.test
force: true
-'''
+"""
import os
diff --git a/plugins/modules/ipa_group.py b/plugins/modules/ipa_group.py
index 92470606fc..60077a2c6a 100644
--- a/plugins/modules/ipa_group.py
+++ b/plugins/modules/ipa_group.py
@@ -7,13 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_group
author: Thomas Krahn (@Nosmoht)
short_description: Manage FreeIPA group
description:
- - Add, modify and delete group within IPA server
+ - Add, modify and delete group within IPA server.
attributes:
check_mode:
support: full
@@ -22,77 +21,76 @@ attributes:
options:
append:
description:
- - If V(true), add the listed O(user) and O(group) to the group members.
- - If V(false), only the listed O(user) and O(group) will be group members, removing any other members.
+ - If V(true), add the listed O(user) and O(group) to the group members.
+ - If V(false), only the listed O(user) and O(group) will be group members, removing any other members.
default: false
type: bool
version_added: 4.0.0
cn:
description:
- - Canonical name.
- - Can not be changed as it is the unique identifier.
+ - Canonical name.
+ - Can not be changed as it is the unique identifier.
required: true
aliases: ['name']
type: str
description:
description:
- - Description of the group.
+ - Description of the group.
type: str
external:
description:
- - Allow adding external non-IPA members from trusted domains.
+ - Allow adding external non-IPA members from trusted domains.
type: bool
gidnumber:
description:
- - GID (use this option to set it manually).
+ - GID (use this option to set it manually).
aliases: ['gid']
type: str
group:
description:
- - List of group names assigned to this group.
- - If O(append=false) and an empty list is passed all groups will be removed from this group.
- - Groups that are already assigned but not passed will be removed.
- - If O(append=true) the listed groups will be assigned without removing other groups.
- - If option is omitted assigned groups will not be checked or changed.
+ - List of group names assigned to this group.
+ - If O(append=false) and an empty list is passed all groups will be removed from this group.
+ - Groups that are already assigned but not passed will be removed.
+ - If O(append=true) the listed groups will be assigned without removing other groups.
+ - If option is omitted assigned groups will not be checked or changed.
type: list
elements: str
nonposix:
description:
- - Create as a non-POSIX group.
+ - Create as a non-POSIX group.
type: bool
user:
description:
- - List of user names assigned to this group.
- - If O(append=false) and an empty list is passed all users will be removed from this group.
- - Users that are already assigned but not passed will be removed.
- - If O(append=true) the listed users will be assigned without removing other users.
- - If option is omitted assigned users will not be checked or changed.
+ - List of user names assigned to this group.
+ - If O(append=false) and an empty list is passed all users will be removed from this group.
+ - Users that are already assigned but not passed will be removed.
+ - If O(append=true) the listed users will be assigned without removing other users.
+ - If option is omitted assigned users will not be checked or changed.
type: list
elements: str
external_user:
description:
- - List of external users assigned to this group.
- - Behaves identically to O(user) with respect to O(append) attribute.
- - List entries can be in V(DOMAIN\\\\username) or SID format.
- - Unless SIDs are provided, the module will always attempt to make changes even if the group already has all the users.
- This is because only SIDs are returned by IPA query.
- - O(external=true) is needed for this option to work.
+ - List of external users assigned to this group.
+ - Behaves identically to O(user) with respect to O(append) attribute.
+ - List entries can be in V(DOMAIN\\\\username) or SID format.
+ - Unless SIDs are provided, the module will always attempt to make changes even if the group already has all the users.
+ This is because only SIDs are returned by IPA query.
+ - O(external=true) is needed for this option to work.
type: list
elements: str
version_added: 6.3.0
state:
description:
- - State to ensure
+ - State to ensure.
default: "present"
choices: ["absent", "present"]
type: str
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure group is present
community.general.ipa_group:
name: oinstall
@@ -106,8 +104,8 @@ EXAMPLES = r'''
community.general.ipa_group:
name: ops
group:
- - sysops
- - appops
+ - sysops
+ - appops
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
@@ -116,8 +114,8 @@ EXAMPLES = r'''
community.general.ipa_group:
name: sysops
user:
- - linus
- - larry
+ - linus
+ - larry
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
@@ -126,7 +124,7 @@ EXAMPLES = r'''
community.general.ipa_group:
name: developers
user:
- - john
+ - john
append: true
state: present
ipa_host: ipa.example.com
@@ -135,25 +133,25 @@ EXAMPLES = r'''
- name: Add external user to a group
community.general.ipa_group:
- name: developers
- external: true
- append: true
- external_user:
- - S-1-5-21-123-1234-12345-63421
- ipa_host: ipa.example.com
- ipa_user: admin
- ipa_pass: topsecret
+ name: developers
+ external: true
+ append: true
+ external_user:
+ - S-1-5-21-123-1234-12345-63421
+ ipa_host: ipa.example.com
+ ipa_user: admin
+ ipa_pass: topsecret
- name: Add a user from MYDOMAIN
community.general.ipa_group:
- name: developers
- external: true
- append: true
- external_user:
- - MYDOMAIN\\john
- ipa_host: ipa.example.com
- ipa_user: admin
- ipa_pass: topsecret
+ name: developers
+ external: true
+ append: true
+ external_user:
+ - MYDOMAIN\\john
+ ipa_host: ipa.example.com
+ ipa_user: admin
+ ipa_pass: topsecret
- name: Ensure group is absent
community.general.ipa_group:
@@ -162,14 +160,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
group:
- description: Group as returned by IPA API
+ description: Group as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_hbacrule.py b/plugins/modules/ipa_hbacrule.py
index 77a4d0d487..d168a3a7e0 100644
--- a/plugins/modules/ipa_hbacrule.py
+++ b/plugins/modules/ipa_hbacrule.py
@@ -7,8 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_hbacrule
author: Thomas Krahn (@Nosmoht)
short_description: Manage FreeIPA HBAC rule
@@ -22,99 +21,98 @@ attributes:
options:
cn:
description:
- - Canonical name.
- - Can not be changed as it is the unique identifier.
+ - Canonical name.
+ - Can not be changed as it is the unique identifier.
required: true
aliases: ["name"]
type: str
description:
- description: Description
+ description: Description.
type: str
host:
description:
- - List of host names to assign.
- - If an empty list is passed all hosts will be removed from the rule.
- - If option is omitted hosts will not be checked or changed.
+ - List of host names to assign.
+ - If an empty list is passed all hosts will be removed from the rule.
+ - If option is omitted hosts will not be checked or changed.
required: false
type: list
elements: str
hostcategory:
- description: Host category
+ description: Host category.
choices: ['all']
type: str
hostgroup:
description:
- - List of hostgroup names to assign.
- - If an empty list is passed all hostgroups will be removed. from the rule
- - If option is omitted hostgroups will not be checked or changed.
+ - List of hostgroup names to assign.
+ - If an empty list is passed all hostgroups will be removed from the rule.
+ - If option is omitted hostgroups will not be checked or changed.
type: list
elements: str
service:
description:
- - List of service names to assign.
- - If an empty list is passed all services will be removed from the rule.
- - If option is omitted services will not be checked or changed.
+ - List of service names to assign.
+ - If an empty list is passed all services will be removed from the rule.
+ - If option is omitted services will not be checked or changed.
type: list
elements: str
servicecategory:
- description: Service category
+ description: Service category.
choices: ['all']
type: str
servicegroup:
description:
- - List of service group names to assign.
- - If an empty list is passed all assigned service groups will be removed from the rule.
- - If option is omitted service groups will not be checked or changed.
+ - List of service group names to assign.
+ - If an empty list is passed all assigned service groups will be removed from the rule.
+ - If option is omitted service groups will not be checked or changed.
type: list
elements: str
sourcehost:
description:
- - List of source host names to assign.
- - If an empty list if passed all assigned source hosts will be removed from the rule.
- - If option is omitted source hosts will not be checked or changed.
+ - List of source host names to assign.
+ - If an empty list if passed all assigned source hosts will be removed from the rule.
+ - If option is omitted source hosts will not be checked or changed.
type: list
elements: str
sourcehostcategory:
- description: Source host category
+ description: Source host category.
choices: ['all']
type: str
sourcehostgroup:
description:
- - List of source host group names to assign.
- - If an empty list if passed all assigned source host groups will be removed from the rule.
- - If option is omitted source host groups will not be checked or changed.
+ - List of source host group names to assign.
+ - If an empty list if passed all assigned source host groups will be removed from the rule.
+ - If option is omitted source host groups will not be checked or changed.
type: list
elements: str
state:
- description: State to ensure
+ description: State to ensure.
default: "present"
- choices: ["absent", "disabled", "enabled","present"]
+ choices: ["absent", "disabled", "enabled", "present"]
type: str
user:
description:
- - List of user names to assign.
- - If an empty list if passed all assigned users will be removed from the rule.
- - If option is omitted users will not be checked or changed.
+ - List of user names to assign.
+ - If an empty list if passed all assigned users will be removed from the rule.
+ - If option is omitted users will not be checked or changed.
type: list
elements: str
usercategory:
- description: User category
+ description: User category.
choices: ['all']
type: str
usergroup:
description:
- - List of user group names to assign.
- - If an empty list if passed all assigned user groups will be removed from the rule.
- - If option is omitted user groups will not be checked or changed.
+ - List of user group names to assign.
+ - If an empty list if passed all assigned user groups will be removed from the rule.
+ - If option is omitted user groups will not be checked or changed.
type: list
elements: str
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure rule to allow all users to access any host from any host
community.general.ipa_hbacrule:
name: allow_all
@@ -132,9 +130,9 @@ EXAMPLES = r'''
name: allow_all_developers_access_to_db
description: Allow all developers to access any database from any host
hostgroup:
- - db-server
+ - db-server
usergroup:
- - developers
+ - developers
state: present
ipa_host: ipa.example.com
ipa_user: admin
@@ -147,14 +145,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
hbacrule:
description: HBAC rule as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_host.py b/plugins/modules/ipa_host.py
index 791cee91f3..a78ea6223e 100644
--- a/plugins/modules/ipa_host.py
+++ b/plugins/modules/ipa_host.py
@@ -7,8 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_host
author: Thomas Krahn (@Nosmoht)
short_description: Manage FreeIPA host
@@ -22,73 +21,73 @@ attributes:
options:
fqdn:
description:
- - Full qualified domain name.
- - Can not be changed as it is the unique identifier.
+ - Full qualified domain name.
+ - Can not be changed as it is the unique identifier.
required: true
aliases: ["name"]
type: str
description:
description:
- - A description of this host.
+ - A description of this host.
type: str
force:
description:
- - Force host name even if not in DNS.
+ - Force host name even if not in DNS.
required: false
type: bool
ip_address:
description:
- - Add the host to DNS with this IP address.
+ - Add the host to DNS with this IP address.
type: str
mac_address:
description:
- - List of Hardware MAC address(es) off this host.
- - If option is omitted MAC addresses will not be checked or changed.
- - If an empty list is passed all assigned MAC addresses will be removed.
- - MAC addresses that are already assigned but not passed will be removed.
+ - List of Hardware MAC address(es) off this host.
+ - If option is omitted MAC addresses will not be checked or changed.
+ - If an empty list is passed all assigned MAC addresses will be removed.
+ - MAC addresses that are already assigned but not passed will be removed.
aliases: ["macaddress"]
type: list
elements: str
ns_host_location:
description:
- - Host location (e.g. "Lab 2")
+ - Host location (for example V(Lab 2)).
aliases: ["nshostlocation"]
type: str
ns_hardware_platform:
description:
- - Host hardware platform (e.g. "Lenovo T61")
+ - Host hardware platform (for example V(Lenovo T61")).
aliases: ["nshardwareplatform"]
type: str
ns_os_version:
description:
- - Host operating system and version (e.g. "Fedora 9")
+ - Host operating system and version (for example V(Fedora 9)).
aliases: ["nsosversion"]
type: str
user_certificate:
description:
- - List of Base-64 encoded server certificates.
- - If option is omitted certificates will not be checked or changed.
- - If an empty list is passed all assigned certificates will be removed.
- - Certificates already assigned but not passed will be removed.
+ - List of Base-64 encoded server certificates.
+ - If option is omitted certificates will not be checked or changed.
+ - If an empty list is passed all assigned certificates will be removed.
+ - Certificates already assigned but not passed will be removed.
aliases: ["usercertificate"]
type: list
elements: str
state:
description:
- - State to ensure.
+ - State to ensure.
default: present
choices: ["absent", "disabled", "enabled", "present"]
type: str
force_creation:
description:
- - Create host if O(state=disabled) or O(state=enabled) but not present.
+ - Create host if O(state=disabled) or O(state=enabled) but not present.
default: true
type: bool
version_added: 9.5.0
update_dns:
description:
- - If set V(true) with O(state=absent), then removes DNS records of the host managed by FreeIPA DNS.
- - This option has no effect for states other than "absent".
+ - If set V(true) with O(state=absent), then removes DNS records of the host managed by FreeIPA DNS.
+ - This option has no effect for states other than V(absent).
type: bool
random_password:
description: Generate a random password to be used in bulk enrollment.
@@ -96,10 +95,9 @@ options:
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure host is present
community.general.ipa_host:
name: host01.example.com
@@ -109,8 +107,8 @@ EXAMPLES = r'''
ns_os_version: CentOS 7
ns_hardware_platform: Lenovo T61
mac_address:
- - "08:00:27:E3:B1:2D"
- - "52:54:00:BD:97:1E"
+ - "08:00:27:E3:B1:2D"
+ - "52:54:00:BD:97:1E"
state: present
ipa_host: ipa.example.com
ipa_user: admin
@@ -159,18 +157,18 @@ EXAMPLES = r'''
ipa_user: admin
ipa_pass: topsecret
update_dns: true
-'''
+"""
-RETURN = r'''
+RETURN = r"""
host:
description: Host as returned by IPA API.
returned: always
type: dict
host_diff:
- description: List of options that differ and would be changed
+ description: List of options that differ and would be changed.
returned: if check mode and a difference is found
type: list
-'''
+"""
import traceback
@@ -272,6 +270,10 @@ def ensure(module, client):
data = {}
for key in diff:
data[key] = module_host.get(key)
+ if "usercertificate" not in data:
+ data["usercertificate"] = [
+ cert['__base64__'] for cert in ipa_host.get("usercertificate", [])
+ ]
ipa_host_show = client.host_show(name=name)
if ipa_host_show.get('has_keytab', True) and (state == 'disabled' or module.params.get('random_password')):
client.host_disable(name=name)
diff --git a/plugins/modules/ipa_hostgroup.py b/plugins/modules/ipa_hostgroup.py
index 9e6abf32aa..c1e7d3ad56 100644
--- a/plugins/modules/ipa_hostgroup.py
+++ b/plugins/modules/ipa_hostgroup.py
@@ -7,8 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_hostgroup
author: Thomas Krahn (@Nosmoht)
short_description: Manage FreeIPA host-group
@@ -22,61 +21,61 @@ attributes:
options:
append:
description:
- - If V(true), add the listed O(host) to the O(hostgroup).
- - If V(false), only the listed O(host) will be in O(hostgroup), removing any other hosts.
+ - If V(true), add the listed O(host) to the O(hostgroup).
+ - If V(false), only the listed O(host) will be in O(hostgroup), removing any other hosts.
default: false
type: bool
version_added: 6.6.0
cn:
description:
- - Name of host-group.
- - Can not be changed as it is the unique identifier.
+ - Name of host-group.
+ - Can not be changed as it is the unique identifier.
required: true
aliases: ["name"]
type: str
description:
description:
- - Description.
+ - Description.
type: str
host:
description:
- - List of hosts that belong to the host-group.
- - If an empty list is passed all hosts will be removed from the group.
- - If option is omitted hosts will not be checked or changed.
- - If option is passed all assigned hosts that are not passed will be unassigned from the group.
+ - List of hosts that belong to the host-group.
+ - If an empty list is passed all hosts will be removed from the group.
+ - If option is omitted hosts will not be checked or changed.
+ - If option is passed all assigned hosts that are not passed will be unassigned from the group.
type: list
elements: str
hostgroup:
description:
- - List of host-groups than belong to that host-group.
- - If an empty list is passed all host-groups will be removed from the group.
- - If option is omitted host-groups will not be checked or changed.
- - If option is passed all assigned hostgroups that are not passed will be unassigned from the group.
+ - List of host-groups than belong to that host-group.
+ - If an empty list is passed all host-groups will be removed from the group.
+ - If option is omitted host-groups will not be checked or changed.
+ - If option is passed all assigned hostgroups that are not passed will be unassigned from the group.
type: list
elements: str
state:
description:
- - State to ensure.
- - V("absent") and V("disabled") give the same results.
- - V("present") and V("enabled") give the same results.
+ - State to ensure.
+ - V("absent") and V("disabled") give the same results.
+ - V("present") and V("enabled") give the same results.
default: "present"
choices: ["absent", "disabled", "enabled", "present"]
type: str
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure host-group databases is present
community.general.ipa_hostgroup:
name: databases
state: present
host:
- - db.example.com
+ - db.example.com
hostgroup:
- - mysql-server
- - oracle-server
+ - mysql-server
+ - oracle-server
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
@@ -88,14 +87,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
hostgroup:
description: Hostgroup as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_otpconfig.py b/plugins/modules/ipa_otpconfig.py
index e2d8f0cd52..3c07c7eda3 100644
--- a/plugins/modules/ipa_otpconfig.py
+++ b/plugins/modules/ipa_otpconfig.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_otpconfig
author: justchris1 (@justchris1)
short_description: Manage FreeIPA OTP Configuration Settings
@@ -41,10 +40,9 @@ options:
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure the TOTP authentication window is set to 300 seconds
community.general.ipa_otpconfig:
ipatokentotpauthwindow: '300'
@@ -72,14 +70,14 @@ EXAMPLES = r'''
ipa_host: localhost
ipa_user: admin
ipa_pass: supersecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
otpconfig:
description: OTP configuration as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_otptoken.py b/plugins/modules/ipa_otptoken.py
index d8a5b3cf1d..5f5c8dd612 100644
--- a/plugins/modules/ipa_otptoken.py
+++ b/plugins/modules/ipa_otptoken.py
@@ -7,8 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_otptoken
author: justchris1 (@justchris1)
short_description: Manage FreeIPA OTPs
@@ -27,25 +26,25 @@ options:
aliases: ["name"]
type: str
newuniqueid:
- description: If specified, the unique id specified will be changed to this.
+ description: If specified, the unique ID specified will be changed to this.
type: str
otptype:
description:
- - Type of OTP.
- - "B(Note:) Cannot be modified after OTP is created."
+ - Type of OTP.
+ - B(Note:) Cannot be modified after OTP is created.
type: str
- choices: [ totp, hotp ]
+ choices: [totp, hotp]
secretkey:
description:
- - Token secret (Base64).
- - If OTP is created and this is not specified, a random secret will be generated by IPA.
- - "B(Note:) Cannot be modified after OTP is created."
+ - Token secret (Base64).
+ - If OTP is created and this is not specified, a random secret will be generated by IPA.
+ - B(Note:) Cannot be modified after OTP is created.
type: str
description:
description: Description of the token (informational only).
type: str
owner:
- description: Assigned user of the token.
+ description: Assigned user of the token.
type: str
enabled:
description: Mark the token as enabled (default V(true)).
@@ -53,15 +52,15 @@ options:
type: bool
notbefore:
description:
- - First date/time the token can be used.
- - In the format C(YYYYMMddHHmmss).
- - For example, C(20180121182022) will allow the token to be used starting on 21 January 2018 at 18:20:22.
+ - First date/time the token can be used.
+ - In the format C(YYYYMMddHHmmss).
+ - For example, V(20180121182022) will allow the token to be used starting on 21 January 2018 at 18:20:22.
type: str
notafter:
description:
- - Last date/time the token can be used.
- - In the format C(YYYYMMddHHmmss).
- - For example, C(20200121182022) will allow the token to be used until 21 January 2020 at 18:20:22.
+ - Last date/time the token can be used.
+ - In the format C(YYYYMMddHHmmss).
+ - For example, V(20200121182022) will allow the token to be used until 21 January 2020 at 18:20:22.
type: str
vendor:
description: Token vendor name (informational only).
@@ -79,37 +78,37 @@ options:
type: str
algorithm:
description:
- - Token hash algorithm.
- - "B(Note:) Cannot be modified after OTP is created."
+ - Token hash algorithm.
+ - B(Note:) Cannot be modified after OTP is created.
choices: ['sha1', 'sha256', 'sha384', 'sha512']
type: str
digits:
description:
- - Number of digits each token code will have.
- - "B(Note:) Cannot be modified after OTP is created."
- choices: [ 6, 8 ]
+ - Number of digits each token code will have.
+ - B(Note:) Cannot be modified after OTP is created.
+ choices: [6, 8]
type: int
offset:
description:
- - TOTP token / IPA server time difference.
- - "B(Note:) Cannot be modified after OTP is created."
+ - TOTP token / IPA server time difference.
+ - B(Note:) Cannot be modified after OTP is created.
type: int
interval:
description:
- - Length of TOTP token code validity in seconds.
- - "B(Note:) Cannot be modified after OTP is created."
+ - Length of TOTP token code validity in seconds.
+ - B(Note:) Cannot be modified after OTP is created.
type: int
counter:
description:
- - Initial counter for the HOTP token.
- - "B(Note:) Cannot be modified after OTP is created."
+ - Initial counter for the HOTP token.
+ - B(Note:) Cannot be modified after OTP is created.
type: int
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a totp for pinky, allowing the IPA server to generate using defaults
community.general.ipa_otptoken:
uniqueid: Token123
@@ -161,14 +160,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
otptoken:
- description: OTP Token as returned by IPA API
+ description: OTP Token as returned by IPA API.
returned: always
type: dict
-'''
+"""
import base64
import traceback
diff --git a/plugins/modules/ipa_pwpolicy.py b/plugins/modules/ipa_pwpolicy.py
index ba7d702916..5b41651e09 100644
--- a/plugins/modules/ipa_pwpolicy.py
+++ b/plugins/modules/ipa_pwpolicy.py
@@ -7,152 +7,153 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_pwpolicy
author: Adralioh (@adralioh)
short_description: Manage FreeIPA password policies
description:
-- Add, modify, or delete a password policy using the IPA API.
+ - Add, modify, or delete a password policy using the IPA API.
version_added: 2.0.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- group:
- description:
- - Name of the group that the policy applies to.
- - If omitted, the global policy is used.
- aliases: ["name"]
- type: str
- state:
- description: State to ensure.
- default: "present"
- choices: ["absent", "present"]
- type: str
- maxpwdlife:
- description: Maximum password lifetime (in days).
- type: str
- minpwdlife:
- description: Minimum password lifetime (in hours).
- type: str
- historylength:
- description:
- - Number of previous passwords that are remembered.
- - Users cannot reuse remembered passwords.
- type: str
- minclasses:
- description: Minimum number of character classes.
- type: str
- minlength:
- description: Minimum password length.
- type: str
- priority:
- description:
- - Priority of the policy.
- - High number means lower priority.
- - Required when C(cn) is not the global policy.
- type: str
- maxfailcount:
- description: Maximum number of consecutive failures before lockout.
- type: str
- failinterval:
- description: Period (in seconds) after which the number of failed login attempts is reset.
- type: str
- lockouttime:
- description: Period (in seconds) for which users are locked out.
- type: str
- gracelimit:
- description: Maximum number of LDAP logins after password expiration.
- type: int
- version_added: 8.2.0
- maxrepeat:
- description: Maximum number of allowed same consecutive characters in the new password.
- type: int
- version_added: 8.2.0
- maxsequence:
- description: Maximum length of monotonic character sequences in the new password. An example of a monotonic sequence of length 5 is V(12345).
- type: int
- version_added: 8.2.0
- dictcheck:
- description: Check whether the password (with possible modifications) matches a word in a dictionary (using cracklib).
- type: bool
- version_added: 8.2.0
- usercheck:
- description: Check whether the password (with possible modifications) contains the user name in some form (if the name has > 3 characters).
- type: bool
- version_added: 8.2.0
+ group:
+ description:
+ - Name of the group that the policy applies to.
+ - If omitted, the global policy is used.
+ aliases: ["name"]
+ type: str
+ state:
+ description: State to ensure.
+ default: "present"
+ choices: ["absent", "present"]
+ type: str
+ maxpwdlife:
+ description: Maximum password lifetime (in days).
+ type: str
+ minpwdlife:
+ description: Minimum password lifetime (in hours).
+ type: str
+ historylength:
+ description:
+ - Number of previous passwords that are remembered.
+ - Users cannot reuse remembered passwords.
+ type: str
+ minclasses:
+ description: Minimum number of character classes.
+ type: str
+ minlength:
+ description: Minimum password length.
+ type: str
+ priority:
+ description:
+ - Priority of the policy.
+ - High number means lower priority.
+ - Required when C(cn) is not the global policy.
+ type: str
+ maxfailcount:
+ description: Maximum number of consecutive failures before lockout.
+ type: str
+ failinterval:
+ description: Period (in seconds) after which the number of failed login attempts is reset.
+ type: str
+ lockouttime:
+ description: Period (in seconds) for which users are locked out.
+ type: str
+ gracelimit:
+ description: Maximum number of LDAP logins after password expiration.
+ type: int
+ version_added: 8.2.0
+ maxrepeat:
+ description: Maximum number of allowed same consecutive characters in the new password.
+ type: int
+ version_added: 8.2.0
+ maxsequence:
+ description: Maximum length of monotonic character sequences in the new password. An example of a monotonic sequence of
+ length 5 is V(12345).
+ type: int
+ version_added: 8.2.0
+ dictcheck:
+ description: Check whether the password (with possible modifications) matches a word in a dictionary (using cracklib).
+ type: bool
+ version_added: 8.2.0
+ usercheck:
+ description: Check whether the password (with possible modifications) contains the user name in some form (if the name
+ has > 3 characters).
+ type: bool
+ version_added: 8.2.0
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Modify the global password policy
community.general.ipa_pwpolicy:
- maxpwdlife: '90'
- minpwdlife: '1'
- historylength: '8'
- minclasses: '3'
- minlength: '16'
- maxfailcount: '6'
- failinterval: '60'
- lockouttime: '600'
- ipa_host: ipa.example.com
- ipa_user: admin
- ipa_pass: topsecret
+ maxpwdlife: '90'
+ minpwdlife: '1'
+ historylength: '8'
+ minclasses: '3'
+ minlength: '16'
+ maxfailcount: '6'
+ failinterval: '60'
+ lockouttime: '600'
+ ipa_host: ipa.example.com
+ ipa_user: admin
+ ipa_pass: topsecret
- name: Ensure the password policy for the group admins is present
community.general.ipa_pwpolicy:
- group: admins
- state: present
- maxpwdlife: '60'
- minpwdlife: '24'
- historylength: '16'
- minclasses: '4'
- priority: '10'
- minlength: '6'
- maxfailcount: '4'
- failinterval: '600'
- lockouttime: '1200'
- gracelimit: 3
- maxrepeat: 3
- maxsequence: 3
- dictcheck: true
- usercheck: true
- ipa_host: ipa.example.com
- ipa_user: admin
- ipa_pass: topsecret
+ group: admins
+ state: present
+ maxpwdlife: '60'
+ minpwdlife: '24'
+ historylength: '16'
+ minclasses: '4'
+ priority: '10'
+ minlength: '6'
+ maxfailcount: '4'
+ failinterval: '600'
+ lockouttime: '1200'
+ gracelimit: 3
+ maxrepeat: 3
+ maxsequence: 3
+ dictcheck: true
+ usercheck: true
+ ipa_host: ipa.example.com
+ ipa_user: admin
+ ipa_pass: topsecret
- name: Ensure that the group sysops does not have a unique password policy
community.general.ipa_pwpolicy:
- group: sysops
- state: absent
- ipa_host: ipa.example.com
- ipa_user: admin
- ipa_pass: topsecret
-'''
+ group: sysops
+ state: absent
+ ipa_host: ipa.example.com
+ ipa_user: admin
+ ipa_pass: topsecret
+"""
-RETURN = r'''
+RETURN = r"""
pwpolicy:
- description: Password policy as returned by IPA API.
- returned: always
- type: dict
- sample:
- cn: ['admins']
- cospriority: ['10']
- dn: 'cn=admins,cn=EXAMPLE.COM,cn=kerberos,dc=example,dc=com'
- krbmaxpwdlife: ['60']
- krbminpwdlife: ['24']
- krbpwdfailurecountinterval: ['600']
- krbpwdhistorylength: ['16']
- krbpwdlockoutduration: ['1200']
- krbpwdmaxfailure: ['4']
- krbpwdmindiffchars: ['4']
- objectclass: ['top', 'nscontainer', 'krbpwdpolicy']
-'''
+ description: Password policy as returned by IPA API.
+ returned: always
+ type: dict
+ sample:
+ cn: ['admins']
+ cospriority: ['10']
+ dn: 'cn=admins,cn=EXAMPLE.COM,cn=kerberos,dc=example,dc=com'
+ krbmaxpwdlife: ['60']
+ krbminpwdlife: ['24']
+ krbpwdfailurecountinterval: ['600']
+ krbpwdhistorylength: ['16']
+ krbpwdlockoutduration: ['1200']
+ krbpwdmaxfailure: ['4']
+ krbpwdmindiffchars: ['4']
+ objectclass: ['top', 'nscontainer', 'krbpwdpolicy']
+"""
import traceback
diff --git a/plugins/modules/ipa_role.py b/plugins/modules/ipa_role.py
index fce315b662..e77b732cb2 100644
--- a/plugins/modules/ipa_role.py
+++ b/plugins/modules/ipa_role.py
@@ -7,13 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_role
author: Thomas Krahn (@Nosmoht)
short_description: Manage FreeIPA role
description:
-- Add, modify and delete a role within FreeIPA server using FreeIPA API.
+ - Add, modify and delete a role within FreeIPA server using FreeIPA API.
attributes:
check_mode:
support: full
@@ -22,53 +21,53 @@ attributes:
options:
cn:
description:
- - Role name.
- - Can not be changed as it is the unique identifier.
+ - Role name.
+ - Can not be changed as it is the unique identifier.
required: true
aliases: ['name']
type: str
description:
description:
- - A description of this role-group.
+ - A description of this role-group.
type: str
group:
description:
- - List of group names assign to this role.
- - If an empty list is passed all assigned groups will be unassigned from the role.
- - If option is omitted groups will not be checked or changed.
- - If option is passed all assigned groups that are not passed will be unassigned from the role.
+ - List of group names assign to this role.
+ - If an empty list is passed all assigned groups will be unassigned from the role.
+ - If option is omitted groups will not be checked or changed.
+ - If option is passed all assigned groups that are not passed will be unassigned from the role.
type: list
elements: str
host:
description:
- - List of host names to assign.
- - If an empty list is passed all assigned hosts will be unassigned from the role.
- - If option is omitted hosts will not be checked or changed.
- - If option is passed all assigned hosts that are not passed will be unassigned from the role.
+ - List of host names to assign.
+ - If an empty list is passed all assigned hosts will be unassigned from the role.
+ - If option is omitted hosts will not be checked or changed.
+ - If option is passed all assigned hosts that are not passed will be unassigned from the role.
type: list
elements: str
hostgroup:
description:
- - List of host group names to assign.
- - If an empty list is passed all assigned host groups will be removed from the role.
- - If option is omitted host groups will not be checked or changed.
- - If option is passed all assigned hostgroups that are not passed will be unassigned from the role.
+ - List of host group names to assign.
+ - If an empty list is passed all assigned host groups will be removed from the role.
+ - If option is omitted host groups will not be checked or changed.
+ - If option is passed all assigned hostgroups that are not passed will be unassigned from the role.
type: list
elements: str
privilege:
description:
- - List of privileges granted to the role.
- - If an empty list is passed all assigned privileges will be removed.
- - If option is omitted privileges will not be checked or changed.
- - If option is passed all assigned privileges that are not passed will be removed.
+ - List of privileges granted to the role.
+ - If an empty list is passed all assigned privileges will be removed.
+ - If option is omitted privileges will not be checked or changed.
+ - If option is passed all assigned privileges that are not passed will be removed.
type: list
elements: str
service:
description:
- - List of service names to assign.
- - If an empty list is passed all assigned services will be removed from the role.
- - If option is omitted services will not be checked or changed.
- - If option is passed all assigned services that are not passed will be removed from the role.
+ - List of service names to assign.
+ - If an empty list is passed all assigned services will be removed from the role.
+ - If option is omitted services will not be checked or changed.
+ - If option is passed all assigned services that are not passed will be removed from the role.
type: list
elements: str
state:
@@ -78,26 +77,25 @@ options:
type: str
user:
description:
- - List of user names to assign.
- - If an empty list is passed all assigned users will be removed from the role.
- - If option is omitted users will not be checked or changed.
+ - List of user names to assign.
+ - If an empty list is passed all assigned users will be removed from the role.
+ - If option is omitted users will not be checked or changed.
type: list
elements: str
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure role is present
community.general.ipa_role:
name: dba
description: Database Administrators
state: present
user:
- - pinky
- - brain
+ - pinky
+ - brain
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
@@ -107,16 +105,16 @@ EXAMPLES = r'''
name: another-role
description: Just another role
group:
- - editors
+ - editors
host:
- - host01.example.com
+ - host01.example.com
hostgroup:
- - hostgroup01
+ - hostgroup01
privilege:
- - Group Administrators
- - User Administrators
+ - Group Administrators
+ - User Administrators
service:
- - service01
+ - service01
- name: Ensure role is absent
community.general.ipa_role:
@@ -125,14 +123,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
role:
description: Role as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_service.py b/plugins/modules/ipa_service.py
index d9541674f2..54c5575950 100644
--- a/plugins/modules/ipa_service.py
+++ b/plugins/modules/ipa_service.py
@@ -7,13 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_service
author: Cédric Parent (@cprh)
short_description: Manage FreeIPA service
description:
-- Add and delete an IPA service using IPA API.
+ - Add and delete an IPA service using IPA API.
attributes:
check_mode:
support: full
@@ -22,26 +21,26 @@ attributes:
options:
krbcanonicalname:
description:
- - Principal of the service.
- - Can not be changed as it is the unique identifier.
+ - Principal of the service.
+ - Can not be changed as it is the unique identifier.
required: true
aliases: ["name"]
type: str
hosts:
description:
- - Defines the list of 'ManagedBy' hosts.
+ - Defines the list of C(ManagedBy) hosts.
required: false
type: list
elements: str
force:
description:
- - Force principal name even if host is not in DNS.
+ - Force principal name even if host is not in DNS.
required: false
type: bool
skip_host_check:
description:
- - Force service to be created even when host object does not exist to manage it.
- - This is only used on creation, not for updating existing services.
+ - Force service to be created even when host object does not exist to manage it.
+ - This is only used on creation, not for updating existing services.
required: false
type: bool
default: false
@@ -55,10 +54,9 @@ options:
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure service is present
community.general.ipa_service:
name: http/host01.example.com
@@ -79,19 +77,19 @@ EXAMPLES = r'''
community.general.ipa_service:
name: http/host01.example.com
hosts:
- - host01.example.com
- - host02.example.com
+ - host01.example.com
+ - host02.example.com
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
service:
description: Service as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_subca.py b/plugins/modules/ipa_subca.py
index 882b1ac396..ddb551689d 100644
--- a/plugins/modules/ipa_subca.py
+++ b/plugins/modules/ipa_subca.py
@@ -7,13 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_subca
author: Abhijeet Kasurde (@Akasurde)
short_description: Manage FreeIPA Lightweight Sub Certificate Authorities
description:
-- Add, modify, enable, disable and delete an IPA Lightweight Sub Certificate Authorities using IPA API.
+ - Add, modify, enable, disable and delete an IPA Lightweight Sub Certificate Authorities using IPA API.
attributes:
check_mode:
support: full
@@ -22,23 +21,23 @@ attributes:
options:
subca_name:
description:
- - The Sub Certificate Authority name which needs to be managed.
+ - The Sub Certificate Authority name which needs to be managed.
required: true
aliases: ["name"]
type: str
subca_subject:
description:
- - The Sub Certificate Authority's Subject. e.g., 'CN=SampleSubCA1,O=testrelm.test'.
+ - The Sub Certificate Authority's Subject, for example V(CN=SampleSubCA1,O=testrelm.test).
required: true
type: str
subca_desc:
description:
- - The Sub Certificate Authority's description.
+ - The Sub Certificate Authority's description.
type: str
state:
description:
- - State to ensure.
- - State 'disable' and 'enable' is available for FreeIPA 4.4.2 version and onwards.
+ - State to ensure.
+ - States V(disable) and V(enable) are available for FreeIPA 4.4.2 version and onwards.
required: false
default: present
choices: ["absent", "disabled", "enabled", "present"]
@@ -46,10 +45,9 @@ options:
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Ensure IPA Sub CA is present
community.general.ipa_subca:
ipa_host: spider.example.com
@@ -72,14 +70,14 @@ EXAMPLES = '''
ipa_pass: Passw0rd!
state: disable
subca_name: AnsibleSubCA1
-'''
+"""
-RETURN = r'''
+RETURN = r"""
subca:
description: IPA Sub CA record as returned by IPA API.
returned: always
type: dict
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ipa import IPAClient, ipa_argument_spec
diff --git a/plugins/modules/ipa_sudocmd.py b/plugins/modules/ipa_sudocmd.py
index d3139ba1c3..f52d3e9e6d 100644
--- a/plugins/modules/ipa_sudocmd.py
+++ b/plugins/modules/ipa_sudocmd.py
@@ -7,13 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_sudocmd
author: Thomas Krahn (@Nosmoht)
short_description: Manage FreeIPA sudo command
description:
-- Add, modify or delete sudo command within FreeIPA server using FreeIPA API.
+ - Add, modify or delete sudo command within FreeIPA server using FreeIPA API.
attributes:
check_mode:
support: full
@@ -22,13 +21,13 @@ attributes:
options:
sudocmd:
description:
- - Sudo command.
+ - Sudo command.
aliases: ['name']
required: true
type: str
description:
description:
- - A description of this command.
+ - A description of this command.
type: str
state:
description: State to ensure.
@@ -38,10 +37,9 @@ options:
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure sudo command exists
community.general.ipa_sudocmd:
name: su
@@ -57,14 +55,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
sudocmd:
- description: Sudo command as return from IPA API
+ description: Sudo command as return from IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_sudocmdgroup.py b/plugins/modules/ipa_sudocmdgroup.py
index a768e74a1a..c7ab798f4c 100644
--- a/plugins/modules/ipa_sudocmdgroup.py
+++ b/plugins/modules/ipa_sudocmdgroup.py
@@ -7,13 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_sudocmdgroup
author: Thomas Krahn (@Nosmoht)
short_description: Manage FreeIPA sudo command group
description:
-- Add, modify or delete sudo command group within IPA server using IPA API.
+ - Add, modify or delete sudo command group within IPA server using IPA API.
attributes:
check_mode:
support: full
@@ -22,13 +21,13 @@ attributes:
options:
cn:
description:
- - Sudo Command Group.
+ - Sudo Command Group.
aliases: ['name']
required: true
type: str
description:
description:
- - Group description.
+ - Group description.
type: str
state:
description: State to ensure.
@@ -37,24 +36,23 @@ options:
type: str
sudocmd:
description:
- - List of sudo commands to assign to the group.
- - If an empty list is passed all assigned commands will be removed from the group.
- - If option is omitted sudo commands will not be checked or changed.
+ - List of sudo commands to assign to the group.
+ - If an empty list is passed all assigned commands will be removed from the group.
+ - If option is omitted sudo commands will not be checked or changed.
type: list
elements: str
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure sudo command group exists
community.general.ipa_sudocmdgroup:
name: group01
description: Group of important commands
sudocmd:
- - su
+ - su
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
@@ -66,14 +64,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
sudocmdgroup:
- description: Sudo command group as returned by IPA API
+ description: Sudo command group as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_sudorule.py b/plugins/modules/ipa_sudorule.py
index 223f6b6de7..1670a52035 100644
--- a/plugins/modules/ipa_sudorule.py
+++ b/plugins/modules/ipa_sudorule.py
@@ -7,13 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_sudorule
author: Thomas Krahn (@Nosmoht)
short_description: Manage FreeIPA sudo rule
description:
-- Add, modify or delete sudo rule within IPA server using IPA API.
+ - Add, modify or delete sudo rule within IPA server using IPA API.
attributes:
check_mode:
support: full
@@ -22,83 +21,83 @@ attributes:
options:
cn:
description:
- - Canonical name.
- - Can not be changed as it is the unique identifier.
+ - Canonical name.
+ - Can not be changed as it is the unique identifier.
required: true
aliases: ['name']
type: str
cmdcategory:
description:
- - Command category the rule applies to.
+ - Command category the rule applies to.
choices: ['all']
type: str
cmd:
description:
- - List of commands assigned to the rule.
- - If an empty list is passed all commands will be removed from the rule.
- - If option is omitted commands will not be checked or changed.
+ - List of commands assigned to the rule.
+ - If an empty list is passed all commands will be removed from the rule.
+ - If option is omitted commands will not be checked or changed.
type: list
elements: str
cmdgroup:
description:
- - List of command groups assigned to the rule.
- - If an empty list is passed all command groups will be removed from the rule.
- - If option is omitted command groups will not be checked or changed.
+ - List of command groups assigned to the rule.
+ - If an empty list is passed all command groups will be removed from the rule.
+ - If option is omitted command groups will not be checked or changed.
type: list
elements: str
version_added: 2.0.0
deny_cmd:
description:
- - List of denied commands assigned to the rule.
- - If an empty list is passed all commands will be removed from the rule.
- - If option is omitted commands will not be checked or changed.
+ - List of denied commands assigned to the rule.
+ - If an empty list is passed all commands will be removed from the rule.
+ - If option is omitted commands will not be checked or changed.
type: list
elements: str
version_added: 8.1.0
deny_cmdgroup:
description:
- - List of denied command groups assigned to the rule.
- - If an empty list is passed all command groups will be removed from the rule.
- - If option is omitted command groups will not be checked or changed.
+ - List of denied command groups assigned to the rule.
+ - If an empty list is passed all command groups will be removed from the rule.
+ - If option is omitted command groups will not be checked or changed.
type: list
elements: str
version_added: 8.1.0
description:
description:
- - Description of the sudo rule.
+ - Description of the sudo rule.
type: str
host:
description:
- - List of hosts assigned to the rule.
- - If an empty list is passed all hosts will be removed from the rule.
- - If option is omitted hosts will not be checked or changed.
- - Option O(hostcategory) must be omitted to assign hosts.
+ - List of hosts assigned to the rule.
+ - If an empty list is passed all hosts will be removed from the rule.
+ - If option is omitted hosts will not be checked or changed.
+ - Option O(hostcategory) must be omitted to assign hosts.
type: list
elements: str
hostcategory:
description:
- - Host category the rule applies to.
- - If V(all) is passed one must omit O(host) and O(hostgroup).
- - Option O(host) and O(hostgroup) must be omitted to assign V(all).
+ - Host category the rule applies to.
+ - If V(all) is passed one must omit O(host) and O(hostgroup).
+ - Option O(host) and O(hostgroup) must be omitted to assign V(all).
choices: ['all']
type: str
hostgroup:
description:
- - List of host groups assigned to the rule.
- - If an empty list is passed all host groups will be removed from the rule.
- - If option is omitted host groups will not be checked or changed.
- - Option O(hostcategory) must be omitted to assign host groups.
+ - List of host groups assigned to the rule.
+ - If an empty list is passed all host groups will be removed from the rule.
+ - If option is omitted host groups will not be checked or changed.
+ - Option O(hostcategory) must be omitted to assign host groups.
type: list
elements: str
runasextusers:
description:
- - List of external RunAs users
+ - List of external RunAs users.
type: list
elements: str
version_added: 2.3.0
runasusercategory:
description:
- - RunAs User category the rule applies to.
+ - RunAs User category the rule applies to.
choices: ['all']
type: str
runasgroupcategory:
@@ -113,21 +112,21 @@ options:
elements: str
user:
description:
- - List of users assigned to the rule.
- - If an empty list is passed all users will be removed from the rule.
- - If option is omitted users will not be checked or changed.
+ - List of users assigned to the rule.
+ - If an empty list is passed all users will be removed from the rule.
+ - If option is omitted users will not be checked or changed.
type: list
elements: str
usercategory:
description:
- - User category the rule applies to.
+ - User category the rule applies to.
choices: ['all']
type: str
usergroup:
description:
- - List of user groups assigned to the rule.
- - If an empty list is passed all user groups will be removed from the rule.
- - If option is omitted user groups will not be checked or changed.
+ - List of user groups assigned to the rule.
+ - If an empty list is passed all user groups will be removed from the rule.
+ - If option is omitted user groups will not be checked or changed.
type: list
elements: str
state:
@@ -138,18 +137,18 @@ options:
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
-- name: Ensure sudo rule is present that's allows all every body to execute any command on any host without being asked for a password.
+EXAMPLES = r"""
+- name: Ensure sudo rule is present that's allows all every body to execute any command on any host without being asked
+ for a password.
community.general.ipa_sudorule:
name: sudo_all_nopasswd
cmdcategory: all
description: Allow to run every command with sudo without password
hostcategory: all
sudoopt:
- - '!authenticate'
+ - '!authenticate'
usercategory: all
ipa_host: ipa.example.com
ipa_user: admin
@@ -161,13 +160,13 @@ EXAMPLES = r'''
description: Allow developers to run every command with sudo on all database server
cmdcategory: all
host:
- - db01.example.com
+ - db01.example.com
hostgroup:
- - db-server
+ - db-server
sudoopt:
- - '!authenticate'
+ - '!authenticate'
usergroup:
- - developers
+ - developers
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
@@ -177,25 +176,25 @@ EXAMPLES = r'''
name: sudo_operations_all
description: Allow operators to run any commands that is part of operations-cmdgroup on any host as user root.
cmdgroup:
- - operations-cmdgroup
+ - operations-cmdgroup
hostcategory: all
runasextusers:
- - root
+ - root
sudoopt:
- - '!authenticate'
+ - '!authenticate'
usergroup:
- - operators
+ - operators
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
sudorule:
- description: Sudorule as returned by IPA
+ description: Sudorule as returned by IPA.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipa_user.py b/plugins/modules/ipa_user.py
index e8a1858d0b..47d50972bd 100644
--- a/plugins/modules/ipa_user.py
+++ b/plugins/modules/ipa_user.py
@@ -7,13 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_user
author: Thomas Krahn (@Nosmoht)
short_description: Manage FreeIPA users
description:
-- Add, modify and delete user within IPA server.
+ - Add, modify and delete user within IPA server.
attributes:
check_mode:
support: full
@@ -25,46 +24,46 @@ options:
type: str
update_password:
description:
- - Set password for a user.
+ - Set password for a user.
type: str
default: 'always'
- choices: [ always, on_create ]
+ choices: [always, on_create]
givenname:
description:
- - First name.
- - If user does not exist and O(state=present), the usage of O(givenname) is required.
+ - First name.
+ - If user does not exist and O(state=present), the usage of O(givenname) is required.
type: str
krbpasswordexpiration:
description:
- - Date at which the user password will expire.
- - In the format YYYYMMddHHmmss.
- - e.g. 20180121182022 will expire on 21 January 2018 at 18:20:22.
+ - Date at which the user password will expire.
+ - In the format YYYYMMddHHmmss.
+ - For example V(20180121182022) will expire on 21 January 2018 at 18:20:22.
type: str
loginshell:
description: Login shell.
type: str
mail:
description:
- - List of mail addresses assigned to the user.
- - If an empty list is passed all assigned email addresses will be deleted.
- - If None is passed email addresses will not be checked or changed.
+ - List of mail addresses assigned to the user.
+ - If an empty list is passed all assigned email addresses will be deleted.
+ - If None is passed email addresses will not be checked or changed.
type: list
elements: str
password:
description:
- - Password for a user.
- - Will not be set for an existing user unless O(update_password=always), which is the default.
+ - Password for a user.
+ - Will not be set for an existing user unless O(update_password=always), which is the default.
type: str
sn:
description:
- - Surname.
- - If user does not exist and O(state=present), the usage of O(sn) is required.
+ - Surname.
+ - If user does not exist and O(state=present), the usage of O(sn) is required.
type: str
sshpubkey:
description:
- - List of public SSH key.
- - If an empty list is passed all assigned public keys will be deleted.
- - If None is passed SSH public keys will not be checked or changed.
+ - List of public SSH key.
+ - If an empty list is passed all assigned public keys will be deleted.
+ - If None is passed SSH public keys will not be checked or changed.
type: list
elements: str
state:
@@ -74,37 +73,37 @@ options:
type: str
telephonenumber:
description:
- - List of telephone numbers assigned to the user.
- - If an empty list is passed all assigned telephone numbers will be deleted.
- - If None is passed telephone numbers will not be checked or changed.
+ - List of telephone numbers assigned to the user.
+ - If an empty list is passed all assigned telephone numbers will be deleted.
+ - If None is passed telephone numbers will not be checked or changed.
type: list
elements: str
title:
description: Title.
type: str
uid:
- description: uid of the user.
+ description: Uid of the user.
required: true
aliases: ["name"]
type: str
uidnumber:
description:
- - Account Settings UID/Posix User ID number.
+ - Account Settings UID/Posix User ID number.
type: str
gidnumber:
description:
- - Posix Group ID.
+ - Posix Group ID.
type: str
homedirectory:
description:
- - Default home directory of the user.
+ - Default home directory of the user.
type: str
version_added: '0.2.0'
userauthtype:
description:
- - The authentication type to use for the user.
- - To remove all authentication types from the user, use an empty list V([]).
- - The choice V(idp) and V(passkey) has been added in community.general 8.1.0.
+ - The authentication type to use for the user.
+ - To remove all authentication types from the user, use an empty list V([]).
+ - The choice V(idp) and V(passkey) has been added in community.general 8.1.0.
choices: ["password", "radius", "otp", "pkinit", "hardened", "idp", "passkey"]
type: list
elements: str
@@ -114,11 +113,11 @@ extends_documentation_fragment:
- community.general.attributes
requirements:
-- base64
-- hashlib
-'''
+ - base64
+ - hashlib
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure pinky is present and always reset password
community.general.ipa_user:
name: pinky
@@ -127,12 +126,12 @@ EXAMPLES = r'''
givenname: Pinky
sn: Acme
mail:
- - pinky@acme.com
+ - pinky@acme.com
telephonenumber:
- - '+555123456'
+ - '+555123456'
sshpubkey:
- - ssh-rsa ....
- - ssh-dsa ....
+ - ssh-rsa ....
+ - ssh-dsa ....
uidnumber: '1001'
gidnumber: '100'
homedirectory: /home/pinky
@@ -170,14 +169,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
user:
- description: User as returned by IPA API
+ description: User as returned by IPA API.
returned: always
type: dict
-'''
+"""
import base64
import hashlib
@@ -269,7 +268,7 @@ def get_user_diff(client, ipa_user, module_user):
if 'sshpubkeyfp' in ipa_user and ipa_user['sshpubkeyfp'][0][:7].upper() == 'SHA256:':
hash_algo = 'sha256'
module_user['sshpubkeyfp'] = [get_ssh_key_fingerprint(pubkey, hash_algo) for pubkey in module_user['ipasshpubkey']]
- # Remove the ipasshpubkey element as it is not returned from IPA but save it's value to be used later on
+ # Remove the ipasshpubkey element as it is not returned from IPA but save its value to be used later on
sshpubkey = module_user['ipasshpubkey']
del module_user['ipasshpubkey']
diff --git a/plugins/modules/ipa_vault.py b/plugins/modules/ipa_vault.py
index 88947e470e..23002b7ce0 100644
--- a/plugins/modules/ipa_vault.py
+++ b/plugins/modules/ipa_vault.py
@@ -7,84 +7,82 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipa_vault
author: Juan Manuel Parrilla (@jparrill)
short_description: Manage FreeIPA vaults
description:
-- Add, modify and delete vaults and secret vaults.
-- KRA service should be enabled to use this module.
+ - Add, modify and delete vaults and secret vaults.
+ - KRA service should be enabled to use this module.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- cn:
- description:
- - Vault name.
- - Can not be changed as it is the unique identifier.
- required: true
- aliases: ["name"]
- type: str
+ cn:
description:
- description:
- - Description.
- type: str
- ipavaulttype:
- description:
- - Vault types are based on security level.
- default: "symmetric"
- choices: ["asymmetric", "standard", "symmetric"]
- aliases: ["vault_type"]
- type: str
- ipavaultpublickey:
- description:
- - Public key.
- aliases: ["vault_public_key"]
- type: str
- ipavaultsalt:
- description:
- - Vault Salt.
- aliases: ["vault_salt"]
- type: str
- username:
- description:
- - Any user can own one or more user vaults.
- - Mutually exclusive with service.
- aliases: ["user"]
- type: list
- elements: str
- service:
- description:
- - Any service can own one or more service vaults.
- - Mutually exclusive with user.
- type: str
- state:
- description:
- - State to ensure.
- default: "present"
- choices: ["absent", "present"]
- type: str
- replace:
- description:
- - Force replace the existent vault on IPA server.
- type: bool
- default: false
- choices: ["True", "False"]
- validate_certs:
- description:
- - Validate IPA server certificates.
- type: bool
- default: true
+ - Vault name.
+ - Can not be changed as it is the unique identifier.
+ required: true
+ aliases: ["name"]
+ type: str
+ description:
+ description:
+ - Description.
+ type: str
+ ipavaulttype:
+ description:
+ - Vault types are based on security level.
+ default: "symmetric"
+ choices: ["asymmetric", "standard", "symmetric"]
+ aliases: ["vault_type"]
+ type: str
+ ipavaultpublickey:
+ description:
+ - Public key.
+ aliases: ["vault_public_key"]
+ type: str
+ ipavaultsalt:
+ description:
+ - Vault Salt.
+ aliases: ["vault_salt"]
+ type: str
+ username:
+ description:
+ - Any user can own one or more user vaults.
+ - Mutually exclusive with O(service).
+ aliases: ["user"]
+ type: list
+ elements: str
+ service:
+ description:
+ - Any service can own one or more service vaults.
+ - Mutually exclusive with O(user).
+ type: str
+ state:
+ description:
+ - State to ensure.
+ default: "present"
+ choices: ["absent", "present"]
+ type: str
+ replace:
+ description:
+ - Force replace the existent vault on IPA server.
+ type: bool
+ default: false
+ choices: ["True", "False"]
+ validate_certs:
+ description:
+ - Validate IPA server certificates.
+ type: bool
+ default: true
extends_documentation_fragment:
- community.general.ipa.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure vault is present
community.general.ipa_vault:
name: vault01
@@ -128,14 +126,14 @@ EXAMPLES = r'''
ipa_host: ipa.example.com
ipa_user: admin
ipa_pass: topsecret
-'''
+"""
-RETURN = r'''
+RETURN = r"""
vault:
- description: Vault as returned by IPA API
+ description: Vault as returned by IPA API.
returned: always
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/ipbase_info.py b/plugins/modules/ipbase_info.py
index c6a5511b73..3c7d3d26c1 100644
--- a/plugins/modules/ipbase_info.py
+++ b/plugins/modules/ipbase_info.py
@@ -8,13 +8,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: "ipbase_info"
version_added: "7.0.0"
short_description: "Retrieve IP geolocation and other facts of a host's IP address using the ipbase.com API"
description:
- - "Retrieve IP geolocation and other facts of a host's IP address using the ipbase.com API"
+ - Retrieve IP geolocation and other facts of a host's IP address using the ipbase.com API.
author: "Dominik Kukacka (@dominikkukacka)"
extends_documentation_fragment:
- "community.general.attributes"
@@ -22,31 +21,31 @@ extends_documentation_fragment:
options:
ip:
description:
- - "The IP you want to get the info for. If not specified the API will detect the IP automatically."
+ - The IP you want to get the info for. If not specified the API will detect the IP automatically.
required: false
type: str
apikey:
description:
- - "The API key for the request if you need more requests."
+ - The API key for the request if you need more requests.
required: false
type: str
hostname:
description:
- - "If the O(hostname) parameter is set to V(true), the API response will contain the hostname of the IP."
+ - If the O(hostname) parameter is set to V(true), the API response will contain the hostname of the IP.
required: false
type: bool
default: false
language:
description:
- - "An ISO Alpha 2 Language Code for localizing the IP data"
+ - An ISO Alpha 2 Language Code for localizing the IP data.
required: false
type: str
default: "en"
notes:
- - "Check U(https://ipbase.com/) for more information."
-'''
+ - Check U(https://ipbase.com/) for more information.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: "Get IP geolocation information of the primary outgoing IP"
community.general.ipbase_info:
register: my_ip_info
@@ -64,12 +63,12 @@ EXAMPLES = '''
hostname: true
language: "de"
register: my_ip_info
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
data:
- description: "JSON parsed response from ipbase.com. Please refer to U(https://ipbase.com/docs/info) for the detailed structure of the response."
+ description: "JSON parsed response from ipbase.com. Please refer to U(https://ipbase.com/docs/info) for the detailed structure
+ of the response."
returned: success
type: dict
sample: {
@@ -213,7 +212,7 @@ data:
]
}
}
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/ipify_facts.py b/plugins/modules/ipify_facts.py
index ff17d7e543..7767c8d0ff 100644
--- a/plugins/modules/ipify_facts.py
+++ b/plugins/modules/ipify_facts.py
@@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ipify_facts
short_description: Retrieve the public IP of your internet gateway
description:
- If behind NAT and need to know the public IP of your internet gateway.
author:
-- René Moser (@resmo)
+ - René Moser (@resmo)
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.facts
@@ -40,9 +39,9 @@ options:
default: true
notes:
- Visit https://www.ipify.org to get more information.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
# Gather IP facts from ipify.org
- name: Get my public IP
community.general.ipify_facts:
@@ -52,16 +51,15 @@ EXAMPLES = r'''
community.general.ipify_facts:
api_url: http://api.example.com/ipify
timeout: 20
-'''
+"""
-RETURN = r'''
----
+RETURN = r"""
ipify_public_ip:
description: Public IP of the internet gateway.
returned: success
type: str
sample: 1.2.3.4
-'''
+"""
import json
diff --git a/plugins/modules/ipinfoio_facts.py b/plugins/modules/ipinfoio_facts.py
index f29b3cbf4c..5db21dc8f8 100644
--- a/plugins/modules/ipinfoio_facts.py
+++ b/plugins/modules/ipinfoio_facts.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ipinfoio_facts
short_description: Retrieve IP geolocation facts of a host's IP address
description:
- - "Gather IP geolocation facts of a host's IP address using ipinfo.io API"
+ - Gather IP geolocation facts of a host's IP address using ipinfo.io API.
author: "Aleksei Kostiuk (@akostyuk)"
extends_documentation_fragment:
- community.general.attributes
@@ -23,65 +22,65 @@ extends_documentation_fragment:
options:
timeout:
description:
- - HTTP connection timeout in seconds
+ - HTTP connection timeout in seconds.
required: false
default: 10
type: int
http_agent:
description:
- - Set http user agent
+ - Set http user agent.
required: false
default: "ansible-ipinfoio-module/0.0.1"
type: str
notes:
- - "Check http://ipinfo.io/ for more information"
-'''
+ - Check U(http://ipinfo.io/) for more information.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Retrieve geolocation data of a host's IP address
- name: Get IP geolocation data
community.general.ipinfoio_facts:
-'''
+"""
-RETURN = '''
+RETURN = r"""
ansible_facts:
- description: "Dictionary of ip geolocation facts for a host's IP address"
+ description: "Dictionary of IP geolocation facts for a host's IP address."
returned: changed
type: complex
contains:
ip:
- description: "Public IP address of a host"
+ description: "Public IP address of a host."
type: str
sample: "8.8.8.8"
hostname:
- description: Domain name
+ description: Domain name.
type: str
sample: "google-public-dns-a.google.com"
country:
- description: ISO 3166-1 alpha-2 country code
+ description: ISO 3166-1 alpha-2 country code.
type: str
sample: "US"
region:
- description: State or province name
+ description: State or province name.
type: str
sample: "California"
city:
- description: City name
+ description: City name.
type: str
sample: "Mountain View"
loc:
- description: Latitude and Longitude of the location
+ description: Latitude and Longitude of the location.
type: str
sample: "37.3860,-122.0838"
org:
- description: "organization's name"
+ description: "Organization's name."
type: str
sample: "AS3356 Level 3 Communications, Inc."
postal:
- description: Postal code
+ description: Postal code.
type: str
sample: "94035"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url
diff --git a/plugins/modules/ipmi_boot.py b/plugins/modules/ipmi_boot.py
index 9f0016560e..bd96b35a51 100644
--- a/plugins/modules/ipmi_boot.py
+++ b/plugins/modules/ipmi_boot.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ipmi_boot
short_description: Management of order of boot devices
description:
- - Use this module to manage order of boot devices
+ - Use this module to manage order of boot devices.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -25,7 +24,7 @@ attributes:
options:
name:
description:
- - Hostname or ip address of the BMC.
+ - Hostname or IP address of the BMC.
required: true
type: str
port:
@@ -51,15 +50,15 @@ options:
version_added: 4.1.0
bootdev:
description:
- - Set boot device to use on next reboot
- - "The choices for the device are:
- - network -- Request network boot
- - floppy -- Boot from floppy
- - hd -- Boot from hard drive
- - safe -- Boot from hard drive, requesting 'safe mode'
- - optical -- boot from CD/DVD/BD drive
- - setup -- Boot into setup utility
- - default -- remove any IPMI directed boot device request"
+ - Set boot device to use on next reboot.
+ - 'The choices for the device are:'
+ - V(network) -- Request network boot.
+ - V(floppy) -- Boot from floppy.
+ - V(hd) -- Boot from hard drive.
+ - V(safe) -- Boot from hard drive, requesting 'safe mode'.
+ - V(optical) -- boot from CD/DVD/BD drive.
+ - V(setup) -- Boot into setup utility.
+ - V(default) -- remove any IPMI directed boot device request.
required: true
choices:
- network
@@ -73,49 +72,46 @@ options:
state:
description:
- Whether to ensure that boot devices is desired.
- - "The choices for the state are:
- - present -- Request system turn on
- - absent -- Request system turn on"
+ - 'The choices for the state are: - present -- Request system turn on - absent -- Request system turn on.'
default: present
- choices: [ present, absent ]
+ choices: [present, absent]
type: str
persistent:
description:
- - If set, ask that system firmware uses this device beyond next boot.
- Be aware many systems do not honor this.
+ - If set, ask that system firmware uses this device beyond next boot. Be aware many systems do not honor this.
type: bool
default: false
uefiboot:
description:
- - If set, request UEFI boot explicitly.
- Strictly speaking, the spec suggests that if not set, the system should BIOS boot and offers no "don't care" option.
- In practice, this flag not being set does not preclude UEFI boot on any system I've encountered.
+ - If set, request UEFI boot explicitly. Strictly speaking, the spec suggests that if not set, the system should BIOS
+ boot and offers no "do not care" option. In practice, this flag not being set does not preclude UEFI boot on any system
+ I have encountered.
type: bool
default: false
requirements:
- pyghmi
author: "Bulat Gaifullin (@bgaifullin) "
-'''
+"""
-RETURN = '''
+RETURN = r"""
bootdev:
- description: The boot device name which will be used beyond next boot.
- returned: success
- type: str
- sample: default
+ description: The boot device name which will be used beyond next boot.
+ returned: success
+ type: str
+ sample: default
persistent:
- description: If True, system firmware will use this device beyond next boot.
- returned: success
- type: bool
- sample: false
+ description: If True, system firmware will use this device beyond next boot.
+ returned: success
+ type: bool
+ sample: false
uefimode:
- description: If True, system firmware will use UEFI boot explicitly beyond next boot.
- returned: success
- type: bool
- sample: false
-'''
+ description: If True, system firmware will use UEFI boot explicitly beyond next boot.
+ returned: success
+ type: bool
+ sample: false
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Ensure bootdevice is HD
community.general.ipmi_boot:
name: test.testdomain.com
@@ -131,7 +127,7 @@ EXAMPLES = '''
key: 1234567890AABBCCDEFF000000EEEE12
bootdev: network
state: absent
-'''
+"""
import traceback
import binascii
diff --git a/plugins/modules/ipmi_power.py b/plugins/modules/ipmi_power.py
index 587cee06f3..e230fe4060 100644
--- a/plugins/modules/ipmi_power.py
+++ b/plugins/modules/ipmi_power.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ipmi_power
short_description: Power management for machine
description:
- - Use this module for power management
+ - Use this module for power management.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -25,7 +24,7 @@ attributes:
options:
name:
description:
- - Hostname or ip address of the BMC.
+ - Hostname or IP address of the BMC.
required: true
type: str
port:
@@ -52,12 +51,12 @@ options:
state:
description:
- Whether to ensure that the machine in desired state.
- - "The choices for state are:
- - on -- Request system turn on
- - off -- Request system turn off without waiting for OS to shutdown
- - shutdown -- Have system request OS proper shutdown
- - reset -- Request system reset without waiting for OS
- - boot -- If system is off, then 'on', else 'reset'"
+ - 'The choices for state are:'
+ - V(on) -- Request system turn on.
+ - V(off) -- Request system turn off without waiting for OS to shutdown.
+ - V(shutdown) -- Have system request OS proper shutdown.
+ - V(reset) -- Request system reset without waiting for OS.
+ - V(boot) -- If system is off, then V(on), else V(reset).
- Either this option or O(machine) is required.
choices: ['on', 'off', shutdown, reset, boot]
type: str
@@ -68,8 +67,7 @@ options:
type: int
machine:
description:
- - Provide a list of the remote target address for the bridge IPMI request,
- and the power status.
+ - Provide a list of the remote target address for the bridge IPMI request, and the power status.
- Either this option or O(state) is required.
required: false
type: list
@@ -92,40 +90,31 @@ options:
requirements:
- pyghmi
author: "Bulat Gaifullin (@bgaifullin) "
-'''
+"""
-RETURN = '''
+RETURN = r"""
powerstate:
- description: The current power state of the machine.
- returned: success and O(machine) is not provided
- type: str
- sample: 'on'
+ description: The current power state of the machine.
+ returned: success and O(machine) is not provided
+ type: str
+ sample: 'on'
status:
- description: The current power state of the machine when the machine option is set.
- returned: success and O(machine) is provided
- type: list
- elements: dict
- version_added: 4.3.0
- contains:
- powerstate:
- description: The current power state of the machine specified by RV(status[].targetAddress).
- type: str
- targetAddress:
- description: The remote target address.
- type: int
- sample: [
- {
- "powerstate": "on",
- "targetAddress": 48,
- },
- {
- "powerstate": "on",
- "targetAddress": 50,
- },
- ]
-'''
+ description: The current power state of the machine when the machine option is set.
+ returned: success and O(machine) is provided
+ type: list
+ elements: dict
+ version_added: 4.3.0
+ contains:
+ powerstate:
+ description: The current power state of the machine specified by RV(status[].targetAddress).
+ type: str
+ targetAddress:
+ description: The remote target address.
+ type: int
+ sample: [{"powerstate": "on", "targetAddress": 48}, {"powerstate": "on", "targetAddress": 50}]
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Ensure machine is powered on
community.general.ipmi_power:
name: test.testdomain.com
@@ -153,7 +142,7 @@ EXAMPLES = '''
state: 'on'
- targetAddress: 50
state: 'off'
-'''
+"""
import traceback
import binascii
diff --git a/plugins/modules/iptables_state.py b/plugins/modules/iptables_state.py
index c97b5694c9..6f3fa19042 100644
--- a/plugins/modules/iptables_state.py
+++ b/plugins/modules/iptables_state.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: iptables_state
short_description: Save iptables state into a file or restore it from a file
version_added: '1.1.0'
@@ -19,26 +18,17 @@ extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.flow
description:
- - C(iptables) is used to set up, maintain, and inspect the tables of IP
- packet filter rules in the Linux kernel.
- - This module handles the saving and/or loading of rules. This is the same
- as the behaviour of the C(iptables-save) and C(iptables-restore) (or
- C(ip6tables-save) and C(ip6tables-restore) for IPv6) commands which this
- module uses internally.
- - Modifying the state of the firewall remotely may lead to loose access to
- the host in case of mistake in new ruleset. This module embeds a rollback
- feature to avoid this, by telling the host to restore previous rules if a
- cookie is still there after a given delay, and all this time telling the
- controller to try to remove this cookie on the host through a new
- connection.
+ - C(iptables) is used to set up, maintain, and inspect the tables of IP packet filter rules in the Linux kernel.
+ - This module handles the saving and/or loading of rules. This is the same as the behaviour of the C(iptables-save) and
+ C(iptables-restore) (or C(ip6tables-save) and C(ip6tables-restore) for IPv6) commands which this module uses internally.
+ - Modifying the state of the firewall remotely may lead to loose access to the host in case of mistake in new ruleset. This
+ module embeds a rollback feature to avoid this, by telling the host to restore previous rules if a cookie is still there
+ after a given delay, and all this time telling the controller to try to remove this cookie on the host through a new connection.
notes:
- - The rollback feature is not a module option and depends on task's
- attributes. To enable it, the module must be played asynchronously, i.e.
- by setting task attributes C(poll) to V(0), and C(async) to a value less
- or equal to C(ANSIBLE_TIMEOUT). If C(async) is greater, the rollback will
- still happen if it shall happen, but you will experience a connection
- timeout instead of more relevant info returned by the module after its
- failure.
+ - The rollback feature is not a module option and depends on task's attributes. To enable it, the module must be played
+ asynchronously, in other words by setting task attributes C(poll) to V(0), and C(async) to a value less or equal to C(ANSIBLE_TIMEOUT).
+ If C(async) is greater, the rollback will still happen if it shall happen, but you will experience a connection timeout
+ instead of more relevant info returned by the module after its failure.
attributes:
check_mode:
support: full
@@ -59,22 +49,18 @@ options:
description:
- Which version of the IP protocol this module should apply to.
type: str
- choices: [ ipv4, ipv6 ]
+ choices: [ipv4, ipv6]
default: ipv4
modprobe:
description:
- - Specify the path to the C(modprobe) program internally used by iptables
- related commands to load kernel modules.
- - By default, V(/proc/sys/kernel/modprobe) is inspected to determine the
- executable's path.
+ - Specify the path to the C(modprobe) program internally used by iptables related commands to load kernel modules.
+ - By default, V(/proc/sys/kernel/modprobe) is inspected to determine the executable's path.
type: path
noflush:
description:
- For O(state=restored), ignored otherwise.
- - If V(false), restoring iptables rules from a file flushes (deletes)
- all previous contents of the respective table(s). If V(true), the
- previous rules are left untouched (but policies are updated anyway,
- for all built-in chains).
+ - If V(false), restoring iptables rules from a file flushes (deletes) all previous contents of the respective table(s).
+ If V(true), the previous rules are left untouched (but policies are updated anyway, for all built-in chains).
type: bool
default: false
path:
@@ -85,29 +71,26 @@ options:
required: true
state:
description:
- - Whether the firewall state should be saved (into a file) or restored
- (from a file).
+ - Whether the firewall state should be saved (into a file) or restored (from a file).
type: str
- choices: [ saved, restored ]
+ choices: [saved, restored]
required: true
table:
description:
- - When O(state=restored), restore only the named table even if the input
- file contains other tables. Fail if the named table is not declared in
- the file.
- - When O(state=saved), restrict output to the specified table. If not
- specified, output includes all active tables.
+ - When O(state=restored), restore only the named table even if the input file contains other tables. Fail if the named
+ table is not declared in the file.
+ - When O(state=saved), restrict output to the specified table. If not specified, output includes all active tables.
type: str
- choices: [ filter, nat, mangle, raw, security ]
+ choices: [filter, nat, mangle, raw, security]
wait:
description:
- - Wait N seconds for the xtables lock to prevent instant failure in case
- multiple instances of the program are running concurrently.
+ - Wait N seconds for the xtables lock to prevent instant failure in case multiple instances of the program are running
+ concurrently.
type: int
requirements: [iptables, ip6tables]
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
# This will apply to all loaded/active IPv4 tables.
- name: Save current state of the firewall in system file
community.general.iptables_state:
@@ -151,9 +134,9 @@ EXAMPLES = r'''
- name: show current state of the firewall
ansible.builtin.debug:
var: iptables_state.initial_state
-'''
+"""
-RETURN = r'''
+RETURN = r"""
applied:
description: Whether or not the wanted state has been successfully restored.
type: bool
@@ -235,7 +218,7 @@ tables:
]
}
returned: always
-'''
+"""
import re
diff --git a/plugins/modules/ipwcli_dns.py b/plugins/modules/ipwcli_dns.py
index 3ffad79fb6..118f59e8d9 100644
--- a/plugins/modules/ipwcli_dns.py
+++ b/plugins/modules/ipwcli_dns.py
@@ -8,127 +8,124 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ipwcli_dns
-short_description: Manage DNS Records for Ericsson IPWorks via ipwcli
+short_description: Manage DNS Records for Ericsson IPWorks using C(ipwcli)
version_added: '0.2.0'
description:
- - "Manage DNS records for the Ericsson IPWorks DNS server. The module will use the ipwcli to deploy the DNS records."
-
+ - Manage DNS records for the Ericsson IPWorks DNS server. The module will use the C(ipwcli) to deploy the DNS records.
requirements:
- - ipwcli (installed on Ericsson IPWorks)
+ - ipwcli (installed on Ericsson IPWorks)
notes:
- - To make the DNS record changes effective, you need to run C(update dnsserver) on the ipwcli.
-
+ - To make the DNS record changes effective, you need to run C(update dnsserver) on the ipwcli.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- dnsname:
- description:
- - Name of the record.
- required: true
- type: str
- type:
- description:
- - Type of the record.
- required: true
- type: str
- choices: [ NAPTR, SRV, A, AAAA ]
- container:
- description:
- - Sets the container zone for the record.
- required: true
- type: str
- address:
- description:
- - The IP address for the A or AAAA record.
- - Required for O(type=A) or O(type=AAAA).
- type: str
- ttl:
- description:
- - Sets the TTL of the record.
- type: int
- default: 3600
- state:
- description:
- - Whether the record should exist or not.
- type: str
- choices: [ absent, present ]
- default: present
- priority:
- description:
- - Sets the priority of the SRV record.
- type: int
- default: 10
- weight:
- description:
- - Sets the weight of the SRV record.
- type: int
- default: 10
- port:
- description:
- - Sets the port of the SRV record.
- - Required for O(type=SRV).
- type: int
- target:
- description:
- - Sets the target of the SRV record.
- - Required for O(type=SRV).
- type: str
- order:
- description:
- - Sets the order of the NAPTR record.
- - Required for O(type=NAPTR).
- type: int
- preference:
- description:
- - Sets the preference of the NAPTR record.
- - Required for O(type=NAPTR).
- type: int
- flags:
- description:
- - Sets one of the possible flags of NAPTR record.
- - Required for O(type=NAPTR).
- type: str
- choices: ['S', 'A', 'U', 'P']
- service:
- description:
- - Sets the service of the NAPTR record.
- - Required for O(type=NAPTR).
- type: str
- replacement:
- description:
- - Sets the replacement of the NAPTR record.
- - Required for O(type=NAPTR).
- type: str
- username:
- description:
- - Username to login on ipwcli.
- type: str
- required: true
- password:
- description:
- - Password to login on ipwcli.
- type: str
- required: true
+ dnsname:
+ description:
+ - Name of the record.
+ required: true
+ type: str
+ type:
+ description:
+ - Type of the record.
+ required: true
+ type: str
+ choices: [NAPTR, SRV, A, AAAA]
+ container:
+ description:
+ - Sets the container zone for the record.
+ required: true
+ type: str
+ address:
+ description:
+ - The IP address for the A or AAAA record.
+ - Required for O(type=A) or O(type=AAAA).
+ type: str
+ ttl:
+ description:
+ - Sets the TTL of the record.
+ type: int
+ default: 3600
+ state:
+ description:
+ - Whether the record should exist or not.
+ type: str
+ choices: [absent, present]
+ default: present
+ priority:
+ description:
+ - Sets the priority of the SRV record.
+ type: int
+ default: 10
+ weight:
+ description:
+ - Sets the weight of the SRV record.
+ type: int
+ default: 10
+ port:
+ description:
+ - Sets the port of the SRV record.
+ - Required for O(type=SRV).
+ type: int
+ target:
+ description:
+ - Sets the target of the SRV record.
+ - Required for O(type=SRV).
+ type: str
+ order:
+ description:
+ - Sets the order of the NAPTR record.
+ - Required for O(type=NAPTR).
+ type: int
+ preference:
+ description:
+ - Sets the preference of the NAPTR record.
+ - Required for O(type=NAPTR).
+ type: int
+ flags:
+ description:
+ - Sets one of the possible flags of NAPTR record.
+ - Required for O(type=NAPTR).
+ type: str
+ choices: ['S', 'A', 'U', 'P']
+ service:
+ description:
+ - Sets the service of the NAPTR record.
+ - Required for O(type=NAPTR).
+ type: str
+ replacement:
+ description:
+ - Sets the replacement of the NAPTR record.
+ - Required for O(type=NAPTR).
+ type: str
+ username:
+ description:
+ - Username to login on ipwcli.
+ type: str
+ required: true
+ password:
+ description:
+ - Password to login on ipwcli.
+ type: str
+ required: true
author:
- - Christian Wollinger (@cwollinger)
-'''
+ - Christian Wollinger (@cwollinger)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create A record
community.general.ipwcli_dns:
dnsname: example.com
@@ -157,14 +154,14 @@ EXAMPLES = '''
service: 'SIP+D2T'
replacement: '_sip._tcp.test.example.com.'
flags: S
-'''
+"""
-RETURN = '''
+RETURN = r"""
record:
- description: The created record from the input params
- type: str
- returned: always
-'''
+ description: The created record from the input params.
+ type: str
+ returned: always
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/irc.py b/plugins/modules/irc.py
index 748479e87b..cbeb3fafa0 100644
--- a/plugins/modules/irc.py
+++ b/plugins/modules/irc.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: irc
short_description: Send a message to an IRC channel or a nick
description:
@@ -26,12 +25,12 @@ options:
server:
type: str
description:
- - IRC server name/address
+ - IRC server name/address.
default: localhost
port:
type: int
description:
- - IRC server port number
+ - IRC server port number.
default: 6667
nick:
type: str
@@ -46,45 +45,44 @@ options:
topic:
type: str
description:
- - Set the channel topic
+ - Set the channel topic.
color:
type: str
description:
- Text color for the message.
default: "none"
- choices: [ "none", "white", "black", "blue", "green", "red", "brown", "purple", "orange", "yellow", "light_green", "teal", "light_cyan",
- "light_blue", "pink", "gray", "light_gray"]
+ choices: ["none", "white", "black", "blue", "green", "red", "brown", "purple", "orange", "yellow", "light_green", "teal",
+ "light_cyan", "light_blue", "pink", "gray", "light_gray"]
aliases: [colour]
channel:
type: str
description:
- - Channel name. One of nick_to or channel needs to be set. When both are set, the message will be sent to both of them.
+ - Channel name. One of nick_to or channel needs to be set. When both are set, the message will be sent to both of them.
nick_to:
type: list
elements: str
description:
- - A list of nicknames to send the message to. One of nick_to or channel needs to be set. When both are defined, the message will be sent to both of them.
+ - A list of nicknames to send the message to. One of nick_to or channel needs to be set. When both are defined, the
+ message will be sent to both of them.
key:
type: str
description:
- - Channel key
+ - Channel key.
passwd:
type: str
description:
- - Server password
+ - Server password.
timeout:
type: int
description:
- - Timeout to use while waiting for successful registration and join
- messages, this is to prevent an endless loop
+ - Timeout to use while waiting for successful registration and join messages, this is to prevent an endless loop.
default: 30
use_tls:
description:
- - Designates whether TLS/SSL should be used when connecting to the IRC server
- - O(use_tls) is available since community.general 8.1.0, before the option
- was exlusively called O(use_ssl). The latter is now an alias of O(use_tls).
- - B(Note:) for security reasons, you should always set O(use_tls=true) and
- O(validate_certs=true) whenever possible.
+ - Designates whether TLS/SSL should be used when connecting to the IRC server.
+ - O(use_tls) is available since community.general 8.1.0, before the option was exlusively called O(use_ssl). The latter
+ is now an alias of O(use_tls).
+ - B(Note:) for security reasons, you should always set O(use_tls=true) and O(validate_certs=true) whenever possible.
- The default of this option changed to V(true) in community.general 10.0.0.
type: bool
default: true
@@ -92,36 +90,35 @@ options:
- use_ssl
part:
description:
- - Designates whether user should part from channel after sending message or not.
- Useful for when using a faux bot and not wanting join/parts between messages.
+ - Designates whether user should part from channel after sending message or not. Useful for when using a mock bot and
+ not wanting join/parts between messages.
type: bool
default: true
style:
type: str
description:
- - Text style for the message. Note italic does not work on some clients
- choices: [ "bold", "underline", "reverse", "italic", "none" ]
+ - Text style for the message. Note italic does not work on some clients.
+ choices: ["bold", "underline", "reverse", "italic", "none"]
default: none
validate_certs:
description:
- If set to V(false), the SSL certificates will not be validated.
- - This should always be set to V(true). Using V(false) is unsafe and should only be done
- if the network between between Ansible and the IRC server is known to be safe.
- - B(Note:) for security reasons, you should always set O(use_tls=true) and
- O(validate_certs=true) whenever possible.
+ - This should always be set to V(true). Using V(false) is unsafe and should only be done if the network between between
+ Ansible and the IRC server is known to be safe.
+ - B(Note:) for security reasons, you should always set O(use_tls=true) and O(validate_certs=true) whenever possible.
- The default of this option changed to V(true) in community.general 10.0.0.
type: bool
default: true
version_added: 8.1.0
# informational: requirements for nodes
-requirements: [ socket ]
+requirements: [socket]
author:
- - "Jan-Piet Mens (@jpmens)"
- - "Matt Martz (@sivel)"
-'''
+ - "Jan-Piet Mens (@jpmens)"
+ - "Matt Martz (@sivel)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Send a message to an IRC channel from nick ansible
community.general.irc:
server: irc.example.net
@@ -156,7 +153,7 @@ EXAMPLES = '''
msg: 'All finished at {{ ansible_date_time.iso8601 }}'
color: red
nick: ansibleIRC
-'''
+"""
# ===========================================
# IRC module support methods.
diff --git a/plugins/modules/iso_create.py b/plugins/modules/iso_create.py
index c39c710d53..008cb271bb 100644
--- a/plugins/modules/iso_create.py
+++ b/plugins/modules/iso_create.py
@@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: iso_create
short_description: Generate ISO file with specified files or folders
description:
@@ -31,60 +30,60 @@ attributes:
support: none
options:
- src_files:
- description:
- - This is a list of absolute paths of source files or folders which will be contained in the new generated ISO file.
- - Will fail if specified file or folder in O(src_files) does not exist on local machine.
- - 'Note: With all ISO9660 levels from 1 to 3, all file names are restricted to uppercase letters, numbers and
- underscores (_). File names are limited to 31 characters, directory nesting is limited to 8 levels, and path
- names are limited to 255 characters.'
- type: list
- required: true
- elements: path
- dest_iso:
- description:
- - The absolute path with file name of the new generated ISO file on local machine.
- - Will create intermediate folders when they does not exist.
- type: path
- required: true
- interchange_level:
- description:
- - The ISO9660 interchange level to use, it dictates the rules on the names of files.
- - Levels and valid values V(1), V(2), V(3), V(4) are supported.
- - The default value is level V(1), which is the most conservative, level V(3) is recommended.
- - ISO9660 file names at interchange level V(1) cannot have more than 8 characters or 3 characters in the extension.
- type: int
- default: 1
- choices: [1, 2, 3, 4]
- vol_ident:
- description:
- - The volume identification string to use on the new generated ISO image.
- type: str
- rock_ridge:
- description:
- - Whether to make this ISO have the Rock Ridge extensions or not.
- - Valid values are V(1.09), V(1.10) or V(1.12), means adding the specified Rock Ridge version to the ISO.
- - If unsure, set V(1.09) to ensure maximum compatibility.
- - If not specified, then not add Rock Ridge extension to the ISO.
- type: str
- choices: ['1.09', '1.10', '1.12']
- joliet:
- description:
- - Support levels and valid values are V(1), V(2), or V(3).
- - Level V(3) is by far the most common.
- - If not specified, then no Joliet support is added.
- type: int
- choices: [1, 2, 3]
- udf:
- description:
- - Whether to add UDF support to this ISO.
- - If set to V(true), then version 2.60 of the UDF spec is used.
- - If not specified or set to V(false), then no UDF support is added.
- type: bool
- default: false
-'''
+ src_files:
+ description:
+ - This is a list of absolute paths of source files or folders which will be contained in the new generated ISO file.
+ - Will fail if specified file or folder in O(src_files) does not exist on local machine.
+ - 'Note: With all ISO9660 levels from 1 to 3, all file names are restricted to uppercase letters, numbers and underscores
+ (_). File names are limited to 31 characters, directory nesting is limited to 8 levels, and path names are limited
+ to 255 characters.'
+ type: list
+ required: true
+ elements: path
+ dest_iso:
+ description:
+ - The absolute path with file name of the new generated ISO file on local machine.
+ - Will create intermediate folders when they does not exist.
+ type: path
+ required: true
+ interchange_level:
+ description:
+ - The ISO9660 interchange level to use, it dictates the rules on the names of files.
+ - Levels and valid values V(1), V(2), V(3), V(4) are supported.
+ - The default value is level V(1), which is the most conservative, level V(3) is recommended.
+ - ISO9660 file names at interchange level V(1) cannot have more than 8 characters or 3 characters in the extension.
+ type: int
+ default: 1
+ choices: [1, 2, 3, 4]
+ vol_ident:
+ description:
+ - The volume identification string to use on the new generated ISO image.
+ type: str
+ rock_ridge:
+ description:
+ - Whether to make this ISO have the Rock Ridge extensions or not.
+ - Valid values are V(1.09), V(1.10) or V(1.12), means adding the specified Rock Ridge version to the ISO.
+ - If unsure, set V(1.09) to ensure maximum compatibility.
+ - If not specified, then not add Rock Ridge extension to the ISO.
+ type: str
+ choices: ['1.09', '1.10', '1.12']
+ joliet:
+ description:
+ - Support levels and valid values are V(1), V(2), or V(3).
+ - Level V(3) is by far the most common.
+ - If not specified, then no Joliet support is added.
+ type: int
+ choices: [1, 2, 3]
+ udf:
+ description:
+ - Whether to add UDF support to this ISO.
+ - If set to V(true), then version 2.60 of the UDF spec is used.
+ - If not specified or set to V(false), then no UDF support is added.
+ type: bool
+ default: false
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create an ISO file
community.general.iso_create:
src_files:
@@ -109,46 +108,46 @@ EXAMPLES = r'''
interchange_level: 3
joliet: 3
vol_ident: WIN_AUTOINSTALL
-'''
+"""
-RETURN = r'''
+RETURN = r"""
source_file:
- description: Configured source files or directories list.
- returned: on success
- type: list
- elements: path
- sample: ["/path/to/file.txt", "/path/to/folder"]
+ description: Configured source files or directories list.
+ returned: on success
+ type: list
+ elements: path
+ sample: ["/path/to/file.txt", "/path/to/folder"]
created_iso:
- description: Created iso file path.
- returned: on success
- type: str
- sample: "/path/to/test.iso"
+ description: Created iso file path.
+ returned: on success
+ type: str
+ sample: "/path/to/test.iso"
interchange_level:
- description: Configured interchange level.
- returned: on success
- type: int
- sample: 3
+ description: Configured interchange level.
+ returned: on success
+ type: int
+ sample: 3
vol_ident:
- description: Configured volume identification string.
- returned: on success
- type: str
- sample: "OEMDRV"
+ description: Configured volume identification string.
+ returned: on success
+ type: str
+ sample: "OEMDRV"
joliet:
- description: Configured Joliet support level.
- returned: on success
- type: int
- sample: 3
+ description: Configured Joliet support level.
+ returned: on success
+ type: int
+ sample: 3
rock_ridge:
- description: Configured Rock Ridge version.
- returned: on success
- type: str
- sample: "1.09"
+ description: Configured Rock Ridge version.
+ returned: on success
+ type: str
+ sample: "1.09"
udf:
- description: Configured UDF support.
- returned: on success
- type: bool
- sample: false
-'''
+ description: Configured UDF support.
+ returned: on success
+ type: bool
+ sample: false
+"""
import os
import traceback
diff --git a/plugins/modules/iso_customize.py b/plugins/modules/iso_customize.py
index 543faaa5ef..feac8417b8 100644
--- a/plugins/modules/iso_customize.py
+++ b/plugins/modules/iso_customize.py
@@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: iso_customize
short_description: Add/remove/change files in ISO file
description:
@@ -34,25 +33,25 @@ attributes:
options:
src_iso:
description:
- - This is the path of source ISO file.
+ - This is the path of source ISO file.
type: path
required: true
dest_iso:
description:
- - The path of the customized ISO file.
+ - The path of the customized ISO file.
type: path
required: true
delete_files:
description:
- - Absolute paths for files inside the ISO file that should be removed.
+ - Absolute paths for files inside the ISO file that should be removed.
type: list
required: false
elements: str
default: []
add_files:
description:
- - Allows to add and replace files in the ISO file.
- - Will create intermediate folders inside the ISO file when they do not exist.
+ - Allows to add and replace files in the ISO file.
+ - Will create intermediate folders inside the ISO file when they do not exist.
type: list
required: false
elements: dict
@@ -60,23 +59,22 @@ options:
suboptions:
src_file:
description:
- - The path with file name on the machine the module is executed on.
+ - The path with file name on the machine the module is executed on.
type: path
required: true
dest_file:
description:
- - The absolute path of the file inside the ISO file.
+ - The absolute path of the file inside the ISO file.
type: str
required: true
notes:
-- The C(pycdlib) library states it supports Python 2.7 and 3.4+.
-- >
- The function C(add_file) in pycdlib will overwrite the existing file in ISO with type ISO9660 / Rock Ridge 1.12 / Joliet / UDF.
- But it will not overwrite the existing file in ISO with Rock Ridge 1.09 / 1.10.
- So we take workaround "delete the existing file and then add file for ISO with Rock Ridge".
-'''
+ - The C(pycdlib) library states it supports Python 2.7 and 3.4+.
+ - The function C(add_file) in pycdlib will overwrite the existing file in ISO with type ISO9660 / Rock Ridge 1.12 / Joliet
+ / UDF. But it will not overwrite the existing file in ISO with Rock Ridge 1.09 / 1.10. So we take workaround "delete the
+ existing file and then add file for ISO with Rock Ridge".
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: "Customize ISO file"
community.general.iso_customize:
src_iso: "/path/to/ubuntu-22.04-desktop-amd64.iso"
@@ -89,9 +87,9 @@ EXAMPLES = r'''
- src_file: "/path/to/ubuntu.seed"
dest_file: "/preseed/ubuntu.seed"
register: customize_iso_result
-'''
+"""
-RETURN = r'''
+RETURN = r"""
src_iso:
description: Path of source ISO file.
returned: on success
@@ -102,7 +100,7 @@ dest_iso:
returned: on success
type: str
sample: "/path/to/customized.iso"
-'''
+"""
import os
diff --git a/plugins/modules/iso_extract.py b/plugins/modules/iso_extract.py
index 087ef2843f..8cda967b64 100644
--- a/plugins/modules/iso_extract.py
+++ b/plugins/modules/iso_extract.py
@@ -11,8 +11,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
- Jeroen Hoekx (@jhoekx)
- Matt Robinson (@ribbons)
@@ -21,12 +20,10 @@ module: iso_extract
short_description: Extract files from an ISO image
description:
- This module has two possible ways of operation.
- - If 7zip is installed on the system, this module extracts files from an ISO
- into a temporary directory and copies files to a given destination,
- if needed.
- - If the user has mount-capabilities (CAP_SYS_ADMIN on Linux) this module
- mounts the ISO image to a temporary location, and copies files to a given
- destination, if needed.
+ - If 7zip is installed on the system, this module extracts files from an ISO into a temporary directory and copies files
+ to a given destination, if needed.
+ - If the user has mount-capabilities (CAP_SYS_ADMIN on Linux) this module mounts the ISO image to a temporary location,
+ and copies files to a given destination, if needed.
requirements:
- Either 7z (from C(7zip) or C(p7zip) package)
- Or mount capabilities (root-access, or CAP_SYS_ADMIN capability on Linux)
@@ -40,51 +37,59 @@ attributes:
options:
image:
description:
- - The ISO image to extract files from.
+ - The ISO image to extract files from.
type: path
required: true
- aliases: [ path, src ]
+ aliases: [path, src]
dest:
description:
- - The destination directory to extract files to.
+ - The destination directory to extract files to.
type: path
required: true
files:
description:
- - A list of files to extract from the image.
- - Extracting directories does not work.
+ - A list of files to extract from the image.
+ - Extracting directories does not work.
type: list
elements: str
required: true
force:
description:
- - If V(true), which will replace the remote file when contents are different than the source.
- - If V(false), the file will only be extracted and copied if the destination does not already exist.
+ - If V(true), which will replace the remote file when contents are different than the source.
+ - If V(false), the file will only be extracted and copied if the destination does not already exist.
type: bool
default: true
executable:
description:
- - The path to the C(7z) executable to use for extracting files from the ISO.
- - If not provided, it will assume the value V(7z).
+ - The path to the C(7z) executable to use for extracting files from the ISO.
+ - If not provided, it will assume the value V(7z).
type: path
+ password:
+ description:
+ - Password used to decrypt files from the ISO.
+ - Will only be used if 7z is used.
+ - The password is used as a command line argument to 7z. This is a B(potential security risk) that allows passwords
+ to be revealed if someone else can list running processes on the same machine in the right moment.
+ type: str
+ version_added: 10.1.0
notes:
-- Only the file checksum (content) is taken into account when extracting files
- from the ISO image. If O(force=false), only checks the presence of the file.
-'''
+ - Only the file checksum (content) is taken into account when extracting files from the ISO image. If O(force=false), only
+ checks the presence of the file.
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Extract kernel and ramdisk from a LiveCD
community.general.iso_extract:
image: /tmp/rear-test.iso
dest: /tmp/virt-rear/
files:
- - isolinux/kernel
- - isolinux/initrd.cgz
-'''
+ - isolinux/kernel
+ - isolinux/initrd.cgz
+"""
-RETURN = r'''
+RETURN = r"""
#
-'''
+"""
import os.path
import shutil
@@ -100,6 +105,7 @@ def main():
dest=dict(type='path', required=True),
files=dict(type='list', elements='str', required=True),
force=dict(type='bool', default=True),
+ password=dict(type='str', no_log=True),
executable=dict(type='path'), # No default on purpose
),
supports_check_mode=True,
@@ -108,6 +114,7 @@ def main():
dest = module.params['dest']
files = module.params['files']
force = module.params['force']
+ password = module.params['password']
executable = module.params['executable']
result = dict(
@@ -154,7 +161,10 @@ def main():
# Use 7zip when we have a binary, otherwise try to mount
if binary:
- cmd = [binary, 'x', image, '-o%s' % tmp_dir] + extract_files
+ cmd = [binary, 'x', image, '-o%s' % tmp_dir]
+ if password:
+ cmd += ["-p%s" % password]
+ cmd += extract_files
else:
cmd = [module.get_bin_path('mount'), '-o', 'loop,ro', image, tmp_dir]
diff --git a/plugins/modules/jabber.py b/plugins/modules/jabber.py
index 650b29957d..01a34ff9f5 100644
--- a/plugins/modules/jabber.py
+++ b/plugins/modules/jabber.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: jabber
short_description: Send a message to jabber user or chat room
description:
- - Send a message to jabber
+ - Send a message to jabber.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -26,17 +25,17 @@ options:
user:
type: str
description:
- - User as which to connect
+ - User as which to connect.
required: true
password:
type: str
description:
- - password for user to connect
+ - Password for user to connect.
required: true
to:
type: str
description:
- - user ID or name of the room, when using room use a slash to indicate your nick.
+ - User ID or name of the room, when using room use a slash to indicate your nick.
required: true
msg:
type: str
@@ -46,24 +45,22 @@ options:
host:
type: str
description:
- - host to connect, overrides user info
+ - Host to connect, overrides user info.
port:
type: int
description:
- - port to connect to, overrides default
+ - Port to connect to, overrides default.
default: 5222
encoding:
type: str
description:
- - message encoding
-
-# informational: requirements for nodes
+ - Message encoding.
requirements:
- - python xmpp (xmpppy)
+ - python xmpp (xmpppy)
author: "Brian Coca (@bcoca)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Send a message to a user
community.general.jabber:
user: mybot@example.net
@@ -86,7 +83,7 @@ EXAMPLES = '''
password: secret
to: mychaps@example.net
msg: Ansible task finished
-'''
+"""
import time
import traceback
diff --git a/plugins/modules/java_cert.py b/plugins/modules/java_cert.py
index e2d04b71e2..8746c2d617 100644
--- a/plugins/modules/java_cert.py
+++ b/plugins/modules/java_cert.py
@@ -8,14 +8,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: java_cert
short_description: Uses keytool to import/remove certificate to/from java keystore (cacerts)
description:
- - This is a wrapper module around keytool, which can be used to import certificates
- and optionally private keys to a given java keystore, or remove them from it.
+ - This is a wrapper module around keytool, which can be used to import certificates and optionally private keys to a given
+ java keystore, or remove them from it.
extends_documentation_fragment:
- community.general.attributes
- ansible.builtin.files
@@ -61,9 +60,8 @@ options:
pkcs12_path:
description:
- Local path to load PKCS12 keystore from.
- - Unlike O(cert_url), O(cert_path) and O(cert_content), the PKCS12 keystore embeds the private key matching
- the certificate, and is used to import both the certificate and its private key into the
- java keystore.
+ - Unlike O(cert_url), O(cert_path) and O(cert_content), the PKCS12 keystore embeds the private key matching the certificate,
+ and is used to import both the certificate and its private key into the java keystore.
- Exactly one of O(cert_url), O(cert_path), O(cert_content), or O(pkcs12_path) is required to load certificate.
type: path
pkcs12_password:
@@ -100,10 +98,10 @@ options:
state:
description:
- Defines action which can be either certificate import or removal.
- - When state is present, the certificate will always idempotently be inserted
- into the keystore, even if there already exists a cert alias that is different.
+ - When state is present, the certificate will always idempotently be inserted into the keystore, even if there already
+ exists a cert alias that is different.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
mode:
version_added: 8.5.0
@@ -125,10 +123,10 @@ options:
version_added: 8.5.0
requirements: [openssl, keytool]
author:
-- Adam Hamsik (@haad)
-'''
+ - Adam Hamsik (@haad)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Import SSL certificate from google.com to a given cacerts keystore
community.general.java_cert:
cert_url: google.com
@@ -196,9 +194,9 @@ EXAMPLES = r'''
keystore_pass: changeit
keystore_create: true
state: present
-'''
+"""
-RETURN = r'''
+RETURN = r"""
msg:
description: Output from stdout of keytool command after execution of given command.
returned: success
@@ -216,7 +214,7 @@ cmd:
returned: success
type: str
sample: "keytool -importcert -noprompt -keystore"
-'''
+"""
import os
import tempfile
@@ -280,7 +278,7 @@ def _get_first_certificate_from_x509_file(module, pem_certificate_file, pem_cert
(extract_rc, dummy, extract_stderr) = module.run_command(extract_cmd, check_rc=False)
if extract_rc != 0:
- # this time it's a real failure
+ # this time it is a real failure
module.fail_json(msg="Internal module failure, cannot extract certificate, error: %s" % extract_stderr,
rc=extract_rc, cmd=extract_cmd)
diff --git a/plugins/modules/java_keystore.py b/plugins/modules/java_keystore.py
index 0a8e3398d5..df7e71abbe 100644
--- a/plugins/modules/java_keystore.py
+++ b/plugins/modules/java_keystore.py
@@ -10,8 +10,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: java_keystore
short_description: Create a Java keystore in JKS format
description:
@@ -25,25 +24,22 @@ options:
name:
description:
- Name of the certificate in the keystore.
- - If the provided name does not exist in the keystore, the module
- will re-create the keystore. This behavior changed in community.general 3.0.0,
- before that the module would fail when the name did not match.
+ - If the provided name does not exist in the keystore, the module will re-create the keystore. This behavior changed
+ in community.general 3.0.0, before that the module would fail when the name did not match.
type: str
required: true
certificate:
description:
- Content of the certificate used to create the keystore.
- - If the fingerprint of the provided certificate does not match the
- fingerprint of the certificate bundled in the keystore, the keystore
- is regenerated with the provided certificate.
+ - If the fingerprint of the provided certificate does not match the fingerprint of the certificate bundled in the keystore,
+ the keystore is regenerated with the provided certificate.
- Exactly one of O(certificate) or O(certificate_path) is required.
type: str
certificate_path:
description:
- Location of the certificate used to create the keystore.
- - If the fingerprint of the provided certificate does not match the
- fingerprint of the certificate bundled in the keystore, the keystore
- is regenerated with the provided certificate.
+ - If the fingerprint of the provided certificate does not match the fingerprint of the certificate bundled in the keystore,
+ the keystore is regenerated with the provided certificate.
- Exactly one of O(certificate) or O(certificate_path) is required.
type: path
version_added: '3.0.0'
@@ -66,10 +62,8 @@ options:
password:
description:
- Password that should be used to secure the keystore.
- - If the provided password fails to unlock the keystore, the module
- will re-create the keystore with the new passphrase. This behavior
- changed in community.general 3.0.0, before that the module would fail
- when the password did not match.
+ - If the provided password fails to unlock the keystore, the module will re-create the keystore with the new passphrase.
+ This behavior changed in community.general 3.0.0, before that the module would fail when the password did not match.
type: str
required: true
dest:
@@ -106,16 +100,13 @@ options:
keystore_type:
description:
- Type of the Java keystore.
- - When this option is omitted and the keystore doesn't already exist, the
- behavior follows C(keytool)'s default store type which depends on
- Java version; V(pkcs12) since Java 9 and V(jks) prior (may also
- be V(pkcs12) if new default has been backported to this version).
- - When this option is omitted and the keystore already exists, the current
- type is left untouched, unless another option leads to overwrite the
- keystore (in that case, this option behaves like for keystore creation).
- - When O(keystore_type) is set, the keystore is created with this type if
- it does not already exist, or is overwritten to match the given type in
- case of mismatch.
+ - When this option is omitted and the keystore does not already exist, the behavior follows C(keytool)'s default store
+ type which depends on Java version; V(pkcs12) since Java 9 and V(jks) prior (may also be V(pkcs12) if new default
+ has been backported to this version).
+ - When this option is omitted and the keystore already exists, the current type is left untouched, unless another option
+ leads to overwrite the keystore (in that case, this option behaves like for keystore creation).
+ - When O(keystore_type) is set, the keystore is created with this type if it does not already exist, or is overwritten
+ to match the given type in case of mismatch.
type: str
choices:
- jks
@@ -135,16 +126,14 @@ seealso:
- module: community.crypto.openssl_pkcs12
- module: community.general.java_cert
notes:
- - O(certificate) and O(private_key) require that their contents are available
- on the controller (either inline in a playbook, or with the P(ansible.builtin.file#lookup) lookup),
- while O(certificate_path) and O(private_key_path) require that the files are
- available on the target host.
- - By design, any change of a value of options O(keystore_type), O(name) or
- O(password), as well as changes of key or certificate materials will cause
- the existing O(dest) to be overwritten.
-'''
+ - O(certificate) and O(private_key) require that their contents are available on the controller (either inline in a playbook,
+ or with the P(ansible.builtin.file#lookup) lookup), while O(certificate_path) and O(private_key_path) require that the
+ files are available on the target host.
+ - By design, any change of a value of options O(keystore_type), O(name) or O(password), as well as changes of key or certificate
+ materials will cause the existing O(dest) to be overwritten.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a keystore for the given certificate/private key pair (inline)
community.general.java_keystore:
name: example
@@ -174,9 +163,9 @@ EXAMPLES = '''
private_key_path: /etc/ssl/private/ssl-cert-snakeoil.key
password: changeit
dest: /etc/security/keystore.jks
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
description: Output from stdout of keytool/openssl command after execution of given command or an error.
returned: changed and failure
@@ -190,17 +179,17 @@ err:
sample: "Keystore password is too short - must be at least 6 characters\n"
rc:
- description: keytool/openssl command execution return value
+ description: Keytool/openssl command execution return value.
returned: changed and failure
type: int
sample: "0"
cmd:
- description: Executed command to get action done
+ description: Executed command to get action done.
returned: changed and failure
type: str
sample: "/usr/bin/openssl x509 -noout -in /tmp/user/1000/tmp8jd_lh23 -fingerprint -sha256"
-'''
+"""
import os
diff --git a/plugins/modules/jboss.py b/plugins/modules/jboss.py
index 3d07a38d63..2d4f4b9bad 100644
--- a/plugins/modules/jboss.py
+++ b/plugins/modules/jboss.py
@@ -9,7 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: jboss
short_description: Deploy applications to JBoss
description:
@@ -39,23 +39,23 @@ options:
- The location in the filesystem where the deployment scanner listens.
type: path
state:
- choices: [ present, absent ]
+ choices: [present, absent]
default: "present"
description:
- Whether the application should be deployed or undeployed.
type: str
notes:
- - The JBoss standalone deployment-scanner has to be enabled in standalone.xml
- - The module can wait until O(deployment) file is deployed/undeployed by deployment-scanner.
- Duration of waiting time depends on scan-interval parameter from standalone.xml.
- - Ensure no identically named application is deployed through the JBoss CLI
+ - The JBoss standalone deployment-scanner has to be enabled in C(standalone.xml).
+ - The module can wait until O(deployment) file is deployed/undeployed by deployment-scanner. Duration of waiting time depends
+ on scan-interval parameter from C(standalone.xml).
+ - Ensure no identically named application is deployed through the JBoss CLI.
seealso:
-- name: WildFly reference
- description: Complete reference of the WildFly documentation.
- link: https://docs.wildfly.org
+ - name: WildFly reference
+ description: Complete reference of the WildFly documentation.
+ link: https://docs.wildfly.org
author:
- Jeroen Hoekx (@jhoekx)
-'''
+"""
EXAMPLES = r"""
- name: Deploy a hello world application to the default deploy_path
diff --git a/plugins/modules/jenkins_build.py b/plugins/modules/jenkins_build.py
index 6d830849e7..cec8fcc490 100644
--- a/plugins/modules/jenkins_build.py
+++ b/plugins/modules/jenkins_build.py
@@ -8,13 +8,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: jenkins_build
short_description: Manage jenkins builds
version_added: 2.2.0
description:
- - Manage Jenkins builds with Jenkins REST API.
+ - Manage Jenkins builds with Jenkins REST API.
requirements:
- "python-jenkins >= 0.4.12"
author:
@@ -64,7 +63,7 @@ options:
type: str
user:
description:
- - User to authenticate with the Jenkins server.
+ - User to authenticate with the Jenkins server.
type: str
detach:
description:
@@ -79,9 +78,9 @@ options:
default: 10
type: int
version_added: 7.4.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a jenkins build using basic authentication
community.general.jenkins_build:
name: "test-check"
@@ -108,10 +107,9 @@ EXAMPLES = '''
user: Jenkins
token: abcdefghijklmnopqrstuvwxyz123456
url: http://localhost:8080
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
name:
description: Name of the jenkins job.
returned: success
@@ -128,7 +126,7 @@ user:
type: str
sample: admin
url:
- description: Url to connect to the Jenkins server.
+ description: URL to connect to the Jenkins server.
returned: success
type: str
sample: https://jenkins.mydomain.com
@@ -136,7 +134,7 @@ build_info:
description: Build info of the jenkins job.
returned: success
type: dict
-'''
+"""
import traceback
from time import sleep
diff --git a/plugins/modules/jenkins_build_info.py b/plugins/modules/jenkins_build_info.py
index eae6eb9374..f252eb504a 100644
--- a/plugins/modules/jenkins_build_info.py
+++ b/plugins/modules/jenkins_build_info.py
@@ -8,13 +8,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: jenkins_build_info
short_description: Get information about Jenkins builds
version_added: 7.4.0
description:
- - Get information about Jenkins builds with Jenkins REST API.
+ - Get information about Jenkins builds with Jenkins REST API.
requirements:
- "python-jenkins >= 0.4.12"
author:
@@ -48,11 +47,11 @@ options:
type: str
user:
description:
- - User to authenticate with the Jenkins server.
+ - User to authenticate with the Jenkins server.
type: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get information about a jenkins build using basic authentication
community.general.jenkins_build_info:
name: "test-check"
@@ -74,10 +73,9 @@ EXAMPLES = '''
user: Jenkins
token: abcdefghijklmnopqrstuvwxyz123456
url: http://localhost:8080
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
name:
description: Name of the jenkins job.
returned: success
@@ -102,7 +100,7 @@ build_info:
description: Build info of the jenkins job.
returned: success
type: dict
-'''
+"""
import traceback
diff --git a/plugins/modules/jenkins_job.py b/plugins/modules/jenkins_job.py
index e8301041f2..93d922ed22 100644
--- a/plugins/modules/jenkins_job.py
+++ b/plugins/modules/jenkins_job.py
@@ -8,12 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: jenkins_job
short_description: Manage jenkins jobs
description:
- - Manage Jenkins jobs by using Jenkins REST API.
+ - Manage Jenkins jobs by using Jenkins REST API.
requirements:
- "python-jenkins >= 0.4.12"
author: "Sergio Millan Rodriguez (@sermilrod)"
@@ -28,7 +27,7 @@ options:
config:
type: str
description:
- - config in XML format.
+ - Config in XML format.
- Required if job does not yet exist.
- Mutually exclusive with O(enabled).
- Considered if O(state=present).
@@ -71,20 +70,19 @@ options:
user:
type: str
description:
- - User to authenticate with the Jenkins server.
+ - User to authenticate with the Jenkins server.
required: false
validate_certs:
type: bool
default: true
description:
- - If set to V(false), the SSL certificates will not be validated.
- This should only set to V(false) used on personally controlled sites
- using self-signed certificates as it avoids verifying the source site.
+ - If set to V(false), the SSL certificates will not be validated. This should only set to V(false) used on personally
+ controlled sites using self-signed certificates as it avoids verifying the source site.
- The C(python-jenkins) library only handles this by using the environment variable E(PYTHONHTTPSVERIFY).
version_added: 2.3.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a jenkins job using basic authentication
community.general.jenkins_job:
config: "{{ lookup('file', 'templates/test.xml') }}"
@@ -132,10 +130,9 @@ EXAMPLES = '''
enabled: false
url: http://localhost:8080
user: admin
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
name:
description: Name of the jenkins job.
returned: success
@@ -157,11 +154,11 @@ user:
type: str
sample: admin
url:
- description: Url to connect to the Jenkins server.
+ description: URL to connect to the Jenkins server.
returned: success
type: str
sample: https://jenkins.mydomain.com
-'''
+"""
import os
import traceback
diff --git a/plugins/modules/jenkins_job_info.py b/plugins/modules/jenkins_job_info.py
index 40e1d7aea3..f406ec3b4b 100644
--- a/plugins/modules/jenkins_job_info.py
+++ b/plugins/modules/jenkins_job_info.py
@@ -9,8 +9,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: jenkins_job_info
short_description: Get information about Jenkins jobs
description:
@@ -51,18 +50,18 @@ options:
user:
type: str
description:
- - User to authenticate with the Jenkins server.
+ - User to authenticate with the Jenkins server.
validate_certs:
description:
- - If set to V(false), the SSL certificates will not be validated.
- - This should only set to V(false) used on personally controlled sites using self-signed certificates.
+ - If set to V(false), the SSL certificates will not be validated.
+ - This should only set to V(false) used on personally controlled sites using self-signed certificates.
default: true
type: bool
author:
- "Chris St. Pierre (@stpierre)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Get all Jenkins jobs anonymously
- community.general.jenkins_job_info:
user: admin
@@ -122,24 +121,23 @@ EXAMPLES = '''
token: 126df5c60d66c66e3b75b11104a16a8a
url: https://jenkins.example.com
register: my_jenkins_job_info
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
jobs:
- description: All jobs found matching the specified criteria
+ description: All jobs found matching the specified criteria.
returned: success
type: list
sample:
[
- {
- "name": "test-job",
- "fullname": "test-folder/test-job",
- "url": "http://localhost:8080/job/test-job/",
- "color": "blue"
- },
+ {
+ "name": "test-job",
+ "fullname": "test-folder/test-job",
+ "url": "http://localhost:8080/job/test-job/",
+ "color": "blue"
+ },
]
-'''
+"""
import ssl
import fnmatch
@@ -212,8 +210,8 @@ def get_jobs(module):
jobs = all_jobs
# python-jenkins includes the internal Jenkins class used for each job
# in its return value; we strip that out because the leading underscore
- # (and the fact that it's not documented in the python-jenkins docs)
- # indicates that it's not part of the dependable public interface.
+ # (and the fact that it is not documented in the python-jenkins docs)
+ # indicates that it is not part of the dependable public interface.
for job in jobs:
if "_class" in job:
del job["_class"]
diff --git a/plugins/modules/jenkins_node.py b/plugins/modules/jenkins_node.py
index 9406eab4c5..affd462659 100644
--- a/plugins/modules/jenkins_node.py
+++ b/plugins/modules/jenkins_node.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: jenkins_node
short_description: Manage Jenkins nodes
version_added: 10.0.0
@@ -25,8 +24,7 @@ attributes:
check_mode:
support: partial
details:
- - Check mode is unable to show configuration changes for a node that is not yet
- present.
+ - Check mode is unable to show configuration changes for a node that is not yet present.
diff_mode:
support: none
options:
@@ -50,8 +48,8 @@ options:
type: str
state:
description:
- - Specifies whether the Jenkins node should be V(present) (created), V(absent)
- (deleted), V(enabled) (online) or V(disabled) (offline).
+ - Specifies whether the Jenkins node should be V(present) (created), V(absent) (deleted), V(enabled) (online) or V(disabled)
+ (offline).
default: present
choices: ['enabled', 'disabled', 'present', 'absent']
type: str
@@ -66,18 +64,15 @@ options:
elements: str
offline_message:
description:
- - Specifies the offline reason message to be set when configuring the Jenkins node
- state.
- - If O(offline_message) is given and requested O(state) is not V(disabled), an
- error will be raised.
- - Internally O(offline_message) is set via the V(toggleOffline) API, so updating
- the message when the node is already offline (current state V(disabled)) is not
- possible. In this case, a warning will be issued.
+ - Specifies the offline reason message to be set when configuring the Jenkins node state.
+ - If O(offline_message) is given and requested O(state) is not V(disabled), an error will be raised.
+ - Internally O(offline_message) is set using the V(toggleOffline) API, so updating the message when the node is already
+ offline (current state V(disabled)) is not possible. In this case, a warning will be issued.
type: str
version_added: 10.0.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a Jenkins node using token authentication
community.general.jenkins_node:
url: http://localhost:8080
@@ -105,12 +100,11 @@ EXAMPLES = '''
community.general.jenkins_node:
name: my-node
state: disabled
- offline_message: >
+ offline_message: >-
This node is offline for some reason.
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
url:
description: URL used to connect to the Jenkins server.
returned: success
@@ -151,7 +145,7 @@ configured:
description: Whether or not the Jenkins node was configured by the task.
returned: success
type: bool
-'''
+"""
import sys
import traceback
diff --git a/plugins/modules/jenkins_plugin.py b/plugins/modules/jenkins_plugin.py
index 8834e0a2b2..73ff40c725 100644
--- a/plugins/modules/jenkins_plugin.py
+++ b/plugins/modules/jenkins_plugin.py
@@ -9,14 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: jenkins_plugin
author: Jiri Tyr (@jtyr)
short_description: Add or remove Jenkins plugin
description:
- Ansible module which helps to manage Jenkins plugins.
-
attributes:
check_mode:
support: full
@@ -53,8 +51,7 @@ options:
type: str
description:
- Desired plugin state.
- - If set to V(latest), the check for new version will be performed
- every time. This is suitable to keep the plugin up-to-date.
+ - If set to V(latest), the check for new version will be performed every time. This is suitable to keep the plugin up-to-date.
choices: [absent, present, pinned, unpinned, enabled, disabled, latest]
default: present
timeout:
@@ -65,12 +62,10 @@ options:
updates_expiration:
type: int
description:
- - Number of seconds after which a new copy of the C(update-center.json)
- file is downloaded. This is used to avoid the need to download the
- plugin to calculate its checksum when O(state=latest) is specified.
- - Set it to V(0) if no cache file should be used. In that case, the
- plugin file will always be downloaded to calculate its checksum when
- O(state=latest) is specified.
+ - Number of seconds after which a new copy of the C(update-center.json) file is downloaded. This is used to avoid the
+ need to download the plugin to calculate its checksum when O(state=latest) is specified.
+ - Set it to V(0) if no cache file should be used. In that case, the plugin file will always be downloaded to calculate
+ its checksum when O(state=latest) is specified.
default: 86400
updates_url:
type: list
@@ -83,7 +78,7 @@ options:
type: list
elements: str
description:
- - A list of URL segment(s) to retrieve the update center json file from.
+ - A list of URL segment(s) to retrieve the update center JSON file from.
default: ['update-center.json', 'updates/update-center.json']
version_added: 3.3.0
latest_plugins_url_segments:
@@ -109,12 +104,11 @@ options:
type: str
description:
- Plugin version number.
- - If this option is specified, all plugin dependencies must be installed
- manually.
- - It might take longer to verify that the correct version is installed.
- This is especially true if a specific version number is specified.
- - Quote the version to prevent the value to be interpreted as float. For
- example if V(1.20) would be unquoted, it would become V(1.2).
+ - If this option is specified, all plugin dependencies must be installed manually.
+ - It might take longer to verify that the correct version is installed. This is especially true if a specific version
+ number is specified.
+ - Quote the version to prevent the value to be interpreted as float. For example if V(1.20) would be unquoted, it would
+ become V(1.2).
with_dependencies:
description:
- Defines whether to install plugin dependencies.
@@ -123,24 +117,20 @@ options:
default: true
notes:
- - Plugin installation should be run under root or the same user which owns
- the plugin files on the disk. Only if the plugin is not installed yet and
- no version is specified, the API installation is performed which requires
- only the Web UI credentials.
- - It is necessary to notify the handler or call the M(ansible.builtin.service) module to
- restart the Jenkins service after a new plugin was installed.
- - Pinning works only if the plugin is installed and Jenkins service was
- successfully restarted after the plugin installation.
- - It is not possible to run the module remotely by changing the O(url)
- parameter to point to the Jenkins server. The module must be used on the
- host where Jenkins runs as it needs direct access to the plugin files.
+ - Plugin installation should be run under root or the same user which owns the plugin files on the disk. Only if the plugin
+ is not installed yet and no version is specified, the API installation is performed which requires only the Web UI credentials.
+ - It is necessary to notify the handler or call the M(ansible.builtin.service) module to restart the Jenkins service after
+ a new plugin was installed.
+ - Pinning works only if the plugin is installed and Jenkins service was successfully restarted after the plugin installation.
+ - It is not possible to run the module remotely by changing the O(url) parameter to point to the Jenkins server. The module
+ must be used on the host where Jenkins runs as it needs direct access to the plugin files.
extends_documentation_fragment:
- ansible.builtin.url
- ansible.builtin.files
- community.general.attributes
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install plugin
community.general.jenkins_plugin:
name: build-pipeline-plugin
@@ -281,8 +271,8 @@ EXAMPLES = '''
retries: 60
delay: 5
until: >
- 'status' in jenkins_service_status and
- jenkins_service_status['status'] == 200
+ 'status' in jenkins_service_status and
+ jenkins_service_status['status'] == 200
when: jenkins_restart_required
- name: Reset the fact
@@ -305,20 +295,20 @@ EXAMPLES = '''
when: >
'enabled' in item.value
with_dict: "{{ my_jenkins_plugins }}"
-'''
+"""
-RETURN = '''
+RETURN = r"""
plugin:
- description: plugin name
- returned: success
- type: str
- sample: build-pipeline-plugin
+ description: Plugin name.
+ returned: success
+ type: str
+ sample: build-pipeline-plugin
state:
- description: state of the target, after execution
- returned: success
- type: str
- sample: "present"
-'''
+ description: State of the target, after execution.
+ returned: success
+ type: str
+ sample: "present"
+"""
import hashlib
import io
diff --git a/plugins/modules/jenkins_script.py b/plugins/modules/jenkins_script.py
index 030c8e6fa3..bd30f9daa7 100644
--- a/plugins/modules/jenkins_script.py
+++ b/plugins/modules/jenkins_script.py
@@ -9,17 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
author: James Hogarth (@hogarthj)
module: jenkins_script
short_description: Executes a groovy script in the jenkins instance
description:
- - The C(jenkins_script) module takes a script plus a dict of values
- to use within the script and returns the result of the script being run.
-
+ - The C(jenkins_script) module takes a script plus a dict of values to use within the script and returns the result of the
+ script being run.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
@@ -31,20 +29,18 @@ options:
script:
type: str
description:
- - The groovy script to be executed.
- This gets passed as a string Template if args is defined.
+ - The groovy script to be executed. This gets passed as a string Template if args is defined.
required: true
url:
type: str
description:
- - The jenkins server to execute the script against. The default is a local
- jenkins instance that is not being proxied through a webserver.
+ - The jenkins server to execute the script against. The default is a local jenkins instance that is not being proxied
+ through a webserver.
default: http://localhost:8080
validate_certs:
description:
- - If set to V(false), the SSL certificates will not be validated.
- This should only set to V(false) used on personally controlled sites
- using self-signed certificates as it avoids verifying the source site.
+ - If set to V(false), the SSL certificates will not be validated. This should only set to V(false) used on personally
+ controlled sites using self-signed certificates as it avoids verifying the source site.
type: bool
default: true
user:
@@ -58,21 +54,18 @@ options:
timeout:
type: int
description:
- - The request timeout in seconds
+ - The request timeout in seconds.
default: 10
args:
type: dict
description:
- A dict of key-value pairs used in formatting the script using string.Template (see https://docs.python.org/2/library/string.html#template-strings).
-
notes:
- - Since the script can do anything this does not report on changes.
- Knowing the script is being run it's important to set changed_when
- for the ansible output to be clear on any alterations made.
+ - Since the script can do anything this does not report on changes. Knowing the script is being run it is important to set
+ C(changed_when) for the ansible output to be clear on any alterations made.
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Obtaining a list of plugins
community.general.jenkins_script:
script: 'println(Jenkins.instance.pluginManager.plugins)'
@@ -82,10 +75,10 @@ EXAMPLES = '''
- name: Setting master using a variable to hold a more complicate script
ansible.builtin.set_fact:
setmaster_mode: |
- import jenkins.model.*
- instance = Jenkins.getInstance()
- instance.setMode(${jenkins_mode})
- instance.save()
+ import jenkins.model.*
+ instance = Jenkins.getInstance()
+ instance.setMode(${jenkins_mode})
+ instance.save()
- name: Use the variable as the script
community.general.jenkins_script:
@@ -99,16 +92,16 @@ EXAMPLES = '''
user: admin
password: admin
url: https://localhost
- validate_certs: false # only do this when you trust the network!
-'''
+ validate_certs: false # only do this when you trust the network!
+"""
-RETURN = '''
+RETURN = r"""
output:
- description: Result of script
- returned: success
- type: str
- sample: 'Result: true'
-'''
+ description: Result of script.
+ returned: success
+ type: str
+ sample: 'Result: true'
+"""
import json
diff --git a/plugins/modules/jira.py b/plugins/modules/jira.py
index 64aed7e149..93d988e38b 100644
--- a/plugins/modules/jira.py
+++ b/plugins/modules/jira.py
@@ -20,7 +20,6 @@ module: jira
short_description: Create and modify issues in a JIRA instance
description:
- Create and modify issues in a JIRA instance.
-
extends_documentation_fragment:
- community.general.attributes
@@ -36,90 +35,96 @@ options:
required: true
description:
- Base URI for the JIRA instance.
-
operation:
type: str
required: true
- aliases: [ command ]
- choices: [ attach, comment, create, edit, fetch, link, search, transition, update, worklog ]
+ aliases: [command]
+ choices: [attach, comment, create, edit, fetch, link, search, transition, update, worklog]
description:
- The operation to perform.
- V(worklog) was added in community.general 6.5.0.
-
username:
type: str
description:
- The username to log-in with.
- Must be used with O(password). Mutually exclusive with O(token).
-
password:
type: str
description:
- The password to log-in with.
- - Must be used with O(username). Mutually exclusive with O(token).
-
+ - Must be used with O(username). Mutually exclusive with O(token).
token:
type: str
description:
- The personal access token to log-in with.
- Mutually exclusive with O(username) and O(password).
version_added: 4.2.0
+ client_cert:
+ type: path
+ description:
+ - Client certificate if required.
+ - In addition to O(username) and O(password) or O(token). Not mutually exclusive.
+ version_added: 10.4.0
+ client_key:
+ type: path
+ description:
+ - Client certificate key if required.
+ - In addition to O(username) and O(password) or O(token). Not mutually exclusive.
+ version_added: 10.4.0
project:
type: str
required: false
description:
- The project for this operation. Required for issue creation.
-
summary:
type: str
required: false
description:
- - The issue summary, where appropriate.
- - Note that JIRA may not allow changing field values on specific transitions or states.
-
+ - The issue summary, where appropriate.
+ - Note that JIRA may not allow changing field values on specific transitions or states.
description:
type: str
required: false
description:
- - The issue description, where appropriate.
- - Note that JIRA may not allow changing field values on specific transitions or states.
-
+ - The issue description, where appropriate.
+ - Note that JIRA may not allow changing field values on specific transitions or states.
issuetype:
type: str
required: false
description:
- - The issue type, for issue creation.
-
+ - The issue type, for issue creation.
issue:
type: str
required: false
description:
- - An existing issue key to operate on.
+ - An existing issue key to operate on.
aliases: ['ticket']
comment:
type: str
required: false
description:
- - The comment text to add.
- - Note that JIRA may not allow changing field values on specific transitions or states.
-
+ - The comment text to add.
+ - Note that JIRA may not allow changing field values on specific transitions or states.
comment_visibility:
type: dict
description:
- - Used to specify comment comment visibility.
- - See U(https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-comments/#api-rest-api-2-issue-issueidorkey-comment-post) for details.
+ - Used to specify comment comment visibility.
+ - See
+ U(https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-comments/#api-rest-api-2-issue-issueidorkey-comment-post)
+ for details.
suboptions:
type:
description:
- - Use type to specify which of the JIRA visibility restriction types will be used.
+ - Use type to specify which of the JIRA visibility restriction types will be used.
type: str
required: true
choices: [group, role]
value:
description:
- - Use value to specify value corresponding to the type of visibility restriction. For example name of the group or role.
+ - Use value to specify value corresponding to the type of visibility restriction. For example name of the group
+ or role.
type: str
required: true
version_added: '3.2.0'
@@ -128,63 +133,67 @@ options:
type: str
required: false
description:
- - Only used when O(operation) is V(transition), and a bit of a misnomer, it actually refers to the transition name.
-
+ - Only used when O(operation) is V(transition), and a bit of a misnomer, it actually refers to the transition name.
+ - This is mutually exclusive with O(status_id).
+ status_id:
+ type: str
+ required: false
+ description:
+ - Only used when O(operation) is V(transition), and refers to the transition ID.
+ - This is mutually exclusive with O(status).
+ version_added: 10.3.0
assignee:
type: str
required: false
description:
- - Sets the the assignee when O(operation) is V(create), V(transition), or V(edit).
- - Recent versions of JIRA no longer accept a user name as a user identifier. In that case, use O(account_id) instead.
- - Note that JIRA may not allow changing field values on specific transitions or states.
-
+ - Sets the the assignee when O(operation) is V(create), V(transition), or V(edit).
+ - Recent versions of JIRA no longer accept a user name as a user identifier. In that case, use O(account_id) instead.
+ - Note that JIRA may not allow changing field values on specific transitions or states.
account_id:
type: str
description:
- - Sets the account identifier for the assignee when O(operation) is V(create), V(transition), or V(edit).
- - Note that JIRA may not allow changing field values on specific transitions or states.
+ - Sets the account identifier for the assignee when O(operation) is V(create), V(transition), or V(edit).
+ - Note that JIRA may not allow changing field values on specific transitions or states.
version_added: 2.5.0
linktype:
type: str
required: false
description:
- - Set type of link, when action 'link' selected.
-
+ - Set type of link, when action 'link' selected.
inwardissue:
type: str
required: false
description:
- - Set issue from which link will be created.
-
+ - Set issue from which link will be created.
outwardissue:
type: str
required: false
description:
- - Set issue to which link will be created.
-
+ - Set issue to which link will be created.
fields:
type: dict
required: false
description:
- - This is a free-form data structure that can contain arbitrary data. This is passed directly to the JIRA REST API
- (possibly after merging with other required data, as when passed to create). See examples for more information,
- and the JIRA REST API for the structure required for various fields.
- - When passed to comment, the data structure is merged at the first level since community.general 4.6.0. Useful to add JIRA properties for example.
- - Note that JIRA may not allow changing field values on specific transitions or states.
+ - This is a free-form data structure that can contain arbitrary data. This is passed directly to the JIRA REST API (possibly
+ after merging with other required data, as when passed to create). See examples for more information, and the JIRA
+ REST API for the structure required for various fields.
+ - When passed to comment, the data structure is merged at the first level since community.general 4.6.0. Useful to add
+ JIRA properties for example.
+ - Note that JIRA may not allow changing field values on specific transitions or states.
default: {}
jql:
required: false
description:
- - Query JIRA in JQL Syntax, e.g. 'CMDB Hostname'='test.example.com'.
+ - Query JIRA in JQL Syntax, for example V("CMDB Hostname" = test.example.com).
type: str
version_added: '0.2.0'
maxresults:
required: false
description:
- - Limit the result of O(operation=search). If no value is specified, the default jira limit will be used.
- - Used when O(operation=search) only, ignored otherwise.
+ - Limit the result of O(operation=search). If no value is specified, the default jira limit will be used.
+ - Used when O(operation=search) only, ignored otherwise.
type: int
version_added: '0.2.0'
@@ -198,7 +207,7 @@ options:
validate_certs:
required: false
description:
- - Require valid SSL certificates (set to V(false) if you would like to use self-signed certificates)
+ - Require valid SSL certificates (set to V(false) if you would like to use self-signed certificates).
default: true
type: bool
@@ -212,27 +221,24 @@ options:
required: true
type: path
description:
- - The path to the file to upload (from the remote node) or, if O(attachment.content) is specified,
- the filename to use for the attachment.
+ - The path to the file to upload (from the remote node) or, if O(attachment.content) is specified, the filename
+ to use for the attachment.
content:
type: str
description:
- - The Base64 encoded contents of the file to attach. If not specified, the contents of O(attachment.filename) will be
- used instead.
+ - The Base64 encoded contents of the file to attach. If not specified, the contents of O(attachment.filename) will
+ be used instead.
mimetype:
type: str
description:
- - The MIME type to supply for the upload. If not specified, best-effort detection will be
- done.
-
+ - The MIME type to supply for the upload. If not specified, best-effort detection will be done.
notes:
- - "Currently this only works with basic-auth, or tokens."
- - "To use with JIRA Cloud, pass the login e-mail as the O(username) and the API token as O(password)."
-
+ - Currently this only works with basic-auth, or tokens.
+ - To use with JIRA Cloud, pass the login e-mail as the O(username) and the API token as O(password).
author:
-- "Steve Smith (@tarka)"
-- "Per Abildgaard Toft (@pertoft)"
-- "Brandon McNama (@DWSR)"
+ - "Steve Smith (@tarka)"
+ - "Per Abildgaard Toft (@pertoft)"
+ - "Brandon McNama (@DWSR)"
"""
EXAMPLES = r"""
@@ -249,8 +255,8 @@ EXAMPLES = r"""
issuetype: Task
args:
fields:
- customfield_13225: "test"
- customfield_12931: {"value": "Test"}
+ customfield_13225: "test"
+ customfield_12931: {"value": "Test"}
register: issue
- name: Comment on issue
@@ -362,9 +368,9 @@ EXAMPLES = r"""
operation: edit
args:
fields:
- labels:
- - autocreated
- - ansible
+ labels:
+ - autocreated
+ - ansible
# Updating a field using operations: add, set & remove
- name: Change the value of a Select dropdown
@@ -376,8 +382,8 @@ EXAMPLES = r"""
operation: update
args:
fields:
- customfield_12931: [ {'set': {'value': 'Virtual'}} ]
- customfield_13820: [ {'set': {'value':'Manually'}} ]
+ customfield_12931: ['set': {'value': 'Virtual'}]
+ customfield_13820: ['set': {'value': 'Manually'}]
register: cmdb_issue
delegate_to: localhost
@@ -406,7 +412,7 @@ EXAMPLES = r"""
jql: project=cmdb AND cf[13225]="test"
args:
fields:
- lastViewed: null
+ lastViewed:
register: issue
- name: Create a unix account for the reporter
@@ -452,6 +458,23 @@ EXAMPLES = r"""
operation: attach
attachment:
filename: topsecretreport.xlsx
+
+# Use username, password and client certificate authentification
+- name: Create an issue
+ community.general.jira:
+ uri: '{{ server }}'
+ username: '{{ user }}'
+ password: '{{ pass }}'
+ client_cert: '{{ path/to/client-cert }}'
+ client_key: '{{ path/to/client-key }}'
+
+# Use token and client certificate authentification
+- name: Create an issue
+ community.general.jira:
+ uri: '{{ server }}'
+ token: '{{ token }}'
+ client_cert: '{{ path/to/client-cert }}'
+ client_key: '{{ path/to/client-key }}'
"""
import base64
@@ -486,6 +509,8 @@ class JIRA(StateModuleHelper):
username=dict(type='str'),
password=dict(type='str', no_log=True),
token=dict(type='str', no_log=True),
+ client_cert=dict(type='path'),
+ client_key=dict(type='path'),
project=dict(type='str', ),
summary=dict(type='str', ),
description=dict(type='str', ),
@@ -497,6 +522,7 @@ class JIRA(StateModuleHelper):
value=dict(type='str', required=True)
)),
status=dict(type='str', ),
+ status_id=dict(type='str', ),
assignee=dict(type='str', ),
fields=dict(default={}, type='dict'),
linktype=dict(type='str', ),
@@ -512,9 +538,11 @@ class JIRA(StateModuleHelper):
['username', 'token'],
['password', 'token'],
['assignee', 'account_id'],
+ ['status', 'status_id']
],
required_together=[
['username', 'password'],
+ ['client_cert', 'client_key']
],
required_one_of=[
['username', 'token'],
@@ -525,7 +553,8 @@ class JIRA(StateModuleHelper):
('operation', 'comment', ['issue', 'comment']),
('operation', 'workflow', ['issue', 'comment']),
('operation', 'fetch', ['issue']),
- ('operation', 'transition', ['issue', 'status']),
+ ('operation', 'transition', ['issue']),
+ ('operation', 'transition', ['status', 'status_id'], True),
('operation', 'link', ['linktype', 'inwardissue', 'outwardissue']),
('operation', 'search', ['jql']),
),
@@ -630,14 +659,27 @@ class JIRA(StateModuleHelper):
turl = self.vars.restbase + '/issue/' + self.vars.issue + "/transitions"
tmeta = self.get(turl)
- target = self.vars.status
tid = None
+ target = None
+
+ if self.vars.status is not None:
+ target = self.vars.status.strip()
+ elif self.vars.status_id is not None:
+ tid = self.vars.status_id.strip()
+
for t in tmeta['transitions']:
- if t['name'] == target:
- tid = t['id']
- break
+ if target is not None:
+ if t['name'] == target:
+ tid = t['id']
+ break
+ else:
+ if tid == t['id']:
+ break
else:
- raise ValueError("Failed find valid transition for '%s'" % target)
+ if target is not None:
+ raise ValueError("Failed find valid transition for '%s'" % target)
+ else:
+ raise ValueError("Failed find valid transition for ID '%s'" % tid)
fields = dict(self.vars.fields)
if self.vars.summary is not None:
diff --git a/plugins/modules/kdeconfig.py b/plugins/modules/kdeconfig.py
index 96d7df8b8d..334db3aee4 100644
--- a/plugins/modules/kdeconfig.py
+++ b/plugins/modules/kdeconfig.py
@@ -7,15 +7,13 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: kdeconfig
short_description: Manage KDE configuration files
version_added: "6.5.0"
description:
- Add or change individual settings in KDE configuration files.
- It uses B(kwriteconfig) under the hood.
-
options:
path:
description:
@@ -24,8 +22,7 @@ options:
required: true
kwriteconfig_path:
description:
- - Path to the kwriteconfig executable. If not specified, Ansible will try
- to discover it.
+ - Path to the kwriteconfig executable. If not specified, Ansible will try to discover it.
type: path
values:
description:
@@ -74,9 +71,9 @@ requirements:
- kwriteconfig
author:
- Salvatore Mesoraca (@smeso)
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Ensure "Homepage=https://www.ansible.com/" in group "Branding"
community.general.kdeconfig:
path: /etc/xdg/kickoffrc
@@ -97,9 +94,9 @@ EXAMPLES = r'''
key: KEY
value: VALUE
backup: true
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
import os
import shutil
diff --git a/plugins/modules/kernel_blacklist.py b/plugins/modules/kernel_blacklist.py
index 224b5bba8c..1dbf94f629 100644
--- a/plugins/modules/kernel_blacklist.py
+++ b/plugins/modules/kernel_blacklist.py
@@ -9,47 +9,45 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: kernel_blacklist
author:
- - Matthias Vogelgesang (@matze)
+ - Matthias Vogelgesang (@matze)
short_description: Blacklist kernel modules
description:
- - Add or remove kernel modules from blacklist.
+ - Add or remove kernel modules from blacklist.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
options:
- name:
- type: str
- description:
- - Name of kernel module to black- or whitelist.
- required: true
- state:
- type: str
- description:
- - Whether the module should be present in the blacklist or absent.
- choices: [ absent, present ]
- default: present
- blacklist_file:
- type: str
- description:
- - If specified, use this blacklist file instead of
- C(/etc/modprobe.d/blacklist-ansible.conf).
- default: /etc/modprobe.d/blacklist-ansible.conf
-'''
+ name:
+ type: str
+ description:
+ - Name of kernel module to black- or whitelist.
+ required: true
+ state:
+ type: str
+ description:
+ - Whether the module should be present in the blacklist or absent.
+ choices: [absent, present]
+ default: present
+ blacklist_file:
+ type: str
+ description:
+ - If specified, use this blacklist file instead of C(/etc/modprobe.d/blacklist-ansible.conf).
+ default: /etc/modprobe.d/blacklist-ansible.conf
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Blacklist the nouveau driver module
community.general.kernel_blacklist:
name: nouveau
state: present
-'''
+"""
import os
import re
diff --git a/plugins/modules/keycloak_authentication.py b/plugins/modules/keycloak_authentication.py
index bc2898d9be..a117c730e6 100644
--- a/plugins/modules/keycloak_authentication.py
+++ b/plugins/modules/keycloak_authentication.py
@@ -7,109 +7,109 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_authentication
short_description: Configure authentication in Keycloak
description:
- - This module actually can only make a copy of an existing authentication flow, add an execution to it and configure it.
- - It can also delete the flow.
-
+ - This module actually can only make a copy of an existing authentication flow, add an execution to it and configure it.
+ - It can also delete the flow.
version_added: "3.3.0"
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- realm:
- description:
- - The name of the realm in which is the authentication.
- required: true
- type: str
- alias:
- description:
- - Alias for the authentication flow.
- required: true
- type: str
+ realm:
description:
+ - The name of the realm in which is the authentication.
+ required: true
+ type: str
+ alias:
+ description:
+ - Alias for the authentication flow.
+ required: true
+ type: str
+ description:
+ description:
+ - Description of the flow.
+ type: str
+ providerId:
+ description:
+ - C(providerId) for the new flow when not copied from an existing flow.
+ choices: ["basic-flow", "client-flow"]
+ type: str
+ copyFrom:
+ description:
+ - C(flowAlias) of the authentication flow to use for the copy.
+ type: str
+ authenticationExecutions:
+ description:
+ - Configuration structure for the executions.
+ type: list
+ elements: dict
+ suboptions:
+ providerId:
description:
- - Description of the flow.
+ - C(providerID) for the new flow when not copied from an existing flow.
type: str
- providerId:
+ displayName:
description:
- - C(providerId) for the new flow when not copied from an existing flow.
- choices: [ "basic-flow", "client-flow" ]
+ - Name of the execution or subflow to create or update.
type: str
- copyFrom:
+ requirement:
description:
- - C(flowAlias) of the authentication flow to use for the copy.
+ - Control status of the subflow or execution.
+ choices: ["REQUIRED", "ALTERNATIVE", "DISABLED", "CONDITIONAL"]
type: str
- authenticationExecutions:
+ flowAlias:
description:
- - Configuration structure for the executions.
- type: list
- elements: dict
- suboptions:
- providerId:
- description:
- - C(providerID) for the new flow when not copied from an existing flow.
- type: str
- displayName:
- description:
- - Name of the execution or subflow to create or update.
- type: str
- requirement:
- description:
- - Control status of the subflow or execution.
- choices: [ "REQUIRED", "ALTERNATIVE", "DISABLED", "CONDITIONAL" ]
- type: str
- flowAlias:
- description:
- - Alias of parent flow.
- type: str
- authenticationConfig:
- description:
- - Describe the config of the authentication.
- type: dict
- index:
- description:
- - Priority order of the execution.
- type: int
- subFlowType:
- description:
- - For new subflows, optionally specify the type.
- - Is only used at creation.
- choices: ["basic-flow", "form-flow"]
- default: "basic-flow"
- type: str
- version_added: 6.6.0
- state:
- description:
- - Control if the authentication flow must exists or not.
- choices: [ "present", "absent" ]
- default: present
+ - Alias of parent flow.
type: str
- force:
- type: bool
- default: false
+ authenticationConfig:
description:
- - If V(true), allows to remove the authentication flow and recreate it.
-
+ - Describe the config of the authentication.
+ type: dict
+ index:
+ description:
+ - Priority order of the execution.
+ type: int
+ subFlowType:
+ description:
+ - For new subflows, optionally specify the type.
+ - Is only used at creation.
+ choices: ["basic-flow", "form-flow"]
+ default: "basic-flow"
+ type: str
+ version_added: 6.6.0
+ state:
+ description:
+ - Control if the authentication flow must exists or not.
+ choices: ["present", "absent"]
+ default: present
+ type: str
+ force:
+ type: bool
+ default: false
+ description:
+ - If V(true), allows to remove the authentication flow and recreate it.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Philippe Gauthier (@elfelip)
- - Gaëtan Daubresse (@Gaetan2907)
-'''
+ - Philippe Gauthier (@elfelip)
+ - Gaëtan Daubresse (@Gaetan2907)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create an authentication flow from first broker login and add an execution to it.
community.general.keycloak_authentication:
auth_keycloak_url: http://localhost:8080/auth
@@ -123,15 +123,15 @@ EXAMPLES = '''
- providerId: "test-execution1"
requirement: "REQUIRED"
authenticationConfig:
- alias: "test.execution1.property"
- config:
- test1.property: "value"
+ alias: "test.execution1.property"
+ config:
+ test1.property: "value"
- providerId: "test-execution2"
requirement: "REQUIRED"
authenticationConfig:
- alias: "test.execution2.property"
- config:
- test2.property: "value"
+ alias: "test.execution2.property"
+ config:
+ test2.property: "value"
state: present
- name: Re-create the authentication flow
@@ -147,9 +147,9 @@ EXAMPLES = '''
- providerId: "test-provisioning"
requirement: "REQUIRED"
authenticationConfig:
- alias: "test.provisioning.property"
- config:
- test.provisioning.property: "value"
+ alias: "test.provisioning.property"
+ config:
+ test.provisioning.property: "value"
state: present
force: true
@@ -181,13 +181,13 @@ EXAMPLES = '''
realm: master
alias: "Copy of first broker login"
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
end_state:
description: Representation of the authentication after module execution.
@@ -219,7 +219,7 @@ end_state:
"providerId": "basic-flow",
"topLevel": true
}
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak \
import KeycloakAPI, keycloak_argument_spec, get_token, KeycloakError, is_struct_included
@@ -246,7 +246,7 @@ def create_or_update_executions(kc, config, realm='master'):
"""
Create or update executions for an authentication flow.
:param kc: Keycloak API access.
- :param config: Representation of the authentication flow including it's executions.
+ :param config: Representation of the authentication flow including its executions.
:param realm: Realm
:return: tuple (changed, dict(before, after)
WHERE
@@ -257,6 +257,7 @@ def create_or_update_executions(kc, config, realm='master'):
changed = False
after = ""
before = ""
+ execution = None
if "authenticationExecutions" in config:
# Get existing executions on the Keycloak server for this alias
existing_executions = kc.get_executions_representation(config, realm=realm)
@@ -283,27 +284,27 @@ def create_or_update_executions(kc, config, realm='master'):
if new_exec['index'] is None:
new_exec_index = exec_index
before += str(existing_executions[exec_index]) + '\n'
- id_to_update = existing_executions[exec_index]["id"]
+ execution = existing_executions[exec_index].copy()
# Remove exec from list in case 2 exec with same name
existing_executions[exec_index].clear()
elif new_exec["providerId"] is not None:
kc.create_execution(new_exec, flowAlias=flow_alias_parent, realm=realm)
+ execution = kc.get_executions_representation(config, realm=realm)[exec_index]
exec_found = True
exec_index = new_exec_index
- id_to_update = kc.get_executions_representation(config, realm=realm)[exec_index]["id"]
after += str(new_exec) + '\n'
elif new_exec["displayName"] is not None:
kc.create_subflow(new_exec["displayName"], flow_alias_parent, realm=realm, flowType=new_exec["subFlowType"])
+ execution = kc.get_executions_representation(config, realm=realm)[exec_index]
exec_found = True
exec_index = new_exec_index
- id_to_update = kc.get_executions_representation(config, realm=realm)[exec_index]["id"]
after += str(new_exec) + '\n'
if exec_found:
changed = True
if exec_index != -1:
# Update the existing execution
updated_exec = {
- "id": id_to_update
+ "id": execution["id"]
}
# add the execution configuration
if new_exec["authenticationConfig"] is not None:
@@ -313,6 +314,8 @@ def create_or_update_executions(kc, config, realm='master'):
if key not in ("flowAlias", "authenticationConfig", "subFlowType"):
updated_exec[key] = new_exec[key]
if new_exec["requirement"] is not None:
+ if "priority" in execution:
+ updated_exec["priority"] = execution["priority"]
kc.update_authentication_executions(flow_alias_parent, updated_exec, realm=realm)
diff = exec_index - new_exec_index
kc.change_execution_priority(updated_exec["id"], diff, realm=realm)
@@ -356,7 +359,8 @@ def main():
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']])
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
)
result = dict(changed=False, msg='', flow={})
diff --git a/plugins/modules/keycloak_authentication_required_actions.py b/plugins/modules/keycloak_authentication_required_actions.py
index 5ffbd2033c..147acf9a1e 100644
--- a/plugins/modules/keycloak_authentication_required_actions.py
+++ b/plugins/modules/keycloak_authentication_required_actions.py
@@ -9,81 +9,82 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_authentication_required_actions
short_description: Allows administration of Keycloak authentication required actions
description:
- - This module can register, update and delete required actions.
- - It also filters out any duplicate required actions by their alias. The first occurrence is preserved.
-
+ - This module can register, update and delete required actions.
+ - It also filters out any duplicate required actions by their alias. The first occurrence is preserved.
version_added: 7.1.0
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- realm:
+ realm:
+ description:
+ - The name of the realm in which are the authentication required actions.
+ required: true
+ type: str
+ required_actions:
+ elements: dict
+ description:
+ - Authentication required action.
+ suboptions:
+ alias:
description:
- - The name of the realm in which are the authentication required actions.
+ - Unique name of the required action.
required: true
type: str
- required_actions:
- elements: dict
+ config:
description:
- - Authentication required action.
- suboptions:
- alias:
- description:
- - Unique name of the required action.
- required: true
- type: str
- config:
- description:
- - Configuration for the required action.
- type: dict
- defaultAction:
- description:
- - Indicates, if any new user will have the required action assigned to it.
- type: bool
- enabled:
- description:
- - Indicates, if the required action is enabled or not.
- type: bool
- name:
- description:
- - Displayed name of the required action. Required for registration.
- type: str
- priority:
- description:
- - Priority of the required action.
- type: int
- providerId:
- description:
- - Provider ID of the required action. Required for registration.
- type: str
- type: list
- state:
- choices: [ "absent", "present" ]
+ - Configuration for the required action.
+ type: dict
+ defaultAction:
description:
- - Control if the realm authentication required actions are going to be registered/updated (V(present)) or deleted (V(absent)).
- required: true
+ - Indicates, if any new user will have the required action assigned to it.
+ type: bool
+ enabled:
+ description:
+ - Indicates, if the required action is enabled or not.
+ type: bool
+ name:
+ description:
+ - Displayed name of the required action. Required for registration.
type: str
+ priority:
+ description:
+ - Priority of the required action.
+ type: int
+ providerId:
+ description:
+ - Provider ID of the required action. Required for registration.
+ type: str
+ type: list
+ state:
+ choices: ["absent", "present"]
+ description:
+ - Control if the realm authentication required actions are going to be registered/updated (V(present)) or deleted (V(absent)).
+ required: true
+ type: str
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Skrekulko (@Skrekulko)
-'''
+ - Skrekulko (@Skrekulko)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Register a new required action.
community.general.keycloak_authentication_required_actions:
auth_client_id: "admin-cli"
@@ -123,56 +124,55 @@ EXAMPLES = '''
required_action:
- alias: "TERMS_AND_CONDITIONS"
state: "absent"
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
end_state:
- description: Representation of the authentication required actions after module execution.
- returned: on success
- type: complex
- contains:
- alias:
- description:
- - Unique name of the required action.
- sample: test-provider-id
- type: str
- config:
- description:
- - Configuration for the required action.
- sample: {}
- type: dict
- defaultAction:
- description:
- - Indicates, if any new user will have the required action assigned to it.
- sample: false
- type: bool
- enabled:
- description:
- - Indicates, if the required action is enabled or not.
- sample: false
- type: bool
- name:
- description:
- - Displayed name of the required action. Required for registration.
- sample: Test provider ID
- type: str
- priority:
- description:
- - Priority of the required action.
- sample: 90
- type: int
- providerId:
- description:
- - Provider ID of the required action. Required for registration.
- sample: test-provider-id
- type: str
-
-'''
+ description: Representation of the authentication required actions after module execution.
+ returned: on success
+ type: complex
+ contains:
+ alias:
+ description:
+ - Unique name of the required action.
+ sample: test-provider-id
+ type: str
+ config:
+ description:
+ - Configuration for the required action.
+ sample: {}
+ type: dict
+ defaultAction:
+ description:
+ - Indicates, if any new user will have the required action assigned to it.
+ sample: false
+ type: bool
+ enabled:
+ description:
+ - Indicates, if the required action is enabled or not.
+ sample: false
+ type: bool
+ name:
+ description:
+ - Displayed name of the required action. Required for registration.
+ sample: Test provider ID
+ type: str
+ priority:
+ description:
+ - Priority of the required action.
+ sample: 90
+ type: int
+ providerId:
+ description:
+ - Provider ID of the required action. Required for registration.
+ sample: test-provider-id
+ type: str
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, \
keycloak_argument_spec, get_token, KeycloakError
@@ -238,7 +238,8 @@ def main():
argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']])
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
)
result = dict(changed=False, msg='', end_state={}, diff=dict(before={}, after={}))
diff --git a/plugins/modules/keycloak_authz_authorization_scope.py b/plugins/modules/keycloak_authz_authorization_scope.py
index 5eef9ac765..6b2e3c30f6 100644
--- a/plugins/modules/keycloak_authz_authorization_scope.py
+++ b/plugins/modules/keycloak_authz_authorization_scope.py
@@ -9,78 +9,76 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_authz_authorization_scope
-short_description: Allows administration of Keycloak client authorization scopes via Keycloak API
+short_description: Allows administration of Keycloak client authorization scopes using Keycloak API
version_added: 6.6.0
description:
- - This module allows the administration of Keycloak client Authorization Scopes via the Keycloak REST
- API. Authorization Scopes are only available if a client has Authorization enabled.
-
- - This module requires access to the REST API via OpenID Connect; the user connecting and the realm
- being used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate realm definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase options used by Keycloak.
- The Authorization Services paths and payloads have not officially been documented by the Keycloak project.
- U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/)
-
+ - This module allows the administration of Keycloak client Authorization Scopes using the Keycloak REST API. Authorization
+ Scopes are only available if a client has Authorization enabled.
+ - This module requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have
+ the requisite access rights. In a default Keycloak installation, admin-cli and an admin user would work, as would a separate
+ realm definition with the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase options used by Keycloak. The Authorization Services
+ paths and payloads have not officially been documented by the Keycloak project.
+ U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/).
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the authorization scope.
- - On V(present), the authorization scope will be created (or updated if it exists already).
- - On V(absent), the authorization scope will be removed if it exists.
- choices: ['present', 'absent']
- default: 'present'
- type: str
- name:
- description:
- - Name of the authorization scope to create.
- type: str
- required: true
- display_name:
- description:
- - The display name of the authorization scope.
- type: str
- required: false
- icon_uri:
- description:
- - The icon URI for the authorization scope.
- type: str
- required: false
- client_id:
- description:
- - The C(clientId) of the Keycloak client that should have the authorization scope.
- - This is usually a human-readable name of the Keycloak client.
- type: str
- required: true
- realm:
- description:
- - The name of the Keycloak realm the Keycloak client is in.
- type: str
- required: true
+ state:
+ description:
+ - State of the authorization scope.
+ - On V(present), the authorization scope will be created (or updated if it exists already).
+ - On V(absent), the authorization scope will be removed if it exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+ name:
+ description:
+ - Name of the authorization scope to create.
+ type: str
+ required: true
+ display_name:
+ description:
+ - The display name of the authorization scope.
+ type: str
+ required: false
+ icon_uri:
+ description:
+ - The icon URI for the authorization scope.
+ type: str
+ required: false
+ client_id:
+ description:
+ - The C(clientId) of the Keycloak client that should have the authorization scope.
+ - This is usually a human-readable name of the Keycloak client.
+ type: str
+ required: true
+ realm:
+ description:
+ - The name of the Keycloak realm the Keycloak client is in.
+ type: str
+ required: true
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Samuli Seppänen (@mattock)
-'''
+ - Samuli Seppänen (@mattock)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Manage Keycloak file:delete authorization scope
keycloak_authz_authorization_scope:
name: file:delete
@@ -92,41 +90,40 @@ EXAMPLES = '''
auth_username: keycloak
auth_password: keycloak
auth_realm: master
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
end_state:
- description: Representation of the authorization scope after module execution.
- returned: on success
- type: complex
- contains:
- id:
- description: ID of the authorization scope.
- type: str
- returned: when O(state=present)
- sample: a6ab1cf2-1001-40ec-9f39-48f23b6a0a41
- name:
- description: Name of the authorization scope.
- type: str
- returned: when O(state=present)
- sample: file:delete
- display_name:
- description: Display name of the authorization scope.
- type: str
- returned: when O(state=present)
- sample: File delete
- icon_uri:
- description: Icon URI for the authorization scope.
- type: str
- returned: when O(state=present)
- sample: http://localhost/icon.png
-
-'''
+ description: Representation of the authorization scope after module execution.
+ returned: on success
+ type: complex
+ contains:
+ id:
+ description: ID of the authorization scope.
+ type: str
+ returned: when O(state=present)
+ sample: a6ab1cf2-1001-40ec-9f39-48f23b6a0a41
+ name:
+ description: Name of the authorization scope.
+ type: str
+ returned: when O(state=present)
+ sample: file:delete
+ display_name:
+ description: Display name of the authorization scope.
+ type: str
+ returned: when O(state=present)
+ sample: File delete
+ icon_uri:
+ description: Icon URI for the authorization scope.
+ type: str
+ returned: when O(state=present)
+ sample: http://localhost/icon.png
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, \
keycloak_argument_spec, get_token, KeycloakError
@@ -157,7 +154,9 @@ def main():
supports_check_mode=True,
required_one_of=(
[['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', end_state={}, diff=dict(before={}, after={}))
diff --git a/plugins/modules/keycloak_authz_custom_policy.py b/plugins/modules/keycloak_authz_custom_policy.py
index 8363c252e2..5e1a2a6a2d 100644
--- a/plugins/modules/keycloak_authz_custom_policy.py
+++ b/plugins/modules/keycloak_authz_custom_policy.py
@@ -9,75 +9,73 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_authz_custom_policy
-short_description: Allows administration of Keycloak client custom Javascript policies via Keycloak API
+short_description: Allows administration of Keycloak client custom Javascript policies using Keycloak API
version_added: 7.5.0
description:
- - This module allows the administration of Keycloak client custom Javascript via the Keycloak REST
- API. Custom Javascript policies are only available if a client has Authorization enabled and if
- they have been deployed to the Keycloak server as JAR files.
-
- - This module requires access to the REST API via OpenID Connect; the user connecting and the realm
- being used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate realm definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase options used by Keycloak.
- The Authorization Services paths and payloads have not officially been documented by the Keycloak project.
- U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/)
-
+ - This module allows the administration of Keycloak client custom Javascript using the Keycloak REST API. Custom Javascript
+ policies are only available if a client has Authorization enabled and if they have been deployed to the Keycloak server
+ as JAR files.
+ - This module requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have
+ the requisite access rights. In a default Keycloak installation, admin-cli and an admin user would work, as would a separate
+ realm definition with the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase options used by Keycloak. The Authorization Services
+ paths and payloads have not officially been documented by the Keycloak project.
+ U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/).
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the custom policy.
- - On V(present), the custom policy will be created (or updated if it exists already).
- - On V(absent), the custom policy will be removed if it exists.
- choices: ['present', 'absent']
- default: 'present'
- type: str
- name:
- description:
- - Name of the custom policy to create.
- type: str
- required: true
- policy_type:
- description:
- - The type of the policy. This must match the name of the custom policy deployed to the server.
- - Multiple policies pointing to the same policy type can be created, but their names have to differ.
- type: str
- required: true
- client_id:
- description:
- - The V(clientId) of the Keycloak client that should have the custom policy attached to it.
- - This is usually a human-readable name of the Keycloak client.
- type: str
- required: true
- realm:
- description:
- - The name of the Keycloak realm the Keycloak client is in.
- type: str
- required: true
+ state:
+ description:
+ - State of the custom policy.
+ - On V(present), the custom policy will be created (or updated if it exists already).
+ - On V(absent), the custom policy will be removed if it exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+ name:
+ description:
+ - Name of the custom policy to create.
+ type: str
+ required: true
+ policy_type:
+ description:
+ - The type of the policy. This must match the name of the custom policy deployed to the server.
+ - Multiple policies pointing to the same policy type can be created, but their names have to differ.
+ type: str
+ required: true
+ client_id:
+ description:
+ - The V(clientId) of the Keycloak client that should have the custom policy attached to it.
+ - This is usually a human-readable name of the Keycloak client.
+ type: str
+ required: true
+ realm:
+ description:
+ - The name of the Keycloak realm the Keycloak client is in.
+ type: str
+ required: true
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Samuli Seppänen (@mattock)
-'''
+ - Samuli Seppänen (@mattock)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Manage Keycloak custom authorization policy
community.general.keycloak_authz_custom_policy:
name: OnlyOwner
@@ -89,31 +87,30 @@ EXAMPLES = '''
auth_username: keycloak
auth_password: keycloak
auth_realm: master
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
end_state:
- description: Representation of the custom policy after module execution.
- returned: on success
- type: dict
- contains:
- name:
- description: Name of the custom policy.
- type: str
- returned: when I(state=present)
- sample: file:delete
- policy_type:
- description: Type of custom policy.
- type: str
- returned: when I(state=present)
- sample: File delete
-
-'''
+ description: Representation of the custom policy after module execution.
+ returned: on success
+ type: dict
+ contains:
+ name:
+ description: Name of the custom policy.
+ type: str
+ returned: when I(state=present)
+ sample: file:delete
+ policy_type:
+ description: Type of custom policy.
+ type: str
+ returned: when I(state=present)
+ sample: File delete
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, \
keycloak_argument_spec, get_token, KeycloakError
@@ -143,7 +140,9 @@ def main():
supports_check_mode=True,
required_one_of=(
[['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', end_state={})
diff --git a/plugins/modules/keycloak_authz_permission.py b/plugins/modules/keycloak_authz_permission.py
index ef81fb8c31..683b5f8c18 100644
--- a/plugins/modules/keycloak_authz_permission.py
+++ b/plugins/modules/keycloak_authz_permission.py
@@ -9,125 +9,121 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_authz_permission
version_added: 7.2.0
-short_description: Allows administration of Keycloak client authorization permissions via Keycloak API
+short_description: Allows administration of Keycloak client authorization permissions using Keycloak API
description:
- - This module allows the administration of Keycloak client authorization permissions via the Keycloak REST
- API. Authorization permissions are only available if a client has Authorization enabled.
-
- - There are some peculiarities in JSON paths and payloads for authorization permissions. In particular
- POST and PUT operations are targeted at permission endpoints, whereas GET requests go to policies
- endpoint. To make matters more interesting the JSON responses from GET requests return data in a
- different format than what is expected for POST and PUT. The end result is that it is not possible to
- detect changes to things like policies, scopes or resources - at least not without a large number of
- additional API calls. Therefore this module always updates authorization permissions instead of
- attempting to determine if changes are truly needed.
-
- - This module requires access to the REST API via OpenID Connect; the user connecting and the realm
- being used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate realm definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase options used by Keycloak.
- The Authorization Services paths and payloads have not officially been documented by the Keycloak project.
- U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/)
-
+ - This module allows the administration of Keycloak client authorization permissions using the Keycloak REST API. Authorization
+ permissions are only available if a client has Authorization enabled.
+ - There are some peculiarities in JSON paths and payloads for authorization permissions. In particular POST and PUT operations
+ are targeted at permission endpoints, whereas GET requests go to policies endpoint. To make matters more interesting the
+ JSON responses from GET requests return data in a different format than what is expected for POST and PUT. The end result
+ is that it is not possible to detect changes to things like policies, scopes or resources - at least not without a large
+ number of additional API calls. Therefore this module always updates authorization permissions instead of attempting to
+ determine if changes are truly needed.
+ - This module requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have
+ the requisite access rights. In a default Keycloak installation, admin-cli and an admin user would work, as would a separate
+ realm definition with the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase options used by Keycloak. The Authorization Services
+ paths and payloads have not officially been documented by the Keycloak project.
+ U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/).
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the authorization permission.
- - On V(present), the authorization permission will be created (or updated if it exists already).
- - On V(absent), the authorization permission will be removed if it exists.
- choices: ['present', 'absent']
- default: 'present'
- type: str
- name:
- description:
- - Name of the authorization permission to create.
- type: str
- required: true
+ state:
description:
- description:
- - The description of the authorization permission.
- type: str
- required: false
- permission_type:
- description:
- - The type of authorization permission.
- - On V(scope) create a scope-based permission.
- - On V(resource) create a resource-based permission.
- type: str
- required: true
- choices:
- - resource
- - scope
- decision_strategy:
- description:
- - The decision strategy to use with this permission.
- type: str
- default: UNANIMOUS
- required: false
- choices:
- - UNANIMOUS
- - AFFIRMATIVE
- - CONSENSUS
- resources:
- description:
- - Resource names to attach to this permission.
- - Scope-based permissions can only include one resource.
- - Resource-based permissions can include multiple resources.
- type: list
- elements: str
- default: []
- required: false
- scopes:
- description:
- - Scope names to attach to this permission.
- - Resource-based permissions cannot have scopes attached to them.
- type: list
- elements: str
- default: []
- required: false
- policies:
- description:
- - Policy names to attach to this permission.
- type: list
- elements: str
- default: []
- required: false
- client_id:
- description:
- - The clientId of the keycloak client that should have the authorization scope.
- - This is usually a human-readable name of the Keycloak client.
- type: str
- required: true
- realm:
- description:
- - The name of the Keycloak realm the Keycloak client is in.
- type: str
- required: true
+ - State of the authorization permission.
+ - On V(present), the authorization permission will be created (or updated if it exists already).
+ - On V(absent), the authorization permission will be removed if it exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+ name:
+ description:
+ - Name of the authorization permission to create.
+ type: str
+ required: true
+ description:
+ description:
+ - The description of the authorization permission.
+ type: str
+ required: false
+ permission_type:
+ description:
+ - The type of authorization permission.
+ - On V(scope) create a scope-based permission.
+ - On V(resource) create a resource-based permission.
+ type: str
+ required: true
+ choices:
+ - resource
+ - scope
+ decision_strategy:
+ description:
+ - The decision strategy to use with this permission.
+ type: str
+ default: UNANIMOUS
+ required: false
+ choices:
+ - UNANIMOUS
+ - AFFIRMATIVE
+ - CONSENSUS
+ resources:
+ description:
+ - Resource names to attach to this permission.
+ - Scope-based permissions can only include one resource.
+ - Resource-based permissions can include multiple resources.
+ type: list
+ elements: str
+ default: []
+ required: false
+ scopes:
+ description:
+ - Scope names to attach to this permission.
+ - Resource-based permissions cannot have scopes attached to them.
+ type: list
+ elements: str
+ default: []
+ required: false
+ policies:
+ description:
+ - Policy names to attach to this permission.
+ type: list
+ elements: str
+ default: []
+ required: false
+ client_id:
+ description:
+ - The clientId of the keycloak client that should have the authorization scope.
+ - This is usually a human-readable name of the Keycloak client.
+ type: str
+ required: true
+ realm:
+ description:
+ - The name of the Keycloak realm the Keycloak client is in.
+ type: str
+ required: true
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Samuli Seppänen (@mattock)
-'''
+ - Samuli Seppänen (@mattock)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Manage scope-based Keycloak authorization permission
community.general.keycloak_authz_permission:
name: ScopePermission
@@ -161,68 +157,68 @@ EXAMPLES = '''
auth_username: keycloak
auth_password: keycloak
auth_realm: master
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
end_state:
- description: Representation of the authorization permission after module execution.
- returned: on success
- type: complex
- contains:
- id:
- description: ID of the authorization permission.
- type: str
- returned: when O(state=present)
- sample: 9da05cd2-b273-4354-bbd8-0c133918a454
- name:
- description: Name of the authorization permission.
- type: str
- returned: when O(state=present)
- sample: ResourcePermission
- description:
- description: Description of the authorization permission.
- type: str
- returned: when O(state=present)
- sample: Resource Permission
- type:
- description: Type of the authorization permission.
- type: str
- returned: when O(state=present)
- sample: resource
- decisionStrategy:
- description: The decision strategy to use.
- type: str
- returned: when O(state=present)
- sample: UNANIMOUS
- logic:
- description: The logic used for the permission (part of the payload, but has a fixed value).
- type: str
- returned: when O(state=present)
- sample: POSITIVE
- resources:
- description: IDs of resources attached to this permission.
- type: list
- returned: when O(state=present)
- sample:
- - 49e052ff-100d-4b79-a9dd-52669ed3c11d
- scopes:
- description: IDs of scopes attached to this permission.
- type: list
- returned: when O(state=present)
- sample:
- - 9da05cd2-b273-4354-bbd8-0c133918a454
- policies:
- description: IDs of policies attached to this permission.
- type: list
- returned: when O(state=present)
- sample:
- - 9da05cd2-b273-4354-bbd8-0c133918a454
-'''
+ description: Representation of the authorization permission after module execution.
+ returned: on success
+ type: complex
+ contains:
+ id:
+ description: ID of the authorization permission.
+ type: str
+ returned: when O(state=present)
+ sample: 9da05cd2-b273-4354-bbd8-0c133918a454
+ name:
+ description: Name of the authorization permission.
+ type: str
+ returned: when O(state=present)
+ sample: ResourcePermission
+ description:
+ description: Description of the authorization permission.
+ type: str
+ returned: when O(state=present)
+ sample: Resource Permission
+ type:
+ description: Type of the authorization permission.
+ type: str
+ returned: when O(state=present)
+ sample: resource
+ decisionStrategy:
+ description: The decision strategy to use.
+ type: str
+ returned: when O(state=present)
+ sample: UNANIMOUS
+ logic:
+ description: The logic used for the permission (part of the payload, but has a fixed value).
+ type: str
+ returned: when O(state=present)
+ sample: POSITIVE
+ resources:
+ description: IDs of resources attached to this permission.
+ type: list
+ returned: when O(state=present)
+ sample:
+ - 49e052ff-100d-4b79-a9dd-52669ed3c11d
+ scopes:
+ description: IDs of scopes attached to this permission.
+ type: list
+ returned: when O(state=present)
+ sample:
+ - 9da05cd2-b273-4354-bbd8-0c133918a454
+ policies:
+ description: IDs of policies attached to this permission.
+ type: list
+ returned: when O(state=present)
+ sample:
+ - 9da05cd2-b273-4354-bbd8-0c133918a454
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, \
keycloak_argument_spec, get_token, KeycloakError
@@ -258,7 +254,9 @@ def main():
supports_check_mode=True,
required_one_of=(
[['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
# Convenience variables
state = module.params.get('state')
diff --git a/plugins/modules/keycloak_authz_permission_info.py b/plugins/modules/keycloak_authz_permission_info.py
index 8b4e96b416..0271dfd4c4 100644
--- a/plugins/modules/keycloak_authz_permission_info.py
+++ b/plugins/modules/keycloak_authz_permission_info.py
@@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_authz_permission_info
version_added: 7.2.0
@@ -18,47 +17,47 @@ version_added: 7.2.0
short_description: Query Keycloak client authorization permissions information
description:
- - This module allows querying information about Keycloak client authorization permissions from the
- resources endpoint via the Keycloak REST API. Authorization permissions are only available if a
- client has Authorization enabled.
-
- - This module requires access to the REST API via OpenID Connect; the user connecting and the realm
- being used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate realm definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase options used by Keycloak.
- The Authorization Services paths and payloads have not officially been documented by the Keycloak project.
- U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/)
+ - This module allows querying information about Keycloak client authorization permissions from the resources endpoint using
+ the Keycloak REST API. Authorization permissions are only available if a client has Authorization enabled.
+ - This module requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have
+ the requisite access rights. In a default Keycloak installation, admin-cli and an admin user would work, as would a separate
+ realm definition with the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase options used by Keycloak. The Authorization Services
+ paths and payloads have not officially been documented by the Keycloak project.
+ U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/).
+attributes:
+ action_group:
+ version_added: 10.2.0
options:
- name:
- description:
- - Name of the authorization permission to create.
- type: str
- required: true
- client_id:
- description:
- - The clientId of the keycloak client that should have the authorization scope.
- - This is usually a human-readable name of the Keycloak client.
- type: str
- required: true
- realm:
- description:
- - The name of the Keycloak realm the Keycloak client is in.
- type: str
- required: true
+ name:
+ description:
+ - Name of the authorization permission to create.
+ type: str
+ required: true
+ client_id:
+ description:
+ - The clientId of the keycloak client that should have the authorization scope.
+ - This is usually a human-readable name of the Keycloak client.
+ type: str
+ required: true
+ realm:
+ description:
+ - The name of the Keycloak realm the Keycloak client is in.
+ type: str
+ required: true
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
+ - community.general.attributes.info_module
author:
- - Samuli Seppänen (@mattock)
-'''
+ - Samuli Seppänen (@mattock)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Query Keycloak authorization permission
community.general.keycloak_authz_permission_info:
name: ScopePermission
@@ -68,48 +67,48 @@ EXAMPLES = '''
auth_username: keycloak
auth_password: keycloak
auth_realm: master
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
queried_state:
- description: State of the resource (a policy) as seen by Keycloak.
- returned: on success
- type: complex
- contains:
- id:
- description: ID of the authorization permission.
- type: str
- sample: 9da05cd2-b273-4354-bbd8-0c133918a454
- name:
- description: Name of the authorization permission.
- type: str
- sample: ResourcePermission
- description:
- description: Description of the authorization permission.
- type: str
- sample: Resource Permission
- type:
- description: Type of the authorization permission.
- type: str
- sample: resource
- decisionStrategy:
- description: The decision strategy.
- type: str
- sample: UNANIMOUS
- logic:
- description: The logic used for the permission (part of the payload, but has a fixed value).
- type: str
- sample: POSITIVE
- config:
- description: Configuration of the permission (empty in all observed cases).
- type: dict
- sample: {}
-'''
+ description: State of the resource (a policy) as seen by Keycloak.
+ returned: on success
+ type: complex
+ contains:
+ id:
+ description: ID of the authorization permission.
+ type: str
+ sample: 9da05cd2-b273-4354-bbd8-0c133918a454
+ name:
+ description: Name of the authorization permission.
+ type: str
+ sample: ResourcePermission
+ description:
+ description: Description of the authorization permission.
+ type: str
+ sample: Resource Permission
+ type:
+ description: Type of the authorization permission.
+ type: str
+ sample: resource
+ decisionStrategy:
+ description: The decision strategy.
+ type: str
+ sample: UNANIMOUS
+ logic:
+ description: The logic used for the permission (part of the payload, but has a fixed value).
+ type: str
+ sample: POSITIVE
+ config:
+ description: Configuration of the permission (empty in all observed cases).
+ type: dict
+ sample: {}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, \
keycloak_argument_spec, get_token, KeycloakError
@@ -136,7 +135,9 @@ def main():
supports_check_mode=True,
required_one_of=(
[['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
# Convenience variables
name = module.params.get('name')
diff --git a/plugins/modules/keycloak_client.py b/plugins/modules/keycloak_client.py
index d2800be292..70ff21a915 100644
--- a/plugins/modules/keycloak_client.py
+++ b/plugins/modules/keycloak_client.py
@@ -8,600 +8,550 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_client
-short_description: Allows administration of Keycloak clients via Keycloak API
+short_description: Allows administration of Keycloak clients using Keycloak API
description:
- - This module allows the administration of Keycloak clients via the Keycloak REST API. It
- requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
- Aliases are provided so camelCased versions can be used as well.
-
- - The Keycloak API does not always sanity check inputs e.g. you can set
- SAML-specific settings on an OpenID Connect client for instance and vice versa. Be careful.
- If you do not specify a setting, usually a sensible default is chosen.
-
+ - This module allows the administration of Keycloak clients using the Keycloak REST API. It requires access to the REST
+ API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default
+ Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with the scope tailored
+ to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html). Aliases are provided so camelCased versions can be used
+ as well.
+ - The Keycloak API does not always sanity check inputs, for example you can set SAML-specific settings on an OpenID Connect
+ client for instance and the other way around. Be careful. If you do not specify a setting, usually a sensible default
+ is chosen.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the client
- - On V(present), the client will be created (or updated if it exists already).
- - On V(absent), the client will be removed if it exists
- choices: ['present', 'absent']
- default: 'present'
- type: str
-
- realm:
- description:
- - The realm to create the client in.
- type: str
- default: master
-
- client_id:
- description:
- - Client id of client to be worked on. This is usually an alphanumeric name chosen by
- you. Either this or O(id) is required. If you specify both, O(id) takes precedence.
- This is 'clientId' in the Keycloak REST API.
- aliases:
- - clientId
- type: str
-
- id:
- description:
- - Id of client to be worked on. This is usually an UUID. Either this or O(client_id)
- is required. If you specify both, this takes precedence.
- type: str
-
- name:
- description:
- - Name of the client (this is not the same as O(client_id)).
- type: str
-
+ state:
description:
+ - State of the client.
+ - On V(present), the client will be created (or updated if it exists already).
+ - On V(absent), the client will be removed if it exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+
+ realm:
+ description:
+ - The realm to create the client in.
+ type: str
+ default: master
+
+ client_id:
+ description:
+ - Client ID of client to be worked on. This is usually an alphanumeric name chosen by you. Either this or O(id) is required.
+ If you specify both, O(id) takes precedence. This is C(clientId) in the Keycloak REST API.
+ aliases:
+ - clientId
+ type: str
+
+ id:
+ description:
+ - ID of client to be worked on. This is usually an UUID. Either this or O(client_id) is required. If you specify both,
+ this takes precedence.
+ type: str
+
+ name:
+ description:
+ - Name of the client (this is not the same as O(client_id)).
+ type: str
+
+ description:
+ description:
+ - Description of the client in Keycloak.
+ type: str
+
+ root_url:
+ description:
+ - Root URL appended to relative URLs for this client. This is C(rootUrl) in the Keycloak REST API.
+ aliases:
+ - rootUrl
+ type: str
+
+ admin_url:
+ description:
+ - URL to the admin interface of the client. This is C(adminUrl) in the Keycloak REST API.
+ aliases:
+ - adminUrl
+ type: str
+
+ base_url:
+ description:
+ - Default URL to use when the auth server needs to redirect or link back to the client This is C(baseUrl) in the Keycloak
+ REST API.
+ aliases:
+ - baseUrl
+ type: str
+
+ enabled:
+ description:
+ - Is this client enabled or not?
+ type: bool
+
+ client_authenticator_type:
+ description:
+ - How do clients authenticate with the auth server? Either V(client-secret), V(client-jwt), or V(client-x509) can be
+ chosen. When using V(client-secret), the module parameter O(secret) can set it, for V(client-jwt), you can use the
+ keys C(use.jwks.url), C(jwks.url), and C(jwt.credential.certificate) in the O(attributes) module parameter to configure
+ its behavior. For V(client-x509) you can use the keys C(x509.allow.regex.pattern.comparison) and C(x509.subjectdn)
+ in the O(attributes) module parameter to configure which certificate(s) to accept.
+ - This is C(clientAuthenticatorType) in the Keycloak REST API.
+ choices: ['client-secret', 'client-jwt', 'client-x509']
+ aliases:
+ - clientAuthenticatorType
+ type: str
+
+ secret:
+ description:
+ - When using O(client_authenticator_type=client-secret) (the default), you can specify a secret here (otherwise one
+ will be generated if it does not exit). If changing this secret, the module will not register a change currently (but
+ the changed secret will be saved).
+ type: str
+
+ registration_access_token:
+ description:
+ - The registration access token provides access for clients to the client registration service. This is C(registrationAccessToken)
+ in the Keycloak REST API.
+ aliases:
+ - registrationAccessToken
+ type: str
+
+ default_roles:
+ description:
+ - List of default roles for this client. If the client roles referenced do not exist yet, they will be created. This
+ is C(defaultRoles) in the Keycloak REST API.
+ aliases:
+ - defaultRoles
+ type: list
+ elements: str
+
+ redirect_uris:
+ description:
+ - Acceptable redirect URIs for this client. This is C(redirectUris) in the Keycloak REST API.
+ aliases:
+ - redirectUris
+ type: list
+ elements: str
+
+ web_origins:
+ description:
+ - List of allowed CORS origins. This is C(webOrigins) in the Keycloak REST API.
+ aliases:
+ - webOrigins
+ type: list
+ elements: str
+
+ not_before:
+ description:
+ - Revoke any tokens issued before this date for this client (this is a UNIX timestamp). This is C(notBefore) in the
+ Keycloak REST API.
+ type: int
+ aliases:
+ - notBefore
+
+ bearer_only:
+ description:
+ - The access type of this client is bearer-only. This is C(bearerOnly) in the Keycloak REST API.
+ aliases:
+ - bearerOnly
+ type: bool
+
+ consent_required:
+ description:
+ - If enabled, users have to consent to client access. This is C(consentRequired) in the Keycloak REST API.
+ aliases:
+ - consentRequired
+ type: bool
+
+ standard_flow_enabled:
+ description:
+ - Enable standard flow for this client or not (OpenID connect). This is C(standardFlowEnabled) in the Keycloak REST
+ API.
+ aliases:
+ - standardFlowEnabled
+ type: bool
+
+ implicit_flow_enabled:
+ description:
+ - Enable implicit flow for this client or not (OpenID connect). This is C(implicitFlowEnabled) in the Keycloak REST
+ API.
+ aliases:
+ - implicitFlowEnabled
+ type: bool
+
+ direct_access_grants_enabled:
+ description:
+ - Are direct access grants enabled for this client or not (OpenID connect). This is C(directAccessGrantsEnabled) in
+ the Keycloak REST API.
+ aliases:
+ - directAccessGrantsEnabled
+ type: bool
+
+ service_accounts_enabled:
+ description:
+ - Are service accounts enabled for this client or not (OpenID connect). This is C(serviceAccountsEnabled) in the Keycloak
+ REST API.
+ aliases:
+ - serviceAccountsEnabled
+ type: bool
+
+ authorization_services_enabled:
+ description:
+ - Are authorization services enabled for this client or not (OpenID connect). This is C(authorizationServicesEnabled)
+ in the Keycloak REST API.
+ aliases:
+ - authorizationServicesEnabled
+ type: bool
+
+ public_client:
+ description:
+ - Is the access type for this client public or not. This is C(publicClient) in the Keycloak REST API.
+ aliases:
+ - publicClient
+ type: bool
+
+ frontchannel_logout:
+ description:
+ - Is frontchannel logout enabled for this client or not. This is C(frontchannelLogout) in the Keycloak REST API.
+ aliases:
+ - frontchannelLogout
+ type: bool
+
+ protocol:
+ description:
+ - Type of client.
+ - At creation only, default value will be V(openid-connect) if O(protocol) is omitted.
+ - The V(docker-v2) value was added in community.general 8.6.0.
+ type: str
+ choices: ['openid-connect', 'saml', 'docker-v2']
+
+ full_scope_allowed:
+ description:
+ - Is the "Full Scope Allowed" feature set for this client or not. This is C(fullScopeAllowed) in the Keycloak REST API.
+ aliases:
+ - fullScopeAllowed
+ type: bool
+
+ node_re_registration_timeout:
+ description:
+ - Cluster node re-registration timeout for this client. This is C(nodeReRegistrationTimeout) in the Keycloak REST API.
+ type: int
+ aliases:
+ - nodeReRegistrationTimeout
+
+ registered_nodes:
+ description:
+ - Dict of registered cluster nodes (with C(nodename) as the key and last registration time as the value). This is C(registeredNodes)
+ in the Keycloak REST API.
+ type: dict
+ aliases:
+ - registeredNodes
+
+ client_template:
+ description:
+ - Client template to use for this client. If it does not exist this field will silently be dropped. This is C(clientTemplate)
+ in the Keycloak REST API.
+ type: str
+ aliases:
+ - clientTemplate
+
+ use_template_config:
+ description:
+ - Whether or not to use configuration from the O(client_template). This is C(useTemplateConfig) in the Keycloak REST
+ API.
+ aliases:
+ - useTemplateConfig
+ type: bool
+
+ use_template_scope:
+ description:
+ - Whether or not to use scope configuration from the O(client_template). This is C(useTemplateScope) in the Keycloak
+ REST API.
+ aliases:
+ - useTemplateScope
+ type: bool
+
+ use_template_mappers:
+ description:
+ - Whether or not to use mapper configuration from the O(client_template). This is C(useTemplateMappers) in the Keycloak
+ REST API.
+ aliases:
+ - useTemplateMappers
+ type: bool
+
+ always_display_in_console:
+ description:
+ - Whether or not to display this client in account console, even if the user does not have an active session.
+ aliases:
+ - alwaysDisplayInConsole
+ type: bool
+ version_added: 4.7.0
+
+ surrogate_auth_required:
+ description:
+ - Whether or not surrogate auth is required. This is C(surrogateAuthRequired) in the Keycloak REST API.
+ aliases:
+ - surrogateAuthRequired
+ type: bool
+
+ authorization_settings:
+ description:
+ - A data structure defining the authorization settings for this client. For reference, please see the Keycloak API docs
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html#_resourceserverrepresentation). This is C(authorizationSettings)
+ in the Keycloak REST API.
+ type: dict
+ aliases:
+ - authorizationSettings
+
+ authentication_flow_binding_overrides:
+ description:
+ - Override realm authentication flow bindings.
+ type: dict
+ suboptions:
+ browser:
description:
- - Description of the client in Keycloak.
+ - Flow ID of the browser authentication flow.
+ - O(authentication_flow_binding_overrides.browser) and O(authentication_flow_binding_overrides.browser_name) are
+ mutually exclusive.
type: str
- root_url:
+ browser_name:
description:
- - Root URL appended to relative URLs for this client.
- This is 'rootUrl' in the Keycloak REST API.
+ - Flow name of the browser authentication flow.
+ - O(authentication_flow_binding_overrides.browser) and O(authentication_flow_binding_overrides.browser_name) are
+ mutually exclusive.
aliases:
- - rootUrl
+ - browserName
+ type: str
+ version_added: 9.1.0
+
+ direct_grant:
+ description:
+ - Flow ID of the direct grant authentication flow.
+ - O(authentication_flow_binding_overrides.direct_grant) and O(authentication_flow_binding_overrides.direct_grant_name)
+ are mutually exclusive.
+ aliases:
+ - directGrant
type: str
- admin_url:
+ direct_grant_name:
description:
- - URL to the admin interface of the client.
- This is 'adminUrl' in the Keycloak REST API.
+ - Flow name of the direct grant authentication flow.
+ - O(authentication_flow_binding_overrides.direct_grant) and O(authentication_flow_binding_overrides.direct_grant_name)
+ are mutually exclusive.
aliases:
- - adminUrl
+ - directGrantName
+ type: str
+ version_added: 9.1.0
+ aliases:
+ - authenticationFlowBindingOverrides
+ version_added: 3.4.0
+
+ default_client_scopes:
+ description:
+ - List of default client scopes.
+ aliases:
+ - defaultClientScopes
+ type: list
+ elements: str
+ version_added: 4.7.0
+
+ optional_client_scopes:
+ description:
+ - List of optional client scopes.
+ aliases:
+ - optionalClientScopes
+ type: list
+ elements: str
+ version_added: 4.7.0
+
+ protocol_mappers:
+ description:
+ - A list of dicts defining protocol mappers for this client. This is C(protocolMappers) in the Keycloak REST API.
+ aliases:
+ - protocolMappers
+ type: list
+ elements: dict
+ suboptions:
+ consentRequired:
+ description:
+ - Specifies whether a user needs to provide consent to a client for this mapper to be active.
+ type: bool
+
+ consentText:
+ description:
+ - The human-readable name of the consent the user is presented to accept.
type: str
- base_url:
+ id:
description:
- - Default URL to use when the auth server needs to redirect or link back to the client
- This is 'baseUrl' in the Keycloak REST API.
- aliases:
- - baseUrl
+ - Usually a UUID specifying the internal ID of this protocol mapper instance.
type: str
- enabled:
+ name:
description:
- - Is this client enabled or not?
- type: bool
-
- client_authenticator_type:
- description:
- - How do clients authenticate with the auth server? Either V(client-secret),
- V(client-jwt), or V(client-x509) can be chosen. When using V(client-secret), the module parameter
- O(secret) can set it, for V(client-jwt), you can use the keys C(use.jwks.url),
- C(jwks.url), and C(jwt.credential.certificate) in the O(attributes) module parameter
- to configure its behavior. For V(client-x509) you can use the keys C(x509.allow.regex.pattern.comparison)
- and C(x509.subjectdn) in the O(attributes) module parameter to configure which certificate(s) to accept.
- - This is 'clientAuthenticatorType' in the Keycloak REST API.
- choices: ['client-secret', 'client-jwt', 'client-x509']
- aliases:
- - clientAuthenticatorType
+ - The name of this protocol mapper.
type: str
- secret:
+ protocol:
description:
- - When using O(client_authenticator_type=client-secret) (the default), you can
- specify a secret here (otherwise one will be generated if it does not exit). If
- changing this secret, the module will not register a change currently (but the
- changed secret will be saved).
- type: str
-
- registration_access_token:
- description:
- - The registration access token provides access for clients to the client registration
- service.
- This is 'registrationAccessToken' in the Keycloak REST API.
- aliases:
- - registrationAccessToken
- type: str
-
- default_roles:
- description:
- - list of default roles for this client. If the client roles referenced do not exist
- yet, they will be created.
- This is 'defaultRoles' in the Keycloak REST API.
- aliases:
- - defaultRoles
- type: list
- elements: str
-
- redirect_uris:
- description:
- - Acceptable redirect URIs for this client.
- This is 'redirectUris' in the Keycloak REST API.
- aliases:
- - redirectUris
- type: list
- elements: str
-
- web_origins:
- description:
- - List of allowed CORS origins.
- This is 'webOrigins' in the Keycloak REST API.
- aliases:
- - webOrigins
- type: list
- elements: str
-
- not_before:
- description:
- - Revoke any tokens issued before this date for this client (this is a UNIX timestamp).
- This is 'notBefore' in the Keycloak REST API.
- type: int
- aliases:
- - notBefore
-
- bearer_only:
- description:
- - The access type of this client is bearer-only.
- This is 'bearerOnly' in the Keycloak REST API.
- aliases:
- - bearerOnly
- type: bool
-
- consent_required:
- description:
- - If enabled, users have to consent to client access.
- This is 'consentRequired' in the Keycloak REST API.
- aliases:
- - consentRequired
- type: bool
-
- standard_flow_enabled:
- description:
- - Enable standard flow for this client or not (OpenID connect).
- This is 'standardFlowEnabled' in the Keycloak REST API.
- aliases:
- - standardFlowEnabled
- type: bool
-
- implicit_flow_enabled:
- description:
- - Enable implicit flow for this client or not (OpenID connect).
- This is 'implicitFlowEnabled' in the Keycloak REST API.
- aliases:
- - implicitFlowEnabled
- type: bool
-
- direct_access_grants_enabled:
- description:
- - Are direct access grants enabled for this client or not (OpenID connect).
- This is 'directAccessGrantsEnabled' in the Keycloak REST API.
- aliases:
- - directAccessGrantsEnabled
- type: bool
-
- service_accounts_enabled:
- description:
- - Are service accounts enabled for this client or not (OpenID connect).
- This is 'serviceAccountsEnabled' in the Keycloak REST API.
- aliases:
- - serviceAccountsEnabled
- type: bool
-
- authorization_services_enabled:
- description:
- - Are authorization services enabled for this client or not (OpenID connect).
- This is 'authorizationServicesEnabled' in the Keycloak REST API.
- aliases:
- - authorizationServicesEnabled
- type: bool
-
- public_client:
- description:
- - Is the access type for this client public or not.
- This is 'publicClient' in the Keycloak REST API.
- aliases:
- - publicClient
- type: bool
-
- frontchannel_logout:
- description:
- - Is frontchannel logout enabled for this client or not.
- This is 'frontchannelLogout' in the Keycloak REST API.
- aliases:
- - frontchannelLogout
- type: bool
-
- protocol:
- description:
- - Type of client.
- - At creation only, default value will be V(openid-connect) if O(protocol) is omitted.
- - The V(docker-v2) value was added in community.general 8.6.0.
- type: str
+ - This specifies for which protocol this protocol mapper is active.
choices: ['openid-connect', 'saml', 'docker-v2']
-
- full_scope_allowed:
- description:
- - Is the "Full Scope Allowed" feature set for this client or not.
- This is 'fullScopeAllowed' in the Keycloak REST API.
- aliases:
- - fullScopeAllowed
- type: bool
-
- node_re_registration_timeout:
- description:
- - Cluster node re-registration timeout for this client.
- This is 'nodeReRegistrationTimeout' in the Keycloak REST API.
- type: int
- aliases:
- - nodeReRegistrationTimeout
-
- registered_nodes:
- description:
- - dict of registered cluster nodes (with C(nodename) as the key and last registration
- time as the value).
- This is 'registeredNodes' in the Keycloak REST API.
- type: dict
- aliases:
- - registeredNodes
-
- client_template:
- description:
- - Client template to use for this client. If it does not exist this field will silently
- be dropped.
- This is 'clientTemplate' in the Keycloak REST API.
type: str
- aliases:
- - clientTemplate
- use_template_config:
+ protocolMapper:
description:
- - Whether or not to use configuration from the O(client_template).
- This is 'useTemplateConfig' in the Keycloak REST API.
- aliases:
- - useTemplateConfig
- type: bool
+ - 'The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide
+ since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:'
+ - V(docker-v2-allow-all-mapper).
+ - V(oidc-address-mapper).
+ - V(oidc-full-name-mapper).
+ - V(oidc-group-membership-mapper).
+ - V(oidc-hardcoded-claim-mapper).
+ - V(oidc-hardcoded-role-mapper).
+ - V(oidc-role-name-mapper).
+ - V(oidc-script-based-protocol-mapper).
+ - V(oidc-sha256-pairwise-sub-mapper).
+ - V(oidc-usermodel-attribute-mapper).
+ - V(oidc-usermodel-client-role-mapper).
+ - V(oidc-usermodel-property-mapper).
+ - V(oidc-usermodel-realm-role-mapper).
+ - V(oidc-usersessionmodel-note-mapper).
+ - V(saml-group-membership-mapper).
+ - V(saml-hardcode-attribute-mapper).
+ - V(saml-hardcode-role-mapper).
+ - V(saml-role-list-mapper).
+ - V(saml-role-name-mapper).
+ - V(saml-user-attribute-mapper).
+ - V(saml-user-property-mapper).
+ - V(saml-user-session-note-mapper).
+ - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to
+ Server Info -> Providers and looking under 'protocol-mapper'.
+ type: str
- use_template_scope:
+ config:
description:
- - Whether or not to use scope configuration from the O(client_template).
- This is 'useTemplateScope' in the Keycloak REST API.
- aliases:
- - useTemplateScope
- type: bool
-
- use_template_mappers:
- description:
- - Whether or not to use mapper configuration from the O(client_template).
- This is 'useTemplateMappers' in the Keycloak REST API.
- aliases:
- - useTemplateMappers
- type: bool
-
- always_display_in_console:
- description:
- - Whether or not to display this client in account console, even if the
- user does not have an active session.
- aliases:
- - alwaysDisplayInConsole
- type: bool
- version_added: 4.7.0
-
- surrogate_auth_required:
- description:
- - Whether or not surrogate auth is required.
- This is 'surrogateAuthRequired' in the Keycloak REST API.
- aliases:
- - surrogateAuthRequired
- type: bool
-
- authorization_settings:
- description:
- - a data structure defining the authorization settings for this client. For reference,
- please see the Keycloak API docs at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html#_resourceserverrepresentation).
- This is 'authorizationSettings' in the Keycloak REST API.
+ - Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value
+ of O(protocol_mappers[].protocolMapper) and are not documented other than by the source of the mappers and its
+ parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing
+ protocol mapper configuration through check-mode in the RV(existing) field.
type: dict
- aliases:
- - authorizationSettings
- authentication_flow_binding_overrides:
+ attributes:
+ description:
+ - A dict of further attributes for this client. This can contain various configuration settings; an example is given
+ in the examples section. While an exhaustive list of permissible options is not available; possible options as of
+ Keycloak 3.4 are listed below. The Keycloak API does not validate whether a given option is appropriate for the protocol
+ used; if specified anyway, Keycloak will simply not use it.
+ type: dict
+ suboptions:
+ saml.authnstatement:
description:
- - Override realm authentication flow bindings.
- type: dict
- suboptions:
- browser:
- description:
- - Flow ID of the browser authentication flow.
- - O(authentication_flow_binding_overrides.browser)
- and O(authentication_flow_binding_overrides.browser_name) are mutually exclusive.
- type: str
-
- browser_name:
- description:
- - Flow name of the browser authentication flow.
- - O(authentication_flow_binding_overrides.browser)
- and O(authentication_flow_binding_overrides.browser_name) are mutually exclusive.
- aliases:
- - browserName
- type: str
- version_added: 9.1.0
-
- direct_grant:
- description:
- - Flow ID of the direct grant authentication flow.
- - O(authentication_flow_binding_overrides.direct_grant)
- and O(authentication_flow_binding_overrides.direct_grant_name) are mutually exclusive.
- aliases:
- - directGrant
- type: str
-
- direct_grant_name:
- description:
- - Flow name of the direct grant authentication flow.
- - O(authentication_flow_binding_overrides.direct_grant)
- and O(authentication_flow_binding_overrides.direct_grant_name) are mutually exclusive.
- aliases:
- - directGrantName
- type: str
- version_added: 9.1.0
- aliases:
- - authenticationFlowBindingOverrides
- version_added: 3.4.0
-
- default_client_scopes:
+ - For SAML clients, boolean specifying whether or not a statement containing method and timestamp should be included
+ in the login response.
+ saml.client.signature:
description:
- - List of default client scopes.
- aliases:
- - defaultClientScopes
- type: list
- elements: str
- version_added: 4.7.0
-
- optional_client_scopes:
+ - For SAML clients, boolean specifying whether a client signature is required and validated.
+ saml.encrypt:
description:
- - List of optional client scopes.
- aliases:
- - optionalClientScopes
- type: list
- elements: str
- version_added: 4.7.0
-
- protocol_mappers:
+ - Boolean specifying whether SAML assertions should be encrypted with the client's public key.
+ saml.force.post.binding:
description:
- - a list of dicts defining protocol mappers for this client.
- This is 'protocolMappers' in the Keycloak REST API.
- aliases:
- - protocolMappers
- type: list
- elements: dict
- suboptions:
- consentRequired:
- description:
- - Specifies whether a user needs to provide consent to a client for this mapper to be active.
- type: bool
-
- consentText:
- description:
- - The human-readable name of the consent the user is presented to accept.
- type: str
-
- id:
- description:
- - Usually a UUID specifying the internal ID of this protocol mapper instance.
- type: str
-
- name:
- description:
- - The name of this protocol mapper.
- type: str
-
- protocol:
- description:
- - This specifies for which protocol this protocol mapper is active.
- choices: ['openid-connect', 'saml', 'docker-v2']
- type: str
-
- protocolMapper:
- description:
- - "The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is
- impossible to provide since this may be extended through SPIs by the user of Keycloak,
- by default Keycloak as of 3.4 ships with at least:"
- - V(docker-v2-allow-all-mapper)
- - V(oidc-address-mapper)
- - V(oidc-full-name-mapper)
- - V(oidc-group-membership-mapper)
- - V(oidc-hardcoded-claim-mapper)
- - V(oidc-hardcoded-role-mapper)
- - V(oidc-role-name-mapper)
- - V(oidc-script-based-protocol-mapper)
- - V(oidc-sha256-pairwise-sub-mapper)
- - V(oidc-usermodel-attribute-mapper)
- - V(oidc-usermodel-client-role-mapper)
- - V(oidc-usermodel-property-mapper)
- - V(oidc-usermodel-realm-role-mapper)
- - V(oidc-usersessionmodel-note-mapper)
- - V(saml-group-membership-mapper)
- - V(saml-hardcode-attribute-mapper)
- - V(saml-hardcode-role-mapper)
- - V(saml-role-list-mapper)
- - V(saml-role-name-mapper)
- - V(saml-user-attribute-mapper)
- - V(saml-user-property-mapper)
- - V(saml-user-session-note-mapper)
- - An exhaustive list of available mappers on your installation can be obtained on
- the admin console by going to Server Info -> Providers and looking under
- 'protocol-mapper'.
- type: str
-
- config:
- description:
- - Dict specifying the configuration options for the protocol mapper; the
- contents differ depending on the value of O(protocol_mappers[].protocolMapper) and are not documented
- other than by the source of the mappers and its parent class(es). An example is given
- below. It is easiest to obtain valid config values by dumping an already-existing
- protocol mapper configuration through check-mode in the RV(existing) field.
- type: dict
-
- attributes:
+ - For SAML clients, boolean specifying whether always to use POST binding for responses.
+ saml.onetimeuse.condition:
description:
- - A dict of further attributes for this client. This can contain various configuration
- settings; an example is given in the examples section. While an exhaustive list of
- permissible options is not available; possible options as of Keycloak 3.4 are listed below. The Keycloak
- API does not validate whether a given option is appropriate for the protocol used; if specified
- anyway, Keycloak will simply not use it.
- type: dict
- suboptions:
- saml.authnstatement:
- description:
- - For SAML clients, boolean specifying whether or not a statement containing method and timestamp
- should be included in the login response.
+ - For SAML clients, boolean specifying whether a OneTimeUse condition should be included in login responses.
+ saml.server.signature:
+ description:
+ - Boolean specifying whether SAML documents should be signed by the realm.
+ saml.server.signature.keyinfo.ext:
+ description:
+ - For SAML clients, boolean specifying whether REDIRECT signing key lookup should be optimized through inclusion
+ of the signing key ID in the SAML Extensions element.
+ saml.signature.algorithm:
+ description:
+ - Signature algorithm used to sign SAML documents. One of V(RSA_SHA256), V(RSA_SHA1), V(RSA_SHA512), or V(DSA_SHA1).
+ saml.signing.certificate:
+ description:
+ - SAML signing key certificate, base64-encoded.
+ saml.signing.private.key:
+ description:
+ - SAML signing key private key, base64-encoded.
+ saml_assertion_consumer_url_post:
+ description:
+ - SAML POST Binding URL for the client's assertion consumer service (login responses).
+ saml_assertion_consumer_url_redirect:
+ description:
+ - SAML Redirect Binding URL for the client's assertion consumer service (login responses).
+ saml_force_name_id_format:
+ description:
+ - For SAML clients, Boolean specifying whether to ignore requested NameID subject format and using the configured
+ one instead.
+ saml_name_id_format:
+ description:
+ - For SAML clients, the NameID format to use (one of V(username), V(email), V(transient), or V(persistent)).
+ saml_signature_canonicalization_method:
+ description:
+ - SAML signature canonicalization method. This is one of four values, namely V(http://www.w3.org/2001/10/xml-exc-c14n#)
+ for EXCLUSIVE, V(http://www.w3.org/2001/10/xml-exc-c14n#WithComments) for EXCLUSIVE_WITH_COMMENTS,
+ V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315)
+ for INCLUSIVE, and V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) for INCLUSIVE_WITH_COMMENTS.
+ saml_single_logout_service_url_post:
+ description:
+ - SAML POST binding URL for the client's single logout service.
+ saml_single_logout_service_url_redirect:
+ description:
+ - SAML redirect binding URL for the client's single logout service.
+ user.info.response.signature.alg:
+ description:
+ - For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses. One of V(RS256) or V(unsigned).
+ request.object.signature.alg:
+ description:
+ - For OpenID-Connect clients, JWA algorithm which the client needs to use when sending OIDC request object. One
+ of V(any), V(none), V(RS256).
+ use.jwks.url:
+ description:
+ - For OpenID-Connect clients, boolean specifying whether to use a JWKS URL to obtain client public keys.
+ jwks.url:
+ description:
+ - For OpenID-Connect clients, URL where client keys in JWK are stored.
+ jwt.credential.certificate:
+ description:
+ - For OpenID-Connect clients, client certificate for validating JWT issued by client and signed by its key, base64-encoded.
+ x509.subjectdn:
+ description:
+ - For OpenID-Connect clients, subject which will be used to authenticate the client.
+ type: str
+ version_added: 9.5.0
- saml.client.signature:
- description:
- - For SAML clients, boolean specifying whether a client signature is required and validated.
-
- saml.encrypt:
- description:
- - Boolean specifying whether SAML assertions should be encrypted with the client's public key.
-
- saml.force.post.binding:
- description:
- - For SAML clients, boolean specifying whether always to use POST binding for responses.
-
- saml.onetimeuse.condition:
- description:
- - For SAML clients, boolean specifying whether a OneTimeUse condition should be included in login responses.
-
- saml.server.signature:
- description:
- - Boolean specifying whether SAML documents should be signed by the realm.
-
- saml.server.signature.keyinfo.ext:
- description:
- - For SAML clients, boolean specifying whether REDIRECT signing key lookup should be optimized through inclusion
- of the signing key id in the SAML Extensions element.
-
- saml.signature.algorithm:
- description:
- - Signature algorithm used to sign SAML documents. One of V(RSA_SHA256), V(RSA_SHA1), V(RSA_SHA512), or V(DSA_SHA1).
-
- saml.signing.certificate:
- description:
- - SAML signing key certificate, base64-encoded.
-
- saml.signing.private.key:
- description:
- - SAML signing key private key, base64-encoded.
-
- saml_assertion_consumer_url_post:
- description:
- - SAML POST Binding URL for the client's assertion consumer service (login responses).
-
- saml_assertion_consumer_url_redirect:
- description:
- - SAML Redirect Binding URL for the client's assertion consumer service (login responses).
-
- saml_force_name_id_format:
- description:
- - For SAML clients, Boolean specifying whether to ignore requested NameID subject format and using the configured one instead.
-
- saml_name_id_format:
- description:
- - For SAML clients, the NameID format to use (one of V(username), V(email), V(transient), or V(persistent))
-
- saml_signature_canonicalization_method:
- description:
- - SAML signature canonicalization method. This is one of four values, namely
- V(http://www.w3.org/2001/10/xml-exc-c14n#) for EXCLUSIVE,
- V(http://www.w3.org/2001/10/xml-exc-c14n#WithComments) for EXCLUSIVE_WITH_COMMENTS,
- V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315) for INCLUSIVE, and
- V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) for INCLUSIVE_WITH_COMMENTS.
-
- saml_single_logout_service_url_post:
- description:
- - SAML POST binding url for the client's single logout service.
-
- saml_single_logout_service_url_redirect:
- description:
- - SAML redirect binding url for the client's single logout service.
-
- user.info.response.signature.alg:
- description:
- - For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses. One of V(RS256) or V(unsigned).
-
- request.object.signature.alg:
- description:
- - For OpenID-Connect clients, JWA algorithm which the client needs to use when sending
- OIDC request object. One of V(any), V(none), V(RS256).
-
- use.jwks.url:
- description:
- - For OpenID-Connect clients, boolean specifying whether to use a JWKS URL to obtain client
- public keys.
-
- jwks.url:
- description:
- - For OpenID-Connect clients, URL where client keys in JWK are stored.
-
- jwt.credential.certificate:
- description:
- - For OpenID-Connect clients, client certificate for validating JWT issued by
- client and signed by its key, base64-encoded.
-
- x509.subjectdn:
- description:
- - For OpenID-Connect clients, subject which will be used to authenticate the client.
- type: str
- version_added: 9.5.0
-
- x509.allow.regex.pattern.comparison:
- description:
- - For OpenID-Connect clients, boolean specifying whether to allow C(x509.subjectdn) as regular expression.
- type: bool
- version_added: 9.5.0
+ x509.allow.regex.pattern.comparison:
+ description:
+ - For OpenID-Connect clients, boolean specifying whether to allow C(x509.subjectdn) as regular expression.
+ type: bool
+ version_added: 9.5.0
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Eike Frost (@eikef)
-'''
+ - Eike Frost (@eikef)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create or update Keycloak client (minimal example), authentication with credentials
community.general.keycloak_client:
auth_keycloak_url: https://auth.example.com/auth
@@ -702,7 +652,7 @@ EXAMPLES = '''
- test01
- test02
authentication_flow_binding_overrides:
- browser: 4c90336b-bf1d-4b87-916d-3677ba4e5fbb
+ browser: 4c90336b-bf1d-4b87-916d-3677ba4e5fbb
protocol_mappers:
- config:
access.token.claim: true
@@ -741,48 +691,36 @@ EXAMPLES = '''
jwks.url: JWKS_URL_FOR_CLIENT_AUTH_JWT
jwt.credential.certificate: JWT_CREDENTIAL_CERTIFICATE_FOR_CLIENT_AUTH
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Client testclient has been updated"
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Client testclient has been updated"
proposed:
- description: Representation of proposed client.
- returned: always
- type: dict
- sample: {
- clientId: "test"
- }
+ description: Representation of proposed client.
+ returned: always
+ type: dict
+ sample: {clientId: "test"}
existing:
- description: Representation of existing client (sample is truncated).
- returned: always
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
+ description: Representation of existing client (sample is truncated).
+ returned: always
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
end_state:
- description: Representation of client after module execution (sample is truncated).
- returned: on success
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
-'''
+ description: Representation of client after module execution (sample is truncated).
+ returned: on success
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
- keycloak_argument_spec, get_token, KeycloakError, is_struct_included
+ keycloak_argument_spec, get_token, KeycloakError
from ansible.module_utils.basic import AnsibleModule
import copy
@@ -805,9 +743,6 @@ def normalise_cr(clientrep, remove_ids=False):
# Avoid the dict passed in to be modified
clientrep = clientrep.copy()
- if 'attributes' in clientrep:
- clientrep['attributes'] = list(sorted(clientrep['attributes']))
-
if 'defaultClientScopes' in clientrep:
clientrep['defaultClientScopes'] = list(sorted(clientrep['defaultClientScopes']))
@@ -823,9 +758,20 @@ def normalise_cr(clientrep, remove_ids=False):
if remove_ids:
mapper.pop('id', None)
+ # Convert bool to string
+ if 'config' in mapper:
+ for key, value in mapper['config'].items():
+ if isinstance(value, bool):
+ mapper['config'][key] = str(value).lower()
+
# Set to a default value.
mapper['consentRequired'] = mapper.get('consentRequired', False)
+ if 'attributes' in clientrep:
+ for key, value in clientrep['attributes'].items():
+ if isinstance(value, bool):
+ clientrep['attributes'][key] = str(value).lower()
+ clientrep['attributes'].pop('client.secret.creation.time', None)
return clientrep
@@ -840,8 +786,11 @@ def sanitize_cr(clientrep):
result['secret'] = 'no_log'
if 'attributes' in result:
attributes = result['attributes']
- if isinstance(attributes, dict) and 'saml.signing.private.key' in attributes:
- attributes['saml.signing.private.key'] = 'no_log'
+ if isinstance(attributes, dict):
+ if 'saml.signing.private.key' in attributes:
+ attributes['saml.signing.private.key'] = 'no_log'
+ if 'saml.encryption.private.key' in attributes:
+ attributes['saml.encryption.private.key'] = 'no_log'
return normalise_cr(result)
@@ -986,7 +935,9 @@ def main():
supports_check_mode=True,
required_one_of=([['client_id', 'id'],
['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
@@ -1015,6 +966,11 @@ def main():
else:
before_client = kc.get_client_by_id(cid, realm=realm)
+ # kc drops the variable 'authorizationServicesEnabled' if set to false
+ # to minimize diff/changes we set it to false if not set by kc
+ if before_client and 'authorizationServicesEnabled' not in before_client:
+ before_client['authorizationServicesEnabled'] = False
+
if before_client is None:
before_client = {}
@@ -1024,13 +980,6 @@ def main():
for client_param in client_params:
new_param_value = module.params.get(client_param)
- # some lists in the Keycloak API are sorted, some are not.
- if isinstance(new_param_value, list):
- if client_param in ['attributes']:
- try:
- new_param_value = sorted(new_param_value)
- except TypeError:
- pass
# Unfortunately, the ansible argument spec checker introduces variables with null values when
# they are not specified
if client_param == 'protocol_mappers':
@@ -1093,7 +1042,7 @@ def main():
if module._diff:
result['diff'] = dict(before=sanitize_cr(before_norm),
after=sanitize_cr(desired_norm))
- result['changed'] = not is_struct_included(desired_norm, before_norm, CLIENT_META_DATA)
+ result['changed'] = desired_norm != before_norm
module.exit_json(**result)
diff --git a/plugins/modules/keycloak_client_rolemapping.py b/plugins/modules/keycloak_client_rolemapping.py
index be419904a7..cb1cad8291 100644
--- a/plugins/modules/keycloak_client_rolemapping.py
+++ b/plugins/modules/keycloak_client_rolemapping.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_client_rolemapping
short_description: Allows administration of Keycloak client_rolemapping with the Keycloak API
@@ -17,126 +16,117 @@ short_description: Allows administration of Keycloak client_rolemapping with the
version_added: 3.5.0
description:
- - This module allows you to add, remove or modify Keycloak client_rolemapping with the Keycloak REST API.
- It requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
-
- - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
- be returned that way by this module. You may pass single values for attributes when calling the module,
- and this will be translated into a list suitable for the API.
-
- - When updating a client_rolemapping, where possible provide the role ID to the module. This removes a lookup
- to the API to translate the name into the role ID.
-
+ - This module allows you to add, remove or modify Keycloak client_rolemapping with the Keycloak REST API. It requires access
+ to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights.
+ In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with
+ the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
+ - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that
+ way by this module. You may pass single values for attributes when calling the module, and this will be translated into
+ a list suitable for the API.
+ - When updating a client_rolemapping, where possible provide the role ID to the module. This removes a lookup to the API
+ to translate the name into the role ID.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the client_rolemapping.
- - On V(present), the client_rolemapping will be created if it does not yet exist, or updated with the parameters you provide.
- - On V(absent), the client_rolemapping will be removed if it exists.
- default: 'present'
- type: str
- choices:
- - present
- - absent
+ state:
+ description:
+ - State of the client_rolemapping.
+ - On V(present), the client_rolemapping will be created if it does not yet exist, or updated with the parameters you
+ provide.
+ - On V(absent), the client_rolemapping will be removed if it exists.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
- realm:
+ realm:
+ type: str
+ description:
+ - They Keycloak realm under which this role_representation resides.
+ default: 'master'
+
+ group_name:
+ type: str
+ description:
+ - Name of the group to be mapped.
+ - This parameter is required (can be replaced by gid for less API call).
+ parents:
+ version_added: "7.1.0"
+ type: list
+ description:
+ - List of parent groups for the group to handle sorted top to bottom.
+ - Set this if your group is a subgroup and you do not provide the GID in O(gid).
+ elements: dict
+ suboptions:
+ id:
type: str
description:
- - They Keycloak realm under which this role_representation resides.
- default: 'master'
-
- group_name:
+ - Identify parent by ID.
+ - Needs less API calls than using O(parents[].name).
+ - A deep parent chain can be started at any point when first given parent is given as ID.
+ - Note that in principle both ID and name can be specified at the same time but current implementation only always
+ use just one of them, with ID being preferred.
+ name:
type: str
description:
- - Name of the group to be mapped.
- - This parameter is required (can be replaced by gid for less API call).
-
- parents:
- version_added: "7.1.0"
- type: list
- description:
- - List of parent groups for the group to handle sorted top to bottom.
- - >-
- Set this if your group is a subgroup and you do not provide the GID in O(gid).
- elements: dict
- suboptions:
- id:
- type: str
- description:
- - Identify parent by ID.
- - Needs less API calls than using O(parents[].name).
- - A deep parent chain can be started at any point when first given parent is given as ID.
- - Note that in principle both ID and name can be specified at the same time
- but current implementation only always use just one of them, with ID
- being preferred.
- name:
- type: str
- description:
- - Identify parent by name.
- - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
- - When giving a parent chain with only names it must be complete up to the top.
- - Note that in principle both ID and name can be specified at the same time
- but current implementation only always use just one of them, with ID
- being preferred.
- gid:
+ - Identify parent by name.
+ - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
+ - When giving a parent chain with only names it must be complete up to the top.
+ - Note that in principle both ID and name can be specified at the same time but current implementation only always
+ use just one of them, with ID being preferred.
+ gid:
+ type: str
+ description:
+ - ID of the group to be mapped.
+ - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of
+ API calls required.
+ client_id:
+ type: str
+ description:
+ - Name of the client to be mapped (different than O(cid)).
+ - This parameter is required (can be replaced by cid for less API call).
+ cid:
+ type: str
+ description:
+ - ID of the client to be mapped.
+ - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of
+ API calls required.
+ roles:
+ description:
+ - Roles to be mapped to the group.
+ type: list
+ elements: dict
+ suboptions:
+ name:
type: str
description:
- - Id of the group to be mapped.
- - This parameter is not required for updating or deleting the rolemapping but
- providing it will reduce the number of API calls required.
-
- client_id:
+ - Name of the role_representation.
+ - This parameter is required only when creating or updating the role_representation.
+ id:
type: str
description:
- - Name of the client to be mapped (different than O(cid)).
- - This parameter is required (can be replaced by cid for less API call).
-
- cid:
- type: str
- description:
- - Id of the client to be mapped.
- - This parameter is not required for updating or deleting the rolemapping but
- providing it will reduce the number of API calls required.
-
- roles:
- description:
- - Roles to be mapped to the group.
- type: list
- elements: dict
- suboptions:
- name:
- type: str
- description:
- - Name of the role_representation.
- - This parameter is required only when creating or updating the role_representation.
- id:
- type: str
- description:
- - The unique identifier for this role_representation.
- - This parameter is not required for updating or deleting a role_representation but
- providing it will reduce the number of API calls required.
-
+ - The unique identifier for this role_representation.
+ - This parameter is not required for updating or deleting a role_representation but providing it will reduce the
+ number of API calls required.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Gaëtan Daubresse (@Gaetan2907)
-'''
+ - Gaëtan Daubresse (@Gaetan2907)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Map a client role to a group, authentication with credentials
community.general.keycloak_client_rolemapping:
realm: MyCustomRealm
@@ -206,50 +196,37 @@ EXAMPLES = '''
- name: role_name2
id: role_id2
delegate_to: localhost
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Role role1 assigned to group group1."
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Role role1 assigned to group group1."
proposed:
- description: Representation of proposed client role mapping.
- returned: always
- type: dict
- sample: {
- clientId: "test"
- }
+ description: Representation of proposed client role mapping.
+ returned: always
+ type: dict
+ sample: {clientId: "test"}
existing:
- description:
- - Representation of existing client role mapping.
- - The sample is truncated.
- returned: always
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
+ description:
+ - Representation of existing client role mapping.
+ - The sample is truncated.
+ returned: always
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
end_state:
- description:
- - Representation of client role mapping after module execution.
- - The sample is truncated.
- returned: on success
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
-'''
+ description:
+ - Representation of client role mapping after module execution.
+ - The sample is truncated.
+ returned: on success
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import (
KeycloakAPI, keycloak_argument_spec, get_token, KeycloakError,
@@ -292,7 +269,9 @@ def main():
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
diff --git a/plugins/modules/keycloak_client_rolescope.py b/plugins/modules/keycloak_client_rolescope.py
index cca72f0ddd..7c87c0664c 100644
--- a/plugins/modules/keycloak_client_rolescope.py
+++ b/plugins/modules/keycloak_client_rolescope.py
@@ -8,81 +8,77 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_client_rolescope
-short_description: Allows administration of Keycloak client roles scope to restrict the usage of certain roles to a other specific client applications.
+short_description: Allows administration of Keycloak client roles scope to restrict the usage of certain roles to a other
+ specific client applications
version_added: 8.6.0
description:
- - This module allows you to add or remove Keycloak roles from clients scope via the Keycloak REST API.
- It requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - Client O(client_id) must have O(community.general.keycloak_client#module:full_scope_allowed) set to V(false).
-
- - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
- be returned that way by this module. You may pass single values for attributes when calling the module,
- and this will be translated into a list suitable for the API.
-
+ - This module allows you to add or remove Keycloak roles from clients scope using the Keycloak REST API. It requires access
+ to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights.
+ In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with
+ the scope tailored to your needs and a user having the expected roles.
+ - Client O(client_id) must have O(community.general.keycloak_client#module:full_scope_allowed) set to V(false).
+ - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that
+ way by this module. You may pass single values for attributes when calling the module, and this will be translated into
+ a list suitable for the API.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the role mapping.
- - On V(present), all roles in O(role_names) will be mapped if not exists yet.
- - On V(absent), all roles mapping in O(role_names) will be removed if it exists.
- default: 'present'
- type: str
- choices:
- - present
- - absent
-
- realm:
- type: str
- description:
- - The Keycloak realm under which clients resides.
- default: 'master'
-
- client_id:
- type: str
- required: true
- description:
- - Roles provided in O(role_names) while be added to this client scope.
-
- client_scope_id:
- type: str
- description:
- - If the O(role_names) are client role, the client ID under which it resides.
- - If this parameter is absent, the roles are considered a realm role.
- role_names:
- required: true
- type: list
- elements: str
- description:
- - Names of roles to manipulate.
- - If O(client_scope_id) is present, all roles must be under this client.
- - If O(client_scope_id) is absent, all roles must be under the realm.
+ state:
+ description:
+ - State of the role mapping.
+ - On V(present), all roles in O(role_names) will be mapped if not exists yet.
+ - On V(absent), all roles mapping in O(role_names) will be removed if it exists.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
+ realm:
+ type: str
+ description:
+ - The Keycloak realm under which clients resides.
+ default: 'master'
+ client_id:
+ type: str
+ required: true
+ description:
+ - Roles provided in O(role_names) while be added to this client scope.
+ client_scope_id:
+ type: str
+ description:
+ - If the O(role_names) are client role, the client ID under which it resides.
+ - If this parameter is absent, the roles are considered a realm role.
+ role_names:
+ required: true
+ type: list
+ elements: str
+ description:
+ - Names of roles to manipulate.
+ - If O(client_scope_id) is present, all roles must be under this client.
+ - If O(client_scope_id) is absent, all roles must be under the realm.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Andre Desrosiers (@desand01)
-'''
+ - Andre Desrosiers (@desand01)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add roles to public client scope
community.general.keycloak_client_rolescope:
auth_keycloak_url: https://auth.example.com/auth
@@ -93,8 +89,8 @@ EXAMPLES = '''
client_id: frontend-client-public
client_scope_id: backend-client-private
role_names:
- - backend-role-admin
- - backend-role-user
+ - backend-role-admin
+ - backend-role-user
- name: Remove roles from public client scope
community.general.keycloak_client_rolescope:
@@ -106,7 +102,7 @@ EXAMPLES = '''
client_id: frontend-client-public
client_scope_id: backend-client-private
role_names:
- - backend-role-admin
+ - backend-role-admin
state: absent
- name: Add realm roles to public client scope
@@ -118,16 +114,16 @@ EXAMPLES = '''
realm: MyCustomRealm
client_id: frontend-client-public
role_names:
- - realm-role-admin
- - realm-role-user
-'''
+ - realm-role-admin
+ - realm-role-user
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Client role scope for frontend-client-public has been updated"
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Client role scope for frontend-client-public has been updated"
end_state:
description: Representation of role role scope after module execution.
@@ -135,22 +131,22 @@ end_state:
type: list
elements: dict
sample: [
- {
- "clientRole": false,
- "composite": false,
- "containerId": "MyCustomRealm",
- "id": "47293104-59a6-46f0-b460-2e9e3c9c424c",
- "name": "backend-role-admin"
- },
- {
- "clientRole": false,
- "composite": false,
- "containerId": "MyCustomRealm",
- "id": "39c62a6d-542c-4715-92d2-41021eb33967",
- "name": "backend-role-user"
- }
+ {
+ "clientRole": false,
+ "composite": false,
+ "containerId": "MyCustomRealm",
+ "id": "47293104-59a6-46f0-b460-2e9e3c9c424c",
+ "name": "backend-role-admin"
+ },
+ {
+ "clientRole": false,
+ "composite": false,
+ "containerId": "MyCustomRealm",
+ "id": "39c62a6d-542c-4715-92d2-41021eb33967",
+ "name": "backend-role-user"
+ }
]
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, \
keycloak_argument_spec, get_token, KeycloakError
diff --git a/plugins/modules/keycloak_clientscope.py b/plugins/modules/keycloak_clientscope.py
index 576a831bdb..4c452d4f2e 100644
--- a/plugins/modules/keycloak_clientscope.py
+++ b/plugins/modules/keycloak_clientscope.py
@@ -8,163 +8,153 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_clientscope
-short_description: Allows administration of Keycloak client_scopes via Keycloak API
+short_description: Allows administration of Keycloak client_scopes using Keycloak API
version_added: 3.4.0
description:
- - This module allows you to add, remove or modify Keycloak client_scopes via the Keycloak REST API.
- It requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
-
- - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
- be returned that way by this module. You may pass single values for attributes when calling the module,
- and this will be translated into a list suitable for the API.
-
- - When updating a client_scope, where possible provide the client_scope ID to the module. This removes a lookup
- to the API to translate the name into the client_scope ID.
-
+ - This module allows you to add, remove or modify Keycloak client_scopes using the Keycloak REST API. It requires access
+ to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights.
+ In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with
+ the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
+ - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that
+ way by this module. You may pass single values for attributes when calling the module, and this will be translated into
+ a list suitable for the API.
+ - When updating a client_scope, where possible provide the client_scope ID to the module. This removes a lookup to the API
+ to translate the name into the client_scope ID.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the client_scope.
- - On V(present), the client_scope will be created if it does not yet exist, or updated with the parameters you provide.
- - On V(absent), the client_scope will be removed if it exists.
- default: 'present'
- type: str
- choices:
- - present
- - absent
-
- name:
- type: str
- description:
- - Name of the client_scope.
- - This parameter is required only when creating or updating the client_scope.
-
- realm:
- type: str
- description:
- - They Keycloak realm under which this client_scope resides.
- default: 'master'
-
- id:
- type: str
- description:
- - The unique identifier for this client_scope.
- - This parameter is not required for updating or deleting a client_scope but
- providing it will reduce the number of API calls required.
-
+ state:
description:
- type: str
- description:
- - Description for this client_scope.
- - This parameter is not required for updating or deleting a client_scope.
+ - State of the client_scope.
+ - On V(present), the client_scope will be created if it does not yet exist, or updated with the parameters you provide.
+ - On V(absent), the client_scope will be removed if it exists.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
- protocol:
+ name:
+ type: str
+ description:
+ - Name of the client_scope.
+ - This parameter is required only when creating or updating the client_scope.
+ realm:
+ type: str
+ description:
+ - They Keycloak realm under which this client_scope resides.
+ default: 'master'
+
+ id:
+ type: str
+ description:
+ - The unique identifier for this client_scope.
+ - This parameter is not required for updating or deleting a client_scope but providing it will reduce the number of
+ API calls required.
+ description:
+ type: str
+ description:
+ - Description for this client_scope.
+ - This parameter is not required for updating or deleting a client_scope.
+ protocol:
+ description:
+ - Type of client.
+ - The V(docker-v2) value was added in community.general 8.6.0.
+ choices: ['openid-connect', 'saml', 'wsfed', 'docker-v2']
+ type: str
+
+ protocol_mappers:
+ description:
+ - A list of dicts defining protocol mappers for this client.
+ - This is C(protocolMappers) in the Keycloak REST API.
+ aliases:
+ - protocolMappers
+ type: list
+ elements: dict
+ suboptions:
+ protocol:
description:
- - Type of client.
- - The V(docker-v2) value was added in community.general 8.6.0.
+ - This specifies for which protocol this protocol mapper.
+ - Is active.
choices: ['openid-connect', 'saml', 'wsfed', 'docker-v2']
type: str
- protocol_mappers:
+ protocolMapper:
description:
- - A list of dicts defining protocol mappers for this client.
- - This is 'protocolMappers' in the Keycloak REST API.
- aliases:
- - protocolMappers
- type: list
- elements: dict
- suboptions:
- protocol:
- description:
- - This specifies for which protocol this protocol mapper.
- - is active.
- choices: ['openid-connect', 'saml', 'wsfed', 'docker-v2']
- type: str
+ - 'The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide
+ since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:'
+ - V(docker-v2-allow-all-mapper).
+ - V(oidc-address-mapper).
+ - V(oidc-full-name-mapper).
+ - V(oidc-group-membership-mapper).
+ - V(oidc-hardcoded-claim-mapper).
+ - V(oidc-hardcoded-role-mapper).
+ - V(oidc-role-name-mapper).
+ - V(oidc-script-based-protocol-mapper).
+ - V(oidc-sha256-pairwise-sub-mapper).
+ - V(oidc-usermodel-attribute-mapper).
+ - V(oidc-usermodel-client-role-mapper).
+ - V(oidc-usermodel-property-mapper).
+ - V(oidc-usermodel-realm-role-mapper).
+ - V(oidc-usersessionmodel-note-mapper).
+ - V(saml-group-membership-mapper).
+ - V(saml-hardcode-attribute-mapper).
+ - V(saml-hardcode-role-mapper).
+ - V(saml-role-list-mapper).
+ - V(saml-role-name-mapper).
+ - V(saml-user-attribute-mapper).
+ - V(saml-user-property-mapper).
+ - V(saml-user-session-note-mapper).
+ - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to
+ Server Info -> Providers and looking under 'protocol-mapper'.
+ type: str
- protocolMapper:
- description:
- - "The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is
- impossible to provide since this may be extended through SPIs by the user of Keycloak,
- by default Keycloak as of 3.4 ships with at least:"
- - V(docker-v2-allow-all-mapper)
- - V(oidc-address-mapper)
- - V(oidc-full-name-mapper)
- - V(oidc-group-membership-mapper)
- - V(oidc-hardcoded-claim-mapper)
- - V(oidc-hardcoded-role-mapper)
- - V(oidc-role-name-mapper)
- - V(oidc-script-based-protocol-mapper)
- - V(oidc-sha256-pairwise-sub-mapper)
- - V(oidc-usermodel-attribute-mapper)
- - V(oidc-usermodel-client-role-mapper)
- - V(oidc-usermodel-property-mapper)
- - V(oidc-usermodel-realm-role-mapper)
- - V(oidc-usersessionmodel-note-mapper)
- - V(saml-group-membership-mapper)
- - V(saml-hardcode-attribute-mapper)
- - V(saml-hardcode-role-mapper)
- - V(saml-role-list-mapper)
- - V(saml-role-name-mapper)
- - V(saml-user-attribute-mapper)
- - V(saml-user-property-mapper)
- - V(saml-user-session-note-mapper)
- - An exhaustive list of available mappers on your installation can be obtained on
- the admin console by going to Server Info -> Providers and looking under
- 'protocol-mapper'.
- type: str
+ name:
+ description:
+ - The name of this protocol mapper.
+ type: str
- name:
- description:
- - The name of this protocol mapper.
- type: str
+ id:
+ description:
+ - Usually a UUID specifying the internal ID of this protocol mapper instance.
+ type: str
- id:
- description:
- - Usually a UUID specifying the internal ID of this protocol mapper instance.
- type: str
-
- config:
- description:
- - Dict specifying the configuration options for the protocol mapper; the
- contents differ depending on the value of O(protocol_mappers[].protocolMapper) and are not documented
- other than by the source of the mappers and its parent class(es). An example is given
- below. It is easiest to obtain valid config values by dumping an already-existing
- protocol mapper configuration through check-mode in the RV(existing) return value.
- type: dict
-
- attributes:
+ config:
+ description:
+ - Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value
+ of O(protocol_mappers[].protocolMapper) and are not documented other than by the source of the mappers and its
+ parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing
+ protocol mapper configuration through check-mode in the RV(existing) return value.
type: dict
- description:
- - A dict of key/value pairs to set as custom attributes for the client_scope.
- - Values may be single values (for example a string) or a list of strings.
+ attributes:
+ type: dict
+ description:
+ - A dict of key/value pairs to set as custom attributes for the client_scope.
+ - Values may be single values (for example a string) or a list of strings.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Gaëtan Daubresse (@Gaetan2907)
-'''
+ - Gaëtan Daubresse (@Gaetan2907)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a Keycloak client_scopes, authentication with credentials
community.general.keycloak_clientscope:
name: my-new-kc-clientscope
@@ -251,54 +241,42 @@ EXAMPLES = '''
protocol: saml
protocolMapper: saml-role-list-mapper
attributes:
- attrib1: value1
- attrib2: value2
- attrib3:
- - with
- - numerous
- - individual
- - list
- - items
+ attrib1: value1
+ attrib2: value2
+ attrib3:
+ - with
+ - numerous
+ - individual
+ - list
+ - items
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Client_scope testclientscope has been updated"
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Client_scope testclientscope has been updated"
proposed:
- description: Representation of proposed client scope.
- returned: always
- type: dict
- sample: {
- clientId: "test"
- }
+ description: Representation of proposed client scope.
+ returned: always
+ type: dict
+ sample: {clientId: "test"}
existing:
- description: Representation of existing client scope (sample is truncated).
- returned: always
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
+ description: Representation of existing client scope (sample is truncated).
+ returned: always
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
end_state:
- description: Representation of client scope after module execution (sample is truncated).
- returned: on success
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
-'''
+ description: Representation of client scope after module execution (sample is truncated).
+ returned: on success
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError, is_struct_included
@@ -317,9 +295,6 @@ def normalise_cr(clientscoperep, remove_ids=False):
# Avoid the dict passed in to be modified
clientscoperep = clientscoperep.copy()
- if 'attributes' in clientscoperep:
- clientscoperep['attributes'] = list(sorted(clientscoperep['attributes']))
-
if 'protocolMappers' in clientscoperep:
clientscoperep['protocolMappers'] = sorted(clientscoperep['protocolMappers'], key=lambda x: (x.get('name'), x.get('protocol'), x.get('protocolMapper')))
for mapper in clientscoperep['protocolMappers']:
@@ -380,7 +355,9 @@ def main():
supports_check_mode=True,
required_one_of=([['id', 'name'],
['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
@@ -418,13 +395,6 @@ def main():
for clientscope_param in clientscope_params:
new_param_value = module.params.get(clientscope_param)
- # some lists in the Keycloak API are sorted, some are not.
- if isinstance(new_param_value, list):
- if clientscope_param in ['attributes']:
- try:
- new_param_value = sorted(new_param_value)
- except TypeError:
- pass
# Unfortunately, the ansible argument spec checker introduces variables with null values when
# they are not specified
if clientscope_param == 'protocol_mappers':
diff --git a/plugins/modules/keycloak_clientscope_type.py b/plugins/modules/keycloak_clientscope_type.py
index 0c919afdad..0e742f676c 100644
--- a/plugins/modules/keycloak_clientscope_type.py
+++ b/plugins/modules/keycloak_clientscope_type.py
@@ -9,27 +9,25 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_clientscope_type
-short_description: Set the type of aclientscope in realm or client via Keycloak API
+short_description: Set the type of aclientscope in realm or client using Keycloak API
version_added: 6.6.0
description:
- - This module allows you to set the type (optional, default) of clientscopes
- via the Keycloak REST API. It requires access to the REST API via OpenID
- Connect; the user connecting and the client being used must have the
- requisite access rights. In a default Keycloak installation, admin-cli and
- an admin user would work, as would a separate client definition with the
- scope tailored to your needs and a user having the expected roles.
-
+ - This module allows you to set the type (optional, default) of clientscopes using the Keycloak REST API. It requires access
+ to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights.
+ In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with
+ the scope tailored to your needs and a user having the expected roles.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
realm:
@@ -40,7 +38,7 @@ options:
client_id:
description:
- - The O(client_id) of the client. If not set the clientscop types are set as a default for the realm.
+ - The O(client_id) of the client. If not set the clientscope types are set as a default for the realm.
aliases:
- clientId
type: str
@@ -59,13 +57,14 @@ options:
extends_documentation_fragment:
- community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
- community.general.attributes
author:
- Simon Pahl (@simonpahl)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Set default client scopes on realm level
community.general.keycloak_clientscope_type:
auth_client_id: admin-cli
@@ -88,42 +87,33 @@ EXAMPLES = '''
default_clientscopes: ['profile', 'roles']
optional_clientscopes: ['phone']
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: ""
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: ""
proposed:
- description: Representation of proposed client-scope types mapping.
- returned: always
- type: dict
- sample: {
- default_clientscopes: ["profile", "role"],
- optional_clientscopes: []
- }
+ description: Representation of proposed client-scope types mapping.
+ returned: always
+ type: dict
+ sample: {default_clientscopes: ["profile", "role"], optional_clientscopes: []}
existing:
- description:
- - Representation of client scopes before module execution.
- returned: always
- type: dict
- sample: {
- default_clientscopes: ["profile", "role"],
- optional_clientscopes: ["phone"]
- }
+ description:
+ - Representation of client scopes before module execution.
+ returned: always
+ type: dict
+ sample: {default_clientscopes: ["profile", "role"], optional_clientscopes: ["phone"]}
end_state:
- description:
- - Representation of client scopes after module execution.
- - The sample is truncated.
- returned: on success
- type: dict
- sample: {
- default_clientscopes: ["profile", "role"],
- optional_clientscopes: []
- }
-'''
+ description:
+ - Representation of client scopes after module execution.
+ - The sample is truncated.
+ returned: on success
+ type: dict
+ sample: {default_clientscopes: ["profile", "role"], optional_clientscopes: []}
+"""
from ansible.module_utils.basic import AnsibleModule
@@ -159,11 +149,13 @@ def keycloak_clientscope_type_module():
['default_clientscopes', 'optional_clientscopes']
]),
required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
mutually_exclusive=[
['token', 'auth_realm'],
['token', 'auth_username'],
['token', 'auth_password']
- ])
+ ],
+ )
return module
@@ -190,6 +182,15 @@ def extract_field(dictionary, field='name'):
return [cs[field] for cs in dictionary]
+def normalize_scopes(scopes):
+ scopes_copy = scopes.copy()
+ if isinstance(scopes_copy.get('default_clientscopes'), list):
+ scopes_copy['default_clientscopes'] = sorted(scopes_copy['default_clientscopes'])
+ if isinstance(scopes_copy.get('optional_clientscopes'), list):
+ scopes_copy['optional_clientscopes'] = sorted(scopes_copy['optional_clientscopes'])
+ return scopes_copy
+
+
def main():
"""
Module keycloak_clientscope_type
@@ -244,7 +245,7 @@ def main():
})
if module._diff:
- result['diff'] = dict(before=result['existing'], after=result['proposed'])
+ result['diff'] = dict(before=normalize_scopes(result['existing']), after=normalize_scopes(result['proposed']))
default_clientscopes_add = clientscopes_to_add(default_clientscopes_existing, default_clientscopes_real)
optional_clientscopes_add = clientscopes_to_add(optional_clientscopes_existing, optional_clientscopes_real)
diff --git a/plugins/modules/keycloak_clientsecret_info.py b/plugins/modules/keycloak_clientsecret_info.py
index c772620351..da07d03248 100644
--- a/plugins/modules/keycloak_clientsecret_info.py
+++ b/plugins/modules/keycloak_clientsecret_info.py
@@ -9,28 +9,25 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_clientsecret_info
-short_description: Retrieve client secret via Keycloak API
+short_description: Retrieve client secret using Keycloak API
version_added: 6.1.0
description:
- - This module allows you to get a Keycloak client secret via the Keycloak
- REST API. It requires access to the REST API via OpenID Connect; the user
- connecting and the client being used must have the requisite access rights.
- In a default Keycloak installation, admin-cli and an admin user would work,
- as would a separate client definition with the scope tailored to your needs
- and a user having the expected roles.
-
- - When retrieving a new client secret, where possible provide the client's
- O(id) (not O(client_id)) to the module. This removes a lookup to the API to
- translate the O(client_id) into the client ID.
-
- - "Note that this module returns the client secret. To avoid this showing up in the logs,
- please add C(no_log: true) to the task."
+ - This module allows you to get a Keycloak client secret using the Keycloak REST API. It requires access to the REST API
+ using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default
+ Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with the scope tailored
+ to your needs and a user having the expected roles.
+ - When retrieving a new client secret, where possible provide the client's O(id) (not O(client_id)) to the module. This
+ removes a lookup to the API to translate the O(client_id) into the client ID.
+ - 'Note that this module returns the client secret. To avoid this showing up in the logs, please add C(no_log: true) to
+ the task.'
+attributes:
+ action_group:
+ version_added: 10.2.0
options:
realm:
@@ -42,14 +39,13 @@ options:
id:
description:
- The unique identifier for this client.
- - This parameter is not required for getting or generating a client secret but
- providing it will reduce the number of API calls required.
+ - This parameter is not required for getting or generating a client secret but providing it will reduce the number of
+ API calls required.
type: str
client_id:
description:
- - The O(client_id) of the client. Passing this instead of O(id) results in an
- extra API call.
+ - The O(client_id) of the client. Passing this instead of O(id) results in an extra API call.
aliases:
- clientId
type: str
@@ -57,15 +53,16 @@ options:
extends_documentation_fragment:
- community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
- community.general.attributes
- community.general.attributes.info_module
author:
- Fynn Chen (@fynncfchen)
- John Cant (@johncant)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get a Keycloak client secret, authentication with credentials
community.general.keycloak_clientsecret_info:
id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd'
@@ -97,16 +94,16 @@ EXAMPLES = '''
token: TOKEN
delegate_to: localhost
no_log: true
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Textual description of whether we succeeded or failed
+ description: Textual description of whether we succeeded or failed.
returned: always
type: str
clientsecret_info:
- description: Representation of the client secret
+ description: Representation of the client secret.
returned: on success
type: complex
contains:
@@ -120,7 +117,7 @@ clientsecret_info:
type: str
returned: always
sample: cUGnX1EIeTtPPAkcyGMv0ncyqDPu68P1
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import (
KeycloakAPI, KeycloakError, get_token)
diff --git a/plugins/modules/keycloak_clientsecret_regenerate.py b/plugins/modules/keycloak_clientsecret_regenerate.py
index 7e8b295433..bb449abc10 100644
--- a/plugins/modules/keycloak_clientsecret_regenerate.py
+++ b/plugins/modules/keycloak_clientsecret_regenerate.py
@@ -9,34 +9,29 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_clientsecret_regenerate
-short_description: Regenerate Keycloak client secret via Keycloak API
+short_description: Regenerate Keycloak client secret using Keycloak API
version_added: 6.1.0
description:
- - This module allows you to regenerate a Keycloak client secret via the
- Keycloak REST API. It requires access to the REST API via OpenID Connect;
- the user connecting and the client being used must have the requisite access
- rights. In a default Keycloak installation, admin-cli and an admin user
- would work, as would a separate client definition with the scope tailored to
- your needs and a user having the expected roles.
-
- - When regenerating a client secret, where possible provide the client's id
- (not client_id) to the module. This removes a lookup to the API to
- translate the client_id into the client ID.
-
- - "Note that this module returns the client secret. To avoid this showing up in the logs,
- please add C(no_log: true) to the task."
-
+ - This module allows you to regenerate a Keycloak client secret using the Keycloak REST API. It requires access to the REST
+ API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default
+ Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with the scope tailored
+ to your needs and a user having the expected roles.
+ - When regenerating a client secret, where possible provide the client's ID (not client_id) to the module. This removes
+ a lookup to the API to translate the client_id into the client ID.
+ - 'Note that this module returns the client secret. To avoid this showing up in the logs, please add C(no_log: true) to
+ the task.'
attributes:
check_mode:
support: full
diff_mode:
support: none
+ action_group:
+ version_added: 10.2.0
options:
realm:
@@ -48,14 +43,13 @@ options:
id:
description:
- The unique identifier for this client.
- - This parameter is not required for getting or generating a client secret but
- providing it will reduce the number of API calls required.
+ - This parameter is not required for getting or generating a client secret but providing it will reduce the number of
+ API calls required.
type: str
client_id:
description:
- - The client_id of the client. Passing this instead of id results in an
- extra API call.
+ - The client_id of the client. Passing this instead of ID results in an extra API call.
aliases:
- clientId
type: str
@@ -63,14 +57,15 @@ options:
extends_documentation_fragment:
- community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
- community.general.attributes
author:
- Fynn Chen (@fynncfchen)
- John Cant (@johncant)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Regenerate a Keycloak client secret, authentication with credentials
community.general.keycloak_clientsecret_regenerate:
id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd'
@@ -102,16 +97,16 @@ EXAMPLES = '''
token: TOKEN
delegate_to: localhost
no_log: true
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
description: Message as to what action was taken.
returned: always
type: str
end_state:
- description: Representation of the client credential after module execution
+ description: Representation of the client credential after module execution.
returned: on success
type: complex
contains:
@@ -125,8 +120,7 @@ end_state:
type: str
returned: always
sample: cUGnX1EIeTtPPAkcyGMv0ncyqDPu68P1
-
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import (
KeycloakAPI, KeycloakError, get_token)
diff --git a/plugins/modules/keycloak_clienttemplate.py b/plugins/modules/keycloak_clienttemplate.py
index 7bffb5cbb6..ae6e61380e 100644
--- a/plugins/modules/keycloak_clienttemplate.py
+++ b/plugins/modules/keycloak_clienttemplate.py
@@ -8,173 +8,165 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_clienttemplate
-short_description: Allows administration of Keycloak client templates via Keycloak API
+short_description: Allows administration of Keycloak client templates using Keycloak API
description:
- - This module allows the administration of Keycloak client templates via the Keycloak REST API. It
- requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html)
-
- - The Keycloak API does not always enforce for only sensible settings to be used -- you can set
- SAML-specific settings on an OpenID Connect client for instance and vice versa. Be careful.
- If you do not specify a setting, usually a sensible default is chosen.
-
+ - This module allows the administration of Keycloak client templates using the Keycloak REST API. It requires access to
+ the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights.
+ In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with
+ the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
+ - The Keycloak API does not always enforce for only sensible settings to be used -- you can set SAML-specific settings on
+ an OpenID Connect client for instance and the other way around. Be careful. If you do not specify a setting, usually a
+ sensible default is chosen.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the client template.
- - On V(present), the client template will be created (or updated if it exists already).
- - On V(absent), the client template will be removed if it exists
- choices: ['present', 'absent']
- default: 'present'
- type: str
-
- id:
- description:
- - Id of client template to be worked on. This is usually a UUID.
- type: str
-
- realm:
- description:
- - Realm this client template is found in.
- type: str
- default: master
-
- name:
- description:
- - Name of the client template.
- type: str
-
+ state:
description:
+ - State of the client template.
+ - On V(present), the client template will be created (or updated if it exists already).
+ - On V(absent), the client template will be removed if it exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+
+ id:
+ description:
+ - ID of client template to be worked on. This is usually a UUID.
+ type: str
+
+ realm:
+ description:
+ - Realm this client template is found in.
+ type: str
+ default: master
+
+ name:
+ description:
+ - Name of the client template.
+ type: str
+
+ description:
+ description:
+ - Description of the client template in Keycloak.
+ type: str
+
+ protocol:
+ description:
+ - Type of client template.
+ - The V(docker-v2) value was added in community.general 8.6.0.
+ choices: ['openid-connect', 'saml', 'docker-v2']
+ type: str
+
+ full_scope_allowed:
+ description:
+ - Is the "Full Scope Allowed" feature set for this client template or not. This is C(fullScopeAllowed) in the Keycloak
+ REST API.
+ type: bool
+
+ protocol_mappers:
+ description:
+ - A list of dicts defining protocol mappers for this client template. This is C(protocolMappers) in the Keycloak REST
+ API.
+ type: list
+ elements: dict
+ suboptions:
+ consentRequired:
description:
- - Description of the client template in Keycloak.
+ - Specifies whether a user needs to provide consent to a client for this mapper to be active.
+ type: bool
+
+ consentText:
+ description:
+ - The human-readable name of the consent the user is presented to accept.
type: str
- protocol:
+ id:
description:
- - Type of client template.
- - The V(docker-v2) value was added in community.general 8.6.0.
+ - Usually a UUID specifying the internal ID of this protocol mapper instance.
+ type: str
+
+ name:
+ description:
+ - The name of this protocol mapper.
+ type: str
+
+ protocol:
+ description:
+ - This specifies for which protocol this protocol mapper is active.
choices: ['openid-connect', 'saml', 'docker-v2']
type: str
- full_scope_allowed:
+ protocolMapper:
description:
- - Is the "Full Scope Allowed" feature set for this client template or not.
- This is 'fullScopeAllowed' in the Keycloak REST API.
- type: bool
+ - 'The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide
+ since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:'
+ - V(docker-v2-allow-all-mapper).
+ - V(oidc-address-mapper).
+ - V(oidc-full-name-mapper).
+ - V(oidc-group-membership-mapper).
+ - V(oidc-hardcoded-claim-mapper).
+ - V(oidc-hardcoded-role-mapper).
+ - V(oidc-role-name-mapper).
+ - V(oidc-script-based-protocol-mapper).
+ - V(oidc-sha256-pairwise-sub-mapper).
+ - V(oidc-usermodel-attribute-mapper).
+ - V(oidc-usermodel-client-role-mapper).
+ - V(oidc-usermodel-property-mapper).
+ - V(oidc-usermodel-realm-role-mapper).
+ - V(oidc-usersessionmodel-note-mapper).
+ - V(saml-group-membership-mapper).
+ - V(saml-hardcode-attribute-mapper).
+ - V(saml-hardcode-role-mapper).
+ - V(saml-role-list-mapper).
+ - V(saml-role-name-mapper).
+ - V(saml-user-attribute-mapper).
+ - V(saml-user-property-mapper).
+ - V(saml-user-session-note-mapper).
+ - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to
+ Server Info -> Providers and looking under 'protocol-mapper'.
+ type: str
- protocol_mappers:
+ config:
description:
- - a list of dicts defining protocol mappers for this client template.
- This is 'protocolMappers' in the Keycloak REST API.
- type: list
- elements: dict
- suboptions:
- consentRequired:
- description:
- - Specifies whether a user needs to provide consent to a client for this mapper to be active.
- type: bool
-
- consentText:
- description:
- - The human-readable name of the consent the user is presented to accept.
- type: str
-
- id:
- description:
- - Usually a UUID specifying the internal ID of this protocol mapper instance.
- type: str
-
- name:
- description:
- - The name of this protocol mapper.
- type: str
-
- protocol:
- description:
- - This specifies for which protocol this protocol mapper is active.
- choices: ['openid-connect', 'saml', 'docker-v2']
- type: str
-
- protocolMapper:
- description:
- - "The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is
- impossible to provide since this may be extended through SPIs by the user of Keycloak,
- by default Keycloak as of 3.4 ships with at least:"
- - V(docker-v2-allow-all-mapper)
- - V(oidc-address-mapper)
- - V(oidc-full-name-mapper)
- - V(oidc-group-membership-mapper)
- - V(oidc-hardcoded-claim-mapper)
- - V(oidc-hardcoded-role-mapper)
- - V(oidc-role-name-mapper)
- - V(oidc-script-based-protocol-mapper)
- - V(oidc-sha256-pairwise-sub-mapper)
- - V(oidc-usermodel-attribute-mapper)
- - V(oidc-usermodel-client-role-mapper)
- - V(oidc-usermodel-property-mapper)
- - V(oidc-usermodel-realm-role-mapper)
- - V(oidc-usersessionmodel-note-mapper)
- - V(saml-group-membership-mapper)
- - V(saml-hardcode-attribute-mapper)
- - V(saml-hardcode-role-mapper)
- - V(saml-role-list-mapper)
- - V(saml-role-name-mapper)
- - V(saml-user-attribute-mapper)
- - V(saml-user-property-mapper)
- - V(saml-user-session-note-mapper)
- - An exhaustive list of available mappers on your installation can be obtained on
- the admin console by going to Server Info -> Providers and looking under
- 'protocol-mapper'.
- type: str
-
- config:
- description:
- - Dict specifying the configuration options for the protocol mapper; the
- contents differ depending on the value of O(protocol_mappers[].protocolMapper) and are not documented
- other than by the source of the mappers and its parent class(es). An example is given
- below. It is easiest to obtain valid config values by dumping an already-existing
- protocol mapper configuration through check-mode in the RV(existing) field.
- type: dict
-
- attributes:
- description:
- - A dict of further attributes for this client template. This can contain various
- configuration settings, though in the default installation of Keycloak as of 3.4, none
- are documented or known, so this is usually empty.
+ - Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value
+ of O(protocol_mappers[].protocolMapper) and are not documented other than by the source of the mappers and its
+ parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing
+ protocol mapper configuration through check-mode in the RV(existing) field.
type: dict
-notes:
- - The Keycloak REST API defines further fields (namely C(bearerOnly), C(consentRequired), C(standardFlowEnabled),
- C(implicitFlowEnabled), C(directAccessGrantsEnabled), C(serviceAccountsEnabled), C(publicClient), and
- C(frontchannelLogout)) which, while available with keycloak_client, do not have any effect on
- Keycloak client-templates and are discarded if supplied with an API request changing client-templates. As such,
- they are not available through this module.
+ attributes:
+ description:
+ - A dict of further attributes for this client template. This can contain various configuration settings, though in
+ the default installation of Keycloak as of 3.4, none are documented or known, so this is usually empty.
+ type: dict
+notes:
+ - The Keycloak REST API defines further fields (namely C(bearerOnly), C(consentRequired), C(standardFlowEnabled), C(implicitFlowEnabled),
+ C(directAccessGrantsEnabled), C(serviceAccountsEnabled), C(publicClient), and C(frontchannelLogout)) which, while available
+ with keycloak_client, do not have any effect on Keycloak client-templates and are discarded if supplied with an API request
+ changing client-templates. As such, they are not available through this module.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Eike Frost (@eikef)
-'''
+ - Eike Frost (@eikef)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create or update Keycloak client template (minimal), authentication with credentials
community.general.keycloak_client:
auth_client_id: admin-cli
@@ -233,47 +225,35 @@ EXAMPLES = '''
full_scope_allowed: false
id: bce6f5e9-d7d3-4955-817e-c5b7f8d65b3f
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Client template testclient has been updated"
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Client template testclient has been updated"
proposed:
- description: Representation of proposed client template.
- returned: always
- type: dict
- sample: {
- name: "test01"
- }
+ description: Representation of proposed client template.
+ returned: always
+ type: dict
+ sample: {name: "test01"}
existing:
- description: Representation of existing client template (sample is truncated).
- returned: always
- type: dict
- sample: {
- "description": "test01",
- "fullScopeAllowed": false,
- "id": "9c3712ab-decd-481e-954f-76da7b006e5f",
- "name": "test01",
- "protocol": "saml"
- }
+ description: Representation of existing client template (sample is truncated).
+ returned: always
+ type: dict
+ sample: {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01",
+ "protocol": "saml"}
end_state:
- description: Representation of client template after module execution (sample is truncated).
- returned: on success
- type: dict
- sample: {
- "description": "test01",
- "fullScopeAllowed": false,
- "id": "9c3712ab-decd-481e-954f-76da7b006e5f",
- "name": "test01",
- "protocol": "saml"
- }
-'''
+ description: Representation of client template after module execution (sample is truncated).
+ returned: on success
+ type: dict
+ sample: {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01",
+ "protocol": "saml"}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError
@@ -317,7 +297,9 @@ def main():
supports_check_mode=True,
required_one_of=([['id', 'name'],
['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
diff --git a/plugins/modules/keycloak_component.py b/plugins/modules/keycloak_component.py
index 375953c3e8..d5a3be2a8e 100644
--- a/plugins/modules/keycloak_component.py
+++ b/plugins/modules/keycloak_component.py
@@ -8,77 +8,76 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_component
-short_description: Allows administration of Keycloak components via Keycloak API
+short_description: Allows administration of Keycloak components using Keycloak API
version_added: 10.0.0
description:
- - This module allows the administration of Keycloak components via the Keycloak REST API. It
- requires access to the REST API via OpenID Connect; the user connecting and the realm being
- used must have the requisite access rights. In a default Keycloak installation, C(admin-cli)
- and an C(admin) user would work, as would a separate realm definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/latest/rest-api/index.html).
- Aliases are provided so camelCased versions can be used as well.
-
+ - This module allows the administration of Keycloak components using the Keycloak REST API. It requires access to the REST
+ API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default
+ Keycloak installation, C(admin-cli) and an C(admin) user would work, as would a separate realm definition with the scope
+ tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/latest/rest-api/index.html). Aliases are provided so camelCased versions can be
+ used as well.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the Keycloak component.
- - On V(present), the component will be created (or updated if it exists already).
- - On V(absent), the component will be removed if it exists.
- choices: ['present', 'absent']
- default: 'present'
- type: str
- name:
- description:
- - Name of the component to create.
- type: str
- required: true
- parent_id:
- description:
- - The parent_id of the component. In practice the ID (name) of the realm.
- type: str
- required: true
- provider_id:
- description:
- - The name of the "provider ID" for the key.
- type: str
- required: true
- provider_type:
- description:
- - The name of the "provider type" for the key. That is, V(org.keycloak.storage.UserStorageProvider),
- V(org.keycloak.userprofile.UserProfileProvider), ...
- - See U(https://www.keycloak.org/docs/latest/server_development/index.html#_providers).
- type: str
- required: true
- config:
- description:
- - Configuration properties for the provider.
- - Contents vary depending on the provider type.
- type: dict
+ state:
+ description:
+ - State of the Keycloak component.
+ - On V(present), the component will be created (or updated if it exists already).
+ - On V(absent), the component will be removed if it exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+ name:
+ description:
+ - Name of the component to create.
+ type: str
+ required: true
+ parent_id:
+ description:
+ - The parent_id of the component. In practice the ID (name) of the realm.
+ type: str
+ required: true
+ provider_id:
+ description:
+ - The name of the "provider ID" for the key.
+ type: str
+ required: true
+ provider_type:
+ description:
+ - The name of the "provider type" for the key. That is, V(org.keycloak.storage.UserStorageProvider), V(org.keycloak.userprofile.UserProfileProvider),
+ ...
+ - See U(https://www.keycloak.org/docs/latest/server_development/index.html#_providers).
+ type: str
+ required: true
+ config:
+ description:
+ - Configuration properties for the provider.
+ - Contents vary depending on the provider type.
+ type: dict
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Björn Bösel (@fivetide)
-'''
+ - Björn Bösel (@fivetide)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Manage Keycloak User Storage Provider
community.general.keycloak_component:
auth_keycloak_url: http://localhost:8080/auth
@@ -94,42 +93,42 @@ EXAMPLES = '''
myCustomKey: "my_custom_key"
cachePolicy: "NO_CACHE"
enabled: true
-'''
+"""
-RETURN = '''
+RETURN = r"""
end_state:
- description: Representation of the keycloak_component after module execution.
- returned: on success
- type: dict
- contains:
- id:
- description: ID of the component.
- type: str
- returned: when O(state=present)
- sample: 5b7ec13f-99da-46ad-8326-ab4c73cf4ce4
- name:
- description: Name of the component.
- type: str
- returned: when O(state=present)
- sample: mykey
- parentId:
- description: ID of the realm this key belongs to.
- type: str
- returned: when O(state=present)
- sample: myrealm
- providerId:
- description: The ID of the key provider.
- type: str
- returned: when O(state=present)
- sample: rsa
- providerType:
- description: The type of provider.
- type: str
- returned: when O(state=present)
- config:
- description: component configuration.
- type: dict
-'''
+ description: Representation of the keycloak_component after module execution.
+ returned: on success
+ type: dict
+ contains:
+ id:
+ description: ID of the component.
+ type: str
+ returned: when O(state=present)
+ sample: 5b7ec13f-99da-46ad-8326-ab4c73cf4ce4
+ name:
+ description: Name of the component.
+ type: str
+ returned: when O(state=present)
+ sample: mykey
+ parentId:
+ description: ID of the realm this key belongs to.
+ type: str
+ returned: when O(state=present)
+ sample: myrealm
+ providerId:
+ description: The ID of the key provider.
+ type: str
+ returned: when O(state=present)
+ sample: rsa
+ providerType:
+ description: The type of provider.
+ type: str
+ returned: when O(state=present)
+ config:
+ description: Component configuration.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError
@@ -157,7 +156,9 @@ def main():
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', end_state={}, diff=dict(before={}, after={}))
diff --git a/plugins/modules/keycloak_component_info.py b/plugins/modules/keycloak_component_info.py
index a788735d98..79a6d58720 100644
--- a/plugins/modules/keycloak_component_info.py
+++ b/plugins/modules/keycloak_component_info.py
@@ -8,100 +8,98 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_component_info
-short_description: Retrive component info in Keycloak
+short_description: Retrieve component info in Keycloak
version_added: 8.2.0
description:
- - This module retrive information on component from Keycloak.
+ - This module retrieve information on component from Keycloak.
+attributes:
+ action_group:
+ version_added: 10.2.0
+
options:
- realm:
- description:
- - The name of the realm.
- required: true
- type: str
- name:
- description:
- - Name of the Component.
- type: str
- provider_type:
- description:
- - Provider type of components.
- - "Example:
- V(org.keycloak.storage.UserStorageProvider),
- V(org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy),
- V(org.keycloak.keys.KeyProvider),
- V(org.keycloak.userprofile.UserProfileProvider),
- V(org.keycloak.storage.ldap.mappers.LDAPStorageMapper)."
- type: str
- parent_id:
- description:
- - Container ID of the components.
- type: str
+ realm:
+ description:
+ - The name of the realm.
+ required: true
+ type: str
+ name:
+ description:
+ - Name of the Component.
+ type: str
+ provider_type:
+ description:
+ - Provider type of components.
+ - 'Examples: V(org.keycloak.storage.UserStorageProvider), V(org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy),
+ V(org.keycloak.keys.KeyProvider), V(org.keycloak.userprofile.UserProfileProvider), V(org.keycloak.storage.ldap.mappers.LDAPStorageMapper).'
+ type: str
+ parent_id:
+ description:
+ - Container ID of the components.
+ type: str
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
+ - community.general.attributes.info_module
author:
- - Andre Desrosiers (@desand01)
-'''
+ - Andre Desrosiers (@desand01)
+"""
-EXAMPLES = '''
- - name: Retrive info of a UserStorageProvider named myldap
- community.general.keycloak_component_info:
- auth_keycloak_url: http://localhost:8080/auth
- auth_sername: admin
- auth_password: password
- auth_realm: master
- realm: myrealm
- name: myldap
- provider_type: org.keycloak.storage.UserStorageProvider
+EXAMPLES = r"""
+- name: Retrive info of a UserStorageProvider named myldap
+ community.general.keycloak_component_info:
+ auth_keycloak_url: http://localhost:8080/auth
+ auth_sername: admin
+ auth_password: password
+ auth_realm: master
+ realm: myrealm
+ name: myldap
+ provider_type: org.keycloak.storage.UserStorageProvider
- - name: Retrive key info component
- community.general.keycloak_component_info:
- auth_keycloak_url: http://localhost:8080/auth
- auth_sername: admin
- auth_password: password
- auth_realm: master
- realm: myrealm
- name: rsa-enc-generated
- provider_type: org.keycloak.keys.KeyProvider
+- name: Retrive key info component
+ community.general.keycloak_component_info:
+ auth_keycloak_url: http://localhost:8080/auth
+ auth_sername: admin
+ auth_password: password
+ auth_realm: master
+ realm: myrealm
+ name: rsa-enc-generated
+ provider_type: org.keycloak.keys.KeyProvider
- - name: Retrive all component from realm master
- community.general.keycloak_component_info:
- auth_keycloak_url: http://localhost:8080/auth
- auth_sername: admin
- auth_password: password
- auth_realm: master
- realm: myrealm
+- name: Retrive all component from realm master
+ community.general.keycloak_component_info:
+ auth_keycloak_url: http://localhost:8080/auth
+ auth_sername: admin
+ auth_password: password
+ auth_realm: master
+ realm: myrealm
- - name: Retrive all sub components of parent component filter by type
- community.general.keycloak_component_info:
- auth_keycloak_url: http://localhost:8080/auth
- auth_sername: admin
- auth_password: password
- auth_realm: master
- realm: myrealm
- parent_id: "075ef2fa-19fc-4a6d-bf4c-249f57365fd2"
- provider_type: "org.keycloak.storage.ldap.mappers.LDAPStorageMapper"
+- name: Retrive all sub components of parent component filter by type
+ community.general.keycloak_component_info:
+ auth_keycloak_url: http://localhost:8080/auth
+ auth_sername: admin
+ auth_password: password
+ auth_realm: master
+ realm: myrealm
+ parent_id: "075ef2fa-19fc-4a6d-bf4c-249f57365fd2"
+ provider_type: "org.keycloak.storage.ldap.mappers.LDAPStorageMapper"
+"""
-
-'''
-
-RETURN = '''
+RETURN = r"""
components:
description: JSON representation of components.
returned: always
type: list
elements: dict
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, \
keycloak_argument_spec, get_token, KeycloakError
diff --git a/plugins/modules/keycloak_group.py b/plugins/modules/keycloak_group.py
index 5398a4b5d0..08d2555745 100644
--- a/plugins/modules/keycloak_group.py
+++ b/plugins/modules/keycloak_group.py
@@ -8,119 +8,106 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_group
-short_description: Allows administration of Keycloak groups via Keycloak API
+short_description: Allows administration of Keycloak groups using Keycloak API
description:
- - This module allows you to add, remove or modify Keycloak groups via the Keycloak REST API.
- It requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/20.0.2/rest-api/index.html).
-
- - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
- be returned that way by this module. You may pass single values for attributes when calling the module,
- and this will be translated into a list suitable for the API.
-
- - When updating a group, where possible provide the group ID to the module. This removes a lookup
- to the API to translate the name into the group ID.
-
+ - This module allows you to add, remove or modify Keycloak groups using the Keycloak REST API. It requires access to the
+ REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In
+ a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with the
+ scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/20.0.2/rest-api/index.html).
+ - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that
+ way by this module. You may pass single values for attributes when calling the module, and this will be translated into
+ a list suitable for the API.
+ - When updating a group, where possible provide the group ID to the module. This removes a lookup to the API to translate
+ the name into the group ID.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the group.
- - On V(present), the group will be created if it does not yet exist, or updated with the parameters you provide.
- - >-
- On V(absent), the group will be removed if it exists. Be aware that absenting
- a group with subgroups will automatically delete all its subgroups too.
- default: 'present'
- type: str
- choices:
- - present
- - absent
+ state:
+ description:
+ - State of the group.
+ - On V(present), the group will be created if it does not yet exist, or updated with the parameters you provide.
+ - On V(absent), the group will be removed if it exists. Be aware that absenting a group with subgroups will automatically
+ delete all its subgroups too.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
- name:
+ name:
+ type: str
+ description:
+ - Name of the group.
+ - This parameter is required only when creating or updating the group.
+ realm:
+ type: str
+ description:
+ - They Keycloak realm under which this group resides.
+ default: 'master'
+
+ id:
+ type: str
+ description:
+ - The unique identifier for this group.
+ - This parameter is not required for updating or deleting a group but providing it will reduce the number of API calls
+ required.
+ attributes:
+ type: dict
+ description:
+ - A dict of key/value pairs to set as custom attributes for the group.
+ - Values may be single values (for example a string) or a list of strings.
+ parents:
+ version_added: "6.4.0"
+ type: list
+ description:
+ - List of parent groups for the group to handle sorted top to bottom.
+ - Set this to create a group as a subgroup of another group or groups (parents) or when accessing an existing subgroup
+ by name.
+ - Not necessary to set when accessing an existing subgroup by its C(ID) because in that case the group can be directly
+ queried without necessarily knowing its parent(s).
+ elements: dict
+ suboptions:
+ id:
type: str
description:
- - Name of the group.
- - This parameter is required only when creating or updating the group.
-
- realm:
+ - Identify parent by ID.
+ - Needs less API calls than using O(parents[].name).
+ - A deep parent chain can be started at any point when first given parent is given as ID.
+ - Note that in principle both ID and name can be specified at the same time but current implementation only always
+ use just one of them, with ID being preferred.
+ name:
type: str
description:
- - They Keycloak realm under which this group resides.
- default: 'master'
-
- id:
- type: str
- description:
- - The unique identifier for this group.
- - This parameter is not required for updating or deleting a group but
- providing it will reduce the number of API calls required.
-
- attributes:
- type: dict
- description:
- - A dict of key/value pairs to set as custom attributes for the group.
- - Values may be single values (e.g. a string) or a list of strings.
-
- parents:
- version_added: "6.4.0"
- type: list
- description:
- - List of parent groups for the group to handle sorted top to bottom.
- - >-
- Set this to create a group as a subgroup of another group or groups (parents) or
- when accessing an existing subgroup by name.
- - >-
- Not necessary to set when accessing an existing subgroup by its C(ID) because in
- that case the group can be directly queried without necessarily knowing its parent(s).
- elements: dict
- suboptions:
- id:
- type: str
- description:
- - Identify parent by ID.
- - Needs less API calls than using O(parents[].name).
- - A deep parent chain can be started at any point when first given parent is given as ID.
- - Note that in principle both ID and name can be specified at the same time
- but current implementation only always use just one of them, with ID
- being preferred.
- name:
- type: str
- description:
- - Identify parent by name.
- - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
- - When giving a parent chain with only names it must be complete up to the top.
- - Note that in principle both ID and name can be specified at the same time
- but current implementation only always use just one of them, with ID
- being preferred.
-
+ - Identify parent by name.
+ - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
+ - When giving a parent chain with only names it must be complete up to the top.
+ - Note that in principle both ID and name can be specified at the same time but current implementation only always
+ use just one of them, with ID being preferred.
notes:
- - Presently, the RV(end_state.realmRoles), RV(end_state.clientRoles), and RV(end_state.access) attributes returned by the Keycloak API
- are read-only for groups. This limitation will be removed in a later version of this module.
-
+ - Presently, the RV(end_state.realmRoles), RV(end_state.clientRoles), and RV(end_state.access) attributes returned by the
+ Keycloak API are read-only for groups. This limitation will be removed in a later version of this module.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Adam Goossens (@adamgoossens)
-'''
+ - Adam Goossens (@adamgoossens)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a Keycloak group, authentication with credentials
community.general.keycloak_group:
name: my-new-kc-group
@@ -188,14 +175,14 @@ EXAMPLES = '''
auth_password: PASSWORD
name: my-new_group
attributes:
- attrib1: value1
- attrib2: value2
- attrib3:
- - with
- - numerous
- - individual
- - list
- - items
+ attrib1: value1
+ attrib2: value2
+ attrib3:
+ - with
+ - numerous
+ - individual
+ - list
+ - items
delegate_to: localhost
- name: Create a Keycloak subgroup of a base group (using parent name)
@@ -255,64 +242,64 @@ EXAMPLES = '''
parents:
- id: "{{ result_new_kcgrp_sub.end_state.id }}"
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
end_state:
- description: Representation of the group after module execution (sample is truncated).
- returned: on success
- type: complex
- contains:
- id:
- description: GUID that identifies the group.
- type: str
- returned: always
- sample: 23f38145-3195-462c-97e7-97041ccea73e
- name:
- description: Name of the group.
- type: str
- returned: always
- sample: grp-test-123
- attributes:
- description: Attributes applied to this group.
- type: dict
- returned: always
- sample:
- attr1: ["val1", "val2", "val3"]
- path:
- description: URI path to the group.
- type: str
- returned: always
- sample: /grp-test-123
- realmRoles:
- description: An array of the realm-level roles granted to this group.
- type: list
- returned: always
- sample: []
- subGroups:
- description: A list of groups that are children of this group. These groups will have the same parameters as
- documented here.
- type: list
- returned: always
- clientRoles:
- description: A list of client-level roles granted to this group.
- type: list
- returned: always
- sample: []
- access:
- description: A dict describing the accesses you have to this group based on the credentials used.
- type: dict
- returned: always
- sample:
- manage: true
- manageMembership: true
- view: true
-'''
+ description: Representation of the group after module execution (sample is truncated).
+ returned: on success
+ type: complex
+ contains:
+ id:
+ description: GUID that identifies the group.
+ type: str
+ returned: always
+ sample: 23f38145-3195-462c-97e7-97041ccea73e
+ name:
+ description: Name of the group.
+ type: str
+ returned: always
+ sample: grp-test-123
+ attributes:
+ description: Attributes applied to this group.
+ type: dict
+ returned: always
+ sample:
+ attr1: ["val1", "val2", "val3"]
+ path:
+ description: URI path to the group.
+ type: str
+ returned: always
+ sample: /grp-test-123
+ realmRoles:
+ description: An array of the realm-level roles granted to this group.
+ type: list
+ returned: always
+ sample: []
+ subGroups:
+ description: A list of groups that are children of this group. These groups will have the same parameters as documented
+ here.
+ type: list
+ returned: always
+ clientRoles:
+ description: A list of client-level roles granted to this group.
+ type: list
+ returned: always
+ sample: []
+ access:
+ description: A dict describing the accesses you have to this group based on the credentials used.
+ type: dict
+ returned: always
+ sample:
+ manage: true
+ manageMembership: true
+ view: true
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError
@@ -348,7 +335,9 @@ def main():
supports_check_mode=True,
required_one_of=([['id', 'name'],
['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, group='')
@@ -369,7 +358,7 @@ def main():
parents = module.params.get('parents')
# attributes in Keycloak have their values returned as lists
- # via the API. attributes is a dict, so we'll transparently convert
+ # using the API. attributes is a dict, so we'll transparently convert
# the values to lists.
if attributes is not None:
for key, val in module.params['attributes'].items():
diff --git a/plugins/modules/keycloak_identity_provider.py b/plugins/modules/keycloak_identity_provider.py
index 609673653b..68a31a227b 100644
--- a/plugins/modules/keycloak_identity_provider.py
+++ b/plugins/modules/keycloak_identity_provider.py
@@ -8,282 +8,282 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_identity_provider
-short_description: Allows administration of Keycloak identity providers via Keycloak API
+short_description: Allows administration of Keycloak identity providers using Keycloak API
version_added: 3.6.0
description:
- - This module allows you to add, remove or modify Keycloak identity providers via the Keycloak REST API.
- It requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/15.0/rest-api/index.html).
-
+ - This module allows you to add, remove or modify Keycloak identity providers using the Keycloak REST API. It requires access
+ to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights.
+ In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with
+ the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/15.0/rest-api/index.html).
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the identity provider.
- - On V(present), the identity provider will be created if it does not yet exist, or updated with the parameters you provide.
- - On V(absent), the identity provider will be removed if it exists.
- default: 'present'
- type: str
- choices:
- - present
- - absent
+ state:
+ description:
+ - State of the identity provider.
+ - On V(present), the identity provider will be created if it does not yet exist, or updated with the parameters you
+ provide.
+ - On V(absent), the identity provider will be removed if it exists.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
- realm:
- description:
- - The Keycloak realm under which this identity provider resides.
- default: 'master'
- type: str
+ realm:
+ description:
+ - The Keycloak realm under which this identity provider resides.
+ default: 'master'
+ type: str
- alias:
- description:
- - The alias uniquely identifies an identity provider and it is also used to build the redirect URI.
- required: true
- type: str
+ alias:
+ description:
+ - The alias uniquely identifies an identity provider and it is also used to build the redirect URI.
+ required: true
+ type: str
- display_name:
+ display_name:
+ description:
+ - Friendly name for identity provider.
+ aliases:
+ - displayName
+ type: str
+
+ enabled:
+ description:
+ - Enable/disable this identity provider.
+ type: bool
+
+ store_token:
+ description:
+ - Enable/disable whether tokens must be stored after authenticating users.
+ aliases:
+ - storeToken
+ type: bool
+
+ add_read_token_role_on_create:
+ description:
+ - Enable/disable whether new users can read any stored tokens. This assigns the C(broker.read-token) role.
+ aliases:
+ - addReadTokenRoleOnCreate
+ type: bool
+
+ trust_email:
+ description:
+ - If enabled, email provided by this provider is not verified even if verification is enabled for the realm.
+ aliases:
+ - trustEmail
+ type: bool
+
+ link_only:
+ description:
+ - If true, users cannot log in through this provider. They can only link to this provider. This is useful if you do
+ not want to allow login from the provider, but want to integrate with a provider.
+ aliases:
+ - linkOnly
+ type: bool
+
+ first_broker_login_flow_alias:
+ description:
+ - Alias of authentication flow, which is triggered after first login with this identity provider.
+ aliases:
+ - firstBrokerLoginFlowAlias
+ type: str
+
+ post_broker_login_flow_alias:
+ description:
+ - Alias of authentication flow, which is triggered after each login with this identity provider.
+ aliases:
+ - postBrokerLoginFlowAlias
+ type: str
+
+ authenticate_by_default:
+ description:
+ - Specifies if this identity provider should be used by default for authentication even before displaying login screen.
+ aliases:
+ - authenticateByDefault
+ type: bool
+
+ provider_id:
+ description:
+ - Protocol used by this provider (supported values are V(oidc) or V(saml)).
+ aliases:
+ - providerId
+ type: str
+
+ config:
+ description:
+ - Dict specifying the configuration options for the provider; the contents differ depending on the value of O(provider_id).
+ Examples are given below for V(oidc) and V(saml). It is easiest to obtain valid config values by dumping an already-existing
+ identity provider configuration through check-mode in the RV(existing) field.
+ type: dict
+ suboptions:
+ hide_on_login_page:
description:
- - Friendly name for identity provider.
+ - If hidden, login with this provider is possible only if requested explicitly, for example using the C(kc_idp_hint)
+ parameter.
aliases:
- - displayName
- type: str
-
- enabled:
- description:
- - Enable/disable this identity provider.
+ - hideOnLoginPage
type: bool
- store_token:
+ gui_order:
description:
- - Enable/disable whether tokens must be stored after authenticating users.
+ - Number defining order of the provider in GUI (for example, on Login page).
aliases:
- - storeToken
- type: bool
+ - guiOrder
+ type: int
- add_read_token_role_on_create:
+ sync_mode:
description:
- - Enable/disable whether new users can read any stored tokens. This assigns the C(broker.read-token) role.
+ - Default sync mode for all mappers. The sync mode determines when user data will be synced using the mappers.
aliases:
- - addReadTokenRoleOnCreate
- type: bool
-
- trust_email:
- description:
- - If enabled, email provided by this provider is not verified even if verification is enabled for the realm.
- aliases:
- - trustEmail
- type: bool
-
- link_only:
- description:
- - If true, users cannot log in through this provider. They can only link to this provider.
- This is useful if you don't want to allow login from the provider, but want to integrate with a provider.
- aliases:
- - linkOnly
- type: bool
-
- first_broker_login_flow_alias:
- description:
- - Alias of authentication flow, which is triggered after first login with this identity provider.
- aliases:
- - firstBrokerLoginFlowAlias
+ - syncMode
type: str
- post_broker_login_flow_alias:
+ issuer:
description:
- - Alias of authentication flow, which is triggered after each login with this identity provider.
- aliases:
- - postBrokerLoginFlowAlias
+ - The issuer identifier for the issuer of the response. If not provided, no validation will be performed.
type: str
- authenticate_by_default:
+ authorizationUrl:
description:
- - Specifies if this identity provider should be used by default for authentication even before displaying login screen.
- aliases:
- - authenticateByDefault
+ - The Authorization URL.
+ type: str
+
+ tokenUrl:
+ description:
+ - The Token URL.
+ type: str
+
+ logoutUrl:
+ description:
+ - End session endpoint to use to logout user from external IDP.
+ type: str
+
+ userInfoUrl:
+ description:
+ - The User Info URL.
+ type: str
+
+ clientAuthMethod:
+ description:
+ - The client authentication method.
+ type: str
+
+ clientId:
+ description:
+ - The client or client identifier registered within the identity provider.
+ type: str
+
+ clientSecret:
+ description:
+ - The client or client secret registered within the identity provider.
+ type: str
+
+ defaultScope:
+ description:
+ - The scopes to be sent when asking for authorization.
+ type: str
+
+ validateSignature:
+ description:
+ - Enable/disable signature validation of external IDP signatures.
type: bool
- provider_id:
+ useJwksUrl:
description:
- - Protocol used by this provider (supported values are V(oidc) or V(saml)).
- aliases:
- - providerId
+ - If the switch is on, identity provider public keys will be downloaded from given JWKS URL.
+ type: bool
+
+ jwksUrl:
+ description:
+ - URL where identity provider keys in JWK format are stored. See JWK specification for more details.
type: str
- config:
+ entityId:
description:
- - Dict specifying the configuration options for the provider; the contents differ depending on the value of O(provider_id).
- Examples are given below for V(oidc) and V(saml). It is easiest to obtain valid config values by dumping an already-existing
- identity provider configuration through check-mode in the RV(existing) field.
+ - The Entity ID that will be used to uniquely identify this SAML Service Provider.
+ type: str
+
+ singleSignOnServiceUrl:
+ description:
+ - The URL that must be used to send authentication requests (SAML AuthnRequest).
+ type: str
+
+ singleLogoutServiceUrl:
+ description:
+ - The URL that must be used to send logout requests.
+ type: str
+
+ backchannelSupported:
+ description:
+ - Does the external IDP support backchannel logout?
+ type: str
+
+ nameIDPolicyFormat:
+ description:
+ - Specifies the URI reference corresponding to a name identifier format.
+ type: str
+
+ principalType:
+ description:
+ - Way to identify and track external users from the assertion.
+ type: str
+
+ mappers:
+ description:
+ - A list of dicts defining mappers associated with this Identity Provider.
+ type: list
+ elements: dict
+ suboptions:
+ id:
+ description:
+ - Unique ID of this mapper.
+ type: str
+
+ name:
+ description:
+ - Name of the mapper.
+ type: str
+
+ identityProviderAlias:
+ description:
+ - Alias of the identity provider for this mapper.
+ type: str
+
+ identityProviderMapper:
+ description:
+ - Type of mapper.
+ type: str
+
+ config:
+ description:
+ - Dict specifying the configuration options for the mapper; the contents differ depending on the value of O(mappers[].identityProviderMapper).
type: dict
- suboptions:
- hide_on_login_page:
- description:
- - If hidden, login with this provider is possible only if requested explicitly, for example using the C(kc_idp_hint) parameter.
- aliases:
- - hideOnLoginPage
- type: bool
-
- gui_order:
- description:
- - Number defining order of the provider in GUI (for example, on Login page).
- aliases:
- - guiOrder
- type: int
-
- sync_mode:
- description:
- - Default sync mode for all mappers. The sync mode determines when user data will be synced using the mappers.
- aliases:
- - syncMode
- type: str
-
- issuer:
- description:
- - The issuer identifier for the issuer of the response. If not provided, no validation will be performed.
- type: str
-
- authorizationUrl:
- description:
- - The Authorization URL.
- type: str
-
- tokenUrl:
- description:
- - The Token URL.
- type: str
-
- logoutUrl:
- description:
- - End session endpoint to use to logout user from external IDP.
- type: str
-
- userInfoUrl:
- description:
- - The User Info URL.
- type: str
-
- clientAuthMethod:
- description:
- - The client authentication method.
- type: str
-
- clientId:
- description:
- - The client or client identifier registered within the identity provider.
- type: str
-
- clientSecret:
- description:
- - The client or client secret registered within the identity provider.
- type: str
-
- defaultScope:
- description:
- - The scopes to be sent when asking for authorization.
- type: str
-
- validateSignature:
- description:
- - Enable/disable signature validation of external IDP signatures.
- type: bool
-
- useJwksUrl:
- description:
- - If the switch is on, identity provider public keys will be downloaded from given JWKS URL.
- type: bool
-
- jwksUrl:
- description:
- - URL where identity provider keys in JWK format are stored. See JWK specification for more details.
- type: str
-
- entityId:
- description:
- - The Entity ID that will be used to uniquely identify this SAML Service Provider.
- type: str
-
- singleSignOnServiceUrl:
- description:
- - The URL that must be used to send authentication requests (SAML AuthnRequest).
- type: str
-
- singleLogoutServiceUrl:
- description:
- - The URL that must be used to send logout requests.
- type: str
-
- backchannelSupported:
- description:
- - Does the external IDP support backchannel logout?
- type: str
-
- nameIDPolicyFormat:
- description:
- - Specifies the URI reference corresponding to a name identifier format.
- type: str
-
- principalType:
- description:
- - Way to identify and track external users from the assertion.
- type: str
-
- mappers:
- description:
- - A list of dicts defining mappers associated with this Identity Provider.
- type: list
- elements: dict
- suboptions:
- id:
- description:
- - Unique ID of this mapper.
- type: str
-
- name:
- description:
- - Name of the mapper.
- type: str
-
- identityProviderAlias:
- description:
- - Alias of the identity provider for this mapper.
- type: str
-
- identityProviderMapper:
- description:
- - Type of mapper.
- type: str
-
- config:
- description:
- - Dict specifying the configuration options for the mapper; the contents differ depending on the value of
- O(mappers[].identityProviderMapper).
- type: dict
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Laurent Paumier (@laurpaum)
-'''
+ - Laurent Paumier (@laurpaum)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create OIDC identity provider, authentication with credentials
community.general.keycloak_identity_provider:
state: present
@@ -344,14 +344,14 @@ EXAMPLES = '''
attribute.friendly.name: User Roles
attribute.name: roles
syncMode: INHERIT
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Identity provider my-idp has been created"
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Identity provider my-idp has been created"
proposed:
description: Representation of proposed identity provider.
@@ -425,7 +425,7 @@ end_state:
"storeToken": false,
"trustEmail": false,
}
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError
@@ -498,7 +498,9 @@ def main():
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
diff --git a/plugins/modules/keycloak_realm.py b/plugins/modules/keycloak_realm.py
index 747acf3081..6d896d4141 100644
--- a/plugins/modules/keycloak_realm.py
+++ b/plugins/modules/keycloak_realm.py
@@ -9,520 +9,518 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_realm
-short_description: Allows administration of Keycloak realm via Keycloak API
+short_description: Allows administration of Keycloak realm using Keycloak API
version_added: 3.0.0
description:
- - This module allows the administration of Keycloak realm via the Keycloak REST API. It
- requires access to the REST API via OpenID Connect; the user connecting and the realm being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate realm definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
- Aliases are provided so camelCased versions can be used as well.
-
- - The Keycloak API does not always sanity check inputs e.g. you can set
- SAML-specific settings on an OpenID Connect client for instance and vice versa. Be careful.
- If you do not specify a setting, usually a sensible default is chosen.
-
+ - This module allows the administration of Keycloak realm using the Keycloak REST API. It requires access to the REST API
+ using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default
+ Keycloak installation, admin-cli and an admin user would work, as would a separate realm definition with the scope tailored
+ to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html). Aliases are provided so camelCased versions can be used
+ as well.
+ - The Keycloak API does not always sanity check inputs, for example you can set SAML-specific settings on an OpenID Connect
+ client for instance and also the other way around. B(Be careful). If you do not specify a setting, usually a sensible
+ default is chosen.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the realm.
- - On V(present), the realm will be created (or updated if it exists already).
- - On V(absent), the realm will be removed if it exists.
- choices: ['present', 'absent']
- default: 'present'
- type: str
+ state:
+ description:
+ - State of the realm.
+ - On V(present), the realm will be created (or updated if it exists already).
+ - On V(absent), the realm will be removed if it exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
- id:
- description:
- - The realm to create.
- type: str
- realm:
- description:
- - The realm name.
- type: str
- access_code_lifespan:
- description:
- - The realm access code lifespan.
- aliases:
- - accessCodeLifespan
- type: int
- access_code_lifespan_login:
- description:
- - The realm access code lifespan login.
- aliases:
- - accessCodeLifespanLogin
- type: int
- access_code_lifespan_user_action:
- description:
- - The realm access code lifespan user action.
- aliases:
- - accessCodeLifespanUserAction
- type: int
- access_token_lifespan:
- description:
- - The realm access token lifespan.
- aliases:
- - accessTokenLifespan
- type: int
- access_token_lifespan_for_implicit_flow:
- description:
- - The realm access token lifespan for implicit flow.
- aliases:
- - accessTokenLifespanForImplicitFlow
- type: int
- account_theme:
- description:
- - The realm account theme.
- aliases:
- - accountTheme
- type: str
- action_token_generated_by_admin_lifespan:
- description:
- - The realm action token generated by admin lifespan.
- aliases:
- - actionTokenGeneratedByAdminLifespan
- type: int
- action_token_generated_by_user_lifespan:
- description:
- - The realm action token generated by user lifespan.
- aliases:
- - actionTokenGeneratedByUserLifespan
- type: int
- admin_events_details_enabled:
- description:
- - The realm admin events details enabled.
- aliases:
- - adminEventsDetailsEnabled
- type: bool
- admin_events_enabled:
- description:
- - The realm admin events enabled.
- aliases:
- - adminEventsEnabled
- type: bool
- admin_theme:
- description:
- - The realm admin theme.
- aliases:
- - adminTheme
- type: str
- attributes:
- description:
- - The realm attributes.
- type: dict
- browser_flow:
- description:
- - The realm browser flow.
- aliases:
- - browserFlow
- type: str
- browser_security_headers:
- description:
- - The realm browser security headers.
- aliases:
- - browserSecurityHeaders
- type: dict
- brute_force_protected:
- description:
- - The realm brute force protected.
- aliases:
- - bruteForceProtected
- type: bool
- client_authentication_flow:
- description:
- - The realm client authentication flow.
- aliases:
- - clientAuthenticationFlow
- type: str
- client_scope_mappings:
- description:
- - The realm client scope mappings.
- aliases:
- - clientScopeMappings
- type: dict
- default_default_client_scopes:
- description:
- - The realm default default client scopes.
- aliases:
- - defaultDefaultClientScopes
- type: list
- elements: str
- default_groups:
- description:
- - The realm default groups.
- aliases:
- - defaultGroups
- type: list
- elements: str
- default_locale:
- description:
- - The realm default locale.
- aliases:
- - defaultLocale
- type: str
- default_optional_client_scopes:
- description:
- - The realm default optional client scopes.
- aliases:
- - defaultOptionalClientScopes
- type: list
- elements: str
- default_roles:
- description:
- - The realm default roles.
- aliases:
- - defaultRoles
- type: list
- elements: str
- default_signature_algorithm:
- description:
- - The realm default signature algorithm.
- aliases:
- - defaultSignatureAlgorithm
- type: str
- direct_grant_flow:
- description:
- - The realm direct grant flow.
- aliases:
- - directGrantFlow
- type: str
- display_name:
- description:
- - The realm display name.
- aliases:
- - displayName
- type: str
- display_name_html:
- description:
- - The realm display name HTML.
- aliases:
- - displayNameHtml
- type: str
- docker_authentication_flow:
- description:
- - The realm docker authentication flow.
- aliases:
- - dockerAuthenticationFlow
- type: str
- duplicate_emails_allowed:
- description:
- - The realm duplicate emails allowed option.
- aliases:
- - duplicateEmailsAllowed
- type: bool
- edit_username_allowed:
- description:
- - The realm edit username allowed option.
- aliases:
- - editUsernameAllowed
- type: bool
- email_theme:
- description:
- - The realm email theme.
- aliases:
- - emailTheme
- type: str
- enabled:
- description:
- - The realm enabled option.
- type: bool
- enabled_event_types:
- description:
- - The realm enabled event types.
- aliases:
- - enabledEventTypes
- type: list
- elements: str
- events_enabled:
- description:
- - Enables or disables login events for this realm.
- aliases:
- - eventsEnabled
- type: bool
- version_added: 3.6.0
- events_expiration:
- description:
- - The realm events expiration.
- aliases:
- - eventsExpiration
- type: int
- events_listeners:
- description:
- - The realm events listeners.
- aliases:
- - eventsListeners
- type: list
- elements: str
- failure_factor:
- description:
- - The realm failure factor.
- aliases:
- - failureFactor
- type: int
- internationalization_enabled:
- description:
- - The realm internationalization enabled option.
- aliases:
- - internationalizationEnabled
- type: bool
- login_theme:
- description:
- - The realm login theme.
- aliases:
- - loginTheme
- type: str
- login_with_email_allowed:
- description:
- - The realm login with email allowed option.
- aliases:
- - loginWithEmailAllowed
- type: bool
- max_delta_time_seconds:
- description:
- - The realm max delta time in seconds.
- aliases:
- - maxDeltaTimeSeconds
- type: int
- max_failure_wait_seconds:
- description:
- - The realm max failure wait in seconds.
- aliases:
- - maxFailureWaitSeconds
- type: int
- minimum_quick_login_wait_seconds:
- description:
- - The realm minimum quick login wait in seconds.
- aliases:
- - minimumQuickLoginWaitSeconds
- type: int
- not_before:
- description:
- - The realm not before.
- aliases:
- - notBefore
- type: int
- offline_session_idle_timeout:
- description:
- - The realm offline session idle timeout.
- aliases:
- - offlineSessionIdleTimeout
- type: int
- offline_session_max_lifespan:
- description:
- - The realm offline session max lifespan.
- aliases:
- - offlineSessionMaxLifespan
- type: int
- offline_session_max_lifespan_enabled:
- description:
- - The realm offline session max lifespan enabled option.
- aliases:
- - offlineSessionMaxLifespanEnabled
- type: bool
- otp_policy_algorithm:
- description:
- - The realm otp policy algorithm.
- aliases:
- - otpPolicyAlgorithm
- type: str
- otp_policy_digits:
- description:
- - The realm otp policy digits.
- aliases:
- - otpPolicyDigits
- type: int
- otp_policy_initial_counter:
- description:
- - The realm otp policy initial counter.
- aliases:
- - otpPolicyInitialCounter
- type: int
- otp_policy_look_ahead_window:
- description:
- - The realm otp policy look ahead window.
- aliases:
- - otpPolicyLookAheadWindow
- type: int
- otp_policy_period:
- description:
- - The realm otp policy period.
- aliases:
- - otpPolicyPeriod
- type: int
- otp_policy_type:
- description:
- - The realm otp policy type.
- aliases:
- - otpPolicyType
- type: str
- otp_supported_applications:
- description:
- - The realm otp supported applications.
- aliases:
- - otpSupportedApplications
- type: list
- elements: str
- password_policy:
- description:
- - The realm password policy.
- aliases:
- - passwordPolicy
- type: str
- organizations_enabled:
- description:
- - Enables support for experimental organization feature.
- aliases:
- - organizationsEnabled
- type: bool
- version_added: 10.0.0
- permanent_lockout:
- description:
- - The realm permanent lockout.
- aliases:
- - permanentLockout
- type: bool
- quick_login_check_milli_seconds:
- description:
- - The realm quick login check in milliseconds.
- aliases:
- - quickLoginCheckMilliSeconds
- type: int
- refresh_token_max_reuse:
- description:
- - The realm refresh token max reuse.
- aliases:
- - refreshTokenMaxReuse
- type: int
- registration_allowed:
- description:
- - The realm registration allowed option.
- aliases:
- - registrationAllowed
- type: bool
- registration_email_as_username:
- description:
- - The realm registration email as username option.
- aliases:
- - registrationEmailAsUsername
- type: bool
- registration_flow:
- description:
- - The realm registration flow.
- aliases:
- - registrationFlow
- type: str
- remember_me:
- description:
- - The realm remember me option.
- aliases:
- - rememberMe
- type: bool
- reset_credentials_flow:
- description:
- - The realm reset credentials flow.
- aliases:
- - resetCredentialsFlow
- type: str
- reset_password_allowed:
- description:
- - The realm reset password allowed option.
- aliases:
- - resetPasswordAllowed
- type: bool
- revoke_refresh_token:
- description:
- - The realm revoke refresh token option.
- aliases:
- - revokeRefreshToken
- type: bool
- smtp_server:
- description:
- - The realm smtp server.
- aliases:
- - smtpServer
- type: dict
- ssl_required:
- description:
- - The realm ssl required option.
- choices: ['all', 'external', 'none']
- aliases:
- - sslRequired
- type: str
- sso_session_idle_timeout:
- description:
- - The realm sso session idle timeout.
- aliases:
- - ssoSessionIdleTimeout
- type: int
- sso_session_idle_timeout_remember_me:
- description:
- - The realm sso session idle timeout remember me.
- aliases:
- - ssoSessionIdleTimeoutRememberMe
- type: int
- sso_session_max_lifespan:
- description:
- - The realm sso session max lifespan.
- aliases:
- - ssoSessionMaxLifespan
- type: int
- sso_session_max_lifespan_remember_me:
- description:
- - The realm sso session max lifespan remember me.
- aliases:
- - ssoSessionMaxLifespanRememberMe
- type: int
- supported_locales:
- description:
- - The realm supported locales.
- aliases:
- - supportedLocales
- type: list
- elements: str
- user_managed_access_allowed:
- description:
- - The realm user managed access allowed option.
- aliases:
- - userManagedAccessAllowed
- type: bool
- verify_email:
- description:
- - The realm verify email option.
- aliases:
- - verifyEmail
- type: bool
- wait_increment_seconds:
- description:
- - The realm wait increment in seconds.
- aliases:
- - waitIncrementSeconds
- type: int
+ id:
+ description:
+ - The realm to create.
+ type: str
+ realm:
+ description:
+ - The realm name.
+ type: str
+ access_code_lifespan:
+ description:
+ - The realm access code lifespan.
+ aliases:
+ - accessCodeLifespan
+ type: int
+ access_code_lifespan_login:
+ description:
+ - The realm access code lifespan login.
+ aliases:
+ - accessCodeLifespanLogin
+ type: int
+ access_code_lifespan_user_action:
+ description:
+ - The realm access code lifespan user action.
+ aliases:
+ - accessCodeLifespanUserAction
+ type: int
+ access_token_lifespan:
+ description:
+ - The realm access token lifespan.
+ aliases:
+ - accessTokenLifespan
+ type: int
+ access_token_lifespan_for_implicit_flow:
+ description:
+ - The realm access token lifespan for implicit flow.
+ aliases:
+ - accessTokenLifespanForImplicitFlow
+ type: int
+ account_theme:
+ description:
+ - The realm account theme.
+ aliases:
+ - accountTheme
+ type: str
+ action_token_generated_by_admin_lifespan:
+ description:
+ - The realm action token generated by admin lifespan.
+ aliases:
+ - actionTokenGeneratedByAdminLifespan
+ type: int
+ action_token_generated_by_user_lifespan:
+ description:
+ - The realm action token generated by user lifespan.
+ aliases:
+ - actionTokenGeneratedByUserLifespan
+ type: int
+ admin_events_details_enabled:
+ description:
+ - The realm admin events details enabled.
+ aliases:
+ - adminEventsDetailsEnabled
+ type: bool
+ admin_events_enabled:
+ description:
+ - The realm admin events enabled.
+ aliases:
+ - adminEventsEnabled
+ type: bool
+ admin_theme:
+ description:
+ - The realm admin theme.
+ aliases:
+ - adminTheme
+ type: str
+ attributes:
+ description:
+ - The realm attributes.
+ type: dict
+ browser_flow:
+ description:
+ - The realm browser flow.
+ aliases:
+ - browserFlow
+ type: str
+ browser_security_headers:
+ description:
+ - The realm browser security headers.
+ aliases:
+ - browserSecurityHeaders
+ type: dict
+ brute_force_protected:
+ description:
+ - The realm brute force protected.
+ aliases:
+ - bruteForceProtected
+ type: bool
+ client_authentication_flow:
+ description:
+ - The realm client authentication flow.
+ aliases:
+ - clientAuthenticationFlow
+ type: str
+ client_scope_mappings:
+ description:
+ - The realm client scope mappings.
+ aliases:
+ - clientScopeMappings
+ type: dict
+ default_default_client_scopes:
+ description:
+ - The realm default default client scopes.
+ aliases:
+ - defaultDefaultClientScopes
+ type: list
+ elements: str
+ default_groups:
+ description:
+ - The realm default groups.
+ aliases:
+ - defaultGroups
+ type: list
+ elements: str
+ default_locale:
+ description:
+ - The realm default locale.
+ aliases:
+ - defaultLocale
+ type: str
+ default_optional_client_scopes:
+ description:
+ - The realm default optional client scopes.
+ aliases:
+ - defaultOptionalClientScopes
+ type: list
+ elements: str
+ default_roles:
+ description:
+ - The realm default roles.
+ aliases:
+ - defaultRoles
+ type: list
+ elements: str
+ default_signature_algorithm:
+ description:
+ - The realm default signature algorithm.
+ aliases:
+ - defaultSignatureAlgorithm
+ type: str
+ direct_grant_flow:
+ description:
+ - The realm direct grant flow.
+ aliases:
+ - directGrantFlow
+ type: str
+ display_name:
+ description:
+ - The realm display name.
+ aliases:
+ - displayName
+ type: str
+ display_name_html:
+ description:
+ - The realm display name HTML.
+ aliases:
+ - displayNameHtml
+ type: str
+ docker_authentication_flow:
+ description:
+ - The realm docker authentication flow.
+ aliases:
+ - dockerAuthenticationFlow
+ type: str
+ duplicate_emails_allowed:
+ description:
+ - The realm duplicate emails allowed option.
+ aliases:
+ - duplicateEmailsAllowed
+ type: bool
+ edit_username_allowed:
+ description:
+ - The realm edit username allowed option.
+ aliases:
+ - editUsernameAllowed
+ type: bool
+ email_theme:
+ description:
+ - The realm email theme.
+ aliases:
+ - emailTheme
+ type: str
+ enabled:
+ description:
+ - The realm enabled option.
+ type: bool
+ enabled_event_types:
+ description:
+ - The realm enabled event types.
+ aliases:
+ - enabledEventTypes
+ type: list
+ elements: str
+ events_enabled:
+ description:
+ - Enables or disables login events for this realm.
+ aliases:
+ - eventsEnabled
+ type: bool
+ version_added: 3.6.0
+ events_expiration:
+ description:
+ - The realm events expiration.
+ aliases:
+ - eventsExpiration
+ type: int
+ events_listeners:
+ description:
+ - The realm events listeners.
+ aliases:
+ - eventsListeners
+ type: list
+ elements: str
+ failure_factor:
+ description:
+ - The realm failure factor.
+ aliases:
+ - failureFactor
+ type: int
+ internationalization_enabled:
+ description:
+ - The realm internationalization enabled option.
+ aliases:
+ - internationalizationEnabled
+ type: bool
+ login_theme:
+ description:
+ - The realm login theme.
+ aliases:
+ - loginTheme
+ type: str
+ login_with_email_allowed:
+ description:
+ - The realm login with email allowed option.
+ aliases:
+ - loginWithEmailAllowed
+ type: bool
+ max_delta_time_seconds:
+ description:
+ - The realm max delta time in seconds.
+ aliases:
+ - maxDeltaTimeSeconds
+ type: int
+ max_failure_wait_seconds:
+ description:
+ - The realm max failure wait in seconds.
+ aliases:
+ - maxFailureWaitSeconds
+ type: int
+ minimum_quick_login_wait_seconds:
+ description:
+ - The realm minimum quick login wait in seconds.
+ aliases:
+ - minimumQuickLoginWaitSeconds
+ type: int
+ not_before:
+ description:
+ - The realm not before.
+ aliases:
+ - notBefore
+ type: int
+ offline_session_idle_timeout:
+ description:
+ - The realm offline session idle timeout.
+ aliases:
+ - offlineSessionIdleTimeout
+ type: int
+ offline_session_max_lifespan:
+ description:
+ - The realm offline session max lifespan.
+ aliases:
+ - offlineSessionMaxLifespan
+ type: int
+ offline_session_max_lifespan_enabled:
+ description:
+ - The realm offline session max lifespan enabled option.
+ aliases:
+ - offlineSessionMaxLifespanEnabled
+ type: bool
+ otp_policy_algorithm:
+ description:
+ - The realm otp policy algorithm.
+ aliases:
+ - otpPolicyAlgorithm
+ type: str
+ otp_policy_digits:
+ description:
+ - The realm otp policy digits.
+ aliases:
+ - otpPolicyDigits
+ type: int
+ otp_policy_initial_counter:
+ description:
+ - The realm otp policy initial counter.
+ aliases:
+ - otpPolicyInitialCounter
+ type: int
+ otp_policy_look_ahead_window:
+ description:
+ - The realm otp policy look ahead window.
+ aliases:
+ - otpPolicyLookAheadWindow
+ type: int
+ otp_policy_period:
+ description:
+ - The realm otp policy period.
+ aliases:
+ - otpPolicyPeriod
+ type: int
+ otp_policy_type:
+ description:
+ - The realm otp policy type.
+ aliases:
+ - otpPolicyType
+ type: str
+ otp_supported_applications:
+ description:
+ - The realm otp supported applications.
+ aliases:
+ - otpSupportedApplications
+ type: list
+ elements: str
+ password_policy:
+ description:
+ - The realm password policy.
+ aliases:
+ - passwordPolicy
+ type: str
+ organizations_enabled:
+ description:
+ - Enables support for experimental organization feature.
+ aliases:
+ - organizationsEnabled
+ type: bool
+ version_added: 10.0.0
+ permanent_lockout:
+ description:
+ - The realm permanent lockout.
+ aliases:
+ - permanentLockout
+ type: bool
+ quick_login_check_milli_seconds:
+ description:
+ - The realm quick login check in milliseconds.
+ aliases:
+ - quickLoginCheckMilliSeconds
+ type: int
+ refresh_token_max_reuse:
+ description:
+ - The realm refresh token max reuse.
+ aliases:
+ - refreshTokenMaxReuse
+ type: int
+ registration_allowed:
+ description:
+ - The realm registration allowed option.
+ aliases:
+ - registrationAllowed
+ type: bool
+ registration_email_as_username:
+ description:
+ - The realm registration email as username option.
+ aliases:
+ - registrationEmailAsUsername
+ type: bool
+ registration_flow:
+ description:
+ - The realm registration flow.
+ aliases:
+ - registrationFlow
+ type: str
+ remember_me:
+ description:
+ - The realm remember me option.
+ aliases:
+ - rememberMe
+ type: bool
+ reset_credentials_flow:
+ description:
+ - The realm reset credentials flow.
+ aliases:
+ - resetCredentialsFlow
+ type: str
+ reset_password_allowed:
+ description:
+ - The realm reset password allowed option.
+ aliases:
+ - resetPasswordAllowed
+ type: bool
+ revoke_refresh_token:
+ description:
+ - The realm revoke refresh token option.
+ aliases:
+ - revokeRefreshToken
+ type: bool
+ smtp_server:
+ description:
+ - The realm smtp server.
+ aliases:
+ - smtpServer
+ type: dict
+ ssl_required:
+ description:
+ - The realm ssl required option.
+ choices: ['all', 'external', 'none']
+ aliases:
+ - sslRequired
+ type: str
+ sso_session_idle_timeout:
+ description:
+ - The realm sso session idle timeout.
+ aliases:
+ - ssoSessionIdleTimeout
+ type: int
+ sso_session_idle_timeout_remember_me:
+ description:
+ - The realm sso session idle timeout remember me.
+ aliases:
+ - ssoSessionIdleTimeoutRememberMe
+ type: int
+ sso_session_max_lifespan:
+ description:
+ - The realm sso session max lifespan.
+ aliases:
+ - ssoSessionMaxLifespan
+ type: int
+ sso_session_max_lifespan_remember_me:
+ description:
+ - The realm sso session max lifespan remember me.
+ aliases:
+ - ssoSessionMaxLifespanRememberMe
+ type: int
+ supported_locales:
+ description:
+ - The realm supported locales.
+ aliases:
+ - supportedLocales
+ type: list
+ elements: str
+ user_managed_access_allowed:
+ description:
+ - The realm user managed access allowed option.
+ aliases:
+ - userManagedAccessAllowed
+ type: bool
+ verify_email:
+ description:
+ - The realm verify email option.
+ aliases:
+ - verifyEmail
+ type: bool
+ wait_increment_seconds:
+ description:
+ - The realm wait increment in seconds.
+ aliases:
+ - waitIncrementSeconds
+ type: int
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Christophe Gilles (@kris2kris)
-'''
+ - Christophe Gilles (@kris2kris)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create or update Keycloak realm (minimal example)
community.general.keycloak_realm:
auth_client_id: admin-cli
@@ -530,8 +528,7 @@ EXAMPLES = '''
auth_realm: master
auth_username: USERNAME
auth_password: PASSWORD
- id: realm
- realm: realm
+ realm: unique_realm_name
state: present
- name: Delete a Keycloak realm
@@ -541,48 +538,35 @@ EXAMPLES = '''
auth_realm: master
auth_username: USERNAME
auth_password: PASSWORD
- id: test
+ realm: unique_realm_name
state: absent
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Realm testrealm has been updated"
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Realm testrealm has been updated"
proposed:
- description: Representation of proposed realm.
- returned: always
- type: dict
- sample: {
- id: "test"
- }
+ description: Representation of proposed realm.
+ returned: always
+ type: dict
+ sample: {realm: "test"}
existing:
- description: Representation of existing realm (sample is truncated).
- returned: always
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
+ description: Representation of existing realm (sample is truncated).
+ returned: always
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
end_state:
- description: Representation of realm after module execution (sample is truncated).
- returned: on success
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
-'''
+ description: Representation of realm after module execution (sample is truncated).
+ returned: on success
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError
@@ -722,7 +706,9 @@ def main():
supports_check_mode=True,
required_one_of=([['id', 'realm', 'enabled'],
['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
@@ -780,9 +766,6 @@ def main():
# Process a creation
result['changed'] = True
- if 'id' not in desired_realm:
- module.fail_json(msg='id needs to be specified when creating a new realm')
-
if module._diff:
result['diff'] = dict(before='', after=sanitize_cr(desired_realm))
@@ -791,11 +774,11 @@ def main():
# create it
kc.create_realm(desired_realm)
- after_realm = kc.get_realm_by_id(desired_realm['id'])
+ after_realm = kc.get_realm_by_id(desired_realm['realm'])
result['end_state'] = sanitize_cr(after_realm)
- result['msg'] = 'Realm %s has been created.' % desired_realm['id']
+ result['msg'] = 'Realm %s has been created.' % desired_realm['realm']
module.exit_json(**result)
else:
@@ -829,7 +812,7 @@ def main():
result['diff'] = dict(before=before_realm_sanitized,
after=sanitize_cr(after_realm))
- result['msg'] = 'Realm %s has been updated.' % desired_realm['id']
+ result['msg'] = 'Realm %s has been updated.' % desired_realm['realm']
module.exit_json(**result)
else:
@@ -848,7 +831,7 @@ def main():
result['proposed'] = {}
result['end_state'] = {}
- result['msg'] = 'Realm %s has been deleted.' % before_realm['id']
+ result['msg'] = 'Realm %s has been deleted.' % before_realm['realm']
module.exit_json(**result)
diff --git a/plugins/modules/keycloak_realm_info.py b/plugins/modules/keycloak_realm_info.py
index 5c2ebb4c9e..838b19513d 100644
--- a/plugins/modules/keycloak_realm_info.py
+++ b/plugins/modules/keycloak_realm_info.py
@@ -8,98 +8,94 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_realm_info
-short_description: Allows obtaining Keycloak realm public information via Keycloak API
+short_description: Allows obtaining Keycloak realm public information using Keycloak API
version_added: 4.3.0
description:
- - This module allows you to get Keycloak realm public information via the Keycloak REST API.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
-
- - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
- be returned that way by this module. You may pass single values for attributes when calling the module,
- and this will be translated into a list suitable for the API.
-
+ - This module allows you to get Keycloak realm public information using the Keycloak REST API.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
+ - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that
+ way by this module. You may pass single values for attributes when calling the module, and this will be translated into
+ a list suitable for the API.
extends_documentation_fragment:
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.attributes
+ - community.general.attributes.info_module
options:
- auth_keycloak_url:
- description:
- - URL to the Keycloak instance.
- type: str
- required: true
- aliases:
- - url
- validate_certs:
- description:
- - Verify TLS certificates (do not disable this in production).
- type: bool
- default: true
+ auth_keycloak_url:
+ description:
+ - URL to the Keycloak instance.
+ type: str
+ required: true
+ aliases:
+ - url
+ validate_certs:
+ description:
+ - Verify TLS certificates (do not disable this in production).
+ type: bool
+ default: true
- realm:
- type: str
- description:
- - They Keycloak realm ID.
- default: 'master'
+ realm:
+ type: str
+ description:
+ - They Keycloak realm ID.
+ default: 'master'
author:
- - Fynn Chen (@fynncfchen)
-'''
+ - Fynn Chen (@fynncfchen)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get a Keycloak public key
community.general.keycloak_realm_info:
realm: MyCustomRealm
auth_keycloak_url: https://auth.example.com/auth
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
realm_info:
- description:
- - Representation of the realm public information.
- returned: always
- type: dict
- contains:
- realm:
- description: Realm ID.
- type: str
- returned: always
- sample: MyRealm
- public_key:
- description: Public key of the realm.
- type: str
- returned: always
- sample: MIIBIjANBgkqhkiG9w0BAQEFAAO...
- token-service:
- description: Token endpoint URL.
- type: str
- returned: always
- sample: https://auth.example.com/auth/realms/MyRealm/protocol/openid-connect
- account-service:
- description: Account console URL.
- type: str
- returned: always
- sample: https://auth.example.com/auth/realms/MyRealm/account
- tokens-not-before:
- description: The token not before.
- type: int
- returned: always
- sample: 0
-'''
+ description:
+ - Representation of the realm public information.
+ returned: always
+ type: dict
+ contains:
+ realm:
+ description: Realm ID.
+ type: str
+ returned: always
+ sample: MyRealm
+ public_key:
+ description: Public key of the realm.
+ type: str
+ returned: always
+ sample: MIIBIjANBgkqhkiG9w0BAQEFAAO...
+ token-service:
+ description: Token endpoint URL.
+ type: str
+ returned: always
+ sample: https://auth.example.com/auth/realms/MyRealm/protocol/openid-connect
+ account-service:
+ description: Account console URL.
+ type: str
+ returned: always
+ sample: https://auth.example.com/auth/realms/MyRealm/account
+ tokens-not-before:
+ description: The token not before.
+ type: int
+ returned: always
+ sample: 0
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/keycloak_realm_key.py b/plugins/modules/keycloak_realm_key.py
index edc8a6068e..97e0af6da5 100644
--- a/plugins/modules/keycloak_realm_key.py
+++ b/plugins/modules/keycloak_realm_key.py
@@ -9,142 +9,130 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_realm_key
-short_description: Allows administration of Keycloak realm keys via Keycloak API
+short_description: Allows administration of Keycloak realm keys using Keycloak API
version_added: 7.5.0
description:
- - This module allows the administration of Keycloak realm keys via the Keycloak REST API. It
- requires access to the REST API via OpenID Connect; the user connecting and the realm being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate realm definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
- Aliases are provided so camelCased versions can be used as well.
-
- - This module is unable to detect changes to the actual cryptographic key after importing it.
- However, if some other property is changed alongside the cryptographic key, then the key
- will also get changed as a side-effect, as the JSON payload needs to include the private key.
- This can be considered either a bug or a feature, as the alternative would be to always
- update the realm key whether it has changed or not.
-
- - If certificate is not explicitly provided it will be dynamically created by Keycloak.
- Therefore comparing the current state of the certificate to the desired state (which may be
- empty) is not possible.
-
+ - This module allows the administration of Keycloak realm keys using the Keycloak REST API. It requires access to the REST
+ API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default
+ Keycloak installation, admin-cli and an admin user would work, as would a separate realm definition with the scope tailored
+ to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html). Aliases are provided so camelCased versions can be used
+ as well.
+ - This module is unable to detect changes to the actual cryptographic key after importing it. However, if some other property
+ is changed alongside the cryptographic key, then the key will also get changed as a side-effect, as the JSON payload needs
+ to include the private key. This can be considered either a bug or a feature, as the alternative would be to always update
+ the realm key whether it has changed or not.
+ - If certificate is not explicitly provided it will be dynamically created by Keycloak. Therefore comparing the current
+ state of the certificate to the desired state (which may be empty) is not possible.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: partial
+ check_mode:
+ support: full
+ diff_mode:
+ support: partial
+ action_group:
+ version_added: 10.2.0
options:
- state:
+ state:
+ description:
+ - State of the keycloak realm key.
+ - On V(present), the realm key will be created (or updated if it exists already).
+ - On V(absent), the realm key will be removed if it exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+ name:
+ description:
+ - Name of the realm key to create.
+ type: str
+ required: true
+ force:
+ description:
+ - Enforce the state of the private key and certificate. This is not automatically the case as this module is unable
+ to determine the current state of the private key and thus cannot trigger an update based on an actual divergence.
+ That said, a private key update may happen even if force is false as a side-effect of other changes.
+ default: false
+ type: bool
+ parent_id:
+ description:
+ - The parent_id of the realm key. In practice the name of the realm.
+ type: str
+ required: true
+ provider_id:
+ description:
+ - The name of the "provider ID" for the key.
+ - The value V(rsa-enc) has been added in community.general 8.2.0.
+ choices: ['rsa', 'rsa-enc']
+ default: 'rsa'
+ type: str
+ config:
+ description:
+ - Dict specifying the key and its properties.
+ type: dict
+ suboptions:
+ active:
description:
- - State of the keycloak realm key.
- - On V(present), the realm key will be created (or updated if it exists already).
- - On V(absent), the realm key will be removed if it exists.
- choices: ['present', 'absent']
- default: 'present'
- type: str
- name:
- description:
- - Name of the realm key to create.
- type: str
- required: true
- force:
- description:
- - Enforce the state of the private key and certificate. This is not automatically the
- case as this module is unable to determine the current state of the private key and
- thus cannot trigger an update based on an actual divergence. That said, a private key
- update may happen even if force is false as a side-effect of other changes.
- default: false
+ - Whether they key is active or inactive. Not to be confused with the state of the Ansible resource managed by the
+ O(state) parameter.
+ default: true
type: bool
- parent_id:
+ enabled:
description:
- - The parent_id of the realm key. In practice the name of the realm.
- type: str
+ - Whether the key is enabled or disabled. Not to be confused with the state of the Ansible resource managed by the
+ O(state) parameter.
+ default: true
+ type: bool
+ priority:
+ description:
+ - The priority of the key.
+ type: int
required: true
- provider_id:
+ algorithm:
description:
- - The name of the "provider ID" for the key.
- - The value V(rsa-enc) has been added in community.general 8.2.0.
- choices: ['rsa', 'rsa-enc']
- default: 'rsa'
+ - Key algorithm.
+ - The values V(RS384), V(RS512), V(PS256), V(PS384), V(PS512), V(RSA1_5), V(RSA-OAEP), V(RSA-OAEP-256) have been
+ added in community.general 8.2.0.
+ default: RS256
+ choices: ['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512', 'RSA1_5', 'RSA-OAEP', 'RSA-OAEP-256']
type: str
- config:
+ private_key:
description:
- - Dict specifying the key and its properties.
- type: dict
- suboptions:
- active:
- description:
- - Whether they key is active or inactive. Not to be confused with the state
- of the Ansible resource managed by the O(state) parameter.
- default: true
- type: bool
- enabled:
- description:
- - Whether the key is enabled or disabled. Not to be confused with the state
- of the Ansible resource managed by the O(state) parameter.
- default: true
- type: bool
- priority:
- description:
- - The priority of the key.
- type: int
- required: true
- algorithm:
- description:
- - Key algorithm.
- - The values V(RS384), V(RS512), V(PS256), V(PS384), V(PS512), V(RSA1_5),
- V(RSA-OAEP), V(RSA-OAEP-256) have been added in community.general 8.2.0.
- default: RS256
- choices: ['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512', 'RSA1_5', 'RSA-OAEP', 'RSA-OAEP-256']
- type: str
- private_key:
- description:
- - The private key as an ASCII string. Contents of the key must match O(config.algorithm)
- and O(provider_id).
- - Please note that the module cannot detect whether the private key specified differs from the
- current state's private key. Use O(force=true) to force the module to update the private key
- if you expect it to be updated.
- required: true
- type: str
- certificate:
- description:
- - A certificate signed with the private key as an ASCII string. Contents of the
- key must match O(config.algorithm) and O(provider_id).
- - If you want Keycloak to automatically generate a certificate using your private key
- then set this to an empty string.
- required: true
- type: str
+ - The private key as an ASCII string. Contents of the key must match O(config.algorithm) and O(provider_id).
+ - Please note that the module cannot detect whether the private key specified differs from the current state's private
+ key. Use O(force=true) to force the module to update the private key if you expect it to be updated.
+ required: true
+ type: str
+ certificate:
+ description:
+ - A certificate signed with the private key as an ASCII string. Contents of the key must match O(config.algorithm)
+ and O(provider_id).
+ - If you want Keycloak to automatically generate a certificate using your private key then set this to an empty
+ string.
+ required: true
+ type: str
notes:
- - Current value of the private key cannot be fetched from Keycloak.
- Therefore comparing its desired state to the current state is not
- possible.
- - If certificate is not explicitly provided it will be dynamically created
- by Keycloak. Therefore comparing the current state of the certificate to
- the desired state (which may be empty) is not possible.
- - Due to the private key and certificate options the module is
- B(not fully idempotent). You can use O(force=true) to force the module
- to always update if you know that the private key might have changed.
-
+ - Current value of the private key cannot be fetched from Keycloak. Therefore comparing its desired state to the current
+ state is not possible.
+ - If certificate is not explicitly provided it will be dynamically created by Keycloak. Therefore comparing the current
+ state of the certificate to the desired state (which may be empty) is not possible.
+ - Due to the private key and certificate options the module is B(not fully idempotent). You can use O(force=true) to force
+ the module to always update if you know that the private key might have changed.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Samuli Seppänen (@mattock)
-'''
+ - Samuli Seppänen (@mattock)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Manage Keycloak realm key (certificate autogenerated by Keycloak)
community.general.keycloak_realm_key:
name: custom
@@ -179,54 +167,49 @@ EXAMPLES = '''
active: true
priority: 120
algorithm: RS256
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
end_state:
- description: Representation of the keycloak_realm_key after module execution.
- returned: on success
- type: dict
- contains:
- id:
- description: ID of the realm key.
- type: str
- returned: when O(state=present)
- sample: 5b7ec13f-99da-46ad-8326-ab4c73cf4ce4
- name:
- description: Name of the realm key.
- type: str
- returned: when O(state=present)
- sample: mykey
- parentId:
- description: ID of the realm this key belongs to.
- type: str
- returned: when O(state=present)
- sample: myrealm
- providerId:
- description: The ID of the key provider.
- type: str
- returned: when O(state=present)
- sample: rsa
- providerType:
- description: The type of provider.
- type: str
- returned: when O(state=present)
- config:
- description: Realm key configuration.
- type: dict
- returned: when O(state=present)
- sample: {
- "active": ["true"],
- "algorithm": ["RS256"],
- "enabled": ["true"],
- "priority": ["140"]
- }
-'''
+ description: Representation of the keycloak_realm_key after module execution.
+ returned: on success
+ type: dict
+ contains:
+ id:
+ description: ID of the realm key.
+ type: str
+ returned: when O(state=present)
+ sample: 5b7ec13f-99da-46ad-8326-ab4c73cf4ce4
+ name:
+ description: Name of the realm key.
+ type: str
+ returned: when O(state=present)
+ sample: mykey
+ parentId:
+ description: ID of the realm this key belongs to.
+ type: str
+ returned: when O(state=present)
+ sample: myrealm
+ providerId:
+ description: The ID of the key provider.
+ type: str
+ returned: when O(state=present)
+ sample: rsa
+ providerType:
+ description: The type of provider.
+ type: str
+ returned: when O(state=present)
+ config:
+ description: Realm key configuration.
+ type: dict
+ returned: when O(state=present)
+ sample: {"active": ["true"], "algorithm": ["RS256"], "enabled": ["true"], "priority": ["140"]}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError
@@ -281,7 +264,9 @@ def main():
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
# Initialize the result object. Only "changed" seems to have special
# meaning for Ansible.
diff --git a/plugins/modules/keycloak_realm_keys_metadata_info.py b/plugins/modules/keycloak_realm_keys_metadata_info.py
index ef4048b891..9946bd88ba 100644
--- a/plugins/modules/keycloak_realm_keys_metadata_info.py
+++ b/plugins/modules/keycloak_realm_keys_metadata_info.py
@@ -9,37 +9,39 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: keycloak_realm_keys_metadata_info
-short_description: Allows obtaining Keycloak realm keys metadata via Keycloak API
+short_description: Allows obtaining Keycloak realm keys metadata using Keycloak API
version_added: 9.3.0
description:
- - This module allows you to get Keycloak realm keys metadata via the Keycloak REST API.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/latest/rest-api/index.html).
+ - This module allows you to get Keycloak realm keys metadata using the Keycloak REST API.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/latest/rest-api/index.html).
+attributes:
+ action_group:
+ version_added: 10.2.0
options:
- realm:
- type: str
- description:
- - They Keycloak realm to fetch keys metadata.
- default: 'master'
+ realm:
+ type: str
+ description:
+ - They Keycloak realm to fetch keys metadata.
+ default: 'master'
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
+ - community.general.attributes.info_module
author:
- - Thomas Bach (@thomasbach-dev)
+ - Thomas Bach (@thomasbach-dev)
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Fetch Keys metadata
community.general.keycloak_realm_keys_metadata_info:
auth_keycloak_url: https://auth.example.com/auth
@@ -62,30 +64,28 @@ EXAMPLES = """
delegate_to: localhost
"""
-RETURN = """
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
+ description: Message as to what action was taken.
+ returned: always
+ type: str
keys_metadata:
- description:
+ description:
- - Representation of the realm keys metadata (see
- U(https://www.keycloak.org/docs-api/latest/rest-api/index.html#KeysMetadataRepresentation)).
-
- returned: always
- type: dict
- contains:
- active:
- description: A mapping (that is, a dict) from key algorithms to UUIDs.
- type: dict
- returned: always
- keys:
- description: A list of dicts providing detailed information on the keys.
- type: list
- elements: dict
- returned: always
+ - Representation of the realm keys metadata (see U(https://www.keycloak.org/docs-api/latest/rest-api/index.html#KeysMetadataRepresentation)).
+ returned: always
+ type: dict
+ contains:
+ active:
+ description: A mapping (that is, a dict) from key algorithms to UUIDs.
+ type: dict
+ returned: always
+ keys:
+ description: A list of dicts providing detailed information on the keys.
+ type: list
+ elements: dict
+ returned: always
"""
from ansible.module_utils.basic import AnsibleModule
@@ -105,7 +105,8 @@ def main():
argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([["token", "auth_realm", "auth_username", "auth_password"]]),
- required_together=([["auth_realm", "auth_username", "auth_password"]]),
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
)
result = dict(changed=False, msg="", keys_metadata="")
diff --git a/plugins/modules/keycloak_realm_rolemapping.py b/plugins/modules/keycloak_realm_rolemapping.py
index 693cf9894a..2937ed0ec0 100644
--- a/plugins/modules/keycloak_realm_rolemapping.py
+++ b/plugins/modules/keycloak_realm_rolemapping.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_realm_rolemapping
short_description: Allows administration of Keycloak realm role mappings into groups with the Keycloak API
@@ -17,116 +16,107 @@ short_description: Allows administration of Keycloak realm role mappings into gr
version_added: 8.2.0
description:
- - This module allows you to add, remove or modify Keycloak realm role
- mappings into groups with the Keycloak REST API. It requires access to the
- REST API via OpenID Connect; the user connecting and the client being used
- must have the requisite access rights. In a default Keycloak installation,
- admin-cli and an admin user would work, as would a separate client
- definition with the scope tailored to your needs and a user having the
- expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/18.0/rest-api/index.html).
-
- - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
- be returned that way by this module. You may pass single values for attributes when calling the module,
- and this will be translated into a list suitable for the API.
-
- - When updating a group_rolemapping, where possible provide the role ID to the module. This removes a lookup
- to the API to translate the name into the role ID.
-
+ - This module allows you to add, remove or modify Keycloak realm role mappings into groups with the Keycloak REST API. It
+ requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite
+ access rights. In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client
+ definition with the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/18.0/rest-api/index.html).
+ - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that
+ way by this module. You may pass single values for attributes when calling the module, and this will be translated into
+ a list suitable for the API.
+ - When updating a group_rolemapping, where possible provide the role ID to the module. This removes a lookup to the API
+ to translate the name into the role ID.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the realm_rolemapping.
- - On C(present), the realm_rolemapping will be created if it does not yet exist, or updated with the parameters you provide.
- - On C(absent), the realm_rolemapping will be removed if it exists.
- default: 'present'
- type: str
- choices:
- - present
- - absent
+ state:
+ description:
+ - State of the realm_rolemapping.
+ - On C(present), the realm_rolemapping will be created if it does not yet exist, or updated with the parameters you
+ provide.
+ - On C(absent), the realm_rolemapping will be removed if it exists.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
- realm:
+ realm:
+ type: str
+ description:
+ - They Keycloak realm under which this role_representation resides.
+ default: 'master'
+
+ group_name:
+ type: str
+ description:
+ - Name of the group to be mapped.
+ - This parameter is required (can be replaced by gid for less API call).
+ parents:
+ type: list
+ description:
+ - List of parent groups for the group to handle sorted top to bottom.
+ - Set this if your group is a subgroup and you do not provide the GID in O(gid).
+ elements: dict
+ suboptions:
+ id:
type: str
description:
- - They Keycloak realm under which this role_representation resides.
- default: 'master'
-
- group_name:
+ - Identify parent by ID.
+ - Needs less API calls than using O(parents[].name).
+ - A deep parent chain can be started at any point when first given parent is given as ID.
+ - Note that in principle both ID and name can be specified at the same time but current implementation only always
+ use just one of them, with ID being preferred.
+ name:
type: str
description:
- - Name of the group to be mapped.
- - This parameter is required (can be replaced by gid for less API call).
-
- parents:
- type: list
- description:
- - List of parent groups for the group to handle sorted top to bottom.
- - >-
- Set this if your group is a subgroup and you do not provide the GID in O(gid).
- elements: dict
- suboptions:
- id:
- type: str
- description:
- - Identify parent by ID.
- - Needs less API calls than using O(parents[].name).
- - A deep parent chain can be started at any point when first given parent is given as ID.
- - Note that in principle both ID and name can be specified at the same time
- but current implementation only always use just one of them, with ID
- being preferred.
- name:
- type: str
- description:
- - Identify parent by name.
- - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
- - When giving a parent chain with only names it must be complete up to the top.
- - Note that in principle both ID and name can be specified at the same time
- but current implementation only always use just one of them, with ID
- being preferred.
- gid:
+ - Identify parent by name.
+ - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
+ - When giving a parent chain with only names it must be complete up to the top.
+ - Note that in principle both ID and name can be specified at the same time but current implementation only always
+ use just one of them, with ID being preferred.
+ gid:
+ type: str
+ description:
+ - ID of the group to be mapped.
+ - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of
+ API calls required.
+ roles:
+ description:
+ - Roles to be mapped to the group.
+ type: list
+ elements: dict
+ suboptions:
+ name:
type: str
description:
- - ID of the group to be mapped.
- - This parameter is not required for updating or deleting the rolemapping but
- providing it will reduce the number of API calls required.
-
- roles:
+ - Name of the role_representation.
+ - This parameter is required only when creating or updating the role_representation.
+ id:
+ type: str
description:
- - Roles to be mapped to the group.
- type: list
- elements: dict
- suboptions:
- name:
- type: str
- description:
- - Name of the role_representation.
- - This parameter is required only when creating or updating the role_representation.
- id:
- type: str
- description:
- - The unique identifier for this role_representation.
- - This parameter is not required for updating or deleting a role_representation but
- providing it will reduce the number of API calls required.
-
+ - The unique identifier for this role_representation.
+ - This parameter is not required for updating or deleting a role_representation but providing it will reduce the
+ number of API calls required.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Gaëtan Daubresse (@Gaetan2907)
- - Marius Huysamen (@mhuysamen)
- - Alexander Groß (@agross)
-'''
+ - Gaëtan Daubresse (@Gaetan2907)
+ - Marius Huysamen (@mhuysamen)
+ - Alexander Groß (@agross)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Map a client role to a group, authentication with credentials
community.general.keycloak_realm_rolemapping:
realm: MyCustomRealm
@@ -192,49 +182,37 @@ EXAMPLES = '''
- name: role_name2
id: role_id2
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Role role1 assigned to group group1."
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Role role1 assigned to group group1."
proposed:
- description: Representation of proposed client role mapping.
- returned: always
- type: dict
- sample: {
- clientId: "test"
- }
+ description: Representation of proposed client role mapping.
+ returned: always
+ type: dict
+ sample: {clientId: "test"}
existing:
- description:
- - Representation of existing client role mapping.
- - The sample is truncated.
- returned: always
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
+ description:
+ - Representation of existing client role mapping.
+ - The sample is truncated.
+ returned: always
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
end_state:
- description:
- - Representation of client role mapping after module execution.
- - The sample is truncated.
- returned: on success
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
-'''
+ description:
+ - Representation of client role mapping after module execution.
+ - The sample is truncated.
+ returned: on success
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import (
KeycloakAPI, keycloak_argument_spec, get_token, KeycloakError,
@@ -275,7 +253,9 @@ def main():
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
diff --git a/plugins/modules/keycloak_role.py b/plugins/modules/keycloak_role.py
index f3e01483f8..93705e2b4e 100644
--- a/plugins/modules/keycloak_role.py
+++ b/plugins/modules/keycloak_role.py
@@ -8,121 +8,116 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_role
-short_description: Allows administration of Keycloak roles via Keycloak API
+short_description: Allows administration of Keycloak roles using Keycloak API
version_added: 3.4.0
description:
- - This module allows you to add, remove or modify Keycloak roles via the Keycloak REST API.
- It requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
-
- - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
- be returned that way by this module. You may pass single values for attributes when calling the module,
- and this will be translated into a list suitable for the API.
-
+ - This module allows you to add, remove or modify Keycloak roles using the Keycloak REST API. It requires access to the
+ REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In
+ a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with the
+ scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
+ - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that
+ way by this module. You may pass single values for attributes when calling the module, and this will be translated into
+ a list suitable for the API.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the role.
- - On V(present), the role will be created if it does not yet exist, or updated with the parameters you provide.
- - On V(absent), the role will be removed if it exists.
- default: 'present'
- type: str
- choices:
- - present
- - absent
+ state:
+ description:
+ - State of the role.
+ - On V(present), the role will be created if it does not yet exist, or updated with the parameters you provide.
+ - On V(absent), the role will be removed if it exists.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
- name:
+ name:
+ type: str
+ required: true
+ description:
+ - Name of the role.
+ - This parameter is required.
+ description:
+ type: str
+ description:
+ - The role description.
+ realm:
+ type: str
+ description:
+ - The Keycloak realm under which this role resides.
+ default: 'master'
+
+ client_id:
+ type: str
+ description:
+ - If the role is a client role, the client ID under which it resides.
+ - If this parameter is absent, the role is considered a realm role.
+ attributes:
+ type: dict
+ description:
+ - A dict of key/value pairs to set as custom attributes for the role.
+ - Values may be single values (for example a string) or a list of strings.
+ composite:
+ description:
+ - If V(true), the role is a composition of other realm and/or client role.
+ default: false
+ type: bool
+ version_added: 7.1.0
+ composites:
+ description:
+ - List of roles to include to the composite realm role.
+ - If the composite role is a client role, the C(clientId) (not ID of the client) must be specified.
+ default: []
+ type: list
+ elements: dict
+ version_added: 7.1.0
+ suboptions:
+ name:
+ description:
+ - Name of the role. This can be the name of a REALM role or a client role.
type: str
required: true
+ client_id:
description:
- - Name of the role.
- - This parameter is required.
-
- description:
+ - Client ID if the role is a client role. Do not include this option for a REALM role.
+ - Use the client ID you can see in the Keycloak console, not the technical ID of the client.
type: str
+ required: false
+ aliases:
+ - clientId
+ state:
description:
- - The role description.
-
- realm:
+ - Create the composite if present, remove it if absent.
type: str
- description:
- - The Keycloak realm under which this role resides.
- default: 'master'
-
- client_id:
- type: str
- description:
- - If the role is a client role, the client id under which it resides.
- - If this parameter is absent, the role is considered a realm role.
-
- attributes:
- type: dict
- description:
- - A dict of key/value pairs to set as custom attributes for the role.
- - Values may be single values (e.g. a string) or a list of strings.
- composite:
- description:
- - If V(true), the role is a composition of other realm and/or client role.
- default: false
- type: bool
- version_added: 7.1.0
- composites:
- description:
- - List of roles to include to the composite realm role.
- - If the composite role is a client role, the C(clientId) (not ID of the client) must be specified.
- default: []
- type: list
- elements: dict
- version_added: 7.1.0
- suboptions:
- name:
- description:
- - Name of the role. This can be the name of a REALM role or a client role.
- type: str
- required: true
- client_id:
- description:
- - Client ID if the role is a client role. Do not include this option for a REALM role.
- - Use the client ID you can see in the Keycloak console, not the technical ID of the client.
- type: str
- required: false
- aliases:
- - clientId
- state:
- description:
- - Create the composite if present, remove it if absent.
- type: str
- choices:
- - present
- - absent
- default: present
+ choices:
+ - present
+ - absent
+ default: present
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Laurent Paumier (@laurpaum)
-'''
+ - Laurent Paumier (@laurpaum)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a Keycloak realm role, authentication with credentials
community.general.keycloak_role:
name: my-new-kc-role
@@ -178,60 +173,44 @@ EXAMPLES = '''
auth_password: PASSWORD
name: my-new-role
attributes:
- attrib1: value1
- attrib2: value2
- attrib3:
- - with
- - numerous
- - individual
- - list
- - items
+ attrib1: value1
+ attrib2: value2
+ attrib3:
+ - with
+ - numerous
+ - individual
+ - list
+ - items
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Role myrole has been updated"
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Role myrole has been updated"
proposed:
- description: Representation of proposed role.
- returned: always
- type: dict
- sample: {
- "description": "My updated test description"
- }
+ description: Representation of proposed role.
+ returned: always
+ type: dict
+ sample: {"description": "My updated test description"}
existing:
- description: Representation of existing role.
- returned: always
- type: dict
- sample: {
- "attributes": {},
- "clientRole": true,
- "composite": false,
- "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a",
- "description": "My client test role",
- "id": "561703dd-0f38-45ff-9a5a-0c978f794547",
- "name": "myrole"
- }
+ description: Representation of existing role.
+ returned: always
+ type: dict
+ sample: {"attributes": {}, "clientRole": true, "composite": false, "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a",
+ "description": "My client test role", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"}
end_state:
- description: Representation of role after module execution (sample is truncated).
- returned: on success
- type: dict
- sample: {
- "attributes": {},
- "clientRole": true,
- "composite": false,
- "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a",
- "description": "My updated client test role",
- "id": "561703dd-0f38-45ff-9a5a-0c978f794547",
- "name": "myrole"
- }
-'''
+ description: Representation of role after module execution (sample is truncated).
+ returned: on success
+ type: dict
+ sample: {"attributes": {}, "clientRole": true, "composite": false, "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a",
+ "description": "My updated client test role", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError, is_struct_included
@@ -269,7 +248,9 @@ def main():
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
@@ -287,7 +268,7 @@ def main():
state = module.params.get('state')
# attributes in Keycloak have their values returned as lists
- # via the API. attributes is a dict, so we'll transparently convert
+ # using the API. attributes is a dict, so we'll transparently convert
# the values to lists.
if module.params.get('attributes') is not None:
for key, val in module.params['attributes'].items():
diff --git a/plugins/modules/keycloak_user.py b/plugins/modules/keycloak_user.py
index 1aeff0da5f..9c2c110903 100644
--- a/plugins/modules/keycloak_user.py
+++ b/plugins/modules/keycloak_user.py
@@ -9,222 +9,224 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_user
short_description: Create and configure a user in Keycloak
description:
- - This module creates, removes, or updates Keycloak users.
+ - This module creates, removes, or updates Keycloak users.
version_added: 7.1.0
options:
- auth_username:
- aliases: []
- realm:
+ auth_username:
+ aliases: []
+ realm:
+ description:
+ - The name of the realm in which is the client.
+ default: master
+ type: str
+ username:
+ description:
+ - Username for the user.
+ required: true
+ type: str
+ id:
+ description:
+ - ID of the user on the Keycloak server if known.
+ type: str
+ enabled:
+ description:
+ - Enabled user.
+ type: bool
+ email_verified:
+ description:
+ - Check the validity of user email.
+ default: false
+ type: bool
+ aliases:
+ - emailVerified
+ first_name:
+ description:
+ - The user's first name.
+ required: false
+ type: str
+ aliases:
+ - firstName
+ last_name:
+ description:
+ - The user's last name.
+ required: false
+ type: str
+ aliases:
+ - lastName
+ email:
+ description:
+ - User email.
+ required: false
+ type: str
+ federation_link:
+ description:
+ - Federation Link.
+ required: false
+ type: str
+ aliases:
+ - federationLink
+ service_account_client_id:
+ description:
+ - Description of the client Application.
+ required: false
+ type: str
+ aliases:
+ - serviceAccountClientId
+ client_consents:
+ description:
+ - Client Authenticator Type.
+ type: list
+ elements: dict
+ default: []
+ aliases:
+ - clientConsents
+ suboptions:
+ client_id:
description:
- - The name of the realm in which is the client.
- default: master
+ - Client ID of the client role. Not the technical ID of the client.
type: str
- username:
- description:
- - Username for the user.
required: true
- type: str
- id:
- description:
- - ID of the user on the Keycloak server if known.
- type: str
- enabled:
- description:
- - Enabled user.
- type: bool
- email_verified:
- description:
- - Check the validity of user email.
- default: false
- type: bool
aliases:
- - emailVerified
- first_name:
+ - clientId
+ roles:
description:
- - The user's first name.
- required: false
- type: str
- aliases:
- - firstName
- last_name:
- description:
- - The user's last name.
- required: false
- type: str
- aliases:
- - lastName
- email:
- description:
- - User email.
- required: false
- type: str
- federation_link:
- description:
- - Federation Link.
- required: false
- type: str
- aliases:
- - federationLink
- service_account_client_id:
- description:
- - Description of the client Application.
- required: false
- type: str
- aliases:
- - serviceAccountClientId
- client_consents:
- description:
- - Client Authenticator Type.
- type: list
- elements: dict
- default: []
- aliases:
- - clientConsents
- suboptions:
- client_id:
- description:
- - Client ID of the client role. Not the technical ID of the client.
- type: str
- required: true
- aliases:
- - clientId
- roles:
- description:
- - List of client roles to assign to the user.
- type: list
- required: true
- elements: str
- groups:
- description:
- - List of groups for the user.
- type: list
- elements: dict
- default: []
- suboptions:
- name:
- description:
- - Name of the group.
- type: str
- state:
- description:
- - Control whether the user must be member of this group or not.
- choices: [ "present", "absent" ]
- default: present
- type: str
- credentials:
- description:
- - User credentials.
- default: []
- type: list
- elements: dict
- suboptions:
- type:
- description:
- - Credential type.
- type: str
- required: true
- value:
- description:
- - Value of the credential.
- type: str
- required: true
- temporary:
- description:
- - If V(true), the users are required to reset their credentials at next login.
- type: bool
- default: false
- required_actions:
- description:
- - RequiredActions user Auth.
- default: []
+ - List of client roles to assign to the user.
type: list
+ required: true
elements: str
- aliases:
- - requiredActions
- federated_identities:
+ groups:
+ description:
+ - List of groups for the user.
+ type: list
+ elements: dict
+ default: []
+ suboptions:
+ name:
description:
- - List of IDPs of user.
- default: []
- type: list
- elements: str
- aliases:
- - federatedIdentities
- attributes:
- description:
- - List of user attributes.
- required: false
- type: list
- elements: dict
- suboptions:
- name:
- description:
- - Name of the attribute.
- type: str
- values:
- description:
- - Values for the attribute as list.
- type: list
- elements: str
- state:
- description:
- - Control whether the attribute must exists or not.
- choices: [ "present", "absent" ]
- default: present
- type: str
- access:
- description:
- - list user access.
- required: false
- type: dict
- disableable_credential_types:
- description:
- - list user Credential Type.
- default: []
- type: list
- elements: str
- aliases:
- - disableableCredentialTypes
- origin:
- description:
- - user origin.
- required: false
+ - Name of the group.
type: str
- self:
+ state:
description:
- - user self administration.
- required: false
- type: str
- state:
- description:
- - Control whether the user should exists or not.
- choices: [ "present", "absent" ]
+ - Control whether the user must be member of this group or not.
+ choices: ["present", "absent"]
default: present
type: str
- force:
+ credentials:
+ description:
+ - User credentials.
+ default: []
+ type: list
+ elements: dict
+ suboptions:
+ type:
description:
- - If V(true), allows to remove user and recreate it.
+ - Credential type.
+ type: str
+ required: true
+ value:
+ description:
+ - Value of the credential.
+ type: str
+ required: true
+ temporary:
+ description:
+ - If V(true), the users are required to reset their credentials at next login.
type: bool
default: false
+ required_actions:
+ description:
+ - RequiredActions user Auth.
+ default: []
+ type: list
+ elements: str
+ aliases:
+ - requiredActions
+ federated_identities:
+ description:
+ - List of IDPs of user.
+ default: []
+ type: list
+ elements: str
+ aliases:
+ - federatedIdentities
+ attributes:
+ description:
+ - List of user attributes.
+ required: false
+ type: list
+ elements: dict
+ suboptions:
+ name:
+ description:
+ - Name of the attribute.
+ type: str
+ values:
+ description:
+ - Values for the attribute as list.
+ type: list
+ elements: str
+ state:
+ description:
+ - Control whether the attribute must exists or not.
+ choices: ["present", "absent"]
+ default: present
+ type: str
+ access:
+ description:
+ - List user access.
+ required: false
+ type: dict
+ disableable_credential_types:
+ description:
+ - List user Credential Type.
+ default: []
+ type: list
+ elements: str
+ aliases:
+ - disableableCredentialTypes
+ origin:
+ description:
+ - User origin.
+ required: false
+ type: str
+ self:
+ description:
+ - User self administration.
+ required: false
+ type: str
+ state:
+ description:
+ - Control whether the user should exists or not.
+ choices: ["present", "absent"]
+ default: present
+ type: str
+ force:
+ description:
+ - If V(true), allows to remove user and recreate it.
+ type: bool
+ default: false
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
notes:
- - The module does not modify the user ID of an existing user.
+ - The module does not modify the user ID of an existing user.
author:
- - Philippe Gauthier (@elfelip)
-'''
+ - Philippe Gauthier (@elfelip)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a user user1
community.general.keycloak_user:
auth_keycloak_url: http://localhost:8080/auth
@@ -238,21 +240,21 @@ EXAMPLES = '''
enabled: true
emailVerified: false
credentials:
- - type: password
- value: password
- temporary: false
+ - type: password
+ value: password
+ temporary: false
attributes:
- - name: attr1
- values:
- - value1
- state: present
- - name: attr2
- values:
- - value2
- state: absent
+ - name: attr1
+ values:
+ - value1
+ state: present
+ - name: attr2
+ values:
+ - value2
+ state: absent
groups:
- - name: group1
- state: present
+ - name: group1
+ state: present
state: present
- name: Re-create a User
@@ -268,21 +270,21 @@ EXAMPLES = '''
enabled: true
emailVerified: false
credentials:
- - type: password
- value: password
- temporary: false
+ - type: password
+ value: password
+ temporary: false
attributes:
- - name: attr1
- values:
- - value1
- state: present
- - name: attr2
- values:
- - value2
- state: absent
+ - name: attr1
+ values:
+ - value1
+ state: present
+ - name: attr2
+ values:
+ - value2
+ state: absent
groups:
- - name: group1
- state: present
+ - name: group1
+ state: present
state: present
- name: Re-create a User
@@ -298,21 +300,21 @@ EXAMPLES = '''
enabled: true
emailVerified: false
credentials:
- - type: password
- value: password
- temporary: false
+ - type: password
+ value: password
+ temporary: false
attributes:
- - name: attr1
- values:
- - value1
- state: present
- - name: attr2
- values:
- - value2
- state: absent
+ - name: attr1
+ values:
+ - value1
+ state: present
+ - name: attr2
+ values:
+ - value2
+ state: absent
groups:
- - name: group1
- state: present
+ - name: group1
+ state: present
state: present
force: true
@@ -324,9 +326,9 @@ EXAMPLES = '''
realm: master
username: user1
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
description: Message as to what action was taken.
returned: always
@@ -341,14 +343,15 @@ existing:
returned: on success
type: dict
end_state:
- description: Representation of the user after module execution
+ description: Representation of the user after module execution.
returned: on success
type: dict
changed:
description: Return V(true) if the operation changed the user on the keycloak server, V(false) otherwise.
returned: always
type: bool
-'''
+"""
+
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError, is_struct_included
from ansible.module_utils.basic import AnsibleModule
@@ -405,7 +408,9 @@ def main():
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
diff --git a/plugins/modules/keycloak_user_federation.py b/plugins/modules/keycloak_user_federation.py
index 215aa7f4ca..78b8b0fdeb 100644
--- a/plugins/modules/keycloak_user_federation.py
+++ b/plugins/modules/keycloak_user_federation.py
@@ -8,620 +8,594 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_user_federation
-short_description: Allows administration of Keycloak user federations via Keycloak API
+short_description: Allows administration of Keycloak user federations using Keycloak API
version_added: 3.7.0
description:
- - This module allows you to add, remove or modify Keycloak user federations via the Keycloak REST API.
- It requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/20.0.2/rest-api/index.html).
-
+ - This module allows you to add, remove or modify Keycloak user federations using the Keycloak REST API. It requires access
+ to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights.
+ In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with
+ the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/20.0.2/rest-api/index.html).
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the user federation.
- - On V(present), the user federation will be created if it does not yet exist, or updated with
- the parameters you provide.
- - On V(absent), the user federation will be removed if it exists.
- default: 'present'
- type: str
- choices:
- - present
- - absent
+ state:
+ description:
+ - State of the user federation.
+ - On V(present), the user federation will be created if it does not yet exist, or updated with the parameters you provide.
+ - On V(absent), the user federation will be removed if it exists.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
- realm:
- description:
- - The Keycloak realm under which this user federation resides.
- default: 'master'
- type: str
+ realm:
+ description:
+ - The Keycloak realm under which this user federation resides.
+ default: 'master'
+ type: str
- id:
- description:
- - The unique ID for this user federation. If left empty, the user federation will be searched
- by its O(name).
- type: str
+ id:
+ description:
+ - The unique ID for this user federation. If left empty, the user federation will be searched by its O(name).
+ type: str
- name:
- description:
- - Display name of provider when linked in admin console.
- type: str
+ name:
+ description:
+ - Display name of provider when linked in admin console.
+ type: str
- provider_id:
- description:
- - Provider for this user federation. Built-in providers are V(ldap), V(kerberos), and V(sssd).
- Custom user storage providers can also be used.
- aliases:
- - providerId
- type: str
+ provider_id:
+ description:
+ - Provider for this user federation. Built-in providers are V(ldap), V(kerberos), and V(sssd). Custom user storage providers
+ can also be used.
+ aliases:
+ - providerId
+ type: str
- provider_type:
- description:
- - Component type for user federation (only supported value is V(org.keycloak.storage.UserStorageProvider)).
- aliases:
- - providerType
- default: org.keycloak.storage.UserStorageProvider
- type: str
+ provider_type:
+ description:
+ - Component type for user federation (only supported value is V(org.keycloak.storage.UserStorageProvider)).
+ aliases:
+ - providerType
+ default: org.keycloak.storage.UserStorageProvider
+ type: str
- parent_id:
- description:
- - Unique ID for the parent of this user federation. Realm ID will be automatically used if left blank.
- aliases:
- - parentId
- type: str
+ parent_id:
+ description:
+ - Unique ID for the parent of this user federation. Realm ID will be automatically used if left blank.
+ aliases:
+ - parentId
+ type: str
- remove_unspecified_mappers:
+ remove_unspecified_mappers:
+ description:
+ - Remove mappers that are not specified in the configuration for this federation.
+ - Set to V(false) to keep mappers that are not listed in O(mappers).
+ type: bool
+ default: true
+ version_added: 9.4.0
+
+ bind_credential_update_mode:
+ description:
+ - The value of the config parameter O(config.bindCredential) is redacted in the Keycloak responses. Comparing the redacted
+ value with the desired value always evaluates to not equal. This means the before and desired states are never equal
+ if the parameter is set.
+ - Set to V(always) to include O(config.bindCredential) in the comparison of before and desired state. Because of the
+ redacted value returned by Keycloak the module will always detect a change and make an update if a O(config.bindCredential)
+ value is set.
+ - Set to V(only_indirect) to exclude O(config.bindCredential) when comparing the before state with the desired state.
+ The value of O(config.bindCredential) will only be updated if there are other changes to the user federation that
+ require an update.
+ type: str
+ default: always
+ choices:
+ - always
+ - only_indirect
+ version_added: 9.5.0
+
+ config:
+ description:
+ - Dict specifying the configuration options for the provider; the contents differ depending on the value of O(provider_id).
+ Examples are given below for V(ldap), V(kerberos) and V(sssd). It is easiest to obtain valid config values by dumping
+ an already-existing user federation configuration through check-mode in the RV(existing) field.
+ - The value V(sssd) has been supported since community.general 4.2.0.
+ type: dict
+ suboptions:
+ enabled:
description:
- - Remove mappers that are not specified in the configuration for this federation.
- - Set to V(false) to keep mappers that are not listed in O(mappers).
- type: bool
+ - Enable/disable this user federation.
default: true
- version_added: 9.4.0
+ type: bool
- bind_credential_update_mode:
+ priority:
description:
- - The value of the config parameter O(config.bindCredential) is redacted in the Keycloak responses.
- Comparing the redacted value with the desired value always evaluates to not equal. This means
- the before and desired states are never equal if the parameter is set.
- - Set to V(always) to include O(config.bindCredential) in the comparison of before and desired state.
- Because of the redacted value returned by Keycloak the module will always detect a change
- and make an update if a O(config.bindCredential) value is set.
- - Set to V(only_indirect) to exclude O(config.bindCredential) when comparing the before state with the
- desired state. The value of O(config.bindCredential) will only be updated if there are other changes
- to the user federation that require an update.
+ - Priority of provider when doing a user lookup. Lowest first.
+ default: 0
+ type: int
+
+ importEnabled:
+ description:
+ - If V(true), LDAP users will be imported into Keycloak DB and synced by the configured sync policies.
+ default: true
+ type: bool
+
+ editMode:
+ description:
+ - V(READ_ONLY) is a read-only LDAP store. V(WRITABLE) means data will be synced back to LDAP on demand. V(UNSYNCED)
+ means user data will be imported, but not synced back to LDAP.
type: str
- default: always
choices:
- - always
- - only_indirect
+ - READ_ONLY
+ - WRITABLE
+ - UNSYNCED
+
+ syncRegistrations:
+ description:
+ - Should newly created users be created within LDAP store? Priority effects which provider is chosen to sync the
+ new user.
+ default: false
+ type: bool
+
+ vendor:
+ description:
+ - LDAP vendor (provider).
+ - Use short name. For instance, write V(rhds) for "Red Hat Directory Server".
+ type: str
+
+ usernameLDAPAttribute:
+ description:
+ - Name of LDAP attribute, which is mapped as Keycloak username. For many LDAP server vendors it can be V(uid). For
+ Active directory it can be V(sAMAccountName) or V(cn). The attribute should be filled for all LDAP user records
+ you want to import from LDAP to Keycloak.
+ type: str
+
+ rdnLDAPAttribute:
+ description:
+ - Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it is the same as Username
+ LDAP attribute, however it is not required. For example for Active directory, it is common to use V(cn) as RDN
+ attribute when username attribute might be V(sAMAccountName).
+ type: str
+
+ uuidLDAPAttribute:
+ description:
+ - Name of LDAP attribute, which is used as unique object identifier (UUID) for objects in LDAP. For many LDAP server
+ vendors, it is V(entryUUID); however some are different. For example for Active directory it should be V(objectGUID).
+ If your LDAP server does not support the notion of UUID, you can use any other attribute that is supposed to be
+ unique among LDAP users in tree.
+ type: str
+
+ userObjectClasses:
+ description:
+ - All values of LDAP objectClass attribute for users in LDAP divided by comma. For example V(inetOrgPerson, organizationalPerson).
+ Newly created Keycloak users will be written to LDAP with all those object classes and existing LDAP user records
+ are found just if they contain all those object classes.
+ type: str
+
+ connectionUrl:
+ description:
+ - Connection URL to your LDAP server.
+ type: str
+
+ usersDn:
+ description:
+ - Full DN of LDAP tree where your users are. This DN is the parent of LDAP users.
+ type: str
+
+ customUserSearchFilter:
+ description:
+ - Additional LDAP Filter for filtering searched users. Leave this empty if you do not need additional filter.
+ type: str
+
+ searchScope:
+ description:
+ - For one level, the search applies only for users in the DNs specified by User DNs. For subtree, the search applies
+ to the whole subtree. See LDAP documentation for more details.
+ default: '1'
+ type: str
+ choices:
+ - '1'
+ - '2'
+
+ authType:
+ description:
+ - Type of the Authentication method used during LDAP Bind operation. It is used in most of the requests sent to
+ the LDAP server.
+ default: 'none'
+ type: str
+ choices:
+ - none
+ - simple
+
+ bindDn:
+ description:
+ - DN of LDAP user which will be used by Keycloak to access LDAP server.
+ type: str
+
+ bindCredential:
+ description:
+ - Password of LDAP admin.
+ type: str
+
+ startTls:
+ description:
+ - Encrypts the connection to LDAP using STARTTLS, which will disable connection pooling.
+ default: false
+ type: bool
+
+ usePasswordModifyExtendedOp:
+ description:
+ - Use the LDAPv3 Password Modify Extended Operation (RFC-3062). The password modify extended operation usually requires
+ that LDAP user already has password in the LDAP server. So when this is used with 'Sync Registrations', it can
+ be good to add also 'Hardcoded LDAP attribute mapper' with randomly generated initial password.
+ default: false
+ type: bool
+
+ validatePasswordPolicy:
+ description:
+ - Determines if Keycloak should validate the password with the realm password policy before updating it.
+ default: false
+ type: bool
+
+ trustEmail:
+ description:
+ - If enabled, email provided by this provider is not verified even if verification is enabled for the realm.
+ default: false
+ type: bool
+
+ useTruststoreSpi:
+ description:
+ - Specifies whether LDAP connection will use the truststore SPI with the truststore configured in standalone.xml/domain.xml.
+ V(always) means that it will always use it. V(never) means that it will not use it. V(ldapsOnly) means that it
+ will use if your connection URL use ldaps.
+ - Note even if standalone.xml/domain.xml is not configured, the default Java cacerts or certificate specified by
+ C(javax.net.ssl.trustStore) property will be used.
+ default: ldapsOnly
+ type: str
+ choices:
+ - always
+ - ldapsOnly
+ - never
+
+ connectionTimeout:
+ description:
+ - LDAP Connection Timeout in milliseconds.
+ type: int
+
+ readTimeout:
+ description:
+ - LDAP Read Timeout in milliseconds. This timeout applies for LDAP read operations.
+ type: int
+
+ pagination:
+ description:
+ - Does the LDAP server support pagination.
+ default: true
+ type: bool
+
+ connectionPooling:
+ description:
+ - Determines if Keycloak should use connection pooling for accessing LDAP server.
+ default: true
+ type: bool
+
+ connectionPoolingAuthentication:
+ description:
+ - A list of space-separated authentication types of connections that may be pooled.
+ type: str
+ choices:
+ - none
+ - simple
+ - DIGEST-MD5
+
+ connectionPoolingDebug:
+ description:
+ - A string that indicates the level of debug output to produce. Example valid values are V(fine) (trace connection
+ creation and removal) and V(all) (all debugging information).
+ type: str
+
+ connectionPoolingInitSize:
+ description:
+ - The number of connections per connection identity to create when initially creating a connection for the identity.
+ type: int
+
+ connectionPoolingMaxSize:
+ description:
+ - The maximum number of connections per connection identity that can be maintained concurrently.
+ type: int
+
+ connectionPoolingPrefSize:
+ description:
+ - The preferred number of connections per connection identity that should be maintained concurrently.
+ type: int
+
+ connectionPoolingProtocol:
+ description:
+ - A list of space-separated protocol types of connections that may be pooled. Valid types are V(plain) and V(ssl).
+ type: str
+
+ connectionPoolingTimeout:
+ description:
+ - The number of milliseconds that an idle connection may remain in the pool without being closed and removed from
+ the pool.
+ type: int
+
+ allowKerberosAuthentication:
+ description:
+ - Enable/disable HTTP authentication of users with SPNEGO/Kerberos tokens. The data about authenticated users will
+ be provisioned from this LDAP server.
+ default: false
+ type: bool
+
+ kerberosRealm:
+ description:
+ - Name of kerberos realm.
+ type: str
+
+ krbPrincipalAttribute:
+ description:
+ - Name of the LDAP attribute, which refers to Kerberos principal. This is used to lookup appropriate LDAP user after
+ successful Kerberos/SPNEGO authentication in Keycloak. When this is empty, the LDAP user will be looked based
+ on LDAP username corresponding to the first part of his Kerberos principal. For instance, for principal C(john@KEYCLOAK.ORG),
+ it will assume that LDAP username is V(john).
+ type: str
+ version_added: 8.1.0
+
+ serverPrincipal:
+ description:
+ - Full name of server principal for HTTP service including server and domain name. For example V(HTTP/host.foo.org@FOO.ORG).
+ Use V(*) to accept any service principal in the KeyTab file.
+ type: str
+
+ keyTab:
+ description:
+ - Location of Kerberos KeyTab file containing the credentials of server principal. For example V(/etc/krb5.keytab).
+ type: str
+
+ debug:
+ description:
+ - Enable/disable debug logging to standard output for Krb5LoginModule.
+ type: bool
+
+ useKerberosForPasswordAuthentication:
+ description:
+ - Use Kerberos login module for authenticate username/password against Kerberos server instead of authenticating
+ against LDAP server with Directory Service API.
+ default: false
+ type: bool
+
+ allowPasswordAuthentication:
+ description:
+ - Enable/disable possibility of username/password authentication against Kerberos database.
+ type: bool
+
+ batchSizeForSync:
+ description:
+ - Count of LDAP users to be imported from LDAP to Keycloak within a single transaction.
+ default: 1000
+ type: int
+
+ fullSyncPeriod:
+ description:
+ - Period for full synchronization in seconds.
+ default: -1
+ type: int
+
+ changedSyncPeriod:
+ description:
+ - Period for synchronization of changed or newly created LDAP users in seconds.
+ default: -1
+ type: int
+
+ updateProfileFirstLogin:
+ description:
+ - Update profile on first login.
+ type: bool
+
+ cachePolicy:
+ description:
+ - Cache Policy for this storage provider.
+ type: str
+ default: 'DEFAULT'
+ choices:
+ - DEFAULT
+ - EVICT_DAILY
+ - EVICT_WEEKLY
+ - MAX_LIFESPAN
+ - NO_CACHE
+
+ evictionDay:
+ description:
+ - Day of the week the entry will become invalid on.
+ type: str
+
+ evictionHour:
+ description:
+ - Hour of day the entry will become invalid on.
+ type: str
+
+ evictionMinute:
+ description:
+ - Minute of day the entry will become invalid on.
+ type: str
+
+ maxLifespan:
+ description:
+ - Max lifespan of cache entry in milliseconds.
+ type: int
+
+ referral:
+ description:
+ - Specifies if LDAP referrals should be followed or ignored. Please note that enabling referrals can slow down authentication
+ as it allows the LDAP server to decide which other LDAP servers to use. This could potentially include untrusted
+ servers.
+ type: str
+ choices:
+ - ignore
+ - follow
version_added: 9.5.0
- config:
+ mappers:
+ description:
+ - A list of dicts defining mappers associated with this Identity Provider.
+ type: list
+ elements: dict
+ suboptions:
+ id:
description:
- - Dict specifying the configuration options for the provider; the contents differ depending on
- the value of O(provider_id). Examples are given below for V(ldap), V(kerberos) and V(sssd).
- It is easiest to obtain valid config values by dumping an already-existing user federation
- configuration through check-mode in the RV(existing) field.
- - The value V(sssd) has been supported since community.general 4.2.0.
+ - Unique ID of this mapper.
+ type: str
+
+ name:
+ description:
+ - Name of the mapper. If no ID is given, the mapper will be searched by name.
+ type: str
+
+ parentId:
+ description:
+ - Unique ID for the parent of this mapper. ID of the user federation will automatically be used if left blank.
+ type: str
+
+ providerId:
+ description:
+ - The mapper type for this mapper (for instance V(user-attribute-ldap-mapper)).
+ type: str
+
+ providerType:
+ description:
+ - Component type for this mapper.
+ type: str
+ default: org.keycloak.storage.ldap.mappers.LDAPStorageMapper
+
+ config:
+ description:
+ - Dict specifying the configuration options for the mapper; the contents differ depending on the value of I(identityProviderMapper).
type: dict
- suboptions:
- enabled:
- description:
- - Enable/disable this user federation.
- default: true
- type: bool
-
- priority:
- description:
- - Priority of provider when doing a user lookup. Lowest first.
- default: 0
- type: int
-
- importEnabled:
- description:
- - If V(true), LDAP users will be imported into Keycloak DB and synced by the configured
- sync policies.
- default: true
- type: bool
-
- editMode:
- description:
- - V(READ_ONLY) is a read-only LDAP store. V(WRITABLE) means data will be synced back to LDAP
- on demand. V(UNSYNCED) means user data will be imported, but not synced back to LDAP.
- type: str
- choices:
- - READ_ONLY
- - WRITABLE
- - UNSYNCED
-
- syncRegistrations:
- description:
- - Should newly created users be created within LDAP store? Priority effects which
- provider is chosen to sync the new user.
- default: false
- type: bool
-
- vendor:
- description:
- - LDAP vendor (provider).
- - Use short name. For instance, write V(rhds) for "Red Hat Directory Server".
- type: str
-
- usernameLDAPAttribute:
- description:
- - Name of LDAP attribute, which is mapped as Keycloak username. For many LDAP server
- vendors it can be V(uid). For Active directory it can be V(sAMAccountName) or V(cn).
- The attribute should be filled for all LDAP user records you want to import from
- LDAP to Keycloak.
- type: str
-
- rdnLDAPAttribute:
- description:
- - Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN.
- Usually it's the same as Username LDAP attribute, however it is not required. For
- example for Active directory, it is common to use V(cn) as RDN attribute when
- username attribute might be V(sAMAccountName).
- type: str
-
- uuidLDAPAttribute:
- description:
- - Name of LDAP attribute, which is used as unique object identifier (UUID) for objects
- in LDAP. For many LDAP server vendors, it is V(entryUUID); however some are different.
- For example for Active directory it should be V(objectGUID). If your LDAP server does
- not support the notion of UUID, you can use any other attribute that is supposed to
- be unique among LDAP users in tree.
- type: str
-
- userObjectClasses:
- description:
- - All values of LDAP objectClass attribute for users in LDAP divided by comma.
- For example V(inetOrgPerson, organizationalPerson). Newly created Keycloak users
- will be written to LDAP with all those object classes and existing LDAP user records
- are found just if they contain all those object classes.
- type: str
-
- connectionUrl:
- description:
- - Connection URL to your LDAP server.
- type: str
-
- usersDn:
- description:
- - Full DN of LDAP tree where your users are. This DN is the parent of LDAP users.
- type: str
-
- customUserSearchFilter:
- description:
- - Additional LDAP Filter for filtering searched users. Leave this empty if you don't
- need additional filter.
- type: str
-
- searchScope:
- description:
- - For one level, the search applies only for users in the DNs specified by User DNs.
- For subtree, the search applies to the whole subtree. See LDAP documentation for
- more details.
- default: '1'
- type: str
- choices:
- - '1'
- - '2'
-
- authType:
- description:
- - Type of the Authentication method used during LDAP Bind operation. It is used in
- most of the requests sent to the LDAP server.
- default: 'none'
- type: str
- choices:
- - none
- - simple
-
- bindDn:
- description:
- - DN of LDAP user which will be used by Keycloak to access LDAP server.
- type: str
-
- bindCredential:
- description:
- - Password of LDAP admin.
- type: str
-
- startTls:
- description:
- - Encrypts the connection to LDAP using STARTTLS, which will disable connection pooling.
- default: false
- type: bool
-
- usePasswordModifyExtendedOp:
- description:
- - Use the LDAPv3 Password Modify Extended Operation (RFC-3062). The password modify
- extended operation usually requires that LDAP user already has password in the LDAP
- server. So when this is used with 'Sync Registrations', it can be good to add also
- 'Hardcoded LDAP attribute mapper' with randomly generated initial password.
- default: false
- type: bool
-
- validatePasswordPolicy:
- description:
- - Determines if Keycloak should validate the password with the realm password policy
- before updating it.
- default: false
- type: bool
-
- trustEmail:
- description:
- - If enabled, email provided by this provider is not verified even if verification is
- enabled for the realm.
- default: false
- type: bool
-
- useTruststoreSpi:
- description:
- - Specifies whether LDAP connection will use the truststore SPI with the truststore
- configured in standalone.xml/domain.xml. V(always) means that it will always use it.
- V(never) means that it will not use it. V(ldapsOnly) means that it will use if
- your connection URL use ldaps. Note even if standalone.xml/domain.xml is not
- configured, the default Java cacerts or certificate specified by
- C(javax.net.ssl.trustStore) property will be used.
- default: ldapsOnly
- type: str
- choices:
- - always
- - ldapsOnly
- - never
-
- connectionTimeout:
- description:
- - LDAP Connection Timeout in milliseconds.
- type: int
-
- readTimeout:
- description:
- - LDAP Read Timeout in milliseconds. This timeout applies for LDAP read operations.
- type: int
-
- pagination:
- description:
- - Does the LDAP server support pagination.
- default: true
- type: bool
-
- connectionPooling:
- description:
- - Determines if Keycloak should use connection pooling for accessing LDAP server.
- default: true
- type: bool
-
- connectionPoolingAuthentication:
- description:
- - A list of space-separated authentication types of connections that may be pooled.
- type: str
- choices:
- - none
- - simple
- - DIGEST-MD5
-
- connectionPoolingDebug:
- description:
- - A string that indicates the level of debug output to produce. Example valid values are
- V(fine) (trace connection creation and removal) and V(all) (all debugging information).
- type: str
-
- connectionPoolingInitSize:
- description:
- - The number of connections per connection identity to create when initially creating a
- connection for the identity.
- type: int
-
- connectionPoolingMaxSize:
- description:
- - The maximum number of connections per connection identity that can be maintained
- concurrently.
- type: int
-
- connectionPoolingPrefSize:
- description:
- - The preferred number of connections per connection identity that should be maintained
- concurrently.
- type: int
-
- connectionPoolingProtocol:
- description:
- - A list of space-separated protocol types of connections that may be pooled.
- Valid types are V(plain) and V(ssl).
- type: str
-
- connectionPoolingTimeout:
- description:
- - The number of milliseconds that an idle connection may remain in the pool without
- being closed and removed from the pool.
- type: int
-
- allowKerberosAuthentication:
- description:
- - Enable/disable HTTP authentication of users with SPNEGO/Kerberos tokens. The data
- about authenticated users will be provisioned from this LDAP server.
- default: false
- type: bool
-
- kerberosRealm:
- description:
- - Name of kerberos realm.
- type: str
-
- krbPrincipalAttribute:
- description:
- - Name of the LDAP attribute, which refers to Kerberos principal.
- This is used to lookup appropriate LDAP user after successful Kerberos/SPNEGO authentication in Keycloak.
- When this is empty, the LDAP user will be looked based on LDAP username corresponding
- to the first part of his Kerberos principal. For instance, for principal C(john@KEYCLOAK.ORG),
- it will assume that LDAP username is V(john).
- type: str
- version_added: 8.1.0
-
- serverPrincipal:
- description:
- - Full name of server principal for HTTP service including server and domain name. For
- example V(HTTP/host.foo.org@FOO.ORG). Use V(*) to accept any service principal in the
- KeyTab file.
- type: str
-
- keyTab:
- description:
- - Location of Kerberos KeyTab file containing the credentials of server principal. For
- example V(/etc/krb5.keytab).
- type: str
-
- debug:
- description:
- - Enable/disable debug logging to standard output for Krb5LoginModule.
- type: bool
-
- useKerberosForPasswordAuthentication:
- description:
- - Use Kerberos login module for authenticate username/password against Kerberos server
- instead of authenticating against LDAP server with Directory Service API.
- default: false
- type: bool
-
- allowPasswordAuthentication:
- description:
- - Enable/disable possibility of username/password authentication against Kerberos database.
- type: bool
-
- batchSizeForSync:
- description:
- - Count of LDAP users to be imported from LDAP to Keycloak within a single transaction.
- default: 1000
- type: int
-
- fullSyncPeriod:
- description:
- - Period for full synchronization in seconds.
- default: -1
- type: int
-
- changedSyncPeriod:
- description:
- - Period for synchronization of changed or newly created LDAP users in seconds.
- default: -1
- type: int
-
- updateProfileFirstLogin:
- description:
- - Update profile on first login.
- type: bool
-
- cachePolicy:
- description:
- - Cache Policy for this storage provider.
- type: str
- default: 'DEFAULT'
- choices:
- - DEFAULT
- - EVICT_DAILY
- - EVICT_WEEKLY
- - MAX_LIFESPAN
- - NO_CACHE
-
- evictionDay:
- description:
- - Day of the week the entry will become invalid on.
- type: str
-
- evictionHour:
- description:
- - Hour of day the entry will become invalid on.
- type: str
-
- evictionMinute:
- description:
- - Minute of day the entry will become invalid on.
- type: str
-
- maxLifespan:
- description:
- - Max lifespan of cache entry in milliseconds.
- type: int
-
- referral:
- description:
- - Specifies if LDAP referrals should be followed or ignored. Please note that enabling
- referrals can slow down authentication as it allows the LDAP server to decide which other
- LDAP servers to use. This could potentially include untrusted servers.
- type: str
- choices:
- - ignore
- - follow
- version_added: 9.5.0
-
- mappers:
- description:
- - A list of dicts defining mappers associated with this Identity Provider.
- type: list
- elements: dict
- suboptions:
- id:
- description:
- - Unique ID of this mapper.
- type: str
-
- name:
- description:
- - Name of the mapper. If no ID is given, the mapper will be searched by name.
- type: str
-
- parentId:
- description:
- - Unique ID for the parent of this mapper. ID of the user federation will automatically
- be used if left blank.
- type: str
-
- providerId:
- description:
- - The mapper type for this mapper (for instance V(user-attribute-ldap-mapper)).
- type: str
-
- providerType:
- description:
- - Component type for this mapper.
- type: str
- default: org.keycloak.storage.ldap.mappers.LDAPStorageMapper
-
- config:
- description:
- - Dict specifying the configuration options for the mapper; the contents differ
- depending on the value of I(identityProviderMapper).
- # TODO: what is identityProviderMapper above???
- type: dict
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Laurent Paumier (@laurpaum)
-'''
+ - Laurent Paumier (@laurpaum)
+"""
-EXAMPLES = '''
- - name: Create LDAP user federation
- community.general.keycloak_user_federation:
- auth_keycloak_url: https://keycloak.example.com/auth
- auth_realm: master
- auth_username: admin
- auth_password: password
- realm: my-realm
- name: my-ldap
- state: present
- provider_id: ldap
- provider_type: org.keycloak.storage.UserStorageProvider
- config:
- priority: 0
- enabled: true
- cachePolicy: DEFAULT
- batchSizeForSync: 1000
- editMode: READ_ONLY
- importEnabled: true
- syncRegistrations: false
- vendor: other
- usernameLDAPAttribute: uid
- rdnLDAPAttribute: uid
- uuidLDAPAttribute: entryUUID
- userObjectClasses: inetOrgPerson, organizationalPerson
- connectionUrl: ldaps://ldap.example.com:636
- usersDn: ou=Users,dc=example,dc=com
- authType: simple
- bindDn: cn=directory reader
- bindCredential: password
- searchScope: 1
- validatePasswordPolicy: false
- trustEmail: false
- useTruststoreSpi: ldapsOnly
- connectionPooling: true
- pagination: true
- allowKerberosAuthentication: false
- debug: false
- useKerberosForPasswordAuthentication: false
- mappers:
- - name: "full name"
- providerId: "full-name-ldap-mapper"
- providerType: "org.keycloak.storage.ldap.mappers.LDAPStorageMapper"
- config:
- ldap.full.name.attribute: cn
- read.only: true
- write.only: false
+EXAMPLES = r"""
+- name: Create LDAP user federation
+ community.general.keycloak_user_federation:
+ auth_keycloak_url: https://keycloak.example.com/auth
+ auth_realm: master
+ auth_username: admin
+ auth_password: password
+ realm: my-realm
+ name: my-ldap
+ state: present
+ provider_id: ldap
+ provider_type: org.keycloak.storage.UserStorageProvider
+ config:
+ priority: 0
+ enabled: true
+ cachePolicy: DEFAULT
+ batchSizeForSync: 1000
+ editMode: READ_ONLY
+ importEnabled: true
+ syncRegistrations: false
+ vendor: other
+ usernameLDAPAttribute: uid
+ rdnLDAPAttribute: uid
+ uuidLDAPAttribute: entryUUID
+ userObjectClasses: inetOrgPerson, organizationalPerson
+ connectionUrl: ldaps://ldap.example.com:636
+ usersDn: ou=Users,dc=example,dc=com
+ authType: simple
+ bindDn: cn=directory reader
+ bindCredential: password
+ searchScope: 1
+ validatePasswordPolicy: false
+ trustEmail: false
+ useTruststoreSpi: ldapsOnly
+ connectionPooling: true
+ pagination: true
+ allowKerberosAuthentication: false
+ debug: false
+ useKerberosForPasswordAuthentication: false
+ mappers:
+ - name: "full name"
+ providerId: "full-name-ldap-mapper"
+ providerType: "org.keycloak.storage.ldap.mappers.LDAPStorageMapper"
+ config:
+ ldap.full.name.attribute: cn
+ read.only: true
+ write.only: false
- - name: Create Kerberos user federation
- community.general.keycloak_user_federation:
- auth_keycloak_url: https://keycloak.example.com/auth
- auth_realm: master
- auth_username: admin
- auth_password: password
- realm: my-realm
- name: my-kerberos
- state: present
- provider_id: kerberos
- provider_type: org.keycloak.storage.UserStorageProvider
- config:
- priority: 0
- enabled: true
- cachePolicy: DEFAULT
- kerberosRealm: EXAMPLE.COM
- serverPrincipal: HTTP/host.example.com@EXAMPLE.COM
- keyTab: keytab
- allowPasswordAuthentication: false
- updateProfileFirstLogin: false
+- name: Create Kerberos user federation
+ community.general.keycloak_user_federation:
+ auth_keycloak_url: https://keycloak.example.com/auth
+ auth_realm: master
+ auth_username: admin
+ auth_password: password
+ realm: my-realm
+ name: my-kerberos
+ state: present
+ provider_id: kerberos
+ provider_type: org.keycloak.storage.UserStorageProvider
+ config:
+ priority: 0
+ enabled: true
+ cachePolicy: DEFAULT
+ kerberosRealm: EXAMPLE.COM
+ serverPrincipal: HTTP/host.example.com@EXAMPLE.COM
+ keyTab: keytab
+ allowPasswordAuthentication: false
+ updateProfileFirstLogin: false
- - name: Create sssd user federation
- community.general.keycloak_user_federation:
- auth_keycloak_url: https://keycloak.example.com/auth
- auth_realm: master
- auth_username: admin
- auth_password: password
- realm: my-realm
- name: my-sssd
- state: present
- provider_id: sssd
- provider_type: org.keycloak.storage.UserStorageProvider
- config:
- priority: 0
- enabled: true
- cachePolicy: DEFAULT
+- name: Create sssd user federation
+ community.general.keycloak_user_federation:
+ auth_keycloak_url: https://keycloak.example.com/auth
+ auth_realm: master
+ auth_username: admin
+ auth_password: password
+ realm: my-realm
+ name: my-sssd
+ state: present
+ provider_id: sssd
+ provider_type: org.keycloak.storage.UserStorageProvider
+ config:
+ priority: 0
+ enabled: true
+ cachePolicy: DEFAULT
- - name: Delete user federation
- community.general.keycloak_user_federation:
- auth_keycloak_url: https://keycloak.example.com/auth
- auth_realm: master
- auth_username: admin
- auth_password: password
- realm: my-realm
- name: my-federation
- state: absent
+- name: Delete user federation
+ community.general.keycloak_user_federation:
+ auth_keycloak_url: https://keycloak.example.com/auth
+ auth_realm: master
+ auth_username: admin
+ auth_password: password
+ realm: my-realm
+ name: my-federation
+ state: absent
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "No changes required to user federation 164bb483-c613-482e-80fe-7f1431308799."
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "No changes required to user federation 164bb483-c613-482e-80fe-7f1431308799."
proposed:
description: Representation of proposed user federation.
@@ -741,7 +715,7 @@ end_state:
"providerId": "kerberos",
"providerType": "org.keycloak.storage.UserStorageProvider"
}
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError
@@ -865,7 +839,9 @@ def main():
supports_check_mode=True,
required_one_of=([['id', 'name'],
['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
diff --git a/plugins/modules/keycloak_user_rolemapping.py b/plugins/modules/keycloak_user_rolemapping.py
index 59727a346e..c7af801706 100644
--- a/plugins/modules/keycloak_user_rolemapping.py
+++ b/plugins/modules/keycloak_user_rolemapping.py
@@ -7,8 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_user_rolemapping
short_description: Allows administration of Keycloak user_rolemapping with the Keycloak API
@@ -16,107 +15,99 @@ short_description: Allows administration of Keycloak user_rolemapping with the K
version_added: 5.7.0
description:
- - This module allows you to add, remove or modify Keycloak user_rolemapping with the Keycloak REST API.
- It requires access to the REST API via OpenID Connect; the user connecting and the client being
- used must have the requisite access rights. In a default Keycloak installation, admin-cli
- and an admin user would work, as would a separate client definition with the scope tailored
- to your needs and a user having the expected roles.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
-
- - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
- be returned that way by this module. You may pass single values for attributes when calling the module,
- and this will be translated into a list suitable for the API.
-
- - When updating a user_rolemapping, where possible provide the role ID to the module. This removes a lookup
- to the API to translate the name into the role ID.
-
+ - This module allows you to add, remove or modify Keycloak user_rolemapping with the Keycloak REST API. It requires access
+ to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights.
+ In a default Keycloak installation, admin-cli and an admin user would work, as would a separate client definition with
+ the scope tailored to your needs and a user having the expected roles.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
+ - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that
+ way by this module. You may pass single values for attributes when calling the module, and this will be translated into
+ a list suitable for the API.
+ - When updating a user_rolemapping, where possible provide the role ID to the module. This removes a lookup to the API to
+ translate the name into the role ID.
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the user_rolemapping.
- - On V(present), the user_rolemapping will be created if it does not yet exist, or updated with the parameters you provide.
- - On V(absent), the user_rolemapping will be removed if it exists.
- default: 'present'
- type: str
- choices:
- - present
- - absent
+ state:
+ description:
+ - State of the user_rolemapping.
+ - On V(present), the user_rolemapping will be created if it does not yet exist, or updated with the parameters you provide.
+ - On V(absent), the user_rolemapping will be removed if it exists.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
- realm:
+ realm:
+ type: str
+ description:
+ - They Keycloak realm under which this role_representation resides.
+ default: 'master'
+
+ target_username:
+ type: str
+ description:
+ - Username of the user roles are mapped to.
+ - This parameter is not required (can be replaced by uid for less API call).
+ uid:
+ type: str
+ description:
+ - ID of the user to be mapped.
+ - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of
+ API calls required.
+ service_account_user_client_id:
+ type: str
+ description:
+ - Client ID of the service-account-user to be mapped.
+ - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of
+ API calls required.
+ client_id:
+ type: str
+ description:
+ - Name of the client to be mapped (different than O(cid)).
+ - This parameter is required if O(cid) is not provided (can be replaced by O(cid) to reduce the number of API calls
+ that must be made).
+ cid:
+ type: str
+ description:
+ - ID of the client to be mapped.
+ - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of
+ API calls required.
+ roles:
+ description:
+ - Roles to be mapped to the user.
+ type: list
+ elements: dict
+ suboptions:
+ name:
type: str
description:
- - They Keycloak realm under which this role_representation resides.
- default: 'master'
-
- target_username:
+ - Name of the role representation.
+ - This parameter is required only when creating or updating the role_representation.
+ id:
type: str
description:
- - Username of the user roles are mapped to.
- - This parameter is not required (can be replaced by uid for less API call).
-
- uid:
- type: str
- description:
- - ID of the user to be mapped.
- - This parameter is not required for updating or deleting the rolemapping but
- providing it will reduce the number of API calls required.
-
- service_account_user_client_id:
- type: str
- description:
- - Client ID of the service-account-user to be mapped.
- - This parameter is not required for updating or deleting the rolemapping but
- providing it will reduce the number of API calls required.
-
- client_id:
- type: str
- description:
- - Name of the client to be mapped (different than O(cid)).
- - This parameter is required if O(cid) is not provided (can be replaced by O(cid)
- to reduce the number of API calls that must be made).
-
- cid:
- type: str
- description:
- - ID of the client to be mapped.
- - This parameter is not required for updating or deleting the rolemapping but
- providing it will reduce the number of API calls required.
-
- roles:
- description:
- - Roles to be mapped to the user.
- type: list
- elements: dict
- suboptions:
- name:
- type: str
- description:
- - Name of the role representation.
- - This parameter is required only when creating or updating the role_representation.
- id:
- type: str
- description:
- - The unique identifier for this role_representation.
- - This parameter is not required for updating or deleting a role_representation but
- providing it will reduce the number of API calls required.
-
+ - The unique identifier for this role_representation.
+ - This parameter is not required for updating or deleting a role_representation but providing it will reduce the
+ number of API calls required.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- - Dušan Marković (@bratwurzt)
-'''
+ - Dušan Marković (@bratwurzt)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Map a client role to a user, authentication with credentials
community.general.keycloak_user_rolemapping:
realm: MyCustomRealm
@@ -186,49 +177,37 @@ EXAMPLES = '''
- name: role_name2
id: role_id2
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message as to what action was taken.
- returned: always
- type: str
- sample: "Role role1 assigned to user user1."
+ description: Message as to what action was taken.
+ returned: always
+ type: str
+ sample: "Role role1 assigned to user user1."
proposed:
- description: Representation of proposed client role mapping.
- returned: always
- type: dict
- sample: {
- clientId: "test"
- }
+ description: Representation of proposed client role mapping.
+ returned: always
+ type: dict
+ sample: {clientId: "test"}
existing:
- description:
- - Representation of existing client role mapping.
- - The sample is truncated.
- returned: always
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
+ description:
+ - Representation of existing client role mapping.
+ - The sample is truncated.
+ returned: always
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
end_state:
- description:
- - Representation of client role mapping after module execution.
- - The sample is truncated.
- returned: on success
- type: dict
- sample: {
- "adminUrl": "http://www.example.com/admin_url",
- "attributes": {
- "request.object.signature.alg": "RS256",
- }
- }
-'''
+ description:
+ - Representation of client role mapping after module execution.
+ - The sample is truncated.
+ returned: on success
+ type: dict
+ sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, \
keycloak_argument_spec, get_token, KeycloakError
@@ -265,7 +244,9 @@ def main():
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password'],
['uid', 'target_username', 'service_account_user_client_id']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={})
diff --git a/plugins/modules/keycloak_userprofile.py b/plugins/modules/keycloak_userprofile.py
index 57e1c42e96..f637271497 100644
--- a/plugins/modules/keycloak_userprofile.py
+++ b/plugins/modules/keycloak_userprofile.py
@@ -8,275 +8,275 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: keycloak_userprofile
short_description: Allows managing Keycloak User Profiles
description:
- - This module allows you to create, update, or delete Keycloak User Profiles via Keycloak API. You can also customize the "Unmanaged Attributes" with it.
-
- - The names of module options are snake_cased versions of the camelCase ones found in the
- Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/24.0.5/rest-api/index.html).
- For compatibility reasons, the module also accepts the camelCase versions of the options.
-
+ - This module allows you to create, update, or delete Keycloak User Profiles using the Keycloak API. You can also customize
+ the "Unmanaged Attributes" with it.
+ - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation
+ at U(https://www.keycloak.org/docs-api/24.0.5/rest-api/index.html). For compatibility reasons, the module also accepts
+ the camelCase versions of the options.
version_added: "9.4.0"
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
+ action_group:
+ version_added: 10.2.0
options:
- state:
- description:
- - State of the User Profile provider.
- - On V(present), the User Profile provider will be created if it does not yet exist, or updated with
- the parameters you provide.
- - On V(absent), the User Profile provider will be removed if it exists.
- default: 'present'
- type: str
- choices:
- - present
- - absent
+ state:
+ description:
+ - State of the User Profile provider.
+ - On V(present), the User Profile provider will be created if it does not yet exist, or updated with the parameters
+ you provide.
+ - On V(absent), the User Profile provider will be removed if it exists.
+ default: 'present'
+ type: str
+ choices:
+ - present
+ - absent
- parent_id:
+ parent_id:
+ description:
+ - The parent ID of the realm key. In practice the ID (name) of the realm.
+ aliases:
+ - parentId
+ - realm
+ type: str
+ required: true
+
+ provider_id:
+ description:
+ - The name of the provider ID for the key (supported value is V(declarative-user-profile)).
+ aliases:
+ - providerId
+ choices: ['declarative-user-profile']
+ default: 'declarative-user-profile'
+ type: str
+
+ provider_type:
+ description:
+ - Component type for User Profile (only supported value is V(org.keycloak.userprofile.UserProfileProvider)).
+ aliases:
+ - providerType
+ choices: ['org.keycloak.userprofile.UserProfileProvider']
+ default: org.keycloak.userprofile.UserProfileProvider
+ type: str
+
+ config:
+ description:
+ - The configuration of the User Profile Provider.
+ type: dict
+ required: false
+ suboptions:
+ kc_user_profile_config:
description:
- - The parent ID of the realm key. In practice the ID (name) of the realm.
+ - Define a declarative User Profile. See EXAMPLES for more context.
aliases:
- - parentId
- - realm
- type: str
- required: true
-
- provider_id:
- description:
- - The name of the provider ID for the key (supported value is V(declarative-user-profile)).
- aliases:
- - providerId
- choices: ['declarative-user-profile']
- default: 'declarative-user-profile'
- type: str
-
- provider_type:
- description:
- - Component type for User Profile (only supported value is V(org.keycloak.userprofile.UserProfileProvider)).
- aliases:
- - providerType
- choices: ['org.keycloak.userprofile.UserProfileProvider']
- default: org.keycloak.userprofile.UserProfileProvider
- type: str
-
- config:
- description:
- - The configuration of the User Profile Provider.
- type: dict
- required: false
+ - kcUserProfileConfig
+ type: list
+ elements: dict
suboptions:
- kc_user_profile_config:
+ attributes:
+ description:
+ - A list of attributes to be included in the User Profile.
+ type: list
+ elements: dict
+ suboptions:
+ name:
description:
- - Define a declarative User Profile. See EXAMPLES for more context.
+ - The name of the attribute.
+ type: str
+ required: true
+
+ display_name:
+ description:
+ - The display name of the attribute.
aliases:
- - kcUserProfileConfig
- type: list
- elements: dict
+ - displayName
+ type: str
+ required: true
+
+ validations:
+ description:
+ - The validations to be applied to the attribute.
+ type: dict
suboptions:
- attributes:
+ length:
+ description:
+ - The length validation for the attribute.
+ type: dict
+ suboptions:
+ min:
description:
- - A list of attributes to be included in the User Profile.
- type: list
- elements: dict
- suboptions:
- name:
- description:
- - The name of the attribute.
- type: str
- required: true
-
- display_name:
- description:
- - The display name of the attribute.
- aliases:
- - displayName
- type: str
- required: true
-
- validations:
- description:
- - The validations to be applied to the attribute.
- type: dict
- suboptions:
- length:
- description:
- - The length validation for the attribute.
- type: dict
- suboptions:
- min:
- description:
- - The minimum length of the attribute.
- type: int
- max:
- description:
- - The maximum length of the attribute.
- type: int
- required: true
-
- email:
- description:
- - The email validation for the attribute.
- type: dict
-
- username_prohibited_characters:
- description:
- - The prohibited characters validation for the username attribute.
- type: dict
- aliases:
- - usernameProhibitedCharacters
-
- up_username_not_idn_homograph:
- description:
- - The validation to prevent IDN homograph attacks in usernames.
- type: dict
- aliases:
- - upUsernameNotIdnHomograph
-
- person_name_prohibited_characters:
- description:
- - The prohibited characters validation for person name attributes.
- type: dict
- aliases:
- - personNameProhibitedCharacters
-
- uri:
- description:
- - The URI validation for the attribute.
- type: dict
-
- pattern:
- description:
- - The pattern validation for the attribute using regular expressions.
- type: dict
-
- options:
- description:
- - Validation to ensure the attribute matches one of the provided options.
- type: dict
-
- annotations:
- description:
- - Annotations for the attribute.
- type: dict
-
- group:
- description:
- - Specifies the User Profile group where this attribute will be added.
- type: str
-
- permissions:
- description:
- - The permissions for viewing and editing the attribute.
- type: dict
- suboptions:
- view:
- description:
- - The roles that can view the attribute.
- - Supported values are V(admin) and V(user).
- type: list
- elements: str
- default:
- - admin
- - user
-
- edit:
- description:
- - The roles that can edit the attribute.
- - Supported values are V(admin) and V(user).
- type: list
- elements: str
- default:
- - admin
- - user
-
- multivalued:
- description:
- - Whether the attribute can have multiple values.
- type: bool
- default: false
-
- required:
- description:
- - The roles that require this attribute.
- type: dict
- suboptions:
- roles:
- description:
- - The roles for which this attribute is required.
- - Supported values are V(admin) and V(user).
- type: list
- elements: str
- default:
- - user
-
- groups:
+ - The minimum length of the attribute.
+ type: int
+ max:
description:
- - A list of attribute groups to be included in the User Profile.
- type: list
- elements: dict
- suboptions:
- name:
- description:
- - The name of the group.
- type: str
- required: true
+ - The maximum length of the attribute.
+ type: int
+ required: true
- display_header:
- description:
- - The display header for the group.
- aliases:
- - displayHeader
- type: str
- required: true
+ email:
+ description:
+ - The email validation for the attribute.
+ type: dict
- display_description:
- description:
- - The display description for the group.
- aliases:
- - displayDescription
- type: str
- required: false
+ username_prohibited_characters:
+ description:
+ - The prohibited characters validation for the username attribute.
+ type: dict
+ aliases:
+ - usernameProhibitedCharacters
- annotations:
- description:
- - The annotations included in the group.
- type: dict
- required: false
+ up_username_not_idn_homograph:
+ description:
+ - The validation to prevent IDN homograph attacks in usernames.
+ type: dict
+ aliases:
+ - upUsernameNotIdnHomograph
- unmanaged_attribute_policy:
- description:
- - Policy for unmanaged attributes.
- aliases:
- - unmanagedAttributePolicy
- type: str
- choices:
- - ENABLED
- - ADMIN_EDIT
- - ADMIN_VIEW
+ person_name_prohibited_characters:
+ description:
+ - The prohibited characters validation for person name attributes.
+ type: dict
+ aliases:
+ - personNameProhibitedCharacters
+
+ uri:
+ description:
+ - The URI validation for the attribute.
+ type: dict
+
+ pattern:
+ description:
+ - The pattern validation for the attribute using regular expressions.
+ type: dict
+
+ options:
+ description:
+ - Validation to ensure the attribute matches one of the provided options.
+ type: dict
+
+ annotations:
+ description:
+ - Annotations for the attribute.
+ type: dict
+
+ group:
+ description:
+ - Specifies the User Profile group where this attribute will be added.
+ type: str
+
+ permissions:
+ description:
+ - The permissions for viewing and editing the attribute.
+ type: dict
+ suboptions:
+ view:
+ description:
+ - The roles that can view the attribute.
+ - Supported values are V(admin) and V(user).
+ type: list
+ elements: str
+ default:
+ - admin
+ - user
+
+ edit:
+ description:
+ - The roles that can edit the attribute.
+ - Supported values are V(admin) and V(user).
+ type: list
+ elements: str
+ default:
+ - admin
+ - user
+
+ multivalued:
+ description:
+ - Whether the attribute can have multiple values.
+ type: bool
+ default: false
+
+ required:
+ description:
+ - The roles that require this attribute.
+ type: dict
+ suboptions:
+ roles:
+ description:
+ - The roles for which this attribute is required.
+ - Supported values are V(admin) and V(user).
+ type: list
+ elements: str
+ default:
+ - user
+
+ groups:
+ description:
+ - A list of attribute groups to be included in the User Profile.
+ type: list
+ elements: dict
+ suboptions:
+ name:
+ description:
+ - The name of the group.
+ type: str
+ required: true
+
+ display_header:
+ description:
+ - The display header for the group.
+ aliases:
+ - displayHeader
+ type: str
+ required: true
+
+ display_description:
+ description:
+ - The display description for the group.
+ aliases:
+ - displayDescription
+ type: str
+ required: false
+
+ annotations:
+ description:
+ - The annotations included in the group.
+ type: dict
+ required: false
+
+ unmanaged_attribute_policy:
+ description:
+ - Policy for unmanaged attributes.
+ aliases:
+ - unmanagedAttributePolicy
+ type: str
+ choices:
+ - ENABLED
+ - ADMIN_EDIT
+ - ADMIN_VIEW
notes:
- - Currently, only a single V(declarative-user-profile) entry is supported for O(provider_id) (design of the Keyckoak API).
- However, there can be multiple O(config.kc_user_profile_config[].attributes[]) entries.
-
+ - Currently, only a single V(declarative-user-profile) entry is supported for O(provider_id) (design of the Keyckoak API).
+ However, there can be multiple O(config.kc_user_profile_config[].attributes[]) entries.
extends_documentation_fragment:
- - community.general.keycloak
- - community.general.attributes
+ - community.general.keycloak
+ - community.general.keycloak.actiongroup_keycloak
+ - community.general.attributes
author:
- Eike Waldt (@yeoldegrove)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a Declarative User Profile with default settings
community.general.keycloak_userprofile:
state: present
@@ -394,9 +394,9 @@ EXAMPLES = '''
config:
kc_user_profile_config:
- unmanagedAttributePolicy: ADMIN_VIEW
-'''
+"""
-RETURN = '''
+RETURN = r"""
msg:
description: The output message generated by the module.
returned: always
@@ -406,8 +406,8 @@ data:
description: The data returned by the Keycloak API.
returned: when state is present
type: dict
- sample: {...}
-'''
+ sample: {'...': '...'}
+"""
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \
keycloak_argument_spec, get_token, KeycloakError
@@ -425,7 +425,7 @@ def remove_null_values(data):
# Recursively remove null values from lists
return [remove_null_values(item) for item in data if item is not None]
else:
- # Return the data if it's neither a dictionary nor a list
+ # Return the data if it is neither a dictionary nor a list
return data
@@ -437,7 +437,7 @@ def camel_recursive(data):
# Apply camelCase conversion to each item in the list
return [camel_recursive(item) for item in data]
else:
- # Return the data as is if it's not a dict or list
+ # Return the data as-is if it is not a dict or list
return data
@@ -534,7 +534,9 @@ def main():
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]),
- required_together=([['auth_realm', 'auth_username', 'auth_password']]))
+ required_together=([['auth_realm', 'auth_username', 'auth_password']]),
+ required_by={'refresh_token': 'auth_realm'},
+ )
# Initialize the result object. Only "changed" seems to have special
# meaning for Ansible.
diff --git a/plugins/modules/keyring.py b/plugins/modules/keyring.py
index 8329b727bd..3a8cbcae02 100644
--- a/plugins/modules/keyring.py
+++ b/plugins/modules/keyring.py
@@ -13,15 +13,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r"""
----
module: keyring
version_added: 5.2.0
author:
- Alexander Hussey (@ahussey-redhat)
short_description: Set or delete a passphrase using the Operating System's native keyring
description: >-
- This module uses the L(keyring Python library, https://pypi.org/project/keyring/)
- to set or delete passphrases for a given service and username from the OS' native keyring.
+ This module uses the L(keyring Python library, https://pypi.org/project/keyring/) to set or delete passphrases for a given
+ service and username from the OS' native keyring.
requirements:
- keyring (Python library)
- gnome-keyring (application - required for headless Gnome keyring access)
diff --git a/plugins/modules/keyring_info.py b/plugins/modules/keyring_info.py
index 5c41ecc4d0..836ecafdde 100644
--- a/plugins/modules/keyring_info.py
+++ b/plugins/modules/keyring_info.py
@@ -13,15 +13,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r"""
----
module: keyring_info
version_added: 5.2.0
author:
- Alexander Hussey (@ahussey-redhat)
short_description: Get a passphrase using the Operating System's native keyring
description: >-
- This module uses the L(keyring Python library, https://pypi.org/project/keyring/)
- to retrieve passphrases for a given service and username from the OS' native keyring.
+ This module uses the L(keyring Python library, https://pypi.org/project/keyring/) to retrieve passphrases for a given service
+ and username from the OS' native keyring.
requirements:
- keyring (Python library)
- gnome-keyring (application - required for headless Linux keyring access)
@@ -45,24 +44,24 @@ options:
"""
EXAMPLES = r"""
- - name: Retrieve password for service_name/user_name
- community.general.keyring_info:
- service: test
- username: test1
- keyring_password: "{{ keyring_password }}"
- register: test_password
+- name: Retrieve password for service_name/user_name
+ community.general.keyring_info:
+ service: test
+ username: test1
+ keyring_password: "{{ keyring_password }}"
+ register: test_password
- - name: Display password
- ansible.builtin.debug:
- msg: "{{ test_password.passphrase }}"
+- name: Display password
+ ansible.builtin.debug:
+ msg: "{{ test_password.passphrase }}"
"""
RETURN = r"""
- passphrase:
- description: A string containing the password.
- returned: success and the password exists
- type: str
- sample: Password123
+passphrase:
+ description: A string containing the password.
+ returned: success and the password exists
+ type: str
+ sample: Password123
"""
try:
diff --git a/plugins/modules/kibana_plugin.py b/plugins/modules/kibana_plugin.py
index f6744b3960..09703b504c 100644
--- a/plugins/modules/kibana_plugin.py
+++ b/plugins/modules/kibana_plugin.py
@@ -11,71 +11,70 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: kibana_plugin
short_description: Manage Kibana plugins
description:
- - This module can be used to manage Kibana plugins.
+ - This module can be used to manage Kibana plugins.
author: Thierno IB. BARRY (@barryib)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
+ name:
+ description:
- Name of the plugin to install.
- required: true
- type: str
- state:
- description:
+ required: true
+ type: str
+ state:
+ description:
- Desired state of a plugin.
- choices: ["present", "absent"]
- default: present
- type: str
- url:
- description:
+ choices: ["present", "absent"]
+ default: present
+ type: str
+ url:
+ description:
- Set exact URL to download the plugin from.
- - For local file, prefix its absolute path with file://
- type: str
- timeout:
- description:
- - "Timeout setting: 30s, 1m, 1h etc."
- default: 1m
- type: str
- plugin_bin:
- description:
+ - For local file, prefix its absolute path with C(file://).
+ type: str
+ timeout:
+ description:
+ - 'Timeout setting: V(30s), V(1m), V(1h) and so on.'
+ default: 1m
+ type: str
+ plugin_bin:
+ description:
- Location of the Kibana binary.
- default: /opt/kibana/bin/kibana
- type: path
- plugin_dir:
- description:
+ default: /opt/kibana/bin/kibana
+ type: path
+ plugin_dir:
+ description:
- Your configured plugin directory specified in Kibana.
- default: /opt/kibana/installedPlugins/
- type: path
- version:
- description:
+ default: /opt/kibana/installedPlugins/
+ type: path
+ version:
+ description:
- Version of the plugin to be installed.
- If plugin exists with previous version, plugin will B(not) be updated unless O(force) is set to V(true).
- type: str
- force:
- description:
+ type: str
+ force:
+ description:
- Delete and re-install the plugin. Can be useful for plugins update.
- type: bool
- default: false
- allow_root:
- description:
+ type: bool
+ default: false
+ allow_root:
+ description:
- Whether to allow C(kibana) and C(kibana-plugin) to be run as root. Passes the C(--allow-root) flag to these commands.
- type: bool
- default: false
- version_added: 2.3.0
-'''
+ type: bool
+ default: false
+ version_added: 2.3.0
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install Elasticsearch head plugin
community.general.kibana_plugin:
state: present
@@ -91,38 +90,38 @@ EXAMPLES = '''
community.general.kibana_plugin:
state: absent
name: elasticsearch/marvel
-'''
+"""
-RETURN = '''
+RETURN = r"""
cmd:
- description: the launched command during plugin management (install / remove)
- returned: success
- type: str
+ description: The launched command during plugin management (install / remove).
+ returned: success
+ type: str
name:
- description: the plugin name to install or remove
- returned: success
- type: str
+ description: The plugin name to install or remove.
+ returned: success
+ type: str
url:
- description: the url from where the plugin is installed from
- returned: success
- type: str
+ description: The URL from where the plugin is installed from.
+ returned: success
+ type: str
timeout:
- description: the timeout for plugin download
- returned: success
- type: str
+ description: The timeout for plugin download.
+ returned: success
+ type: str
stdout:
- description: the command stdout
- returned: success
- type: str
+ description: The command stdout.
+ returned: success
+ type: str
stderr:
- description: the command stderr
- returned: success
- type: str
+ description: The command stderr.
+ returned: success
+ type: str
state:
- description: the state for the managed plugin
- returned: success
- type: str
-'''
+ description: The state for the managed plugin.
+ returned: success
+ type: str
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/krb_ticket.py b/plugins/modules/krb_ticket.py
index 8894a64ef6..e021050c22 100644
--- a/plugins/modules/krb_ticket.py
+++ b/plugins/modules/krb_ticket.py
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: krb_ticket
short_description: Kerberos utils for managing tickets
version_added: 10.0.0
@@ -51,20 +50,24 @@ options:
- Use O(cache_name) as the ticket cache name and location.
- If this option is not used, the default cache name and location are used.
- The default credentials cache may vary between systems.
- - If not set the the value of E(KRB5CCNAME) environment variable will be used instead, its value is used to name the default ticket cache.
+ - If not set the the value of E(KRB5CCNAME) environment variable will be used instead, its value is used to name the
+ default ticket cache.
type: str
lifetime:
description:
- Requests a ticket with the lifetime, if the O(lifetime) is not specified, the default ticket lifetime is used.
- - Specifying a ticket lifetime longer than the maximum ticket lifetime (configured by each site) will not override the configured maximum ticket lifetime.
- - "The value for O(lifetime) must be followed by one of the following suffixes: V(s) - seconds, V(m) - minutes, V(h) - hours, V(d) - days."
+ - Specifying a ticket lifetime longer than the maximum ticket lifetime (configured by each site) will not override the
+ configured maximum ticket lifetime.
+ - 'The value for O(lifetime) must be followed by one of the following suffixes: V(s) - seconds, V(m) - minutes, V(h)
+ - hours, V(d) - days.'
- You cannot mix units; a value of V(3h30m) will result in an error.
- See U(https://web.mit.edu/kerberos/krb5-1.12/doc/basic/date_format.html) for reference.
type: str
start_time:
description:
- Requests a postdated ticket.
- - Postdated tickets are issued with the invalid flag set, and need to be resubmitted to the KDC for validation before use.
+ - Postdated tickets are issued with the invalid flag set, and need to be resubmitted to the KDC for validation before
+ use.
- O(start_time) specifies the duration of the delay before the ticket can become valid.
- You can use absolute time formats, for example V(July 27, 2012 at 20:30) you would neet to set O(start_time=20120727203000).
- You can also use time duration format similar to O(lifetime) or O(renewable).
@@ -73,7 +76,8 @@ options:
renewable:
description:
- Requests renewable tickets, with a total lifetime equal to O(renewable).
- - "The value for O(renewable) must be followed by one of the following delimiters: V(s) - seconds, V(m) - minutes, V(h) - hours, V(d) - days."
+ - 'The value for O(renewable) must be followed by one of the following delimiters: V(s) - seconds, V(m) - minutes, V(h)
+ - hours, V(d) - days.'
- You cannot mix units; a value of V(3h30m) will result in an error.
- See U(https://web.mit.edu/kerberos/krb5-1.12/doc/basic/date_format.html) for reference.
type: str
@@ -95,7 +99,8 @@ options:
type: bool
canonicalization:
description:
- - Requests canonicalization of the principal name, and allows the KDC to reply with a different client principal from the one requested.
+ - Requests canonicalization of the principal name, and allows the KDC to reply with a different client principal from
+ the one requested.
type: bool
enterprise:
description:
@@ -125,9 +130,9 @@ requirements:
- krb5-user and krb5-config packages
extends_documentation_fragment:
- community.general.attributes
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Get Kerberos ticket using default principal
community.general.krb_ticket:
password: some_password
@@ -179,7 +184,7 @@ EXAMPLES = r'''
community.general.krb_ticket:
state: absent
kdestroy_all: true
-'''
+"""
from ansible.module_utils.basic import AnsibleModule, env_fallback
from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt
diff --git a/plugins/modules/launchd.py b/plugins/modules/launchd.py
index a6427bdb2f..03dc3a5928 100644
--- a/plugins/modules/launchd.py
+++ b/plugins/modules/launchd.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: launchd
author:
- Martin Migasiewicz (@martinm82)
@@ -20,51 +19,53 @@ description:
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
+ name:
+ description:
- Name of the service.
- type: str
- required: true
- state:
- description:
- - V(started)/V(stopped) are idempotent actions that will not run
- commands unless necessary.
- - Launchd does not support V(restarted) nor V(reloaded) natively.
- These will trigger a stop/start (restarted) or an unload/load
- (reloaded).
- - V(restarted) unloads and loads the service before start to ensure
- that the latest job definition (plist) is used.
- - V(reloaded) unloads and loads the service to ensure that the latest
- job definition (plist) is used. Whether a service is started or
- stopped depends on the content of the definition file.
- type: str
- choices: [ reloaded, restarted, started, stopped, unloaded ]
- enabled:
- description:
+ type: str
+ required: true
+ plist:
+ description:
+ - Name of the V(.plist) file for the service.
+ - Defaults to V({name}.plist).
+ type: str
+ version_added: 10.1.0
+ state:
+ description:
+ - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
+ - Launchd does not support V(restarted) nor V(reloaded) natively. These will trigger a stop/start (restarted) or an
+ unload/load (reloaded).
+ - V(restarted) unloads and loads the service before start to ensure that the latest job definition (plist) is used.
+ - V(reloaded) unloads and loads the service to ensure that the latest job definition (plist) is used. Whether a service
+ is started or stopped depends on the content of the definition file.
+ type: str
+ choices: [reloaded, restarted, started, stopped, unloaded]
+ enabled:
+ description:
- Whether the service should start on boot.
- - B(At least one of state and enabled are required.)
- type: bool
- force_stop:
- description:
+ - B(At least one of state and enabled are required).
+ type: bool
+ force_stop:
+ description:
- Whether the service should not be restarted automatically by launchd.
- - Services might have the 'KeepAlive' attribute set to true in a launchd configuration.
- In case this is set to true, stopping a service will cause that launchd starts the service again.
- - Set this option to V(true) to let this module change the 'KeepAlive' attribute to V(false).
- type: bool
- default: false
+ - Services might have the 'KeepAlive' attribute set to true in a launchd configuration. In case this is set to true,
+ stopping a service will cause that launchd starts the service again.
+ - Set this option to V(true) to let this module change the C(KeepAlive) attribute to V(false).
+ type: bool
+ default: false
notes:
-- A user must privileged to manage services using this module.
+ - A user must privileged to manage services using this module.
requirements:
-- A system managed by launchd
-- The plistlib python library
-'''
+ - A system managed by launchd
+ - The plistlib Python library
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Make sure spotify webhelper is started
community.general.launchd:
name: com.spotify.webhelper
@@ -100,11 +101,17 @@ EXAMPLES = r'''
community.general.launchd:
name: org.memcached
state: unloaded
-'''
-RETURN = r'''
+- name: restart sshd
+ community.general.launchd:
+ name: com.openssh.sshd
+ plist: ssh.plist
+ state: restarted
+"""
+
+RETURN = r"""
status:
- description: Metadata about service status
+ description: Metadata about service status.
returned: always
type: dict
sample:
@@ -114,7 +121,7 @@ status:
"previous_pid": "82636",
"previous_state": "running"
}
-'''
+"""
import os
import plistlib
@@ -145,25 +152,31 @@ class ServiceState:
class Plist:
- def __init__(self, module, service):
+ def __init__(self, module, service, filename=None):
self.__changed = False
self.__service = service
+ if filename is not None:
+ self.__filename = filename
+ else:
+ self.__filename = '%s.plist' % service
state, pid, dummy, dummy = LaunchCtlList(module, self.__service).run()
# Check if readPlist is available or not
self.old_plistlib = hasattr(plistlib, 'readPlist')
- self.__file = self.__find_service_plist(self.__service)
+ self.__file = self.__find_service_plist(self.__filename)
if self.__file is None:
- msg = 'Unable to infer the path of %s service plist file' % self.__service
+ msg = 'Unable to find the plist file %s for service %s' % (
+ self.__filename, self.__service,
+ )
if pid is None and state == ServiceState.UNLOADED:
msg += ' and it was not found among active services'
module.fail_json(msg=msg)
self.__update(module)
@staticmethod
- def __find_service_plist(service_name):
+ def __find_service_plist(filename):
"""Finds the plist file associated with a service"""
launchd_paths = [
@@ -180,7 +193,6 @@ class Plist:
except OSError:
continue
- filename = '%s.plist' % service_name
if filename in files:
return os.path.join(path, filename)
return None
@@ -461,6 +473,7 @@ def main():
module = AnsibleModule(
argument_spec=dict(
name=dict(type='str', required=True),
+ plist=dict(type='str'),
state=dict(type='str', choices=['reloaded', 'restarted', 'started', 'stopped', 'unloaded']),
enabled=dict(type='bool'),
force_stop=dict(type='bool', default=False),
@@ -472,6 +485,7 @@ def main():
)
service = module.params['name']
+ plist_filename = module.params['plist']
action = module.params['state']
rc = 0
out = err = ''
@@ -483,7 +497,7 @@ def main():
# We will tailor the plist file in case one of the options
# (enabled, force_stop) was specified.
- plist = Plist(module, service)
+ plist = Plist(module, service, plist_filename)
result['changed'] = plist.is_changed()
# Gather information about the service to be controlled.
diff --git a/plugins/modules/layman.py b/plugins/modules/layman.py
index 13d514274b..b0fab39233 100644
--- a/plugins/modules/layman.py
+++ b/plugins/modules/layman.py
@@ -10,14 +10,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: layman
author: "Jakub Jirutka (@jirutka)"
short_description: Manage Gentoo overlays
description:
- - Uses Layman to manage an additional repositories for the Portage package manager on Gentoo Linux.
- Please note that Layman must be installed on a managed node prior using this module.
+ - Uses Layman to manage an additional repositories for the Portage package manager on Gentoo Linux. Please note that Layman
+ must be installed on a managed node prior using this module.
requirements:
- layman python module
extends_documentation_fragment:
@@ -30,15 +29,14 @@ attributes:
options:
name:
description:
- - The overlay id to install, synchronize, or uninstall.
- Use 'ALL' to sync all of the installed overlays (can be used only when O(state=updated)).
+ - The overlay ID to install, synchronize, or uninstall. Use V(ALL) to sync all of the installed overlays (can be used
+ only when O(state=updated)).
required: true
type: str
list_url:
description:
- - An URL of the alternative overlays list that defines the overlay to install.
- This list will be fetched and saved under C(${overlay_defs}/${name}.xml), where
- C(overlay_defs) is read from the Layman's configuration.
+ - An URL of the alternative overlays list that defines the overlay to install. This list will be fetched and saved under
+ C(${overlay_defs}/${name}.xml), where C(overlay_defs) is read from the Layman's configuration.
aliases: [url]
type: str
state:
@@ -49,14 +47,12 @@ options:
type: str
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be
- set to V(false) when no other option exists. Prior to 1.9.3 the code
- defaulted to V(false).
+ - If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists.
type: bool
default: true
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install the overlay mozilla which is on the central overlays list
community.general.layman:
name: mozilla
@@ -81,7 +77,7 @@ EXAMPLES = '''
community.general.layman:
name: cvut
state: absent
-'''
+"""
import shutil
import traceback
diff --git a/plugins/modules/lbu.py b/plugins/modules/lbu.py
index c961b6060d..e91fd5e01a 100644
--- a/plugins/modules/lbu.py
+++ b/plugins/modules/lbu.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: lbu
short_description: Local Backup Utility for Alpine Linux
@@ -17,8 +16,7 @@ short_description: Local Backup Utility for Alpine Linux
version_added: '0.2.0'
description:
- - Manage Local Backup Utility of Alpine Linux in run-from-RAM mode
-
+ - Manage Local Backup Utility of Alpine Linux in run-from-RAM mode.
extends_documentation_fragment:
- community.general.attributes
@@ -31,24 +29,24 @@ attributes:
options:
commit:
description:
- - Control whether to commit changed files.
+ - Control whether to commit changed files.
type: bool
exclude:
description:
- - List of paths to exclude.
+ - List of paths to exclude.
type: list
elements: str
include:
description:
- - List of paths to include.
+ - List of paths to include.
type: list
elements: str
author:
- Kaarle Ritvanen (@kunkku)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Commit changed files (if any)
- name: Commit
community.general.lbu:
@@ -59,22 +57,22 @@ EXAMPLES = '''
community.general.lbu:
commit: true
exclude:
- - /etc/opt
+ - /etc/opt
# Include paths without committing
- name: Include file and directory
community.general.lbu:
include:
- - /root/.ssh/authorized_keys
- - /var/lib/misc
-'''
+ - /root/.ssh/authorized_keys
+ - /var/lib/misc
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Error message
+ description: Error message.
type: str
returned: on failure
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/ldap_attrs.py b/plugins/modules/ldap_attrs.py
index 7986833a6e..c7ccd42154 100644
--- a/plugins/modules/ldap_attrs.py
+++ b/plugins/modules/ldap_attrs.py
@@ -12,27 +12,17 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ldap_attrs
short_description: Add or remove multiple LDAP attribute values
description:
- Add or remove multiple LDAP attribute values.
notes:
- - This only deals with attributes on existing entries. To add or remove
- whole entries, see M(community.general.ldap_entry).
- - The default authentication settings will attempt to use a SASL EXTERNAL
- bind over a UNIX domain socket. This works well with the default Ubuntu
- install for example, which includes a cn=peercred,cn=external,cn=auth ACL
- rule allowing root to modify the server configuration. If you need to use
- a simple bind to access your server, pass the credentials in O(bind_dn)
- and O(bind_pw).
- - For O(state=present) and O(state=absent), all value comparisons are
- performed on the server for maximum accuracy. For O(state=exact), values
- have to be compared in Python, which obviously ignores LDAP matching
- rules. This should work out in most cases, but it is theoretically
- possible to see spurious changes when target and actual values are
- semantically identical but lexically distinct.
+ - This only deals with attributes on existing entries. To add or remove whole entries, see M(community.general.ldap_entry).
+ - For O(state=present) and O(state=absent), all value comparisons are performed on the server for maximum accuracy. For
+ O(state=exact), values have to be compared in Python, which obviously ignores LDAP matching rules. This should work out
+ in most cases, but it is theoretically possible to see spurious changes when target and actual values are semantically
+ identical but lexically distinct.
version_added: '0.2.0'
author:
- Jiri Tyr (@jtyr)
@@ -53,46 +43,39 @@ options:
choices: [present, absent, exact]
default: present
description:
- - The state of the attribute values. If V(present), all given attribute
- values will be added if they're missing. If V(absent), all given
- attribute values will be removed if present. If V(exact), the set of
- attribute values will be forced to exactly those provided and no others.
- If O(state=exact) and the attribute value is empty, all values for
+ - The state of the attribute values. If V(present), all given attribute values will be added if they are missing. If
+ V(absent), all given attribute values will be removed if present. If V(exact), the set of attribute values will be
+ forced to exactly those provided and no others. If O(state=exact) and the attribute value is empty, all values for
this attribute will be removed.
attributes:
required: true
type: dict
description:
- The attribute(s) and value(s) to add or remove.
- - Each attribute value can be a string for single-valued attributes or
- a list of strings for multi-valued attributes.
- - If you specify values for this option in YAML, please note that you can improve
- readability for long string values by using YAML block modifiers as seen in the
- examples for this module.
- - Note that when using values that YAML/ansible-core interprets as other types,
- like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if
- these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
+ - Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes.
+ - If you specify values for this option in YAML, please note that you can improve readability for long string values
+ by using YAML block modifiers as seen in the examples for this module.
+ - Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10)
+ (float), make sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
ordered:
required: false
type: bool
default: false
description:
- - If V(true), prepend list values with X-ORDERED index numbers in all
- attributes specified in the current task. This is useful mostly with
- C(olcAccess) attribute to easily manage LDAP Access Control Lists.
+ - If V(true), prepend list values with X-ORDERED index numbers in all attributes specified in the current task. This
+ is useful mostly with C(olcAccess) attribute to easily manage LDAP Access Control Lists.
extends_documentation_fragment:
- community.general.ldap.documentation
- community.general.attributes
-
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Configure directory number 1 for example.com
community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config
attributes:
- olcSuffix: dc=example,dc=com
+ olcSuffix: dc=example,dc=com
state: exact
# The complex argument format is required here to pass a list of ACL strings.
@@ -100,17 +83,17 @@ EXAMPLES = r'''
community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config
attributes:
- olcAccess:
- - >-
- {0}to attrs=userPassword,shadowLastChange
- by self write
- by anonymous auth
- by dn="cn=admin,dc=example,dc=com" write
- by * none'
- - >-
- {1}to dn.base="dc=example,dc=com"
- by dn="cn=admin,dc=example,dc=com" write
- by * read
+ olcAccess:
+ - >-
+ {0}to attrs=userPassword,shadowLastChange
+ by self write
+ by anonymous auth
+ by dn="cn=admin,dc=example,dc=com" write
+ by * none'
+ - >-
+ {1}to dn.base="dc=example,dc=com"
+ by dn="cn=admin,dc=example,dc=com" write
+ by * read
state: exact
# An alternative approach with automatic X-ORDERED numbering
@@ -118,17 +101,17 @@ EXAMPLES = r'''
community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config
attributes:
- olcAccess:
- - >-
- to attrs=userPassword,shadowLastChange
- by self write
- by anonymous auth
- by dn="cn=admin,dc=example,dc=com" write
- by * none'
- - >-
- to dn.base="dc=example,dc=com"
- by dn="cn=admin,dc=example,dc=com" write
- by * read
+ olcAccess:
+ - >-
+ to attrs=userPassword,shadowLastChange
+ by self write
+ by anonymous auth
+ by dn="cn=admin,dc=example,dc=com" write
+ by * none'
+ - >-
+ to dn.base="dc=example,dc=com"
+ by dn="cn=admin,dc=example,dc=com" write
+ by * read
ordered: true
state: exact
@@ -136,23 +119,23 @@ EXAMPLES = r'''
community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config
attributes:
- olcDbIndex:
- - objectClass eq
- - uid eq
+ olcDbIndex:
+ - objectClass eq
+ - uid eq
- name: Set up a root user, which we can use later to bootstrap the directory
community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config
attributes:
- olcRootDN: cn=root,dc=example,dc=com
- olcRootPW: "{SSHA}tabyipcHzhwESzRaGA7oQ/SDoBZQOGND"
+ olcRootDN: cn=root,dc=example,dc=com
+ olcRootPW: "{SSHA}tabyipcHzhwESzRaGA7oQ/SDoBZQOGND"
state: exact
- name: Remove an attribute with a specific value
community.general.ldap_attrs:
dn: uid=jdoe,ou=people,dc=example,dc=com
attributes:
- description: "An example user account"
+ description: "An example user account"
state: absent
server_uri: ldap://localhost/
bind_dn: cn=admin,dc=example,dc=com
@@ -162,22 +145,22 @@ EXAMPLES = r'''
community.general.ldap_attrs:
dn: uid=jdoe,ou=people,dc=example,dc=com
attributes:
- description: []
+ description: []
state: exact
server_uri: ldap://localhost/
bind_dn: cn=admin,dc=example,dc=com
bind_pw: password
-'''
+"""
-RETURN = r'''
+RETURN = r"""
modlist:
- description: list of modified parameters
+ description: List of modified parameters.
returned: success
type: list
sample:
- [2, "olcRootDN", ["cn=root,dc=example,dc=com"]]
-'''
+"""
import traceback
diff --git a/plugins/modules/ldap_entry.py b/plugins/modules/ldap_entry.py
index 5deaf7c4c4..230f6337ab 100644
--- a/plugins/modules/ldap_entry.py
+++ b/plugins/modules/ldap_entry.py
@@ -11,21 +11,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ldap_entry
short_description: Add or remove LDAP entries
description:
- - Add or remove LDAP entries. This module only asserts the existence or
- non-existence of an LDAP entry, not its attributes. To assert the
- attribute values of an entry, see M(community.general.ldap_attrs).
-notes:
- - The default authentication settings will attempt to use a SASL EXTERNAL
- bind over a UNIX domain socket. This works well with the default Ubuntu
- install for example, which includes a cn=peercred,cn=external,cn=auth ACL
- rule allowing root to modify the server configuration. If you need to use
- a simple bind to access your server, pass the credentials in O(bind_dn)
- and O(bind_pw).
+ - Add or remove LDAP entries. This module only asserts the existence or non-existence of an LDAP entry, not its attributes.
+ To assert the attribute values of an entry, see M(community.general.ldap_attrs).
author:
- Jiri Tyr (@jtyr)
requirements:
@@ -38,24 +29,19 @@ attributes:
options:
attributes:
description:
- - If O(state=present), attributes necessary to create an entry. Existing
- entries are never modified. To assert specific attribute values on an
- existing entry, use M(community.general.ldap_attrs) module instead.
- - Each attribute value can be a string for single-valued attributes or
- a list of strings for multi-valued attributes.
- - If you specify values for this option in YAML, please note that you can improve
- readability for long string values by using YAML block modifiers as seen in the
- examples for this module.
- - Note that when using values that YAML/ansible-core interprets as other types,
- like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if
- these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
+ - If O(state=present), attributes necessary to create an entry. Existing entries are never modified. To assert specific
+ attribute values on an existing entry, use M(community.general.ldap_attrs) module instead.
+ - Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes.
+ - If you specify values for this option in YAML, please note that you can improve readability for long string values
+ by using YAML block modifiers as seen in the examples for this module.
+ - Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10)
+ (float), make sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
type: dict
default: {}
objectClass:
description:
- - If O(state=present), value or list of values to use when creating
- the entry. It can either be a string or an actual list of
- strings.
+ - If O(state=present), value or list of values to use when creating the entry. It can either be a string or an actual
+ list of strings.
type: list
elements: str
state:
@@ -66,19 +52,17 @@ options:
type: str
recursive:
description:
- - If O(state=delete), a flag indicating whether a single entry or the
- whole branch must be deleted.
+ - If O(state=delete), a flag indicating whether a single entry or the whole branch must be deleted.
type: bool
default: false
version_added: 4.6.0
extends_documentation_fragment:
- community.general.ldap.documentation
- community.general.attributes
-
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Make sure we have a parent entry for users
community.general.ldap_entry:
dn: ou=users,dc=example,dc=com
@@ -103,19 +87,19 @@ EXAMPLES = """
attributes:
description: An LDAP Administrator
roleOccupant:
- - cn=Chocs Puddington,ou=Information Technology,dc=example,dc=com
- - cn=Alice Stronginthebrain,ou=Information Technology,dc=example,dc=com
+ - cn=Chocs Puddington,ou=Information Technology,dc=example,dc=com
+ - cn=Alice Stronginthebrain,ou=Information Technology,dc=example,dc=com
olcAccess:
- - >-
- {0}to attrs=userPassword,shadowLastChange
- by self write
- by anonymous auth
- by dn="cn=admin,dc=example,dc=com" write
- by * none'
- - >-
- {1}to dn.base="dc=example,dc=com"
- by dn="cn=admin,dc=example,dc=com" write
- by * read
+ - >-
+ {0}to attrs=userPassword,shadowLastChange
+ by self write
+ by anonymous auth
+ by dn="cn=admin,dc=example,dc=com" write
+ by * none'
+ - >-
+ {1}to dn.base="dc=example,dc=com"
+ by dn="cn=admin,dc=example,dc=com" write
+ by * read
- name: Get rid of an old entry
community.general.ldap_entry:
@@ -143,7 +127,7 @@ EXAMPLES = """
"""
-RETURN = """
+RETURN = r"""
# Default return values
"""
diff --git a/plugins/modules/ldap_inc.py b/plugins/modules/ldap_inc.py
new file mode 100644
index 0000000000..ea6788de66
--- /dev/null
+++ b/plugins/modules/ldap_inc.py
@@ -0,0 +1,243 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024, Philippe Duveau
+# Copyright (c) 2019, Maciej Delmanowski (ldap_attrs.py)
+# Copyright (c) 2017, Alexander Korinek (ldap_attrs.py)
+# Copyright (c) 2016, Peter Sagerson (ldap_attrs.py)
+# Copyright (c) 2016, Jiri Tyr (ldap_attrs.py)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# The code of this module is derived from that of ldap_attrs.py
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = r"""
+module: ldap_inc
+short_description: Use the Modify-Increment LDAP V3 feature to increment an attribute value
+version_added: 10.2.0
+description:
+ - Atomically increments the value of an attribute and return its new value.
+notes:
+ - When implemented by the directory server, the module uses the ModifyIncrement extension defined in L(RFC4525, https://www.rfc-editor.org/rfc/rfc4525.html)
+ and the control PostRead. This extension and the control are implemented in OpenLdap but not all directory servers implement
+ them. In this case, the module automatically uses a more classic method based on two phases, first the current value is
+ read then the modify operation remove the old value and add the new one in a single request. If the value has changed
+ by a concurrent call then the remove action will fail. Then the sequence is retried 3 times before raising an error to
+ the playbook. In an heavy modification environment, the module does not guarante to be systematically successful.
+ - This only deals with integer attribute of an existing entry. To modify attributes of an entry, see M(community.general.ldap_attrs)
+ or to add or remove whole entries, see M(community.general.ldap_entry).
+author:
+ - Philippe Duveau (@pduveau)
+requirements:
+ - python-ldap
+attributes:
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
+options:
+ dn:
+ required: true
+ type: str
+ description:
+ - The DN entry containing the attribute to increment.
+ attribute:
+ required: true
+ type: str
+ description:
+ - The attribute to increment.
+ increment:
+ required: false
+ type: int
+ default: 1
+ description:
+ - The value of the increment to apply.
+ method:
+ required: false
+ type: str
+ default: auto
+ choices: [auto, rfc4525, legacy]
+ description:
+ - If V(auto), the module determines automatically the method to use.
+ - If V(rfc4525) or V(legacy) force to use the corresponding method.
+extends_documentation_fragment:
+ - community.general.ldap.documentation
+ - community.general.attributes
+"""
+
+
+EXAMPLES = r"""
+- name: Increments uidNumber 1 Number for example.com
+ community.general.ldap_inc:
+ dn: "cn=uidNext,ou=unix-management,dc=example,dc=com"
+ attribute: "uidNumber"
+ increment: "1"
+ register: ldap_uidNumber_sequence
+
+- name: Modifies the user to define its identification number (uidNumber) when incrementation is successful
+ community.general.ldap_attrs:
+ dn: "cn=john,ou=posix-users,dc=example,dc=com"
+ state: present
+ attributes:
+ - uidNumber: "{{ ldap_uidNumber_sequence.value }}"
+ when: ldap_uidNumber_sequence.incremented
+"""
+
+
+RETURN = r"""
+incremented:
+ description:
+ - It is set to V(true) if the attribute value has changed.
+ returned: success
+ type: bool
+ sample: true
+
+attribute:
+ description:
+ - The name of the attribute that was incremented.
+ returned: success
+ type: str
+ sample: uidNumber
+
+value:
+ description:
+ - The new value after incrementing.
+ returned: success
+ type: str
+ sample: "2"
+
+rfc4525:
+ description:
+ - Is V(true) if the method used to increment is based on RFC4525, V(false) if legacy.
+ returned: success
+ type: bool
+ sample: true
+"""
+
+from ansible.module_utils.basic import AnsibleModule, missing_required_lib
+from ansible.module_utils.common.text.converters import to_native, to_bytes
+from ansible_collections.community.general.plugins.module_utils import deps
+from ansible_collections.community.general.plugins.module_utils.ldap import LdapGeneric, gen_specs, ldap_required_together
+
+with deps.declare("ldap", reason=missing_required_lib('python-ldap')):
+ import ldap
+ import ldap.controls.readentry
+
+
+class LdapInc(LdapGeneric):
+ def __init__(self, module):
+ LdapGeneric.__init__(self, module)
+ # Shortcuts
+ self.attr = self.module.params['attribute']
+ self.increment = self.module.params['increment']
+ self.method = self.module.params['method']
+
+ def inc_rfc4525(self):
+ return [(ldap.MOD_INCREMENT, self.attr, [to_bytes(str(self.increment))])]
+
+ def inc_legacy(self, curr_val, new_val):
+ return [(ldap.MOD_DELETE, self.attr, [to_bytes(curr_val)]),
+ (ldap.MOD_ADD, self.attr, [to_bytes(new_val)])]
+
+ def serverControls(self):
+ return [ldap.controls.readentry.PostReadControl(attrList=[self.attr])]
+
+ LDAP_MOD_INCREMENT = to_bytes("1.3.6.1.1.14")
+
+
+def main():
+ module = AnsibleModule(
+ argument_spec=gen_specs(
+ attribute=dict(type='str', required=True),
+ increment=dict(type='int', default=1, required=False),
+ method=dict(type='str', default='auto', choices=['auto', 'rfc4525', 'legacy']),
+ ),
+ supports_check_mode=True,
+ required_together=ldap_required_together(),
+ )
+
+ deps.validate(module)
+
+ # Instantiate the LdapAttr object
+ mod = LdapInc(module)
+
+ changed = False
+ ret = ""
+ rfc4525 = False
+
+ try:
+ if mod.increment != 0 and not module.check_mode:
+ changed = True
+
+ if mod.method != "auto":
+ rfc4525 = mod.method == "rfc425"
+ else:
+ rootDSE = mod.connection.search_ext_s(
+ base="",
+ scope=ldap.SCOPE_BASE,
+ attrlist=["*", "+"])
+ if len(rootDSE) == 1:
+ if to_bytes(ldap.CONTROL_POST_READ) in rootDSE[0][1]["supportedControl"] and (
+ mod.LDAP_MOD_INCREMENT in rootDSE[0][1]["supportedFeatures"] or
+ mod.LDAP_MOD_INCREMENT in rootDSE[0][1]["supportedExtension"]
+ ):
+ rfc4525 = True
+
+ if rfc4525:
+ dummy, dummy, dummy, resp_ctrls = mod.connection.modify_ext_s(
+ dn=mod.dn,
+ modlist=mod.inc_rfc4525(),
+ serverctrls=mod.serverControls(),
+ clientctrls=None)
+ if len(resp_ctrls) == 1:
+ ret = resp_ctrls[0].entry[mod.attr][0]
+
+ else:
+ tries = 0
+ max_tries = 3
+ while tries < max_tries:
+ tries = tries + 1
+ result = mod.connection.search_ext_s(
+ base=mod.dn,
+ scope=ldap.SCOPE_BASE,
+ filterstr="(%s=*)" % mod.attr,
+ attrlist=[mod.attr])
+ if len(result) != 1:
+ module.fail_json(msg="The entry does not exist or does not contain the specified attribute.")
+ return
+ try:
+ ret = str(int(result[0][1][mod.attr][0]) + mod.increment)
+ # if the current value first arg in inc_legacy has changed then the modify will fail
+ mod.connection.modify_s(
+ dn=mod.dn,
+ modlist=mod.inc_legacy(result[0][1][mod.attr][0], ret))
+ break
+ except ldap.NO_SUCH_ATTRIBUTE:
+ if tries == max_tries:
+ module.fail_json(msg="The increment could not be applied after " + str(max_tries) + " tries.")
+ return
+
+ else:
+ result = mod.connection.search_ext_s(
+ base=mod.dn,
+ scope=ldap.SCOPE_BASE,
+ filterstr="(%s=*)" % mod.attr,
+ attrlist=[mod.attr])
+ if len(result) == 1:
+ ret = str(int(result[0][1][mod.attr][0]) + mod.increment)
+ changed = mod.increment != 0
+ else:
+ module.fail_json(msg="The entry does not exist or does not contain the specified attribute.")
+
+ except Exception as e:
+ module.fail_json(msg="Attribute action failed.", details=to_native(e))
+
+ module.exit_json(changed=changed, incremented=changed, attribute=mod.attr, value=ret, rfc4525=rfc4525)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/plugins/modules/ldap_passwd.py b/plugins/modules/ldap_passwd.py
index 5044586b0f..b29254f8c6 100644
--- a/plugins/modules/ldap_passwd.py
+++ b/plugins/modules/ldap_passwd.py
@@ -9,21 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ldap_passwd
short_description: Set passwords in LDAP
description:
- - Set a password for an LDAP entry. This module only asserts that
- a given password is valid for a given entry. To assert the
- existence of an entry, see M(community.general.ldap_entry).
-notes:
- - The default authentication settings will attempt to use a SASL EXTERNAL
- bind over a UNIX domain socket. This works well with the default Ubuntu
- install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL
- rule allowing root to modify the server configuration. If you need to use
- a simple bind to access your server, pass the credentials in O(bind_dn)
- and O(bind_pw).
+ - Set a password for an LDAP entry. This module only asserts that a given password is valid for a given entry. To assert
+ the existence of an entry, see M(community.general.ldap_entry).
author:
- Keller Fuchs (@KellerFuchs)
requirements:
@@ -41,10 +32,9 @@ options:
extends_documentation_fragment:
- community.general.ldap.documentation
- community.general.attributes
+"""
-'''
-
-EXAMPLES = """
+EXAMPLES = r"""
- name: Set a password for the admin user
community.general.ldap_passwd:
dn: cn=admin,dc=example,dc=com
@@ -56,13 +46,13 @@ EXAMPLES = """
passwd: "{{ item.value }}"
with_dict:
alice: alice123123
- bob: "|30b!"
+ bob: "|30b!"
admin: "{{ vault_secret }}"
"""
-RETURN = """
+RETURN = r"""
modlist:
- description: list of modified parameters
+ description: List of modified parameters.
returned: success
type: list
sample:
diff --git a/plugins/modules/ldap_search.py b/plugins/modules/ldap_search.py
index 7958f86e0b..155e9859d5 100644
--- a/plugins/modules/ldap_search.py
+++ b/plugins/modules/ldap_search.py
@@ -10,19 +10,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r"""
----
module: ldap_search
version_added: '0.2.0'
short_description: Search for entries in a LDAP server
description:
- Return the results of an LDAP search.
-notes:
- - The default authentication settings will attempt to use a SASL EXTERNAL
- bind over a UNIX domain socket. This works well with the default Ubuntu
- install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL
- rule allowing root to modify the server configuration. If you need to use
- a simple bind to access your server, pass the credentials in O(bind_dn)
- and O(bind_pw).
author:
- Sebastian Pfahl (@eryx12o45)
requirements:
@@ -55,30 +47,27 @@ options:
type: list
elements: str
description:
- - A list of attributes for limiting the result. Use an
- actual list or a comma-separated string.
+ - A list of attributes for limiting the result. Use an actual list or a comma-separated string.
schema:
default: false
type: bool
description:
- - Set to V(true) to return the full attribute schema of entries, not
- their attribute values. Overrides O(attrs) when provided.
+ - Set to V(true) to return the full attribute schema of entries, not their attribute values. Overrides O(attrs) when
+ provided.
page_size:
default: 0
type: int
description:
- - The page size when performing a simple paged result search (RFC 2696).
- This setting can be tuned to reduce issues with timeouts and server limits.
+ - The page size when performing a simple paged result search (RFC 2696). This setting can be tuned to reduce issues
+ with timeouts and server limits.
- Setting the page size to V(0) (default) disables paged searching.
version_added: 7.1.0
base64_attributes:
description:
- - If provided, all attribute values returned that are listed in this option
- will be Base64 encoded.
- - If the special value V(*) appears in this list, all attributes will be
- Base64 encoded.
- - All other attribute values will be converted to UTF-8 strings. If they
- contain binary data, please note that invalid UTF-8 bytes will be omitted.
+ - If provided, all attribute values returned that are listed in this option will be Base64 encoded.
+ - If the special value V(*) appears in this list, all attributes will be Base64 encoded.
+ - All other attribute values will be converted to UTF-8 strings. If they contain binary data, please note that invalid
+ UTF-8 bytes will be omitted.
type: list
elements: str
version_added: 7.0.0
@@ -102,17 +91,15 @@ EXAMPLES = r"""
register: ldap_group_gids
"""
-RESULTS = """
+RESULTS = r"""
results:
description:
- For every entry found, one dictionary will be returned.
- Every dictionary contains a key C(dn) with the entry's DN as a value.
- - Every attribute of the entry found is added to the dictionary. If the key
- has precisely one value, that value is taken directly, otherwise the key's
- value is a list.
- - Note that all values (for single-element lists) and list elements (for multi-valued
- lists) will be UTF-8 strings. Some might contain Base64-encoded binary data; which
- ones is determined by the O(base64_attributes) option.
+ - Every attribute of the entry found is added to the dictionary. If the key has precisely one value, that value is taken
+ directly, otherwise the key's value is a list.
+ - Note that all values (for single-element lists) and list elements (for multi-valued lists) will be UTF-8 strings. Some
+ might contain Base64-encoded binary data; which ones is determined by the O(base64_attributes) option.
type: list
elements: dict
"""
diff --git a/plugins/modules/librato_annotation.py b/plugins/modules/librato_annotation.py
index ebfb751546..35fc810c65 100644
--- a/plugins/modules/librato_annotation.py
+++ b/plugins/modules/librato_annotation.py
@@ -9,74 +9,76 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: librato_annotation
-short_description: Create an annotation in librato
+short_description: Create an annotation in Librato
description:
- - Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created automatically
+ - Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created
+ automatically.
author: "Seth Edwards (@Sedward)"
requirements: []
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- user:
- type: str
- description:
- - Librato account username
- required: true
- api_key:
- type: str
- description:
- - Librato account api key
- required: true
- name:
- type: str
- description:
- - The annotation stream name
- - If the annotation stream does not exist, it will be created automatically
- required: false
- title:
- type: str
- description:
- - The title of an annotation is a string and may contain spaces
- - The title should be a short, high-level summary of the annotation e.g. v45 Deployment
- required: true
- source:
- type: str
- description:
- - A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population
- required: false
+ user:
+ type: str
description:
- type: str
- description:
- - The description contains extra metadata about a particular annotation
- - The description should contain specifics on the individual annotation e.g. Deployed 9b562b2 shipped new feature foo!
- required: false
- start_time:
- type: int
- description:
- - The unix timestamp indicating the time at which the event referenced by this annotation started
- required: false
- end_time:
- type: int
- description:
- - The unix timestamp indicating the time at which the event referenced by this annotation ended
- - For events that have a duration, this is a useful way to annotate the duration of the event
- required: false
- links:
- type: list
- elements: dict
- description:
- - See examples
-'''
+ - Librato account username.
+ required: true
+ api_key:
+ type: str
+ description:
+ - Librato account API key.
+ required: true
+ name:
+ type: str
+ description:
+ - The annotation stream name.
+ - If the annotation stream does not exist, it will be created automatically.
+ required: false
+ title:
+ type: str
+ description:
+ - The title of an annotation is a string and may contain spaces.
+ - The title should be a short, high-level summary of the annotation for example V(v45 Deployment).
+ required: true
+ source:
+ type: str
+ description:
+ - A string which describes the originating source of an annotation when that annotation is tracked across multiple members
+ of a population.
+ required: false
+ description:
+ type: str
+ description:
+ - The description contains extra metadata about a particular annotation.
+ - The description should contain specifics on the individual annotation for example V(Deployed 9b562b2 shipped new feature
+ foo!).
+ required: false
+ start_time:
+ type: int
+ description:
+ - The unix timestamp indicating the time at which the event referenced by this annotation started.
+ required: false
+ end_time:
+ type: int
+ description:
+ - The unix timestamp indicating the time at which the event referenced by this annotation ended.
+ - For events that have a duration, this is a useful way to annotate the duration of the event.
+ required: false
+ links:
+ type: list
+ elements: dict
+ description:
+ - See examples.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a simple annotation event with a source
community.general.librato_annotation:
user: user@example.com
@@ -105,7 +107,7 @@ EXAMPLES = '''
description: This is a detailed description of maintenance
start_time: 1395940006
end_time: 1395954406
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url
diff --git a/plugins/modules/linode.py b/plugins/modules/linode.py
index 9b0dabdff2..fcfcce4d0a 100644
--- a/plugins/modules/linode.py
+++ b/plugins/modules/linode.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: linode
short_description: Manage instances on the Linode Public Cloud
description:
@@ -24,34 +23,33 @@ attributes:
options:
state:
description:
- - Indicate desired state of the resource
- choices: [ absent, active, deleted, present, restarted, started, stopped ]
+ - Indicate desired state of the resource.
+ choices: [absent, active, deleted, present, restarted, started, stopped]
default: present
type: str
api_key:
description:
- - Linode API key.
- - E(LINODE_API_KEY) environment variable can be used instead.
+ - Linode API key.
+ - E(LINODE_API_KEY) environment variable can be used instead.
type: str
required: true
name:
description:
- - Name to give the instance (alphanumeric, dashes, underscore).
- - To keep sanity on the Linode Web Console, name is prepended with C(LinodeID-).
+ - Name to give the instance (alphanumeric, dashes, underscore).
+ - To keep sanity on the Linode Web Console, name is prepended with C(LinodeID-).
required: true
type: str
displaygroup:
description:
- - Add the instance to a Display Group in Linode Manager.
+ - Add the instance to a Display Group in Linode Manager.
type: str
default: ''
linode_id:
description:
- - Unique ID of a linode server. This value is read-only in the sense that
- if you specify it on creation of a Linode it will not be used. The
- Linode API generates these IDs and we can those generated value here to
- reference a Linode more specifically. This is useful for idempotence.
- aliases: [ lid ]
+ - Unique ID of a Linode server. This value is read-only in the sense that if you specify it on creation of a Linode
+ it will not be used. The Linode API generates these IDs and we can those generated value here to reference a Linode
+ more specifically. This is useful for idempotence.
+ aliases: [lid]
type: int
additional_disks:
description:
@@ -61,119 +59,118 @@ options:
elements: dict
alert_bwin_enabled:
description:
- - Set status of bandwidth in alerts.
+ - Set status of bandwidth in alerts.
type: bool
alert_bwin_threshold:
description:
- - Set threshold in MB of bandwidth in alerts.
+ - Set threshold in MB of bandwidth in alerts.
type: int
alert_bwout_enabled:
description:
- - Set status of bandwidth out alerts.
+ - Set status of bandwidth out alerts.
type: bool
alert_bwout_threshold:
description:
- - Set threshold in MB of bandwidth out alerts.
+ - Set threshold in MB of bandwidth out alerts.
type: int
alert_bwquota_enabled:
description:
- - Set status of bandwidth quota alerts as percentage of network transfer quota.
+ - Set status of bandwidth quota alerts as percentage of network transfer quota.
type: bool
alert_bwquota_threshold:
description:
- - Set threshold in MB of bandwidth quota alerts.
+ - Set threshold in MB of bandwidth quota alerts.
type: int
alert_cpu_enabled:
description:
- - Set status of receiving CPU usage alerts.
+ - Set status of receiving CPU usage alerts.
type: bool
alert_cpu_threshold:
description:
- - Set percentage threshold for receiving CPU usage alerts. Each CPU core adds 100% to total.
+ - Set percentage threshold for receiving CPU usage alerts. Each CPU core adds 100% to total.
type: int
alert_diskio_enabled:
description:
- - Set status of receiving disk IO alerts.
+ - Set status of receiving disk IO alerts.
type: bool
alert_diskio_threshold:
description:
- - Set threshold for average IO ops/sec over 2 hour period.
+ - Set threshold for average IO ops/sec over 2 hour period.
type: int
backupweeklyday:
description:
- - Day of the week to take backups.
+ - Day of the week to take backups.
type: int
backupwindow:
description:
- - The time window in which backups will be taken.
+ - The time window in which backups will be taken.
type: int
plan:
description:
- - plan to use for the instance (Linode plan)
+ - Plan to use for the instance (Linode plan).
type: int
payment_term:
description:
- - payment term to use for the instance (payment term in months)
+ - Payment term to use for the instance (payment term in months).
default: 1
- choices: [ 1, 12, 24 ]
+ choices: [1, 12, 24]
type: int
password:
description:
- - root password to apply to a new server (auto generated if missing)
+ - Root password to apply to a new server (auto generated if missing).
type: str
private_ip:
description:
- - Add private IPv4 address when Linode is created.
- - Default is V(false).
+ - Add private IPv4 address when Linode is created.
+ - Default is V(false).
type: bool
ssh_pub_key:
description:
- - SSH public key applied to root user
+ - SSH public key applied to root user.
type: str
swap:
description:
- - swap size in MB
+ - Swap size in MB.
default: 512
type: int
distribution:
description:
- - distribution to use for the instance (Linode Distribution)
+ - Distribution to use for the instance (Linode Distribution).
type: int
datacenter:
description:
- - datacenter to create an instance in (Linode Datacenter)
+ - Datacenter to create an instance in (Linode Datacenter).
type: int
kernel_id:
description:
- - kernel to use for the instance (Linode Kernel)
+ - Kernel to use for the instance (Linode Kernel).
type: int
wait:
description:
- - wait for the instance to be in state V(running) before returning
+ - Wait for the instance to be in state V(running) before returning.
type: bool
default: true
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
default: 300
type: int
watchdog:
description:
- - Set status of Lassie watchdog.
+ - Set status of Lassie watchdog.
type: bool
default: true
requirements:
- - linode-python
+ - linode-python
author:
-- Vincent Viallet (@zbal)
+ - Vincent Viallet (@zbal)
notes:
- Please note, linode-python does not have python 3 support.
- This module uses the now deprecated v3 of the Linode API.
- Please review U(https://www.linode.com/api/linode) for determining the required parameters.
-'''
-
-EXAMPLES = '''
+"""
+EXAMPLES = r"""
- name: Create a new Linode
community.general.linode:
name: linode-test1
@@ -185,97 +182,97 @@ EXAMPLES = '''
- name: Create a server with a private IP Address
community.general.linode:
- module: linode
- api_key: 'longStringFromLinodeApi'
- name: linode-test1
- plan: 1
- datacenter: 2
- distribution: 99
- password: 'superSecureRootPassword'
- private_ip: true
- ssh_pub_key: 'ssh-rsa qwerty'
- swap: 768
- wait: true
- wait_timeout: 600
- state: present
+ module: linode
+ api_key: 'longStringFromLinodeApi'
+ name: linode-test1
+ plan: 1
+ datacenter: 2
+ distribution: 99
+ password: 'superSecureRootPassword'
+ private_ip: true
+ ssh_pub_key: 'ssh-rsa qwerty'
+ swap: 768
+ wait: true
+ wait_timeout: 600
+ state: present
delegate_to: localhost
register: linode_creation
- name: Fully configure new server
community.general.linode:
- api_key: 'longStringFromLinodeApi'
- name: linode-test1
- plan: 4
- datacenter: 2
- distribution: 99
- kernel_id: 138
- password: 'superSecureRootPassword'
- private_ip: true
- ssh_pub_key: 'ssh-rsa qwerty'
- swap: 768
- wait: true
- wait_timeout: 600
- state: present
- alert_bwquota_enabled: true
- alert_bwquota_threshold: 80
- alert_bwin_enabled: true
- alert_bwin_threshold: 10
- alert_cpu_enabled: true
- alert_cpu_threshold: 210
- alert_bwout_enabled: true
- alert_bwout_threshold: 10
- alert_diskio_enabled: true
- alert_diskio_threshold: 10000
- backupweeklyday: 1
- backupwindow: 2
- displaygroup: 'test'
- additional_disks:
+ api_key: 'longStringFromLinodeApi'
+ name: linode-test1
+ plan: 4
+ datacenter: 2
+ distribution: 99
+ kernel_id: 138
+ password: 'superSecureRootPassword'
+ private_ip: true
+ ssh_pub_key: 'ssh-rsa qwerty'
+ swap: 768
+ wait: true
+ wait_timeout: 600
+ state: present
+ alert_bwquota_enabled: true
+ alert_bwquota_threshold: 80
+ alert_bwin_enabled: true
+ alert_bwin_threshold: 10
+ alert_cpu_enabled: true
+ alert_cpu_threshold: 210
+ alert_bwout_enabled: true
+ alert_bwout_threshold: 10
+ alert_diskio_enabled: true
+ alert_diskio_threshold: 10000
+ backupweeklyday: 1
+ backupwindow: 2
+ displaygroup: 'test'
+ additional_disks:
- {Label: 'disk1', Size: 2500, Type: 'raw'}
- {Label: 'newdisk', Size: 2000}
- watchdog: true
+ watchdog: true
delegate_to: localhost
register: linode_creation
- name: Ensure a running server (create if missing)
community.general.linode:
- api_key: 'longStringFromLinodeApi'
- name: linode-test1
- plan: 1
- datacenter: 2
- distribution: 99
- password: 'superSecureRootPassword'
- ssh_pub_key: 'ssh-rsa qwerty'
- swap: 768
- wait: true
- wait_timeout: 600
- state: present
+ api_key: 'longStringFromLinodeApi'
+ name: linode-test1
+ plan: 1
+ datacenter: 2
+ distribution: 99
+ password: 'superSecureRootPassword'
+ ssh_pub_key: 'ssh-rsa qwerty'
+ swap: 768
+ wait: true
+ wait_timeout: 600
+ state: present
delegate_to: localhost
register: linode_creation
- name: Delete a server
community.general.linode:
- api_key: 'longStringFromLinodeApi'
- name: linode-test1
- linode_id: "{{ linode_creation.instance.id }}"
- state: absent
+ api_key: 'longStringFromLinodeApi'
+ name: linode-test1
+ linode_id: "{{ linode_creation.instance.id }}"
+ state: absent
delegate_to: localhost
- name: Stop a server
community.general.linode:
- api_key: 'longStringFromLinodeApi'
- name: linode-test1
- linode_id: "{{ linode_creation.instance.id }}"
- state: stopped
+ api_key: 'longStringFromLinodeApi'
+ name: linode-test1
+ linode_id: "{{ linode_creation.instance.id }}"
+ state: stopped
delegate_to: localhost
- name: Reboot a server
community.general.linode:
- api_key: 'longStringFromLinodeApi'
- name: linode-test1
- linode_id: "{{ linode_creation.instance.id }}"
- state: restarted
+ api_key: 'longStringFromLinodeApi'
+ name: linode-test1
+ linode_id: "{{ linode_creation.instance.id }}"
+ state: restarted
delegate_to: localhost
-'''
+"""
import time
import traceback
diff --git a/plugins/modules/linode_v4.py b/plugins/modules/linode_v4.py
index da885f3a5f..b650f7f104 100644
--- a/plugins/modules/linode_v4.py
+++ b/plugins/modules/linode_v4.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: linode_v4
short_description: Manage instances on the Linode cloud
description: Manage instances on the Linode cloud.
@@ -18,9 +17,8 @@ requirements:
author:
- Luke Murphy (@decentral1se)
notes:
- - No Linode resizing is currently implemented. This module will, in time,
- replace the current Linode module which uses deprecated API bindings on the
- Linode side.
+ - No Linode resizing is currently implemented. This module will, in time, replace the current Linode module which uses deprecated
+ API bindings on the Linode side.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -31,52 +29,44 @@ attributes:
options:
region:
description:
- - The region of the instance. This is a required parameter only when
- creating Linode instances. See
- U(https://www.linode.com/docs/api/regions/).
+ - The region of the instance. This is a required parameter only when creating Linode instances. See U(https://www.linode.com/docs/api/regions/).
type: str
image:
description:
- - The image of the instance. This is a required parameter only when
- creating Linode instances. See
- U(https://www.linode.com/docs/api/images/).
+ - The image of the instance. This is a required parameter only when creating Linode instances.
+ - See U(https://www.linode.com/docs/api/images/).
type: str
type:
description:
- - The type of the instance. This is a required parameter only when
- creating Linode instances. See
- U(https://www.linode.com/docs/api/linode-types/).
+ - The type of the instance. This is a required parameter only when creating Linode instances.
+ - See U(https://www.linode.com/docs/api/linode-types/).
type: str
label:
description:
- - The instance label. This label is used as the main determiner for
- idempotence for the module and is therefore mandatory.
+ - The instance label. This label is used as the main determiner for idempotence for the module and is therefore mandatory.
type: str
required: true
group:
description:
- - The group that the instance should be marked under. Please note, that
- group labelling is deprecated but still supported. The encouraged
- method for marking instances is to use tags.
+ - The group that the instance should be marked under. Please note, that group labelling is deprecated but still supported.
+ The encouraged method for marking instances is to use tags.
type: str
private_ip:
description:
- - If V(true), the created Linode will have private networking enabled and
- assigned a private IPv4 address.
+ - If V(true), the created Linode will have private networking enabled and assigned a private IPv4 address.
type: bool
default: false
version_added: 3.0.0
tags:
description:
- - The tags that the instance should be marked under. See
- U(https://www.linode.com/docs/api/tags/).
+ - The tags that the instance should be marked under.
+ - See U(https://www.linode.com/docs/api/tags/).
type: list
elements: str
root_pass:
description:
- - The password for the root user. If not specified, one will be
- generated. This generated password will be available in the task
- success JSON.
+ - The password for the root user. If not specified, one will be generated. This generated password will be available
+ in the task success JSON.
type: str
authorized_keys:
description:
@@ -88,33 +78,31 @@ options:
- The desired instance state.
type: str
choices:
- - present
- - absent
+ - present
+ - absent
required: true
access_token:
description:
- - The Linode API v4 access token. It may also be specified by exposing
- the E(LINODE_ACCESS_TOKEN) environment variable. See
- U(https://www.linode.com/docs/api#access-and-authentication).
+ - The Linode API v4 access token. It may also be specified by exposing the E(LINODE_ACCESS_TOKEN) environment variable.
+ - See U(https://www.linode.com/docs/api#access-and-authentication).
required: true
type: str
stackscript_id:
description:
- The numeric ID of the StackScript to use when creating the instance.
- See U(https://www.linode.com/docs/api/stackscripts/).
+ - See U(https://www.linode.com/docs/api/stackscripts/).
type: int
version_added: 1.3.0
stackscript_data:
description:
- - An object containing arguments to any User Defined Fields present in
- the StackScript used when creating the instance.
- Only valid when a stackscript_id is provided.
- See U(https://www.linode.com/docs/api/stackscripts/).
+ - An object containing arguments to any User Defined Fields present in the StackScript used when creating the instance.
+ Only valid when a O(stackscript_id) is provided.
+ - See U(https://www.linode.com/docs/api/stackscripts/).
type: dict
version_added: 1.3.0
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create a new Linode.
community.general.linode_v4:
label: new-linode
@@ -135,7 +123,7 @@ EXAMPLES = """
state: absent
"""
-RETURN = """
+RETURN = r"""
instance:
description: The instance description in JSON serialized form.
returned: Always.
diff --git a/plugins/modules/listen_ports_facts.py b/plugins/modules/listen_ports_facts.py
index 08030a8b37..9f9eb66481 100644
--- a/plugins/modules/listen_ports_facts.py
+++ b/plugins/modules/listen_ports_facts.py
@@ -8,21 +8,19 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: listen_ports_facts
author:
- - Nathan Davison (@ndavison)
+ - Nathan Davison (@ndavison)
description:
- - Gather facts on processes listening on TCP and UDP ports using the C(netstat) or C(ss) commands.
- - This module currently supports Linux only.
+ - Gather facts on processes listening on TCP and UDP ports using the C(netstat) or C(ss) commands.
+ - This module currently supports Linux only.
requirements:
- netstat or ss
short_description: Gather facts on processes listening on TCP and UDP ports
notes:
- - |
- C(ss) returns all processes for each listen address and port.
- This plugin will return each of them, so multiple entries for the same listen address and port are likely in results.
+ - C(ss) returns all processes for each listen address and port.
+ - This plugin will return each of them, so multiple entries for the same listen address and port are likely in results.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.facts
@@ -31,7 +29,7 @@ options:
command:
description:
- Override which command to use for fetching listen ports.
- - 'By default module will use first found supported command on the system (in alphanumerical order).'
+ - By default module will use first found supported command on the system (in alphanumerical order).
type: str
choices:
- netstat
@@ -39,15 +37,15 @@ options:
version_added: 4.1.0
include_non_listening:
description:
- - Show both listening and non-listening sockets (for TCP this means established connections).
- - Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state),
- RV(ansible_facts.tcp_listen[].foreign_address), and RV(ansible_facts.udp_listen[].foreign_address) to the returned facts.
+ - Show both listening and non-listening sockets (for TCP this means established connections).
+ - Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state), RV(ansible_facts.tcp_listen[].foreign_address),
+ and RV(ansible_facts.udp_listen[].foreign_address) to the returned facts.
type: bool
default: false
version_added: 5.4.0
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather facts on listening ports
community.general.listen_ports_facts:
@@ -77,11 +75,11 @@ EXAMPLES = r'''
community.general.listen_ports_facts:
command: 'netstat'
include_non_listening: true
-'''
+"""
-RETURN = r'''
+RETURN = r"""
ansible_facts:
- description: Dictionary containing details of TCP and UDP ports with listening servers
+ description: Dictionary containing details of TCP and UDP ports with listening servers.
returned: always
type: complex
contains:
@@ -189,7 +187,7 @@ ansible_facts:
returned: always
type: str
sample: "root"
-'''
+"""
import re
import platform
diff --git a/plugins/modules/lldp.py b/plugins/modules/lldp.py
index fb608ff138..7f4a820257 100644
--- a/plugins/modules/lldp.py
+++ b/plugins/modules/lldp.py
@@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: lldp
-requirements: [ lldpctl ]
-short_description: Get details reported by lldp
+requirements: [lldpctl]
+short_description: Get details reported by LLDP
description:
- - Reads data out of lldpctl
+ - Reads data out of C(lldpctl).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -23,28 +22,32 @@ attributes:
support: none
diff_mode:
support: none
-options: {}
+options:
+ multivalues:
+ description: If lldpctl outputs an attribute multiple time represent all values as a list.
+ required: false
+ type: bool
+ default: false
author: "Andy Hill (@andyhky)"
notes:
- - Requires lldpd running and lldp enabled on switches
-'''
+ - Requires C(lldpd) running and LLDP enabled on switches.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Retrieve switch/port information
- - name: Gather information from lldp
- community.general.lldp:
+- name: Gather information from LLDP
+ community.general.lldp:
- - name: Print each switch/port
- ansible.builtin.debug:
+- name: Print each switch/port
+ ansible.builtin.debug:
msg: "{{ lldp[item]['chassis']['name'] }} / {{ lldp[item]['port']['ifname'] }}"
- with_items: "{{ lldp.keys() }}"
+ with_items: "{{ lldp.keys() }}"
# TASK: [Print each switch/port] ***********************************************************
# ok: [10.13.0.22] => (item=eth2) => {"item": "eth2", "msg": "switch1.example.com / Gi0/24"}
# ok: [10.13.0.22] => (item=eth1) => {"item": "eth1", "msg": "switch2.example.com / Gi0/3"}
# ok: [10.13.0.22] => (item=eth0) => {"item": "eth0", "msg": "switch3.example.com / Gi0/3"}
-
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
@@ -55,26 +58,49 @@ def gather_lldp(module):
if output:
output_dict = {}
current_dict = {}
- lldp_entries = output.split("\n")
+ lldp_entries = output.strip().split("\n")
+ final = ""
for entry in lldp_entries:
if entry.startswith('lldp'):
path, value = entry.strip().split("=", 1)
path = path.split(".")
path_components, final = path[:-1], path[-1]
+ elif final in current_dict and isinstance(current_dict[final], str):
+ current_dict[final] += '\n' + entry
+ continue
+ elif final in current_dict and isinstance(current_dict[final], list):
+ current_dict[final][-1] += '\n' + entry
+ continue
else:
- value = current_dict[final] + '\n' + entry
+ continue
current_dict = output_dict
for path_component in path_components:
current_dict[path_component] = current_dict.get(path_component, {})
+ if not isinstance(current_dict[path_component], dict):
+ current_dict[path_component] = {'value': current_dict[path_component]}
current_dict = current_dict[path_component]
- current_dict[final] = value
+
+ if final in current_dict and isinstance(current_dict[final], dict) and module.params['multivalues']:
+ current_dict = current_dict[final]
+ final = 'value'
+
+ if final not in current_dict or not module.params['multivalues']:
+ current_dict[final] = value
+ elif isinstance(current_dict[final], str):
+ current_dict[final] = [current_dict[final], value]
+ elif isinstance(current_dict[final], list):
+ current_dict[final].append(value)
+
return output_dict
def main():
- module = AnsibleModule({})
+ module_args = dict(
+ multivalues=dict(type='bool', required=False, default=False)
+ )
+ module = AnsibleModule(module_args)
lldp_output = gather_lldp(module)
try:
diff --git a/plugins/modules/locale_gen.py b/plugins/modules/locale_gen.py
index 8886cdc9cd..db9ea191e8 100644
--- a/plugins/modules/locale_gen.py
+++ b/plugins/modules/locale_gen.py
@@ -8,40 +8,48 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: locale_gen
short_description: Creates or removes locales
description:
- - Manages locales by editing /etc/locale.gen and invoking locale-gen.
+ - Manages locales in Debian and Ubuntu systems.
author:
- - Augustus Kling (@AugustusKling)
+ - Augustus Kling (@AugustusKling)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- type: list
- elements: str
- description:
- - Name and encoding of the locales, such as V(en_GB.UTF-8).
- - Before community.general 9.3.0, this was a string. Using a string still works.
- required: true
- state:
- type: str
- description:
- - Whether the locale shall be present.
- choices: [ absent, present ]
- default: present
+ name:
+ type: list
+ elements: str
+ description:
+ - Name and encoding of the locales, such as V(en_GB.UTF-8).
+ - Before community.general 9.3.0, this was a string. Using a string still works.
+ required: true
+ state:
+ type: str
+ description:
+ - Whether the locales shall be present.
+ choices: [absent, present]
+ default: present
notes:
- - This module does not support RHEL-based systems.
-'''
+ - If C(/etc/locale.gen) exists, the module will assume to be using the B(glibc) mechanism, else if C(/var/lib/locales/supported.d/)
+ exists it will assume to be using the B(ubuntu_legacy) mechanism, else it will raise an error.
+ - When using glibc mechanism, it will manage locales by editing C(/etc/locale.gen) and running C(locale-gen).
+ - When using ubuntu_legacy mechanism, it will manage locales by editing C(/var/lib/locales/supported.d/local) and then running
+ C(locale-gen).
+ - Please note that the code path that uses ubuntu_legacy mechanism has not been tested for a while, because Ubuntu is already
+ using the glibc mechanism. There is no support for that, given our inability to test it. Therefore, that mechanism is
+ B(deprecated) and will be removed in community.general 13.0.0.
+ - Currently the module is B(only supported for Debian and Ubuntu) systems.
+ - This module requires the package C(locales) installed in Debian and Ubuntu systems.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Ensure a locale exists
community.general.locale_gen:
name: de_CH.UTF-8
@@ -53,7 +61,19 @@ EXAMPLES = '''
- en_GB.UTF-8
- nl_NL.UTF-8
state: present
-'''
+"""
+
+RETURN = r"""
+mechanism:
+ description: Mechanism used to deploy the locales.
+ type: str
+ choices:
+ - glibc
+ - ubuntu_legacy
+ returned: success
+ sample: glibc
+ version_added: 10.2.0
+"""
import os
import re
@@ -64,22 +84,25 @@ from ansible_collections.community.general.plugins.module_utils.mh.deco import c
from ansible_collections.community.general.plugins.module_utils.locale_gen import locale_runner, locale_gen_runner
-class LocaleGen(StateModuleHelper):
- LOCALE_NORMALIZATION = {
- ".utf8": ".UTF-8",
- ".eucjp": ".EUC-JP",
- ".iso885915": ".ISO-8859-15",
- ".cp1251": ".CP1251",
- ".koi8r": ".KOI8-R",
- ".armscii8": ".ARMSCII-8",
- ".euckr": ".EUC-KR",
- ".gbk": ".GBK",
- ".gb18030": ".GB18030",
- ".euctw": ".EUC-TW",
- }
- LOCALE_GEN = "/etc/locale.gen"
- LOCALE_SUPPORTED = "/var/lib/locales/supported.d/"
+ETC_LOCALE_GEN = "/etc/locale.gen"
+VAR_LIB_LOCALES = "/var/lib/locales/supported.d"
+VAR_LIB_LOCALES_LOCAL = os.path.join(VAR_LIB_LOCALES, "local")
+SUPPORTED_LOCALES = "/usr/share/i18n/SUPPORTED"
+LOCALE_NORMALIZATION = {
+ ".utf8": ".UTF-8",
+ ".eucjp": ".EUC-JP",
+ ".iso885915": ".ISO-8859-15",
+ ".cp1251": ".CP1251",
+ ".koi8r": ".KOI8-R",
+ ".armscii8": ".ARMSCII-8",
+ ".euckr": ".EUC-KR",
+ ".gbk": ".GBK",
+ ".gb18030": ".GB18030",
+ ".euctw": ".EUC-TW",
+}
+
+class LocaleGen(StateModuleHelper):
output_params = ["name"]
module = dict(
argument_spec=dict(
@@ -91,14 +114,35 @@ class LocaleGen(StateModuleHelper):
use_old_vardict = False
def __init_module__(self):
- self.vars.set("ubuntu_mode", False)
- if os.path.exists(self.LOCALE_SUPPORTED):
+ self.MECHANISMS = dict(
+ ubuntu_legacy=dict(
+ available=SUPPORTED_LOCALES,
+ apply_change=self.apply_change_ubuntu_legacy,
+ ),
+ glibc=dict(
+ available=SUPPORTED_LOCALES,
+ apply_change=self.apply_change_glibc,
+ ),
+ )
+
+ if os.path.exists(ETC_LOCALE_GEN):
+ self.vars.ubuntu_mode = False
+ self.vars.mechanism = "glibc"
+ elif os.path.exists(VAR_LIB_LOCALES):
self.vars.ubuntu_mode = True
+ self.vars.mechanism = "ubuntu_legacy"
+ self.module.deprecate(
+ "On this machine mechanism=ubuntu_legacy is used. This mechanism is deprecated and will be removed from"
+ " in community.general 13.0.0. If you see this message on a modern Debian or Ubuntu version,"
+ " please create an issue in the community.general repository",
+ version="13.0.0", collection_name="community.general"
+ )
else:
- if not os.path.exists(self.LOCALE_GEN):
- self.do_raise("{0} and {1} are missing. Is the package \"locales\" installed?".format(
- self.LOCALE_SUPPORTED, self.LOCALE_GEN
- ))
+ self.do_raise('{0} and {1} are missing. Is the package "locales" installed?'.format(
+ VAR_LIB_LOCALES, ETC_LOCALE_GEN
+ ))
+
+ self.runner = locale_runner(self.module)
self.assert_available()
self.vars.set("is_present", self.is_present(), output=False)
@@ -116,30 +160,26 @@ class LocaleGen(StateModuleHelper):
checking either :
* if the locale is present in /etc/locales.gen
* or if the locale is present in /usr/share/i18n/SUPPORTED"""
- __regexp = r'^#?\s*(?P\S+[\._\S]+) (?P\S+)\s*$'
- if self.vars.ubuntu_mode:
- __locales_available = '/usr/share/i18n/SUPPORTED'
- else:
- __locales_available = '/etc/locale.gen'
+ regexp = r'^\s*#?\s*(?P\S+[\._\S]+) (?P\S+)\s*$'
+ locales_available = self.MECHANISMS[self.vars.mechanism]["available"]
- re_compiled = re.compile(__regexp)
- with open(__locales_available, 'r') as fd:
+ re_compiled = re.compile(regexp)
+ with open(locales_available, 'r') as fd:
lines = fd.readlines()
- res = [re_compiled.match(line) for line in lines]
- if self.verbosity >= 4:
- self.vars.available_lines = lines
+ res = [re_compiled.match(line) for line in lines]
+ self.vars.set("available_lines", lines, verbosity=4)
- locales_not_found = []
- for locale in self.vars.name:
- # Check if the locale is not found in any of the matches
- if not any(match and match.group("locale") == locale for match in res):
- locales_not_found.append(locale)
+ locales_not_found = []
+ for locale in self.vars.name:
+ # Check if the locale is not found in any of the matches
+ if not any(match and match.group("locale") == locale for match in res):
+ locales_not_found.append(locale)
# locale may be installed but not listed in the file, for example C.UTF-8 in some systems
locales_not_found = self.locale_get_not_present(locales_not_found)
if locales_not_found:
- self.do_raise("The following locales you've entered are not available on your system: {0}".format(', '.join(locales_not_found)))
+ self.do_raise("The following locales you have entered are not available on your system: {0}".format(', '.join(locales_not_found)))
def is_present(self):
return not self.locale_get_not_present(self.vars.name)
@@ -161,13 +201,13 @@ class LocaleGen(StateModuleHelper):
def fix_case(self, name):
"""locale -a might return the encoding in either lower or upper case.
Passing through this function makes them uniform for comparisons."""
- for s, r in self.LOCALE_NORMALIZATION.items():
+ for s, r in LOCALE_NORMALIZATION.items():
name = name.replace(s, r)
return name
- def set_locale(self, names, enabled=True):
+ def set_locale_glibc(self, names, enabled=True):
""" Sets the state of the locale. Defaults to enabled. """
- with open("/etc/locale.gen", 'r') as fr:
+ with open(ETC_LOCALE_GEN, 'r') as fr:
lines = fr.readlines()
locale_regexes = []
@@ -186,10 +226,10 @@ class LocaleGen(StateModuleHelper):
lines[i] = search.sub(replace, lines[i])
# Write the modified content back to the file
- with open("/etc/locale.gen", 'w') as fw:
+ with open(ETC_LOCALE_GEN, 'w') as fw:
fw.writelines(lines)
- def apply_change(self, targetState, names):
+ def apply_change_glibc(self, targetState, names):
"""Create or remove locale.
Keyword arguments:
@@ -197,13 +237,13 @@ class LocaleGen(StateModuleHelper):
names -- Names list including encoding such as de_CH.UTF-8.
"""
- self.set_locale(names, enabled=(targetState == "present"))
+ self.set_locale_glibc(names, enabled=(targetState == "present"))
runner = locale_gen_runner(self.module)
with runner() as ctx:
ctx.run()
- def apply_change_ubuntu(self, targetState, names):
+ def apply_change_ubuntu_legacy(self, targetState, names):
"""Create or remove locale.
Keyword arguments:
@@ -219,9 +259,9 @@ class LocaleGen(StateModuleHelper):
ctx.run()
else:
# Delete locale involves discarding the locale from /var/lib/locales/supported.d/local and regenerating all locales.
- with open("/var/lib/locales/supported.d/local", "r") as fr:
+ with open(VAR_LIB_LOCALES_LOCAL, "r") as fr:
content = fr.readlines()
- with open("/var/lib/locales/supported.d/local", "w") as fw:
+ with open(VAR_LIB_LOCALES_LOCAL, "w") as fw:
for line in content:
locale, charset = line.split(' ')
if locale not in names:
@@ -235,10 +275,7 @@ class LocaleGen(StateModuleHelper):
def __state_fallback__(self):
if self.vars.state_tracking == self.vars.state:
return
- if self.vars.ubuntu_mode:
- self.apply_change_ubuntu(self.vars.state, self.vars.name)
- else:
- self.apply_change(self.vars.state, self.vars.name)
+ self.MECHANISMS[self.vars.mechanism]["apply_change"](self.vars.state, self.vars.name)
def main():
diff --git a/plugins/modules/logentries.py b/plugins/modules/logentries.py
index f177cf4546..420f054fac 100644
--- a/plugins/modules/logentries.py
+++ b/plugins/modules/logentries.py
@@ -9,49 +9,49 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: logentries
author: "Ivan Vanderbyl (@ivanvanderbyl)"
-short_description: Module for tracking logs via logentries.com
+short_description: Module for tracking logs using U(logentries.com)
description:
- - Sends logs to LogEntries in realtime
+ - Sends logs to LogEntries in realtime.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- path:
- type: str
- description:
- - path to a log file
- required: true
- state:
- type: str
- description:
- - following state of the log
- choices: [ 'present', 'absent', 'followed', 'unfollowed' ]
- required: false
- default: present
- name:
- type: str
- description:
- - name of the log
- required: false
- logtype:
- type: str
- description:
- - type of the log
- required: false
- aliases: [type]
+ path:
+ type: str
+ description:
+ - Path to a log file.
+ required: true
+ state:
+ type: str
+ description:
+ - Following state of the log.
+ choices: ['present', 'absent', 'followed', 'unfollowed']
+ required: false
+ default: present
+ name:
+ type: str
+ description:
+ - Name of the log.
+ required: false
+ logtype:
+ type: str
+ description:
+ - Type of the log.
+ required: false
+ aliases: [type]
notes:
- - Requires the LogEntries agent which can be installed following the instructions at logentries.com
-'''
-EXAMPLES = '''
+ - Requires the LogEntries agent which can be installed following the instructions at U(logentries.com).
+"""
+
+EXAMPLES = r"""
- name: Track nginx logs
community.general.logentries:
path: /var/log/nginx/access.log
@@ -62,7 +62,7 @@ EXAMPLES = '''
community.general.logentries:
path: /var/log/nginx/error.log
state: absent
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/logentries_msg.py b/plugins/modules/logentries_msg.py
index 03851ad1f4..dd3b88d624 100644
--- a/plugins/modules/logentries_msg.py
+++ b/plugins/modules/logentries_msg.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: logentries_msg
short_description: Send a message to logentries
description:
- - Send a message to logentries
+ - Send a message to logentries.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -36,24 +35,24 @@ options:
api:
type: str
description:
- - API endpoint
+ - API endpoint.
default: data.logentries.com
port:
type: int
description:
- - API endpoint port
+ - API endpoint port.
default: 80
author: "Jimmy Tang (@jcftang) "
-'''
+"""
-RETURN = '''# '''
+RETURN = """# """
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Send a message to logentries
community.general.logentries_msg:
- token=00000000-0000-0000-0000-000000000000
- msg="{{ ansible_hostname }}"
-'''
+ token: 00000000-0000-0000-0000-000000000000
+ msg: "{{ ansible_hostname }}"
+"""
import socket
diff --git a/plugins/modules/logstash_plugin.py b/plugins/modules/logstash_plugin.py
index 7ee118ff28..ba7bdc2cc5 100644
--- a/plugins/modules/logstash_plugin.py
+++ b/plugins/modules/logstash_plugin.py
@@ -8,53 +8,51 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: logstash_plugin
short_description: Manage Logstash plugins
description:
- - Manages Logstash plugins.
+ - Manages Logstash plugins.
author: Loic Blot (@nerzhul)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- type: str
- description:
- - Install plugin with that name.
- required: true
- state:
- type: str
- description:
- - Apply plugin state.
- choices: ["present", "absent"]
- default: present
- plugin_bin:
- type: path
- description:
- - Specify logstash-plugin to use for plugin management.
- default: /usr/share/logstash/bin/logstash-plugin
- proxy_host:
- type: str
- description:
- - Proxy host to use during plugin installation.
- proxy_port:
- type: str
- description:
- - Proxy port to use during plugin installation.
- version:
- type: str
- description:
- - Specify plugin Version of the plugin to install.
- If plugin exists with previous version, it will NOT be updated.
-'''
+ name:
+ type: str
+ description:
+ - Install plugin with that name.
+ required: true
+ state:
+ type: str
+ description:
+ - Apply plugin state.
+ choices: ["present", "absent"]
+ default: present
+ plugin_bin:
+ type: path
+ description:
+ - Specify logstash-plugin to use for plugin management.
+ default: /usr/share/logstash/bin/logstash-plugin
+ proxy_host:
+ type: str
+ description:
+ - Proxy host to use during plugin installation.
+ proxy_port:
+ type: str
+ description:
+ - Proxy port to use during plugin installation.
+ version:
+ type: str
+ description:
+ - Specify plugin Version of the plugin to install. If plugin exists with previous version, it will NOT be updated.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install Logstash beats input plugin
community.general.logstash_plugin:
state: present
@@ -77,7 +75,7 @@ EXAMPLES = '''
name: logstash-input-beats
environment:
LS_JAVA_OPTS: "-Xms256m -Xmx256m"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/lvg.py b/plugins/modules/lvg.py
index 7ff7e3a2e7..b16cdd87a2 100644
--- a/plugins/modules/lvg.py
+++ b/plugins/modules/lvg.py
@@ -9,10 +9,9 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
-- Alexander Bulimov (@abulimov)
+ - Alexander Bulimov (@abulimov)
module: lvg
short_description: Configure LVM volume groups
description:
@@ -27,78 +26,84 @@ attributes:
options:
vg:
description:
- - The name of the volume group.
+ - The name of the volume group.
type: str
required: true
pvs:
description:
- - List of comma-separated devices to use as physical devices in this volume group.
- - Required when creating or resizing volume group.
- - The module will take care of running pvcreate if needed.
+ - List of comma-separated devices to use as physical devices in this volume group.
+ - Required when creating or resizing volume group.
+ - The module will take care of running pvcreate if needed.
+ - O(remove_extra_pvs) controls whether or not unspecified physical devices are removed from the volume group.
type: list
elements: str
pesize:
description:
- - "The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector
- (where the sector size is the largest sector size of the PVs currently used in the VG),
- or at least 128KiB."
- - O(pesize) can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte.
+ - The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector (where the sector size is the
+ largest sector size of the PVs currently used in the VG), or at least 128KiB.
+ - O(pesize) can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte.
type: str
default: "4"
pv_options:
description:
- - Additional options to pass to C(pvcreate) when creating the volume group.
+ - Additional options to pass to C(pvcreate) when creating the volume group.
type: str
default: ''
pvresize:
description:
- - If V(true), resize the physical volume to the maximum available size.
+ - If V(true), resize the physical volume to the maximum available size.
type: bool
default: false
version_added: '0.2.0'
vg_options:
description:
- - Additional options to pass to C(vgcreate) when creating the volume group.
+ - Additional options to pass to C(vgcreate) when creating the volume group.
type: str
default: ''
state:
description:
- - Control if the volume group exists and it's state.
- - The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0
- - "If V(active) or V(inactive), the module manages the VG's logical volumes current state.
- The module also handles the VG's autoactivation state if supported
- unless when creating a volume group and the autoactivation option specified in O(vg_options)."
+ - Control if the volume group exists and its state.
+ - The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0.
+ - If V(active) or V(inactive), the module manages the VG's logical volumes current state. The module also handles the
+ VG's autoactivation state if supported unless when creating a volume group and the autoactivation option specified
+ in O(vg_options).
type: str
- choices: [ absent, present, active, inactive ]
+ choices: [absent, present, active, inactive]
default: present
force:
description:
- - If V(true), allows to remove volume group with logical volumes.
+ - If V(true), allows to remove volume group with logical volumes.
type: bool
default: false
reset_vg_uuid:
description:
- - Whether the volume group's UUID is regenerated.
- - This is B(not idempotent). Specifying this parameter always results in a change.
+ - Whether the volume group's UUID is regenerated.
+ - This is B(not idempotent). Specifying this parameter always results in a change.
type: bool
default: false
version_added: 7.1.0
reset_pv_uuid:
description:
- - Whether the volume group's physical volumes' UUIDs are regenerated.
- - This is B(not idempotent). Specifying this parameter always results in a change.
+ - Whether the volume group's physical volumes' UUIDs are regenerated.
+ - This is B(not idempotent). Specifying this parameter always results in a change.
type: bool
default: false
version_added: 7.1.0
+ remove_extra_pvs:
+ description:
+ - Remove physical volumes from the volume group which are not in O(pvs).
+ type: bool
+ default: true
+ version_added: 10.4.0
seealso:
-- module: community.general.filesystem
-- module: community.general.lvol
-- module: community.general.parted
+ - module: community.general.filesystem
+ - module: community.general.lvol
+ - module: community.general.parted
notes:
- This module does not modify PE size for already present volume group.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a volume group on top of /dev/sda1 with physical extent size = 32MB
community.general.lvg:
vg: vg.services
@@ -154,7 +159,7 @@ EXAMPLES = r'''
pvs: /dev/sdb1,/dev/sdc5
reset_vg_uuid: true
reset_pv_uuid: true
-'''
+"""
import itertools
import os
@@ -385,6 +390,7 @@ def main():
force=dict(type='bool', default=False),
reset_vg_uuid=dict(type='bool', default=False),
reset_pv_uuid=dict(type='bool', default=False),
+ remove_extra_pvs=dict(type="bool", default=True),
),
required_if=[
['reset_pv_uuid', True, ['pvs']],
@@ -401,6 +407,7 @@ def main():
vgoptions = module.params['vg_options'].split()
reset_vg_uuid = module.boolean(module.params['reset_vg_uuid'])
reset_pv_uuid = module.boolean(module.params['reset_pv_uuid'])
+ remove_extra_pvs = module.boolean(module.params["remove_extra_pvs"])
this_vg = find_vg(module=module, vg=vg)
present_state = state in ['present', 'active', 'inactive']
@@ -496,6 +503,9 @@ def main():
devs_to_remove = list(set(current_devs) - set(dev_list))
devs_to_add = list(set(dev_list) - set(current_devs))
+ if not remove_extra_pvs:
+ devs_to_remove = []
+
if current_devs:
if present_state:
for device in current_devs:
diff --git a/plugins/modules/lvg_rename.py b/plugins/modules/lvg_rename.py
index bd48ffa62f..37f513697e 100644
--- a/plugins/modules/lvg_rename.py
+++ b/plugins/modules/lvg_rename.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
- Laszlo Szomor (@lszomor)
module: lvg_rename
@@ -27,23 +26,23 @@ version_added: 7.1.0
options:
vg:
description:
- - The name or UUID of the source VG.
- - See V(vgrename(8\)) for valid values.
+ - The name or UUID of the source VG.
+ - See V(vgrename(8\)) for valid values.
type: str
required: true
vg_new:
description:
- - The new name of the VG.
- - See V(lvm(8\)) for valid names.
+ - The new name of the VG.
+ - See V(lvm(8\)) for valid names.
type: str
required: true
seealso:
-- module: community.general.lvg
+ - module: community.general.lvg
notes:
- This module does not modify VG renaming-related configurations like C(fstab) entries or boot parameters.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Rename a VG by name
community.general.lvg_rename:
vg: vg_orig_name
@@ -53,7 +52,7 @@ EXAMPLES = r'''
community.general.lvg_rename:
vg_uuid: SNgd0Q-rPYa-dPB8-U1g6-4WZI-qHID-N7y9Vj
vg_new: vg_new_name
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/lvol.py b/plugins/modules/lvol.py
index 3a2f5c7cdd..6166e437f2 100644
--- a/plugins/modules/lvol.py
+++ b/plugins/modules/lvol.py
@@ -8,13 +8,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
author:
- - Jeroen Hoekx (@jhoekx)
- - Alexander Bulimov (@abulimov)
- - Raoul Baudach (@unkaputtbar112)
- - Ziga Kern (@zigaSRC)
+ - Jeroen Hoekx (@jhoekx)
+ - Alexander Bulimov (@abulimov)
+ - Raoul Baudach (@unkaputtbar112)
+ - Ziga Kern (@zigaSRC)
module: lvol
short_description: Configure LVM logical volumes
description:
@@ -31,75 +30,75 @@ options:
type: str
required: true
description:
- - The volume group this logical volume is part of.
+ - The volume group this logical volume is part of.
lv:
type: str
description:
- - The name of the logical volume.
+ - The name of the logical volume.
size:
type: str
description:
- - The size of the logical volume, according to lvcreate(8) --size, by
- default in megabytes or optionally with one of [bBsSkKmMgGtTpPeE] units; or
- according to lvcreate(8) --extents as a percentage of [VG|PVS|FREE|ORIGIN];
- Float values must begin with a digit.
- - When resizing, apart from specifying an absolute size you may, according to
- lvextend(8)|lvreduce(8) C(--size), specify the amount to extend the logical volume with
- the prefix V(+) or the amount to reduce the logical volume by with prefix V(-).
- - Resizing using V(+) or V(-) was not supported prior to community.general 3.0.0.
- - Please note that when using V(+), V(-), or percentage of FREE, the module is B(not idempotent).
+ - The size of the logical volume, according to lvcreate(8) C(--size), by default in megabytes or optionally with one
+ of [bBsSkKmMgGtTpPeE] units; or according to lvcreate(8) C(--extents) as a percentage of [VG|PVS|FREE|ORIGIN]; Float
+ values must begin with a digit.
+ - When resizing, apart from specifying an absolute size you may, according to lvextend(8)|lvreduce(8) C(--size), specify
+ the amount to extend the logical volume with the prefix V(+) or the amount to reduce the logical volume by with prefix
+ V(-).
+ - Resizing using V(+) or V(-) was not supported prior to community.general 3.0.0.
+ - Please note that when using V(+), V(-), or percentage of FREE, the module is B(not idempotent).
state:
type: str
description:
- - Control if the logical volume exists. If V(present) and the
- volume does not already exist then the O(size) option is required.
- choices: [ absent, present ]
+ - Control if the logical volume exists. If V(present) and the volume does not already exist then the O(size) option
+ is required.
+ choices: [absent, present]
default: present
active:
description:
- - Whether the volume is active and visible to the host.
+ - Whether the volume is active and visible to the host.
type: bool
default: true
force:
description:
- - Shrink or remove operations of volumes requires this switch. Ensures that
- that filesystems get never corrupted/destroyed by mistake.
+ - Shrink or remove operations of volumes requires this switch. Ensures that filesystems never get corrupted/destroyed
+ by mistake.
type: bool
default: false
opts:
type: str
description:
- - Free-form options to be passed to the lvcreate command.
+ - Free-form options to be passed to the lvcreate command.
snapshot:
type: str
description:
- - The name of a snapshot volume to be configured. When creating a snapshot volume, the O(lv) parameter specifies the origin volume.
+ - The name of a snapshot volume to be configured. When creating a snapshot volume, the O(lv) parameter specifies the
+ origin volume.
pvs:
type: list
elements: str
description:
- - List of physical volumes (for example V(/dev/sda, /dev/sdb)).
+ - List of physical volumes (for example V(/dev/sda, /dev/sdb)).
thinpool:
type: str
description:
- - The thin pool volume name. When you want to create a thin provisioned volume, specify a thin pool volume name.
+ - The thin pool volume name. When you want to create a thin provisioned volume, specify a thin pool volume name.
shrink:
description:
- - Shrink if current size is higher than size requested.
+ - Shrink if current size is higher than size requested.
type: bool
default: true
resizefs:
description:
- - Resize the underlying filesystem together with the logical volume.
- - Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems.
- Attempts to resize other filesystem types will fail.
+ - Resize the underlying filesystem together with the logical volume.
+ - Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems. Attempts to resize other filesystem types
+ result in failure.
type: bool
default: false
notes:
- You must specify lv (when managing the state of logical volumes) or thinpool (when managing a thin provisioned volume).
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a logical volume of 512m
community.general.lvol:
vg: firefly
@@ -233,7 +232,7 @@ EXAMPLES = '''
lv: test
thinpool: testpool
size: 128g
-'''
+"""
import re
import shlex
diff --git a/plugins/modules/lxc_container.py b/plugins/modules/lxc_container.py
index 2d768eaafd..8d5face301 100644
--- a/plugins/modules/lxc_container.py
+++ b/plugins/modules/lxc_container.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: lxc_container
short_description: Manage LXC Containers
description:
@@ -19,183 +18,172 @@ author: "Kevin Carter (@cloudnull)"
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of a container.
- type: str
- required: true
- backing_store:
- choices:
- - dir
- - lvm
- - loop
- - btrfs
- - overlayfs
- - zfs
- description:
- - Backend storage type for the container.
- type: str
- default: dir
- template:
- description:
- - Name of the template to use within an LXC create.
- type: str
- default: ubuntu
- template_options:
- description:
- - Template options when building the container.
- type: str
- config:
- description:
- - Path to the LXC configuration file.
- type: path
- lv_name:
- description:
- - Name of the logical volume, defaults to the container name.
- - If not specified, it defaults to C($CONTAINER_NAME).
- type: str
- vg_name:
- description:
- - If backend store is lvm, specify the name of the volume group.
- type: str
- default: lxc
- thinpool:
- description:
- - Use LVM thin pool called TP.
- type: str
- fs_type:
- description:
- - Create fstype TYPE.
- type: str
- default: ext4
- fs_size:
- description:
- - File system Size.
- type: str
- default: 5G
- directory:
- description:
- - Place rootfs directory under DIR.
- type: path
- zfs_root:
- description:
- - Create zfs under given zfsroot.
- type: str
- container_command:
- description:
- - Run a command within a container.
- type: str
- lxc_path:
- description:
- - Place container under E(PATH).
- type: path
- container_log:
- description:
- - Enable a container log for host actions to the container.
- type: bool
- default: false
- container_log_level:
- choices:
- - Info
- - info
- - INFO
- - Error
- - error
- - ERROR
- - Debug
- - debug
- - DEBUG
- description:
- - Set the log level for a container where O(container_log) was set.
- type: str
- required: false
- default: INFO
- clone_name:
- description:
- - Name of the new cloned server.
- - This is only used when state is clone.
- type: str
- clone_snapshot:
- description:
- - Create a snapshot a container when cloning.
- - This is not supported by all container storage backends.
- - Enabling this may fail if the backing store does not support snapshots.
- type: bool
- default: false
- archive:
- description:
- - Create an archive of a container.
- - This will create a tarball of the running container.
- type: bool
- default: false
- archive_path:
- description:
- - Path the save the archived container.
- - If the path does not exist the archive method will attempt to create it.
- type: path
- archive_compression:
- choices:
- - gzip
- - bzip2
- - none
- description:
- - Type of compression to use when creating an archive of a running
- container.
- type: str
- default: gzip
- state:
- choices:
- - started
- - stopped
- - restarted
- - absent
- - frozen
- - clone
- description:
- - Define the state of a container.
- - If you clone a container using O(clone_name) the newly cloned
- container created in a stopped state.
- - The running container will be stopped while the clone operation is
- happening and upon completion of the clone the original container
- state will be restored.
- type: str
- default: started
- container_config:
- description:
- - A list of C(key=value) options to use when configuring a container.
- type: list
- elements: str
+ name:
+ description:
+ - Name of a container.
+ type: str
+ required: true
+ backing_store:
+ choices:
+ - dir
+ - lvm
+ - loop
+ - btrfs
+ - overlayfs
+ - zfs
+ description:
+ - Backend storage type for the container.
+ type: str
+ default: dir
+ template:
+ description:
+ - Name of the template to use within an LXC create.
+ type: str
+ default: ubuntu
+ template_options:
+ description:
+ - Template options when building the container.
+ type: str
+ config:
+ description:
+ - Path to the LXC configuration file.
+ type: path
+ lv_name:
+ description:
+ - Name of the logical volume, defaults to the container name.
+ - If not specified, it defaults to E(CONTAINER_NAME).
+ type: str
+ vg_name:
+ description:
+ - If backend store is lvm, specify the name of the volume group.
+ type: str
+ default: lxc
+ thinpool:
+ description:
+ - Use LVM thin pool called TP.
+ type: str
+ fs_type:
+ description:
+ - Create fstype TYPE.
+ type: str
+ default: ext4
+ fs_size:
+ description:
+ - File system Size.
+ type: str
+ default: 5G
+ directory:
+ description:
+ - Place rootfs directory under DIR.
+ type: path
+ zfs_root:
+ description:
+ - Create zfs under given zfsroot.
+ type: str
+ container_command:
+ description:
+ - Run a command within a container.
+ type: str
+ lxc_path:
+ description:
+ - Place container under E(PATH).
+ type: path
+ container_log:
+ description:
+ - Enable a container log for host actions to the container.
+ type: bool
+ default: false
+ container_log_level:
+ choices:
+ - Info
+ - info
+ - INFO
+ - Error
+ - error
+ - ERROR
+ - Debug
+ - debug
+ - DEBUG
+ description:
+ - Set the log level for a container where O(container_log) was set.
+ type: str
+ required: false
+ default: INFO
+ clone_name:
+ description:
+ - Name of the new cloned server.
+ - This is only used when state is clone.
+ type: str
+ clone_snapshot:
+ description:
+ - Create a snapshot a container when cloning.
+ - This is not supported by all container storage backends.
+ - Enabling this may fail if the backing store does not support snapshots.
+ type: bool
+ default: false
+ archive:
+ description:
+ - Create an archive of a container.
+ - This will create a tarball of the running container.
+ type: bool
+ default: false
+ archive_path:
+ description:
+ - Path the save the archived container.
+ - If the path does not exist the archive method will attempt to create it.
+ type: path
+ archive_compression:
+ choices:
+ - gzip
+ - bzip2
+ - none
+ description:
+ - Type of compression to use when creating an archive of a running container.
+ type: str
+ default: gzip
+ state:
+ choices:
+ - started
+ - stopped
+ - restarted
+ - absent
+ - frozen
+ - clone
+ description:
+ - Define the state of a container.
+ - If you clone a container using O(clone_name) the newly cloned container created in a stopped state.
+ - The running container will be stopped while the clone operation is happening and upon completion of the clone the
+ original container state will be restored.
+ type: str
+ default: started
+ container_config:
+ description:
+ - A list of C(key=value) options to use when configuring a container.
+ type: list
+ elements: str
requirements:
- 'lxc >= 2.0 # OS package'
- 'python3 >= 3.5 # OS Package'
- 'python3-lxc # OS Package'
notes:
- - Containers must have a unique name. If you attempt to create a container
- with a name that already exists in the users namespace the module will
- simply return as "unchanged".
- - The O(container_command) can be used with any state except V(absent). If
- used with state V(stopped) the container will be V(started), the command
- executed, and then the container V(stopped) again. Likewise if O(state=stopped)
- and the container does not exist it will be first created,
- V(started), the command executed, and then V(stopped). If you use a "|"
- in the variable you can use common script formatting within the variable
- itself. The O(container_command) option will always execute as BASH.
- When using O(container_command), a log file is created in the C(/tmp/) directory
- which contains both C(stdout) and C(stderr) of any command executed.
- - If O(archive=true) the system will attempt to create a compressed
- tarball of the running container. The O(archive) option supports LVM backed
- containers and will create a snapshot of the running container when
- creating the archive.
- - If your distro does not have a package for C(python3-lxc), which is a
- requirement for this module, it can be installed from source at
- U(https://github.com/lxc/python3-lxc) or installed via pip using the
- package name C(lxc).
-'''
+ - Containers must have a unique name. If you attempt to create a container with a name that already exists in the users
+ namespace the module will simply return as "unchanged".
+ - The O(container_command) can be used with any state except V(absent). If used with state V(stopped) the container will
+ be V(started), the command executed, and then the container V(stopped) again. Likewise if O(state=stopped) and the container
+ does not exist it will be first created, V(started), the command executed, and then V(stopped). If you use a C(|) in the
+ variable you can use common script formatting within the variable itself. The O(container_command) option will always
+ execute as C(bash). When using O(container_command), a log file is created in the C(/tmp/) directory which contains both
+ C(stdout) and C(stderr) of any command executed.
+ - If O(archive=true) the system will attempt to create a compressed tarball of the running container. The O(archive) option
+ supports LVM backed containers and will create a snapshot of the running container when creating the archive.
+ - If your distro does not have a package for C(python3-lxc), which is a requirement for this module, it can be installed
+ from source at U(https://github.com/lxc/python3-lxc) or installed using C(pip install lxc).
+"""
EXAMPLES = r"""
- name: Create a started container
@@ -268,14 +256,14 @@ EXAMPLES = r"""
ansible.builtin.debug:
var: lvm_container_info
-- name: Run a command in a container and ensure its in a "stopped" state.
+- name: Run a command in a container and ensure it is in a "stopped" state.
community.general.lxc_container:
name: test-container-started
state: stopped
container_command: |
echo 'hello world.' | tee /opt/stopped
-- name: Run a command in a container and ensure its it in a "frozen" state.
+- name: Run a command in a container and ensure it is in a "frozen" state.
community.general.lxc_container:
name: test-container-stopped
state: frozen
@@ -382,45 +370,45 @@ EXAMPLES = r"""
RETURN = r"""
lxc_container:
- description: container information
- returned: success
- type: complex
- contains:
- name:
- description: name of the lxc container
- returned: success
- type: str
- sample: test_host
- init_pid:
- description: pid of the lxc init process
- returned: success
- type: int
- sample: 19786
- interfaces:
- description: list of the container's network interfaces
- returned: success
- type: list
- sample: [ "eth0", "lo" ]
- ips:
- description: list of ips
- returned: success
- type: list
- sample: [ "10.0.3.3" ]
- state:
- description: resulting state of the container
- returned: success
- type: str
- sample: "running"
- archive:
- description: resulting state of the container
- returned: success, when archive is true
- type: str
- sample: "/tmp/test-container-config.tar"
- clone:
- description: if the container was cloned
- returned: success, when clone_name is specified
- type: bool
- sample: true
+ description: Container information.
+ returned: success
+ type: complex
+ contains:
+ name:
+ description: Name of the LXC container.
+ returned: success
+ type: str
+ sample: test_host
+ init_pid:
+ description: Pid of the LXC init process.
+ returned: success
+ type: int
+ sample: 19786
+ interfaces:
+ description: List of the container's network interfaces.
+ returned: success
+ type: list
+ sample: ["eth0", "lo"]
+ ips:
+ description: List of IPs.
+ returned: success
+ type: list
+ sample: ["10.0.3.3"]
+ state:
+ description: Resulting state of the container.
+ returned: success
+ type: str
+ sample: "running"
+ archive:
+ description: Resulting state of the container.
+ returned: success, when archive is true
+ type: str
+ sample: "/tmp/test-container-config.tar"
+ clone:
+ description: If the container was cloned.
+ returned: success, when clone_name is specified
+ type: bool
+ sample: true
"""
import os
@@ -694,7 +682,7 @@ class LxcContainerManagement(object):
"""Configure an LXC container.
Write new configuration values to the lxc config file. This will
- stop the container if it's running write the new options and then
+ stop the container if it is running write the new options and then
restart the container upon completion.
"""
diff --git a/plugins/modules/lxca_cmms.py b/plugins/modules/lxca_cmms.py
index 1f811a7efa..8ece67470b 100644
--- a/plugins/modules/lxca_cmms.py
+++ b/plugins/modules/lxca_cmms.py
@@ -8,16 +8,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
author:
- Naval Patel (@navalkp)
- Prashant Bhosale (@prabhosa)
module: lxca_cmms
short_description: Custom module for lxca cmms inventory utility
description:
- - This module returns/displays a inventory details of cmms
-
+ - This module returns/displays a inventory details of cmms.
attributes:
check_mode:
support: none
@@ -26,32 +24,28 @@ attributes:
options:
uuid:
- description:
- uuid of device, this is string with length greater than 16.
+ description: UUID of device, this is string with length greater than 16.
type: str
command_options:
- description:
- options to filter nodes information
+ description: Options to filter nodes information.
default: cmms
choices:
- - cmms
- - cmms_by_uuid
- - cmms_by_chassis_uuid
+ - cmms
+ - cmms_by_uuid
+ - cmms_by_chassis_uuid
type: str
chassis:
- description:
- uuid of chassis, this is string with length greater than 16.
+ description: UUID of chassis, this is string with length greater than 16.
type: str
extends_documentation_fragment:
- community.general.lxca_common
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# get all cmms info
- name: Get nodes data from LXCA
community.general.lxca_cmms:
@@ -76,28 +70,27 @@ EXAMPLES = '''
auth_url: "https://10.243.15.168"
chassis: "3C737AA5E31640CE949B10C129A8B01F"
command_options: cmms_by_chassis_uuid
+"""
-'''
-
-RETURN = r'''
+RETURN = r"""
result:
- description: cmms detail from lxca
- returned: success
- type: dict
- sample:
- cmmList:
- - machineType: ''
- model: ''
- type: 'CMM'
- uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF'
+ description: Cmms detail from lxca.
+ returned: success
+ type: dict
+ sample:
+ cmmList:
+ - machineType: ''
+ model: ''
+ type: 'CMM'
+ uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties
- - machineType: ''
- model: ''
- type: 'CMM'
- uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF'
+ - machineType: ''
+ model: ''
+ type: 'CMM'
+ uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties
# Multiple cmms details
-'''
+"""
import traceback
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/lxca_nodes.py b/plugins/modules/lxca_nodes.py
index 3b37322edb..f133671114 100644
--- a/plugins/modules/lxca_nodes.py
+++ b/plugins/modules/lxca_nodes.py
@@ -8,16 +8,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
author:
- Naval Patel (@navalkp)
- Prashant Bhosale (@prabhosa)
module: lxca_nodes
short_description: Custom module for lxca nodes inventory utility
description:
- - This module returns/displays a inventory details of nodes
-
+ - This module returns/displays a inventory details of nodes.
attributes:
check_mode:
support: none
@@ -26,34 +24,30 @@ attributes:
options:
uuid:
- description:
- uuid of device, this is string with length greater than 16.
+ description: UUID of device, this is string with length greater than 16.
type: str
command_options:
- description:
- options to filter nodes information
+ description: Options to filter nodes information.
default: nodes
choices:
- - nodes
- - nodes_by_uuid
- - nodes_by_chassis_uuid
- - nodes_status_managed
- - nodes_status_unmanaged
+ - nodes
+ - nodes_by_uuid
+ - nodes_by_chassis_uuid
+ - nodes_status_managed
+ - nodes_status_unmanaged
type: str
chassis:
- description:
- uuid of chassis, this is string with length greater than 16.
+ description: UUID of chassis, this is string with length greater than 16.
type: str
extends_documentation_fragment:
- community.general.lxca_common
- community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# get all nodes info
- name: Get nodes data from LXCA
community.general.lxca_nodes:
@@ -95,28 +89,27 @@ EXAMPLES = '''
login_password: Password
auth_url: "https://10.243.15.168"
command_options: nodes_status_unmanaged
+"""
-'''
-
-RETURN = r'''
+RETURN = r"""
result:
- description: nodes detail from lxca
- returned: always
- type: dict
- sample:
- nodeList:
- - machineType: '6241'
- model: 'AC1'
- type: 'Rack-TowerServer'
- uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF'
+ description: Nodes detail from lxca.
+ returned: always
+ type: dict
+ sample:
+ nodeList:
+ - machineType: '6241'
+ model: 'AC1'
+ type: 'Rack-TowerServer'
+ uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties
- - machineType: '8871'
- model: 'AC1'
- type: 'Rack-TowerServer'
- uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF'
+ - machineType: '8871'
+ model: 'AC1'
+ type: 'Rack-TowerServer'
+ uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties
# Multiple nodes details
-'''
+"""
import traceback
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/lxd_container.py b/plugins/modules/lxd_container.py
index 5c5d8a4d8d..4fc0e4293d 100644
--- a/plugins/modules/lxd_container.py
+++ b/plugins/modules/lxd_container.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: lxd_container
short_description: Manage LXD instances
description:
@@ -19,198 +18,182 @@ author: "Hiroaki Nakamura (@hnakamur)"
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- version_added: 6.4.0
- diff_mode:
- support: full
- version_added: 6.4.0
+ check_mode:
+ support: full
+ version_added: 6.4.0
+ diff_mode:
+ support: full
+ version_added: 6.4.0
options:
- name:
- description:
- - Name of an instance.
- type: str
- required: true
- project:
- description:
- - 'Project of an instance.
- See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).'
- required: false
- type: str
- version_added: 4.8.0
- architecture:
- description:
- - 'The architecture for the instance (for example V(x86_64) or V(i686)).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- type: str
- required: false
- config:
- description:
- - 'The config for the instance (for example V({"limits.cpu": "2"})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- - If the instance already exists and its "config" values in metadata
- obtained from the LXD API U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get)
- are different, then this module tries to apply the configurations
- U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put).
- - The keys starting with C(volatile.) are ignored for this comparison when O(ignore_volatile_options=true).
- type: dict
- required: false
- ignore_volatile_options:
- description:
- - If set to V(true), options starting with C(volatile.) are ignored. As a result,
- they are reapplied for each execution.
- - This default behavior can be changed by setting this option to V(false).
- - The default value changed from V(true) to V(false) in community.general 6.0.0.
- type: bool
- required: false
- default: false
- version_added: 3.7.0
- profiles:
- description:
- - Profile to be used by the instance.
- type: list
- elements: str
- devices:
- description:
- - 'The devices for the instance
- (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- type: dict
- required: false
- ephemeral:
- description:
- - Whether or not the instance is ephemeral (for example V(true) or V(false)).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
- required: false
- type: bool
- source:
- description:
- - 'The source for the instance
- (for example V({ "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/",
- "protocol": "simplestreams", "alias": "22.04" })).'
- - 'See U(https://documentation.ubuntu.com/lxd/en/latest/api/) for complete API documentation.'
- - 'Note that C(protocol) accepts two choices: V(lxd) or V(simplestreams).'
- required: false
- type: dict
- state:
- choices:
- - started
- - stopped
- - restarted
- - absent
- - frozen
- description:
- - Define the state of an instance.
- required: false
- default: started
- type: str
- target:
- description:
- - For cluster deployments. Will attempt to create an instance on a target node.
- If the instance exists elsewhere in a cluster, then it will not be replaced or moved.
- The name should respond to same name of the node you see in C(lxc cluster list).
- type: str
- required: false
- version_added: 1.0.0
- timeout:
- description:
- - A timeout for changing the state of the instance.
- - This is also used as a timeout for waiting until IPv4 addresses
- are set to the all network interfaces in the instance after
- starting or restarting.
- required: false
- default: 30
- type: int
- type:
- description:
- - Instance type can be either V(virtual-machine) or V(container).
- required: false
- default: container
- choices:
- - container
- - virtual-machine
- type: str
- version_added: 4.1.0
- wait_for_ipv4_addresses:
- description:
- - If this is V(true), the C(lxd_container) waits until IPv4 addresses
- are set to the all network interfaces in the instance after
- starting or restarting.
- required: false
- default: false
- type: bool
- wait_for_container:
- description:
- - If set to V(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 V(true), the C(lxd_container) forces to stop the instance
- when it stops or restarts the instance.
- required: false
- default: false
- type: bool
- url:
- description:
- - The unix domain socket path or the https URL for the LXD server.
- required: false
- default: unix:/var/lib/lxd/unix.socket
- type: str
- snap_url:
- description:
- - The unix domain socket path when LXD is installed by snap package manager.
- required: false
- default: unix:/var/snap/lxd/common/lxd/unix.socket
- type: str
- client_key:
- description:
- - The client certificate key file path.
- - If not specified, it defaults to C(${HOME}/.config/lxc/client.key).
- required: false
- aliases: [ key_file ]
- type: path
- client_cert:
- description:
- - The client certificate file path.
- - If not specified, it defaults to C(${HOME}/.config/lxc/client.crt).
- required: false
- aliases: [ cert_file ]
- type: path
- trust_password:
- description:
- - The client trusted password.
- - 'You need to set this password on the LXD server before
- running this module using the following command:
- C(lxc config set core.trust_password ).
- See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- - If trust_password is set, this module send a request for
- authentication before sending any requests.
- required: false
- type: str
+ name:
+ description:
+ - Name of an instance.
+ type: str
+ required: true
+ project:
+ description:
+ - Project of an instance.
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).
+ required: false
+ type: str
+ version_added: 4.8.0
+ architecture:
+ description:
+ - The architecture for the instance (for example V(x86_64) or V(i686)).
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
+ type: str
+ required: false
+ config:
+ description:
+ - 'The config for the instance (for example V({"limits.cpu": "2"})).'
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
+ - If the instance already exists and its "config" values in metadata obtained from the LXD API
+ U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get)
+ are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put).
+ - The keys starting with C(volatile.) are ignored for this comparison when O(ignore_volatile_options=true).
+ type: dict
+ required: false
+ ignore_volatile_options:
+ description:
+ - If set to V(true), options starting with C(volatile.) are ignored. As a result, they are reapplied for each execution.
+ - This default behavior can be changed by setting this option to V(false).
+ - The default value changed from V(true) to V(false) in community.general 6.0.0.
+ type: bool
+ required: false
+ default: false
+ version_added: 3.7.0
+ profiles:
+ description:
+ - Profile to be used by the instance.
+ type: list
+ elements: str
+ devices:
+ description:
+ - 'The devices for the instance (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})).'
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
+ type: dict
+ required: false
+ ephemeral:
+ description:
+ - Whether or not the instance is ephemeral (for example V(true) or V(false)).
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
+ required: false
+ type: bool
+ source:
+ description:
+ - 'The source for the instance (for example V({ "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/",
+ "protocol": "simplestreams", "alias": "22.04" })).'
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/) for complete API documentation.
+ - 'Note that C(protocol) accepts two choices: V(lxd) or V(simplestreams).'
+ required: false
+ type: dict
+ state:
+ choices:
+ - started
+ - stopped
+ - restarted
+ - absent
+ - frozen
+ description:
+ - Define the state of an instance.
+ required: false
+ default: started
+ type: str
+ target:
+ description:
+ - For cluster deployments. Will attempt to create an instance on a target node. If the instance exists elsewhere in
+ a cluster, then it will not be replaced or moved. The name should respond to same name of the node you see in C(lxc
+ cluster list).
+ type: str
+ required: false
+ version_added: 1.0.0
+ timeout:
+ description:
+ - A timeout for changing the state of the instance.
+ - This is also used as a timeout for waiting until IPv4 addresses are set to the all network interfaces in the instance
+ after starting or restarting.
+ required: false
+ default: 30
+ type: int
+ type:
+ description:
+ - Instance type can be either V(virtual-machine) or V(container).
+ required: false
+ default: container
+ choices:
+ - container
+ - virtual-machine
+ type: str
+ version_added: 4.1.0
+ wait_for_ipv4_addresses:
+ description:
+ - If this is V(true), the C(lxd_container) waits until IPv4 addresses are set to the all network interfaces in the instance
+ after starting or restarting.
+ required: false
+ default: false
+ type: bool
+ wait_for_container:
+ description:
+ - If set to V(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 V(true), the C(lxd_container) forces to stop the instance when it stops or restarts the instance.
+ required: false
+ default: false
+ type: bool
+ url:
+ description:
+ - The unix domain socket path or the https URL for the LXD server.
+ required: false
+ default: unix:/var/lib/lxd/unix.socket
+ type: str
+ snap_url:
+ description:
+ - The unix domain socket path when LXD is installed by snap package manager.
+ required: false
+ default: unix:/var/snap/lxd/common/lxd/unix.socket
+ type: str
+ client_key:
+ description:
+ - The client certificate key file path.
+ - If not specified, it defaults to C(${HOME}/.config/lxc/client.key).
+ required: false
+ aliases: [key_file]
+ type: path
+ client_cert:
+ description:
+ - The client certificate file path.
+ - If not specified, it defaults to C(${HOME}/.config/lxc/client.crt).
+ required: false
+ aliases: [cert_file]
+ type: path
+ trust_password:
+ description:
+ - The client trusted password.
+ - 'You need to set this password on the LXD server before running this module using the following command: C(lxc config
+ set core.trust_password ). See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
+ - If trust_password is set, this module send a request for authentication before sending any requests.
+ required: false
+ type: str
notes:
- Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance
- with a name that already existed in the users namespace the module will
- simply return as "unchanged".
- - There are two ways to run commands inside a container or virtual machine, using the command
- module or using the ansible lxd connection plugin bundled in Ansible >=
- 2.1, the later requires python to be installed in the instance which can
- be done with the command module.
- - You can copy a file from the host to the instance
- with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module
- and the P(community.general.lxd#connection) connection plugin.
- See the example below.
- - You can copy a file in the created instance to the localhost
- with C(command=lxc file pull instance_name/dir/filename filename).
+ with a name that already existed in the users namespace the module will simply return as "unchanged".
+ - There are two ways to run commands inside a container or virtual machine, using the command module or using the ansible
+ lxd connection plugin bundled in Ansible >= 2.1, the later requires python to be installed in the instance which can be
+ done with the command module.
+ - You can copy a file from the host to the instance with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template)
+ module and the P(community.general.lxd#connection) connection plugin. See the example below.
+ - You can copy a file in the created instance to the localhost with C(command=lxc file pull instance_name/dir/filename filename).
See the first example below.
- - linuxcontainers.org has phased out LXC/LXD support with March 2024
+ - Linuxcontainers.org has phased out LXC/LXD support with March 2024
(U(https://discuss.linuxcontainers.org/t/important-notice-for-lxd-users-image-server/18479)).
Currently only Ubuntu is still providing images.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# An example for creating a Ubuntu container and install python
- hosts: localhost
connection: local
@@ -279,7 +262,7 @@ EXAMPLES = '''
source:
type: image
mode: pull
- # Provides Ubuntu minimal images
+ # Provides Ubuntu minimal images
server: https://cloud-images.ubuntu.com/minimal/releases/
protocol: simplestreams
alias: "22.04"
@@ -335,8 +318,8 @@ EXAMPLES = '''
community.general.lxd_container:
url: https://127.0.0.1:8443
# These client_cert and client_key values are equal to the default values.
- #client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
- #client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
+ # client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
+ # client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
trust_password: mypassword
name: mycontainer
state: restarted
@@ -400,12 +383,12 @@ EXAMPLES = '''
protocol: simplestreams
type: image
mode: pull
- server: [...] # URL to the image server
+ server: ['...'] # URL to the image server
alias: debian/11
timeout: 600
-'''
+"""
-RETURN = '''
+RETURN = r"""
addresses:
description: Mapping from the network device name to a list of IPv4 addresses in the instance.
returned: when state is started or restarted
@@ -426,7 +409,8 @@ actions:
returned: success
type: list
sample: ["create", "start"]
-'''
+"""
+
import copy
import datetime
import os
diff --git a/plugins/modules/lxd_profile.py b/plugins/modules/lxd_profile.py
index 13660fd91d..efdf50ea90 100644
--- a/plugins/modules/lxd_profile.py
+++ b/plugins/modules/lxd_profile.py
@@ -9,126 +9,114 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: lxd_profile
short_description: Manage LXD profiles
description:
- - Management of LXD profiles
+ - Management of LXD profiles.
author: "Hiroaki Nakamura (@hnakamur)"
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of a profile.
- required: true
- type: str
- project:
- description:
- - 'Project of a profile.
- See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).'
- type: str
- required: false
- version_added: 4.8.0
+ name:
description:
- description:
- - Description of the profile.
- type: str
- config:
- description:
- - 'The config for the instance (e.g. {"limits.memory": "4GB"}).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
- - If the profile already exists and its "config" value in metadata
- obtained from
- GET /1.0/profiles/
- U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get)
- are different, then this module tries to apply the configurations
- U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_put).
- - Not all config values are supported to apply the existing profile.
- Maybe you need to delete and recreate a profile.
- required: false
- type: dict
- devices:
- description:
- - 'The devices for the profile
- (e.g. {"rootfs": {"path": "/dev/kvm", "type": "unix-char"}).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
- required: false
- type: dict
- new_name:
- description:
- - A new name of a profile.
- - If this parameter is specified a profile will be renamed to this name.
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_post).
- required: false
- type: str
- merge_profile:
- description:
- - Merge the configuration of the present profile with the new desired configuration,
- instead of replacing it.
- required: false
- default: false
- type: bool
- version_added: 2.1.0
- state:
- choices:
- - present
- - absent
- description:
- - Define the state of a profile.
- required: false
- default: present
- type: str
- url:
- description:
- - The unix domain socket path or the https URL for the LXD server.
- required: false
- default: unix:/var/lib/lxd/unix.socket
- type: str
- snap_url:
- description:
- - The unix domain socket path when LXD is installed by snap package manager.
- required: false
- default: unix:/var/snap/lxd/common/lxd/unix.socket
- type: str
- client_key:
- description:
- - The client certificate key file path.
- - If not specified, it defaults to C($HOME/.config/lxc/client.key).
- required: false
- aliases: [ key_file ]
- type: path
- client_cert:
- description:
- - The client certificate file path.
- - If not specified, it defaults to C($HOME/.config/lxc/client.crt).
- required: false
- aliases: [ cert_file ]
- type: path
- trust_password:
- description:
- - The client trusted password.
- - You need to set this password on the LXD server before
- running this module using the following command.
- lxc config set core.trust_password
- See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/)
- - If trust_password is set, this module send a request for
- authentication before sending any requests.
- required: false
- type: str
+ - Name of a profile.
+ required: true
+ type: str
+ project:
+ description:
+ - Project of a profile. See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).
+ type: str
+ required: false
+ version_added: 4.8.0
+ description:
+ description:
+ - Description of the profile.
+ type: str
+ config:
+ description:
+ - 'The config for the instance (for example V({"limits.memory": "4GB"})).'
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).
+ - If the profile already exists and its C(config) value in metadata obtained from GET /1.0/profiles/
+ U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get)
+ are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_put).
+ - Not all config values are supported to apply the existing profile. Maybe you need to delete and recreate a profile.
+ required: false
+ type: dict
+ devices:
+ description:
+ - 'The devices for the profile (for example V({"rootfs": {"path": "/dev/kvm", "type": "unix-char"})).'
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).
+ required: false
+ type: dict
+ new_name:
+ description:
+ - A new name of a profile.
+ - If this parameter is specified a profile will be renamed to this name.
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_post).
+ required: false
+ type: str
+ merge_profile:
+ description:
+ - Merge the configuration of the present profile with the new desired configuration, instead of replacing it.
+ required: false
+ default: false
+ type: bool
+ version_added: 2.1.0
+ state:
+ choices:
+ - present
+ - absent
+ description:
+ - Define the state of a profile.
+ required: false
+ default: present
+ type: str
+ url:
+ description:
+ - The unix domain socket path or the https URL for the LXD server.
+ required: false
+ default: unix:/var/lib/lxd/unix.socket
+ type: str
+ snap_url:
+ description:
+ - The unix domain socket path when LXD is installed by snap package manager.
+ required: false
+ default: unix:/var/snap/lxd/common/lxd/unix.socket
+ type: str
+ client_key:
+ description:
+ - The client certificate key file path.
+ - If not specified, it defaults to C($HOME/.config/lxc/client.key).
+ required: false
+ aliases: [key_file]
+ type: path
+ client_cert:
+ description:
+ - The client certificate file path.
+ - If not specified, it defaults to C($HOME/.config/lxc/client.crt).
+ required: false
+ aliases: [cert_file]
+ type: path
+ trust_password:
+ description:
+ - The client trusted password.
+ - 'You need to set this password on the LXD server before running this module using the following command: C(lxc config
+ set core.trust_password ). See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
+ - If O(trust_password) is set, this module send a request for authentication before sending any requests.
+ required: false
+ type: str
notes:
- - Profiles must have a unique name. If you attempt to create a profile
- with a name that already existed in the users namespace the module will
- simply return as "unchanged".
-'''
+ - Profiles must have a unique name. If you attempt to create a profile with a name that already existed in the users namespace
+ the module will simply return as "unchanged".
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# An example for creating a profile
- hosts: localhost
connection: local
@@ -162,22 +150,22 @@ EXAMPLES = '''
- hosts: localhost
connection: local
tasks:
- - name: Create macvlan profile
- community.general.lxd_profile:
- url: https://127.0.0.1:8443
- # These client_cert and client_key values are equal to the default values.
- #client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
- #client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
- trust_password: mypassword
- name: macvlan
- state: present
- config: {}
- description: my macvlan profile
- devices:
- eth0:
- nictype: macvlan
- parent: br0
- type: nic
+ - name: Create macvlan profile
+ community.general.lxd_profile:
+ url: https://127.0.0.1:8443
+ # These client_cert and client_key values are equal to the default values.
+ # client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
+ # client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
+ trust_password: mypassword
+ name: macvlan
+ state: present
+ config: {}
+ description: my macvlan profile
+ devices:
+ eth0:
+ nictype: macvlan
+ parent: br0
+ type: nic
# An example for modify/merge a profile
- hosts: localhost
@@ -214,11 +202,11 @@ EXAMPLES = '''
name: macvlan
new_name: macvlan2
state: present
-'''
+"""
-RETURN = '''
+RETURN = r"""
old_state:
- description: The old state of the profile
+ description: The old state of the profile.
returned: success
type: str
sample: "absent"
@@ -232,7 +220,7 @@ actions:
returned: success
type: list
sample: ["create"]
-'''
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/lxd_project.py b/plugins/modules/lxd_project.py
index 0d321808a2..98068175aa 100644
--- a/plugins/modules/lxd_project.py
+++ b/plugins/modules/lxd_project.py
@@ -7,8 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: lxd_project
short_description: Manage LXD projects
version_added: 4.8.0
@@ -18,98 +17,91 @@ author: "Raymond Chang (@we10710aa)"
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of the project.
- required: true
- type: str
+ name:
description:
- description:
- - Description of the project.
- type: str
- config:
- description:
- - 'The config for the project (for example V({"features.profiles": "true"})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).'
- - If the project already exists and its "config" value in metadata
- obtained from
- C(GET /1.0/projects/)
- U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get)
- are different, then this module tries to apply the configurations
- U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_put).
- type: dict
- new_name:
- description:
- - A new name of a project.
- - If this parameter is specified a project will be renamed to this name.
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_post).
- required: false
- type: str
- merge_project:
- description:
- - Merge the configuration of the present project with the new desired configuration,
- instead of replacing it. If configuration is the same after merged, no change will be made.
- required: false
- default: false
- type: bool
- state:
- choices:
- - present
- - absent
- description:
- - Define the state of a project.
- required: false
- default: present
- type: str
- url:
- description:
- - The Unix domain socket path or the https URL for the LXD server.
- required: false
- default: unix:/var/lib/lxd/unix.socket
- type: str
- snap_url:
- description:
- - The Unix domain socket path when LXD is installed by snap package manager.
- required: false
- default: unix:/var/snap/lxd/common/lxd/unix.socket
- type: str
- client_key:
- description:
- - The client certificate key file path.
- - If not specified, it defaults to C($HOME/.config/lxc/client.key).
- required: false
- aliases: [ key_file ]
- type: path
- client_cert:
- description:
- - The client certificate file path.
- - If not specified, it defaults to C($HOME/.config/lxc/client.crt).
- required: false
- aliases: [ cert_file ]
- type: path
- trust_password:
- description:
- - The client trusted password.
- - 'You need to set this password on the LXD server before
- running this module using the following command:
- C(lxc config set core.trust_password )
- See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- - If O(trust_password) is set, this module send a request for
- authentication before sending any requests.
- required: false
- type: str
+ - Name of the project.
+ required: true
+ type: str
+ description:
+ description:
+ - Description of the project.
+ type: str
+ config:
+ description:
+ - 'The config for the project (for example V({"features.profiles": "true"})).'
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).
+ - If the project already exists and its "config" value in metadata obtained from C(GET /1.0/projects/)
+ U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get)
+ are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_put).
+ type: dict
+ new_name:
+ description:
+ - A new name of a project.
+ - If this parameter is specified a project will be renamed to this name.
+ - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_post).
+ required: false
+ type: str
+ merge_project:
+ description:
+ - Merge the configuration of the present project with the new desired configuration, instead of replacing it. If configuration
+ is the same after merged, no change will be made.
+ required: false
+ default: false
+ type: bool
+ state:
+ choices:
+ - present
+ - absent
+ description:
+ - Define the state of a project.
+ required: false
+ default: present
+ type: str
+ url:
+ description:
+ - The Unix domain socket path or the https URL for the LXD server.
+ required: false
+ default: unix:/var/lib/lxd/unix.socket
+ type: str
+ snap_url:
+ description:
+ - The Unix domain socket path when LXD is installed by snap package manager.
+ required: false
+ default: unix:/var/snap/lxd/common/lxd/unix.socket
+ type: str
+ client_key:
+ description:
+ - The client certificate key file path.
+ - If not specified, it defaults to C($HOME/.config/lxc/client.key).
+ required: false
+ aliases: [key_file]
+ type: path
+ client_cert:
+ description:
+ - The client certificate file path.
+ - If not specified, it defaults to C($HOME/.config/lxc/client.crt).
+ required: false
+ aliases: [cert_file]
+ type: path
+ trust_password:
+ description:
+ - The client trusted password.
+ - 'You need to set this password on the LXD server before running this module using the following command: C(lxc config
+ set core.trust_password ) See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
+ - If O(trust_password) is set, this module send a request for authentication before sending any requests.
+ required: false
+ type: str
notes:
- - Projects must have a unique name. If you attempt to create a project
- with a name that already existed in the users namespace the module will
- simply return as "unchanged".
-'''
+ - Projects must have a unique name. If you attempt to create a project with a name that already existed in the users namespace
+ the module will simply return as "unchanged".
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# An example for creating a project
- hosts: localhost
connection: local
@@ -132,9 +124,9 @@ EXAMPLES = '''
state: present
config: {}
description: my new project
-'''
+"""
-RETURN = '''
+RETURN = r"""
old_state:
description: The old state of the project.
returned: success
@@ -184,7 +176,7 @@ actions:
type: list
elements: str
sample: ["create"]
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.lxd import (
LXDClient, LXDClientException, default_key_file, default_cert_file
diff --git a/plugins/modules/macports.py b/plugins/modules/macports.py
index cd620687d7..3f02eeb411 100644
--- a/plugins/modules/macports.py
+++ b/plugins/modules/macports.py
@@ -12,54 +12,54 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: macports
author: "Jimmy Tang (@jcftang)"
short_description: Package manager for MacPorts
description:
- - Manages MacPorts packages (ports)
+ - Manages MacPorts packages (ports).
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- description:
- - A list of port names.
- aliases: ['port']
- type: list
- elements: str
- selfupdate:
- description:
- - Update Macports and the ports tree, either prior to installing ports or as a separate step.
- - Equivalent to running C(port selfupdate).
- aliases: ['update_cache', 'update_ports']
- default: false
- type: bool
- state:
- description:
- - Indicates the desired state of the port.
- choices: [ 'present', 'absent', 'active', 'inactive', 'installed', 'removed']
- default: present
- type: str
- upgrade:
- description:
- - Upgrade all outdated ports, either prior to installing ports or as a separate step.
- - Equivalent to running C(port upgrade outdated).
- default: false
- type: bool
- variant:
- description:
- - A port variant specification.
- - 'O(variant) is only supported with O(state=installed) and O(state=present).'
- aliases: ['variants']
- type: str
-'''
-EXAMPLES = '''
+ name:
+ description:
+ - A list of port names.
+ aliases: ['port']
+ type: list
+ elements: str
+ selfupdate:
+ description:
+ - Update Macports and the ports tree, either prior to installing ports or as a separate step.
+ - Equivalent to running C(port selfupdate).
+ aliases: ['update_cache', 'update_ports']
+ default: false
+ type: bool
+ state:
+ description:
+ - Indicates the desired state of the port.
+ choices: ['present', 'absent', 'active', 'inactive', 'installed', 'removed']
+ default: present
+ type: str
+ upgrade:
+ description:
+ - Upgrade all outdated ports, either prior to installing ports or as a separate step.
+ - Equivalent to running C(port upgrade outdated).
+ default: false
+ type: bool
+ variant:
+ description:
+ - A port variant specification.
+ - O(variant) is only supported with O(state=installed) and O(state=present).
+ aliases: ['variants']
+ type: str
+"""
+
+EXAMPLES = r"""
- name: Install the foo port
community.general.macports:
name: foo
@@ -74,8 +74,8 @@ EXAMPLES = '''
name: "{{ ports }}"
vars:
ports:
- - foo
- - foo-tools
+ - foo
+ - foo-tools
- name: Update Macports and the ports tree, then upgrade all outdated ports
community.general.macports:
@@ -101,7 +101,7 @@ EXAMPLES = '''
community.general.macports:
name: foo
state: inactive
-'''
+"""
import re
@@ -221,7 +221,7 @@ def install_ports(module, port_path, ports, variant, stdout, stderr):
def activate_ports(module, port_path, ports, stdout, stderr):
- """ Activate a port if it's inactive. """
+ """ Activate a port if it is inactive. """
activate_c = 0
@@ -248,7 +248,7 @@ def activate_ports(module, port_path, ports, stdout, stderr):
def deactivate_ports(module, port_path, ports, stdout, stderr):
- """ Deactivate a port if it's active. """
+ """ Deactivate a port if it is active. """
deactivated_c = 0
diff --git a/plugins/modules/mail.py b/plugins/modules/mail.py
index 1916c140c3..03192e5bf8 100644
--- a/plugins/modules/mail.py
+++ b/plugins/modules/mail.py
@@ -9,27 +9,21 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
-- Dag Wieers (@dagwieers)
+ - Dag Wieers (@dagwieers)
module: mail
short_description: Send an email
description:
-- This module is useful for sending emails from playbooks.
-- One may wonder why automate sending emails? In complex environments
- there are from time to time processes that cannot be automated, either
- because you lack the authority to make it so, or because not everyone
- agrees to a common approach.
-- If you cannot automate a specific step, but the step is non-blocking,
- sending out an email to the responsible party to make them perform their
- part of the bargain is an elegant way to put the responsibility in
- someone else's lap.
-- Of course sending out a mail can be equally useful as a way to notify
- one or more people in a team that a specific action has been
- (successfully) taken.
+ - This module is useful for sending emails from playbooks.
+ - One may wonder why automate sending emails? In complex environments there are from time to time processes that cannot
+ be automated, either because you lack the authority to make it so, or because not everyone agrees to a common approach.
+ - If you cannot automate a specific step, but the step is non-blocking, sending out an email to the responsible party to
+ make them perform their part of the bargain is an elegant way to put the responsibility in someone else's lap.
+ - Of course sending out a mail can be equally useful as a way to notify one or more people in a team that a specific action
+ has been (successfully) taken.
extends_documentation_fragment:
-- community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
@@ -38,106 +32,106 @@ attributes:
options:
sender:
description:
- - The email-address the mail is sent from. May contain address and phrase.
+ - The email-address the mail is sent from. May contain address and phrase.
type: str
default: root
- aliases: [ from ]
+ aliases: [from]
to:
description:
- - The email-address(es) the mail is being sent to.
- - This is a list, which may contain address and phrase portions.
+ - The email-address(es) the mail is being sent to.
+ - This is a list, which may contain address and phrase portions.
type: list
elements: str
default: root
- aliases: [ recipients ]
+ aliases: [recipients]
cc:
description:
- - The email-address(es) the mail is being copied to.
- - This is a list, which may contain address and phrase portions.
+ - The email-address(es) the mail is being copied to.
+ - This is a list, which may contain address and phrase portions.
type: list
elements: str
default: []
bcc:
description:
- - The email-address(es) the mail is being 'blind' copied to.
- - This is a list, which may contain address and phrase portions.
+ - The email-address(es) the mail is being 'blind' copied to.
+ - This is a list, which may contain address and phrase portions.
type: list
elements: str
default: []
subject:
description:
- - The subject of the email being sent.
+ - The subject of the email being sent.
required: true
type: str
- aliases: [ msg ]
+ aliases: [msg]
body:
description:
- - The body of the email being sent.
+ - The body of the email being sent.
type: str
username:
description:
- - If SMTP requires username.
+ - If SMTP requires username.
type: str
password:
description:
- - If SMTP requires password.
+ - If SMTP requires password.
type: str
host:
description:
- - The mail server.
+ - The mail server.
type: str
default: localhost
port:
description:
- - The mail server port.
- - This must be a valid integer between 1 and 65534
+ - The mail server port.
+ - This must be a valid integer between V(1) and V(65534).
type: int
default: 25
attach:
description:
- - A list of pathnames of files to attach to the message.
- - Attached files will have their content-type set to C(application/octet-stream).
+ - A list of pathnames of files to attach to the message.
+ - Attached files will have their content-type set to C(application/octet-stream).
type: list
elements: path
default: []
headers:
description:
- - A list of headers which should be added to the message.
- - Each individual header is specified as C(header=value) (see example below).
+ - A list of headers which should be added to the message.
+ - Each individual header is specified as V(header=value) (see example below).
type: list
elements: str
default: []
charset:
description:
- - The character set of email being sent.
+ - The character set of email being sent.
type: str
default: utf-8
subtype:
description:
- - The minor mime type, can be either V(plain) or V(html).
- - The major type is always V(text).
+ - The minor mime type, can be either V(plain) or V(html).
+ - The major type is always V(text).
type: str
- choices: [ html, plain ]
+ choices: [html, plain]
default: plain
secure:
description:
- - If V(always), the connection will only send email if the connection is Encrypted.
- If the server doesn't accept the encrypted connection it will fail.
- - If V(try), the connection will attempt to setup a secure SSL/TLS session, before trying to send.
- - If V(never), the connection will not attempt to setup a secure SSL/TLS session, before sending
- - If V(starttls), the connection will try to upgrade to a secure SSL/TLS connection, before sending.
- If it is unable to do so it will fail.
+ - If V(always), the connection will only send email if the connection is Encrypted. If the server does not accept the
+ encrypted connection it will fail.
+ - If V(try), the connection will attempt to setup a secure SSL/TLS session, before trying to send.
+ - If V(never), the connection will not attempt to setup a secure SSL/TLS session, before sending.
+ - If V(starttls), the connection will try to upgrade to a secure SSL/TLS connection, before sending. If it is unable
+ to do so it will fail.
type: str
- choices: [ always, never, starttls, try ]
+ choices: [always, never, starttls, try]
default: try
timeout:
description:
- - Sets the timeout in seconds for connection attempts.
+ - Sets the timeout in seconds for connection attempts.
type: int
default: 20
ehlohost:
description:
- - Allows for manual specification of host for EHLO.
+ - Allows for manual specification of host for EHLO.
type: str
version_added: 3.8.0
message_id_domain:
@@ -147,9 +141,9 @@ options:
type: str
default: ansible
version_added: 8.2.0
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Example playbook sending mail to root
community.general.mail:
subject: System {{ ansible_hostname }} has been successfully provisioned.
@@ -174,15 +168,15 @@ EXAMPLES = r'''
body: Hello, this is an e-mail. I hope you like it ;-)
from: jane@example.net (Jane Jolie)
to:
- - John Doe
- - Suzie Something
+ - John Doe
+ - Suzie Something
cc: Charlie Root
attach:
- - /etc/group
- - /tmp/avatar2.png
+ - /etc/group
+ - /tmp/avatar2.png
headers:
- - Reply-To=john@example.com
- - X-Special="Something or other"
+ - Reply-To=john@example.com
+ - X-Special="Something or other"
charset: us-ascii
delegate_to: localhost
@@ -222,7 +216,7 @@ EXAMPLES = r'''
subject: Ansible-report
body: System {{ ansible_hostname }} has been successfully provisioned.
secure: starttls
-'''
+"""
import os
import smtplib
diff --git a/plugins/modules/make.py b/plugins/modules/make.py
index 39392afca6..a574560f7f 100644
--- a/plugins/modules/make.py
+++ b/plugins/modules/make.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: make
short_description: Run targets in a Makefile
requirements:
@@ -65,9 +64,9 @@ options:
type: list
elements: str
version_added: 7.2.0
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Build the default target
community.general.make:
chdir: /home/ubuntu/cool-project
@@ -103,9 +102,9 @@ EXAMPLES = r'''
# The following adds TARGET=arm64 TARGET_ARCH=aarch64 to the command line:
TARGET: arm64
TARGET_ARCH: aarch64
-'''
+"""
-RETURN = r'''
+RETURN = r"""
chdir:
description:
- The value of the module parameter O(chdir).
@@ -143,7 +142,7 @@ targets:
type: str
returned: success
version_added: 7.2.0
-'''
+"""
from ansible.module_utils.six import iteritems
from ansible.module_utils.six.moves import shlex_quote
diff --git a/plugins/modules/manageiq_alert_profiles.py b/plugins/modules/manageiq_alert_profiles.py
index eb6424bcdd..fff9552a6c 100644
--- a/plugins/modules/manageiq_alert_profiles.py
+++ b/plugins/modules/manageiq_alert_profiles.py
@@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: manageiq_alert_profiles
short_description: Configuration of alert profiles for ManageIQ
@@ -20,7 +19,6 @@ extends_documentation_fragment:
author: Elad Alfassa (@elad661)
description:
- The manageiq_alert_profiles module supports adding, updating and deleting alert profiles in ManageIQ.
-
attributes:
check_mode:
support: none
@@ -31,35 +29,33 @@ options:
state:
type: str
description:
- - absent - alert profile should not exist,
- - present - alert profile should exist,
+ - V(absent) - alert profile should not exist,
+ - V(present) - alert profile should exist.
choices: ['absent', 'present']
default: 'present'
name:
type: str
description:
- The unique alert profile name in ManageIQ.
- - Required when state is "absent" or "present".
+ required: true
resource_type:
type: str
description:
- - The resource type for the alert profile in ManageIQ. Required when state is "present".
- choices: ['Vm', 'ContainerNode', 'MiqServer', 'Host', 'Storage', 'EmsCluster',
- 'ExtManagementSystem', 'MiddlewareServer']
+ - The resource type for the alert profile in ManageIQ. Required when O(state=present).
+ choices: ['Vm', 'ContainerNode', 'MiqServer', 'Host', 'Storage', 'EmsCluster', 'ExtManagementSystem', 'MiddlewareServer']
alerts:
type: list
elements: str
description:
- List of alert descriptions to assign to this profile.
- - Required if state is "present"
+ - Required if O(state=present).
notes:
type: str
description:
- - Optional notes for this profile
+ - Optional notes for this profile.
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add an alert profile to ManageIQ
community.general.manageiq_alert_profiles:
state: present
@@ -72,7 +68,7 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Delete an alert profile from ManageIQ
community.general.manageiq_alert_profiles:
@@ -82,11 +78,11 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
-'''
+ validate_certs: false # only do this when you trust the network!
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec
@@ -118,8 +114,7 @@ class ManageIQAlertProfiles(object):
"""
alerts = []
for alert_description in alert_descriptions:
- alert = self.manageiq.find_collection_resource_or_fail("alert_definitions",
- description=alert_description)
+ alert = self.manageiq.find_collection_resource_or_fail("alert_definitions", description=alert_description)
alerts.append(alert['href'])
return alerts
@@ -257,7 +252,7 @@ class ManageIQAlertProfiles(object):
def main():
argument_spec = dict(
- name=dict(type='str'),
+ name=dict(type='str', required=True),
resource_type=dict(type='str', choices=['Vm',
'ContainerNode',
'MiqServer',
@@ -274,8 +269,7 @@ def main():
argument_spec.update(manageiq_argument_spec())
module = AnsibleModule(argument_spec=argument_spec,
- required_if=[('state', 'present', ['name', 'resource_type']),
- ('state', 'absent', ['name'])])
+ required_if=[('state', 'present', ['resource_type', 'alerts'])])
state = module.params['state']
name = module.params['name']
@@ -283,8 +277,7 @@ def main():
manageiq = ManageIQ(module)
manageiq_alert_profiles = ManageIQAlertProfiles(manageiq)
- existing_profile = manageiq.find_collection_resource_by("alert_definition_profiles",
- name=name)
+ existing_profile = manageiq.find_collection_resource_by("alert_definition_profiles", name=name)
# we need to add or update the alert profile
if state == "present":
diff --git a/plugins/modules/manageiq_alerts.py b/plugins/modules/manageiq_alerts.py
index 53f40fb00c..87fafcf10b 100644
--- a/plugins/modules/manageiq_alerts.py
+++ b/plugins/modules/manageiq_alerts.py
@@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: manageiq_alerts
short_description: Configuration of alerts in ManageIQ
@@ -20,7 +19,6 @@ extends_documentation_fragment:
author: Elad Alfassa (@elad661)
description:
- The manageiq_alerts module supports adding, updating and deleting alerts in ManageIQ.
-
attributes:
check_mode:
support: none
@@ -31,8 +29,8 @@ options:
state:
type: str
description:
- - absent - alert should not exist,
- - present - alert should exist,
+ - V(absent) - alert should not exist,
+ - V(present) - alert should exist.
required: false
choices: ['absent', 'present']
default: 'present'
@@ -44,9 +42,8 @@ options:
resource_type:
type: str
description:
- - The entity type for the alert in ManageIQ. Required when state is "present".
- choices: ['Vm', 'ContainerNode', 'MiqServer', 'Host', 'Storage', 'EmsCluster',
- 'ExtManagementSystem', 'MiddlewareServer']
+ - The entity type for the alert in ManageIQ. Required when O(state=present).
+ choices: ['Vm', 'ContainerNode', 'MiqServer', 'Host', 'Storage', 'EmsCluster', 'ExtManagementSystem', 'MiddlewareServer']
expression_type:
type: str
description:
@@ -58,20 +55,18 @@ options:
description:
- The alert expression for ManageIQ.
- Can either be in the "Miq Expression" format or the "Hash Expression format".
- - Required if state is "present".
+ - Required if O(state=present).
enabled:
description:
- - Enable or disable the alert. Required if state is "present".
+ - Enable or disable the alert. Required if O(state=present).
type: bool
options:
type: dict
description:
- - Additional alert options, such as notification type and frequency
+ - Additional alert options, such as notification type and frequency.
+"""
-
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add an alert with a "hash expression" to ManageIQ
community.general.manageiq_alerts:
state: present
@@ -83,15 +78,15 @@ EXAMPLES = '''
from: "example@example.com"
resource_type: ContainerNode
expression:
- eval_method: hostd_log_threshold
- mode: internal
- options: {}
+ eval_method: hostd_log_threshold
+ mode: internal
+ options: {}
enabled: true
manageiq_connection:
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Add an alert with a "miq expression" to ManageIQ
community.general.manageiq_alerts:
@@ -105,20 +100,20 @@ EXAMPLES = '''
resource_type: Vm
expression_type: miq
expression:
- and:
- - CONTAINS:
- tag: Vm.managed-environment
- value: prod
- - not:
- CONTAINS:
- tag: Vm.host.managed-environment
- value: prod
+ and:
+ - CONTAINS:
+ tag: Vm.managed-environment
+ value: prod
+ - not:
+ CONTAINS:
+ tag: Vm.host.managed-environment
+ value: prod
enabled: true
manageiq_connection:
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Delete an alert from ManageIQ
community.general.manageiq_alerts:
@@ -128,11 +123,11 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
-'''
+ validate_certs: false # only do this when you trust the network!
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec
@@ -156,7 +151,7 @@ class ManageIQAlert(object):
self.miq_expression = alert['miq_expression']
if 'exp' in self.miq_expression:
# miq_expression is a field that needs a special case, because
- # it's returned surrounded by a dict named exp even though we don't
+ # it is returned surrounded by a dict named exp even though we don't
# send it with that dict.
self.miq_expression = self.miq_expression['exp']
diff --git a/plugins/modules/manageiq_group.py b/plugins/modules/manageiq_group.py
index e060b9a01a..9781ebfc98 100644
--- a/plugins/modules/manageiq_group.py
+++ b/plugins/modules/manageiq_group.py
@@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: manageiq_group
short_description: Management of groups in ManageIQ
@@ -33,70 +32,69 @@ options:
state:
type: str
description:
- - absent - group should not exist, present - group should be.
+ - V(absent) - group should not exist,
+ - V(present) - group should exist.
choices: ['absent', 'present']
default: 'present'
description:
type: str
description:
- - The group description.
+ - The group description.
required: true
- default: null
role_id:
type: int
description:
- - The the group role id
+ - The the group role ID.
required: false
- default: null
role:
type: str
description:
- - The the group role name
- - The O(role_id) has precedence over the O(role) when supplied.
+ - The the group role name.
+ - The O(role_id) has precedence over the O(role) when supplied.
required: false
- default: null
+ default:
tenant_id:
type: int
description:
- - The tenant for the group identified by the tenant id.
+ - The tenant for the group identified by the tenant ID.
required: false
- default: null
+ default:
tenant:
type: str
description:
- - The tenant for the group identified by the tenant name.
- - The O(tenant_id) has precedence over the O(tenant) when supplied.
- - Tenant names are case sensitive.
+ - The tenant for the group identified by the tenant name.
+ - The O(tenant_id) has precedence over the O(tenant) when supplied.
+ - Tenant names are case sensitive.
required: false
- default: null
+ default:
managed_filters:
- description: The tag values per category
+ description: The tag values per category.
type: dict
required: false
- default: null
+ default:
managed_filters_merge_mode:
type: str
description:
- - In merge mode existing categories are kept or updated, new categories are added.
- - In replace mode all categories will be replaced with the supplied O(managed_filters).
- choices: [ merge, replace ]
+ - In merge mode existing categories are kept or updated, new categories are added.
+ - In replace mode all categories will be replaced with the supplied O(managed_filters).
+ choices: [merge, replace]
default: replace
belongsto_filters:
- description: A list of strings with a reference to the allowed host, cluster or folder
+ description: A list of strings with a reference to the allowed host, cluster or folder.
type: list
elements: str
required: false
- default: null
+ default:
belongsto_filters_merge_mode:
type: str
description:
- - In merge mode existing settings are merged with the supplied O(belongsto_filters).
- - In replace mode current values are replaced with the supplied O(belongsto_filters).
- choices: [ merge, replace ]
+ - In merge mode existing settings are merged with the supplied O(belongsto_filters).
+ - In replace mode current values are replaced with the supplied O(belongsto_filters).
+ choices: [merge, replace]
default: replace
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a group in ManageIQ with the role EvmRole-user and tenant 'my_tenant'
community.general.manageiq_group:
description: 'MyGroup-user'
@@ -106,7 +104,7 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Create a group in ManageIQ with the role EvmRole-user and tenant with tenant_id 4
community.general.manageiq_group:
@@ -117,33 +115,33 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name:
- - Create or update a group in ManageIQ with the role EvmRole-user and tenant my_tenant.
- - Apply 3 prov_max_cpu and 2 department tags to the group.
- - Limit access to a cluster for the group.
+ - Create or update a group in ManageIQ with the role EvmRole-user and tenant my_tenant.
+ - Apply 3 prov_max_cpu and 2 department tags to the group.
+ - Limit access to a cluster for the group.
community.general.manageiq_group:
description: 'MyGroup-user'
role: 'EvmRole-user'
tenant: my_tenant
managed_filters:
prov_max_cpu:
- - '1'
- - '2'
- - '4'
+ - '1'
+ - '2'
+ - '4'
department:
- - defense
- - engineering
+ - defense
+ - engineering
managed_filters_merge_mode: replace
belongsto_filters:
- - "/belongsto/ExtManagementSystem|ProviderName/EmsFolder|Datacenters/EmsFolder|dc_name/EmsFolder|host/EmsCluster|Cluster name"
+ - "/belongsto/ExtManagementSystem|ProviderName/EmsFolder|Datacenters/EmsFolder|dc_name/EmsFolder|host/EmsCluster|Cluster name"
belongsto_filters_merge_mode: merge
manageiq_connection:
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Delete a group in ManageIQ
community.general.manageiq_group:
@@ -161,53 +159,53 @@ EXAMPLES = '''
manageiq_connection:
url: 'http://127.0.0.1:3000'
token: 'sometoken'
-'''
+"""
-RETURN = '''
+RETURN = r"""
group:
description: The group.
returned: success
type: complex
contains:
description:
- description: The group description
+ description: The group description.
returned: success
type: str
id:
- description: The group id
+ description: The group ID.
returned: success
type: int
group_type:
- description: The group type, system or user
+ description: The group type, system or user.
returned: success
type: str
role:
- description: The group role name
+ description: The group role name.
returned: success
type: str
tenant:
- description: The group tenant name
+ description: The group tenant name.
returned: success
type: str
managed_filters:
- description: The tag values per category
+ description: The tag values per category.
returned: success
type: dict
belongsto_filters:
- description: A list of strings with a reference to the allowed host, cluster or folder
+ description: A list of strings with a reference to the allowed host, cluster or folder.
returned: success
type: list
created_on:
- description: Group creation date
+ description: Group creation date.
returned: success
type: str
sample: "2018-08-12T08:37:55+00:00"
updated_on:
- description: Group update date
+ description: Group update date.
returned: success
type: int
sample: "2018-08-12T08:37:55+00:00"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec
diff --git a/plugins/modules/manageiq_policies.py b/plugins/modules/manageiq_policies.py
index f2101ad28b..6e2ac36a38 100644
--- a/plugins/modules/manageiq_policies.py
+++ b/plugins/modules/manageiq_policies.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: manageiq_policies
short_description: Management of resource policy_profiles in ManageIQ
@@ -21,7 +20,6 @@ extends_documentation_fragment:
author: Daniel Korn (@dkorn)
description:
- The manageiq_policies module supports adding and deleting policy_profiles in ManageIQ.
-
attributes:
check_mode:
support: none
@@ -33,7 +31,7 @@ options:
type: str
description:
- V(absent) - policy_profiles should not exist,
- - V(present) - policy_profiles should exist,
+ - V(present) - policy_profiles should exist.
choices: ['absent', 'present']
default: 'present'
policy_profiles:
@@ -47,9 +45,8 @@ options:
description:
- The type of the resource to which the profile should be [un]assigned.
required: true
- choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster',
- 'data store', 'group', 'resource pool', 'service', 'service template',
- 'template', 'tenant', 'user']
+ choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service',
+ 'service template', 'template', 'tenant', 'user']
resource_name:
type: str
description:
@@ -61,9 +58,9 @@ options:
- The ID of the resource to which the profile should be [un]assigned.
- Must be specified if O(resource_name) is not set. Both options are mutually exclusive.
version_added: 2.2.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Assign new policy_profile for a provider in ManageIQ
community.general.manageiq_policies:
resource_name: 'EngLab'
@@ -74,7 +71,7 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Unassign a policy_profile for a provider in ManageIQ
community.general.manageiq_policies:
@@ -87,16 +84,16 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
-'''
+ validate_certs: false # only do this when you trust the network!
+"""
-RETURN = '''
+RETURN = r"""
manageiq_policies:
description:
- - List current policy_profile and policies for a provider in ManageIQ
+ - List current policy_profile and policies for a provider in ManageIQ.
returned: always
type: dict
- sample: '{
+ sample: {
"changed": false,
"profiles": [
{
@@ -121,8 +118,8 @@ manageiq_policies:
"profile_name": "openscap profile"
}
]
- }'
-'''
+ }
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec, manageiq_entities
diff --git a/plugins/modules/manageiq_policies_info.py b/plugins/modules/manageiq_policies_info.py
index fda7dcadfe..4ef51515a6 100644
--- a/plugins/modules/manageiq_policies_info.py
+++ b/plugins/modules/manageiq_policies_info.py
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: manageiq_policies_info
version_added: 5.8.0
@@ -24,16 +23,14 @@ extends_documentation_fragment:
author: Alexei Znamensky (@russoz)
description:
- The manageiq_policies module supports listing policy_profiles in ManageIQ.
-
options:
resource_type:
type: str
description:
- The type of the resource to obtain the profile for.
required: true
- choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster',
- 'data store', 'group', 'resource pool', 'service', 'service template',
- 'template', 'tenant', 'user']
+ choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service',
+ 'service template', 'template', 'tenant', 'user']
resource_name:
type: str
description:
@@ -44,9 +41,9 @@ options:
description:
- The ID of the resource to obtain the profile for.
- Must be specified if O(resource_name) is not set. Both options are mutually exclusive.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List current policy_profile and policies for a provider in ManageIQ
community.general.manageiq_policies_info:
resource_name: 'EngLab'
@@ -56,9 +53,9 @@ EXAMPLES = '''
username: 'admin'
password: 'smartvm'
register: result
-'''
+"""
-RETURN = '''
+RETURN = r"""
profiles:
description:
- List current policy_profile and policies for a provider in ManageIQ.
@@ -78,7 +75,7 @@ profiles:
name: schedule compliance after smart state analysis
profile_description: OpenSCAP profile
profile_name: openscap profile
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec, manageiq_entities
diff --git a/plugins/modules/manageiq_provider.py b/plugins/modules/manageiq_provider.py
index 35c73a38b3..98677c7beb 100644
--- a/plugins/modules/manageiq_provider.py
+++ b/plugins/modules/manageiq_provider.py
@@ -9,7 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: manageiq_provider
short_description: Management of provider in ManageIQ
extends_documentation_fragment:
@@ -19,7 +19,6 @@ extends_documentation_fragment:
author: Daniel Korn (@dkorn)
description:
- The manageiq_provider module supports adding, updating, and deleting provider in ManageIQ.
-
attributes:
check_mode:
support: none
@@ -30,7 +29,9 @@ options:
state:
type: str
description:
- - absent - provider should not exist, present - provider should be present, refresh - provider will be refreshed
+ - V(absent) - provider should not exist,
+ - V(present) - provider should be present,
+ - V(refresh) - provider will be refreshed.
choices: ['absent', 'present', 'refresh']
default: 'present'
name:
@@ -47,30 +48,30 @@ options:
default: 'default'
provider_region:
type: str
- description: The provider region name to connect to (e.g. AWS region for Amazon).
+ description: The provider region name to connect to (for example AWS region for Amazon).
host_default_vnc_port_start:
type: str
- description: The first port in the host VNC range. defaults to None.
+ description: The first port in the host VNC range.
host_default_vnc_port_end:
type: str
- description: The last port in the host VNC range. defaults to None.
+ description: The last port in the host VNC range.
subscription:
type: str
- description: Microsoft Azure subscription ID. defaults to None.
+ description: Microsoft Azure subscription ID.
project:
type: str
- description: Google Compute Engine Project ID. defaults to None.
+ description: Google Compute Engine Project ID.
azure_tenant_id:
type: str
description: Tenant ID. defaults to None.
- aliases: [ keystone_v3_domain_id ]
+ aliases: [keystone_v3_domain_id]
tenant_mapping_enabled:
type: bool
default: false
- description: Whether to enable mapping of existing tenants. defaults to False.
+ description: Whether to enable mapping of existing tenants.
api_version:
type: str
- description: The OpenStack Keystone API version. defaults to None.
+ description: The OpenStack Keystone API version.
choices: ['v2', 'v3']
provider:
@@ -79,32 +80,32 @@ options:
suboptions:
hostname:
type: str
- description: The provider's api hostname.
+ description: The provider's API hostname.
required: true
port:
type: int
- description: The provider's api port.
+ description: The provider's API port.
userid:
type: str
- description: Provider's api endpoint authentication userid. defaults to None.
+ description: Provider's API endpoint authentication userid.
password:
type: str
- description: Provider's api endpoint authentication password. defaults to None.
+ description: Provider's API endpoint authentication password.
auth_key:
type: str
- description: Provider's api endpoint authentication bearer token. defaults to None.
+ description: Provider's API endpoint authentication bearer token.
validate_certs:
- description: Whether SSL certificates should be verified for HTTPS requests (deprecated). defaults to True.
+ description: Whether SSL certificates should be verified for HTTPS requests (deprecated).
type: bool
default: true
- aliases: [ verify_ssl ]
+ aliases: [verify_ssl]
security_protocol:
type: str
- description: How SSL certificates should be used for HTTPS requests. defaults to None.
- choices: ['ssl-with-validation','ssl-with-validation-custom-ca','ssl-without-validation','non-ssl']
+ description: How SSL certificates should be used for HTTPS requests.
+ choices: ['ssl-with-validation', 'ssl-with-validation-custom-ca', 'ssl-without-validation', 'non-ssl']
certificate_authority:
type: str
- description: The CA bundle string with custom certificates. defaults to None.
+ description: The CA bundle string with custom certificates.
path:
type: str
description:
@@ -125,39 +126,38 @@ options:
type: str
description:
- TODO needs documentation.
-
metrics:
description: Metrics endpoint connection information.
type: dict
suboptions:
hostname:
type: str
- description: The provider's api hostname.
+ description: The provider's API hostname.
required: true
port:
type: int
- description: The provider's api port.
+ description: The provider's API port.
userid:
type: str
- description: Provider's api endpoint authentication userid. defaults to None.
+ description: Provider's API endpoint authentication userid.
password:
type: str
- description: Provider's api endpoint authentication password. defaults to None.
+ description: Provider's API endpoint authentication password.
auth_key:
type: str
- description: Provider's api endpoint authentication bearer token. defaults to None.
+ description: Provider's API endpoint authentication bearer token.
validate_certs:
- description: Whether SSL certificates should be verified for HTTPS requests (deprecated). defaults to True.
+ description: Whether SSL certificates should be verified for HTTPS requests (deprecated).
type: bool
default: true
- aliases: [ verify_ssl ]
+ aliases: [verify_ssl]
security_protocol:
type: str
- choices: ['ssl-with-validation','ssl-with-validation-custom-ca','ssl-without-validation','non-ssl']
- description: How SSL certificates should be used for HTTPS requests. defaults to None.
+ choices: ['ssl-with-validation', 'ssl-with-validation-custom-ca', 'ssl-without-validation', 'non-ssl']
+ description: How SSL certificates should be used for HTTPS requests.
certificate_authority:
type: str
- description: The CA bundle string with custom certificates. defaults to None.
+ description: The CA bundle string with custom certificates.
path:
type: str
description: Database name for oVirt metrics. Defaults to V(ovirt_engine_history).
@@ -177,35 +177,34 @@ options:
type: str
description:
- TODO needs documentation.
-
alerts:
description: Alerts endpoint connection information.
type: dict
suboptions:
hostname:
type: str
- description: The provider's api hostname.
+ description: The provider's API hostname.
required: true
port:
type: int
- description: The provider's api port.
+ description: The provider's API port.
userid:
type: str
- description: Provider's api endpoint authentication userid. defaults to None.
+ description: Provider's API endpoint authentication userid. defaults to None.
password:
type: str
- description: Provider's api endpoint authentication password. defaults to None.
+ description: Provider's API endpoint authentication password. defaults to None.
auth_key:
type: str
- description: Provider's api endpoint authentication bearer token. defaults to None.
+ description: Provider's API endpoint authentication bearer token. defaults to None.
validate_certs:
type: bool
description: Whether SSL certificates should be verified for HTTPS requests (deprecated). defaults to True.
default: true
- aliases: [ verify_ssl ]
+ aliases: [verify_ssl]
security_protocol:
type: str
- choices: ['ssl-with-validation','ssl-with-validation-custom-ca','ssl-without-validation', 'non-ssl']
+ choices: ['ssl-with-validation', 'ssl-with-validation-custom-ca', 'ssl-without-validation', 'non-ssl']
description: How SSL certificates should be used for HTTPS requests. defaults to None.
certificate_authority:
type: str
@@ -230,7 +229,6 @@ options:
type: str
description:
- TODO needs documentation.
-
ssh_keypair:
description: SSH key pair used for SSH connections to all hosts in this provider.
type: dict
@@ -250,10 +248,10 @@ options:
- Whether certificates should be verified for connections.
type: bool
default: true
- aliases: [ verify_ssl ]
+ aliases: [verify_ssl]
security_protocol:
type: str
- choices: ['ssl-with-validation','ssl-with-validation-custom-ca','ssl-without-validation', 'non-ssl']
+ choices: ['ssl-with-validation', 'ssl-with-validation-custom-ca', 'ssl-without-validation', 'non-ssl']
description:
- TODO needs documentation.
certificate_authority:
@@ -288,9 +286,9 @@ options:
type: int
description:
- TODO needs documentation.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a new provider in ManageIQ ('Hawkular' metrics)
community.general.manageiq_provider:
name: 'EngLab'
@@ -507,10 +505,10 @@ EXAMPLES = '''
hostname: 'gce.example.com'
auth_key: 'google_json_key'
validate_certs: 'false'
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec
diff --git a/plugins/modules/manageiq_tags.py b/plugins/modules/manageiq_tags.py
index 3ab5eca4f8..f4136d1732 100644
--- a/plugins/modules/manageiq_tags.py
+++ b/plugins/modules/manageiq_tags.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: manageiq_tags
short_description: Management of resource tags in ManageIQ
@@ -21,7 +20,6 @@ extends_documentation_fragment:
author: Daniel Korn (@dkorn)
description:
- The manageiq_tags module supports adding, updating and deleting tags in ManageIQ.
-
attributes:
check_mode:
support: none
@@ -32,7 +30,7 @@ options:
state:
type: str
description:
- - V(absent) - tags should not exist.
+ - V(absent) - tags should not exist,
- V(present) - tags should exist.
choices: ['absent', 'present']
default: 'present'
@@ -47,9 +45,8 @@ options:
description:
- The relevant resource type in manageiq.
required: true
- choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster',
- 'data store', 'group', 'resource pool', 'service', 'service template',
- 'template', 'tenant', 'user']
+ choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service',
+ 'service template', 'template', 'tenant', 'user']
resource_name:
type: str
description:
@@ -61,38 +58,38 @@ options:
- Must be specified if O(resource_name) is not set. Both options are mutually exclusive.
type: int
version_added: 2.2.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create new tags for a provider in ManageIQ.
community.general.manageiq_tags:
resource_name: 'EngLab'
resource_type: 'provider'
tags:
- - category: environment
- name: prod
- - category: owner
- name: prod_ops
+ - category: environment
+ name: prod
+ - category: owner
+ name: prod_ops
manageiq_connection:
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when connecting to localhost!
+ validate_certs: false # only do this when connecting to localhost!
- name: Create new tags for a provider in ManageIQ.
community.general.manageiq_tags:
resource_id: 23000000790497
resource_type: 'provider'
tags:
- - category: environment
- name: prod
- - category: owner
- name: prod_ops
+ - category: environment
+ name: prod
+ - category: owner
+ name: prod_ops
manageiq_connection:
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when connecting to localhost!
+ validate_certs: false # only do this when connecting to localhost!
- name: Remove tags for a provider in ManageIQ.
community.general.manageiq_tags:
@@ -100,19 +97,19 @@ EXAMPLES = '''
resource_name: 'EngLab'
resource_type: 'provider'
tags:
- - category: environment
- name: prod
- - category: owner
- name: prod_ops
+ - category: environment
+ name: prod
+ - category: owner
+ name: prod_ops
manageiq_connection:
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when connecting to localhost!
-'''
+ validate_certs: false # only do this when connecting to localhost!
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import (
diff --git a/plugins/modules/manageiq_tags_info.py b/plugins/modules/manageiq_tags_info.py
index 75e111540b..a39f4b84d3 100644
--- a/plugins/modules/manageiq_tags_info.py
+++ b/plugins/modules/manageiq_tags_info.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: manageiq_tags_info
version_added: 5.8.0
short_description: Retrieve resource tags in ManageIQ
@@ -22,16 +21,14 @@ extends_documentation_fragment:
author: Alexei Znamensky (@russoz)
description:
- This module supports retrieving resource tags from ManageIQ.
-
options:
resource_type:
type: str
description:
- The relevant resource type in ManageIQ.
required: true
- choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster',
- 'data store', 'group', 'resource pool', 'service', 'service template',
- 'template', 'tenant', 'user']
+ choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service',
+ 'service template', 'template', 'tenant', 'user']
resource_name:
type: str
description:
@@ -42,9 +39,9 @@ options:
- The ID of the resource at which tags will be controlled.
- Must be specified if O(resource_name) is not set. Both options are mutually exclusive.
type: int
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List current tags for a provider in ManageIQ.
community.general.manageiq_tags_info:
resource_name: 'EngLab'
@@ -54,15 +51,15 @@ EXAMPLES = '''
username: 'admin'
password: 'smartvm'
register: result
-'''
+"""
-RETURN = '''
+RETURN = r"""
tags:
description: List of tags associated with the resource.
returned: on success
type: list
elements: dict
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import (
diff --git a/plugins/modules/manageiq_tenant.py b/plugins/modules/manageiq_tenant.py
index a5a56191e7..deb2fc452d 100644
--- a/plugins/modules/manageiq_tenant.py
+++ b/plugins/modules/manageiq_tenant.py
@@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: manageiq_tenant
short_description: Management of tenants in ManageIQ
@@ -31,7 +30,8 @@ options:
state:
type: str
description:
- - absent - tenant should not exist, present - tenant should be.
+ - V(absent) - tenant should not exist,
+ - V(present) - tenant should be.
choices: ['absent', 'present']
default: 'present'
name:
@@ -39,42 +39,42 @@ options:
description:
- The tenant name.
required: true
- default: null
+ default:
description:
type: str
description:
- - The tenant description.
+ - The tenant description.
required: true
- default: null
+ default:
parent_id:
type: int
description:
- - The id of the parent tenant. If not supplied the root tenant is used.
- - The O(parent_id) takes president over O(parent) when supplied
+ - The ID of the parent tenant. If not supplied the root tenant is used.
+ - The O(parent_id) takes president over O(parent) when supplied.
required: false
- default: null
+ default:
parent:
type: str
description:
- - The name of the parent tenant. If not supplied and no O(parent_id) is supplied the root tenant is used.
+ - The name of the parent tenant. If not supplied and no O(parent_id) is supplied the root tenant is used.
required: false
- default: null
+ default:
quotas:
type: dict
description:
- - The tenant quotas.
- - All parameters case sensitive.
- - 'Valid attributes are:'
- - ' - C(cpu_allocated) (int): use null to remove the quota.'
- - ' - C(mem_allocated) (GB): use null to remove the quota.'
- - ' - C(storage_allocated) (GB): use null to remove the quota.'
- - ' - C(vms_allocated) (int): use null to remove the quota.'
- - ' - C(templates_allocated) (int): use null to remove the quota.'
+ - The tenant quotas.
+ - All parameters case sensitive.
+ - 'Valid attributes are:'
+ - '- V(cpu_allocated) (int): use null to remove the quota.'
+ - '- V(mem_allocated) (GB): use null to remove the quota.'
+ - '- V(storage_allocated) (GB): use null to remove the quota.'
+ - '- V(vms_allocated) (int): use null to remove the quota.'
+ - '- V(templates_allocated) (int): use null to remove the quota.'
required: false
default: {}
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Update the root tenant in ManageIQ
community.general.manageiq_tenant:
name: 'My Company'
@@ -83,7 +83,7 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Create a tenant in ManageIQ
community.general.manageiq_tenant:
@@ -94,7 +94,7 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Delete a tenant in ManageIQ
community.general.manageiq_tenant:
@@ -105,7 +105,7 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Set tenant quota for cpu_allocated, mem_allocated, remove quota for vms_allocated
community.general.manageiq_tenant:
@@ -114,12 +114,12 @@ EXAMPLES = '''
quotas:
- cpu_allocated: 100
- mem_allocated: 50
- - vms_allocated: null
+ - vms_allocated:
manageiq_connection:
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Delete a tenant in ManageIQ using a token
@@ -130,39 +130,39 @@ EXAMPLES = '''
manageiq_connection:
url: 'http://127.0.0.1:3000'
token: 'sometoken'
- validate_certs: false # only do this when you trust the network!
-'''
+ validate_certs: false # only do this when you trust the network!
+"""
-RETURN = '''
+RETURN = r"""
tenant:
description: The tenant.
returned: success
type: complex
contains:
id:
- description: The tenant id
+ description: The tenant ID.
returned: success
type: int
name:
- description: The tenant name
+ description: The tenant name.
returned: success
type: str
description:
- description: The tenant description
+ description: The tenant description.
returned: success
type: str
parent_id:
- description: The id of the parent tenant
+ description: The ID of the parent tenant.
returned: success
type: int
quotas:
- description: List of tenant quotas
+ description: List of tenant quotas.
returned: success
type: list
sample:
cpu_allocated: 100
mem_allocated: 50
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec
diff --git a/plugins/modules/manageiq_user.py b/plugins/modules/manageiq_user.py
index 0d8a81984f..a4d5c21dfc 100644
--- a/plugins/modules/manageiq_user.py
+++ b/plugins/modules/manageiq_user.py
@@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: manageiq_user
short_description: Management of users in ManageIQ
@@ -20,7 +19,6 @@ extends_documentation_fragment:
author: Daniel Korn (@dkorn)
description:
- The manageiq_user module supports adding, updating and deleting users in ManageIQ.
-
attributes:
check_mode:
support: none
@@ -31,7 +29,8 @@ options:
state:
type: str
description:
- - absent - user should not exist, present - user should be.
+ - V(absent) - user should not exist,
+ - V(present) - user should be.
choices: ['absent', 'present']
default: 'present'
userid:
@@ -60,10 +59,11 @@ options:
default: always
choices: ['always', 'on_create']
description:
- - V(always) will update passwords unconditionally. V(on_create) will only set the password for a newly created user.
-'''
+ - V(always) will update passwords unconditionally.
+ - V(on_create) will only set the password for a newly created user.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a new user in ManageIQ
community.general.manageiq_user:
userid: 'jdoe'
@@ -75,7 +75,7 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Create a new user in ManageIQ using a token
community.general.manageiq_user:
@@ -87,7 +87,7 @@ EXAMPLES = '''
manageiq_connection:
url: 'http://127.0.0.1:3000'
token: 'sometoken'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Delete a user in ManageIQ
community.general.manageiq_user:
@@ -97,7 +97,7 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Delete a user in ManageIQ using a token
community.general.manageiq_user:
@@ -106,7 +106,7 @@ EXAMPLES = '''
manageiq_connection:
url: 'http://127.0.0.1:3000'
token: 'sometoken'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Update email of user in ManageIQ
community.general.manageiq_user:
@@ -116,7 +116,7 @@ EXAMPLES = '''
url: 'http://127.0.0.1:3000'
username: 'admin'
password: 'smartvm'
- validate_certs: false # only do this when you trust the network!
+ validate_certs: false # only do this when you trust the network!
- name: Update email of user in ManageIQ using a token
community.general.manageiq_user:
@@ -125,11 +125,11 @@ EXAMPLES = '''
manageiq_connection:
url: 'http://127.0.0.1:3000'
token: 'sometoken'
- validate_certs: false # only do this when you trust the network!
-'''
+ validate_certs: false # only do this when you trust the network!
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec
diff --git a/plugins/modules/mas.py b/plugins/modules/mas.py
index 8bb80840ca..3659c97636 100644
--- a/plugins/modules/mas.py
+++ b/plugins/modules/mas.py
@@ -10,54 +10,54 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: mas
short_description: Manage Mac App Store applications with mas-cli
description:
- - Installs, uninstalls and updates macOS applications from the Mac App Store using the C(mas-cli).
+ - Installs, uninstalls and updates macOS applications from the Mac App Store using the C(mas-cli).
version_added: '0.2.0'
author:
- - Michael Heap (@mheap)
- - Lukas Bestle (@lukasbestle)
+ - Michael Heap (@mheap)
+ - Lukas Bestle (@lukasbestle)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- id:
- description:
- - The Mac App Store identifier of the app(s) you want to manage.
- - This can be found by running C(mas search APP_NAME) on your machine.
- type: list
- elements: int
- state:
- description:
- - Desired state of the app installation.
- - The V(absent) value requires root permissions, also see the examples.
- type: str
- choices:
- - absent
- - latest
- - present
- default: present
- upgrade_all:
- description:
- - Upgrade all installed Mac App Store apps.
- type: bool
- default: false
- aliases: ["upgrade"]
+ id:
+ description:
+ - The Mac App Store identifier of the app(s) you want to manage.
+ - This can be found by running C(mas search APP_NAME) on your machine.
+ type: list
+ elements: int
+ state:
+ description:
+ - Desired state of the app installation.
+ - The V(absent) value requires root permissions, also see the examples.
+ type: str
+ choices:
+ - absent
+ - latest
+ - present
+ default: present
+ upgrade_all:
+ description:
+ - Upgrade all installed Mac App Store apps.
+ type: bool
+ default: false
+ aliases: ["upgrade"]
requirements:
- - macOS 10.11+
- - "mas-cli (U(https://github.com/mas-cli/mas)) 1.5.0+ available as C(mas) in the bin path"
- - The Apple ID to use already needs to be signed in to the Mac App Store (check with C(mas account)).
- - The feature of "checking if user is signed in" is disabled for anyone using macOS 12.0+.
- - Users need to sign in via the Mac App Store GUI beforehand for anyone using macOS 12.0+ due to U(https://github.com/mas-cli/mas/issues/417).
-'''
+ - macOS 10.11 or higher.
+ - "mas-cli (U(https://github.com/mas-cli/mas)) 1.5.0+ available as C(mas) in the bin path"
+ - The Apple ID to use already needs to be signed in to the Mac App Store (check with C(mas account)).
+ - The feature of "checking if user is signed in" is disabled for anyone using macOS 12.0+.
+ - Users need to sign in to the Mac App Store GUI beforehand for anyone using macOS 12.0+ due to U(https://github.com/mas-cli/mas/issues/417).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install Keynote
community.general.mas:
id: 409183694
@@ -99,9 +99,9 @@ EXAMPLES = '''
id: 413857545
state: absent
become: true # Uninstallation requires root permissions
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from ansible.module_utils.basic import AnsibleModule
import os
diff --git a/plugins/modules/matrix.py b/plugins/modules/matrix.py
index 0b419c8d93..186c57dd31 100644
--- a/plugins/modules/matrix.py
+++ b/plugins/modules/matrix.py
@@ -8,58 +8,57 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
author: "Jan Christian Grünhage (@jcgruenhage)"
module: matrix
short_description: Send notifications to matrix
description:
- - This module sends html formatted notifications to matrix rooms.
+ - This module sends html formatted notifications to matrix rooms.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- msg_plain:
- type: str
- description:
- - Plain text form of the message to send to matrix, usually markdown
- required: true
- msg_html:
- type: str
- description:
- - HTML form of the message to send to matrix
- required: true
- room_id:
- type: str
- description:
- - ID of the room to send the notification to
- required: true
- hs_url:
- type: str
- description:
- - URL of the homeserver, where the CS-API is reachable
- required: true
- token:
- type: str
- description:
- - Authentication token for the API call. If provided, user_id and password are not required
- user_id:
- type: str
- description:
- - The user id of the user
- password:
- type: str
- description:
- - The password to log in with
+ msg_plain:
+ type: str
+ description:
+ - Plain text form of the message to send to matrix, usually markdown.
+ required: true
+ msg_html:
+ type: str
+ description:
+ - HTML form of the message to send to matrix.
+ required: true
+ room_id:
+ type: str
+ description:
+ - ID of the room to send the notification to.
+ required: true
+ hs_url:
+ type: str
+ description:
+ - URL of the homeserver, where the CS-API is reachable.
+ required: true
+ token:
+ type: str
+ description:
+ - Authentication token for the API call. If provided, O(user_id) and O(password) are not required.
+ user_id:
+ type: str
+ description:
+ - The user ID of the user.
+ password:
+ type: str
+ description:
+ - The password to log in with.
requirements:
- - matrix-client (Python library)
-'''
+ - matrix-client (Python library)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Send matrix notification with token
community.general.matrix:
msg_plain: "**hello world**"
@@ -76,10 +75,10 @@ EXAMPLES = '''
hs_url: "https://matrix.org"
user_id: "ansible_notification_bot"
password: "{{ matrix_auth_password }}"
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
import traceback
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
diff --git a/plugins/modules/mattermost.py b/plugins/modules/mattermost.py
index af8ce69600..ed046e6481 100644
--- a/plugins/modules/mattermost.py
+++ b/plugins/modules/mattermost.py
@@ -15,14 +15,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: mattermost
short_description: Send Mattermost notifications
description:
- - Sends notifications to U(http://your.mattermost.url) via the Incoming WebHook integration.
+ - Sends notifications to U(http://your.mattermost.url) using the Incoming WebHook integration.
author: "Benjamin Jolivot (@bjolivot)"
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -32,15 +32,13 @@ options:
url:
type: str
description:
- - Mattermost url (i.e. http://mattermost.yourcompany.com).
+ - Mattermost URL (for example V(http://mattermost.yourcompany.com)).
required: true
api_key:
type: str
description:
- - Mattermost webhook api key. Log into your mattermost site, go to
- Menu -> Integration -> Incoming Webhook -> Add Incoming Webhook.
- This will give you full URL. O(api_key) is the last part.
- http://mattermost.example.com/hooks/C(API_KEY)
+ - Mattermost webhook API key. Log into your Mattermost site, go to Menu -> Integration -> Incoming Webhook -> Add Incoming
+ Webhook. This will give you full URL. O(api_key) is the last part. U(http://mattermost.example.com/hooks/API_KEY).
required: true
text:
type: str
@@ -73,17 +71,17 @@ options:
type: str
description:
- Set a priority for the message.
- choices: [ important, urgent ]
+ choices: [important, urgent]
version_added: 10.0.0
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
default: true
type: bool
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Send notification message via Mattermost
community.general.mattermost:
url: http://mattermost.example.com
@@ -117,16 +115,16 @@ EXAMPLES = """
short: true
"""
-RETURN = '''
+RETURN = r"""
payload:
- description: Mattermost payload
- returned: success
- type: str
+ description: Mattermost payload.
+ returned: success
+ type: str
webhook_url:
- description: URL the webhook is sent to
- returned: success
- type: str
-'''
+ description: URL the webhook is sent to.
+ returned: success
+ type: str
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url
diff --git a/plugins/modules/maven_artifact.py b/plugins/modules/maven_artifact.py
index e239b4a164..a165c5a32a 100644
--- a/plugins/modules/maven_artifact.py
+++ b/plugins/modules/maven_artifact.py
@@ -11,171 +11,169 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: maven_artifact
short_description: Downloads an Artifact from a Maven Repository
description:
- - Downloads an artifact from a maven repository given the maven coordinates provided to the module.
- - Can retrieve snapshots or release versions of the artifact and will resolve the latest available
- version if one is not available.
+ - Downloads an artifact from a maven repository given the maven coordinates provided to the module.
+ - Can retrieve snapshots or release versions of the artifact and will resolve the latest available version if one is not
+ available.
author: "Chris Schmidt (@chrisisbeef)"
requirements:
- - lxml
- - boto if using a S3 repository (V(s3://...))
+ - lxml
+ - boto if using a S3 repository (V(s3://...))
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- group_id:
- type: str
- description:
- - The Maven groupId coordinate.
- required: true
- artifact_id:
- type: str
- description:
- - The maven artifactId coordinate.
- required: true
- version:
- type: str
- description:
- - The maven version coordinate.
- - Mutually exclusive with O(version_by_spec).
- version_by_spec:
- type: str
- description:
- - The maven dependency version ranges.
- - See supported version ranges on U(https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution)
- - The range type V((,1.0],[1.2,\)) and V((,1.1\),(1.1,\)) is not supported.
- - Mutually exclusive with O(version).
- version_added: '0.2.0'
- classifier:
- type: str
- description:
- - The maven classifier coordinate.
- default: ''
- extension:
- type: str
- description:
- - The maven type/extension coordinate.
- default: jar
- repository_url:
- type: str
- description:
- - The URL of the Maven Repository to download from.
- - Use V(s3://...) if the repository is hosted on Amazon S3.
- - Use V(file://...) if the repository is local.
- default: https://repo1.maven.org/maven2
- username:
- type: str
- description:
- - The username to authenticate as to the Maven Repository. Use AWS secret key of the repository is hosted on S3.
- aliases: [ "aws_secret_key" ]
- password:
- type: str
- description:
- - The password to authenticate with to the Maven Repository. Use AWS secret access key of the repository is hosted on S3.
- aliases: [ "aws_secret_access_key" ]
- headers:
- description:
- - Add custom HTTP headers to a request in hash/dict format.
- type: dict
- force_basic_auth:
- description:
- - httplib2, the library used by the uri module only sends authentication information when a webservice
- responds to an initial request with a 401 status. Since some basic auth services do not properly
- send a 401, logins will fail. This option forces the sending of the Basic authentication header
- upon initial request.
- default: false
- type: bool
- version_added: '0.2.0'
- dest:
- type: path
- description:
- - The path where the artifact should be written to.
- - If file mode or ownerships are specified and destination path already exists, they affect the downloaded file.
- required: true
- state:
- type: str
- description:
- - The desired state of the artifact.
- default: present
- choices: [present,absent]
- timeout:
- type: int
- description:
- - Specifies a timeout in seconds for the connection attempt.
- default: 10
- validate_certs:
- description:
- - If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists.
- type: bool
- default: true
- client_cert:
- description:
- - PEM formatted certificate chain file to be used for SSL client authentication.
- - This file can also include the key as well, and if the key is included, O(client_key) is not required.
- type: path
- version_added: '1.3.0'
- client_key:
- description:
- - PEM formatted file that contains your private key to be used for SSL client authentication.
- - If O(client_cert) contains both the certificate and key, this option is not required.
- type: path
- version_added: '1.3.0'
- keep_name:
- description:
- - If V(true), the downloaded artifact's name is preserved, i.e the version number remains part of it.
- - This option only has effect when O(dest) is a directory and O(version) is set to V(latest) or O(version_by_spec)
- is defined.
- type: bool
- default: false
- verify_checksum:
- type: str
- description:
- - If V(never), the MD5/SHA1 checksum will never be downloaded and verified.
- - If V(download), the MD5/SHA1 checksum will be downloaded and verified only after artifact download. This is the default.
- - If V(change), the MD5/SHA1 checksum will be downloaded and verified if the destination already exist,
- to verify if they are identical. This was the behaviour before 2.6. Since it downloads the checksum before (maybe)
- downloading the artifact, and since some repository software, when acting as a proxy/cache, return a 404 error
- if the artifact has not been cached yet, it may fail unexpectedly.
- If you still need it, you should consider using V(always) instead - if you deal with a checksum, it is better to
- use it to verify integrity after download.
- - V(always) combines V(download) and V(change).
- required: false
- default: 'download'
- choices: ['never', 'download', 'change', 'always']
- checksum_alg:
- type: str
- description:
- - If V(md5), checksums will use the MD5 algorithm. This is the default.
- - If V(sha1), checksums will use the SHA1 algorithm. This can be used on systems configured to use
- FIPS-compliant algorithms, since MD5 will be blocked on such systems.
- default: 'md5'
- choices: ['md5', 'sha1']
- version_added: 3.2.0
- unredirected_headers:
- type: list
- elements: str
- version_added: 5.2.0
- description:
- - A list of headers that should not be included in the redirection. This headers are sent to the C(fetch_url) function.
- - On ansible-core version 2.12 or later, the default of this option is V([Authorization, Cookie]).
- - Useful if the redirection URL does not need to have sensitive headers in the request.
- - Requires ansible-core version 2.12 or later.
- directory_mode:
- type: str
- description:
- - Filesystem permission mode applied recursively to O(dest) when it is a directory.
+ group_id:
+ type: str
+ description:
+ - The Maven groupId coordinate.
+ required: true
+ artifact_id:
+ type: str
+ description:
+ - The maven artifactId coordinate.
+ required: true
+ version:
+ type: str
+ description:
+ - The maven version coordinate.
+ - Mutually exclusive with O(version_by_spec).
+ version_by_spec:
+ type: str
+ description:
+ - The maven dependency version ranges.
+ - See supported version ranges on U(https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution).
+ - The range type V((,1.0],[1.2,\)) and V((,1.1\),(1.1,\)) is not supported.
+ - Mutually exclusive with O(version).
+ version_added: '0.2.0'
+ classifier:
+ type: str
+ description:
+ - The maven classifier coordinate.
+ default: ''
+ extension:
+ type: str
+ description:
+ - The maven type/extension coordinate.
+ default: jar
+ repository_url:
+ type: str
+ description:
+ - The URL of the Maven Repository to download from.
+ - Use V(s3://...) if the repository is hosted on Amazon S3.
+ - Use V(file://...) if the repository is local.
+ default: https://repo1.maven.org/maven2
+ username:
+ type: str
+ description:
+ - The username to authenticate as to the Maven Repository. Use AWS secret key of the repository is hosted on S3.
+ aliases: ["aws_secret_key"]
+ password:
+ type: str
+ description:
+ - The password to authenticate with to the Maven Repository. Use AWS secret access key of the repository is hosted on
+ S3.
+ aliases: ["aws_secret_access_key"]
+ headers:
+ description:
+ - Add custom HTTP headers to a request in hash/dict format.
+ type: dict
+ force_basic_auth:
+ description:
+ - C(httplib2), the library used by the URI module only sends authentication information when a webservice responds to an
+ initial request with a 401 status. Since some basic auth services do not properly send a 401, logins will fail. This
+ option forces the sending of the Basic authentication header upon initial request.
+ default: false
+ type: bool
+ version_added: '0.2.0'
+ dest:
+ type: path
+ description:
+ - The path where the artifact should be written to.
+ - If file mode or ownerships are specified and destination path already exists, they affect the downloaded file.
+ required: true
+ state:
+ type: str
+ description:
+ - The desired state of the artifact.
+ default: present
+ choices: [present, absent]
+ timeout:
+ type: int
+ description:
+ - Specifies a timeout in seconds for the connection attempt.
+ default: 10
+ validate_certs:
+ description:
+ - If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists.
+ type: bool
+ default: true
+ client_cert:
+ description:
+ - PEM formatted certificate chain file to be used for SSL client authentication.
+ - This file can also include the key as well, and if the key is included, O(client_key) is not required.
+ type: path
+ version_added: '1.3.0'
+ client_key:
+ description:
+ - PEM formatted file that contains your private key to be used for SSL client authentication.
+ - If O(client_cert) contains both the certificate and key, this option is not required.
+ type: path
+ version_added: '1.3.0'
+ keep_name:
+ description:
+ - If V(true), the downloaded artifact's name is preserved, in other words the version number remains part of it.
+ - This option only has effect when O(dest) is a directory and O(version) is set to V(latest) or O(version_by_spec) is
+ defined.
+ type: bool
+ default: false
+ verify_checksum:
+ type: str
+ description:
+ - If V(never), the MD5/SHA1 checksum will never be downloaded and verified.
+ - If V(download), the MD5/SHA1 checksum will be downloaded and verified only after artifact download. This is the default.
+ - If V(change), the MD5/SHA1 checksum will be downloaded and verified if the destination already exist, to verify if
+ they are identical. This was the behaviour before 2.6. Since it downloads the checksum before (maybe) downloading
+ the artifact, and since some repository software, when acting as a proxy/cache, return a 404 error if the artifact
+ has not been cached yet, it may fail unexpectedly. If you still need it, you should consider using V(always) instead
+ - if you deal with a checksum, it is better to use it to verify integrity after download.
+ - V(always) combines V(download) and V(change).
+ required: false
+ default: 'download'
+ choices: ['never', 'download', 'change', 'always']
+ checksum_alg:
+ type: str
+ description:
+ - If V(md5), checksums will use the MD5 algorithm. This is the default.
+ - If V(sha1), checksums will use the SHA1 algorithm. This can be used on systems configured to use FIPS-compliant algorithms,
+ since MD5 will be blocked on such systems.
+ default: 'md5'
+ choices: ['md5', 'sha1']
+ version_added: 3.2.0
+ unredirected_headers:
+ type: list
+ elements: str
+ version_added: 5.2.0
+ description:
+ - A list of headers that should not be included in the redirection. This headers are sent to the C(fetch_url) function.
+ - On ansible-core version 2.12 or later, the default of this option is V([Authorization, Cookie]).
+ - Useful if the redirection URL does not need to have sensitive headers in the request.
+ - Requires ansible-core version 2.12 or later.
+ directory_mode:
+ type: str
+ description:
+ - Filesystem permission mode applied recursively to O(dest) when it is a directory.
extends_documentation_fragment:
- - ansible.builtin.files
- - community.general.attributes
-'''
+ - ansible.builtin.files
+ - community.general.attributes
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Download the latest version of the JUnit framework artifact from Maven Central
community.general.maven_artifact:
group_id: junit
@@ -236,7 +234,7 @@ EXAMPLES = '''
artifact_id: junit
version_by_spec: "[3.8,4.0)"
dest: /tmp/
-'''
+"""
import hashlib
import os
diff --git a/plugins/modules/memset_dns_reload.py b/plugins/modules/memset_dns_reload.py
index 8cff51ade1..7781abbf76 100644
--- a/plugins/modules/memset_dns_reload.py
+++ b/plugins/modules/memset_dns_reload.py
@@ -8,53 +8,48 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: memset_dns_reload
author: "Simon Weald (@glitchcrab)"
short_description: Request reload of Memset's DNS infrastructure,
notes:
- - DNS reload requests are a best-effort service provided by Memset; these generally
- happen every 15 minutes by default, however you can request an immediate reload if
- later tasks rely on the records being created. An API key generated via the
- Memset customer control panel is required with the following minimum scope -
- C(dns.reload). If you wish to poll the job status to wait until the reload has
- completed, then C(job.status) is also required.
+ - DNS reload requests are a best-effort service provided by Memset; these generally happen every 15 minutes by default,
+ however you can request an immediate reload if later tasks rely on the records being created. An API key generated using
+ the Memset customer control panel is required with the following minimum scope - C(dns.reload). If you wish to poll the
+ job status to wait until the reload has completed, then C(job.status) is also required.
description:
- Request a reload of Memset's DNS infrastructure, and optionally poll until it finishes.
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- api_key:
- required: true
- type: str
- description:
- - The API key obtained from the Memset control panel.
- poll:
- default: false
- type: bool
- description:
- - Boolean value, if set will poll the reload job's status and return
- when the job has completed (unless the 30 second timeout is reached first).
- If the timeout is reached then the task will not be marked as failed, but
- stderr will indicate that the polling failed.
-'''
+ api_key:
+ required: true
+ type: str
+ description:
+ - The API key obtained from the Memset control panel.
+ poll:
+ default: false
+ type: bool
+ description:
+ - Boolean value, if set will poll the reload job's status and return when the job has completed (unless the 30 second
+ timeout is reached first). If the timeout is reached then the task will not be marked as failed, but stderr will indicate
+ that the polling failed.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Submit DNS reload and poll
community.general.memset_dns_reload:
api_key: 5eb86c9196ab03919abcf03857163741
poll: true
delegate_to: localhost
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
memset_api:
description: Raw response from the Memset API.
returned: always
@@ -85,7 +80,7 @@ memset_api:
returned: always
type: str
sample: "dns"
-'''
+"""
from time import sleep
diff --git a/plugins/modules/memset_memstore_info.py b/plugins/modules/memset_memstore_info.py
index 5dfd1f956a..e9f2699812 100644
--- a/plugins/modules/memset_memstore_info.py
+++ b/plugins/modules/memset_memstore_info.py
@@ -8,107 +8,104 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: memset_memstore_info
author: "Simon Weald (@glitchcrab)"
short_description: Retrieve Memstore product usage information
notes:
- - An API key generated via the Memset customer control panel is needed with the
- following minimum scope - C(memstore.usage).
+ - An API key generated using the Memset customer control panel is needed with the following minimum scope - C(memstore.usage).
description:
- - Retrieve Memstore product usage information.
+ - Retrieve Memstore product usage information.
extends_documentation_fragment:
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.attributes
+ - community.general.attributes.info_module
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- api_key:
- required: true
- type: str
- description:
- - The API key obtained from the Memset control panel.
- name:
- required: true
- type: str
- description:
- - The Memstore product name (that is, C(mstestyaa1)).
-'''
+ api_key:
+ required: true
+ type: str
+ description:
+ - The API key obtained from the Memset control panel.
+ name:
+ required: true
+ type: str
+ description:
+ - The Memstore product name (that is, V(mstestyaa1)).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get usage for mstestyaa1
community.general.memset_memstore_info:
name: mstestyaa1
api_key: 5eb86c9896ab03919abcf03857163741
delegate_to: localhost
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
memset_api:
- description: Info from the Memset API
+ description: Info from the Memset API.
returned: always
type: complex
contains:
cdn_bandwidth:
- description: Dictionary of CDN bandwidth facts
+ description: Dictionary of CDN bandwidth facts.
returned: always
type: complex
contains:
bytes_out:
- description: Outbound CDN bandwidth for the last 24 hours in bytes
+ description: Outbound CDN bandwidth for the last 24 hours in bytes.
returned: always
type: int
sample: 1000
requests:
- description: Number of requests in the last 24 hours
+ description: Number of requests in the last 24 hours.
returned: always
type: int
sample: 10
bytes_in:
- description: Inbound CDN bandwidth for the last 24 hours in bytes
+ description: Inbound CDN bandwidth for the last 24 hours in bytes.
returned: always
type: int
sample: 1000
containers:
- description: Number of containers
+ description: Number of containers.
returned: always
type: int
sample: 10
bytes:
- description: Space used in bytes
+ description: Space used in bytes.
returned: always
type: int
sample: 3860997965
objs:
- description: Number of objects
+ description: Number of objects.
returned: always
type: int
sample: 1000
bandwidth:
- description: Dictionary of CDN bandwidth facts
+ description: Dictionary of CDN bandwidth facts.
returned: always
type: complex
contains:
bytes_out:
- description: Outbound bandwidth for the last 24 hours in bytes
+ description: Outbound bandwidth for the last 24 hours in bytes.
returned: always
type: int
sample: 1000
requests:
- description: Number of requests in the last 24 hours
+ description: Number of requests in the last 24 hours.
returned: always
type: int
sample: 10
bytes_in:
- description: Inbound bandwidth for the last 24 hours in bytes
+ description: Inbound bandwidth for the last 24 hours in bytes.
returned: always
type: int
sample: 1000
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.memset import memset_api_call
diff --git a/plugins/modules/memset_server_info.py b/plugins/modules/memset_server_info.py
index 40862ae944..3c0829ce09 100644
--- a/plugins/modules/memset_server_info.py
+++ b/plugins/modules/memset_server_info.py
@@ -8,48 +8,45 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: memset_server_info
author: "Simon Weald (@glitchcrab)"
short_description: Retrieve server information
notes:
- - An API key generated via the Memset customer control panel is needed with the
- following minimum scope - C(server.info).
+ - An API key generated using the Memset customer control panel is needed with the following minimum scope - C(server.info).
description:
- - Retrieve server information.
+ - Retrieve server information.
extends_documentation_fragment:
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.attributes
+ - community.general.attributes.info_module
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- api_key:
- required: true
- type: str
- description:
- - The API key obtained from the Memset control panel.
- name:
- required: true
- type: str
- description:
- - The server product name (that is, C(testyaa1)).
-'''
+ api_key:
+ required: true
+ type: str
+ description:
+ - The API key obtained from the Memset control panel.
+ name:
+ required: true
+ type: str
+ description:
+ - The server product name (that is, C(testyaa1)).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get details for testyaa1
community.general.memset_server_info:
name: testyaa1
api_key: 5eb86c9896ab03919abcf03857163741
delegate_to: localhost
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
memset_api:
- description: Info from the Memset API
+ description: Info from the Memset API.
returned: always
type: complex
contains:
@@ -59,7 +56,7 @@ memset_api:
type: bool
sample: true
control_panel:
- description: Whether the server has a control panel (i.e. cPanel).
+ description: Whether the server has a control panel (for example cPanel).
returned: always
type: str
sample: 'cpanel'
@@ -103,7 +100,7 @@ memset_api:
}
}
firewall_type:
- description: The type of firewall the server has (i.e. self-managed, managed).
+ description: The type of firewall the server has (for example self-managed, managed).
returned: always
type: str
sample: 'managed'
@@ -113,7 +110,7 @@ memset_api:
type: str
sample: 'testyaa1.miniserver.com'
ignore_monitoring_off:
- description: When true, Memset won't remind the customer that monitoring is disabled.
+ description: When true, Memset does not remind the customer that monitoring is disabled.
returned: always
type: bool
sample: true
@@ -136,7 +133,7 @@ memset_api:
type: bool
sample: true
monitoring_level:
- description: The server's monitoring level (i.e. basic).
+ description: The server's monitoring level (for example V(basic)).
returned: always
type: str
sample: 'basic'
@@ -149,7 +146,7 @@ memset_api:
description: The network zone(s) the server is in.
returned: always
type: list
- sample: [ 'reading' ]
+ sample: ['reading']
nickname:
description: Customer-set nickname for the server.
returned: always
@@ -196,7 +193,7 @@ memset_api:
type: str
sample: 'GBP'
renewal_price_vat:
- description: VAT rate for renewal payments
+ description: VAT rate for renewal payments.
returned: always
type: str
sample: '20'
@@ -206,7 +203,7 @@ memset_api:
type: str
sample: '2013-04-10'
status:
- description: Current status of the server (i.e. live, onhold).
+ description: Current status of the server (for example live, onhold).
returned: always
type: str
sample: 'LIVE'
@@ -216,7 +213,7 @@ memset_api:
type: str
sample: 'managed'
type:
- description: What this server is (i.e. dedicated)
+ description: What this server is (for example V(dedicated)).
returned: always
type: str
sample: 'miniserver'
@@ -233,7 +230,7 @@ memset_api:
returned: always
type: str
sample: 'basic'
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.memset import memset_api_call
diff --git a/plugins/modules/memset_zone.py b/plugins/modules/memset_zone.py
index e405ad3e86..2c80503bec 100644
--- a/plugins/modules/memset_zone.py
+++ b/plugins/modules/memset_zone.py
@@ -8,60 +8,56 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: memset_zone
author: "Simon Weald (@glitchcrab)"
short_description: Creates and deletes Memset DNS zones
notes:
- - Zones can be thought of as a logical group of domains, all of which share the
- same DNS records (i.e. they point to the same IP). An API key generated via the
- Memset customer control panel is needed with the following minimum scope -
- C(dns.zone_create), C(dns.zone_delete), C(dns.zone_list).
+ - Zones can be thought of as a logical group of domains, all of which share the same DNS records (in other words they point
+ to the same IP). An API key generated using the Memset customer control panel is needed with the following minimum scope
+ - C(dns.zone_create), C(dns.zone_delete), C(dns.zone_list).
description:
- Manage DNS zones in a Memset account.
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- required: true
- description:
- - Indicates desired state of resource.
- type: str
- choices: [ absent, present ]
- api_key:
- required: true
- description:
- - The API key obtained from the Memset control panel.
- type: str
- name:
- required: true
- description:
- - The zone nickname; usually the same as the main domain. Ensure this
- value has at most 250 characters.
- type: str
- aliases: [ nickname ]
- ttl:
- description:
- - The default TTL for all records created in the zone. This must be a
- valid int from U(https://www.memset.com/apidocs/methods_dns.html#dns.zone_create).
- type: int
- default: 0
- choices: [ 0, 300, 600, 900, 1800, 3600, 7200, 10800, 21600, 43200, 86400 ]
- force:
- required: false
- default: false
- type: bool
- description:
- - Forces deletion of a zone and all zone domains/zone records it contains.
-'''
+ state:
+ required: true
+ description:
+ - Indicates desired state of resource.
+ type: str
+ choices: [absent, present]
+ api_key:
+ required: true
+ description:
+ - The API key obtained from the Memset control panel.
+ type: str
+ name:
+ required: true
+ description:
+ - The zone nickname; usually the same as the main domain. Ensure this value has at most 250 characters.
+ type: str
+ aliases: [nickname]
+ ttl:
+ description:
+ - The default TTL for all records created in the zone. This must be a valid int from U(https://www.memset.com/apidocs/methods_dns.html#dns.zone_create).
+ type: int
+ default: 0
+ choices: [0, 300, 600, 900, 1800, 3600, 7200, 10800, 21600, 43200, 86400]
+ force:
+ required: false
+ default: false
+ type: bool
+ description:
+ - Forces deletion of a zone and all zone domains/zone records it contains.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Create the zone 'test'
- name: Create zone
community.general.memset_zone:
@@ -79,40 +75,40 @@ EXAMPLES = '''
api_key: 5eb86c9196ab03919abcf03857163741
force: true
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
memset_api:
- description: Zone info from the Memset API
+ description: Zone info from the Memset API.
returned: when state == present
type: complex
contains:
domains:
- description: List of domains in this zone
+ description: List of domains in this zone.
returned: always
type: list
sample: []
id:
- description: Zone id
+ description: Zone ID.
returned: always
type: str
sample: "b0bb1ce851aeea6feeb2dc32fe83bf9c"
nickname:
- description: Zone name
+ description: Zone name.
returned: always
type: str
sample: "example.com"
records:
- description: List of DNS records for domains in this zone
+ description: List of DNS records for domains in this zone.
returned: always
type: list
sample: []
ttl:
- description: Default TTL for domains in this zone
+ description: Default TTL for domains in this zone.
returned: always
type: int
sample: 300
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.memset import check_zone
diff --git a/plugins/modules/memset_zone_domain.py b/plugins/modules/memset_zone_domain.py
index 7443e6c256..6e4dd27320 100644
--- a/plugins/modules/memset_zone_domain.py
+++ b/plugins/modules/memset_zone_domain.py
@@ -8,53 +8,50 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: memset_zone_domain
author: "Simon Weald (@glitchcrab)"
short_description: Create and delete domains in Memset DNS zones
notes:
- - Zone domains can be thought of as a collection of domains, all of which share the
- same DNS records (i.e. they point to the same IP). An API key generated via the
- Memset customer control panel is needed with the following minimum scope -
- C(dns.zone_domain_create), C(dns.zone_domain_delete), C(dns.zone_domain_list).
- - Currently this module can only create one domain at a time. Multiple domains should
- be created using C(loop).
+ - Zone domains can be thought of as a collection of domains, all of which share the same DNS records (in other words, they
+ point to the same IP). An API key generated using the Memset customer control panel is needed with the following minimum
+ scope - C(dns.zone_domain_create), C(dns.zone_domain_delete), C(dns.zone_domain_list).
+ - Currently this module can only create one domain at a time. Multiple domains should be created using C(loop).
description:
- Manage DNS zone domains in a Memset account.
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- default: present
- description:
- - Indicates desired state of resource.
- type: str
- choices: [ absent, present ]
- api_key:
- required: true
- description:
- - The API key obtained from the Memset control panel.
- type: str
- domain:
- required: true
- description:
- - The zone domain name. Ensure this value has at most 250 characters.
- type: str
- aliases: ['name']
- zone:
- required: true
- description:
- - The zone to add the domain to (this must already exist).
- type: str
-'''
+ state:
+ default: present
+ description:
+ - Indicates desired state of resource.
+ type: str
+ choices: [absent, present]
+ api_key:
+ required: true
+ description:
+ - The API key obtained from the Memset control panel.
+ type: str
+ domain:
+ required: true
+ description:
+ - The zone domain name. Ensure this value has at most 250 characters.
+ type: str
+ aliases: ['name']
+ zone:
+ required: true
+ description:
+ - The zone to add the domain to (this must already exist).
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Create the zone domain 'test.com'
- name: Create zone domain
community.general.memset_zone_domain:
@@ -63,25 +60,25 @@ EXAMPLES = '''
state: present
api_key: 5eb86c9196ab03919abcf03857163741
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
memset_api:
- description: Domain info from the Memset API
+ description: Domain info from the Memset API.
returned: when changed or state == present
type: complex
contains:
domain:
- description: Domain name
+ description: Domain name.
returned: always
type: str
sample: "example.com"
id:
- description: Domain ID
+ description: Domain ID.
returned: always
type: str
sample: "b0bb1ce851aeea6feeb2dc32fe83bf9c"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.memset import get_zone_id
@@ -256,7 +253,7 @@ def main():
retvals = create_or_delete_domain(args)
# we would need to populate the return values with the API's response
- # in several places so it's easier to do it at the end instead.
+ # in several places so it is easier to do it at the end instead.
if not retvals['failed']:
if args['state'] == 'present' and not module.check_mode:
payload = dict()
diff --git a/plugins/modules/memset_zone_record.py b/plugins/modules/memset_zone_record.py
index 349240b84e..7c16ee31eb 100644
--- a/plugins/modules/memset_zone_record.py
+++ b/plugins/modules/memset_zone_record.py
@@ -8,83 +8,79 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: memset_zone_record
author: "Simon Weald (@glitchcrab)"
short_description: Create and delete records in Memset DNS zones
notes:
- - Zones can be thought of as a logical group of domains, all of which share the
- same DNS records (i.e. they point to the same IP). An API key generated via the
- Memset customer control panel is needed with the following minimum scope -
- C(dns.zone_create), C(dns.zone_delete), C(dns.zone_list).
- - Currently this module can only create one DNS record at a time. Multiple records
- should be created using C(loop).
+ - Zones can be thought of as a logical group of domains, all of which share the same DNS records (in other words they point
+ to the same IP). An API key generated using the Memset customer control panel is needed with the following minimum scope
+ - C(dns.zone_create), C(dns.zone_delete), C(dns.zone_list).
+ - Currently this module can only create one DNS record at a time. Multiple records should be created using C(loop).
description:
- Manage DNS records in a Memset account.
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- default: present
- description:
- - Indicates desired state of resource.
- type: str
- choices: [ absent, present ]
- api_key:
- required: true
- description:
- - The API key obtained from the Memset control panel.
- type: str
- address:
- required: true
- description:
- - The address for this record (can be IP or text string depending on record type).
- type: str
- aliases: [ ip, data ]
- priority:
- description:
- - C(SRV) and C(TXT) record priority, in the range 0 > 999 (inclusive).
- type: int
- default: 0
- record:
- required: false
- description:
- - The subdomain to create.
- type: str
- default: ''
- type:
- required: true
- description:
- - The type of DNS record to create.
- choices: [ A, AAAA, CNAME, MX, NS, SRV, TXT ]
- type: str
- relative:
- type: bool
- default: false
- description:
- - If set then the current domain is added onto the address field for C(CNAME), C(MX), C(NS)
- and C(SRV)record types.
- ttl:
- description:
- - The record's TTL in seconds (will inherit zone's TTL if not explicitly set). This must be a
- valid int from U(https://www.memset.com/apidocs/methods_dns.html#dns.zone_record_create).
- default: 0
- choices: [ 0, 300, 600, 900, 1800, 3600, 7200, 10800, 21600, 43200, 86400 ]
- type: int
- zone:
- required: true
- description:
- - The name of the zone to which to add the record to.
- type: str
-'''
+ state:
+ default: present
+ description:
+ - Indicates desired state of resource.
+ type: str
+ choices: [absent, present]
+ api_key:
+ required: true
+ description:
+ - The API key obtained from the Memset control panel.
+ type: str
+ address:
+ required: true
+ description:
+ - The address for this record (can be IP or text string depending on record type).
+ type: str
+ aliases: [ip, data]
+ priority:
+ description:
+ - C(SRV) and C(TXT) record priority, in the range 0 > 999 (inclusive).
+ type: int
+ default: 0
+ record:
+ required: false
+ description:
+ - The subdomain to create.
+ type: str
+ default: ''
+ type:
+ required: true
+ description:
+ - The type of DNS record to create.
+ choices: [A, AAAA, CNAME, MX, NS, SRV, TXT]
+ type: str
+ relative:
+ type: bool
+ default: false
+ description:
+ - If set then the current domain is added onto the address field for C(CNAME), C(MX), C(NS) and C(SRV)record types.
+ ttl:
+ description:
+ - The record's TTL in seconds (will inherit zone's TTL if not explicitly set). This must be a valid int from
+ U(https://www.memset.com/apidocs/methods_dns.html#dns.zone_record_create).
+ default: 0
+ choices: [0, 300, 600, 900, 1800, 3600, 7200, 10800, 21600, 43200, 86400]
+ type: int
+ zone:
+ required: true
+ description:
+ - The name of the zone to which to add the record to.
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Create DNS record for www.domain.com
- name: Create DNS record
community.general.memset_zone_record:
@@ -118,11 +114,11 @@ EXAMPLES = '''
address: "{{ item.address }}"
delegate_to: localhost
with_items:
- - { 'zone': 'domain1.com', 'type': 'A', 'record': 'www', 'address': '1.2.3.4' }
- - { 'zone': 'domain2.com', 'type': 'A', 'record': 'mail', 'address': '4.3.2.1' }
-'''
+ - {'zone': 'domain1.com', 'type': 'A', 'record': 'www', 'address': '1.2.3.4'}
+ - {'zone': 'domain2.com', 'type': 'A', 'record': 'mail', 'address': '4.3.2.1'}
+"""
-RETURN = '''
+RETURN = r"""
memset_api:
description: Record info from the Memset API.
returned: when state == present
@@ -168,7 +164,7 @@ memset_api:
returned: always
type: str
sample: "b0bb1ce851aeea6feeb2dc32fe83bf9c"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.memset import get_zone_id
diff --git a/plugins/modules/mksysb.py b/plugins/modules/mksysb.py
index d1f49ca82e..d3c9abeac0 100644
--- a/plugins/modules/mksysb.py
+++ b/plugins/modules/mksysb.py
@@ -10,20 +10,19 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
author: Kairo Araujo (@kairoaraujo)
module: mksysb
short_description: Generates AIX mksysb rootvg backups
description:
-- This module manages a basic AIX mksysb (image) of rootvg.
+ - This module manages a basic AIX mksysb (image) of rootvg.
seealso:
-- name: C(mksysb) command manual page
- description: Manual page for the command.
- link: https://www.ibm.com/docs/en/aix/7.3?topic=m-mksysb-command
+ - name: C(mksysb) command manual page
+ description: Manual page for the command.
+ link: https://www.ibm.com/docs/en/aix/7.3?topic=m-mksysb-command
extends_documentation_fragment:
-- community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -32,63 +31,62 @@ attributes:
options:
backup_crypt_files:
description:
- - Backup encrypted files.
+ - Backup encrypted files.
type: bool
default: true
backup_dmapi_fs:
description:
- - Back up DMAPI filesystem files.
+ - Back up DMAPI filesystem files.
type: bool
default: true
create_map_files:
description:
- - Creates a new MAP files.
+ - Creates a new MAP files.
type: bool
default: false
exclude_files:
description:
- - Excludes files using C(/etc/rootvg.exclude).
+ - Excludes files using C(/etc/rootvg.exclude).
type: bool
default: false
exclude_wpar_files:
description:
- - Excludes WPAR files.
+ - Excludes WPAR files.
type: bool
default: false
extended_attrs:
description:
- - Backup extended attributes.
+ - Backup extended attributes.
type: bool
default: true
name:
type: str
description:
- - Backup name
+ - Backup name.
required: true
new_image_data:
description:
- - Creates a new file data.
+ - Creates a new file data.
type: bool
default: true
software_packing:
description:
- - Exclude files from packing option listed in C(/etc/exclude_packing.rootvg).
+ - Exclude files from packing option listed in C(/etc/exclude_packing.rootvg).
type: bool
default: false
storage_path:
type: str
description:
- - Storage path where the mksysb will stored.
+ - Storage path where the mksysb will stored.
required: true
use_snapshot:
description:
- - Creates backup using snapshots.
+ - Creates backup using snapshots.
type: bool
default: false
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Running a backup image mksysb
community.general.mksysb:
name: myserver
@@ -97,8 +95,7 @@ EXAMPLES = """
exclude_wpar_files: true
"""
-RETURN = """
----
+RETURN = r"""
changed:
description: Return changed for mksysb actions as true or false.
returned: always
diff --git a/plugins/modules/modprobe.py b/plugins/modules/modprobe.py
index 57e682245f..cff77e9558 100644
--- a/plugins/modules/modprobe.py
+++ b/plugins/modules/modprobe.py
@@ -8,58 +8,60 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: modprobe
short_description: Load or unload kernel modules
author:
- - David Stygstra (@stygstra)
- - Julien Dauphant (@jdauphant)
- - Matt Jeffery (@mattjeffery)
+ - David Stygstra (@stygstra)
+ - Julien Dauphant (@jdauphant)
+ - Matt Jeffery (@mattjeffery)
description:
- - Load or unload kernel modules.
+ - Load or unload kernel modules.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- type: str
- required: true
- description:
- - Name of kernel module to manage.
- state:
- type: str
- description:
- - Whether the module should be present or absent.
- choices: [ absent, present ]
- default: present
- params:
- type: str
- description:
- - Modules parameters.
- default: ''
- persistent:
- type: str
- choices: [ disabled, absent, present ]
- default: disabled
- description:
- - Persistency between reboots for configured module.
- - This option creates files in C(/etc/modules-load.d/) and C(/etc/modprobe.d/) that make your module configuration persistent during reboots.
- - If V(present), adds module name to C(/etc/modules-load.d/) and params to C(/etc/modprobe.d/) so the module will be loaded on next reboot.
- - If V(absent), will comment out module name from C(/etc/modules-load.d/) and comment out params from C(/etc/modprobe.d/) so the module will not be
- loaded on next reboot.
- - If V(disabled), will not touch anything and leave C(/etc/modules-load.d/) and C(/etc/modprobe.d/) as it is.
- - Note that it is usually a better idea to rely on the automatic module loading by PCI IDs, USB IDs, DMI IDs or similar triggers encoded in the
- kernel modules themselves instead of configuration like this.
- - In fact, most modern kernel modules are prepared for automatic loading already.
- - "B(Note:) This option works only with distributions that use C(systemd) when set to values other than V(disabled)."
-'''
+ name:
+ type: str
+ required: true
+ description:
+ - Name of kernel module to manage.
+ state:
+ type: str
+ description:
+ - Whether the module should be present or absent.
+ choices: [absent, present]
+ default: present
+ params:
+ type: str
+ description:
+ - Modules parameters.
+ default: ''
+ persistent:
+ type: str
+ choices: [disabled, absent, present]
+ default: disabled
+ version_added: 7.0.0
+ description:
+ - Persistency between reboots for configured module.
+ - This option creates files in C(/etc/modules-load.d/) and C(/etc/modprobe.d/) that make your module configuration persistent
+ during reboots.
+ - If V(present), adds module name to C(/etc/modules-load.d/) and params to C(/etc/modprobe.d/) so the module will be
+ loaded on next reboot.
+ - If V(absent), will comment out module name from C(/etc/modules-load.d/) and comment out params from C(/etc/modprobe.d/)
+ so the module will not be loaded on next reboot.
+ - If V(disabled), will not touch anything and leave C(/etc/modules-load.d/) and C(/etc/modprobe.d/) as it is.
+ - Note that it is usually a better idea to rely on the automatic module loading by PCI IDs, USB IDs, DMI IDs or similar
+ triggers encoded in the kernel modules themselves instead of configuration like this.
+ - In fact, most modern kernel modules are prepared for automatic loading already.
+ - B(Note:) This option works only with distributions that use C(systemd) when set to values other than V(disabled).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add the 802.1q module
community.general.modprobe:
name: 8021q
@@ -77,7 +79,7 @@ EXAMPLES = '''
state: present
params: 'numdummies=2'
persistent: present
-'''
+"""
import os.path
import platform
diff --git a/plugins/modules/monit.py b/plugins/modules/monit.py
index 5475ab1e52..65b6c606e9 100644
--- a/plugins/modules/monit.py
+++ b/plugins/modules/monit.py
@@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: monit
-short_description: Manage the state of a program monitored via Monit
+short_description: Manage the state of a program monitored using Monit
description:
- - Manage the state of a program monitored via Monit.
+ - Manage the state of a program monitored using Monit.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -32,26 +31,25 @@ options:
description:
- The state of service.
required: true
- choices: [ "present", "started", "stopped", "restarted", "monitored", "unmonitored", "reloaded" ]
+ choices: ["present", "started", "stopped", "restarted", "monitored", "unmonitored", "reloaded"]
type: str
timeout:
description:
- - If there are pending actions for the service monitored by monit, then Ansible will check
- for up to this many seconds to verify the requested action has been performed.
- Ansible will sleep for five seconds between each check.
+ - If there are pending actions for the service monitored by monit, then Ansible will check for up to this many seconds
+ to verify the requested action has been performed. Ansible will sleep for five seconds between each check.
default: 300
type: int
author:
- - Darryl Stoflet (@dstoflet)
- - Simon Kelly (@snopoke)
-'''
+ - Darryl Stoflet (@dstoflet)
+ - Simon Kelly (@snopoke)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Manage the state of program httpd to be in started state
community.general.monit:
name: httpd
state: started
-'''
+"""
import time
import re
@@ -218,7 +216,7 @@ class Monit(object):
return running_status
def wait_for_monit_to_stop_pending(self, current_status=None):
- """Fails this run if there is no status or it's pending/initializing for timeout"""
+ """Fails this run if there is no status or it is pending/initializing for timeout"""
timeout_time = time.time() + self.timeout
if not current_status:
diff --git a/plugins/modules/mqtt.py b/plugins/modules/mqtt.py
index f8d64e6a00..9c610d02c7 100644
--- a/plugins/modules/mqtt.py
+++ b/plugins/modules/mqtt.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: mqtt
short_description: Publish a message on an MQTT topic for the IoT
description:
@@ -26,12 +25,12 @@ options:
server:
type: str
description:
- - MQTT broker address/name
+ - MQTT broker address/name.
default: localhost
port:
type: int
description:
- - MQTT broker port number
+ - MQTT broker port number.
default: 1883
username:
type: str
@@ -44,76 +43,68 @@ options:
client_id:
type: str
description:
- - MQTT client identifier
+ - MQTT client identifier.
- If not specified, a value C(hostname + pid) will be used.
topic:
type: str
description:
- - MQTT topic name
+ - MQTT topic name.
required: true
payload:
type: str
description:
- - Payload. The special string V("None") may be used to send a NULL
- (that is, empty) payload which is useful to simply notify with the O(topic)
- or to clear previously retained messages.
+ - Payload. The special string V("None") may be used to send a NULL (that is, empty) payload which is useful to simply
+ notify with the O(topic) or to clear previously retained messages.
required: true
qos:
type: str
description:
- - QoS (Quality of Service)
+ - QoS (Quality of Service).
default: "0"
- choices: [ "0", "1", "2" ]
+ choices: ["0", "1", "2"]
retain:
description:
- - Setting this flag causes the broker to retain (i.e. keep) the message so that
- applications that subsequently subscribe to the topic can received the last
- retained message immediately.
+ - Setting this flag causes the broker to retain (in other words keep) the message so that applications that subsequently
+ subscribe to the topic can received the last retained message immediately.
type: bool
default: false
ca_cert:
type: path
description:
- - The path to the Certificate Authority certificate files that are to be
- treated as trusted by this client. If this is the only option given
- then the client will operate in a similar manner to a web browser. That
- is to say it will require the broker to have a certificate signed by the
- Certificate Authorities in ca_certs and will communicate using TLS v1,
- but will not attempt any form of authentication. This provides basic
- network encryption but may not be sufficient depending on how the broker
- is configured.
- aliases: [ ca_certs ]
+ - The path to the Certificate Authority certificate files that are to be treated as trusted by this client. If this
+ is the only option given then the client will operate in a similar manner to a web browser. That is to say it will
+ require the broker to have a certificate signed by the Certificate Authorities in ca_certs and will communicate using
+ TLS v1, but will not attempt any form of authentication. This provides basic network encryption but may not be sufficient
+ depending on how the broker is configured.
+ aliases: [ca_certs]
client_cert:
type: path
description:
- - The path pointing to the PEM encoded client certificate. If this is not
- None it will be used as client information for TLS based
- authentication. Support for this feature is broker dependent.
- aliases: [ certfile ]
+ - The path pointing to the PEM encoded client certificate. If this is not None it will be used as client information
+ for TLS based authentication. Support for this feature is broker dependent.
+ aliases: [certfile]
client_key:
type: path
description:
- - The path pointing to the PEM encoded client private key. If this is not
- None it will be used as client information for TLS based
- authentication. Support for this feature is broker dependent.
- aliases: [ keyfile ]
+ - The path pointing to the PEM encoded client private key. If this is not None it will be used as client information
+ for TLS based authentication. Support for this feature is broker dependent.
+ aliases: [keyfile]
tls_version:
description:
- Specifies the version of the SSL/TLS protocol to be used.
- - By default (if the python version supports it) the highest TLS version is
- detected. If unavailable, TLS v1 is used.
+ - By default (if the python version supports it) the highest TLS version is detected. If unavailable, TLS v1 is used.
type: str
choices:
- tlsv1.1
- tlsv1.2
-requirements: [ mosquitto ]
+requirements: [mosquitto]
notes:
- - This module requires a connection to an MQTT broker such as Mosquitto
- U(http://mosquitto.org) and the I(Paho) C(mqtt) Python client (U(https://pypi.org/project/paho-mqtt/)).
+ - This module requires a connection to an MQTT broker such as Mosquitto U(http://mosquitto.org) and the I(Paho) C(mqtt)
+ Python client (U(https://pypi.org/project/paho-mqtt/)).
author: "Jan-Piet Mens (@jpmens)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Publish a message on an MQTT topic
community.general.mqtt:
topic: 'service/ansible/{{ ansible_hostname }}'
@@ -122,7 +113,7 @@ EXAMPLES = '''
retain: false
client_id: ans001
delegate_to: localhost
-'''
+"""
# ===========================================
# MQTT module support methods.
diff --git a/plugins/modules/mssql_db.py b/plugins/modules/mssql_db.py
index a85f721fca..e1fc222e71 100644
--- a/plugins/modules/mssql_db.py
+++ b/plugins/modules/mssql_db.py
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: mssql_db
short_description: Add or remove MSSQL databases from a remote host
description:
@@ -26,56 +25,55 @@ attributes:
options:
name:
description:
- - name of the database to add or remove
+ - Name of the database to add or remove.
required: true
- aliases: [ db ]
+ aliases: [db]
type: str
login_user:
description:
- - The username used to authenticate with
+ - The username used to authenticate with.
type: str
default: ''
login_password:
description:
- - The password used to authenticate with
+ - The password used to authenticate with.
type: str
default: ''
login_host:
description:
- - Host running the database
+ - Host running the database.
type: str
required: true
login_port:
description:
- - Port of the MSSQL server. Requires login_host be defined as other than localhost if login_port is used
+ - Port of the MSSQL server. Requires login_host be defined as other than localhost if login_port is used.
default: '1433'
type: str
state:
description:
- - The database state
+ - The database state.
default: present
- choices: [ "present", "absent", "import" ]
+ choices: ["present", "absent", "import"]
type: str
target:
description:
- - Location, on the remote host, of the dump file to read from or write to. Uncompressed SQL
- files (C(.sql)) files are supported.
+ - Location, on the remote host, of the dump file to read from or write to. Uncompressed SQL files (C(.sql)) files are
+ supported.
type: str
autocommit:
description:
- - Automatically commit the change only if the import succeed. Sometimes it is necessary to use autocommit=true, since some content can't be changed
- within a transaction.
+ - Automatically commit the change only if the import succeed. Sometimes it is necessary to use autocommit=true, since
+ some content can not be changed within a transaction.
type: bool
default: false
notes:
- - Requires the pymssql Python package on the remote host. For Ubuntu, this
- is as easy as pip install pymssql (See M(ansible.builtin.pip).)
+ - Requires the pymssql Python package on the remote host. For Ubuntu, this is as easy as pip install pymssql (See M(ansible.builtin.pip)).
requirements:
- - pymssql
+ - pymssql
author: Vedit Firat Arig (@vedit)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a new database with name 'jackdata'
community.general.mssql_db:
name: jackdata
@@ -92,11 +90,11 @@ EXAMPLES = '''
name: my_db
state: import
target: /tmp/dump.sql
-'''
+"""
-RETURN = '''
+RETURN = r"""
#
-'''
+"""
import os
import traceback
diff --git a/plugins/modules/mssql_script.py b/plugins/modules/mssql_script.py
index b1713092c8..872b2ee13d 100644
--- a/plugins/modules/mssql_script.py
+++ b/plugins/modules/mssql_script.py
@@ -7,8 +7,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: mssql_script
short_description: Execute SQL scripts on a MSSQL database
@@ -17,77 +16,75 @@ version_added: "4.0.0"
description:
- Execute SQL scripts on a MSSQL database.
-
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: partial
- details:
- - The script will not be executed in check mode.
- diff_mode:
- support: none
+ check_mode:
+ support: partial
+ details:
+ - The script will not be executed in check mode.
+ diff_mode:
+ support: none
options:
- name:
- description: Database to run script against.
- aliases: [ db ]
- default: ''
- type: str
- login_user:
- description: The username used to authenticate with.
- type: str
- login_password:
- description: The password used to authenticate with.
- type: str
- login_host:
- description: Host running the database.
- type: str
- required: true
- login_port:
- description: Port of the MSSQL server. Requires O(login_host) be defined as well.
- default: 1433
- type: int
- script:
- description:
- - The SQL script to be executed.
- - Script can contain multiple SQL statements. Multiple Batches can be separated by V(GO) command.
- - Each batch must return at least one result set.
- required: true
- type: str
- transaction:
- description:
- - If transactional mode is requested, start a transaction and commit the change only if the script succeed.
- Otherwise, rollback the transaction.
- - If transactional mode is not requested (default), automatically commit the change.
- type: bool
- default: false
- version_added: 8.4.0
- output:
- description:
- - With V(default) each row will be returned as a list of values. See RV(query_results).
- - Output format V(dict) will return dictionary with the column names as keys. See RV(query_results_dict).
- - V(dict) requires named columns to be returned by each query otherwise an error is thrown.
- choices: [ "dict", "default" ]
- default: 'default'
- type: str
- params:
- description: |
- Parameters passed to the script as SQL parameters.
- (Query V('SELECT %(name\)s"') with V(example: '{"name": "John Doe"}).)'
- type: dict
+ name:
+ description: Database to run script against.
+ aliases: [db]
+ default: ''
+ type: str
+ login_user:
+ description: The username used to authenticate with.
+ type: str
+ login_password:
+ description: The password used to authenticate with.
+ type: str
+ login_host:
+ description: Host running the database.
+ type: str
+ required: true
+ login_port:
+ description: Port of the MSSQL server. Requires O(login_host) be defined as well.
+ default: 1433
+ type: int
+ script:
+ description:
+ - The SQL script to be executed.
+ - Script can contain multiple SQL statements. Multiple Batches can be separated by V(GO) command.
+ - Each batch must return at least one result set.
+ required: true
+ type: str
+ transaction:
+ description:
+ - If transactional mode is requested, start a transaction and commit the change only if the script succeed. Otherwise,
+ rollback the transaction.
+ - If transactional mode is not requested (default), automatically commit the change.
+ type: bool
+ default: false
+ version_added: 8.4.0
+ output:
+ description:
+ - With V(default) each row will be returned as a list of values. See RV(query_results).
+ - Output format V(dict) will return dictionary with the column names as keys. See RV(query_results_dict).
+ - V(dict) requires named columns to be returned by each query otherwise an error is thrown.
+ choices: ["dict", "default"]
+ default: 'default'
+ type: str
+ params:
+ description: |-
+ Parameters passed to the script as SQL parameters.
+ (Query V('SELECT %(name\)s"') with V(example: '{"name": "John Doe"}).)'.
+ type: dict
notes:
- - Requires the pymssql Python package on the remote host. For Ubuntu, this
- is as easy as C(pip install pymssql) (See M(ansible.builtin.pip).)
+ - Requires the pymssql Python package on the remote host. For Ubuntu, this is as easy as C(pip install pymssql) (See M(ansible.builtin.pip)).
requirements:
- - pymssql
+ - pymssql
author:
- - Kris Budde (@kbudde)
-'''
+ - Kris Budde (@kbudde)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Check DB connection
community.general.mssql_script:
login_user: "{{ mssql_login_user }}"
@@ -140,11 +137,11 @@ EXAMPLES = r'''
register: result_batches
- assert:
that:
- - result_batches.query_results | length == 2 # two batch results
- - result_batches.query_results[0] | length == 2 # two selects in first batch
- - result_batches.query_results[0][0] | length == 1 # one row in first select
- - result_batches.query_results[0][0][0] | length == 1 # one column in first row
- - result_batches.query_results[0][0][0][0] == 'Batch 0 - Select 0' # each row contains a list of values.
+ - result_batches.query_results | length == 2 # two batch results
+ - result_batches.query_results[0] | length == 2 # two selects in first batch
+ - result_batches.query_results[0][0] | length == 1 # one row in first select
+ - result_batches.query_results[0][0][0] | length == 1 # one column in first row
+ - result_batches.query_results[0][0][0][0] == 'Batch 0 - Select 0' # each row contains a list of values.
- name: two batches with dict output
community.general.mssql_script:
@@ -161,68 +158,68 @@ EXAMPLES = r'''
register: result_batches_dict
- assert:
that:
- - result_batches_dict.query_results_dict | length == 2 # two batch results
- - result_batches_dict.query_results_dict[0] | length == 2 # two selects in first batch
- - result_batches_dict.query_results_dict[0][0] | length == 1 # one row in first select
- - result_batches_dict.query_results_dict[0][0][0]['b0s0'] == 'Batch 0 - Select 0' # column 'b0s0' of first row
-'''
+ - result_batches_dict.query_results_dict | length == 2 # two batch results
+ - result_batches_dict.query_results_dict[0] | length == 2 # two selects in first batch
+ - result_batches_dict.query_results_dict[0][0] | length == 1 # one row in first select
+ - result_batches_dict.query_results_dict[0][0][0]['b0s0'] == 'Batch 0 - Select 0' # column 'b0s0' of first row
+"""
-RETURN = r'''
+RETURN = r"""
query_results:
- description: List of batches (queries separated by V(GO) keyword).
- type: list
- elements: list
- returned: success and O(output=default)
- sample: [[[["Batch 0 - Select 0"]], [["Batch 0 - Select 1"]]], [[["Batch 1 - Select 0"]]]]
- contains:
- queries:
- description:
- - List of result sets of each query.
- - If a query returns no results, the results of this and all the following queries will not be included in the output.
- - Use the V(GO) keyword in O(script) to separate queries.
- type: list
- elements: list
- contains:
- rows:
- description: List of rows returned by query.
- type: list
- elements: list
- contains:
- column_value:
- description:
- - List of column values.
- - Any non-standard JSON type is converted to string.
- type: list
- example: ["Batch 0 - Select 0"]
- returned: success, if output is default
+ description: List of batches (queries separated by V(GO) keyword).
+ type: list
+ elements: list
+ returned: success and O(output=default)
+ sample: [[[["Batch 0 - Select 0"]], [["Batch 0 - Select 1"]]], [[["Batch 1 - Select 0"]]]]
+ contains:
+ queries:
+ description:
+ - List of result sets of each query.
+ - If a query returns no results, the results of this and all the following queries will not be included in the output.
+ - Use the V(GO) keyword in O(script) to separate queries.
+ type: list
+ elements: list
+ contains:
+ rows:
+ description: List of rows returned by query.
+ type: list
+ elements: list
+ contains:
+ column_value:
+ description:
+ - List of column values.
+ - Any non-standard JSON type is converted to string.
+ type: list
+ example: ["Batch 0 - Select 0"]
+ returned: success, if output is default
query_results_dict:
- description: List of batches (queries separated by V(GO) keyword).
- type: list
- elements: list
- returned: success and O(output=dict)
- sample: [[[["Batch 0 - Select 0"]], [["Batch 0 - Select 1"]]], [[["Batch 1 - Select 0"]]]]
- contains:
- queries:
- description:
- - List of result sets of each query.
- - If a query returns no results, the results of this and all the following queries will not be included in the output.
- Use 'GO' keyword to separate queries.
- type: list
- elements: list
- contains:
- rows:
- description: List of rows returned by query.
- type: list
- elements: list
- contains:
- column_dict:
- description:
- - Dictionary of column names and values.
- - Any non-standard JSON type is converted to string.
- type: dict
- example: {"col_name": "Batch 0 - Select 0"}
- returned: success, if output is dict
-'''
+ description: List of batches (queries separated by V(GO) keyword).
+ type: list
+ elements: list
+ returned: success and O(output=dict)
+ sample: [[[["Batch 0 - Select 0"]], [["Batch 0 - Select 1"]]], [[["Batch 1 - Select 0"]]]]
+ contains:
+ queries:
+ description:
+ - List of result sets of each query.
+ - If a query returns no results, the results of this and all the following queries will not be included in the output.
+ Use V(GO) keyword to separate queries.
+ type: list
+ elements: list
+ contains:
+ rows:
+ description: List of rows returned by query.
+ type: list
+ elements: list
+ contains:
+ column_dict:
+ description:
+ - Dictionary of column names and values.
+ - Any non-standard JSON type is converted to string.
+ type: dict
+ example: {"col_name": "Batch 0 - Select 0"}
+ returned: success, if output is dict
+"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
import traceback
diff --git a/plugins/modules/nagios.py b/plugins/modules/nagios.py
index 0f1f0b7c50..3c12b85c0b 100644
--- a/plugins/modules/nagios.py
+++ b/plugins/modules/nagios.py
@@ -14,20 +14,19 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: nagios
short_description: Perform common tasks in Nagios related to downtime and notifications
description:
- - "The C(nagios) module has two basic functions: scheduling downtime and toggling alerts for services or hosts."
+ - 'The C(nagios) module has two basic functions: scheduling downtime and toggling alerts for services or hosts.'
- The C(nagios) module is not idempotent.
- - All actions require the O(host) parameter to be given explicitly. In playbooks you can use the C({{inventory_hostname}}) variable to refer
- to the host the playbook is currently running on.
- - You can specify multiple services at once by separating them with commas, .e.g. O(services=httpd,nfs,puppet).
- - When specifying what service to handle there is a special service value, O(host), which will handle alerts/downtime/acknowledge for the I(host itself),
- for example O(services=host). This keyword may not be given with other services at the same time.
- B(Setting alerts/downtime/acknowledge for a host does not affect alerts/downtime/acknowledge for any of the services running on it.)
- To schedule downtime for all services on particular host use keyword "all", for example O(services=all).
+ - All actions require the O(host) parameter to be given explicitly. In playbooks you can use the C({{inventory_hostname}})
+ variable to refer to the host the playbook is currently running on.
+ - You can specify multiple services at once by separating them with commas, for example O(services=httpd,nfs,puppet).
+ - When specifying what service to handle there is a special service value, O(host), which will handle alerts/downtime/acknowledge
+ for the I(host itself), for example O(services=host). This keyword may not be given with other services at the same time.
+ B(Setting alerts/downtime/acknowledge for a host does not affect alerts/downtime/acknowledge for any of the services running
+ on it.) To schedule downtime for all services on particular host use keyword "all", for example O(services=all).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -41,9 +40,8 @@ options:
- Action to take.
- The V(acknowledge) and V(forced_check) actions were added in community.general 1.2.0.
required: true
- choices: [ "downtime", "delete_downtime", "enable_alerts", "disable_alerts", "silence", "unsilence",
- "silence_nagios", "unsilence_nagios", "command", "servicegroup_service_downtime",
- "servicegroup_host_downtime", "acknowledge", "forced_check" ]
+ choices: ["downtime", "delete_downtime", "enable_alerts", "disable_alerts", "silence", "unsilence", "silence_nagios",
+ "unsilence_nagios", "command", "servicegroup_service_downtime", "servicegroup_host_downtime", "acknowledge", "forced_check"]
type: str
host:
description:
@@ -51,18 +49,16 @@ options:
type: str
cmdfile:
description:
- - Path to the nagios I(command file) (FIFO pipe).
- Only required if auto-detection fails.
+ - Path to the nagios I(command file) (FIFO pipe). Only required if auto-detection fails.
type: str
author:
description:
- - Author to leave downtime comments as.
- Only used when O(action) is V(downtime) or V(acknowledge).
+ - Author to leave downtime comments as. Only used when O(action) is V(downtime) or V(acknowledge).
type: str
default: Ansible
comment:
description:
- - Comment when O(action) is V(downtime) or V(acknowledge).
+ - Comment when O(action) is V(downtime) or V(acknowledge).
type: str
default: Scheduling downtime
start:
@@ -79,8 +75,8 @@ options:
services:
description:
- What to manage downtime/alerts for. Separate multiple services with commas.
- - "B(Required) option when O(action) is one of: V(downtime), V(acknowledge), V(forced_check), V(enable_alerts), V(disable_alerts)."
- aliases: [ "service" ]
+ - 'B(Required) option when O(action) is one of: V(downtime), V(acknowledge), V(forced_check), V(enable_alerts), V(disable_alerts).'
+ aliases: ["service"]
type: str
servicegroup:
description:
@@ -94,9 +90,9 @@ options:
type: str
author: "Tim Bielawa (@tbielawa)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Set 30 minutes of apache downtime
community.general.nagios:
action: downtime
@@ -245,7 +241,7 @@ EXAMPLES = '''
community.general.nagios:
action: command
command: DISABLE_FAILURE_PREDICTION
-'''
+"""
import time
import os.path
diff --git a/plugins/modules/netcup_dns.py b/plugins/modules/netcup_dns.py
index cba70c0fa3..900eb01e0d 100644
--- a/plugins/modules/netcup_dns.py
+++ b/plugins/modules/netcup_dns.py
@@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: netcup_dns
notes: []
short_description: Manage Netcup DNS records
description:
- - "Manages DNS records via the Netcup API, see the docs U(https://ccp.netcup.net/run/webservice/servers/endpoint.php)."
+ - Manages DNS records using the Netcup API, see the docs U(https://ccp.netcup.net/run/webservice/servers/endpoint.php).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -26,17 +25,17 @@ attributes:
options:
api_key:
description:
- - "API key for authentication, must be obtained via the netcup CCP (U(https://ccp.netcup.net))."
+ - API key for authentication, must be obtained using the netcup CCP (U(https://ccp.netcup.net)).
required: true
type: str
api_password:
description:
- - "API password for authentication, must be obtained via the netcup CCP (U(https://ccp.netcup.net))."
+ - API password for authentication, must be obtained using the netcup CCP (U(https://ccp.netcup.net)).
required: true
type: str
customer_id:
description:
- - Netcup customer id.
+ - Netcup customer ID.
required: true
type: int
domain:
@@ -48,7 +47,7 @@ options:
description:
- Record to add or delete, supports wildcard (V(*)). Default is V(@) (that is, the zone name).
default: "@"
- aliases: [ name ]
+ aliases: [name]
type: str
type:
description:
@@ -80,7 +79,7 @@ options:
- Whether the record should exist or not.
required: false
default: present
- choices: [ 'present', 'absent' ]
+ choices: ['present', 'absent']
type: str
timeout:
description:
@@ -91,10 +90,9 @@ options:
requirements:
- "nc-dnsapi >= 0.1.3"
author: "Nicolai Buchwitz (@nbuchwitz)"
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a record of type A
community.general.netcup_dns:
api_key: "..."
@@ -156,41 +154,41 @@ EXAMPLES = '''
type: "A"
value: "127.0.0.1"
timeout: 30
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
records:
- description: list containing all records
- returned: success
- type: complex
- contains:
- name:
- description: the record name
- returned: success
- type: str
- sample: fancy-hostname
- type:
- description: the record type
- returned: success
- type: str
- sample: A
- value:
- description: the record destination
- returned: success
- type: str
- sample: 127.0.0.1
- priority:
- description: the record priority (only relevant if type=MX)
- returned: success
- type: int
- sample: 0
- id:
- description: internal id of the record
- returned: success
- type: int
- sample: 12345
-'''
+ description: List containing all records.
+ returned: success
+ type: list
+ elements: dict
+ contains:
+ name:
+ description: The record name.
+ returned: success
+ type: str
+ sample: fancy-hostname
+ type:
+ description: The record type.
+ returned: success
+ type: str
+ sample: A
+ value:
+ description: The record destination.
+ returned: success
+ type: str
+ sample: 127.0.0.1
+ priority:
+ description: The record priority (only relevant if RV(records[].type=MX)).
+ returned: success
+ type: int
+ sample: 0
+ id:
+ description: Internal ID of the record.
+ returned: success
+ type: int
+ sample: 12345
+"""
import traceback
diff --git a/plugins/modules/newrelic_deployment.py b/plugins/modules/newrelic_deployment.py
index e5a1160822..b9ce8af586 100644
--- a/plugins/modules/newrelic_deployment.py
+++ b/plugins/modules/newrelic_deployment.py
@@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: newrelic_deployment
author: "Matt Coddington (@mcodd)"
short_description: Notify New Relic about app deployments
description:
- - Notify New Relic about app deployments (see https://docs.newrelic.com/docs/apm/new-relic-apm/maintenance/record-monitor-deployments/)
+ - Notify New Relic about app deployments (see U(https://docs.newrelic.com/docs/apm/new-relic-apm/maintenance/record-monitor-deployments/)).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -44,49 +43,49 @@ options:
changelog:
type: str
description:
- - A list of changes for this deployment
+ - A list of changes for this deployment.
required: false
description:
type: str
description:
- - Text annotation for the deployment - notes for you
+ - Text annotation for the deployment - notes for you.
required: false
revision:
type: str
description:
- - A revision number (e.g., git commit SHA)
+ - A revision number (for example, git commit SHA).
required: true
user:
type: str
description:
- - The name of the user/process that triggered this deployment
+ - The name of the user/process that triggered this deployment.
required: false
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
required: false
default: true
type: bool
app_name_exact_match:
type: bool
description:
- - If this flag is set to V(true) then the application ID lookup by name would only work for an exact match.
- If set to V(false) it returns the first result.
+ - If this flag is set to V(true) then the application ID lookup by name would only work for an exact match. If set to
+ V(false) it returns the first result.
required: false
default: false
version_added: 7.5.0
requirements: []
-'''
+"""
-EXAMPLES = '''
-- name: Notify New Relic about an app deployment
+EXAMPLES = r"""
+- name: Notify New Relic about an app deployment
community.general.newrelic_deployment:
token: AAAAAA
app_name: myapp
user: ansible deployment
revision: '1.0'
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url
diff --git a/plugins/modules/nexmo.py b/plugins/modules/nexmo.py
index 39f127f98c..ef6502532d 100644
--- a/plugins/modules/nexmo.py
+++ b/plugins/modules/nexmo.py
@@ -9,11 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: nexmo
-short_description: Send a SMS via nexmo
+short_description: Send a SMS using nexmo
description:
- - Send a SMS message via nexmo
+ - Send a SMS message using nexmo.
author: "Matt Martz (@sivel)"
attributes:
check_mode:
@@ -24,42 +24,41 @@ options:
api_key:
type: str
description:
- - Nexmo API Key
+ - Nexmo API Key.
required: true
api_secret:
type: str
description:
- - Nexmo API Secret
+ - Nexmo API Secret.
required: true
src:
type: int
description:
- - Nexmo Number to send from
+ - Nexmo Number to send from.
required: true
dest:
type: list
elements: int
description:
- - Phone number(s) to send SMS message to
+ - Phone number(s) to send SMS message to.
required: true
msg:
type: str
description:
- - Message to text to send. Messages longer than 160 characters will be
- split into multiple messages
+ - Message to text to send. Messages longer than 160 characters will be split into multiple messages.
required: true
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
type: bool
default: true
extends_documentation_fragment:
- ansible.builtin.url
- community.general.attributes
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Send notification message via Nexmo
community.general.nexmo:
api_key: 640c8a53
diff --git a/plugins/modules/nginx_status_info.py b/plugins/modules/nginx_status_info.py
index 6bbea078b0..7f9865878c 100644
--- a/plugins/modules/nginx_status_info.py
+++ b/plugins/modules/nginx_status_info.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: nginx_status_info
short_description: Retrieve information on nginx status
description:
@@ -34,9 +33,9 @@ options:
notes:
- See U(http://nginx.org/en/docs/http/ngx_http_stub_status_module.html) for more information.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
# Gather status info from nginx on localhost
- name: Get current http stats
community.general.nginx_status_info:
@@ -49,10 +48,9 @@ EXAMPLES = r'''
url: http://localhost/nginx_status
timeout: 20
register: result
-'''
+"""
-RETURN = r'''
----
+RETURN = r"""
active_connections:
description: Active connections.
returned: success
@@ -64,7 +62,8 @@ accepts:
type: int
sample: 81769947
handled:
- description: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached.
+ description: The total number of handled connections. Generally, the parameter value is the same as accepts unless some
+ resource limits have been reached.
returned: success
type: int
sample: 81769947
@@ -93,7 +92,7 @@ data:
returned: success
type: str
sample: "Active connections: 2340 \nserver accepts handled requests\n 81769947 81769947 144332345 \nReading: 0 Writing: 241 Waiting: 2092 \n"
-'''
+"""
import re
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/nictagadm.py b/plugins/modules/nictagadm.py
index 5b81861e8f..a02a8fcffd 100644
--- a/plugins/modules/nictagadm.py
+++ b/plugins/modules/nictagadm.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: nictagadm
short_description: Manage nic tags on SmartOS systems
description:
@@ -26,39 +25,39 @@ attributes:
options:
name:
description:
- - Name of the nic tag.
+ - Name of the nic tag.
required: true
type: str
mac:
description:
- - Specifies the O(mac) address to attach the nic tag to when not creating an O(etherstub).
- - Parameters O(mac) and O(etherstub) are mutually exclusive.
+ - Specifies the O(mac) address to attach the nic tag to when not creating an O(etherstub).
+ - Parameters O(mac) and O(etherstub) are mutually exclusive.
type: str
etherstub:
description:
- - Specifies that the nic tag will be attached to a created O(etherstub).
- - Parameter O(etherstub) is mutually exclusive with both O(mtu), and O(mac).
+ - Specifies that the nic tag will be attached to a created O(etherstub).
+ - Parameter O(etherstub) is mutually exclusive with both O(mtu), and O(mac).
type: bool
default: false
mtu:
description:
- - Specifies the size of the O(mtu) of the desired nic tag.
- - Parameters O(mtu) and O(etherstub) are mutually exclusive.
+ - Specifies the size of the O(mtu) of the desired nic tag.
+ - Parameters O(mtu) and O(etherstub) are mutually exclusive.
type: int
force:
description:
- - When O(state=absent) this switch will use the C(-f) parameter and delete the nic tag regardless of existing VMs.
+ - When O(state=absent) this switch will use the C(-f) parameter and delete the nic tag regardless of existing VMs.
type: bool
default: false
state:
description:
- - Create or delete a SmartOS nic tag.
+ - Create or delete a SmartOS nic tag.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create 'storage0' on '00:1b:21:a3:f5:4d'
community.general.nictagadm:
name: storage0
@@ -70,11 +69,11 @@ EXAMPLES = r'''
community.general.nictagadm:
name: storage0
state: absent
-'''
+"""
-RETURN = r'''
+RETURN = r"""
name:
- description: nic tag name
+ description: Nic tag name.
returned: always
type: str
sample: storage0
@@ -84,26 +83,26 @@ mac:
type: str
sample: 00:1b:21:a3:f5:4d
etherstub:
- description: specifies if the nic tag will create and attach to an etherstub.
+ description: Specifies if the nic tag will create and attach to an etherstub.
returned: always
type: bool
sample: false
mtu:
- description: specifies which MTU size was passed during the nictagadm add command. mtu and etherstub are mutually exclusive.
+ description: Specifies which MTU size was passed during the nictagadm add command. mtu and etherstub are mutually exclusive.
returned: always
type: int
sample: 1500
force:
- description: Shows if -f was used during the deletion of a nic tag
+ description: Shows if -f was used during the deletion of a nic tag.
returned: always
type: bool
sample: false
state:
- description: state of the target
+ description: State of the target.
returned: always
type: str
sample: present
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.network import is_mac
diff --git a/plugins/modules/nmcli.py b/plugins/modules/nmcli.py
index e2803432a9..3c895e76ec 100644
--- a/plugins/modules/nmcli.py
+++ b/plugins/modules/nmcli.py
@@ -9,1058 +9,1112 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: nmcli
author:
- - Chris Long (@alcamie101)
+ - Chris Long (@alcamie101)
short_description: Manage Networking
requirements:
- - nmcli
+ - nmcli
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
description:
- - 'Manage the network devices. Create, modify and manage various connection and device type e.g., ethernet, teams, bonds, vlans etc.'
- - 'On CentOS 8 and Fedora >=29 like systems, the requirements can be met by installing the following packages: NetworkManager.'
- - 'On CentOS 7 and Fedora <=28 like systems, the requirements can be met by installing the following packages: NetworkManager-tui.'
- - 'On Ubuntu and Debian like systems, the requirements can be met by installing the following packages: network-manager'
- - 'On openSUSE, the requirements can be met by installing the following packages: NetworkManager.'
+ - Manage the network devices. Create, modify and manage various connection and device type, for example V(ethernet), V(team),
+ V(bond), V(vlan) and so on.
+ - 'On CentOS 8 and Fedora >=29 like systems, the requirements can be met by installing the following packages: NetworkManager.'
+ - 'On CentOS 7 and Fedora <=28 like systems, the requirements can be met by installing the following packages: NetworkManager-tui.'
+ - 'On Ubuntu and Debian like systems, the requirements can be met by installing the following packages: network-manager.'
+ - 'On openSUSE, the requirements can be met by installing the following packages: NetworkManager.'
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
options:
- state:
+ state:
+ description:
+ - Whether the device should exist or not, taking action if the state is different from what is stated.
+ - Using O(state=present) to create connection will automatically bring connection up.
+ - Using O(state=up) and O(state=down) will not modify connection with other parameters. These states have been added
+ in community.general 9.5.0.
+ type: str
+ required: true
+ choices: [absent, present, up, down]
+ autoconnect:
+ description:
+ - Whether the connection should start on boot.
+ - Whether the connection profile can be automatically activated.
+ type: bool
+ default: true
+ conn_name:
+ description:
+ - The name used to call the connection. Pattern is V([-][-]).
+ type: str
+ required: true
+ conn_reload:
+ description:
+ - Whether the connection should be reloaded if it was modified.
+ type: bool
+ required: false
+ default: false
+ version_added: 9.5.0
+ ifname:
+ description:
+ - The interface to bind the connection to.
+ - The connection will only be applicable to this interface name.
+ - A special value of V(*) can be used for interface-independent connections.
+ - The ifname argument is mandatory for all connection types except bond, team, bridge, vlan and vpn.
+ - This parameter defaults to O(conn_name) when left unset for all connection types except vpn that removes it.
+ type: str
+ type:
+ description:
+ - This is the type of device or network connection that you wish to create or modify.
+ - Type V(dummy) is added in community.general 3.5.0.
+ - Type V(gsm) is added in community.general 3.7.0.
+ - Type V(infiniband) is added in community.general 2.0.0.
+ - Type V(loopback) is added in community.general 8.1.0.
+ - Type V(macvlan) is added in community.general 6.6.0.
+ - Type V(ovs-bridge) is added in community.general 8.6.0.
+ - Type V(ovs-interface) is added in community.general 8.6.0.
+ - Type V(ovs-port) is added in community.general 8.6.0.
+ - Type V(wireguard) is added in community.general 4.3.0.
+ - Type V(vpn) is added in community.general 5.1.0.
+ - Type V(vrf) is added in community.general 10.4.0.
+ - Using V(bond-slave), V(bridge-slave), or V(team-slave) implies V(ethernet) connection type with corresponding O(slave_type)
+ option.
+ - If you want to control non-ethernet connection attached to V(bond), V(bridge), or V(team) consider using O(slave_type)
+ option.
+ type: str
+ choices: [bond, bond-slave, bridge, bridge-slave, dummy, ethernet, generic, gre, infiniband, ipip, macvlan, sit, team,
+ team-slave, vlan, vxlan, wifi, gsm, wireguard, ovs-bridge, ovs-port, ovs-interface, vpn, vrf, loopback]
+ mode:
+ description:
+ - This is the type of device or network connection that you wish to create for a bond or bridge.
+ type: str
+ choices: [802.3ad, active-backup, balance-alb, balance-rr, balance-tlb, balance-xor, broadcast]
+ default: balance-rr
+ transport_mode:
+ description:
+ - This option sets the connection type of Infiniband IPoIB devices.
+ type: str
+ choices: [datagram, connected]
+ version_added: 5.8.0
+ slave_type:
+ description:
+ - Type of the device of this slave's master connection (for example V(bond)).
+ - Type V(ovs-port) is added in community.general 8.6.0.
+ type: str
+ choices: ['bond', 'bridge', 'team', 'ovs-port', 'vrf']
+ version_added: 7.0.0
+ master:
+ description:
+ - Master [-][-].
+ - The Type Of Service.
+ type: int
+ route_metric4:
+ description:
+ - Set metric level of ipv4 routes configured on interface.
+ type: int
+ version_added: 2.0.0
+ routing_rules4:
+ description:
+ - Is the same as in an C(ip rule add) command, except always requires specifying a priority.
+ type: list
+ elements: str
+ version_added: 3.3.0
+ never_default4:
+ description:
+ - Set as default route.
+ - This parameter is mutually_exclusive with gw4 parameter.
+ type: bool
+ default: false
+ version_added: 2.0.0
+ dns4:
+ description:
+ - A list of up to 3 DNS servers.
+ - The entries must be IPv4 addresses, for example V(192.0.2.53).
+ elements: str
+ type: list
+ dns4_search:
+ description:
+ - A list of DNS search domains.
+ elements: str
+ type: list
+ dns4_options:
+ description:
+ - A list of DNS options.
+ elements: str
+ type: list
+ version_added: 7.2.0
+ dns4_ignore_auto:
+ description:
+ - Ignore automatically configured IPv4 name servers.
+ type: bool
+ default: false
+ version_added: 3.2.0
+ method4:
+ description:
+ - Configuration method to be used for IPv4.
+ - If O(ip4) is set, C(ipv4.method) is automatically set to V(manual) and this parameter is not needed.
+ type: str
+ choices: [auto, link-local, manual, shared, disabled]
+ version_added: 2.2.0
+ may_fail4:
+ description:
+ - If you need O(ip4) configured before C(network-online.target) is reached, set this option to V(false).
+ - This option applies when O(method4) is not V(disabled).
+ type: bool
+ default: true
+ version_added: 3.3.0
+ ip6:
+ description:
+ - List of IPv6 addresses to this interface.
+ - Use the format V(abbe::cafe/128) or V(abbe::cafe).
+ - If defined and O(method6) is not specified, automatically set C(ipv6.method) to V(manual).
+ type: list
+ elements: str
+ gw6:
+ description:
+ - The IPv6 gateway for this interface.
+ - Use the format V(2001:db8::1).
+ type: str
+ gw6_ignore_auto:
+ description:
+ - Ignore automatically configured IPv6 routes.
+ type: bool
+ default: false
+ version_added: 3.2.0
+ routes6:
+ description:
+ - The list of IPv6 routes.
+ - Use the format V(fd12:3456:789a:1::/64 2001:dead:beef::1).
+ - To specify more complex routes, use the O(routes6_extended) option.
+ type: list
+ elements: str
+ version_added: 4.4.0
+ routes6_extended:
+ description:
+ - The list of IPv6 routes but with parameters.
+ type: list
+ elements: dict
+ suboptions:
+ ip:
+ description:
+ - IP or prefix of route.
+ - Use the format V(fd12:3456:789a:1::/64).
type: str
required: true
- conn_reload:
+ next_hop:
description:
- - Whether the connection should be reloaded if it was modified.
+ - Use the format V(2001:dead:beef::1).
+ type: str
+ metric:
+ description:
+ - Route metric.
+ type: int
+ table:
+ description:
+ - The table to add this route to.
+ - The default depends on C(ipv6.route-table).
+ type: int
+ cwnd:
+ description:
+ - The clamp for congestion window.
+ type: int
+ mtu:
+ description:
+ - If non-zero, only transmit packets of the specified size or smaller.
+ type: int
+ onlink:
+ description:
+ - Pretend that the nexthop is directly attached to this link, even if it does not match any interface prefix.
type: bool
- required: false
- default: false
- version_added: 9.5.0
- ifname:
+ route_metric6:
+ description:
+ - Set metric level of IPv6 routes configured on interface.
+ type: int
+ version_added: 4.4.0
+ dns6:
+ description:
+ - A list of up to 3 DNS servers.
+ - The entries must be IPv6 addresses, for example V(2001:4860:4860::8888).
+ elements: str
+ type: list
+ dns6_search:
+ description:
+ - A list of DNS search domains.
+ elements: str
+ type: list
+ dns6_options:
+ description:
+ - A list of DNS options.
+ elements: str
+ type: list
+ version_added: 7.2.0
+ dns6_ignore_auto:
+ description:
+ - Ignore automatically configured IPv6 name servers.
+ type: bool
+ default: false
+ version_added: 3.2.0
+ method6:
+ description:
+ - Configuration method to be used for IPv6.
+ - If O(ip6) is set, C(ipv6.method) is automatically set to V(manual) and this parameter is not needed.
+ - V(disabled) was added in community.general 3.3.0.
+ type: str
+ choices: [ignore, auto, dhcp, link-local, manual, shared, disabled]
+ version_added: 2.2.0
+ ip_privacy6:
+ description:
+ - If enabled, it makes the kernel generate a temporary IPv6 address in addition to the public one.
+ type: str
+ choices: [disabled, prefer-public-addr, prefer-temp-addr, unknown]
+ version_added: 4.2.0
+ addr_gen_mode6:
+ description:
+ - Configure method for creating the address for use with IPv6 Stateless Address Autoconfiguration.
+ - V(default) and V(default-or-eui64) have been added in community.general 6.5.0.
+ type: str
+ choices: [default, default-or-eui64, eui64, stable-privacy]
+ version_added: 4.2.0
+ mtu:
+ description:
+ - The connection MTU, for example V(9000). This can not be applied when creating the interface and is done once the
+ interface has been created.
+ - Can be used when modifying Team, VLAN, Ethernet (Future plans to implement wifi, gsm, pppoe, infiniband).
+ - This parameter defaults to V(1500) when unset.
+ type: int
+ dhcp_client_id:
+ description:
+ - DHCP Client Identifier sent to the DHCP server.
+ type: str
+ primary:
+ description:
+ - This is only used with bond and is the primary interface name (for "active-backup" mode), this is the usually the
+ 'ifname'.
+ type: str
+ miimon:
+ description:
+ - This is only used with bond - miimon.
+ - This parameter defaults to V(100) when unset.
+ type: int
+ downdelay:
+ description:
+ - This is only used with bond - downdelay.
+ type: int
+ updelay:
+ description:
+ - This is only used with bond - updelay.
+ type: int
+ xmit_hash_policy:
+ description:
+ - This is only used with bond - xmit_hash_policy type.
+ type: str
+ version_added: 5.6.0
+ fail_over_mac:
+ description:
+ - This is only used with bond - fail_over_mac.
+ type: str
+ choices: [none, active, follow]
+ version_added: 10.3.0
+ arp_interval:
+ description:
+ - This is only used with bond - ARP interval.
+ type: int
+ arp_ip_target:
+ description:
+ - This is only used with bond - ARP IP target.
+ type: str
+ stp:
+ description:
+ - This is only used with bridge and controls whether Spanning Tree Protocol (STP) is enabled for this bridge.
+ type: bool
+ default: true
+ priority:
+ description:
+ - This is only used with 'bridge' - sets STP priority.
+ type: int
+ default: 128
+ forwarddelay:
+ description:
+ - This is only used with bridge - [forward-delay <2-30>] STP forwarding delay, in seconds.
+ type: int
+ default: 15
+ hellotime:
+ description:
+ - This is only used with bridge - [hello-time <1-10>] STP hello time, in seconds.
+ type: int
+ default: 2
+ maxage:
+ description:
+ - This is only used with bridge - [max-age <6-42>] STP maximum message age, in seconds.
+ type: int
+ default: 20
+ ageingtime:
+ description:
+ - This is only used with bridge - [ageing-time <0-1000000>] the Ethernet MAC address aging time, in seconds.
+ type: int
+ default: 300
+ mac:
+ description:
+ - MAC address of the connection.
+ - Note this requires a recent kernel feature, originally introduced in 3.15 upstream kernel.
+ type: str
+ slavepriority:
+ description:
+ - This is only used with 'bridge-slave' - [<0-63>] - STP priority of this slave.
+ type: int
+ default: 32
+ path_cost:
+ description:
+ - This is only used with 'bridge-slave' - [<1-65535>] - STP port cost for destinations using this slave.
+ type: int
+ default: 100
+ hairpin:
+ description:
+ - This is only used with 'bridge-slave' - 'hairpin mode' for the slave, which allows frames to be sent back out through
+ the slave the frame was received on.
+ - The default change to V(false) in community.general 7.0.0. It used to be V(true) before.
+ type: bool
+ default: false
+ runner:
+ description:
+ - This is the type of device or network connection that you wish to create for a team.
+ type: str
+ choices: [broadcast, roundrobin, activebackup, loadbalance, lacp]
+ default: roundrobin
+ version_added: 3.4.0
+ runner_hwaddr_policy:
+ description:
+ - This defines the policy of how hardware addresses of team device and port devices should be set during the team lifetime.
+ type: str
+ choices: [same_all, by_active, only_active]
+ version_added: 3.4.0
+ runner_fast_rate:
+ description:
+ - Option specifies the rate at which our link partner is asked to transmit LACPDU packets. If this is V(true) then packets
+ will be sent once per second. Otherwise they will be sent every 30 seconds.
+ - Only allowed for O(runner=lacp).
+ type: bool
+ version_added: 6.5.0
+ vlanid:
+ description:
+ - This is only used with VLAN - VLAN ID in range <0-4095>.
+ type: int
+ vlandev:
+ description:
+ - This is only used with VLAN - parent device this VLAN is on, can use ifname.
+ type: str
+ flags:
+ description:
+ - This is only used with VLAN - flags.
+ type: str
+ ingress:
+ description:
+ - This is only used with VLAN - VLAN ingress priority mapping.
+ type: str
+ egress:
+ description:
+ - This is only used with VLAN - VLAN egress priority mapping.
+ type: str
+ vxlan_id:
+ description:
+ - This is only used with VXLAN - VXLAN ID.
+ type: int
+ vxlan_remote:
+ description:
+ - This is only used with VXLAN - VXLAN destination IP address.
+ type: str
+ vxlan_local:
+ description:
+ - This is only used with VXLAN - VXLAN local IP address.
+ type: str
+ ip_tunnel_dev:
+ description:
+ - This is used with GRE/IPIP/SIT - parent device this GRE/IPIP/SIT tunnel, can use ifname.
+ type: str
+ ip_tunnel_remote:
+ description:
+ - This is used with GRE/IPIP/SIT - GRE/IPIP/SIT destination IP address.
+ type: str
+ ip_tunnel_local:
+ description:
+ - This is used with GRE/IPIP/SIT - GRE/IPIP/SIT local IP address.
+ type: str
+ ip_tunnel_input_key:
+ description:
+ - The key used for tunnel input packets.
+ - Only used when O(type=gre).
+ type: str
+ version_added: 3.6.0
+ ip_tunnel_output_key:
+ description:
+ - The key used for tunnel output packets.
+ - Only used when O(type=gre).
+ type: str
+ version_added: 3.6.0
+ table:
+ description:
+ - This is only used with VRF - VRF table number.
+ type: int
+ version_added: 10.4.0
+ zone:
+ description:
+ - The trust level of the connection.
+ - When updating this property on a currently activated connection, the change takes effect immediately.
+ type: str
+ version_added: 2.0.0
+ wifi_sec:
+ description:
+ - The security configuration of the WiFi connection.
+ - Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on
+ the host.
+ - 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-802-11-wireless-security.html).'
+ - 'For instance to use common WPA-PSK auth with a password: V({key-mgmt: wpa-psk, psk: my_password}).'
+ type: dict
+ suboptions:
+ auth-alg:
description:
- - The interface to bind the connection to.
- - The connection will only be applicable to this interface name.
- - A special value of V('*') can be used for interface-independent connections.
- - The ifname argument is mandatory for all connection types except bond, team, bridge, vlan and vpn.
- - This parameter defaults to O(conn_name) when left unset for all connection types except vpn that removes it.
+ - When WEP is used (that is, if O(wifi_sec.key-mgmt) is V(none) or V(ieee8021x)) indicate the 802.11 authentication
+ algorithm required by the AP here.
+ - One of V(open) for Open System, V(shared) for Shared Key, or V(leap) for Cisco LEAP.
+ - When using Cisco LEAP (that is, if O(wifi_sec.key-mgmt=ieee8021x) and O(wifi_sec.auth-alg=leap)) the O(wifi_sec.leap-username)
+ and O(wifi_sec.leap-password) properties must be specified.
type: str
- type:
+ choices: [open, shared, leap]
+ fils:
description:
- - This is the type of device or network connection that you wish to create or modify.
- - Type V(dummy) is added in community.general 3.5.0.
- - Type V(gsm) is added in community.general 3.7.0.
- - Type V(infiniband) is added in community.general 2.0.0.
- - Type V(loopback) is added in community.general 8.1.0.
- - Type V(macvlan) is added in community.general 6.6.0.
- - Type V(ovs-bridge) is added in community.general 8.6.0.
- - Type V(ovs-interface) is added in community.general 8.6.0.
- - Type V(ovs-port) is added in community.general 8.6.0.
- - Type V(wireguard) is added in community.general 4.3.0.
- - Type V(vpn) is added in community.general 5.1.0.
- - Using V(bond-slave), V(bridge-slave), or V(team-slave) implies V(ethernet) connection type with corresponding O(slave_type) option.
- - If you want to control non-ethernet connection attached to V(bond), V(bridge), or V(team) consider using O(slave_type) option.
- type: str
- choices: [ bond, bond-slave, bridge, bridge-slave, dummy, ethernet, generic, gre, infiniband, ipip, macvlan, sit, team, team-slave, vlan, vxlan,
- wifi, gsm, wireguard, ovs-bridge, ovs-port, ovs-interface, vpn, loopback ]
- mode:
+ - Indicates whether Fast Initial Link Setup (802.11ai) must be enabled for the connection.
+ - One of V(0) (use global default value), V(1) (disable FILS), V(2) (enable FILS if the supplicant and the access
+ point support it) or V(3) (enable FILS and fail if not supported).
+ - When set to V(0) and no global default is set, FILS will be optionally enabled.
+ type: int
+ choices: [0, 1, 2, 3]
+ default: 0
+ group:
description:
- - This is the type of device or network connection that you wish to create for a bond or bridge.
- type: str
- choices: [ 802.3ad, active-backup, balance-alb, balance-rr, balance-tlb, balance-xor, broadcast ]
- default: balance-rr
- transport_mode:
- description:
- - This option sets the connection type of Infiniband IPoIB devices.
- type: str
- choices: [ datagram, connected ]
- version_added: 5.8.0
- slave_type:
- description:
- - Type of the device of this slave's master connection (for example V(bond)).
- - Type V(ovs-port) is added in community.general 8.6.0.
- type: str
- choices: [ 'bond', 'bridge', 'team', 'ovs-port' ]
- version_added: 7.0.0
- master:
- description:
- - Master ] STP forwarding delay, in seconds.
+ - If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple
+ fragments.
+ - If zero a default MTU is used. Note that contrary to wg-quick's MTU setting, this does not take into account the
+ current routes at the time of activation.
type: int
- default: 15
- hellotime:
+ peer-routes:
description:
- - This is only used with bridge - [hello-time <1-10>] STP hello time, in seconds.
- type: int
- default: 2
- maxage:
- description:
- - This is only used with bridge - [max-age <6-42>] STP maximum message age, in seconds.
- type: int
- default: 20
- ageingtime:
- description:
- - This is only used with bridge - [ageing-time <0-1000000>] the Ethernet MAC address aging time, in seconds.
- type: int
- default: 300
- mac:
- description:
- - MAC address of the connection.
- - Note this requires a recent kernel feature, originally introduced in 3.15 upstream kernel.
- type: str
- slavepriority:
- description:
- - This is only used with 'bridge-slave' - [<0-63>] - STP priority of this slave.
- type: int
- default: 32
- path_cost:
- description:
- - This is only used with 'bridge-slave' - [<1-65535>] - STP port cost for destinations via this slave.
- type: int
- default: 100
- hairpin:
- description:
- - This is only used with 'bridge-slave' - 'hairpin mode' for the slave, which allows frames to be sent back out through the slave the
- frame was received on.
- - The default change to V(false) in community.general 7.0.0. It used to be V(true) before.
+ - Whether to automatically add routes for the AllowedIPs ranges of the peers.
+ - If V(true) (the default), NetworkManager will automatically add routes in the routing tables according to C(ipv4.route-table)
+ and C(ipv6.route-table). Usually you want this automatism enabled.
+ - If V(false), no such routes are added automatically. In this case, the user may want to configure static routes
+ in C(ipv4.routes) and C(ipv6.routes), respectively.
+ - Note that if the peer's AllowedIPs is V(0.0.0.0/0) or V(::/0) and the profile's C(ipv4.never-default) or C(ipv6.never-default)
+ setting is enabled, the peer route for this peer will not be added automatically.
type: bool
- default: false
- runner:
- description:
- - This is the type of device or network connection that you wish to create for a team.
+ private-key:
+ description: The 256 bit private-key in base64 encoding.
type: str
- choices: [ broadcast, roundrobin, activebackup, loadbalance, lacp ]
- default: roundrobin
- version_added: 3.4.0
- runner_hwaddr_policy:
- description:
- - This defines the policy of how hardware addresses of team device and port devices
- should be set during the team lifetime.
+ private-key-flags:
+ description: C(NMSettingSecretFlags) indicating how to handle the O(wireguard.private-key) property.
+ type: int
+ choices: [0, 1, 2]
+ vpn:
+ description:
+ - Configuration of a VPN connection (PPTP and L2TP).
+ - In order to use L2TP you need to be sure that C(network-manager-l2tp) - and C(network-manager-l2tp-gnome) if host
+ has UI - are installed on the host.
+ type: dict
+ version_added: 5.1.0
+ suboptions:
+ permissions:
+ description: User that will have permission to use the connection.
type: str
- choices: [ same_all, by_active, only_active ]
- version_added: 3.4.0
- runner_fast_rate:
+ required: true
+ service-type:
+ description: This defines the service type of connection.
+ type: str
+ required: true
+ gateway:
+ description: The gateway to connection. It can be an IP address (for example V(192.0.2.1)) or a FQDN address (for
+ example V(vpn.example.com)).
+ type: str
+ required: true
+ password-flags:
description:
- - Option specifies the rate at which our link partner is asked to transmit LACPDU
- packets. If this is V(true) then packets will be sent once per second. Otherwise they
- will be sent every 30 seconds.
- - Only allowed for O(runner=lacp).
+ - NMSettingSecretFlags indicating how to handle the C(vpn.password) property.
+ - 'Following choices are allowed: V(0) B(NONE): The system is responsible for providing and storing this secret
+ (default); V(1) B(AGENT_OWNED): A user secret agent is responsible for providing and storing this secret; when
+ it is required agents will be asked to retrieve it; V(2) B(NOT_SAVED): This secret should not be saved, but should
+ be requested from the user each time it is needed; V(4) B(NOT_REQUIRED): In situations where it cannot be automatically
+ determined that the secret is required (some VPNs and PPP providers do not require all secrets) this flag indicates
+ that the specific secret is not required.'
+ type: int
+ choices: [0, 1, 2, 4]
+ default: 0
+ user:
+ description: Username provided by VPN administrator.
+ type: str
+ required: true
+ ipsec-enabled:
+ description:
+ - Enable or disable IPSec tunnel to L2TP host.
+ - This option is need when O(vpn.service-type) is V(org.freedesktop.NetworkManager.l2tp).
type: bool
- version_added: 6.5.0
- vlanid:
+ ipsec-psk:
description:
- - This is only used with VLAN - VLAN ID in range <0-4095>.
+ - The pre-shared key in base64 encoding.
+ - "You can encode using this Ansible jinja2 expression: V(\"0s{{ '[YOUR PRE-SHARED KEY]' | ansible.builtin.b64encode }}\")."
+ - This is only used when O(vpn.ipsec-enabled=true).
+ type: str
+ sriov:
+ description:
+ - Allow to configure SR-IOV settings.
+ - 'An up-to-date list of supported attributes can be found here:
+ U(https://networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/settings-sriov.html).'
+ type: dict
+ version_added: 10.1.0
+ suboptions:
+ autoprobe-drivers:
+ description:
+ - Whether to autoprobe virtual functions by a compatible driver.
type: int
- vlandev:
+ eswitch-encap-mode:
description:
- - This is only used with VLAN - parent device this VLAN is on, can use ifname.
- type: str
- flags:
- description:
- - This is only used with VLAN - flags.
- type: str
- ingress:
- description:
- - This is only used with VLAN - VLAN ingress priority mapping.
- type: str
- egress:
- description:
- - This is only used with VLAN - VLAN egress priority mapping.
- type: str
- vxlan_id:
- description:
- - This is only used with VXLAN - VXLAN ID.
+ - Select the eswitch encapsulation support.
type: int
- vxlan_remote:
- description:
- - This is only used with VXLAN - VXLAN destination IP address.
- type: str
- vxlan_local:
- description:
- - This is only used with VXLAN - VXLAN local IP address.
- type: str
- ip_tunnel_dev:
+ eswitch-inline-mode:
description:
- - This is used with GRE/IPIP/SIT - parent device this GRE/IPIP/SIT tunnel, can use ifname.
+ - Select the eswitch inline-mode of the device.
+ type: int
+ eswitch-mode:
+ description:
+ - Select the eswitch mode of the device.
+ type: int
+ total-vfs:
+ description: Number of virtual functions to create. Consult your NIC documentation for the maximum number of VFs supported.
+ type: int
+ vfs:
+ description:
+ - 'Virtual function descriptors in the form: V(INDEX [ATTR=VALUE[ ATTR=VALUE]...]).'
+ - Multiple VFs can be specified using a comma as separator, for example V(2 mac=00:11:22:33:44:55 spoof-check=true,3
+ vlans=100).
type: str
- ip_tunnel_remote:
- description:
- - This is used with GRE/IPIP/SIT - GRE/IPIP/SIT destination IP address.
- type: str
- ip_tunnel_local:
- description:
- - This is used with GRE/IPIP/SIT - GRE/IPIP/SIT local IP address.
- type: str
- ip_tunnel_input_key:
- description:
- - The key used for tunnel input packets.
- - Only used when O(type=gre).
- type: str
- version_added: 3.6.0
- ip_tunnel_output_key:
- description:
- - The key used for tunnel output packets.
- - Only used when O(type=gre).
- type: str
- version_added: 3.6.0
- zone:
- description:
- - The trust level of the connection.
- - When updating this property on a currently activated connection, the change takes effect immediately.
- type: str
- version_added: 2.0.0
- wifi_sec:
- description:
- - The security configuration of the WiFi connection.
- - Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- - 'An up-to-date list of supported attributes can be found here:
- U(https://networkmanager.dev/docs/api/latest/settings-802-11-wireless-security.html).'
- - 'For instance to use common WPA-PSK auth with a password:
- V({key-mgmt: wpa-psk, psk: my_password}).'
- type: dict
- suboptions:
- auth-alg:
- description:
- - When WEP is used (that is, if O(wifi_sec.key-mgmt) is V(none) or V(ieee8021x)) indicate the 802.11
- authentication algorithm required by the AP here.
- - One of V(open) for Open System, V(shared) for Shared Key, or V(leap) for Cisco LEAP.
- - When using Cisco LEAP (that is, if O(wifi_sec.key-mgmt=ieee8021x) and O(wifi_sec.auth-alg=leap))
- the O(wifi_sec.leap-username) and O(wifi_sec.leap-password) properties
- must be specified.
- type: str
- choices: [ open, shared, leap ]
- fils:
- description:
- - Indicates whether Fast Initial Link Setup (802.11ai) must be enabled for the connection.
- - One of V(0) (use global default value), V(1) (disable FILS), V(2) (enable FILS if the supplicant and the access point support it) or V(3)
- (enable FILS and fail if not supported).
- - When set to V(0) and no global default is set, FILS will be optionally enabled.
- type: int
- choices: [ 0, 1, 2, 3 ]
- default: 0
- group:
- description:
- - A list of group/broadcast encryption algorithms which prevents connections to Wi-Fi networks that do not utilize one of the algorithms in
- the list.
- - For maximum compatibility leave this property empty.
- type: list
- elements: str
- choices: [ wep40, wep104, tkip, ccmp ]
- key-mgmt:
- description:
- - Key management used for the connection.
- - One of V(none) (WEP or no password protection), V(ieee8021x) (Dynamic WEP), V(owe) (Opportunistic Wireless Encryption), V(wpa-psk) (WPA2
- + WPA3 personal), V(sae) (WPA3 personal only), V(wpa-eap) (WPA2 + WPA3 enterprise) or V(wpa-eap-suite-b-192) (WPA3 enterprise only).
- - This property must be set for any Wi-Fi connection that uses security.
- type: str
- choices: [ none, ieee8021x, owe, wpa-psk, sae, wpa-eap, wpa-eap-suite-b-192 ]
- leap-password-flags:
- description: Flags indicating how to handle the O(wifi_sec.leap-password) property.
- type: list
- elements: int
- leap-password:
- description: The login password for legacy LEAP connections (that is, if O(wifi_sec.key-mgmt=ieee8021x) and O(wifi_sec.auth-alg=leap)).
- type: str
- leap-username:
- description: The login username for legacy LEAP connections (that is, if O(wifi_sec.key-mgmt=ieee8021x) and O(wifi_sec.auth-alg=leap)).
- type: str
- pairwise:
- description:
- - A list of pairwise encryption algorithms which prevents connections to Wi-Fi networks that do not utilize one of the algorithms in the
- list.
- - For maximum compatibility leave this property empty.
- type: list
- elements: str
- choices: [ tkip, ccmp ]
- pmf:
- description:
- - Indicates whether Protected Management Frames (802.11w) must be enabled for the connection.
- - One of V(0) (use global default value), V(1) (disable PMF), V(2) (enable PMF if the
- supplicant and the access point support it) or V(3) (enable PMF and fail if not supported).
- - When set to V(0) and no global default is set, PMF will be optionally enabled.
- type: int
- choices: [ 0, 1, 2, 3 ]
- default: 0
- proto:
- description:
- - List of strings specifying the allowed WPA protocol versions to use.
- - Each element may be V(wpa) (allow WPA) or V(rsn) (allow WPA2/RSN).
- - If not specified, both WPA and RSN connections are allowed.
- type: list
- elements: str
- choices: [ wpa, rsn ]
- psk-flags:
- description: Flags indicating how to handle the O(wifi_sec.psk) property.
- type: list
- elements: int
- psk:
- description:
- - Pre-Shared-Key for WPA networks.
- - For WPA-PSK, it is either an ASCII passphrase of 8 to 63 characters that is
- (as specified in the 802.11i standard) hashed to derive the
- actual key, or the key in form of 64 hexadecimal character.
- - The WPA3-Personal networks use a passphrase of any length for SAE authentication.
- type: str
- wep-key-flags:
- description:
- - Flags indicating how to handle the O(wifi_sec.wep-key0), O(wifi_sec.wep-key1),
- O(wifi_sec.wep-key2), and O(wifi_sec.wep-key3) properties.
- type: list
- elements: int
- wep-key-type:
- description:
- - Controls the interpretation of WEP keys.
- - Allowed values are V(1), in which case the key is either a 10- or 26-character hexadecimal string, or a 5- or 13-character ASCII
- password; or V(2), in which case the passphrase is provided as a string and will be hashed using the de-facto MD5 method to derive the
- actual WEP key.
- type: int
- choices: [ 1, 2 ]
- wep-key0:
- description:
- - Index 0 WEP key. This is the WEP key used in most networks.
- - See the O(wifi_sec.wep-key-type) property for a description of how this key is interpreted.
- type: str
- wep-key1:
- description:
- - Index 1 WEP key. This WEP index is not used by most networks.
- - See the O(wifi_sec.wep-key-type) property for a description of how this key is interpreted.
- type: str
- wep-key2:
- description:
- - Index 2 WEP key. This WEP index is not used by most networks.
- - See the O(wifi_sec.wep-key-type) property for a description of how this key is interpreted.
- type: str
- wep-key3:
- description:
- - Index 3 WEP key. This WEP index is not used by most networks.
- - See the O(wifi_sec.wep-key-type) property for a description of how this key is interpreted.
- type: str
- wep-tx-keyidx:
- description:
- - When static WEP is used (that is, if O(wifi_sec.key-mgmt=none)) and a non-default WEP key index
- is used by the AP, put that WEP key index here.
- - Valid values are V(0) (default key) through V(3).
- - Note that some consumer access points (like the Linksys WRT54G) number the keys V(1) to V(4).
- type: int
- choices: [ 0, 1, 2, 3 ]
- default: 0
- wps-method:
- description:
- - Flags indicating which mode of WPS is to be used if any.
- - There is little point in changing the default setting as NetworkManager will automatically determine whether it is feasible to start WPS
- enrollment from the Access Point capabilities.
- - WPS can be disabled by setting this property to a value of V(1).
- type: int
- default: 0
- version_added: 3.0.0
- ssid:
- description:
- - Name of the Wireless router or the access point.
- type: str
- version_added: 3.0.0
- wifi:
- description:
- - The configuration of the WiFi connection.
- - Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- - 'An up-to-date list of supported attributes can be found here:
- U(https://networkmanager.dev/docs/api/latest/settings-802-11-wireless.html).'
- - 'For instance to create a hidden AP mode WiFi connection:
- V({hidden: true, mode: ap}).'
- type: dict
- suboptions:
- ap-isolation:
- description:
- - Configures AP isolation, which prevents communication between wireless devices connected to this AP.
- - This property can be set to a value different from V(-1) only when the interface is configured in AP mode.
- - If set to V(1), devices are not able to communicate with each other. This increases security because it protects devices against attacks
- from other clients in the network. At the same time, it prevents devices to access resources on the same wireless networks as file
- shares, printers, etc.
- - If set to V(0), devices can talk to each other.
- - When set to V(-1), the global default is used; in case the global default is unspecified it is assumed to be V(0).
- type: int
- choices: [ -1, 0, 1 ]
- default: -1
- assigned-mac-address:
- description:
- - The new field for the cloned MAC address.
- - It can be either a hardware address in ASCII representation, or one of the special values V(preserve), V(permanent), V(random) or
- V(stable).
- - This field replaces the deprecated O(wifi.cloned-mac-address) on D-Bus, which can only contain explicit hardware addresses.
- - Note that this property only exists in D-Bus API. libnm and nmcli continue to call this property C(cloned-mac-address).
- type: str
- band:
- description:
- - 802.11 frequency band of the network.
- - One of V(a) for 5GHz 802.11a or V(bg) for 2.4GHz 802.11.
- - This will lock associations to the Wi-Fi network to the specific band, so for example, if V(a) is specified, the device will not
- associate with the same network in the 2.4GHz band even if the network's settings are compatible.
- - This setting depends on specific driver capability and may not work with all drivers.
- type: str
- choices: [ a, bg ]
- bssid:
- description:
- - If specified, directs the device to only associate with the given access point.
- - This capability is highly driver dependent and not supported by all devices.
- - Note this property does not control the BSSID used when creating an Ad-Hoc network and is unlikely to in the future.
- type: str
- channel:
- description:
- - Wireless channel to use for the Wi-Fi connection.
- - The device will only join (or create for Ad-Hoc networks) a Wi-Fi network on the specified channel.
- - Because channel numbers overlap between bands, this property also requires the O(wifi.band) property to be set.
- type: int
- default: 0
- cloned-mac-address:
- description:
- - This D-Bus field is deprecated in favor of O(wifi.assigned-mac-address) which is more flexible and allows specifying special variants like
- V(random).
- - For libnm and nmcli, this field is called C(cloned-mac-address).
- type: str
- generate-mac-address-mask:
- description:
- - With O(wifi.cloned-mac-address) setting V(random) or V(stable), by default all bits of the MAC address are scrambled and a
- locally-administered, unicast MAC address is created. This property allows to specify that certain bits are fixed.
- - Note that the least significant bit of the first MAC address will always be unset to create a unicast MAC address.
- - If the property is V(null), it is eligible to be overwritten by a default connection setting.
- - If the value is still V(null) or an empty string, the default is to create a locally-administered, unicast MAC address.
- - If the value contains one MAC address, this address is used as mask. The set bits of the mask are to be filled with the current MAC
- address of the device, while the unset bits are subject to randomization.
- - Setting V(FE:FF:FF:00:00:00) means to preserve the OUI of the current MAC address and only randomize the lower 3 bytes using the
- V(random) or V(stable) algorithm.
- - If the value contains one additional MAC address after the mask, this address is used instead of the current MAC address to fill the bits
- that shall not be randomized.
- - For example, a value of V(FE:FF:FF:00:00:00 68:F7:28:00:00:00) will set the OUI of the MAC address to 68:F7:28, while the lower bits are
- randomized.
- - A value of V(02:00:00:00:00:00 00:00:00:00:00:00) will create a fully scrambled globally-administered, burned-in MAC address.
- - If the value contains more than one additional MAC addresses, one of them is chosen randomly. For example,
- V(02:00:00:00:00:00 00:00:00:00:00:00 02:00:00:00:00:00) will create a fully scrambled MAC address, randomly locally or globally
- administered.
- type: str
- hidden:
- description:
- - If V(true), indicates that the network is a non-broadcasting network that hides its SSID. This works both in infrastructure and AP mode.
- - In infrastructure mode, various workarounds are used for a more reliable discovery of hidden networks, such as probe-scanning the SSID.
- However, these workarounds expose inherent insecurities with hidden SSID networks, and thus hidden SSID networks should be used with
- caution.
- - In AP mode, the created network does not broadcast its SSID.
- - Note that marking the network as hidden may be a privacy issue for you (in infrastructure mode) or client stations (in AP mode), as the
- explicit probe-scans are distinctly recognizable on the air.
- type: bool
- default: false
- mac-address-blacklist:
- description:
- - A list of permanent MAC addresses of Wi-Fi devices to which this connection should never apply.
- - Each MAC address should be given in the standard hex-digits-and-colons notation (for example, V(00:11:22:33:44:55)).
- type: list
- elements: str
- mac-address-randomization:
- description:
- - One of V(0) (never randomize unless the user has set a global default to randomize and the supplicant supports randomization), V(1)
- (never randomize the MAC address), or V(2) (always randomize the MAC address).
- - This property is deprecated for O(wifi.cloned-mac-address).
- type: int
- default: 0
- choices: [ 0, 1, 2 ]
- mac-address:
- description:
- - If specified, this connection will only apply to the Wi-Fi device whose permanent MAC address matches.
- - This property does not change the MAC address of the device (for example for MAC spoofing).
- type: str
- mode:
- description: Wi-Fi network mode. If blank, V(infrastructure) is assumed.
- type: str
- choices: [ infrastructure, mesh, adhoc, ap ]
- default: infrastructure
- mtu:
- description: If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple Ethernet frames.
- type: int
- default: 0
- powersave:
- description:
- - One of V(2) (disable Wi-Fi power saving), V(3) (enable Wi-Fi power saving), V(1) (don't touch currently configure setting) or V(0) (use
- the globally configured value).
- - All other values are reserved.
- type: int
- default: 0
- choices: [ 0, 1, 2, 3 ]
- rate:
- description:
- - If non-zero, directs the device to only use the specified bitrate for communication with the access point.
- - Units are in Kb/s, so for example V(5500) = 5.5 Mbit/s.
- - This property is highly driver dependent and not all devices support setting a static bitrate.
- type: int
- default: 0
- tx-power:
- description:
- - If non-zero, directs the device to use the specified transmit power.
- - Units are dBm.
- - This property is highly driver dependent and not all devices support setting a static transmit power.
- type: int
- default: 0
- wake-on-wlan:
- description:
- - The NMSettingWirelessWakeOnWLan options to enable. Not all devices support all options.
- - May be any combination of C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_ANY) (V(0x2)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_DISCONNECT) (V(0x4)),
- C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_MAGIC) (V(0x8)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_GTK_REKEY_FAILURE) (V(0x10)),
- C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_EAP_IDENTITY_REQUEST) (V(0x20)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_4WAY_HANDSHAKE) (V(0x40)),
- C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_RFKILL_RELEASE) (V(0x80)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_TCP) (V(0x100)) or the special values
- V(0x1) (to use global settings) and V(0x8000) (to disable management of Wake-on-LAN in NetworkManager).
- - Note the option values' sum must be specified in order to combine multiple options.
- type: int
- default: 1
- version_added: 3.5.0
- ignore_unsupported_suboptions:
- description:
- - Ignore suboptions which are invalid or unsupported by the version of NetworkManager/nmcli installed on the host.
- - Only O(wifi) and O(wifi_sec) options are currently affected.
- type: bool
- default: false
- version_added: 3.6.0
- gsm:
- description:
- - The configuration of the GSM connection.
- - Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- - 'An up-to-date list of supported attributes can be found here:
- U(https://networkmanager.dev/docs/api/latest/settings-gsm.html).'
- - 'For instance to use apn, pin, username and password:
- V({apn: provider.apn, pin: 1234, username: apn.username, password: apn.password}).'
- type: dict
- version_added: 3.7.0
- suboptions:
- apn:
- description:
- - The GPRS Access Point Name specifying the APN used when establishing a data session with the GSM-based network.
- - The APN often determines how the user will be billed for their network usage and whether the user has access to the Internet or
- just a provider-specific walled-garden, so it is important to use the correct APN for the user's mobile broadband plan.
- - The APN may only be composed of the characters a-z, 0-9, ., and - per GSM 03.60 Section 14.9.
- type: str
- auto-config:
- description: When V(true), the settings such as O(gsm.apn), O(gsm.username), or O(gsm.password) will default to values that match the network
- the modem will register to in the Mobile Broadband Provider database.
- type: bool
- default: false
- device-id:
- description:
- - The device unique identifier (as given by the V(WWAN) management service) which this connection applies to.
- - If given, the connection will only apply to the specified device.
- type: str
- home-only:
- description:
- - When V(true), only connections to the home network will be allowed.
- - Connections to roaming networks will not be made.
- type: bool
- default: false
- mtu:
- description: If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple Ethernet frames.
- type: int
- default: 0
- network-id:
- description:
- - The Network ID (GSM LAI format, ie MCC-MNC) to force specific network registration.
- - If the Network ID is specified, NetworkManager will attempt to force the device to register only on the specified network.
- - This can be used to ensure that the device does not roam when direct roaming control of the device is not otherwise possible.
- type: str
- number:
- description: Legacy setting that used to help establishing PPP data sessions for GSM-based modems.
- type: str
- password:
- description:
- - The password used to authenticate with the network, if required.
- - Many providers do not require a password, or accept any password.
- - But if a password is required, it is specified here.
- type: str
- password-flags:
- description:
- - NMSettingSecretFlags indicating how to handle the O(gsm.password) property.
- - 'Following choices are allowed:
- V(0) B(NONE): The system is responsible for providing and storing this secret (default),
- V(1) B(AGENT_OWNED): A user secret agent is responsible for providing and storing this secret; when it is required agents will be
- asked to retrieve it
- V(2) B(NOT_SAVED): This secret should not be saved, but should be requested from the user each time it is needed
- V(4) B(NOT_REQUIRED): In situations where it cannot be automatically determined that the secret is required
- (some VPNs and PPP providers do not require all secrets) this flag indicates that the specific secret is not required.'
- type: int
- choices: [ 0, 1, 2 , 4 ]
- default: 0
- pin:
- description:
- - If the SIM is locked with a PIN it must be unlocked before any other operations are requested.
- - Specify the PIN here to allow operation of the device.
- type: str
- pin-flags:
- description:
- - NMSettingSecretFlags indicating how to handle the O(gsm.pin) property.
- - See O(gsm.password-flags) for NMSettingSecretFlags choices.
- type: int
- choices: [ 0, 1, 2 , 4 ]
- default: 0
- sim-id:
- description:
- - The SIM card unique identifier (as given by the C(WWAN) management service) which this connection applies to.
- - 'If given, the connection will apply to any device also allowed by O(gsm.device-id) which contains a SIM card matching
- the given identifier.'
- type: str
- sim-operator-id:
- description:
- - A MCC/MNC string like V(310260) or V(21601I) identifying the specific mobile network operator which this connection applies to.
- - 'If given, the connection will apply to any device also allowed by O(gsm.device-id) and O(gsm.sim-id) which contains a SIM card
- provisioned by the given operator.'
- type: str
- username:
- description:
- - The username used to authenticate with the network, if required.
- - Many providers do not require a username, or accept any username.
- - But if a username is required, it is specified here.
- macvlan:
- description:
- - The configuration of the MAC VLAN connection.
- - Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- - 'An up-to-date list of supported attributes can be found here:
- U(https://networkmanager.dev/docs/api/latest/settings-macvlan.html).'
- type: dict
- version_added: 6.6.0
- suboptions:
- mode:
- description:
- - The macvlan mode, which specifies the communication mechanism between multiple macvlans on the same lower device.
- - 'Following choices are allowed: V(1) B(vepa), V(2) B(bridge), V(3) B(private), V(4) B(passthru)
- and V(5) B(source)'
- type: int
- choices: [ 1, 2, 3, 4, 5 ]
- required: true
- parent:
- description:
- - If given, specifies the parent interface name or parent connection UUID from which this MAC-VLAN interface should
- be created. If this property is not specified, the connection must contain an "802-3-ethernet" setting with a
- "mac-address" property.
- type: str
- required: true
- promiscuous:
- description:
- - Whether the interface should be put in promiscuous mode.
- type: bool
- tap:
- description:
- - Whether the interface should be a MACVTAP.
- type: bool
- wireguard:
- description:
- - The configuration of the Wireguard connection.
- - Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- - 'An up-to-date list of supported attributes can be found here:
- U(https://networkmanager.dev/docs/api/latest/settings-wireguard.html).'
- - 'For instance to configure a listen port:
- V({listen-port: 12345}).'
- type: dict
- version_added: 4.3.0
- suboptions:
- fwmark:
- description:
- - The 32-bit fwmark for outgoing packets.
- - The use of fwmark is optional and is by default off. Setting it to 0 disables it.
- - Note that O(wireguard.ip4-auto-default-route) or O(wireguard.ip6-auto-default-route) enabled, implies to automatically choose a fwmark.
- type: int
- ip4-auto-default-route:
- description:
- - Whether to enable special handling of the IPv4 default route.
- - If enabled, the IPv4 default route from O(wireguard.peer-routes) will be placed to a dedicated routing-table and two policy
- routing rules will be added.
- - The fwmark number is also used as routing-table for the default-route, and if fwmark is zero, an unused fwmark/table is chosen
- automatically. This corresponds to what wg-quick does with Table=auto and what WireGuard calls "Improved Rule-based Routing"
- type: bool
- ip6-auto-default-route:
- description:
- - Like O(wireguard.ip4-auto-default-route), but for the IPv6 default route.
- type: bool
- listen-port:
- description: The WireGuard connection listen-port. If not specified, the port will be chosen randomly when the
- interface comes up.
- type: int
- mtu:
- description:
- - If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple fragments.
- - If zero a default MTU is used. Note that contrary to wg-quick's MTU setting, this does not take into account the current routes
- at the time of activation.
- type: int
- peer-routes:
- description:
- - Whether to automatically add routes for the AllowedIPs ranges of the peers.
- - If V(true) (the default), NetworkManager will automatically add routes in the routing tables according to C(ipv4.route-table) and
- C(ipv6.route-table). Usually you want this automatism enabled.
- - If V(false), no such routes are added automatically. In this case, the user may want to configure static routes in C(ipv4.routes)
- and C(ipv6.routes), respectively.
- - Note that if the peer's AllowedIPs is V(0.0.0.0/0) or V(::/0) and the profile's C(ipv4.never-default) or C(ipv6.never-default)
- setting is enabled, the peer route for this peer won't be added automatically.
- type: bool
- private-key:
- description: The 256 bit private-key in base64 encoding.
- type: str
- private-key-flags:
- description: C(NMSettingSecretFlags) indicating how to handle the O(wireguard.private-key) property.
- type: int
- choices: [ 0, 1, 2 ]
- vpn:
- description:
- - Configuration of a VPN connection (PPTP and L2TP).
- - In order to use L2TP you need to be sure that C(network-manager-l2tp) - and C(network-manager-l2tp-gnome)
- if host has UI - are installed on the host.
- type: dict
- version_added: 5.1.0
- suboptions:
- permissions:
- description: User that will have permission to use the connection.
- type: str
- required: true
- service-type:
- description: This defines the service type of connection.
- type: str
- required: true
- gateway:
- description: The gateway to connection. It can be an IP address (for example V(192.0.2.1))
- or a FQDN address (for example V(vpn.example.com)).
- type: str
- required: true
- password-flags:
- description:
- - NMSettingSecretFlags indicating how to handle the C(vpn.password) property.
- - 'Following choices are allowed:
- V(0) B(NONE): The system is responsible for providing and storing this secret (default);
- V(1) B(AGENT_OWNED): A user secret agent is responsible for providing and storing this secret; when it is required agents will be
- asked to retrieve it;
- V(2) B(NOT_SAVED): This secret should not be saved, but should be requested from the user each time it is needed;
- V(4) B(NOT_REQUIRED): In situations where it cannot be automatically determined that the secret is required
- (some VPNs and PPP providers do not require all secrets) this flag indicates that the specific secret is not required.'
- type: int
- choices: [ 0, 1, 2 , 4 ]
- default: 0
- user:
- description: Username provided by VPN administrator.
- type: str
- required: true
- ipsec-enabled:
- description:
- - Enable or disable IPSec tunnel to L2TP host.
- - This option is need when O(vpn.service-type) is V(org.freedesktop.NetworkManager.l2tp).
- type: bool
- ipsec-psk:
- description:
- - The pre-shared key in base64 encoding.
- - >
- You can encode using this Ansible jinja2 expression: V("0s{{ '[YOUR PRE-SHARED KEY]' | ansible.builtin.b64encode }}").
- - This is only used when O(vpn.ipsec-enabled=true).
- type: str
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
# These examples are using the following inventory:
#
# ## Directory layout:
@@ -1171,230 +1225,229 @@ EXAMPLES = r'''
## playbook-add.yml example
----
- hosts: openstack-stage
remote_user: root
tasks:
- - name: Install needed network manager libs
- ansible.builtin.package:
- name:
- - NetworkManager-libnm
- - nm-connection-editor
- - libsemanage-python
- - policycoreutils-python
- state: present
+ - name: Install needed network manager libs
+ ansible.builtin.package:
+ name:
+ - NetworkManager-libnm
+ - nm-connection-editor
+ - libsemanage-python
+ - policycoreutils-python
+ state: present
##### Working with all cloud nodes - Teaming
- - name: Try nmcli add team - conn_name only & ip4 gw4
- community.general.nmcli:
- type: team
- conn_name: '{{ item.conn_name }}'
- ip4: '{{ item.ip4 }}'
- gw4: '{{ item.gw4 }}'
- state: present
- with_items:
- - '{{ nmcli_team }}'
+ - name: Try nmcli add team - conn_name only & ip4 gw4
+ community.general.nmcli:
+ type: team
+ conn_name: '{{ item.conn_name }}'
+ ip4: '{{ item.ip4 }}'
+ gw4: '{{ item.gw4 }}'
+ state: present
+ with_items:
+ - '{{ nmcli_team }}'
- - name: Try nmcli add teams-slave
- community.general.nmcli:
- type: team-slave
- conn_name: '{{ item.conn_name }}'
- ifname: '{{ item.ifname }}'
- master: '{{ item.master }}'
- state: present
- with_items:
- - '{{ nmcli_team_slave }}'
+ - name: Try nmcli add teams-slave
+ community.general.nmcli:
+ type: team-slave
+ conn_name: '{{ item.conn_name }}'
+ ifname: '{{ item.ifname }}'
+ master: '{{ item.master }}'
+ state: present
+ with_items:
+ - '{{ nmcli_team_slave }}'
###### Working with all cloud nodes - Bonding
- - name: Try nmcli add bond - conn_name only & ip4 gw4 mode
- community.general.nmcli:
- type: bond
- conn_name: '{{ item.conn_name }}'
- ip4: '{{ item.ip4 }}'
- gw4: '{{ item.gw4 }}'
- mode: '{{ item.mode }}'
- state: present
- with_items:
- - '{{ nmcli_bond }}'
+ - name: Try nmcli add bond - conn_name only & ip4 gw4 mode
+ community.general.nmcli:
+ type: bond
+ conn_name: '{{ item.conn_name }}'
+ ip4: '{{ item.ip4 }}'
+ gw4: '{{ item.gw4 }}'
+ mode: '{{ item.mode }}'
+ state: present
+ with_items:
+ - '{{ nmcli_bond }}'
- - name: Try nmcli add bond-slave
- community.general.nmcli:
- type: bond-slave
- conn_name: '{{ item.conn_name }}'
- ifname: '{{ item.ifname }}'
- master: '{{ item.master }}'
- state: present
- with_items:
- - '{{ nmcli_bond_slave }}'
+ - name: Try nmcli add bond-slave
+ community.general.nmcli:
+ type: bond-slave
+ conn_name: '{{ item.conn_name }}'
+ ifname: '{{ item.ifname }}'
+ master: '{{ item.master }}'
+ state: present
+ with_items:
+ - '{{ nmcli_bond_slave }}'
##### Working with all cloud nodes - Ethernet
- - name: Try nmcli add Ethernet - conn_name only & ip4 gw4
- community.general.nmcli:
- type: ethernet
- conn_name: '{{ item.conn_name }}'
- ip4: '{{ item.ip4 }}'
- gw4: '{{ item.gw4 }}'
- state: present
- with_items:
- - '{{ nmcli_ethernet }}'
+ - name: Try nmcli add Ethernet - conn_name only & ip4 gw4
+ community.general.nmcli:
+ type: ethernet
+ conn_name: '{{ item.conn_name }}'
+ ip4: '{{ item.ip4 }}'
+ gw4: '{{ item.gw4 }}'
+ state: present
+ with_items:
+ - '{{ nmcli_ethernet }}'
## playbook-del.yml example
- hosts: openstack-stage
remote_user: root
tasks:
- - name: Try nmcli del team - multiple
- community.general.nmcli:
- conn_name: '{{ item.conn_name }}'
- state: absent
- with_items:
- - conn_name: em1
- - conn_name: em2
- - conn_name: p1p1
- - conn_name: p1p2
- - conn_name: p2p1
- - conn_name: p2p2
- - conn_name: tenant
- - conn_name: storage
- - conn_name: external
- - conn_name: team-em1
- - conn_name: team-em2
- - conn_name: team-p1p1
- - conn_name: team-p1p2
- - conn_name: team-p2p1
- - conn_name: team-p2p2
+ - name: Try nmcli del team - multiple
+ community.general.nmcli:
+ conn_name: '{{ item.conn_name }}'
+ state: absent
+ with_items:
+ - conn_name: em1
+ - conn_name: em2
+ - conn_name: p1p1
+ - conn_name: p1p2
+ - conn_name: p2p1
+ - conn_name: p2p2
+ - conn_name: tenant
+ - conn_name: storage
+ - conn_name: external
+ - conn_name: team-em1
+ - conn_name: team-em2
+ - conn_name: team-p1p1
+ - conn_name: team-p1p2
+ - conn_name: team-p2p1
+ - conn_name: team-p2p2
- - name: Add an Ethernet connection with static IP configuration
- community.general.nmcli:
- conn_name: my-eth1
- ifname: eth1
- type: ethernet
- ip4: 192.0.2.100/24
- gw4: 192.0.2.1
- state: present
+ - name: Add an Ethernet connection with static IP configuration
+ community.general.nmcli:
+ conn_name: my-eth1
+ ifname: eth1
+ type: ethernet
+ ip4: 192.0.2.100/24
+ gw4: 192.0.2.1
+ state: present
- - name: Add an Team connection with static IP configuration
- community.general.nmcli:
- conn_name: my-team1
- ifname: my-team1
- type: team
- ip4: 192.0.2.100/24
- gw4: 192.0.2.1
- state: present
- autoconnect: true
+ - name: Add an Team connection with static IP configuration
+ community.general.nmcli:
+ conn_name: my-team1
+ ifname: my-team1
+ type: team
+ ip4: 192.0.2.100/24
+ gw4: 192.0.2.1
+ state: present
+ autoconnect: true
- - name: Optionally, at the same time specify IPv6 addresses for the device
- community.general.nmcli:
- conn_name: my-eth1
- ifname: eth1
- type: ethernet
- ip4: 192.0.2.100/24
- gw4: 192.0.2.1
- ip6: 2001:db8::cafe
- gw6: 2001:db8::1
- state: present
+ - name: Optionally, at the same time specify IPv6 addresses for the device
+ community.general.nmcli:
+ conn_name: my-eth1
+ ifname: eth1
+ type: ethernet
+ ip4: 192.0.2.100/24
+ gw4: 192.0.2.1
+ ip6: 2001:db8::cafe
+ gw6: 2001:db8::1
+ state: present
- - name: Add two IPv4 DNS server addresses
- community.general.nmcli:
- conn_name: my-eth1
- type: ethernet
- dns4:
- - 192.0.2.53
- - 198.51.100.53
- state: present
+ - name: Add two IPv4 DNS server addresses
+ community.general.nmcli:
+ conn_name: my-eth1
+ type: ethernet
+ dns4:
+ - 192.0.2.53
+ - 198.51.100.53
+ state: present
- - name: Make a profile usable for all compatible Ethernet interfaces
- community.general.nmcli:
- ctype: ethernet
- name: my-eth1
- ifname: '*'
- state: present
+ - name: Make a profile usable for all compatible Ethernet interfaces
+ community.general.nmcli:
+ ctype: ethernet
+ name: my-eth1
+ ifname: '*'
+ state: present
- - name: Change the property of a setting e.g. MTU
- community.general.nmcli:
- conn_name: my-eth1
- mtu: 9000
- type: ethernet
- state: present
+ - name: Change the property of a setting e.g. MTU
+ community.general.nmcli:
+ conn_name: my-eth1
+ mtu: 9000
+ type: ethernet
+ state: present
- - name: Change the property of a setting e.g. MTU and reload connection
- community.general.nmcli:
- conn_name: my-eth1
- mtu: 1500
- type: ethernet
- state: present
- conn_reload: true
+ - name: Change the property of a setting e.g. MTU and reload connection
+ community.general.nmcli:
+ conn_name: my-eth1
+ mtu: 1500
+ type: ethernet
+ state: present
+ conn_reload: true
- - name: Disable connection
- community.general.nmcli:
- conn_name: my-eth1
- state: down
+ - name: Disable connection
+ community.general.nmcli:
+ conn_name: my-eth1
+ state: down
- - name: Reload and enable connection
- community.general.nmcli:
- conn_name: my-eth1
- state: up
- reload: true
+ - name: Reload and enable connection
+ community.general.nmcli:
+ conn_name: my-eth1
+ state: up
+ reload: true
- - name: Add second ip4 address
- community.general.nmcli:
- conn_name: my-eth1
- ifname: eth1
- type: ethernet
- ip4:
- - 192.0.2.100/24
- - 192.0.3.100/24
- state: present
+ - name: Add second ip4 address
+ community.general.nmcli:
+ conn_name: my-eth1
+ ifname: eth1
+ type: ethernet
+ ip4:
+ - 192.0.2.100/24
+ - 192.0.3.100/24
+ state: present
- - name: Add second ip6 address
- community.general.nmcli:
- conn_name: my-eth1
- ifname: eth1
- type: ethernet
- ip6:
- - 2001:db8::cafe
- - 2002:db8::cafe
- state: present
+ - name: Add second ip6 address
+ community.general.nmcli:
+ conn_name: my-eth1
+ ifname: eth1
+ type: ethernet
+ ip6:
+ - 2001:db8::cafe
+ - 2002:db8::cafe
+ state: present
- - name: Add VxLan
- community.general.nmcli:
- type: vxlan
- conn_name: vxlan_test1
- vxlan_id: 16
- vxlan_local: 192.168.1.2
- vxlan_remote: 192.168.1.5
+ - name: Add VxLan
+ community.general.nmcli:
+ type: vxlan
+ conn_name: vxlan_test1
+ vxlan_id: 16
+ vxlan_local: 192.168.1.2
+ vxlan_remote: 192.168.1.5
- - name: Add gre
- community.general.nmcli:
- type: gre
- conn_name: gre_test1
- ip_tunnel_dev: eth0
- ip_tunnel_local: 192.168.1.2
- ip_tunnel_remote: 192.168.1.5
+ - name: Add gre
+ community.general.nmcli:
+ type: gre
+ conn_name: gre_test1
+ ip_tunnel_dev: eth0
+ ip_tunnel_local: 192.168.1.2
+ ip_tunnel_remote: 192.168.1.5
- - name: Add ipip
- community.general.nmcli:
- type: ipip
- conn_name: ipip_test1
- ip_tunnel_dev: eth0
- ip_tunnel_local: 192.168.1.2
- ip_tunnel_remote: 192.168.1.5
+ - name: Add ipip
+ community.general.nmcli:
+ type: ipip
+ conn_name: ipip_test1
+ ip_tunnel_dev: eth0
+ ip_tunnel_local: 192.168.1.2
+ ip_tunnel_remote: 192.168.1.5
- - name: Add sit
- community.general.nmcli:
- type: sit
- conn_name: sit_test1
- ip_tunnel_dev: eth0
- ip_tunnel_local: 192.168.1.2
- ip_tunnel_remote: 192.168.1.5
+ - name: Add sit
+ community.general.nmcli:
+ type: sit
+ conn_name: sit_test1
+ ip_tunnel_dev: eth0
+ ip_tunnel_local: 192.168.1.2
+ ip_tunnel_remote: 192.168.1.5
- - name: Add zone
- community.general.nmcli:
- type: ethernet
- conn_name: my-eth1
- zone: external
- state: present
+ - name: Add zone
+ community.general.nmcli:
+ type: ethernet
+ conn_name: my-eth1
+ zone: external
+ state: present
# nmcli exits with status 0 if it succeeds and exits with a status greater
# than zero when there is a failure. The following list of status codes may be
@@ -1442,10 +1495,10 @@ EXAMPLES = r'''
conn_name: my-gsm-provider
ifname: cdc-wdm0
gsm:
- apn: my.provider.apn
- username: my-provider-username
- password: my-provider-password
- pin: my-sim-pin
+ apn: my.provider.apn
+ username: my-provider-username
+ password: my-provider-password
+ pin: my-sim-pin
autoconnect: true
state: present
@@ -1455,8 +1508,8 @@ EXAMPLES = r'''
conn_name: my-macvlan-connection
ifname: mymacvlan0
macvlan:
- mode: 2
- parent: eth1
+ mode: 2
+ parent: eth1
autoconnect: true
state: present
@@ -1466,8 +1519,8 @@ EXAMPLES = r'''
conn_name: my-wg-provider
ifname: mywg0
wireguard:
- listen-port: 51820
- private-key: my-private-key
+ listen-port: 51820
+ private-key: my-private-key
autoconnect: true
state: present
@@ -1478,13 +1531,13 @@ EXAMPLES = r'''
type: vpn
conn_name: my-vpn-connection
vpn:
- permissions: "{{ ansible_user }}"
- service-type: org.freedesktop.NetworkManager.l2tp
- gateway: vpn.example.com
- password-flags: 2
- user: brittany
- ipsec-enabled: true
- ipsec-psk: "0s{{ 'Brittany123' | ansible.builtin.b64encode }}"
+ permissions: "{{ ansible_user }}"
+ service-type: org.freedesktop.NetworkManager.l2tp
+ gateway: vpn.example.com
+ password-flags: 2
+ user: brittany
+ ipsec-enabled: true
+ ipsec-psk: "0s{{ 'Brittany123' | ansible.builtin.b64encode }}"
autoconnect: false
state: present
@@ -1522,6 +1575,29 @@ EXAMPLES = r'''
vlanid: 5
state: present
+## Creating VRF and adding VLAN interface to it
+- name: Create VRF
+ community.general.nmcli:
+ type: vrf
+ ifname: vrf10
+ table: 10
+ state: present
+ conn_name: vrf10
+ method4: disabled
+ method6: disabled
+
+- name: Create VLAN interface inside VRF
+ community.general.nmcli:
+ conn_name: "eth0.124"
+ type: vlan
+ vlanid: "124"
+ vlandev: "eth0"
+ master: "vrf10"
+ slave_type: vrf
+ state: "present"
+ ip4: '192.168.124.50'
+ gw4: '192.168.124.1'
+
## Defining ip rules while setting a static IP
## table 'production' is set with id 200 in this example.
- name: Set Static ips for interface with ip rules and routes
@@ -1563,7 +1639,7 @@ EXAMPLES = r'''
slave_type: ovs-port
type: ethernet
state: present
-'''
+"""
RETURN = r"""#
"""
@@ -1650,6 +1726,7 @@ class Nmcli(object):
self.downdelay = module.params['downdelay']
self.updelay = module.params['updelay']
self.xmit_hash_policy = module.params['xmit_hash_policy']
+ self.fail_over_mac = module.params['fail_over_mac']
self.arp_interval = module.params['arp_interval']
self.arp_ip_target = module.params['arp_ip_target']
self.slavepriority = module.params['slavepriority']
@@ -1687,6 +1764,7 @@ class Nmcli(object):
self.wireguard = module.params['wireguard']
self.vpn = module.params['vpn']
self.transport_mode = module.params['transport_mode']
+ self.sriov = module.params['sriov']
if self.method4:
self.ipv4_method = self.method4
@@ -1706,6 +1784,9 @@ class Nmcli(object):
else:
self.ipv6_method = None
+ if self.type == "vrf":
+ self.table = module.params['table']
+
self.edit_commands = []
self.extra_options_validation()
@@ -1738,7 +1819,8 @@ class Nmcli(object):
# IP address options.
# The ovs-interface type can be both ip_conn_type and have a master
- if (self.ip_conn_type and not self.master) or self.type == "ovs-interface":
+ # An interface that has a master but is of slave type vrf can have an IP address
+ if (self.ip_conn_type and (not self.master or self.slave_type == "vrf")) or self.type == "ovs-interface":
options.update({
'ipv4.addresses': self.enforce_ipv4_cidr_notation(self.ip4),
'ipv4.dhcp-client-id': self.dhcp_client_id,
@@ -1797,6 +1879,7 @@ class Nmcli(object):
'primary': self.primary,
'updelay': self.updelay,
'xmit_hash_policy': self.xmit_hash_policy,
+ 'fail_over_mac': self.fail_over_mac,
})
elif self.type == 'bond-slave':
if self.slave_type and self.slave_type != 'bond':
@@ -1951,6 +2034,17 @@ class Nmcli(object):
options.update({
'infiniband.transport-mode': self.transport_mode,
})
+ elif self.type == 'vrf':
+ options.update({
+ 'table': self.table,
+ })
+
+ if self.type == 'ethernet':
+ if self.sriov:
+ for name, value in self.sriov.items():
+ options.update({
+ 'sriov.%s' % name: value,
+ })
# Convert settings values based on the situation.
for setting, value in options.items():
@@ -2000,6 +2094,7 @@ class Nmcli(object):
'vpn',
'loopback',
'ovs-interface',
+ 'vrf'
)
@property
@@ -2237,6 +2332,9 @@ class Nmcli(object):
if key == 'xmit_hash_policy':
cmd.extend(['+bond.options', 'xmit_hash_policy=%s' % value])
continue
+ if key == 'fail_over_mac':
+ cmd.extend(['+bond.options', 'fail_over_mac=%s' % value])
+ continue
cmd.extend([key, value])
return self.execute_command(cmd)
@@ -2416,9 +2514,11 @@ class Nmcli(object):
if isinstance(current_value, list) and isinstance(value, list):
# compare values between two lists
- if key in ('ipv4.addresses', 'ipv6.addresses'):
+ if key in ('ipv4.addresses', 'ipv6.addresses', 'ipv4.dns', 'ipv6.dns', 'ipv4.dns-search', 'ipv6.dns-search'):
# The order of IP addresses matters because the first one
# is the default source address for outbound connections.
+ # Similarly, the order of DNS nameservers and search
+ # suffixes is important.
changed |= current_value != value
else:
changed |= sorted(current_value) != sorted(value)
@@ -2468,7 +2568,7 @@ def main():
conn_name=dict(type='str', required=True),
conn_reload=dict(type='bool', default=False),
master=dict(type='str'),
- slave_type=dict(type='str', choices=['bond', 'bridge', 'team', 'ovs-port']),
+ slave_type=dict(type='str', choices=['bond', 'bridge', 'team', 'ovs-port', 'vrf']),
ifname=dict(type='str'),
type=dict(type='str',
choices=[
@@ -2496,6 +2596,7 @@ def main():
'ovs-interface',
'ovs-bridge',
'ovs-port',
+ 'vrf',
]),
ip4=dict(type='list', elements='str'),
gw4=dict(type='str'),
@@ -2553,6 +2654,7 @@ def main():
downdelay=dict(type='int'),
updelay=dict(type='int'),
xmit_hash_policy=dict(type='str'),
+ fail_over_mac=dict(type='str', choices=['none', 'active', 'follow']),
arp_interval=dict(type='int'),
arp_ip_target=dict(type='str'),
primary=dict(type='str'),
@@ -2607,6 +2709,8 @@ def main():
wireguard=dict(type='dict'),
vpn=dict(type='dict'),
transport_mode=dict(type='str', choices=['datagram', 'connected']),
+ sriov=dict(type='dict'),
+ table=dict(type='int'),
),
mutually_exclusive=[['never_default4', 'gw4'],
['routes4_extended', 'routes4'],
diff --git a/plugins/modules/nomad_job.py b/plugins/modules/nomad_job.py
index 87e8ec04ca..9b3a670cd9 100644
--- a/plugins/modules/nomad_job.py
+++ b/plugins/modules/nomad_job.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: nomad_job
author: FERREIRA Christophe (@chris93111)
version_added: "1.3.0"
@@ -17,53 +16,53 @@ short_description: Launch a Nomad Job
description:
- Launch a Nomad job.
- Stop a Nomad job.
- - Force start a Nomad job
+ - Force start a Nomad job.
requirements:
- python-nomad
extends_documentation_fragment:
- community.general.nomad
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of job for delete, stop and start job without source.
- - Name of job for delete, stop and start job without source.
- - Either this or O(content) must be specified.
- type: str
- state:
- description:
- - Deploy or remove job.
- choices: ["present", "absent"]
- required: true
- type: str
- force_start:
- description:
- - Force job to started.
- type: bool
- default: false
- content:
- description:
- - Content of Nomad job.
- - Either this or O(name) must be specified.
- type: str
- content_format:
- description:
- - Type of content of Nomad job.
- choices: ["hcl", "json"]
- default: hcl
- type: str
+ name:
+ description:
+ - Name of job for delete, stop and start job without source.
+ - Name of job for delete, stop and start job without source.
+ - Either this or O(content) must be specified.
+ type: str
+ state:
+ description:
+ - Deploy or remove job.
+ choices: ["present", "absent"]
+ required: true
+ type: str
+ force_start:
+ description:
+ - Force job to started.
+ type: bool
+ default: false
+ content:
+ description:
+ - Content of Nomad job.
+ - Either this or O(name) must be specified.
+ type: str
+ content_format:
+ description:
+ - Type of content of Nomad job.
+ choices: ["hcl", "json"]
+ default: hcl
+ type: str
seealso:
- name: Nomad jobs documentation
description: Complete documentation for Nomad API jobs.
link: https://www.nomadproject.io/api-docs/jobs/
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create job
community.general.nomad_job:
host: localhost
@@ -92,7 +91,7 @@ EXAMPLES = '''
name: api
timeout: 120
force_start: true
-'''
+"""
import json
diff --git a/plugins/modules/nomad_job_info.py b/plugins/modules/nomad_job_info.py
index bd7cf8ca98..0a5c81cf15 100644
--- a/plugins/modules/nomad_job_info.py
+++ b/plugins/modules/nomad_job_info.py
@@ -8,15 +8,14 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: nomad_job_info
author: FERREIRA Christophe (@chris93111)
version_added: "1.3.0"
short_description: Get Nomad Jobs info
description:
- - Get info for one Nomad job.
- - List Nomad jobs.
+ - Get info for one Nomad job.
+ - List Nomad jobs.
requirements:
- python-nomad
extends_documentation_fragment:
@@ -24,18 +23,18 @@ extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.info_module
options:
- name:
- description:
- - Name of job for Get info.
- - If not specified, lists all jobs.
- type: str
+ name:
+ description:
+ - Name of job for Get info.
+ - If not specified, lists all jobs.
+ type: str
seealso:
- name: Nomad jobs documentation
description: Complete documentation for Nomad API jobs.
link: https://www.nomadproject.io/api-docs/jobs/
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get info for job awx
community.general.nomad_job_info:
host: localhost
@@ -46,10 +45,9 @@ EXAMPLES = '''
community.general.nomad_job_info:
host: localhost
register: result
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
result:
description: List with dictionary contains jobs info
returned: success
@@ -264,7 +262,7 @@ result:
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible.module_utils.common.text.converters import to_native
diff --git a/plugins/modules/nomad_token.py b/plugins/modules/nomad_token.py
index 51a2f97163..07abd9d7c3 100644
--- a/plugins/modules/nomad_token.py
+++ b/plugins/modules/nomad_token.py
@@ -9,60 +9,59 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: nomad_token
author: Pedro Nascimento (@apecnascimento)
version_added: "8.1.0"
short_description: Manage Nomad ACL tokens
description:
- - This module allows to create Bootstrap tokens, create ACL tokens, update ACL tokens, and delete ACL tokens.
+ - This module allows to create Bootstrap tokens, create ACL tokens, update ACL tokens, and delete ACL tokens.
requirements:
- - python-nomad
+ - python-nomad
extends_documentation_fragment:
- - community.general.nomad
- - community.general.attributes
+ - community.general.nomad
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of ACL token to create.
- type: str
- token_type:
- description:
- - The type of the token can be V(client), V(management), or V(bootstrap).
- choices: ["client", "management", "bootstrap"]
- type: str
- default: "client"
- policies:
- description:
- - A list of the policies assigned to the token.
- type: list
- elements: str
- default: []
- global_replicated:
- description:
- - Indicates whether or not the token was created with the C(--global).
- type: bool
- default: false
- state:
- description:
- - Create or remove ACL token.
- choices: ["present", "absent"]
- required: true
- type: str
+ name:
+ description:
+ - Name of ACL token to create.
+ type: str
+ token_type:
+ description:
+ - The type of the token can be V(client), V(management), or V(bootstrap).
+ choices: ["client", "management", "bootstrap"]
+ type: str
+ default: "client"
+ policies:
+ description:
+ - A list of the policies assigned to the token.
+ type: list
+ elements: str
+ default: []
+ global_replicated:
+ description:
+ - Indicates whether or not the token was created with the C(--global).
+ type: bool
+ default: false
+ state:
+ description:
+ - Create or remove ACL token.
+ choices: ["present", "absent"]
+ required: true
+ type: str
seealso:
- name: Nomad ACL documentation
description: Complete documentation for Nomad API ACL.
link: https://developer.hashicorp.com/nomad/api-docs/acl/tokens
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create boostrap token
community.general.nomad_token:
host: localhost
@@ -75,7 +74,7 @@ EXAMPLES = '''
name: "Dev token"
token_type: client
policies:
- - readonly
+ - readonly
global_replicated: false
state: absent
@@ -85,8 +84,8 @@ EXAMPLES = '''
name: "Dev token"
token_type: client
policies:
- - readonly
- - devpolicy
+ - readonly
+ - devpolicy
global_replicated: false
state: absent
@@ -95,9 +94,9 @@ EXAMPLES = '''
host: localhost
name: "Dev token"
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
result:
description: Result returned by nomad.
returned: always
@@ -119,7 +118,7 @@ result:
"secret_id": "12e878ab-e1f6-e103-b4c4-3b5173bb4cea",
"type": "client"
}
-'''
+"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible.module_utils.common.text.converters import to_native
diff --git a/plugins/modules/nosh.py b/plugins/modules/nosh.py
index 0e03142d81..da9db091bc 100644
--- a/plugins/modules/nosh.py
+++ b/plugins/modules/nosh.py
@@ -9,67 +9,61 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: nosh
author:
- - "Thomas Caravia (@tacatac)"
+ - "Thomas Caravia (@tacatac)"
short_description: Manage services with nosh
description:
- - Control running and enabled state for system-wide or user services.
- - BSD and Linux systems are supported.
+ - Control running and enabled state for system-wide or user services.
+ - BSD and Linux systems are supported.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- type: str
- required: true
- description:
- - Name of the service to manage.
- state:
- type: str
- required: false
- choices: [ started, stopped, reset, restarted, reloaded ]
- description:
- - V(started)/V(stopped) are idempotent actions that will not run
- commands unless necessary.
- V(restarted) will always bounce the service.
- V(reloaded) will send a SIGHUP or start the service.
- V(reset) will start or stop the service according to whether it is
- enabled or not.
- enabled:
- required: false
- type: bool
- description:
- - Enable or disable the service, independently of C(*.preset) file
- preference or running state. Mutually exclusive with O(preset). Will take
- effect prior to O(state=reset).
- preset:
- required: false
- type: bool
- description:
- - Enable or disable the service according to local preferences in C(*.preset) files.
- Mutually exclusive with O(enabled). Only has an effect if set to true. Will take
- effect prior to O(state=reset).
- user:
- required: false
- default: false
- type: bool
- description:
- - Run system-control talking to the calling user's service manager, rather than
- the system-wide service manager.
+ name:
+ type: str
+ required: true
+ description:
+ - Name of the service to manage.
+ state:
+ type: str
+ required: false
+ choices: [started, stopped, reset, restarted, reloaded]
+ description:
+ - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
+ - V(restarted) will always bounce the service.
+ - V(reloaded) will send a SIGHUP or start the service.
+ - V(reset) will start or stop the service according to whether it is enabled or not.
+ enabled:
+ required: false
+ type: bool
+ description:
+ - Enable or disable the service, independently of C(*.preset) file preference or running state. Mutually exclusive with
+ O(preset). Will take effect prior to O(state=reset).
+ preset:
+ required: false
+ type: bool
+ description:
+ - Enable or disable the service according to local preferences in C(*.preset) files. Mutually exclusive with O(enabled).
+ Only has an effect if set to true. Will take effect prior to O(state=reset).
+ user:
+ required: false
+ default: false
+ type: bool
+ description:
+ - Run system-control talking to the calling user's service manager, rather than the system-wide service manager.
requirements:
- - A system with an active nosh service manager, see Notes for further information.
+ - A system with an active nosh service manager, see Notes for further information.
notes:
- - Information on the nosh utilities suite may be found at U(https://jdebp.eu/Softwares/nosh/).
-'''
+ - Information on the nosh utilities suite may be found at U(https://jdebp.eu/Softwares/nosh/).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Start dnscache if not running
community.general.nosh:
name: dnscache
@@ -122,215 +116,216 @@ EXAMPLES = '''
ansible.builtin.fail:
msg: "The {{ result.name }} service is running"
when: result.status and result.status['DaemontoolsEncoreState'] == "running"
-'''
+"""
-RETURN = '''
+RETURN = r"""
name:
- description: name used to find the service
- returned: success
- type: str
- sample: "sshd"
+ description: Name used to find the service.
+ returned: success
+ type: str
+ sample: "sshd"
service_path:
- description: resolved path for the service
- returned: success
- type: str
- sample: "/var/sv/sshd"
+ description: Resolved path for the service.
+ returned: success
+ type: str
+ sample: "/var/sv/sshd"
enabled:
- description: whether the service is enabled at system bootstrap
- returned: success
- type: bool
- sample: true
+ description: Whether the service is enabled at system bootstrap.
+ returned: success
+ type: bool
+ sample: true
preset:
- description: whether the enabled status reflects the one set in the relevant C(*.preset) file
- returned: success
- type: bool
- sample: 'False'
+ description: Whether the enabled status reflects the one set in the relevant C(*.preset) file.
+ returned: success
+ type: bool
+ sample: 'False'
state:
- description: service process run state, V(none) if the service is not loaded and will not be started
- returned: if state option is used
- type: str
- sample: "reloaded"
+ description: Service process run state, V(none) if the service is not loaded and will not be started.
+ returned: if state option is used
+ type: str
+ sample: "reloaded"
status:
- description: A dictionary with the key=value pairs returned by C(system-control show-json) or V(none) if the service is not loaded
- returned: success
- type: complex
- contains:
- After:
- description: [] # FIXME
- returned: success
- type: list
- sample: ["/etc/service-bundles/targets/basic","../sshdgenkeys", "log"]
- Before:
- description: [] # FIXME
- returned: success
- type: list
- sample: ["/etc/service-bundles/targets/shutdown"]
- Conflicts:
- description: [] # FIXME
- returned: success
- type: list
- sample: []
- DaemontoolsEncoreState:
- description: [] # FIXME
- returned: success
- type: str
- sample: "running"
- DaemontoolsState:
- description: [] # FIXME
- returned: success
- type: str
- sample: "up"
- Enabled:
- description: [] # FIXME
- returned: success
- type: bool
- sample: true
- LogService:
- description: [] # FIXME
- returned: success
- type: str
- sample: "../cyclog@sshd"
- MainPID:
- description: [] # FIXME
- returned: success
- type: int
- sample: 661
- Paused:
- description: [] # FIXME
- returned: success
- type: bool
- sample: 'False'
- ReadyAfterRun:
- description: [] # FIXME
- returned: success
- type: bool
- sample: 'False'
- RemainAfterExit:
- description: [] # FIXME
- returned: success
- type: bool
- sample: 'False'
- Required-By:
- description: [] # FIXME
- returned: success
- type: list
- sample: []
- RestartExitStatusCode:
- description: [] # FIXME
- returned: success
- type: int
- sample: '0'
- RestartExitStatusNumber:
- description: [] # FIXME
- returned: success
- type: int
- sample: '0'
- RestartTimestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 4611686019935648081
- RestartUTCTimestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 1508260140
- RunExitStatusCode:
- description: [] # FIXME
- returned: success
- type: int
- sample: '0'
- RunExitStatusNumber:
- description: [] # FIXME
- returned: success
- type: int
- sample: '0'
- RunTimestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 4611686019935648081
- RunUTCTimestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 1508260140
- StartExitStatusCode:
- description: [] # FIXME
- returned: success
- type: int
- sample: 1
- StartExitStatusNumber:
- description: [] # FIXME
- returned: success
- type: int
- sample: '0'
- StartTimestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 4611686019935648081
- StartUTCTimestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 1508260140
- StopExitStatusCode:
- description: [] # FIXME
- returned: success
- type: int
- sample: '0'
- StopExitStatusNumber:
- description: [] # FIXME
- returned: success
- type: int
- sample: '0'
- StopTimestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 4611686019935648081
- StopUTCTimestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 1508260140
- Stopped-By:
- description: [] # FIXME
- returned: success
- type: list
- sample: ["/etc/service-bundles/targets/shutdown"]
- Timestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 4611686019935648081
- UTCTimestamp:
- description: [] # FIXME
- returned: success
- type: int
- sample: 1508260140
- Want:
- description: [] # FIXME
- returned: success
- type: str
- sample: "nothing"
- Wanted-By:
- description: [] # FIXME
- returned: success
- type: list
- sample: ["/etc/service-bundles/targets/server","/etc/service-bundles/targets/sockets"]
- Wants:
- description: [] # FIXME
- returned: success
- type: list
- sample: ["/etc/service-bundles/targets/basic","../sshdgenkeys"]
+ description: A dictionary with the key=value pairs returned by C(system-control show-json) or V(none) if the service is
+ not loaded.
+ returned: success
+ type: complex
+ contains:
+ After:
+ description: [] # FIXME
+ returned: success
+ type: list
+ sample: ["/etc/service-bundles/targets/basic", "../sshdgenkeys", "log"]
+ Before:
+ description: [] # FIXME
+ returned: success
+ type: list
+ sample: ["/etc/service-bundles/targets/shutdown"]
+ Conflicts:
+ description: [] # FIXME
+ returned: success
+ type: list
+ sample: []
+ DaemontoolsEncoreState:
+ description: [] # FIXME
+ returned: success
+ type: str
+ sample: "running"
+ DaemontoolsState:
+ description: [] # FIXME
+ returned: success
+ type: str
+ sample: "up"
+ Enabled:
+ description: [] # FIXME
+ returned: success
+ type: bool
+ sample: true
+ LogService:
+ description: [] # FIXME
+ returned: success
+ type: str
+ sample: "../cyclog@sshd"
+ MainPID:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 661
+ Paused:
+ description: [] # FIXME
+ returned: success
+ type: bool
+ sample: 'False'
+ ReadyAfterRun:
+ description: [] # FIXME
+ returned: success
+ type: bool
+ sample: 'False'
+ RemainAfterExit:
+ description: [] # FIXME
+ returned: success
+ type: bool
+ sample: 'False'
+ Required-By:
+ description: [] # FIXME
+ returned: success
+ type: list
+ sample: []
+ RestartExitStatusCode:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: '0'
+ RestartExitStatusNumber:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: '0'
+ RestartTimestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 4611686019935648081
+ RestartUTCTimestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 1508260140
+ RunExitStatusCode:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: '0'
+ RunExitStatusNumber:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: '0'
+ RunTimestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 4611686019935648081
+ RunUTCTimestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 1508260140
+ StartExitStatusCode:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 1
+ StartExitStatusNumber:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: '0'
+ StartTimestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 4611686019935648081
+ StartUTCTimestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 1508260140
+ StopExitStatusCode:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: '0'
+ StopExitStatusNumber:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: '0'
+ StopTimestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 4611686019935648081
+ StopUTCTimestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 1508260140
+ Stopped-By:
+ description: [] # FIXME
+ returned: success
+ type: list
+ sample: ["/etc/service-bundles/targets/shutdown"]
+ Timestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 4611686019935648081
+ UTCTimestamp:
+ description: [] # FIXME
+ returned: success
+ type: int
+ sample: 1508260140
+ Want:
+ description: [] # FIXME
+ returned: success
+ type: str
+ sample: "nothing"
+ Wanted-By:
+ description: [] # FIXME
+ returned: success
+ type: list
+ sample: ["/etc/service-bundles/targets/server", "/etc/service-bundles/targets/sockets"]
+ Wants:
+ description: [] # FIXME
+ returned: success
+ type: list
+ sample: ["/etc/service-bundles/targets/basic", "../sshdgenkeys"]
user:
- description: whether the user-level service manager is called
- returned: success
- type: bool
- sample: false
-'''
+ description: Whether the user-level service manager is called.
+ returned: success
+ type: bool
+ sample: false
+"""
import json
diff --git a/plugins/modules/npm.py b/plugins/modules/npm.py
index a906b2c127..25b116f2e8 100644
--- a/plugins/modules/npm.py
+++ b/plugins/modules/npm.py
@@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: npm
short_description: Manage node.js packages with npm
description:
@@ -83,7 +82,7 @@ options:
required: false
type: str
default: present
- choices: [ "present", "absent", "latest" ]
+ choices: ["present", "absent", "latest"]
no_optional:
description:
- Use the C(--no-optional) flag when installing.
@@ -103,10 +102,10 @@ options:
default: false
version_added: 9.5.0
requirements:
- - npm installed in bin path (recommended /usr/local/bin)
-'''
+ - npm installed in bin path (recommended /usr/local/bin)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Install "coffee-script" node.js package.
community.general.npm:
name: coffee-script
@@ -153,7 +152,7 @@ EXAMPLES = r'''
path: /app/location
executable: /opt/nvm/v0.10.1/bin/npm
state: present
-'''
+"""
import json
import os
diff --git a/plugins/modules/nsupdate.py b/plugins/modules/nsupdate.py
index c9a6ba2133..9f665626b2 100644
--- a/plugins/modules/nsupdate.py
+++ b/plugins/modules/nsupdate.py
@@ -14,89 +14,87 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: nsupdate
short_description: Manage DNS records
description:
- - Create, update and remove DNS records using DDNS updates
+ - Create, update and remove DNS records using DDNS updates.
requirements:
- dnspython
author: "Loic Blot (@nerzhul)"
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Manage DNS record.
- choices: ['present', 'absent']
- default: 'present'
- type: str
- server:
- description:
- - Apply DNS modification on this server, specified by IPv4 or IPv6 address.
- required: true
- type: str
- port:
- description:
- - Use this TCP port when connecting to O(server).
- default: 53
- type: int
- key_name:
- description:
- - Use TSIG key name to authenticate against DNS O(server)
- type: str
- key_secret:
- description:
- - Use TSIG key secret, associated with O(key_name), to authenticate against O(server)
- type: str
- key_algorithm:
- description:
- - Specify key algorithm used by O(key_secret).
- choices: ['HMAC-MD5.SIG-ALG.REG.INT', 'hmac-md5', 'hmac-sha1', 'hmac-sha224', 'hmac-sha256', 'hmac-sha384',
- 'hmac-sha512']
- default: 'hmac-md5'
- type: str
- zone:
- description:
- - DNS record will be modified on this O(zone).
- - When omitted DNS will be queried to attempt finding the correct zone.
- type: str
- record:
- description:
- - Sets the DNS record to modify. When zone is omitted this has to be absolute (ending with a dot).
- required: true
- type: str
- type:
- description:
- - Sets the record type.
- default: 'A'
- type: str
- ttl:
- description:
- - Sets the record TTL.
- default: 3600
- type: int
- value:
- description:
- - Sets the record value.
- type: list
- elements: str
- protocol:
- description:
- - Sets the transport protocol (TCP or UDP). TCP is the recommended and a more robust option.
- default: 'tcp'
- choices: ['tcp', 'udp']
- type: str
-'''
+ state:
+ description:
+ - Manage DNS record.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+ server:
+ description:
+ - Apply DNS modification on this server, specified by IPv4 or IPv6 address.
+ required: true
+ type: str
+ port:
+ description:
+ - Use this TCP port when connecting to O(server).
+ default: 53
+ type: int
+ key_name:
+ description:
+ - Use TSIG key name to authenticate against DNS O(server).
+ type: str
+ key_secret:
+ description:
+ - Use TSIG key secret, associated with O(key_name), to authenticate against O(server).
+ type: str
+ key_algorithm:
+ description:
+ - Specify key algorithm used by O(key_secret).
+ choices: ['HMAC-MD5.SIG-ALG.REG.INT', 'hmac-md5', 'hmac-sha1', 'hmac-sha224', 'hmac-sha256', 'hmac-sha384', 'hmac-sha512']
+ default: 'hmac-md5'
+ type: str
+ zone:
+ description:
+ - DNS record will be modified on this O(zone).
+ - When omitted DNS will be queried to attempt finding the correct zone.
+ type: str
+ record:
+ description:
+ - Sets the DNS record to modify. When zone is omitted this has to be absolute (ending with a dot).
+ required: true
+ type: str
+ type:
+ description:
+ - Sets the record type.
+ default: 'A'
+ type: str
+ ttl:
+ description:
+ - Sets the record TTL.
+ default: 3600
+ type: int
+ value:
+ description:
+ - Sets the record value.
+ type: list
+ elements: str
+ protocol:
+ description:
+ - Sets the transport protocol (TCP or UDP). TCP is the recommended and a more robust option.
+ default: 'tcp'
+ choices: ['tcp', 'udp']
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add or modify ansible.example.org A to 192.168.1.1"
community.general.nsupdate:
key_name: "nsupdate"
@@ -143,49 +141,49 @@ EXAMPLES = '''
record: "1.1.168.192.in-addr.arpa."
type: "PTR"
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
changed:
- description: If module has modified record
- returned: success
- type: str
+ description: If module has modified record.
+ returned: success
+ type: str
record:
- description: DNS record
- returned: success
- type: str
- sample: 'ansible'
+ description: DNS record.
+ returned: success
+ type: str
+ sample: 'ansible'
ttl:
- description: DNS record TTL
- returned: success
- type: int
- sample: 86400
+ description: DNS record TTL.
+ returned: success
+ type: int
+ sample: 86400
type:
- description: DNS record type
- returned: success
- type: str
- sample: 'CNAME'
+ description: DNS record type.
+ returned: success
+ type: str
+ sample: 'CNAME'
value:
- description: DNS record value(s)
- returned: success
- type: list
- sample: '192.168.1.1'
+ description: DNS record value(s).
+ returned: success
+ type: list
+ sample: '192.168.1.1'
zone:
- description: DNS record zone
- returned: success
- type: str
- sample: 'example.org.'
+ description: DNS record zone.
+ returned: success
+ type: str
+ sample: 'example.org.'
dns_rc:
- description: dnspython return code
- returned: always
- type: int
- sample: 4
+ description: C(dnspython) return code.
+ returned: always
+ type: int
+ sample: 4
dns_rc_str:
- description: dnspython return code (string representation)
- returned: always
- type: str
- sample: 'REFUSED'
-'''
+ description: C(dnspython) return code (string representation).
+ returned: always
+ type: str
+ sample: 'REFUSED'
+"""
import traceback
diff --git a/plugins/modules/ocapi_command.py b/plugins/modules/ocapi_command.py
index b6b9b6b98e..39269c99cb 100644
--- a/plugins/modules/ocapi_command.py
+++ b/plugins/modules/ocapi_command.py
@@ -8,14 +8,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ocapi_command
version_added: 6.3.0
short_description: Manages Out-Of-Band controllers using Open Composable API (OCAPI)
description:
- - Builds OCAPI URIs locally and sends them to remote OOB controllers to
- perform an action.
+ - Builds OCAPI URIs locally and sends them to remote OOB controllers to perform an action.
- Manages OOB controller such as Indicator LED, Reboot, Power Mode, Firmware Update.
extends_documentation_fragment:
- community.general.attributes
@@ -41,7 +39,7 @@ options:
- Base URI of OOB controller.
type: str
proxy_slot_number:
- description: For proxied inband requests, the slot number of the IOM. Only applies if O(baseuri) is a proxy server.
+ description: For proxied inband requests, the slot number of the IOM. Only applies if O(baseuri) is a proxy server.
type: int
update_image_path:
required: false
@@ -70,104 +68,104 @@ options:
type: int
author: "Mike Moerk (@mikemoerk)"
-'''
+"""
-EXAMPLES = '''
- - name: Set the power state to low
- community.general.ocapi_command:
- category: Chassis
- command: PowerModeLow
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+EXAMPLES = r"""
+- name: Set the power state to low
+ community.general.ocapi_command:
+ category: Chassis
+ command: PowerModeLow
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set the power state to normal
- community.general.ocapi_command:
- category: Chassis
- command: PowerModeNormal
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- - name: Set chassis indicator LED to on
- community.general.ocapi_command:
- category: Chassis
- command: IndicatorLedOn
- baseuri: "{{ baseuri }}"
- proxy_slot_number: 2
- username: "{{ username }}"
- password: "{{ password }}"
- - name: Set chassis indicator LED to off
- community.general.ocapi_command:
- category: Chassis
- command: IndicatorLedOff
- baseuri: "{{ baseuri }}"
- proxy_slot_number: 2
- username: "{{ username }}"
- password: "{{ password }}"
- - name: Reset Enclosure
- community.general.ocapi_command:
- category: Systems
- command: PowerGracefulRestart
- baseuri: "{{ baseuri }}"
- proxy_slot_number: 2
- username: "{{ username }}"
- password: "{{ password }}"
- - name: Firmware Upload
- community.general.ocapi_command:
- category: Update
- command: FWUpload
- baseuri: "iom1.wdc.com"
- proxy_slot_number: 2
- username: "{{ username }}"
- password: "{{ password }}"
- update_image_path: "/path/to/firmware.tar.gz"
- - name: Firmware Update
- community.general.ocapi_command:
- category: Update
- command: FWUpdate
- baseuri: "iom1.wdc.com"
- proxy_slot_number: 2
- username: "{{ username }}"
- password: "{{ password }}"
- - name: Firmware Activate
- community.general.ocapi_command:
- category: Update
- command: FWActivate
- baseuri: "iom1.wdc.com"
- proxy_slot_number: 2
- username: "{{ username }}"
- password: "{{ password }}"
- - name: Delete Job
- community.general.ocapi_command:
- category: Jobs
- command: DeleteJob
- job_name: FirmwareUpdate
- baseuri: "{{ baseuri }}"
- proxy_slot_number: 2
- username: "{{ username }}"
- password: "{{ password }}"
-'''
+- name: Set the power state to normal
+ community.general.ocapi_command:
+ category: Chassis
+ command: PowerModeNormal
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+- name: Set chassis indicator LED to on
+ community.general.ocapi_command:
+ category: Chassis
+ command: IndicatorLedOn
+ baseuri: "{{ baseuri }}"
+ proxy_slot_number: 2
+ username: "{{ username }}"
+ password: "{{ password }}"
+- name: Set chassis indicator LED to off
+ community.general.ocapi_command:
+ category: Chassis
+ command: IndicatorLedOff
+ baseuri: "{{ baseuri }}"
+ proxy_slot_number: 2
+ username: "{{ username }}"
+ password: "{{ password }}"
+- name: Reset Enclosure
+ community.general.ocapi_command:
+ category: Systems
+ command: PowerGracefulRestart
+ baseuri: "{{ baseuri }}"
+ proxy_slot_number: 2
+ username: "{{ username }}"
+ password: "{{ password }}"
+- name: Firmware Upload
+ community.general.ocapi_command:
+ category: Update
+ command: FWUpload
+ baseuri: "iom1.wdc.com"
+ proxy_slot_number: 2
+ username: "{{ username }}"
+ password: "{{ password }}"
+ update_image_path: "/path/to/firmware.tar.gz"
+- name: Firmware Update
+ community.general.ocapi_command:
+ category: Update
+ command: FWUpdate
+ baseuri: "iom1.wdc.com"
+ proxy_slot_number: 2
+ username: "{{ username }}"
+ password: "{{ password }}"
+- name: Firmware Activate
+ community.general.ocapi_command:
+ category: Update
+ command: FWActivate
+ baseuri: "iom1.wdc.com"
+ proxy_slot_number: 2
+ username: "{{ username }}"
+ password: "{{ password }}"
+- name: Delete Job
+ community.general.ocapi_command:
+ category: Jobs
+ command: DeleteJob
+ job_name: FirmwareUpdate
+ baseuri: "{{ baseuri }}"
+ proxy_slot_number: 2
+ username: "{{ username }}"
+ password: "{{ password }}"
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message with action result or error description.
- returned: always
- type: str
- sample: "Action was successful"
+ description: Message with action result or error description.
+ returned: always
+ type: str
+ sample: "Action was successful"
jobUri:
- description: URI to use to monitor status of the operation. Returned for async commands such as Firmware Update, Firmware Activate.
- returned: when supported
- type: str
- sample: "https://ioma.wdc.com/Storage/Devices/openflex-data24-usalp03020qb0003/Jobs/FirmwareUpdate/"
+ description: URI to use to monitor status of the operation. Returned for async commands such as Firmware Update, Firmware
+ Activate.
+ returned: when supported
+ type: str
+ sample: "https://ioma.wdc.com/Storage/Devices/openflex-data24-usalp03020qb0003/Jobs/FirmwareUpdate/"
operationStatusId:
- description: OCAPI State ID (see OCAPI documentation for possible values).
- returned: when supported
- type: int
- sample: 2
-
-'''
+ description: OCAPI State ID (see OCAPI documentation for possible values).
+ returned: when supported
+ type: int
+ sample: 2
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ocapi_utils import OcapiUtils
diff --git a/plugins/modules/ocapi_info.py b/plugins/modules/ocapi_info.py
index 9906d804c1..f4a216a47d 100644
--- a/plugins/modules/ocapi_info.py
+++ b/plugins/modules/ocapi_info.py
@@ -10,14 +10,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ocapi_info
version_added: 6.3.0
short_description: Manages Out-Of-Band controllers using Open Composable API (OCAPI)
description:
- - Builds OCAPI URIs locally and sends them to remote OOB controllers to
- get information back.
+ - Builds OCAPI URIs locally and sends them to remote OOB controllers to get information back.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.info_module
@@ -38,7 +36,7 @@ options:
- Base URI of OOB controller.
type: str
proxy_slot_number:
- description: For proxied inband requests, the slot number of the IOM. Only applies if O(baseuri) is a proxy server.
+ description: For proxied inband requests, the slot number of the IOM. Only applies if O(baseuri) is a proxy server.
type: int
username:
required: true
@@ -62,63 +60,64 @@ options:
author: "Mike Moerk (@mikemoerk)"
-'''
+"""
-EXAMPLES = '''
- - name: Get job status
- community.general.ocapi_info:
- category: Status
- command: JobStatus
- baseuri: "http://iom1.wdc.com"
- jobName: FirmwareUpdate
- username: "{{ username }}"
- password: "{{ password }}"
-'''
+EXAMPLES = r"""
+- name: Get job status
+ community.general.ocapi_info:
+ category: Status
+ command: JobStatus
+ baseuri: "http://iom1.wdc.com"
+ jobName: FirmwareUpdate
+ username: "{{ username }}"
+ password: "{{ password }}"
+"""
-RETURN = '''
+RETURN = r"""
msg:
- description: Message with action result or error description.
- returned: always
- type: str
- sample: "Action was successful"
+ description: Message with action result or error description.
+ returned: always
+ type: str
+ sample: "Action was successful"
percentComplete:
- description: Percent complete of the relevant operation. Applies to O(command=JobStatus).
- returned: when supported
- type: int
- sample: 99
+ description: Percent complete of the relevant operation. Applies to O(command=JobStatus).
+ returned: when supported
+ type: int
+ sample: 99
operationStatus:
- description: Status of the relevant operation. Applies to O(command=JobStatus). See OCAPI documentation for details.
- returned: when supported
- type: str
- sample: "Activate needed"
+ description: Status of the relevant operation. Applies to O(command=JobStatus). See OCAPI documentation for details.
+ returned: when supported
+ type: str
+ sample: "Activate needed"
operationStatusId:
- description: Integer value of status (corresponds to operationStatus). Applies to O(command=JobStatus). See OCAPI documentation for details.
- returned: when supported
- type: int
- sample: 65540
+ description: Integer value of status (corresponds to operationStatus). Applies to O(command=JobStatus). See OCAPI documentation
+ for details.
+ returned: when supported
+ type: int
+ sample: 65540
operationHealth:
- description: Health of the operation. Applies to O(command=JobStatus). See OCAPI documentation for details.
- returned: when supported
- type: str
- sample: "OK"
+ description: Health of the operation. Applies to O(command=JobStatus). See OCAPI documentation for details.
+ returned: when supported
+ type: str
+ sample: "OK"
operationHealthId:
- description: >
- Integer value for health of the operation (corresponds to RV(operationHealth)). Applies to O(command=JobStatus).
- See OCAPI documentation for details.
- returned: when supported
- type: str
- sample: "OK"
+ description: >-
+ Integer value for health of the operation (corresponds to RV(operationHealth)). Applies to O(command=JobStatus). See OCAPI
+ documentation for details.
+ returned: when supported
+ type: str
+ sample: "OK"
details:
- description: Details of the relevant operation. Applies to O(command=JobStatus).
- returned: when supported
- type: list
- elements: str
+ description: Details of the relevant operation. Applies to O(command=JobStatus).
+ returned: when supported
+ type: list
+ elements: str
status:
description: Dictionary containing status information. See OCAPI documentation for details.
@@ -139,7 +138,7 @@ status:
"Name": "In service"
}
}
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.ocapi_utils import OcapiUtils
diff --git a/plugins/modules/oci_vcn.py b/plugins/modules/oci_vcn.py
index bf110b94b5..47d38137ea 100644
--- a/plugins/modules/oci_vcn.py
+++ b/plugins/modules/oci_vcn.py
@@ -8,49 +8,46 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oci_vcn
short_description: Manage Virtual Cloud Networks(VCN) in OCI
description:
- - This module allows the user to create, delete and update virtual cloud networks(VCNs) in OCI.
- The complete Oracle Cloud Infrastructure Ansible Modules can be downloaded from
- U(https://github.com/oracle/oci-ansible-modules/releases).
+ - This module allows the user to create, delete and update virtual cloud networks(VCNs) in OCI. The complete Oracle Cloud
+ Infrastructure Ansible Modules can be downloaded from U(https://github.com/oracle/oci-ansible-modules/releases).
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- cidr_block:
- description: The CIDR IP address block of the VCN. Required when creating a VCN with O(state=present).
- type: str
- required: false
- compartment_id:
- description: The OCID of the compartment to contain the VCN. Required when creating a VCN with O(state=present).
- This option is mutually exclusive with O(vcn_id).
- type: str
- display_name:
- description: A user-friendly name. Does not have to be unique, and it's changeable.
- type: str
- aliases: [ 'name' ]
- dns_label:
- description: A DNS label for the VCN, used in conjunction with the VNIC's hostname and subnet's DNS label to
- form a fully qualified domain name (FQDN) for each VNIC within this subnet (for example,
- bminstance-1.subnet123.vcn1.oraclevcn.com). Not required to be unique, but it's a best practice
- to set unique DNS labels for VCNs in your tenancy. Must be an alphanumeric string that begins
- with a letter. The value cannot be changed.
- type: str
- state:
- description: Create or update a VCN with O(state=present). Use O(state=absent) to delete a VCN.
- type: str
- default: present
- choices: ['present', 'absent']
- vcn_id:
- description: The OCID of the VCN. Required when deleting a VCN with O(state=absent) or updating a VCN
- with O(state=present). This option is mutually exclusive with O(compartment_id).
- type: str
- aliases: [ 'id' ]
+ cidr_block:
+ description: The CIDR IP address block of the VCN. Required when creating a VCN with O(state=present).
+ type: str
+ required: false
+ compartment_id:
+ description: The OCID of the compartment to contain the VCN. Required when creating a VCN with O(state=present). This
+ option is mutually exclusive with O(vcn_id).
+ type: str
+ display_name:
+ description: A user-friendly name. Does not have to be unique, and it is changeable.
+ type: str
+ aliases: ['name']
+ dns_label:
+ description: A DNS label for the VCN, used in conjunction with the VNIC's hostname and subnet's DNS label to form a fully
+ qualified domain name (FQDN) for each VNIC within this subnet (for example, V(bminstance-1.subnet123.vcn1.oraclevcn.com)).
+ Not required to be unique, but it is a best practice to set unique DNS labels for VCNs in your tenancy. Must be an alphanumeric
+ string that begins with a letter. The value cannot be changed.
+ type: str
+ state:
+ description: Create or update a VCN with O(state=present). Use O(state=absent) to delete a VCN.
+ type: str
+ default: present
+ choices: ['present', 'absent']
+ vcn_id:
+ description: The OCID of the VCN. Required when deleting a VCN with O(state=absent) or updating a VCN with O(state=present).
+ This option is mutually exclusive with O(compartment_id).
+ type: str
+ aliases: ['id']
author: "Rohit Chaware (@rohitChaware)"
extends_documentation_fragment:
- community.general.oracle
@@ -58,10 +55,9 @@ extends_documentation_fragment:
- community.general.oracle_wait_options
- community.general.oracle_tags
- community.general.attributes
+"""
-'''
-
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create a VCN
community.general.oci_vcn:
cidr_block: '10.0.0.0/16'
@@ -80,7 +76,7 @@ EXAMPLES = """
state: absent
"""
-RETURN = """
+RETURN = r"""
vcn:
description: Information about the VCN
returned: On successful create and update operation
diff --git a/plugins/modules/odbc.py b/plugins/modules/odbc.py
index bc2e89656d..54c923cf1e 100644
--- a/plugins/modules/odbc.py
+++ b/plugins/modules/odbc.py
@@ -8,55 +8,54 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: odbc
author: "John Westcott IV (@john-westcott-iv)"
version_added: "1.0.0"
-short_description: Execute SQL via ODBC
+short_description: Execute SQL using ODBC
description:
- - Read/Write info via ODBC drivers.
+ - Read/Write info using ODBC drivers.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- dsn:
- description:
- - The connection string passed into ODBC.
- required: true
- type: str
- query:
- description:
- - The SQL query to perform.
- required: true
- type: str
- params:
- description:
- - Parameters to pass to the SQL query.
- type: list
- elements: str
- commit:
- description:
- - Perform a commit after the execution of the SQL query.
- - Some databases allow a commit after a select whereas others raise an exception.
- - Default is V(true) to support legacy module behavior.
- type: bool
- default: true
- version_added: 1.3.0
+ dsn:
+ description:
+ - The connection string passed into ODBC.
+ required: true
+ type: str
+ query:
+ description:
+ - The SQL query to perform.
+ required: true
+ type: str
+ params:
+ description:
+ - Parameters to pass to the SQL query.
+ type: list
+ elements: str
+ commit:
+ description:
+ - Perform a commit after the execution of the SQL query.
+ - Some databases allow a commit after a select whereas others raise an exception.
+ - Default is V(true) to support legacy module behavior.
+ type: bool
+ default: true
+ version_added: 1.3.0
requirements:
- "pyodbc"
notes:
- - "Like the command module, this module always returns changed = yes whether or not the query would change the database."
- - "To alter this behavior you can use C(changed_when): [yes or no]."
- - "For details about return values (description and row_count) see U(https://github.com/mkleehammer/pyodbc/wiki/Cursor)."
-'''
+ - Like the command module, this module always returns V(changed=true) whether or not the query would change the database.
+ - 'To alter this behavior you can use C(changed_when): [true or false].'
+ - For details about return values (RV(description) and RV(row_count)) see U(https://github.com/mkleehammer/pyodbc/wiki/Cursor).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Set some values in the test db
community.general.odbc:
dsn: "DRIVER={ODBC Driver 13 for SQL Server};Server=db.ansible.com;Database=my_db;UID=admin;PWD=password;"
@@ -65,24 +64,24 @@ EXAMPLES = '''
- "value1"
commit: false
changed_when: false
-'''
+"""
-RETURN = '''
+RETURN = r"""
results:
- description: List of lists of strings containing selected rows, likely empty for DDL statements.
- returned: success
- type: list
- elements: list
+ description: List of lists of strings containing selected rows, likely empty for DDL statements.
+ returned: success
+ type: list
+ elements: list
description:
- description: "List of dicts about the columns selected from the cursors, likely empty for DDL statements. See notes."
- returned: success
- type: list
- elements: dict
+ description: "List of dicts about the columns selected from the cursors, likely empty for DDL statements. See notes."
+ returned: success
+ type: list
+ elements: dict
row_count:
- description: "The number of rows selected or modified according to the cursor defaults to -1. See notes."
- returned: success
- type: str
-'''
+ description: "The number of rows selected or modified according to the cursor defaults to V(-1). See notes."
+ returned: success
+ type: str
+"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible.module_utils.common.text.converters import to_native
diff --git a/plugins/modules/office_365_connector_card.py b/plugins/modules/office_365_connector_card.py
index ed8ebd188b..8ff82fecc1 100644
--- a/plugins/modules/office_365_connector_card.py
+++ b/plugins/modules/office_365_connector_card.py
@@ -8,17 +8,16 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: office_365_connector_card
short_description: Use webhooks to create Connector Card messages within an Office 365 group
description:
- - Creates Connector Card messages through
- Office 365 Connectors
+ - Creates Connector Card messages through Office 365 Connectors.
+ - See
U(https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#connector-card-for-microsoft-365-groups).
author: "Marc Sensenich (@marc-sensenich)"
notes:
- - This module is not idempotent, therefore if the same task is run twice
- there will be two Connector Cards created
+ - This module is not idempotent, therefore if the same task is run twice there will be two Connector Cards created.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -37,7 +36,7 @@ options:
description:
- A string used for summarizing card content.
- This will be shown as the message subject.
- - This is required if the text parameter isn't populated.
+ - This is required if the text parameter is not populated.
color:
type: str
description:
@@ -51,22 +50,21 @@ options:
description:
- The main text of the card.
- This will be rendered below the sender information and optional title,
- - and above any sections or actions present.
+ - And above any sections or actions present.
actions:
type: list
elements: dict
description:
- - This array of objects will power the action links
- - found at the bottom of the card.
+ - This array of objects will power the action links found at the bottom of the card.
sections:
type: list
elements: dict
description:
- Contains a list of sections to display in the card.
- For more information see U(https://learn.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#section-fields).
-'''
+"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create a simple Connector Card
community.general.office_365_connector_card:
webhook: https://outlook.office.com/webhook/GUID/IncomingWebhook/GUID/GUID
@@ -77,71 +75,70 @@ EXAMPLES = """
webhook: https://outlook.office.com/webhook/GUID/IncomingWebhook/GUID/GUID
summary: This is the summary property
title: This is the **card's title** property
- text: This is the **card's text** property. Lorem ipsum dolor sit amet, consectetur
- adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+ text: This is the **card's text** property. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+ tempor incididunt ut labore et dolore magna aliqua.
color: E81123
sections:
- - title: This is the **section's title** property
- activity_image: http://connectorsdemo.azurewebsites.net/images/MSC12_Oscar_002.jpg
- activity_title: This is the section's **activityTitle** property
- activity_subtitle: This is the section's **activitySubtitle** property
- activity_text: This is the section's **activityText** property.
- hero_image:
- image: http://connectorsdemo.azurewebsites.net/images/WIN12_Scene_01.jpg
- title: This is the image's alternate text
- text: This is the section's text property. Lorem ipsum dolor sit amet, consectetur
- adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
- facts:
- - name: This is a fact name
- value: This is a fact value
- - name: This is a fact name
- value: This is a fact value
- - name: This is a fact name
- value: This is a fact value
- images:
- - image: http://connectorsdemo.azurewebsites.net/images/MicrosoftSurface_024_Cafe_OH-06315_VS_R1c.jpg
- title: This is the image's alternate text
- - image: http://connectorsdemo.azurewebsites.net/images/WIN12_Scene_01.jpg
- title: This is the image's alternate text
- - image: http://connectorsdemo.azurewebsites.net/images/WIN12_Anthony_02.jpg
- title: This is the image's alternate text
- actions:
- - "@type": ActionCard
- name: Comment
- inputs:
- - "@type": TextInput
- id: comment
- is_multiline: true
- title: Input's title property
+ - title: This is the **section's title** property
+ activity_image: http://connectorsdemo.azurewebsites.net/images/MSC12_Oscar_002.jpg
+ activity_title: This is the section's **activityTitle** property
+ activity_subtitle: This is the section's **activitySubtitle** property
+ activity_text: This is the section's **activityText** property.
+ hero_image:
+ image: http://connectorsdemo.azurewebsites.net/images/WIN12_Scene_01.jpg
+ title: This is the image's alternate text
+ text: This is the section's text property. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+ tempor incididunt ut labore et dolore magna aliqua.
+ facts:
+ - name: This is a fact name
+ value: This is a fact value
+ - name: This is a fact name
+ value: This is a fact value
+ - name: This is a fact name
+ value: This is a fact value
+ images:
+ - image: http://connectorsdemo.azurewebsites.net/images/MicrosoftSurface_024_Cafe_OH-06315_VS_R1c.jpg
+ title: This is the image's alternate text
+ - image: http://connectorsdemo.azurewebsites.net/images/WIN12_Scene_01.jpg
+ title: This is the image's alternate text
+ - image: http://connectorsdemo.azurewebsites.net/images/WIN12_Anthony_02.jpg
+ title: This is the image's alternate text
actions:
- - "@type": HttpPOST
- name: Save
- target: http://...
- - "@type": ActionCard
- name: Due Date
- inputs:
- - "@type": DateInput
- id: dueDate
- title: Input's title property
- actions:
- - "@type": HttpPOST
- name: Save
- target: http://...
- - "@type": HttpPOST
- name: Action's name prop.
- target: http://...
- - "@type": OpenUri
- name: Action's name prop
- targets:
- - os: default
- uri: http://...
- - start_group: true
- title: This is the title of a **second section**
- text: This second section is visually separated from the first one by setting its
- **startGroup** property to true.
+ - "@type": ActionCard
+ name: Comment
+ inputs:
+ - "@type": TextInput
+ id: comment
+ is_multiline: true
+ title: Input's title property
+ actions:
+ - "@type": HttpPOST
+ name: Save
+ target: http://...
+ - "@type": ActionCard
+ name: Due Date
+ inputs:
+ - "@type": DateInput
+ id: dueDate
+ title: Input's title property
+ actions:
+ - "@type": HttpPOST
+ name: Save
+ target: http://...
+ - "@type": HttpPOST
+ name: Action's name prop.
+ target: http://...
+ - "@type": OpenUri
+ name: Action's name prop
+ targets:
+ - os: default
+ uri: http://...
+ - start_group: true
+ title: This is the title of a **second section**
+ text: This second section is visually separated from the first one by setting its **startGroup** property to true.
"""
-RETURN = """
+RETURN = r"""
"""
# import module snippets
diff --git a/plugins/modules/ohai.py b/plugins/modules/ohai.py
index 7fdab3bb75..32b14b2e81 100644
--- a/plugins/modules/ohai.py
+++ b/plugins/modules/ohai.py
@@ -9,15 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ohai
short_description: Returns inventory data from I(Ohai)
description:
- - Similar to the M(community.general.facter) module, this runs the I(Ohai) discovery program
- (U(https://docs.chef.io/ohai.html)) on the remote host and
- returns JSON inventory data.
- I(Ohai) data is a bit more verbose and nested than I(facter).
+ - Similar to the M(community.general.facter) module, this runs the I(Ohai) discovery program (U(https://docs.chef.io/ohai.html))
+ on the remote host and returns JSON inventory data. I(Ohai) data is a bit more verbose and nested than I(facter).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -27,16 +24,16 @@ attributes:
support: none
options: {}
notes: []
-requirements: [ "ohai" ]
+requirements: ["ohai"]
author:
- "Ansible Core Team"
- "Michael DeHaan (@mpdehaan)"
-'''
+"""
-EXAMPLES = '''
-# Retrieve (ohai) data from all Web servers and store in one-file per host
+EXAMPLES = r"""
ansible webservers -m ohai --tree=/tmp/ohaidata
-'''
+...
+"""
import json
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/omapi_host.py b/plugins/modules/omapi_host.py
index c93c578535..36c5434fd5 100644
--- a/plugins/modules/omapi_host.py
+++ b/plugins/modules/omapi_host.py
@@ -10,11 +10,10 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: omapi_host
short_description: Setup OMAPI hosts
-description: Manage OMAPI hosts into compatible DHCPd servers
+description: Manage OMAPI hosts into compatible DHCPd servers.
requirements:
- pypureomapi
author:
@@ -22,65 +21,64 @@ author:
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Create or remove OMAPI host.
- type: str
- required: true
- choices: [ absent, present ]
- hostname:
- description:
- - Sets the host lease hostname (mandatory if state=present).
- type: str
- aliases: [ name ]
- host:
- description:
- - Sets OMAPI server host to interact with.
- type: str
- default: localhost
- port:
- description:
- - Sets the OMAPI server port to interact with.
- type: int
- default: 7911
- key_name:
- description:
- - Sets the TSIG key name for authenticating against OMAPI server.
- type: str
- required: true
- key:
- description:
- - Sets the TSIG key content for authenticating against OMAPI server.
- type: str
- required: true
- macaddr:
- description:
- - Sets the lease host MAC address.
- type: str
- required: true
- ip:
- description:
- - Sets the lease host IP address.
- type: str
- statements:
- description:
- - Attach a list of OMAPI DHCP statements with host lease (without ending semicolon).
- type: list
- elements: str
- default: []
- ddns:
- description:
- - Enable dynamic DNS updates for this host.
- type: bool
- default: false
-
-'''
-EXAMPLES = r'''
+ state:
+ description:
+ - Create or remove OMAPI host.
+ type: str
+ required: true
+ choices: [absent, present]
+ hostname:
+ description:
+ - Sets the host lease hostname (mandatory if O(state=present)).
+ type: str
+ aliases: [name]
+ host:
+ description:
+ - Sets OMAPI server host to interact with.
+ type: str
+ default: localhost
+ port:
+ description:
+ - Sets the OMAPI server port to interact with.
+ type: int
+ default: 7911
+ key_name:
+ description:
+ - Sets the TSIG key name for authenticating against OMAPI server.
+ type: str
+ required: true
+ key:
+ description:
+ - Sets the TSIG key content for authenticating against OMAPI server.
+ type: str
+ required: true
+ macaddr:
+ description:
+ - Sets the lease host MAC address.
+ type: str
+ required: true
+ ip:
+ description:
+ - Sets the lease host IP address.
+ type: str
+ statements:
+ description:
+ - Attach a list of OMAPI DHCP statements with host lease (without ending semicolon).
+ type: list
+ elements: str
+ default: []
+ ddns:
+ description:
+ - Enable dynamic DNS updates for this host.
+ type: bool
+ default: false
+"""
+EXAMPLES = r"""
- name: Add a host using OMAPI
community.general.omapi_host:
key_name: defomapi
@@ -91,8 +89,8 @@ EXAMPLES = r'''
ip: 192.168.88.99
ddns: true
statements:
- - filename "pxelinux.0"
- - next-server 1.1.1.1
+ - filename "pxelinux.0"
+ - next-server 1.1.1.1
state: present
- name: Remove a host using OMAPI
@@ -102,35 +100,35 @@ EXAMPLES = r'''
host: 10.1.1.1
macaddr: 00:66:ab:dd:11:44
state: absent
-'''
+"""
-RETURN = r'''
+RETURN = r"""
lease:
- description: dictionary containing host information
- returned: success
- type: complex
- contains:
- ip-address:
- description: IP address, if there is.
- returned: success
- type: str
- sample: '192.168.1.5'
- hardware-address:
- description: MAC address
- returned: success
- type: str
- sample: '00:11:22:33:44:55'
- hardware-type:
- description: hardware type, generally '1'
- returned: success
- type: int
- sample: 1
- name:
- description: hostname
- returned: success
- type: str
- sample: 'mydesktop'
-'''
+ description: Dictionary containing host information.
+ returned: success
+ type: complex
+ contains:
+ ip-address:
+ description: IP address, if there is.
+ returned: success
+ type: str
+ sample: '192.168.1.5'
+ hardware-address:
+ description: MAC address.
+ returned: success
+ type: str
+ sample: '00:11:22:33:44:55'
+ hardware-type:
+ description: Hardware type, generally V(1).
+ returned: success
+ type: int
+ sample: 1
+ name:
+ description: Hostname.
+ returned: success
+ type: str
+ sample: 'mydesktop'
+"""
import binascii
import socket
diff --git a/plugins/modules/one_host.py b/plugins/modules/one_host.py
index 6188f3d0f7..8246172c90 100644
--- a/plugins/modules/one_host.py
+++ b/plugins/modules/one_host.py
@@ -10,87 +10,86 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: one_host
short_description: Manages OpenNebula Hosts
requirements:
- - pyone
+ - pyone
description:
- - "Manages OpenNebula Hosts"
-
+ - Manages OpenNebula Hosts.
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Hostname of the machine to manage.
- required: true
- type: str
- state:
- description:
- - Takes the host to the desired lifecycle state.
- - If V(absent) the host will be deleted from the cluster.
- - If V(present) the host will be created in the cluster (includes V(enabled), V(disabled) and V(offline) states).
- - If V(enabled) the host is fully operational.
- - V(disabled), e.g. to perform maintenance operations.
- - V(offline), host is totally offline.
- choices:
- - absent
- - present
- - enabled
- - disabled
- - offline
- default: present
- type: str
- im_mad_name:
- description:
- - The name of the information manager, this values are taken from the oned.conf with the tag name IM_MAD (name)
- default: kvm
- type: str
- vmm_mad_name:
- description:
- - The name of the virtual machine manager mad name, this values are taken from the oned.conf with the tag name VM_MAD (name)
- default: kvm
- type: str
- cluster_id:
- description:
- - The cluster ID.
- default: 0
- type: int
- cluster_name:
- description:
- - The cluster specified by name.
- type: str
- labels:
- description:
- - The labels for this host.
- type: list
- elements: str
- template:
- description:
- - The template or attribute changes to merge into the host template.
- aliases:
- - attributes
- type: dict
+ name:
+ description:
+ - Hostname of the machine to manage.
+ required: true
+ type: str
+ state:
+ description:
+ - Takes the host to the desired lifecycle state.
+ - If V(absent) the host will be deleted from the cluster.
+ - If V(present) the host will be created in the cluster (includes V(enabled), V(disabled) and V(offline) states).
+ - If V(enabled) the host is fully operational.
+ - V(disabled), for example to perform maintenance operations.
+ - V(offline), host is totally offline.
+ choices:
+ - absent
+ - present
+ - enabled
+ - disabled
+ - offline
+ default: present
+ type: str
+ im_mad_name:
+ description:
+ - The name of the information manager, this values are taken from the oned.conf with the tag name IM_MAD (name).
+ default: kvm
+ type: str
+ vmm_mad_name:
+ description:
+ - The name of the virtual machine manager mad name, this values are taken from the oned.conf with the tag name VM_MAD
+ (name).
+ default: kvm
+ type: str
+ cluster_id:
+ description:
+ - The cluster ID.
+ default: 0
+ type: int
+ cluster_name:
+ description:
+ - The cluster specified by name.
+ type: str
+ labels:
+ description:
+ - The labels for this host.
+ type: list
+ elements: str
+ template:
+ description:
+ - The template or attribute changes to merge into the host template.
+ aliases:
+ - attributes
+ type: dict
extends_documentation_fragment:
- - community.general.opennebula
- - community.general.attributes
+ - community.general.opennebula
+ - community.general.attributes
author:
- - Rafael del Valle (@rvalle)
-'''
+ - Rafael del Valle (@rvalle)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a new host in OpenNebula
community.general.one_host:
name: host1
@@ -102,15 +101,15 @@ EXAMPLES = '''
name: host2
cluster_name: default
template:
- LABELS:
- - gold
- - ssd
- RESERVED_CPU: -100
-'''
+ LABELS:
+ - gold
+ - ssd
+ RESERVED_CPU: -100
+"""
# TODO: pending setting guidelines on returned values
-RETURN = '''
-'''
+RETURN = r"""
+"""
# TODO: Documentation on valid state transitions is required to properly implement all valid cases
# TODO: To be coherent with CLI this module should also provide "flush" functionality
diff --git a/plugins/modules/one_image.py b/plugins/modules/one_image.py
index 68db40adb4..e5ffb68b4f 100644
--- a/plugins/modules/one_image.py
+++ b/plugins/modules/one_image.py
@@ -8,82 +8,81 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: one_image
short_description: Manages OpenNebula images
description:
- - Manages OpenNebula images
+ - Manages OpenNebula images.
requirements:
- pyone
extends_documentation_fragment:
- community.general.opennebula
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- id:
- description:
- - A O(id) of the image you would like to manage.
- type: int
- name:
- description:
- - A O(name) of the image you would like to manage.
- - Required if O(create=true).
- type: str
- state:
- description:
- - V(present) - state that is used to manage the image.
- - V(absent) - delete the image.
- - V(cloned) - clone the image.
- - V(renamed) - rename the image to the O(new_name).
- choices: ["present", "absent", "cloned", "renamed"]
- default: present
- type: str
- enabled:
- description:
- - Whether the image should be enabled or disabled.
- type: bool
- new_name:
- description:
- - A name that will be assigned to the existing or new image.
- - In the case of cloning, by default O(new_name) will take the name of the origin image with the prefix 'Copy of'.
- type: str
- persistent:
- description:
- - Whether the image should be persistent or non-persistent.
- type: bool
- version_added: 9.5.0
- create:
- description:
- - Whether the image should be created if not present.
- - This is ignored if O(state=absent).
- type: bool
- version_added: 10.0.0
- template:
- description:
- - Use with O(create=true) to specify image template.
- type: str
- version_added: 10.0.0
- datastore_id:
- description:
- - Use with O(create=true) to specify datastore for image.
- type: int
- version_added: 10.0.0
- wait_timeout:
- description:
- - Seconds to wait until image is ready, deleted or cloned.
- type: int
- default: 60
- version_added: 10.0.0
+ id:
+ description:
+ - A O(id) of the image you would like to manage.
+ type: int
+ name:
+ description:
+ - A O(name) of the image you would like to manage.
+ - Required if O(create=true).
+ type: str
+ state:
+ description:
+ - V(present) - state that is used to manage the image.
+ - V(absent) - delete the image.
+ - V(cloned) - clone the image.
+ - V(renamed) - rename the image to the O(new_name).
+ choices: ["present", "absent", "cloned", "renamed"]
+ default: present
+ type: str
+ enabled:
+ description:
+ - Whether the image should be enabled or disabled.
+ type: bool
+ new_name:
+ description:
+ - A name that will be assigned to the existing or new image.
+ - In the case of cloning, by default O(new_name) will take the name of the origin image with the prefix 'Copy of'.
+ type: str
+ persistent:
+ description:
+ - Whether the image should be persistent or non-persistent.
+ type: bool
+ version_added: 9.5.0
+ create:
+ description:
+ - Whether the image should be created if not present.
+ - This is ignored if O(state=absent).
+ type: bool
+ version_added: 10.0.0
+ template:
+ description:
+ - Use with O(create=true) to specify image template.
+ type: str
+ version_added: 10.0.0
+ datastore_id:
+ description:
+ - Use with O(create=true) to specify datastore for image.
+ type: int
+ version_added: 10.0.0
+ wait_timeout:
+ description:
+ - Seconds to wait until image is ready, deleted or cloned.
+ type: int
+ default: 60
+ version_added: 10.0.0
author:
- - "Milan Ilic (@ilicmilan)"
-'''
+ - "Milan Ilic (@ilicmilan)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Fetch the IMAGE by id
community.general.one_image:
id: 45
@@ -147,228 +146,228 @@ EXAMPLES = '''
create: true
datastore_id: 100
wait_timeout: 900
- template: |
+ template: |-
PATH = "https://192.0.2.200/repo/tipa_image.raw"
TYPE = "OS"
SIZE = 82048
FORMAT = "raw"
PERSISTENT = "Yes"
DEV_PREFIX = "vd"
-'''
+"""
-RETURN = '''
+RETURN = r"""
id:
- description: image id
- type: int
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample: 153
+ description: Image ID.
+ type: int
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample: 153
name:
- description: image name
- type: str
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample: app1
+ description: Image name.
+ type: str
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample: app1
group_id:
- description: image's group id
- type: int
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample: 1
+ description: Image's group ID.
+ type: int
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample: 1
group_name:
- description: image's group name
- type: str
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample: one-users
+ description: Image's group name.
+ type: str
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample: one-users
owner_id:
- description: image's owner id
- type: int
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample: 143
+ description: Image's owner ID.
+ type: int
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample: 143
owner_name:
- description: image's owner name
- type: str
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample: ansible-test
+ description: Image's owner name.
+ type: str
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample: ansible-test
state:
- description: state of image instance
- type: str
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample: READY
+ description: State of image instance.
+ type: str
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample: READY
used:
- description: is image in use
- type: bool
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample: true
+ description: Is image in use.
+ type: bool
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample: true
running_vms:
- description: count of running vms that use this image
- type: int
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample: 7
+ description: Count of running vms that use this image.
+ type: int
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample: 7
permissions:
- description: The image's permissions.
- type: dict
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
- contains:
- owner_u:
- description: The image's owner USAGE permissions.
- type: str
- sample: 1
- owner_m:
- description: The image's owner MANAGE permissions.
- type: str
- sample: 0
- owner_a:
- description: The image's owner ADMIN permissions.
- type: str
- sample: 0
- group_u:
- description: The image's group USAGE permissions.
- type: str
- sample: 0
- group_m:
- description: The image's group MANAGE permissions.
- type: str
- sample: 0
- group_a:
- description: The image's group ADMIN permissions.
- type: str
- sample: 0
- other_u:
- description: The image's other users USAGE permissions.
- type: str
- sample: 0
- other_m:
- description: The image's other users MANAGE permissions.
- type: str
- sample: 0
- other_a:
- description: The image's other users ADMIN permissions
- type: str
- sample: 0
- sample:
- owner_u: 1
- owner_m: 0
- owner_a: 0
- group_u: 0
- group_m: 0
- group_a: 0
- other_u: 0
- other_m: 0
- other_a: 0
+ description: The image's permissions.
+ type: dict
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
+ contains:
+ owner_u:
+ description: The image's owner USAGE permissions.
+ type: str
+ sample: 1
+ owner_m:
+ description: The image's owner MANAGE permissions.
+ type: str
+ sample: 0
+ owner_a:
+ description: The image's owner ADMIN permissions.
+ type: str
+ sample: 0
+ group_u:
+ description: The image's group USAGE permissions.
+ type: str
+ sample: 0
+ group_m:
+ description: The image's group MANAGE permissions.
+ type: str
+ sample: 0
+ group_a:
+ description: The image's group ADMIN permissions.
+ type: str
+ sample: 0
+ other_u:
+ description: The image's other users USAGE permissions.
+ type: str
+ sample: 0
+ other_m:
+ description: The image's other users MANAGE permissions.
+ type: str
+ sample: 0
+ other_a:
+ description: The image's other users ADMIN permissions.
+ type: str
+ sample: 0
+ sample:
+ owner_u: 1
+ owner_m: 0
+ owner_a: 0
+ group_u: 0
+ group_m: 0
+ group_a: 0
+ other_u: 0
+ other_m: 0
+ other_a: 0
type:
- description: The image's type.
- type: str
- sample: 0
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's type.
+ type: str
+ sample: 0
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
disk_type:
- description: The image's format type.
- type: str
- sample: 0
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's format type.
+ type: str
+ sample: 0
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
persistent:
- description: The image's persistence status (1 means true, 0 means false).
- type: int
- sample: 1
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's persistence status (1 means true, 0 means false).
+ type: int
+ sample: 1
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
source:
- description: The image's source.
- type: str
- sample: /var/lib/one//datastores/100/somerandomstringxd
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ description: The image's source.
+ type: str
+ sample: /var/lib/one//datastores/100/somerandomstringxd
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
path:
- description: The image's filesystem path.
- type: str
- sample: /var/tmp/hello.qcow2
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's filesystem path.
+ type: str
+ sample: /var/tmp/hello.qcow2
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
fstype:
- description: The image's filesystem type.
- type: str
- sample: ext4
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's filesystem type.
+ type: str
+ sample: ext4
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
size:
- description: The image's size in MegaBytes.
- type: int
- sample: 10000
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's size in MegaBytes.
+ type: int
+ sample: 10000
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
cloning_ops:
- description: The image's cloning operations per second.
- type: int
- sample: 0
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's cloning operations per second.
+ type: int
+ sample: 0
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
cloning_id:
- description: The image's cloning ID.
- type: int
- sample: -1
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's cloning ID.
+ type: int
+ sample: -1
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
target_snapshot:
- description: The image's target snapshot.
- type: int
- sample: 1
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's target snapshot.
+ type: int
+ sample: 1
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
datastore_id:
- description: The image's datastore ID.
- type: int
- sample: 100
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's datastore ID.
+ type: int
+ sample: 100
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
datastore:
- description: The image's datastore name.
- type: int
- sample: image_datastore
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
+ description: The image's datastore name.
+ type: int
+ sample: image_datastore
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
vms:
- description: The image's list of vm ID's.
- type: list
- elements: int
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample:
- - 1
- - 2
- - 3
- version_added: 9.5.0
+ description: The image's list of vm ID's.
+ type: list
+ elements: int
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample:
+ - 1
+ - 2
+ - 3
+ version_added: 9.5.0
clones:
- description: The image's list of clones ID's.
- type: list
- elements: int
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample:
- - 1
- - 2
- - 3
- version_added: 9.5.0
+ description: The image's list of clones ID's.
+ type: list
+ elements: int
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample:
+ - 1
+ - 2
+ - 3
+ version_added: 9.5.0
app_clones:
- description: The image's list of app_clones ID's.
- type: list
- elements: int
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- sample:
- - 1
- - 2
- - 3
- version_added: 9.5.0
+ description: The image's list of app_clones ID's.
+ type: list
+ elements: int
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ sample:
+ - 1
+ - 2
+ - 3
+ version_added: 9.5.0
snapshots:
- description: The image's list of snapshots.
- type: list
- returned: when O(state=present), O(state=cloned), or O(state=renamed)
- version_added: 9.5.0
- sample:
- - date: 123123
- parent: 1
- size: 10228
- allow_orphans: 1
- children: 0
- active: 1
- name: SampleName
-'''
+ description: The image's list of snapshots.
+ type: list
+ returned: when O(state=present), O(state=cloned), or O(state=renamed)
+ version_added: 9.5.0
+ sample:
+ - date: 123123
+ parent: 1
+ size: 10228
+ allow_orphans: 1
+ children: 0
+ active: 1
+ name: SampleName
+"""
from ansible_collections.community.general.plugins.module_utils.opennebula import OpenNebulaModule
diff --git a/plugins/modules/one_image_info.py b/plugins/modules/one_image_info.py
index 4bc48dfda1..7e5def76fb 100644
--- a/plugins/modules/one_image_info.py
+++ b/plugins/modules/one_image_info.py
@@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: one_image_info
short_description: Gather information on OpenNebula images
description:
@@ -23,7 +22,7 @@ extends_documentation_fragment:
options:
ids:
description:
- - A list of images ids whose facts you want to gather.
+ - A list of images IDs whose facts you want to gather.
- Module can use integers too.
aliases: ['id']
type: list
@@ -31,17 +30,17 @@ options:
name:
description:
- A O(name) of the image whose facts will be gathered.
- - If the O(name) begins with V(~) the O(name) will be used as regex pattern
- - which restricts the list of images (whose facts will be returned) whose names match specified regex.
+ - If the O(name) begins with V(~) the O(name) will be used as regex pattern, which restricts the list of images (whose
+ facts will be returned) whose names match specified regex.
- Also, if the O(name) begins with V(~*) case-insensitive matching will be performed.
- See examples for more details.
type: str
author:
- - "Milan Ilic (@ilicmilan)"
- - "Jan Meerkamp (@meerkampdvv)"
-'''
+ - "Milan Ilic (@ilicmilan)"
+ - "Jan Meerkamp (@meerkampdvv)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather facts about all images
community.general.one_image_info:
register: result
@@ -76,201 +75,201 @@ EXAMPLES = '''
community.general.one_image_info:
name: '~*foo-image-.*'
register: foo_images
-'''
+"""
-RETURN = '''
+RETURN = r"""
images:
- description: A list of images info
- type: complex
- returned: success
- contains:
- id:
- description: The image's id.
- type: int
- sample: 153
- name:
- description: The image's name.
- type: str
- sample: app1
- group_id:
- description: The image's group id
- type: int
- sample: 1
- group_name:
- description: The image's group name.
- type: str
- sample: one-users
- owner_id:
- description: The image's owner id.
- type: int
- sample: 143
- owner_name:
- description: The image's owner name.
- type: str
- sample: ansible-test
- state:
- description: The image's state.
- type: str
- sample: READY
- used:
- description: The image's usage status.
- type: bool
- sample: true
- running_vms:
- description: The image's count of running vms that use this image.
- type: int
- sample: 7
- permissions:
- description: The image's permissions.
- type: dict
- version_added: 9.5.0
- contains:
- owner_u:
- description: The image's owner USAGE permissions.
- type: str
- sample: 1
- owner_m:
- description: The image's owner MANAGE permissions.
- type: str
- sample: 0
- owner_a:
- description: The image's owner ADMIN permissions.
- type: str
- sample: 0
- group_u:
- description: The image's group USAGE permissions.
- type: str
- sample: 0
- group_m:
- description: The image's group MANAGE permissions.
- type: str
- sample: 0
- group_a:
- description: The image's group ADMIN permissions.
- type: str
- sample: 0
- other_u:
- description: The image's other users USAGE permissions.
- type: str
- sample: 0
- other_m:
- description: The image's other users MANAGE permissions.
- type: str
- sample: 0
- other_a:
- description: The image's other users ADMIN permissions
- type: str
- sample: 0
- sample:
- owner_u: 1
- owner_m: 0
- owner_a: 0
- group_u: 0
- group_m: 0
- group_a: 0
- other_u: 0
- other_m: 0
- other_a: 0
- type:
- description: The image's type.
- type: int
- sample: 0
- version_added: 9.5.0
- disk_type:
- description: The image's format type.
- type: int
- sample: 0
- version_added: 9.5.0
- persistent:
- description: The image's persistence status (1 means true, 0 means false).
- type: int
- sample: 1
- version_added: 9.5.0
- source:
- description: The image's source.
- type: str
- sample: /var/lib/one//datastores/100/somerandomstringxd
- version_added: 9.5.0
- path:
- description: The image's filesystem path.
- type: str
- sample: /var/tmp/hello.qcow2
- version_added: 9.5.0
- fstype:
- description: The image's filesystem type.
- type: str
- sample: ext4
- version_added: 9.5.0
- size:
- description: The image's size in MegaBytes.
- type: int
- sample: 10000
- version_added: 9.5.0
- cloning_ops:
- description: The image's cloning operations per second.
- type: int
- sample: 0
- version_added: 9.5.0
- cloning_id:
- description: The image's cloning ID.
- type: int
- sample: -1
- version_added: 9.5.0
- target_snapshot:
- description: The image's target snapshot.
- type: int
- sample: 1
- version_added: 9.5.0
- datastore_id:
- description: The image's datastore ID.
- type: int
- sample: 100
- version_added: 9.5.0
- datastore:
- description: The image's datastore name.
- type: int
- sample: image_datastore
- version_added: 9.5.0
- vms:
- description: The image's list of vm ID's.
- type: list
- elements: int
- version_added: 9.5.0
- sample:
- - 1
- - 2
- - 3
- clones:
- description: The image's list of clones ID's.
- type: list
- elements: int
- version_added: 9.5.0
- sample:
- - 1
- - 2
- - 3
- app_clones:
- description: The image's list of app_clones ID's.
- type: list
- elements: int
- version_added: 9.5.0
- sample:
- - 1
- - 2
- - 3
- snapshots:
- description: The image's list of snapshots.
- type: list
- version_added: 9.5.0
- sample:
- - date: 123123
- parent: 1
- size: 10228
- allow_orphans: 1
- children: 0
- active: 1
- name: SampleName
-'''
+ description: A list of images info.
+ type: complex
+ returned: success
+ contains:
+ id:
+ description: The image's ID.
+ type: int
+ sample: 153
+ name:
+ description: The image's name.
+ type: str
+ sample: app1
+ group_id:
+ description: The image's group ID.
+ type: int
+ sample: 1
+ group_name:
+ description: The image's group name.
+ type: str
+ sample: one-users
+ owner_id:
+ description: The image's owner ID.
+ type: int
+ sample: 143
+ owner_name:
+ description: The image's owner name.
+ type: str
+ sample: ansible-test
+ state:
+ description: The image's state.
+ type: str
+ sample: READY
+ used:
+ description: The image's usage status.
+ type: bool
+ sample: true
+ running_vms:
+ description: The image's count of running vms that use this image.
+ type: int
+ sample: 7
+ permissions:
+ description: The image's permissions.
+ type: dict
+ version_added: 9.5.0
+ contains:
+ owner_u:
+ description: The image's owner USAGE permissions.
+ type: str
+ sample: 1
+ owner_m:
+ description: The image's owner MANAGE permissions.
+ type: str
+ sample: 0
+ owner_a:
+ description: The image's owner ADMIN permissions.
+ type: str
+ sample: 0
+ group_u:
+ description: The image's group USAGE permissions.
+ type: str
+ sample: 0
+ group_m:
+ description: The image's group MANAGE permissions.
+ type: str
+ sample: 0
+ group_a:
+ description: The image's group ADMIN permissions.
+ type: str
+ sample: 0
+ other_u:
+ description: The image's other users USAGE permissions.
+ type: str
+ sample: 0
+ other_m:
+ description: The image's other users MANAGE permissions.
+ type: str
+ sample: 0
+ other_a:
+ description: The image's other users ADMIN permissions.
+ type: str
+ sample: 0
+ sample:
+ owner_u: 1
+ owner_m: 0
+ owner_a: 0
+ group_u: 0
+ group_m: 0
+ group_a: 0
+ other_u: 0
+ other_m: 0
+ other_a: 0
+ type:
+ description: The image's type.
+ type: int
+ sample: 0
+ version_added: 9.5.0
+ disk_type:
+ description: The image's format type.
+ type: int
+ sample: 0
+ version_added: 9.5.0
+ persistent:
+ description: The image's persistence status (1 means true, 0 means false).
+ type: int
+ sample: 1
+ version_added: 9.5.0
+ source:
+ description: The image's source.
+ type: str
+ sample: /var/lib/one//datastores/100/somerandomstringxd
+ version_added: 9.5.0
+ path:
+ description: The image's filesystem path.
+ type: str
+ sample: /var/tmp/hello.qcow2
+ version_added: 9.5.0
+ fstype:
+ description: The image's filesystem type.
+ type: str
+ sample: ext4
+ version_added: 9.5.0
+ size:
+ description: The image's size in MegaBytes.
+ type: int
+ sample: 10000
+ version_added: 9.5.0
+ cloning_ops:
+ description: The image's cloning operations per second.
+ type: int
+ sample: 0
+ version_added: 9.5.0
+ cloning_id:
+ description: The image's cloning ID.
+ type: int
+ sample: -1
+ version_added: 9.5.0
+ target_snapshot:
+ description: The image's target snapshot.
+ type: int
+ sample: 1
+ version_added: 9.5.0
+ datastore_id:
+ description: The image's datastore ID.
+ type: int
+ sample: 100
+ version_added: 9.5.0
+ datastore:
+ description: The image's datastore name.
+ type: int
+ sample: image_datastore
+ version_added: 9.5.0
+ vms:
+ description: The image's list of vm ID's.
+ type: list
+ elements: int
+ version_added: 9.5.0
+ sample:
+ - 1
+ - 2
+ - 3
+ clones:
+ description: The image's list of clones ID's.
+ type: list
+ elements: int
+ version_added: 9.5.0
+ sample:
+ - 1
+ - 2
+ - 3
+ app_clones:
+ description: The image's list of app_clones ID's.
+ type: list
+ elements: int
+ version_added: 9.5.0
+ sample:
+ - 1
+ - 2
+ - 3
+ snapshots:
+ description: The image's list of snapshots.
+ type: list
+ version_added: 9.5.0
+ sample:
+ - date: 123123
+ parent: 1
+ size: 10228
+ allow_orphans: 1
+ children: 0
+ active: 1
+ name: SampleName
+"""
from ansible_collections.community.general.plugins.module_utils.opennebula import OpenNebulaModule
diff --git a/plugins/modules/one_service.py b/plugins/modules/one_service.py
index 25ead72c1d..8244e0ca5a 100644
--- a/plugins/modules/one_service.py
+++ b/plugins/modules/one_service.py
@@ -8,12 +8,11 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: one_service
short_description: Deploy and manage OpenNebula services
description:
- - Manage OpenNebula services
+ - Manage OpenNebula services.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -30,11 +29,13 @@ options:
type: str
api_username:
description:
- - Name of the user to login into the OpenNebula OneFlow API server. If not set then the value of the E(ONEFLOW_USERNAME) environment variable is used.
+ - Name of the user to login into the OpenNebula OneFlow API server. If not set then the value of the E(ONEFLOW_USERNAME)
+ environment variable is used.
type: str
api_password:
description:
- - Password of the user to login into OpenNebula OneFlow API server. If not set then the value of the E(ONEFLOW_PASSWORD) environment variable is used.
+ - Password of the user to login into OpenNebula OneFlow API server. If not set then the value of the E(ONEFLOW_PASSWORD)
+ environment variable is used.
type: str
template_name:
description:
@@ -54,8 +55,8 @@ options:
type: str
unique:
description:
- - Setting O(unique=true) will make sure that there is only one service instance running with a name set with O(service_name) when
- instantiating a service from a template specified with O(template_id) or O(template_name). Check examples below.
+ - Setting O(unique=true) will make sure that there is only one service instance running with a name set with O(service_name)
+ when instantiating a service from a template specified with O(template_id) or O(template_name). Check examples below.
type: bool
default: false
state:
@@ -67,7 +68,8 @@ options:
type: str
mode:
description:
- - Set permission mode of a service instance in octet format, for example V(0600) to give owner C(use) and C(manage) and nothing to group and others.
+ - Set permission mode of a service instance in octet format, for example V(0600) to give owner C(use) and C(manage)
+ and nothing to group and others.
type: str
owner_id:
description:
@@ -106,10 +108,10 @@ options:
type: bool
default: false
author:
- - "Milan Ilic (@ilicmilan)"
-'''
+ - "Milan Ilic (@ilicmilan)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Instantiate a new service
community.general.one_service:
template_id: 90
@@ -178,57 +180,57 @@ EXAMPLES = '''
role: foo
cardinality: 7
wait: true
-'''
+"""
-RETURN = '''
+RETURN = r"""
service_id:
- description: service id
- type: int
- returned: success
- sample: 153
+ description: Service ID.
+ type: int
+ returned: success
+ sample: 153
service_name:
- description: service name
- type: str
- returned: success
- sample: app1
+ description: Service name.
+ type: str
+ returned: success
+ sample: app1
group_id:
- description: service's group id
- type: int
- returned: success
- sample: 1
+ description: Service's group ID.
+ type: int
+ returned: success
+ sample: 1
group_name:
- description: service's group name
- type: str
- returned: success
- sample: one-users
+ description: Service's group name.
+ type: str
+ returned: success
+ sample: one-users
owner_id:
- description: service's owner id
- type: int
- returned: success
- sample: 143
+ description: Service's owner ID.
+ type: int
+ returned: success
+ sample: 143
owner_name:
- description: service's owner name
- type: str
- returned: success
- sample: ansible-test
+ description: Service's owner name.
+ type: str
+ returned: success
+ sample: ansible-test
state:
- description: state of service instance
- type: str
- returned: success
- sample: RUNNING
+ description: State of service instance.
+ type: str
+ returned: success
+ sample: RUNNING
mode:
- description: service's mode
- type: int
- returned: success
- sample: 660
+ description: Service's mode.
+ type: int
+ returned: success
+ sample: 660
roles:
- description: list of dictionaries of roles, each role is described by name, cardinality, state and nodes ids
- type: list
- returned: success
- sample:
- - {"cardinality": 1,"name": "foo","state": "RUNNING", "ids": [ 123, 456 ]}
- - {"cardinality": 2,"name": "bar","state": "RUNNING", "ids": [ 452, 567, 746 ]}
-'''
+ description: List of dictionaries of roles, each role is described by name, cardinality, state and nodes IDs.
+ type: list
+ returned: success
+ sample:
+ - {"cardinality": 1, "name": "foo", "state": "RUNNING", "ids": [123, 456]}
+ - {"cardinality": 2, "name": "bar", "state": "RUNNING", "ids": [452, 567, 746]}
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/one_template.py b/plugins/modules/one_template.py
index 1fcc81c540..71db2c1d2c 100644
--- a/plugins/modules/one_template.py
+++ b/plugins/modules/one_template.py
@@ -9,8 +9,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: one_template
short_description: Manages OpenNebula templates
@@ -21,27 +20,25 @@ requirements:
- pyone
description:
- - "Manages OpenNebula templates."
-
+ - Manages OpenNebula templates.
attributes:
check_mode:
support: partial
details:
- - Note that check mode always returns C(changed=true) for existing templates, even if the template would not actually change.
+ - Note that check mode always returns C(changed=true) for existing templates, even if the template would not actually
+ change.
diff_mode:
support: none
options:
id:
description:
- - A O(id) of the template you would like to manage. If not set then a
- - new template will be created with the given O(name).
+ - A O(id) of the template you would like to manage. If not set then a new template will be created with the given O(name).
type: int
name:
description:
- - A O(name) of the template you would like to manage. If a template with
- - the given name does not exist it will be created, otherwise it will be
- - managed by this module.
+ - A O(name) of the template you would like to manage. If a template with the given name does not exist it will be created,
+ otherwise it will be managed by this module.
type: str
template:
description:
@@ -54,6 +51,16 @@ options:
choices: ["present", "absent"]
default: present
type: str
+ filter:
+ description:
+ - V(user_primary_group) - Resources belonging to the user's primary group.
+ - V(user) - Resources belonging to the user.
+ - V(all) - All resources.
+ - V(user_groups) - Resources belonging to the user and any of his groups.
+ choices: [user_primary_group, user, all, user_groups]
+ default: user
+ type: str
+ version_added: 10.3.0
extends_documentation_fragment:
- community.general.opennebula
@@ -61,9 +68,9 @@ extends_documentation_fragment:
author:
- "Jyrki Gadinger (@nilsding)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Fetch the TEMPLATE by id
community.general.one_template:
id: 6459
@@ -110,44 +117,44 @@ EXAMPLES = '''
community.general.one_template:
id: 6459
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
id:
- description: template id
- type: int
- returned: when O(state=present)
- sample: 153
+ description: Template ID.
+ type: int
+ returned: when O(state=present)
+ sample: 153
name:
- description: template name
- type: str
- returned: when O(state=present)
- sample: app1
+ description: Template name.
+ type: str
+ returned: when O(state=present)
+ sample: app1
template:
- description: the parsed template
- type: dict
- returned: when O(state=present)
+ description: The parsed template.
+ type: dict
+ returned: when O(state=present)
group_id:
- description: template's group id
- type: int
- returned: when O(state=present)
- sample: 1
+ description: Template's group ID.
+ type: int
+ returned: when O(state=present)
+ sample: 1
group_name:
- description: template's group name
- type: str
- returned: when O(state=present)
- sample: one-users
+ description: Template's group name.
+ type: str
+ returned: when O(state=present)
+ sample: one-users
owner_id:
- description: template's owner id
- type: int
- returned: when O(state=present)
- sample: 143
+ description: Template's owner ID.
+ type: int
+ returned: when O(state=present)
+ sample: 143
owner_name:
- description: template's owner name
- type: str
- returned: when O(state=present)
- sample: ansible-test
-'''
+ description: Template's owner name.
+ type: str
+ returned: when O(state=present)
+ sample: ansible-test
+"""
from ansible_collections.community.general.plugins.module_utils.opennebula import OpenNebulaModule
@@ -160,6 +167,7 @@ class TemplateModule(OpenNebulaModule):
name=dict(type='str', required=False),
state=dict(type='str', choices=['present', 'absent'], default='present'),
template=dict(type='str', required=False),
+ filter=dict(type='str', required=False, choices=['user_primary_group', 'user', 'all', 'user_groups'], default='user'),
)
mutually_exclusive = [
@@ -185,10 +193,11 @@ class TemplateModule(OpenNebulaModule):
name = params.get('name')
desired_state = params.get('state')
template_data = params.get('template')
+ filter = params.get('filter')
self.result = {}
- template = self.get_template_instance(id, name)
+ template = self.get_template_instance(id, name, filter)
needs_creation = False
if not template and desired_state != 'absent':
if id:
@@ -200,16 +209,19 @@ class TemplateModule(OpenNebulaModule):
self.result = self.delete_template(template)
else:
if needs_creation:
- self.result = self.create_template(name, template_data)
+ self.result = self.create_template(name, template_data, filter)
else:
- self.result = self.update_template(template, template_data)
+ self.result = self.update_template(template, template_data, filter)
self.exit()
- def get_template(self, predicate):
- # -3 means "Resources belonging to the user"
+ def get_template(self, predicate, filter):
+ # filter was included, for discussions see:
+ # Issue: https://github.com/ansible-collections/community.general/issues/9278
+ # PR: https://github.com/ansible-collections/community.general/pull/9547
# the other two parameters are used for pagination, -1 for both essentially means "return all"
- pool = self.one.templatepool.info(-3, -1, -1)
+ filter_values = {'user_primary_group': -4, 'user': -3, 'all': -2, 'user_groups': -1}
+ pool = self.one.templatepool.info(filter_values[filter], -1, -1)
for template in pool.VMTEMPLATE:
if predicate(template):
@@ -217,17 +229,17 @@ class TemplateModule(OpenNebulaModule):
return None
- def get_template_by_id(self, template_id):
- return self.get_template(lambda template: (template.ID == template_id))
+ def get_template_by_id(self, template_id, filter):
+ return self.get_template(lambda template: (template.ID == template_id), filter)
- def get_template_by_name(self, name):
- return self.get_template(lambda template: (template.NAME == name))
+ def get_template_by_name(self, name, filter):
+ return self.get_template(lambda template: (template.NAME == name), filter)
- def get_template_instance(self, requested_id, requested_name):
+ def get_template_instance(self, requested_id, requested_name, filter):
if requested_id:
- return self.get_template_by_id(requested_id)
+ return self.get_template_by_id(requested_id, filter)
else:
- return self.get_template_by_name(requested_name)
+ return self.get_template_by_name(requested_name, filter)
def get_template_info(self, template):
info = {
@@ -242,21 +254,21 @@ class TemplateModule(OpenNebulaModule):
return info
- def create_template(self, name, template_data):
+ def create_template(self, name, template_data, filter):
if not self.module.check_mode:
self.one.template.allocate("NAME = \"" + name + "\"\n" + template_data)
- result = self.get_template_info(self.get_template_by_name(name))
+ result = self.get_template_info(self.get_template_by_name(name, filter))
result['changed'] = True
return result
- def update_template(self, template, template_data):
+ def update_template(self, template, template_data, filter):
if not self.module.check_mode:
# 0 = replace the whole template
self.one.template.update(template.ID, template_data, 0)
- result = self.get_template_info(self.get_template_by_id(template.ID))
+ result = self.get_template_info(self.get_template_by_id(template.ID, filter))
if self.module.check_mode:
# Unfortunately it is not easy to detect if the template would have changed, therefore always report a change here.
result['changed'] = True
diff --git a/plugins/modules/one_vm.py b/plugins/modules/one_vm.py
index 2f4ee25354..0b6d27aae9 100644
--- a/plugins/modules/one_vm.py
+++ b/plugins/modules/one_vm.py
@@ -9,12 +9,11 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: one_vm
short_description: Creates or terminates OpenNebula instances
description:
- - Manages OpenNebula instances
+ - Manages OpenNebula instances.
requirements:
- pyone
extends_documentation_fragment:
@@ -28,49 +27,47 @@ options:
api_url:
description:
- URL of the OpenNebula RPC server.
- - It is recommended to use HTTPS so that the username/password are not
- transferred over the network unencrypted.
+ - It is recommended to use HTTPS so that the username/password are not transferred over the network unencrypted.
- If not set then the value of the E(ONE_URL) environment variable is used.
type: str
api_username:
description:
- - Name of the user to login into the OpenNebula RPC server. If not set
- then the value of the E(ONE_USERNAME) environment variable is used.
+ - Name of the user to login into the OpenNebula RPC server. If not set then the value of the E(ONE_USERNAME) environment
+ variable is used.
type: str
api_password:
description:
- - Password of the user to login into OpenNebula RPC server. If not set
- then the value of the E(ONE_PASSWORD) environment variable is used.
- if both O(api_username) or O(api_password) are not set, then it will try
- authenticate with ONE auth file. Default path is "~/.one/one_auth".
+ - Password of the user to login into OpenNebula RPC server. If not set then the value of the E(ONE_PASSWORD) environment
+ variable is used. if both O(api_username) or O(api_password) are not set, then it will try authenticate with ONE auth
+ file. Default path is C(~/.one/one_auth).
- Set environment variable E(ONE_AUTH) to override this path.
type: str
template_name:
description:
- - Name of VM template to use to create a new instance
+ - Name of VM template to use to create a new instance.
type: str
template_id:
description:
- - ID of a VM template to use to create a new instance
+ - ID of a VM template to use to create a new instance.
type: int
vm_start_on_hold:
description:
- - Set to true to put vm on hold while creating
+ - Set to true to put vm on hold while creating.
default: false
type: bool
instance_ids:
description:
- - 'A list of instance ids used for states: V(absent), V(running), V(rebooted), V(poweredoff).'
+ - 'A list of instance IDs used for states: V(absent), V(running), V(rebooted), V(poweredoff).'
aliases: ['ids']
type: list
elements: int
state:
description:
- V(present) - create instances from a template specified with C(template_id)/C(template_name).
- - V(running) - run instances
- - V(poweredoff) - power-off instances
- - V(rebooted) - reboot instances
- - V(absent) - terminate instances
+ - V(running) - run instances.
+ - V(poweredoff) - power-off instances.
+ - V(rebooted) - reboot instances.
+ - V(absent) - terminate instances.
choices: ["present", "absent", "running", "rebooted", "poweredoff"]
default: present
type: str
@@ -81,92 +78,81 @@ options:
type: bool
wait:
description:
- - Wait for the instance to reach its desired state before returning. Keep
- in mind if you are waiting for instance to be in running state it
- doesn't mean that you will be able to SSH on that machine only that
- boot process have started on that instance, see 'wait_for' example for
- details.
+ - Wait for the instance to reach its desired state before returning. Keep in mind if you are waiting for instance to
+ be in running state it does not mean that you will be able to SSH on that machine only that boot process have started
+ on that instance. See the example using the M(ansible.builtin.wait_for) module for details.
default: true
type: bool
wait_timeout:
description:
- - How long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
default: 300
type: int
attributes:
description:
- - A dictionary of key/value attributes to add to new instances, or for
- setting C(state) of instances with these attributes.
+ - A dictionary of key/value attributes to add to new instances, or for setting C(state) of instances with these attributes.
- Keys are case insensitive and OpenNebula automatically converts them to upper case.
- - Be aware C(NAME) is a special attribute which sets the name of the VM when it's deployed.
- - C(#) character(s) can be appended to the C(NAME) and the module will automatically add
- indexes to the names of VMs.
- - For example':' C(NAME':' foo-###) would create VMs with names C(foo-000), C(foo-001),...
- - When used with O(count_attributes) and O(exact_count) the module will
- match the base name without the index part.
+ - Be aware V(NAME) is a special attribute which sets the name of the VM when it is deployed.
+ - C(#) character(s) can be appended to the C(NAME) and the module will automatically add indexes to the names of VMs.
+ - 'For example: V(NAME: foo-###) would create VMs with names V(foo-000), V(foo-001),...'
+ - When used with O(count_attributes) and O(exact_count) the module will match the base name without the index part.
default: {}
type: dict
labels:
description:
- - A list of labels to associate with new instances, or for setting
- C(state) of instances with these labels.
+ - A list of labels to associate with new instances, or for setting C(state) of instances with these labels.
default: []
type: list
elements: str
count_attributes:
description:
- - A dictionary of key/value attributes that can only be used with
- O(exact_count) to determine how many nodes based on a specific
- attributes criteria should be deployed. This can be expressed in
- multiple ways and is shown in the EXAMPLES section.
+ - A dictionary of key/value attributes that can only be used with O(exact_count) to determine how many nodes based on
+ a specific attributes criteria should be deployed. This can be expressed in multiple ways and is shown in the EXAMPLES
+ section.
type: dict
count_labels:
description:
- - A list of labels that can only be used with O(exact_count) to determine
- how many nodes based on a specific labels criteria should be deployed.
- This can be expressed in multiple ways and is shown in the EXAMPLES
- section.
+ - A list of labels that can only be used with O(exact_count) to determine how many nodes based on a specific labels
+ criteria should be deployed. This can be expressed in multiple ways and is shown in the EXAMPLES section.
type: list
elements: str
count:
description:
- - Number of instances to launch
+ - Number of instances to launch.
default: 1
type: int
exact_count:
description:
- - Indicates how many instances that match O(count_attributes) and
- O(count_labels) parameters should be deployed. Instances are either
- created or terminated based on this value.
- - 'B(NOTE:) Instances with the least IDs will be terminated first.'
+ - Indicates how many instances that match O(count_attributes) and O(count_labels) parameters should be deployed. Instances
+ are either created or terminated based on this value.
+ - B(NOTE:) Instances with the least IDs will be terminated first.
type: int
mode:
description:
- - Set permission mode of the instance in octet format, for example V(0600) to give owner C(use) and C(manage) and nothing to group and others.
+ - Set permission mode of the instance in octet format, for example V(0600) to give owner C(use) and C(manage) and nothing
+ to group and others.
type: str
owner_id:
description:
- - ID of the user which will be set as the owner of the instance
+ - ID of the user which will be set as the owner of the instance.
type: int
group_id:
description:
- - ID of the group which will be set as the group of the instance
+ - ID of the group which will be set as the group of the instance.
type: int
memory:
description:
- - The size of the memory for new instances (in MB, GB, ...)
+ - The size of the memory for new instances (in MB, GB, ..).
type: str
disk_size:
description:
- The size of the disk created for new instances (in MB, GB, TB,...).
- - 'B(NOTE:) If The Template hats Multiple Disks the Order of the Sizes is
- matched against the order specified in O(template_id)/O(template_name).'
+ - B(NOTE:) If The Template hats Multiple Disks the Order of the Sizes is matched against the order specified in O(template_id)/O(template_name).
type: list
elements: str
cpu:
description:
- - Percentage of CPU divided by 100 required for the new instance. Half a
- processor is written 0.5.
+ - Percentage of CPU divided by 100 required for the new instance. Half a processor is written 0.5.
type: float
vcpu:
description:
@@ -183,8 +169,8 @@ options:
- Creates an image from a VM disk.
- It is a dictionary where you have to specify C(name) of the new image.
- Optionally you can specify C(disk_id) of the disk you want to save. By default C(disk_id) is 0.
- - 'B(NOTE:) This operation will only be performed on the first VM (if more than one VM ID is passed)
- and the VM has to be in the C(poweredoff) state.'
+ - B(NOTE:) This operation will only be performed on the first VM (if more than one VM ID is passed) and the VM has to
+ be in the C(poweredoff) state.
- Also this operation will fail if an image with specified C(name) already exists.
type: dict
persistent:
@@ -195,28 +181,28 @@ options:
version_added: '0.2.0'
datastore_id:
description:
- - Name of Datastore to use to create a new instance
+ - Name of Datastore to use to create a new instance.
version_added: '0.2.0'
type: int
datastore_name:
description:
- - Name of Datastore to use to create a new instance
+ - Name of Datastore to use to create a new instance.
version_added: '0.2.0'
type: str
updateconf:
description:
- When O(instance_ids) is provided, updates running VMs with the C(updateconf) API call.
- - When new VMs are being created, emulates the C(updateconf) API call via direct template merge.
+ - When new VMs are being created, emulates the C(updateconf) API call using direct template merge.
- Allows for complete modifications of the C(CONTEXT) attribute.
type: dict
version_added: 6.3.0
author:
- - "Milan Ilic (@ilicmilan)"
- - "Jan Meerkamp (@meerkampdvv)"
-'''
+ - "Milan Ilic (@ilicmilan)"
+ - "Jan Meerkamp (@meerkampdvv)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a new instance
community.general.one_vm:
template_id: 90
@@ -356,8 +342,9 @@ EXAMPLES = '''
register: vm
- name: Wait for SSH to come up
- ansible.builtin.wait_for_connection:
- delegate_to: '{{ vm.instances[0].networks[0].ip }}'
+ ansible.builtin.wait_for:
+ port: 22
+ host: '{{ vm.instances[0].networks[0].ip }}'
- name: Terminate VMs by ids
community.general.one_vm:
@@ -441,241 +428,220 @@ EXAMPLES = '''
SSH_PUBLIC_KEY: |-
ssh-rsa ...
ssh-ed25519 ...
-'''
+"""
-RETURN = '''
+RETURN = r"""
instances_ids:
- description: a list of instances ids whose state is changed or which are fetched with O(instance_ids) option.
- type: list
- returned: success
- sample: [ 1234, 1235 ]
+ description: A list of instances IDs whose state is changed or which are fetched with O(instance_ids) option.
+ type: list
+ returned: success
+ sample: [1234, 1235]
instances:
- description: a list of instances info whose state is changed or which are fetched with O(instance_ids) option.
- type: complex
- returned: success
- contains:
- vm_id:
- description: vm id
- type: int
- sample: 153
- vm_name:
- description: vm name
- type: str
- sample: foo
- template_id:
- description: vm's template id
- type: int
- sample: 153
- group_id:
- description: vm's group id
- type: int
- sample: 1
- group_name:
- description: vm's group name
- type: str
- sample: one-users
- owner_id:
- description: vm's owner id
- type: int
- sample: 143
- owner_name:
- description: vm's owner name
- type: str
- sample: app-user
- mode:
- description: vm's mode
- type: str
- returned: success
- sample: 660
- state:
- description: state of an instance
- type: str
- sample: ACTIVE
- lcm_state:
- description: lcm state of an instance that is only relevant when the state is ACTIVE
- type: str
- sample: RUNNING
- cpu:
- description: Percentage of CPU divided by 100
- type: float
- sample: 0.2
- vcpu:
- description: Number of CPUs (cores)
- type: int
- sample: 2
- memory:
- description: The size of the memory in MB
- type: str
- sample: 4096 MB
- disk_size:
- description: The size of the disk in MB
- type: str
- sample: 20480 MB
- networks:
- description: a list of dictionaries with info about IP, NAME, MAC, SECURITY_GROUPS for each NIC
- type: list
- sample: [
- {
- "ip": "10.120.5.33",
- "mac": "02:00:0a:78:05:21",
- "name": "default-test-private",
- "security_groups": "0,10"
- },
- {
- "ip": "10.120.5.34",
- "mac": "02:00:0a:78:05:22",
- "name": "default-test-private",
- "security_groups": "0"
- }
- ]
- uptime_h:
- description: Uptime of the instance in hours
- type: int
- sample: 35
- labels:
- description: A list of string labels that are associated with the instance
- type: list
- sample: [
- "foo",
- "spec-label"
- ]
- attributes:
- description: A dictionary of key/values attributes that are associated with the instance
- type: dict
- sample: {
- "HYPERVISOR": "kvm",
- "LOGO": "images/logos/centos.png",
- "TE_GALAXY": "bar",
- "USER_INPUTS": null
- }
- updateconf:
- description: A dictionary of key/values attributes that are set with the updateconf API call.
- type: dict
- version_added: 6.3.0
- sample: {
- "OS": { "ARCH": "x86_64" },
- "CONTEXT": {
- "START_SCRIPT": "ip r r 169.254.16.86/32 dev eth0",
- "SSH_PUBLIC_KEY": "ssh-rsa ...\\nssh-ed25519 ..."
- }
- }
+ description: A list of instances info whose state is changed or which are fetched with O(instance_ids) option.
+ type: complex
+ returned: success
+ contains:
+ vm_id:
+ description: Vm ID.
+ type: int
+ sample: 153
+ vm_name:
+ description: Vm name.
+ type: str
+ sample: foo
+ template_id:
+ description: Vm's template ID.
+ type: int
+ sample: 153
+ group_id:
+ description: Vm's group ID.
+ type: int
+ sample: 1
+ group_name:
+ description: Vm's group name.
+ type: str
+ sample: one-users
+ owner_id:
+ description: Vm's owner ID.
+ type: int
+ sample: 143
+ owner_name:
+ description: Vm's owner name.
+ type: str
+ sample: app-user
+ mode:
+ description: Vm's mode.
+ type: str
+ returned: success
+ sample: 660
+ state:
+ description: State of an instance.
+ type: str
+ sample: ACTIVE
+ lcm_state:
+ description: Lcm state of an instance that is only relevant when the state is ACTIVE.
+ type: str
+ sample: RUNNING
+ cpu:
+ description: Percentage of CPU divided by 100.
+ type: float
+ sample: 0.2
+ vcpu:
+ description: Number of CPUs (cores).
+ type: int
+ sample: 2
+ memory:
+ description: The size of the memory in MB.
+ type: str
+ sample: 4096 MB
+ disk_size:
+ description: The size of the disk in MB.
+ type: str
+ sample: 20480 MB
+ networks:
+ description: A list of dictionaries with info about IP, NAME, MAC, SECURITY_GROUPS for each NIC.
+ type: list
+ sample: [
+ {
+ "ip": "10.120.5.33",
+ "mac": "02:00:0a:78:05:21",
+ "name": "default-test-private",
+ "security_groups": "0,10"
+ },
+ {
+ "ip": "10.120.5.34",
+ "mac": "02:00:0a:78:05:22",
+ "name": "default-test-private",
+ "security_groups": "0"
+ }
+ ]
+ uptime_h:
+ description: Uptime of the instance in hours.
+ type: int
+ sample: 35
+ labels:
+ description: A list of string labels that are associated with the instance.
+ type: list
+ sample: ["foo", "spec-label"]
+ attributes:
+ description: A dictionary of key/values attributes that are associated with the instance.
+ type: dict
+ sample: {
+ "HYPERVISOR": "kvm",
+ "LOGO": "images/logos/centos.png",
+ "TE_GALAXY": "bar",
+ "USER_INPUTS": null
+ }
+ updateconf:
+ description: A dictionary of key/values attributes that are set with the updateconf API call.
+ type: dict
+ version_added: 6.3.0
+ sample: {
+ "OS": { "ARCH": "x86_64" },
+ "CONTEXT": {
+ "START_SCRIPT": "ip r r 169.254.16.86/32 dev eth0",
+ "SSH_PUBLIC_KEY": "ssh-rsa ...\\nssh-ed25519 ..."
+ }
+ }
tagged_instances:
- description:
- - A list of instances info based on a specific attributes and/or
- - labels that are specified with O(count_attributes) and O(count_labels)
- - options.
- type: complex
- returned: success
- contains:
- vm_id:
- description: vm id
- type: int
- sample: 153
- vm_name:
- description: vm name
- type: str
- sample: foo
- template_id:
- description: vm's template id
- type: int
- sample: 153
- group_id:
- description: vm's group id
- type: int
- sample: 1
- group_name:
- description: vm's group name
- type: str
- sample: one-users
- owner_id:
- description: vm's user id
- type: int
- sample: 143
- owner_name:
- description: vm's user name
- type: str
- sample: app-user
- mode:
- description: vm's mode
- type: str
- returned: success
- sample: 660
- state:
- description: state of an instance
- type: str
- sample: ACTIVE
- lcm_state:
- description: lcm state of an instance that is only relevant when the state is ACTIVE
- type: str
- sample: RUNNING
- cpu:
- description: Percentage of CPU divided by 100
- type: float
- sample: 0.2
- vcpu:
- description: Number of CPUs (cores)
- type: int
- sample: 2
- memory:
- description: The size of the memory in MB
- type: str
- sample: 4096 MB
- disk_size:
- description: The size of the disk in MB
- type: list
- sample: [
- "20480 MB",
- "10240 MB"
- ]
- networks:
- description: a list of dictionaries with info about IP, NAME, MAC, SECURITY_GROUPS for each NIC
- type: list
- sample: [
- {
- "ip": "10.120.5.33",
- "mac": "02:00:0a:78:05:21",
- "name": "default-test-private",
- "security_groups": "0,10"
- },
- {
- "ip": "10.120.5.34",
- "mac": "02:00:0a:78:05:22",
- "name": "default-test-private",
- "security_groups": "0"
- }
- ]
- uptime_h:
- description: Uptime of the instance in hours
- type: int
- sample: 35
- labels:
- description: A list of string labels that are associated with the instance
- type: list
- sample: [
- "foo",
- "spec-label"
- ]
- attributes:
- description: A dictionary of key/values attributes that are associated with the instance
- type: dict
- sample: {
- "HYPERVISOR": "kvm",
- "LOGO": "images/logos/centos.png",
- "TE_GALAXY": "bar",
- "USER_INPUTS": null
- }
- updateconf:
- description: A dictionary of key/values attributes that are set with the updateconf API call
- type: dict
- version_added: 6.3.0
- sample: {
- "OS": { "ARCH": "x86_64" },
- "CONTEXT": {
- "START_SCRIPT": "ip r r 169.254.16.86/32 dev eth0",
- "SSH_PUBLIC_KEY": "ssh-rsa ...\\nssh-ed25519 ..."
- }
- }
-'''
+ description:
+ - A list of instances info based on a specific attributes and/or labels that are specified with O(count_attributes) and
+ O(count_labels) options.
+ type: complex
+ returned: success
+ contains:
+ vm_id:
+ description: Vm ID.
+ type: int
+ sample: 153
+ vm_name:
+ description: Vm name.
+ type: str
+ sample: foo
+ template_id:
+ description: Vm's template ID.
+ type: int
+ sample: 153
+ group_id:
+ description: Vm's group ID.
+ type: int
+ sample: 1
+ group_name:
+ description: Vm's group name.
+ type: str
+ sample: one-users
+ owner_id:
+ description: Vm's user ID.
+ type: int
+ sample: 143
+ owner_name:
+ description: Vm's user name.
+ type: str
+ sample: app-user
+ mode:
+ description: Vm's mode.
+ type: str
+ returned: success
+ sample: 660
+ state:
+ description: State of an instance.
+ type: str
+ sample: ACTIVE
+ lcm_state:
+ description: Lcm state of an instance that is only relevant when the state is ACTIVE.
+ type: str
+ sample: RUNNING
+ cpu:
+ description: Percentage of CPU divided by 100.
+ type: float
+ sample: 0.2
+ vcpu:
+ description: Number of CPUs (cores).
+ type: int
+ sample: 2
+ memory:
+ description: The size of the memory in MB.
+ type: str
+ sample: 4096 MB
+ disk_size:
+ description: The size of the disk in MB.
+ type: list
+ sample: ["20480 MB", "10240 MB"]
+ networks:
+ description: A list of dictionaries with info about IP, NAME, MAC, SECURITY_GROUPS for each NIC.
+ type: list
+ sample: [
+ {
+ "ip": "10.120.5.33",
+ "mac": "02:00:0a:78:05:21",
+ "name": "default-test-private",
+ "security_groups": "0,10"
+ },
+ {
+ "ip": "10.120.5.34",
+ "mac": "02:00:0a:78:05:22",
+ "name": "default-test-private",
+ "security_groups": "0"
+ }
+ ]
+ uptime_h:
+ description: Uptime of the instance in hours.
+ type: int
+ sample: 35
+ labels:
+ description: A list of string labels that are associated with the instance.
+ type: list
+ sample: ["foo", "spec-label"]
+ attributes:
+ description: A dictionary of key/values attributes that are associated with the instance.
+ type: dict
+ sample: {"HYPERVISOR": "kvm", "LOGO": "images/logos/centos.png", "TE_GALAXY": "bar", "USER_INPUTS": null}
+ updateconf:
+ description: A dictionary of key/values attributes that are set with the updateconf API call.
+ type: dict
+ version_added: 6.3.0
+ sample: {"OS": {"ARCH": "x86_64"}, "CONTEXT": {"START_SCRIPT": "ip r r 169.254.16.86/32 dev eth0", "SSH_PUBLIC_KEY": "ssh-rsa ...\\nssh-ed25519 ..."}}
+"""
try:
import pyone
diff --git a/plugins/modules/one_vnet.py b/plugins/modules/one_vnet.py
index 2dcf20de5f..b8cb0c6559 100644
--- a/plugins/modules/one_vnet.py
+++ b/plugins/modules/one_vnet.py
@@ -9,8 +9,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: one_vnet
short_description: Manages OpenNebula virtual networks
version_added: 9.4.0
@@ -23,7 +22,8 @@ attributes:
check_mode:
support: partial
details:
- - Note that check mode always returns C(changed=true) for existing networks, even if the network would not actually change.
+ - Note that check mode always returns C(changed=true) for existing networks, even if the network would not actually
+ change.
diff_mode:
support: none
options:
@@ -34,9 +34,8 @@ options:
type: int
name:
description:
- - A O(name) of the network you would like to manage. If a network with
- the given name does not exist it will be created, otherwise it will be
- managed by this module.
+ - A O(name) of the network you would like to manage. If a network with the given name does not exist it will be created,
+ otherwise it will be managed by this module.
type: str
template:
description:
@@ -53,9 +52,9 @@ options:
extends_documentation_fragment:
- community.general.opennebula
- community.general.attributes
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Make sure the network is present by ID
community.general.one_vnet:
id: 0
@@ -87,174 +86,174 @@ EXAMPLES = '''
community.general.one_vnet:
id: 0
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
id:
- description: The network id.
- type: int
- returned: when O(state=present)
- sample: 153
+ description: The network ID.
+ type: int
+ returned: when O(state=present)
+ sample: 153
name:
- description: The network name.
- type: str
- returned: when O(state=present)
- sample: app1
+ description: The network name.
+ type: str
+ returned: when O(state=present)
+ sample: app1
template:
- description: The parsed network template.
- type: dict
- returned: when O(state=present)
- sample:
- BRIDGE: onebr.1000
- BRIDGE_TYPE: linux
- DESCRIPTION: sampletext
- PHYDEV: eth0
- SECURITY_GROUPS: 0
- VLAN_ID: 1000
- VN_MAD: 802.1Q
+ description: The parsed network template.
+ type: dict
+ returned: when O(state=present)
+ sample:
+ BRIDGE: onebr.1000
+ BRIDGE_TYPE: linux
+ DESCRIPTION: sampletext
+ PHYDEV: eth0
+ SECURITY_GROUPS: 0
+ VLAN_ID: 1000
+ VN_MAD: 802.1Q
user_id:
- description: The network's user name.
- type: int
- returned: when O(state=present)
- sample: 1
+ description: The network's user name.
+ type: int
+ returned: when O(state=present)
+ sample: 1
user_name:
- description: The network's user id.
- type: str
- returned: when O(state=present)
- sample: oneadmin
+ description: The network's user ID.
+ type: str
+ returned: when O(state=present)
+ sample: oneadmin
group_id:
- description: The network's group id.
- type: int
- returned: when O(state=present)
- sample: 1
+ description: The network's group ID.
+ type: int
+ returned: when O(state=present)
+ sample: 1
group_name:
- description: The network's group name.
- type: str
- returned: when O(state=present)
- sample: one-users
+ description: The network's group name.
+ type: str
+ returned: when O(state=present)
+ sample: one-users
owner_id:
- description: The network's owner id.
- type: int
- returned: when O(state=present)
- sample: 143
+ description: The network's owner ID.
+ type: int
+ returned: when O(state=present)
+ sample: 143
owner_name:
- description: The network's owner name.
- type: str
- returned: when O(state=present)
- sample: ansible-test
+ description: The network's owner name.
+ type: str
+ returned: when O(state=present)
+ sample: ansible-test
permissions:
- description: The network's permissions.
- type: dict
- returned: when O(state=present)
- contains:
- owner_u:
- description: The network's owner USAGE permissions.
- type: str
- sample: 1
- owner_m:
- description: The network's owner MANAGE permissions.
- type: str
- sample: 0
- owner_a:
- description: The network's owner ADMIN permissions.
- type: str
- sample: 0
- group_u:
- description: The network's group USAGE permissions.
- type: str
- sample: 0
- group_m:
- description: The network's group MANAGE permissions.
- type: str
- sample: 0
- group_a:
- description: The network's group ADMIN permissions.
- type: str
- sample: 0
- other_u:
- description: The network's other users USAGE permissions.
- type: str
- sample: 0
- other_m:
- description: The network's other users MANAGE permissions.
- type: str
- sample: 0
- other_a:
- description: The network's other users ADMIN permissions
- type: str
- sample: 0
- sample:
- owner_u: 1
- owner_m: 0
- owner_a: 0
- group_u: 0
- group_m: 0
- group_a: 0
- other_u: 0
- other_m: 0
- other_a: 0
+ description: The network's permissions.
+ type: dict
+ returned: when O(state=present)
+ contains:
+ owner_u:
+ description: The network's owner USAGE permissions.
+ type: str
+ sample: 1
+ owner_m:
+ description: The network's owner MANAGE permissions.
+ type: str
+ sample: 0
+ owner_a:
+ description: The network's owner ADMIN permissions.
+ type: str
+ sample: 0
+ group_u:
+ description: The network's group USAGE permissions.
+ type: str
+ sample: 0
+ group_m:
+ description: The network's group MANAGE permissions.
+ type: str
+ sample: 0
+ group_a:
+ description: The network's group ADMIN permissions.
+ type: str
+ sample: 0
+ other_u:
+ description: The network's other users USAGE permissions.
+ type: str
+ sample: 0
+ other_m:
+ description: The network's other users MANAGE permissions.
+ type: str
+ sample: 0
+ other_a:
+ description: The network's other users ADMIN permissions.
+ type: str
+ sample: 0
+ sample:
+ owner_u: 1
+ owner_m: 0
+ owner_a: 0
+ group_u: 0
+ group_m: 0
+ group_a: 0
+ other_u: 0
+ other_m: 0
+ other_a: 0
clusters:
- description: The network's clusters.
- type: list
- returned: when O(state=present)
- sample: [0, 100]
+ description: The network's clusters.
+ type: list
+ returned: when O(state=present)
+ sample: [0, 100]
bridge:
- description: The network's bridge interface.
- type: str
- returned: when O(state=present)
- sample: br0
+ description: The network's bridge interface.
+ type: str
+ returned: when O(state=present)
+ sample: br0
bridge_type:
- description: The network's bridge type.
- type: str
- returned: when O(state=present)
- sample: linux
+ description: The network's bridge type.
+ type: str
+ returned: when O(state=present)
+ sample: linux
parent_network_id:
- description: The network's parent network id.
- type: int
- returned: when O(state=present)
- sample: 1
+ description: The network's parent network ID.
+ type: int
+ returned: when O(state=present)
+ sample: 1
vn_mad:
- description: The network's VN_MAD.
- type: str
- returned: when O(state=present)
- sample: bridge
+ description: The network's VN_MAD.
+ type: str
+ returned: when O(state=present)
+ sample: bridge
phydev:
- description: The network's physical device (NIC).
- type: str
- returned: when O(state=present)
- sample: eth0
+ description: The network's physical device (NIC).
+ type: str
+ returned: when O(state=present)
+ sample: eth0
vlan_id:
- description: The network's VLAN tag.
- type: int
- returned: when O(state=present)
- sample: 1000
+ description: The network's VLAN tag.
+ type: int
+ returned: when O(state=present)
+ sample: 1000
outer_vlan_id:
- description: The network's outer VLAN tag.
- type: int
- returned: when O(state=present)
- sample: 1000
+ description: The network's outer VLAN tag.
+ type: int
+ returned: when O(state=present)
+ sample: 1000
vrouters:
- description: The network's list of virtual routers IDs.
- type: list
- returned: when O(state=present)
- sample: [0, 1]
+ description: The network's list of virtual routers IDs.
+ type: list
+ returned: when O(state=present)
+ sample: [0, 1]
ar_pool:
- description: The network's list of ar_pool.
- type: list
- returned: when O(state=present)
- sample:
- - ar_id: 0
- ip: 192.0.2.1
- mac: 6c:1e:46:01:cd:d1
- size: 20
- type: IP4
- - ar_id: 1
- allocated: 0
- ip: 198.51.100.1
- mac: 5d:9b:c0:9e:f6:e5
- size: 20
- type: IP4
-'''
+ description: The network's list of ar_pool.
+ type: list
+ returned: when O(state=present)
+ sample:
+ - ar_id: 0
+ ip: 192.0.2.1
+ mac: 6c:1e:46:01:cd:d1
+ size: 20
+ type: IP4
+ - ar_id: 1
+ allocated: 0
+ ip: 198.51.100.1
+ mac: 5d:9b:c0:9e:f6:e5
+ size: 20
+ type: IP4
+"""
from ansible_collections.community.general.plugins.module_utils.opennebula import OpenNebulaModule
diff --git a/plugins/modules/oneandone_firewall_policy.py b/plugins/modules/oneandone_firewall_policy.py
index dfcabf6f6e..743694cf90 100644
--- a/plugins/modules/oneandone_firewall_policy.py
+++ b/plugins/modules/oneandone_firewall_policy.py
@@ -7,13 +7,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneandone_firewall_policy
short_description: Configure 1&1 firewall policy
description:
- - Create, remove, reconfigure, update firewall policies.
- This module has a dependency on 1and1 >= 1.0.
+ - Create, remove, reconfigure, update firewall policies. This module has a dependency on 1and1 >= 1.0.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -28,21 +26,19 @@ options:
required: false
type: str
default: 'present'
- choices: [ "present", "absent", "update" ]
+ choices: ["present", "absent", "update"]
auth_token:
description:
- Authenticating API token provided by 1&1.
type: str
api_url:
description:
- - Custom API URL. Overrides the
- ONEANDONE_API_URL environment variable.
+ - Custom API URL. Overrides the E(ONEANDONE_API_URL) environment variable.
type: str
required: false
name:
description:
- - Firewall policy name used with present state. Used as identifier (id or name) when used with absent state.
- maxLength=128
+ - Firewall policy name used with present state. Used as identifier (id or name) when used with absent state. maxLength=128.
type: str
firewall_policy:
description:
@@ -50,61 +46,59 @@ options:
type: str
rules:
description:
- - A list of rules that will be set for the firewall policy.
- Each rule must contain protocol parameter, in addition to three optional parameters
- (port_from, port_to, and source)
+ - A list of rules that will be set for the firewall policy. Each rule must contain protocol parameter, in addition to
+ three optional parameters (port_from, port_to, and source).
type: list
elements: dict
default: []
add_server_ips:
description:
- - A list of server identifiers (id or name) to be assigned to a firewall policy.
- Used in combination with update state.
+ - A list of server identifiers (id or name) to be assigned to a firewall policy. Used in combination with update state.
type: list
elements: str
required: false
default: []
remove_server_ips:
description:
- - A list of server IP ids to be unassigned from a firewall policy. Used in combination with update state.
+ - A list of server IP IDs to be unassigned from a firewall policy. Used in combination with update state.
type: list
elements: str
required: false
default: []
add_rules:
description:
- - A list of rules that will be added to an existing firewall policy.
- It is syntax is the same as the one used for rules parameter. Used in combination with update state.
+ - A list of rules that will be added to an existing firewall policy. It is syntax is the same as the one used for rules
+ parameter. Used in combination with update state.
type: list
elements: dict
required: false
default: []
remove_rules:
description:
- - A list of rule ids that will be removed from an existing firewall policy. Used in combination with update state.
+ - A list of rule IDs that will be removed from an existing firewall policy. Used in combination with update state.
type: list
elements: str
required: false
default: []
description:
description:
- - Firewall policy description. maxLength=256
+ - Firewall policy description. maxLength=256.
type: str
required: false
wait:
description:
- - wait for the instance to be in state 'running' before returning
+ - Wait for the instance to be in state 'running' before returning.
required: false
default: true
type: bool
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
wait_interval:
description:
- - Defines the number of seconds to wait when using the _wait_for methods
+ - Defines the number of seconds to wait when using the _wait_for methods.
type: int
default: 5
@@ -112,22 +106,21 @@ requirements:
- "1and1"
author:
- - "Amel Ajdinovic (@aajdinov)"
- - "Ethan Devenport (@edevenport)"
-'''
+ - "Amel Ajdinovic (@aajdinov)"
+ - "Ethan Devenport (@edevenport)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a firewall policy
community.general.oneandone_firewall_policy:
auth_token: oneandone_private_api_key
name: ansible-firewall-policy
description: Testing creation of firewall policies with ansible
rules:
- -
- protocol: TCP
- port_from: 80
- port_to: 80
- source: 0.0.0.0
+ - protocol: TCP
+ port_from: 80
+ port_to: 80
+ source: 0.0.0.0
wait: true
wait_timeout: 500
@@ -150,8 +143,8 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
firewall_policy: ansible-firewall-policy-updated
add_server_ips:
- - server_identifier (id or name)
- - server_identifier #2 (id or name)
+ - server_identifier (id or name)
+ - server_identifier #2 (id or name)
wait: true
wait_timeout: 500
state: update
@@ -161,7 +154,7 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
firewall_policy: ansible-firewall-policy-updated
remove_server_ips:
- - B2504878540DBC5F7634EB00A07C1EBD (server's IP id)
+ - B2504878540DBC5F7634EB00A07C1EBD (server's IP id)
wait: true
wait_timeout: 500
state: update
@@ -172,16 +165,14 @@ EXAMPLES = '''
firewall_policy: ansible-firewall-policy-updated
description: Adding rules to an existing firewall policy
add_rules:
- -
- protocol: TCP
- port_from: 70
- port_to: 70
- source: 0.0.0.0
- -
- protocol: TCP
- port_from: 60
- port_to: 60
- source: 0.0.0.0
+ - protocol: TCP
+ port_from: 70
+ port_to: 70
+ source: 0.0.0.0
+ - protocol: TCP
+ port_from: 60
+ port_to: 60
+ source: 0.0.0.0
wait: true
wait_timeout: 500
state: update
@@ -191,21 +182,21 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
firewall_policy: ansible-firewall-policy-updated
remove_rules:
- - rule_id #1
- - rule_id #2
- - ...
+ - rule_id #1
+ - rule_id #2
+ - '...'
wait: true
wait_timeout: 500
state: update
-'''
+"""
-RETURN = '''
+RETURN = r"""
firewall_policy:
- description: Information about the firewall policy that was processed
- type: dict
- sample: '{"id": "92B74394A397ECC3359825C1656D67A6", "name": "Default Policy"}'
- returned: always
-'''
+ description: Information about the firewall policy that was processed.
+ type: dict
+ sample: '{"id": "92B74394A397ECC3359825C1656D67A6", "name": "Default Policy"}'
+ returned: always
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/oneandone_load_balancer.py b/plugins/modules/oneandone_load_balancer.py
index da361ef2dc..cb915e4efa 100644
--- a/plugins/modules/oneandone_load_balancer.py
+++ b/plugins/modules/oneandone_load_balancer.py
@@ -7,13 +7,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneandone_load_balancer
short_description: Configure 1&1 load balancer
description:
- - Create, remove, update load balancers.
- This module has a dependency on 1and1 >= 1.0.
+ - Create, remove, update load balancers. This module has a dependency on 1and1 >= 1.0.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -28,7 +26,7 @@ options:
type: str
required: false
default: 'present'
- choices: [ "present", "absent", "update" ]
+ choices: ["present", "absent", "update"]
auth_token:
description:
- Authenticating API token provided by 1&1.
@@ -39,32 +37,30 @@ options:
type: str
api_url:
description:
- - Custom API URL. Overrides the
- E(ONEANDONE_API_URL) environment variable.
+ - Custom API URL. Overrides the E(ONEANDONE_API_URL) environment variable.
type: str
required: false
name:
description:
- - Load balancer name used with present state. Used as identifier (id or name) when used with absent state.
- maxLength=128
+ - Load balancer name used with present state. Used as identifier (ID or name) when used with absent state. maxLength=128.
type: str
health_check_test:
description:
- Type of the health check. At the moment, HTTP is not allowed.
type: str
- choices: [ "NONE", "TCP", "HTTP", "ICMP" ]
+ choices: ["NONE", "TCP", "HTTP", "ICMP"]
health_check_interval:
description:
- - Health check period in seconds. minimum=5, maximum=300, multipleOf=1
+ - Health check period in seconds. minimum=5, maximum=300, multipleOf=1.
type: str
health_check_path:
description:
- - Url to call for checking. Required for HTTP health check. maxLength=1000
+ - URL to call for checking. Required for HTTP health check. maxLength=1000.
type: str
required: false
health_check_parse:
description:
- - Regular expression to check. Required for HTTP health check. maxLength=64
+ - Regular expression to check. Required for HTTP health check. maxLength=64.
type: str
required: false
persistence:
@@ -73,88 +69,87 @@ options:
type: bool
persistence_time:
description:
- - Persistence time in seconds. Required if persistence is enabled. minimum=30, maximum=1200, multipleOf=1
+ - Persistence time in seconds. Required if persistence is enabled. minimum=30, maximum=1200, multipleOf=1.
type: str
method:
description:
- Balancing procedure.
type: str
- choices: [ "ROUND_ROBIN", "LEAST_CONNECTIONS" ]
+ choices: ["ROUND_ROBIN", "LEAST_CONNECTIONS"]
datacenter:
description:
- ID or country code of the datacenter where the load balancer will be created.
- If not specified, it defaults to V(US).
type: str
- choices: [ "US", "ES", "DE", "GB" ]
+ choices: ["US", "ES", "DE", "GB"]
required: false
rules:
description:
- - A list of rule objects that will be set for the load balancer. Each rule must contain protocol,
- port_balancer, and port_server parameters, in addition to source parameter, which is optional.
+ - A list of rule objects that will be set for the load balancer. Each rule must contain protocol, port_balancer, and
+ port_server parameters, in addition to source parameter, which is optional.
type: list
elements: dict
default: []
description:
description:
- - Description of the load balancer. maxLength=256
+ - Description of the load balancer. maxLength=256.
type: str
required: false
add_server_ips:
description:
- - A list of server identifiers (id or name) to be assigned to a load balancer.
- Used in combination with update state.
+ - A list of server identifiers (id or name) to be assigned to a load balancer. Used in combination with O(state=update).
type: list
elements: str
required: false
default: []
remove_server_ips:
description:
- - A list of server IP ids to be unassigned from a load balancer. Used in combination with update state.
+ - A list of server IP IDs to be unassigned from a load balancer. Used in combination with O(state=update).
type: list
elements: str
required: false
default: []
add_rules:
description:
- - A list of rules that will be added to an existing load balancer.
- It is syntax is the same as the one used for rules parameter. Used in combination with update state.
+ - A list of rules that will be added to an existing load balancer. It is syntax is the same as the one used for rules
+ parameter. Used in combination with O(state=update).
type: list
elements: dict
required: false
default: []
remove_rules:
description:
- - A list of rule ids that will be removed from an existing load balancer. Used in combination with update state.
+ - A list of rule IDs that will be removed from an existing load balancer. Used in combination with O(state=update).
type: list
elements: str
required: false
default: []
wait:
description:
- - wait for the instance to be in state 'running' before returning
+ - Wait for the instance to be in state 'running' before returning.
required: false
default: true
type: bool
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
wait_interval:
description:
- - Defines the number of seconds to wait when using the _wait_for methods
+ - Defines the number of seconds to wait when using the _wait_for methods.
type: int
default: 5
requirements:
- - "1and1"
+ - "1and1"
author:
- Amel Ajdinovic (@aajdinov)
- Ethan Devenport (@edevenport)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a load balancer
community.general.oneandone_load_balancer:
auth_token: oneandone_private_api_key
@@ -167,11 +162,10 @@ EXAMPLES = '''
method: ROUND_ROBIN
datacenter: US
rules:
- -
- protocol: TCP
- port_balancer: 80
- port_server: 80
- source: 0.0.0.0
+ - protocol: TCP
+ port_balancer: 80
+ port_server: 80
+ source: 0.0.0.0
wait: true
wait_timeout: 500
@@ -199,7 +193,7 @@ EXAMPLES = '''
load_balancer: ansible load balancer updated
description: Adding server to a load balancer with ansible
add_server_ips:
- - server identifier (id or name)
+ - server identifier (id or name)
wait: true
wait_timeout: 500
state: update
@@ -210,7 +204,7 @@ EXAMPLES = '''
load_balancer: ansible load balancer updated
description: Removing server from a load balancer with ansible
remove_server_ips:
- - B2504878540DBC5F7634EB00A07C1EBD (server's ip id)
+ - B2504878540DBC5F7634EB00A07C1EBD (server's ip id)
wait: true
wait_timeout: 500
state: update
@@ -221,16 +215,14 @@ EXAMPLES = '''
load_balancer: ansible load balancer updated
description: Adding rules to a load balancer with ansible
add_rules:
- -
- protocol: TCP
- port_balancer: 70
- port_server: 70
- source: 0.0.0.0
- -
- protocol: TCP
- port_balancer: 60
- port_server: 60
- source: 0.0.0.0
+ - protocol: TCP
+ port_balancer: 70
+ port_server: 70
+ source: 0.0.0.0
+ - protocol: TCP
+ port_balancer: 60
+ port_server: 60
+ source: 0.0.0.0
wait: true
wait_timeout: 500
state: update
@@ -241,21 +233,21 @@ EXAMPLES = '''
load_balancer: ansible load balancer updated
description: Adding rules to a load balancer with ansible
remove_rules:
- - rule_id #1
- - rule_id #2
- - ...
+ - rule_id #1
+ - rule_id #2
+ - '...'
wait: true
wait_timeout: 500
state: update
-'''
+"""
-RETURN = '''
+RETURN = r"""
load_balancer:
- description: Information about the load balancer that was processed
- type: dict
- sample: '{"id": "92B74394A397ECC3359825C1656D67A6", "name": "Default Balancer"}'
- returned: always
-'''
+ description: Information about the load balancer that was processed.
+ type: dict
+ sample: '{"id": "92B74394A397ECC3359825C1656D67A6", "name": "Default Balancer"}'
+ returned: always
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/oneandone_monitoring_policy.py b/plugins/modules/oneandone_monitoring_policy.py
index abdf8ca7ad..a0aa17611e 100644
--- a/plugins/modules/oneandone_monitoring_policy.py
+++ b/plugins/modules/oneandone_monitoring_policy.py
@@ -7,14 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneandone_monitoring_policy
short_description: Configure 1&1 monitoring policy
description:
- - Create, remove, update monitoring policies
- (and add/remove ports, processes, and servers).
- This module has a dependency on 1and1 >= 1.0.
+ - Create, remove, update monitoring policies (and add/remove ports, processes, and servers). This module has a dependency
+ on 1and1 >= 1.0.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -29,20 +27,19 @@ options:
type: str
required: false
default: present
- choices: [ "present", "absent", "update" ]
+ choices: ["present", "absent", "update"]
auth_token:
description:
- Authenticating API token provided by 1&1.
type: str
api_url:
description:
- - Custom API URL. Overrides the
- ONEANDONE_API_URL environment variable.
+ - Custom API URL. Overrides the E(ONEANDONE_API_URL) environment variable.
type: str
required: false
name:
description:
- - Monitoring policy name used with present state. Used as identifier (id or name) when used with absent state. maxLength=128
+ - Monitoring policy name used with present state. Used as identifier (id or name) when used with absent state. maxLength=128.
type: str
monitoring_policy:
description:
@@ -54,19 +51,18 @@ options:
type: str
email:
description:
- - User's email. maxLength=128
+ - User's email. maxLength=128.
type: str
description:
description:
- - Monitoring policy description. maxLength=256
+ - Monitoring policy description. maxLength=256.
type: str
required: false
thresholds:
description:
- - Monitoring policy thresholds. Each of the suboptions have warning and critical,
- which both have alert and value suboptions. Warning is used to set limits for
- warning alerts, critical is used to set critical alerts. alert enables alert,
- and value is used to advise when the value is exceeded.
+ - Monitoring policy thresholds. Each of the suboptions have warning and critical, which both have alert and value suboptions.
+ Warning is used to set limits for warning alerts, critical is used to set critical alerts. alert enables alert, and
+ value is used to advise when the value is exceeded.
type: list
elements: dict
default: []
@@ -101,16 +97,16 @@ options:
protocol:
description:
- Internet protocol.
- choices: [ "TCP", "UDP" ]
+ choices: ["TCP", "UDP"]
required: true
port:
description:
- - Port number. minimum=1, maximum=65535
+ - Port number. minimum=1, maximum=65535.
required: true
alert_if:
description:
- Case of alert.
- choices: [ "RESPONDING", "NOT_RESPONDING" ]
+ choices: ["RESPONDING", "NOT_RESPONDING"]
required: true
email_notification:
description:
@@ -125,12 +121,12 @@ options:
suboptions:
process:
description:
- - Name of the process. maxLength=50
+ - Name of the process. maxLength=50.
required: true
alert_if:
description:
- Case of alert.
- choices: [ "RUNNING", "NOT_RUNNING" ]
+ choices: ["RUNNING", "NOT_RUNNING"]
required: true
add_ports:
description:
@@ -190,18 +186,18 @@ options:
default: []
wait:
description:
- - wait for the instance to be in state 'running' before returning
+ - Wait for the instance to be in state 'running' before returning.
required: false
default: true
type: bool
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
wait_interval:
description:
- - Defines the number of seconds to wait when using the _wait_for methods
+ - Defines the number of seconds to wait when using the _wait_for methods.
type: int
default: 5
@@ -209,11 +205,11 @@ requirements:
- "1and1"
author:
- - "Amel Ajdinovic (@aajdinov)"
- - "Ethan Devenport (@edevenport)"
-'''
+ - "Amel Ajdinovic (@aajdinov)"
+ - "Ethan Devenport (@edevenport)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a monitoring policy
community.general.oneandone_monitoring_policy:
auth_token: oneandone_private_api_key
@@ -222,57 +218,50 @@ EXAMPLES = '''
email: your@emailaddress.com
agent: true
thresholds:
- -
- cpu:
- warning:
- value: 80
- alert: false
- critical:
- value: 92
- alert: false
- -
- ram:
- warning:
- value: 80
- alert: false
- critical:
- value: 90
- alert: false
- -
- disk:
- warning:
- value: 80
- alert: false
- critical:
- value: 90
- alert: false
- -
- internal_ping:
- warning:
- value: 50
- alert: false
- critical:
- value: 100
- alert: false
- -
- transfer:
- warning:
- value: 1000
- alert: false
- critical:
- value: 2000
- alert: false
+ - cpu:
+ warning:
+ value: 80
+ alert: false
+ critical:
+ value: 92
+ alert: false
+ - ram:
+ warning:
+ value: 80
+ alert: false
+ critical:
+ value: 90
+ alert: false
+ - disk:
+ warning:
+ value: 80
+ alert: false
+ critical:
+ value: 90
+ alert: false
+ - internal_ping:
+ warning:
+ value: 50
+ alert: false
+ critical:
+ value: 100
+ alert: false
+ - transfer:
+ warning:
+ value: 1000
+ alert: false
+ critical:
+ value: 2000
+ alert: false
ports:
- -
- protocol: TCP
- port: 22
- alert_if: RESPONDING
- email_notification: false
+ - protocol: TCP
+ port: 22
+ alert_if: RESPONDING
+ email_notification: false
processes:
- -
- process: test
- alert_if: NOT_RUNNING
- email_notification: false
+ - process: test
+ alert_if: NOT_RUNNING
+ email_notification: false
wait: true
- name: Destroy a monitoring policy
@@ -289,46 +278,41 @@ EXAMPLES = '''
description: Testing creation of a monitoring policy with ansible updated
email: another@emailaddress.com
thresholds:
- -
- cpu:
- warning:
- value: 70
- alert: false
- critical:
- value: 90
- alert: false
- -
- ram:
- warning:
- value: 70
- alert: false
- critical:
- value: 80
- alert: false
- -
- disk:
- warning:
- value: 70
- alert: false
- critical:
- value: 80
- alert: false
- -
- internal_ping:
- warning:
- value: 60
- alert: false
- critical:
- value: 90
- alert: false
- -
- transfer:
- warning:
- value: 900
- alert: false
- critical:
- value: 1900
- alert: false
+ - cpu:
+ warning:
+ value: 70
+ alert: false
+ critical:
+ value: 90
+ alert: false
+ - ram:
+ warning:
+ value: 70
+ alert: false
+ critical:
+ value: 80
+ alert: false
+ - disk:
+ warning:
+ value: 70
+ alert: false
+ critical:
+ value: 80
+ alert: false
+ - internal_ping:
+ warning:
+ value: 60
+ alert: false
+ critical:
+ value: 90
+ alert: false
+ - transfer:
+ warning:
+ value: 900
+ alert: false
+ critical:
+ value: 1900
+ alert: false
wait: true
state: update
@@ -337,11 +321,10 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
monitoring_policy: ansible monitoring policy updated
add_ports:
- -
- protocol: TCP
- port: 33
- alert_if: RESPONDING
- email_notification: false
+ - protocol: TCP
+ port: 33
+ alert_if: RESPONDING
+ email_notification: false
wait: true
state: update
@@ -350,18 +333,16 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
monitoring_policy: ansible monitoring policy updated
update_ports:
- -
- id: existing_port_id
- protocol: TCP
- port: 34
- alert_if: RESPONDING
- email_notification: false
- -
- id: existing_port_id
- protocol: TCP
- port: 23
- alert_if: RESPONDING
- email_notification: false
+ - id: existing_port_id
+ protocol: TCP
+ port: 34
+ alert_if: RESPONDING
+ email_notification: false
+ - id: existing_port_id
+ protocol: TCP
+ port: 23
+ alert_if: RESPONDING
+ email_notification: false
wait: true
state: update
@@ -370,7 +351,7 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
monitoring_policy: ansible monitoring policy updated
remove_ports:
- - port_id
+ - port_id
state: update
- name: Add a process to a monitoring policy
@@ -378,10 +359,9 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
monitoring_policy: ansible monitoring policy updated
add_processes:
- -
- process: test_2
- alert_if: NOT_RUNNING
- email_notification: false
+ - process: test_2
+ alert_if: NOT_RUNNING
+ email_notification: false
wait: true
state: update
@@ -390,16 +370,14 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
monitoring_policy: ansible monitoring policy updated
update_processes:
- -
- id: process_id
- process: test_1
- alert_if: NOT_RUNNING
- email_notification: false
- -
- id: process_id
- process: test_3
- alert_if: NOT_RUNNING
- email_notification: false
+ - id: process_id
+ process: test_1
+ alert_if: NOT_RUNNING
+ email_notification: false
+ - id: process_id
+ process: test_3
+ alert_if: NOT_RUNNING
+ email_notification: false
wait: true
state: update
@@ -408,7 +386,7 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
monitoring_policy: ansible monitoring policy updated
remove_processes:
- - process_id
+ - process_id
wait: true
state: update
@@ -417,7 +395,7 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
monitoring_policy: ansible monitoring policy updated
add_servers:
- - server id or name
+ - server id or name
wait: true
state: update
@@ -426,18 +404,18 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
monitoring_policy: ansible monitoring policy updated
remove_servers:
- - server01
+ - server01
wait: true
state: update
-'''
+"""
-RETURN = '''
+RETURN = r"""
monitoring_policy:
- description: Information about the monitoring policy that was processed
- type: dict
- sample: '{"id": "92B74394A397ECC3359825C1656D67A6", "name": "Default Policy"}'
- returned: always
-'''
+ description: Information about the monitoring policy that was processed.
+ type: dict
+ sample: '{"id": "92B74394A397ECC3359825C1656D67A6", "name": "Default Policy"}'
+ returned: always
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/oneandone_private_network.py b/plugins/modules/oneandone_private_network.py
index cf74597edb..1a56fe345c 100644
--- a/plugins/modules/oneandone_private_network.py
+++ b/plugins/modules/oneandone_private_network.py
@@ -7,13 +7,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneandone_private_network
short_description: Configure 1&1 private networking
description:
- - Create, remove, reconfigure, update a private network.
- This module has a dependency on 1and1 >= 1.0.
+ - Create, remove, reconfigure, update a private network. This module has a dependency on 1and1 >= 1.0.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -28,7 +26,7 @@ options:
type: str
required: false
default: 'present'
- choices: [ "present", "absent", "update" ]
+ choices: ["present", "absent", "update"]
auth_token:
description:
- Authenticating API token provided by 1&1.
@@ -39,8 +37,7 @@ options:
type: str
api_url:
description:
- - Custom API URL. Overrides the
- ONEANDONE_API_URL environment variable.
+ - Custom API URL. Overrides the E(ONEANDONE_API_URL) environment variable.
type: str
required: false
name:
@@ -53,16 +50,16 @@ options:
type: str
datacenter:
description:
- - The identifier of the datacenter where the private network will be created
+ - The identifier of the datacenter where the private network will be created.
type: str
choices: [US, ES, DE, GB]
network_address:
description:
- - Set a private network space, i.e. 192.168.1.0
+ - Set a private network space, for example V(192.168.1.0).
type: str
subnet_mask:
description:
- - Set the netmask for the private network, i.e. 255.255.255.0
+ - Set the netmask for the private network, for example V(255.255.255.0).
type: str
add_members:
description:
@@ -78,30 +75,30 @@ options:
default: []
wait:
description:
- - wait for the instance to be in state 'running' before returning
+ - Wait for the instance to be in state 'running' before returning.
required: false
default: true
type: bool
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
wait_interval:
description:
- - Defines the number of seconds to wait when using the _wait_for methods
+ - Defines the number of seconds to wait when using the _wait_for methods.
type: int
default: 5
requirements:
- - "1and1"
+ - "1and1"
author:
- Amel Ajdinovic (@aajdinov)
- Ethan Devenport (@edevenport)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a private network
community.general.oneandone_private_network:
auth_token: oneandone_private_api_key
@@ -131,7 +128,7 @@ EXAMPLES = '''
state: update
private_network: backup_network
add_members:
- - server identifier (id or name)
+ - server identifier (id or name)
- name: Remove members from the private network
community.general.oneandone_private_network:
@@ -139,16 +136,16 @@ EXAMPLES = '''
state: update
private_network: backup_network
remove_members:
- - server identifier (id or name)
-'''
+ - server identifier (id or name)
+"""
-RETURN = '''
+RETURN = r"""
private_network:
- description: Information about the private network.
- type: dict
- sample: '{"name": "backup_network", "id": "55726DEDA20C99CF6F2AF8F18CAC9963"}'
- returned: always
-'''
+ description: Information about the private network.
+ type: dict
+ sample: '{"name": "backup_network", "id": "55726DEDA20C99CF6F2AF8F18CAC9963"}'
+ returned: always
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/oneandone_public_ip.py b/plugins/modules/oneandone_public_ip.py
index 2dceb41bff..c30c0bbdc7 100644
--- a/plugins/modules/oneandone_public_ip.py
+++ b/plugins/modules/oneandone_public_ip.py
@@ -7,13 +7,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneandone_public_ip
short_description: Configure 1&1 public IPs
description:
- - Create, update, and remove public IPs.
- This module has a dependency on 1and1 >= 1.0.
+ - Create, update, and remove public IPs. This module has a dependency on 1and1 >= 1.0.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -24,24 +22,23 @@ attributes:
options:
state:
description:
- - Define a public ip state to create, remove, or update.
+ - Define a public IP state to create, remove, or update.
type: str
required: false
default: 'present'
- choices: [ "present", "absent", "update" ]
+ choices: ["present", "absent", "update"]
auth_token:
description:
- Authenticating API token provided by 1&1.
type: str
api_url:
description:
- - Custom API URL. Overrides the
- ONEANDONE_API_URL environment variable.
+ - Custom API URL. Overrides the E(ONEANDONE_API_URL) environment variable.
type: str
required: false
reverse_dns:
description:
- - Reverse DNS name. maxLength=256
+ - Reverse DNS name. maxLength=256.
type: str
required: false
datacenter:
@@ -64,30 +61,30 @@ options:
type: str
wait:
description:
- - wait for the instance to be in state 'running' before returning
+ - Wait for the instance to be in state 'running' before returning.
required: false
default: true
type: bool
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
wait_interval:
description:
- - Defines the number of seconds to wait when using the _wait_for methods
+ - Defines the number of seconds to wait when using the _wait_for methods.
type: int
default: 5
requirements:
- - "1and1"
+ - "1and1"
author:
- Amel Ajdinovic (@aajdinov)
- Ethan Devenport (@edevenport)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a public IP
community.general.oneandone_public_ip:
auth_token: oneandone_private_api_key
@@ -107,15 +104,15 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
public_ip_id: public ip id
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
public_ip:
- description: Information about the public ip that was processed
- type: dict
- sample: '{"id": "F77CC589EBC120905B4F4719217BFF6D", "ip": "10.5.132.106"}'
- returned: always
-'''
+ description: Information about the public IP that was processed.
+ type: dict
+ sample: '{"id": "F77CC589EBC120905B4F4719217BFF6D", "ip": "10.5.132.106"}'
+ returned: always
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/oneandone_server.py b/plugins/modules/oneandone_server.py
index b6653b48b1..ae9198c7d0 100644
--- a/plugins/modules/oneandone_server.py
+++ b/plugins/modules/oneandone_server.py
@@ -7,13 +7,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneandone_server
short_description: Create, destroy, start, stop, and reboot a 1&1 Host server
description:
- - Create, destroy, update, start, stop, and reboot a 1&1 Host server.
- When the server is created it can optionally wait for it to be 'running' before returning.
+ - Create, destroy, update, start, stop, and reboot a 1&1 Host server. When the server is created it can optionally wait
+ for it to be 'running' before returning.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -27,23 +26,21 @@ options:
- Define a server's state to create, remove, start or stop it.
type: str
default: present
- choices: [ "present", "absent", "running", "stopped" ]
+ choices: ["present", "absent", "running", "stopped"]
auth_token:
description:
- - Authenticating API token provided by 1&1. Overrides the
- ONEANDONE_AUTH_TOKEN environment variable.
+ - Authenticating API token provided by 1&1. Overrides the E(ONEANDONE_AUTH_TOKEN) environment variable.
type: str
api_url:
description:
- - Custom API URL. Overrides the
- ONEANDONE_API_URL environment variable.
+ - Custom API URL. Overrides the E(ONEANDONE_API_URL) environment variable.
type: str
datacenter:
description:
- The datacenter location.
type: str
default: US
- choices: [ "US", "ES", "DE", "GB" ]
+ choices: ["US", "ES", "DE", "GB"]
hostname:
description:
- The hostname or ID of the server. Only used when state is 'present'.
@@ -54,35 +51,30 @@ options:
type: str
appliance:
description:
- - The operating system name or ID for the server.
- It is required only for 'present' state.
+ - The operating system name or ID for the server. It is required only for 'present' state.
type: str
fixed_instance_size:
description:
- - The instance size name or ID of the server.
- It is required only for 'present' state, and it is mutually exclusive with
- vcore, cores_per_processor, ram, and hdds parameters.
- - 'The available choices are: V(S), V(M), V(L), V(XL), V(XXL), V(3XL), V(4XL), V(5XL)'
+ - The instance size name or ID of the server. It is required only for 'present' state, and it is mutually exclusive
+ with vcore, cores_per_processor, ram, and hdds parameters.
+ - 'The available choices are: V(S), V(M), V(L), V(XL), V(XXL), V(3XL), V(4XL), V(5XL).'
type: str
vcore:
description:
- - The total number of processors.
- It must be provided with cores_per_processor, ram, and hdds parameters.
+ - The total number of processors. It must be provided with O(cores_per_processor), O(ram), and O(hdds) parameters.
type: int
cores_per_processor:
description:
- - The number of cores per processor.
- It must be provided with vcore, ram, and hdds parameters.
+ - The number of cores per processor. It must be provided with O(vcore), O(ram), and O(hdds) parameters.
type: int
ram:
description:
- - The amount of RAM memory.
- It must be provided with with vcore, cores_per_processor, and hdds parameters.
+ - The amount of RAM memory. It must be provided with with O(vcore), O(cores_per_processor), and O(hdds) parameters.
type: float
hdds:
description:
- - A list of hard disks with nested "size" and "is_main" properties.
- It must be provided with vcore, cores_per_processor, and ram parameters.
+ - A list of hard disks with nested O(ignore:hdds[].size) and O(ignore:hdds[].is_main) properties. It must be provided with O(vcore),
+ O(cores_per_processor), and O(ram) parameters.
type: list
elements: dict
private_network:
@@ -119,30 +111,27 @@ options:
- The type of server to be built.
type: str
default: "cloud"
- choices: [ "cloud", "baremetal", "k8s_node" ]
+ choices: ["cloud", "baremetal", "k8s_node"]
wait:
description:
- - Wait for the server to be in state 'running' before returning.
- Also used for delete operation (set to 'false' if you don't want to wait
- for each individual server to be deleted before moving on with
- other tasks.)
+ - Wait for the server to be in state 'running' before returning. Also used for delete operation (set to V(false) if
+ you do not want to wait for each individual server to be deleted before moving on with other tasks).
type: bool
default: true
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
wait_interval:
description:
- - Defines the number of seconds to wait when using the wait_for methods
+ - Defines the number of seconds to wait when using the wait_for methods.
type: int
default: 5
auto_increment:
description:
- - When creating multiple servers at once, whether to differentiate
- hostnames by appending a count after them or substituting the count
- where there is a %02d or %03d in the hostname string.
+ - When creating multiple servers at once, whether to differentiate hostnames by appending a count after them or substituting
+ the count where there is a %02d or %03d in the hostname string.
type: bool
default: true
@@ -150,12 +139,11 @@ requirements:
- "1and1"
author:
- - "Amel Ajdinovic (@aajdinov)"
- - "Ethan Devenport (@edevenport)"
+ - "Amel Ajdinovic (@aajdinov)"
+ - "Ethan Devenport (@edevenport)"
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create three servers and enumerate their names
community.general.oneandone_server:
auth_token: oneandone_private_api_key
@@ -201,16 +189,16 @@ EXAMPLES = '''
auth_token: oneandone_private_api_key
state: stopped
server: 'node01'
-'''
+"""
-RETURN = '''
+RETURN = r"""
servers:
- description: Information about each server that was processed
- type: list
- sample:
- - {"hostname": "my-server", "id": "server-id"}
- returned: always
-'''
+ description: Information about each server that was processed.
+ type: list
+ sample:
+ - {"hostname": "my-server", "id": "server-id"}
+ returned: always
+"""
import os
import time
@@ -530,7 +518,7 @@ def startstop_server(module, oneandone_conn):
# Resolve server
server = get_server(oneandone_conn, server_id, True)
if server:
- # Attempt to change the server state, only if it's not already there
+ # Attempt to change the server state, only if it is not already there
# or on its way.
try:
if state == 'stopped' and server['status']['state'] == 'POWERED_ON':
diff --git a/plugins/modules/onepassword_info.py b/plugins/modules/onepassword_info.py
index b63352790f..00fa847c07 100644
--- a/plugins/modules/onepassword_info.py
+++ b/plugins/modules/onepassword_info.py
@@ -12,108 +12,111 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: onepassword_info
author:
- - Ryan Conway (@Rylon)
+ - Ryan Conway (@Rylon)
requirements:
- - C(op) 1Password command line utility. See U(https://support.1password.com/command-line/)
+ - C(op) 1Password command line utility. See U(https://support.1password.com/command-line/)
notes:
- - Tested with C(op) version 0.5.5
- - "Based on the P(community.general.onepassword#lookup) lookup plugin by Scott Buchanan ."
+ - Tested with C(op) version 0.5.5.
+ - Based on the P(community.general.onepassword#lookup) lookup plugin by Scott Buchanan .
short_description: Gather items from 1Password
description:
- - M(community.general.onepassword_info) wraps the C(op) command line utility to fetch data about one or more 1Password items.
- - A fatal error occurs if any of the items being searched for can not be found.
- - Recommend using with the C(no_log) option to avoid logging the values of the secrets being retrieved.
+ - M(community.general.onepassword_info) wraps the C(op) command line utility to fetch data about one or more 1Password items.
+ - A fatal error occurs if any of the items being searched for can not be found.
+ - Recommend using with the C(no_log) option to avoid logging the values of the secrets being retrieved.
extends_documentation_fragment:
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.attributes
+ - community.general.attributes.info_module
options:
- search_terms:
- type: list
- elements: dict
+ search_terms:
+ type: list
+ elements: dict
+ description:
+ - A list of one or more search terms.
+ - Each search term can either be a simple string or it can be a dictionary for more control.
+ - When passing a simple string, O(search_terms[].field) is assumed to be V(password).
+ - When passing a dictionary, the following fields are available.
+ suboptions:
+ name:
+ type: str
description:
- - A list of one or more search terms.
- - Each search term can either be a simple string or it can be a dictionary for more control.
- - When passing a simple string, O(search_terms[].field) is assumed to be V(password).
- - When passing a dictionary, the following fields are available.
- suboptions:
- name:
- type: str
- description:
- - The name of the 1Password item to search for (required).
- field:
- type: str
- description:
- - The name of the field to search for within this item (optional, defaults to "password" (or "document" if the item has an attachment).
- section:
- type: str
- description:
- - The name of a section within this item containing the specified field (optional, will search all sections if not specified).
- vault:
- type: str
- description:
- - The name of the particular 1Password vault to search, useful if your 1Password user has access to multiple vaults (optional).
+ - The name of the 1Password item to search for (required).
+ field:
+ type: str
+ description:
+ - The name of the field to search for within this item (optional, defaults to V(password), or V(document) if the
+ item has an attachment).
+ section:
+ type: str
+ description:
+ - The name of a section within this item containing the specified field (optional, will search all sections if not
+ specified).
+ vault:
+ type: str
+ description:
+ - The name of the particular 1Password vault to search, useful if your 1Password user has access to multiple vaults
+ (optional).
+ required: true
+ auto_login:
+ type: dict
+ description:
+ - A dictionary containing authentication details. If this is set, M(community.general.onepassword_info) will attempt
+ to sign in to 1Password automatically.
+ - Without this option, you must have already logged in using the 1Password CLI before running Ansible.
+ - It is B(highly) recommended to store 1Password credentials in an Ansible Vault. Ensure that the key used to encrypt
+ the Ansible Vault is equal to or greater in strength than the 1Password master password.
+ suboptions:
+ subdomain:
+ type: str
+ description:
+ - 1Password subdomain name (V(subdomain).1password.com).
+ - If this is not specified, the most recent subdomain will be used.
+ username:
+ type: str
+ description:
+ - 1Password username.
+ - Only required for initial sign in.
+ master_password:
+ type: str
+ description:
+ - The master password for your subdomain.
+ - This is always required when specifying O(auto_login).
required: true
- auto_login:
- type: dict
+ secret_key:
+ type: str
description:
- - A dictionary containing authentication details. If this is set, M(community.general.onepassword_info)
- will attempt to sign in to 1Password automatically.
- - Without this option, you must have already logged in via the 1Password CLI before running Ansible.
- - It is B(highly) recommended to store 1Password credentials in an Ansible Vault. Ensure that the key used to encrypt
- the Ansible Vault is equal to or greater in strength than the 1Password master password.
- suboptions:
- subdomain:
- type: str
- description:
- - 1Password subdomain name (.1password.com).
- - If this is not specified, the most recent subdomain will be used.
- username:
- type: str
- description:
- - 1Password username.
- - Only required for initial sign in.
- master_password:
- type: str
- description:
- - The master password for your subdomain.
- - This is always required when specifying O(auto_login).
- required: true
- secret_key:
- type: str
- description:
- - The secret key for your subdomain.
- - Only required for initial sign in.
- required: false
- cli_path:
- type: path
- description: Used to specify the exact path to the C(op) command line interface
- required: false
- default: 'op'
-'''
+ - The secret key for your subdomain.
+ - Only required for initial sign in.
+ required: false
+ cli_path:
+ type: path
+ description: Used to specify the exact path to the C(op) command line interface.
+ required: false
+ default: 'op'
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Gather secrets from 1Password, assuming there is a 'password' field:
- name: Get a password
community.general.onepassword_info:
search_terms: My 1Password item
delegate_to: localhost
register: my_1password_item
- no_log: true # Don't want to log the secrets to the console!
+ no_log: true # Don't want to log the secrets to the console!
# Gather secrets from 1Password, with more advanced search terms:
- name: Get a password
community.general.onepassword_info:
search_terms:
- - name: My 1Password item
- field: Custom field name # optional, defaults to 'password'
- section: Custom section name # optional, defaults to 'None'
- vault: Name of the vault # optional, only necessary if there is more than 1 Vault available
+ - name: My 1Password item
+ field: Custom field name # optional, defaults to 'password'
+ section: Custom section name # optional, defaults to 'None'
+ vault: Name of the vault # optional, only necessary if there is more than 1 Vault available
delegate_to: localhost
register: my_1password_item
- no_log: true # Don't want to log the secrets to the console!
+ no_log: true # Don't want to log the secrets to the console!
# Gather secrets combining simple and advanced search terms to retrieve two items, one of which we fetch two
# fields. In the first 'password' is fetched, as a field name is not specified (default behaviour) and in the
@@ -121,39 +124,39 @@ EXAMPLES = '''
- name: Get a password
community.general.onepassword_info:
search_terms:
- - My 1Password item # 'name' is optional when passing a simple string...
- - name: My Other 1Password item # ...but it can also be set for consistency
- - name: My 1Password item
- field: Custom field name # optional, defaults to 'password'
- section: Custom section name # optional, defaults to 'None'
- vault: Name of the vault # optional, only necessary if there is more than 1 Vault available
+ - My 1Password item # 'name' is optional when passing a simple string...
+ - name: My Other 1Password item # ...but it can also be set for consistency
+ - name: My 1Password item
+ field: Custom field name # optional, defaults to 'password'
+ section: Custom section name # optional, defaults to 'None'
+ vault: Name of the vault # optional, only necessary if there is more than 1 Vault available
- name: A 1Password item with document attachment
delegate_to: localhost
register: my_1password_item
- no_log: true # Don't want to log the secrets to the console!
+ no_log: true # Don't want to log the secrets to the console!
- name: Debug a password (for example)
ansible.builtin.debug:
msg: "{{ my_1password_item['onepassword']['My 1Password item'] }}"
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
# One or more dictionaries for each matching item from 1Password, along with the appropriate fields.
# This shows the response you would expect to receive from the third example documented above.
onepassword:
- description: Dictionary of each 1password item matching the given search terms, shows what would be returned from the third example above.
- returned: success
- type: dict
- sample:
- "My 1Password item":
- password: the value of this field
- Custom field name: the value of this field
- "My Other 1Password item":
- password: the value of this field
- "A 1Password item with document attachment":
- document: the contents of the document attached to this item
-'''
+ description: Dictionary of each 1password item matching the given search terms, shows what would be returned from the third
+ example above.
+ returned: success
+ type: dict
+ sample:
+ "My 1Password item":
+ password: the value of this field
+ Custom field name: the value of this field
+ "My Other 1Password item":
+ password: the value of this field
+ "A 1Password item with document attachment":
+ document: the contents of the document attached to this item
+"""
import errno
diff --git a/plugins/modules/oneview_datacenter_info.py b/plugins/modules/oneview_datacenter_info.py
index ed04e2279f..1ca33023db 100644
--- a/plugins/modules/oneview_datacenter_info.py
+++ b/plugins/modules/oneview_datacenter_info.py
@@ -7,43 +7,41 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_datacenter_info
short_description: Retrieve information about the OneView Data Centers
description:
- - Retrieve information about the OneView Data Centers.
+ - Retrieve information about the OneView Data Centers.
requirements:
- - "hpOneView >= 2.0.1"
+ - "hpOneView >= 2.0.1"
author:
- - Alex Monteiro (@aalexmonteiro)
- - Madhav Bharadwaj (@madhav-bharadwaj)
- - Priyanka Sood (@soodpr)
- - Ricardo Galeno (@ricardogpsf)
+ - Alex Monteiro (@aalexmonteiro)
+ - Madhav Bharadwaj (@madhav-bharadwaj)
+ - Priyanka Sood (@soodpr)
+ - Ricardo Galeno (@ricardogpsf)
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- name:
- description:
- - Data Center name.
- type: str
- options:
- description:
- - "Retrieve additional information. Options available: 'visualContent'."
- type: list
- elements: str
+ name:
+ description:
+ - Data Center name.
+ type: str
+ options:
+ description:
+ - 'Retrieve additional information. Options available: V(visualContent).'
+ type: list
+ elements: str
extends_documentation_fragment:
- community.general.oneview
- community.general.oneview.factsparams
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather information about all Data Centers
community.general.oneview_datacenter_info:
hostname: 172.16.101.48
@@ -107,19 +105,19 @@ EXAMPLES = '''
- name: Print fetched information about Data Center Visual Content
ansible.builtin.debug:
msg: "{{ result.datacenter_visual_content }}"
-'''
+"""
-RETURN = '''
+RETURN = r"""
datacenters:
- description: Has all the OneView information about the Data Centers.
- returned: Always, but can be null.
- type: dict
+ description: Has all the OneView information about the Data Centers.
+ returned: Always, but can be null.
+ type: dict
datacenter_visual_content:
- description: Has information about the Data Center Visual Content.
- returned: When requested, but can be null.
- type: dict
-'''
+ description: Has information about the Data Center Visual Content.
+ returned: When requested, but can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/oneview_enclosure_info.py b/plugins/modules/oneview_enclosure_info.py
index 4e203a50ac..05992ee501 100644
--- a/plugins/modules/oneview_enclosure_info.py
+++ b/plugins/modules/oneview_enclosure_info.py
@@ -8,44 +8,41 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_enclosure_info
short_description: Retrieve information about one or more Enclosures
description:
- - Retrieve information about one or more of the Enclosures from OneView.
+ - Retrieve information about one or more of the Enclosures from OneView.
requirements:
- - hpOneView >= 2.0.1
+ - hpOneView >= 2.0.1
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- name:
- description:
- - Enclosure name.
- type: str
- options:
- description:
- - "List with options to gather additional information about an Enclosure and related resources.
- Options allowed: V(script), V(environmentalConfiguration), and V(utilization). For the option V(utilization),
- you can provide specific parameters."
- type: list
- elements: raw
+ name:
+ description:
+ - Enclosure name.
+ type: str
+ options:
+ description:
+ - 'List with options to gather additional information about an Enclosure and related resources. Options allowed: V(script),
+ V(environmentalConfiguration), and V(utilization). For the option V(utilization), you can provide specific parameters.'
+ type: list
+ elements: raw
extends_documentation_fragment:
- community.general.oneview
- community.general.oneview.factsparams
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather information about all Enclosures
community.general.oneview_enclosure_info:
hostname: 172.16.101.48
@@ -98,9 +95,9 @@ EXAMPLES = '''
community.general.oneview_enclosure_info:
name: Test-Enclosure
options:
- - script # optional
- - environmentalConfiguration # optional
- - utilization # optional
+ - script # optional
+ - environmentalConfiguration # optional
+ - utilization # optional
hostname: 172.16.101.48
username: administrator
password: my_password
@@ -126,11 +123,11 @@ EXAMPLES = '''
msg: "{{ result.enclosure_utilization }}"
- name: "Gather information about an Enclosure with temperature data at a resolution of one sample per day, between two
- specified dates"
+ specified dates"
community.general.oneview_enclosure_info:
name: Test-Enclosure
options:
- - utilization: # optional
+ - utilization: # optional
fields: AmbientTemperature
filter:
- startDate=2016-07-01T14:29:42.000Z
@@ -152,29 +149,29 @@ EXAMPLES = '''
- name: Print fetched information about Enclosure Utilization
ansible.builtin.debug:
msg: "{{ result.enclosure_utilization }}"
-'''
+"""
-RETURN = '''
+RETURN = r"""
enclosures:
- description: Has all the OneView information about the Enclosures.
- returned: Always, but can be null.
- type: dict
+ description: Has all the OneView information about the Enclosures.
+ returned: Always, but can be null.
+ type: dict
enclosure_script:
- description: Has all the OneView information about the script of an Enclosure.
- returned: When requested, but can be null.
- type: str
+ description: Has all the OneView information about the script of an Enclosure.
+ returned: When requested, but can be null.
+ type: str
enclosure_environmental_configuration:
- description: Has all the OneView information about the environmental configuration of an Enclosure.
- returned: When requested, but can be null.
- type: dict
+ description: Has all the OneView information about the environmental configuration of an Enclosure.
+ returned: When requested, but can be null.
+ type: dict
enclosure_utilization:
- description: Has all the OneView information about the utilization of an Enclosure.
- returned: When requested, but can be null.
- type: dict
-'''
+ description: Has all the OneView information about the utilization of an Enclosure.
+ returned: When requested, but can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/oneview_ethernet_network.py b/plugins/modules/oneview_ethernet_network.py
index 981d949cdc..823fea3b2c 100644
--- a/plugins/modules/oneview_ethernet_network.py
+++ b/plugins/modules/oneview_ethernet_network.py
@@ -7,46 +7,44 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_ethernet_network
short_description: Manage OneView Ethernet Network resources
description:
- - Provides an interface to manage Ethernet Network resources. Can create, update, or delete.
+ - Provides an interface to manage Ethernet Network resources. Can create, update, or delete.
requirements:
- - hpOneView >= 3.1.0
+ - hpOneView >= 3.1.0
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Indicates the desired state for the Ethernet Network resource.
- - V(present) will ensure data properties are compliant with OneView.
- - V(absent) will remove the resource from OneView, if it exists.
- - V(default_bandwidth_reset) will reset the network connection template to the default.
- type: str
- default: present
- choices: [present, absent, default_bandwidth_reset]
- data:
- description:
- - List with Ethernet Network properties.
- type: dict
- required: true
+ state:
+ description:
+ - Indicates the desired state for the Ethernet Network resource.
+ - V(present) will ensure data properties are compliant with OneView.
+ - V(absent) will remove the resource from OneView, if it exists.
+ - V(default_bandwidth_reset) will reset the network connection template to the default.
+ type: str
+ default: present
+ choices: [present, absent, default_bandwidth_reset]
+ data:
+ description:
+ - List with Ethernet Network properties.
+ type: dict
+ required: true
extends_documentation_fragment:
- - community.general.oneview
- - community.general.oneview.validateetag
- - community.general.attributes
+ - community.general.oneview
+ - community.general.oneview.validateetag
+ - community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Ensure that the Ethernet Network is present using the default configuration
community.general.oneview_ethernet_network:
config: '/etc/oneview/oneview_config.json'
@@ -64,8 +62,8 @@ EXAMPLES = '''
name: 'Test Ethernet Network'
purpose: Management
bandwidth:
- maximumBandwidth: 3000
- typicalBandwidth: 2000
+ maximumBandwidth: 3000
+ typicalBandwidth: 2000
delegate_to: localhost
- name: Ensure that the Ethernet Network is present with name 'Renamed Ethernet Network'
@@ -107,24 +105,24 @@ EXAMPLES = '''
data:
name: 'Test Ethernet Network'
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
ethernet_network:
- description: Has the facts about the Ethernet Networks.
- returned: On state 'present'. Can be null.
- type: dict
+ description: Has the facts about the Ethernet Networks.
+ returned: On O(state=present). Can be null.
+ type: dict
ethernet_network_bulk:
- description: Has the facts about the Ethernet Networks affected by the bulk insert.
- returned: When 'vlanIdRange' attribute is in data argument. Can be null.
- type: dict
+ description: Has the facts about the Ethernet Networks affected by the bulk insert.
+ returned: When V(vlanIdRange) attribute is in O(data) argument. Can be null.
+ type: dict
ethernet_network_connection_template:
- description: Has the facts about the Ethernet Network Connection Template.
- returned: On state 'default_bandwidth_reset'. Can be null.
- type: dict
-'''
+ description: Has the facts about the Ethernet Network Connection Template.
+ returned: On O(state=default_bandwidth_reset). Can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase, OneViewModuleResourceNotFound
diff --git a/plugins/modules/oneview_ethernet_network_info.py b/plugins/modules/oneview_ethernet_network_info.py
index 7da008b04e..c1c0a327fe 100644
--- a/plugins/modules/oneview_ethernet_network_info.py
+++ b/plugins/modules/oneview_ethernet_network_info.py
@@ -7,42 +7,40 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_ethernet_network_info
short_description: Retrieve the information about one or more of the OneView Ethernet Networks
description:
- - Retrieve the information about one or more of the Ethernet Networks from OneView.
+ - Retrieve the information about one or more of the Ethernet Networks from OneView.
requirements:
- - hpOneView >= 2.0.1
+ - hpOneView >= 2.0.1
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- name:
- description:
- - Ethernet Network name.
- type: str
- options:
- description:
- - "List with options to gather additional information about an Ethernet Network and related resources.
- Options allowed: V(associatedProfiles) and V(associatedUplinkGroups)."
- type: list
- elements: str
+ name:
+ description:
+ - Ethernet Network name.
+ type: str
+ options:
+ description:
+ - 'List with options to gather additional information about an Ethernet Network and related resources. Options allowed:
+ V(associatedProfiles) and V(associatedUplinkGroups).'
+ type: list
+ elements: str
extends_documentation_fragment:
- community.general.oneview
- community.general.oneview.factsparams
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather information about all Ethernet Networks
community.general.oneview_ethernet_network_info:
config: /etc/oneview/oneview_config.json
@@ -96,24 +94,24 @@ EXAMPLES = '''
- name: Print fetched information about Ethernet Network Associated Uplink Groups
ansible.builtin.debug:
msg: "{{ result.enet_associated_uplink_groups }}"
-'''
+"""
-RETURN = '''
+RETURN = r"""
ethernet_networks:
- description: Has all the OneView information about the Ethernet Networks.
- returned: Always, but can be null.
- type: dict
+ description: Has all the OneView information about the Ethernet Networks.
+ returned: Always, but can be null.
+ type: dict
enet_associated_profiles:
- description: Has all the OneView information about the profiles which are using the Ethernet network.
- returned: When requested, but can be null.
- type: dict
+ description: Has all the OneView information about the profiles which are using the Ethernet network.
+ returned: When requested, but can be null.
+ type: dict
enet_associated_uplink_groups:
- description: Has all the OneView information about the uplink sets which are using the Ethernet network.
- returned: When requested, but can be null.
- type: dict
-'''
+ description: Has all the OneView information about the uplink sets which are using the Ethernet network.
+ returned: When requested, but can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/oneview_fc_network.py b/plugins/modules/oneview_fc_network.py
index 9f0c4358b7..312a5dc893 100644
--- a/plugins/modules/oneview_fc_network.py
+++ b/plugins/modules/oneview_fc_network.py
@@ -7,43 +7,41 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_fc_network
short_description: Manage OneView Fibre Channel Network resources
description:
- - Provides an interface to manage Fibre Channel Network resources. Can create, update, and delete.
+ - Provides an interface to manage Fibre Channel Network resources. Can create, update, and delete.
requirements:
- - "hpOneView >= 4.0.0"
+ - "hpOneView >= 4.0.0"
author: "Felipe Bulsoni (@fgbulsoni)"
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Indicates the desired state for the Fibre Channel Network resource.
- V(present) will ensure data properties are compliant with OneView.
- V(absent) will remove the resource from OneView, if it exists.
- type: str
- choices: ['present', 'absent']
- required: true
- data:
- description:
- - List with the Fibre Channel Network properties.
- type: dict
- required: true
+ state:
+ description:
+ - Indicates the desired state for the Fibre Channel Network resource.
+ - V(present) will ensure data properties are compliant with OneView.
+ - V(absent) will remove the resource from OneView, if it exists.
+ type: str
+ choices: ['present', 'absent']
+ required: true
+ data:
+ description:
+ - List with the Fibre Channel Network properties.
+ type: dict
+ required: true
extends_documentation_fragment:
- - community.general.oneview
- - community.general.oneview.validateetag
- - community.general.attributes
+ - community.general.oneview
+ - community.general.oneview.validateetag
+ - community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Ensure that the Fibre Channel Network is present using the default configuration
community.general.oneview_fc_network:
config: "{{ config_file_path }}"
@@ -75,14 +73,14 @@ EXAMPLES = '''
state: absent
data:
name: 'New FC Network'
-'''
+"""
-RETURN = '''
+RETURN = r"""
fc_network:
- description: Has the facts about the managed OneView FC Network.
- returned: On state 'present'. Can be null.
- type: dict
-'''
+ description: Has the facts about the managed OneView FC Network.
+ returned: On O(state=present). Can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/oneview_fc_network_info.py b/plugins/modules/oneview_fc_network_info.py
index 096af48308..af20869dc3 100644
--- a/plugins/modules/oneview_fc_network_info.py
+++ b/plugins/modules/oneview_fc_network_info.py
@@ -7,37 +7,35 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_fc_network_info
short_description: Retrieve the information about one or more of the OneView Fibre Channel Networks
description:
- - Retrieve the information about one or more of the Fibre Channel Networks from OneView.
+ - Retrieve the information about one or more of the Fibre Channel Networks from OneView.
requirements:
- - hpOneView >= 2.0.1
+ - hpOneView >= 2.0.1
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- name:
- description:
- - Fibre Channel Network name.
- type: str
+ name:
+ description:
+ - Fibre Channel Network name.
+ type: str
extends_documentation_fragment:
- community.general.oneview
- community.general.oneview.factsparams
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather information about all Fibre Channel Networks
community.general.oneview_fc_network_info:
config: /etc/oneview/oneview_config.json
@@ -73,14 +71,14 @@ EXAMPLES = '''
- name: Print fetched information about Fibre Channel Network found by name
ansible.builtin.debug:
msg: "{{ result.fc_networks }}"
-'''
+"""
-RETURN = '''
+RETURN = r"""
fc_networks:
- description: Has all the OneView information about the Fibre Channel Networks.
- returned: Always, but can be null.
- type: dict
-'''
+ description: Has all the OneView information about the Fibre Channel Networks.
+ returned: Always, but can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/oneview_fcoe_network.py b/plugins/modules/oneview_fcoe_network.py
index e1216b1d95..15128bd372 100644
--- a/plugins/modules/oneview_fcoe_network.py
+++ b/plugins/modules/oneview_fcoe_network.py
@@ -7,44 +7,42 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_fcoe_network
short_description: Manage OneView FCoE Network resources
description:
- - Provides an interface to manage FCoE Network resources. Can create, update, or delete.
+ - Provides an interface to manage FCoE Network resources. Can create, update, or delete.
requirements:
- - "Python >= 2.7.9"
- - "hpOneView >= 4.0.0"
+ - "Python >= 2.7.9"
+ - "hpOneView >= 4.0.0"
author: "Felipe Bulsoni (@fgbulsoni)"
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Indicates the desired state for the FCoE Network resource.
- V(present) will ensure data properties are compliant with OneView.
- V(absent) will remove the resource from OneView, if it exists.
- type: str
- default: present
- choices: ['present', 'absent']
- data:
- description:
- - List with FCoE Network properties.
- type: dict
- required: true
+ state:
+ description:
+ - Indicates the desired state for the FCoE Network resource.
+ - V(present) will ensure data properties are compliant with OneView.
+ - V(absent) will remove the resource from OneView, if it exists.
+ type: str
+ default: present
+ choices: ['present', 'absent']
+ data:
+ description:
+ - List with FCoE Network properties.
+ type: dict
+ required: true
extends_documentation_fragment:
- - community.general.oneview
- - community.general.oneview.validateetag
- - community.general.attributes
+ - community.general.oneview
+ - community.general.oneview.validateetag
+ - community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Ensure that FCoE Network is present using the default configuration
community.general.oneview_fcoe_network:
config: '/etc/oneview/oneview_config.json'
@@ -72,14 +70,14 @@ EXAMPLES = '''
data:
name: New FCoE Network
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
fcoe_network:
- description: Has the facts about the OneView FCoE Networks.
- returned: On state 'present'. Can be null.
- type: dict
-'''
+ description: Has the facts about the OneView FCoE Networks.
+ returned: On O(state=present). Can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/oneview_fcoe_network_info.py b/plugins/modules/oneview_fcoe_network_info.py
index b3460d59aa..6d5074be4a 100644
--- a/plugins/modules/oneview_fcoe_network_info.py
+++ b/plugins/modules/oneview_fcoe_network_info.py
@@ -7,36 +7,34 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_fcoe_network_info
short_description: Retrieve the information about one or more of the OneView FCoE Networks
description:
- - Retrieve the information about one or more of the FCoE Networks from OneView.
+ - Retrieve the information about one or more of the FCoE Networks from OneView.
requirements:
- - hpOneView >= 2.0.1
+ - hpOneView >= 2.0.1
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- name:
- description:
- - FCoE Network name.
- type: str
+ name:
+ description:
+ - FCoE Network name.
+ type: str
extends_documentation_fragment:
- community.general.oneview
- community.general.oneview.factsparams
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather information about all FCoE Networks
community.general.oneview_fcoe_network_info:
config: /etc/oneview/oneview_config.json
@@ -72,14 +70,14 @@ EXAMPLES = '''
- name: Print fetched information about FCoE Network found by name
ansible.builtin.debug:
msg: "{{ result.fcoe_networks }}"
-'''
+"""
-RETURN = '''
+RETURN = r"""
fcoe_networks:
- description: Has all the OneView information about the FCoE Networks.
- returned: Always, but can be null.
- type: dict
-'''
+ description: Has all the OneView information about the FCoE Networks.
+ returned: Always, but can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/oneview_logical_interconnect_group.py b/plugins/modules/oneview_logical_interconnect_group.py
index d1303f011a..a45224cb31 100644
--- a/plugins/modules/oneview_logical_interconnect_group.py
+++ b/plugins/modules/oneview_logical_interconnect_group.py
@@ -8,45 +8,43 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_logical_interconnect_group
short_description: Manage OneView Logical Interconnect Group resources
description:
- - Provides an interface to manage Logical Interconnect Group resources. Can create, update, or delete.
+ - Provides an interface to manage Logical Interconnect Group resources. Can create, update, or delete.
requirements:
- - hpOneView >= 4.0.0
+ - hpOneView >= 4.0.0
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Indicates the desired state for the Logical Interconnect Group resource.
- V(absent) will remove the resource from OneView, if it exists.
- V(present) will ensure data properties are compliant with OneView.
- type: str
- choices: [absent, present]
- default: present
- data:
- description:
- - List with the Logical Interconnect Group properties.
- type: dict
- required: true
+ state:
+ description:
+ - Indicates the desired state for the Logical Interconnect Group resource.
+ - V(absent) will remove the resource from OneView, if it exists.
+ - V(present) will ensure data properties are compliant with OneView.
+ type: str
+ choices: [absent, present]
+ default: present
+ data:
+ description:
+ - List with the Logical Interconnect Group properties.
+ type: dict
+ required: true
extends_documentation_fragment:
- - community.general.oneview
- - community.general.oneview.validateetag
- - community.general.attributes
+ - community.general.oneview
+ - community.general.oneview.validateetag
+ - community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Ensure that the Logical Interconnect Group is present
community.general.oneview_logical_interconnect_group:
config: /etc/oneview/oneview_config.json
@@ -57,13 +55,13 @@ EXAMPLES = '''
enclosureType: C7000
interconnectMapTemplate:
interconnectMapEntryTemplates:
- - logicalDownlinkUri: ~
+ - logicalDownlinkUri:
logicalLocation:
- locationEntries:
- - relativeValue: 1
- type: Bay
- - relativeValue: 1
- type: Enclosure
+ locationEntries:
+ - relativeValue: 1
+ type: Bay
+ - relativeValue: 1
+ type: Enclosure
permittedInterconnectTypeName: HP VC Flex-10/10D Module
# Alternatively you can inform permittedInterconnectTypeUri
delegate_to: localhost
@@ -95,14 +93,14 @@ EXAMPLES = '''
data:
name: New Logical Interconnect Group
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
logical_interconnect_group:
- description: Has the facts about the OneView Logical Interconnect Group.
- returned: On state 'present'. Can be null.
- type: dict
-'''
+ description: Has the facts about the OneView Logical Interconnect Group.
+ returned: On O(state=present). Can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase, OneViewModuleResourceNotFound
diff --git a/plugins/modules/oneview_logical_interconnect_group_info.py b/plugins/modules/oneview_logical_interconnect_group_info.py
index 6f6a908f29..1c9e415d0e 100644
--- a/plugins/modules/oneview_logical_interconnect_group_info.py
+++ b/plugins/modules/oneview_logical_interconnect_group_info.py
@@ -8,36 +8,34 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_logical_interconnect_group_info
short_description: Retrieve information about one or more of the OneView Logical Interconnect Groups
description:
- - Retrieve information about one or more of the Logical Interconnect Groups from OneView
+ - Retrieve information about one or more of the Logical Interconnect Groups from OneView.
requirements:
- - hpOneView >= 2.0.1
+ - hpOneView >= 2.0.1
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- name:
- description:
- - Logical Interconnect Group name.
- type: str
+ name:
+ description:
+ - Logical Interconnect Group name.
+ type: str
extends_documentation_fragment:
- community.general.oneview
- community.general.oneview.factsparams
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather information about all Logical Interconnect Groups
community.general.oneview_logical_interconnect_group_info:
hostname: 172.16.101.48
@@ -85,14 +83,14 @@ EXAMPLES = '''
- name: Print fetched information about Logical Interconnect Group found by name
ansible.builtin.debug:
msg: "{{ result.logical_interconnect_groups }}"
-'''
+"""
-RETURN = '''
+RETURN = r"""
logical_interconnect_groups:
- description: Has all the OneView information about the Logical Interconnect Groups.
- returned: Always, but can be null.
- type: dict
-'''
+ description: Has all the OneView information about the Logical Interconnect Groups.
+ returned: Always, but can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/oneview_network_set.py b/plugins/modules/oneview_network_set.py
index 0efd417d63..a7fae51f21 100644
--- a/plugins/modules/oneview_network_set.py
+++ b/plugins/modules/oneview_network_set.py
@@ -7,46 +7,44 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_network_set
short_description: Manage HPE OneView Network Set resources
description:
- - Provides an interface to manage Network Set resources. Can create, update, or delete.
+ - Provides an interface to manage Network Set resources. Can create, update, or delete.
requirements:
- - hpOneView >= 4.0.0
+ - hpOneView >= 4.0.0
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Indicates the desired state for the Network Set resource.
- - V(present) will ensure data properties are compliant with OneView.
- - V(absent) will remove the resource from OneView, if it exists.
- type: str
- default: present
- choices: ['present', 'absent']
- data:
- description:
- - List with the Network Set properties.
- type: dict
- required: true
+ state:
+ description:
+ - Indicates the desired state for the Network Set resource.
+ - V(present) will ensure data properties are compliant with OneView.
+ - V(absent) will remove the resource from OneView, if it exists.
+ type: str
+ default: present
+ choices: ['present', 'absent']
+ data:
+ description:
+ - List with the Network Set properties.
+ type: dict
+ required: true
extends_documentation_fragment:
- - community.general.oneview
- - community.general.oneview.validateetag
- - community.general.attributes
+ - community.general.oneview
+ - community.general.oneview.validateetag
+ - community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a Network Set
community.general.oneview_network_set:
config: /etc/oneview/oneview_config.json
@@ -54,8 +52,8 @@ EXAMPLES = '''
data:
name: OneViewSDK Test Network Set
networkUris:
- - Test Ethernet Network_1 # can be a name
- - /rest/ethernet-networks/e4360c9d-051d-4931-b2aa-7de846450dd8 # or a URI
+ - Test Ethernet Network_1 # can be a name
+ - /rest/ethernet-networks/e4360c9d-051d-4931-b2aa-7de846450dd8 # or a URI
delegate_to: localhost
- name: Update the Network Set name to 'OneViewSDK Test Network Set - Renamed' and change the associated networks
@@ -74,7 +72,7 @@ EXAMPLES = '''
config: /etc/oneview/oneview_config.json
state: absent
data:
- name: OneViewSDK Test Network Set - Renamed
+ name: OneViewSDK Test Network Set - Renamed
delegate_to: localhost
- name: Update the Network set with two scopes
@@ -87,14 +85,14 @@ EXAMPLES = '''
- /rest/scopes/01SC123456
- /rest/scopes/02SC123456
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
network_set:
- description: Has the facts about the Network Set.
- returned: On state 'present', but can be null.
- type: dict
-'''
+ description: Has the facts about the Network Set.
+ returned: On O(state=present), but can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase, OneViewModuleResourceNotFound
diff --git a/plugins/modules/oneview_network_set_info.py b/plugins/modules/oneview_network_set_info.py
index cef53d8fcd..51e7d0b510 100644
--- a/plugins/modules/oneview_network_set_info.py
+++ b/plugins/modules/oneview_network_set_info.py
@@ -7,45 +7,42 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_network_set_info
short_description: Retrieve information about the OneView Network Sets
description:
- - Retrieve information about the Network Sets from OneView.
+ - Retrieve information about the Network Sets from OneView.
requirements:
- - hpOneView >= 2.0.1
+ - hpOneView >= 2.0.1
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- name:
- description:
- - Network Set name.
- type: str
+ name:
+ description:
+ - Network Set name.
+ type: str
- options:
- description:
- - "List with options to gather information about Network Set.
- Option allowed: V(withoutEthernet).
- The option V(withoutEthernet) retrieves the list of network_sets excluding Ethernet networks."
- type: list
- elements: str
+ options:
+ description:
+ - 'List with options to gather information about Network Set. Option allowed: V(withoutEthernet). The option V(withoutEthernet)
+ retrieves the list of network_sets excluding Ethernet networks.'
+ type: list
+ elements: str
extends_documentation_fragment:
- community.general.oneview
- community.general.oneview.factsparams
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather information about all Network Sets
community.general.oneview_network_set_info:
hostname: 172.16.101.48
@@ -86,7 +83,7 @@ EXAMPLES = '''
password: my_password
api_version: 500
options:
- - withoutEthernet
+ - withoutEthernet
no_log: true
delegate_to: localhost
register: result
@@ -118,7 +115,7 @@ EXAMPLES = '''
api_version: 500
name: Name of the Network Set
options:
- - withoutEthernet
+ - withoutEthernet
no_log: true
delegate_to: localhost
register: result
@@ -126,14 +123,14 @@ EXAMPLES = '''
- name: Print fetched information about Network Set found by name, excluding Ethernet networks
ansible.builtin.debug:
msg: "{{ result.network_sets }}"
-'''
+"""
-RETURN = '''
+RETURN = r"""
network_sets:
- description: Has all the OneView information about the Network Sets.
- returned: Always, but can be empty.
- type: dict
-'''
+ description: Has all the OneView information about the Network Sets.
+ returned: Always, but can be empty.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/oneview_san_manager.py b/plugins/modules/oneview_san_manager.py
index 15282aec21..23732cdaaf 100644
--- a/plugins/modules/oneview_san_manager.py
+++ b/plugins/modules/oneview_san_manager.py
@@ -7,47 +7,45 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_san_manager
short_description: Manage OneView SAN Manager resources
description:
- - Provides an interface to manage SAN Manager resources. Can create, update, or delete.
+ - Provides an interface to manage SAN Manager resources. Can create, update, or delete.
requirements:
- - hpOneView >= 3.1.1
+ - hpOneView >= 3.1.1
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Indicates the desired state for the Uplink Set resource.
- - V(present) ensures data properties are compliant with OneView.
- - V(absent) removes the resource from OneView, if it exists.
- - V(connection_information_set) updates the connection information for the SAN Manager. This operation is non-idempotent.
- type: str
- default: present
- choices: [present, absent, connection_information_set]
- data:
- description:
- - List with SAN Manager properties.
- type: dict
- required: true
+ state:
+ description:
+ - Indicates the desired state for the Uplink Set resource.
+ - V(present) ensures data properties are compliant with OneView.
+ - V(absent) removes the resource from OneView, if it exists.
+ - V(connection_information_set) updates the connection information for the SAN Manager. This operation is non-idempotent.
+ type: str
+ default: present
+ choices: [present, absent, connection_information_set]
+ data:
+ description:
+ - List with SAN Manager properties.
+ type: dict
+ required: true
extends_documentation_fragment:
- - community.general.oneview
- - community.general.oneview.validateetag
- - community.general.attributes
+ - community.general.oneview
+ - community.general.oneview.validateetag
+ - community.general.attributes
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Creates a Device Manager for the Brocade SAN provider with the given hostname and credentials
community.general.oneview_san_manager:
config: /etc/oneview/oneview_config.json
@@ -123,14 +121,14 @@ EXAMPLES = '''
data:
name: '172.18.15.1'
delegate_to: localhost
-'''
+"""
-RETURN = '''
+RETURN = r"""
san_manager:
- description: Has the OneView facts about the SAN Manager.
- returned: On state 'present'. Can be null.
- type: dict
-'''
+ description: Has the OneView facts about the SAN Manager.
+ returned: On O(state=present). Can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase, OneViewModuleValueError
diff --git a/plugins/modules/oneview_san_manager_info.py b/plugins/modules/oneview_san_manager_info.py
index f994280ca8..63797e298e 100644
--- a/plugins/modules/oneview_san_manager_info.py
+++ b/plugins/modules/oneview_san_manager_info.py
@@ -7,44 +7,42 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: oneview_san_manager_info
short_description: Retrieve information about one or more of the OneView SAN Managers
description:
- - Retrieve information about one or more of the SAN Managers from OneView
+ - Retrieve information about one or more of the SAN Managers from OneView.
requirements:
- - hpOneView >= 2.0.1
+ - hpOneView >= 2.0.1
author:
- - Felipe Bulsoni (@fgbulsoni)
- - Thiago Miotto (@tmiotto)
- - Adriane Cardozo (@adriane-cardozo)
+ - Felipe Bulsoni (@fgbulsoni)
+ - Thiago Miotto (@tmiotto)
+ - Adriane Cardozo (@adriane-cardozo)
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- provider_display_name:
- description:
- - Provider Display Name.
- type: str
- params:
- description:
- - List of params to delimit, filter and sort the list of resources.
- - "params allowed:
- - V(start): The first item to return, using 0-based indexing.
- - V(count): The number of resources to return.
- - V(query): A general query string to narrow the list of resources returned.
- - V(sort): The sort order of the returned data set."
- type: dict
+ provider_display_name:
+ description:
+ - Provider Display Name.
+ type: str
+ params:
+ description:
+ - List of params to delimit, filter and sort the list of resources.
+ - 'Params allowed:'
+ - 'V(start): The first item to return, using 0-based indexing.'
+ - 'V(count): The number of resources to return.'
+ - 'V(query): A general query string to narrow the list of resources returned.'
+ - 'V(sort): The sort order of the returned data set.'
+ type: dict
extends_documentation_fragment:
- community.general.oneview
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Gather information about all SAN Managers
community.general.oneview_san_manager_info:
config: /etc/oneview/oneview_config.json
@@ -80,14 +78,14 @@ EXAMPLES = '''
- name: Print fetched information about SAN Manager found by provider display name
ansible.builtin.debug:
msg: "{{ result.san_managers }}"
-'''
+"""
-RETURN = '''
+RETURN = r"""
san_managers:
- description: Has all the OneView information about the SAN Managers.
- returned: Always, but can be null.
- type: dict
-'''
+ description: Has all the OneView information about the SAN Managers.
+ returned: Always, but can be null.
+ type: dict
+"""
from ansible_collections.community.general.plugins.module_utils.oneview import OneViewModuleBase
diff --git a/plugins/modules/online_server_info.py b/plugins/modules/online_server_info.py
index f6d03cb275..e36c78ef0e 100644
--- a/plugins/modules/online_server_info.py
+++ b/plugins/modules/online_server_info.py
@@ -8,23 +8,21 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: online_server_info
short_description: Gather information about Online servers
description:
- Gather information about the servers.
- - U(https://www.online.net/en/dedicated-server)
+ - U(https://www.online.net/en/dedicated-server).
author:
- "Remy Leone (@remyleone)"
extends_documentation_fragment:
- community.general.online
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather Online server information
community.general.online_server_info:
api_token: '0d1627e8-bbf0-44c5-a46f-5c4d3aef033f'
@@ -32,13 +30,13 @@ EXAMPLES = r'''
- ansible.builtin.debug:
msg: "{{ result.online_server_info }}"
-'''
+"""
-RETURN = r'''
+RETURN = r"""
online_server_info:
description:
- Response from Online API.
- - "For more details please refer to: U(https://console.online.net/en/api/)."
+ - 'For more details please refer to: U(https://console.online.net/en/api/).'
returned: success
type: list
elements: dict
@@ -130,7 +128,7 @@ online_server_info:
"support": "Basic service level"
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.online import (
diff --git a/plugins/modules/online_user_info.py b/plugins/modules/online_user_info.py
index 1d91418caf..60e0763267 100644
--- a/plugins/modules/online_user_info.py
+++ b/plugins/modules/online_user_info.py
@@ -7,7 +7,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: online_user_info
short_description: Gather information about Online user
description:
@@ -18,22 +18,22 @@ extends_documentation_fragment:
- community.general.online
- community.general.attributes
- community.general.attributes.info_module
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather Online user info
community.general.online_user_info:
register: result
- ansible.builtin.debug:
msg: "{{ result.online_user_info }}"
-'''
+"""
-RETURN = r'''
+RETURN = r"""
online_user_info:
description:
- Response from Online API.
- - "For more details please refer to: U(https://console.online.net/en/api/)."
+ - 'For more details please refer to: U(https://console.online.net/en/api/).'
returned: success
type: dict
sample:
@@ -45,7 +45,7 @@ online_user_info:
"last_name": "bar",
"login": "foobar"
}
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.online import (
diff --git a/plugins/modules/open_iscsi.py b/plugins/modules/open_iscsi.py
index df8a694a7e..defb0a072b 100644
--- a/plugins/modules/open_iscsi.py
+++ b/plugins/modules/open_iscsi.py
@@ -8,103 +8,100 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: open_iscsi
author:
- - Serge van Ginderachter (@srvg)
+ - Serge van Ginderachter (@srvg)
short_description: Manage iSCSI targets with Open-iSCSI
description:
- - Discover targets on given portal, (dis)connect targets, mark targets to
- manually or auto start, return device nodes of connected targets.
+ - Discover targets on given portal, (dis)connect targets, mark targets to manually or auto start, return device nodes of
+ connected targets.
requirements:
- - open_iscsi library and tools (iscsiadm)
+ - open_iscsi library and tools (iscsiadm)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- portal:
- description:
- - The domain name or IP address of the iSCSI target.
- type: str
- aliases: [ ip ]
- port:
- description:
- - The port on which the iSCSI target process listens.
- type: str
- default: '3260'
- target:
- description:
- - The iSCSI target name.
- type: str
- aliases: [ name, targetname ]
- login:
- description:
- - Whether the target node should be connected.
- - When O(target) is omitted, will login to all available.
- type: bool
- aliases: [ state ]
- node_auth:
- description:
- - The value for C(node.session.auth.authmethod).
- type: str
- default: CHAP
- node_user:
- description:
- - The value for C(node.session.auth.username).
- type: str
- node_pass:
- description:
- - The value for C(node.session.auth.password).
- type: str
- node_user_in:
- description:
- - The value for C(node.session.auth.username_in).
- type: str
- version_added: 3.8.0
- node_pass_in:
- description:
- - The value for C(node.session.auth.password_in).
- type: str
- version_added: 3.8.0
- auto_node_startup:
- description:
- - Whether the target node should be automatically connected at startup.
- type: bool
- aliases: [ automatic ]
- auto_portal_startup:
- description:
- - Whether the target node portal should be automatically connected at startup.
- type: bool
- version_added: 3.2.0
- discover:
- description:
- - Whether the list of target nodes on the portal should be
- (re)discovered and added to the persistent iSCSI database.
- - Keep in mind that C(iscsiadm) discovery resets configuration, like C(node.startup)
- to manual, hence combined with O(auto_node_startup=true) will always return
- a changed state.
- type: bool
- default: false
- show_nodes:
- description:
- - Whether the list of nodes in the persistent iSCSI database should be returned by the module.
- type: bool
- default: false
- rescan:
- description:
- - Rescan an established session for discovering new targets.
- - When O(target) is omitted, will rescan all sessions.
- type: bool
- default: false
- version_added: 4.1.0
-'''
+ portal:
+ description:
+ - The domain name or IP address of the iSCSI target.
+ type: str
+ aliases: [ip]
+ port:
+ description:
+ - The port on which the iSCSI target process listens.
+ type: str
+ default: '3260'
+ target:
+ description:
+ - The iSCSI target name.
+ type: str
+ aliases: [name, targetname]
+ login:
+ description:
+ - Whether the target node should be connected.
+ - When O(target) is omitted, will login to all available.
+ type: bool
+ aliases: [state]
+ node_auth:
+ description:
+ - The value for C(node.session.auth.authmethod).
+ type: str
+ default: CHAP
+ node_user:
+ description:
+ - The value for C(node.session.auth.username).
+ type: str
+ node_pass:
+ description:
+ - The value for C(node.session.auth.password).
+ type: str
+ node_user_in:
+ description:
+ - The value for C(node.session.auth.username_in).
+ type: str
+ version_added: 3.8.0
+ node_pass_in:
+ description:
+ - The value for C(node.session.auth.password_in).
+ type: str
+ version_added: 3.8.0
+ auto_node_startup:
+ description:
+ - Whether the target node should be automatically connected at startup.
+ type: bool
+ aliases: [automatic]
+ auto_portal_startup:
+ description:
+ - Whether the target node portal should be automatically connected at startup.
+ type: bool
+ version_added: 3.2.0
+ discover:
+ description:
+ - Whether the list of target nodes on the portal should be (re)discovered and added to the persistent iSCSI database.
+ - Keep in mind that C(iscsiadm) discovery resets configuration, like C(node.startup) to manual, hence combined with
+ O(auto_node_startup=true) will always return a changed state.
+ type: bool
+ default: false
+ show_nodes:
+ description:
+ - Whether the list of nodes in the persistent iSCSI database should be returned by the module.
+ type: bool
+ default: false
+ rescan:
+ description:
+ - Rescan an established session for discovering new targets.
+ - When O(target) is omitted, will rescan all sessions.
+ type: bool
+ default: false
+ version_added: 4.1.0
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Perform a discovery on sun.com and show available target nodes
community.general.open_iscsi:
show_nodes: true
@@ -144,7 +141,7 @@ EXAMPLES = r'''
community.general.open_iscsi:
rescan: true
target: iqn.1986-03.com.sun:02:f8c1f9e0-c3ec-ec84-c9c9-8bfb0cd5de3d
-'''
+"""
import glob
import os
diff --git a/plugins/modules/openbsd_pkg.py b/plugins/modules/openbsd_pkg.py
index 69ac7bff8e..b9a541cc44 100644
--- a/plugins/modules/openbsd_pkg.py
+++ b/plugins/modules/openbsd_pkg.py
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: openbsd_pkg
author:
- Patrik Lundin (@eest)
@@ -21,69 +20,64 @@ description:
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: partial
- version_added: 9.1.0
- details:
- - Only works when check mode is not enabled.
+ check_mode:
+ support: full
+ diff_mode:
+ support: partial
+ version_added: 9.1.0
+ details:
+ - Only works when check mode is not enabled.
options:
- name:
- description:
- - A name or a list of names of the packages.
- required: true
- type: list
- elements: str
- state:
- description:
- - V(present) will make sure the package is installed.
- - V(latest) will make sure the latest version of the package is installed.
- - V(absent) will make sure the specified package is not installed.
- choices: [ absent, latest, present, installed, removed ]
- default: present
- type: str
- build:
- description:
- - Build the package from source instead of downloading and installing
- a binary. Requires that the port source tree is already installed.
- Automatically builds and installs the 'sqlports' package, if it is
- not already installed.
- - Mutually exclusive with O(snapshot).
- type: bool
- default: false
- snapshot:
- description:
- - Force C(%c) and C(%m) to expand to C(snapshots), even on a release kernel.
- - Mutually exclusive with O(build).
- type: bool
- default: false
- version_added: 1.3.0
- ports_dir:
- description:
- - When used in combination with the O(build) option, allows overriding
- the default ports source directory.
- default: /usr/ports
- type: path
- clean:
- description:
- - When updating or removing packages, delete the extra configuration
- file(s) in the old packages which are annotated with @extra in
- the packaging-list.
- type: bool
- default: false
- quick:
- description:
- - Replace or delete packages quickly; do not bother with checksums
- before removing normal files.
- type: bool
- default: false
+ name:
+ description:
+ - A name or a list of names of the packages.
+ required: true
+ type: list
+ elements: str
+ state:
+ description:
+ - V(present) will make sure the package is installed.
+ - V(latest) will make sure the latest version of the package is installed.
+ - V(absent) will make sure the specified package is not installed.
+ choices: [absent, latest, present, installed, removed]
+ default: present
+ type: str
+ build:
+ description:
+ - Build the package from source instead of downloading and installing a binary. Requires that the port source tree is
+ already installed. Automatically builds and installs the C(sqlports) package, if it is not already installed.
+ - Mutually exclusive with O(snapshot).
+ type: bool
+ default: false
+ snapshot:
+ description:
+ - Force C(%c) and C(%m) to expand to C(snapshots), even on a release kernel.
+ - Mutually exclusive with O(build).
+ type: bool
+ default: false
+ version_added: 1.3.0
+ ports_dir:
+ description:
+ - When used in combination with the O(build) option, allows overriding the default ports source directory.
+ default: /usr/ports
+ type: path
+ clean:
+ description:
+ - When updating or removing packages, delete the extra configuration file(s) in the old packages which are annotated
+ with C(@extra) in the packaging-list.
+ type: bool
+ default: false
+ quick:
+ description:
+ - Replace or delete packages quickly; do not bother with checksums before removing normal files.
+ type: bool
+ default: false
notes:
- - When used with a C(loop:) each package will be processed individually,
- it is much more efficient to pass the list directly to the O(name) option.
-'''
+ - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly
+ to the O(name) option.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Make sure nmap is installed
community.general.openbsd_pkg:
name: nmap
@@ -125,7 +119,7 @@ EXAMPLES = '''
name: '*'
state: latest
-- name: Purge a package and it's configuration files
+- name: Purge a package and its configuration files
community.general.openbsd_pkg:
name: mpd
clean: true
@@ -136,7 +130,7 @@ EXAMPLES = '''
name: qt5
quick: true
state: absent
-'''
+"""
import os
import platform
diff --git a/plugins/modules/opendj_backendprop.py b/plugins/modules/opendj_backendprop.py
index fed53532d9..cd55a39d51 100644
--- a/plugins/modules/opendj_backendprop.py
+++ b/plugins/modules/opendj_backendprop.py
@@ -8,94 +8,93 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: opendj_backendprop
-short_description: Will update the backend configuration of OpenDJ via the dsconfig set-backend-prop command
+short_description: Will update the backend configuration of OpenDJ using the dsconfig set-backend-prop command
description:
- - This module will update settings for OpenDJ with the command set-backend-prop.
- - It will check first via de get-backend-prop if configuration needs to be applied.
+ - This module will update settings for OpenDJ with the command set-backend-prop.
+ - It will check first using de get-backend-prop if configuration needs to be applied.
author:
- - Werner Dijkerman (@dj-wasabi)
+ - Werner Dijkerman (@dj-wasabi)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- opendj_bindir:
- description:
- - The path to the bin directory of OpenDJ.
- required: false
- default: /opt/opendj/bin
- type: path
- hostname:
- description:
- - The hostname of the OpenDJ server.
- required: true
- type: str
- port:
- description:
- - The Admin port on which the OpenDJ instance is available.
- required: true
- type: str
- username:
- description:
- - The username to connect to.
- required: false
- default: cn=Directory Manager
- type: str
- password:
- description:
- - The password for the cn=Directory Manager user.
- - Either password or passwordfile is needed.
- required: false
- type: str
- passwordfile:
- description:
- - Location to the password file which holds the password for the cn=Directory Manager user.
- - Either password or passwordfile is needed.
- required: false
- type: path
- backend:
- description:
- - The name of the backend on which the property needs to be updated.
- required: true
- type: str
- name:
- description:
- - The configuration setting to update.
- required: true
- type: str
- value:
- description:
- - The value for the configuration item.
- required: true
- type: str
- state:
- description:
- - If configuration needs to be added/updated
- required: false
- default: "present"
- type: str
-'''
+ opendj_bindir:
+ description:
+ - The path to the bin directory of OpenDJ.
+ required: false
+ default: /opt/opendj/bin
+ type: path
+ hostname:
+ description:
+ - The hostname of the OpenDJ server.
+ required: true
+ type: str
+ port:
+ description:
+ - The Admin port on which the OpenDJ instance is available.
+ required: true
+ type: str
+ username:
+ description:
+ - The username to connect to.
+ required: false
+ default: cn=Directory Manager
+ type: str
+ password:
+ description:
+ - The password for the C(cn=Directory Manager) user.
+ - Either password or passwordfile is needed.
+ required: false
+ type: str
+ passwordfile:
+ description:
+ - Location to the password file which holds the password for the C(cn=Directory Manager) user.
+ - Either password or passwordfile is needed.
+ required: false
+ type: path
+ backend:
+ description:
+ - The name of the backend on which the property needs to be updated.
+ required: true
+ type: str
+ name:
+ description:
+ - The configuration setting to update.
+ required: true
+ type: str
+ value:
+ description:
+ - The value for the configuration item.
+ required: true
+ type: str
+ state:
+ description:
+ - If configuration needs to be added/updated.
+ required: false
+ default: "present"
+ type: str
+"""
-EXAMPLES = '''
- - name: Add or update OpenDJ backend properties
- action: opendj_backendprop
- hostname=localhost
- port=4444
- username="cn=Directory Manager"
- password=password
- backend=userRoot
- name=index-entry-limit
- value=5000
-'''
+EXAMPLES = r"""
+- name: Add or update OpenDJ backend properties
+ opendj_backendprop:
+ hostname: localhost
+ port: 4444
+ username: "cn=Directory Manager"
+ password: password
+ backend: userRoot
+ name: index-entry-limit
+ value: 5000
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/openwrt_init.py b/plugins/modules/openwrt_init.py
index 46fdea5e27..bf5ce2b76a 100644
--- a/plugins/modules/openwrt_init.py
+++ b/plugins/modules/openwrt_init.py
@@ -8,52 +8,51 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: openwrt_init
author:
- - "Andrew Gaffney (@agaffney)"
+ - "Andrew Gaffney (@agaffney)"
short_description: Manage services on OpenWrt
description:
- - Controls OpenWrt services on remote hosts.
+ - Controls OpenWrt services on remote hosts.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- type: str
- description:
- - Name of the service.
- required: true
- aliases: ['service']
- state:
- type: str
- description:
- - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
- - V(restarted) will always bounce the service.
- - V(reloaded) will always reload.
- choices: [ 'started', 'stopped', 'restarted', 'reloaded' ]
- enabled:
- description:
- - Whether the service should start on boot. B(At least one of state and enabled are required.)
- type: bool
- pattern:
- type: str
- description:
- - If the service does not respond to the 'running' command, name a
- substring to look for as would be found in the output of the C(ps)
- command as a stand-in for a 'running' result. If the string is found,
- the service will be assumed to be running.
+ name:
+ type: str
+ description:
+ - Name of the service.
+ required: true
+ aliases: ['service']
+ state:
+ type: str
+ description:
+ - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
+ - V(restarted) will always bounce the service.
+ - V(reloaded) will always reload.
+ choices: ['started', 'stopped', 'restarted', 'reloaded']
+ enabled:
+ description:
+ - Whether the service should start on boot. B(At least one of state and enabled are required).
+ type: bool
+ pattern:
+ type: str
+ description:
+ - If the service does not respond to the 'running' command, name a substring to look for as would be found in the output
+ of the C(ps) command as a stand-in for a 'running' result. If the string is found, the service will be assumed to
+ be running.
notes:
- - One option other than name is required.
+ - One option other than O(name) is required.
requirements:
- - An OpenWrt system (with python)
-'''
+ - An OpenWrt system (with python)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Start service httpd, if not running
community.general.openwrt_init:
state: started
@@ -73,10 +72,10 @@ EXAMPLES = '''
community.general.openwrt_init:
name: httpd
enabled: true
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/opkg.py b/plugins/modules/opkg.py
index da51755efb..4c2fe74949 100644
--- a/plugins/modules/opkg.py
+++ b/plugins/modules/opkg.py
@@ -11,72 +11,69 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: opkg
author: "Patrick Pelletier (@skinp)"
short_description: Package manager for OpenWrt and Openembedded/Yocto based Linux distributions
description:
- - Manages ipk packages for OpenWrt and Openembedded/Yocto based Linux distributions
+ - Manages ipk packages for OpenWrt and Openembedded/Yocto based Linux distributions.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of package(s) to install/remove.
- - C(NAME=VERSION) syntax is also supported to install a package
- in a certain version. See the examples. This only works on Yocto based
- Linux distributions (opkg>=0.3.2) and not for OpenWrt. This is
- supported since community.general 6.2.0.
- aliases: [pkg]
- required: true
- type: list
- elements: str
- state:
- description:
- - State of the package.
- choices: [ 'present', 'absent', 'installed', 'removed' ]
- default: present
- type: str
- force:
- description:
- - The C(opkg --force) parameter used.
- - Passing V("") as value and not passing any value at all have both
- the same effect of B(not) using any C(--force-) parameter.
- choices:
- - ""
- - "depends"
- - "maintainer"
- - "reinstall"
- - "overwrite"
- - "downgrade"
- - "space"
- - "postinstall"
- - "remove"
- - "checksum"
- - "removal-of-dependent-packages"
- type: str
- update_cache:
- description:
- - Update the package DB first.
- default: false
- type: bool
- executable:
- description:
- - The executable location for C(opkg).
- type: path
- version_added: 7.2.0
+ name:
+ description:
+ - Name of package(s) to install/remove.
+ - V(NAME=VERSION) syntax is also supported to install a package in a certain version. See the examples. This only works
+ on Yocto based Linux distributions (opkg>=0.3.2) and not for OpenWrt. This is supported since community.general 6.2.0.
+ aliases: [pkg]
+ required: true
+ type: list
+ elements: str
+ state:
+ description:
+ - State of the package.
+ choices: ['present', 'absent', 'installed', 'removed']
+ default: present
+ type: str
+ force:
+ description:
+ - The C(opkg --force) parameter used.
+ - State V("") is deprecated and will be removed in community.general 12.0.0. Please omit the parameter O(force) to obtain
+ the same behavior.
+ choices:
+ - ""
+ - "depends"
+ - "maintainer"
+ - "reinstall"
+ - "overwrite"
+ - "downgrade"
+ - "space"
+ - "postinstall"
+ - "remove"
+ - "checksum"
+ - "removal-of-dependent-packages"
+ type: str
+ update_cache:
+ description:
+ - Update the package DB first.
+ default: false
+ type: bool
+ executable:
+ description:
+ - The executable location for C(opkg).
+ type: path
+ version_added: 7.2.0
requirements:
- - opkg
- - python
-'''
+ - opkg
+ - python
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install foo
community.general.opkg:
name: foo
@@ -110,9 +107,9 @@ EXAMPLES = '''
name: foo
state: present
force: overwrite
-'''
+"""
-RETURN = """
+RETURN = r"""
version:
description: Version of opkg.
type: str
@@ -152,7 +149,11 @@ class Opkg(StateModuleHelper):
)
def _force(value):
+ # 12.0.0 function _force() to be removed entirely
if value == "":
+ self.deprecate('Value "" is deprecated. Simply omit the parameter "force" to prevent any --force-X argument when running opkg',
+ version="12.0.0",
+ collection_name="community.general")
value = None
return cmd_runner_fmt.as_optval("--force-")(value, ctx_ignore_none=True)
@@ -164,7 +165,7 @@ class Opkg(StateModuleHelper):
arg_formats=dict(
package=cmd_runner_fmt.as_list(),
state=cmd_runner_fmt.as_map(state_map),
- force=cmd_runner_fmt.as_func(_force),
+ force=cmd_runner_fmt.as_func(_force), # 12.0.0 replace with cmd_runner_fmt.as_optval("--force-")
update_cache=cmd_runner_fmt.as_bool("update"),
version=cmd_runner_fmt.as_fixed("--version"),
),
diff --git a/plugins/modules/osx_defaults.py b/plugins/modules/osx_defaults.py
index db5d889a37..75bd03b4ad 100644
--- a/plugins/modules/osx_defaults.py
+++ b/plugins/modules/osx_defaults.py
@@ -10,18 +10,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: osx_defaults
author:
# DO NOT RE-ADD GITHUB HANDLE!
-- Franck Nijhof (!UNKNOWN)
+ - Franck Nijhof (!UNKNOWN)
short_description: Manage macOS user defaults
description:
- - osx_defaults allows users to read, write, and delete macOS user defaults from Ansible scripts.
- - macOS applications and other programs use the defaults system to record user preferences and other
- information that must be maintained when the applications are not running (such as default font for new
- documents, or the position of an Info panel).
+ - This module allows users to read, write, and delete macOS user defaults from Ansible scripts.
+ - MacOS applications and other programs use the defaults system to record user preferences and other information that must
+ be maintained when the applications are not running (such as default font for new documents, or the position of an Info
+ panel).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -48,7 +47,7 @@ options:
description:
- The type of value to write.
type: str
- choices: [ array, bool, boolean, date, float, int, integer, string ]
+ choices: [array, bool, boolean, date, float, int, integer, string]
default: string
check_type:
description:
@@ -72,7 +71,7 @@ options:
- The state of the user defaults.
- If set to V(list) will query the given parameter specified by O(key). Returns V(null) is nothing found or mis-spelled.
type: str
- choices: [ absent, list, present ]
+ choices: [absent, list, present]
default: present
path:
description:
@@ -80,10 +79,10 @@ options:
type: str
default: /usr/bin:/usr/local/bin
notes:
- - Apple Mac caches defaults. You may need to logout and login to apply the changes.
-'''
+ - Apple Mac caches defaults. You may need to logout and login to apply the changes.
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Set boolean valued key for application domain
community.general.osx_defaults:
domain: com.apple.Safari
@@ -135,7 +134,7 @@ EXAMPLES = r'''
domain: com.geekchimp.macable
key: ExampleKeyToRemove
state: absent
-'''
+"""
from datetime import datetime
import re
diff --git a/plugins/modules/ovh_ip_failover.py b/plugins/modules/ovh_ip_failover.py
index 58d340e3e9..0734e985f7 100644
--- a/plugins/modules/ovh_ip_failover.py
+++ b/plugins/modules/ovh_ip_failover.py
@@ -9,88 +9,80 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ovh_ip_failover
short_description: Manage OVH IP failover address
description:
- - Manage OVH (French European hosting provider) IP Failover Address. For now, this module can only be used to move
- an ip failover (or failover block) between services
+ - Manage OVH (French European hosting provider) IP Failover Address. For now, this module can only be used to move an IP
+ failover (or failover block) between services.
author: "Pascal HERAUD (@pascalheraud)"
notes:
- - Uses the python OVH Api U(https://github.com/ovh/python-ovh).
- You have to create an application (a key and secret) with a consumer
- key as described into U(https://docs.ovh.com/gb/en/customer/first-steps-with-ovh-api/)
+ - Uses the Python OVH API U(https://github.com/ovh/python-ovh). You have to create an application (a key and secret) with
+ a consumer key as described into U(https://docs.ovh.com/gb/en/customer/first-steps-with-ovh-api/).
requirements:
- - ovh >= 0.4.8
+ - ovh >= 0.4.8
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- required: true
- description:
- - The IP address to manage (can be a single IP like 1.1.1.1
- or a block like 1.1.1.1/28 )
- type: str
- service:
- required: true
- description:
- - The name of the OVH service this IP address should be routed
- type: str
- endpoint:
- required: true
- description:
- - The endpoint to use ( for instance ovh-eu)
- type: str
- wait_completion:
- required: false
- default: true
- type: bool
- description:
- - If true, the module will wait for the IP address to be moved.
- If false, exit without waiting. The taskId will be returned
- in module output
- wait_task_completion:
- required: false
- default: 0
- description:
- - If not 0, the module will wait for this task id to be
- completed. Use wait_task_completion if you want to wait for
- completion of a previously executed task with
- wait_completion=false. You can execute this module repeatedly on
- a list of failover IPs using wait_completion=false (see examples)
- type: int
- application_key:
- required: true
- description:
- - The applicationKey to use
- type: str
- application_secret:
- required: true
- description:
- - The application secret to use
- type: str
- consumer_key:
- required: true
- description:
- - The consumer key to use
- type: str
- timeout:
- required: false
- default: 120
- description:
- - The timeout in seconds used to wait for a task to be
- completed. Default is 120 seconds.
- type: int
+ name:
+ required: true
+ description:
+ - The IP address to manage (can be a single IP like V(1.1.1.1) or a block like V(1.1.1.1/28)).
+ type: str
+ service:
+ required: true
+ description:
+ - The name of the OVH service this IP address should be routed.
+ type: str
+ endpoint:
+ required: true
+ description:
+ - The endpoint to use (for instance V(ovh-eu)).
+ type: str
+ wait_completion:
+ required: false
+ default: true
+ type: bool
+ description:
+ - If true, the module will wait for the IP address to be moved. If false, exit without waiting. The taskId will be returned
+ in module output.
+ wait_task_completion:
+ required: false
+ default: 0
+ description:
+ - If not 0, the module will wait for this task ID to be completed. Use O(wait_task_completion) if you want to wait for
+ completion of a previously executed task with O(wait_completion=false). You can execute this module repeatedly on
+ a list of failover IPs using O(wait_completion=false) (see examples).
+ type: int
+ application_key:
+ required: true
+ description:
+ - The applicationKey to use.
+ type: str
+ application_secret:
+ required: true
+ description:
+ - The application secret to use.
+ type: str
+ consumer_key:
+ required: true
+ description:
+ - The consumer key to use.
+ type: str
+ timeout:
+ required: false
+ default: 120
+ description:
+ - The timeout in seconds used to wait for a task to be completed. Default is 120 seconds.
+ type: int
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# Route an IP address 1.1.1.1 to the service ns666.ovh.net
- community.general.ovh_ip_failover:
name: 1.1.1.1
@@ -116,10 +108,10 @@ EXAMPLES = '''
application_key: yourkey
application_secret: yoursecret
consumer_key: yourconsumerkey
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
import time
@@ -167,7 +159,7 @@ def waitForTaskDone(client, name, taskId, timeout):
task = client.get('/ip/{0}/task/{1}'.format(quote_plus(name), taskId))
if task['status'] == 'done':
return True
- time.sleep(5) # Delay for 5 sec because it's long to wait completion, do not harass the API
+ time.sleep(5) # Delay for 5 sec to not harass the API
currentTimeout -= 5
if currentTimeout < 0:
return False
diff --git a/plugins/modules/ovh_ip_loadbalancing_backend.py b/plugins/modules/ovh_ip_loadbalancing_backend.py
index f70b5804a7..cefb9231bd 100644
--- a/plugins/modules/ovh_ip_loadbalancing_backend.py
+++ b/plugins/modules/ovh_ip_loadbalancing_backend.py
@@ -9,85 +9,80 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ovh_ip_loadbalancing_backend
short_description: Manage OVH IP LoadBalancing backends
description:
- - Manage OVH (French European hosting provider) LoadBalancing IP backends
+ - Manage OVH (French European hosting provider) LoadBalancing IP backends.
author: Pascal Heraud (@pascalheraud)
notes:
- - Uses the python OVH Api U(https://github.com/ovh/python-ovh).
- You have to create an application (a key and secret) with a consumer
- key as described into U(https://docs.ovh.com/gb/en/customer/first-steps-with-ovh-api/)
+ - Uses the Python OVH API U(https://github.com/ovh/python-ovh). You have to create an application (a key and secret) with
+ a consumer key as described into U(https://docs.ovh.com/gb/en/customer/first-steps-with-ovh-api/).
requirements:
- - ovh > 0.3.5
+ - ovh > 0.3.5
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- required: true
- description:
- - Name of the LoadBalancing internal name (ip-X.X.X.X)
- type: str
- backend:
- required: true
- description:
- - The IP address of the backend to update / modify / delete
- type: str
- state:
- default: present
- choices: ['present', 'absent']
- description:
- - Determines whether the backend is to be created/modified
- or deleted
- type: str
- probe:
- default: 'none'
- choices: ['none', 'http', 'icmp' , 'oco']
- description:
- - Determines the type of probe to use for this backend
- type: str
- weight:
- default: 8
- description:
- - Determines the weight for this backend
- type: int
- endpoint:
- required: true
- description:
- - The endpoint to use ( for instance ovh-eu)
- type: str
- application_key:
- required: true
- description:
- - The applicationKey to use
- type: str
- application_secret:
- required: true
- description:
- - The application secret to use
- type: str
- consumer_key:
- required: true
- description:
- - The consumer key to use
- type: str
- timeout:
- default: 120
- description:
- - The timeout in seconds used to wait for a task to be
- completed.
- type: int
+ name:
+ required: true
+ description:
+ - Name of the LoadBalancing internal name (V(ip-X.X.X.X)).
+ type: str
+ backend:
+ required: true
+ description:
+ - The IP address of the backend to update / modify / delete.
+ type: str
+ state:
+ default: present
+ choices: ['present', 'absent']
+ description:
+ - Determines whether the backend is to be created/modified or deleted.
+ type: str
+ probe:
+ default: 'none'
+ choices: ['none', 'http', 'icmp', 'oco']
+ description:
+ - Determines the type of probe to use for this backend.
+ type: str
+ weight:
+ default: 8
+ description:
+ - Determines the weight for this backend.
+ type: int
+ endpoint:
+ required: true
+ description:
+ - The endpoint to use (for instance V(ovh-eu)).
+ type: str
+ application_key:
+ required: true
+ description:
+ - The applicationKey to use.
+ type: str
+ application_secret:
+ required: true
+ description:
+ - The application secret to use.
+ type: str
+ consumer_key:
+ required: true
+ description:
+ - The consumer key to use.
+ type: str
+ timeout:
+ default: 120
+ description:
+ - The timeout in seconds used to wait for a task to be completed.
+ type: int
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Adds or modify the backend '212.1.1.1' to a loadbalancing 'ip-1.1.1.1'
ovh_ip_loadbalancing:
name: ip-1.1.1.1
@@ -109,10 +104,10 @@ EXAMPLES = '''
application_key: yourkey
application_secret: yoursecret
consumer_key: yourconsumerkey
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
import time
diff --git a/plugins/modules/ovh_monthly_billing.py b/plugins/modules/ovh_monthly_billing.py
index c2f503e3ad..438bf7db7f 100644
--- a/plugins/modules/ovh_monthly_billing.py
+++ b/plugins/modules/ovh_monthly_billing.py
@@ -9,52 +9,51 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: ovh_monthly_billing
author: Francois Lallart (@fraff)
version_added: '0.2.0'
short_description: Manage OVH monthly billing
description:
- - Enable monthly billing on OVH cloud instances (be aware OVH does not allow to disable it).
-requirements: [ "ovh" ]
+ - Enable monthly billing on OVH cloud instances (be aware OVH does not allow to disable it).
+requirements: ["ovh"]
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- project_id:
- required: true
- type: str
- description:
- - ID of the project, get it with U(https://api.ovh.com/console/#/cloud/project#GET)
- instance_id:
- required: true
- type: str
- description:
- - ID of the instance, get it with U(https://api.ovh.com/console/#/cloud/project/%7BserviceName%7D/instance#GET)
- endpoint:
- type: str
- description:
- - The endpoint to use (for instance ovh-eu)
- application_key:
- type: str
- description:
- - The applicationKey to use
- application_secret:
- type: str
- description:
- - The application secret to use
- consumer_key:
- type: str
- description:
- - The consumer key to use
-'''
+ project_id:
+ required: true
+ type: str
+ description:
+ - ID of the project, get it with U(https://api.ovh.com/console/#/cloud/project#GET).
+ instance_id:
+ required: true
+ type: str
+ description:
+ - ID of the instance, get it with U(https://api.ovh.com/console/#/cloud/project/%7BserviceName%7D/instance#GET).
+ endpoint:
+ type: str
+ description:
+ - The endpoint to use (for instance V(ovh-eu)).
+ application_key:
+ type: str
+ description:
+ - The applicationKey to use.
+ application_secret:
+ type: str
+ description:
+ - The application secret to use.
+ consumer_key:
+ type: str
+ description:
+ - The consumer key to use.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Basic usage, using auth from /etc/ovh.conf
community.general.ovh_monthly_billing:
project_id: 0c727a20aa144485b70c44dee9123b46
@@ -75,10 +74,10 @@ EXAMPLES = '''
application_key: yourkey
application_secret: yoursecret
consumer_key: yourconsumerkey
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
import traceback
diff --git a/plugins/modules/pacemaker_cluster.py b/plugins/modules/pacemaker_cluster.py
index 60d8656ac3..caf18abb27 100644
--- a/plugins/modules/pacemaker_cluster.py
+++ b/plugins/modules/pacemaker_cluster.py
@@ -8,71 +8,60 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pacemaker_cluster
short_description: Manage pacemaker clusters
author:
- Mathieu Bultel (@matbu)
description:
- - This module can manage a pacemaker cluster and nodes from Ansible using
- the pacemaker cli.
+ - This module can manage a pacemaker cluster and nodes from Ansible using the pacemaker CLI.
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- description:
- - Indicate desired state of the cluster
- choices: [ cleanup, offline, online, restart ]
- type: str
- node:
- description:
- - Specify which node of the cluster you want to manage. None == the
- cluster status itself, 'all' == check the status of all nodes.
- type: str
- timeout:
- description:
- - Timeout when the module should considered that the action has failed
- default: 300
- type: int
- force:
- description:
- - Force the change of the cluster state
- type: bool
- default: true
-'''
-EXAMPLES = '''
----
+ state:
+ description:
+ - Indicate desired state of the cluster.
+ choices: [cleanup, offline, online, restart]
+ type: str
+ node:
+ description:
+ - Specify which node of the cluster you want to manage. V(null) == the cluster status itself, V(all) == check the status
+ of all nodes.
+ type: str
+ timeout:
+ description:
+ - Timeout when the module should considered that the action has failed.
+ default: 300
+ type: int
+ force:
+ description:
+ - Force the change of the cluster state.
+ type: bool
+ default: true
+"""
+
+EXAMPLES = r"""
- name: Set cluster Online
hosts: localhost
gather_facts: false
tasks:
- - name: Get cluster state
- community.general.pacemaker_cluster:
- state: online
-'''
+ - name: Get cluster state
+ community.general.pacemaker_cluster:
+ state: online
+"""
-RETURN = '''
-changed:
- description: true if the cluster state has changed
- type: bool
- returned: always
+RETURN = r"""
out:
- description: The output of the current state of the cluster. It return a
- list of the nodes state.
- type: str
- sample: 'out: [[" overcloud-controller-0", " Online"]]}'
- returned: always
-rc:
- description: exit code of the module
- type: bool
- returned: always
-'''
+ description: The output of the current state of the cluster. It returns a list of the nodes state.
+ type: str
+ sample: 'out: [[" overcloud-controller-0", " Online"]]}'
+ returned: always
+"""
import time
@@ -83,7 +72,7 @@ _PCS_CLUSTER_DOWN = "Error: cluster is not currently running on this node"
def get_cluster_status(module):
- cmd = "pcs cluster status"
+ cmd = ["pcs", "cluster", "status"]
rc, out, err = module.run_command(cmd)
if out in _PCS_CLUSTER_DOWN:
return 'offline'
@@ -92,10 +81,8 @@ def get_cluster_status(module):
def get_node_status(module, node='all'):
- if node == 'all':
- cmd = "pcs cluster pcsd-status %s" % node
- else:
- cmd = "pcs cluster pcsd-status"
+ node_l = ["all"] if node == "all" else []
+ cmd = ["pcs", "cluster", "pcsd-status"] + node_l
rc, out, err = module.run_command(cmd)
if rc == 1:
module.fail_json(msg="Command execution failed.\nCommand: `%s`\nError: %s" % (cmd, err))
@@ -106,7 +93,7 @@ def get_node_status(module, node='all'):
def clean_cluster(module, timeout):
- cmd = "pcs resource cleanup"
+ cmd = ["pcs", "resource", "cleanup"]
rc, out, err = module.run_command(cmd)
if rc == 1:
module.fail_json(msg="Command execution failed.\nCommand: `%s`\nError: %s" % (cmd, err))
@@ -114,11 +101,11 @@ def clean_cluster(module, timeout):
def set_cluster(module, state, timeout, force):
if state == 'online':
- cmd = "pcs cluster start"
+ cmd = ["pcs", "cluster", "start"]
if state == 'offline':
- cmd = "pcs cluster stop"
+ cmd = ["pcs", "cluster", "stop"]
if force:
- cmd = "%s --force" % cmd
+ cmd = cmd + ["--force"]
rc, out, err = module.run_command(cmd)
if rc == 1:
module.fail_json(msg="Command execution failed.\nCommand: `%s`\nError: %s" % (cmd, err))
@@ -134,35 +121,6 @@ def set_cluster(module, state, timeout, force):
module.fail_json(msg="Failed to set the state `%s` on the cluster\n" % (state))
-def set_node(module, state, timeout, force, node='all'):
- # map states
- if state == 'online':
- cmd = "pcs cluster start"
- if state == 'offline':
- cmd = "pcs cluster stop"
- if force:
- cmd = "%s --force" % cmd
-
- nodes_state = get_node_status(module, node)
- for node in nodes_state:
- if node[1].strip().lower() != state:
- cmd = "%s %s" % (cmd, node[0].strip())
- rc, out, err = module.run_command(cmd)
- if rc == 1:
- module.fail_json(msg="Command execution failed.\nCommand: `%s`\nError: %s" % (cmd, err))
-
- t = time.time()
- ready = False
- while time.time() < t + timeout:
- nodes_state = get_node_status(module)
- for node in nodes_state:
- if node[1].strip().lower() == state:
- ready = True
- break
- if not ready:
- module.fail_json(msg="Failed to set the state `%s` on the cluster\n" % (state))
-
-
def main():
argument_spec = dict(
state=dict(type='str', choices=['online', 'offline', 'restart', 'cleanup']),
@@ -210,7 +168,7 @@ def main():
cluster_state = get_node_status(module, node)
module.exit_json(changed=True, out=cluster_state)
- if state in ['restart']:
+ elif state == 'restart':
if module.check_mode:
module.exit_json(changed=True)
set_cluster(module, 'offline', timeout, force)
@@ -221,17 +179,16 @@ def main():
if cluster_state == 'online':
module.exit_json(changed=True, out=cluster_state)
else:
- module.fail_json(msg="Failed during the restart of the cluster, the cluster can't be started")
+ module.fail_json(msg="Failed during the restart of the cluster, the cluster cannot be started")
else:
- module.fail_json(msg="Failed during the restart of the cluster, the cluster can't be stopped")
+ module.fail_json(msg="Failed during the restart of the cluster, the cluster cannot be stopped")
- if state in ['cleanup']:
+ elif state == 'cleanup':
if module.check_mode:
module.exit_json(changed=True)
clean_cluster(module, timeout)
cluster_state = get_cluster_status(module)
- module.exit_json(changed=True,
- out=cluster_state)
+ module.exit_json(changed=True, out=cluster_state)
if __name__ == '__main__':
diff --git a/plugins/modules/pacemaker_resource.py b/plugins/modules/pacemaker_resource.py
new file mode 100644
index 0000000000..187ba6f1f0
--- /dev/null
+++ b/plugins/modules/pacemaker_resource.py
@@ -0,0 +1,228 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2025, Dexter Le
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: pacemaker_resource
+short_description: Manage pacemaker resources
+author:
+ - Dexter Le (@munchtoast)
+version_added: 10.5.0
+description:
+ - This module can manage resources in a Pacemaker cluster using the pacemaker CLI.
+extends_documentation_fragment:
+ - community.general.attributes
+attributes:
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
+options:
+ state:
+ description:
+ - Indicate desired state for cluster resource.
+ choices: [ present, absent, enabled, disabled ]
+ default: present
+ type: str
+ name:
+ description:
+ - Specify the resource name to create.
+ required: true
+ type: str
+ resource_type:
+ description:
+ - Resource type to create.
+ type: dict
+ suboptions:
+ resource_name:
+ description:
+ - Specify the resource type name.
+ type: str
+ resource_standard:
+ description:
+ - Specify the resource type standard.
+ type: str
+ resource_provider:
+ description:
+ - Specify the resource type providers.
+ type: str
+ resource_option:
+ description:
+ - Specify the resource option to create.
+ type: list
+ elements: str
+ default: []
+ resource_operation:
+ description:
+ - List of operations to associate with resource.
+ type: list
+ elements: dict
+ default: []
+ suboptions:
+ operation_action:
+ description:
+ - Operation action to associate with resource.
+ type: str
+ operation_option:
+ description:
+ - Operation option to associate with action.
+ type: list
+ elements: str
+ resource_meta:
+ description:
+ - List of meta to associate with resource.
+ type: list
+ elements: str
+ resource_argument:
+ description:
+ - Action to associate with resource.
+ type: dict
+ suboptions:
+ argument_action:
+ description:
+ - Action to apply to resource.
+ type: str
+ choices: [ clone, master, group, promotable ]
+ argument_option:
+ description:
+ - Options to associate with resource action.
+ type: list
+ elements: str
+ wait:
+ description:
+ - Timeout period for polling the resource creation.
+ type: int
+ default: 300
+'''
+
+EXAMPLES = '''
+---
+- name: Create pacemaker resource
+ hosts: localhost
+ gather_facts: false
+ tasks:
+ - name: Create virtual-ip resource
+ community.general.pacemaker_resource:
+ state: present
+ name: virtual-ip
+ resource_type:
+ resource_name: IPaddr2
+ resource_option:
+ - "ip=[192.168.2.1]"
+ resource_argument:
+ argument_action: group
+ argument_option:
+ - master
+ resource_operation:
+ - operation_action: monitor
+ operation_option:
+ - interval=20
+'''
+
+RETURN = '''
+cluster_resources:
+ description: The cluster resource output message.
+ type: str
+ sample: "Assumed agent name ocf:heartbeat:IPaddr2 (deduced from IPaddr2)"
+ returned: always
+'''
+
+from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper
+from ansible_collections.community.general.plugins.module_utils.pacemaker import pacemaker_runner
+
+
+class PacemakerResource(StateModuleHelper):
+ module = dict(
+ argument_spec=dict(
+ state=dict(type='str', default='present', choices=[
+ 'present', 'absent', 'enabled', 'disabled']),
+ name=dict(type='str', required=True),
+ resource_type=dict(type='dict', options=dict(
+ resource_name=dict(type='str'),
+ resource_standard=dict(type='str'),
+ resource_provider=dict(type='str'),
+ )),
+ resource_option=dict(type='list', elements='str', default=list()),
+ resource_operation=dict(type='list', elements='dict', default=list(), options=dict(
+ operation_action=dict(type='str'),
+ operation_option=dict(type='list', elements='str'),
+ )),
+ resource_meta=dict(type='list', elements='str'),
+ resource_argument=dict(type='dict', options=dict(
+ argument_action=dict(type='str', choices=['clone', 'master', 'group', 'promotable']),
+ argument_option=dict(type='list', elements='str'),
+ )),
+ wait=dict(type='int', default=300),
+ ),
+ required_if=[('state', 'present', ['resource_type', 'resource_option'])],
+ supports_check_mode=True,
+ )
+ use_old_vardict = False
+ default_state = "present"
+
+ def __init_module__(self):
+ self.runner = pacemaker_runner(self.module, cli_action='resource')
+ self.vars.set('previous_value', self._get())
+ self.vars.set('value', self.vars.previous_value, change=True, diff=True)
+
+ def _process_command_output(self, fail_on_err, ignore_err_msg=""):
+ def process(rc, out, err):
+ if fail_on_err and rc != 0 and err and ignore_err_msg not in err:
+ self.do_raise('pcs failed with error (rc={0}): {1}'.format(rc, err))
+ out = out.rstrip()
+ return None if out == "" else out
+ return process
+
+ def _get(self):
+ with self.runner('state name', output_process=self._process_command_output(False)) as ctx:
+ return ctx.run(state='status')
+
+ def state_absent(self):
+ with self.runner('state name', output_process=self._process_command_output(True, "does not exist"), check_mode_skip=True) as ctx:
+ ctx.run()
+ self.vars.set('value', self._get())
+ self.vars.stdout = ctx.results_out
+ self.vars.stderr = ctx.results_err
+ self.vars.cmd = ctx.cmd
+
+ def state_present(self):
+ with self.runner(
+ 'state name resource_type resource_option resource_operation resource_meta resource_argument wait',
+ output_process=self._process_command_output(True, "already exists"),
+ check_mode_skip=True) as ctx:
+ ctx.run()
+ self.vars.set('value', self._get())
+ self.vars.stdout = ctx.results_out
+ self.vars.stderr = ctx.results_err
+ self.vars.cmd = ctx.cmd
+
+ def state_enabled(self):
+ with self.runner('state name', output_process=self._process_command_output(True, "Starting"), check_mode_skip=True) as ctx:
+ ctx.run()
+ self.vars.set('value', self._get())
+ self.vars.stdout = ctx.results_out
+ self.vars.stderr = ctx.results_err
+ self.vars.cmd = ctx.cmd
+
+ def state_disabled(self):
+ with self.runner('state name', output_process=self._process_command_output(True, "Stopped"), check_mode_skip=True) as ctx:
+ ctx.run()
+ self.vars.set('value', self._get())
+ self.vars.stdout = ctx.results_out
+ self.vars.stderr = ctx.results_err
+ self.vars.cmd = ctx.cmd
+
+
+def main():
+ PacemakerResource.execute()
+
+
+if __name__ == '__main__':
+ main()
diff --git a/plugins/modules/packet_device.py b/plugins/modules/packet_device.py
index 519a7031e1..d3746b173f 100644
--- a/plugins/modules/packet_device.py
+++ b/plugins/modules/packet_device.py
@@ -10,26 +10,23 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: packet_device
short_description: Manage a bare metal server in the Packet Host
description:
- - Manage a bare metal server in the Packet Host (a "device" in the API terms).
- - When the machine is created it can optionally wait for public IP address, or for active state.
- - This module has a dependency on packet >= 1.0.
- - API is documented at U(https://www.packet.net/developers/api/devices).
-
-
+ - Manage a bare metal server in the Packet Host (a "device" in the API terms).
+ - When the machine is created it can optionally wait for public IP address, or for active state.
+ - This module has a dependency on packet >= 1.0.
+ - API is documented at U(https://www.packet.net/developers/api/devices).
author:
- - Tomas Karasek (@t0mk)
- - Matt Baldwin (@baldwinSPC)
- - Thibaud Morel l'Horset (@teebes)
+ - Tomas Karasek (@t0mk)
+ - Matt Baldwin (@baldwinSPC)
+ - Thibaud Morel l'Horset (@teebes)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
@@ -45,7 +42,7 @@ options:
count:
description:
- - The number of devices to create. Count number can be included in hostname via the %d string formatter.
+ - The number of devices to create. Count number can be included in hostname using the C(%d) string formatter.
default: 1
type: int
@@ -114,15 +111,17 @@ options:
state:
description:
- Desired state of the device.
- - If set to V(present) (the default), the module call will return immediately after the device-creating HTTP request successfully returns.
- - If set to V(active), the module call will block until all the specified devices are in state active due to the Packet API, or until O(wait_timeout).
+ - If set to V(present) (the default), the module call will return immediately after the device-creating HTTP request
+ successfully returns.
+ - If set to V(active), the module call will block until all the specified devices are in state active due to the Packet
+ API, or until O(wait_timeout).
choices: [present, absent, active, inactive, rebooted]
default: present
type: str
user_data:
description:
- - Userdata blob made available to the machine
+ - Userdata blob made available to the machine.
type: str
wait_for_public_IPv:
@@ -130,13 +129,14 @@ options:
- Whether to wait for the instance to be assigned a public IPv4/IPv6 address.
- If set to 4, it will wait until IPv4 is assigned to the instance.
- If set to 6, wait until public IPv6 is assigned to the instance.
- choices: [4,6]
+ choices: [4, 6]
type: int
wait_timeout:
description:
- How long (seconds) to wait either for automatic IP address assignment, or for the device to reach the V(active) state.
- - If O(wait_for_public_IPv) is set and O(state=active), the module will wait for both events consequently, applying the timeout twice.
+ - If O(wait_for_public_IPv) is set and O(state=active), the module will wait for both events consequently, applying
+ the timeout twice.
default: 900
type: int
@@ -156,11 +156,10 @@ options:
requirements:
- - "packet-python >= 1.35"
+ - "packet-python >= 1.35"
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# All the examples assume that you have your Packet API token in environment variable PACKET_API_TOKEN.
# You can also pass it to the auth_token parameter of the module instead.
@@ -169,79 +168,79 @@ EXAMPLES = '''
- name: Create 1 device
hosts: localhost
tasks:
- - community.general.packet_device:
- project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
- hostnames: myserver
- tags: ci-xyz
- operating_system: ubuntu_16_04
- plan: baremetal_0
- facility: sjc1
+ - community.general.packet_device:
+ project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
+ hostnames: myserver
+ tags: ci-xyz
+ operating_system: ubuntu_16_04
+ plan: baremetal_0
+ facility: sjc1
-# Create the same device and wait until it is in state "active", (when it's
+# Create the same device and wait until it is in state "active", (when it is
# ready for other API operations). Fail if the device is not "active" in
# 10 minutes.
- name: Create device and wait up to 10 minutes for active state
hosts: localhost
tasks:
- - community.general.packet_device:
- project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
- hostnames: myserver
- operating_system: ubuntu_16_04
- plan: baremetal_0
- facility: sjc1
- state: active
- wait_timeout: 600
+ - community.general.packet_device:
+ project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
+ hostnames: myserver
+ operating_system: ubuntu_16_04
+ plan: baremetal_0
+ facility: sjc1
+ state: active
+ wait_timeout: 600
- name: Create 3 ubuntu devices called server-01, server-02 and server-03
hosts: localhost
tasks:
- - community.general.packet_device:
- project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
- hostnames: server-%02d
- count: 3
- operating_system: ubuntu_16_04
- plan: baremetal_0
- facility: sjc1
+ - community.general.packet_device:
+ project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
+ hostnames: server-%02d
+ count: 3
+ operating_system: ubuntu_16_04
+ plan: baremetal_0
+ facility: sjc1
- name: Create 3 coreos devices with userdata, wait until they get IPs and then wait for SSH
hosts: localhost
tasks:
- - name: Create 3 devices and register their facts
- community.general.packet_device:
- hostnames: [coreos-one, coreos-two, coreos-three]
- operating_system: coreos_stable
- plan: baremetal_0
- facility: ewr1
- locked: true
- project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
- wait_for_public_IPv: 4
- user_data: |
- #cloud-config
- ssh_authorized_keys:
- - {{ lookup('file', 'my_packet_sshkey') }}
- coreos:
- etcd:
- discovery: https://discovery.etcd.io/6a28e078895c5ec737174db2419bb2f3
- addr: $private_ipv4:4001
- peer-addr: $private_ipv4:7001
- fleet:
- public-ip: $private_ipv4
- units:
- - name: etcd.service
- command: start
- - name: fleet.service
- command: start
- register: newhosts
+ - name: Create 3 devices and register their facts
+ community.general.packet_device:
+ hostnames: [coreos-one, coreos-two, coreos-three]
+ operating_system: coreos_stable
+ plan: baremetal_0
+ facility: ewr1
+ locked: true
+ project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
+ wait_for_public_IPv: 4
+ user_data: |
+ #cloud-config
+ ssh_authorized_keys:
+ - {{ lookup('file', 'my_packet_sshkey') }}
+ coreos:
+ etcd:
+ discovery: https://discovery.etcd.io/6a28e078895c5ec737174db2419bb2f3
+ addr: $private_ipv4:4001
+ peer-addr: $private_ipv4:7001
+ fleet:
+ public-ip: $private_ipv4
+ units:
+ - name: etcd.service
+ command: start
+ - name: fleet.service
+ command: start
+ register: newhosts
- - name: Wait for ssh
- ansible.builtin.wait_for:
- delay: 1
- host: "{{ item.public_ipv4 }}"
- port: 22
- state: started
- timeout: 500
- with_items: "{{ newhosts.devices }}"
+ - name: Wait for ssh
+ ansible.builtin.wait_for:
+ delay: 1
+ host: "{{ item.public_ipv4 }}"
+ port: 22
+ state: started
+ timeout: 500
+ with_items: "{{ newhosts.devices }}"
# Other states of devices
@@ -249,38 +248,38 @@ EXAMPLES = '''
- name: Remove 3 devices by uuid
hosts: localhost
tasks:
- - community.general.packet_device:
- project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
- state: absent
- device_ids:
- - 1fb4faf8-a638-4ac7-8f47-86fe514c30d8
- - 2eb4faf8-a638-4ac7-8f47-86fe514c3043
- - 6bb4faf8-a638-4ac7-8f47-86fe514c301f
-'''
+ - community.general.packet_device:
+ project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
+ state: absent
+ device_ids:
+ - 1fb4faf8-a638-4ac7-8f47-86fe514c30d8
+ - 2eb4faf8-a638-4ac7-8f47-86fe514c3043
+ - 6bb4faf8-a638-4ac7-8f47-86fe514c301f
+"""
-RETURN = '''
+RETURN = r"""
changed:
- description: True if a device was altered in any way (created, modified or removed)
- type: bool
- sample: true
- returned: success
+ description: True if a device was altered in any way (created, modified or removed).
+ type: bool
+ sample: true
+ returned: success
devices:
- description: Information about each device that was processed
- type: list
- sample:
- - {
- "hostname": "my-server.com",
- "id": "2a5122b9-c323-4d5c-b53c-9ad3f54273e7",
- "public_ipv4": "147.229.15.12",
- "private-ipv4": "10.0.15.12",
- "tags": [],
- "locked": false,
- "state": "provisioning",
- "public_ipv6": "2604:1380:2:5200::3"
- }
- returned: success
-''' # NOQA
+ description: Information about each device that was processed.
+ type: list
+ sample:
+ - {
+ "hostname": "my-server.com",
+ "id": "2a5122b9-c323-4d5c-b53c-9ad3f54273e7",
+ "public_ipv4": "147.229.15.12",
+ "private-ipv4": "10.0.15.12",
+ "tags": [],
+ "locked": false,
+ "state": "provisioning",
+ "public_ipv6": "2604:1380:2:5200::3"
+ }
+ returned: success
+"""
import os
diff --git a/plugins/modules/packet_ip_subnet.py b/plugins/modules/packet_ip_subnet.py
index 530cfe3a79..ab74dac840 100644
--- a/plugins/modules/packet_ip_subnet.py
+++ b/plugins/modules/packet_ip_subnet.py
@@ -10,26 +10,24 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: packet_ip_subnet
short_description: Assign IP subnet to a bare metal server
description:
- - Assign or unassign IPv4 or IPv6 subnets to or from a device in the Packet host.
- - IPv4 subnets must come from already reserved block.
- - IPv6 subnets must come from publicly routable /56 block from your project.
- - See U(https://support.packet.com/kb/articles/elastic-ips) for more info on IP block reservation.
-
+ - Assign or unassign IPv4 or IPv6 subnets to or from a device in the Packet host.
+ - IPv4 subnets must come from already reserved block.
+ - IPv6 subnets must come from publicly routable /56 block from your project.
+ - See U(https://support.packet.com/kb/articles/elastic-ips) for more info on IP block reservation.
version_added: '0.2.0'
author:
- - Tomas Karasek (@t0mk)
- - Nurfet Becirevic (@nurfet-becirevic)
+ - Tomas Karasek (@t0mk)
+ - Nurfet Becirevic (@nurfet-becirevic)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
@@ -77,18 +75,20 @@ options:
state:
description:
- Desired state of the IP subnet on the specified device.
- - With O(state=present), you must specify either O(hostname) or O(device_id). Subnet with given CIDR will then be assigned to the specified device.
- - With O(state=absent), you can specify either O(hostname) or O(device_id). The subnet will be removed from specified devices.
- - If you leave both O(hostname) and O(device_id) empty, the subnet will be removed from any device it's assigned to.
+ - With O(state=present), you must specify either O(hostname) or O(device_id). Subnet with given CIDR will then be assigned
+ to the specified device.
+ - With O(state=absent), you can specify either O(hostname) or O(device_id). The subnet will be removed from specified
+ devices.
+ - If you leave both O(hostname) and O(device_id) empty, the subnet will be removed from any device it is assigned to.
choices: ['present', 'absent']
default: 'present'
type: str
requirements:
- - "packet-python >= 1.35"
-'''
+ - "packet-python >= 1.35"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
# You can also pass it to the auth_token parameter of the module instead.
@@ -96,33 +96,33 @@ EXAMPLES = '''
hosts: localhost
tasks:
- - packet_device:
- project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
- hostnames: myserver
- operating_system: ubuntu_16_04
- plan: baremetal_0
- facility: sjc1
- state: active
+ - packet_device:
+ project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
+ hostnames: myserver
+ operating_system: ubuntu_16_04
+ plan: baremetal_0
+ facility: sjc1
+ state: active
# Pick an IPv4 address from a block allocated to your project.
- - community.general.packet_ip_subnet:
- project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
- hostname: myserver
- cidr: "147.75.201.78/32"
+ - community.general.packet_ip_subnet:
+ project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
+ hostname: myserver
+ cidr: "147.75.201.78/32"
# Release IP address 147.75.201.78
- name: Unassign IP address from any device in your project
hosts: localhost
tasks:
- - community.general.packet_ip_subnet:
- project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
- cidr: "147.75.201.78/32"
- state: absent
-'''
+ - community.general.packet_ip_subnet:
+ project_id: 89b497ee-5afc-420a-8fb5-56984898f4df
+ cidr: "147.75.201.78/32"
+ state: absent
+"""
-RETURN = '''
+RETURN = r"""
changed:
description: True if an IP address assignments were altered in any way (created or removed).
type: bool
@@ -140,7 +140,7 @@ subnet:
sample:
address: 147.75.90.241
address_family: 4
- assigned_to: { href : /devices/61f9aa5e-0530-47f5-97c2-113828e61ed0 }
+ assigned_to: {href: /devices/61f9aa5e-0530-47f5-97c2-113828e61ed0}
cidr: 31
created_at: '2017-08-07T15:15:30Z'
enabled: true
@@ -153,7 +153,7 @@ subnet:
network: 147.75.90.240
public: true
returned: success
-'''
+"""
import uuid
diff --git a/plugins/modules/packet_project.py b/plugins/modules/packet_project.py
index d8c991dba2..d61c9e598b 100644
--- a/plugins/modules/packet_project.py
+++ b/plugins/modules/packet_project.py
@@ -10,24 +10,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: packet_project
short_description: Create/delete a project in Packet host
description:
- - Create/delete a project in Packet host.
- - API is documented at U(https://www.packet.com/developers/api/#projects).
-
+ - Create/delete a project in Packet host.
+ - API is documented at U(https://www.packet.com/developers/api/#projects).
version_added: '0.2.0'
author:
- - Tomas Karasek (@t0mk)
- - Nurfet Becirevic (@nurfet-becirevic)
+ - Tomas Karasek (@t0mk)
+ - Nurfet Becirevic (@nurfet-becirevic)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
@@ -51,13 +49,13 @@ options:
auth_token:
description:
- - Packet api token. You can also supply it in environment variable E(PACKET_API_TOKEN).
+ - Packet API token. You can also supply it in environment variable E(PACKET_API_TOKEN).
type: str
name:
- description:
- - Name for/of the project.
- type: str
+ description:
+ - Name for/of the project.
+ type: str
org_id:
description:
@@ -76,11 +74,10 @@ options:
type: str
requirements:
- - "packet-python >= 1.40"
+ - "packet-python >= 1.40"
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
# You can also pass the api token in module param auth_token.
@@ -110,9 +107,9 @@ EXAMPLES = '''
community.general.packet_project:
name: "newer project"
payment_method: "the other visa"
-'''
+"""
-RETURN = '''
+RETURN = r"""
changed:
description: True if a project was created or removed.
type: bool
@@ -128,7 +125,7 @@ id:
description: UUID of addressed project.
type: str
returned: success
-'''
+"""
from ansible.module_utils.basic import AnsibleModule, env_fallback
from ansible.module_utils.common.text.converters import to_native
diff --git a/plugins/modules/packet_sshkey.py b/plugins/modules/packet_sshkey.py
index 6519735dcc..8172482108 100644
--- a/plugins/modules/packet_sshkey.py
+++ b/plugins/modules/packet_sshkey.py
@@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: packet_sshkey
short_description: Create/delete an SSH key in Packet host
description:
- - Create/delete an SSH key in Packet host.
- - API is documented at U(https://www.packet.net/help/api/#page:ssh-keys,header:ssh-keys-ssh-keys-post).
+ - Create/delete an SSH key in Packet host.
+ - API is documented at U(https://www.packet.net/help/api/#page:ssh-keys,header:ssh-keys-ssh-keys-post).
author: "Tomas Karasek (@t0mk) "
extends_documentation_fragment:
- community.general.attributes
@@ -26,42 +25,41 @@ attributes:
options:
state:
description:
- - Indicate desired state of the target.
+ - Indicate desired state of the target.
default: present
choices: ['present', 'absent']
type: str
auth_token:
description:
- - Packet API token. You can also supply it in environment variable E(PACKET_API_TOKEN).
+ - Packet API token. You can also supply it in environment variable E(PACKET_API_TOKEN).
type: str
label:
description:
- - Label for the key. If you keep it empty, it will be read from key string.
+ - Label for the key. If you keep it empty, it will be read from key string.
type: str
aliases: [name]
id:
description:
- - UUID of the key which you want to remove.
+ - UUID of the key which you want to remove.
type: str
fingerprint:
description:
- - Fingerprint of the key which you want to remove.
+ - Fingerprint of the key which you want to remove.
type: str
key:
description:
- - Public Key string ({type} {base64 encoded key} {description}).
+ - Public Key string (V({type} {base64 encoded key} {description})).
type: str
key_file:
description:
- - File with the public key.
+ - File with the public key.
type: path
requirements:
- packet-python
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
# You can also pass the api token in module param auth_token.
@@ -84,27 +82,27 @@ EXAMPLES = '''
community.general.packet_sshkey:
state: absent
id: eef49903-7a09-4ca1-af67-4087c29ab5b6
-'''
+"""
-RETURN = '''
+RETURN = r"""
changed:
- description: True if a sshkey was created or removed.
- type: bool
- sample: true
- returned: always
+ description: True if a sshkey was created or removed.
+ type: bool
+ sample: true
+ returned: always
sshkeys:
description: Information about sshkeys that were created/removed.
type: list
sample: [
- {
- "fingerprint": "5c:93:74:7c:ed:07:17:62:28:75:79:23:d6:08:93:46",
- "id": "41d61bd8-3342-428b-a09c-e67bdd18a9b7",
- "key": "ssh-dss AAAAB3NzaC1kc3MAAACBAIfNT5S0ncP4BBJBYNhNPxFF9lqVhfPeu6SM1LoCocxqDc1AT3zFRi8hjIf6TLZ2AA4FYbcAWxLMhiBxZRVldT9GdBXile78kAK5z3bKTwq152DCqpxwwbaTIggLFhsU8wrfBsPWnDuAxZ0h7mmrCjoLIE3CNLDA/NmV3iB8xMThAAAAFQCStcesSgR1adPORzBxTr7hug92LwAAAIBOProm3Gk+HWedLyE8IfofLaOeRnbBRHAOL4z0SexKkVOnQ/LGN/uDIIPGGBDYTvXgKZT+jbHeulRJ2jKgfSpGKN4JxFQ8uzVH492jEiiUJtT72Ss1dCV4PmyERVIw+f54itihV3z/t25dWgowhb0int8iC/OY3cGodlmYb3wdcQAAAIBuLbB45djZXzUkOTzzcRDIRfhaxo5WipbtEM2B1fuBt2gyrvksPpH/LK6xTjdIIb0CxPu4OCxwJG0aOz5kJoRnOWIXQGhH7VowrJhsqhIc8gN9ErbO5ea8b1L76MNcAotmBDeTUiPw01IJ8MdDxfmcsCslJKgoRKSmQpCwXQtN2g== tomk@hp2",
- "label": "mynewkey33"
- }
+ {
+ "fingerprint": "5c:93:74:7c:ed:07:17:62:28:75:79:23:d6:08:93:46",
+ "id": "41d61bd8-3342-428b-a09c-e67bdd18a9b7",
+ "key": "ssh-dss AAAAB3NzaC1kc3MAAACBA ... MdDxfmcsCslJKgoRKSmQpCwXQtN2g== user@server",
+ "label": "mynewkey33"
+ }
]
returned: always
-''' # NOQA
+"""
import os
import uuid
diff --git a/plugins/modules/packet_volume.py b/plugins/modules/packet_volume.py
index 659e8d8aa3..229d63a756 100644
--- a/plugins/modules/packet_volume.py
+++ b/plugins/modules/packet_volume.py
@@ -9,24 +9,22 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: packet_volume
short_description: Create/delete a volume in Packet host
description:
- - Create/delete a volume in Packet host.
- - API is documented at U(https://www.packet.com/developers/api/#volumes).
-
+ - Create/delete a volume in Packet host.
+ - API is documented at U(https://www.packet.com/developers/api/#volumes).
version_added: '0.2.0'
author:
- - Tomas Karasek (@t0mk)
- - Nurfet Becirevic (@nurfet-becirevic)
+ - Tomas Karasek (@t0mk)
+ - Nurfet Becirevic (@nurfet-becirevic)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
@@ -55,14 +53,13 @@ options:
name:
description:
- - Selector for API-generated name of the volume
+ - Selector for API-generated name of the volume.
type: str
description:
description:
- User-defined description attribute for Packet volume.
- - "It is used used as idempotent identifier - if volume with given
- description exists, new one is not created."
+ - It is used used as idempotent identifier - if volume with given description exists, new one is not created.
type: str
id:
@@ -72,7 +69,7 @@ options:
plan:
description:
- - storage_1 for standard tier, storage_2 for premium (performance) tier.
+ - V(storage_1) for standard tier, V(storage_2) for premium (performance) tier.
- Tiers are described at U(https://www.packet.com/cloud/storage/).
choices: ['storage_1', 'storage_2']
default: 'storage_1'
@@ -91,7 +88,7 @@ options:
locked:
description:
- - Create new volume locked.
+ - Create new volume locked.
type: bool
default: false
@@ -123,10 +120,9 @@ options:
requirements:
- "packet-python >= 1.35"
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
# You can also pass the api token in module param auth_token.
@@ -154,25 +150,25 @@ EXAMPLES = '''
id: "{{ result_create.id }}"
project_id: "{{ project_id }}"
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
id:
- description: UUID of specified volume
- type: str
- returned: success
- sample: 53000fb2-ee46-4673-93a8-de2c2bdba33c
+ description: UUID of specified volume.
+ type: str
+ returned: success
+ sample: 53000fb2-ee46-4673-93a8-de2c2bdba33c
name:
- description: The API-generated name of the volume resource.
- type: str
- returned: if volume is attached/detached to/from some device
- sample: "volume-a91dc506"
+ description: The API-generated name of the volume resource.
+ type: str
+ returned: if volume is attached/detached to/from some device
+ sample: "volume-a91dc506"
description:
- description: The user-defined description of the volume resource.
- type: str
- returned: success
- sample: "Just another volume"
-'''
+ description: The user-defined description of the volume resource.
+ type: str
+ returned: success
+ sample: "Just another volume"
+"""
import uuid
diff --git a/plugins/modules/packet_volume_attachment.py b/plugins/modules/packet_volume_attachment.py
index a46fef55cb..7537c1c3fe 100644
--- a/plugins/modules/packet_volume_attachment.py
+++ b/plugins/modules/packet_volume_attachment.py
@@ -10,27 +10,24 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: packet_volume_attachment
short_description: Attach/detach a volume to a device in the Packet host
description:
- - Attach/detach a volume to a device in the Packet host.
- - API is documented at U(https://www.packet.com/developers/api/volumes/).
- - "This module creates the attachment route in the Packet API. In order to discover
- the block devices on the server, you have to run the Attach Scripts,
- as documented at U(https://help.packet.net/technical/storage/packet-block-storage-linux)."
-
+ - Attach/detach a volume to a device in the Packet host.
+ - API is documented at U(https://www.packet.com/developers/api/volumes/).
+ - This module creates the attachment route in the Packet API. In order to discover the block devices on the server, you
+ have to run the Attach Scripts, as documented at U(https://help.packet.net/technical/storage/packet-block-storage-linux).
version_added: '0.2.0'
author:
- - Tomas Karasek (@t0mk)
- - Nurfet Becirevic (@nurfet-becirevic)
+ - Tomas Karasek (@t0mk)
+ - Nurfet Becirevic (@nurfet-becirevic)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
@@ -61,7 +58,7 @@ options:
description:
- Selector for the volume.
- It can be a UUID, an API-generated volume name, or user-defined description string.
- - 'Example values: 4a347482-b546-4f67-8300-fb5018ef0c5, volume-4a347482, "my volume"'
+ - 'Example values: V(4a347482-b546-4f67-8300-fb5018ef0c5), V(volume-4a347482), V(my volume).'
type: str
required: true
@@ -69,15 +66,14 @@ options:
description:
- Selector for the device.
- It can be a UUID of the device, or a hostname.
- - 'Example values: 98a14f7a-3d27-4478-b7cf-35b5670523f3, "my device"'
+ - 'Example values: 98a14f7a-3d27-4478-b7cf-35b5670523f3, "my device".'
type: str
requirements:
- "packet-python >= 1.35"
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
# All the examples assume that you have your Packet API token in env var PACKET_API_TOKEN.
# You can also pass the api token in module param auth_token.
@@ -122,19 +118,19 @@ EXAMPLES = '''
volume: "{{ volname }}"
device: "{{ devname }}"
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
volume_id:
- description: UUID of volume addressed by the module call.
- type: str
- returned: success
+ description: UUID of volume addressed by the module call.
+ type: str
+ returned: success
device_id:
- description: UUID of device addressed by the module call.
- type: str
- returned: success
-'''
+ description: UUID of device addressed by the module call.
+ type: str
+ returned: success
+"""
import uuid
diff --git a/plugins/modules/pacman.py b/plugins/modules/pacman.py
index f13bde317c..38a98bba60 100644
--- a/plugins/modules/pacman.py
+++ b/plugins/modules/pacman.py
@@ -12,172 +12,165 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: pacman
short_description: Manage packages with I(pacman)
description:
- - Manage packages with the I(pacman) package manager, which is used by Arch Linux and its variants.
+ - Manage packages with the I(pacman) package manager, which is used by Arch Linux and its variants.
author:
- - Indrajit Raychaudhuri (@indrajitr)
- - Aaron Bull Schaefer (@elasticdog)
- - Maxime de Roucy (@tchernomax)
- - Jean Raby (@jraby)
+ - Indrajit Raychaudhuri (@indrajitr)
+ - Aaron Bull Schaefer (@elasticdog)
+ - Maxime de Roucy (@tchernomax)
+ - Jean Raby (@jraby)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
options:
- name:
- description:
- - Name or list of names of the package(s) or file(s) to install, upgrade, or remove.
- Cannot be used in combination with O(upgrade).
- aliases: [ package, pkg ]
- type: list
- elements: str
-
- state:
- description:
- - Whether to install (V(present) or V(installed), V(latest)), or remove (V(absent) or V(removed)) a package.
- - V(present) and V(installed) will simply ensure that a desired package is installed.
- - V(latest) will update the specified package if it is not of the latest available version.
- - V(absent) and V(removed) will remove the specified package.
- default: present
- choices: [ absent, installed, latest, present, removed ]
- type: str
-
- force:
- description:
- - When removing packages, forcefully remove them, without any checks.
- Same as O(extra_args="--nodeps --nodeps").
- - When combined with O(update_cache), force a refresh of all package databases.
- Same as O(update_cache_extra_args="--refresh --refresh").
- default: false
- type: bool
-
- remove_nosave:
- description:
- - When removing packages, do not save modified configuration files as C(.pacsave) files.
- (passes C(--nosave) to pacman)
- version_added: 4.6.0
- default: false
- type: bool
-
- executable:
- description:
- - Path of the binary to use. This can either be C(pacman) or a pacman compatible AUR helper.
- - Pacman compatibility is unfortunately ill defined, in particular, this modules makes
- extensive use of the C(--print-format) directive which is known not to be implemented by
- some AUR helpers (notably, C(yay)).
- - Beware that AUR helpers might behave unexpectedly and are therefore not recommended.
- default: pacman
- type: str
- version_added: 3.1.0
-
- extra_args:
- description:
- - Additional option to pass to pacman when enforcing O(state).
- default: ''
- type: str
-
- update_cache:
- description:
- - Whether or not to refresh the master package lists.
- - This can be run as part of a package installation or as a separate step.
- - If not specified, it defaults to V(false).
- - Please note that this option only had an influence on the module's C(changed) state
- if O(name) and O(upgrade) are not specified before community.general 5.0.0.
- See the examples for how to keep the old behavior.
- type: bool
-
- update_cache_extra_args:
- description:
- - Additional option to pass to pacman when enforcing O(update_cache).
- default: ''
- type: str
-
- upgrade:
- description:
- - Whether or not to upgrade the whole system.
- Cannot be used in combination with O(name).
- - If not specified, it defaults to V(false).
- type: bool
-
- upgrade_extra_args:
- description:
- - Additional option to pass to pacman when enforcing O(upgrade).
- default: ''
- type: str
-
- reason:
- description:
- - The install reason to set for the packages.
- choices: [ dependency, explicit ]
- type: str
- version_added: 5.4.0
-
- reason_for:
- description:
- - Set the install reason for V(all) packages or only for V(new) packages.
- - In case of O(state=latest) already installed packages which will be updated to a newer version are not counted as V(new).
- default: new
- choices: [ all, new ]
- type: str
- version_added: 5.4.0
-
-notes:
- - When used with a C(loop:) each package will be processed individually,
- it is much more efficient to pass the list directly to the O(name) option.
- - To use an AUR helper (O(executable) option), a few extra setup steps might be required beforehand.
- For example, a dedicated build user with permissions to install packages could be necessary.
- - >
- In the tests, while using C(yay) as the O(executable) option, the module failed to install AUR packages
- with the error: C(error: target not found: ).
-"""
-
-RETURN = """
-packages:
+ name:
description:
- - A list of packages that have been changed.
- - Before community.general 4.5.0 this was only returned when O(upgrade=true).
- In community.general 4.5.0, it was sometimes omitted when the package list is empty,
- but since community.general 4.6.0 it is always returned when O(name) is specified or
- O(upgrade=true).
- returned: success and O(name) is specified or O(upgrade=true)
+ - Name or list of names of the package(s) or file(s) to install, upgrade, or remove. Cannot be used in combination with
+ O(upgrade).
+ aliases: [package, pkg]
type: list
elements: str
- sample: [ package, other-package ]
-cache_updated:
+ state:
description:
- - The changed status of C(pacman -Sy).
- - Useful when O(name) or O(upgrade=true) are specified next to O(update_cache=true).
- returned: success, when O(update_cache=true)
+ - Whether to install (V(present) or V(installed), V(latest)), or remove (V(absent) or V(removed)) a package.
+ - V(present) and V(installed) will simply ensure that a desired package is installed.
+ - V(latest) will update the specified package if it is not of the latest available version.
+ - V(absent) and V(removed) will remove the specified package.
+ default: present
+ choices: [absent, installed, latest, present, removed]
+ type: str
+
+ force:
+ description:
+ - When removing packages, forcefully remove them, without any checks. Same as O(extra_args="--nodeps --nodeps").
+ - When combined with O(update_cache), force a refresh of all package databases. Same as O(update_cache_extra_args="--refresh
+ --refresh").
+ default: false
type: bool
- sample: false
+
+ remove_nosave:
+ description:
+ - When removing packages, do not save modified configuration files as C(.pacsave) files. (passes C(--nosave) to pacman).
version_added: 4.6.0
+ default: false
+ type: bool
-stdout:
+ executable:
description:
- - Output from pacman.
- returned: success, when needed
+ - Path of the binary to use. This can either be C(pacman) or a pacman compatible AUR helper.
+ - Pacman compatibility is unfortunately ill defined, in particular, this modules makes extensive use of the C(--print-format)
+ directive which is known not to be implemented by some AUR helpers (notably, C(yay)).
+ - Beware that AUR helpers might behave unexpectedly and are therefore not recommended.
+ default: pacman
type: str
- sample: ":: Synchronizing package databases... core is up to date :: Starting full system upgrade..."
- version_added: 4.1.0
+ version_added: 3.1.0
-stderr:
+ extra_args:
description:
- - Error output from pacman.
- returned: success, when needed
+ - Additional option to pass to pacman when enforcing O(state).
+ default: ''
type: str
- sample: "warning: libtool: local (2.4.6+44+gb9b44533-14) is newer than core (2.4.6+42+gb88cebd5-15)\nwarning ..."
- version_added: 4.1.0
+
+ update_cache:
+ description:
+ - Whether or not to refresh the master package lists.
+ - This can be run as part of a package installation or as a separate step.
+ - If not specified, it defaults to V(false).
+ - Please note that this option only had an influence on the module's C(changed) state if O(name) and O(upgrade) are
+ not specified before community.general 5.0.0. See the examples for how to keep the old behavior.
+ type: bool
+
+ update_cache_extra_args:
+ description:
+ - Additional option to pass to pacman when enforcing O(update_cache).
+ default: ''
+ type: str
+
+ upgrade:
+ description:
+ - Whether or not to upgrade the whole system. Cannot be used in combination with O(name).
+ - If not specified, it defaults to V(false).
+ type: bool
+
+ upgrade_extra_args:
+ description:
+ - Additional option to pass to pacman when enforcing O(upgrade).
+ default: ''
+ type: str
+
+ reason:
+ description:
+ - The install reason to set for the packages.
+ choices: [dependency, explicit]
+ type: str
+ version_added: 5.4.0
+
+ reason_for:
+ description:
+ - Set the install reason for V(all) packages or only for V(new) packages.
+ - In case of O(state=latest) already installed packages which will be updated to a newer version are not counted as
+ V(new).
+ default: new
+ choices: [all, new]
+ type: str
+ version_added: 5.4.0
+
+notes:
+ - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly
+ to the O(name) option.
+ - To use an AUR helper (O(executable) option), a few extra setup steps might be required beforehand. For example, a dedicated
+ build user with permissions to install packages could be necessary.
+ - 'In the tests, while using C(yay) as the O(executable) option, the module failed to install AUR packages with the error:
+ C(error: target not found: ).'
"""
-EXAMPLES = """
+RETURN = r"""
+packages:
+ description:
+ - A list of packages that have been changed.
+ - Before community.general 4.5.0 this was only returned when O(upgrade=true). In community.general 4.5.0, it was sometimes
+ omitted when the package list is empty, but since community.general 4.6.0 it is always returned when O(name) is specified
+ or O(upgrade=true).
+ returned: success and O(name) is specified or O(upgrade=true)
+ type: list
+ elements: str
+ sample: [package, other-package]
+
+cache_updated:
+ description:
+ - The changed status of C(pacman -Sy).
+ - Useful when O(name) or O(upgrade=true) are specified next to O(update_cache=true).
+ returned: success, when O(update_cache=true)
+ type: bool
+ sample: false
+ version_added: 4.6.0
+
+stdout:
+ description:
+ - Output from pacman.
+ returned: success, when needed
+ type: str
+ sample: ":: Synchronizing package databases... core is up to date :: Starting full system upgrade..."
+ version_added: 4.1.0
+
+stderr:
+ description:
+ - Error output from pacman.
+ returned: success, when needed
+ type: str
+ sample: "warning: libtool: local (2.4.6+44+gb9b44533-14) is newer than core (2.4.6+42+gb88cebd5-15)\nwarning ..."
+ version_added: 4.1.0
+"""
+
+EXAMPLES = r"""
- name: Install package foo from repo
community.general.pacman:
name: foo
diff --git a/plugins/modules/pacman_key.py b/plugins/modules/pacman_key.py
index 4b7b2639ec..f98fb6f8a3 100644
--- a/plugins/modules/pacman_key.py
+++ b/plugins/modules/pacman_key.py
@@ -8,84 +8,83 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pacman_key
author:
- - George Rawlinson (@grawlinson)
+ - George Rawlinson (@grawlinson)
version_added: "3.2.0"
short_description: Manage pacman's list of trusted keys
description:
- - Add or remove gpg keys from the pacman keyring.
+ - Add or remove gpg keys from the pacman keyring.
notes:
- - Use full-length key ID (40 characters).
- - Keys will be verified when using O(data), O(file), or O(url) unless O(verify) is overridden.
- - Keys will be locally signed after being imported into the keyring.
- - If the key ID exists in the keyring, the key will not be added unless O(force_update) is specified.
- - O(data), O(file), O(url), and O(keyserver) are mutually exclusive.
+ - Use full-length key ID (40 characters).
+ - Keys will be verified when using O(data), O(file), or O(url) unless O(verify) is overridden.
+ - Keys will be locally signed after being imported into the keyring.
+ - If the key ID exists in the keyring, the key will not be added unless O(force_update) is specified.
+ - O(data), O(file), O(url), and O(keyserver) are mutually exclusive.
requirements:
- - gpg
- - pacman-key
+ - gpg
+ - pacman-key
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- id:
- description:
- - The 40 character identifier of the key.
- - Including this allows check mode to correctly report the changed state.
- - Do not specify a subkey ID, instead specify the primary key ID.
- required: true
- type: str
- data:
- description:
- - The keyfile contents to add to the keyring.
- - Must be of C(PGP PUBLIC KEY BLOCK) type.
- type: str
- file:
- description:
- - The path to a keyfile on the remote server to add to the keyring.
- - Remote file must be of C(PGP PUBLIC KEY BLOCK) type.
- type: path
- url:
- description:
- - The URL to retrieve keyfile from.
- - Remote file must be of C(PGP PUBLIC KEY BLOCK) type.
- type: str
- keyserver:
- description:
- - The keyserver used to retrieve key from.
- type: str
- verify:
- description:
- - Whether or not to verify the keyfile's key ID against specified key ID.
- type: bool
- default: true
- force_update:
- description:
- - This forces the key to be updated if it already exists in the keyring.
- type: bool
- default: false
- keyring:
- description:
- - The full path to the keyring folder on the remote server.
- - If not specified, module will use pacman's default (V(/etc/pacman.d/gnupg)).
- - Useful if the remote system requires an alternative gnupg directory.
- type: path
- default: /etc/pacman.d/gnupg
- state:
- description:
- - Ensures that the key is present (added) or absent (revoked).
- default: present
- choices: [ absent, present ]
- type: str
-'''
+ id:
+ description:
+ - The 40 character identifier of the key.
+ - Including this allows check mode to correctly report the changed state.
+ - Do not specify a subkey ID, instead specify the primary key ID.
+ required: true
+ type: str
+ data:
+ description:
+ - The keyfile contents to add to the keyring.
+ - Must be of C(PGP PUBLIC KEY BLOCK) type.
+ type: str
+ file:
+ description:
+ - The path to a keyfile on the remote server to add to the keyring.
+ - Remote file must be of C(PGP PUBLIC KEY BLOCK) type.
+ type: path
+ url:
+ description:
+ - The URL to retrieve keyfile from.
+ - Remote file must be of C(PGP PUBLIC KEY BLOCK) type.
+ type: str
+ keyserver:
+ description:
+ - The keyserver used to retrieve key from.
+ type: str
+ verify:
+ description:
+ - Whether or not to verify the keyfile's key ID against specified key ID.
+ type: bool
+ default: true
+ force_update:
+ description:
+ - This forces the key to be updated if it already exists in the keyring.
+ type: bool
+ default: false
+ keyring:
+ description:
+ - The full path to the keyring folder on the remote server.
+ - If not specified, module will use pacman's default (V(/etc/pacman.d/gnupg)).
+ - Useful if the remote system requires an alternative gnupg directory.
+ type: path
+ default: /etc/pacman.d/gnupg
+ state:
+ description:
+ - Ensures that the key is present (added) or absent (revoked).
+ default: present
+ choices: [absent, present]
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Import a key via local file
community.general.pacman_key:
id: 01234567890ABCDE01234567890ABCDE12345678
@@ -119,9 +118,9 @@ EXAMPLES = '''
community.general.pacman_key:
id: 01234567890ABCDE01234567890ABCDE12345678
state: absent
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
import os.path
import tempfile
diff --git a/plugins/modules/pagerduty.py b/plugins/modules/pagerduty.py
index 853bd6d797..0c14688dbd 100644
--- a/plugins/modules/pagerduty.py
+++ b/plugins/modules/pagerduty.py
@@ -9,84 +9,83 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: pagerduty
short_description: Create PagerDuty maintenance windows
description:
- - This module will let you create PagerDuty maintenance windows
+ - This module will let you create PagerDuty maintenance windows.
author:
- - "Andrew Newdigate (@suprememoocow)"
- - "Dylan Silva (@thaumos)"
- - "Justin Johns (!UNKNOWN)"
- - "Bruce Pennypacker (@bpennypacker)"
+ - "Andrew Newdigate (@suprememoocow)"
+ - "Dylan Silva (@thaumos)"
+ - "Justin Johns (!UNKNOWN)"
+ - "Bruce Pennypacker (@bpennypacker)"
requirements:
- - PagerDuty API access
+ - PagerDuty API access
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- type: str
- description:
- - Create a maintenance window or get a list of ongoing windows.
- required: true
- choices: [ "running", "started", "ongoing", "absent" ]
- name:
- type: str
- description:
- - PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API.
- user:
- type: str
- description:
- - PagerDuty user ID. Obsolete. Please, use O(token) for authorization.
- token:
- type: str
- description:
- - A pagerduty token, generated on the pagerduty site. It is used for authorization.
- required: true
- requester_id:
- type: str
- description:
- - ID of user making the request. Only needed when creating a maintenance_window.
- service:
- type: list
- elements: str
- description:
- - A comma separated list of PagerDuty service IDs.
- aliases: [ services ]
- window_id:
- type: str
- description:
- - ID of maintenance window. Only needed when absent a maintenance_window.
- hours:
- type: str
- description:
- - Length of maintenance window in hours.
- default: '1'
- minutes:
- type: str
- description:
- - Maintenance window in minutes (this is added to the hours).
- default: '0'
- desc:
- type: str
- description:
- - Short description of maintenance window.
- default: Created by Ansible
- validate_certs:
- description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
- type: bool
- default: true
-'''
+ state:
+ type: str
+ description:
+ - Create a maintenance window or get a list of ongoing windows.
+ required: true
+ choices: ["running", "started", "ongoing", "absent"]
+ name:
+ type: str
+ description:
+ - PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API.
+ user:
+ type: str
+ description:
+ - PagerDuty user ID. Obsolete. Please, use O(token) for authorization.
+ token:
+ type: str
+ description:
+ - A pagerduty token, generated on the pagerduty site. It is used for authorization.
+ required: true
+ requester_id:
+ type: str
+ description:
+ - ID of user making the request. Only needed when creating a maintenance_window.
+ service:
+ type: list
+ elements: str
+ description:
+ - A comma separated list of PagerDuty service IDs.
+ aliases: [services]
+ window_id:
+ type: str
+ description:
+ - ID of maintenance window. Only needed when absent a maintenance_window.
+ hours:
+ type: str
+ description:
+ - Length of maintenance window in hours.
+ default: '1'
+ minutes:
+ type: str
+ description:
+ - Maintenance window in minutes (this is added to the hours).
+ default: '0'
+ desc:
+ type: str
+ description:
+ - Short description of maintenance window.
+ default: Created by Ansible
+ validate_certs:
+ description:
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
+ type: bool
+ default: true
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List ongoing maintenance windows using a token
community.general.pagerduty:
name: companyabc
@@ -143,7 +142,7 @@ EXAMPLES = '''
token: yourtoken
state: absent
window_id: "{{ pd_window.result.maintenance_windows[0].id }}"
-'''
+"""
import datetime
import json
diff --git a/plugins/modules/pagerduty_alert.py b/plugins/modules/pagerduty_alert.py
index 3c0327e5ab..347e849822 100644
--- a/plugins/modules/pagerduty_alert.py
+++ b/plugins/modules/pagerduty_alert.py
@@ -8,150 +8,141 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: pagerduty_alert
short_description: Trigger, acknowledge or resolve PagerDuty incidents
description:
- - This module will let you trigger, acknowledge or resolve a PagerDuty incident by sending events
+ - This module will let you trigger, acknowledge or resolve a PagerDuty incident by sending events.
author:
- - "Amanpreet Singh (@ApsOps)"
- - "Xiao Shen (@xshen1)"
+ - "Amanpreet Singh (@ApsOps)"
+ - "Xiao Shen (@xshen1)"
requirements:
- - PagerDuty API access
+ - PagerDuty API access
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- type: str
- description:
- - PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API.
- api_key:
- type: str
- description:
- - The pagerduty API key (readonly access), generated on the pagerduty site.
- - Required if O(api_version=v1).
- integration_key:
- type: str
- description:
- - The GUID of one of your 'Generic API' services.
- - This is the 'integration key' listed on a 'Integrations' tab of PagerDuty service.
- service_id:
- type: str
- description:
- - ID of PagerDuty service when incidents will be triggered, acknowledged or resolved.
- - Required if O(api_version=v1).
- service_key:
- type: str
- description:
- - The GUID of one of your 'Generic API' services. Obsolete. Please use O(integration_key).
- state:
- type: str
- description:
- - Type of event to be sent.
- required: true
- choices:
- - 'triggered'
- - 'acknowledged'
- - 'resolved'
- api_version:
- type: str
- description:
- - The API version we want to use to run the module.
- - V1 is more limited with option we can provide to trigger incident.
- - V2 has more variables for example, O(severity), O(source), O(custom_details), etc.
- default: 'v1'
- choices:
- - 'v1'
- - 'v2'
- version_added: 7.4.0
- client:
- type: str
- description:
- - The name of the monitoring client that is triggering this event.
- required: false
- client_url:
- type: str
- description:
- - The URL of the monitoring client that is triggering this event.
- required: false
- component:
- type: str
- description:
- - Component of the source machine that is responsible for the event, for example C(mysql) or C(eth0).
- required: false
- version_added: 7.4.0
- custom_details:
- type: dict
- description:
- - Additional details about the event and affected system.
- - A dictionary with custom keys and values.
- required: false
- version_added: 7.4.0
- desc:
- type: str
- description:
- - For O(state=triggered) - Required. Short description of the problem that led to this trigger. This field (or a truncated version)
- will be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents tables in the PagerDuty UI.
- The maximum length is 1024 characters.
- - For O(state=acknowledged) or O(state=resolved) - Text that will appear in the incident's log associated with this event.
- required: false
- default: Created via Ansible
- incident_class:
- type: str
- description:
- - The class/type of the event, for example C(ping failure) or C(cpu load).
- required: false
- version_added: 7.4.0
- incident_key:
- type: str
- description:
- - Identifies the incident to which this O(state) should be applied.
- - For O(state=triggered) - If there's no open (i.e. unresolved) incident with this key, a new one will be created. If there's already an
- open incident with a matching key, this event will be appended to that incident's log. The event key provides an easy way to 'de-dup'
- problem reports. If no O(incident_key) is provided, then it will be generated by PagerDuty.
- - For O(state=acknowledged) or O(state=resolved) - This should be the incident_key you received back when the incident was first opened by a
- trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded.
- required: false
- link_url:
- type: str
- description:
- - Relevant link url to the alert. For example, the website or the job link.
- required: false
- version_added: 7.4.0
- link_text:
- type: str
- description:
- - A short description of the link_url.
- required: false
- version_added: 7.4.0
- source:
- type: str
- description:
- - The unique location of the affected system, preferably a hostname or FQDN.
- - Required in case of O(state=trigger) and O(api_version=v2).
- required: false
- version_added: 7.4.0
- severity:
- type: str
- description:
- - The perceived severity of the status the event is describing with respect to the affected system.
- - Required in case of O(state=trigger) and O(api_version=v2).
- default: 'critical'
- choices:
- - 'critical'
- - 'warning'
- - 'error'
- - 'info'
- version_added: 7.4.0
-'''
+ name:
+ type: str
+ description:
+ - PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API.
+ api_key:
+ type: str
+ description:
+ - The pagerduty API key (readonly access), generated on the pagerduty site.
+ - Required if O(api_version=v1).
+ integration_key:
+ type: str
+ description:
+ - The GUID of one of your 'Generic API' services.
+ - This is the 'integration key' listed on a 'Integrations' tab of PagerDuty service.
+ service_id:
+ type: str
+ description:
+ - ID of PagerDuty service when incidents will be triggered, acknowledged or resolved.
+ - Required if O(api_version=v1).
+ service_key:
+ type: str
+ description:
+ - The GUID of one of your 'Generic API' services. Obsolete. Please use O(integration_key).
+ state:
+ type: str
+ description:
+ - Type of event to be sent.
+ required: true
+ choices:
+ - 'triggered'
+ - 'acknowledged'
+ - 'resolved'
+ api_version:
+ type: str
+ description:
+ - The API version we want to use to run the module.
+ - V1 is more limited with option we can provide to trigger incident.
+ - V2 has more variables for example, O(severity), O(source), O(custom_details) and so on.
+ default: 'v1'
+ choices:
+ - 'v1'
+ - 'v2'
+ version_added: 7.4.0
+ client:
+ type: str
+ description:
+ - The name of the monitoring client that is triggering this event.
+ client_url:
+ type: str
+ description:
+ - The URL of the monitoring client that is triggering this event.
+ component:
+ type: str
+ description:
+ - Component of the source machine that is responsible for the event, for example C(mysql) or C(eth0).
+ version_added: 7.4.0
+ custom_details:
+ type: dict
+ description:
+ - Additional details about the event and affected system.
+ - A dictionary with custom keys and values.
+ version_added: 7.4.0
+ desc:
+ type: str
+ description:
+ - For O(state=triggered) - Required. Short description of the problem that led to this trigger. This field (or a truncated
+ version) will be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents
+ tables in the PagerDuty UI. The maximum length is 1024 characters.
+ - For O(state=acknowledged) or O(state=resolved) - Text that will appear in the incident's log associated with this
+ event.
+ default: Created via Ansible
+ incident_class:
+ type: str
+ description:
+ - The class/type of the event, for example C(ping failure) or C(cpu load).
+ version_added: 7.4.0
+ incident_key:
+ type: str
+ description:
+ - Identifies the incident to which this O(state) should be applied.
+ - For O(state=triggered) - If there is no open (in other words unresolved) incident with this key, a new one will be
+ created. If there is already an open incident with a matching key, this event will be appended to that incident's
+ log. The event key provides an easy way to 'de-dup' problem reports. If no O(incident_key) is provided, then it will
+ be generated by PagerDuty.
+ - For O(state=acknowledged) or O(state=resolved) - This should be the incident_key you received back when the incident
+ was first opened by a trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded.
+ link_url:
+ type: str
+ description:
+ - Relevant link URL to the alert. For example, the website or the job link.
+ version_added: 7.4.0
+ link_text:
+ type: str
+ description:
+ - A short description of the O(link_url).
+ version_added: 7.4.0
+ source:
+ type: str
+ description:
+ - The unique location of the affected system, preferably a hostname or FQDN.
+ - Required in case of O(state=trigger) and O(api_version=v2).
+ version_added: 7.4.0
+ severity:
+ type: str
+ description:
+ - The perceived severity of the status the event is describing with respect to the affected system.
+ - Required in case of O(state=trigger) and O(api_version=v2).
+ default: 'critical'
+ choices:
+ - 'critical'
+ - 'warning'
+ - 'error'
+ - 'info'
+ version_added: 7.4.0
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Trigger an incident with just the basic options
community.general.pagerduty_alert:
name: companyabc
@@ -226,7 +217,7 @@ EXAMPLES = '''
integration_key: xxx
incident_key: somekey
state: resolved
-'''
+"""
import json
from ansible.module_utils.basic import AnsibleModule
@@ -331,25 +322,25 @@ def send_event_v2(module, service_key, event_type, payload, link,
def main():
module = AnsibleModule(
argument_spec=dict(
- name=dict(required=False),
- api_key=dict(required=False, no_log=True),
- integration_key=dict(required=False, no_log=True),
- service_id=dict(required=False),
- service_key=dict(required=False, no_log=True),
+ name=dict(),
+ api_key=dict(no_log=True),
+ integration_key=dict(no_log=True),
+ service_id=dict(),
+ service_key=dict(no_log=True),
state=dict(
required=True, choices=['triggered', 'acknowledged', 'resolved']
),
api_version=dict(type='str', default='v1', choices=['v1', 'v2']),
- client=dict(required=False),
- client_url=dict(required=False),
- component=dict(required=False),
- custom_details=dict(required=False, type='dict'),
- desc=dict(required=False, default='Created via Ansible'),
- incident_class=dict(required=False),
- incident_key=dict(required=False, no_log=False),
- link_url=dict(required=False),
- link_text=dict(required=False),
- source=dict(required=False),
+ client=dict(),
+ client_url=dict(),
+ component=dict(),
+ custom_details=dict(type='dict'),
+ desc=dict(default='Created via Ansible'),
+ incident_class=dict(),
+ incident_key=dict(no_log=False),
+ link_url=dict(),
+ link_text=dict(),
+ source=dict(),
severity=dict(
default='critical', choices=['critical', 'warning', 'error', 'info']
),
diff --git a/plugins/modules/pagerduty_change.py b/plugins/modules/pagerduty_change.py
index acd31fb447..2b63859f1d 100644
--- a/plugins/modules/pagerduty_change.py
+++ b/plugins/modules/pagerduty_change.py
@@ -8,7 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: pagerduty_change
short_description: Track a code or infrastructure change as a PagerDuty change event
version_added: 1.3.0
@@ -31,8 +31,8 @@ attributes:
options:
integration_key:
description:
- - The integration key that identifies the service the change was made to.
- This can be found by adding an integration to a service in PagerDuty.
+ - The integration key that identifies the service the change was made to. This can be found by adding an integration
+ to a service in PagerDuty.
required: true
type: str
summary:
@@ -82,14 +82,14 @@ options:
type: str
validate_certs:
description:
- - If V(false), SSL certificates for the target URL will not be validated.
- This should only be used on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates for the target URL will not be validated. This should only be used on personally controlled
+ sites using self-signed certificates.
required: false
default: true
type: bool
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Track the deployment as a PagerDuty change event
community.general.pagerduty_change:
integration_key: abc123abc123abc123abc123abc123ab
@@ -106,7 +106,7 @@ EXAMPLES = '''
environment: production
link_url: https://github.com/ansible-collections/community.general/pull/1269
link_text: View changes on GitHub
-'''
+"""
from ansible.module_utils.urls import fetch_url
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/pagerduty_user.py b/plugins/modules/pagerduty_user.py
index eb8a309562..e03342c792 100644
--- a/plugins/modules/pagerduty_user.py
+++ b/plugins/modules/pagerduty_user.py
@@ -8,64 +8,63 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: pagerduty_user
short_description: Manage a user account on PagerDuty
description:
- - This module manages the creation/removal of a user account on PagerDuty.
+ - This module manages the creation/removal of a user account on PagerDuty.
version_added: '1.3.0'
author: Zainab Alsaffar (@zanssa)
requirements:
- - pdpyras python module = 4.1.1
- - PagerDuty API Access
+ - pdpyras python module = 4.1.1
+ - PagerDuty API Access
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- access_token:
- description:
- - An API access token to authenticate with the PagerDuty REST API.
- required: true
- type: str
- pd_user:
- description:
- - Name of the user in PagerDuty.
- required: true
- type: str
- pd_email:
- description:
- - The user's email address.
- - O(pd_email) is the unique identifier used and cannot be updated using this module.
- required: true
- type: str
- pd_role:
- description:
- - The user's role.
- choices: ['global_admin', 'manager', 'responder', 'observer', 'stakeholder', 'limited_stakeholder', 'restricted_access']
- default: 'responder'
- type: str
- state:
- description:
- - State of the user.
- - On V(present), it creates a user if the user doesn't exist.
- - On V(absent), it removes a user if the account exists.
- choices: ['present', 'absent']
- default: 'present'
- type: str
- pd_teams:
- description:
- - The teams to which the user belongs.
- - Required if O(state=present).
- type: list
- elements: str
-'''
+ access_token:
+ description:
+ - An API access token to authenticate with the PagerDuty REST API.
+ required: true
+ type: str
+ pd_user:
+ description:
+ - Name of the user in PagerDuty.
+ required: true
+ type: str
+ pd_email:
+ description:
+ - The user's email address.
+ - O(pd_email) is the unique identifier used and cannot be updated using this module.
+ required: true
+ type: str
+ pd_role:
+ description:
+ - The user's role.
+ choices: ['global_admin', 'manager', 'responder', 'observer', 'stakeholder', 'limited_stakeholder', 'restricted_access']
+ default: 'responder'
+ type: str
+ state:
+ description:
+ - State of the user.
+ - On V(present), it creates a user if the user does not exist.
+ - On V(absent), it removes a user if the account exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ type: str
+ pd_teams:
+ description:
+ - The teams to which the user belongs.
+ - Required if O(state=present).
+ type: list
+ elements: str
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a user account on PagerDuty
community.general.pagerduty_user:
access_token: 'Your_Access_token'
@@ -81,9 +80,9 @@ EXAMPLES = r'''
pd_user: user_full_name
pd_email: user_email
state: "absent"
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from os import path
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/pam_limits.py b/plugins/modules/pam_limits.py
index 4ed037a6ff..d21781ac6c 100644
--- a/plugins/modules/pam_limits.py
+++ b/plugins/modules/pam_limits.py
@@ -8,11 +8,10 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: pam_limits
author:
-- "Sebastien Rohaut (@usawa)"
+ - "Sebastien Rohaut (@usawa)"
short_description: Modify Linux PAM limits
description:
- The M(community.general.pam_limits) module modifies PAM limits.
@@ -38,32 +37,32 @@ options:
description:
- Limit type, see C(man 5 limits.conf) for an explanation.
required: true
- choices: [ "hard", "soft", "-" ]
+ choices: ["hard", "soft", "-"]
limit_item:
type: str
description:
- The limit to be set.
required: true
choices:
- - "core"
- - "data"
- - "fsize"
- - "memlock"
- - "nofile"
- - "rss"
- - "stack"
- - "cpu"
- - "nproc"
- - "as"
- - "maxlogins"
- - "maxsyslogins"
- - "priority"
- - "locks"
- - "sigpending"
- - "msgqueue"
- - "nice"
- - "rtprio"
- - "chroot"
+ - "core"
+ - "data"
+ - "fsize"
+ - "memlock"
+ - "nofile"
+ - "rss"
+ - "stack"
+ - "cpu"
+ - "nproc"
+ - "as"
+ - "maxlogins"
+ - "maxsyslogins"
+ - "priority"
+ - "locks"
+ - "sigpending"
+ - "msgqueue"
+ - "nice"
+ - "rtprio"
+ - "chroot"
value:
type: str
description:
@@ -74,24 +73,24 @@ options:
required: true
backup:
description:
- - Create a backup file including the timestamp information so you can get
- the original file back if you somehow clobbered it incorrectly.
+ - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered
+ it incorrectly.
required: false
type: bool
default: false
use_min:
description:
- If set to V(true), the minimal value will be used or conserved.
- - If the specified value is inferior to the value in the file,
- file content is replaced with the new value, else content is not modified.
+ - If the specified value is inferior to the value in the file, file content is replaced with the new value, else content
+ is not modified.
required: false
type: bool
default: false
use_max:
description:
- If set to V(true), the maximal value will be used or conserved.
- - If the specified value is superior to the value in the file,
- file content is replaced with the new value, else content is not modified.
+ - If the specified value is superior to the value in the file, file content is replaced with the new value, else content
+ is not modified.
required: false
type: bool
default: false
@@ -109,9 +108,9 @@ options:
default: ''
notes:
- If O(dest) file does not exist, it is created.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Add or modify nofile soft limit for the user joe
community.general.pam_limits:
domain: joe
@@ -141,7 +140,7 @@ EXAMPLES = r'''
limit_type: hard
limit_item: nofile
value: 39693561
-'''
+"""
import os
import re
diff --git a/plugins/modules/pamd.py b/plugins/modules/pamd.py
index 0ad4c8787e..ec2127483e 100644
--- a/plugins/modules/pamd.py
+++ b/plugins/modules/pamd.py
@@ -9,15 +9,15 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: pamd
author:
- - Kenneth D. Evensen (@kevensen)
+ - Kenneth D. Evensen (@kevensen)
short_description: Manage PAM Modules
description:
- Edit PAM service's type, control, module path and module arguments.
- - In order for a PAM rule to be modified, the type, control and
- module_path must match an existing rule. See man(5) pam.d for details.
+ - In order for a PAM rule to be modified, the type, control and module_path must match an existing rule. See man(5) pam.d
+ for details.
notes:
- This module does not handle authselect profiles.
extends_documentation_fragment:
@@ -30,8 +30,7 @@ attributes:
options:
name:
description:
- - The name generally refers to the PAM service file to
- change, for example system-auth.
+ - The name generally refers to the PAM service file to change, for example system-auth.
type: str
required: true
type:
@@ -40,12 +39,11 @@ options:
- The O(type), O(control), and O(module_path) options all must match a rule to be modified.
type: str
required: true
- choices: [ account, -account, auth, -auth, password, -password, session, -session ]
+ choices: [account, -account, auth, -auth, password, -password, session, -session]
control:
description:
- The control of the PAM rule being modified.
- - This may be a complicated control with brackets. If this is the case, be
- sure to put "[bracketed controls]" in quotes.
+ - This may be a complicated control with brackets. If this is the case, be sure to put "[bracketed controls]" in quotes.
- The O(type), O(control), and O(module_path) options all must match a rule to be modified.
type: str
required: true
@@ -57,55 +55,51 @@ options:
required: true
new_type:
description:
- - The new type to assign to the new rule.
+ - The new type to assign to the new rule.
type: str
- choices: [ account, -account, auth, -auth, password, -password, session, -session ]
+ choices: [account, -account, auth, -auth, password, -password, session, -session]
new_control:
description:
- - The new control to assign to the new rule.
+ - The new control to assign to the new rule.
type: str
new_module_path:
description:
- - The new module path to be assigned to the new rule.
+ - The new module path to be assigned to the new rule.
type: str
module_arguments:
description:
- - When O(state=updated), the O(module_arguments) will replace existing module_arguments.
- - When O(state=args_absent) args matching those listed in O(module_arguments) will be removed.
- - When O(state=args_present) any args listed in O(module_arguments) are added if
- missing from the existing rule.
- - Furthermore, if the module argument takes a value denoted by C(=),
- the value will be changed to that specified in module_arguments.
+ - When O(state=updated), the O(module_arguments) will replace existing module_arguments.
+ - When O(state=args_absent) args matching those listed in O(module_arguments) will be removed.
+ - When O(state=args_present) any args listed in O(module_arguments) are added if missing from the existing rule.
+ - Furthermore, if the module argument takes a value denoted by C(=), the value will be changed to that specified in
+ module_arguments.
type: list
elements: str
state:
description:
- - The default of V(updated) will modify an existing rule if type,
- control and module_path all match an existing rule.
- - With V(before), the new rule will be inserted before a rule matching type,
- control and module_path.
- - Similarly, with V(after), the new rule will be inserted after an existing rulematching type,
- control and module_path.
- - With either V(before) or V(after) O(new_type), O(new_control), and O(new_module_path) must all be specified.
- - If state is V(args_absent) or V(args_present), O(new_type), O(new_control), and O(new_module_path) will be ignored.
- - State V(absent) will remove the rule.
+ - The default of V(updated) will modify an existing rule if type, control and module_path all match an existing rule.
+ - With V(before), the new rule will be inserted before a rule matching type, control and module_path.
+ - Similarly, with V(after), the new rule will be inserted after an existing rulematching type, control and module_path.
+ - With either V(before) or V(after) O(new_type), O(new_control), and O(new_module_path) must all be specified.
+ - If state is V(args_absent) or V(args_present), O(new_type), O(new_control), and O(new_module_path) will be ignored.
+ - State V(absent) will remove the rule.
type: str
- choices: [ absent, before, after, args_absent, args_present, updated ]
+ choices: [absent, before, after, args_absent, args_present, updated]
default: updated
path:
description:
- - This is the path to the PAM service files.
+ - This is the path to the PAM service files.
type: path
default: /etc/pam.d
backup:
- description:
- - Create a backup file including the timestamp information so you can
- get the original file back if you somehow clobbered it incorrectly.
- type: bool
- default: false
-'''
+ description:
+ - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered
+ it incorrectly.
+ type: bool
+ default: false
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Update pamd rule's control in /etc/pam.d/system-auth
community.general.pamd:
name: system-auth
@@ -133,8 +127,7 @@ EXAMPLES = r'''
new_module_path: pam_faillock.so
state: before
-- name: Insert a new rule pam_wheel.so with argument 'use_uid' after an \
- existing rule pam_rootok.so
+- name: Insert a new rule pam_wheel.so with argument 'use_uid' after an existing rule pam_rootok.so
community.general.pamd:
name: su
type: auth
@@ -161,11 +154,7 @@ EXAMPLES = r'''
type: auth
control: required
module_path: pam_faillock.so
- module_arguments: 'preauth
- silent
- deny=3
- unlock_time=604800
- fail_interval=900'
+ module_arguments: 'preauth silent deny=3 unlock_time=604800 fail_interval=900'
state: updated
- name: Remove specific arguments from a rule
@@ -193,8 +182,8 @@ EXAMPLES = r'''
control: '[success=1 default=ignore]'
module_path: pam_succeed_if.so
module_arguments:
- - crond
- - quiet
+ - crond
+ - quiet
state: args_present
- name: Module arguments requiring commas must be listed as a Yaml list
@@ -204,7 +193,7 @@ EXAMPLES = r'''
control: required
module_path: pam_access.so
module_arguments:
- - listsep=,
+ - listsep=,
state: args_present
- name: Update specific argument value in a rule
@@ -226,21 +215,20 @@ EXAMPLES = r'''
type: auth
module_path: pam_sss.so
control: 'requisite'
-'''
+"""
-RETURN = r'''
+RETURN = r"""
change_count:
- description: How many rules were changed.
- type: int
- sample: 1
- returned: success
+ description: How many rules were changed.
+ type: int
+ sample: 1
+ returned: success
backupdest:
- description:
- - "The file name of the backup file, if created."
- returned: success
- type: str
-...
-'''
+ description:
+ - The file name of the backup file, if created.
+ returned: success
+ type: str
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/parted.py b/plugins/modules/parted.py
index b3616a8ecd..98f8f4d647 100644
--- a/plugins/modules/parted.py
+++ b/plugins/modules/parted.py
@@ -9,21 +9,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
- - Fabrizio Colonna (@ColOfAbRiX)
+ - Fabrizio Colonna (@ColOfAbRiX)
module: parted
short_description: Configure block device partitions
description:
- - This module allows configuring block device partition using the C(parted)
- command line tool. For a full description of the fields and the options
- check the GNU parted manual.
+ - This module allows configuring block device partition using the C(parted) command line tool. For a full description of
+ the fields and the options check the GNU parted manual.
requirements:
- This module requires C(parted) version 1.8.3 and above.
- Option O(align) (except V(undefined)) requires C(parted) 2.1 or above.
- - If the version of C(parted) is below 3.1, it requires a Linux version running
- the C(sysfs) file system C(/sys/).
+ - If the version of C(parted) is below 3.1, it requires a Linux version running the C(sysfs) file system C(/sys/).
- Requires the C(resizepart) command when using the O(resize) parameter.
extends_documentation_fragment:
- community.general.attributes
@@ -36,15 +33,15 @@ options:
device:
description:
- The block device (disk) where to operate.
- - Regular files can also be partitioned, but it is recommended to create a
- loopback device using C(losetup) to easily access its partitions.
+ - Regular files can also be partitioned, but it is recommended to create a loopback device using C(losetup) to easily
+ access its partitions.
type: str
required: true
align:
description:
- Set alignment for newly created partitions. Use V(undefined) for parted default alignment.
type: str
- choices: [ cylinder, minimal, none, optimal, undefined ]
+ choices: [cylinder, minimal, none, optimal, undefined]
default: optimal
number:
description:
@@ -53,46 +50,43 @@ options:
type: int
unit:
description:
- - Selects the current default unit that Parted will use to display
- locations and capacities on the disk and to interpret those given by the
- user if they are not suffixed by an unit.
+ - Selects the current default unit that Parted will use to display locations and capacities on the disk and to interpret
+ those given by the user if they are not suffixed by an unit.
- When fetching information about a disk, it is recommended to always specify a unit.
type: str
- choices: [ s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact ]
+ choices: [s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact]
default: KiB
label:
description:
- Disk label type or partition table to use.
- - If O(device) already contains a different label, it will be changed to O(label)
- and any previous partitions will be lost.
+ - If O(device) already contains a different label, it will be changed to O(label) and any previous partitions will be
+ lost.
- A O(name) must be specified for a V(gpt) partition table.
type: str
- choices: [ aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun ]
+ choices: [aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun]
default: msdos
part_type:
description:
- May be specified only with O(label=msdos) or O(label=dvh).
- Neither O(part_type) nor O(name) may be used with O(label=sun).
type: str
- choices: [ extended, logical, primary ]
+ choices: [extended, logical, primary]
default: primary
part_start:
description:
- - Where the partition will start as offset from the beginning of the disk,
- that is, the "distance" from the start of the disk. Negative numbers
- specify distance from the end of the disk.
- - The distance can be specified with all the units supported by parted
- (except compat) and it is case sensitive, for example V(10GiB), V(15%).
+ - Where the partition will start as offset from the beginning of the disk, that is, the "distance" from the start of
+ the disk. Negative numbers specify distance from the end of the disk.
+ - The distance can be specified with all the units supported by parted (except compat) and it is case sensitive, for
+ example V(10GiB), V(15%).
- Using negative values may require setting of O(fs_type) (see notes).
type: str
default: 0%
part_end:
description:
- - Where the partition will end as offset from the beginning of the disk,
- that is, the "distance" from the start of the disk. Negative numbers
- specify distance from the end of the disk.
- - The distance can be specified with all the units supported by parted
- (except compat) and it is case sensitive, for example V(10GiB), V(15%).
+ - Where the partition will end as offset from the beginning of the disk, that is, the "distance" from the start of the
+ disk. Negative numbers specify distance from the end of the disk.
+ - The distance can be specified with all the units supported by parted (except compat) and it is case sensitive, for
+ example V(10GiB), V(15%).
type: str
default: 100%
name:
@@ -108,7 +102,7 @@ options:
- Whether to create or delete a partition.
- If set to V(info) the module will only return the device information.
type: str
- choices: [ absent, present, info ]
+ choices: [absent, present, info]
default: info
fs_type:
description:
@@ -124,18 +118,16 @@ options:
version_added: '1.3.0'
notes:
- - When fetching information about a new disk and when the version of parted
- installed on the system is before version 3.1, the module queries the kernel
- through C(/sys/) to obtain disk information. In this case the units CHS and
- CYL are not supported.
- - Negative O(part_start) start values were rejected if O(fs_type) was not given.
- This bug was fixed in parted 3.2.153. If you want to use negative O(part_start),
- specify O(fs_type) as well or make sure your system contains newer parted.
-'''
+ - When fetching information about a new disk and when the version of parted installed on the system is before version 3.1,
+ the module queries the kernel through C(/sys/) to obtain disk information. In this case the units CHS and CYL are not
+ supported.
+ - Negative O(part_start) start values were rejected if O(fs_type) was not given. This bug was fixed in parted 3.2.153. If
+ you want to use negative O(part_start), specify O(fs_type) as well or make sure your system contains newer parted.
+"""
-RETURN = r'''
+RETURN = r"""
partition_info:
- description: Current partition information
+ description: Current partition information.
returned: success
type: complex
contains:
@@ -146,7 +138,7 @@ partition_info:
description: List of device partitions.
type: list
script:
- description: parted script executed by module
+ description: Parted script executed by module.
type: str
sample: {
"disk": {
@@ -177,9 +169,9 @@ partition_info:
}],
"script": "unit KiB print "
}
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create a new ext4 primary partition
community.general.parted:
device: /dev/sdb
@@ -204,7 +196,7 @@ EXAMPLES = r'''
community.general.parted:
device: /dev/sdb
number: 2
- flags: [ lvm ]
+ flags: [lvm]
state: present
part_start: 1GiB
@@ -235,7 +227,7 @@ EXAMPLES = r'''
part_end: "100%"
resize: true
state: present
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
@@ -596,11 +588,8 @@ def read_record(file_path, default=None):
Reads the first line of a file and returns it.
"""
try:
- f = open(file_path, 'r')
- try:
+ with open(file_path, 'r') as f:
return f.readline().strip()
- finally:
- f.close()
except IOError:
return default
diff --git a/plugins/modules/pear.py b/plugins/modules/pear.py
index 36770de6c5..05135925bc 100644
--- a/plugins/modules/pear.py
+++ b/plugins/modules/pear.py
@@ -12,54 +12,55 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pear
short_description: Manage pear/pecl packages
description:
- - Manage PHP packages with the pear package manager.
+ - Manage PHP packages with the pear package manager.
author:
- - Jonathan Lestrelin (@jle64)
+ - Jonathan Lestrelin (@jle64)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- type: str
- description:
- - Name of the package to install, upgrade, or remove.
- required: true
- aliases: [pkg]
- state:
- type: str
- description:
- - Desired state of the package.
- default: "present"
- choices: ["present", "installed", "latest", "absent", "removed"]
- executable:
- type: path
- description:
- - Path to the pear executable.
- prompts:
- description:
- - List of regular expressions that can be used to detect prompts during pear package installation to answer the expected question.
- - Prompts will be processed in the same order as the packages list.
- - You can optionally specify an answer to any question in the list.
- - If no answer is provided, the list item will only contain the regular expression.
- - "To specify an answer, the item will be a dict with the regular expression as key and the answer as value C(my_regular_expression: 'an_answer')."
- - You can provide a list containing items with or without answer.
- - A prompt list can be shorter or longer than the packages list but will issue a warning.
- - If you want to specify that a package will not need prompts in the middle of a list, V(null).
- type: list
- elements: raw
- version_added: 0.2.0
-'''
+ name:
+ type: str
+ description:
+ - Name of the package to install, upgrade, or remove.
+ required: true
+ aliases: [pkg]
+ state:
+ type: str
+ description:
+ - Desired state of the package.
+ default: "present"
+ choices: ["present", "installed", "latest", "absent", "removed"]
+ executable:
+ type: path
+ description:
+ - Path to the pear executable.
+ prompts:
+ description:
+ - List of regular expressions that can be used to detect prompts during pear package installation to answer the expected
+ question.
+ - Prompts will be processed in the same order as the packages list.
+ - You can optionally specify an answer to any question in the list.
+ - If no answer is provided, the list item will only contain the regular expression.
+ - "To specify an answer, the item will be a dict with the regular expression as key and the answer as value C(my_regular_expression:
+ 'an_answer')."
+ - You can provide a list containing items with or without answer.
+ - A prompt list can be shorter or longer than the packages list but will issue a warning.
+ - If you want to specify that a package will not need prompts in the middle of a list, V(null).
+ type: list
+ elements: raw
+ version_added: 0.2.0
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Install pear package
community.general.pear:
name: Net_URL2
@@ -75,18 +76,17 @@ EXAMPLES = r'''
name: pecl/apcu
state: present
prompts:
- - (.*)Enable internal debugging in APCu \[no\]
+ - (.*)Enable internal debugging in APCu \[no\]
- name: Install pecl package with expected prompt and an answer
community.general.pear:
name: pecl/apcu
state: present
prompts:
- - (.*)Enable internal debugging in APCu \[no\]: "yes"
+ - (.*)Enable internal debugging in APCu \[no\]: "yes"
-- name: Install multiple pear/pecl packages at once with prompts.
- Prompts will be processed on the same order as the packages order.
- If there is more prompts than packages, packages without prompts will be installed without any prompt expected.
+- name: Install multiple pear/pecl packages at once with prompts. Prompts will be processed on the same order as the packages
+ order. If there is more prompts than packages, packages without prompts will be installed without any prompt expected.
If there is more packages than prompts, additional prompts will be ignored.
community.general.pear:
name: pecl/gnupg, pecl/apcu
@@ -95,10 +95,9 @@ EXAMPLES = r'''
- I am a test prompt because gnupg doesnt asks anything
- (.*)Enable internal debugging in APCu \[no\]: "yes"
-- name: Install multiple pear/pecl packages at once skipping the first prompt.
- Prompts will be processed on the same order as the packages order.
- If there is more prompts than packages, packages without prompts will be installed without any prompt expected.
- If there is more packages than prompts, additional prompts will be ignored.
+- name: Install multiple pear/pecl packages at once skipping the first prompt. Prompts will be processed on the same order
+ as the packages order. If there is more prompts than packages, packages without prompts will be installed without any
+ prompt expected. If there is more packages than prompts, additional prompts will be ignored.
community.general.pear:
name: pecl/gnupg, pecl/apcu
state: present
@@ -115,7 +114,7 @@ EXAMPLES = r'''
community.general.pear:
name: Net_URL2,pecl/json_post
state: absent
-'''
+"""
import os
@@ -227,7 +226,7 @@ def install_packages(module, state, packages, prompts):
# Preparing prompts answer according to item type
tmp_prompts = []
for _item in prompts:
- # If the current item is a dict then we expect it's key to be the prompt regex and it's value to be the answer
+ # If the current item is a dict then we expect its key to be the prompt regex and its value to be the answer
# We also expect here that the dict only has ONE key and the first key will be taken
if isinstance(_item, dict):
key = list(_item.keys())[0]
diff --git a/plugins/modules/pids.py b/plugins/modules/pids.py
index 99b52ef1dd..2db5dbfa23 100644
--- a/plugins/modules/pids.py
+++ b/plugins/modules/pids.py
@@ -7,9 +7,10 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: pids
-description: "Retrieves a list of PIDs of given process name in Ansible controller/controlled machines.Returns an empty list if no process in that name exists."
+description: "Retrieves a list of PIDs of given process name in Ansible controller/controlled machines. Returns an empty list
+ if no process in that name exists."
short_description: Retrieves process IDs list if the process is running otherwise return empty list
author:
- Saranya Sridharan (@saranyasridharan)
@@ -35,13 +36,13 @@ options:
type: bool
default: false
version_added: 3.0.0
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
# Pass the process name
- name: Getting process IDs of the process
community.general.pids:
- name: python
+ name: python
register: pids_of_python
- name: Printing the process IDs obtained
@@ -52,15 +53,15 @@ EXAMPLES = r'''
community.general.pids:
pattern: python(2(\.7)?|3(\.6)?)?\s+myapp\.py
register: myapp_pids
-'''
+"""
-RETURN = '''
+RETURN = r"""
pids:
- description: Process IDs of the given process
+ description: Process IDs of the given process.
returned: list of none, one, or more process IDs
type: list
- sample: [100,200]
-'''
+ sample: [100, 200]
+"""
import abc
import re
diff --git a/plugins/modules/pingdom.py b/plugins/modules/pingdom.py
index bd4826a780..192dd244f2 100644
--- a/plugins/modules/pingdom.py
+++ b/plugins/modules/pingdom.py
@@ -8,56 +8,55 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: pingdom
short_description: Pause/unpause Pingdom alerts
description:
- - This module will let you pause/unpause Pingdom alerts
+ - This module will let you pause/unpause Pingdom alerts.
author:
- - "Dylan Silva (@thaumos)"
- - "Justin Johns (!UNKNOWN)"
+ - "Dylan Silva (@thaumos)"
+ - "Justin Johns (!UNKNOWN)"
requirements:
- - "This pingdom python library: https://github.com/mbabineau/pingdom-python"
+ - "This pingdom python library: U(https://github.com/mbabineau/pingdom-python)"
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- type: str
- description:
- - Define whether or not the check should be running or paused.
- required: true
- choices: [ "running", "paused", "started", "stopped" ]
- checkid:
- type: str
- description:
- - Pingdom ID of the check.
- required: true
- uid:
- type: str
- description:
- - Pingdom user ID.
- required: true
- passwd:
- type: str
- description:
- - Pingdom user password.
- required: true
- key:
- type: str
- description:
- - Pingdom API key.
- required: true
+ state:
+ type: str
+ description:
+ - Define whether or not the check should be running or paused.
+ required: true
+ choices: ["running", "paused", "started", "stopped"]
+ checkid:
+ type: str
+ description:
+ - Pingdom ID of the check.
+ required: true
+ uid:
+ type: str
+ description:
+ - Pingdom user ID.
+ required: true
+ passwd:
+ type: str
+ description:
+ - Pingdom user password.
+ required: true
+ key:
+ type: str
+ description:
+ - Pingdom API key.
+ required: true
notes:
- - This module does not yet have support to add/remove checks.
-'''
+ - This module does not yet have support to add/remove checks.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Pause the check with the ID of 12345
community.general.pingdom:
uid: example@example.com
@@ -73,7 +72,7 @@ EXAMPLES = '''
key: apipassword123
checkid: 12345
state: running
-'''
+"""
import traceback
diff --git a/plugins/modules/pip_package_info.py b/plugins/modules/pip_package_info.py
index f7354e3678..0be9b34fe9 100644
--- a/plugins/modules/pip_package_info.py
+++ b/plugins/modules/pip_package_info.py
@@ -9,33 +9,33 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: pip_package_info
short_description: Pip package information
description:
- - Return information about installed pip packages
+ - Return information about installed pip packages.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.info_module
options:
clients:
description:
- - A list of the pip executables that will be used to get the packages.
- They can be supplied with the full path or just the executable name, for example V(pip3.7).
+ - A list of the pip executables that will be used to get the packages. They can be supplied with the full path or just
+ the executable name, for example V(pip3.7).
default: ['pip']
required: false
type: list
elements: path
requirements:
- pip >= 20.3b1 (necessary for the C(--format) option)
- - The requested pip executables must be installed on the target.
+ - The requested C(pip) executables must be installed on the target.
author:
- Matthew Jones (@matburt)
- Brian Coca (@bcoca)
- Adam Miller (@maxamillion)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Just get the list from default pip
community.general.pip_package_info:
@@ -46,16 +46,16 @@ EXAMPLES = '''
- name: Get from specific paths (virtualenvs?)
community.general.pip_package_info:
clients: '/home/me/projec42/python/pip3.5'
-'''
+"""
-RETURN = '''
+RETURN = r"""
packages:
- description: a dictionary of installed package data
+ description: A dictionary of installed package data.
returned: always
type: dict
contains:
python:
- description: A dictionary with each pip client which then contains a list of dicts with python package information
+ description: A dictionary with each pip client which then contains a list of dicts with python package information.
returned: always
type: dict
sample:
@@ -91,7 +91,8 @@ packages:
],
},
}
-'''
+"""
+
import json
import os
diff --git a/plugins/modules/pipx.py b/plugins/modules/pipx.py
index 9bde0f180c..e7806d4e75 100644
--- a/plugins/modules/pipx.py
+++ b/plugins/modules/pipx.py
@@ -9,16 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: pipx
short_description: Manages applications installed with pipx
version_added: 3.8.0
description:
-- Manage Python applications installed in isolated virtualenvs using pipx.
+ - Manage Python applications installed in isolated virtualenvs using pipx.
extends_documentation_fragment:
-- community.general.attributes
-- community.general.pipx
+ - community.general.attributes
+ - community.general.pipx
attributes:
check_mode:
support: full
@@ -28,131 +27,132 @@ options:
state:
type: str
choices:
- - present
- - absent
- - install
- - install_all
- - uninstall
- - uninstall_all
- - inject
- - uninject
- - upgrade
- - upgrade_shared
- - upgrade_all
- - reinstall
- - reinstall_all
- - latest
- - pin
- - unpin
+ - present
+ - absent
+ - install
+ - install_all
+ - uninstall
+ - uninstall_all
+ - inject
+ - uninject
+ - upgrade
+ - upgrade_shared
+ - upgrade_all
+ - reinstall
+ - reinstall_all
+ - latest
+ - pin
+ - unpin
default: install
description:
- - Desired state for the application.
- - The states V(present) and V(absent) are aliases to V(install) and V(uninstall), respectively.
- - The state V(latest) is equivalent to executing the task twice, with state V(install) and then V(upgrade). It was added in community.general
- 5.5.0.
- - The states V(install_all), V(uninject), V(upgrade_shared), V(pin) and V(unpin) are only available in C(pipx>=1.6.0), make sure to have a
- compatible version when using this option. These states have been added in community.general 9.4.0.
+ - Desired state for the application.
+ - The states V(present) and V(absent) are aliases to V(install) and V(uninstall), respectively.
+ - The state V(latest) is equivalent to executing the task twice, with state V(install) and then V(upgrade). It was added
+ in community.general 5.5.0.
+ - The states V(install_all), V(uninject), V(upgrade_shared), V(pin) and V(unpin) are only available in C(pipx>=1.6.0),
+ make sure to have a compatible version when using this option. These states have been added in community.general 9.4.0.
name:
type: str
description:
- - The name of the application. In C(pipx) documentation it is also referred to as the name of the virtual environment where the application
- will be installed.
- - If O(name) is a simple package name without version specifiers, then that name is used as the Python package name to be installed.
- - Use O(source) for passing package specifications or installing from URLs or directories.
+ - The name of the application. In C(pipx) documentation it is also referred to as the name of the virtual environment
+ where the application will be installed.
+ - If O(name) is a simple package name without version specifiers, then that name is used as the Python package name
+ to be installed.
+ - Use O(source) for passing package specifications or installing from URLs or directories.
source:
type: str
description:
- - Source for the package. This option is used when O(state=install) or O(state=latest), and it is ignored with other states.
- - Use O(source) when installing a Python package with version specifier, or from a local path, from a VCS URL or compressed file.
- - The value of this option is passed as-is to C(pipx).
- - O(name) is still required when using O(source) to establish the application name without fetching the package from a remote source.
+ - Source for the package. This option is used when O(state=install) or O(state=latest), and it is ignored with other
+ states.
+ - Use O(source) when installing a Python package with version specifier, or from a local path, from a VCS URL or compressed
+ file.
+ - The value of this option is passed as-is to C(pipx).
+ - O(name) is still required when using O(source) to establish the application name without fetching the package from
+ a remote source.
install_apps:
description:
- - Add apps from the injected packages.
- - Only used when O(state=inject).
+ - Add apps from the injected packages.
+ - Only used when O(state=inject).
type: bool
default: false
version_added: 6.5.0
install_deps:
description:
- - Include applications of dependent packages.
- - Only used when O(state=install), O(state=latest), or O(state=inject).
+ - Include applications of dependent packages.
+ - Only used when O(state=install), O(state=latest), or O(state=inject).
type: bool
default: false
inject_packages:
description:
- - Packages to be injected into an existing virtual environment.
- - Only used when O(state=inject).
+ - Packages to be injected into an existing virtual environment.
+ - Only used when O(state=inject).
type: list
elements: str
force:
description:
- - Force modification of the application's virtual environment. See C(pipx) for details.
- - Only used when O(state=install), O(state=upgrade), O(state=upgrade_all), O(state=latest), or O(state=inject).
+ - Force modification of the application's virtual environment. See C(pipx) for details.
+ - Only used when O(state=install), O(state=upgrade), O(state=upgrade_all), O(state=latest), or O(state=inject).
type: bool
default: false
include_injected:
description:
- - Upgrade the injected packages along with the application.
- - Only used when O(state=upgrade), O(state=upgrade_all), or O(state=latest).
- - This is used with O(state=upgrade) and O(state=latest) since community.general 6.6.0.
+ - Upgrade the injected packages along with the application.
+ - Only used when O(state=upgrade), O(state=upgrade_all), or O(state=latest).
+ - This is used with O(state=upgrade) and O(state=latest) since community.general 6.6.0.
type: bool
default: false
index_url:
description:
- - Base URL of Python Package Index.
- - Only used when O(state=install), O(state=upgrade), O(state=latest), or O(state=inject).
+ - Base URL of Python Package Index.
+ - Only used when O(state=install), O(state=upgrade), O(state=latest), or O(state=inject).
type: str
python:
description:
- - Python version to be used when creating the application virtual environment. Must be 3.6+.
- - Only used when O(state=install), O(state=latest), O(state=reinstall), or O(state=reinstall_all).
+ - Python version to be used when creating the application virtual environment. Must be 3.6+.
+ - Only used when O(state=install), O(state=latest), O(state=reinstall), or O(state=reinstall_all).
type: str
system_site_packages:
description:
- - Give application virtual environment access to the system site-packages directory.
- - Only used when O(state=install) or O(state=latest).
+ - Give application virtual environment access to the system site-packages directory.
+ - Only used when O(state=install) or O(state=latest).
type: bool
default: false
version_added: 6.6.0
editable:
description:
- - Install the project in editable mode.
+ - Install the project in editable mode.
type: bool
default: false
version_added: 4.6.0
pip_args:
description:
- - Arbitrary arguments to pass directly to C(pip).
+ - Arbitrary arguments to pass directly to C(pip).
type: str
version_added: 4.6.0
suffix:
description:
- - Optional suffix for virtual environment and executable names.
- - "B(Warning:) C(pipx) documentation states this is an B(experimental) feature subject to change."
+ - Optional suffix for virtual environment and executable names.
+ - B(Warning:) C(pipx) documentation states this is an B(experimental) feature subject to change.
type: str
version_added: 9.3.0
global:
version_added: 9.4.0
spec_metadata:
description:
- - Spec metadata file for O(state=install_all).
- - This content of the file is usually generated with C(pipx list --json), and it can be obtained with M(community.general.pipx_info) with
- O(community.general.pipx_info#module:include_raw=true) and obtaining the content from the RV(community.general.pipx_info#module:raw_output).
+ - Spec metadata file for O(state=install_all).
+ - This content of the file is usually generated with C(pipx list --json), and it can be obtained with M(community.general.pipx_info)
+ with O(community.general.pipx_info#module:include_raw=true) and obtaining the content from the RV(community.general.pipx_info#module:raw_output).
type: path
version_added: 9.4.0
notes:
-- >
- This first implementation does not verify whether a specified version constraint has been installed or not.
- Hence, when using version operators, C(pipx) module will always try to execute the operation,
- even when the application was previously installed.
- This feature will be added in the future.
+ - This first implementation does not verify whether a specified version constraint has been installed or not. Hence, when
+ using version operators, C(pipx) module will always try to execute the operation, even when the application was previously
+ installed. This feature will be added in the future.
author:
-- "Alexei Znamensky (@russoz)"
+ - "Alexei Znamensky (@russoz)"
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: Install tox
community.general.pipx:
name: tox
@@ -181,15 +181,24 @@ EXAMPLES = """
- name: Install multiple packages from list
vars:
pipx_packages:
- - pycowsay
- - black
- - tox
+ - pycowsay
+ - black
+ - tox
community.general.pipx:
name: "{{ item }}"
state: latest
with_items: "{{ pipx_packages }}"
"""
+RETURN = r"""
+version:
+ description: Version of pipx.
+ type: str
+ returned: always
+ sample: "1.7.1"
+ version_added: 10.1.0
+"""
+
from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper
from ansible_collections.community.general.plugins.module_utils.pipx import pipx_runner, pipx_common_argspec, make_process_list
@@ -272,6 +281,10 @@ class PipX(StateModuleHelper):
self.vars.set('application', self._retrieve_installed(), change=True, diff=True)
+ with self.runner("version") as ctx:
+ rc, out, err = ctx.run()
+ self.vars.version = out.strip()
+
def __quit_module__(self):
self.vars.application = self._retrieve_installed()
@@ -369,12 +382,12 @@ class PipX(StateModuleHelper):
def state_latest(self):
if not self.vars.application or self.vars.force:
self.changed = True
- args_order = 'state index_url install_deps force python system_site_packages editable pip_args suffix name_source'
+ args_order = 'state global index_url install_deps force python system_site_packages editable pip_args suffix name_source'
with self.runner(args_order, check_mode_skip=True) as ctx:
ctx.run(state='install', name_source=[self.vars.name, self.vars.source])
self._capture_results(ctx)
- with self.runner('state include_injected index_url force editable pip_args name', check_mode_skip=True) as ctx:
+ with self.runner('state global include_injected index_url force editable pip_args name', check_mode_skip=True) as ctx:
ctx.run(state='upgrade')
self._capture_results(ctx)
diff --git a/plugins/modules/pipx_info.py b/plugins/modules/pipx_info.py
index 33fbad0e5d..91d2fdb21c 100644
--- a/plugins/modules/pipx_info.py
+++ b/plugins/modules/pipx_info.py
@@ -9,46 +9,44 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: pipx_info
short_description: Rretrieves information about applications installed with pipx
version_added: 5.6.0
description:
-- Retrieve details about Python applications installed in isolated virtualenvs using pipx.
+ - Retrieve details about Python applications installed in isolated virtualenvs using pipx.
extends_documentation_fragment:
-- community.general.attributes
-- community.general.attributes.info_module
-- community.general.pipx
+ - community.general.attributes
+ - community.general.attributes.info_module
+ - community.general.pipx
options:
name:
description:
- - Name of an application installed with C(pipx).
+ - Name of an application installed with C(pipx).
type: str
include_deps:
description:
- - Include dependent packages in the output.
+ - Include dependent packages in the output.
type: bool
default: false
include_injected:
description:
- - Include injected packages in the output.
+ - Include injected packages in the output.
type: bool
default: false
include_raw:
description:
- - Returns the raw output of C(pipx list --json).
- - The raw output is not affected by O(include_deps) or O(include_injected).
+ - Returns the raw output of C(pipx list --json).
+ - The raw output is not affected by O(include_deps) or O(include_injected).
type: bool
default: false
global:
version_added: 9.3.0
author:
-- "Alexei Znamensky (@russoz)"
+ - "Alexei Znamensky (@russoz)"
"""
-EXAMPLES = """
----
+EXAMPLES = r"""
- name: retrieve all installed applications
community.general.pipx_info: {}
@@ -68,10 +66,9 @@ EXAMPLES = """
include_deps: true
"""
-RETURN = """
----
+RETURN = r"""
application:
- description: The list of installed applications
+ description: The list of installed applications.
returned: success
type: list
elements: dict
@@ -100,8 +97,8 @@ application:
licenses: "0.6.1"
pinned:
description:
- - Whether the installed application is pinned or not.
- - When using C(pipx<=1.6.0), this returns C(null).
+ - Whether the installed application is pinned or not.
+ - When using C(pipx<=1.6.0), this returns C(null).
returned: success
type: bool
sample:
@@ -119,6 +116,13 @@ cmd:
type: list
elements: str
sample: ["/usr/bin/python3.10", "-m", "pipx", "list", "--include-injected", "--json"]
+
+version:
+ description: Version of pipx.
+ type: str
+ returned: always
+ sample: "1.7.1"
+ version_added: 10.1.0
"""
from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper
@@ -149,6 +153,9 @@ class PipXInfo(ModuleHelper):
facts = ansible_facts(self.module, gather_subset=['python'])
self.command = [facts['python']['executable'], '-m', 'pipx']
self.runner = pipx_runner(self.module, self.command)
+ with self.runner("version") as ctx:
+ rc, out, err = ctx.run()
+ self.vars.version = out.strip()
def __run__(self):
output_process = make_process_list(self, **self.vars.as_dict())
diff --git a/plugins/modules/pkg5.py b/plugins/modules/pkg5.py
index 08fa9272f7..34e86c3774 100644
--- a/plugins/modules/pkg5.py
+++ b/plugins/modules/pkg5.py
@@ -8,11 +8,10 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pkg5
author:
-- Peter Oliver (@mavit)
+ - Peter Oliver (@mavit)
short_description: Manages packages with the Solaris 11 Image Packaging System
description:
- IPS packages are the native packages in Solaris 11 and higher.
@@ -36,7 +35,7 @@ options:
state:
description:
- Whether to install (V(present), V(latest)), or remove (V(absent)) a package.
- choices: [ absent, latest, present, installed, removed, uninstalled ]
+ choices: [absent, latest, present, installed, removed, uninstalled]
default: present
type: str
accept_licenses:
@@ -44,7 +43,7 @@ options:
- Accept any licences.
type: bool
default: false
- aliases: [ accept, accept_licences ]
+ aliases: [accept, accept_licences]
be_name:
description:
- Creates a new boot environment with the given name.
@@ -60,8 +59,8 @@ options:
type: bool
default: false
version_added: 9.0.0
-'''
-EXAMPLES = '''
+"""
+EXAMPLES = r"""
- name: Install Vim
community.general.pkg5:
name: editor/vim
@@ -79,9 +78,9 @@ EXAMPLES = '''
- name: Install several packages at once
community.general.pkg5:
name:
- - /file/gnu-findutils
- - /text/gnu-grep
-'''
+ - /file/gnu-findutils
+ - /text/gnu-grep
+"""
import re
diff --git a/plugins/modules/pkg5_publisher.py b/plugins/modules/pkg5_publisher.py
index 6d07e455f4..01c9d48cce 100644
--- a/plugins/modules/pkg5_publisher.py
+++ b/plugins/modules/pkg5_publisher.py
@@ -10,15 +10,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pkg5_publisher
author: "Peter Oliver (@mavit)"
short_description: Manages Solaris 11 Image Packaging System publishers
description:
- IPS packages are the native packages in Solaris 11 and higher.
- - This modules will configure which publishers a client will download IPS
- packages from.
+ - This modules will configure which publishers a client will download IPS packages from.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -31,18 +29,17 @@ options:
description:
- The publisher's name.
required: true
- aliases: [ publisher ]
+ aliases: [publisher]
type: str
state:
description:
- Whether to ensure that a publisher is present or absent.
default: present
- choices: [ present, absent ]
+ choices: [present, absent]
type: str
sticky:
description:
- - Packages installed from a sticky repository can only receive updates
- from that repository.
+ - Packages installed from a sticky repository can only receive updates from that repository.
type: bool
enabled:
description:
@@ -60,8 +57,8 @@ options:
- Multiple values may be provided.
type: list
elements: str
-'''
-EXAMPLES = '''
+"""
+EXAMPLES = r"""
- name: Fetch packages for the solaris publisher direct from Oracle
community.general.pkg5_publisher:
name: solaris
@@ -72,7 +69,7 @@ EXAMPLES = '''
community.general.pkg5_publisher:
name: site
origin: 'https://pkg.example.com/site/'
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/pkgin.py b/plugins/modules/pkgin.py
index 8b29655d37..21a3b10016 100644
--- a/plugins/modules/pkgin.py
+++ b/plugins/modules/pkgin.py
@@ -16,70 +16,67 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pkgin
short_description: Package manager for SmartOS, NetBSD, et al
description:
- - "The standard package manager for SmartOS, but also usable on NetBSD
- or any OS that uses C(pkgsrc). (Home: U(http://pkgin.net/))"
+ - 'The standard package manager for SmartOS, but also usable on NetBSD or any OS that uses C(pkgsrc). (Home: U(http://pkgin.net/)).'
author:
- - "Larry Gilbert (@L2G)"
- - "Shaun Zinck (@szinck)"
- - "Jasper Lievisse Adriaanse (@jasperla)"
+ - "Larry Gilbert (@L2G)"
+ - "Shaun Zinck (@szinck)"
+ - "Jasper Lievisse Adriaanse (@jasperla)"
notes:
- - "Known bug with pkgin < 0.8.0: if a package is removed and another
- package depends on it, the other package will be silently removed as
- well."
+ - 'Known bug with pkgin < 0.8.0: if a package is removed and another package depends on it, the other package will be silently
+ removed as well.'
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of package to install/remove;
- - multiple names may be given, separated by commas
- aliases: [pkg]
- type: list
- elements: str
- state:
- description:
- - Intended state of the package
- choices: [ 'present', 'absent' ]
- default: present
- type: str
- update_cache:
- description:
- - Update repository database. Can be run with other steps or on it's own.
- type: bool
- default: false
- upgrade:
- description:
- - Upgrade main packages to their newer versions
- type: bool
- default: false
- full_upgrade:
- description:
- - Upgrade all packages to their newer versions
- type: bool
- default: false
- clean:
- description:
- - Clean packages cache
- type: bool
- default: false
- force:
- description:
- - Force package reinstall
- type: bool
- default: false
-'''
+ name:
+ description:
+ - Name of package to install/remove;
+ - Multiple names may be given, separated by commas.
+ aliases: [pkg]
+ type: list
+ elements: str
+ state:
+ description:
+ - Intended state of the package.
+ choices: ['present', 'absent']
+ default: present
+ type: str
+ update_cache:
+ description:
+ - Update repository database. Can be run with other steps or on its own.
+ type: bool
+ default: false
+ upgrade:
+ description:
+ - Upgrade main packages to their newer versions.
+ type: bool
+ default: false
+ full_upgrade:
+ description:
+ - Upgrade all packages to their newer versions.
+ type: bool
+ default: false
+ clean:
+ description:
+ - Clean packages cache.
+ type: bool
+ default: false
+ force:
+ description:
+ - Force package reinstall.
+ type: bool
+ default: false
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install package foo
community.general.pkgin:
name: foo
@@ -125,7 +122,7 @@ EXAMPLES = '''
- name: Clean packages cache (equivalent to pkgin clean)
community.general.pkgin:
clean: true
-'''
+"""
import re
diff --git a/plugins/modules/pkgng.py b/plugins/modules/pkgng.py
index 7a04ee3a6e..582abd3649 100644
--- a/plugins/modules/pkgng.py
+++ b/plugins/modules/pkgng.py
@@ -14,107 +14,101 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pkgng
short_description: Package manager for FreeBSD >= 9.0
description:
- - Manage binary packages for FreeBSD using 'pkgng' which is available in versions after 9.0.
+ - Manage binary packages for FreeBSD using C(pkgng) which is available in versions after 9.0.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name or list of names of packages to install/remove.
- - "With O(name=*), O(state=latest) will operate, but O(state=present) and O(state=absent) will be noops."
- required: true
- aliases: [pkg]
- type: list
- elements: str
- state:
- description:
- - State of the package.
- choices: [ 'present', 'latest', 'absent' ]
- required: false
- default: present
- type: str
- cached:
- description:
- - Use local package base instead of fetching an updated one.
- type: bool
- required: false
- default: false
- annotation:
- description:
- - A list of keyvalue-pairs of the form
- C(<+/-/:>[=]). A V(+) denotes adding an annotation, a
- V(-) denotes removing an annotation, and V(:) denotes modifying an
- annotation.
- If setting or modifying annotations, a value must be provided.
- required: false
- type: list
- elements: str
- pkgsite:
- description:
- - For pkgng versions before 1.1.4, specify packagesite to use
- for downloading packages. If not specified, use settings from
- C(/usr/local/etc/pkg.conf).
- - For newer pkgng versions, specify a the name of a repository
- configured in C(/usr/local/etc/pkg/repos).
- required: false
- type: str
- rootdir:
- description:
- - For pkgng versions 1.5 and later, pkg will install all packages
- within the specified root directory.
- - Can not be used together with O(chroot) or O(jail) options.
- required: false
- type: path
- chroot:
- description:
- - Pkg will chroot in the specified environment.
- - Can not be used together with O(rootdir) or O(jail) options.
- required: false
- type: path
- jail:
- description:
- - Pkg will execute in the given jail name or id.
- - Can not be used together with O(chroot) or O(rootdir) options.
- type: str
- autoremove:
- description:
- - Remove automatically installed packages which are no longer needed.
- required: false
- type: bool
- default: false
- ignore_osver:
- description:
- - Ignore FreeBSD OS version check, useful on -STABLE and -CURRENT branches.
- - Defines the E(IGNORE_OSVERSION) environment variable.
- required: false
- type: bool
- default: false
- version_added: 1.3.0
- use_globs:
- description:
- - Treat the package names as shell glob patterns.
- required: false
- type: bool
- default: true
- version_added: 9.3.0
+ name:
+ description:
+ - Name or list of names of packages to install/remove.
+ - With O(name=*), O(state=latest) will operate, but O(state=present) and O(state=absent) will be noops.
+ required: true
+ aliases: [pkg]
+ type: list
+ elements: str
+ state:
+ description:
+ - State of the package.
+ choices: ['present', 'latest', 'absent']
+ required: false
+ default: present
+ type: str
+ cached:
+ description:
+ - Use local package base instead of fetching an updated one.
+ type: bool
+ required: false
+ default: false
+ annotation:
+ description:
+ - A list of keyvalue-pairs of the form C(<+/-/:>[=]). A V(+) denotes adding an annotation, a V(-) denotes
+ removing an annotation, and V(:) denotes modifying an annotation. If setting or modifying annotations, a value must
+ be provided.
+ required: false
+ type: list
+ elements: str
+ pkgsite:
+ description:
+ - For C(pkgng) versions before 1.1.4, specify C(packagesite) to use for downloading packages. If not specified, use
+ settings from C(/usr/local/etc/pkg.conf).
+ - For newer C(pkgng) versions, specify a the name of a repository configured in C(/usr/local/etc/pkg/repos).
+ required: false
+ type: str
+ rootdir:
+ description:
+ - For C(pkgng) versions 1.5 and later, pkg will install all packages within the specified root directory.
+ - Can not be used together with O(chroot) or O(jail) options.
+ required: false
+ type: path
+ chroot:
+ description:
+ - Pkg will chroot in the specified environment.
+ - Can not be used together with O(rootdir) or O(jail) options.
+ required: false
+ type: path
+ jail:
+ description:
+ - Pkg will execute in the given jail name or ID.
+ - Can not be used together with O(chroot) or O(rootdir) options.
+ type: str
+ autoremove:
+ description:
+ - Remove automatically installed packages which are no longer needed.
+ required: false
+ type: bool
+ default: false
+ ignore_osver:
+ description:
+ - Ignore FreeBSD OS version check, useful on C(-STABLE) and C(-CURRENT) branches.
+ - Defines the E(IGNORE_OSVERSION) environment variable.
+ required: false
+ type: bool
+ default: false
+ version_added: 1.3.0
+ use_globs:
+ description:
+ - Treat the package names as shell glob patterns.
+ required: false
+ type: bool
+ default: true
+ version_added: 9.3.0
author: "bleader (@bleader)"
notes:
- - When using pkgsite, be careful that already in cache packages won't be downloaded again.
- - When used with a C(loop:) each package will be processed individually,
- it is much more efficient to pass the list directly to the O(name) option.
-'''
+ - When using pkgsite, be careful that already in cache packages will not be downloaded again.
+ - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly
+ to the O(name) option.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install package foo
community.general.pkgng:
name: foo
@@ -149,7 +143,7 @@ EXAMPLES = '''
name: foo/bar
state: latest
use_globs: false
-'''
+"""
from collections import defaultdict
diff --git a/plugins/modules/pkgutil.py b/plugins/modules/pkgutil.py
index 15f98a9d49..7eb18cdb20 100644
--- a/plugins/modules/pkgutil.py
+++ b/plugins/modules/pkgutil.py
@@ -12,63 +12,63 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: pkgutil
short_description: OpenCSW package management on Solaris
description:
-- This module installs, updates and removes packages from the OpenCSW project for Solaris.
-- Unlike the M(community.general.svr4pkg) module, it will resolve and download dependencies.
-- See U(https://www.opencsw.org/) for more information about the project.
+ - This module installs, updates and removes packages from the OpenCSW project for Solaris.
+ - Unlike the M(community.general.svr4pkg) module, it will resolve and download dependencies.
+ - See U(https://www.opencsw.org/) for more information about the project.
author:
-- Alexander Winkler (@dermute)
-- David Ponessa (@scathatheworm)
+ - Alexander Winkler (@dermute)
+ - David Ponessa (@scathatheworm)
extends_documentation_fragment:
-- community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
details:
- - In order to check the availability of packages, the catalog cache under C(/var/opt/csw/pkgutil) may be refreshed even in check mode.
+ - In order to check the availability of packages, the catalog cache under C(/var/opt/csw/pkgutil) may be refreshed even
+ in check mode.
diff_mode:
support: none
options:
name:
description:
- - The name of the package.
- - When using O(state=latest), this can be V('*'), which updates all installed packages managed by pkgutil.
+ - The name of the package.
+ - When using O(state=latest), this can be V('*'), which updates all installed packages managed by pkgutil.
type: list
required: true
elements: str
- aliases: [ pkg ]
+ aliases: [pkg]
site:
description:
- - The repository path to install the package from.
- - Its global definition is in C(/etc/opt/csw/pkgutil.conf).
+ - The repository path to install the package from.
+ - Its global definition is in C(/etc/opt/csw/pkgutil.conf).
required: false
type: str
state:
description:
- - Whether to install (V(present)/V(installed)), or remove (V(absent)/V(removed)) packages.
- - The upgrade (V(latest)) operation will update/install the packages to the latest version available.
+ - Whether to install (V(present)/V(installed)), or remove (V(absent)/V(removed)) packages.
+ - The upgrade (V(latest)) operation will update/install the packages to the latest version available.
type: str
required: true
- choices: [ absent, installed, latest, present, removed ]
+ choices: [absent, installed, latest, present, removed]
update_catalog:
description:
- - If you always want to refresh your catalog from the mirror, even when it's not stale, set this to V(true).
+ - If you always want to refresh your catalog from the mirror, even when it is not stale, set this to V(true).
type: bool
default: false
force:
description:
- - To allow the update process to downgrade packages to match what is present in the repository, set this to V(true).
- - This is useful for rolling back to stable from testing, or similar operations.
+ - To allow the update process to downgrade packages to match what is present in the repository, set this to V(true).
+ - This is useful for rolling back to stable from testing, or similar operations.
type: bool
default: false
version_added: 1.2.0
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Install a package
community.general.pkgutil:
name: CSWcommon
@@ -88,8 +88,8 @@ EXAMPLES = r'''
- name: Install several packages
community.general.pkgutil:
name:
- - CSWsudo
- - CSWtop
+ - CSWsudo
+ - CSWtop
state: present
- name: Update all packages
@@ -102,9 +102,9 @@ EXAMPLES = r'''
name: '*'
state: latest
force: true
-'''
+"""
-RETURN = r''' # '''
+RETURN = r""" # """
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/pmem.py b/plugins/modules/pmem.py
index 4d10c448e1..66c1d27033 100644
--- a/plugins/modules/pmem.py
+++ b/plugins/modules/pmem.py
@@ -7,21 +7,20 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
- - Masayoshi Mizuma (@mizumm)
+ - Masayoshi Mizuma (@mizumm)
module: pmem
short_description: Configure Intel Optane Persistent Memory modules
version_added: 4.5.0
description:
- - This module allows Configuring Intel Optane Persistent Memory modules
- (PMem) using ipmctl and ndctl command line tools.
+ - This module allows Configuring Intel Optane Persistent Memory modules (PMem) using C(ipmctl) and C(ndctl) command line
+ tools.
requirements:
- - ipmctl and ndctl command line tools
- - xmltodict
+ - C(ipmctl) and C(ndctl) command line tools
+ - xmltodict
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
@@ -30,33 +29,32 @@ attributes:
options:
appdirect:
description:
- - Percentage of the total capacity to use in AppDirect Mode (V(0)-V(100)).
- - Create AppDirect capacity utilizing hardware interleaving across the
- requested PMem modules if applicable given the specified target.
- - Total of O(appdirect), O(memorymode) and O(reserved) must be V(100)
+ - Percentage of the total capacity to use in AppDirect Mode (V(0)-V(100)).
+ - Create AppDirect capacity utilizing hardware interleaving across the requested PMem modules if applicable given the
+ specified target.
+ - Total of O(appdirect), O(memorymode) and O(reserved) must be V(100).
type: int
appdirect_interleaved:
description:
- - Create AppDirect capacity that is interleaved any other PMem modules.
+ - Create AppDirect capacity that is interleaved any other PMem modules.
type: bool
required: false
default: true
memorymode:
description:
- - Percentage of the total capacity to use in Memory Mode (V(0)-V(100)).
+ - Percentage of the total capacity to use in Memory Mode (V(0)-V(100)).
type: int
reserved:
description:
- - Percentage of the capacity to reserve (V(0)-V(100)). O(reserved) will not be mapped
- into the system physical address space and will be presented as reserved
- capacity with Show Device and Show Memory Resources Commands.
- - O(reserved) will be set automatically if this is not configured.
+ - Percentage of the capacity to reserve (V(0)-V(100)). O(reserved) will not be mapped into the system physical address
+ space and will be presented as reserved capacity with Show Device and Show Memory Resources Commands.
+ - O(reserved) will be set automatically if this is not configured.
type: int
required: false
socket:
description:
- - This enables to set the configuration for each socket by using the socket ID.
- - Total of O(appdirect), O(memorymode) and O(reserved) must be V(100) within one socket.
+ - This enables to set the configuration for each socket by using the socket ID.
+ - Total of O(appdirect), O(memorymode) and O(reserved) must be V(100) within one socket.
type: list
elements: dict
suboptions:
@@ -66,18 +64,18 @@ options:
required: true
appdirect:
description:
- - Percentage of the total capacity to use in AppDirect Mode (V(0)-V(100)) within the socket ID.
+ - Percentage of the total capacity to use in AppDirect Mode (V(0)-V(100)) within the socket ID.
type: int
required: true
appdirect_interleaved:
description:
- - Create AppDirect capacity that is interleaved any other PMem modules within the socket ID.
+ - Create AppDirect capacity that is interleaved any other PMem modules within the socket ID.
type: bool
required: false
default: true
memorymode:
description:
- - Percentage of the total capacity to use in Memory Mode (V(0)-V(100)) within the socket ID.
+ - Percentage of the total capacity to use in Memory Mode (V(0)-V(100)) within the socket ID.
type: int
required: true
reserved:
@@ -86,86 +84,86 @@ options:
type: int
namespace:
description:
- - This enables to set the configuration for the namespace of the PMem.
+ - This enables to set the configuration for the namespace of the PMem.
type: list
elements: dict
suboptions:
mode:
description:
- - The mode of namespace. The detail of the mode is in the man page of ndctl-create-namespace.
+ - The mode of namespace. The detail of the mode is in the man page of ndctl-create-namespace.
type: str
required: true
choices: ['raw', 'sector', 'fsdax', 'devdax']
type:
description:
- - The type of namespace. The detail of the type is in the man page of ndctl-create-namespace.
+ - The type of namespace. The detail of the type is in the man page of ndctl-create-namespace.
type: str
required: false
choices: ['pmem', 'blk']
size:
description:
- - The size of namespace. This option supports the suffixes V(k) or V(K) or V(KB) for KiB,
- V(m) or V(M) or V(MB) for MiB, V(g) or V(G) or V(GB) for GiB and V(t) or V(T) or V(TB) for TiB.
+ - The size of namespace. This option supports the suffixes V(k) or V(K) or V(KB) for KiB, V(m) or V(M) or V(MB)
+ for MiB, V(g) or V(G) or V(GB) for GiB and V(t) or V(T) or V(TB) for TiB.
- This option is required if multiple namespaces are configured.
- If this option is not set, all of the available space of a region is configured.
type: str
required: false
namespace_append:
description:
- - Enable to append the new namespaces to the system.
- - The default is V(false) so the all existing namespaces not listed in O(namespace) are removed.
+ - Enable to append the new namespaces to the system.
+ - The default is V(false) so the all existing namespaces not listed in O(namespace) are removed.
type: bool
default: false
required: false
-'''
+"""
-RETURN = r'''
+RETURN = r"""
reboot_required:
- description: Indicates that the system reboot is required to complete the PMem configuration.
- returned: success
- type: bool
- sample: true
+ description: Indicates that the system reboot is required to complete the PMem configuration.
+ returned: success
+ type: bool
+ sample: true
result:
- description:
- - Shows the value of AppDirect, Memory Mode and Reserved size in bytes.
- - If O(socket) argument is provided, shows the values in each socket with C(socket) which contains the socket ID.
- - If O(namespace) argument is provided, shows the detail of each namespace.
- returned: success
- type: list
- elements: dict
- contains:
- appdirect:
- description: AppDirect size in bytes.
- type: int
- memorymode:
- description: Memory Mode size in bytes.
- type: int
- reserved:
- description: Reserved size in bytes.
- type: int
- socket:
- description: The socket ID to be configured.
- type: int
- namespace:
- description: The list of the detail of namespace.
- type: list
- sample: [
- {
- "appdirect": 111669149696,
- "memorymode": 970662608896,
- "reserved": 3626500096,
- "socket": 0
- },
- {
- "appdirect": 111669149696,
- "memorymode": 970662608896,
- "reserved": 3626500096,
- "socket": 1
- }
- ]
-'''
+ description:
+ - Shows the value of AppDirect, Memory Mode and Reserved size in bytes.
+ - If O(socket) argument is provided, shows the values in each socket with C(socket) which contains the socket ID.
+ - If O(namespace) argument is provided, shows the detail of each namespace.
+ returned: success
+ type: list
+ elements: dict
+ contains:
+ appdirect:
+ description: AppDirect size in bytes.
+ type: int
+ memorymode:
+ description: Memory Mode size in bytes.
+ type: int
+ reserved:
+ description: Reserved size in bytes.
+ type: int
+ socket:
+ description: The socket ID to be configured.
+ type: int
+ namespace:
+ description: The list of the detail of namespace.
+ type: list
+ sample: [
+ {
+ "appdirect": 111669149696,
+ "memorymode": 970662608896,
+ "reserved": 3626500096,
+ "socket": 0
+ },
+ {
+ "appdirect": 111669149696,
+ "memorymode": 970662608896,
+ "reserved": 3626500096,
+ "socket": 1
+ }
+ ]
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Configure the Pmem as AppDirect 10, Memory Mode 70, and the Reserved 20 percent.
community.general.pmem:
appdirect: 10
@@ -205,7 +203,7 @@ EXAMPLES = r'''
- size: 320MB
type: pmem
mode: sector
-'''
+"""
import json
import re
@@ -538,7 +536,7 @@ class PersistentMemory(object):
out = xmltodict.parse(goal, dict_constructor=dict)['ConfigGoalList']['ConfigGoal']
for entry in out:
- # Probably it's a bug of ipmctl to show the socket goal
+ # Probably it is a bug of ipmctl to show the socket goal
# which isn't specified by the -socket option.
# Anyway, filter the noise out here:
if skt and skt['id'] != int(entry['SocketID'], 16):
diff --git a/plugins/modules/pnpm.py b/plugins/modules/pnpm.py
index 315b07ba8e..c4dbf55dff 100644
--- a/plugins/modules/pnpm.py
+++ b/plugins/modules/pnpm.py
@@ -12,13 +12,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: pnpm
-short_description: Manage node.js packages with pnpm
+short_description: Manage Node.js packages with C(pnpm)
version_added: 7.4.0
description:
- - Manage node.js packages with the L(pnpm package manager, https://pnpm.io/).
+ - Manage Node.js packages with the L(pnpm package manager, https://pnpm.io/).
author:
- "Aritra Sen (@aretrosen)"
- "Chris Hoffman (@chrishoffman), creator of NPM Ansible module"
@@ -32,18 +31,18 @@ attributes:
options:
name:
description:
- - The name of a node.js library to install.
- - All packages in package.json are installed if not provided.
+ - The name of a Node.js library to install.
+ - All packages in C(package.json) are installed if not provided.
type: str
required: false
alias:
description:
- - Alias of the node.js library.
+ - Alias of the Node.js library.
type: str
required: false
path:
description:
- - The base path to install the node.js libraries.
+ - The base path to install the Node.js libraries.
type: path
required: false
version:
@@ -53,7 +52,7 @@ options:
required: false
global:
description:
- - Install the node.js library globally.
+ - Install the Node.js library globally.
required: false
default: false
type: bool
@@ -97,7 +96,7 @@ options:
type: bool
state:
description:
- - Installation state of the named node.js library.
+ - Installation state of the named Node.js library.
- If V(absent) is selected, a name option must be provided.
type: str
required: false
@@ -107,36 +106,36 @@ requirements:
- Pnpm executable present in E(PATH).
"""
-EXAMPLES = """
-- name: Install "tailwindcss" node.js package.
+EXAMPLES = r"""
+- name: Install "tailwindcss" Node.js package.
community.general.pnpm:
name: tailwindcss
path: /app/location
-- name: Install "tailwindcss" node.js package on version 3.3.2
+- name: Install "tailwindcss" Node.js package on version 3.3.2
community.general.pnpm:
name: tailwindcss
version: 3.3.2
path: /app/location
-- name: Install "tailwindcss" node.js package globally.
+- name: Install "tailwindcss" Node.js package globally.
community.general.pnpm:
name: tailwindcss
global: true
-- name: Install "tailwindcss" node.js package as dev dependency.
+- name: Install "tailwindcss" Node.js package as dev dependency.
community.general.pnpm:
name: tailwindcss
path: /app/location
dev: true
-- name: Install "tailwindcss" node.js package as optional dependency.
+- name: Install "tailwindcss" Node.js package as optional dependency.
community.general.pnpm:
name: tailwindcss
path: /app/location
optional: true
-- name: Install "tailwindcss" node.js package version 0.1.3 as tailwind-1
+- name: Install "tailwindcss" Node.js package version 0.1.3 as tailwind-1
community.general.pnpm:
name: tailwindcss
alias: tailwind-1
@@ -158,6 +157,7 @@ EXAMPLES = """
path: /app/location
state: latest
"""
+
import json
import os
diff --git a/plugins/modules/portage.py b/plugins/modules/portage.py
index 8ae8efb087..4a1cb1b990 100644
--- a/plugins/modules/portage.py
+++ b/plugins/modules/portage.py
@@ -14,13 +14,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: portage
short_description: Package manager for Gentoo
description:
- - Manages Gentoo packages
-
+ - Manages Gentoo packages.
extends_documentation_fragment:
- community.general.attributes
@@ -33,21 +31,21 @@ attributes:
options:
package:
description:
- - Package atom or set, for example V(sys-apps/foo) or V(>foo-2.13) or V(@world)
+ - Package atom or set, for example V(sys-apps/foo) or V(>foo-2.13) or V(@world).
aliases: [name]
type: list
elements: str
state:
description:
- - State of the package atom
+ - State of the package atom.
default: "present"
- choices: [ "present", "installed", "emerged", "absent", "removed", "unmerged", "latest" ]
+ choices: ["present", "installed", "emerged", "absent", "removed", "unmerged", "latest"]
type: str
update:
description:
- - Update packages to the best version available (--update)
+ - Update packages to the best version available (C(--update)).
type: bool
default: false
@@ -59,82 +57,81 @@ options:
deep:
description:
- - Consider the entire dependency tree of packages (--deep)
+ - Consider the entire dependency tree of packages (C(--deep)).
type: bool
default: false
newuse:
description:
- - Include installed packages where USE flags have changed (--newuse)
+ - Include installed packages where USE flags have changed (C(--newuse)).
type: bool
default: false
changed_use:
description:
- - Include installed packages where USE flags have changed, except when
- - flags that the user has not enabled are added or removed
- - (--changed-use)
+ - Include installed packages where USE flags have changed, except when.
+ - Flags that the user has not enabled are added or removed.
+ - (C(--changed-use)).
type: bool
default: false
oneshot:
description:
- - Do not add the packages to the world file (--oneshot)
+ - Do not add the packages to the world file (C(--oneshot)).
type: bool
default: false
noreplace:
description:
- - Do not re-emerge installed packages (--noreplace)
+ - Do not re-emerge installed packages (C(--noreplace)).
type: bool
default: true
nodeps:
description:
- - Only merge packages but not their dependencies (--nodeps)
+ - Only merge packages but not their dependencies (C(--nodeps)).
type: bool
default: false
onlydeps:
description:
- - Only merge packages' dependencies but not the packages (--onlydeps)
+ - Only merge packages' dependencies but not the packages (C(--onlydeps)).
type: bool
default: false
depclean:
description:
- - Remove packages not needed by explicitly merged packages (--depclean)
- - If no package is specified, clean up the world's dependencies
- - Otherwise, --depclean serves as a dependency aware version of --unmerge
+ - Remove packages not needed by explicitly merged packages (C(--depclean)).
+ - If no package is specified, clean up the world's dependencies.
+ - Otherwise, C(--depclean) serves as a dependency aware version of C(--unmerge).
type: bool
default: false
quiet:
description:
- - Run emerge in quiet mode (--quiet)
+ - Run emerge in quiet mode (C(--quiet)).
type: bool
default: false
verbose:
description:
- - Run emerge in verbose mode (--verbose)
+ - Run emerge in verbose mode (C(--verbose)).
type: bool
default: false
select:
description:
- If set to V(true), explicitely add the package to the world file.
- - Please note that this option is not used for idempotency, it is only used
- when actually installing a package.
+ - Please note that this option is not used for idempotency, it is only used when actually installing a package.
type: bool
version_added: 8.6.0
sync:
description:
- - Sync package repositories first
- - If V(yes), perform "emerge --sync"
- - If V(web), perform "emerge-webrsync"
- choices: [ "web", "yes", "no" ]
+ - Sync package repositories first.
+ - If V(yes), perform C(emerge --sync).
+ - If V(web), perform C(emerge-webrsync).
+ choices: ["web", "yes", "no"]
type: str
getbinpkgonly:
@@ -171,16 +168,14 @@ options:
jobs:
description:
- Specifies the number of packages to build simultaneously.
- - "Since version 2.6: Value of 0 or False resets any previously added"
- - --jobs setting values
+ - 'Since version 2.6: Value of V(0) or V(false) resets any previously added C(--jobs) setting values.'
type: int
loadavg:
description:
- - Specifies that no new builds should be started if there are
- - other builds running and the load average is at least LOAD
- - "Since version 2.6: Value of 0 or False resets any previously added"
- - --load-average setting values
+ - Specifies that no new builds should be started if there are other builds running and the load average is at least
+ LOAD.
+ - 'Since version 2.6: Value of 0 or False resets any previously added C(--load-average) setting values.'
type: float
withbdeps:
@@ -191,26 +186,24 @@ options:
quietbuild:
description:
- - Redirect all build output to logs alone, and do not display it
- - on stdout (--quiet-build)
+ - Redirect all build output to logs alone, and do not display it on stdout (C(--quiet-build)).
type: bool
default: false
quietfail:
description:
- - Suppresses display of the build log on stdout (--quiet-fail)
- - Only the die message and the path of the build log will be
- - displayed on stdout.
+ - Suppresses display of the build log on stdout (--quiet-fail).
+ - Only the die message and the path of the build log will be displayed on stdout.
type: bool
default: false
author:
- - "William L Thomson Jr (@wltjr)"
- - "Yap Sok Ann (@sayap)"
- - "Andrew Udvare (@Tatsh)"
-'''
+ - "William L Thomson Jr (@wltjr)"
+ - "Yap Sok Ann (@sayap)"
+ - "Andrew Udvare (@Tatsh)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Make sure package foo is installed
community.general.portage:
package: foo
@@ -252,7 +245,7 @@ EXAMPLES = '''
package: foo
state: absent
depclean: true
-'''
+"""
import os
import re
diff --git a/plugins/modules/portinstall.py b/plugins/modules/portinstall.py
index 59dafb1eb8..d4e1591d32 100644
--- a/plugins/modules/portinstall.py
+++ b/plugins/modules/portinstall.py
@@ -12,43 +12,42 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: portinstall
short_description: Installing packages from FreeBSD's ports system
description:
- - Manage packages for FreeBSD using 'portinstall'.
+ - Manage packages for FreeBSD using C(portinstall).
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- description:
- - name of package to install/remove
- aliases: [pkg]
- required: true
- type: str
- state:
- description:
- - state of the package
- choices: [ 'present', 'absent' ]
- required: false
- default: present
- type: str
- use_packages:
- description:
- - use packages instead of ports whenever available
- type: bool
- required: false
- default: true
+ name:
+ description:
+ - Name of package to install/remove.
+ aliases: [pkg]
+ required: true
+ type: str
+ state:
+ description:
+ - State of the package.
+ choices: ['present', 'absent']
+ required: false
+ default: present
+ type: str
+ use_packages:
+ description:
+ - Use packages instead of ports whenever available.
+ type: bool
+ required: false
+ default: true
author: "berenddeboer (@berenddeboer)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install package foo
community.general.portinstall:
name: foo
@@ -63,7 +62,7 @@ EXAMPLES = '''
community.general.portinstall:
name: foo,bar
state: absent
-'''
+"""
import re
diff --git a/plugins/modules/pritunl_org.py b/plugins/modules/pritunl_org.py
index 4945a8fc20..a96a68c72e 100644
--- a/plugins/modules/pritunl_org.py
+++ b/plugins/modules/pritunl_org.py
@@ -8,54 +8,48 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: pritunl_org
author: Florian Dambrine (@Lowess)
version_added: 2.5.0
short_description: Manages Pritunl Organizations using the Pritunl API
description:
- - A module to manage Pritunl organizations using the Pritunl API.
+ - A module to manage Pritunl organizations using the Pritunl API.
extends_documentation_fragment:
- - community.general.pritunl
- - community.general.attributes
+ - community.general.pritunl
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- type: str
- required: true
- aliases:
- - org
- description:
- - The name of the organization to manage in Pritunl.
-
- force:
- type: bool
- default: false
- description:
- - If O(force) is V(true) and O(state) is V(absent), the module
- will delete the organization, no matter if it contains users
- or not. By default O(force) is V(false), which will cause the
- module to fail the deletion of the organization when it contains
- users.
-
- state:
- type: str
- default: 'present'
- choices:
- - present
- - absent
- description:
- - If V(present), the module adds organization O(name) to
- Pritunl. If V(absent), attempt to delete the organization
- from Pritunl (please read about O(force) usage).
+ name:
+ type: str
+ required: true
+ aliases:
+ - org
+ description:
+ - The name of the organization to manage in Pritunl.
+ force:
+ type: bool
+ default: false
+ description:
+ - If O(force) is V(true) and O(state) is V(absent), the module will delete the organization, no matter if it contains
+ users or not. By default O(force) is V(false), which will cause the module to fail the deletion of the organization
+ when it contains users.
+ state:
+ type: str
+ default: 'present'
+ choices:
+ - present
+ - absent
+ description:
+ - If V(present), the module adds organization O(name) to Pritunl. If V(absent), attempt to delete the organization from
+ Pritunl (please read about O(force) usage).
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Ensure the organization named MyOrg exists
community.general.pritunl_org:
state: present
@@ -67,7 +61,7 @@ EXAMPLES = """
name: MyOrg
"""
-RETURN = """
+RETURN = r"""
response:
description: JSON representation of a Pritunl Organization.
returned: success
diff --git a/plugins/modules/pritunl_org_info.py b/plugins/modules/pritunl_org_info.py
index 979e29b5a0..dc198bc9cc 100644
--- a/plugins/modules/pritunl_org_info.py
+++ b/plugins/modules/pritunl_org_info.py
@@ -8,32 +8,29 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: pritunl_org_info
author: Florian Dambrine (@Lowess)
version_added: 2.5.0
short_description: List Pritunl Organizations using the Pritunl API
description:
- - A module to list Pritunl organizations using the Pritunl API.
+ - A module to list Pritunl organizations using the Pritunl API.
extends_documentation_fragment:
- - community.general.pritunl
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.pritunl
+ - community.general.attributes
+ - community.general.attributes.info_module
options:
- organization:
- type: str
- required: false
- aliases:
- - org
- default: null
- description:
- - Name of the Pritunl organization to search for.
- If none provided, the module will return all Pritunl
- organizations.
+ organization:
+ type: str
+ required: false
+ aliases:
+ - org
+ default: null
+ description:
+ - Name of the Pritunl organization to search for. If none provided, the module will return all Pritunl organizations.
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: List all existing Pritunl organizations
community.general.pritunl_org_info:
@@ -42,7 +39,7 @@ EXAMPLES = """
organization: MyOrg
"""
-RETURN = """
+RETURN = r"""
organizations:
description: List of Pritunl organizations.
returned: success
diff --git a/plugins/modules/pritunl_user.py b/plugins/modules/pritunl_user.py
index bdbc335d90..dd8721d1ba 100644
--- a/plugins/modules/pritunl_user.py
+++ b/plugins/modules/pritunl_user.py
@@ -8,97 +8,87 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: pritunl_user
author: "Florian Dambrine (@Lowess)"
version_added: 2.3.0
short_description: Manage Pritunl Users using the Pritunl API
description:
- - A module to manage Pritunl users using the Pritunl API.
+ - A module to manage Pritunl users using the Pritunl API.
extends_documentation_fragment:
- - community.general.pritunl
- - community.general.attributes
+ - community.general.pritunl
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- organization:
- type: str
- required: true
- aliases:
- - org
- description:
- - The name of the organization the user is part of.
-
- state:
- type: str
- default: 'present'
- choices:
- - present
- - absent
- description:
- - If V(present), the module adds user O(user_name) to
- the Pritunl O(organization). If V(absent), removes the user
- O(user_name) from the Pritunl O(organization).
-
- user_name:
- type: str
- required: true
- default: null
- description:
- - Name of the user to create or delete from Pritunl.
-
- user_email:
- type: str
- required: false
- default: null
- description:
- - Email address associated with the user O(user_name).
-
- user_type:
- type: str
- required: false
- default: client
- choices:
- - client
- - server
- description:
- - Type of the user O(user_name).
-
- user_groups:
- type: list
- elements: str
- required: false
- default: null
- description:
- - List of groups associated with the user O(user_name).
-
- user_disabled:
- type: bool
- required: false
- default: null
- description:
- - Enable/Disable the user O(user_name).
-
- user_gravatar:
- type: bool
- required: false
- default: null
- description:
- - Enable/Disable Gravatar usage for the user O(user_name).
-
- user_mac_addresses:
- type: list
- elements: str
- description:
- - Allowed MAC addresses for the user O(user_name).
- version_added: 5.0.0
+ organization:
+ type: str
+ required: true
+ aliases:
+ - org
+ description:
+ - The name of the organization the user is part of.
+ state:
+ type: str
+ default: 'present'
+ choices:
+ - present
+ - absent
+ description:
+ - If V(present), the module adds user O(user_name) to the Pritunl O(organization). If V(absent), removes the user O(user_name)
+ from the Pritunl O(organization).
+ user_name:
+ type: str
+ required: true
+ default:
+ description:
+ - Name of the user to create or delete from Pritunl.
+ user_email:
+ type: str
+ required: false
+ default:
+ description:
+ - Email address associated with the user O(user_name).
+ user_type:
+ type: str
+ required: false
+ default: client
+ choices:
+ - client
+ - server
+ description:
+ - Type of the user O(user_name).
+ user_groups:
+ type: list
+ elements: str
+ required: false
+ default:
+ description:
+ - List of groups associated with the user O(user_name).
+ user_disabled:
+ type: bool
+ required: false
+ default:
+ description:
+ - Enable/Disable the user O(user_name).
+ user_gravatar:
+ type: bool
+ required: false
+ default:
+ description:
+ - Enable/Disable Gravatar usage for the user O(user_name).
+ user_mac_addresses:
+ type: list
+ elements: str
+ description:
+ - Allowed MAC addresses for the user O(user_name).
+ version_added: 5.0.0
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create the user Foo with email address foo@bar.com in MyOrg
community.general.pritunl_user:
state: present
@@ -123,7 +113,7 @@ EXAMPLES = """
user_name: Foo
"""
-RETURN = """
+RETURN = r"""
response:
description: JSON representation of Pritunl Users.
returned: success
diff --git a/plugins/modules/pritunl_user_info.py b/plugins/modules/pritunl_user_info.py
index 3f8f62003f..02d8512315 100644
--- a/plugins/modules/pritunl_user_info.py
+++ b/plugins/modules/pritunl_user_info.py
@@ -8,45 +8,42 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: pritunl_user_info
author: "Florian Dambrine (@Lowess)"
version_added: 2.3.0
short_description: List Pritunl Users using the Pritunl API
description:
- - A module to list Pritunl users using the Pritunl API.
+ - A module to list Pritunl users using the Pritunl API.
extends_documentation_fragment:
- - community.general.pritunl
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.pritunl
+ - community.general.attributes
+ - community.general.attributes.info_module
options:
- organization:
- type: str
- required: true
- aliases:
- - org
- description:
- - The name of the organization the user is part of.
-
- user_name:
- type: str
- required: false
- description:
- - Name of the user to filter on Pritunl.
-
- user_type:
- type: str
- required: false
- default: client
- choices:
- - client
- - server
- description:
- - Type of the user O(user_name).
+ organization:
+ type: str
+ required: true
+ aliases:
+ - org
+ description:
+ - The name of the organization the user is part of.
+ user_name:
+ type: str
+ required: false
+ description:
+ - Name of the user to filter on Pritunl.
+ user_type:
+ type: str
+ required: false
+ default: client
+ choices:
+ - client
+ - server
+ description:
+ - Type of the user O(user_name).
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: List all existing users part of the organization MyOrg
community.general.pritunl_user_info:
state: list
@@ -59,7 +56,7 @@ EXAMPLES = """
user_name: Florian
"""
-RETURN = """
+RETURN = r"""
users:
description: List of Pritunl users.
returned: success
diff --git a/plugins/modules/profitbricks.py b/plugins/modules/profitbricks.py
index 875bd78c4e..e72144f759 100644
--- a/plugins/modules/profitbricks.py
+++ b/plugins/modules/profitbricks.py
@@ -8,13 +8,19 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: profitbricks
short_description: Create, destroy, start, stop, and reboot a ProfitBricks virtual machine
description:
- - Create, destroy, update, start, stop, and reboot a ProfitBricks virtual machine. When the virtual machine is created it can optionally wait
- for it to be 'running' before returning. This module has a dependency on profitbricks >= 1.0.0
+ - Create, destroy, update, start, stop, and reboot a ProfitBricks virtual machine. When the virtual machine is created it
+ can optionally wait for it to be 'running' before returning. This module has a dependency on profitbricks >= 1.0.0.
+deprecated:
+ removed_in: 11.0.0
+ why: Module relies on library unsupported since 2021.
+ alternative: >
+ Profitbricks has rebranded as Ionos Cloud and they provide a collection named ionoscloudsdk.ionoscloud.
+ Whilst it is likely it will provide the features of this module, that has not been verified.
+ Please refer to that collection's documentation for more details.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -34,7 +40,7 @@ options:
type: str
image:
description:
- - The system image ID for creating the virtual machine, e.g. a3eae284-a2fe-11e4-b187-5f1f641608c8.
+ - The system image ID for creating the virtual machine, for example V(a3eae284-a2fe-11e4-b187-5f1f641608c8).
type: str
image_password:
description:
@@ -65,7 +71,7 @@ options:
- The CPU family type to allocate to the virtual machine.
type: str
default: AMD_OPTERON
- choices: [ "AMD_OPTERON", "INTEL_XEON" ]
+ choices: ["AMD_OPTERON", "INTEL_XEON"]
volume_size:
description:
- The size in GB of the boot volume.
@@ -76,10 +82,10 @@ options:
- The bus type for the volume.
type: str
default: VIRTIO
- choices: [ "IDE", "VIRTIO"]
+ choices: ["IDE", "VIRTIO"]
instance_ids:
description:
- - list of instance ids, currently only used when state='absent' to remove instances.
+ - List of instance IDs, currently only used when state='absent' to remove instances.
type: list
elements: str
default: []
@@ -93,7 +99,7 @@ options:
- The datacenter location. Use only if you want to create the Datacenter or else this value is ignored.
type: str
default: us/las
- choices: [ "us/las", "de/fra", "de/fkb" ]
+ choices: ["us/las", "de/fra", "de/fkb"]
assign_public_ip:
description:
- This will assign the machine to the public LAN. If no LAN exists with public Internet access it is created.
@@ -106,47 +112,46 @@ options:
default: 1
subscription_user:
description:
- - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable.
+ - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable.
type: str
subscription_password:
description:
- - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable.
+ - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable.
type: str
wait:
description:
- - wait for the instance to be in state 'running' before returning
+ - Wait for the instance to be in state 'running' before returning.
type: bool
default: true
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
remove_boot_volume:
description:
- - remove the bootVolume of the virtual machine you're destroying.
+ - Remove the bootVolume of the virtual machine you are destroying.
type: bool
default: true
state:
description:
- - create or terminate instances
+ - Create or terminate instances.
- 'The choices available are: V(running), V(stopped), V(absent), V(present).'
type: str
default: 'present'
disk_type:
description:
- - the type of disk to be allocated.
+ - The type of disk to be allocated.
type: str
choices: [SSD, HDD]
default: HDD
requirements:
- - "profitbricks"
+ - "profitbricks"
author: Matt Baldwin (@baldwinSPC)
-'''
-
-EXAMPLES = '''
+"""
+EXAMPLES = r"""
# Note: These examples do not set authentication details, see the AWS Guide for details.
# Provisioning example
@@ -192,7 +197,7 @@ EXAMPLES = '''
- 'web003.stackpointcloud.com'
wait_timeout: 500
state: stopped
-'''
+"""
import re
import uuid
diff --git a/plugins/modules/profitbricks_datacenter.py b/plugins/modules/profitbricks_datacenter.py
index 4aa1fa5eeb..3f9561cb41 100644
--- a/plugins/modules/profitbricks_datacenter.py
+++ b/plugins/modules/profitbricks_datacenter.py
@@ -8,13 +8,20 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: profitbricks_datacenter
short_description: Create or destroy a ProfitBricks Virtual Datacenter
description:
- - This is a simple module that supports creating or removing vDCs. A vDC is required before you can create servers. This module has a dependency
- on profitbricks >= 1.0.0
+ - This is a simple module that supports creating or removing vDCs. A vDC is required before you can create servers. This
+ module has a dependency on profitbricks >= 1.0.0.
+deprecated:
+ removed_in: 11.0.0
+ why: Module relies on library unsupported since 2021.
+ alternative: >
+ Profitbricks has rebranded as Ionos Cloud and they provide a collection named ionoscloudsdk.ionoscloud.
+ Whilst it is likely it will provide the features of this module, that has not been verified.
+ Please refer to that collection's documentation for more details.
+
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -38,41 +45,41 @@ options:
type: str
required: false
default: us/las
- choices: [ "us/las", "de/fra", "de/fkb" ]
+ choices: ["us/las", "de/fra", "de/fkb"]
subscription_user:
description:
- - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable.
+ - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable.
type: str
required: false
subscription_password:
description:
- - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable.
+ - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable.
type: str
required: false
wait:
description:
- - wait for the datacenter to be created before returning
+ - Wait for the datacenter to be created before returning.
required: false
default: true
type: bool
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
state:
description:
- Create or terminate datacenters.
- - "The available choices are: V(present), V(absent)."
+ - 'The available choices are: V(present), V(absent).'
type: str
required: false
default: 'present'
-requirements: [ "profitbricks" ]
+requirements: ["profitbricks"]
author: Matt Baldwin (@baldwinSPC)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a datacenter
community.general.profitbricks_datacenter:
datacenter: Tardis One
@@ -83,7 +90,7 @@ EXAMPLES = '''
datacenter: Tardis One
wait_timeout: 500
state: absent
-'''
+"""
import re
import time
diff --git a/plugins/modules/profitbricks_nic.py b/plugins/modules/profitbricks_nic.py
index 9498be15dc..94d68677d6 100644
--- a/plugins/modules/profitbricks_nic.py
+++ b/plugins/modules/profitbricks_nic.py
@@ -8,12 +8,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: profitbricks_nic
short_description: Create or Remove a NIC
description:
- - This module allows you to create or restore a volume snapshot. This module has a dependency on profitbricks >= 1.0.0
+ - This module allows you to create or restore a volume snapshot. This module has a dependency on profitbricks >= 1.0.0.
+deprecated:
+ removed_in: 11.0.0
+ why: Module relies on library unsupported since 2021.
+ alternative: >
+ Profitbricks has rebranded as Ionos Cloud and they provide a collection named ionoscloudsdk.ionoscloud.
+ Whilst it is likely it will provide the features of this module, that has not been verified.
+ Please refer to that collection's documentation for more details.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -39,42 +45,42 @@ options:
type: str
lan:
description:
- - The LAN to place the NIC on. You can pass a LAN that doesn't exist and it will be created. Required on create.
+ - The LAN to place the NIC on. You can pass a LAN that does not exist and it will be created. Required on create.
type: str
subscription_user:
description:
- - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable.
+ - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable.
type: str
required: true
subscription_password:
description:
- - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable.
+ - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable.
type: str
required: true
wait:
description:
- - wait for the operation to complete before returning
+ - Wait for the operation to complete before returning.
required: false
default: true
type: bool
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
state:
description:
- - Indicate desired state of the resource
- - "The available choices are: V(present), V(absent)."
+ - Indicate desired state of the resource.
+ - 'The available choices are: V(present), V(absent).'
type: str
required: false
default: 'present'
-requirements: [ "profitbricks" ]
+requirements: ["profitbricks"]
author: Matt Baldwin (@baldwinSPC)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a NIC
community.general.profitbricks_nic:
datacenter: Tardis One
@@ -90,7 +96,7 @@ EXAMPLES = '''
name: 7341c2454f
wait_timeout: 500
state: absent
-'''
+"""
import re
import uuid
diff --git a/plugins/modules/profitbricks_volume.py b/plugins/modules/profitbricks_volume.py
index f623da7128..6f5b65cd00 100644
--- a/plugins/modules/profitbricks_volume.py
+++ b/plugins/modules/profitbricks_volume.py
@@ -8,12 +8,19 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: profitbricks_volume
short_description: Create or destroy a volume
description:
- - Allows you to create or remove a volume from a ProfitBricks datacenter. This module has a dependency on profitbricks >= 1.0.0
+ - Allows you to create or remove a volume from a ProfitBricks datacenter. This module has a dependency on profitbricks >=
+ 1.0.0.
+deprecated:
+ removed_in: 11.0.0
+ why: Module relies on library unsupported since 2021.
+ alternative: >
+ Profitbricks has rebranded as Ionos Cloud and they provide a collection named ionoscloudsdk.ionoscloud.
+ Whilst it is likely it will provide the features of this module, that has not been verified.
+ Please refer to that collection's documentation for more details.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -42,10 +49,11 @@ options:
type: str
required: false
default: VIRTIO
- choices: [ "IDE", "VIRTIO"]
+ choices: ["IDE", "VIRTIO"]
image:
description:
- - The system image ID for the volume, e.g. a3eae284-a2fe-11e4-b187-5f1f641608c8. This can also be a snapshot image ID.
+ - The system image ID for the volume, for example V(a3eae284-a2fe-11e4-b187-5f1f641608c8). This can also be a snapshot
+ image ID.
type: str
image_password:
description:
@@ -64,11 +72,11 @@ options:
type: str
required: false
default: HDD
- choices: [ "HDD", "SSD" ]
+ choices: ["HDD", "SSD"]
licence_type:
description:
- The licence type for the volume. This is used when the image is non-standard.
- - "The available choices are: V(LINUX), V(WINDOWS), V(UNKNOWN), V(OTHER)."
+ - 'The available choices are: V(LINUX), V(WINDOWS), V(UNKNOWN), V(OTHER).'
type: str
required: false
default: UNKNOWN
@@ -85,35 +93,35 @@ options:
type: bool
instance_ids:
description:
- - list of instance ids, currently only used when state='absent' to remove instances.
+ - List of instance IDs, currently only used when O(state=absent) to remove instances.
type: list
elements: str
default: []
subscription_user:
description:
- - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable.
+ - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable.
type: str
required: false
subscription_password:
description:
- - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable.
+ - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable.
type: str
required: false
wait:
description:
- - wait for the datacenter to be created before returning
+ - Wait for the datacenter to be created before returning.
required: false
default: true
type: bool
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
state:
description:
- - create or terminate datacenters
- - "The available choices are: V(present), V(absent)."
+ - Create or terminate datacenters.
+ - 'The available choices are: V(present), V(absent).'
type: str
required: false
default: 'present'
@@ -122,11 +130,11 @@ options:
- Server name to attach the volume to.
type: str
-requirements: [ "profitbricks" ]
+requirements: ["profitbricks"]
author: Matt Baldwin (@baldwinSPC)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create multiple volumes
community.general.profitbricks_volume:
datacenter: Tardis One
@@ -144,7 +152,7 @@ EXAMPLES = '''
- 'vol02'
wait_timeout: 500
state: absent
-'''
+"""
import re
import time
diff --git a/plugins/modules/profitbricks_volume_attachments.py b/plugins/modules/profitbricks_volume_attachments.py
index 76459515ee..8f7d2f1d53 100644
--- a/plugins/modules/profitbricks_volume_attachments.py
+++ b/plugins/modules/profitbricks_volume_attachments.py
@@ -8,12 +8,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: profitbricks_volume_attachments
short_description: Attach or detach a volume
description:
- - Allows you to attach or detach a volume from a ProfitBricks server. This module has a dependency on profitbricks >= 1.0.0
+ - Allows you to attach or detach a volume from a ProfitBricks server. This module has a dependency on profitbricks >= 1.0.0.
+deprecated:
+ removed_in: 11.0.0
+ why: Module relies on library unsupported since 2021.
+ alternative: >
+ Profitbricks has rebranded as Ionos Cloud and they provide a collection named ionoscloudsdk.ionoscloud.
+ Whilst it is likely it will provide the features of this module, that has not been verified.
+ Please refer to that collection's documentation for more details.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -36,38 +42,38 @@ options:
type: str
subscription_user:
description:
- - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable.
+ - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable.
type: str
required: false
subscription_password:
description:
- - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable.
+ - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable.
type: str
required: false
wait:
description:
- - wait for the operation to complete before returning
+ - Wait for the operation to complete before returning.
required: false
default: true
type: bool
wait_timeout:
description:
- - how long before wait gives up, in seconds
+ - How long before wait gives up, in seconds.
type: int
default: 600
state:
description:
- - Indicate desired state of the resource
- - "The available choices are: V(present), V(absent)."
+ - Indicate desired state of the resource.
+ - 'The available choices are: V(present), V(absent).'
type: str
required: false
default: 'present'
-requirements: [ "profitbricks" ]
+requirements: ["profitbricks"]
author: Matt Baldwin (@baldwinSPC)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Attach a volume
community.general.profitbricks_volume_attachments:
datacenter: Tardis One
@@ -83,7 +89,7 @@ EXAMPLES = '''
volume: vol01
wait_timeout: 500
state: absent
-'''
+"""
import re
import time
diff --git a/plugins/modules/proxmox.py b/plugins/modules/proxmox.py
index 52d5a849f3..035de02521 100644
--- a/plugins/modules/proxmox.py
+++ b/plugins/modules/proxmox.py
@@ -6,10 +6,10 @@
# SPDX-License-Identifier: GPL-3.0-or-later
from __future__ import absolute_import, division, print_function
+
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: proxmox
short_description: Management of instances in Proxmox VE cluster
description:
@@ -26,30 +26,31 @@ attributes:
options:
password:
description:
- - the instance root password
+ - The instance root password.
type: str
hostname:
description:
- - the instance hostname
- - required only for O(state=present)
- - must be unique if vmid is not passed
+ - The instance hostname.
+ - Required only for O(state=present).
+ - Must be unique if vmid is not passed.
type: str
ostemplate:
description:
- - the template for VM creating
- - required only for O(state=present)
+ - The template for VM creating.
+ - Required only for O(state=present).
type: str
disk:
description:
- - This option was previously described as "hard disk size in GB for instance" however several formats describing
- a lxc mount are permitted.
- - Older versions of Proxmox will accept a numeric value for size using the O(storage) parameter to automatically
- choose which storage to allocate from, however new versions enforce the C(:) syntax.
- - "Additional options are available by using some combination of the following key-value pairs as a
- comma-delimited list C([volume=] [,acl=<1|0>] [,mountoptions=] [,quota=<1|0>]
- [,replicate=<1|0>] [,ro=<1|0>] [,shared=<1|0>] [,size=])."
+ - This option was previously described as "hard disk size in GB for instance" however several formats describing a lxc
+ mount are permitted.
+ - Older versions of Proxmox will accept a numeric value for size using the O(storage) parameter to automatically choose
+ which storage to allocate from, however new versions enforce the C(:) syntax.
+ - Additional options are available by using some combination of the following key-value pairs as a comma-delimited list
+ C([volume=]
+ [,acl=<1|0>] [,mountoptions=] [,replicate=<1|0>] [,ro=<1|0>] [,shared=<1|0>]
+ [,size=]).
- See U(https://pve.proxmox.com/wiki/Linux_Container) for a full description.
- - This option is mutually exclusive with O(storage) and O(disk_volume).
+ - This option is mutually exclusive with O(disk_volume).
type: str
disk_volume:
description:
@@ -69,13 +70,13 @@ options:
- O(disk_volume.volume) is the name of an existing volume.
- If not defined, the module will check if one exists. If not, a new volume will be created.
- If defined, the volume must exist under that name.
- - Required only if O(disk_volume.storage) is defined and mutually exclusive with O(disk_volume.host_path).
+ - Required only if O(disk_volume.storage) is defined, and mutually exclusive with O(disk_volume.host_path).
type: str
size:
description:
- O(disk_volume.size) is the size of the storage to use.
- - The size is given in GB.
- - Required only if O(disk_volume.storage) is defined and mutually exclusive with O(disk_volume.host_path).
+ - The size is given in GiB.
+ - Required only if O(disk_volume.storage) is defined, and mutually exclusive with O(disk_volume.host_path).
type: int
host_path:
description:
@@ -93,19 +94,19 @@ options:
type: int
cpus:
description:
- - numbers of allocated cpus for instance
+ - Number of allocated cpus for instance.
type: int
memory:
description:
- - memory size in MB for instance
+ - Memory size in MB for instance.
type: int
swap:
description:
- - swap memory size in MB for instance
+ - Swap memory size in MB for instance.
type: int
netif:
description:
- - specifies network interfaces for the container. As a hash/dictionary defining interfaces.
+ - Specifies network interfaces for the container. As a hash/dictionary defining interfaces.
type: dict
features:
description:
@@ -117,7 +118,8 @@ options:
startup:
description:
- Specifies the startup order of the container.
- - Use C(order=#) where C(#) is a non-negative number to define the general startup order. Shutdown in done with reverse ordering.
+ - Use C(order=#) where C(#) is a non-negative number to define the general startup order. Shutdown in done with reverse
+ ordering.
- Use C(up=#) where C(#) is in seconds, to specify a delay to wait before the next VM is started.
- Use C(down=#) where C(#) is in seconds, to specify a delay to wait before the next VM is stopped.
type: list
@@ -157,7 +159,7 @@ options:
size:
description:
- O(mount_volumes[].size) is the size of the storage to use.
- - The size is given in GB.
+ - The size is given in GiB.
- Required only if O(mount_volumes[].storage) is defined and mutually exclusive with O(mount_volumes[].host_path).
type: int
host_path:
@@ -177,37 +179,38 @@ options:
type: dict
ip_address:
description:
- - specifies the address the container will be assigned
+ - Specifies the address the container will be assigned.
type: str
onboot:
description:
- - specifies whether a VM will be started during system bootup
+ - Specifies whether a VM will be started during system bootup.
type: bool
storage:
description:
- Target storage.
- - This Option is mutually exclusive with O(disk) and O(disk_volume).
+ - This option is mutually exclusive with O(disk_volume) and O(mount_volumes).
type: str
default: 'local'
ostype:
description:
- Specifies the C(ostype) of the LXC container.
- If set to V(auto), no C(ostype) will be provided on instance creation.
- choices: ['auto', 'debian', 'devuan', 'ubuntu', 'centos', 'fedora', 'opensuse', 'archlinux', 'alpine', 'gentoo', 'nixos', 'unmanaged']
+ choices: ['auto', 'debian', 'devuan', 'ubuntu', 'centos', 'fedora', 'opensuse', 'archlinux', 'alpine', 'gentoo', 'nixos',
+ 'unmanaged']
type: str
default: 'auto'
version_added: 8.1.0
cpuunits:
description:
- - CPU weight for a VM
+ - CPU weight for a VM.
type: int
nameserver:
description:
- - sets DNS server IP address for a container
+ - Sets DNS server IP address for a container.
type: str
searchdomain:
description:
- - sets DNS search domain for a container
+ - Sets DNS search domain for a container.
type: str
tags:
description:
@@ -219,21 +222,22 @@ options:
version_added: 6.2.0
timeout:
description:
- - timeout for operations
+ - Timeout for operations.
type: int
default: 30
update:
description:
- If V(true), the container will be updated with new values.
+ - The current default value of V(false) is deprecated and should will change to V(true) in community.general 11.0.0.
+ Please set O(update) explicitly to V(false) or V(true) to avoid surprises and get rid of the deprecation warning.
type: bool
- default: false
version_added: 8.1.0
force:
description:
- Forcing operations.
- Can be used only with states V(present), V(stopped), V(restarted).
- - with O(state=present) force option allow to overwrite existing container.
- - with states V(stopped), V(restarted) allow to force stop instance.
+ - With O(state=present) force option allow to overwrite existing container.
+ - With states V(stopped), V(restarted) allow to force stop instance.
type: bool
default: false
purge:
@@ -247,14 +251,14 @@ options:
version_added: 2.3.0
state:
description:
- - Indicate desired state of the instance
- - V(template) was added in community.general 8.1.0.
+ - Indicate desired state of the instance.
+ - V(template) was added in community.general 8.1.0.
type: str
choices: ['present', 'started', 'absent', 'stopped', 'restarted', 'template']
default: present
pubkey:
description:
- - Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions
+ - Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions.
type: str
unprivileged:
description:
@@ -306,9 +310,9 @@ extends_documentation_fragment:
- community.general.proxmox.documentation
- community.general.proxmox.selection
- community.general.attributes
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create new container with minimal options
community.general.proxmox:
vmid: 100
@@ -494,8 +498,8 @@ EXAMPLES = r'''
hostname: example.org
ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
features:
- - nesting=1
- - mount=cifs,nfs
+ - nesting=1
+ - mount=cifs,nfs
- name: >
Create a linked clone of the template container with id 100. The newly created container with be a
@@ -599,402 +603,30 @@ EXAMPLES = r'''
api_password: 1q2w3e
api_host: node1
state: absent
-'''
+"""
import re
import time
-from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
-
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native
-
-
from ansible_collections.community.general.plugins.module_utils.proxmox import (
- ansible_to_proxmox_bool, proxmox_auth_argument_spec, ProxmoxAnsible)
-
-VZ_TYPE = None
+ ProxmoxAnsible,
+ ansible_to_proxmox_bool,
+ proxmox_auth_argument_spec,
+)
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
-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.get('template', False)
-
- def update_config(self, vmid, node, disk, cpus, memory, swap, **kwargs):
- if VZ_TYPE != "lxc":
- self.module.fail_json(
- changed=False,
- msg="Updating configuration is only supported for LXC enabled proxmox clusters.",
- )
-
- def parse_disk_string(disk_string):
- # Example strings:
- # "acl=0,thin1:base-100-disk-1,size=8G"
- # "thin1:10,backup=0"
- # "local:20"
- # "volume=local-lvm:base-100-disk-1,size=20G"
- # "/mnt/bindmounts/shared,mp=/shared"
- # "volume=/dev/USB01,mp=/mnt/usb01"
- args = disk_string.split(",")
- # If the volume is not explicitly defined but implicit by only passing a key,
- # add the "volume=" key prefix for ease of parsing.
- args = ["volume=" + arg if "=" not in arg else arg for arg in args]
- # Then create a dictionary from the arguments
- disk_kwargs = dict(map(lambda item: item.split("="), args))
-
- VOLUME_PATTERN = r"""(?x)
- (?:(?P[\w\-.]+):
- (?:(?P\d+)|
- (?P[^,\s]+))
- )|
- (?P[^,\s]+)
- """
- # DISCLAIMER:
- # There are two things called a "volume":
- # 1. The "volume" key which describes the storage volume, device or directory to mount into the container.
- # 2. The storage volume of a storage-backed mount point in the PVE storage sub system.
- # In this section, we parse the "volume" key and check which type of mount point we are dealing with.
- pattern = re.compile(VOLUME_PATTERN)
- match_dict = pattern.match(disk_kwargs.pop("volume")).groupdict()
- match_dict = {k: v for k, v in match_dict.items() if v is not None}
-
- if "storage" in match_dict and "volume" in match_dict:
- disk_kwargs["storage"] = match_dict["storage"]
- disk_kwargs["volume"] = match_dict["volume"]
- elif "storage" in match_dict and "size" in match_dict:
- disk_kwargs["storage"] = match_dict["storage"]
- disk_kwargs["size"] = match_dict["size"]
- elif "host_path" in match_dict:
- disk_kwargs["host_path"] = match_dict["host_path"]
-
- # Pattern matching only available in Python 3.10+
- # match match_dict:
- # case {"storage": storage, "volume": volume}:
- # disk_kwargs["storage"] = storage
- # disk_kwargs["volume"] = volume
-
- # case {"storage": storage, "size": size}:
- # disk_kwargs["storage"] = storage
- # disk_kwargs["size"] = size
-
- # case {"host_path": host_path}:
- # disk_kwargs["host_path"] = host_path
-
- return disk_kwargs
-
- def convert_mounts(mount_dict):
- return_list = []
- for mount_key, mount_value in mount_dict.items():
- mount_config = parse_disk_string(mount_value)
- return_list.append(dict(id=mount_key, **mount_config))
-
- return return_list
-
- def build_volume(
- key,
- storage=None,
- volume=None,
- host_path=None,
- size=None,
- mountpoint=None,
- options=None,
- **kwargs
- ):
- if size is not None and isinstance(size, str):
- size = size.strip("G")
- # 1. Handle volume checks/creation
- # 1.1 Check if defined volume exists
- if volume is not None:
- storage_content = self.get_storage_content(node, storage, vmid=vmid)
- vol_ids = [vol["volid"] for vol in storage_content]
- volid = "{storage}:{volume}".format(storage=storage, volume=volume)
- if volid not in vol_ids:
- self.module.fail_json(
- changed=False,
- msg="Storage {storage} does not contain volume {volume}".format(
- storage=storage,
- volume=volume,
- ),
- )
- vol_string = "{storage}:{volume},size={size}G".format(
- storage=storage, volume=volume, size=size
- )
- # 1.2 If volume not defined (but storage is), check if it exists
- elif storage is not None:
- api_node = self.proxmox_api.nodes(
- node
- ) # The node must exist, but not the LXC
- try:
- vol = api_node.lxc(vmid).get("config").get(key)
- volume = parse_disk_string(vol).get("volume")
- vol_string = "{storage}:{volume},size={size}G".format(
- storage=storage, volume=volume, size=size
- )
-
- # If not, we have proxmox create one using the special syntax
- except Exception:
- vol_string = "{storage}:{size}".format(storage=storage, size=size)
- else:
- raise AssertionError('Internal error')
-
- # 1.3 If we have a host_path, we don't have storage, a volume, or a size
- vol_string = ",".join(
- [vol_string] +
- ([] if host_path is None else [host_path]) +
- ([] if mountpoint is None else ["mp={0}".format(mountpoint)]) +
- ([] if options is None else ["{0}={1}".format(k, v) for k, v in options.items()]) +
- ([] if not kwargs else ["{0}={1}".format(k, v) for k, v in kwargs.items()])
- )
-
- return {key: vol_string}
-
- # Version limited features
- minimum_version = {"tags": "6.1", "timezone": "6.3"}
- proxmox_node = self.proxmox_api.nodes(node)
-
- pve_version = self.version()
-
- # Fail on unsupported features
- for option, version in minimum_version.items():
- if pve_version < LooseVersion(version) and option in kwargs:
- self.module.fail_json(
- changed=False,
- msg="Feature {option} is only supported in PVE {version}+, and you're using PVE {pve_version}".format(
- option=option, version=version, pve_version=pve_version
- ),
- )
-
- # Remove all empty kwarg entries
- kwargs = {key: val for key, val in kwargs.items() if val is not None}
-
- if cpus is not None:
- kwargs["cpulimit"] = cpus
- if disk is not None:
- kwargs["disk_volume"] = parse_disk_string(disk)
- if "disk_volume" in kwargs:
- disk_dict = build_volume(key="rootfs", **kwargs.pop("disk_volume"))
- kwargs.update(disk_dict)
- if memory is not None:
- kwargs["memory"] = memory
- if swap is not None:
- kwargs["swap"] = swap
- if "netif" in kwargs:
- kwargs.update(kwargs.pop("netif"))
- if "mounts" in kwargs:
- kwargs["mount_volumes"] = convert_mounts(kwargs.pop("mounts"))
- if "mount_volumes" in kwargs:
- mounts_list = kwargs.pop("mount_volumes")
- for mount_config in mounts_list:
- key = mount_config.pop("id")
- mount_dict = build_volume(key=key, **mount_config)
- kwargs.update(mount_dict)
- # LXC tags are expected to be valid and presented as a comma/semi-colon delimited string
- if "tags" in kwargs:
- re_tag = re.compile(r"^[a-z0-9_][a-z0-9_\-\+\.]*$")
- for tag in kwargs["tags"]:
- if not re_tag.match(tag):
- self.module.fail_json(msg="%s is not a valid tag" % tag)
- kwargs["tags"] = ",".join(kwargs["tags"])
-
- # fetch the current config
- current_config = getattr(proxmox_node, VZ_TYPE)(vmid).config.get()
-
- # compare the requested config against the current
- update_config = False
- for (arg, value) in kwargs.items():
- # if the arg isn't in the current config, it needs to be updated
- if arg not in current_config:
- update_config = True
- break
- # some values are lists, the order isn't always the same, so split them and compare by key
- if isinstance(value, str):
- current_values = current_config[arg].split(",")
- requested_values = value.split(",")
- for new_value in requested_values:
- if new_value not in current_values:
- update_config = True
- break
- # if it's not a list (or string) just compare the current value
- else:
- # some types don't match with the API, so forcing to string for comparison
- if str(value) != str(current_config[arg]):
- update_config = True
- break
-
- if update_config:
- getattr(proxmox_node, VZ_TYPE)(vmid).config.put(vmid=vmid, node=node, **kwargs)
- else:
- self.module.exit_json(changed=False, msg="Container config is already up to date")
-
- def create_instance(self, vmid, node, disk, storage, cpus, memory, swap, timeout, clone, **kwargs):
-
- # Version limited features
- minimum_version = {
- 'tags': '6.1',
- 'timezone': '6.3'
- }
- proxmox_node = self.proxmox_api.nodes(node)
-
- # Remove all empty kwarg entries
- kwargs = {k: v for k, v in kwargs.items() if v is not None}
-
- pve_version = self.version()
-
- # Fail on unsupported features
- for option, version in minimum_version.items():
- if pve_version < LooseVersion(version) and option in kwargs:
- self.module.fail_json(changed=False, msg="Feature {option} is only supported in PVE {version}+, and you're using PVE {pve_version}".
- format(option=option, version=version, pve_version=pve_version))
-
- 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:
- kwargs['cpus'] = cpus
- kwargs['disk'] = disk
-
- # LXC tags are expected to be valid and presented as a comma/semi-colon delimited string
- if 'tags' in kwargs:
- re_tag = re.compile(r'^[a-z0-9_][a-z0-9_\-\+\.]*$')
- for tag in kwargs['tags']:
- if not re_tag.match(tag):
- self.module.fail_json(msg='%s is not a valid tag' % tag)
- kwargs['tags'] = ",".join(kwargs['tags'])
-
- if kwargs.get('ostype') == 'auto':
- kwargs.pop('ostype')
-
- 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.")
-
- clone_is_template = self.is_template_container(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 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.")
-
- 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')
-
- 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]
-
- 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)
-
- while timeout:
- if self.api_task_ok(node, taskid):
- return True
- timeout -= 1
- if timeout == 0:
- self.module.fail_json(vmid=vmid, node=node, 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 start_instance(self, vm, vmid, timeout):
- taskid = getattr(self.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.start.post()
- while timeout:
- if self.api_task_ok(vm['node'], taskid):
- return True
- timeout -= 1
- if timeout == 0:
- self.module.fail_json(vmid=vmid, taskid=taskid, 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
-
- 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.api_task_ok(vm['node'], taskid):
- return True
- timeout -= 1
- if timeout == 0:
- self.module.fail_json(vmid=vmid, taskid=taskid, 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 convert_to_template(self, vm, vmid, timeout, force):
- if getattr(self.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'running' and force:
- self.stop_instance(vm, vmid, timeout, force)
- # not sure why, but templating a container doesn't return a taskid
- getattr(self.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).template.post()
- return True
-
- 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.api_task_ok(vm['node'], taskid):
- return True
- timeout -= 1
- if timeout == 0:
- self.module.fail_json(vmid=vmid, taskid=taskid, 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),
+def get_proxmox_args():
+ return dict(
+ vmid=dict(type="int", required=False),
node=dict(),
pool=dict(),
password=dict(no_log=True),
hostname=dict(),
ostemplate=dict(),
- disk=dict(type='str'),
+ disk=dict(type="str"),
disk_volume=dict(
type="dict",
options=dict(
@@ -1014,12 +646,12 @@ def main():
("host_path", "size"),
],
),
- cores=dict(type='int'),
- cpus=dict(type='int'),
- memory=dict(type='int'),
- swap=dict(type='int'),
- netif=dict(type='dict'),
- mounts=dict(type='dict'),
+ cores=dict(type="int"),
+ cpus=dict(type="int"),
+ memory=dict(type="int"),
+ swap=dict(type="int"),
+ netif=dict(type="dict"),
+ mounts=dict(type="dict"),
mount_volumes=dict(
type="list",
elements="dict",
@@ -1043,282 +675,1064 @@ def main():
],
),
ip_address=dict(),
- ostype=dict(default='auto', choices=[
- 'auto', 'debian', 'devuan', 'ubuntu', 'centos', 'fedora', 'opensuse', 'archlinux', 'alpine', 'gentoo', 'nixos', 'unmanaged'
- ]),
- onboot=dict(type='bool'),
- features=dict(type='list', elements='str'),
- startup=dict(type='list', elements='str'),
- storage=dict(default='local'),
- cpuunits=dict(type='int'),
+ ostype=dict(
+ default="auto",
+ choices=[
+ "auto",
+ "debian",
+ "devuan",
+ "ubuntu",
+ "centos",
+ "fedora",
+ "opensuse",
+ "archlinux",
+ "alpine",
+ "gentoo",
+ "nixos",
+ "unmanaged",
+ ],
+ ),
+ onboot=dict(type="bool"),
+ features=dict(type="list", elements="str"),
+ startup=dict(type="list", elements="str"),
+ storage=dict(default="local"),
+ cpuunits=dict(type="int"),
nameserver=dict(),
searchdomain=dict(),
- timeout=dict(type='int', default=30),
- update=dict(type='bool', default=False),
- force=dict(type='bool', default=False),
- purge=dict(type='bool', default=False),
- state=dict(default='present', choices=['present', 'absent', 'stopped', 'started', 'restarted', 'template']),
- pubkey=dict(type='str'),
- unprivileged=dict(type='bool', default=True),
- description=dict(type='str'),
- hookscript=dict(type='str'),
- timezone=dict(type='str'),
- clone=dict(type='int'),
- clone_type=dict(default='opportunistic', choices=['full', 'linked', 'opportunistic']),
- tags=dict(type='list', elements='str')
+ timeout=dict(type="int", default=30),
+ update=dict(type="bool"),
+ force=dict(type="bool", default=False),
+ purge=dict(type="bool", default=False),
+ state=dict(
+ default="present",
+ choices=[
+ "present",
+ "absent",
+ "stopped",
+ "started",
+ "restarted",
+ "template",
+ ],
+ ),
+ pubkey=dict(type="str"),
+ unprivileged=dict(type="bool", default=True),
+ description=dict(type="str"),
+ hookscript=dict(type="str"),
+ timezone=dict(type="str"),
+ clone=dict(type="int"),
+ clone_type=dict(
+ default="opportunistic", choices=["full", "linked", "opportunistic"]
+ ),
+ tags=dict(type="list", elements="str"),
)
- module_args.update(proxmox_args)
- module = AnsibleModule(
+
+def get_ansible_module():
+ module_args = proxmox_auth_argument_spec()
+ module_args.update(get_proxmox_args())
+
+ return AnsibleModule(
argument_spec=module_args,
required_if=[
- ('state', 'present', ['node', 'hostname']),
- # Require one of clone, ostemplate, or update. Together with mutually_exclusive this ensures that we
- # either clone a container or create a new one from a template file.
- ('state', 'present', ('clone', 'ostemplate', 'update'), True),
+ ("state", "present", ["node", "hostname"]),
+ # Require one of clone, ostemplate, or update.
+ # Together with mutually_exclusive this ensures that we either
+ # clone a container or create a new one from a template file.
+ ("state", "present", ("clone", "ostemplate", "update"), True),
],
required_together=[("api_token_id", "api_token_secret")],
- required_one_of=[("api_password", "api_token_id")],
+ required_one_of=[
+ ("api_password", "api_token_id"),
+ ("vmid", "hostname"),
+ ],
mutually_exclusive=[
- (
- "clone",
- "ostemplate",
- "update",
- ), # Creating a new container is done either by cloning an existing one, or based on a template.
- ("disk", "disk_volume", "storage"),
+ # Creating a new container is done either by cloning an existing one, or based on a template.
+ ("clone", "ostemplate", "update"),
+ ("disk", "disk_volume"),
+ ("storage", "disk_volume"),
("mounts", "mount_volumes"),
],
)
+
+class ProxmoxLxcAnsible(ProxmoxAnsible):
+ MINIMUM_VERSIONS = {
+ "disk_volume": "5.0",
+ "mount_volumes": "5.0",
+ "tags": "6.1",
+ "timezone": "6.3",
+ }
+
+ def __init__(self, module):
+ super(ProxmoxLxcAnsible, self).__init__(module)
+
+ self.VZ_TYPE = "openvz" if self.version() < LooseVersion("4.0") else "lxc"
+ self.params = self.module.params
+
+ def run(self):
+ self.check_supported_features()
+
+ state = self.params.get("state")
+
+ vmid = self.params.get("vmid")
+ hostname = self.params.get("hostname")
+
+ if not vmid and not hostname:
+ self.module.fail_json(msg="Either VMID or hostname must be provided.")
+
+ if state == "present":
+ self.lxc_present(
+ vmid,
+ hostname,
+ node=self.params.get("node"),
+ update=self.params.get("update"),
+ force=self.params.get("force"),
+ )
+ elif state == "absent":
+ self.lxc_absent(
+ vmid,
+ hostname,
+ node=self.params.get("node"),
+ timeout=self.params.get("timeout"),
+ purge=self.params.get("purge"),
+ )
+ elif state == "started":
+ self.lxc_started(
+ vmid,
+ hostname,
+ node=self.params.get("node"),
+ timeout=self.params.get("timeout"),
+ )
+ elif state == "stopped":
+ self.lxc_stopped(
+ vmid,
+ hostname,
+ node=self.params.get("node"),
+ timeout=self.params.get("timeout"),
+ force=self.params.get("force"),
+ )
+ elif state == "restarted":
+ self.lxc_restarted(
+ vmid,
+ hostname,
+ node=self.params.get("node"),
+ timeout=self.params.get("timeout"),
+ force=self.params.get("force"),
+ )
+ elif state == "template":
+ self.lxc_to_template(
+ vmid,
+ hostname,
+ node=self.params.get("node"),
+ timeout=self.params.get("timeout"),
+ force=self.params.get("force"),
+ )
+
+ def lxc_present(self, vmid, hostname, node, update, force):
+ try:
+ lxc = self.get_lxc_resource(vmid, hostname)
+ vmid = vmid or lxc["id"].split("/")[-1]
+ node = node or lxc["node"]
+ except LookupError:
+ lxc = None
+ vmid = vmid or self.get_nextvmid()
+
+ if node is None:
+ raise ValueError(
+ "Argument 'node' is None, but should be found from VMID/hostname or provided."
+ )
+
+ # check if the container exists already
+ if lxc is not None:
+ if update is None:
+ # TODO: Remove deprecation warning in version 11.0.0
+ self.module.deprecate(
+ msg="The default value of false for 'update' has been deprecated and will be changed to true in version 11.0.0.",
+ version="11.0.0",
+ collection_name="community.general",
+ )
+ update = False
+
+ if update:
+ # Update it if we should
+ identifier = self.format_vm_identifier(vmid, hostname)
+ self.update_lxc_instance(
+ vmid,
+ node,
+ cores=self.params.get("cores"),
+ cpus=self.params.get("cpus"),
+ cpuunits=self.params.get("cpuunits"),
+ description=self.params.get("description"),
+ disk=self.params.get("disk"),
+ disk_volume=self.params.get("disk_volume"),
+ features=self.params.get("features"),
+ hookscript=self.params.get("hookscript"),
+ hostname=self.params.get("hostname"),
+ ip_address=self.params.get("ip_address"),
+ memory=self.params.get("memory"),
+ mounts=self.params.get("mounts"),
+ mount_volumes=self.params.get("mount_volumes"),
+ nameserver=self.params.get("nameserver"),
+ netif=self.params.get("netif"),
+ onboot=ansible_to_proxmox_bool(self.params.get("onboot")),
+ searchdomain=self.params.get("searchdomain"),
+ startup=self.params.get("startup"),
+ swap=self.params.get("swap"),
+ tags=self.params.get("tags"),
+ timezone=self.params.get("timezone"),
+ )
+ self.module.exit_json(
+ changed=True, vmid=vmid, msg="VM %s has been updated." % identifier
+ )
+ elif not force:
+ # We're done if it shouldn't be forcefully created
+ identifier = self.format_vm_identifier(vmid, lxc["name"])
+ self.module.exit_json(
+ changed=False, vmid=vmid, msg="VM %s already exists." % identifier
+ )
+ self.module.debug(
+ "VM %s already exists, but we don't update and instead forcefully recreate it."
+ % identifier
+ )
+
+ self.new_lxc_instance(
+ vmid,
+ hostname,
+ node=self.params.get("node"),
+ clone_from=self.params.get("clone"),
+ ostemplate=self.params.get("ostemplate"),
+ force=force,
+ )
+
+ def lxc_absent(self, vmid, hostname, node, timeout, purge):
+ try:
+ lxc = self.get_lxc_resource(vmid, hostname)
+ except LookupError:
+ identifier = self.format_vm_identifier(vmid, hostname)
+ self.module.exit_json(
+ changed=False, vmid=vmid, msg="VM %s is already absent." % (identifier)
+ )
+
+ vmid = vmid or lxc["id"].split("/")[-1]
+ node = node or lxc["node"]
+
+ lxc_status = self.get_lxc_status(vmid, node)
+ identifier = self.format_vm_identifier(vmid, hostname)
+
+ if lxc_status == "running":
+ self.module.exit_json(
+ changed=False,
+ vmid=vmid,
+ msg="VM %s is running. Stop it before deletion." % identifier,
+ )
+ if lxc_status == "mounted":
+ self.module.exit_json(
+ changed=False,
+ vmid=vmid,
+ msg="VM %s is mounted. Stop it with force option before deletion."
+ % identifier,
+ )
+
+ self.remove_lxc_instance(vmid, node, timeout, purge)
+ self.module.exit_json(
+ changed=True, vmid=vmid, msg="VM %s removed." % identifier
+ )
+
+ def lxc_started(self, vmid, hostname, node, timeout):
+ lxc = self.get_lxc_resource(vmid, hostname)
+ vmid = vmid or lxc["id"].split("/")[-1]
+ hostname = hostname or lxc["name"]
+ identifier = self.format_vm_identifier(vmid, hostname)
+ node = node or lxc["node"]
+ lxc_status = self.get_lxc_status(vmid, lxc["node"])
+
+ if lxc_status == "running":
+ self.module.exit_json(
+ changed=False, vmid=vmid, msg="VM %s is already running." % identifier
+ )
+
+ self.start_lxc_instance(vmid, node, timeout)
+ self.module.exit_json(
+ changed=True, vmid=vmid, msg="VM %s started." % identifier
+ )
+
+ def lxc_stopped(self, vmid, hostname, node, timeout, force):
+ lxc = self.get_lxc_resource(vmid, hostname)
+ vmid = vmid or lxc["id"].split("/")[-1]
+ hostname = hostname or lxc["name"]
+ identifier = self.format_vm_identifier(vmid, hostname)
+ node = node or lxc["node"]
+ lxc_status = self.get_lxc_status(vmid, node)
+
+ if lxc_status == "mounted":
+ if force:
+ self.umount_lxc_instance(vmid, hostname, timeout)
+ else:
+ self.module.exit_json(
+ changed=False,
+ vmid=vmid,
+ msg="VM %s is already stopped, but mounted. Use force option to umount it."
+ % identifier,
+ )
+
+ if lxc_status == "stopped":
+ self.module.exit_json(
+ changed=False, vmid=vmid, msg="VM %s is already stopped." % identifier
+ )
+
+ self.stop_lxc_instance(vmid, node, timeout, force)
+ self.module.exit_json(
+ changed=True, vmid=vmid, msg="VM %s stopped." % identifier
+ )
+
+ def lxc_restarted(self, vmid, hostname, node, timeout, force):
+ lxc = self.get_lxc_resource(vmid, hostname)
+
+ vmid = vmid or lxc["id"].split("/")[-1]
+ hostname = hostname or lxc["name"]
+ node = node or lxc["node"]
+
+ identifier = self.format_vm_identifier(vmid, hostname)
+ lxc_status = self.get_lxc_status(vmid, node)
+
+ if lxc_status in ["stopped", "mounted"]:
+ self.module.exit_json(
+ changed=False, vmid=vmid, msg="VM %s is not running." % identifier
+ )
+
+ self.stop_lxc_instance(vmid, node, timeout, force)
+ self.start_lxc_instance(vmid, node, timeout)
+ self.module.exit_json(
+ changed=True, vmid=vmid, msg="VM %s is restarted." % identifier
+ )
+
+ def lxc_to_template(self, vmid, hostname, node, timeout, force):
+ lxc = self.get_lxc_resource(vmid, hostname)
+ vmid = vmid or lxc["id"].split("/")[-1]
+ hostname = hostname or lxc["name"]
+ node = node or lxc["node"]
+ identifier = self.format_vm_identifier(vmid, hostname)
+
+ if self.is_template_container(node, vmid):
+ self.module.exit_json(
+ changed=False,
+ vmid=vmid,
+ msg="VM %s is already a template." % identifier,
+ )
+
+ lxc_status = self.get_lxc_status(vmid, node)
+ if lxc_status == "running" and force:
+ self.stop_instance(vmid, hostname, node, timeout, force)
+
+ proxmox_node = self.proxmox_api.nodes(node)
+ getattr(proxmox_node, self.VZ_TYPE)(vmid).template.post()
+ self.module.exit_json(
+ changed=True, vmid=vmid, msg="VM %s converted to template." % identifier
+ )
+
+ def update_lxc_instance(self, vmid, node, **kwargs):
+ if self.VZ_TYPE != "lxc":
+ self.module.fail_json(
+ msg="Updating LXC containers is only supported for LXC-enabled clusters in PVE 4.0 and above."
+ )
+
+ kwargs = {k: v for k, v in kwargs.items() if v is not None}
+
+ self.validate_tags(kwargs.get("tags", []))
+
+ if "features" in kwargs:
+ kwargs["features"] = ",".join(kwargs.pop("features"))
+ if "startup" in kwargs:
+ kwargs["startup"] = ",".join(kwargs.pop("startup"))
+
+ disk_updates = self.process_disk_keys(
+ vmid,
+ node,
+ kwargs.pop("disk", None),
+ kwargs.pop("disk_volume", None),
+ )
+ mounts_updates = self.process_mount_keys(
+ vmid,
+ node,
+ kwargs.pop("mounts", None),
+ kwargs.pop("mount_volumes", None),
+ )
+ kwargs.update(disk_updates)
+ kwargs.update(mounts_updates)
+
+ if "cpus" in kwargs:
+ kwargs["cpulimit"] = kwargs.pop("cpus")
+ if "netif" in kwargs:
+ kwargs.update(kwargs.pop("netif"))
+
+ if "pubkey" in kwargs:
+ pubkey = kwargs.pop("pubkey")
+ if self.version() >= LooseVersion("4.2"):
+ kwargs["ssh-public-keys"] = pubkey
+ else:
+ self.module.warn(
+ "'pubkey' is not supported for PVE 4.1 and below. Ignoring keyword."
+ )
+
+ # fetch current config
+ proxmox_node = self.proxmox_api.nodes(node)
+ current_config = getattr(proxmox_node, self.VZ_TYPE)(vmid).config.get()
+
+ # create diff between the current and requested config
+ diff = {}
+ for arg, value in kwargs.items():
+ # if the arg isn't in the current config, it needs to be added
+ if arg not in current_config:
+ diff[arg] = value
+ elif isinstance(value, str):
+ # compare all string values as lists as some of them may be lists separated by commas. order doesn't matter
+ current_values = current_config[arg].split(",")
+ requested_values = value.split(",")
+ for new_value in requested_values:
+ if new_value not in current_values:
+ diff[arg] = value
+ break
+ # if it's not a list (or string) just compare the values
+ # some types don't match with the API, so force a string comparison
+ elif str(value) != str(current_config[arg]):
+ diff[arg] = value
+
+ if not diff:
+ self.module.exit_json(
+ changed=False, vmid=vmid, msg="Container config is already up to date."
+ )
+
+ # update the config
+ getattr(proxmox_node, self.VZ_TYPE)(vmid).config.put(
+ vmid=vmid, node=node, **kwargs
+ )
+
+ def new_lxc_instance(self, vmid, hostname, node, clone_from, ostemplate, force):
+ identifier = self.format_vm_identifier(vmid, hostname)
+
+ if clone_from is not None:
+ self.clone_lxc_instance(
+ vmid,
+ node,
+ clone_from,
+ clone_type=self.params.get("clone_type"),
+ timeout=self.params.get("timeout"),
+ description=self.params.get("description"),
+ hostname=hostname,
+ pool=self.params.get("pool"),
+ storage=self.params.get("storage"),
+ )
+ self.module.exit_json(
+ changed=True,
+ vmid=vmid,
+ msg="Cloned VM %s from %d" % (identifier, clone_from),
+ )
+
+ if ostemplate is not None:
+ self.create_lxc_instance(
+ vmid,
+ node,
+ ostemplate,
+ timeout=self.params.get("timeout"),
+ cores=self.params.get("cores"),
+ cpus=self.params.get("cpus"),
+ cpuunits=self.params.get("cpuunits"),
+ description=self.params.get("description"),
+ disk=self.params.get("disk"),
+ disk_volume=self.params.get("disk_volume"),
+ features=self.params.get("features"),
+ force=ansible_to_proxmox_bool(force),
+ hookscript=self.params.get("hookscript"),
+ hostname=hostname,
+ ip_address=self.params.get("ip_address"),
+ memory=self.params.get("memory"),
+ mounts=self.params.get("mounts"),
+ mount_volumes=self.params.get("mount_volumes"),
+ nameserver=self.params.get("nameserver"),
+ netif=self.params.get("netif"),
+ onboot=ansible_to_proxmox_bool(self.params.get("onboot")),
+ ostype=self.params.get("ostype"),
+ password=self.params.get("password"),
+ pool=self.params.get("pool"),
+ pubkey=self.params.get("pubkey"),
+ searchdomain=self.params.get("searchdomain"),
+ startup=self.params.get("startup"),
+ storage=self.params.get("storage"),
+ swap=self.params.get("swap"),
+ tags=self.params.get("tags"),
+ timezone=self.params.get("timezone"),
+ unprivileged=ansible_to_proxmox_bool(self.params.get("unprivileged")),
+ )
+ self.module.exit_json(
+ changed=True,
+ vmid=vmid,
+ msg="Created VM %s from template %s" % (identifier, ostemplate),
+ )
+
+ self.module.fail_json(
+ vmid=vmid,
+ msg="VM %s does not exist but neither clone nor ostemplate were specified!"
+ % identifier,
+ )
+
+ def create_lxc_instance(self, vmid, node, ostemplate, timeout, **kwargs):
+ template_store = ostemplate.split(":")[0]
+ if not self.content_check(node, ostemplate, template_store):
+ self.module.fail_json(
+ vmid=vmid,
+ msg="ostemplate %s does not exist on node %s and storage %s."
+ % (ostemplate, node, template_store),
+ )
+
+ disk_updates = self.process_disk_keys(
+ vmid,
+ node,
+ kwargs.pop("disk"),
+ kwargs.pop("disk_volume"),
+ )
+ mounts_updates = self.process_mount_keys(
+ vmid,
+ node,
+ kwargs.pop("mounts"),
+ kwargs.pop("mount_volumes"),
+ )
+ kwargs.update(disk_updates)
+ kwargs.update(mounts_updates)
+
+ # Remove empty values from kwargs
+ kwargs = {k: v for k, v in kwargs.items() if v is not None}
+
+ if "features" in kwargs:
+ kwargs["features"] = ",".join(kwargs.pop("features"))
+
+ if "startup" in kwargs:
+ kwargs["startup"] = ",".join(kwargs.pop("startup"))
+
+ self.validate_tags(kwargs.get("tags", []))
+
+ if self.VZ_TYPE == "lxc":
+ if "cpus" in kwargs:
+ kwargs["cpuunits"] = kwargs.pop("cpus")
+ kwargs.update(kwargs.pop("netif", {}))
+ else:
+ if "mount_volumes" in kwargs:
+ kwargs.pop("mount_volumes")
+ self.module.warn(
+ "'mount_volumes' is not supported for non-LXC clusters. Ignoring keyword."
+ )
+
+ if "pubkey" in kwargs:
+ pubkey = kwargs.pop("pubkey")
+ if self.version() >= LooseVersion("4.2"):
+ kwargs["ssh-public-keys"] = pubkey
+ else:
+ self.module.warn(
+ "'pubkey' is not supported for PVE 4.1 and below. Ignoring keyword."
+ )
+
+ if kwargs.get("ostype") == "auto":
+ kwargs.pop("ostype")
+
+ proxmox_node = self.proxmox_api.nodes(node)
+ taskid = getattr(proxmox_node, self.VZ_TYPE).create(
+ vmid=vmid, ostemplate=ostemplate, **kwargs
+ )
+ self.handle_api_timeout(
+ vmid,
+ node,
+ taskid,
+ timeout,
+ "Reached timeout while waiting for creation of VM %s from template %s"
+ % (vmid, ostemplate),
+ )
+
+ def clone_lxc_instance(self, vmid, node, clone_from, clone_type, timeout, **kwargs):
+ if self.VZ_TYPE != "lxc":
+ self.module.fail_json(
+ msg="Cloning is only supported for LXC-enabled clusters in PVE 4.0 and above."
+ )
+
+ # Remove empty values from kwargs
+ kwargs = {k: v for k, v in kwargs.items() if v is not None}
+
+ target_is_template = self.is_template_container(node, clone_from)
+ # By default, create a full copy only when the cloned container is not a template.
+ create_full_copy = not target_is_template
+
+ # Only accept parameters that are compatible with the clone endpoint.
+ valid_clone_parameters = ["hostname", "pool", "description"]
+
+ if "storage" not in kwargs and target_is_template:
+ # Cloning a template, so create a full copy instead of a linked copy
+ create_full_copy = True
+ elif "storage" not in kwargs and not target_is_template:
+ self.module.fail_json(
+ changed=False,
+ msg="Clone target container is not a template, storage needs to be specified.",
+ )
+
+ if clone_type == "linked" and not target_is_template:
+ self.module.fail_json(
+ changed=False,
+ msg="Cloning type 'linked' is only supported for template containers.",
+ )
+ elif clone_type == "opportunistic" and not target_is_template:
+ # Cloned container is not a template, so we need our 'storage' parameter
+ valid_clone_parameters.append("storage")
+ elif clone_type == "full":
+ create_full_copy = True
+ valid_clone_parameters.append("storage")
+
+ clone_parameters = {}
+ clone_parameters["full"] = ansible_to_proxmox_bool(create_full_copy)
+
+ for param in valid_clone_parameters:
+ if param in kwargs:
+ clone_parameters[param] = kwargs[param]
+
+ proxmox_node = self.proxmox_api.nodes(node)
+ taskid = getattr(proxmox_node, self.VZ_TYPE)(clone_from).clone.post(
+ newid=vmid, **clone_parameters
+ )
+ self.handle_api_timeout(
+ vmid,
+ node,
+ taskid,
+ timeout,
+ timeout_msg="Reached timeout while waiting for VM to clone.",
+ )
+
+ def start_lxc_instance(self, vmid, node, timeout):
+ proxmox_node = self.proxmox_api.nodes(node)
+ taskid = getattr(proxmox_node, self.VZ_TYPE)(vmid).status.start.post()
+
+ self.handle_api_timeout(
+ vmid,
+ node,
+ taskid,
+ timeout,
+ timeout_msg="Reached timeout while waiting for VM to start.",
+ )
+
+ def stop_lxc_instance(self, vmid, node, timeout, force):
+ stop_params = {}
+ if force:
+ stop_params["forceStop"] = 1
+
+ proxmox_node = self.proxmox_api.nodes(node)
+ taskid = getattr(proxmox_node, self.VZ_TYPE)(vmid).status.shutdown.post(
+ **stop_params
+ )
+
+ self.handle_api_timeout(
+ vmid,
+ node,
+ taskid,
+ timeout,
+ timeout_msg="Reached timeout while waiting for VM to stop.",
+ )
+
+ def umount_lxc_instance(self, vmid, node, timeout):
+ proxmox_node = self.proxmox_api.nodes(node)
+ taskid = getattr(proxmox_node, self.VZ_TYPE)(vmid).status.unmount.post()
+
+ self.handle_api_timeout(
+ vmid,
+ node,
+ taskid,
+ timeout,
+ timeout_msg="Reached timeout while waiting for VM to be unmounted.",
+ )
+
+ def remove_lxc_instance(self, vmid, node, timeout, purge):
+ delete_params = {}
+ if purge:
+ delete_params["purge"] = 1
+
+ proxmox_node = self.proxmox_api.nodes(node)
+ taskid = getattr(proxmox_node, self.VZ_TYPE).delete(vmid, **delete_params)
+
+ self.handle_api_timeout(
+ vmid,
+ node,
+ taskid,
+ timeout,
+ timeout_msg="Reached timeout while waiting for VM to be removed.",
+ )
+
+ def process_disk_keys(self, vmid, node, disk, disk_volume):
+ """
+ Process disk keys and return a formatted disk volume with the `rootfs` key.
+
+ Args:
+ vmid (int): VM identifier.
+ node (str): Node identifier.
+ disk (str, optional): Disk key in the format 'storage:volume'. Defaults to None.
+ disk_volume (Dict[str, Any], optional): Disk volume data. Defaults to None.
+
+ Returns:
+ Dict[str, str]: Formatted disk volume with the `rootfs` or `disk` key (depending on the `VZ_TYPE`), or an empty dict if no disk volume is specified.
+ """
+ if disk is None and disk_volume is None:
+ return {}
+
+ disk_dict = {}
+
+ if disk is not None:
+ if disk.isdigit():
+ disk_dict["rootfs"] = disk
+ else:
+ disk_volume = self.parse_disk_string(disk)
+
+ if disk_volume is not None:
+ disk_dict = self.build_volume(vmid, node, key="rootfs", **disk_volume)
+
+ if self.VZ_TYPE != "lxc":
+ disk_dict["disk"] = disk_dict.pop("rootfs")
+
+ return disk_dict
+
+ def process_mount_keys(self, vmid, node, mounts, mount_volumes):
+ """
+ Process mount keys and return a formatted mount volumes with the `mp[n]` keys.
+
+ Args:
+ vmid (str): VM identifier.
+ node (str): Node identifier.
+ mounts (str, optional): Mount key in the format 'pool:volume'. Defaults to None.
+ mount_volumes (Dict[str, Any], optional): Mount volume data. Defaults to None.
+
+ Returns:
+ Dict[str, str]: Formatted mount volumes with the `mp[n]` keys, or an empty dict if no mount volumes are specified.
+ """
+ if mounts is not None:
+ mount_volumes = []
+ for mount_key, mount_string in mounts.items():
+ mount_config = self.parse_disk_string(mount_string)
+ mount_volumes.append(dict(id=mount_key, **mount_config))
+ elif mount_volumes is None or mount_volumes == []:
+ return {}
+
+ mounts_dict = {}
+ for mount_config in mount_volumes:
+ mount_key = mount_config.pop("id")
+ mount_dict = self.build_volume(vmid, node, key=mount_key, **mount_config)
+ mounts_dict.update(mount_dict)
+
+ return mounts_dict
+
+ def parse_disk_string(self, disk_string):
+ """
+ Parse a disk string and return a dictionary with the disk details.
+
+ Args:
+ disk_string (str): Disk string.
+
+ Returns:
+ Dict[str, Any]: Disk details.
+
+ Note: Below are some example disk strings that this function MUST be able to parse:
+ "acl=0,thin1:base-100-disk-1,size=8G"
+ "thin1:10,backup=0"
+ "local:20"
+ "local-lvm:0.50"
+ "tmp-dir:300/subvol-300-disk-0.subvol,acl=1,size=0T"
+ "tmplog-dir:300/vm-300-disk-0.raw,mp=/var/log,mountoptions=noatime,size=32M"
+ "volume=local-lvm:base-100-disk-1,size=20G"
+ "/mnt/bindmounts/shared,mp=/shared"
+ "volume=/dev/USB01,mp=/mnt/usb01"
+ """
+ args = disk_string.split(",")
+ # If the volume is not explicitly defined but implicit by only passing a key,
+ # add the "volume=" key prefix for ease of parsing.
+ args = ["volume=" + arg if "=" not in arg else arg for arg in args]
+ # Then create a dictionary from the arguments
+ disk_kwargs = dict(map(lambda item: item.split("="), args))
+
+ VOLUME_PATTERN = r"""(?x)
+ ^
+ (?:
+ (?:
+ (?P[\w\-.]+):
+ (?:
+ (?P\d+\.?\d*)|
+ (?P[^,\s]+)
+ )
+ )|
+ (?P[^,\s]+)
+ )
+ $
+ """
+ # DISCLAIMER:
+ # There are two things called a "volume":
+ # 1. The "volume" key which describes the storage volume, device or directory to mount into the container.
+ # 2. The storage volume of a storage-backed mount point in the PVE storage sub system.
+ # In this section, we parse the "volume" key and check which type of mount point we are dealing with.
+ pattern = re.compile(VOLUME_PATTERN)
+ volume_string = disk_kwargs.pop("volume")
+ match = pattern.match(volume_string)
+ if match is None:
+ raise ValueError(("Invalid volume string: %s", volume_string))
+ match_dict = match.groupdict()
+ match_dict = {k: v for k, v in match_dict.items() if v is not None}
+
+ if "storage" in match_dict and "volume" in match_dict:
+ disk_kwargs["storage"] = match_dict["storage"]
+ disk_kwargs["volume"] = match_dict["volume"]
+ elif "storage" in match_dict and "size" in match_dict:
+ disk_kwargs["storage"] = match_dict["storage"]
+ disk_kwargs["size"] = match_dict["size"]
+ elif "host_path" in match_dict:
+ disk_kwargs["host_path"] = match_dict["host_path"]
+
+ # Pattern matching only available in Python 3.10+
+ # TODO: Uncomment the following code once only Python 3.10+ is supported
+ # match match_dict:
+ # case {"storage": storage, "volume": volume}:
+ # disk_kwargs["storage"] = storage
+ # disk_kwargs["volume"] = volume
+
+ # case {"storage": storage, "size": size}:
+ # disk_kwargs["storage"] = storage
+ # disk_kwargs["size"] = size
+
+ # case {"host_path": host_path}:
+ # disk_kwargs["host_path"] = host_path
+
+ return disk_kwargs
+
+ def build_volume(self, vmid, node, key, storage=None, volume=None, host_path=None, size=None, mountpoint=None, options=None, **kwargs):
+ """
+ Build a volume string for the specified VM.
+
+ Args:
+ vmid (str): The VM ID.
+ node (str): The node where the VM resides.
+ key (str): The key for the volume in the VM's config.
+ storage (str, optional): The storage pool where the volume resides. Defaults to None.
+ volume (str, optional): The name of the volume. Defaults to None.
+ host_path (str, optional): The host path to mount. Defaults to None.
+ size (str | int, optional): The size of the volume in GiB. Defaults to None.
+ mountpoint (str, optional): The mountpoint for the volume. Defaults to None.
+ options (Dict[str, Any], optional): Additional options for the volume. Defaults to None.
+ **kwargs: Additional keyword arguments.
+
+ Returns:
+ Dict[str, str]: The built volume string in the format {'volume_key': 'volume_string'}.
+
+ Note: Further documentation can be found in the proxmox-api documentation: https://pve.proxmox.com/wiki/Linux_Container#pct_mount_points
+ Note: To build a valid volume string, we need ONE of the following:
+ A volume name, storage name, and size
+ Only a storage name and size (to create a new volume or assign the volume automatically)
+ A host directory to mount into the container
+ """
+ if isinstance(size, int):
+ size = str(size)
+ if size is not None and isfloat(size):
+ size += "G" # default to GiB
+ # Handle volume checks/creation
+ # TODO: Change the code below to pattern matching once only Python 3.10+ is supported
+ # 1. Check if defined volume exists
+ if volume is not None:
+ storage_content = self.get_storage_content(node, storage, vmid=vmid)
+ vol_ids = [vol["volid"] for vol in storage_content]
+ volid = "{storage}:{volume}".format(storage=storage, volume=volume)
+ if volid not in vol_ids:
+ self.module.fail_json(
+ changed=False,
+ msg="Storage {storage} does not contain volume {volume}".format(
+ storage=storage,
+ volume=volume,
+ ),
+ )
+ vol_string = "{storage}:{volume},size={size}".format(
+ storage=storage, volume=volume, size=size
+ )
+ # 2. If volume not defined (but storage is), check if it exists
+ elif storage is not None:
+ proxmox_node = self.proxmox_api.nodes(
+ node
+ ) # The node must exist, but not the LXC
+ try:
+ vol = proxmox_node.lxc(vmid).get("config").get(key)
+ volume = self.parse_disk_string(vol).get("volume")
+ vol_string = "{storage}:{volume},size={size}".format(
+ storage=storage, volume=volume, size=size
+ )
+
+ # If not, we have proxmox create one using the special syntax
+ except Exception:
+ if size is None:
+ raise ValueError(
+ "Size must be provided for storage-backed volume creation."
+ )
+ elif size.endswith("G"):
+ size = size.rstrip("G")
+ vol_string = "{storage}:{size}".format(storage=storage, size=size)
+ else:
+ raise ValueError(
+ "Size must be provided in GiB for storage-backed volume creation. Convert it to GiB or allocate a new storage manually."
+ )
+ # 3. If we have a host_path, we don't have storage, a volume, or a size
+ # Then we don't have to do anything, just build and return the vol_string
+ elif host_path is not None:
+ vol_string = ""
+ else:
+ raise ValueError(
+ "Could not build a valid volume string. One of volume, storage, or host_path must be provided."
+ )
+
+ if host_path is not None:
+ vol_string += "," + host_path
+
+ if mountpoint is not None:
+ vol_string += ",mp={}".format(mountpoint)
+
+ if options is not None:
+ vol_string += "," + ",".join(
+ ["{0}={1}".format(k, v) for k, v in options.items()]
+ )
+
+ if kwargs:
+ vol_string += "," + ",".join(
+ ["{0}={1}".format(k, v) for k, v in kwargs.items()]
+ )
+ return {key: vol_string}
+
+ def get_lxc_resource(self, vmid, hostname):
+ if not vmid and not hostname:
+ self.module.fail_json(msg="Either VMID or hostname must be provided.")
+
+ if vmid:
+ vm = self.get_lxc_resource_by_id(vmid)
+ elif hostname:
+ vm = self.get_lxc_resource_by_hostname(hostname)
+
+ vmid = vm["vmid"]
+ if vm["type"] != self.VZ_TYPE:
+ identifier = self.format_vm_identifier(vmid, hostname)
+ self.module.fail_json(
+ msg="The specified VM %s is not an %s." % (identifier, self.VZ_TYPE)
+ )
+
+ return vm
+
+ def get_lxc_resource_by_id(self, vmid):
+ vms = self.get_vm_resources()
+
+ vms = [vm for vm in vms if vm["vmid"] == vmid]
+ if len(vms) == 0:
+ raise LookupError("VM with VMID %d does not exist in cluster." % vmid)
+
+ return vms[0]
+
+ def get_lxc_resource_by_hostname(self, hostname):
+ vms = self.get_vm_resources()
+
+ vms = [vm for vm in vms if vm["name"] == hostname]
+ if len(vms) == 0:
+ raise LookupError(
+ "VM with hostname %s does not exist in cluster." % hostname
+ )
+ elif len(vms) > 1:
+ raise ValueError(
+ "Multiple VMs found with hostname %s. Please specify VMID." % hostname
+ )
+
+ return vms[0]
+
+ def get_vm_resources(self):
+ try:
+ return self.proxmox_api.cluster.resources.get(type="vm")
+ except Exception as e:
+ self.module.fail_json(
+ msg="Unable to retrieve list of %s VMs from cluster resources: %s"
+ % (self.VZ_TYPE, e)
+ )
+
+ def get_lxc_status(self, vmid, node_name):
+ try:
+ proxmox_node = self.proxmox_api.nodes(node_name)
+ except Exception as e:
+ self.module.fail_json(msg="Unable to retrieve node information: %s" % e)
+ return getattr(proxmox_node, self.VZ_TYPE)(vmid).status.current.get()['status']
+
+ def format_vm_identifier(self, vmid, hostname):
+ if vmid and hostname:
+ return "%s (%s)" % (hostname, vmid)
+ elif hostname:
+ return hostname
+ else:
+ return to_native(vmid)
+
+ def handle_api_timeout(self, vmid, node, taskid, timeout, timeout_msg=""):
+ if timeout_msg != "":
+ timeout_msg = "%s " % timeout_msg
+
+ while timeout > 0:
+ if self.api_task_ok(node, taskid):
+ return
+ timeout -= 1
+ time.sleep(1)
+
+ self.module.fail_json(
+ vmid=vmid,
+ taskid=taskid,
+ msg="%sLast line in task before timeout: %s"
+ % (timeout_msg, self.proxmox_api.nodes(node).tasks(taskid).log.get()[:1]),
+ )
+
+ def is_template_container(self, node, target):
+ """Check if the specified container is a template."""
+ proxmox_node = self.proxmox_api.nodes(node)
+ config = getattr(proxmox_node, self.VZ_TYPE)(target).config.get()
+ return config.get("template", False)
+
+ def content_check(self, node, ostemplate, template_store):
+ """Check if the specified ostemplate is present in the specified storage."""
+ proxmox_node = self.proxmox_api.nodes(node)
+ storage_contents = proxmox_node.storage(template_store).content.get()
+ return any(content["volid"] == ostemplate for content in storage_contents)
+
+ def validate_tags(self, tags):
+ """Check if the specified tags are valid."""
+ re_tag = re.compile(r"^[a-z0-9_][a-z0-9_\-\+\.]*$")
+ for tag in tags:
+ if not re_tag.match(tag):
+ self.module.fail_json(msg="%s is not a valid tag" % tag)
+ return False
+ return True
+
+ def check_supported_features(self):
+ for option, version in self.MINIMUM_VERSIONS.items():
+ if self.version() < LooseVersion(version) and option in self.module.params:
+ self.module.fail_json(
+ changed=False,
+ msg="Feature {option} is only supported in PVE {version}+, and you're using PVE {pve_version}".format(
+ option=option, version=version, pve_version=self.version()
+ ),
+ )
+
+
+def isfloat(value):
+ if value is None:
+ return False
+ try:
+ float(value)
+ return True
+ except ValueError:
+ return False
+
+
+def main():
+ module = get_ansible_module()
proxmox = ProxmoxLxcAnsible(module)
- global VZ_TYPE
- VZ_TYPE = 'openvz' if proxmox.version() < LooseVersion('4.0') else 'lxc'
-
- state = module.params['state']
- vmid = module.params['vmid']
- node = module.params['node']
- disk = module.params['disk']
- cpus = module.params['cpus']
- memory = module.params['memory']
- swap = module.params['swap']
- storage = module.params['storage']
- hostname = module.params['hostname']
- if module.params['ostemplate'] is not None:
- template_store = module.params['ostemplate'].split(":")[0]
- timeout = module.params['timeout']
- clone = module.params['clone']
-
- # 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 = proxmox.get_nextvmid()
- elif not vmid and hostname:
- vmid = proxmox.get_vmid(hostname)
- 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 proxmox.get_vm(vmid, ignore_missing=True):
- if module.params["update"]:
- try:
- proxmox.update_config(vmid, node, disk, cpus, memory, swap,
- cores=module.params["cores"],
- hostname=module.params["hostname"],
- netif=module.params["netif"],
- disk_volume=module.params["disk_volume"],
- mounts=module.params["mounts"],
- mount_volumes=module.params["mount_volumes"],
- 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"],
- features=",".join(module.params["features"])
- if module.params["features"] is not None
- else None,
- startup=",".join(module.params["startup"])
- if module.params["startup"] is not None
- else None,
- description=module.params["description"],
- hookscript=module.params["hookscript"],
- timezone=module.params["timezone"],
- tags=module.params["tags"])
- module.exit_json(
- changed=True,
- vmid=vmid,
- msg="Configured VM %s" % (vmid),
- )
- except Exception as e:
- module.fail_json(
- vmid=vmid,
- msg="Configuration of %s VM %s failed with exception: %s"
- % (VZ_TYPE, vmid, e),
- )
- if not module.params["force"]:
- module.exit_json(
- changed=False,
- vmid=vmid,
- 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
- proxmox.get_vmid(hostname, ignore_missing=True) and
- not module.params['force']):
- vmid = proxmox.get_vmid(hostname)
- module.exit_json(changed=False, vmid=vmid, msg="VM with hostname %s already exists and has ID number %s" % (hostname, vmid))
- elif not proxmox.get_node(node):
- module.fail_json(vmid=vmid, msg="node '%s' not exists in cluster" % node)
- elif not proxmox.content_check(node, module.params['ostemplate'], template_store):
- module.fail_json(vmid=vmid, msg="ostemplate '%s' not exists on node %s and storage %s"
- % (module.params['ostemplate'], node, template_store))
- except Exception as e:
- module.fail_json(vmid=vmid, msg="Pre-creation checks of {VZ_TYPE} VM {vmid} failed with exception: {e}".format(VZ_TYPE=VZ_TYPE, vmid=vmid, e=e))
-
- try:
- 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'],
- disk_volume=module.params["disk_volume"],
- mounts=module.params['mounts'],
- mount_volumes=module.params["mount_volumes"],
- ostype=module.params['ostype'],
- 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,
- startup=",".join(module.params['startup']) if module.params['startup'] is not None else None,
- unprivileged=ansible_to_proxmox_bool(module.params['unprivileged']),
- description=module.params['description'],
- hookscript=module.params['hookscript'],
- timezone=module.params['timezone'],
- tags=module.params['tags'])
-
- module.exit_json(changed=True, vmid=vmid, msg="Deployed VM %s from template %s" % (vmid, module.params['ostemplate']))
- except Exception as e:
- module.fail_json(vmid=vmid, msg="Creation of %s VM %s failed with exception: %s" % (VZ_TYPE, vmid, e))
-
- # Clone a container
- elif state == 'present' and clone is not None:
- try:
- if proxmox.get_vm(vmid, ignore_missing=True) and not module.params['force']:
- module.exit_json(changed=False, vmid=vmid, 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
- proxmox.get_vmid(hostname, ignore_missing=True) and
- not module.params['force']):
- vmid = proxmox.get_vmid(hostname)
- module.exit_json(changed=False, vmid=vmid, 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, vmid=vmid, msg="Container to be cloned does not exist")
- except Exception as e:
- module.fail_json(vmid=vmid, msg="Pre-clone checks of {VZ_TYPE} VM {vmid} failed with exception: {e}".format(VZ_TYPE=VZ_TYPE, vmid=vmid, e=e))
-
- try:
- proxmox.create_instance(vmid, node, disk, storage, cpus, memory, swap, timeout, clone)
-
- module.exit_json(changed=True, vmid=vmid, msg="Cloned VM %s from %s" % (vmid, clone))
- except Exception as e:
- module.fail_json(vmid=vmid, msg="Cloning %s VM %s failed with exception: %s" % (VZ_TYPE, vmid, e))
-
- elif state == 'started':
- try:
- 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, vmid=vmid, msg="VM %s is already running" % vmid)
-
- if proxmox.start_instance(vm, vmid, timeout):
- module.exit_json(changed=True, vmid=vmid, msg="VM %s started" % vmid)
- except Exception as e:
- module.fail_json(vmid=vmid, msg="starting of VM %s failed with exception: %s" % (vmid, e))
-
- elif state == 'stopped':
- try:
- vm = proxmox.get_vm(vmid)
-
- if getattr(proxmox.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'mounted':
- if module.params['force']:
- if proxmox.umount_instance(vm, vmid, timeout):
- module.exit_json(changed=True, vmid=vmid, msg="VM %s is shutting down" % vmid)
- else:
- module.exit_json(changed=False, vmid=vmid,
- msg=("VM %s is already shutdown, but mounted. You can use force option to umount it.") % vmid)
-
- if getattr(proxmox.proxmox_api.nodes(vm['node']), VZ_TYPE)(vmid).status.current.get()['status'] == 'stopped':
- module.exit_json(changed=False, vmid=vmid, msg="VM %s is already shutdown" % vmid)
-
- if proxmox.stop_instance(vm, vmid, timeout, force=module.params['force']):
- module.exit_json(changed=True, vmid=vmid, msg="VM %s is shutting down" % vmid)
- except Exception as e:
- module.fail_json(vmid=vmid, msg="stopping of VM %s failed with exception: %s" % (vmid, e))
-
- elif state == 'template':
- try:
- vm = proxmox.get_vm(vmid)
-
- proxmox.convert_to_template(vm, vmid, timeout, force=module.params['force'])
- module.exit_json(changed=True, msg="VM %s is converted to template" % vmid)
- except Exception as e:
- module.fail_json(vmid=vmid, msg="conversion of VM %s to template failed with exception: %s" % (vmid, e))
-
- elif state == 'restarted':
- try:
- 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, vmid=vmid, msg="VM %s is not running" % vmid)
-
- if (proxmox.stop_instance(vm, vmid, timeout, force=module.params['force']) and
- proxmox.start_instance(vm, vmid, timeout)):
- module.exit_json(changed=True, vmid=vmid, msg="VM %s is restarted" % vmid)
- except Exception as e:
- module.fail_json(vmid=vmid, msg="restarting of VM %s failed with exception: %s" % (vmid, e))
-
- elif state == 'absent':
- if not vmid:
- module.exit_json(changed=False, vmid=vmid, msg='VM with hostname = %s is already absent' % hostname)
- try:
- vm = proxmox.get_vm(vmid, ignore_missing=True)
- if not vm:
- module.exit_json(changed=False, vmid=vmid, msg="VM %s does not exist" % vmid)
-
- 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, vmid=vmid, msg="VM %s is running. Stop it before deletion." % vmid)
-
- if vm_status == 'mounted':
- module.exit_json(changed=False, vmid=vmid, msg="VM %s is mounted. Stop it with force option before deletion." % vmid)
-
- delete_params = {}
-
- if module.params['purge']:
- delete_params['purge'] = 1
-
- taskid = getattr(proxmox.proxmox_api.nodes(vm['node']), VZ_TYPE).delete(vmid, **delete_params)
-
- while timeout:
- if proxmox.api_task_ok(vm['node'], taskid):
- module.exit_json(changed=True, vmid=vmid, taskid=taskid, msg="VM %s removed" % vmid)
- timeout -= 1
- if timeout == 0:
- module.fail_json(vmid=vmid, taskid=taskid, msg='Reached timeout while waiting for removing VM. Last line in task before timeout: %s'
- % proxmox.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1])
-
- time.sleep(1)
- except Exception as e:
- module.fail_json(vmid=vmid, msg="deletion of VM %s failed with exception: %s" % (vmid, to_native(e)))
+ try:
+ proxmox.run()
+ except Exception as e:
+ module.fail_json(msg="An error occurred: %s" % to_native(e))
-if __name__ == '__main__':
+if __name__ == "__main__":
main()
diff --git a/plugins/modules/proxmox_backup.py b/plugins/modules/proxmox_backup.py
new file mode 100644
index 0000000000..63e19c1d35
--- /dev/null
+++ b/plugins/modules/proxmox_backup.py
@@ -0,0 +1,570 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2024, IamLunchbox
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+
+DOCUMENTATION = r"""
+module: proxmox_backup
+author: "Raphael Grieger (@IamLunchbox) "
+short_description: Start a VM backup in Proxmox VE cluster
+version_added: 10.1.0
+description:
+ - Allows you to create backups of KVM and LXC guests in Proxmox VE cluster.
+ - Offers the GUI functionality of creating a single backup as well as using the run-now functionality from the cluster backup
+ schedule.
+ - The mininum required privileges to use this module are C(VM.Backup) and C(Datastore.AllocateSpace) for the respective
+ VMs and storage.
+ - Most options are optional and if unspecified will be chosen by the Cluster and its default values.
+ - Note that this module B(is not idempotent). It always starts a new backup (when not in check mode).
+attributes:
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
+options:
+ backup_mode:
+ description:
+ - The mode how Proxmox performs backups. The default is, to create a runtime snapshot including memory.
+ - Check U(https://pve.proxmox.com/pve-docs/chapter-vzdump.html#_backup_modes) for an explanation of the differences.
+ type: str
+ choices: ["snapshot", "suspend", "stop"]
+ default: snapshot
+ bandwidth:
+ description:
+ - Limit the I/O bandwidth (in KiB/s) to write backup. V(0) is unlimited.
+ type: int
+ change_detection_mode:
+ description:
+ - Set the change detection mode (available from Proxmox VE 8.3).
+ - It is only used when backing up containers, Proxmox silently ignores this option when applied to kvm guests.
+ type: str
+ choices: ["legacy", "data", "metadata"]
+ compress:
+ description:
+ - Enable additional compression of the backup archive.
+ - V(0) will use the Proxmox recommended value, depending on your storage target.
+ type: str
+ choices: ["0", "1", "gzip", "lzo", "zstd"]
+ compression_threads:
+ description:
+ - The number of threads zstd will use to compress the backup.
+ - V(0) uses 50% of the available cores, anything larger than V(0) will use exactly as many threads.
+ - Is ignored if you specify O(compress=gzip) or O(compress=lzo).
+ type: int
+ description:
+ description:
+ - Specify the description of the backup.
+ - Needs to be a single line, newline and backslash need to be escaped as V(\\n) and V(\\\\) respectively.
+ - If you need variable interpolation, you can set the content as usual through ansible jinja templating and/or let Proxmox
+ substitute templates.
+ - Proxmox currently supports V({{cluster}}), V({{guestname}}), V({{node}}), and V({{vmid}}) as templating variables.
+ Since this is also a jinja delimiter, you need to set these values as raw jinja.
+ default: "{{guestname}}"
+ type: str
+ fleecing:
+ description:
+ - Enable backup fleecing. Works only for virtual machines and their disks.
+ - Must be entered as a string, containing key-value pairs in a list.
+ type: str
+ mode:
+ description:
+ - Specifices the mode to select backup targets.
+ choices: ["include", "all", "pool"]
+ required: true
+ type: str
+ node:
+ description:
+ - Only execute the backup job for the given node.
+ - This option is usually used if O(mode=all).
+ - If you specify a node ID and your vmids or pool do not reside there, they will not be backed up!
+ type: str
+ notification_mode:
+ description:
+ - Determine which notification system to use.
+ type: str
+ choices: ["auto", "legacy-sendmail", "notification-system"]
+ default: auto
+ performance_tweaks:
+ description:
+ - Enable other performance-related settings.
+ - Must be entered as a string, containing comma separated key-value pairs.
+ - 'For example: V(max-workers=2,pbs-entries-max=2).'
+ type: str
+ pool:
+ description:
+ - Specify a pool name to limit backups to guests to the given pool.
+ - Required, when O(mode=pool).
+ - Also required, when your user only has VM.Backup permission for this single pool.
+ type: str
+ protected:
+ description:
+ - Marks backups as protected.
+ - '"Might fail, when the PBS backend has verify enabled due to this bug: U(https://bugzilla.proxmox.com/show_bug.cgi?id=4289)".'
+ type: bool
+ retention:
+ description:
+ - Use custom retention options instead of those from the default cluster configuration (which is usually V("keep-all=1")).
+ - Always requires Datastore.Allocate permission at the storage endpoint.
+ - Specifying a retention time other than V(keep-all=1) might trigger pruning on the datastore, if an existing backup
+ should be deleted due to your specified timeframe.
+ - Deleting requires C(Datastore.Modify) or C(Datastore.Prune) permissions on the backup storage.
+ type: str
+ storage:
+ description:
+ - Store the backup archive on this storage.
+ type: str
+ required: true
+ vmids:
+ description:
+ - The instance IDs to be backed up.
+ - Only valid, if O(mode=include).
+ type: list
+ elements: int
+ wait:
+ description:
+ - Wait for the backup to be finished.
+ - Fails, if job does not succeed successfully within the given timeout.
+ type: bool
+ default: false
+ wait_timeout:
+ description:
+ - Seconds to wait for the backup to be finished.
+ - Will only be evaluated, if O(wait=true).
+ type: int
+ default: 10
+requirements: ["proxmoxer", "requests"]
+extends_documentation_fragment:
+ - community.general.proxmox.actiongroup_proxmox
+ - community.general.proxmox.documentation
+ - community.general.attributes
+"""
+
+EXAMPLES = r"""
+- name: Backup all vms in the Proxmox cluster to storage mypbs
+ community.general.proxmox_backup:
+ api_user: root@pam
+ api_password: secret
+ api_host: node1
+ storage: mypbs
+ mode: all
+
+- name: Backup VMID 100 by stopping it and set an individual retention
+ community.general.proxmox_backup:
+ api_user: root@pam
+ api_password: secret
+ api_host: node1
+ backup-mode: stop
+ mode: include
+ retention: keep-daily=5, keep-last=14, keep-monthly=4, keep-weekly=4, keep-yearly=0
+ storage: mypbs
+ vmid: [100]
+
+- name: Backup all vms on node node2 to storage mypbs and wait for the task to finish
+ community.general.proxmox_backup:
+ api_user: test@pve
+ api_password: 1q2w3e
+ api_host: node2
+ storage: mypbs
+ mode: all
+ node: node2
+ wait: true
+ wait_timeout: 30
+
+- name: Use all the options
+ community.general.proxmox_backup:
+ api_user: root@pam
+ api_password: secret
+ api_host: node1
+ bandwidth: 1000
+ backup_mode: suspend
+ compress: zstd
+ compression_threads: 0
+ description: A single backup for {% raw %}{{ guestname }}{% endraw %}
+ mode: include
+ notification_mode: notification-system
+ protected: true
+ retention: keep-monthly=1, keep-weekly=1
+ storage: mypbs
+ vmids:
+ - 100
+ - 101
+"""
+
+RETURN = r"""
+backups:
+ description: List of nodes and their task IDs.
+ returned: on success
+ type: list
+ elements: dict
+ contains:
+ node:
+ description: Node ID.
+ returned: on success
+ type: str
+ status:
+ description: Last known task status. Will be unknown, if O(wait=false).
+ returned: on success
+ type: str
+ choices: ["unknown", "success", "failed"]
+ upid:
+ description: >-
+ Proxmox cluster UPID, which is needed to lookup task info. Returns OK, when a cluster node did not create a task after
+ being called, for example due to no matching targets.
+ returned: on success
+ type: str
+"""
+
+import time
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.common.text.converters import to_native
+from ansible_collections.community.general.plugins.module_utils.proxmox import ProxmoxAnsible, proxmox_auth_argument_spec
+
+
+def has_permission(permission_tree, permission, search_scopes, default=0, expected=1):
+ return any(permission_tree.get(scope, {}).get(permission, default) == expected for scope in search_scopes)
+
+
+class ProxmoxBackupAnsible(ProxmoxAnsible):
+
+ def _get_permissions(self):
+ return self.proxmox_api.access.permissions.get()
+
+ def _get_resources(self, resource_type=None):
+ return self.proxmox_api.cluster.resources.get(type=resource_type)
+
+ def _get_tasklog(self, node, upid):
+ return self.proxmox_api.nodes(node).tasks(upid).log.get()
+
+ def _get_taskok(self, node, upid):
+ return self.proxmox_api.nodes(node).tasks(upid).status.get()
+
+ def _post_vzdump(self, node, request_body):
+ return self.proxmox_api.nodes(node).vzdump.post(**request_body)
+
+ def request_backup(
+ self,
+ request_body,
+ node_endpoints):
+ task_ids = []
+
+ for node in node_endpoints:
+ upid = self._post_vzdump(node, request_body)
+ if upid != "OK":
+ tasklog = ", ".join(logentry["t"] for logentry in self._get_tasklog(node, upid))
+ else:
+ tasklog = ""
+ task_ids.extend([{"node": node, "upid": upid, "status": "unknown", "log": "%s" % tasklog}])
+ return task_ids
+
+ def check_relevant_nodes(self, node):
+ nodes = [
+ item["node"]
+ for item in self._get_resources("node")
+ if item["status"] == "online"
+ ]
+ if node and node not in nodes:
+ self.module.fail_json(msg="Node %s was specified, but does not exist on the cluster" % node)
+ elif node:
+ return [node]
+ return nodes
+
+ def check_storage_permissions(
+ self,
+ permissions,
+ storage,
+ bandwidth,
+ performance,
+ retention):
+ # Check for Datastore.AllocateSpace in the permission tree
+ if not has_permission(permissions, "Datastore.AllocateSpace", search_scopes=["/", "/storage/", "/storage/" + storage]):
+ self.module.fail_json(changed=False, msg="Insufficient permission: Datastore.AllocateSpace is missing")
+
+ if (bandwidth or performance) and has_permission(permissions, "Sys.Modify", search_scopes=["/"], expected=0):
+ self.module.fail_json(changed=False, msg="Insufficient permission: Performance_tweaks and bandwidth require 'Sys.Modify' permission for '/'")
+
+ if retention:
+ if not has_permission(permissions, "Datastore.Allocate", search_scopes=["/", "/storage", "/storage/" + storage]):
+ self.module.fail_json(changed=False, msg="Insufficient permissions: Custom retention was requested, but Datastore.Allocate is missing")
+
+ def check_vmid_backup_permission(self, permissions, vmids, pool):
+ sufficient_permissions = has_permission(permissions, "VM.Backup", search_scopes=["/", "/vms"])
+ if pool and not sufficient_permissions:
+ sufficient_permissions = has_permission(permissions, "VM.Backup", search_scopes=["/pool/" + pool, "/pool/" + pool + "/vms"])
+
+ if not sufficient_permissions:
+ # Since VM.Backup can be given for each vmid at a time, iterate through all of them
+ # and check, if the permission is set
+ failed_vmids = []
+ for vm in vmids:
+ vm_path = "/vms/" + str(vm)
+ if has_permission(permissions, "VM.Backup", search_scopes=[vm_path], default=1, expected=0):
+ failed_vmids.append(str(vm))
+ if failed_vmids:
+ self.module.fail_json(
+ changed=False, msg="Insufficient permissions: "
+ "You dont have the VM.Backup permission for VMID %s" %
+ ", ".join(failed_vmids))
+ sufficient_permissions = True
+ # Finally, when no check succeeded, fail
+ if not sufficient_permissions:
+ self.module.fail_json(changed=False, msg="Insufficient permissions: You do not have the VM.Backup permission")
+
+ def check_general_backup_permission(self, permissions, pool):
+ if not has_permission(permissions, "VM.Backup", search_scopes=["/", "/vms"] + (["/pool/" + pool] if pool else [])):
+ self.module.fail_json(changed=False, msg="Insufficient permissions: You dont have the VM.Backup permission")
+
+ def check_if_storage_exists(self, storage, node):
+ storages = self.get_storages(type=None)
+ # Loop through all cluster storages and get all matching storages
+ validated_storagepath = [storageentry for storageentry in storages if storageentry["storage"] == storage]
+ if not validated_storagepath:
+ self.module.fail_json(
+ changed=False,
+ msg="Storage %s does not exist in the cluster" %
+ storage)
+
+ def check_vmids(self, vmids):
+ cluster_vmids = [vm["vmid"] for vm in self._get_resources("vm")]
+ if not cluster_vmids:
+ self.module.warn(
+ "VM.Audit permission is missing or there are no VMs. This task might fail if one VMID does not exist")
+ return
+ vmids_not_found = [str(vm) for vm in vmids if vm not in cluster_vmids]
+ if vmids_not_found:
+ self.module.warn(
+ "VMIDs %s not found. This task will fail if one VMID does not exist" %
+ ", ".join(vmids_not_found))
+
+ def wait_for_timeout(self, timeout, raw_tasks):
+
+ # filter all entries, which did not get a task id from the Cluster
+ tasks = []
+ ok_tasks = []
+ for node in raw_tasks:
+ if node["upid"] != "OK":
+ tasks.append(node)
+ else:
+ ok_tasks.append(node)
+
+ start_time = time.time()
+ # iterate through the task ids and check their values
+ while True:
+ for node in tasks:
+ if node["status"] == "unknown":
+ try:
+ # proxmox.api_task_ok does not suffice, since it only
+ # is true at `stopped` and `ok`
+ status = self._get_taskok(node["node"], node["upid"])
+ if status["status"] == "stopped" and status["exitstatus"] == "OK":
+ node["status"] = "success"
+ if status["status"] == "stopped" and status["exitstatus"] == "job errors":
+ node["status"] = "failed"
+ except Exception as e:
+ self.module.fail_json(msg="Unable to retrieve API task ID from node %s: %s" % (node["node"], e))
+ if len([item for item in tasks if item["status"] != "unknown"]) == len(tasks):
+ break
+ if time.time() > start_time + timeout:
+ timeouted_nodes = [
+ node["node"]
+ for node in tasks
+ if node["status"] == "unknown"
+ ]
+ failed_nodes = [node["node"] for node in tasks if node["status"] == "failed"]
+ if failed_nodes:
+ self.module.fail_json(
+ msg="Reached timeout while waiting for backup task. "
+ "Nodes, who reached the timeout: %s. "
+ "Nodes, which failed: %s" %
+ (", ".join(timeouted_nodes), ", ".join(failed_nodes)))
+ self.module.fail_json(
+ msg="Reached timeout while waiting for creating VM snapshot. "
+ "Nodes who reached the timeout: %s" %
+ ", ".join(timeouted_nodes))
+ time.sleep(1)
+
+ error_logs = []
+ for node in tasks:
+ if node["status"] == "failed":
+ tasklog = ", ".join([logentry["t"] for logentry in self._get_tasklog(node["node"], node["upid"])])
+ error_logs.append("%s: %s" % (node, tasklog))
+ if error_logs:
+ self.module.fail_json(
+ msg="An error occured creating the backups. "
+ "These are the last log lines from the failed nodes: %s" %
+ ", ".join(error_logs))
+
+ for node in tasks:
+ tasklog = ", ".join([logentry["t"] for logentry in self._get_tasklog(node["node"], node["upid"])])
+ node["log"] = tasklog
+
+ # Finally, reattach ok tasks to show, that all nodes were contacted
+ tasks.extend(ok_tasks)
+ return tasks
+
+ def permission_check(
+ self,
+ storage,
+ mode,
+ node,
+ bandwidth,
+ performance_tweaks,
+ retention,
+ pool,
+ vmids):
+ permissions = self._get_permissions()
+ self.check_if_storage_exists(storage, node)
+ self.check_storage_permissions(
+ permissions, storage, bandwidth, performance_tweaks, retention)
+ if mode == "include":
+ self.check_vmid_backup_permission(permissions, vmids, pool)
+ else:
+ self.check_general_backup_permission(permissions, pool)
+
+ def prepare_request_parameters(self, module_arguments):
+ # ensure only valid post parameters are passed to proxmox
+ # list of dict items to replace with (new_val, old_val)
+ post_params = [("bwlimit", "bandwidth"),
+ ("compress", "compress"),
+ ("fleecing", "fleecing"),
+ ("mode", "backup_mode"),
+ ("notes-template", "description"),
+ ("notification-mode", "notification_mode"),
+ ("pbs-change-detection-mode", "change_detection_mode"),
+ ("performance", "performance_tweaks"),
+ ("pool", "pool"),
+ ("protected", "protected"),
+ ("prune-backups", "retention"),
+ ("storage", "storage"),
+ ("zstd", "compression_threads"),
+ ("vmid", "vmids")]
+ request_body = {}
+ for new, old in post_params:
+ if module_arguments.get(old):
+ request_body.update({new: module_arguments[old]})
+
+ # Set mode specific values
+ if module_arguments["mode"] == "include":
+ request_body.pop("pool", None)
+ request_body["all"] = 0
+ elif module_arguments["mode"] == "all":
+ request_body.pop("vmid", None)
+ request_body.pop("pool", None)
+ request_body["all"] = 1
+ elif module_arguments["mode"] == "pool":
+ request_body.pop("vmid", None)
+ request_body["all"] = 0
+
+ # Create comma separated list from vmids, the API expects so
+ if request_body.get("vmid"):
+ request_body.update({"vmid": ",".join(str(vmid) for vmid in request_body["vmid"])})
+
+ # remove whitespaces from option strings
+ for key in ("prune-backups", "performance"):
+ if request_body.get(key):
+ request_body[key] = request_body[key].replace(" ", "")
+ # convert booleans to 0/1
+ for key in ("protected",):
+ if request_body.get(key):
+ request_body[key] = 1
+ return request_body
+
+ def backup_create(
+ self,
+ module_arguments,
+ check_mode,
+ node_endpoints):
+ request_body = self.prepare_request_parameters(module_arguments)
+ # stop here, before anything gets changed
+ if check_mode:
+ return []
+
+ task_ids = self.request_backup(request_body, node_endpoints)
+ updated_task_ids = []
+ if module_arguments["wait"]:
+ updated_task_ids = self.wait_for_timeout(
+ module_arguments["wait_timeout"], task_ids)
+ return updated_task_ids if updated_task_ids else task_ids
+
+
+def main():
+ module_args = proxmox_auth_argument_spec()
+ backup_args = {
+ "backup_mode": {"type": "str", "default": "snapshot", "choices": ["snapshot", "suspend", "stop"]},
+ "bandwidth": {"type": "int"},
+ "change_detection_mode": {"type": "str", "choices": ["legacy", "data", "metadata"]},
+ "compress": {"type": "str", "choices": ["0", "1", "gzip", "lzo", "zstd"]},
+ "compression_threads": {"type": "int"},
+ "description": {"type": "str", "default": "{{guestname}}"},
+ "fleecing": {"type": "str"},
+ "mode": {"type": "str", "required": True, "choices": ["include", "all", "pool"]},
+ "node": {"type": "str"},
+ "notification_mode": {"type": "str", "default": "auto", "choices": ["auto", "legacy-sendmail", "notification-system"]},
+ "performance_tweaks": {"type": "str"},
+ "pool": {"type": "str"},
+ "protected": {"type": "bool"},
+ "retention": {"type": "str"},
+ "storage": {"type": "str", "required": True},
+ "vmids": {"type": "list", "elements": "int"},
+ "wait": {"type": "bool", "default": False},
+ "wait_timeout": {"type": "int", "default": 10}}
+ module_args.update(backup_args)
+
+ module = AnsibleModule(
+ argument_spec=module_args,
+ supports_check_mode=True,
+ required_if=[
+ ("mode", "include", ("vmids",), True),
+ ("mode", "pool", ("pool",))
+ ]
+ )
+ proxmox = ProxmoxBackupAnsible(module)
+ bandwidth = module.params["bandwidth"]
+ mode = module.params["mode"]
+ node = module.params["node"]
+ performance_tweaks = module.params["performance_tweaks"]
+ pool = module.params["pool"]
+ retention = module.params["retention"]
+ storage = module.params["storage"]
+ vmids = module.params["vmids"]
+
+ proxmox.permission_check(
+ storage,
+ mode,
+ node,
+ bandwidth,
+ performance_tweaks,
+ retention,
+ pool,
+ vmids)
+ if module.params["mode"] == "include":
+ proxmox.check_vmids(module.params["vmids"])
+ node_endpoints = proxmox.check_relevant_nodes(module.params["node"])
+ try:
+ result = proxmox.backup_create(module.params, module.check_mode, node_endpoints)
+ except Exception as e:
+ module.fail_json(msg="Creating backups failed with exception: %s" % to_native(e))
+
+ if module.check_mode:
+ module.exit_json(backups=result, changed=True, msg="Backups would be created")
+
+ elif len([entry for entry in result if entry["upid"] == "OK"]) == len(result):
+ module.exit_json(backups=result, changed=False, msg="Backup request sent to proxmox, no tasks created")
+
+ elif module.params["wait"]:
+ module.exit_json(backups=result, changed=True, msg="Backups succeeded")
+
+ else:
+ module.exit_json(backups=result, changed=True,
+ msg="Backup tasks created")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/plugins/modules/proxmox_backup_info.py b/plugins/modules/proxmox_backup_info.py
new file mode 100644
index 0000000000..0889239b37
--- /dev/null
+++ b/plugins/modules/proxmox_backup_info.py
@@ -0,0 +1,244 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2024 Marzieh Raoufnezhad
+# Copyright (c) 2024 Maryam Mayabi
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = """
+---
+module: proxmox_backup_info
+
+short_description: Retrieve information on Proxmox scheduled backups
+
+version_added: 10.3.0
+
+description:
+ - Retrieve information such as backup times, VM name, VM ID, mode, backup type, and backup schedule using the Proxmox Server API.
+
+author:
+ - "Marzieh Raoufnezhad (@raoufnezhad) "
+ - "Maryam Mayabi (@mmayabi) "
+
+options:
+ vm_name:
+ description:
+ - The name of the Proxmox VM.
+ - If defined, the returned list will contain backup jobs that have been parsed and filtered based on O(vm_name) value.
+ - Mutually exclusive with O(vm_id) and O(backup_jobs).
+ type: str
+ vm_id:
+ description:
+ - The ID of the Proxmox VM.
+ - If defined, the returned list will contain backup jobs that have been parsed and filtered based on O(vm_id) value.
+ - Mutually exclusive with O(vm_name) and O(backup_jobs).
+ type: str
+ backup_jobs:
+ description:
+ - If V(true), the module will return all backup jobs information.
+ - If V(false), the module will parse all backup jobs based on VM IDs and return a list of VMs' backup information.
+ - Mutually exclusive with O(vm_id) and O(vm_name).
+ default: false
+ type: bool
+
+extends_documentation_fragment:
+ - community.general.proxmox.documentation
+ - community.general.attributes
+ - community.general.attributes.info_module
+ - community.general.proxmox.actiongroup_proxmox
+"""
+
+EXAMPLES = """
+- name: Print all backup information by VM ID and VM name
+ community.general.proxmox_backup_info:
+ api_user: 'myUser@pam'
+ api_password: '*******'
+ api_host: '192.168.20.20'
+
+- name: Print Proxmox backup information for a specific VM based on its name
+ community.general.proxmox_backup_info:
+ api_user: 'myUser@pam'
+ api_password: '*******'
+ api_host: '192.168.20.20'
+ vm_name: 'mailsrv'
+
+- name: Print Proxmox backup information for a specific VM based on its VM ID
+ community.general.proxmox_backup_info:
+ api_user: 'myUser@pam'
+ api_password: '*******'
+ api_host: '192.168.20.20'
+ vm_id: '150'
+
+- name: Print Proxmox all backup job information
+ community.general.proxmox_backup_info:
+ api_user: 'myUser@pam'
+ api_password: '*******'
+ api_host: '192.168.20.20'
+ backup_jobs: true
+"""
+
+RETURN = """
+---
+backup_info:
+ description: The return value provides backup job information based on VM ID or VM name, or total backup job information.
+ returned: on success, but can be empty
+ type: list
+ elements: dict
+ contains:
+ bktype:
+ description: The type of the backup.
+ returned: on success
+ type: str
+ sample: vzdump
+ enabled:
+ description: V(1) if backup is enabled else V(0).
+ returned: on success
+ type: int
+ sample: 1
+ id:
+ description: The backup job ID.
+ returned: on success
+ type: str
+ sample: backup-83831498-c631
+ mode:
+ description: The backup job mode such as snapshot.
+ returned: on success
+ type: str
+ sample: snapshot
+ next-run:
+ description: The next backup time.
+ returned: on success
+ type: str
+ sample: "2024-12-28 11:30:00"
+ schedule:
+ description: The backup job schedule.
+ returned: on success
+ type: str
+ sample: "sat 15:00"
+ storage:
+ description: The backup storage location.
+ returned: on success
+ type: str
+ sample: local
+ vm_name:
+ description: The VM name.
+ returned: on success
+ type: str
+ sample: test01
+ vmid:
+ description: The VM ID.
+ returned: on success
+ type: str
+ sample: "100"
+"""
+
+from datetime import datetime
+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)
+
+
+class ProxmoxBackupInfoAnsible(ProxmoxAnsible):
+
+ # Get all backup information
+ def get_jobs_list(self):
+ try:
+ backupJobs = self.proxmox_api.cluster.backup.get()
+ except Exception as e:
+ self.module.fail_json(msg="Getting backup jobs failed: %s" % e)
+ return backupJobs
+
+ # Get VM information
+ def get_vms_list(self):
+ try:
+ vms = self.proxmox_api.cluster.resources.get(type='vm')
+ except Exception as e:
+ self.module.fail_json(msg="Getting VMs info from cluster failed: %s" % e)
+ return vms
+
+ # Get all backup information by VM ID and VM name
+ def vms_backup_info(self):
+ backupList = self.get_jobs_list()
+ vmInfo = self.get_vms_list()
+ bkInfo = []
+ for backupItem in backupList:
+ nextrun = datetime.fromtimestamp(backupItem['next-run'])
+ vmids = backupItem['vmid'].split(',')
+ for vmid in vmids:
+ for vm in vmInfo:
+ if vm['vmid'] == int(vmid):
+ vmName = vm['name']
+ break
+ bkInfoData = {'id': backupItem['id'],
+ 'schedule': backupItem['schedule'],
+ 'storage': backupItem['storage'],
+ 'mode': backupItem['mode'],
+ 'next-run': nextrun.strftime("%Y-%m-%d %H:%M:%S"),
+ 'enabled': backupItem['enabled'],
+ 'bktype': backupItem['type'],
+ 'vmid': vmid,
+ 'vm_name': vmName}
+ bkInfo.append(bkInfoData)
+ return bkInfo
+
+ # Get proxmox backup information for a specific VM based on its VM ID or VM name
+ def specific_vmbackup_info(self, vm_name_id):
+ fullBackupInfo = self.vms_backup_info()
+ vmBackupJobs = []
+ for vm in fullBackupInfo:
+ if (vm["vm_name"] == vm_name_id or vm["vmid"] == vm_name_id):
+ vmBackupJobs.append(vm)
+ return vmBackupJobs
+
+
+def main():
+ # Define module args
+ args = proxmox_auth_argument_spec()
+ backup_info_args = dict(
+ vm_id=dict(type='str'),
+ vm_name=dict(type='str'),
+ backup_jobs=dict(type='bool', default=False)
+ )
+ args.update(backup_info_args)
+
+ module = AnsibleModule(
+ argument_spec=args,
+ mutually_exclusive=[('backup_jobs', 'vm_id', 'vm_name')],
+ supports_check_mode=True
+ )
+
+ # Define (init) result value
+ result = dict(
+ changed=False
+ )
+
+ # Check if proxmoxer exist
+ if not HAS_PROXMOXER:
+ module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
+
+ # Start to connect to proxmox to get backup data
+ proxmox = ProxmoxBackupInfoAnsible(module)
+ vm_id = module.params['vm_id']
+ vm_name = module.params['vm_name']
+ backup_jobs = module.params['backup_jobs']
+
+ # Update result value based on what requested (module args)
+ if backup_jobs:
+ result['backup_info'] = proxmox.get_jobs_list()
+ elif vm_id:
+ result['backup_info'] = proxmox.specific_vmbackup_info(vm_id)
+ elif vm_name:
+ result['backup_info'] = proxmox.specific_vmbackup_info(vm_name)
+ else:
+ result['backup_info'] = proxmox.vms_backup_info()
+
+ # Return result value
+ module.exit_json(**result)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/plugins/modules/proxmox_disk.py b/plugins/modules/proxmox_disk.py
index a4a9dd8791..8bf8e96108 100644
--- a/plugins/modules/proxmox_disk.py
+++ b/plugins/modules/proxmox_disk.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: proxmox_disk
short_description: Management of a disk of a Qemu(KVM) VM in a Proxmox VE cluster
version_added: 5.7.0
@@ -38,31 +37,22 @@ options:
description:
- The disk key (V(unused[n]), V(ide[n]), V(sata[n]), V(scsi[n]) or V(virtio[n])) you want to operate on.
- Disk buses (IDE, SATA and so on) have fixed ranges of V(n) that accepted by Proxmox API.
- - >
- For IDE: 0-3;
- for SCSI: 0-30;
- for SATA: 0-5;
- for VirtIO: 0-15;
- for Unused: 0-255.
+ - 'For IDE: 0-3; for SCSI: 0-30; for SATA: 0-5; for VirtIO: 0-15; for Unused: 0-255.'
type: str
required: true
state:
description:
- Indicates desired state of the disk.
- - >
- O(state=present) can be used to create, replace disk or update options in existing disk. It will create missing
- disk or update options in existing one by default. See the O(create) parameter description to control behavior
- of this option.
+ - O(state=present) can be used to create, replace disk or update options in existing disk. It will create missing disk
+ or update options in existing one by default. See the O(create) parameter description to control behavior of this
+ option.
- Some updates on options (like O(cache)) are not being applied instantly and require VM restart.
- - >
- Use O(state=detached) to detach existing disk from VM but do not remove it entirely.
- When O(state=detached) and disk is V(unused[n]) it will be left in same state (not removed).
- - >
- O(state=moved) may be used to change backing storage for the disk in bounds of the same VM
- or to send the disk to another VM (using the same backing storage).
- - >
- O(state=resized) intended to change the disk size. As of Proxmox 7.2 you can only increase the disk size
- because shrinking disks is not supported by the PVE API and has to be done manually.
+ - Use O(state=detached) to detach existing disk from VM but do not remove it entirely. When O(state=detached) and disk
+ is V(unused[n]) it will be left in same state (not removed).
+ - O(state=moved) may be used to change backing storage for the disk in bounds of the same VM or to send the disk to
+ another VM (using the same backing storage).
+ - O(state=resized) intended to change the disk size. As of Proxmox 7.2 you can only increase the disk size because shrinking
+ disks is not supported by the PVE API and has to be done manually.
- To entirely remove the disk from backing storage use O(state=absent).
type: str
choices: ['present', 'resized', 'detached', 'moved', 'absent']
@@ -84,10 +74,8 @@ options:
size:
description:
- Desired volume size in GB to allocate when O(state=present) (specify O(size) without suffix).
- - >
- New (or additional) size of volume when O(state=resized). With the V(+) sign
- the value is added to the actual size of the volume
- and without it, the value is taken as an absolute one.
+ - New (or additional) size of volume when O(state=resized). With the V(+) sign the value is added to the actual size
+ of the volume and without it, the value is taken as an absolute one.
type: str
bwlimit:
description:
@@ -176,8 +164,8 @@ options:
import_from:
description:
- Import volume from this existing one.
- - Volume string format
- - C(:/) or C(/)
+ - Volume string format.
+ - V(:/) or V(/).
- Attention! Only root can use absolute paths.
- This parameter is mutually exclusive with O(size).
- Increase O(timeout) parameter when importing large disk images or using slow storage.
@@ -223,7 +211,7 @@ options:
type: int
iothread:
description:
- - Whether to use iothreads for this drive (only for SCSI and VirtIO)
+ - Whether to use iothreads for this drive (only for SCSI and VirtIO).
type: bool
mbps:
description:
@@ -262,10 +250,9 @@ options:
description:
- The ISO image to be mounted on the specified in O(disk) CD-ROM.
- O(media=cdrom) needs to be specified for this option to work.
- - "Image string format:"
- - V(:iso/) to mount ISO.
- - V(cdrom) to use physical CD/DVD drive.
- - V(none) to unmount image from existent CD-ROM or create empty CD-ROM drive.
+ - Use V(:iso/) to mount ISO.
+ - Use V(cdrom) to access the physical CD/DVD drive.
+ - Use V(none) to unmount image from existent CD-ROM or create empty CD-ROM drive.
type: str
version_added: 8.1.0
queues:
@@ -330,9 +317,9 @@ extends_documentation_fragment:
- community.general.proxmox.actiongroup_proxmox
- community.general.proxmox.documentation
- community.general.attributes
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create new disk in VM (do not rewrite in case it exists already)
community.general.proxmox_disk:
api_host: node1
@@ -437,9 +424,9 @@ EXAMPLES = '''
media: cdrom
iso_image: local:iso/favorite_distro_amd64.iso
state: present
-'''
+"""
-RETURN = '''
+RETURN = r"""
vmid:
description: The VM vmid.
returned: success
@@ -450,13 +437,14 @@ msg:
returned: always
type: str
sample: "Disk scsi3 created in VM 101"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec,
ProxmoxAnsible)
from re import compile, match, sub
-from time import sleep
def disk_conf_str_to_dict(config_string):
@@ -531,17 +519,18 @@ class ProxmoxDiskAnsible(ProxmoxAnsible):
}
return params
- def wait_till_complete_or_timeout(self, node_name, task_id):
- timeout = self.module.params['timeout']
- while timeout:
- if self.api_task_ok(node_name, task_id):
- return True
- timeout -= 1
- if timeout <= 0:
- return False
- sleep(1)
-
def create_disk(self, disk, vmid, vm, vm_config):
+ """Create a disk in the specified virtual machine. Check if creation is required,
+ and if so, compile the disk configuration and create it by updating the virtual
+ machine configuration. After calling the API function, wait for the result.
+
+ :param disk: ID of the disk in format "".
+ :param vmid: ID of the virtual machine where the disk will be created.
+ :param vm: Name of the virtual machine where the disk will be created.
+ :param vm_config: Configuration of the virtual machine.
+ :return: (bool, string) Whether the task was successful or not
+ and the message to return to Ansible.
+ """
create = self.module.params['create']
if create == 'disabled' and disk not in vm_config:
# NOOP
@@ -610,15 +599,31 @@ class ProxmoxDiskAnsible(ProxmoxAnsible):
disk_config_to_apply = {self.module.params["disk"]: config_str}
current_task_id = self.proxmox_api.nodes(vm['node']).qemu(vmid).config.post(**disk_config_to_apply)
- task_success = self.wait_till_complete_or_timeout(vm['node'], current_task_id)
+ task_success, fail_reason = self.api_task_complete(vm['node'], current_task_id, self.module.params['timeout'])
+
if task_success:
return True, ok_str % (disk, vmid)
else:
- self.module.fail_json(
- msg=timeout_str % self.proxmox_api.nodes(vm['node']).tasks(current_task_id).log.get()[:1]
- )
+ if fail_reason == ProxmoxAnsible.TASK_TIMED_OUT:
+ self.module.fail_json(
+ msg=timeout_str % self.proxmox_api.nodes(vm['node']).tasks(current_task_id).log.get()[:1]
+ )
+ else:
+ self.module.fail_json(msg="Error occurred on task execution: %s" % fail_reason)
def move_disk(self, disk, vmid, vm, vm_config):
+ """Call the `move_disk` API function that moves the disk to another storage and wait for the result.
+
+ :param disk: ID of disk in format "".
+ :param vmid: ID of virtual machine which disk will be moved.
+ :param vm: Name of virtual machine which disk will be moved.
+ :param vm_config: Virtual machine configuration.
+ :return: (bool, string) Whether the task was successful or not
+ and the message to return to Ansible.
+ """
+ disk_config = disk_conf_str_to_dict(vm_config[disk])
+ disk_storage = disk_config["storage_name"]
+
params = dict()
params['disk'] = disk
params['vmid'] = vmid
@@ -632,19 +637,62 @@ class ProxmoxDiskAnsible(ProxmoxAnsible):
params = {k: v for k, v in params.items() if v is not None}
if params.get('storage', False):
+ # Check if the disk is already in the target storage.
disk_config = disk_conf_str_to_dict(vm_config[disk])
if params['storage'] == disk_config['storage_name']:
- return False
+ return False, "Disk %s already at %s storage" % (disk, disk_storage)
+
+ current_task_id = self.proxmox_api.nodes(vm['node']).qemu(vmid).move_disk.post(**params)
+ task_success, fail_reason = self.api_task_complete(vm['node'], current_task_id, self.module.params['timeout'])
- task_id = self.proxmox_api.nodes(vm['node']).qemu(vmid).move_disk.post(**params)
- task_success = self.wait_till_complete_or_timeout(vm['node'], task_id)
if task_success:
- return True
+ return True, "Disk %s moved from VM %s storage %s" % (disk, vmid, disk_storage)
else:
- self.module.fail_json(
- msg='Reached timeout while waiting for moving VM disk. Last line in task before timeout: %s' %
- self.proxmox_api.nodes(vm['node']).tasks(task_id).log.get()[:1]
- )
+ if fail_reason == ProxmoxAnsible.TASK_TIMED_OUT:
+ self.module.fail_json(
+ msg='Reached timeout while waiting for moving VM disk. Last line in task before timeout: %s' %
+ self.proxmox_api.nodes(vm['node']).tasks(current_task_id).log.get()[:1]
+ )
+ else:
+ self.module.fail_json(msg="Error occurred on task execution: %s" % fail_reason)
+
+ def resize_disk(self, disk, vmid, vm, vm_config):
+ """Call the `resize` API function to change the disk size and wait for the result.
+
+ :param disk: ID of disk in format "".
+ :param vmid: ID of virtual machine which disk will be resized.
+ :param vm: Name of virtual machine which disk will be resized.
+ :param vm_config: Virtual machine configuration.
+ :return: (Bool, string) Whether the task was successful or not
+ and the message to return to Ansible.
+ """
+ size = self.module.params['size']
+ if not match(r'^\+?\d+(\.\d+)?[KMGT]?$', size):
+ self.module.fail_json(msg="Unrecognized size pattern for disk %s: %s" % (disk, size))
+ disk_config = disk_conf_str_to_dict(vm_config[disk])
+ actual_size = disk_config['size']
+ if size == actual_size:
+ return False, "Disk %s is already %s size" % (disk, size)
+
+ # Resize disk API endpoint has changed at v8.0: PUT method become async.
+ version = self.version()
+ pve_major_version = 3 if version < LooseVersion('4.0') else version.version[0]
+ if pve_major_version >= 8:
+ current_task_id = self.proxmox_api.nodes(vm['node']).qemu(vmid).resize.set(disk=disk, size=size)
+ task_success, fail_reason = self.api_task_complete(vm['node'], current_task_id, self.module.params['timeout'])
+ if task_success:
+ return True, "Disk %s resized in VM %s" % (disk, vmid)
+ else:
+ if fail_reason == ProxmoxAnsible.TASK_TIMED_OUT:
+ self.module.fail_json(
+ msg="Reached timeout while resizing disk. Last line in task before timeout: %s" %
+ self.proxmox_api.nodes(vm['node']).tasks(current_task_id).log.get()[:1]
+ )
+ else:
+ self.module.fail_json(msg="Error occurred on task execution: %s" % fail_reason)
+ else:
+ self.proxmox_api.nodes(vm['node']).qemu(vmid).resize.set(disk=disk, size=size)
+ return True, "Disk %s resized in VM %s" % (disk, vmid)
def main():
@@ -783,11 +831,8 @@ def main():
if state == 'present':
try:
- success, message = proxmox.create_disk(disk, vmid, vm, vm_config)
- if success:
- module.exit_json(changed=True, vmid=vmid, msg=message)
- else:
- module.exit_json(changed=False, vmid=vmid, msg=message)
+ changed, message = proxmox.create_disk(disk, vmid, vm, vm_config)
+ module.exit_json(changed=changed, vmid=vmid, msg=message)
except Exception as e:
module.fail_json(vmid=vmid, msg='Unable to create/update disk %s in VM %s: %s' % (disk, vmid, str(e)))
@@ -804,27 +849,15 @@ def main():
elif state == 'moved':
try:
- disk_config = disk_conf_str_to_dict(vm_config[disk])
- disk_storage = disk_config["storage_name"]
- if proxmox.move_disk(disk, vmid, vm, vm_config):
- module.exit_json(changed=True, vmid=vmid,
- msg="Disk %s moved from VM %s storage %s" % (disk, vmid, disk_storage))
- else:
- module.exit_json(changed=False, vmid=vmid, msg="Disk %s already at %s storage" % (disk, disk_storage))
+ changed, message = proxmox.move_disk(disk, vmid, vm, vm_config)
+ module.exit_json(changed=changed, vmid=vmid, msg=message)
except Exception as e:
module.fail_json(msg="Failed to move disk %s in VM %s with exception: %s" % (disk, vmid, str(e)))
elif state == 'resized':
try:
- size = module.params['size']
- if not match(r'^\+?\d+(\.\d+)?[KMGT]?$', size):
- module.fail_json(msg="Unrecognized size pattern for disk %s: %s" % (disk, size))
- disk_config = disk_conf_str_to_dict(vm_config[disk])
- actual_size = disk_config['size']
- if size == actual_size:
- module.exit_json(changed=False, vmid=vmid, msg="Disk %s is already %s size" % (disk, size))
- proxmox.proxmox_api.nodes(vm['node']).qemu(vmid).resize.set(disk=disk, size=size)
- module.exit_json(changed=True, vmid=vmid, msg="Disk %s resized in VM %s" % (disk, vmid))
+ changed, message = proxmox.resize_disk(disk, vmid, vm, vm_config)
+ module.exit_json(changed=changed, vmid=vmid, msg=message)
except Exception as e:
module.fail_json(msg="Failed to resize disk %s in VM %s with exception: %s" % (disk, vmid, str(e)))
diff --git a/plugins/modules/proxmox_domain_info.py b/plugins/modules/proxmox_domain_info.py
index f3ff212bff..d9836da277 100644
--- a/plugins/modules/proxmox_domain_info.py
+++ b/plugins/modules/proxmox_domain_info.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: proxmox_domain_info
short_description: Retrieve information about one or more Proxmox VE domains
version_added: 1.3.0
@@ -31,10 +30,10 @@ extends_documentation_fragment:
- community.general.proxmox.documentation
- community.general.attributes
- community.general.attributes.info_module
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List existing domains
community.general.proxmox_domain_info:
api_host: helldorado
@@ -53,33 +52,33 @@ EXAMPLES = '''
api_token_secret: "{{ token_secret | default(omit) }}"
domain: pve
register: proxmox_domain_pve
-'''
+"""
-RETURN = '''
+RETURN = r"""
proxmox_domains:
- description: List of authentication domains.
- returned: always, but can be empty
- type: list
- elements: dict
- contains:
- comment:
- description: Short description of the realm.
- returned: on success
- type: str
- realm:
- description: Realm name.
- returned: on success
- type: str
- type:
- description: Realm type.
- returned: on success
- type: str
- digest:
- description: Realm hash.
- returned: on success, can be absent
- type: str
-'''
+ description: List of authentication domains.
+ returned: always, but can be empty
+ type: list
+ elements: dict
+ contains:
+ comment:
+ description: Short description of the realm.
+ returned: on success
+ type: str
+ realm:
+ description: Realm name.
+ returned: on success
+ type: str
+ type:
+ description: Realm type.
+ returned: on success
+ type: str
+ digest:
+ description: Realm hash.
+ returned: on success, can be absent
+ type: str
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/proxmox_group_info.py b/plugins/modules/proxmox_group_info.py
index eda1fe04d8..f62d467af8 100644
--- a/plugins/modules/proxmox_group_info.py
+++ b/plugins/modules/proxmox_group_info.py
@@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: proxmox_group_info
short_description: Retrieve information about one or more Proxmox VE groups
version_added: 1.3.0
description:
- - Retrieve information about one or more Proxmox VE groups
+ - Retrieve information about one or more Proxmox VE groups.
attributes:
action_group:
version_added: 9.0.0
@@ -31,10 +30,10 @@ extends_documentation_fragment:
- community.general.proxmox.documentation
- community.general.attributes
- community.general.attributes.info_module
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List existing groups
community.general.proxmox_group_info:
api_host: helldorado
@@ -53,30 +52,30 @@ EXAMPLES = '''
api_token_secret: "{{ token_secret | default(omit) }}"
group: admin
register: proxmox_group_admin
-'''
+"""
-RETURN = '''
+RETURN = r"""
proxmox_groups:
- description: List of groups.
- returned: always, but can be empty
- type: list
- elements: dict
- contains:
- comment:
- description: Short description of the group.
- returned: on success, can be absent
- type: str
- groupid:
- description: Group name.
- returned: on success
- type: str
- users:
- description: List of users in the group.
- returned: on success
- type: list
- elements: str
-'''
+ description: List of groups.
+ returned: always, but can be empty
+ type: list
+ elements: dict
+ contains:
+ comment:
+ description: Short description of the group.
+ returned: on success, can be absent
+ type: str
+ groupid:
+ description: Group name.
+ returned: on success
+ type: str
+ users:
+ description: List of users in the group.
+ returned: on success
+ type: list
+ elements: str
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/proxmox_kvm.py b/plugins/modules/proxmox_kvm.py
index 0c9904873d..714633eaa2 100644
--- a/plugins/modules/proxmox_kvm.py
+++ b/plugins/modules/proxmox_kvm.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: proxmox_kvm
short_description: Management of Qemu(KVM) Virtual Machines in Proxmox VE cluster
description:
@@ -36,14 +35,23 @@ options:
agent:
description:
- Specify if the QEMU Guest Agent should be enabled/disabled.
- - Since community.general 5.5.0, this can also be a string instead of a boolean.
- This allows to specify values such as V(enabled=1,fstrim_cloned_disks=1).
+ - Since community.general 5.5.0, this can also be a string instead of a boolean. This allows to specify values such
+ as V(enabled=1,fstrim_cloned_disks=1).
type: str
args:
description:
- Pass arbitrary arguments to kvm.
- This option is for experts only!
type: str
+ audio:
+ description:
+ - A hash/dictionary of audio devices for the VM. O(audio={"key":"value", "key":"value"}).
+ - Keys allowed are - C(audio[n]) where 0 ≤ n ≤ N.
+ - Values allowed are - C(device="ich9-intel-hda|intel-hda|AC97",driver="none|spice").
+ - C(device) is either V(ich9-intel-hda) or V(intel-hda) or V(AC97).
+ - Option C(driver) is V(none) or V(spice).
+ type: dict
+ version_added: 10.5.0
autostart:
description:
- Specify if the VM should be automatically restarted after crash (currently ignored in PVE API).
@@ -66,21 +74,21 @@ options:
type: str
bootdisk:
description:
- - 'Enable booting from specified disk. Format V((ide|sata|scsi|virtio\)\\d+).'
+ - Enable booting from specified disk. Format V((ide|sata|scsi|virtio\)\\d+).
type: str
cicustom:
description:
- - 'cloud-init: Specify custom files to replace the automatically generated ones at start.'
+ - 'Cloud-init: Specify custom files to replace the automatically generated ones at start.'
type: str
version_added: 1.3.0
cipassword:
description:
- - 'cloud-init: password of default user to create.'
+ - 'Cloud-init: password of default user to create.'
type: str
version_added: 1.3.0
citype:
description:
- - 'cloud-init: Specifies the cloud-init configuration format.'
+ - 'Cloud-init: Specifies the cloud-init configuration format.'
- The default depends on the configured operating system type (V(ostype)).
- We use the V(nocloud) format for Linux, and V(configdrive2) for Windows.
type: str
@@ -88,17 +96,18 @@ options:
version_added: 1.3.0
ciupgrade:
description:
- - 'cloud-init: do an automatic package upgrade after the first boot.'
+ - 'Cloud-init: do an automatic package upgrade after the first boot.'
type: bool
version_added: 10.0.0
ciuser:
description:
- - 'cloud-init: username of default user to create.'
+ - 'Cloud-init: username of default user to create.'
type: str
version_added: 1.3.0
clone:
description:
- - Name of VM to be cloned. If O(vmid) is set, O(clone) can take an arbitrary value but is required for initiating the clone.
+ - Name of VM to be cloned. If O(vmid) is set, O(clone) can take an arbitrary value but is required for initiating the
+ clone.
type: str
cores:
description:
@@ -110,13 +119,13 @@ options:
type: str
cpulimit:
description:
- - Specify if CPU usage will be limited. Value 0 indicates no CPU limit.
- - If the computer has 2 CPUs, it has total of '2' CPU time
+ - Specify if CPU usage will be limited. Value V(0) indicates no CPU limit.
+ - If the computer has 2 CPUs, it has total of '2' CPU time.
type: int
cpuunits:
description:
- Specify CPU weight for a VM.
- - You can disable fair-scheduler configuration by setting this to 0
+ - You can disable fair-scheduler configuration by setting this to V(0).
type: int
delete:
description:
@@ -144,24 +153,24 @@ options:
type: str
format:
description:
- - V(format) is the drive's backing file's data format. Please refer to the Proxmox VE Administrator Guide,
- section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest
- version, tables 3 to 14) to find out format supported by the provided storage backend.
+ - V(format) is the drive's backing file's data format. Please refer to the Proxmox VE Administrator Guide, section
+ Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version, tables
+ 3 to 14) to find out format supported by the provided storage backend.
type: str
efitype:
description:
- V(efitype) indicates the size of the EFI disk.
- V(2m) will allow for a 2MB EFI disk, which will be enough to persist boot order and new boot entries.
- - V(4m) will allow for a 4MB EFI disk, which will additionally allow to store EFI keys in order to enable
- Secure Boot
+ - V(4m) will allow for a 4MB EFI disk, which will additionally allow to store EFI keys in order to enable Secure
+ Boot.
type: str
choices:
- 2m
- 4m
pre_enrolled_keys:
description:
- - V(pre_enrolled_keys) indicates whether EFI keys for Secure Boot should be enrolled V(1) in the VM firmware
- upon creation or not (0).
+ - V(pre_enrolled_keys) indicates whether EFI keys for Secure Boot should be enrolled V(1) in the VM firmware upon
+ creation or not (0).
- If set to V(1), Secure Boot will also be enabled by default when the VM is created.
type: bool
version_added: 4.5.0
@@ -174,14 +183,13 @@ options:
format:
description:
- Target drive's backing file's data format.
- - Used only with clone
+ - Used only with clone.
- Use O(format=unspecified) and O(full=false) for a linked clone.
- - Please refer to the Proxmox VE Administrator Guide, section Proxmox VE Storage (see
- U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version, tables 3 to 14) to find out format
- supported by the provided storage backend.
+ - Please refer to the Proxmox VE Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html)
+ for the latest version, tables 3 to 14) to find out format supported by the provided storage backend.
- Not specifying this option is equivalent to setting it to V(unspecified).
type: str
- choices: [ "cloop", "cow", "qcow", "qcow2", "qed", "raw", "vmdk", "unspecified" ]
+ choices: ["cloop", "cow", "qcow", "qcow2", "qed", "raw", "vmdk", "unspecified"]
freeze:
description:
- Specify if PVE should freeze CPU at startup (use 'c' monitor command to start execution).
@@ -190,7 +198,7 @@ options:
description:
- Create a full copy of all disk. This is always done when you clone a normal VM.
- For VM templates, we try to create a linked clone by default.
- - Used only with clone
+ - Used only with clone.
type: bool
default: true
hookscript:
@@ -202,12 +210,13 @@ options:
description:
- Specify a hash/dictionary of map host pci devices into guest. O(hostpci='{"key":"value", "key":"value"}').
- Keys allowed are - C(hostpci[n]) where 0 ≤ n ≤ N.
- - Values allowed are - C("host="HOSTPCIID[;HOSTPCIID2...]",pcie="1|0",rombar="1|0",x-vga="1|0"").
- - The C(host) parameter is Host PCI device pass through. HOSTPCIID syntax is C(bus:dev.func) (hexadecimal numbers).
- - C(pcie=boolean) C(default=0) Choose the PCI-express bus (needs the q35 machine model).
- - C(rombar=boolean) C(default=1) Specify whether or not the device's ROM will be visible in the guest's memory map.
- - C(x-vga=boolean) C(default=0) Enable vfio-vga device support.
- - /!\ This option allows direct access to host hardware. So it is no longer possible to migrate such machines - use with special care.
+ - Values allowed are - V("host="HOSTPCIID[;HOSTPCIID2...]",pcie="1|0",rombar="1|0",x-vga="1|0"").
+ - The C(host) parameter is Host PCI device pass through. HOSTPCIID syntax is V(bus:dev.func) (hexadecimal numbers).
+ - V(pcie=boolean) V(default=0) Choose the PCI-express bus (needs the q35 machine model).
+ - V(rombar=boolean) V(default=1) Specify whether or not the device's ROM will be visible in the guest's memory map.
+ - V(x-vga=boolean) V(default=0) Enable vfio-vga device support.
+ - /!\ This option allows direct access to host hardware. So it is no longer possible to migrate such machines - use
+ with special care.
type: dict
hotplug:
description:
@@ -223,24 +232,24 @@ options:
ide:
description:
- A hash/dictionary of volume used as IDE hard disk or CD-ROM. O(ide='{"key":"value", "key":"value"}').
- - Keys allowed are - C(ide[n]) where 0 ≤ n ≤ 3.
- - Values allowed are - C("storage:size,format=value").
- - C(storage) is the storage identifier where to create the disk.
- - C(size) is the size of the disk in GB.
- - C(format) is the drive's backing file's data format. C(qcow2|raw|subvol). Please refer to the Proxmox VE
- Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for
- the latest version, tables 3 to 14) to find out format supported by the provided storage backend.
+ - Keys allowed are - V(ide[n]) where 0 ≤ n ≤ 3.
+ - Values allowed are - V("storage:size,format=value").
+ - V(storage) is the storage identifier where to create the disk.
+ - V(size) is the size of the disk in GB.
+ - V(format) is the drive's backing file's data format. V(qcow2|raw|subvol). Please refer to the Proxmox VE Administrator
+ Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version,
+ tables 3 to 14) to find out format supported by the provided storage backend.
type: dict
ipconfig:
description:
- - 'cloud-init: Set the IP configuration.'
- - A hash/dictionary of network ip configurations. O(ipconfig='{"key":"value", "key":"value"}').
- - Keys allowed are - C(ipconfig[n]) where 0 ≤ n ≤ network interfaces.
- - Values allowed are - C("[gw=] [,gw6=] [,ip=] [,ip6=]").
- - 'cloud-init: Specify IP addresses and gateways for the corresponding interface.'
+ - 'Cloud-init: Set the IP configuration.'
+ - A hash/dictionary of network IP configurations. O(ipconfig='{"key":"value", "key":"value"}').
+ - Keys allowed are - V(ipconfig[n]) where 0 ≤ n ≤ network interfaces.
+ - Values allowed are - V("[gw=] [,gw6=] [,ip=] [,ip6=]").
+ - 'Cloud-init: Specify IP addresses and gateways for the corresponding interface.'
- IP addresses use CIDR notation, gateways are optional but they should be in the same subnet of specified IP address.
- - The special string 'dhcp' can be used for IP addresses to use DHCP, in which case no explicit gateway should be provided.
- - For IPv6 the special string 'auto' can be used to use stateless autoconfiguration.
+ - The special string V(dhcp) can be used for IP addresses to use DHCP, in which case no explicit gateway should be provided.
+ - For IPv6 the special string V(auto) can be used to use stateless autoconfiguration.
- If cloud-init is enabled and neither an IPv4 nor an IPv6 address is specified, it defaults to using dhcp on IPv4.
type: dict
version_added: 1.3.0
@@ -265,7 +274,7 @@ options:
machine:
description:
- Specifies the Qemu machine type.
- - 'Type => V((pc|pc(-i440fx\)?-\\d+\\.\\d+(\\.pxe\)?|q35|pc-q35-\\d+\\.\\d+(\\.pxe\)?\)).'
+ - Type => V((pc|pc(-i440fx\)?-\\d+\\.\\d+(\\.pxe\)?|q35|pc-q35-\\d+\\.\\d+(\\.pxe\)?\)).
type: str
memory:
description:
@@ -294,7 +303,7 @@ options:
type: str
nameservers:
description:
- - 'cloud-init: DNS server IP address(es).'
+ - 'Cloud-init: DNS server IP address(es).'
- If unset, PVE host settings are used.
type: list
elements: str
@@ -304,10 +313,13 @@ options:
- A hash/dictionary of network interfaces for the VM. O(net='{"key":"value", "key":"value"}').
- Keys allowed are - C(net[n]) where 0 ≤ n ≤ N.
- Values allowed are - C("model="XX:XX:XX:XX:XX:XX",bridge="value",rate="value",tag="value",firewall="1|0",trunks="vlanid"").
- - Model is one of C(e1000 e1000-82540em e1000-82544gc e1000-82545em i82551 i82557b i82559er ne2k_isa ne2k_pci pcnet rtl8139 virtio vmxnet3).
+ - Model is one of C(e1000 e1000-82540em e1000-82544gc e1000-82545em i82551 i82557b i82559er ne2k_isa ne2k_pci pcnet
+ rtl8139 virtio vmxnet3).
- C(XX:XX:XX:XX:XX:XX) should be an unique MAC address. This is automatically generated if not specified.
- - The C(bridge) parameter can be used to automatically add the interface to a bridge device. The Proxmox VE standard bridge is called 'vmbr0'.
- - Option C(rate) is used to limit traffic bandwidth from and to this interface. It is specified as floating point number, unit is 'Megabytes per second'.
+ - The C(bridge) parameter can be used to automatically add the interface to a bridge device. The Proxmox VE standard
+ bridge is called 'vmbr0'.
+ - Option C(rate) is used to limit traffic bandwidth from and to this interface. It is specified as floating point number,
+ unit is 'Megabytes per second'.
- If you specify no bridge, we create a kvm 'user' (NATed) network device, which provides DHCP and DNS services.
type: dict
newid:
@@ -318,12 +330,12 @@ options:
numa:
description:
- A hash/dictionaries of NUMA topology. O(numa='{"key":"value", "key":"value"}').
- - Keys allowed are - C(numa[n]) where 0 ≤ n ≤ N.
- - Values allowed are - C("cpu="",hostnodes="",memory="number",policy="(bind|interleave|preferred)"").
- - C(cpus) CPUs accessing this NUMA node.
- - C(hostnodes) Host NUMA nodes to use.
- - C(memory) Amount of memory this NUMA node provides.
- - C(policy) NUMA allocation policy.
+ - Keys allowed are - V(numa[n]) where 0 ≤ n ≤ N.
+ - Values allowed are - V("cpu="",hostnodes="",memory="number",policy="(bind|interleave|preferred)"").
+ - V(cpus) CPUs accessing this NUMA node.
+ - V(hostnodes) Host NUMA nodes to use.
+ - V(memory) Amount of memory this NUMA node provides.
+ - V(policy) NUMA allocation policy.
type: dict
numa_enabled:
description:
@@ -361,23 +373,23 @@ options:
description:
- A hash/dictionary of volume used as sata hard disk or CD-ROM. O(sata='{"key":"value", "key":"value"}').
- Keys allowed are - C(sata[n]) where 0 ≤ n ≤ 5.
- - Values allowed are - C("storage:size,format=value").
+ - Values allowed are - C("storage:size,format=value").
- C(storage) is the storage identifier where to create the disk.
- C(size) is the size of the disk in GB.
- - C(format) is the drive's backing file's data format. C(qcow2|raw|subvol). Please refer to the Proxmox VE
- Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for
- the latest version, tables 3 to 14) to find out format supported by the provided storage backend.
+ - C(format) is the drive's backing file's data format. C(qcow2|raw|subvol). Please refer to the Proxmox VE Administrator
+ Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version,
+ tables 3 to 14) to find out format supported by the provided storage backend.
type: dict
scsi:
description:
- A hash/dictionary of volume used as SCSI hard disk or CD-ROM. O(scsi='{"key":"value", "key":"value"}').
- Keys allowed are - C(scsi[n]) where 0 ≤ n ≤ 13.
- - Values allowed are - C("storage:size,format=value").
+ - Values allowed are - C("storage:size,format=value").
- C(storage) is the storage identifier where to create the disk.
- C(size) is the size of the disk in GB.
- - C(format) is the drive's backing file's data format. C(qcow2|raw|subvol). Please refer to the Proxmox VE
- Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for
- the latest version, tables 3 to 14) to find out format supported by the provided storage backend.
+ - C(format) is the drive's backing file's data format. C(qcow2|raw|subvol). Please refer to the Proxmox VE Administrator
+ Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version,
+ tables 3 to 14) to find out format supported by the provided storage backend.
type: dict
scsihw:
description:
@@ -386,7 +398,7 @@ options:
choices: ['lsi', 'lsi53c810', 'virtio-scsi-pci', 'virtio-scsi-single', 'megasas', 'pvscsi']
searchdomains:
description:
- - 'cloud-init: Sets DNS search domain(s).'
+ - 'Cloud-init: Sets DNS search domain(s).'
- If unset, PVE host settings are used.
type: list
elements: str
@@ -396,7 +408,8 @@ options:
- A hash/dictionary of serial device to create inside the VM. V('{"key":"value", "key":"value"}').
- Keys allowed are - serial[n](str; required) where 0 ≤ n ≤ 3.
- Values allowed are - V((/dev/.+|socket\)).
- - /!\ If you pass through a host serial device, it is no longer possible to migrate such machines - use with special care.
+ - /!\ If you pass through a host serial device, it is no longer possible to migrate such machines - use with special
+ care.
type: dict
shares:
description:
@@ -407,20 +420,20 @@ options:
type: int
skiplock:
description:
- - Ignore locks
+ - Ignore locks.
- Only root is allowed to use this option.
type: bool
smbios:
description:
- Specifies SMBIOS type 1 fields.
- - "Comma separated, Base64 encoded (optional) SMBIOS properties:"
- - V([base64=<1|0>] [,family=])
- - V([,manufacturer=])
- - V([,product=])
- - V([,serial=])
- - V([,sku=])
- - V([,uuid=])
- - V([,version=])
+ - Comma separated, Base64 encoded (optional) SMBIOS properties:.
+ - V([base64=<1|0>] [,family=]).
+ - V([,manufacturer=]).
+ - V([,product=]).
+ - V([,serial=]).
+ - V([,sku=]).
+ - V([,uuid=]).
+ - V([,version=]).
type: str
snapname:
description:
@@ -432,7 +445,7 @@ options:
type: int
sshkeys:
description:
- - 'cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work.'
+ - 'Cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work.'
type: str
version_added: 1.3.0
startdate:
@@ -449,10 +462,11 @@ options:
state:
description:
- Indicates desired state of the instance.
- - If V(current), the current state of the VM will be fetched. You can access it with C(results.status)
+ - If V(current), the current state of the VM will be fetched. You can access it with C(results.status).
- V(template) was added in community.general 8.1.0.
+ - V(paused) and V(hibernated) were added in community.general 10.4.0.
type: str
- choices: ['present', 'started', 'absent', 'stopped', 'restarted', 'current', 'template']
+ choices: ['present', 'started', 'absent', 'stopped', 'restarted', 'current', 'template', 'paused', 'hibernated']
default: present
storage:
description:
@@ -473,7 +487,7 @@ options:
target:
description:
- Target node. Only allowed if the original VM is on shared storage.
- - Used only with clone
+ - Used only with clone.
type: str
tdf:
description:
@@ -486,7 +500,8 @@ options:
timeout:
description:
- Timeout for operations.
- - When used with O(state=stopped) the option sets a graceful timeout for VM stop after which a VM will be forcefully stopped.
+ - When used with O(state=stopped) the option sets a graceful timeout for VM stop after which a VM will be forcefully
+ stopped.
type: int
default: 30
tpmstate0:
@@ -512,7 +527,7 @@ options:
- A hash/dictionary of USB devices for the VM. O(usb='{"key":"value", "key":"value"}').
- Keys allowed are - C(usb[n]) where 0 ≤ n ≤ N.
- Values allowed are - C(host="value|spice",mapping="value",usb3="1|0").
- - host is either C(spice) or the USB id/port.
+ - Host is either C(spice) or the USB id/port.
- Option C(mapping) is the mapped USB device name.
- Option C(usb3) enables USB 3 support.
type: dict
@@ -521,15 +536,16 @@ options:
description:
- If V(true), the VM will be updated with new value.
- Because of the operations of the API and security reasons, I have disabled the update of the following parameters
- O(net), O(virtio), O(ide), O(sata), O(scsi). Per example updating O(net) update the MAC address and C(virtio) create always new disk...
- This security feature can be disabled by setting the O(update_unsafe) to V(true).
+ O(net), O(virtio), O(ide), O(sata), O(scsi). Per example updating O(net) update the MAC address and O(virtio) create
+ always new disk... This security feature can be disabled by setting the O(update_unsafe) to V(true).
- Update of O(pool) is disabled. It needs an additional API endpoint not covered by this module.
type: bool
default: false
update_unsafe:
description:
- - If V(true), do not enforce limitations on parameters O(net), O(virtio), O(ide), O(sata), O(scsi), O(efidisk0), and O(tpmstate0).
- Use this option with caution because an improper configuration might result in a permanent loss of data (e.g. disk recreated).
+ - If V(true), do not enforce limitations on parameters O(net), O(virtio), O(ide), O(sata), O(scsi), O(efidisk0), and
+ O(tpmstate0). Use this option with caution because an improper configuration might result in a permanent loss of data
+ (for example disk recreated).
type: bool
default: false
version_added: 8.4.0
@@ -539,19 +555,19 @@ options:
type: int
vga:
description:
- - Select VGA type. If you want to use high resolution modes (>= 1280x1024x16) then you should use option 'std' or 'vmware'.
+ - Select VGA type. If you want to use high resolution modes (>= 1280x1024x16) then you should use option V(std) or V(vmware).
type: str
choices: ['std', 'cirrus', 'vmware', 'qxl', 'serial0', 'serial1', 'serial2', 'serial3', 'qxl2', 'qxl3', 'qxl4']
virtio:
description:
- A hash/dictionary of volume used as VIRTIO hard disk. O(virtio='{"key":"value", "key":"value"}').
- - Keys allowed are - C(virtio[n]) where 0 ≤ n ≤ 15.
- - Values allowed are - C("storage:size,format=value").
- - C(storage) is the storage identifier where to create the disk.
- - C(size) is the size of the disk in GB.
- - C(format) is the drive's backing file's data format. C(qcow2|raw|subvol). Please refer to the Proxmox VE
- Administrator Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html)
- for the latest version, tables 3 to 14) to find out format supported by the provided storage backend.
+ - Keys allowed are - V(virtio[n]) where 0 ≤ n ≤ 15.
+ - Values allowed are - V(storage:size,format=value).
+ - V(storage) is the storage identifier where to create the disk.
+ - V(size) is the size of the disk in GB.
+ - V(format) is the drive's backing file's data format. V(qcow2|raw|subvol). Please refer to the Proxmox VE Administrator
+ Guide, section Proxmox VE Storage (see U(https://pve.proxmox.com/pve-docs/chapter-pvesm.html) for the latest version,
+ tables 3 to 14) to find out format supported by the provided storage backend.
type: dict
watchdog:
description:
@@ -564,9 +580,9 @@ extends_documentation_fragment:
- community.general.proxmox.documentation
- community.general.proxmox.selection
- community.general.attributes
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create new VM with minimal options
community.general.proxmox_kvm:
api_user: root@pam
@@ -846,7 +862,7 @@ EXAMPLES = '''
cores: 8
memory: 16384
net:
- net0: virtio,bridge=vmbr1
+ net0: virtio,bridge=vmbr1
update: true
update_unsafe: true
@@ -886,10 +902,9 @@ EXAMPLES = '''
node: sabrewulf
hookscript: local:snippets/hookscript.pl
update: true
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
vmid:
description: The VM vmid.
returned: success
@@ -901,11 +916,11 @@ status:
type: str
sample: running
msg:
- description: A short message
+ description: A short message.
returned: always
type: str
sample: "VM kropta with vmid = 110 is running"
-'''
+"""
import re
import time
@@ -1057,7 +1072,7 @@ class ProxmoxKvmAnsible(ProxmoxAnsible):
if ('bios' not in kwargs) or ('ovmf' != kwargs['bios']):
self.module.fail_json(msg='efidisk0 cannot be used if bios is not set to ovmf. ')
- # Flatten efidisk0 option to a string so that it's a string which is what Proxmoxer and the API expect
+ # Flatten efidisk0 option to a string so that it is a string which is what Proxmoxer and the API expect
if 'efidisk0' in kwargs:
efidisk0_str = ''
# Regexp to catch underscores in keys name, to replace them after by hyphens
@@ -1072,7 +1087,7 @@ class ProxmoxKvmAnsible(ProxmoxAnsible):
if 'storage' != k])
kwargs['efidisk0'] = efidisk0_str
- # Flatten tpmstate0 option to a string so that it's a string which is what Proxmoxer and the API expect
+ # Flatten tpmstate0 option to a string so that it is a string which is what Proxmoxer and the API expect
if 'tpmstate0' in kwargs:
kwargs['tpmstate0'] = '{storage}:1,version=v{version}'.format(
storage=kwargs['tpmstate0'].get('storage'),
@@ -1080,7 +1095,7 @@ class ProxmoxKvmAnsible(ProxmoxAnsible):
)
# Convert all dict in kwargs to elements.
- # For hostpci[n], ide[n], net[n], numa[n], parallel[n], sata[n], scsi[n], serial[n], virtio[n], ipconfig[n], usb[n]
+ # For audio[n], hostpci[n], ide[n], net[n], numa[n], parallel[n], sata[n], scsi[n], serial[n], virtio[n], ipconfig[n], usb[n]
for k in list(kwargs.keys()):
if isinstance(kwargs[k], dict):
kwargs.update(kwargs[k])
@@ -1203,6 +1218,16 @@ class ProxmoxKvmAnsible(ProxmoxAnsible):
return False
return True
+ def suspend_vm(self, vm, timeout, todisk):
+ vmid = vm['vmid']
+ proxmox_node = self.proxmox_api.nodes(vm['node'])
+ taskid = proxmox_node.qemu(vmid).status.suspend.post(todisk=(1 if todisk else 0), timeout=timeout)
+ if not self.wait_for_task(vm['node'], taskid):
+ self.module.fail_json(msg='Reached timeout while waiting for suspending VM. Last line in task before timeout: %s' %
+ proxmox_node.tasks(taskid).log.get()[:1])
+ return False
+ return True
+
def main():
module_args = proxmox_auth_argument_spec()
@@ -1211,6 +1236,7 @@ def main():
acpi=dict(type='bool'),
agent=dict(type='str'),
args=dict(type='str'),
+ audio=dict(type='dict'),
autostart=dict(type='bool'),
balloon=dict(type='int'),
bios=dict(choices=['seabios', 'ovmf']),
@@ -1282,7 +1308,7 @@ def main():
sshkeys=dict(type='str', no_log=False),
startdate=dict(type='str'),
startup=dict(),
- state=dict(default='present', choices=['present', 'absent', 'stopped', 'started', 'restarted', 'current', 'template']),
+ state=dict(default='present', choices=['present', 'absent', 'stopped', 'started', 'restarted', 'current', 'template', 'paused', 'hibernated']),
storage=dict(type='str'),
tablet=dict(type='bool'),
tags=dict(type='list', elements='str'),
@@ -1419,6 +1445,7 @@ def main():
archive=module.params['archive'],
acpi=module.params['acpi'],
agent=module.params['agent'],
+ audio=module.params['audio'],
autostart=module.params['autostart'],
balloon=module.params['balloon'],
bios=module.params['bios'],
@@ -1606,6 +1633,23 @@ def main():
if status:
module.exit_json(changed=False, vmid=vmid, msg="VM %s with vmid = %s is %s" % (name, vmid, current), **status)
+ elif state in ['paused', 'hibernated']:
+ if not vmid:
+ module.fail_json(msg='VM with name = %s does not exist in cluster' % name)
+
+ status = {}
+ try:
+ vm = proxmox.get_vm(vmid)
+ current = proxmox.proxmox_api.nodes(vm['node']).qemu(vmid).status.current.get()['status']
+ status['status'] = current
+ if current != 'running':
+ module.exit_json(changed=False, vmid=vmid, msg="VM %s is not running" % vmid, **status)
+
+ proxmox.suspend_vm(vm, force=module.params['force'], timeout=module.params['timeout'], todisk=(state == 'hibernated'))
+ module.exit_json(changed=True, vmid=vmid, msg="VM %s is suspending" % vmid, **status)
+ except Exception as e:
+ module.fail_json(vmid=vmid, msg="suspending of VM %s failed with exception: %s" % (vmid, e), **status)
+
if __name__ == '__main__':
main()
diff --git a/plugins/modules/proxmox_nic.py b/plugins/modules/proxmox_nic.py
index 6e94ed0bb6..bd119fe5cc 100644
--- a/plugins/modules/proxmox_nic.py
+++ b/plugins/modules/proxmox_nic.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: proxmox_nic
short_description: Management of a NIC of a Qemu(KVM) VM in a Proxmox VE cluster
version_added: 3.1.0
@@ -52,8 +51,8 @@ options:
description:
- The NIC emulator model.
type: str
- choices: ['e1000', 'e1000-82540em', 'e1000-82544gc', 'e1000-82545em', 'i82551', 'i82557b', 'i82559er', 'ne2k_isa', 'ne2k_pci', 'pcnet',
- 'rtl8139', 'virtio', 'vmxnet3']
+ choices: ['e1000', 'e1000-82540em', 'e1000-82544gc', 'e1000-82545em', 'i82551', 'i82557b', 'i82559er', 'ne2k_isa', 'ne2k_pci',
+ 'pcnet', 'rtl8139', 'virtio', 'vmxnet3']
default: virtio
mtu:
description:
@@ -99,9 +98,9 @@ extends_documentation_fragment:
- community.general.proxmox.actiongroup_proxmox
- community.general.proxmox.documentation
- community.general.attributes
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create NIC net0 targeting the vm by name
community.general.proxmox_nic:
api_user: root@pam
@@ -131,20 +130,20 @@ EXAMPLES = '''
name: my_vm
interface: net0
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
vmid:
description: The VM vmid.
returned: success
type: int
sample: 115
msg:
- description: A short message
+ description: A short message.
returned: always
type: str
sample: "Nic net0 unchanged on VM with vmid 103"
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec, ProxmoxAnsible)
diff --git a/plugins/modules/proxmox_node_info.py b/plugins/modules/proxmox_node_info.py
index 51d8745c05..e243862134 100644
--- a/plugins/modules/proxmox_node_info.py
+++ b/plugins/modules/proxmox_node_info.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: proxmox_node_info
short_description: Retrieve information about one or more Proxmox VE nodes
version_added: 8.2.0
@@ -25,10 +24,10 @@ extends_documentation_fragment:
- community.general.proxmox.documentation
- community.general.attributes
- community.general.attributes.info_module
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List existing nodes
community.general.proxmox_node_info:
api_host: proxmox1
@@ -37,69 +36,69 @@ EXAMPLES = '''
api_token_id: "{{ token_id | default(omit) }}"
api_token_secret: "{{ token_secret | default(omit) }}"
register: proxmox_nodes
-'''
+"""
-RETURN = '''
+RETURN = r"""
proxmox_nodes:
- description: List of Proxmox VE nodes.
- returned: always, but can be empty
- type: list
- elements: dict
- contains:
- cpu:
- description: Current CPU usage in fractional shares of this host's total available CPU.
- returned: on success
- type: float
- disk:
- description: Current local disk usage of this host.
- returned: on success
- type: int
- id:
- description: Identity of the node.
- returned: on success
- type: str
- level:
- description: Support level. Can be blank if not under a paid support contract.
- returned: on success
- type: str
- maxcpu:
- description: Total number of available CPUs on this host.
- returned: on success
- type: int
- maxdisk:
- description: Size of local disk in bytes.
- returned: on success
- type: int
- maxmem:
- description: Memory size in bytes.
- returned: on success
- type: int
- mem:
- description: Used memory in bytes.
- returned: on success
- type: int
- node:
- description: Short hostname of this node.
- returned: on success
- type: str
- ssl_fingerprint:
- description: SSL fingerprint of the node certificate.
- returned: on success
- type: str
- status:
- description: Node status.
- returned: on success
- type: str
- type:
- description: Object type being returned.
- returned: on success
- type: str
- uptime:
- description: Node uptime in seconds.
- returned: on success
- type: int
-'''
+ description: List of Proxmox VE nodes.
+ returned: always, but can be empty
+ type: list
+ elements: dict
+ contains:
+ cpu:
+ description: Current CPU usage in fractional shares of this host's total available CPU.
+ returned: on success
+ type: float
+ disk:
+ description: Current local disk usage of this host.
+ returned: on success
+ type: int
+ id:
+ description: Identity of the node.
+ returned: on success
+ type: str
+ level:
+ description: Support level. Can be blank if not under a paid support contract.
+ returned: on success
+ type: str
+ maxcpu:
+ description: Total number of available CPUs on this host.
+ returned: on success
+ type: int
+ maxdisk:
+ description: Size of local disk in bytes.
+ returned: on success
+ type: int
+ maxmem:
+ description: Memory size in bytes.
+ returned: on success
+ type: int
+ mem:
+ description: Used memory in bytes.
+ returned: on success
+ type: int
+ node:
+ description: Short hostname of this node.
+ returned: on success
+ type: str
+ ssl_fingerprint:
+ description: SSL fingerprint of the node certificate.
+ returned: on success
+ type: str
+ status:
+ description: Node status.
+ returned: on success
+ type: str
+ type:
+ description: Object type being returned.
+ returned: on success
+ type: str
+ uptime:
+ description: Node uptime in seconds.
+ returned: on success
+ type: int
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/proxmox_pool.py b/plugins/modules/proxmox_pool.py
index 5089ec3bef..c53e394eeb 100644
--- a/plugins/modules/proxmox_pool.py
+++ b/plugins/modules/proxmox_pool.py
@@ -8,7 +8,6 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r"""
----
module: proxmox_pool
short_description: Pool management for Proxmox VE cluster
description:
@@ -28,12 +27,12 @@ options:
description:
- The pool ID.
type: str
- aliases: [ "name" ]
+ aliases: ["name"]
required: true
state:
description:
- - Indicate desired state of the pool.
- - The pool must be empty prior deleting it with O(state=absent).
+ - Indicate desired state of the pool.
+ - The pool must be empty prior deleting it with O(state=absent).
choices: ['present', 'absent']
default: present
type: str
@@ -49,7 +48,7 @@ extends_documentation_fragment:
- community.general.attributes
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Create new Proxmox VE pool
community.general.proxmox_pool:
api_host: node1
@@ -67,7 +66,7 @@ EXAMPLES = """
state: absent
"""
-RETURN = """
+RETURN = r"""
poolid:
description: The pool ID.
returned: success
diff --git a/plugins/modules/proxmox_pool_member.py b/plugins/modules/proxmox_pool_member.py
index b26082f975..bd32e94e42 100644
--- a/plugins/modules/proxmox_pool_member.py
+++ b/plugins/modules/proxmox_pool_member.py
@@ -8,7 +8,6 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r"""
----
module: proxmox_pool_member
short_description: Add or delete members from Proxmox VE cluster pools
description:
@@ -27,7 +26,7 @@ options:
description:
- The pool ID.
type: str
- aliases: [ "name" ]
+ aliases: ["name"]
required: true
member:
description:
@@ -44,7 +43,7 @@ options:
type: str
state:
description:
- - Indicate desired state of the pool member.
+ - Indicate desired state of the pool member.
choices: ['present', 'absent']
default: present
type: str
@@ -55,7 +54,7 @@ extends_documentation_fragment:
- community.general.attributes
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Add new VM to Proxmox VE pool
community.general.proxmox_pool_member:
api_host: node1
@@ -93,7 +92,7 @@ EXAMPLES = """
state: absent
"""
-RETURN = """
+RETURN = r"""
poolid:
description: The pool ID.
returned: success
diff --git a/plugins/modules/proxmox_snap.py b/plugins/modules/proxmox_snap.py
index 4f7b345b80..158efe99ec 100644
--- a/plugins/modules/proxmox_snap.py
+++ b/plugins/modules/proxmox_snap.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: proxmox_snap
short_description: Snapshot management of instances in Proxmox VE cluster
version_added: 2.0.0
@@ -30,13 +29,13 @@ options:
type: str
vmid:
description:
- - The instance id.
+ - The instance ID.
- If not set, will be fetched from PromoxAPI based on the hostname.
type: str
state:
description:
- - Indicate desired state of the instance snapshot.
- - The V(rollback) value was added in community.general 4.8.0.
+ - Indicate desired state of the instance snapshot.
+ - The V(rollback) value was added in community.general 4.8.0.
choices: ['present', 'absent', 'rollback']
default: present
type: str
@@ -51,7 +50,8 @@ options:
- Allows to snapshot a container even if it has configured mountpoints.
- Temporarily disables all configured mountpoints, takes snapshot, and finally restores original configuration.
- If running, the container will be stopped and restarted to apply config changes.
- - Due to restrictions in the Proxmox API this option can only be used authenticating as V(root@pam) with O(api_password), API tokens do not work either.
+ - Due to restrictions in the Proxmox API this option can only be used authenticating as V(root@pam) with O(api_password),
+ API tokens do not work either.
- See U(https://pve.proxmox.com/pve-docs/api-viewer/#/nodes/{node}/lxc/{vmid}/config) (PUT tab) for more details.
default: false
type: bool
@@ -80,23 +80,23 @@ options:
description:
- Remove old snapshots if there are more than O(retention) snapshots.
- If O(retention) is set to V(0), all snapshots will be kept.
- - This is only used when O(state=present) and when an actual snapshot is created.
- If no snapshot is created, all existing snapshots will be kept.
+ - This is only used when O(state=present) and when an actual snapshot is created. If no snapshot is created, all existing
+ snapshots will be kept.
default: 0
type: int
version_added: 7.1.0
notes:
- Requires proxmoxer and requests modules on host. These modules can be installed with pip.
-requirements: [ "proxmoxer", "requests" ]
+requirements: ["proxmoxer", "requests"]
author: Jeffrey van Pelt (@Thulium-Drake)
extends_documentation_fragment:
- community.general.proxmox.actiongroup_proxmox
- community.general.proxmox.documentation
- community.general.attributes
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create new container snapshot
community.general.proxmox_snap:
api_user: root@pam
@@ -143,9 +143,9 @@ EXAMPLES = r'''
vmid: 100
state: rollback
snapname: pre-updates
-'''
+"""
-RETURN = r'''#'''
+RETURN = r"""#"""
import time
diff --git a/plugins/modules/proxmox_storage_contents_info.py b/plugins/modules/proxmox_storage_contents_info.py
index b777870e54..e0e95565d7 100644
--- a/plugins/modules/proxmox_storage_contents_info.py
+++ b/plugins/modules/proxmox_storage_contents_info.py
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: proxmox_storage_contents_info
short_description: List content from a Proxmox VE storage
version_added: 8.2.0
@@ -51,7 +50,7 @@ extends_documentation_fragment:
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: List existing storages
community.general.proxmox_storage_contents_info:
api_host: helldorado
@@ -65,7 +64,7 @@ EXAMPLES = """
"""
-RETURN = """
+RETURN = r"""
proxmox_storage_content:
description: Content of of storage attached to a node.
type: list
diff --git a/plugins/modules/proxmox_storage_info.py b/plugins/modules/proxmox_storage_info.py
index fd5a6ee0d8..5b9b1b6aaa 100644
--- a/plugins/modules/proxmox_storage_info.py
+++ b/plugins/modules/proxmox_storage_info.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: proxmox_storage_info
short_description: Retrieve information about one or more Proxmox VE storages
version_added: 2.2.0
@@ -37,10 +36,10 @@ extends_documentation_fragment:
- community.general.attributes.info_module
notes:
- Storage specific options can be returned by this module, please look at the documentation at U(https://pve.proxmox.com/wiki/Storage).
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List existing storages
community.general.proxmox_storage_info:
api_host: helldorado
@@ -69,10 +68,10 @@ EXAMPLES = '''
api_token_secret: "{{ token_secret | default(omit) }}"
storage: lvm2
register: proxmox_storage_lvm
-'''
+"""
-RETURN = '''
+RETURN = r"""
proxmox_storages:
description: List of storage pools.
returned: on success
@@ -80,41 +79,41 @@ proxmox_storages:
elements: dict
contains:
content:
- description: Proxmox content types available in this storage
+ description: Proxmox content types available in this storage.
returned: on success
type: list
elements: str
digest:
- description: Storage's digest
+ description: Storage's digest.
returned: on success
type: str
nodes:
- description: List of nodes associated to this storage
+ description: List of nodes associated to this storage.
returned: on success, if storage is not local
type: list
elements: str
path:
- description: Physical path to this storage
+ description: Physical path to this storage.
returned: on success
type: str
prune-backups:
- description: Backup retention options
+ description: Backup retention options.
returned: on success
type: list
elements: dict
shared:
- description: Is this storage shared
+ description: Is this storage shared.
returned: on success
type: bool
storage:
- description: Storage name
+ description: Storage name.
returned: on success
type: str
type:
- description: Storage type
+ description: Storage type.
returned: on success
type: str
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/proxmox_tasks_info.py b/plugins/modules/proxmox_tasks_info.py
index 65a07566a8..574a971427 100644
--- a/plugins/modules/proxmox_tasks_info.py
+++ b/plugins/modules/proxmox_tasks_info.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: proxmox_tasks_info
short_description: Retrieve information about one or more Proxmox VE tasks
version_added: 3.8.0
@@ -36,10 +35,10 @@ extends_documentation_fragment:
- community.general.proxmox.documentation
- community.general.attributes
- community.general.attributes.info_module
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List tasks on node01
community.general.proxmox_tasks_info:
api_host: proxmoxhost
@@ -60,66 +59,66 @@ EXAMPLES = '''
task: 'UPID:node01:00003263:16167ACE:621EE230:srvreload:networking:root@pam:'
node: node01
register: proxmox_tasks
-'''
+"""
-RETURN = '''
+RETURN = r"""
proxmox_tasks:
- description: List of tasks.
- returned: on success
- type: list
- elements: dict
- contains:
- id:
- description: ID of the task.
- returned: on success
- type: str
- node:
- description: Node name.
- returned: on success
- type: str
- pid:
- description: PID of the task.
- returned: on success
- type: int
- pstart:
- description: pastart of the task.
- returned: on success
- type: int
- starttime:
- description: Starting time of the task.
- returned: on success
- type: int
- type:
- description: Type of the task.
- returned: on success
- type: str
- upid:
- description: UPID of the task.
- returned: on success
- type: str
- user:
- description: User that owns the task.
- returned: on success
- type: str
- endtime:
- description: Endtime of the task.
- returned: on success, can be absent
- type: int
- status:
- description: Status of the task.
- returned: on success, can be absent
- type: str
- failed:
- description: If the task failed.
- returned: when status is defined
- type: bool
+ description: List of tasks.
+ returned: on success
+ type: list
+ elements: dict
+ contains:
+ id:
+ description: ID of the task.
+ returned: on success
+ type: str
+ node:
+ description: Node name.
+ returned: on success
+ type: str
+ pid:
+ description: PID of the task.
+ returned: on success
+ type: int
+ pstart:
+ description: Pastart of the task.
+ returned: on success
+ type: int
+ starttime:
+ description: Starting time of the task.
+ returned: on success
+ type: int
+ type:
+ description: Type of the task.
+ returned: on success
+ type: str
+ upid:
+ description: UPID of the task.
+ returned: on success
+ type: str
+ user:
+ description: User that owns the task.
+ returned: on success
+ type: str
+ endtime:
+ description: Endtime of the task.
+ returned: on success, can be absent
+ type: int
+ status:
+ description: Status of the task.
+ returned: on success, can be absent
+ type: str
+ failed:
+ description: If the task failed.
+ returned: when status is defined
+ type: bool
msg:
- description: Short message.
- returned: on failure
- type: str
- sample: 'Task: UPID:xyz:xyz does not exist on node: proxmoxnode'
-'''
+ description: Short message.
+ returned: on failure
+ type: str
+ sample: 'Task: UPID:xyz:xyz does not exist on node: proxmoxnode'
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.proxmox import (
diff --git a/plugins/modules/proxmox_template.py b/plugins/modules/proxmox_template.py
index 134286164c..0081171878 100644
--- a/plugins/modules/proxmox_template.py
+++ b/plugins/modules/proxmox_template.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: proxmox_template
short_description: Management of OS templates in Proxmox VE cluster
description:
- - allows you to upload/delete templates in Proxmox VE cluster
+ - Allows you to upload/delete templates in Proxmox VE cluster.
attributes:
check_mode:
support: none
@@ -30,8 +29,14 @@ options:
src:
description:
- Path to uploaded file.
- - Required only for O(state=present).
+ - Exactly one of O(src) or O(url) is required for O(state=present).
type: path
+ url:
+ description:
+ - URL to file to download.
+ - Exactly one of O(src) or O(url) is required for O(state=present).
+ type: str
+ version_added: 10.1.0
template:
description:
- The template name.
@@ -62,10 +67,25 @@ options:
default: false
state:
description:
- - Indicate desired state of the template.
+ - Indicate desired state of the template.
type: str
choices: ['present', 'absent']
default: present
+ checksum_algorithm:
+ description:
+ - Algorithm used to verify the checksum.
+ - If specified, O(checksum) must also be specified.
+ type: str
+ choices: ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512']
+ version_added: 10.3.0
+ checksum:
+ description:
+ - The checksum to validate against.
+ - Checksums are often provided by software distributors to verify that a download is not corrupted.
+ - Checksums can usually be found on the distributors download page in the form of a file or string.
+ - If specified, O(checksum_algorithm) must also be specified.
+ type: str
+ version_added: 10.3.0
notes:
- Requires C(proxmoxer) and C(requests) modules on host. Those modules can be installed with M(ansible.builtin.pip).
- C(proxmoxer) >= 1.2.0 requires C(requests_toolbelt) to upload files larger than 256 MB.
@@ -74,9 +94,10 @@ extends_documentation_fragment:
- community.general.proxmox.actiongroup_proxmox
- community.general.proxmox.documentation
- community.general.attributes
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
+---
- name: Upload new openvz template with minimal options
community.general.proxmox_template:
node: uk-mc02
@@ -85,6 +106,14 @@ EXAMPLES = '''
api_host: node1
src: ~/ubuntu-14.04-x86_64.tar.gz
+- name: Pull new openvz template with minimal options
+ community.general.proxmox_template:
+ node: uk-mc02
+ api_user: root@pam
+ api_password: 1q2w3e
+ api_host: node1
+ url: https://ubuntu-mirror/ubuntu-14.04-x86_64.tar.gz
+
- name: >
Upload new openvz template with minimal options use environment
PROXMOX_PASSWORD variable(you should export it before)
@@ -105,6 +134,17 @@ EXAMPLES = '''
src: ~/ubuntu-14.04-x86_64.tar.gz
force: true
+- name: Pull new openvz template with all options and force overwrite
+ community.general.proxmox_template:
+ node: uk-mc02
+ api_user: root@pam
+ api_password: 1q2w3e
+ api_host: node1
+ storage: local
+ content_type: vztmpl
+ url: https://ubuntu-mirror/ubuntu-14.04-x86_64.tar.gz
+ force: true
+
- name: Delete template with minimal options
community.general.proxmox_template:
node: uk-mc02
@@ -123,7 +163,17 @@ EXAMPLES = '''
storage: local
content_type: vztmpl
template: ubuntu-20.04-standard_20.04-1_amd64.tar.gz
-'''
+
+- name: Download and verify a template's checksum
+ community.general.proxmox_template:
+ node: uk-mc02
+ api_user: root@pam
+ api_password: 1q2w3e
+ api_host: node1
+ url: ubuntu-20.04-standard_20.04-1_amd64.tar.gz
+ checksum_algorithm: sha256
+ checksum: 65d860160bdc9b98abf72407e14ca40b609417de7939897d3b58d55787aaef69
+"""
import os
import time
@@ -132,6 +182,7 @@ import traceback
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)
from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+from ansible.module_utils.six.moves.urllib.parse import urlparse, urlencode
REQUESTS_TOOLBELT_ERR = None
try:
@@ -158,10 +209,12 @@ class ProxmoxTemplateAnsible(ProxmoxAnsible):
while timeout:
if self.api_task_ok(node, taskid):
return True
+ elif self.api_task_failed(node, taskid):
+ self.module.fail_json(msg="Task error: %s" % self.proxmox_api.nodes(node).tasks(taskid).status.get()['exitstatus'])
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])
+ self.proxmox_api.nodes(node).tasks(taskid).log.get()[:1])
time.sleep(1)
return False
@@ -179,6 +232,17 @@ class ProxmoxTemplateAnsible(ProxmoxAnsible):
except Exception as e:
self.module.fail_json(msg="Uploading template %s failed with error: %s" % (realpath, e))
+ def fetch_template(self, node, storage, content_type, url, timeout):
+ """Fetch a template from a web url source using the proxmox download-url endpoint
+ """
+ try:
+ taskid = self.proxmox_api.nodes(node).storage(storage)("download-url").post(
+ url=url, content=content_type, filename=os.path.basename(url)
+ )
+ return self.task_status(node, taskid, timeout)
+ except Exception as e:
+ self.module.fail_json(msg="Fetching template from url %s failed with error: %s" % (url, e))
+
def download_template(self, node, storage, template, timeout):
try:
taskid = self.proxmox_api.nodes(node).aplinfo.post(storage=storage, template=template)
@@ -199,26 +263,45 @@ class ProxmoxTemplateAnsible(ProxmoxAnsible):
time.sleep(1)
return False
+ def fetch_and_verify(self, node, storage, url, content_type, timeout, checksum, checksum_algorithm):
+ """ Fetch a template from a web url, then verify it using a checksum.
+ """
+ data = {
+ 'url': url,
+ 'content': content_type,
+ 'filename': os.path.basename(url),
+ 'checksum': checksum,
+ 'checksum-algorithm': checksum_algorithm}
+ try:
+ taskid = self.proxmox_api.nodes(node).storage(storage).post("download-url?{}".format(urlencode(data)))
+ return self.task_status(node, taskid, timeout)
+ except Exception as e:
+ self.module.fail_json(msg="Checksum mismatch: %s" % (e))
+
def main():
module_args = proxmox_auth_argument_spec()
template_args = dict(
node=dict(),
src=dict(type='path'),
+ url=dict(),
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']),
+ checksum_algorithm=dict(choices=['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512']),
+ checksum=dict(type='str'),
)
module_args.update(template_args)
module = AnsibleModule(
argument_spec=module_args,
- required_together=[('api_token_id', 'api_token_secret')],
+ required_together=[('api_token_id', 'api_token_secret'), ('checksum', 'checksum_algorithm')],
required_one_of=[('api_password', 'api_token_id')],
- required_if=[('state', 'absent', ['template'])]
+ required_if=[('state', 'absent', ['template'])],
+ mutually_exclusive=[("src", "url")],
)
proxmox = ProxmoxTemplateAnsible(module)
@@ -227,13 +310,16 @@ def main():
node = module.params['node']
storage = module.params['storage']
timeout = module.params['timeout']
+ checksum = module.params['checksum']
+ checksum_algorithm = module.params['checksum_algorithm']
if state == 'present':
content_type = module.params['content_type']
src = module.params['src']
+ url = module.params['url']
# download appliance template
- if content_type == 'vztmpl' and not src:
+ if content_type == 'vztmpl' and not (src or url):
template = module.params['template']
if not template:
@@ -245,16 +331,30 @@ def main():
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 proxmox.has_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 not src and not url:
+ module.fail_json(msg='src or url param for uploading template file is mandatory')
+ elif not url:
+ template = os.path.basename(src)
+ if proxmox.has_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))
+ elif not (os.path.exists(src) and os.path.isfile(src)):
+ module.fail_json(msg='template file on path %s not exists' % src)
- 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))
+ 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))
+ elif not src:
+ template = os.path.basename(urlparse(url).path)
+ if proxmox.has_template(node, storage, content_type, template):
+ if not module.params['force']:
+ module.exit_json(changed=False, msg='template with volid=%s:%s/%s already exists' % (storage, content_type, template))
+ elif not proxmox.delete_template(node, storage, content_type, template, timeout):
+ module.fail_json(changed=False, msg='failed to delete template with volid=%s:%s/%s' % (storage, content_type, template))
+
+ if checksum:
+ if proxmox.fetch_and_verify(node, storage, url, content_type, timeout, checksum, checksum_algorithm):
+ module.exit_json(changed=True, msg="Checksum verified, template with volid=%s:%s/%s uploaded" % (storage, content_type, template))
+ if proxmox.fetch_template(node, storage, content_type, url, timeout):
+ module.exit_json(changed=True, msg='template with volid=%s:%s/%s uploaded' % (storage, content_type, template))
elif state == 'absent':
try:
diff --git a/plugins/modules/proxmox_user_info.py b/plugins/modules/proxmox_user_info.py
index 8680dec7ca..a8da1ee30a 100644
--- a/plugins/modules/proxmox_user_info.py
+++ b/plugins/modules/proxmox_user_info.py
@@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: proxmox_user_info
short_description: Retrieve information about one or more Proxmox VE users
version_added: 1.3.0
description:
- - Retrieve information about one or more Proxmox VE users
+ - Retrieve information about one or more Proxmox VE users.
attributes:
action_group:
version_added: 9.0.0
@@ -40,9 +39,9 @@ extends_documentation_fragment:
- community.general.proxmox.documentation
- community.general.attributes
- community.general.attributes.info_module
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: List existing users
community.general.proxmox_user_info:
api_host: helldorado
@@ -82,84 +81,84 @@ EXAMPLES = '''
user: admin
domain: pve
register: proxmox_user_admin
-'''
+"""
-RETURN = '''
+RETURN = r"""
proxmox_users:
- description: List of users.
- returned: always, but can be empty
- type: list
- elements: dict
- contains:
- comment:
- description: Short description of the user.
- returned: on success
- type: str
- domain:
- description: User's authentication realm, also the right part of the user ID.
- returned: on success
- type: str
- email:
- description: User's email address.
- returned: on success
- type: str
- enabled:
- description: User's account state.
- returned: on success
- type: bool
- expire:
- description: Expiration date in seconds since EPOCH. Zero means no expiration.
- returned: on success
- type: int
- firstname:
- description: User's first name.
- returned: on success
- type: str
- groups:
- description: List of groups which the user is a member of.
- returned: on success
- type: list
- elements: str
- keys:
- description: User's two factor authentication keys.
- returned: on success
- type: str
- lastname:
- description: User's last name.
- returned: on success
- type: str
- tokens:
- description: List of API tokens associated to the user.
- returned: on success
- type: list
- elements: dict
- contains:
- comment:
- description: Short description of the token.
- returned: on success
- type: str
- expire:
- description: Expiration date in seconds since EPOCH. Zero means no expiration.
- returned: on success
- type: int
- privsep:
- description: Describe if the API token is further restricted with ACLs or is fully privileged.
- returned: on success
- type: bool
- tokenid:
- description: Token name.
- returned: on success
- type: str
- user:
- description: User's login name, also the left part of the user ID.
- returned: on success
- type: str
- userid:
- description: Proxmox user ID, represented as user@realm.
- returned: on success
- type: str
-'''
+ description: List of users.
+ returned: always, but can be empty
+ type: list
+ elements: dict
+ contains:
+ comment:
+ description: Short description of the user.
+ returned: on success
+ type: str
+ domain:
+ description: User's authentication realm, also the right part of the user ID.
+ returned: on success
+ type: str
+ email:
+ description: User's email address.
+ returned: on success
+ type: str
+ enabled:
+ description: User's account state.
+ returned: on success
+ type: bool
+ expire:
+ description: Expiration date in seconds since EPOCH. Zero means no expiration.
+ returned: on success
+ type: int
+ firstname:
+ description: User's first name.
+ returned: on success
+ type: str
+ groups:
+ description: List of groups which the user is a member of.
+ returned: on success
+ type: list
+ elements: str
+ keys:
+ description: User's two factor authentication keys.
+ returned: on success
+ type: str
+ lastname:
+ description: User's last name.
+ returned: on success
+ type: str
+ tokens:
+ description: List of API tokens associated to the user.
+ returned: on success
+ type: list
+ elements: dict
+ contains:
+ comment:
+ description: Short description of the token.
+ returned: on success
+ type: str
+ expire:
+ description: Expiration date in seconds since EPOCH. Zero means no expiration.
+ returned: on success
+ type: int
+ privsep:
+ description: Describe if the API token is further restricted with ACLs or is fully privileged.
+ returned: on success
+ type: bool
+ tokenid:
+ description: Token name.
+ returned: on success
+ type: str
+ user:
+ description: User's login name, also the left part of the user ID.
+ returned: on success
+ type: str
+ userid:
+ description: Proxmox user ID, represented as user@realm.
+ returned: on success
+ type: str
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/proxmox_vm_info.py b/plugins/modules/proxmox_vm_info.py
index e10b9dff6f..34d701c25e 100644
--- a/plugins/modules/proxmox_vm_info.py
+++ b/plugins/modules/proxmox_vm_info.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
----
+DOCUMENTATION = r"""
module: proxmox_vm_info
short_description: Retrieve information about one or more Proxmox VE virtual machines
version_added: 7.2.0
@@ -71,7 +70,7 @@ extends_documentation_fragment:
- community.general.attributes.info_module
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: List all existing virtual machines on node
community.general.proxmox_vm_info:
api_host: proxmoxhost
@@ -108,7 +107,7 @@ EXAMPLES = """
config: current
"""
-RETURN = """
+RETURN = r"""
proxmox_vms:
description: List of virtual machines.
returned: on success
@@ -201,7 +200,7 @@ class ProxmoxVmInfoAnsible(ProxmoxAnsible):
if desired_vm:
desired_vm.update(detected_vm)
desired_vm["vmid"] = this_vm_id
- desired_vm["template"] = proxmox_to_ansible_bool(desired_vm["template"])
+ desired_vm["template"] = proxmox_to_ansible_bool(desired_vm.get("template", 0))
# When user wants to retrieve the VM configuration
if config != "none":
# pending = 0, current = 1
diff --git a/plugins/modules/pubnub_blocks.py b/plugins/modules/pubnub_blocks.py
index 34098873a1..c8992b2aa7 100644
--- a/plugins/modules/pubnub_blocks.py
+++ b/plugins/modules/pubnub_blocks.py
@@ -14,15 +14,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pubnub_blocks
short_description: PubNub blocks management module
description:
- - "This module allows Ansible to interface with the PubNub BLOCKS
- infrastructure by providing the following operations: create / remove,
- start / stop and rename for blocks and create / modify / remove for event
- handlers."
+ - 'This module allows Ansible to interface with the PubNub BLOCKS infrastructure by providing the following operations:
+ create / remove, start / stop and rename for blocks and create / modify / remove for event handlers.'
author:
- PubNub (@pubnub)
- Sergey Mamontov (@parfeon)
@@ -39,38 +36,33 @@ options:
email:
description:
- Email from account for which new session should be started.
- - "Not required if O(cache) contains result of previous module call (in
- same play)."
+ - Not required if O(cache) contains result of previous module call (in same play).
required: false
type: str
default: ''
password:
description:
- Password which match to account to which specified O(email) belong.
- - "Not required if O(cache) contains result of previous module call (in
- same play)."
+ - Not required if O(cache) contains result of previous module call (in same play).
required: false
type: str
default: ''
cache:
- description: >
- In case if single play use blocks management module few times it is
- preferred to enabled 'caching' by making previous module to share
- gathered artifacts and pass them to this parameter.
+ description: >-
+ In case if single play use blocks management module few times it is preferred to enabled 'caching' by making previous
+ module to share gathered artifacts and pass them to this parameter.
required: false
type: dict
default: {}
account:
description:
- - "Name of PubNub account for from which O(application) will be used to
- manage blocks."
- - "User's account will be used if value not set or empty."
+ - Name of PubNub account for from which O(application) will be used to manage blocks.
+ - User's account will be used if value not set or empty.
type: str
default: ''
application:
description:
- - "Name of target PubNub application for which blocks configuration on
- specific O(keyset) will be done."
+ - Name of target PubNub application for which blocks configuration on specific O(keyset) will be done.
type: str
required: true
keyset:
@@ -80,8 +72,7 @@ options:
required: true
state:
description:
- - "Intended block state after event handlers creation / update process
- will be completed."
+ - Intended block state after event handlers creation / update process will be completed.
required: false
default: 'present'
choices: ['started', 'stopped', 'present', 'absent']
@@ -93,55 +84,45 @@ options:
type: str
description:
description:
- - Short block description which will be later visible on
- admin.pubnub.com. Used only if block doesn't exists and won't change
- description for existing block.
+ - Short block description which will be later visible on U(https://admin.pubnub.com).
+ - Used only if block does not exists and does not change description for existing block.
required: false
type: str
event_handlers:
description:
- - "List of event handlers which should be updated for specified block
- O(name)."
- - "Each entry for new event handler should contain: C(name), C(src),
- C(channels), C(event). C(name) used as event handler name which can be
- used later to make changes to it."
+ - List of event handlers which should be updated for specified block O(name).
+ - 'Each entry for new event handler should contain: V(name), V(src), V(channels), V(event). V(name) used as event handler
+ name which can be used later to make changes to it.'
- C(src) is full path to file with event handler code.
- - "C(channels) is name of channel from which event handler is waiting
- for events."
- - "C(event) is type of event which is able to trigger event handler:
- C(js-before-publish), C(js-after-publish), C(js-after-presence)."
- - "Each entry for existing handlers should contain C(name) (so target
- handler can be identified). Rest parameters (C(src), C(channels) and
- C(event)) can be added if changes required for them."
- - "It is possible to rename event handler by adding C(changes) key to
- event handler payload and pass dictionary, which will contain single key
- C(name), where new name should be passed."
- - "To remove particular event handler it is possible to set C(state) for
- it to C(absent) and it will be removed."
+ - V(channels) is name of channel from which event handler is waiting for events.
+ - 'V(event) is type of event which is able to trigger event handler: V(js-before-publish), V(js-after-publish), V(js-after-presence).'
+ - Each entry for existing handlers should contain C(name) (so target handler can be identified). Rest parameters (C(src),
+ C(channels) and C(event)) can be added if changes required for them.
+ - It is possible to rename event handler by adding C(changes) key to event handler payload and pass dictionary, which
+ will contain single key C(name), where new name should be passed.
+ - To remove particular event handler it is possible to set C(state) for it to C(absent) and it will be removed.
required: false
default: []
type: list
elements: dict
changes:
description:
- - "List of fields which should be changed by block itself (doesn't
- affect any event handlers)."
- - "Possible options for change is: O(name)."
+ - List of fields which should be changed by block itself (does not affect any event handlers).
+ - 'Possible options for change is: O(name).'
required: false
default: {}
type: dict
validate_certs:
description:
- - "This key allow to try skip certificates check when performing REST API
- calls. Sometimes host may have issues with certificates on it and this
- will cause problems to call PubNub REST API."
+ - This key allow to try skip certificates check when performing REST API calls. Sometimes host may have issues with
+ certificates on it and this will cause problems to call PubNub REST API.
- If check should be ignored V(false) should be passed to this parameter.
required: false
default: true
type: bool
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Event handler create example.
- name: Create single event handler
community.general.pubnub_blocks:
@@ -151,8 +132,7 @@ EXAMPLES = '''
keyset: '{{ keyset_name }}'
name: '{{ block_name }}'
event_handlers:
- -
- src: '{{ path_to_handler_source }}'
+ - src: '{{ path_to_handler_source }}'
name: '{{ handler_name }}'
event: 'js-before-publish'
channels: '{{ handler_channel }}'
@@ -166,8 +146,7 @@ EXAMPLES = '''
keyset: '{{ keyset_name }}'
name: '{{ block_name }}'
event_handlers:
- -
- name: '{{ handler_name }}'
+ - name: '{{ handler_name }}'
event: 'js-after-publish'
# Stop block and event handlers.
@@ -199,8 +178,7 @@ EXAMPLES = '''
name: '{{ block_name }}'
state: present
event_handlers:
- -
- src: '{{ path_to_handler_1_source }}'
+ - src: '{{ path_to_handler_1_source }}'
name: '{{ event_handler_1_name }}'
channels: '{{ event_handler_1_channel }}'
event: 'js-before-publish'
@@ -213,8 +191,7 @@ EXAMPLES = '''
name: '{{ block_name }}'
state: present
event_handlers:
- -
- src: '{{ path_to_handler_2_source }}'
+ - src: '{{ path_to_handler_2_source }}'
name: '{{ event_handler_2_name }}'
channels: '{{ event_handler_2_channel }}'
event: 'js-before-publish'
@@ -226,17 +203,16 @@ EXAMPLES = '''
keyset: '{{ keyset_name }}'
name: '{{ block_name }}'
state: started
-'''
+"""
-RETURN = '''
+RETURN = r"""
module_cache:
description:
- - Cached account information. In case if with single play module
- used few times it is better to pass cached data to next module calls to speed
- up process.
+ - Cached account information. In case if with single play module used few times it is better to pass cached data to next
+ module calls to speed up process.
type: dict
returned: always
-'''
+"""
import copy
import os
diff --git a/plugins/modules/pulp_repo.py b/plugins/modules/pulp_repo.py
index c581fa3187..0af129d26a 100644
--- a/plugins/modules/pulp_repo.py
+++ b/plugins/modules/pulp_repo.py
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pulp_repo
author: "Joe Adams (@sysadmind)"
short_description: Add or remove Pulp repos from a remote host
@@ -35,78 +34,70 @@ options:
type: str
force_basic_auth:
description:
- - httplib2, the library used by the M(ansible.builtin.uri) module only sends
- authentication information when a webservice responds to an initial
- request with a 401 status. Since some basic auth services do not
- properly send a 401, logins will fail. This option forces the sending of
- the Basic authentication header upon initial request.
+ - C(httplib2), the library used by the M(ansible.builtin.uri) module only sends authentication information when a webservice
+ responds to an initial request with a 401 status. Since some basic auth services do not properly send a 401, logins
+ will fail. This option forces the sending of the Basic authentication header upon initial request.
type: bool
default: false
generate_sqlite:
description:
- - Boolean flag to indicate whether sqlite files should be generated during
- a repository publish.
+ - Boolean flag to indicate whether sqlite files should be generated during a repository publish.
required: false
type: bool
default: false
feed_ca_cert:
description:
- - CA certificate string used to validate the feed source SSL certificate.
- This can be the file content or the path to the file.
+ - CA certificate string used to validate the feed source SSL certificate. This can be the file content or the path to
+ the file.
type: str
- aliases: [ importer_ssl_ca_cert ]
+ aliases: [importer_ssl_ca_cert]
feed_client_cert:
description:
- - Certificate used as the client certificate when synchronizing the
- repository. This is used to communicate authentication information to
- the feed source. The value to this option must be the full path to the
- certificate. The specified file may be the certificate itself or a
- single file containing both the certificate and private key. This can be
- the file content or the path to the file.
+ - Certificate used as the client certificate when synchronizing the repository. This is used to communicate authentication
+ information to the feed source. The value to this option must be the full path to the certificate. The specified file
+ may be the certificate itself or a single file containing both the certificate and private key. This can be the file
+ content or the path to the file.
type: str
- aliases: [ importer_ssl_client_cert ]
+ aliases: [importer_ssl_client_cert]
feed_client_key:
description:
- - Private key to the certificate specified in O(feed_client_cert),
- assuming it is not included in the certificate file itself. This can be
- the file content or the path to the file.
+ - Private key to the certificate specified in O(feed_client_cert), assuming it is not included in the certificate file
+ itself. This can be the file content or the path to the file.
type: str
- aliases: [ importer_ssl_client_key ]
+ aliases: [importer_ssl_client_key]
name:
description:
- Name of the repo to add or remove. This correlates to repo-id in Pulp.
required: true
type: str
- aliases: [ repo ]
+ aliases: [repo]
proxy_host:
description:
- - Proxy url setting for the pulp repository importer. This is in the
- format scheme://host.
+ - Proxy URL setting for the pulp repository importer. This is in the format V(scheme://host).
required: false
- default: null
+ default:
type: str
proxy_port:
description:
- Proxy port setting for the pulp repository importer.
required: false
- default: null
+ default:
type: str
proxy_username:
description:
- Proxy username for the pulp repository importer.
required: false
- default: null
+ default:
type: str
proxy_password:
description:
- Proxy password for the pulp repository importer.
required: false
- default: null
+ default:
type: str
publish_distributor:
description:
- - Distributor to use when O(state=publish). The default is to
- publish all distributors.
+ - Distributor to use when O(state=publish). The default is to publish all distributors.
type: str
pulp_host:
description:
@@ -124,8 +115,7 @@ options:
type: str
repoview:
description:
- - Whether to generate repoview files for a published repository. Setting
- this to V(true) automatically activates O(generate_sqlite).
+ - Whether to generate repoview files for a published repository. Setting this to V(true) automatically activates O(generate_sqlite).
required: false
type: bool
default: false
@@ -141,24 +131,22 @@ options:
default: true
state:
description:
- - The repo state. A state of V(sync) will queue a sync of the repo.
- This is asynchronous but not delayed like a scheduled sync. A state of
- V(publish) will use the repository's distributor to publish the content.
+ - The repo state. A state of V(sync) will queue a sync of the repo. This is asynchronous but not delayed like a scheduled
+ sync. A state of V(publish) will use the repository's distributor to publish the content.
default: present
- choices: [ "present", "absent", "sync", "publish" ]
+ choices: ["present", "absent", "sync", "publish"]
type: str
url_password:
description:
- - The password for use in HTTP basic authentication to the pulp API.
- If the O(url_username) parameter is not specified, the O(url_password)
- parameter will not be used.
+ - The password for use in HTTP basic authentication to the pulp API. If the O(url_username) parameter is not specified,
+ the O(url_password) parameter will not be used.
url_username:
description:
- The username for use in HTTP basic authentication to the pulp API.
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be
- used on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
type: bool
default: true
wait_for_completion:
@@ -167,14 +155,14 @@ options:
type: bool
default: false
notes:
- - This module can currently only create distributors and importers on rpm
- repositories. Contributions to support other repo types are welcome.
+ - This module can currently only create distributors and importers on rpm repositories. Contributions to support other repo
+ types are welcome.
extends_documentation_fragment:
- ansible.builtin.url
- community.general.attributes
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a new repo with name 'my_repo'
community.general.pulp_repo:
name: my_repo
@@ -197,15 +185,15 @@ EXAMPLES = '''
name: my_old_repo
repo_type: rpm
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
repo:
description: Name of the repo that the action was performed on.
returned: success
type: str
sample: my_repo
-'''
+"""
import json
import os
@@ -595,29 +583,20 @@ def main():
if importer_ssl_ca_cert is not None:
importer_ssl_ca_cert_file_path = os.path.abspath(importer_ssl_ca_cert)
if os.path.isfile(importer_ssl_ca_cert_file_path):
- importer_ssl_ca_cert_file_object = open(importer_ssl_ca_cert_file_path, 'r')
- try:
+ with open(importer_ssl_ca_cert_file_path, 'r') as importer_ssl_ca_cert_file_object:
importer_ssl_ca_cert = importer_ssl_ca_cert_file_object.read()
- finally:
- importer_ssl_ca_cert_file_object.close()
if importer_ssl_client_cert is not None:
importer_ssl_client_cert_file_path = os.path.abspath(importer_ssl_client_cert)
if os.path.isfile(importer_ssl_client_cert_file_path):
- importer_ssl_client_cert_file_object = open(importer_ssl_client_cert_file_path, 'r')
- try:
+ with open(importer_ssl_client_cert_file_path, 'r') as importer_ssl_client_cert_file_object:
importer_ssl_client_cert = importer_ssl_client_cert_file_object.read()
- finally:
- importer_ssl_client_cert_file_object.close()
if importer_ssl_client_key is not None:
importer_ssl_client_key_file_path = os.path.abspath(importer_ssl_client_key)
if os.path.isfile(importer_ssl_client_key_file_path):
- importer_ssl_client_key_file_object = open(importer_ssl_client_key_file_path, 'r')
- try:
+ with open(importer_ssl_client_key_file_path, 'r') as importer_ssl_client_key_file_object:
importer_ssl_client_key = importer_ssl_client_key_file_object.read()
- finally:
- importer_ssl_client_key_file_object.close()
server = pulp_server(module, pulp_host, repo_type, wait_for_completion=wait_for_completion)
server.set_repo_list()
diff --git a/plugins/modules/puppet.py b/plugins/modules/puppet.py
index 46326c667f..a631a8ec55 100644
--- a/plugins/modules/puppet.py
+++ b/plugins/modules/puppet.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: puppet
short_description: Runs puppet
description:
@@ -66,11 +65,11 @@ options:
version_added: 5.1.0
logdest:
description:
- - Where the puppet logs should go, if puppet apply is being used.
- - V(all) will go to both C(console) and C(syslog).
- - V(stdout) will be deprecated and replaced by C(console).
+ - Where the puppet logs should go, if puppet apply is being used.
+ - V(all) will go to both C(console) and C(syslog).
+ - V(stdout) will be deprecated and replaced by C(console).
type: str
- choices: [ all, stdout, syslog ]
+ choices: [all, stdout, syslog]
default: stdout
certname:
description:
@@ -94,7 +93,7 @@ options:
type: str
use_srv_records:
description:
- - Toggles use_srv_records flag
+ - Toggles use_srv_records flag.
type: bool
summarize:
description:
@@ -103,8 +102,9 @@ options:
default: false
waitforlock:
description:
- - The maximum amount of time C(puppet) should wait for an already running C(puppet) agent to finish before starting.
- - If a number without unit is provided, it is assumed to be a number of seconds. Allowed units are V(m) for minutes and V(h) for hours.
+ - The maximum amount of time C(puppet) should wait for an already running C(puppet) agent to finish before starting.
+ - If a number without unit is provided, it is assumed to be a number of seconds. Allowed units are V(m) for minutes
+ and V(h) for hours.
type: str
version_added: 9.0.0
verbose:
@@ -119,27 +119,27 @@ options:
default: false
show_diff:
description:
- - Whether to print file changes details
+ - Whether to print file changes details.
type: bool
default: false
environment_lang:
description:
- The lang environment to use when running the puppet agent.
- - The default value, V(C), is supported on every system, but can lead to encoding errors if UTF-8 is used in the output
- - Use V(C.UTF-8) or V(en_US.UTF-8) or similar UTF-8 supporting locales in case of problems. You need to make sure
- the selected locale is supported on the system the puppet agent runs on.
- - Starting with community.general 9.1.0, you can use the value V(auto) and the module will
- try and determine the best parseable locale to use.
+ - The default value, V(C), is supported on every system, but can lead to encoding errors if UTF-8 is used in the output.
+ - Use V(C.UTF-8) or V(en_US.UTF-8) or similar UTF-8 supporting locales in case of problems. You need to make sure the
+ selected locale is supported on the system the puppet agent runs on.
+ - Starting with community.general 9.1.0, you can use the value V(auto) and the module will try and determine the best
+ parseable locale to use.
type: str
default: C
version_added: 8.6.0
requirements:
-- puppet
+ - puppet
author:
-- Monty Taylor (@emonty)
-'''
+ - Monty Taylor (@emonty)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Run puppet agent and fail if anything goes wrong
community.general.puppet:
@@ -162,10 +162,10 @@ EXAMPLES = r'''
- name: Run puppet using a specific tags
community.general.puppet:
tags:
- - update
- - nginx
+ - update
+ - nginx
skip_tags:
- - service
+ - service
- name: Wait 30 seconds for any current puppet runs to finish
community.general.puppet:
@@ -184,7 +184,7 @@ EXAMPLES = r'''
modulepath: /etc/puppet/modules:/opt/stack/puppet-modules:/usr/share/openstack-puppet/modules
logdest: all
manifest: /var/lib/example/puppet_step_config.pp
-'''
+"""
import json
import os
@@ -276,7 +276,7 @@ def main():
# success
module.exit_json(rc=rc, changed=False, stdout=stdout, stderr=stderr)
elif rc == 1:
- # rc==1 could be because it's disabled
+ # rc==1 could be because it is disabled
# rc==1 could also mean there was a compilation failure
disabled = "administratively disabled" in stdout
if disabled:
diff --git a/plugins/modules/pushbullet.py b/plugins/modules/pushbullet.py
index 673f30cc36..8e6ac0ed18 100644
--- a/plugins/modules/pushbullet.py
+++ b/plugins/modules/pushbullet.py
@@ -9,65 +9,60 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
author: "Willy Barro (@willybarro)"
-requirements: [ pushbullet.py ]
+requirements: [pushbullet.py]
module: pushbullet
short_description: Sends notifications to Pushbullet
description:
- - This module sends push notifications via Pushbullet to channels or devices.
+ - This module sends push notifications through Pushbullet to channels or devices.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- api_key:
- type: str
- description:
- - Push bullet API token
- required: true
- channel:
- type: str
- description:
- - The channel TAG you wish to broadcast a push notification,
- as seen on the "My Channels" > "Edit your channel" at
- Pushbullet page.
- device:
- type: str
- description:
- - The device NAME you wish to send a push notification,
- as seen on the Pushbullet main page.
- push_type:
- type: str
- description:
- - Thing you wish to push.
- default: note
- choices: [ "note", "link" ]
- title:
- type: str
- description:
- - Title of the notification.
- required: true
- body:
- type: str
- description:
- - Body of the notification, e.g. Details of the fault you're alerting.
- url:
- type: str
- description:
- - URL field, used when O(push_type=link).
-
+ api_key:
+ type: str
+ description:
+ - Push bullet API token.
+ required: true
+ channel:
+ type: str
+ description:
+ - The channel TAG you wish to broadcast a push notification, as seen on the "My Channels" > "Edit your channel" at Pushbullet
+ page.
+ device:
+ type: str
+ description:
+ - The device NAME you wish to send a push notification, as seen on the Pushbullet main page.
+ push_type:
+ type: str
+ description:
+ - Thing you wish to push.
+ default: note
+ choices: ["note", "link"]
+ title:
+ type: str
+ description:
+ - Title of the notification.
+ required: true
+ body:
+ type: str
+ description:
+ - Body of the notification, for example details of the fault you are alerting.
+ url:
+ type: str
+ description:
+ - URL field, used when O(push_type=link).
notes:
- - Requires pushbullet.py Python package on the remote host.
- You can install it via pip with ($ pip install pushbullet.py).
- See U(https://github.com/randomchars/pushbullet.py)
-'''
+ - Requires C(pushbullet.py) Python package on the remote host. You can install it through C(pip) with C(pip install pushbullet.py).
+ - See U(https://github.com/randomchars/pushbullet.py).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Sends a push notification to a device
community.general.pushbullet:
api_key: "ABC123abc123ABC123abc123ABC123ab"
@@ -94,7 +89,7 @@ EXAMPLES = '''
channel: my-awesome-channel
title: ALERT! Signup service is down
body: Error rate on signup service is over 90% for more than 2 minutes
-'''
+"""
import traceback
diff --git a/plugins/modules/pushover.py b/plugins/modules/pushover.py
index f5493731fa..ae57411531 100644
--- a/plugins/modules/pushover.py
+++ b/plugins/modules/pushover.py
@@ -9,16 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: pushover
-short_description: Send notifications via U(https://pushover.net)
+short_description: Send notifications through U(https://pushover.net)
description:
- - Send notifications via pushover, to subscriber list of devices, and email
- addresses. Requires pushover app on devices.
+ - Send notifications through pushover to subscriber list of devices and email addresses. Requires pushover app on devices.
notes:
- - You will require a pushover.net account to use this module. But no account
- is required to receive messages.
+ - You will require a pushover.net account to use this module. But no account is required to receive messages.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -53,7 +50,7 @@ options:
- Message priority (see U(https://pushover.net) for details).
required: false
default: '0'
- choices: [ '-2', '-1', '0', '1', '2' ]
+ choices: ['-2', '-1', '0', '1', '2']
device:
type: str
description:
@@ -64,9 +61,9 @@ options:
author:
- "Jim Richardson (@weaselkeeper)"
- "Bernd Arnold (@wopfel)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Send notifications via pushover.net
community.general.pushover:
msg: '{{ inventory_hostname }} is acting strange ...'
@@ -90,7 +87,7 @@ EXAMPLES = '''
user_key: baa5fe97f2c5ab3ca8f0bb59
device: admins-iPhone
delegate_to: localhost
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.six.moves.urllib.parse import urlencode
diff --git a/plugins/modules/python_requirements_info.py b/plugins/modules/python_requirements_info.py
index 8e709440d1..a8ef5a952f 100644
--- a/plugins/modules/python_requirements_info.py
+++ b/plugins/modules/python_requirements_info.py
@@ -7,7 +7,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: python_requirements_info
short_description: Show python path and assert dependency versions
description:
@@ -19,18 +19,18 @@ options:
dependencies:
type: list
elements: str
- description: >
- A list of version-likes or module names to check for installation.
- Supported operators: <, >, <=, >=, or ==. The bare module name like
- V(ansible), the module with a specific version like V(boto3==1.6.1), or a
- partial version like V(requests>2) are all valid specifications.
+ description:
+ - 'A list of version-likes or module names to check for installation. Supported operators: C(<), C(>), C(<=), C(>=),
+ or C(==).'
+ - The bare module name like V(ansible), the module with a specific version like V(boto3==1.6.1), or a partial version
+ like V(requests>2) are all valid specifications.
default: []
author:
- Will Thames (@willthames)
- Ryan Scott Brown (@ryansb)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Show python lib/site paths
community.general.python_requirements_info:
@@ -39,21 +39,21 @@ EXAMPLES = '''
dependencies:
- boto3>1.6
- botocore<2
-'''
+"""
-RETURN = '''
+RETURN = r"""
python:
- description: path to python version used
+ description: Path to the Python interpreter used.
returned: always
type: str
sample: /usr/local/opt/python@2/bin/python2.7
python_version:
- description: version of python
+ description: Version of Python.
returned: always
type: str
sample: "2.7.15 (default, May 1 2018, 16:44:08)\n[GCC 4.2.1 Compatible Apple LLVM 9.1.0 (clang-902.0.39.1)]"
python_version_info:
- description: breakdown version of python
+ description: Breakdown version of Python.
returned: always
type: dict
contains:
@@ -84,25 +84,26 @@ python_version_info:
sample: 0
version_added: 4.2.0
python_system_path:
- description: List of paths python is looking for modules in
+ description: List of paths Python is looking for modules in.
returned: always
type: list
sample:
- /usr/local/opt/python@2/site-packages/
- /usr/lib/python/site-packages/
valid:
- description: A dictionary of dependencies that matched their desired versions. If no version was specified, then RV(ignore:desired) will be null
+ description: A dictionary of dependencies that matched their desired versions. If no version was specified, then RV(ignore:desired)
+ will be V(null).
returned: always
type: dict
sample:
boto3:
- desired: null
+ desired:
installed: 1.7.60
botocore:
desired: botocore<2
installed: 1.10.60
mismatched:
- description: A dictionary of dependencies that did not satisfy the desired version
+ description: A dictionary of dependencies that did not satisfy the desired version.
returned: always
type: dict
sample:
@@ -110,13 +111,13 @@ mismatched:
desired: botocore>2
installed: 1.10.60
not_found:
- description: A list of packages that could not be imported at all, and are not installed
+ description: A list of packages that could not be imported at all, and are not installed.
returned: always
type: list
sample:
- boto4
- requests
-'''
+"""
import re
import sys
diff --git a/plugins/modules/read_csv.py b/plugins/modules/read_csv.py
index 3c59013180..ce2631482b 100644
--- a/plugins/modules/read_csv.py
+++ b/plugins/modules/read_csv.py
@@ -8,16 +8,15 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: read_csv
short_description: Read a CSV file
description:
-- Read a CSV file and return a list or a dictionary, containing one dictionary per row.
+ - Read a CSV file and return a list or a dictionary, containing one dictionary per row.
author:
-- Dag Wieers (@dagwieers)
+ - Dag Wieers (@dagwieers)
extends_documentation_fragment:
-- community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -26,58 +25,57 @@ attributes:
options:
path:
description:
- - The CSV filename to read data from.
+ - The CSV filename to read data from.
type: path
required: true
- aliases: [ filename ]
+ aliases: [filename]
key:
description:
- - The column name used as a key for the resulting dictionary.
- - If O(key) is unset, the module returns a list of dictionaries,
- where each dictionary is a row in the CSV file.
+ - The column name used as a key for the resulting dictionary.
+ - If O(key) is unset, the module returns a list of dictionaries, where each dictionary is a row in the CSV file.
type: str
dialect:
description:
- - The CSV dialect to use when parsing the CSV file.
- - Possible values include V(excel), V(excel-tab) or V(unix).
+ - The CSV dialect to use when parsing the CSV file.
+ - Possible values include V(excel), V(excel-tab) or V(unix).
type: str
default: excel
fieldnames:
description:
- - A list of field names for every column.
- - This is needed if the CSV does not have a header.
+ - A list of field names for every column.
+ - This is needed if the CSV does not have a header.
type: list
elements: str
unique:
description:
- - Whether the O(key) used is expected to be unique.
+ - Whether the O(key) used is expected to be unique.
type: bool
default: true
delimiter:
description:
- - A one-character string used to separate fields.
- - When using this parameter, you change the default value used by O(dialect).
- - The default value depends on the dialect used.
+ - A one-character string used to separate fields.
+ - When using this parameter, you change the default value used by O(dialect).
+ - The default value depends on the dialect used.
type: str
skipinitialspace:
description:
- - Whether to ignore any whitespaces immediately following the delimiter.
- - When using this parameter, you change the default value used by O(dialect).
- - The default value depends on the dialect used.
+ - Whether to ignore any whitespaces immediately following the delimiter.
+ - When using this parameter, you change the default value used by O(dialect).
+ - The default value depends on the dialect used.
type: bool
strict:
description:
- - Whether to raise an exception on bad CSV input.
- - When using this parameter, you change the default value used by O(dialect).
- - The default value depends on the dialect used.
+ - Whether to raise an exception on bad CSV input.
+ - When using this parameter, you change the default value used by O(dialect).
+ - The default value depends on the dialect used.
type: bool
seealso:
- plugin: ansible.builtin.csvfile
plugin_type: lookup
description: Can be used to do selective lookups in CSV files from Jinja.
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
# Example CSV file with header
#
# name,uid,gid
@@ -118,9 +116,9 @@ EXAMPLES = r'''
delimiter: ';'
register: users
delegate_to: localhost
-'''
+"""
-RETURN = r'''
+RETURN = r"""
dict:
description: The CSV content as a dictionary.
returned: success
@@ -139,13 +137,13 @@ list:
returned: success
type: list
sample:
- - name: dag
- uid: 500
- gid: 500
- - name: jeroen
- uid: 501
- gid: 500
-'''
+ - name: dag
+ uid: 500
+ gid: 500
+ - name: jeroen
+ uid: 501
+ gid: 500
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native
diff --git a/plugins/modules/redfish_command.py b/plugins/modules/redfish_command.py
index 103f9e1d50..545506f924 100644
--- a/plugins/modules/redfish_command.py
+++ b/plugins/modules/redfish_command.py
@@ -8,13 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: redfish_command
short_description: Manages Out-Of-Band controllers using Redfish APIs
description:
- - Builds Redfish URIs locally and sends them to remote OOB controllers to
- perform an action.
+ - Builds Redfish URIs locally and sends them to remote OOB controllers to perform an action.
- Manages OOB controller ex. reboot, log management.
- Manages OOB controller users ex. add, remove, update.
- Manages system power ex. on, off, graceful and forced reboot.
@@ -62,32 +60,33 @@ options:
version_added: 2.3.0
id:
required: false
- aliases: [ account_id ]
+ aliases: [account_id]
description:
- ID of account to delete/modify.
- - Can also be used in account creation to work around vendor issues where the ID of the new user is required in the POST request.
+ - Can also be used in account creation to work around vendor issues where the ID of the new user is required in the
+ POST request.
type: str
new_username:
required: false
- aliases: [ account_username ]
+ aliases: [account_username]
description:
- Username of account to add/delete/modify.
type: str
new_password:
required: false
- aliases: [ account_password ]
+ aliases: [account_password]
description:
- New password of account to add/modify.
type: str
roleid:
required: false
- aliases: [ account_roleid ]
+ aliases: [account_roleid]
description:
- Role of account to add/modify.
type: str
account_types:
required: false
- aliases: [ account_accounttypes ]
+ aliases: [account_accounttypes]
description:
- Array of account types to apply to a user account.
type: list
@@ -95,7 +94,7 @@ options:
version_added: '7.2.0'
oem_account_types:
required: false
- aliases: [ account_oemaccounttypes ]
+ aliases: [account_oemaccounttypes]
description:
- Array of OEM account types to apply to a user account.
type: list
@@ -109,15 +108,14 @@ options:
timeout:
description:
- Timeout in seconds for HTTP requests to OOB controller.
- - The default value for this parameter changed from V(10) to V(60)
- in community.general 9.0.0.
+ - The default value for this parameter changed from V(10) to V(60) in community.general 9.0.0.
type: int
default: 60
boot_override_mode:
description:
- Boot mode when using an override.
type: str
- choices: [ Legacy, UEFI ]
+ choices: [Legacy, UEFI]
version_added: 3.5.0
uefi_target:
required: false
@@ -131,7 +129,7 @@ options:
type: str
update_username:
required: false
- aliases: [ account_updatename ]
+ aliases: [account_updatename]
description:
- New user name for updating account_username.
type: str
@@ -216,6 +214,31 @@ options:
- Handle to check the status of an update in progress.
type: str
version_added: '6.1.0'
+ update_custom_oem_header:
+ required: false
+ description:
+ - Optional OEM header, sent as separate form-data for the Multipart HTTP push update.
+ - The header shall start with "Oem" according to DMTF Redfish spec 12.6.2.2.
+ - For more details, see U(https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.21.0.html).
+ - If set, then O(update_custom_oem_params) is required too.
+ type: str
+ version_added: '10.1.0'
+ update_custom_oem_params:
+ required: false
+ description:
+ - Custom OEM properties for HTTP Multipart Push updates.
+ - If set, then O(update_custom_oem_header) is required too.
+ - The properties will be passed raw without any validation or conversion by Ansible. This means the content can be a
+ file, a string, or any other data. If the content is a dict that should be converted to JSON, then the content must
+ be converted to JSON before passing it to this module using the P(ansible.builtin.to_json#filter) filter.
+ type: raw
+ version_added: '10.1.0'
+ update_custom_oem_mime_type:
+ required: false
+ description:
+ - MIME Type for custom OEM properties for HTTP Multipart Push updates.
+ type: str
+ version_added: '10.1.0'
virtual_media:
required: false
description:
@@ -269,10 +292,8 @@ options:
type: str
strip_etag_quotes:
description:
- - Removes surrounding quotes of etag used in C(If-Match) header
- of C(PATCH) requests.
- - Only use this option to resolve bad vendor implementation where
- C(If-Match) only matches the unquoted etag string.
+ - Removes surrounding quotes of etag used in C(If-Match) header of C(PATCH) requests.
+ - Only use this option to resolve bad vendor implementation where C(If-Match) only matches the unquoted etag string.
type: bool
default: false
version_added: 3.7.0
@@ -286,7 +307,7 @@ options:
description:
- Mode to apply when reseting to default.
type: str
- choices: [ ResetAll, PreserveNetworkAndUsers, PreserveNetwork ]
+ choices: [ResetAll, PreserveNetworkAndUsers, PreserveNetwork]
version_added: 8.6.0
wait:
required: false
@@ -306,7 +327,7 @@ options:
required: false
description:
- SSL/TLS Ciphers to use for the request.
- - 'When a list is provided, all ciphers are joined in order with V(:).'
+ - When a list is provided, all ciphers are joined in order with V(:).
- See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT)
for more details.
- The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions.
@@ -317,497 +338,512 @@ options:
author:
- "Jose Delarosa (@jose-delarosa)"
- "T S Kushal (@TSKushal)"
-'''
+"""
-EXAMPLES = '''
- - name: Restart system power gracefully
- community.general.redfish_command:
- category: Systems
- command: PowerGracefulRestart
- resource_id: 437XR1138R2
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+EXAMPLES = r"""
+- name: Restart system power gracefully
+ community.general.redfish_command:
+ category: Systems
+ command: PowerGracefulRestart
+ resource_id: 437XR1138R2
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Turn system power off
- community.general.redfish_command:
- category: Systems
- command: PowerForceOff
- resource_id: 437XR1138R2
+- name: Turn system power off
+ community.general.redfish_command:
+ category: Systems
+ command: PowerForceOff
+ resource_id: 437XR1138R2
- - name: Restart system power forcefully
- community.general.redfish_command:
- category: Systems
- command: PowerForceRestart
- resource_id: 437XR1138R2
+- name: Restart system power forcefully
+ community.general.redfish_command:
+ category: Systems
+ command: PowerForceRestart
+ resource_id: 437XR1138R2
- - name: Shutdown system power gracefully
- community.general.redfish_command:
- category: Systems
- command: PowerGracefulShutdown
- resource_id: 437XR1138R2
+- name: Shutdown system power gracefully
+ community.general.redfish_command:
+ category: Systems
+ command: PowerGracefulShutdown
+ resource_id: 437XR1138R2
- - name: Turn system power on
- community.general.redfish_command:
- category: Systems
- command: PowerOn
- resource_id: 437XR1138R2
+- name: Turn system power on
+ community.general.redfish_command:
+ category: Systems
+ command: PowerOn
+ resource_id: 437XR1138R2
- - name: Reboot system power
- community.general.redfish_command:
- category: Systems
- command: PowerReboot
- resource_id: 437XR1138R2
+- name: Reboot system power
+ community.general.redfish_command:
+ category: Systems
+ command: PowerReboot
+ resource_id: 437XR1138R2
- - name: Set one-time boot device to {{ bootdevice }}
- community.general.redfish_command:
- category: Systems
- command: SetOneTimeBoot
- resource_id: 437XR1138R2
- bootdevice: "{{ bootdevice }}"
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set one-time boot device to {{ bootdevice }}
+ community.general.redfish_command:
+ category: Systems
+ command: SetOneTimeBoot
+ resource_id: 437XR1138R2
+ bootdevice: "{{ bootdevice }}"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set one-time boot device to UefiTarget of "/0x31/0x33/0x01/0x01"
- community.general.redfish_command:
- category: Systems
- command: SetOneTimeBoot
- resource_id: 437XR1138R2
- bootdevice: "UefiTarget"
- uefi_target: "/0x31/0x33/0x01/0x01"
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set one-time boot device to UefiTarget of "/0x31/0x33/0x01/0x01"
+ community.general.redfish_command:
+ category: Systems
+ command: SetOneTimeBoot
+ resource_id: 437XR1138R2
+ bootdevice: "UefiTarget"
+ uefi_target: "/0x31/0x33/0x01/0x01"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set one-time boot device to BootNext target of "Boot0001"
- community.general.redfish_command:
- category: Systems
- command: SetOneTimeBoot
- resource_id: 437XR1138R2
- bootdevice: "UefiBootNext"
- boot_next: "Boot0001"
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set one-time boot device to BootNext target of "Boot0001"
+ community.general.redfish_command:
+ category: Systems
+ command: SetOneTimeBoot
+ resource_id: 437XR1138R2
+ bootdevice: "UefiBootNext"
+ boot_next: "Boot0001"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set persistent boot device override
- community.general.redfish_command:
- category: Systems
- command: EnableContinuousBootOverride
- resource_id: 437XR1138R2
- bootdevice: "{{ bootdevice }}"
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set persistent boot device override
+ community.general.redfish_command:
+ category: Systems
+ command: EnableContinuousBootOverride
+ resource_id: 437XR1138R2
+ bootdevice: "{{ bootdevice }}"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set one-time boot to BiosSetup
- community.general.redfish_command:
- category: Systems
- command: SetOneTimeBoot
- boot_next: BiosSetup
- boot_override_mode: Legacy
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set one-time boot to BiosSetup
+ community.general.redfish_command:
+ category: Systems
+ command: SetOneTimeBoot
+ boot_next: BiosSetup
+ boot_override_mode: Legacy
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Disable persistent boot device override
- community.general.redfish_command:
- category: Systems
- command: DisableBootOverride
+- name: Disable persistent boot device override
+ community.general.redfish_command:
+ category: Systems
+ command: DisableBootOverride
- - name: Set system indicator LED to blink using security token for auth
- community.general.redfish_command:
- category: Systems
- command: IndicatorLedBlink
- resource_id: 437XR1138R2
- baseuri: "{{ baseuri }}"
- auth_token: "{{ result.session.token }}"
+- name: Set system indicator LED to blink using security token for auth
+ community.general.redfish_command:
+ category: Systems
+ command: IndicatorLedBlink
+ resource_id: 437XR1138R2
+ baseuri: "{{ baseuri }}"
+ auth_token: "{{ result.session.token }}"
- - name: Add user
- community.general.redfish_command:
- category: Accounts
- command: AddUser
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- new_username: "{{ new_username }}"
- new_password: "{{ new_password }}"
- roleid: "{{ roleid }}"
+- name: Add user
+ community.general.redfish_command:
+ category: Accounts
+ command: AddUser
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ new_username: "{{ new_username }}"
+ new_password: "{{ new_password }}"
+ roleid: "{{ roleid }}"
- - name: Add user with specified account types
- community.general.redfish_command:
- category: Accounts
- command: AddUser
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- new_username: "{{ new_username }}"
- new_password: "{{ new_password }}"
- roleid: "{{ roleid }}"
- account_types:
+- name: Add user with specified account types
+ community.general.redfish_command:
+ category: Accounts
+ command: AddUser
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ new_username: "{{ new_username }}"
+ new_password: "{{ new_password }}"
+ roleid: "{{ roleid }}"
+ account_types:
- Redfish
- WebUI
- - name: Add user using new option aliases
- community.general.redfish_command:
- category: Accounts
- command: AddUser
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_username: "{{ account_username }}"
- account_password: "{{ account_password }}"
- account_roleid: "{{ account_roleid }}"
+- name: Add user using new option aliases
+ community.general.redfish_command:
+ category: Accounts
+ command: AddUser
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_username: "{{ account_username }}"
+ account_password: "{{ account_password }}"
+ account_roleid: "{{ account_roleid }}"
- - name: Delete user
- community.general.redfish_command:
- category: Accounts
- command: DeleteUser
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_username: "{{ account_username }}"
+- name: Delete user
+ community.general.redfish_command:
+ category: Accounts
+ command: DeleteUser
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_username: "{{ account_username }}"
- - name: Disable user
- community.general.redfish_command:
- category: Accounts
- command: DisableUser
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_username: "{{ account_username }}"
+- name: Disable user
+ community.general.redfish_command:
+ category: Accounts
+ command: DisableUser
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_username: "{{ account_username }}"
- - name: Enable user
- community.general.redfish_command:
- category: Accounts
- command: EnableUser
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_username: "{{ account_username }}"
+- name: Enable user
+ community.general.redfish_command:
+ category: Accounts
+ command: EnableUser
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_username: "{{ account_username }}"
- - name: Add and enable user
- community.general.redfish_command:
- category: Accounts
- command: AddUser,EnableUser
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- new_username: "{{ new_username }}"
- new_password: "{{ new_password }}"
- roleid: "{{ roleid }}"
+- name: Add and enable user
+ community.general.redfish_command:
+ category: Accounts
+ command: AddUser,EnableUser
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ new_username: "{{ new_username }}"
+ new_password: "{{ new_password }}"
+ roleid: "{{ roleid }}"
- - name: Update user password
- community.general.redfish_command:
- category: Accounts
- command: UpdateUserPassword
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_username: "{{ account_username }}"
- account_password: "{{ account_password }}"
+- name: Update user password
+ community.general.redfish_command:
+ category: Accounts
+ command: UpdateUserPassword
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_username: "{{ account_username }}"
+ account_password: "{{ account_password }}"
- - name: Update user role
- community.general.redfish_command:
- category: Accounts
- command: UpdateUserRole
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_username: "{{ account_username }}"
- roleid: "{{ roleid }}"
+- name: Update user role
+ community.general.redfish_command:
+ category: Accounts
+ command: UpdateUserRole
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_username: "{{ account_username }}"
+ roleid: "{{ roleid }}"
- - name: Update user name
- community.general.redfish_command:
- category: Accounts
- command: UpdateUserName
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_username: "{{ account_username }}"
- account_updatename: "{{ account_updatename }}"
+- name: Update user name
+ community.general.redfish_command:
+ category: Accounts
+ command: UpdateUserName
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_username: "{{ account_username }}"
+ account_updatename: "{{ account_updatename }}"
- - name: Update user name
- community.general.redfish_command:
- category: Accounts
- command: UpdateUserName
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_username: "{{ account_username }}"
- update_username: "{{ update_username }}"
+- name: Update user name
+ community.general.redfish_command:
+ category: Accounts
+ command: UpdateUserName
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_username: "{{ account_username }}"
+ update_username: "{{ update_username }}"
- - name: Update AccountService properties
- community.general.redfish_command:
- category: Accounts
- command: UpdateAccountServiceProperties
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_properties:
- AccountLockoutThreshold: 5
- AccountLockoutDuration: 600
+- name: Update AccountService properties
+ community.general.redfish_command:
+ category: Accounts
+ command: UpdateAccountServiceProperties
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_properties:
+ AccountLockoutThreshold: 5
+ AccountLockoutDuration: 600
- - name: Update user AccountTypes
- community.general.redfish_command:
- category: Accounts
- command: UpdateUserAccountTypes
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- account_username: "{{ account_username }}"
- account_types:
- - Redfish
- - WebUI
+- name: Update user AccountTypes
+ community.general.redfish_command:
+ category: Accounts
+ command: UpdateUserAccountTypes
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ account_username: "{{ account_username }}"
+ account_types:
+ - Redfish
+ - WebUI
- - name: Clear Manager Logs with a timeout of 20 seconds
- community.general.redfish_command:
- category: Manager
- command: ClearLogs
- resource_id: BMC
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- timeout: 20
+- name: Clear Manager Logs with a timeout of 20 seconds
+ community.general.redfish_command:
+ category: Manager
+ command: ClearLogs
+ resource_id: BMC
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ timeout: 20
- - name: Create session
- community.general.redfish_command:
- category: Sessions
- command: CreateSession
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result
+- name: Create session
+ community.general.redfish_command:
+ category: Sessions
+ command: CreateSession
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result
- - name: Set chassis indicator LED to blink using security token for auth
- community.general.redfish_command:
- category: Chassis
- command: IndicatorLedBlink
- resource_id: 1U
- baseuri: "{{ baseuri }}"
- auth_token: "{{ result.session.token }}"
+- name: Set chassis indicator LED to blink using security token for auth
+ community.general.redfish_command:
+ category: Chassis
+ command: IndicatorLedBlink
+ resource_id: 1U
+ baseuri: "{{ baseuri }}"
+ auth_token: "{{ result.session.token }}"
- - name: Delete session using security token created by CreateSesssion above
- community.general.redfish_command:
- category: Sessions
- command: DeleteSession
- baseuri: "{{ baseuri }}"
- auth_token: "{{ result.session.token }}"
- session_uri: "{{ result.session.uri }}"
+- name: Delete session using security token created by CreateSesssion above
+ community.general.redfish_command:
+ category: Sessions
+ command: DeleteSession
+ baseuri: "{{ baseuri }}"
+ auth_token: "{{ result.session.token }}"
+ session_uri: "{{ result.session.uri }}"
- - name: Clear Sessions
- community.general.redfish_command:
- category: Sessions
- command: ClearSessions
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Clear Sessions
+ community.general.redfish_command:
+ category: Sessions
+ command: ClearSessions
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Simple update
- community.general.redfish_command:
- category: Update
- command: SimpleUpdate
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- update_image_uri: https://example.com/myupdate.img
+- name: Simple update
+ community.general.redfish_command:
+ category: Update
+ command: SimpleUpdate
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ update_image_uri: https://example.com/myupdate.img
- - name: Simple update with additional options
- community.general.redfish_command:
- category: Update
- command: SimpleUpdate
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- update_image_uri: //example.com/myupdate.img
- update_protocol: FTP
- update_targets:
- - /redfish/v1/UpdateService/FirmwareInventory/BMC
- update_creds:
- username: operator
- password: supersecretpwd
+- name: Simple update with additional options
+ community.general.redfish_command:
+ category: Update
+ command: SimpleUpdate
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ update_image_uri: //example.com/myupdate.img
+ update_protocol: FTP
+ update_targets:
+ - /redfish/v1/UpdateService/FirmwareInventory/BMC
+ update_creds:
+ username: operator
+ password: supersecretpwd
- - name: Multipart HTTP push update; timeout is 600 seconds to allow for a
- large image transfer
- community.general.redfish_command:
- category: Update
- command: MultipartHTTPPushUpdate
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- timeout: 600
- update_image_file: ~/images/myupdate.img
+- name: Multipart HTTP push update; timeout is 600 seconds to allow for a large image transfer
+ community.general.redfish_command:
+ category: Update
+ command: MultipartHTTPPushUpdate
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ timeout: 600
+ update_image_file: ~/images/myupdate.img
- - name: Multipart HTTP push with additional options; timeout is 600 seconds
- to allow for a large image transfer
- community.general.redfish_command:
- category: Update
- command: MultipartHTTPPushUpdate
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- timeout: 600
- update_image_file: ~/images/myupdate.img
- update_targets:
- - /redfish/v1/UpdateService/FirmwareInventory/BMC
- update_oem_params:
- PreserveConfiguration: false
+- name: Multipart HTTP push with additional options; timeout is 600 seconds to allow for a large image transfer
+ community.general.redfish_command:
+ category: Update
+ command: MultipartHTTPPushUpdate
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ timeout: 600
+ update_image_file: ~/images/myupdate.img
+ update_targets:
+ - /redfish/v1/UpdateService/FirmwareInventory/BMC
+ update_oem_params:
+ PreserveConfiguration: false
- - name: Perform requested operations to continue the update
- community.general.redfish_command:
- category: Update
- command: PerformRequestedOperations
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- update_handle: /redfish/v1/TaskService/TaskMonitors/735
+- name: Multipart HTTP push with custom OEM options
+ vars:
+ oem_payload:
+ ImageType: BMC
+ community.general.redfish_command:
+ category: Update
+ command: MultipartHTTPPushUpdate
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ update_image_file: ~/images/myupdate.img
+ update_targets:
+ - /redfish/v1/UpdateService/FirmwareInventory/BMC
+ update_custom_oem_header: OemParameters
+ update_custom_oem_mime_type: "application/json"
+ update_custom_oem_params: "{{ oem_payload | to_json }}"
- - name: Insert Virtual Media
- community.general.redfish_command:
- category: Systems
- command: VirtualMediaInsert
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- virtual_media:
- image_url: 'http://example.com/images/SomeLinux-current.iso'
- media_types:
- - CD
- - DVD
- resource_id: 1
+- name: Perform requested operations to continue the update
+ community.general.redfish_command:
+ category: Update
+ command: PerformRequestedOperations
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ update_handle: /redfish/v1/TaskService/TaskMonitors/735
- - name: Insert Virtual Media
- community.general.redfish_command:
- category: Manager
- command: VirtualMediaInsert
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- virtual_media:
- image_url: 'http://example.com/images/SomeLinux-current.iso'
- media_types:
- - CD
- - DVD
- resource_id: BMC
+- name: Insert Virtual Media
+ community.general.redfish_command:
+ category: Systems
+ command: VirtualMediaInsert
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ virtual_media:
+ image_url: 'http://example.com/images/SomeLinux-current.iso'
+ media_types:
+ - CD
+ - DVD
+ resource_id: 1
- - name: Eject Virtual Media
- community.general.redfish_command:
- category: Systems
- command: VirtualMediaEject
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- virtual_media:
- image_url: 'http://example.com/images/SomeLinux-current.iso'
- resource_id: 1
+- name: Insert Virtual Media
+ community.general.redfish_command:
+ category: Manager
+ command: VirtualMediaInsert
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ virtual_media:
+ image_url: 'http://example.com/images/SomeLinux-current.iso'
+ media_types:
+ - CD
+ - DVD
+ resource_id: BMC
- - name: Eject Virtual Media
- community.general.redfish_command:
- category: Manager
- command: VirtualMediaEject
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- virtual_media:
- image_url: 'http://example.com/images/SomeLinux-current.iso'
- resource_id: BMC
+- name: Eject Virtual Media
+ community.general.redfish_command:
+ category: Systems
+ command: VirtualMediaEject
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ virtual_media:
+ image_url: 'http://example.com/images/SomeLinux-current.iso'
+ resource_id: 1
- - name: Restart manager power gracefully
- community.general.redfish_command:
- category: Manager
- command: GracefulRestart
- resource_id: BMC
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Eject Virtual Media
+ community.general.redfish_command:
+ category: Manager
+ command: VirtualMediaEject
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ virtual_media:
+ image_url: 'http://example.com/images/SomeLinux-current.iso'
+ resource_id: BMC
- - name: Restart manager power gracefully and wait for it to be available
- community.general.redfish_command:
- category: Manager
- command: GracefulRestart
- resource_id: BMC
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- wait: True
+- name: Restart manager power gracefully
+ community.general.redfish_command:
+ category: Manager
+ command: GracefulRestart
+ resource_id: BMC
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Restart manager power gracefully
- community.general.redfish_command:
- category: Manager
- command: PowerGracefulRestart
- resource_id: BMC
+- name: Restart manager power gracefully and wait for it to be available
+ community.general.redfish_command:
+ category: Manager
+ command: GracefulRestart
+ resource_id: BMC
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ wait: true
- - name: Turn manager power off
- community.general.redfish_command:
- category: Manager
- command: PowerForceOff
- resource_id: BMC
+- name: Restart manager power gracefully
+ community.general.redfish_command:
+ category: Manager
+ command: PowerGracefulRestart
+ resource_id: BMC
- - name: Restart manager power forcefully
- community.general.redfish_command:
- category: Manager
- command: PowerForceRestart
- resource_id: BMC
+- name: Turn manager power off
+ community.general.redfish_command:
+ category: Manager
+ command: PowerForceOff
+ resource_id: BMC
- - name: Shutdown manager power gracefully
- community.general.redfish_command:
- category: Manager
- command: PowerGracefulShutdown
- resource_id: BMC
+- name: Restart manager power forcefully
+ community.general.redfish_command:
+ category: Manager
+ command: PowerForceRestart
+ resource_id: BMC
- - name: Turn manager power on
- community.general.redfish_command:
- category: Manager
- command: PowerOn
- resource_id: BMC
+- name: Shutdown manager power gracefully
+ community.general.redfish_command:
+ category: Manager
+ command: PowerGracefulShutdown
+ resource_id: BMC
- - name: Reboot manager power
- community.general.redfish_command:
- category: Manager
- command: PowerReboot
- resource_id: BMC
+- name: Turn manager power on
+ community.general.redfish_command:
+ category: Manager
+ command: PowerOn
+ resource_id: BMC
- - name: Factory reset manager to defaults
- community.general.redfish_command:
- category: Manager
- command: ResetToDefaults
- resource_id: BMC
- reset_to_defaults_mode: ResetAll
+- name: Reboot manager power
+ community.general.redfish_command:
+ category: Manager
+ command: PowerReboot
+ resource_id: BMC
- - name: Verify BIOS attributes
- community.general.redfish_command:
- category: Systems
- command: VerifyBiosAttributes
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- bios_attributes:
- SubNumaClustering: "Disabled"
- WorkloadProfile: "Virtualization-MaxPerformance"
-'''
+- name: Factory reset manager to defaults
+ community.general.redfish_command:
+ category: Manager
+ command: ResetToDefaults
+ resource_id: BMC
+ reset_to_defaults_mode: ResetAll
-RETURN = '''
+- name: Verify BIOS attributes
+ community.general.redfish_command:
+ category: Systems
+ command: VerifyBiosAttributes
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ bios_attributes:
+ SubNumaClustering: "Disabled"
+ WorkloadProfile: "Virtualization-MaxPerformance"
+"""
+
+RETURN = r"""
msg:
- description: Message with action result or error description
- returned: always
- type: str
- sample: "Action was successful"
+ description: Message with action result or error description.
+ returned: always
+ type: str
+ sample: "Action was successful"
return_values:
- description: Dictionary containing command-specific response data from the action.
- returned: on success
- type: dict
- version_added: 6.1.0
- sample: {
- "update_status": {
- "handle": "/redfish/v1/TaskService/TaskMonitors/735",
- "messages": [],
- "resets_requested": [],
- "ret": true,
- "status": "New"
- }
+ description: Dictionary containing command-specific response data from the action.
+ returned: on success
+ type: dict
+ version_added: 6.1.0
+ sample: {
+ "update_status": {
+ "handle": "/redfish/v1/TaskService/TaskMonitors/735",
+ "messages": [],
+ "resets_requested": [],
+ "ret": true,
+ "status": "New"
}
-'''
+ }
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.redfish_utils import RedfishUtils
@@ -817,8 +853,10 @@ from ansible.module_utils.common.text.converters import to_native
# More will be added as module features are expanded
CATEGORY_COMMANDS_ALL = {
"Systems": ["PowerOn", "PowerForceOff", "PowerForceRestart", "PowerGracefulRestart",
- "PowerGracefulShutdown", "PowerReboot", "PowerCycle", "SetOneTimeBoot", "EnableContinuousBootOverride", "DisableBootOverride",
- "IndicatorLedOn", "IndicatorLedOff", "IndicatorLedBlink", "VirtualMediaInsert", "VirtualMediaEject", "VerifyBiosAttributes"],
+ "PowerGracefulShutdown", "PowerReboot", "PowerCycle", "PowerFullPowerCycle",
+ "SetOneTimeBoot", "EnableContinuousBootOverride", "DisableBootOverride",
+ "IndicatorLedOn", "IndicatorLedOff", "IndicatorLedBlink", "VirtualMediaInsert",
+ "VirtualMediaEject", "VerifyBiosAttributes"],
"Chassis": ["IndicatorLedOn", "IndicatorLedOff", "IndicatorLedBlink"],
"Accounts": ["AddUser", "EnableUser", "DeleteUser", "DisableUser",
"UpdateUserRole", "UpdateUserPassword", "UpdateUserName",
@@ -863,6 +901,9 @@ def main():
update_protocol=dict(),
update_targets=dict(type='list', elements='str', default=[]),
update_oem_params=dict(type='dict'),
+ update_custom_oem_header=dict(type='str'),
+ update_custom_oem_mime_type=dict(type='str'),
+ update_custom_oem_params=dict(type='raw'),
update_creds=dict(
type='dict',
options=dict(
@@ -895,6 +936,7 @@ def main():
),
required_together=[
('username', 'password'),
+ ('update_custom_oem_header', 'update_custom_oem_params'),
],
required_one_of=[
('username', 'auth_token'),
@@ -941,6 +983,9 @@ def main():
'update_creds': module.params['update_creds'],
'update_apply_time': module.params['update_apply_time'],
'update_oem_params': module.params['update_oem_params'],
+ 'update_custom_oem_header': module.params['update_custom_oem_header'],
+ 'update_custom_oem_params': module.params['update_custom_oem_params'],
+ 'update_custom_oem_mime_type': module.params['update_custom_oem_mime_type'],
'update_handle': module.params['update_handle'],
}
diff --git a/plugins/modules/redfish_config.py b/plugins/modules/redfish_config.py
index 5b9caecc64..817cc18787 100644
--- a/plugins/modules/redfish_config.py
+++ b/plugins/modules/redfish_config.py
@@ -8,13 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: redfish_config
short_description: Manages Out-Of-Band controllers using Redfish APIs
description:
- - Builds Redfish URIs locally and sends them to remote OOB controllers to
- set or update a configuration attribute.
+ - Builds Redfish URIs locally and sends them to remote OOB controllers to set or update a configuration attribute.
- Manages BIOS configuration settings.
- Manages OOB controller configuration settings.
extends_documentation_fragment:
@@ -64,8 +62,7 @@ options:
timeout:
description:
- Timeout in seconds for HTTP requests to OOB controller.
- - The default value for this parameter changed from V(10) to V(60)
- in community.general 9.0.0.
+ - The default value for this parameter changed from V(10) to V(60) in community.general 9.0.0.
type: int
default: 60
boot_order:
@@ -111,10 +108,8 @@ options:
version_added: '0.2.0'
strip_etag_quotes:
description:
- - Removes surrounding quotes of etag used in C(If-Match) header
- of C(PATCH) requests.
- - Only use this option to resolve bad vendor implementation where
- C(If-Match) only matches the unquoted etag string.
+ - Removes surrounding quotes of etag used in C(If-Match) header of C(PATCH) requests.
+ - Only use this option to resolve bad vendor implementation where C(If-Match) only matches the unquoted etag string.
type: bool
default: false
version_added: 3.7.0
@@ -141,7 +136,7 @@ options:
storage_subsystem_id:
required: false
description:
- - Id of the Storage Subsystem on which the volume is to be created.
+ - ID of the Storage Subsystem on which the volume is to be created.
type: str
default: ''
version_added: '7.3.0'
@@ -165,23 +160,31 @@ options:
description:
- Setting parameter to enable or disable SecureBoot.
type: bool
- default: True
+ default: true
version_added: '7.5.0'
volume_details:
required: false
description:
- Setting dict of volume to be created.
- - If C(CapacityBytes) key is not specified in this dictionary, the size of
- the volume will be determined by the Redfish service. It is possible the
- size will not be the maximum available size.
+ - If C(CapacityBytes) key is not specified in this dictionary, the size of the volume will be determined by the Redfish
+ service. It is possible the size will not be the maximum available size.
type: dict
default: {}
version_added: '7.5.0'
+ power_restore_policy:
+ description:
+ - The desired power state of the system when power is restored after a power loss.
+ type: str
+ choices:
+ - AlwaysOn
+ - AlwaysOff
+ - LastState
+ version_added: '10.5.0'
ciphers:
required: false
description:
- SSL/TLS Ciphers to use for the request.
- - 'When a list is provided, all ciphers are joined in order with V(:).'
+ - When a list is provided, all ciphers are joined in order with V(:).
- See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT)
for more details.
- The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions.
@@ -192,195 +195,204 @@ options:
author:
- "Jose Delarosa (@jose-delarosa)"
- "T S Kushal (@TSKushal)"
-'''
+"""
-EXAMPLES = '''
- - name: Set BootMode to UEFI
- community.general.redfish_config:
- category: Systems
- command: SetBiosAttributes
- resource_id: 437XR1138R2
- bios_attributes:
- BootMode: "Uefi"
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+EXAMPLES = r"""
+- name: Set BootMode to UEFI
+ community.general.redfish_config:
+ category: Systems
+ command: SetBiosAttributes
+ resource_id: 437XR1138R2
+ bios_attributes:
+ BootMode: "Uefi"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set multiple BootMode attributes
- community.general.redfish_config:
- category: Systems
- command: SetBiosAttributes
- resource_id: 437XR1138R2
- bios_attributes:
- BootMode: "Bios"
- OneTimeBootMode: "Enabled"
- BootSeqRetry: "Enabled"
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set multiple BootMode attributes
+ community.general.redfish_config:
+ category: Systems
+ command: SetBiosAttributes
+ resource_id: 437XR1138R2
+ bios_attributes:
+ BootMode: "Bios"
+ OneTimeBootMode: "Enabled"
+ BootSeqRetry: "Enabled"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Enable PXE Boot for NIC1
- community.general.redfish_config:
- category: Systems
- command: SetBiosAttributes
- resource_id: 437XR1138R2
- bios_attributes:
- PxeDev1EnDis: Enabled
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Enable PXE Boot for NIC1
+ community.general.redfish_config:
+ category: Systems
+ command: SetBiosAttributes
+ resource_id: 437XR1138R2
+ bios_attributes:
+ PxeDev1EnDis: Enabled
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set BIOS default settings with a timeout of 20 seconds
- community.general.redfish_config:
- category: Systems
- command: SetBiosDefaultSettings
- resource_id: 437XR1138R2
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- timeout: 20
+- name: Set BIOS default settings with a timeout of 20 seconds
+ community.general.redfish_config:
+ category: Systems
+ command: SetBiosDefaultSettings
+ resource_id: 437XR1138R2
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ timeout: 20
- - name: Set boot order
- community.general.redfish_config:
- category: Systems
- command: SetBootOrder
- boot_order:
- - Boot0002
- - Boot0001
- - Boot0000
- - Boot0003
- - Boot0004
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set boot order
+ community.general.redfish_config:
+ category: Systems
+ command: SetBootOrder
+ boot_order:
+ - Boot0002
+ - Boot0001
+ - Boot0000
+ - Boot0003
+ - Boot0004
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set boot order to the default
- community.general.redfish_config:
- category: Systems
- command: SetDefaultBootOrder
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set boot order to the default
+ community.general.redfish_config:
+ category: Systems
+ command: SetDefaultBootOrder
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set Manager Network Protocols
- community.general.redfish_config:
- category: Manager
- command: SetNetworkProtocols
- network_protocols:
- SNMP:
- ProtocolEnabled: true
- Port: 161
- HTTP:
- ProtocolEnabled: false
- Port: 8080
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set Manager Network Protocols
+ community.general.redfish_config:
+ category: Manager
+ command: SetNetworkProtocols
+ network_protocols:
+ SNMP:
+ ProtocolEnabled: true
+ Port: 161
+ HTTP:
+ ProtocolEnabled: false
+ Port: 8080
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set Manager NIC
- community.general.redfish_config:
- category: Manager
- command: SetManagerNic
- nic_config:
- DHCPv4:
- DHCPEnabled: false
- IPv4StaticAddresses:
- Address: 192.168.1.3
- Gateway: 192.168.1.1
- SubnetMask: 255.255.255.0
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set Manager NIC
+ community.general.redfish_config:
+ category: Manager
+ command: SetManagerNic
+ nic_config:
+ DHCPv4:
+ DHCPEnabled: false
+ IPv4StaticAddresses:
+ Address: 192.168.1.3
+ Gateway: 192.168.1.1
+ SubnetMask: 255.255.255.0
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Disable Host Interface
- community.general.redfish_config:
- category: Manager
- command: SetHostInterface
- hostinterface_config:
- InterfaceEnabled: false
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Disable Host Interface
+ community.general.redfish_config:
+ category: Manager
+ command: SetHostInterface
+ hostinterface_config:
+ InterfaceEnabled: false
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Enable Host Interface for HostInterface resource ID '2'
- community.general.redfish_config:
- category: Manager
- command: SetHostInterface
- hostinterface_config:
- InterfaceEnabled: true
- hostinterface_id: "2"
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Enable Host Interface for HostInterface resource ID '2'
+ community.general.redfish_config:
+ category: Manager
+ command: SetHostInterface
+ hostinterface_config:
+ InterfaceEnabled: true
+ hostinterface_id: "2"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set SessionService Session Timeout to 30 minutes
- community.general.redfish_config:
- category: Sessions
- command: SetSessionService
- sessions_config:
- SessionTimeout: 1800
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Set SessionService Session Timeout to 30 minutes
+ community.general.redfish_config:
+ category: Sessions
+ command: SetSessionService
+ sessions_config:
+ SessionTimeout: 1800
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Enable SecureBoot
- community.general.redfish_config:
- category: Systems
- command: EnableSecureBoot
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Enable SecureBoot
+ community.general.redfish_config:
+ category: Systems
+ command: EnableSecureBoot
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Set SecureBoot
- community.general.redfish_config:
- category: Systems
- command: SetSecureBoot
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- secure_boot_enable: True
+- name: Set SecureBoot
+ community.general.redfish_config:
+ category: Systems
+ command: SetSecureBoot
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ secure_boot_enable: true
- - name: Delete All Volumes
- community.general.redfish_config:
- category: Systems
- command: DeleteVolumes
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- storage_subsystem_id: "DExxxxxx"
- volume_ids: ["volume1", "volume2"]
+- name: Delete All Volumes
+ community.general.redfish_config:
+ category: Systems
+ command: DeleteVolumes
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ storage_subsystem_id: "DExxxxxx"
+ volume_ids: ["volume1", "volume2"]
- - name: Create Volume
- community.general.redfish_config:
- category: Systems
- command: CreateVolume
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- storage_subsystem_id: "DExxxxxx"
- volume_details:
- Name: "MR Volume"
- RAIDType: "RAID0"
- Drives:
- - "/redfish/v1/Systems/1/Storage/DE00B000/Drives/1"
+- name: Create Volume
+ community.general.redfish_config:
+ category: Systems
+ command: CreateVolume
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ storage_subsystem_id: "DExxxxxx"
+ volume_details:
+ Name: "MR Volume"
+ RAIDType: "RAID0"
+ Drives:
+ - "/redfish/v1/Systems/1/Storage/DE00B000/Drives/1"
- - name: Set service identification to {{ service_id }}
- community.general.redfish_config:
- category: Manager
- command: SetServiceIdentification
- service_id: "{{ service_id }}"
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
-'''
+- name: Set PowerRestorePolicy
+ community.general.redfish_config:
+ category: Systems
+ command: SetPowerRestorePolicy
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ power_restore_policy: "AlwaysOff"
-RETURN = '''
+- name: Set service identification to {{ service_id }}
+ community.general.redfish_config:
+ category: Manager
+ command: SetServiceIdentification
+ service_id: "{{ service_id }}"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+"""
+
+RETURN = r"""
msg:
- description: Message with action result or error description
- returned: always
- type: str
- sample: "Action was successful"
-'''
+ description: Message with action result or error description.
+ returned: always
+ type: str
+ sample: "Action was successful"
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.redfish_utils import RedfishUtils
@@ -390,7 +402,8 @@ from ansible.module_utils.common.text.converters import to_native
# More will be added as module features are expanded
CATEGORY_COMMANDS_ALL = {
"Systems": ["SetBiosDefaultSettings", "SetBiosAttributes", "SetBootOrder",
- "SetDefaultBootOrder", "EnableSecureBoot", "SetSecureBoot", "DeleteVolumes", "CreateVolume"],
+ "SetDefaultBootOrder", "EnableSecureBoot", "SetSecureBoot", "DeleteVolumes", "CreateVolume",
+ "SetPowerRestorePolicy"],
"Manager": ["SetNetworkProtocols", "SetManagerNic", "SetHostInterface", "SetServiceIdentification"],
"Sessions": ["SetSessionService"],
}
@@ -429,6 +442,7 @@ def main():
volume_ids=dict(type='list', default=[], elements='str'),
secure_boot_enable=dict(type='bool', default=True),
volume_details=dict(type='dict', default={}),
+ power_restore_policy=dict(choices=['AlwaysOn', 'AlwaysOff', 'LastState']),
ciphers=dict(type='list', elements='str'),
),
required_together=[
@@ -494,6 +508,9 @@ def main():
storage_subsystem_id = module.params['storage_subsystem_id']
storage_none_volume_deletion = module.params['storage_none_volume_deletion']
+ # Power Restore Policy
+ power_restore_policy = module.params['power_restore_policy']
+
# ciphers
ciphers = module.params['ciphers']
@@ -537,6 +554,8 @@ def main():
result = rf_utils.delete_volumes(storage_subsystem_id, volume_ids)
elif command == "CreateVolume":
result = rf_utils.create_volume(volume_details, storage_subsystem_id, storage_none_volume_deletion)
+ elif command == "SetPowerRestorePolicy":
+ result = rf_utils.set_power_restore_policy(power_restore_policy)
elif category == "Manager":
# execute only if we find a Manager service resource
diff --git a/plugins/modules/redfish_info.py b/plugins/modules/redfish_info.py
index b1b4a45ee5..66d41883e5 100644
--- a/plugins/modules/redfish_info.py
+++ b/plugins/modules/redfish_info.py
@@ -8,13 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: redfish_info
short_description: Manages Out-Of-Band controllers using Redfish APIs
description:
- - Builds Redfish URIs locally and sends them to remote OOB controllers to
- get information back.
+ - Builds Redfish URIs locally and sends them to remote OOB controllers to get information back.
- Information retrieved is placed in a location specified by the user.
extends_documentation_fragment:
- community.general.attributes
@@ -63,8 +61,7 @@ options:
timeout:
description:
- Timeout in seconds for HTTP requests to OOB controller.
- - The default value for this parameter changed from V(10) to V(60)
- in community.general 9.0.0.
+ - The default value for this parameter changed from V(10) to V(60) in community.general 9.0.0.
type: int
default: 60
update_handle:
@@ -77,7 +74,7 @@ options:
required: false
description:
- SSL/TLS Ciphers to use for the request.
- - 'When a list is provided, all ciphers are joined in order with V(:).'
+ - When a list is provided, all ciphers are joined in order with V(:).
- See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT)
for more details.
- The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions.
@@ -86,309 +83,325 @@ options:
version_added: 9.2.0
author: "Jose Delarosa (@jose-delarosa)"
-'''
+"""
-EXAMPLES = '''
- - name: Get CPU inventory
- community.general.redfish_info:
- category: Systems
- command: GetCpuInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result
+EXAMPLES = r"""
+- name: Get CPU inventory
+ community.general.redfish_info:
+ category: Systems
+ command: GetCpuInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result
- - name: Print fetched information
- ansible.builtin.debug:
- msg: "{{ result.redfish_facts.cpu.entries | to_nice_json }}"
+- name: Print fetched information
+ ansible.builtin.debug:
+ msg: "{{ result.redfish_facts.cpu.entries | to_nice_json }}"
- - name: Get CPU model
- community.general.redfish_info:
- category: Systems
- command: GetCpuInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result
+- name: Get CPU model
+ community.general.redfish_info:
+ category: Systems
+ command: GetCpuInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result
- - name: Print fetched information
- ansible.builtin.debug:
- msg: "{{ result.redfish_facts.cpu.entries.0.Model }}"
+- name: Print fetched information
+ ansible.builtin.debug:
+ msg: "{{ result.redfish_facts.cpu.entries.0.Model }}"
- - name: Get memory inventory
- community.general.redfish_info:
- category: Systems
- command: GetMemoryInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result
+- name: Get memory inventory
+ community.general.redfish_info:
+ category: Systems
+ command: GetMemoryInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result
- - name: Get fan inventory with a timeout of 20 seconds
- community.general.redfish_info:
- category: Chassis
- command: GetFanInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- timeout: 20
- register: result
+- name: Get fan inventory with a timeout of 20 seconds
+ community.general.redfish_info:
+ category: Chassis
+ command: GetFanInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ timeout: 20
+ register: result
- - name: Get Virtual Media information
- community.general.redfish_info:
- category: Manager
- command: GetVirtualMedia
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result
+- name: Get Virtual Media information
+ community.general.redfish_info:
+ category: Manager
+ command: GetVirtualMedia
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result
- - name: Print fetched information
- ansible.builtin.debug:
- msg: "{{ result.redfish_facts.virtual_media.entries | to_nice_json }}"
+- name: Print fetched information
+ ansible.builtin.debug:
+ msg: "{{ result.redfish_facts.virtual_media.entries | to_nice_json }}"
- - name: Get Virtual Media information from Systems
- community.general.redfish_info:
- category: Systems
- command: GetVirtualMedia
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result
+- name: Get Virtual Media information from Systems
+ community.general.redfish_info:
+ category: Systems
+ command: GetVirtualMedia
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result
- - name: Print fetched information
- ansible.builtin.debug:
- msg: "{{ result.redfish_facts.virtual_media.entries | to_nice_json }}"
+- name: Print fetched information
+ ansible.builtin.debug:
+ msg: "{{ result.redfish_facts.virtual_media.entries | to_nice_json }}"
- - name: Get Volume Inventory
- community.general.redfish_info:
- category: Systems
- command: GetVolumeInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result
- - name: Print fetched information
- ansible.builtin.debug:
- msg: "{{ result.redfish_facts.volume.entries | to_nice_json }}"
+- name: Get Volume Inventory
+ community.general.redfish_info:
+ category: Systems
+ command: GetVolumeInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result
+- name: Print fetched information
+ ansible.builtin.debug:
+ msg: "{{ result.redfish_facts.volume.entries | to_nice_json }}"
- - name: Get Session information
- community.general.redfish_info:
- category: Sessions
- command: GetSessions
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result
+- name: Get Session information
+ community.general.redfish_info:
+ category: Sessions
+ command: GetSessions
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result
- - name: Print fetched information
- ansible.builtin.debug:
- msg: "{{ result.redfish_facts.session.entries | to_nice_json }}"
+- name: Print fetched information
+ ansible.builtin.debug:
+ msg: "{{ result.redfish_facts.session.entries | to_nice_json }}"
- - name: Get default inventory information
- community.general.redfish_info:
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- register: result
- - name: Print fetched information
- ansible.builtin.debug:
- msg: "{{ result.redfish_facts | to_nice_json }}"
+- name: Get default inventory information
+ community.general.redfish_info:
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ register: result
+- name: Print fetched information
+ ansible.builtin.debug:
+ msg: "{{ result.redfish_facts | to_nice_json }}"
- - name: Get several inventories
- community.general.redfish_info:
- category: Systems
- command: GetNicInventory,GetBiosAttributes
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get several inventories
+ community.general.redfish_info:
+ category: Systems
+ command: GetNicInventory,GetBiosAttributes
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get default system inventory and user information
- community.general.redfish_info:
- category: Systems,Accounts
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get configuration of the AccountService
+ community.general.redfish_info:
+ category: Accounts
+ command: GetAccountServiceConfig
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get default system, user and firmware information
- community.general.redfish_info:
- category: ["Systems", "Accounts", "Update"]
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get default system inventory and user information
+ community.general.redfish_info:
+ category: Systems,Accounts
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get Manager NIC inventory information
- community.general.redfish_info:
- category: Manager
- command: GetManagerNicInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get default system, user and firmware information
+ community.general.redfish_info:
+ category: ["Systems", "Accounts", "Update"]
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get boot override information
- community.general.redfish_info:
- category: Systems
- command: GetBootOverride
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get Manager NIC inventory information
+ community.general.redfish_info:
+ category: Manager
+ command: GetManagerNicInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get chassis inventory
- community.general.redfish_info:
- category: Chassis
- command: GetChassisInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get boot override information
+ community.general.redfish_info:
+ category: Systems
+ command: GetBootOverride
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get all information available in the Manager category
- community.general.redfish_info:
- category: Manager
- command: all
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get chassis inventory
+ community.general.redfish_info:
+ category: Chassis
+ command: GetChassisInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get firmware update capability information
- community.general.redfish_info:
- category: Update
- command: GetFirmwareUpdateCapabilities
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get all information available in the Manager category
+ community.general.redfish_info:
+ category: Manager
+ command: all
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get firmware inventory
- community.general.redfish_info:
- category: Update
- command: GetFirmwareInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get firmware update capability information
+ community.general.redfish_info:
+ category: Update
+ command: GetFirmwareUpdateCapabilities
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get service identification
- community.general.redfish_info:
- category: Manager
- command: GetServiceIdentification
- manager: "{{ manager }}"
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get firmware inventory
+ community.general.redfish_info:
+ category: Update
+ command: GetFirmwareInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get software inventory
- community.general.redfish_info:
- category: Update
- command: GetSoftwareInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get service identification
+ community.general.redfish_info:
+ category: Manager
+ command: GetServiceIdentification
+ manager: "{{ manager }}"
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get the status of an update operation
- community.general.redfish_info:
- category: Update
- command: GetUpdateStatus
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- update_handle: /redfish/v1/TaskService/TaskMonitors/735
+- name: Get software inventory
+ community.general.redfish_info:
+ category: Update
+ command: GetSoftwareInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get Manager Services
- community.general.redfish_info:
- category: Manager
- command: GetNetworkProtocols
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get the status of an update operation
+ community.general.redfish_info:
+ category: Update
+ command: GetUpdateStatus
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ update_handle: /redfish/v1/TaskService/TaskMonitors/735
- - name: Get all information available in all categories
- community.general.redfish_info:
- category: all
- command: all
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get Manager Services
+ community.general.redfish_info:
+ category: Manager
+ command: GetNetworkProtocols
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get system health report
- community.general.redfish_info:
- category: Systems
- command: GetHealthReport
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get all information available in all categories
+ community.general.redfish_info:
+ category: all
+ command: all
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get chassis health report
- community.general.redfish_info:
- category: Chassis
- command: GetHealthReport
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get system health report
+ community.general.redfish_info:
+ category: Systems
+ command: GetHealthReport
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get manager health report
- community.general.redfish_info:
- category: Manager
- command: GetHealthReport
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get chassis health report
+ community.general.redfish_info:
+ category: Chassis
+ command: GetHealthReport
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get manager Redfish Host Interface inventory
- community.general.redfish_info:
- category: Manager
- command: GetHostInterfaces
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get manager health report
+ community.general.redfish_info:
+ category: Manager
+ command: GetHealthReport
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get Manager Inventory
- community.general.redfish_info:
- category: Manager
- command: GetManagerInventory
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get manager Redfish Host Interface inventory
+ community.general.redfish_info:
+ category: Manager
+ command: GetHostInterfaces
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get HPE Thermal Config
- community.general.redfish_info:
- category: Chassis
- command: GetHPEThermalConfig
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get Manager Inventory
+ community.general.redfish_info:
+ category: Manager
+ command: GetManagerInventory
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get HPE Fan Percent Minimum
- community.general.redfish_info:
- category: Chassis
- command: GetHPEFanPercentMin
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get HPE Thermal Config
+ community.general.redfish_info:
+ category: Chassis
+ command: GetHPEThermalConfig
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Get BIOS registry
- community.general.redfish_info:
- category: Systems
- command: GetBiosRegistries
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
+- name: Get HPE Fan Percent Minimum
+ community.general.redfish_info:
+ category: Chassis
+ command: GetHPEFanPercentMin
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
- - name: Check the availability of the service with a timeout of 5 seconds
- community.general.redfish_info:
- category: Service
- command: CheckAvailability
- baseuri: "{{ baseuri }}"
- username: "{{ username }}"
- password: "{{ password }}"
- timeout: 5
- register: result
-'''
+- name: Get BIOS registry
+ community.general.redfish_info:
+ category: Systems
+ command: GetBiosRegistries
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
-RETURN = '''
+- name: Get power restore policy
+ community.general.redfish_info:
+ category: Systems
+ command: GetPowerRestorePolicy
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+
+- name: Check the availability of the service with a timeout of 5 seconds
+ community.general.redfish_info:
+ category: Service
+ command: CheckAvailability
+ baseuri: "{{ baseuri }}"
+ username: "{{ username }}"
+ password: "{{ password }}"
+ timeout: 5
+ register: result
+"""
+
+RETURN = r"""
result:
- description: different results depending on task
- returned: always
- type: dict
- sample: List of CPUs on system
-'''
+ description: Different results depending on task.
+ returned: always
+ type: dict
+ sample: List of CPUs on system
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.redfish_utils import RedfishUtils
@@ -397,10 +410,11 @@ CATEGORY_COMMANDS_ALL = {
"Systems": ["GetSystemInventory", "GetPsuInventory", "GetCpuInventory",
"GetMemoryInventory", "GetNicInventory", "GetHealthReport",
"GetStorageControllerInventory", "GetDiskInventory", "GetVolumeInventory",
- "GetBiosAttributes", "GetBootOrder", "GetBootOverride", "GetVirtualMedia", "GetBiosRegistries"],
+ "GetBiosAttributes", "GetBootOrder", "GetBootOverride", "GetVirtualMedia", "GetBiosRegistries",
+ "GetPowerRestorePolicy"],
"Chassis": ["GetFanInventory", "GetPsuInventory", "GetChassisPower",
"GetChassisThermals", "GetChassisInventory", "GetHealthReport", "GetHPEThermalConfig", "GetHPEFanPercentMin"],
- "Accounts": ["ListUsers"],
+ "Accounts": ["ListUsers", "GetAccountServiceConfig"],
"Sessions": ["GetSessions"],
"Update": ["GetFirmwareInventory", "GetFirmwareUpdateCapabilities", "GetSoftwareInventory",
"GetUpdateStatus"],
@@ -539,6 +553,8 @@ def main():
result["virtual_media"] = rf_utils.get_multi_virtualmedia(category)
elif command == "GetBiosRegistries":
result["bios_registries"] = rf_utils.get_bios_registries()
+ elif command == "GetPowerRestorePolicy":
+ result["power_restore_policy"] = rf_utils.get_multi_power_restore_policy()
elif category == "Chassis":
# execute only if we find Chassis resource
@@ -573,6 +589,8 @@ def main():
for command in command_list:
if command == "ListUsers":
result["user"] = rf_utils.list_users()
+ elif command == "GetAccountServiceConfig":
+ result["accountservice_config"] = rf_utils.get_accountservice_properties()
elif category == "Update":
# execute only if we find UpdateService resources
diff --git a/plugins/modules/redhat_subscription.py b/plugins/modules/redhat_subscription.py
index 338fb92ebd..6818253c9d 100644
--- a/plugins/modules/redhat_subscription.py
+++ b/plugins/modules/redhat_subscription.py
@@ -10,203 +10,189 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: redhat_subscription
short_description: Manage registration and subscriptions to RHSM using C(subscription-manager)
description:
- - Manage registration and subscription to the Red Hat Subscription Management entitlement platform using the C(subscription-manager) command,
- registering using D-Bus if possible.
+ - Manage registration and subscription to the Red Hat Subscription Management entitlement platform using the C(subscription-manager)
+ command, registering using D-Bus if possible.
author: "Barnaby Court (@barnabycourt)"
notes:
- - |
- The module tries to use the D-Bus C(rhsm) service (part of C(subscription-manager))
- to register, starting from community.general 6.5.0: this is done so credentials
- (username, password, activation keys) can be passed to C(rhsm) in a secure way.
- C(subscription-manager) itself gets credentials only as arguments of command line
- parameters, which is I(not) secure, as they can be easily stolen by checking the
- process listing on the system. Due to limitations of the D-Bus interface of C(rhsm),
- the module will I(not) use D-Bus for registration when trying either to register
- using O(token), or when specifying O(environment), or when the system is old
- (typically RHEL 7 older than 7.4, RHEL 6, and older).
- - In order to register a system, subscription-manager requires either a username and password, or an activationkey and an Organization ID.
- - Since 2.5 values for O(server_hostname), O(server_insecure), O(rhsm_baseurl),
- O(server_proxy_hostname), O(server_proxy_port), O(server_proxy_user) and
- O(server_proxy_password) are no longer taken from the C(/etc/rhsm/rhsm.conf)
- config file and default to V(null).
- - It is possible to interact with C(subscription-manager) only as root,
- so root permissions are required to successfully run this module.
- - Since community.general 6.5.0, credentials (that is, O(username) and O(password),
- O(activationkey), or O(token)) are needed only in case the the system is not registered,
- or O(force_register) is specified; this makes it possible to use the module to tweak an
- already registered system, for example attaching pools to it (using O(pool_ids)),
- and modifying the C(syspurpose) attributes (using O(syspurpose)).
+ - 'The module tries to use the D-Bus C(rhsm) service (part of C(subscription-manager)) to register, starting from community.general
+ 6.5.0: this is done so credentials (username, password, activation keys) can be passed to C(rhsm) in a secure way. C(subscription-manager)
+ itself gets credentials only as arguments of command line parameters, which is I(not) secure, as they can be easily stolen
+ by checking the process listing on the system. Due to limitations of the D-Bus interface of C(rhsm), the module will I(not)
+ use D-Bus for registration when trying either to register using O(token), or when specifying O(environment), or when the
+ system is old (typically RHEL 7 older than 7.4, RHEL 6, and older).'
+ - In order to register a system, subscription-manager requires either a username and password, or an activationkey and an
+ Organization ID.
+ - Since 2.5 values for O(server_hostname), O(server_insecure), O(rhsm_baseurl), O(server_proxy_hostname), O(server_proxy_port),
+ O(server_proxy_user) and O(server_proxy_password) are no longer taken from the C(/etc/rhsm/rhsm.conf) config file and
+ default to V(null).
+ - It is possible to interact with C(subscription-manager) only as root, so root permissions are required to successfully
+ run this module.
+ - Since community.general 6.5.0, credentials (that is, O(username) and O(password), O(activationkey), or O(token)) are needed
+ only in case the the system is not registered, or O(force_register) is specified; this makes it possible to use the module
+ to tweak an already registered system, for example attaching pools to it (using O(pool_ids)), and modifying the C(syspurpose)
+ attributes (using O(syspurpose)).
requirements:
- - subscription-manager
- - Optionally the C(dbus) Python library; this is usually included in the OS
- as it is used by C(subscription-manager).
+ - subscription-manager
+ - Optionally the C(dbus) Python library; this is usually included in the OS as it is used by C(subscription-manager).
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- state:
- description:
- - whether to register and subscribe (V(present)), or unregister (V(absent)) a system
- choices: [ "present", "absent" ]
- default: "present"
+ state:
+ description:
+ - Whether to register and subscribe (V(present)), or unregister (V(absent)) a system.
+ choices: ["present", "absent"]
+ default: "present"
+ type: str
+ username:
+ description:
+ - Access.redhat.com or Red Hat Satellite or Katello username.
+ type: str
+ password:
+ description:
+ - Access.redhat.com or Red Hat Satellite or Katello password.
+ type: str
+ token:
+ description:
+ - Sso.redhat.com API access token.
+ type: str
+ version_added: 6.3.0
+ server_hostname:
+ description:
+ - Specify an alternative Red Hat Subscription Management or Red Hat Satellite or Katello server.
+ type: str
+ server_insecure:
+ description:
+ - Enable or disable https server certificate verification when connecting to O(server_hostname).
+ type: str
+ server_prefix:
+ description:
+ - Specify the prefix when registering to the Red Hat Subscription Management or Red Hat Satellite or Katello server.
+ type: str
+ version_added: 3.3.0
+ server_port:
+ description:
+ - Specify the port when registering to the Red Hat Subscription Management or Red Hat Satellite or Katello server.
+ type: str
+ version_added: 3.3.0
+ rhsm_baseurl:
+ description:
+ - Specify CDN baseurl.
+ type: str
+ rhsm_repo_ca_cert:
+ description:
+ - Specify an alternative location for a CA certificate for CDN.
+ type: str
+ server_proxy_hostname:
+ description:
+ - Specify an HTTP proxy hostname.
+ type: str
+ server_proxy_scheme:
+ description:
+ - Specify an HTTP proxy scheme, for example V(http) or V(https).
+ type: str
+ version_added: 6.2.0
+ server_proxy_port:
+ description:
+ - Specify an HTTP proxy port.
+ type: str
+ server_proxy_user:
+ description:
+ - Specify a user for HTTP proxy with basic authentication.
+ type: str
+ server_proxy_password:
+ description:
+ - Specify a password for HTTP proxy with basic authentication.
+ type: str
+ auto_attach:
+ description:
+ - Upon successful registration, auto-consume available subscriptions.
+ - Please note that the alias O(ignore:autosubscribe) was removed in community.general 9.0.0.
+ type: bool
+ activationkey:
+ description:
+ - Supply an activation key for use with registration.
+ type: str
+ org_id:
+ description:
+ - Organization ID to use in conjunction with activationkey.
+ type: str
+ environment:
+ description:
+ - Register with a specific environment in the destination org. Used with Red Hat Satellite or Katello.
+ type: str
+ pool_ids:
+ description:
+ - Specify subscription pool IDs to consume.
+ - 'A pool ID may be specified as a C(string) - just the pool ID (for example
+ V(0123456789abcdef0123456789abcdef)), or as a C(dict) with the pool ID as the key, and a quantity as the value (for
+ example V(0123456789abcdef0123456789abcdef: 2). If the quantity is provided, it is used to consume multiple entitlements
+ from a pool (the pool must support this).'
+ default: []
+ type: list
+ elements: raw
+ consumer_type:
+ description:
+ - The type of unit to register, defaults to system.
+ type: str
+ consumer_name:
+ description:
+ - Name of the system to register, defaults to the hostname.
+ type: str
+ consumer_id:
+ description:
+ - References an existing consumer ID to resume using a previous registration for this system. If the system's identity
+ certificate is lost or corrupted, this option allows it to resume using its previous identity and subscriptions. The
+ default is to not specify a consumer ID so a new ID is created.
+ type: str
+ force_register:
+ description:
+ - Register the system even if it is already registered.
+ type: bool
+ default: false
+ release:
+ description:
+ - Set a release version.
+ type: str
+ syspurpose:
+ description:
+ - Set syspurpose attributes in file C(/etc/rhsm/syspurpose/syspurpose.json) and synchronize these attributes with RHSM
+ server. Syspurpose attributes help attach the most appropriate subscriptions to the system automatically. When C(syspurpose.json)
+ file already contains some attributes, then new attributes overwrite existing attributes. When some attribute is not
+ listed in the new list of attributes, the existing attribute will be removed from C(syspurpose.json) file. Unknown
+ attributes are ignored.
+ type: dict
+ suboptions:
+ usage:
+ description: Syspurpose attribute usage.
type: str
- username:
- description:
- - access.redhat.com or Red Hat Satellite or Katello username
+ role:
+ description: Syspurpose attribute role.
type: str
- password:
- description:
- - access.redhat.com or Red Hat Satellite or Katello password
+ service_level_agreement:
+ description: Syspurpose attribute service_level_agreement.
type: str
- token:
- description:
- - sso.redhat.com API access token.
- type: str
- version_added: 6.3.0
- server_hostname:
- description:
- - Specify an alternative Red Hat Subscription Management or Red Hat Satellite or Katello server.
- type: str
- server_insecure:
- description:
- - Enable or disable https server certificate verification when connecting to O(server_hostname).
- type: str
- server_prefix:
- description:
- - Specify the prefix when registering to the Red Hat Subscription Management or Red Hat Satellite or Katello server.
- type: str
- version_added: 3.3.0
- server_port:
- description:
- - Specify the port when registering to the Red Hat Subscription Management or Red Hat Satellite or Katello server.
- type: str
- version_added: 3.3.0
- rhsm_baseurl:
- description:
- - Specify CDN baseurl
- type: str
- rhsm_repo_ca_cert:
- description:
- - Specify an alternative location for a CA certificate for CDN
- type: str
- server_proxy_hostname:
- description:
- - Specify an HTTP proxy hostname.
- type: str
- server_proxy_scheme:
- description:
- - Specify an HTTP proxy scheme, for example V(http) or V(https).
- type: str
- version_added: 6.2.0
- server_proxy_port:
- description:
- - Specify an HTTP proxy port.
- type: str
- server_proxy_user:
- description:
- - Specify a user for HTTP proxy with basic authentication
- type: str
- server_proxy_password:
- description:
- - Specify a password for HTTP proxy with basic authentication
- type: str
- auto_attach:
- description:
- - Upon successful registration, auto-consume available subscriptions
- - |
- Please note that the alias O(ignore:autosubscribe) was removed in
- community.general 9.0.0.
- type: bool
- activationkey:
- description:
- - supply an activation key for use with registration
- type: str
- org_id:
- description:
- - Organization ID to use in conjunction with activationkey
- type: str
- environment:
- description:
- - Register with a specific environment in the destination org. Used with Red Hat Satellite or Katello
- type: str
- pool_ids:
- description:
- - |
- Specify subscription pool IDs to consume.
- A pool ID may be specified as a C(string) - just the pool ID (for example V(0123456789abcdef0123456789abcdef)),
- or as a C(dict) with the pool ID as the key, and a quantity as the value (for example
- V(0123456789abcdef0123456789abcdef: 2). If the quantity is provided, it is used to consume multiple
- entitlements from a pool (the pool must support this).
- default: []
+ addons:
+ description: Syspurpose attribute addons.
type: list
- elements: raw
- consumer_type:
+ elements: str
+ sync:
description:
- - The type of unit to register, defaults to system
- type: str
- consumer_name:
- description:
- - Name of the system to register, defaults to the hostname
- type: str
- consumer_id:
- description:
- - |
- References an existing consumer ID to resume using a previous registration
- for this system. If the system's identity certificate is lost or corrupted,
- this option allows it to resume using its previous identity and subscriptions.
- The default is to not specify a consumer ID so a new ID is created.
- type: str
- force_register:
- description:
- - Register the system even if it is already registered
+ - When this option is V(true), then syspurpose attributes are synchronized with RHSM server immediately. When this
+ option is V(false), then syspurpose attributes will be synchronized with RHSM server by rhsmcertd daemon.
type: bool
default: false
- release:
- description:
- - Set a release version
- type: str
- syspurpose:
- description:
- - Set syspurpose attributes in file C(/etc/rhsm/syspurpose/syspurpose.json)
- and synchronize these attributes with RHSM server. Syspurpose attributes help attach
- the most appropriate subscriptions to the system automatically. When C(syspurpose.json) file
- already contains some attributes, then new attributes overwrite existing attributes.
- When some attribute is not listed in the new list of attributes, the existing
- attribute will be removed from C(syspurpose.json) file. Unknown attributes are ignored.
- type: dict
- suboptions:
- usage:
- description: Syspurpose attribute usage
- type: str
- role:
- description: Syspurpose attribute role
- type: str
- service_level_agreement:
- description: Syspurpose attribute service_level_agreement
- type: str
- addons:
- description: Syspurpose attribute addons
- type: list
- elements: str
- sync:
- description:
- - When this option is V(true), then syspurpose attributes are synchronized with
- RHSM server immediately. When this option is V(false), then syspurpose attributes
- will be synchronized with RHSM server by rhsmcertd daemon.
- type: bool
- default: false
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Register as user (joe_user) with password (somepass) and auto-subscribe to available content.
community.general.redhat_subscription:
state: present
@@ -275,17 +261,15 @@ EXAMPLES = '''
- addon1
- addon2
sync: true
-'''
+"""
-RETURN = '''
+RETURN = r"""
subscribed_pool_ids:
- description: List of pool IDs to which system is now subscribed
- returned: success
- type: dict
- sample: {
- "8a85f9815ab905d3015ab928c7005de4": "1"
- }
-'''
+ description: List of pool IDs to which system is now subscribed.
+ returned: success
+ type: dict
+ sample: {"8a85f9815ab905d3015ab928c7005de4": "1"}
+"""
from os.path import isfile
from os import getuid, unlink
@@ -324,9 +308,8 @@ class Rhsm(object):
else:
cfg.set('main', 'enabled', '0')
- fd = open(tmpfile, 'w+')
- cfg.write(fd)
- fd.close()
+ with open(tmpfile, 'w+') as fd:
+ cfg.write(fd)
self.module.atomic_move(tmpfile, plugin_conf)
def enable(self):
@@ -560,6 +543,45 @@ class Rhsm(object):
(distro_version[0] == 9 and distro_version[1] >= 2) or
distro_version[0] > 9)):
dbus_force_option_works = True
+ # We need to use the 'enable_content' D-Bus option to ensure that
+ # content is enabled; sadly the option is available depending on the
+ # version of the distro, and also depending on which API/method is used
+ # for registration.
+ dbus_has_enable_content_option = False
+ if activationkey:
+ def supports_enable_content_for_activation_keys():
+ # subscription-manager in Fedora >= 41 has the new option.
+ if distro_id == 'fedora' and distro_version[0] >= 41:
+ return True
+ # Assume EL distros here.
+ if distro_version[0] >= 10:
+ return True
+ return False
+ dbus_has_enable_content_option = supports_enable_content_for_activation_keys()
+ else:
+ def supports_enable_content_for_credentials():
+ # subscription-manager in any supported Fedora version
+ # has the new option.
+ if distro_id == 'fedora':
+ return True
+ # Check for RHEL 8 >= 8.6, or RHEL >= 9.
+ if distro_id == 'rhel' and \
+ ((distro_version[0] == 8 and distro_version[1] >= 6) or
+ distro_version[0] >= 9):
+ return True
+ # CentOS: similar checks as for RHEL, with one extra bit:
+ # if the 2nd part of the version is empty, it means it is
+ # CentOS Stream, and thus we can assume it has the latest
+ # version of subscription-manager.
+ if distro_id == 'centos' and \
+ ((distro_version[0] == 8 and
+ (distro_version[1] >= 6 or distro_version_parts[1] == '')) or
+ distro_version[0] >= 9):
+ return True
+ # Unknown or old distro: assume it does not support
+ # the new option.
+ return False
+ dbus_has_enable_content_option = supports_enable_content_for_credentials()
if force_register and not dbus_force_option_works and was_registered:
self.unregister()
@@ -632,6 +654,8 @@ class Rhsm(object):
register_opts[environment_key] = environment
if force_register and dbus_force_option_works and was_registered:
register_opts['force'] = True
+ if dbus_has_enable_content_option:
+ register_opts['enable_content'] = "1"
# Wrap it as proper D-Bus dict
register_opts = dbus.Dictionary(register_opts, signature='sv', variant_level=1)
@@ -1135,7 +1159,6 @@ def main():
module.exit_json(changed=False, msg="System already unregistered.")
else:
try:
- rhsm.unsubscribe()
rhsm.unregister()
except Exception as e:
module.fail_json(msg="Failed to unregister: %s" % to_native(e))
diff --git a/plugins/modules/redis.py b/plugins/modules/redis.py
index a30b89922c..9a3d030f52 100644
--- a/plugins/modules/redis.py
+++ b/plugins/modules/redis.py
@@ -8,91 +8,86 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: redis
short_description: Various redis commands, replica and flush
description:
- - Unified utility to interact with redis instances.
+ - Unified utility to interact with redis instances.
extends_documentation_fragment:
- - community.general.redis
- - community.general.attributes
+ - community.general.redis
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- command:
- description:
- - The selected redis command
- - V(config) ensures a configuration setting on an instance.
- - V(flush) flushes all the instance or a specified db.
- - V(replica) sets a redis instance in replica or master mode. (V(slave) is an alias for V(replica).)
- choices: [ config, flush, replica, slave ]
- type: str
- 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]
- type: str
- master_port:
- description:
- - The port of the master instance [replica command]
- type: int
- replica_mode:
- description:
- - The mode of the redis instance [replica command]
- - V(slave) is an alias for V(replica).
- default: replica
- choices: [ master, replica, slave ]
- type: str
- aliases:
- - slave_mode
- db:
- description:
- - The database to flush (used in db mode) [flush command]
- type: int
- flush_mode:
- description:
- - Type of flush (all the dbs in a redis instance or a specific one)
- [flush command]
- default: all
- choices: [ all, db ]
- type: str
- name:
- description:
- - A redis config key.
- type: str
- value:
- description:
- - A redis config value. When memory size is needed, it is possible
- to specify it in the usual form of 1KB, 2M, 400MB where the base is 1024.
- Units are case insensitive i.e. 1m = 1mb = 1M = 1MB.
- type: str
+ command:
+ description:
+ - The selected redis command.
+ - V(config) ensures a configuration setting on an instance.
+ - V(flush) flushes all the instance or a specified db.
+ - V(replica) sets a redis instance in replica or master mode. (V(slave) is an alias for V(replica)).
+ choices: [config, flush, replica, slave]
+ type: str
+ 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].
+ type: str
+ master_port:
+ description:
+ - The port of the master instance [replica command].
+ type: int
+ replica_mode:
+ description:
+ - The mode of the redis instance [replica command].
+ - V(slave) is an alias for V(replica).
+ default: replica
+ choices: [master, replica, slave]
+ type: str
+ aliases:
+ - slave_mode
+ db:
+ description:
+ - The database to flush (used in DB mode) [flush command].
+ type: int
+ flush_mode:
+ description:
+ - Type of flush (all the DBs in a redis instance or a specific one) [flush command].
+ default: all
+ choices: [all, db]
+ type: str
+ name:
+ description:
+ - A redis config key.
+ type: str
+ value:
+ description:
+ - A redis config value. When memory size is needed, it is possible to specify it in the usual form of 1KB, 2M, 400MB
+ where the base is 1024. Units are case insensitive, in other words 1m = 1mb = 1M = 1MB.
+ type: str
notes:
- - Requires the redis-py Python package on the remote host. You can
- install it with pip (pip install redis) or with a package manager.
- https://github.com/andymccurdy/redis-py
- - If the redis master instance we are making replica of is password protected
- this needs to be in the redis.conf in the masterauth variable
-
+ - Requires the C(redis-py) Python package on the remote host. You can install it with pip (C(pip install redis)) or with
+ a package manager. U(https://github.com/andymccurdy/redis-py).
+ - If the redis master instance you are making replica of is password protected this needs to be in the C(redis.conf) in
+ the C(masterauth) variable.
seealso:
- - module: community.general.redis_info
-requirements: [ redis ]
+ - module: community.general.redis_info
+requirements: [redis]
author: "Xabier Larrakoetxea (@slok)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Set local redis instance to be a replica of melee.island on port 6377
community.general.redis:
command: replica
@@ -142,7 +137,7 @@ EXAMPLES = '''
ca_certs: /etc/redis/certs/ca.crt
client_cert_file: /etc/redis/certs/redis.crt
client_key_file: /etc/redis/certs/redis.key
-'''
+"""
import traceback
diff --git a/plugins/modules/redis_data.py b/plugins/modules/redis_data.py
index fe5cc07ef9..03ae78dce3 100644
--- a/plugins/modules/redis_data.py
+++ b/plugins/modules/redis_data.py
@@ -8,71 +8,69 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: redis_data
short_description: Set key value pairs in Redis
version_added: 3.7.0
description:
- - Set key value pairs in Redis database.
+ - Set key value pairs in Redis database.
author: "Andreas Botzner (@paginabianca)"
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- key:
- description:
- - Database key.
- required: true
- type: str
- value:
- description:
- - Value that key should be set to.
- required: false
- type: str
- expiration:
- description:
- - Expiration time in milliseconds.
- Setting this flag will always result in a change in the database.
- required: false
- type: int
- non_existing:
- description:
- - Only set key if it does not already exist.
- required: false
- type: bool
- existing:
- description:
- - Only set key if it already exists.
- required: false
- type: bool
- keep_ttl:
- description:
- - Retain the time to live associated with the key.
- required: false
- type: bool
- state:
- description:
- - State of the key.
- default: present
- type: str
- choices:
- - present
- - absent
+ key:
+ description:
+ - Database key.
+ required: true
+ type: str
+ value:
+ description:
+ - Value that key should be set to.
+ required: false
+ type: str
+ expiration:
+ description:
+ - Expiration time in milliseconds. Setting this flag will always result in a change in the database.
+ required: false
+ type: int
+ non_existing:
+ description:
+ - Only set key if it does not already exist.
+ required: false
+ type: bool
+ existing:
+ description:
+ - Only set key if it already exists.
+ required: false
+ type: bool
+ keep_ttl:
+ description:
+ - Retain the time to live associated with the key.
+ required: false
+ type: bool
+ state:
+ description:
+ - State of the key.
+ default: present
+ type: str
+ choices:
+ - present
+ - absent
extends_documentation_fragment:
- community.general.redis.documentation
- community.general.attributes
seealso:
- - module: community.general.redis_data_incr
- - module: community.general.redis_data_info
- - module: community.general.redis
-'''
+ - module: community.general.redis_data_incr
+ - module: community.general.redis_data_info
+ - module: community.general.redis
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Set key foo=bar on localhost with no username
community.general.redis_data:
login_host: localhost
@@ -116,9 +114,9 @@ EXAMPLES = '''
login_password: supersecret
key: foo
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
old_value:
description: Value of key before setting.
returned: on_success if O(state=present) and key exists in database.
@@ -134,7 +132,7 @@ msg:
returned: always
type: str
sample: 'Set key: foo to bar'
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.redis import (
diff --git a/plugins/modules/redis_data_incr.py b/plugins/modules/redis_data_incr.py
index b359e0cb94..7630d621dc 100644
--- a/plugins/modules/redis_data_incr.py
+++ b/plugins/modules/redis_data_incr.py
@@ -8,24 +8,22 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: redis_data_incr
short_description: Increment keys in Redis
version_added: 4.0.0
description:
- - Increment integers or float keys in Redis database and get new value.
- - Default increment for all keys is 1. For specific increments use the
- O(increment_int) and O(increment_float) options.
+ - Increment integers or float keys in Redis database and get new value.
+ - Default increment for all keys is V(1). For specific increments use the O(increment_int) and O(increment_float) options.
author: "Andreas Botzner (@paginabianca)"
attributes:
check_mode:
support: partial
details:
- - For C(check_mode) to work, the specified O(login_user) needs permission to
- run the C(GET) command on the key, otherwise the module will fail.
- - When using C(check_mode) the module will try to calculate the value that
- Redis would return. If the key is not present, 0.0 is used as value.
+ - For C(check_mode) to work, the specified O(login_user) needs permission to run the C(GET) command on the key, otherwise
+ the module will fail.
+ - When using C(check_mode) the module will try to calculate the value that Redis would return. If the key is not present,
+ V(0.0) is used as value.
diff_mode:
support: none
options:
@@ -42,8 +40,7 @@ options:
increment_float:
description:
- Float amount to increment the key by.
- - This only works with keys that contain float values
- in their string representation.
+ - This only works with keys that contain float values in their string representation.
type: float
required: false
@@ -53,12 +50,12 @@ extends_documentation_fragment:
- community.general.attributes
seealso:
- - module: community.general.redis_data
- - module: community.general.redis_data_info
- - module: community.general.redis
-'''
+ - module: community.general.redis_data
+ - module: community.general.redis_data_info
+ - module: community.general.redis
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Increment integer key foo on localhost with no username and print new value
community.general.redis_data_incr:
login_host: localhost
@@ -77,11 +74,11 @@ EXAMPLES = '''
login_password: somepass
key: foo
increment_float: '20.4'
-'''
+"""
-RETURN = '''
+RETURN = r"""
value:
- description: Incremented value of key
+ description: Incremented value of key.
returned: on success
type: float
sample: '4039.4'
@@ -90,7 +87,7 @@ msg:
returned: always
type: str
sample: 'Incremented key: foo by 20.4 to 65.9'
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.redis import (
diff --git a/plugins/modules/redis_data_info.py b/plugins/modules/redis_data_info.py
index c0af619057..48be45a92f 100644
--- a/plugins/modules/redis_data_info.py
+++ b/plugins/modules/redis_data_info.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: redis_data_info
short_description: Get value of key in Redis database
version_added: 3.7.0
@@ -33,9 +32,9 @@ seealso:
- module: community.general.redis_data_incr
- module: community.general.redis_info
- module: community.general.redis
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get key foo=bar from loalhost with no username
community.general.redis_data_info:
login_host: localhost
@@ -50,9 +49,9 @@ EXAMPLES = '''
validate_certs: true
ssl_ca_certs: /path/to/ca/certs
key: foo
-'''
+"""
-RETURN = '''
+RETURN = r"""
exists:
description: If they key exists in the database.
returned: on success
@@ -67,7 +66,7 @@ msg:
returned: always
type: str
sample: 'Got key: foo with value: bar'
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.redis import (
diff --git a/plugins/modules/redis_info.py b/plugins/modules/redis_info.py
index c75abcf212..bc43f9251e 100644
--- a/plugins/modules/redis_info.py
+++ b/plugins/modules/redis_info.py
@@ -9,17 +9,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: redis_info
short_description: Gather information about Redis servers
version_added: '0.2.0'
description:
-- Gathers information and statistics about Redis servers.
+ - Gathers information and statistics about Redis servers.
extends_documentation_fragment:
-- community.general.redis
-- community.general.attributes
-- community.general.attributes.info_module
+ - community.general.redis
+ - community.general.attributes
+ - community.general.attributes.info_module
options:
login_user:
version_added: 7.5.0
@@ -36,11 +35,11 @@ options:
type: bool
version_added: 9.1.0
seealso:
-- module: community.general.redis
+ - module: community.general.redis
author: "Pavlo Bashynskyi (@levonet)"
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Get server information
community.general.redis_info:
register: result
@@ -57,9 +56,9 @@ EXAMPLES = r'''
- name: Print server cluster information
ansible.builtin.debug:
var: result.cluster_info
-'''
+"""
-RETURN = r'''
+RETURN = r"""
info:
description: The default set of server information sections U(https://redis.io/commands/info).
returned: success
@@ -211,7 +210,7 @@ cluster:
"cluster_stats_messages_received": 1483968,
"total_cluster_links_buffer_limit_exceeded": 0
}
-'''
+"""
import traceback
diff --git a/plugins/modules/rhevm.py b/plugins/modules/rhevm.py
index 7f23009972..4d0a810108 100644
--- a/plugins/modules/rhevm.py
+++ b/plugins/modules/rhevm.py
@@ -8,151 +8,150 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: rhevm
short_description: RHEV/oVirt automation
description:
- - This module only supports oVirt/RHEV version 3.
- - A newer module M(ovirt.ovirt.ovirt_vm) supports oVirt/RHV version 4.
- - Allows you to create/remove/update or powermanage virtual machines on a RHEV/oVirt platform.
+ - This module only supports oVirt/RHEV version 3.
+ - A newer module M(ovirt.ovirt.ovirt_vm) supports oVirt/RHV version 4.
+ - Allows you to create/remove/update or powermanage virtual machines on a RHEV/oVirt platform.
requirements:
- - ovirtsdk
+ - ovirtsdk
author:
- - Timothy Vandenbrande (@TimothyVandenbrande)
+ - Timothy Vandenbrande (@TimothyVandenbrande)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- user:
- description:
- - The user to authenticate with.
- type: str
- default: admin@internal
- password:
- description:
- - The password for user authentication.
- type: str
- required: true
- server:
- description:
- - The name/IP of your RHEV-m/oVirt instance.
- type: str
- default: 127.0.0.1
- port:
- description:
- - The port on which the API is reachable.
- type: int
- default: 443
- insecure_api:
- description:
- - A boolean switch to make a secure or insecure connection to the server.
- type: bool
- default: false
- name:
- description:
- - The name of the VM.
- type: str
- cluster:
- description:
- - The RHEV/oVirt cluster in which you want you VM to start.
- type: str
- default: ''
- datacenter:
- description:
- - The RHEV/oVirt datacenter in which you want you VM to start.
- type: str
- default: Default
- state:
- description:
- - This serves to create/remove/update or powermanage your VM.
- type: str
- choices: [ absent, cd, down, info, ping, present, restarted, up ]
- default: present
- image:
- description:
- - The template to use for the VM.
- type: str
- type:
- description:
- - To define if the VM is a server or desktop.
- type: str
- choices: [ desktop, host, server ]
- default: server
- vmhost:
- description:
- - The host you wish your VM to run on.
- type: str
- vmcpu:
- description:
- - The number of CPUs you want in your VM.
- type: int
- default: 2
- cpu_share:
- description:
- - This parameter is used to configure the CPU share.
- type: int
- default: 0
- vmmem:
- description:
- - The amount of memory you want your VM to use (in GB).
- type: int
- default: 1
- osver:
- description:
- - The operating system option in RHEV/oVirt.
- type: str
- default: rhel_6x64
- mempol:
- description:
- - The minimum amount of memory you wish to reserve for this system.
- type: int
- default: 1
- vm_ha:
- description:
- - To make your VM High Available.
- type: bool
- default: true
- disks:
- description:
- - This option uses complex arguments and is a list of disks with the options name, size and domain.
- type: list
- elements: str
- ifaces:
- description:
- - This option uses complex arguments and is a list of interfaces with the options name and vlan.
- type: list
- elements: str
- aliases: [ interfaces, nics ]
- boot_order:
- description:
- - This option uses complex arguments and is a list of items that specify the bootorder.
- type: list
- elements: str
- default: [ hd, network ]
- del_prot:
- description:
- - This option sets the delete protection checkbox.
- type: bool
- default: true
- cd_drive:
- description:
- - The CD you wish to have mounted on the VM when O(state=cd).
- type: str
- timeout:
- description:
- - The timeout you wish to define for power actions.
- - When O(state=up).
- - When O(state=down).
- - When O(state=restarted).
- type: int
-'''
+ user:
+ description:
+ - The user to authenticate with.
+ type: str
+ default: admin@internal
+ password:
+ description:
+ - The password for user authentication.
+ type: str
+ required: true
+ server:
+ description:
+ - The name/IP of your RHEV-m/oVirt instance.
+ type: str
+ default: 127.0.0.1
+ port:
+ description:
+ - The port on which the API is reachable.
+ type: int
+ default: 443
+ insecure_api:
+ description:
+ - A boolean switch to make a secure or insecure connection to the server.
+ type: bool
+ default: false
+ name:
+ description:
+ - The name of the VM.
+ type: str
+ cluster:
+ description:
+ - The RHEV/oVirt cluster in which you want you VM to start.
+ type: str
+ default: ''
+ datacenter:
+ description:
+ - The RHEV/oVirt datacenter in which you want you VM to start.
+ type: str
+ default: Default
+ state:
+ description:
+ - This serves to create/remove/update or powermanage your VM.
+ type: str
+ choices: [absent, cd, down, info, ping, present, restarted, up]
+ default: present
+ image:
+ description:
+ - The template to use for the VM.
+ type: str
+ type:
+ description:
+ - To define if the VM is a server or desktop.
+ type: str
+ choices: [desktop, host, server]
+ default: server
+ vmhost:
+ description:
+ - The host you wish your VM to run on.
+ type: str
+ vmcpu:
+ description:
+ - The number of CPUs you want in your VM.
+ type: int
+ default: 2
+ cpu_share:
+ description:
+ - This parameter is used to configure the CPU share.
+ type: int
+ default: 0
+ vmmem:
+ description:
+ - The amount of memory you want your VM to use (in GB).
+ type: int
+ default: 1
+ osver:
+ description:
+ - The operating system option in RHEV/oVirt.
+ type: str
+ default: rhel_6x64
+ mempol:
+ description:
+ - The minimum amount of memory you wish to reserve for this system.
+ type: int
+ default: 1
+ vm_ha:
+ description:
+ - To make your VM High Available.
+ type: bool
+ default: true
+ disks:
+ description:
+ - This option uses complex arguments and is a list of disks with the options V(name), V(size), and V(domain).
+ type: list
+ elements: str
+ ifaces:
+ description:
+ - This option uses complex arguments and is a list of interfaces with the options V(name) and V(vlan).
+ type: list
+ elements: str
+ aliases: [interfaces, nics]
+ boot_order:
+ description:
+ - This option uses complex arguments and is a list of items that specify the bootorder.
+ type: list
+ elements: str
+ default: [hd, network]
+ del_prot:
+ description:
+ - This option sets the delete protection checkbox.
+ type: bool
+ default: true
+ cd_drive:
+ description:
+ - The CD you wish to have mounted on the VM when O(state=cd).
+ type: str
+ timeout:
+ description:
+ - The timeout you wish to define for power actions.
+ - When O(state=up).
+ - When O(state=down).
+ - When O(state=restarted).
+ type: int
+"""
-RETURN = r'''
+RETURN = r"""
vm:
description: Returns all of the VMs variables and execution.
returned: always
@@ -216,9 +215,9 @@ vm:
"vmhost": "host416",
"vmmem": "16"
}
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Basic get info from VM
community.general.rhevm:
server: rhevm01
@@ -258,33 +257,33 @@ EXAMPLES = r'''
vmcpu: 4
vmmem: 2
ifaces:
- - name: eth0
- vlan: vlan2202
- - name: eth1
- vlan: vlan36
- - name: eth2
- vlan: vlan38
- - name: eth3
- vlan: vlan2202
+ - name: eth0
+ vlan: vlan2202
+ - name: eth1
+ vlan: vlan36
+ - name: eth2
+ vlan: vlan38
+ - name: eth3
+ vlan: vlan2202
disks:
- - name: root
- size: 10
- domain: ssd-san
- - name: swap
- size: 10
- domain: 15kiscsi-san
- - name: opt
- size: 10
- domain: 15kiscsi-san
- - name: var
- size: 10
- domain: 10kiscsi-san
- - name: home
- size: 10
- domain: sata-san
+ - name: root
+ size: 10
+ domain: ssd-san
+ - name: swap
+ size: 10
+ domain: 15kiscsi-san
+ - name: opt
+ size: 10
+ domain: 15kiscsi-san
+ - name: var
+ size: 10
+ domain: 10kiscsi-san
+ - name: home
+ size: 10
+ domain: sata-san
boot_order:
- - network
- - hd
+ - network
+ - hd
state: present
- name: Add a CD to the disk cd_drive
@@ -302,33 +301,33 @@ EXAMPLES = r'''
type: host
cluster: rhevm01
ifaces:
- - name: em1
- - name: em2
- - name: p3p1
- ip: 172.31.224.200
- netmask: 255.255.254.0
- - name: p3p2
- ip: 172.31.225.200
- netmask: 255.255.254.0
- - name: bond0
- bond:
- - em1
- - em2
- network: rhevm
- ip: 172.31.222.200
- netmask: 255.255.255.0
- management: true
- - name: bond0.36
- network: vlan36
- ip: 10.2.36.200
- netmask: 255.255.254.0
- gateway: 10.2.36.254
- - name: bond0.2202
- network: vlan2202
- - name: bond0.38
- network: vlan38
+ - name: em1
+ - name: em2
+ - name: p3p1
+ ip: 172.31.224.200
+ netmask: 255.255.254.0
+ - name: p3p2
+ ip: 172.31.225.200
+ netmask: 255.255.254.0
+ - name: bond0
+ bond:
+ - em1
+ - em2
+ network: rhevm
+ ip: 172.31.222.200
+ netmask: 255.255.255.0
+ management: true
+ - name: bond0.36
+ network: vlan36
+ ip: 10.2.36.200
+ netmask: 255.255.254.0
+ gateway: 10.2.36.254
+ - name: bond0.2202
+ network: vlan2202
+ - name: bond0.38
+ network: vlan38
state: present
-'''
+"""
import time
diff --git a/plugins/modules/rhsm_release.py b/plugins/modules/rhsm_release.py
index 8c74ca8192..6408d3c171 100644
--- a/plugins/modules/rhsm_release.py
+++ b/plugins/modules/rhsm_release.py
@@ -8,18 +8,16 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: rhsm_release
short_description: Set or Unset RHSM Release version
description:
- Sets or unsets the release version used by RHSM repositories.
notes:
- - This module will fail on an unregistered system.
- Use the M(community.general.redhat_subscription) module to register a system
- prior to setting the RHSM release.
- - It is possible to interact with C(subscription-manager) only as root,
- so root permissions are required to successfully run this module.
+ - This module will fail on an unregistered system. Use the M(community.general.redhat_subscription) module to register a
+ system prior to setting the RHSM release.
+ - It is possible to interact with C(subscription-manager) only as root, so root permissions are required to successfully
+ run this module.
requirements:
- Red Hat Enterprise Linux 6+ with subscription-manager installed
extends_documentation_fragment:
@@ -37,9 +35,9 @@ options:
type: str
author:
- Sean Myers (@seandst)
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Set release version to 7.1
- name: Set RHSM release version
community.general.rhsm_release:
@@ -53,15 +51,15 @@ EXAMPLES = '''
# Unset release version
- name: Unset RHSM release release
community.general.rhsm_release:
- release: null
-'''
+ release:
+"""
-RETURN = '''
+RETURN = r"""
current_release:
- description: The current RHSM release version value
+ description: The current RHSM release version value.
returned: success
type: str
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/rhsm_repository.py b/plugins/modules/rhsm_repository.py
index ed8b0e7d58..c80caa0d6c 100644
--- a/plugins/modules/rhsm_repository.py
+++ b/plugins/modules/rhsm_repository.py
@@ -8,20 +8,18 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: rhsm_repository
short_description: Manage RHSM repositories using the subscription-manager command
description:
- - Manage (Enable/Disable) RHSM repositories to the Red Hat Subscription
- Management entitlement platform using the C(subscription-manager) command.
+ - Manage (Enable/Disable) RHSM repositories to the Red Hat Subscription Management entitlement platform using the C(subscription-manager)
+ command.
author: Giovanni Sciortino (@giovannisciortino)
notes:
- - In order to manage RHSM repositories the system must be already registered
- to RHSM manually or using the Ansible M(community.general.redhat_subscription) module.
- - It is possible to interact with C(subscription-manager) only as root,
- so root permissions are required to successfully run this module.
-
+ - In order to manage RHSM repositories the system must be already registered to RHSM manually or using the Ansible M(community.general.redhat_subscription)
+ module.
+ - It is possible to interact with C(subscription-manager) only as root, so root permissions are required to successfully
+ run this module.
requirements:
- subscription-manager
extends_documentation_fragment:
@@ -34,31 +32,28 @@ attributes:
options:
state:
description:
- - If state is equal to present or disabled, indicates the desired
- repository state.
- - In community.general 10.0.0 the states V(present) and V(absent) have been
- removed. Please use V(enabled) and V(disabled) instead.
+ - If state is equal to present or disabled, indicates the desired repository state.
+ - In community.general 10.0.0 the states V(present) and V(absent) have been removed. Please use V(enabled) and V(disabled)
+ instead.
choices: [enabled, disabled]
default: "enabled"
type: str
name:
description:
- The ID of repositories to enable.
- - To operate on several repositories this can accept a comma separated
- list or a YAML list.
+ - To operate on several repositories this can accept a comma separated list or a YAML list.
required: true
type: list
elements: str
purge:
description:
- - Disable all currently enabled repositories that are not not specified in O(name).
- Only set this to V(true) if passing in a list of repositories to the O(name) field.
- Using this with C(loop) will most likely not have the desired result.
+ - Disable all currently enabled repositories that are not not specified in O(name). Only set this to V(true) if passing
+ in a list of repositories to the O(name) field. Using this with C(loop) will most likely not have the desired result.
type: bool
default: false
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Enable a RHSM repository
community.general.rhsm_repository:
name: rhel-7-server-rpms
@@ -77,16 +72,16 @@ EXAMPLES = '''
community.general.rhsm_repository:
name: rhel-7-server-rpms
purge: true
-'''
+"""
-RETURN = '''
+RETURN = r"""
repositories:
description:
- The list of RHSM repositories with their states.
- When this module is used to change the repository states, this list contains the updated states after the changes.
returned: success
type: list
-'''
+"""
import os
from fnmatch import fnmatch
diff --git a/plugins/modules/riak.py b/plugins/modules/riak.py
index 438263da22..d7b45af5cd 100644
--- a/plugins/modules/riak.py
+++ b/plugins/modules/riak.py
@@ -9,18 +9,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: riak
short_description: This module handles some common Riak operations
description:
- - This module can be used to join nodes to a cluster, check
- the status of the cluster.
+ - This module can be used to join nodes to a cluster, check the status of the cluster.
author:
- - "James Martin (@jsmartin)"
- - "Drew Kerrigan (@drewkerrigan)"
+ - "James Martin (@jsmartin)"
+ - "Drew Kerrigan (@drewkerrigan)"
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: none
@@ -34,17 +32,17 @@ options:
type: str
config_dir:
description:
- - The path to the riak configuration directory
+ - The path to the riak configuration directory.
default: /etc/riak
type: path
http_conn:
description:
- - The ip address and port that is listening for Riak HTTP queries
+ - The IP address and port that is listening for Riak HTTP queries.
default: 127.0.0.1:8098
type: str
target_node:
description:
- - The target node for certain operations (join, ping)
+ - The target node for certain operations (join, ping).
default: riak@127.0.0.1
type: str
wait_for_handoffs:
@@ -64,13 +62,13 @@ options:
type: str
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
type: bool
default: true
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: "Join's a Riak node to another node"
community.general.riak:
command: join
@@ -83,7 +81,7 @@ EXAMPLES = '''
- name: Wait for riak_kv service to startup
community.general.riak:
wait_for_service: kv
-'''
+"""
import json
import time
diff --git a/plugins/modules/rocketchat.py b/plugins/modules/rocketchat.py
index 473f0150ab..91192875dc 100644
--- a/plugins/modules/rocketchat.py
+++ b/plugins/modules/rocketchat.py
@@ -12,11 +12,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: rocketchat
short_description: Send notifications to Rocket Chat
description:
- - The C(rocketchat) module sends notifications to Rocket Chat via the Incoming WebHook integration
+ - This module sends notifications to Rocket Chat through the Incoming WebHook integration.
author: "Ramon de la Fuente (@ramondelafuente)"
extends_documentation_fragment:
- community.general.attributes
@@ -29,15 +29,13 @@ options:
domain:
type: str
description:
- - The domain for your environment without protocol. (For example
- V(example.com) or V(chat.example.com).)
+ - The domain for your environment without protocol. (For example V(example.com) or V(chat.example.com)).
required: true
token:
type: str
description:
- - Rocket Chat Incoming Webhook integration token. This provides
- authentication to Rocket Chat's Incoming webhook for posting
- messages.
+ - Rocket Chat Incoming Webhook integration token. This provides authentication to Rocket Chat's Incoming webhook for
+ posting messages.
required: true
protocol:
type: str
@@ -54,8 +52,8 @@ options:
channel:
type: str
description:
- - Channel to send the message to. If absent, the message goes to the channel selected for the O(token)
- specified during the creation of webhook.
+ - Channel to send the message to. If absent, the message goes to the channel selected for the O(token) specified during
+ the creation of webhook.
username:
type: str
description:
@@ -69,8 +67,7 @@ options:
icon_emoji:
type: str
description:
- - Emoji for the message sender. The representation for the available emojis can be
- got from Rocket Chat.
+ - Emoji for the message sender. The representation for the available emojis can be got from Rocket Chat.
- For example V(:thumbsup:).
- If O(icon_emoji) is set, O(icon_url) will not be used.
link_names:
@@ -83,14 +80,15 @@ options:
- 0
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
type: bool
default: true
color:
type: str
description:
- - Allow text to use default colors - use the default of 'normal' to not send a custom color bar at the start of the message
+ - Allow text to use default colors - use the default of V(normal) to not send a custom color bar at the start of the
+ message.
default: 'normal'
choices:
- 'normal'
@@ -102,17 +100,26 @@ options:
elements: dict
description:
- Define a list of attachments.
-'''
+ is_pre740:
+ description:
+ - If V(true), the payload matches Rocket.Chat prior to 7.4.0 format.
+ This format has been used by the module since its inception, but is no longer supported by Rocket.Chat 7.4.0.
+ - The default value of the option will change to V(false) eventually.
+ - This parameter will be removed in a future release when Rocket.Chat 7.4.0 becomes the minimum supported version.
+ type: bool
+ default: true
+ version_added: 10.5.0
+"""
-EXAMPLES = """
-- name: Send notification message via Rocket Chat
+EXAMPLES = r"""
+- name: Send notification message through Rocket Chat
community.general.rocketchat:
token: thetoken/generatedby/rocketchat
domain: chat.example.com
msg: '{{ inventory_hostname }} completed'
delegate_to: localhost
-- name: Send notification message via Rocket Chat all options
+- name: Send notification message through Rocket Chat all options
community.general.rocketchat:
domain: chat.example.com
token: thetoken/generatedby/rocketchat
@@ -123,7 +130,8 @@ EXAMPLES = """
link_names: 0
delegate_to: localhost
-- name: Insert a color bar in front of the message for visibility purposes and use the default webhook icon and name configured in rocketchat
+- name: Insert a color bar in front of the message for visibility purposes and use the default webhook icon and name configured
+ in rocketchat
community.general.rocketchat:
token: thetoken/generatedby/rocketchat
domain: chat.example.com
@@ -151,12 +159,12 @@ EXAMPLES = """
delegate_to: localhost
"""
-RETURN = """
+RETURN = r"""
changed:
- description: A flag indicating if any change was made or not.
- returned: success
- type: bool
- sample: false
+ description: A flag indicating if any change was made or not.
+ returned: success
+ type: bool
+ sample: false
"""
from ansible.module_utils.basic import AnsibleModule
@@ -166,7 +174,7 @@ from ansible.module_utils.urls import fetch_url
ROCKETCHAT_INCOMING_WEBHOOK = '%s://%s/hooks/%s'
-def build_payload_for_rocketchat(module, text, channel, username, icon_url, icon_emoji, link_names, color, attachments):
+def build_payload_for_rocketchat(module, text, channel, username, icon_url, icon_emoji, link_names, color, attachments, is_pre740):
payload = {}
if color == "normal" and text is not None:
payload = dict(text=text)
@@ -196,7 +204,9 @@ def build_payload_for_rocketchat(module, text, channel, username, icon_url, icon
attachment['fallback'] = attachment['text']
payload['attachments'].append(attachment)
- payload = "payload=" + module.jsonify(payload)
+ payload = module.jsonify(payload)
+ if is_pre740:
+ payload = "payload=" + module.jsonify(payload)
return payload
@@ -226,7 +236,8 @@ def main():
link_names=dict(type='int', default=1, choices=[0, 1]),
validate_certs=dict(default=True, type='bool'),
color=dict(type='str', default='normal', choices=['normal', 'good', 'warning', 'danger']),
- attachments=dict(type='list', elements='dict', required=False)
+ attachments=dict(type='list', elements='dict', required=False),
+ is_pre740=dict(default=True, type='bool')
)
)
@@ -241,8 +252,9 @@ def main():
link_names = module.params['link_names']
color = module.params['color']
attachments = module.params['attachments']
+ is_pre740 = module.params['is_pre740']
- payload = build_payload_for_rocketchat(module, text, channel, username, icon_url, icon_emoji, link_names, color, attachments)
+ payload = build_payload_for_rocketchat(module, text, channel, username, icon_url, icon_emoji, link_names, color, attachments, is_pre740)
do_notify_rocketchat(module, domain, token, protocol, payload)
module.exit_json(msg="OK")
diff --git a/plugins/modules/rollbar_deployment.py b/plugins/modules/rollbar_deployment.py
index 4bce9ab980..a9658dbadf 100644
--- a/plugins/modules/rollbar_deployment.py
+++ b/plugins/modules/rollbar_deployment.py
@@ -9,14 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: rollbar_deployment
author: "Max Riveiro (@kavu)"
short_description: Notify Rollbar about app deployments
description:
- - Notify Rollbar about app deployments
- (see https://rollbar.com/docs/deploys_other/)
+ - Notify Rollbar about app deployments (see U(https://rollbar.com/docs/deploys_other/)).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -33,7 +31,7 @@ options:
environment:
type: str
description:
- - Name of the environment being deployed, e.g. 'production'.
+ - Name of the environment being deployed, for example V(production).
required: true
revision:
type: str
@@ -53,7 +51,7 @@ options:
comment:
type: str
description:
- - Deploy comment (e.g. what is being deployed).
+ - Deploy comment (for example what is being deployed).
required: false
url:
type: str
@@ -63,31 +61,30 @@ options:
default: 'https://api.rollbar.com/api/1/deploy/'
validate_certs:
description:
- - If V(false), SSL certificates for the target url will not be validated.
- This should only be used on personally controlled sites using
- self-signed certificates.
+ - If V(false), SSL certificates for the target URL will not be validated. This should only be used on personally controlled
+ sites using self-signed certificates.
required: false
default: true
type: bool
-'''
+"""
-EXAMPLES = '''
- - name: Rollbar deployment notification
- community.general.rollbar_deployment:
- token: AAAAAA
- environment: staging
- user: ansible
- revision: '4.2'
- rollbar_user: admin
- comment: Test Deploy
+EXAMPLES = r"""
+- name: Rollbar deployment notification
+ community.general.rollbar_deployment:
+ token: AAAAAA
+ environment: staging
+ user: ansible
+ revision: '4.2'
+ rollbar_user: admin
+ comment: Test Deploy
- - name: Notify rollbar about current git revision deployment by current user
- community.general.rollbar_deployment:
- token: "{{ rollbar_access_token }}"
- environment: production
- revision: "{{ lookup('pipe', 'git rev-parse HEAD') }}"
- user: "{{ lookup('env', 'USER') }}"
-'''
+- name: Notify rollbar about current git revision deployment by current user
+ community.general.rollbar_deployment:
+ token: "{{ rollbar_access_token }}"
+ environment: production
+ revision: "{{ lookup('pipe', 'git rev-parse HEAD') }}"
+ user: "{{ lookup('env', 'USER') }}"
+"""
import traceback
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/rpm_ostree_pkg.py b/plugins/modules/rpm_ostree_pkg.py
index 1a02b2d71c..db084c9091 100644
--- a/plugins/modules/rpm_ostree_pkg.py
+++ b/plugins/modules/rpm_ostree_pkg.py
@@ -10,42 +10,49 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: rpm_ostree_pkg
short_description: Install or uninstall overlay additional packages
version_added: "2.0.0"
description:
- - Install or uninstall overlay additional packages using C(rpm-ostree) command.
+ - Install or uninstall overlay additional packages using C(rpm-ostree) command.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- name:
- description:
+ name:
+ description:
- Name of overlay package to install or remove.
- required: true
- type: list
- elements: str
- aliases: [ pkg ]
- state:
- description:
+ required: true
+ type: list
+ elements: str
+ aliases: [pkg]
+ state:
+ description:
- State of the overlay package.
- V(present) simply ensures that a desired package is installed.
- V(absent) removes the specified package.
- choices: [ 'absent', 'present' ]
- default: 'present'
- type: str
+ choices: ['absent', 'present']
+ default: 'present'
+ type: str
+ apply_live:
+ description:
+ - Adds the options C(--apply-live) when O(state=present).
+ - Option is ignored when O(state=absent).
+ - For more information, please see U(https://coreos.github.io/rpm-ostree/apply-live/).
+ type: bool
+ default: false
+ version_added: 10.1.0
author:
- - Dusty Mabe (@dustymabe)
- - Abhijeet Kasurde (@Akasurde)
-'''
+ - Dusty Mabe (@dustymabe)
+ - Abhijeet Kasurde (@Akasurde)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Install overlay package
community.general.rpm_ostree_pkg:
name: nfs-utils
@@ -56,6 +63,12 @@ EXAMPLES = r'''
name: nfs-utils
state: absent
+- name: Apply the overlay package live
+ community.general.rpm_ostree_pkg:
+ name: nfs-utils
+ state: present
+ apply_live: true
+
# In case a different transaction is currently running the module would fail.
# Adding a delay can help mitigate this problem:
- name: Install overlay package
@@ -66,45 +79,51 @@ EXAMPLES = r'''
until: rpm_ostree_pkg is not failed
retries: 10
dealy: 30
-'''
+"""
-RETURN = r'''
+RETURN = r"""
rc:
- description: Return code of rpm-ostree command.
- returned: always
- type: int
- sample: 0
+ description: Return code of rpm-ostree command.
+ returned: always
+ type: int
+ sample: 0
changed:
- description: State changes.
- returned: always
- type: bool
- sample: true
+ description: State changes.
+ returned: always
+ type: bool
+ sample: true
action:
- description: Action performed.
- returned: always
- type: str
- sample: 'install'
+ description: Action performed.
+ returned: always
+ type: str
+ sample: 'install'
packages:
- description: A list of packages specified.
- returned: always
- type: list
- sample: ['nfs-utils']
+ description: A list of packages specified.
+ returned: always
+ type: list
+ sample: ['nfs-utils']
stdout:
- description: Stdout of rpm-ostree command.
- returned: always
- type: str
- sample: 'Staging deployment...done\n...'
+ description: Stdout of rpm-ostree command.
+ returned: always
+ type: str
+ sample: 'Staging deployment...done\n...'
stderr:
- description: Stderr of rpm-ostree command.
- returned: always
- type: str
- sample: ''
+ description: Stderr of rpm-ostree command.
+ returned: always
+ type: str
+ sample: ''
cmd:
- description: Full command used for performed action.
- returned: always
- type: str
- sample: 'rpm-ostree uninstall --allow-inactive --idempotent --unchanged-exit-77 nfs-utils'
-'''
+ description: Full command used for performed action.
+ returned: always
+ type: str
+ sample: 'rpm-ostree uninstall --allow-inactive --idempotent --unchanged-exit-77 nfs-utils'
+needs_reboot:
+ description: Determine if machine needs a reboot to apply current changes.
+ returned: success
+ type: bool
+ sample: true
+ version_added: 10.1.0
+"""
from ansible.module_utils.basic import AnsibleModule
@@ -124,19 +143,24 @@ class RpmOstreePkg:
stdout='',
stderr='',
cmd='',
+ needs_reboot=False,
)
# Ensure rpm-ostree command exists
cmd = [self.module.get_bin_path('rpm-ostree', required=True)]
# Decide action to perform
- if self.state in ('present'):
+ if self.state == 'present':
results['action'] = 'install'
cmd.append('install')
- elif self.state in ('absent'):
+ elif self.state == 'absent':
results['action'] = 'uninstall'
cmd.append('uninstall')
+ # Add the options to the command line
+ if self.params['apply_live'] and self.state == 'present':
+ cmd.extend(['--apply-live', '--assumeyes'])
+
# Additional parameters
cmd.extend(['--allow-inactive', '--idempotent', '--unchanged-exit-77'])
for pkg in self.params['name']:
@@ -145,6 +169,10 @@ class RpmOstreePkg:
rc, out, err = self.module.run_command(cmd)
+ # Determine if system needs a reboot to apply change
+ if 'Changes queued for next boot. Run "systemctl reboot" to start a reboot' in out:
+ results['needs_reboot'] = True
+
results.update(dict(
rc=rc,
cmd=' '.join(cmd),
@@ -180,6 +208,10 @@ def main():
type='list',
elements='str',
),
+ apply_live=dict(
+ type='bool',
+ default=False,
+ ),
),
)
diff --git a/plugins/modules/rundeck_acl_policy.py b/plugins/modules/rundeck_acl_policy.py
index 8f21a32680..aa22e6e6ea 100644
--- a/plugins/modules/rundeck_acl_policy.py
+++ b/plugins/modules/rundeck_acl_policy.py
@@ -11,71 +11,70 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: rundeck_acl_policy
short_description: Manage Rundeck ACL policies
description:
- - Create, update and remove Rundeck ACL policies through HTTP API.
+ - Create, update and remove Rundeck ACL policies through HTTP API.
author: "Loic Blot (@nerzhul)"
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- type: str
- description:
- - Create or remove Rundeck project.
- choices: ['present', 'absent']
- default: 'present'
- name:
- type: str
- description:
- - Sets the project name.
- required: true
- api_token:
- description:
- - Sets the token to authenticate against Rundeck API.
- aliases: ["token"]
- project:
- type: str
- description:
- - Sets the project which receive the ACL policy.
- - If unset, it's a system ACL policy.
- policy:
- type: str
- description:
- - Sets the ACL policy content.
- - ACL policy content is a YAML object as described in http://rundeck.org/docs/man5/aclpolicy.html.
- - It can be a YAML string or a pure Ansible inventory YAML object.
- client_cert:
- version_added: '0.2.0'
- client_key:
- version_added: '0.2.0'
- force:
- version_added: '0.2.0'
- force_basic_auth:
- version_added: '0.2.0'
- http_agent:
- version_added: '0.2.0'
- url_password:
- version_added: '0.2.0'
- url_username:
- version_added: '0.2.0'
- use_proxy:
- version_added: '0.2.0'
- validate_certs:
- version_added: '0.2.0'
+ state:
+ type: str
+ description:
+ - Create or remove Rundeck project.
+ choices: ['present', 'absent']
+ default: 'present'
+ name:
+ type: str
+ description:
+ - Sets the project name.
+ required: true
+ api_token:
+ description:
+ - Sets the token to authenticate against Rundeck API.
+ aliases: ["token"]
+ project:
+ type: str
+ description:
+ - Sets the project which receive the ACL policy.
+ - If unset, it is a system ACL policy.
+ policy:
+ type: str
+ description:
+ - Sets the ACL policy content.
+ - ACL policy content is a YAML object as described in U(http://rundeck.org/docs/man5/aclpolicy.html).
+ - It can be a YAML string or a pure Ansible inventory YAML object.
+ client_cert:
+ version_added: '0.2.0'
+ client_key:
+ version_added: '0.2.0'
+ force:
+ version_added: '0.2.0'
+ force_basic_auth:
+ version_added: '0.2.0'
+ http_agent:
+ version_added: '0.2.0'
+ url_password:
+ version_added: '0.2.0'
+ url_username:
+ version_added: '0.2.0'
+ use_proxy:
+ version_added: '0.2.0'
+ validate_certs:
+ version_added: '0.2.0'
extends_documentation_fragment:
- ansible.builtin.url
- community.general.attributes
- community.general.rundeck
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create or update a rundeck ACL policy in project Ansible
community.general.rundeck_acl_policy:
name: "Project_01"
@@ -100,22 +99,22 @@ EXAMPLES = '''
url: "https://rundeck.example.org"
token: "mytoken"
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
rundeck_response:
- description: Rundeck response when a failure occurs.
- returned: failed
- type: str
+ description: Rundeck response when a failure occurs.
+ returned: failed
+ type: str
before:
- description: Dictionary containing ACL policy information before modification.
- returned: success
- type: dict
+ description: Dictionary containing ACL policy information before modification.
+ returned: success
+ type: dict
after:
- description: Dictionary containing ACL policy information after modification.
- returned: success
- type: dict
-'''
+ description: Dictionary containing ACL policy information after modification.
+ returned: success
+ type: dict
+"""
# import module snippets
import re
@@ -156,7 +155,7 @@ class RundeckACLManager:
if info["status"] == 201:
self.module.exit_json(changed=True, before={}, after=self.get_acl())
elif info["status"] == 400:
- self.module.fail_json(msg="Unable to validate acl %s. Please ensure it's a valid ACL" %
+ self.module.fail_json(msg="Unable to validate acl %s. Please ensure it is a valid ACL" %
self.module.params["name"])
elif info["status"] == 409:
self.module.fail_json(msg="ACL %s already exists" % self.module.params["name"])
@@ -180,7 +179,7 @@ class RundeckACLManager:
if info["status"] == 200:
self.module.exit_json(changed=True, before=facts, after=self.get_acl())
elif info["status"] == 400:
- self.module.fail_json(msg="Unable to validate acl %s. Please ensure it's a valid ACL" %
+ self.module.fail_json(msg="Unable to validate acl %s. Please ensure it is a valid ACL" %
self.module.params["name"])
elif info["status"] == 404:
self.module.fail_json(msg="ACL %s doesn't exists. Cannot update." % self.module.params["name"])
diff --git a/plugins/modules/rundeck_job_executions_info.py b/plugins/modules/rundeck_job_executions_info.py
index 818bde83c0..540c8c7788 100644
--- a/plugins/modules/rundeck_job_executions_info.py
+++ b/plugins/modules/rundeck_job_executions_info.py
@@ -9,43 +9,42 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: rundeck_job_executions_info
short_description: Query executions for a Rundeck job
description:
- - This module gets the list of executions for a specified Rundeck job.
+ - This module gets the list of executions for a specified Rundeck job.
author: "Phillipe Smith (@phsmith)"
version_added: 3.8.0
options:
- job_id:
- type: str
- description:
- - The job unique ID.
- required: true
- status:
- type: str
- description:
- - The job status to filter.
- choices: [succeeded, failed, aborted, running]
- max:
- type: int
- description:
- - Max results to return.
- default: 20
- offset:
- type: int
- description:
- - The start point to return the results.
- default: 0
+ job_id:
+ type: str
+ description:
+ - The job unique ID.
+ required: true
+ status:
+ type: str
+ description:
+ - The job status to filter.
+ choices: [succeeded, failed, aborted, running]
+ max:
+ type: int
+ description:
+ - Max results to return.
+ default: 20
+ offset:
+ type: int
+ description:
+ - The start point to return the results.
+ default: 0
extends_documentation_fragment:
- community.general.rundeck
- url
- community.general.attributes
- community.general.attributes.info_module
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get Rundeck job executions info
community.general.rundeck_job_executions_info:
url: "https://rundeck.example.org"
@@ -57,36 +56,31 @@ EXAMPLES = '''
- name: Show Rundeck job executions info
ansible.builtin.debug:
var: rundeck_job_executions_info.executions
-'''
+"""
-RETURN = '''
+RETURN = r"""
paging:
- description: Results pagination info.
- returned: success
- type: dict
- contains:
- count:
- description: Number of results in the response.
- type: int
- returned: success
- total:
- description: Total number of results.
- type: int
- returned: success
- offset:
- description: Offset from first of all results.
- type: int
- returned: success
- max:
- description: Maximum number of results per page.
- type: int
- returned: success
- sample: {
- "count": 20,
- "total": 100,
- "offset": 0,
- "max": 20
- }
+ description: Results pagination info.
+ returned: success
+ type: dict
+ contains:
+ count:
+ description: Number of results in the response.
+ type: int
+ returned: success
+ total:
+ description: Total number of results.
+ type: int
+ returned: success
+ offset:
+ description: Offset from first of all results.
+ type: int
+ returned: success
+ max:
+ description: Maximum number of results per page.
+ type: int
+ returned: success
+ sample: {"count": 20, "total": 100, "offset": 0, "max": 20}
executions:
description: Job executions list.
returned: always
@@ -127,7 +121,7 @@ executions:
"serverUUID": "5b9a1438-fa3a-457e-b254-8f3d70338068"
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.six.moves.urllib.parse import quote
diff --git a/plugins/modules/rundeck_job_run.py b/plugins/modules/rundeck_job_run.py
index 2ef1447401..f46b5ee432 100644
--- a/plugins/modules/rundeck_job_run.py
+++ b/plugins/modules/rundeck_job_run.py
@@ -9,75 +9,74 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: rundeck_job_run
short_description: Run a Rundeck job
description:
- - This module runs a Rundeck job specified by ID.
+ - This module runs a Rundeck job specified by ID.
author: "Phillipe Smith (@phsmith)"
version_added: 3.8.0
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- job_id:
- type: str
- description:
- - The job unique ID.
- required: true
- job_options:
- type: dict
- description:
- - The job options for the steps.
- - Numeric values must be quoted.
- filter_nodes:
- type: str
- description:
- - Filter the nodes where the jobs must run.
- - See U(https://docs.rundeck.com/docs/manual/11-node-filters.html#node-filter-syntax).
- run_at_time:
- type: str
- description:
- - Schedule the job execution to run at specific date and time.
- - ISO-8601 date and time format like V(2021-10-05T15:45:00-03:00).
- loglevel:
- type: str
- description:
- - Log level configuration.
- choices: [debug, verbose, info, warn, error]
- default: info
- wait_execution:
- type: bool
- description:
- - Wait until the job finished the execution.
- default: true
- wait_execution_delay:
- type: int
- description:
- - Delay, in seconds, between job execution status check requests.
- default: 5
- wait_execution_timeout:
- type: int
- description:
- - Job execution wait timeout in seconds.
- - If the timeout is reached, the job will be aborted.
- - Keep in mind that there is a sleep based on O(wait_execution_delay) after each job status check.
- default: 120
- abort_on_timeout:
- type: bool
- description:
- - Send a job abort request if exceeded the O(wait_execution_timeout) specified.
- default: false
+ job_id:
+ type: str
+ description:
+ - The job unique ID.
+ required: true
+ job_options:
+ type: dict
+ description:
+ - The job options for the steps.
+ - Numeric values must be quoted.
+ filter_nodes:
+ type: str
+ description:
+ - Filter the nodes where the jobs must run.
+ - See U(https://docs.rundeck.com/docs/manual/11-node-filters.html#node-filter-syntax).
+ run_at_time:
+ type: str
+ description:
+ - Schedule the job execution to run at specific date and time.
+ - ISO-8601 date and time format like V(2021-10-05T15:45:00-03:00).
+ loglevel:
+ type: str
+ description:
+ - Log level configuration.
+ choices: [debug, verbose, info, warn, error]
+ default: info
+ wait_execution:
+ type: bool
+ description:
+ - Wait until the job finished the execution.
+ default: true
+ wait_execution_delay:
+ type: int
+ description:
+ - Delay, in seconds, between job execution status check requests.
+ default: 5
+ wait_execution_timeout:
+ type: int
+ description:
+ - Job execution wait timeout in seconds.
+ - If the timeout is reached, the job will be aborted.
+ - Keep in mind that there is a sleep based on O(wait_execution_delay) after each job status check.
+ default: 120
+ abort_on_timeout:
+ type: bool
+ description:
+ - Send a job abort request if exceeded the O(wait_execution_timeout) specified.
+ default: false
extends_documentation_fragment:
- community.general.rundeck
- ansible.builtin.url
- community.general.attributes
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Run a Rundeck job
community.general.rundeck_job_run:
url: "https://rundeck.example.org"
@@ -97,9 +96,9 @@ EXAMPLES = '''
api_token: "mytoken"
job_id: "xxxxxxxxxxxxxxxxx"
job_options:
- option_1: "value_1"
- option_2: "value_3"
- option_3: "value_3"
+ option_1: "value_1"
+ option_2: "value_3"
+ option_3: "value_3"
register: rundeck_job_run
- name: Run a Rundeck job with timeout, delay between status check and abort on timeout
@@ -130,9 +129,9 @@ EXAMPLES = '''
job_id: "xxxxxxxxxxxxxxxxx"
wait_execution: false
register: rundeck_job_run
-'''
+"""
-RETURN = '''
+RETURN = r"""
execution_info:
description: Rundeck job execution metadata.
returned: always
@@ -177,7 +176,7 @@ execution_info:
"output": "Test!"
}
}
-'''
+"""
# Modules import
from datetime import datetime, timedelta
diff --git a/plugins/modules/rundeck_project.py b/plugins/modules/rundeck_project.py
index 79ca575684..0cb6010346 100644
--- a/plugins/modules/rundeck_project.py
+++ b/plugins/modules/rundeck_project.py
@@ -13,60 +13,59 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: rundeck_project
short_description: Manage Rundeck projects
description:
- - Create and remove Rundeck projects through HTTP API.
+ - Create and remove Rundeck projects through HTTP API.
author: "Loic Blot (@nerzhul)"
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- state:
- type: str
- description:
- - Create or remove Rundeck project.
- choices: ['present', 'absent']
- default: 'present'
- name:
- type: str
- description:
- - Sets the project name.
- required: true
- api_token:
- description:
- - Sets the token to authenticate against Rundeck API.
- aliases: ["token"]
- client_cert:
- version_added: '0.2.0'
- client_key:
- version_added: '0.2.0'
- force:
- version_added: '0.2.0'
- force_basic_auth:
- version_added: '0.2.0'
- http_agent:
- version_added: '0.2.0'
- url_password:
- version_added: '0.2.0'
- url_username:
- version_added: '0.2.0'
- use_proxy:
- version_added: '0.2.0'
- validate_certs:
- version_added: '0.2.0'
+ state:
+ type: str
+ description:
+ - Create or remove Rundeck project.
+ choices: ['present', 'absent']
+ default: 'present'
+ name:
+ type: str
+ description:
+ - Sets the project name.
+ required: true
+ api_token:
+ description:
+ - Sets the token to authenticate against Rundeck API.
+ aliases: ["token"]
+ client_cert:
+ version_added: '0.2.0'
+ client_key:
+ version_added: '0.2.0'
+ force:
+ version_added: '0.2.0'
+ force_basic_auth:
+ version_added: '0.2.0'
+ http_agent:
+ version_added: '0.2.0'
+ url_password:
+ version_added: '0.2.0'
+ url_username:
+ version_added: '0.2.0'
+ use_proxy:
+ version_added: '0.2.0'
+ validate_certs:
+ version_added: '0.2.0'
extends_documentation_fragment:
- ansible.builtin.url
- community.general.attributes
- community.general.rundeck
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a rundeck project
community.general.rundeck_project:
name: "Project_01"
@@ -83,22 +82,22 @@ EXAMPLES = '''
url: "https://rundeck.example.org"
api_token: "mytoken"
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
rundeck_response:
- description: Rundeck response when a failure occurs
- returned: failed
- type: str
+ description: Rundeck response when a failure occurs.
+ returned: failed
+ type: str
before:
- description: dictionary containing project information before modification
- returned: success
- type: dict
+ description: Dictionary containing project information before modification.
+ returned: success
+ type: dict
after:
- description: dictionary containing project information after modification
- returned: success
- type: dict
-'''
+ description: Dictionary containing project information after modification.
+ returned: success
+ type: dict
+"""
# import module snippets
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/runit.py b/plugins/modules/runit.py
index 2f1609ca6e..f26f241537 100644
--- a/plugins/modules/runit.py
+++ b/plugins/modules/runit.py
@@ -8,54 +8,50 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: runit
author:
- - James Sumners (@jsumners)
+ - James Sumners (@jsumners)
short_description: Manage runit services
description:
- - Controls runit services on remote hosts using the sv utility.
+ - Controls runit services on remote hosts using the sv utility.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of the service to manage.
- type: str
- required: true
- state:
- description:
- - V(started)/V(stopped) are idempotent actions that will not run
- commands unless necessary. V(restarted) will always bounce the
- service (sv restart) and V(killed) will always bounce the service (sv force-stop).
- V(reloaded) will send a HUP (sv reload).
- V(once) will run a normally downed sv once (sv once), not really
- an idempotent operation.
- type: str
- choices: [ killed, once, reloaded, restarted, started, stopped ]
- enabled:
- description:
- - Whether the service is enabled or not, if disabled it also implies stopped.
- type: bool
- service_dir:
- description:
- - directory runsv watches for services
- type: str
- default: /var/service
- service_src:
- description:
- - directory where services are defined, the source of symlinks to service_dir.
- type: str
- default: /etc/sv
-'''
+ name:
+ description:
+ - Name of the service to manage.
+ type: str
+ required: true
+ state:
+ description:
+ - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary. V(restarted) will always
+ bounce the service (sv restart) and V(killed) will always bounce the service (sv force-stop). V(reloaded) will send
+ a HUP (sv reload). V(once) will run a normally downed sv once (sv once), not really an idempotent operation.
+ type: str
+ choices: [killed, once, reloaded, restarted, started, stopped]
+ enabled:
+ description:
+ - Whether the service is enabled or not, if disabled it also implies stopped.
+ type: bool
+ service_dir:
+ description:
+ - Directory runsv watches for services.
+ type: str
+ default: /var/service
+ service_src:
+ description:
+ - Directory where services are defined, the source of symlinks to O(service_dir).
+ type: str
+ default: /etc/sv
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Start sv dnscache, if not running
community.general.runit:
name: dnscache
@@ -86,7 +82,7 @@ EXAMPLES = r'''
name: dnscache
state: reloaded
service_dir: /run/service
-'''
+"""
import os
import re
diff --git a/plugins/modules/say.py b/plugins/modules/say.py
index 175e5feb0b..2dc359083d 100644
--- a/plugins/modules/say.py
+++ b/plugins/modules/say.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: say
short_description: Makes a computer to speak
description:
- - makes a computer speak! Amuse your friends, annoy your coworkers!
+ - Makes a computer speak! Amuse your friends, annoy your coworkers!
notes:
- In 2.5, this module has been renamed from C(osx_say) to M(community.general.say).
- If you like this module, you may also be interested in the osx_say callback plugin.
@@ -37,19 +36,19 @@ options:
description:
- What voice to use.
required: false
-requirements: [ say or espeak or espeak-ng ]
+requirements: [say or espeak or espeak-ng]
author:
- - "Ansible Core Team"
- - "Michael DeHaan (@mpdehaan)"
-'''
+ - "Ansible Core Team"
+ - "Michael DeHaan (@mpdehaan)"
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Makes a computer to speak
community.general.say:
msg: '{{ inventory_hostname }} is all done'
voice: Zarvox
delegate_to: localhost
-'''
+"""
import platform
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/scaleway_compute.py b/plugins/modules/scaleway_compute.py
index d8480c199d..c61030bede 100644
--- a/plugins/modules/scaleway_compute.py
+++ b/plugins/modules/scaleway_compute.py
@@ -13,16 +13,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_compute
short_description: Scaleway compute management module
author: Remy Leone (@remyleone)
description:
- - "This module manages compute instances on Scaleway."
+ - This module manages compute instances on Scaleway.
extends_documentation_fragment:
- - community.general.scaleway
- - community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
@@ -35,35 +34,33 @@ options:
public_ip:
type: str
description:
- - Manage public IP on a Scaleway server
- - Could be Scaleway IP address UUID
- - V(dynamic) Means that IP is destroyed at the same time the host is destroyed
- - V(absent) Means no public IP at all
+ - Manage public IP on a Scaleway server.
+ - Could be Scaleway IP address UUID.
+ - V(dynamic) Means that IP is destroyed at the same time the host is destroyed.
+ - V(absent) Means no public IP at all.
default: absent
enable_ipv6:
description:
- - Enable public IPv6 connectivity on the instance
+ - Enable public IPv6 connectivity on the instance.
default: false
type: bool
image:
type: str
description:
- - Image identifier used to start the instance with
+ - Image identifier used to start the instance with.
required: true
name:
type: str
description:
- - Name of the instance
-
+ - Name of the instance.
organization:
type: str
description:
- Organization identifier.
- Exactly one of O(project) and O(organization) must be specified.
-
project:
type: str
description:
@@ -74,7 +71,7 @@ options:
state:
type: str
description:
- - Indicate desired state of the instance.
+ - Indicate desired state of the instance.
default: present
choices:
- present
@@ -87,14 +84,14 @@ options:
type: list
elements: str
description:
- - List of tags to apply to the instance (5 max)
+ - List of tags to apply to the instance (5 max).
required: false
default: []
region:
type: str
description:
- - Scaleway compute zone
+ - Scaleway compute zone.
required: true
choices:
- ams1
@@ -109,38 +106,38 @@ options:
commercial_type:
type: str
description:
- - Commercial name of the compute node
+ - Commercial name of the compute node.
required: true
wait:
description:
- - Wait for the instance to reach its desired state before returning.
+ - Wait for the instance to reach its desired state before returning.
type: bool
default: false
wait_timeout:
type: int
description:
- - Time to wait for the server to reach the expected state
+ - Time to wait for the server to reach the expected state.
required: false
default: 300
wait_sleep_time:
type: int
description:
- - Time to wait before every attempt to check the state of the server
+ - Time to wait before every attempt to check the state of the server.
required: false
default: 3
security_group:
type: str
description:
- - Security group unique identifier
- - If no value provided, the default security group or current security group will be used
+ - Security group unique identifier.
+ - If no value provided, the default security group or current security group will be used.
required: false
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a server
community.general.scaleway_compute:
name: foobar
@@ -174,10 +171,10 @@ EXAMPLES = '''
project: 951df375-e094-4d26-97c1-ba548eeb9c42
region: ams1
commercial_type: VC1S
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
import datetime
import time
diff --git a/plugins/modules/scaleway_compute_private_network.py b/plugins/modules/scaleway_compute_private_network.py
index b41720be58..5339dfef15 100644
--- a/plugins/modules/scaleway_compute_private_network.py
+++ b/plugins/modules/scaleway_compute_private_network.py
@@ -11,18 +11,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_compute_private_network
short_description: Scaleway compute - private network management
version_added: 5.2.0
author: Pascal MANGIN (@pastral)
description:
- - This module add or remove a private network to a compute instance
- (U(https://developer.scaleway.com)).
+ - This module add or remove a private network to a compute instance (U(https://developer.scaleway.com)).
extends_documentation_fragment:
- - community.general.scaleway
- - community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
@@ -34,7 +32,7 @@ options:
state:
type: str
description:
- - Indicate desired state of the VPC.
+ - Indicate desired state of the VPC.
default: present
choices:
- present
@@ -49,7 +47,7 @@ options:
region:
type: str
description:
- - Scaleway region to use (for example V(par1)).
+ - Scaleway region to use (for example V(par1)).
required: true
choices:
- ams1
@@ -64,18 +62,17 @@ options:
compute_id:
type: str
description:
- - ID of the compute instance (see M(community.general.scaleway_compute)).
+ - ID of the compute instance (see M(community.general.scaleway_compute)).
required: true
private_network_id:
type: str
description:
- - ID of the private network (see M(community.general.scaleway_private_network)).
+ - ID of the private network (see M(community.general.scaleway_private_network)).
required: true
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Plug a VM to a private network
community.general.scaleway_compute_private_network:
project: '{{ scw_project }}'
@@ -92,10 +89,9 @@ EXAMPLES = '''
region: par1
compute_id: "12345678-f1e6-40ec-83e5-12345d67ed89"
private_network_id: "22345678-f1e6-40ec-83e5-12345d67ed89"
+"""
-'''
-
-RETURN = '''
+RETURN = r"""
scaleway_compute_private_network:
description: Information on the VPC.
returned: success when O(state=present)
@@ -117,7 +113,8 @@ scaleway_compute_private_network:
"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
diff --git a/plugins/modules/scaleway_container.py b/plugins/modules/scaleway_container.py
index a18cb1d75f..dc4df1c1d5 100644
--- a/plugins/modules/scaleway_container.py
+++ b/plugins/modules/scaleway_container.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_container
short_description: Scaleway Container management
version_added: 6.0.0
@@ -109,7 +108,8 @@ options:
privacy:
description:
- Privacy policies define whether a container can be executed anonymously.
- - Choose V(public) to enable anonymous execution, or V(private) to protect your container with an authentication mechanism provided by the Scaleway API.
+ - Choose V(public) to enable anonymous execution, or V(private) to protect your container with an authentication mechanism
+ provided by the Scaleway API.
type: str
default: public
choices:
@@ -147,9 +147,9 @@ options:
- Redeploy the container if update is required.
type: bool
default: false
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a container
community.general.scaleway_container:
namespace_id: '{{ scw_container_namespace }}'
@@ -169,9 +169,9 @@ EXAMPLES = '''
state: absent
region: fr-par
name: my-awesome-container
-'''
+"""
-RETURN = '''
+RETURN = r"""
container:
description: The container information.
returned: when O(state=present)
@@ -181,7 +181,7 @@ container:
description: Container used for testing scaleway_container ansible module
domain_name: cnansibletestgfogtjod-cn-ansible-test.functions.fnc.fr-par.scw.cloud
environment_variables:
- MY_VAR: my_value
+ MY_VAR: my_value
error_message: null
http_option: ""
id: c9070eb0-d7a4-48dd-9af3-4fb139890721
@@ -201,7 +201,7 @@ container:
value: $argon2id$v=19$m=65536,t=1,p=2$tb6UwSPWx/rH5Vyxt9Ujfw$5ZlvaIjWwNDPxD9Rdght3NarJz4IETKjpvAU3mMSmFg
status: created
timeout: 300s
-'''
+"""
from copy import deepcopy
diff --git a/plugins/modules/scaleway_container_info.py b/plugins/modules/scaleway_container_info.py
index 350c96e545..e17547735a 100644
--- a/plugins/modules/scaleway_container_info.py
+++ b/plugins/modules/scaleway_container_info.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_container_info
short_description: Retrieve information on Scaleway Container
version_added: 6.0.0
@@ -46,18 +45,18 @@ options:
description:
- Name of the container.
required: true
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get a container info
community.general.scaleway_container_info:
namespace_id: '{{ scw_container_namespace }}'
region: fr-par
name: my-awesome-container
register: container_info_task
-'''
+"""
-RETURN = '''
+RETURN = r"""
container:
description: The container information.
returned: always
@@ -67,7 +66,7 @@ container:
description: Container used for testing scaleway_container ansible module
domain_name: cnansibletestgfogtjod-cn-ansible-test.functions.fnc.fr-par.scw.cloud
environment_variables:
- MY_VAR: my_value
+ MY_VAR: my_value
error_message: null
http_option: ""
id: c9070eb0-d7a4-48dd-9af3-4fb139890721
@@ -87,7 +86,7 @@ container:
value: $argon2id$v=19$m=65536,t=1,p=2$tb6UwSPWx/rH5Vyxt9Ujfw$5ZlvaIjWwNDPxD9Rdght3NarJz4IETKjpvAU3mMSmFg
status: created
timeout: 300s
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import (
SCALEWAY_REGIONS, scaleway_argument_spec, Scaleway,
diff --git a/plugins/modules/scaleway_container_namespace.py b/plugins/modules/scaleway_container_namespace.py
index 0f5de6c31d..802a491321 100644
--- a/plugins/modules/scaleway_container_namespace.py
+++ b/plugins/modules/scaleway_container_namespace.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_container_namespace
short_description: Scaleway Container namespace management
version_added: 6.0.0
@@ -24,7 +23,7 @@ extends_documentation_fragment:
- community.general.scaleway_waitable_resource
- community.general.attributes
requirements:
- - passlib[argon2] >= 1.7.4
+ - passlib[argon2] >= 1.7.4
attributes:
check_mode:
@@ -84,9 +83,9 @@ options:
- Injected in containers at runtime.
type: dict
default: {}
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a container namespace
community.general.scaleway_container_namespace:
project_id: '{{ scw_project }}'
@@ -105,9 +104,9 @@ EXAMPLES = '''
state: absent
region: fr-par
name: my-awesome-container-namespace
-'''
+"""
-RETURN = '''
+RETURN = r"""
container_namespace:
description: The container namespace information.
returned: when O(state=present)
@@ -128,7 +127,7 @@ container_namespace:
- key: MY_SECRET_VAR
value: $argon2id$v=19$m=65536,t=1,p=2$tb6UwSPWx/rH5Vyxt9Ujfw$5ZlvaIjWwNDPxD9Rdght3NarJz4IETKjpvAU3mMSmFg
status: pending
-'''
+"""
from copy import deepcopy
diff --git a/plugins/modules/scaleway_container_namespace_info.py b/plugins/modules/scaleway_container_namespace_info.py
index d783747203..d1e7196871 100644
--- a/plugins/modules/scaleway_container_namespace_info.py
+++ b/plugins/modules/scaleway_container_namespace_info.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_container_namespace_info
short_description: Retrieve information on Scaleway Container namespace
version_added: 6.0.0
@@ -46,18 +45,18 @@ options:
description:
- Name of the container namespace.
required: true
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get a container namespace info
community.general.scaleway_container_namespace_info:
project_id: '{{ scw_project }}'
region: fr-par
name: my-awesome-container-namespace
register: container_namespace_info_task
-'''
+"""
-RETURN = '''
+RETURN = r"""
container_namespace:
description: The container namespace information.
returned: always
@@ -66,7 +65,7 @@ container_namespace:
description: ""
environment_variables:
MY_VAR: my_value
- error_message: null
+ error_message:
id: 531a1fd7-98d2-4a74-ad77-d398324304b8
name: my-awesome-container-namespace
organization_id: e04e3bdc-015c-4514-afde-9389e9be24b0
@@ -78,7 +77,7 @@ container_namespace:
- key: MY_SECRET_VAR
value: $argon2id$v=19$m=65536,t=1,p=2$tb6UwSPWx/rH5Vyxt9Ujfw$5ZlvaIjWwNDPxD9Rdght3NarJz4IETKjpvAU3mMSmFg
status: pending
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import (
SCALEWAY_REGIONS, scaleway_argument_spec, Scaleway,
diff --git a/plugins/modules/scaleway_container_registry.py b/plugins/modules/scaleway_container_registry.py
index 4f17fecad7..132dfe8bb6 100644
--- a/plugins/modules/scaleway_container_registry.py
+++ b/plugins/modules/scaleway_container_registry.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_container_registry
short_description: Scaleway Container registry management module
version_added: 5.8.0
@@ -77,9 +76,9 @@ options:
- public
- private
default: private
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a container registry
community.general.scaleway_container_registry:
project_id: '{{ scw_project }}'
@@ -94,9 +93,9 @@ EXAMPLES = '''
state: absent
region: fr-par
name: my-awesome-container-registry
-'''
+"""
-RETURN = '''
+RETURN = r"""
container_registry:
description: The container registry information.
returned: when O(state=present)
@@ -116,7 +115,7 @@ container_registry:
status: ready
status_message: ""
updated_at: "2022-10-14T09:51:07.949716Z"
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import (
SCALEWAY_REGIONS, scaleway_argument_spec, Scaleway,
diff --git a/plugins/modules/scaleway_container_registry_info.py b/plugins/modules/scaleway_container_registry_info.py
index 7645789cff..e0fc1db5f3 100644
--- a/plugins/modules/scaleway_container_registry_info.py
+++ b/plugins/modules/scaleway_container_registry_info.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_container_registry_info
short_description: Scaleway Container registry info module
version_added: 5.8.0
@@ -46,18 +45,18 @@ options:
description:
- Name of the container registry.
required: true
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get a container registry info
community.general.scaleway_container_registry_info:
project_id: '{{ scw_project }}'
region: fr-par
name: my-awesome-container-registry
register: container_registry_info_task
-'''
+"""
-RETURN = '''
+RETURN = r"""
container_registry:
description: The container registry information.
returned: always
@@ -77,7 +76,7 @@ container_registry:
status: ready
status_message: ""
updated_at: "2022-10-14T09:51:07.949716Z"
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import (
SCALEWAY_REGIONS, scaleway_argument_spec, Scaleway,
diff --git a/plugins/modules/scaleway_database_backup.py b/plugins/modules/scaleway_database_backup.py
index 1d0c17fb6d..b19a6b49bd 100644
--- a/plugins/modules/scaleway_database_backup.py
+++ b/plugins/modules/scaleway_database_backup.py
@@ -12,17 +12,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_database_backup
short_description: Scaleway database backups management module
version_added: 1.2.0
author: Guillaume Rodriguez (@guillaume_ro_fr)
description:
- - "This module manages database backups on Scaleway account U(https://developer.scaleway.com)."
+ - This module manages database backups on Scaleway account U(https://developer.scaleway.com).
extends_documentation_fragment:
- - community.general.scaleway
- - community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -31,118 +30,118 @@ attributes:
options:
state:
description:
- - Indicate desired state of the database backup.
- - V(present) creates a backup.
- - V(absent) deletes the backup.
- - V(exported) creates a download link for the backup.
- - V(restored) restores the backup to a new database.
+ - Indicate desired state of the database backup.
+ - V(present) creates a backup.
+ - V(absent) deletes the backup.
+ - V(exported) creates a download link for the backup.
+ - V(restored) restores the backup to a new database.
type: str
default: present
choices:
- - present
- - absent
- - exported
- - restored
+ - present
+ - absent
+ - exported
+ - restored
region:
description:
- - Scaleway region to use (for example V(fr-par)).
+ - Scaleway region to use (for example V(fr-par)).
type: str
required: true
choices:
- - fr-par
- - nl-ams
- - pl-waw
+ - fr-par
+ - nl-ams
+ - pl-waw
id:
description:
- - UUID used to identify the database backup.
- - Required for V(absent), V(exported) and V(restored) states.
+ - UUID used to identify the database backup.
+ - Required for V(absent), V(exported) and V(restored) states.
type: str
name:
description:
- - Name used to identify the database backup.
- - Required for V(present) state.
- - Ignored when O(state=absent), O(state=exported) or O(state=restored).
+ - Name used to identify the database backup.
+ - Required for V(present) state.
+ - Ignored when O(state=absent), O(state=exported) or O(state=restored).
type: str
required: false
database_name:
description:
- - Name used to identify the database.
- - Required for V(present) and V(restored) states.
- - Ignored when O(state=absent) or O(state=exported).
+ - Name used to identify the database.
+ - Required for V(present) and V(restored) states.
+ - Ignored when O(state=absent) or O(state=exported).
type: str
required: false
instance_id:
description:
- - UUID of the instance associated to the database backup.
- - Required for V(present) and V(restored) states.
- - Ignored when O(state=absent) or O(state=exported).
+ - UUID of the instance associated to the database backup.
+ - Required for V(present) and V(restored) states.
+ - Ignored when O(state=absent) or O(state=exported).
type: str
required: false
expires_at:
description:
- - Expiration datetime of the database backup (ISO 8601 format).
- - Ignored when O(state=absent), O(state=exported) or O(state=restored).
+ - Expiration datetime of the database backup (ISO 8601 format).
+ - Ignored when O(state=absent), O(state=exported) or O(state=restored).
type: str
required: false
wait:
description:
- - Wait for the instance to reach its desired state before returning.
+ - Wait for the instance to reach its desired state before returning.
type: bool
default: false
wait_timeout:
description:
- - Time to wait for the backup to reach the expected state.
+ - Time to wait for the backup to reach the expected state.
type: int
required: false
default: 300
wait_sleep_time:
description:
- - Time to wait before every attempt to check the state of the backup.
+ - Time to wait before every attempt to check the state of the backup.
type: int
required: false
default: 3
-'''
+"""
-EXAMPLES = '''
- - name: Create a backup
- community.general.scaleway_database_backup:
- name: 'my_backup'
- state: present
- region: 'fr-par'
- database_name: 'my-database'
- instance_id: '50968a80-2909-4e5c-b1af-a2e19860dddb'
+EXAMPLES = r"""
+- name: Create a backup
+ community.general.scaleway_database_backup:
+ name: 'my_backup'
+ state: present
+ region: 'fr-par'
+ database_name: 'my-database'
+ instance_id: '50968a80-2909-4e5c-b1af-a2e19860dddb'
- - name: Export a backup
- community.general.scaleway_database_backup:
- id: '6ef1125a-037e-494f-a911-6d9c49a51691'
- state: exported
- region: 'fr-par'
+- name: Export a backup
+ community.general.scaleway_database_backup:
+ id: '6ef1125a-037e-494f-a911-6d9c49a51691'
+ state: exported
+ region: 'fr-par'
- - name: Restore a backup
- community.general.scaleway_database_backup:
- id: '6ef1125a-037e-494f-a911-6d9c49a51691'
- state: restored
- region: 'fr-par'
- database_name: 'my-new-database'
- instance_id: '50968a80-2909-4e5c-b1af-a2e19860dddb'
+- name: Restore a backup
+ community.general.scaleway_database_backup:
+ id: '6ef1125a-037e-494f-a911-6d9c49a51691'
+ state: restored
+ region: 'fr-par'
+ database_name: 'my-new-database'
+ instance_id: '50968a80-2909-4e5c-b1af-a2e19860dddb'
- - name: Remove a backup
- community.general.scaleway_database_backup:
- id: '6ef1125a-037e-494f-a911-6d9c49a51691'
- state: absent
- region: 'fr-par'
-'''
+- name: Remove a backup
+ community.general.scaleway_database_backup:
+ id: '6ef1125a-037e-494f-a911-6d9c49a51691'
+ state: absent
+ region: 'fr-par'
+"""
-RETURN = '''
+RETURN = r"""
metadata:
description: Backup metadata.
returned: when O(state=present), O(state=exported), or O(state=restored)
@@ -164,7 +163,7 @@ metadata:
"updated_at": "2020-08-06T12:42:10.581649Z"
}
}
-'''
+"""
import datetime
import time
diff --git a/plugins/modules/scaleway_function.py b/plugins/modules/scaleway_function.py
index 2de0afd987..e2142dd1f2 100644
--- a/plugins/modules/scaleway_function.py
+++ b/plugins/modules/scaleway_function.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_function
short_description: Scaleway Function management
version_added: 6.0.0
@@ -97,8 +96,9 @@ options:
runtime:
description:
- - Runtime of the function
- - See U(https://www.scaleway.com/en/docs/compute/functions/reference-content/functions-lifecycle/) for all available runtimes
+ - Runtime of the function.
+ - See U(https://www.scaleway.com/en/docs/compute/functions/reference-content/functions-lifecycle/) for all available
+ runtimes.
type: str
required: true
@@ -121,7 +121,8 @@ options:
privacy:
description:
- Privacy policies define whether a function can be executed anonymously.
- - Choose V(public) to enable anonymous execution, or V(private) to protect your function with an authentication mechanism provided by the Scaleway API.
+ - Choose V(public) to enable anonymous execution, or V(private) to protect your function with an authentication mechanism
+ provided by the Scaleway API.
type: str
default: public
choices:
@@ -133,9 +134,9 @@ options:
- Redeploy the function if update is required.
type: bool
default: false
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a function
community.general.scaleway_function:
namespace_id: '{{ scw_function_namespace }}'
@@ -155,9 +156,9 @@ EXAMPLES = '''
region: fr-par
state: absent
name: my-awesome-function
-'''
+"""
-RETURN = '''
+RETURN = r"""
function:
description: The function information.
returned: when O(state=present)
@@ -186,7 +187,7 @@ function:
value: $argon2id$v=19$m=65536,t=1,p=2$tb6UwSPWx/rH5Vyxt9Ujfw$5ZlvaIjWwNDPxD9Rdght3NarJz4IETKjpvAU3mMSmFg
status: created
timeout: 300s
-'''
+"""
from copy import deepcopy
diff --git a/plugins/modules/scaleway_function_info.py b/plugins/modules/scaleway_function_info.py
index d65987664c..7a3acef11e 100644
--- a/plugins/modules/scaleway_function_info.py
+++ b/plugins/modules/scaleway_function_info.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_function_info
short_description: Retrieve information on Scaleway Function
version_added: 6.0.0
@@ -46,18 +45,18 @@ options:
description:
- Name of the function.
required: true
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get a function info
community.general.scaleway_function_info:
namespace_id: '{{ scw_function_namespace }}'
region: fr-par
name: my-awesome-function
register: function_info_task
-'''
+"""
-RETURN = '''
+RETURN = r"""
function:
description: The function information.
returned: always
@@ -68,7 +67,7 @@ function:
domain_name: fnansibletestfxamabuc-fn-ansible-test.functions.fnc.fr-par.scw.cloud
environment_variables:
MY_VAR: my_value
- error_message: null
+ error_message:
handler: handler.handle
http_option: ""
id: ceb64dc4-4464-4196-8e20-ecef705475d3
@@ -86,7 +85,7 @@ function:
value: $argon2id$v=19$m=65536,t=1,p=2$tb6UwSPWx/rH5Vyxt9Ujfw$5ZlvaIjWwNDPxD9Rdght3NarJz4IETKjpvAU3mMSmFg
status: created
timeout: 300s
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import (
SCALEWAY_REGIONS, scaleway_argument_spec, Scaleway
diff --git a/plugins/modules/scaleway_function_namespace.py b/plugins/modules/scaleway_function_namespace.py
index 7779761e38..d43b42bc7f 100644
--- a/plugins/modules/scaleway_function_namespace.py
+++ b/plugins/modules/scaleway_function_namespace.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_function_namespace
short_description: Scaleway Function namespace management
version_added: 6.0.0
@@ -84,9 +83,9 @@ options:
- Injected in functions at runtime.
type: dict
default: {}
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a function namespace
community.general.scaleway_function_namespace:
project_id: '{{ scw_project }}'
@@ -105,9 +104,9 @@ EXAMPLES = '''
state: absent
region: fr-par
name: my-awesome-function-namespace
-'''
+"""
-RETURN = '''
+RETURN = r"""
function_namespace:
description: The function namespace information.
returned: when O(state=present)
@@ -116,7 +115,7 @@ function_namespace:
description: ""
environment_variables:
MY_VAR: my_value
- error_message: null
+ error_message:
id: 531a1fd7-98d2-4a74-ad77-d398324304b8
name: my-awesome-function-namespace
organization_id: e04e3bdc-015c-4514-afde-9389e9be24b0
@@ -128,7 +127,7 @@ function_namespace:
- key: MY_SECRET_VAR
value: $argon2id$v=19$m=65536,t=1,p=2$tb6UwSPWx/rH5Vyxt9Ujfw$5ZlvaIjWwNDPxD9Rdght3NarJz4IETKjpvAU3mMSmFg
status: pending
-'''
+"""
from copy import deepcopy
diff --git a/plugins/modules/scaleway_function_namespace_info.py b/plugins/modules/scaleway_function_namespace_info.py
index d5d48ee4dd..f2bed200dc 100644
--- a/plugins/modules/scaleway_function_namespace_info.py
+++ b/plugins/modules/scaleway_function_namespace_info.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_function_namespace_info
short_description: Retrieve information on Scaleway Function namespace
version_added: 6.0.0
@@ -46,18 +45,18 @@ options:
description:
- Name of the function namespace.
required: true
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Get a function namespace info
community.general.scaleway_function_namespace_info:
project_id: '{{ scw_project }}'
region: fr-par
name: my-awesome-function-namespace
register: function_namespace_info_task
-'''
+"""
-RETURN = '''
+RETURN = r"""
function_namespace:
description: The function namespace information.
returned: always
@@ -66,7 +65,7 @@ function_namespace:
description: ""
environment_variables:
MY_VAR: my_value
- error_message: null
+ error_message:
id: 531a1fd7-98d2-4a74-ad77-d398324304b8
name: my-awesome-function-namespace
organization_id: e04e3bdc-015c-4514-afde-9389e9be24b0
@@ -78,7 +77,7 @@ function_namespace:
- key: MY_SECRET_VAR
value: $argon2id$v=19$m=65536,t=1,p=2$tb6UwSPWx/rH5Vyxt9Ujfw$5ZlvaIjWwNDPxD9Rdght3NarJz4IETKjpvAU3mMSmFg
status: pending
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import (
SCALEWAY_REGIONS, scaleway_argument_spec, Scaleway,
diff --git a/plugins/modules/scaleway_image_info.py b/plugins/modules/scaleway_image_info.py
index bdae185148..0f6d1539c8 100644
--- a/plugins/modules/scaleway_image_info.py
+++ b/plugins/modules/scaleway_image_info.py
@@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: scaleway_image_info
short_description: Gather information about the Scaleway images available
description:
@@ -37,9 +36,9 @@ options:
- EMEA-FR-PAR2
- waw1
- EMEA-PL-WAW1
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather Scaleway images information
community.general.scaleway_image_info:
region: par1
@@ -47,14 +46,13 @@ EXAMPLES = r'''
- ansible.builtin.debug:
msg: "{{ result.scaleway_image_info }}"
-'''
+"""
-RETURN = r'''
----
+RETURN = r"""
scaleway_image_info:
description:
- Response from Scaleway API.
- - "For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/)."
+ - 'For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/).'
returned: success
type: list
elements: dict
@@ -91,7 +89,7 @@ scaleway_image_info:
"state": "available"
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.scaleway import (
diff --git a/plugins/modules/scaleway_ip.py b/plugins/modules/scaleway_ip.py
index 79f0c7e3fb..2d51478159 100644
--- a/plugins/modules/scaleway_ip.py
+++ b/plugins/modules/scaleway_ip.py
@@ -11,17 +11,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_ip
short_description: Scaleway IP management module
author: Remy Leone (@remyleone)
description:
- - This module manages IP on Scaleway account
- U(https://developer.scaleway.com)
+ - This module manages IP on Scaleway account U(https://developer.scaleway.com).
extends_documentation_fragment:
- - community.general.scaleway
- - community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
@@ -33,7 +31,7 @@ options:
state:
type: str
description:
- - Indicate desired state of the IP.
+ - Indicate desired state of the IP.
default: present
choices:
- present
@@ -42,13 +40,13 @@ options:
organization:
type: str
description:
- - Scaleway organization identifier
+ - Scaleway organization identifier.
required: true
region:
type: str
description:
- - Scaleway region to use (for example par1).
+ - Scaleway region to use (for example par1).
required: true
choices:
- ams1
@@ -63,21 +61,19 @@ options:
id:
type: str
description:
- - id of the Scaleway IP (UUID)
-
+ - ID of the Scaleway IP (UUID).
server:
type: str
description:
- - id of the server you want to attach an IP to.
- - To unattach an IP don't specify this option
-
+ - ID of the server you want to attach an IP to.
+ - To unattach an IP do not specify this option.
reverse:
type: str
description:
- - Reverse to assign to the IP
-'''
+ - Reverse to assign to the IP.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create an IP
community.general.scaleway_ip:
organization: '{{ scw_org }}'
@@ -90,9 +86,9 @@ EXAMPLES = '''
id: '{{ ip_creation_task.scaleway_ip.id }}'
state: absent
region: par1
-'''
+"""
-RETURN = '''
+RETURN = r"""
data:
description: This is only present when O(state=present).
returned: when O(state=present)
@@ -110,8 +106,8 @@ data:
"address": "212.47.232.136"
}
]
- }
-'''
+ }
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import SCALEWAY_LOCATION, scaleway_argument_spec, Scaleway
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/scaleway_ip_info.py b/plugins/modules/scaleway_ip_info.py
index 1fd4be5898..7b8e1e6298 100644
--- a/plugins/modules/scaleway_ip_info.py
+++ b/plugins/modules/scaleway_ip_info.py
@@ -8,12 +8,11 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: scaleway_ip_info
-short_description: Gather information about the Scaleway ips available
+short_description: Gather information about the Scaleway IPs available
description:
- - Gather information about the Scaleway ips available.
+ - Gather information about the Scaleway IPs available.
author:
- "Yanis Guenane (@Spredzy)"
- "Remy Leone (@remyleone)"
@@ -37,24 +36,23 @@ options:
- EMEA-FR-PAR2
- waw1
- EMEA-PL-WAW1
-'''
+"""
-EXAMPLES = r'''
-- name: Gather Scaleway ips information
+EXAMPLES = r"""
+- name: Gather Scaleway IPs information
community.general.scaleway_ip_info:
region: par1
register: result
- ansible.builtin.debug:
msg: "{{ result.scaleway_ip_info }}"
-'''
+"""
-RETURN = r'''
----
+RETURN = r"""
scaleway_ip_info:
description:
- Response from Scaleway API.
- - "For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/)."
+ - 'For more details please refer to U(https://developers.scaleway.com/en/products/instance/api/).'
returned: success
type: list
elements: dict
@@ -71,7 +69,7 @@ scaleway_ip_info:
}
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.scaleway import (
diff --git a/plugins/modules/scaleway_lb.py b/plugins/modules/scaleway_lb.py
index 1083b6da9e..64a45c73ee 100644
--- a/plugins/modules/scaleway_lb.py
+++ b/plugins/modules/scaleway_lb.py
@@ -13,16 +13,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_lb
short_description: Scaleway load-balancer management module
author: Remy Leone (@remyleone)
description:
- - "This module manages load-balancers on Scaleway."
+ - This module manages load-balancers on Scaleway.
extends_documentation_fragment:
- - community.general.scaleway
- - community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
@@ -53,7 +52,7 @@ options:
state:
type: str
description:
- - Indicate desired state of the instance.
+ - Indicate desired state of the instance.
default: present
choices:
- present
@@ -62,7 +61,7 @@ options:
region:
type: str
description:
- - Scaleway zone.
+ - Scaleway zone.
required: true
choices:
- nl-ams
@@ -74,30 +73,29 @@ options:
elements: str
default: []
description:
- - List of tags to apply to the load-balancer.
-
+ - List of tags to apply to the load-balancer.
wait:
description:
- - Wait for the load-balancer to reach its desired state before returning.
+ - Wait for the load-balancer to reach its desired state before returning.
type: bool
default: false
wait_timeout:
type: int
description:
- - Time to wait for the load-balancer to reach the expected state.
+ - Time to wait for the load-balancer to reach the expected state.
required: false
default: 300
wait_sleep_time:
type: int
description:
- - Time to wait before every attempt to check the state of the load-balancer.
+ - Time to wait before every attempt to check the state of the load-balancer.
required: false
default: 3
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a load-balancer
community.general.scaleway_lb:
name: foobar
@@ -113,9 +111,9 @@ EXAMPLES = '''
state: absent
organization_id: 951df375-e094-4d26-97c1-ba548eeb9c42
region: fr-par
-'''
+"""
-RETURNS = '''
+RETURNS = """
{
"scaleway_lb": {
"backend_count": 0,
@@ -156,7 +154,7 @@ RETURNS = '''
]
}
}
-'''
+"""
import datetime
import time
@@ -228,8 +226,8 @@ def lb_attributes_should_be_changed(target_lb, wished_lb):
if diff:
return {attr: wished_lb[attr] for attr in MUTABLE_ATTRIBUTES}
- else:
- return diff
+
+ return {}
def present_strategy(api, wished_lb):
diff --git a/plugins/modules/scaleway_organization_info.py b/plugins/modules/scaleway_organization_info.py
index e9e272c988..603ab3cd4c 100644
--- a/plugins/modules/scaleway_organization_info.py
+++ b/plugins/modules/scaleway_organization_info.py
@@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: scaleway_organization_info
short_description: Gather information about the Scaleway organizations available
description:
@@ -27,20 +26,18 @@ extends_documentation_fragment:
- community.general.scaleway
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather Scaleway organizations information
community.general.scaleway_organization_info:
register: result
- ansible.builtin.debug:
msg: "{{ result.scaleway_organization_info }}"
-'''
+"""
-RETURN = r'''
----
+RETURN = r"""
scaleway_organization_info:
description: Response from Scaleway API.
returned: success
@@ -70,7 +67,7 @@ scaleway_organization_info:
"warnings": []
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule, env_fallback
from ansible_collections.community.general.plugins.module_utils.scaleway import (
diff --git a/plugins/modules/scaleway_private_network.py b/plugins/modules/scaleway_private_network.py
index 0cc9b900f4..922a780098 100644
--- a/plugins/modules/scaleway_private_network.py
+++ b/plugins/modules/scaleway_private_network.py
@@ -11,17 +11,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
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))."
+ - This module manages private network on Scaleway account (U(https://developer.scaleway.com)).
extends_documentation_fragment:
- - community.general.scaleway
- - community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
@@ -33,7 +32,7 @@ options:
state:
type: str
description:
- - Indicate desired state of the VPC.
+ - Indicate desired state of the VPC.
default: present
choices:
- present
@@ -48,7 +47,7 @@ options:
region:
type: str
description:
- - Scaleway region to use (for example V(par1)).
+ - Scaleway region to use (for example V(par1)).
required: true
choices:
- ams1
@@ -63,18 +62,16 @@ options:
name:
type: str
description:
- - Name of the VPC.
-
+ - Name of the VPC.
tags:
type: list
elements: str
description:
- - List of tags to apply to the instance.
+ - List of tags to apply to the instance.
default: []
+"""
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create an private network
community.general.scaleway_vpc:
project: '{{ scw_project }}'
@@ -88,9 +85,9 @@ EXAMPLES = '''
name: 'foo'
state: absent
region: par1
-'''
+"""
-RETURN = '''
+RETURN = r"""
scaleway_private_network:
description: Information on the VPC.
returned: success when O(state=present)
@@ -112,7 +109,7 @@ scaleway_private_network:
"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
diff --git a/plugins/modules/scaleway_security_group.py b/plugins/modules/scaleway_security_group.py
index 3aee99e99a..3e1a28275e 100644
--- a/plugins/modules/scaleway_security_group.py
+++ b/plugins/modules/scaleway_security_group.py
@@ -12,16 +12,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_security_group
short_description: Scaleway Security Group management module
author: Antoine Barbare (@abarbare)
description:
- - "This module manages Security Group on Scaleway account U(https://developer.scaleway.com)."
+ - This module manages Security Group on Scaleway account U(https://developer.scaleway.com).
extends_documentation_fragment:
- - community.general.scaleway
- - community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
@@ -34,7 +33,7 @@ options:
description:
- Indicate desired state of the Security Group.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
organization:
@@ -79,21 +78,21 @@ options:
description:
- Default policy for incoming traffic.
type: str
- choices: [ accept, drop ]
+ choices: [accept, drop]
outbound_default_policy:
description:
- Default policy for outcoming traffic.
type: str
- choices: [ accept, drop ]
+ choices: [accept, drop]
organization_default:
description:
- Create security group to be the default one.
type: bool
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a Security Group
community.general.scaleway_security_group:
state: present
@@ -106,9 +105,9 @@ EXAMPLES = '''
outbound_default_policy: accept
organization_default: false
register: security_group_creation_task
-'''
+"""
-RETURN = '''
+RETURN = r"""
data:
description: This is only present when O(state=present).
returned: when O(state=present)
@@ -127,7 +126,7 @@ data:
"stateful": false
}
}
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import SCALEWAY_LOCATION, scaleway_argument_spec, Scaleway
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/scaleway_security_group_info.py b/plugins/modules/scaleway_security_group_info.py
index fb28e87740..6664938e09 100644
--- a/plugins/modules/scaleway_security_group_info.py
+++ b/plugins/modules/scaleway_security_group_info.py
@@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: scaleway_security_group_info
short_description: Gather information about the Scaleway security groups available
description:
@@ -36,10 +35,9 @@ extends_documentation_fragment:
- community.general.scaleway
- community.general.attributes
- community.general.attributes.info_module
+"""
-'''
-
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather Scaleway security groups information
community.general.scaleway_security_group_info:
region: par1
@@ -47,14 +45,13 @@ EXAMPLES = r'''
- ansible.builtin.debug:
msg: "{{ result.scaleway_security_group_info }}"
-'''
+"""
-RETURN = r'''
----
+RETURN = r"""
scaleway_security_group_info:
description:
- Response from Scaleway API.
- - "For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/)."
+ - 'For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/).'
returned: success
type: list
elements: dict
@@ -75,7 +72,7 @@ scaleway_security_group_info:
]
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.scaleway import (
diff --git a/plugins/modules/scaleway_security_group_rule.py b/plugins/modules/scaleway_security_group_rule.py
index 9cbb2eb57e..ec89d41f6c 100644
--- a/plugins/modules/scaleway_security_group_rule.py
+++ b/plugins/modules/scaleway_security_group_rule.py
@@ -12,13 +12,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_security_group_rule
short_description: Scaleway Security Group Rule management module
author: Antoine Barbare (@abarbare)
description:
- - "This module manages Security Group Rule on Scaleway account U(https://developer.scaleway.com)."
+ - This module manages Security Group Rule on Scaleway account U(https://developer.scaleway.com).
extends_documentation_fragment:
- community.general.scaleway
- community.general.attributes
@@ -99,23 +98,23 @@ options:
description:
- Security Group unique identifier.
required: true
-'''
+"""
-EXAMPLES = '''
- - name: Create a Security Group Rule
- community.general.scaleway_security_group_rule:
- state: present
- region: par1
- protocol: TCP
- port: 80
- ip_range: 0.0.0.0/0
- direction: inbound
- action: accept
- security_group: b57210ee-1281-4820-a6db-329f78596ecb
- register: security_group_rule_creation_task
-'''
+EXAMPLES = r"""
+- name: Create a Security Group Rule
+ community.general.scaleway_security_group_rule:
+ state: present
+ region: par1
+ protocol: TCP
+ port: 80
+ ip_range: 0.0.0.0/0
+ direction: inbound
+ action: accept
+ security_group: b57210ee-1281-4820-a6db-329f78596ecb
+ register: security_group_rule_creation_task
+"""
-RETURN = '''
+RETURN = r"""
data:
description: This is only present when O(state=present).
returned: when O(state=present)
@@ -133,7 +132,7 @@ data:
"id": "10cb0b9a-80f6-4830-abd7-a31cd828b5e9"
}
}
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import SCALEWAY_LOCATION, scaleway_argument_spec, Scaleway, payload_from_object
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/scaleway_server_info.py b/plugins/modules/scaleway_server_info.py
index 01e9410da8..39af47005e 100644
--- a/plugins/modules/scaleway_server_info.py
+++ b/plugins/modules/scaleway_server_info.py
@@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: scaleway_server_info
short_description: Gather information about the Scaleway servers available
description:
@@ -37,9 +36,9 @@ options:
- EMEA-FR-PAR2
- waw1
- EMEA-PL-WAW1
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather Scaleway servers information
community.general.scaleway_server_info:
region: par1
@@ -47,14 +46,13 @@ EXAMPLES = r'''
- ansible.builtin.debug:
msg: "{{ result.scaleway_server_info }}"
-'''
+"""
-RETURN = r'''
----
+RETURN = r"""
scaleway_server_info:
description:
- Response from Scaleway API.
- - "For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/)."
+ - 'For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/).'
returned: success
type: list
elements: dict
@@ -157,7 +155,7 @@ scaleway_server_info:
}
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.scaleway import (
diff --git a/plugins/modules/scaleway_snapshot_info.py b/plugins/modules/scaleway_snapshot_info.py
index 687f43c85b..6b932cced2 100644
--- a/plugins/modules/scaleway_snapshot_info.py
+++ b/plugins/modules/scaleway_snapshot_info.py
@@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: scaleway_snapshot_info
short_description: Gather information about the Scaleway snapshots available
description:
@@ -37,9 +36,9 @@ options:
- EMEA-FR-PAR2
- waw1
- EMEA-PL-WAW1
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather Scaleway snapshots information
community.general.scaleway_snapshot_info:
region: par1
@@ -47,14 +46,13 @@ EXAMPLES = r'''
- ansible.builtin.debug:
msg: "{{ result.scaleway_snapshot_info }}"
-'''
+"""
-RETURN = r'''
----
+RETURN = r"""
scaleway_snapshot_info:
description:
- Response from Scaleway API.
- - "For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/)."
+ - 'For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/).'
returned: success
type: list
elements: dict
@@ -75,7 +73,7 @@ scaleway_snapshot_info:
"volume_type": "l_ssd"
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.scaleway import (
diff --git a/plugins/modules/scaleway_sshkey.py b/plugins/modules/scaleway_sshkey.py
index 5647f9cd05..37e8ec8c3b 100644
--- a/plugins/modules/scaleway_sshkey.py
+++ b/plugins/modules/scaleway_sshkey.py
@@ -13,16 +13,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_sshkey
short_description: Scaleway SSH keys management module
author: Remy Leone (@remyleone)
description:
- - "This module manages SSH keys on Scaleway account U(https://developer.scaleway.com)."
+ - This module manages SSH keys on Scaleway account (U(https://developer.scaleway.com)).
extends_documentation_fragment:
-- community.general.scaleway
-- community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
@@ -34,7 +33,7 @@ options:
state:
type: str
description:
- - Indicate desired state of the SSH key.
+ - Indicate desired state of the SSH key.
default: present
choices:
- present
@@ -42,7 +41,7 @@ options:
ssh_pub_key:
type: str
description:
- - The public SSH key as a string to add.
+ - The public SSH key as a string to add.
required: true
api_url:
type: str
@@ -50,9 +49,9 @@ options:
- Scaleway API URL.
default: 'https://account.scaleway.com'
aliases: ['base_url']
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: "Add SSH key"
community.general.scaleway_sshkey:
ssh_pub_key: "ssh-rsa AAAA..."
@@ -68,9 +67,9 @@ EXAMPLES = '''
ssh_pub_key: "ssh-rsa AAAA..."
state: "present"
oauth_token: "6ecd2c9b-6f4f-44d4-a187-61a92078d08c"
-'''
+"""
-RETURN = '''
+RETURN = r"""
data:
description: This is only present when O(state=present).
returned: when O(state=present)
@@ -80,7 +79,7 @@ data:
{"key": "ssh-rsa AAAA...."}
]
}
-'''
+"""
from ansible.module_utils.basic import AnsibleModule, env_fallback
from ansible_collections.community.general.plugins.module_utils.scaleway import scaleway_argument_spec, Scaleway
diff --git a/plugins/modules/scaleway_user_data.py b/plugins/modules/scaleway_user_data.py
index 72046ff532..f4f2c18624 100644
--- a/plugins/modules/scaleway_user_data.py
+++ b/plugins/modules/scaleway_user_data.py
@@ -13,17 +13,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_user_data
short_description: Scaleway user_data management module
author: Remy Leone (@remyleone)
description:
- - This module manages user_data on compute instances on Scaleway.
- - It can be used to configure cloud-init for instance.
+ - This module manages user_data on compute instances on Scaleway.
+ - It can be used to configure cloud-init for instance.
extends_documentation_fragment:
-- community.general.scaleway
-- community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
@@ -36,20 +35,20 @@ options:
server_id:
type: str
description:
- - Scaleway Compute instance ID of the server.
+ - Scaleway Compute instance ID of the server.
required: true
user_data:
type: dict
description:
- - User defined data. Typically used with C(cloud-init).
- - Pass your C(cloud-init) script here as a string.
+ - User defined data. Typically used with C(cloud-init).
+ - Pass your C(cloud-init) script here as a string.
required: false
region:
type: str
description:
- - Scaleway compute zone.
+ - Scaleway compute zone.
required: true
choices:
- ams1
@@ -60,19 +59,19 @@ options:
- EMEA-FR-PAR2
- waw1
- EMEA-PL-WAW1
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Update the cloud-init
community.general.scaleway_user_data:
server_id: '5a33b4ab-57dd-4eb6-8b0a-d95eb63492ce'
region: ams1
user_data:
cloud-init: 'final_message: "Hello World!"'
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.scaleway import SCALEWAY_LOCATION, scaleway_argument_spec, Scaleway
diff --git a/plugins/modules/scaleway_volume.py b/plugins/modules/scaleway_volume.py
index 46d72288e7..ed6a506742 100644
--- a/plugins/modules/scaleway_volume.py
+++ b/plugins/modules/scaleway_volume.py
@@ -12,16 +12,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: scaleway_volume
short_description: Scaleway volumes management module
author: Henryk Konsek (@hekonsek)
description:
- - "This module manages volumes on Scaleway account U(https://developer.scaleway.com)."
+ - This module manages volumes on Scaleway account U(https://developer.scaleway.com).
extends_documentation_fragment:
-- community.general.scaleway
-- community.general.attributes
+ - community.general.scaleway
+ - community.general.attributes
attributes:
check_mode:
@@ -74,9 +73,9 @@ options:
type: str
description:
- Type of the volume (for example 'l_ssd').
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create 10GB volume
community.general.scaleway_volume:
name: my-volume
@@ -92,9 +91,9 @@ EXAMPLES = '''
name: my-volume
state: absent
region: par1
-'''
+"""
-RETURN = '''
+RETURN = r"""
data:
description: This is only present when O(state=present).
returned: when O(state=present)
@@ -110,7 +109,7 @@ data:
"volume_type": "l_ssd"
}
}
-'''
+"""
from ansible_collections.community.general.plugins.module_utils.scaleway import SCALEWAY_LOCATION, scaleway_argument_spec, Scaleway
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/scaleway_volume_info.py b/plugins/modules/scaleway_volume_info.py
index 471845c43e..1b2e95f88c 100644
--- a/plugins/modules/scaleway_volume_info.py
+++ b/plugins/modules/scaleway_volume_info.py
@@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: scaleway_volume_info
short_description: Gather information about the Scaleway volumes available
description:
@@ -37,9 +36,9 @@ options:
- EMEA-FR-PAR2
- waw1
- EMEA-PL-WAW1
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather Scaleway volumes information
community.general.scaleway_volume_info:
region: par1
@@ -47,14 +46,13 @@ EXAMPLES = r'''
- ansible.builtin.debug:
msg: "{{ result.scaleway_volume_info }}"
-'''
+"""
-RETURN = r'''
----
+RETURN = r"""
scaleway_volume_info:
description:
- Response from Scaleway API.
- - "For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/)."
+ - 'For more details please refer to: U(https://developers.scaleway.com/en/products/instance/api/).'
returned: success
type: list
elements: dict
@@ -73,7 +71,7 @@ scaleway_volume_info:
"volume_type": "l_ssd"
}
]
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.scaleway import (
diff --git a/plugins/modules/sefcontext.py b/plugins/modules/sefcontext.py
index 19c128fa7b..d1023d9d87 100644
--- a/plugins/modules/sefcontext.py
+++ b/plugins/modules/sefcontext.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: sefcontext
short_description: Manages SELinux file context mapping definitions
description:
@@ -28,85 +27,85 @@ attributes:
options:
target:
description:
- - Target path (expression).
+ - Target path (expression).
type: str
required: true
- aliases: [ path ]
+ aliases: [path]
ftype:
description:
- - The file type that should have SELinux contexts applied.
- - "The following file type options are available:"
- - V(a) for all files,
- - V(b) for block devices,
- - V(c) for character devices,
- - V(d) for directories,
- - V(f) for regular files,
- - V(l) for symbolic links,
- - V(p) for named pipes,
- - V(s) for socket files.
+ - The file type that should have SELinux contexts applied.
+ - 'The following file type options are available:'
+ - V(a) for all files,
+ - V(b) for block devices,
+ - V(c) for character devices,
+ - V(d) for directories,
+ - V(f) for regular files,
+ - V(l) for symbolic links,
+ - V(p) for named pipes,
+ - V(s) for socket files.
type: str
- choices: [ a, b, c, d, f, l, p, s ]
+ choices: [a, b, c, d, f, l, p, s]
default: a
setype:
description:
- - SELinux type for the specified O(target).
+ - SELinux type for the specified O(target).
type: str
substitute:
description:
- - Path to use to substitute file context(s) for the specified O(target). The context labeling for the O(target) subtree is made equivalent to this path.
- - This is also referred to as SELinux file context equivalence and it implements the C(equal) functionality of the SELinux management tools.
+ - Path to use to substitute file context(s) for the specified O(target). The context labeling for the O(target) subtree
+ is made equivalent to this path.
+ - This is also referred to as SELinux file context equivalence and it implements the C(equal) functionality of the SELinux
+ management tools.
version_added: 6.4.0
type: str
- aliases: [ equal ]
+ aliases: [equal]
seuser:
description:
- - SELinux user for the specified O(target).
- - Defaults to V(system_u) for new file contexts and to existing value when modifying file contexts.
+ - SELinux user for the specified O(target).
+ - Defaults to V(system_u) for new file contexts and to existing value when modifying file contexts.
type: str
selevel:
description:
- - SELinux range for the specified O(target).
- - Defaults to V(s0) for new file contexts and to existing value when modifying file contexts.
+ - SELinux range for the specified O(target).
+ - Defaults to V(s0) for new file contexts and to existing value when modifying file contexts.
type: str
- aliases: [ serange ]
+ aliases: [serange]
state:
description:
- - Whether the SELinux file context must be V(absent) or V(present).
- - Specifying V(absent) without either O(setype) or O(substitute) deletes both SELinux type or path substitution mappings that match O(target).
+ - Whether the SELinux file context must be V(absent) or V(present).
+ - Specifying V(absent) without either O(setype) or O(substitute) deletes both SELinux type or path substitution mappings
+ that match O(target).
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
reload:
description:
- - Reload SELinux policy after commit.
- - Note that this does not apply SELinux file contexts to existing files.
+ - Reload SELinux policy after commit.
+ - Note that this does not apply SELinux file contexts to existing files.
type: bool
default: true
ignore_selinux_state:
description:
- - Useful for scenarios (chrooted environment) that you can't get the real SELinux state.
+ - Useful for scenarios (chrooted environment) that you cannot get the real SELinux state.
type: bool
default: false
notes:
-- The changes are persistent across reboots.
-- O(setype) and O(substitute) are mutually exclusive.
-- If O(state=present) then one of O(setype) or O(substitute) is mandatory.
-- The M(community.general.sefcontext) module does not modify existing files to the new
- SELinux context(s), so it is advisable to first create the SELinux
- file contexts before creating files, or run C(restorecon) manually
- for the existing files that require the new SELinux file contexts.
-- Not applying SELinux fcontexts to existing files is a deliberate
- decision as it would be unclear what reported changes would entail
- to, and there's no guarantee that applying SELinux fcontext does
- not pick up other unrelated prior changes.
+ - The changes are persistent across reboots.
+ - O(setype) and O(substitute) are mutually exclusive.
+ - If O(state=present) then one of O(setype) or O(substitute) is mandatory.
+ - The M(community.general.sefcontext) module does not modify existing files to the new SELinux context(s), so it is advisable
+ to first create the SELinux file contexts before creating files, or run C(restorecon) manually for the existing files
+ that require the new SELinux file contexts.
+ - Not applying SELinux fcontexts to existing files is a deliberate decision as it would be unclear what reported changes
+ would entail to, and there is no guarantee that applying SELinux fcontext does not pick up other unrelated prior changes.
requirements:
-- libselinux-python
-- policycoreutils-python
+ - libselinux-python
+ - policycoreutils-python
author:
-- Dag Wieers (@dagwieers)
-'''
+ - Dag Wieers (@dagwieers)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Allow apache to modify files in /srv/git_repos
community.general.sefcontext:
target: '/srv/git_repos(/.*)?'
@@ -132,11 +131,11 @@ EXAMPLES = r'''
- name: Apply new SELinux file context to filesystem
ansible.builtin.command: restorecon -irv /srv/git_repos
-'''
+"""
-RETURN = r'''
+RETURN = r"""
# Default return values
-'''
+"""
import traceback
diff --git a/plugins/modules/selinux_permissive.py b/plugins/modules/selinux_permissive.py
index 80439e1de7..b5c0ee4a61 100644
--- a/plugins/modules/selinux_permissive.py
+++ b/plugins/modules/selinux_permissive.py
@@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: selinux_permissive
short_description: Change permissive domain in SELinux policy
description:
@@ -25,20 +24,20 @@ attributes:
options:
domain:
description:
- - The domain that will be added or removed from the list of permissive domains.
+ - The domain that will be added or removed from the list of permissive domains.
type: str
required: true
- aliases: [ name ]
+ aliases: [name]
permissive:
description:
- - Indicate if the domain should or should not be set as permissive.
+ - Indicate if the domain should or should not be set as permissive.
type: bool
required: true
no_reload:
description:
- - Disable reloading of the SELinux policy after making change to a domain's permissive setting.
- - The default is V(false), which causes policy to be reloaded when a domain changes state.
- - Reloading the policy does not work on older versions of the C(policycoreutils-python) library, for example in EL 6."
+ - Disable reloading of the SELinux policy after making change to a domain's permissive setting.
+ - The default is V(false), which causes policy to be reloaded when a domain changes state.
+ - Reloading the policy does not work on older versions of the C(policycoreutils-python) library, for example in EL 6.".
type: bool
default: false
store:
@@ -47,18 +46,18 @@ options:
type: str
default: ''
notes:
- - Requires a recent version of SELinux and C(policycoreutils-python) (EL 6 or newer).
-requirements: [ policycoreutils-python ]
+ - Requires a recent version of SELinux and C(policycoreutils-python) (EL 6 or newer).
+requirements: [policycoreutils-python]
author:
-- Michael Scherer (@mscherer)
-'''
+ - Michael Scherer (@mscherer)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Change the httpd_t domain to permissive
community.general.selinux_permissive:
name: httpd_t
permissive: true
-'''
+"""
import traceback
diff --git a/plugins/modules/selogin.py b/plugins/modules/selogin.py
index 57482b0908..8f1b20c230 100644
--- a/plugins/modules/selogin.py
+++ b/plugins/modules/selogin.py
@@ -8,12 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: selogin
short_description: Manages linux user to SELinux user mapping
description:
- - Manages linux user to SELinux user mapping
+ - Manages linux user to SELinux user mapping.
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -25,15 +24,15 @@ options:
login:
type: str
description:
- - a Linux user
+ - A Linux user.
required: true
seuser:
type: str
description:
- - SELinux user name
+ - SELinux user name.
selevel:
type: str
- aliases: [ serange ]
+ aliases: [serange]
description:
- MLS/MCS Security Range (MLS/MCS Systems only) SELinux Range for SELinux login mapping defaults to the SELinux user record range.
default: s0
@@ -42,7 +41,7 @@ options:
description:
- Desired mapping value.
default: present
- choices: [ 'present', 'absent' ]
+ choices: ['present', 'absent']
reload:
description:
- Reload SELinux policy after commit.
@@ -50,20 +49,20 @@ options:
default: true
ignore_selinux_state:
description:
- - Run independent of selinux runtime state
+ - Run independent of selinux runtime state.
type: bool
default: false
notes:
- - The changes are persistent across reboots
- - Not tested on any debian based system
-requirements: [ 'libselinux', 'policycoreutils' ]
+ - The changes are persistent across reboots.
+ - Not tested on any debian based system.
+requirements: ['libselinux', 'policycoreutils']
author:
-- Dan Keder (@dankeder)
-- Petr Lautrbach (@bachradsusi)
-- James Cassell (@jamescassell)
-'''
+ - Dan Keder (@dankeder)
+ - Petr Lautrbach (@bachradsusi)
+ - James Cassell (@jamescassell)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Modify the default user on the system to the guest_u user
community.general.selogin:
login: __default__
@@ -82,11 +81,11 @@ EXAMPLES = '''
login: '%engineering'
seuser: staff_u
state: present
-'''
+"""
-RETURN = r'''
+RETURN = r"""
# Default return values
-'''
+"""
import traceback
diff --git a/plugins/modules/sendgrid.py b/plugins/modules/sendgrid.py
index b4f6b6eaff..1099f579e1 100644
--- a/plugins/modules/sendgrid.py
+++ b/plugins/modules/sendgrid.py
@@ -9,21 +9,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: sendgrid
short_description: Sends an email with the SendGrid API
description:
- - "Sends an email with a SendGrid account through their API, not through
- the SMTP service."
+ - Sends an email with a SendGrid account through their API, not through the SMTP service.
notes:
- - "This module is non-idempotent because it sends an email through the
- external API. It is idempotent only in the case that the module fails."
- - "Like the other notification modules, this one requires an external
- dependency to work. In this case, you'll need an active SendGrid
- account."
- - "In order to use api_key, cc, bcc, attachments, from_name, html_body, headers
- you must pip install sendgrid"
+ - This module is non-idempotent because it sends an email through the external API. It is idempotent only in the case that
+ the module fails.
+ - Like the other notification modules, this one requires an external dependency to work. In this case, you will need an
+ active SendGrid account.
+ - In order to use O(api_key), O(cc), O(bcc), O(attachments), O(from_name), O(html_body), and O(headers) you must C(pip install
+ sendgrid).
requirements:
- sendgrid Python library 1.6.22 or lower (Sendgrid API V2 supported)
extends_documentation_fragment:
@@ -82,7 +79,7 @@ options:
from_name:
type: str
description:
- - The name you want to appear in the from field, i.e 'John Doe'.
+ - The name you want to appear in the from field, for example V(John Doe).
html_body:
description:
- Whether the body is html content that should be rendered.
@@ -98,9 +95,9 @@ options:
- The e-mail body content.
required: true
author: "Matt Makai (@makaimc)"
-'''
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Send an email to a single recipient that the deployment was successful
community.general.sendgrid:
username: "{{ sendgrid_username }}"
@@ -114,16 +111,16 @@ EXAMPLES = r'''
- name: Send an email to more than one recipient that the build failed
community.general.sendgrid:
- username: "{{ sendgrid_username }}"
- password: "{{ sendgrid_password }}"
- from_address: "build@mycompany.com"
- to_addresses:
- - "ops@mycompany.com"
- - "devteam@mycompany.com"
- subject: "Build failure!."
- body: "Unable to pull source repository from Git server."
+ username: "{{ sendgrid_username }}"
+ password: "{{ sendgrid_password }}"
+ from_address: "build@mycompany.com"
+ to_addresses:
+ - "ops@mycompany.com"
+ - "devteam@mycompany.com"
+ subject: "Build failure!."
+ body: "Unable to pull source repository from Git server."
delegate_to: localhost
-'''
+"""
# =======================================
# sendgrid module support methods
diff --git a/plugins/modules/sensu_check.py b/plugins/modules/sensu_check.py
index 1430d6a6ce..2cac434923 100644
--- a/plugins/modules/sensu_check.py
+++ b/plugins/modules/sensu_check.py
@@ -9,15 +9,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: sensu_check
short_description: Manage Sensu checks
description:
- Manage the checks that should be run on a machine by I(Sensu).
- Most options do not have a default and will not be added to the check definition unless specified.
- - All defaults except O(path), O(state), O(backup) and O(metric) are not managed by this module,
- - they are simply specified for your convenience.
+ - All defaults except O(path), O(state), O(backup) and O(metric) are not managed by this module, they are simply specified
+ for your convenience.
+deprecated:
+ removed_in: 13.0.0
+ why: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
+ alternative: Use Sensu Go and its accompanying collection C(sensu.sensu_go).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -29,127 +32,126 @@ options:
name:
type: str
description:
- - The name of the check
- - This is the key that is used to determine whether a check exists
+ - The name of the check.
+ - This is the key that is used to determine whether a check exists.
required: true
state:
type: str
description:
- - Whether the check should be present or not
- choices: [ 'present', 'absent' ]
+ - Whether the check should be present or not.
+ choices: ['present', 'absent']
default: present
path:
type: str
description:
- - Path to the json file of the check to be added/removed.
+ - Path to the JSON file of the check to be added/removed.
- Will be created if it does not exist (unless O(state=absent)).
- - The parent folders need to exist when O(state=present), otherwise an error will be thrown
+ - The parent folders need to exist when O(state=present), otherwise an error will be thrown.
default: /etc/sensu/conf.d/checks.json
backup:
description:
- - Create a backup file (if yes), including the timestamp information so
- - you can get the original file back if you somehow clobbered it incorrectly.
+ - Create a backup file (if yes), including the timestamp information so you can get the original file back if you somehow
+ clobbered it incorrectly.
type: bool
default: false
command:
type: str
description:
- - Path to the sensu check to run (not required when O(state=absent))
+ - Path to the sensu check to run (not required when O(state=absent)).
handlers:
type: list
elements: str
description:
- - List of handlers to notify when the check fails
+ - List of handlers to notify when the check fails.
subscribers:
type: list
elements: str
description:
- - List of subscribers/channels this check should run for
- - See sensu_subscribers to subscribe a machine to a channel
+ - List of subscribers/channels this check should run for.
+ - See sensu_subscribers to subscribe a machine to a channel.
interval:
type: int
description:
- - Check interval in seconds
+ - Check interval in seconds.
timeout:
type: int
description:
- - Timeout for the check
+ - Timeout for the check.
- If not specified, it defaults to 10.
ttl:
type: int
description:
- - Time to live in seconds until the check is considered stale
+ - Time to live in seconds until the check is considered stale.
handle:
description:
- - Whether the check should be handled or not
+ - Whether the check should be handled or not.
- Default is V(false).
type: bool
subdue_begin:
type: str
description:
- - When to disable handling of check failures
+ - When to disable handling of check failures.
subdue_end:
type: str
description:
- - When to enable handling of check failures
+ - When to enable handling of check failures.
dependencies:
type: list
elements: str
description:
- - Other checks this check depends on, if dependencies fail handling of this check will be disabled
+ - Other checks this check depends on, if dependencies fail handling of this check will be disabled.
metric:
description:
- - Whether the check is a metric
+ - Whether the check is a metric.
type: bool
default: false
standalone:
description:
- - Whether the check should be scheduled by the sensu client or server
- - This option obviates the need for specifying the O(subscribers) option
+ - Whether the check should be scheduled by the sensu client or server.
+ - This option obviates the need for specifying the O(subscribers) option.
- Default is V(false).
type: bool
publish:
description:
- Whether the check should be scheduled at all.
- - You can still issue it via the sensu api
+ - You can still issue it using the sensu API.
- Default is V(false).
type: bool
occurrences:
type: int
description:
- - Number of event occurrences before the handler should take action
+ - Number of event occurrences before the handler should take action.
- If not specified, defaults to 1.
refresh:
type: int
description:
- - Number of seconds handlers should wait before taking second action
+ - Number of seconds handlers should wait before taking second action.
aggregate:
description:
- - Classifies the check as an aggregate check,
- - making it available via the aggregate API
+ - Classifies the check as an aggregate check, making it available using the aggregate API.
- Default is V(false).
type: bool
low_flap_threshold:
type: int
description:
- - The low threshold for flap detection
+ - The low threshold for flap detection.
high_flap_threshold:
type: int
description:
- - The high threshold for flap detection
+ - The high threshold for flap detection.
custom:
type: dict
description:
- A hash/dictionary of custom parameters for mixing to the configuration.
- - You can't rewrite others module parameters using this
+ - You cannot rewrite other module parameters using this.
source:
type: str
description:
- - The check source, used to create a JIT Sensu client for an external resource (e.g. a network switch).
+ - The check source, used to create a JIT Sensu client for an external resource (for example a network switch).
author: "Anders Ingemann (@andsens)"
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Fetch metrics about the CPU load every 60 seconds,
# the sensu server has a handler called 'relay' which forwards stats to graphite
- name: Get cpu metrics
@@ -177,7 +179,7 @@ EXAMPLES = '''
community.general.sensu_check:
name: check_disk_capacity
state: absent
-'''
+"""
import json
import traceback
diff --git a/plugins/modules/sensu_client.py b/plugins/modules/sensu_client.py
index eca0804b0a..955a25f44f 100644
--- a/plugins/modules/sensu_client.py
+++ b/plugins/modules/sensu_client.py
@@ -8,14 +8,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: sensu_client
author: "David Moreau Simard (@dmsimard)"
short_description: Manages Sensu client configuration
description:
- Manages Sensu client configuration.
- - 'For more information, refer to the Sensu documentation: U(https://sensuapp.org/docs/latest/reference/clients.html)'
+ - 'For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/clients.html).'
+deprecated:
+ removed_in: 13.0.0
+ why: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
+ alternative: Use Sensu Go and its accompanying collection C(sensu.sensu_go).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -27,8 +30,8 @@ options:
state:
type: str
description:
- - Whether the client should be present or not
- choices: [ 'present', 'absent' ]
+ - Whether the client should be present or not.
+ choices: ['present', 'absent']
default: present
name:
type: str
@@ -39,17 +42,19 @@ options:
type: str
description:
- An address to help identify and reach the client. This is only informational, usually an IP address or hostname.
- - If not specified it defaults to non-loopback IPv4 address as determined by Ruby Socket.ip_address_list (provided by Sensu).
+ - If not specified it defaults to non-loopback IPv4 address as determined by Ruby C(Socket.ip_address_list) (provided by
+ Sensu).
subscriptions:
type: list
elements: str
description:
- - An array of client subscriptions, a list of roles and/or responsibilities assigned to the system (e.g. webserver).
+ - An array of client subscriptions, a list of roles and/or responsibilities assigned to the system (for example V(webserver)).
- These subscriptions determine which monitoring checks are executed by the client, as check requests are sent to subscriptions.
- The subscriptions array items must be strings.
safe_mode:
description:
- - If safe mode is enabled for the client. Safe mode requires local check definitions in order to accept a check request and execute the check.
+ - If safe mode is enabled for the client. Safe mode requires local check definitions in order to accept a check request
+ and execute the check.
type: bool
default: false
redact:
@@ -69,7 +74,8 @@ options:
keepalive:
type: dict
description:
- - The keepalive definition scope, used to configure Sensu client keepalives behavior (e.g. keepalive thresholds, etc).
+ - The keepalive definition scope, used to configure Sensu client keepalives behavior (for example keepalive thresholds
+ and so).
registration:
type: dict
description:
@@ -98,12 +104,11 @@ options:
servicenow:
type: dict
description:
- - The servicenow definition scope, used to configure the Sensu Enterprise ServiceNow integration (Sensu Enterprise users only).
-notes:
- - Check mode is supported
-'''
+ - The servicenow definition scope, used to configure the Sensu Enterprise ServiceNow integration (Sensu Enterprise users
+ only).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Minimum possible configuration
- name: Configure Sensu client
community.general.sensu_client:
@@ -146,20 +151,20 @@ EXAMPLES = '''
- name: Delete the Sensu client configuration
community.general.sensu_client:
state: "absent"
-'''
+"""
-RETURN = '''
+RETURN = r"""
config:
- description: Effective client configuration, when state is present
+ description: Effective client configuration, when state is present.
returned: success
type: dict
sample: {'name': 'client', 'subscriptions': ['default']}
file:
- description: Path to the client configuration file
+ description: Path to the client configuration file.
returned: success
type: str
sample: "/etc/sensu/conf.d/client.json"
-'''
+"""
import json
import os
@@ -211,7 +216,7 @@ def main():
module.fail_json(
msg=msg.format(path=path, exception=str(e)))
else:
- # Idempotency: it's okay if the file doesn't exist
+ # Idempotency: it is okay if the file doesn't exist
msg = '{path} already does not exist'.format(path=path)
module.exit_json(msg=msg)
@@ -230,7 +235,7 @@ def main():
try:
current_config = json.load(open(path, 'r'))
except (IOError, ValueError):
- # File either doesn't exist or it's invalid JSON
+ # File either doesn't exist or it is invalid JSON
pass
if current_config is not None and current_config == config:
diff --git a/plugins/modules/sensu_handler.py b/plugins/modules/sensu_handler.py
index bbb8dc6129..ff4a77a6ff 100644
--- a/plugins/modules/sensu_handler.py
+++ b/plugins/modules/sensu_handler.py
@@ -8,14 +8,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: sensu_handler
author: "David Moreau Simard (@dmsimard)"
short_description: Manages Sensu handler configuration
description:
- - Manages Sensu handler configuration
- - 'For more information, refer to the Sensu documentation: U(https://sensuapp.org/docs/latest/reference/handlers.html)'
+ - Manages Sensu handler configuration.
+ - 'For more information, refer to the L(Sensu documentation, https://sensuapp.org/docs/latest/reference/handlers.html).'
+deprecated:
+ removed_in: 13.0.0
+ why: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
+ alternative: Use Sensu Go and its accompanying collection C(sensu.sensu_go).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -27,8 +30,8 @@ options:
state:
type: str
description:
- - Whether the handler should be present or not
- choices: [ 'present', 'absent' ]
+ - Whether the handler should be present or not.
+ choices: ['present', 'absent']
default: present
name:
type: str
@@ -38,8 +41,8 @@ options:
type:
type: str
description:
- - The handler type
- choices: [ 'pipe', 'tcp', 'udp', 'transport', 'set' ]
+ - The handler type.
+ choices: ['pipe', 'tcp', 'udp', 'transport', 'set']
filter:
type: str
description:
@@ -81,29 +84,28 @@ options:
type: str
description:
- The handler command to be executed.
- - The event data is passed to the process via STDIN.
- - 'NOTE: the command attribute is only required for Pipe handlers (i.e. handlers configured with "type": "pipe").'
+ - The event data is passed to the process using STDIN.
+ - 'NOTE: the O(command) attribute is only required for Pipe handlers (that is, handlers configured with O(type=pipe)).'
socket:
type: dict
description:
- The socket definition scope, used to configure the TCP/UDP handler socket.
- - 'NOTE: the socket attribute is only required for TCP/UDP handlers (i.e. handlers configured with "type": "tcp" or "type": "udp").'
+ - 'NOTE: the O(socket) attribute is only required for TCP/UDP handlers (that is, handlers configured with O(type=tcp)
+ or O(type=udp)).'
pipe:
type: dict
description:
- The pipe definition scope, used to configure the Sensu transport pipe.
- - 'NOTE: the pipe attribute is only required for Transport handlers (i.e. handlers configured with "type": "transport").'
+ - 'NOTE: the O(pipe) attribute is only required for Transport handlers (that is, handlers configured with O(type=transport)).'
handlers:
type: list
elements: str
description:
- An array of Sensu event handlers (names) to use for events using the handler set.
- - 'NOTE: the handlers attribute is only required for handler sets (i.e. handlers configured with "type": "set").'
-notes:
- - Check mode is supported
-'''
+ - 'NOTE: the O(handlers) attribute is only required for handler sets (that is, handlers configured with O(type=set)).'
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Configure a handler that sends event data as STDIN (pipe)
- name: Configure IRC Sensu handler
community.general.sensu_handler:
@@ -146,25 +148,25 @@ EXAMPLES = '''
owner: "sensu"
group: "sensu"
mode: "0600"
-'''
+"""
-RETURN = '''
+RETURN = r"""
config:
- description: Effective handler configuration, when state is present
+ description: Effective handler configuration, when state is present.
returned: success
type: dict
sample: {'name': 'irc', 'type': 'pipe', 'command': '/usr/local/bin/notify-irc.sh'}
file:
- description: Path to the handler configuration file
+ description: Path to the handler configuration file.
returned: success
type: str
sample: "/etc/sensu/conf.d/handlers/irc.json"
name:
- description: Name of the handler
+ description: Name of the handler.
returned: success
type: str
sample: "irc"
-'''
+"""
import json
import os
@@ -220,7 +222,7 @@ def main():
module.fail_json(
msg=msg.format(path=path, exception=str(e)))
else:
- # Idempotency: it's okay if the file doesn't exist
+ # Idempotency: it is okay if the file doesn't exist
msg = '{path} already does not exist'.format(path=path)
module.exit_json(msg=msg)
@@ -239,7 +241,7 @@ def main():
try:
current_config = json.load(open(path, 'r'))
except (IOError, ValueError):
- # File either doesn't exist or it's invalid JSON
+ # File either doesn't exist or it is invalid JSON
pass
if current_config is not None and current_config == config:
diff --git a/plugins/modules/sensu_silence.py b/plugins/modules/sensu_silence.py
index 25dfc239eb..a6d699f4c1 100644
--- a/plugins/modules/sensu_silence.py
+++ b/plugins/modules/sensu_silence.py
@@ -9,14 +9,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: sensu_silence
author: Steven Bambling (@smbambling)
short_description: Manage Sensu silence entries
description:
- - Create and clear (delete) a silence entries via the Sensu API
- for subscriptions and checks.
+ - Create and clear (delete) a silence entries using the Sensu API for subscriptions and checks.
+deprecated:
+ removed_in: 13.0.0
+ why: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
+ alternative: Use Sensu Go and its accompanying collection C(sensu.sensu_go).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -36,30 +38,27 @@ options:
expire:
type: int
description:
- - If specified, the silence entry will be automatically cleared
- after this number of seconds.
+ - If specified, the silence entry will be automatically cleared after this number of seconds.
expire_on_resolve:
description:
- - If specified as true, the silence entry will be automatically
- cleared once the condition it is silencing is resolved.
+ - If specified as true, the silence entry will be automatically cleared once the condition it is silencing is resolved.
type: bool
reason:
type: str
description:
- - If specified, this free-form string is used to provide context or
- rationale for the reason this silence entry was created.
+ - If specified, this free-form string is used to provide context or rationale for the reason this silence entry was
+ created.
state:
type: str
description:
- - Specifies to create or clear (delete) a silence entry via the Sensu API
+ - Specifies to create or clear (delete) a silence entry using the Sensu API.
default: present
choices: ['present', 'absent']
subscription:
type: str
description:
- Specifies the subscription which the silence entry applies to.
- - To create a silence entry for a client prepend C(client:) to client name.
- Example - C(client:server1.example.dev)
+ - To create a silence entry for a client prepend C(client:) to client name. Example - C(client:server1.example.dev).
required: true
url:
type: str
@@ -67,9 +66,9 @@ options:
- Specifies the URL of the Sensu monitoring host server.
required: false
default: http://127.0.01:4567
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Silence ALL checks for a given client
- name: Silence server1.example.dev
community.general.sensu_silence:
@@ -98,10 +97,10 @@ EXAMPLES = '''
reason: "{{ item.value.reason }}"
creator: "{{ ansible_user_id }}"
with_dict: "{{ silence }}"
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
import json
diff --git a/plugins/modules/sensu_subscription.py b/plugins/modules/sensu_subscription.py
index 0077e2ffa6..da5c50d42f 100644
--- a/plugins/modules/sensu_subscription.py
+++ b/plugins/modules/sensu_subscription.py
@@ -9,12 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: sensu_subscription
short_description: Manage Sensu subscriptions
description:
- - Manage which I(sensu channels) a machine should subscribe to
+ - Manage which I(sensu channels) a machine should subscribe to.
+deprecated:
+ removed_in: 13.0.0
+ why: Sensu Core and Sensu Enterprise products have been End of Life since 2019/20.
+ alternative: Use Sensu Go and its accompanying collection C(sensu.sensu_go).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -26,41 +29,41 @@ options:
name:
type: str
description:
- - The name of the channel
+ - The name of the channel.
required: true
state:
type: str
description:
- - Whether the machine should subscribe or unsubscribe from the channel
- choices: [ 'present', 'absent' ]
+ - Whether the machine should subscribe or unsubscribe from the channel.
+ choices: ['present', 'absent']
required: false
default: present
path:
type: str
description:
- - Path to the subscriptions json file
+ - Path to the subscriptions JSON file.
required: false
default: /etc/sensu/conf.d/subscriptions.json
backup:
description:
- - Create a backup file (if yes), including the timestamp information so you
- - can get the original file back if you somehow clobbered it incorrectly.
+ - Create a backup file (if yes), including the timestamp information so you can get the original file back if you somehow
+ clobbered it incorrectly.
type: bool
required: false
default: false
-requirements: [ ]
+requirements: []
author: Anders Ingemann (@andsens)
-'''
+"""
-RETURN = '''
+RETURN = r"""
reasons:
- description: the reasons why the module changed or did not change something
- returned: success
- type: list
- sample: ["channel subscription was absent and state is `present'"]
-'''
+ description: The reasons why the module changed or did not change something.
+ returned: success
+ type: list
+ sample: ["channel subscription was absent and state is `present'"]
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Subscribe to the nginx channel
- name: Subscribe to nginx checks
community.general.sensu_subscription: name=nginx
@@ -68,7 +71,7 @@ EXAMPLES = '''
# Unsubscribe from the common checks channel
- name: Unsubscribe from common checks
community.general.sensu_subscription: name=common state=absent
-'''
+"""
import json
import traceback
diff --git a/plugins/modules/seport.py b/plugins/modules/seport.py
index 964e8f0eda..24311fc56d 100644
--- a/plugins/modules/seport.py
+++ b/plugins/modules/seport.py
@@ -8,14 +8,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: seport
short_description: Manages SELinux network port type definitions
description:
- - Manages SELinux network port type definitions.
+ - Manages SELinux network port type definitions.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -34,7 +33,7 @@ options:
- Protocol for the specified port.
type: str
required: true
- choices: [ tcp, udp ]
+ choices: [tcp, udp]
setype:
description:
- SELinux type for the specified port.
@@ -44,7 +43,7 @@ options:
description:
- Desired boolean value.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
reload:
description:
@@ -53,26 +52,26 @@ options:
default: true
ignore_selinux_state:
description:
- - Run independent of selinux runtime state
+ - Run independent of selinux runtime state.
type: bool
default: false
local:
description:
- - Work with local modifications only.
+ - Work with local modifications only.
type: bool
default: false
version_added: 5.6.0
notes:
- - The changes are persistent across reboots.
- - Not tested on any debian based system.
+ - The changes are persistent across reboots.
+ - Not tested on any Debian based system.
requirements:
-- libselinux-python
-- policycoreutils-python
+ - libselinux-python
+ - policycoreutils-python
author:
-- Dan Keder (@dankeder)
-'''
+ - Dan Keder (@dankeder)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Allow Apache to listen on tcp port 8888
community.general.seport:
ports: 8888
@@ -110,7 +109,7 @@ EXAMPLES = r'''
setype: ssh_port_t
state: absent
local: true
-'''
+"""
import traceback
diff --git a/plugins/modules/serverless.py b/plugins/modules/serverless.py
index 8aa9396d62..937f7dcdea 100644
--- a/plugins/modules/serverless.py
+++ b/plugins/modules/serverless.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: serverless
short_description: Manages a Serverless Framework project
description:
@@ -26,11 +25,11 @@ options:
description:
- Goal state of given stage/project.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
serverless_bin_path:
description:
- - The path of a serverless framework binary relative to the 'service_path' eg. node_module/.bin/serverless
+ - The path of a serverless framework binary relative to the O(service_path), for example V(node_module/.bin/serverless).
type: path
service_path:
description:
@@ -67,16 +66,15 @@ options:
type: bool
default: false
notes:
- - Currently, the C(serverless) command must be in the path of the node executing the task.
- In the future this may be a flag.
+ - Currently, the C(serverless) command must be in the path of the node executing the task. In the future this may be a flag.
requirements:
-- serverless
-- yaml
+ - serverless
+ - PyYAML
author:
-- Ryan Scott Brown (@ryansb)
-'''
+ - Ryan Scott Brown (@ryansb)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Basic deploy of a service
community.general.serverless:
service_path: '{{ project_dir }}'
@@ -103,9 +101,9 @@ EXAMPLES = r'''
region: us-east-1
service_path: '{{ project_dir }}'
serverless_bin_path: node_modules/.bin/serverless
-'''
+"""
-RETURN = r'''
+RETURN = r"""
service_name:
type: str
description: The service name specified in the serverless.yml that was just deployed.
@@ -120,7 +118,7 @@ command:
description: Full C(serverless) command run by this module, in case you want to re-run the command outside the module.
returned: always
sample: serverless deploy --stage production
-'''
+"""
import os
diff --git a/plugins/modules/shutdown.py b/plugins/modules/shutdown.py
index d8108425eb..d6bd7ecc6b 100644
--- a/plugins/modules/shutdown.py
+++ b/plugins/modules/shutdown.py
@@ -8,14 +8,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
module: shutdown
short_description: Shut down a machine
notes:
- - E(PATH) is ignored on the remote node when searching for the C(shutdown) command. Use O(search_paths)
- to specify locations to search if the default paths do not work.
- - The O(msg) and O(delay) options are not supported when a shutdown command is not found in O(search_paths), instead
- the module will attempt to shutdown the system by calling C(systemctl shutdown).
+ - E(PATH) is ignored on the remote node when searching for the C(shutdown) command. Use O(search_paths) to specify locations
+ to search if the default paths do not work.
+ - The O(msg) and O(delay) options are not supported when a shutdown command is not found in O(search_paths), instead the
+ module attempts to shutdown the system by calling C(systemctl shutdown).
description:
- Shut downs a machine.
version_added: "1.1.0"
@@ -35,8 +35,8 @@ options:
delay:
description:
- Seconds to wait before shutdown. Passed as a parameter to the shutdown command.
- - On Linux, macOS and OpenBSD, this is converted to minutes and rounded down. If less than 60, it will be set to 0.
- - On Solaris and FreeBSD, this will be seconds.
+ - On Linux, macOS and OpenBSD, this is converted to minutes and rounded down. If less than 60, it is set to 0.
+ - On Solaris and FreeBSD, this represents seconds.
type: int
default: 0
msg:
@@ -47,20 +47,21 @@ options:
search_paths:
description:
- Paths to search on the remote machine for the C(shutdown) command.
- - I(Only) these paths will be searched for the C(shutdown) command. E(PATH) is ignored in the remote node when searching for the C(shutdown) command.
+ - I(Only) these paths are searched for the C(shutdown) command. E(PATH) is ignored in the remote node when searching
+ for the C(shutdown) command.
type: list
elements: path
default: ['/sbin', '/usr/sbin', '/usr/local/sbin']
seealso:
-- module: ansible.builtin.reboot
+ - module: ansible.builtin.reboot
author:
- - Matt Davis (@nitzmahone)
- - Sam Doran (@samdoran)
- - Amin Vakil (@aminvakil)
-'''
+ - Matt Davis (@nitzmahone)
+ - Sam Doran (@samdoran)
+ - Amin Vakil (@aminvakil)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Unconditionally shut down the machine with all defaults
community.general.shutdown:
@@ -71,13 +72,13 @@ EXAMPLES = r'''
- name: Shut down a machine with shutdown command in unusual place
community.general.shutdown:
search_paths:
- - '/lib/molly-guard'
-'''
+ - '/lib/molly-guard'
+"""
-RETURN = r'''
+RETURN = r"""
shutdown:
description: V(true) if the machine has been shut down.
returned: always
type: bool
sample: true
-'''
+"""
diff --git a/plugins/modules/simpleinit_msb.py b/plugins/modules/simpleinit_msb.py
index 92738471c2..f4b017a410 100644
--- a/plugins/modules/simpleinit_msb.py
+++ b/plugins/modules/simpleinit_msb.py
@@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: simpleinit_msb
short_description: Manage services on Source Mage GNU/Linux
version_added: 7.5.0
@@ -38,24 +37,21 @@ options:
state:
type: str
required: false
- choices: [ running, started, stopped, restarted, reloaded ]
+ choices: [running, started, stopped, restarted, reloaded]
description:
- - V(started)/V(stopped) are idempotent actions that will not run
- commands unless necessary. V(restarted) will always bounce the
- service. V(reloaded) will always reload.
+ - V(started)/V(stopped) are idempotent actions that do not run commands unless necessary. V(restarted) always bounces
+ the service. V(reloaded) always reloads.
- At least one of O(state) and O(enabled) are required.
- - Note that V(reloaded) will start the
- service if it is not already started, even if your chosen init
- system would not normally.
+ - Note that V(reloaded) starts the service if it is not already started, even if your chosen init system would not normally.
enabled:
type: bool
required: false
description:
- Whether the service should start on boot.
- At least one of O(state) and O(enabled) are required.
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Example action to start service httpd, if not running
community.general.simpleinit_msb:
name: httpd
@@ -80,7 +76,7 @@ EXAMPLES = '''
community.general.simpleinit_msb:
name: httpd
enabled: true
-'''
+"""
import os
import re
diff --git a/plugins/modules/sl_vm.py b/plugins/modules/sl_vm.py
index 1604ffc11f..c5a986843c 100644
--- a/plugins/modules/sl_vm.py
+++ b/plugins/modules/sl_vm.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: sl_vm
short_description: Create or cancel a virtual instance in SoftLayer
description:
@@ -25,7 +24,7 @@ attributes:
options:
instance_id:
description:
- - Instance Id of the virtual instance to perform action option.
+ - Instance ID of the virtual instance to perform action option.
type: str
hostname:
description:
@@ -121,7 +120,7 @@ options:
disks:
description:
- List of disk sizes to be assigned to new virtual instance.
- default: [ 25 ]
+ default: [25]
type: list
elements: int
os_code:
@@ -139,15 +138,15 @@ options:
type: int
public_vlan:
description:
- - VLAN by its Id to be assigned to the public NIC.
+ - VLAN by its ID to be assigned to the public NIC.
type: str
private_vlan:
description:
- - VLAN by its Id to be assigned to the private NIC.
+ - VLAN by its ID to be assigned to the private NIC.
type: str
ssh_keys:
description:
- - List of ssh keys by their Id to be assigned to a virtual instance.
+ - List of ssh keys by their ID to be assigned to a virtual instance.
type: list
elements: str
default: []
@@ -159,7 +158,7 @@ options:
description:
- Create, or cancel a virtual instance.
- Specify V(present) for create, V(absent) to cancel.
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
type: str
wait:
@@ -173,102 +172,102 @@ options:
default: 600
type: int
requirements:
- - softlayer >= 4.1.1
+ - softlayer >= 4.1.1
author:
-- Matt Colton (@mcltn)
-'''
+ - Matt Colton (@mcltn)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Build instance
hosts: localhost
gather_facts: false
tasks:
- - name: Build instance request
- community.general.sl_vm:
- hostname: instance-1
- domain: anydomain.com
- datacenter: dal09
- tags: ansible-module-test
- hourly: true
- private: false
- dedicated: false
- local_disk: true
- cpus: 1
- memory: 1024
- disks: [25]
- os_code: UBUNTU_LATEST
- wait: false
+ - name: Build instance request
+ community.general.sl_vm:
+ hostname: instance-1
+ domain: anydomain.com
+ datacenter: dal09
+ tags: ansible-module-test
+ hourly: true
+ private: false
+ dedicated: false
+ local_disk: true
+ cpus: 1
+ memory: 1024
+ disks: [25]
+ os_code: UBUNTU_LATEST
+ wait: false
- name: Build additional instances
hosts: localhost
gather_facts: false
tasks:
- - name: Build instances request
- community.general.sl_vm:
- hostname: "{{ item.hostname }}"
- domain: "{{ item.domain }}"
- datacenter: "{{ item.datacenter }}"
- tags: "{{ item.tags }}"
- hourly: "{{ item.hourly }}"
- private: "{{ item.private }}"
- dedicated: "{{ item.dedicated }}"
- local_disk: "{{ item.local_disk }}"
- cpus: "{{ item.cpus }}"
- memory: "{{ item.memory }}"
- disks: "{{ item.disks }}"
- os_code: "{{ item.os_code }}"
- ssh_keys: "{{ item.ssh_keys }}"
- wait: "{{ item.wait }}"
- with_items:
- - hostname: instance-2
- domain: anydomain.com
- datacenter: dal09
- tags:
- - ansible-module-test
- - ansible-module-test-replicas
- hourly: true
- private: false
- dedicated: false
- local_disk: true
- cpus: 1
- memory: 1024
- disks:
- - 25
- - 100
- os_code: UBUNTU_LATEST
- ssh_keys: []
- wait: true
- - hostname: instance-3
- domain: anydomain.com
- datacenter: dal09
- tags:
- - ansible-module-test
- - ansible-module-test-replicas
- hourly: true
- private: false
- dedicated: false
- local_disk: true
- cpus: 1
- memory: 1024
- disks:
- - 25
- - 100
- os_code: UBUNTU_LATEST
- ssh_keys: []
- wait: true
+ - name: Build instances request
+ community.general.sl_vm:
+ hostname: "{{ item.hostname }}"
+ domain: "{{ item.domain }}"
+ datacenter: "{{ item.datacenter }}"
+ tags: "{{ item.tags }}"
+ hourly: "{{ item.hourly }}"
+ private: "{{ item.private }}"
+ dedicated: "{{ item.dedicated }}"
+ local_disk: "{{ item.local_disk }}"
+ cpus: "{{ item.cpus }}"
+ memory: "{{ item.memory }}"
+ disks: "{{ item.disks }}"
+ os_code: "{{ item.os_code }}"
+ ssh_keys: "{{ item.ssh_keys }}"
+ wait: "{{ item.wait }}"
+ with_items:
+ - hostname: instance-2
+ domain: anydomain.com
+ datacenter: dal09
+ tags:
+ - ansible-module-test
+ - ansible-module-test-replicas
+ hourly: true
+ private: false
+ dedicated: false
+ local_disk: true
+ cpus: 1
+ memory: 1024
+ disks:
+ - 25
+ - 100
+ os_code: UBUNTU_LATEST
+ ssh_keys: []
+ wait: true
+ - hostname: instance-3
+ domain: anydomain.com
+ datacenter: dal09
+ tags:
+ - ansible-module-test
+ - ansible-module-test-replicas
+ hourly: true
+ private: false
+ dedicated: false
+ local_disk: true
+ cpus: 1
+ memory: 1024
+ disks:
+ - 25
+ - 100
+ os_code: UBUNTU_LATEST
+ ssh_keys: []
+ wait: true
- name: Cancel instances
hosts: localhost
gather_facts: false
tasks:
- - name: Cancel by tag
- community.general.sl_vm:
- state: absent
- tags: ansible-module-test
-'''
+ - name: Cancel by tag
+ community.general.sl_vm:
+ state: absent
+ tags: ansible-module-test
+"""
# TODO: Disabled RETURN as it is breaking the build for docs. Needs to be fixed.
-RETURN = '''# '''
+RETURN = """# """
import json
import time
diff --git a/plugins/modules/slack.py b/plugins/modules/slack.py
index 41dd4f5dba..61ccfbfc9e 100644
--- a/plugins/modules/slack.py
+++ b/plugins/modules/slack.py
@@ -15,11 +15,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = """
+DOCUMENTATION = r"""
module: slack
short_description: Send Slack notifications
description:
- - The M(community.general.slack) module sends notifications to U(http://slack.com) via the Incoming WebHook integration
+ - The M(community.general.slack) module sends notifications to U(http://slack.com) using the Incoming WebHook integration.
author: "Ramon de la Fuente (@ramondelafuente)"
extends_documentation_fragment:
- community.general.attributes
@@ -32,51 +32,45 @@ options:
domain:
type: str
description:
- - Slack (sub)domain for your environment without protocol. (For example
- V(example.slack.com).) In Ansible 1.8 and beyond, this is deprecated and may
- be ignored. See token documentation for information.
+ - Slack (sub)domain for your environment without protocol. (For example V(example.slack.com).) In Ansible 1.8 and beyond,
+ this is deprecated and may be ignored. See token documentation for information.
token:
type: str
description:
- - Slack integration token. This authenticates you to the slack service.
- Make sure to use the correct type of token, depending on what method you use.
- - "Webhook token:
- Prior to Ansible 1.8, a token looked like V(3Ffe373sfhRE6y42Fg3rvf4GlK). In
- Ansible 1.8 and above, Ansible adapts to the new slack API where tokens look
- like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens
- are in the new format then slack will ignore any value of domain. If
- the token is in the old format the domain is required. Ansible has no
- control of when slack will get rid of the old API. When slack does
- that the old format will stop working. ** Please keep in mind the tokens
- are not the API tokens but are the webhook tokens. In slack these are
- found in the webhook URL which are obtained under the apps and integrations.
- The incoming webhooks can be added in that area. In some cases this may
- be locked by your Slack admin and you must request access. It is there
- that the incoming webhooks can be added. The key is on the end of the
- URL given to you in that section."
- - "WebAPI token:
- Slack WebAPI requires a personal, bot or work application token. These tokens start with V(xoxp-), V(xoxb-)
- or V(xoxa-), for example V(xoxb-1234-56789abcdefghijklmnop). WebAPI token is required if you intend to receive thread_id.
- See Slack's documentation (U(https://api.slack.com/docs/token-types)) for more information."
+ - Slack integration token. This authenticates you to the slack service. Make sure to use the correct type of token,
+ depending on what method you use.
+ - 'Webhook token: Prior to Ansible 1.8, a token looked like V(3Ffe373sfhRE6y42Fg3rvf4GlK). In Ansible 1.8 and above,
+ Ansible adapts to the new slack API where tokens look like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens
+ are in the new format then slack will ignore any value of domain. If the token is in the old format the domain is
+ required. Ansible has no control of when slack will get rid of the old API. When slack does that the old format will
+ stop working. ** Please keep in mind the tokens are not the API tokens but are the webhook tokens. In slack these
+ are found in the webhook URL which are obtained under the apps and integrations. The incoming webhooks can be added
+ in that area. In some cases this may be locked by your Slack admin and you must request access. It is there that the
+ incoming webhooks can be added. The key is on the end of the URL given to you in that section.'
+ - "WebAPI token: Slack WebAPI requires a personal, bot or work application token. These tokens start with V(xoxp-),
+ V(xoxb-) or V(xoxa-), for example V(xoxb-1234-56789abcdefghijklmnop). WebAPI token is required if you intend to receive
+ thread_id. See Slack's documentation (U(https://api.slack.com/docs/token-types)) for more information."
required: true
msg:
type: str
description:
- - Message to send. Note that the module does not handle escaping characters.
- Plain-text angle brackets and ampersands should be converted to HTML entities (e.g. & to &) before sending.
- See Slack's documentation (U(https://api.slack.com/docs/message-formatting)) for more.
+ - Message to send. Note that the module does not handle escaping characters. Plain-text angle brackets and ampersands
+ should be converted to HTML entities (for example C(&) to C(&)) before sending. See Slack's documentation
+ (U(https://api.slack.com/docs/message-formatting)) for more.
channel:
type: str
description:
- Channel to send the message to. If absent, the message goes to the channel selected for the O(token).
thread_id:
description:
- - Optional. Timestamp of parent message to thread this message. https://api.slack.com/docs/message-threading
+ - Optional. Timestamp of parent message to thread this message, see U(https://api.slack.com/docs/message-threading).
type: str
message_id:
description:
- Optional. Message ID to edit, instead of posting a new message.
- - If supplied O(channel) must be in form of C(C0xxxxxxx). use C({{ slack_response.channel_id }}) to get RV(ignore:channel_id) from previous task run.
+ - If supplied O(channel) must be in form of C(C0xxxxxxx). use C({{ slack_response.channel }}) to get RV(ignore:channel)
+ from previous task run.
+ - The token needs history scope to get information on the message to edit (C(channels:history,groups:history,mpim:history,im:history)).
- Corresponds to C(ts) in the Slack API (U(https://api.slack.com/messaging/modifying)).
type: str
version_added: 1.2.0
@@ -106,21 +100,23 @@ options:
parse:
type: str
description:
- - Setting for the message parser at Slack
+ - Setting for the message parser at Slack.
choices:
- 'full'
- 'none'
validate_certs:
description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
type: bool
default: true
color:
type: str
description:
- - Allow text to use default colors - use the default of 'normal' to not send a custom color bar at the start of the message.
- - Allowed values for color can be one of 'normal', 'good', 'warning', 'danger', any valid 3 digit or 6 digit hex color value.
+ - Allow text to use default colors - use the default of V(normal) to not send a custom color bar at the start of the
+ message.
+ - Allowed values for color can be one of V(normal), V(good), V(warning), V(danger), any valid 3 digit or 6 digit hex
+ color value.
default: 'normal'
attachments:
type: list
@@ -139,20 +135,21 @@ options:
type: str
description:
- Setting for automatically prepending a V(#) symbol on the passed in O(channel).
- - The V(auto) method prepends a V(#) unless O(channel) starts with one of V(#), V(@), V(C0), V(GF), V(G0), V(CP).
- These prefixes only cover a small set of the prefixes that should not have a V(#) prepended.
- Since an exact condition which O(channel) values must not have the V(#) prefix is not known,
- the value V(auto) for this option will be deprecated in the future. It is best to explicitly set
- O(prepend_hash=always) or O(prepend_hash=never) to obtain the needed behavior.
+ - The V(auto) method prepends a V(#) unless O(channel) starts with one of V(#), V(@), V(C0), V(GF), V(G0), V(CP). These
+ prefixes only cover a small set of the prefixes that should not have a V(#) prepended. Since an exact condition which
+ O(channel) values must not have the V(#) prefix is not known, the value V(auto) for this option will be deprecated
+ in the future. It is best to explicitly set O(prepend_hash=always) or O(prepend_hash=never) to obtain the needed behavior.
+ - The B(current default) is V(auto), which has been B(deprecated) since community.general 10.2.0. It will change to
+ V(never) in community.general 12.0.0. To prevent deprecation warnings you can explicitly set O(prepend_hash) to the
+ value you want. We suggest to only use V(always) or V(never), but not V(auto), when explicitly setting a value.
choices:
- 'always'
- 'never'
- 'auto'
- default: 'auto'
version_added: 6.1.0
"""
-EXAMPLES = """
+EXAMPLES = r"""
- name: Send notification message via Slack
community.general.slack:
token: thetoken/generatedby/slack
@@ -171,7 +168,8 @@ EXAMPLES = """
parse: 'none'
delegate_to: localhost
-- name: Insert a color bar in front of the message for visibility purposes and use the default webhook icon and name configured in Slack
+- name: Insert a color bar in front of the message for visibility purposes and use the default webhook icon and name configured
+ in Slack
community.general.slack:
token: thetoken/generatedby/slack
msg: '{{ inventory_hostname }} is alive!'
@@ -214,14 +212,14 @@ EXAMPLES = """
Display my system load on host A and B
- type: context
elements:
- - type: mrkdwn
- text: |-
- *System A*
- load average: 0,74, 0,66, 0,63
- - type: mrkdwn
- text: |-
- *System B*
- load average: 5,16, 4,64, 2,43
+ - type: mrkdwn
+ text: |-
+ *System A*
+ load average: 0,74, 0,66, 0,63
+ - type: mrkdwn
+ text: |-
+ *System B*
+ load average: 5,16, 4,64, 2,43
- name: Send a message with a link using Slack markup
community.general.slack:
@@ -391,6 +389,8 @@ def get_slack_message(module, token, channel, ts):
if info['status'] != 200:
module.fail_json(msg="failed to get slack message")
data = module.from_json(response.read())
+ if data.get('ok') is False:
+ module.fail_json(msg="failed to get slack message: %s" % data)
if len(data['messages']) < 1:
module.fail_json(msg="no messages matching ts: %s" % ts)
if len(data['messages']) > 1:
@@ -454,7 +454,7 @@ def main():
attachments=dict(type='list', elements='dict'),
blocks=dict(type='list', elements='dict'),
message_id=dict(type='str'),
- prepend_hash=dict(type='str', default='auto', choices=['always', 'never', 'auto']),
+ prepend_hash=dict(type='str', choices=['always', 'never', 'auto']),
),
supports_check_mode=True,
)
@@ -475,6 +475,15 @@ def main():
message_id = module.params['message_id']
prepend_hash = module.params['prepend_hash']
+ if prepend_hash is None:
+ module.deprecate(
+ "The default value 'auto' for 'prepend_hash' is deprecated and will change to 'never' in community.general 12.0.0."
+ " You can explicitly set 'prepend_hash' in your task to avoid this deprecation warning",
+ version="12.0.0",
+ collection_name="community.general",
+ )
+ prepend_hash = 'auto'
+
color_choices = ['normal', 'good', 'warning', 'danger']
if color not in color_choices and not is_valid_hex_color(color):
module.fail_json(msg="Color value specified should be either one of %r "
diff --git a/plugins/modules/slackpkg.py b/plugins/modules/slackpkg.py
index 9347db1591..2ec91de051 100644
--- a/plugins/modules/slackpkg.py
+++ b/plugins/modules/slackpkg.py
@@ -15,49 +15,47 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: slackpkg
short_description: Package manager for Slackware >= 12.2
description:
- - Manage binary packages for Slackware using 'slackpkg' which
- is available in versions after 12.2.
+ - Manage binary packages for Slackware using C(slackpkg) which is available in versions after 12.2.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - name of package to install/remove
- required: true
- type: list
- elements: str
- aliases: [pkg]
+ name:
+ description:
+ - Name of package to install/remove.
+ required: true
+ type: list
+ elements: str
+ aliases: [pkg]
- state:
- description:
- - State of the package, you can use V(installed) as an alias for V(present) and V(removed) as one for V(absent).
- choices: [ 'present', 'absent', 'latest', 'installed', 'removed' ]
- required: false
- default: present
- type: str
+ state:
+ description:
+ - State of the package, you can use V(installed) as an alias for V(present) and V(removed) as one for V(absent).
+ choices: ['present', 'absent', 'latest', 'installed', 'removed']
+ required: false
+ default: present
+ type: str
- update_cache:
- description:
- - update the package database first
- required: false
- default: false
- type: bool
+ update_cache:
+ description:
+ - Update the package database first.
+ required: false
+ default: false
+ type: bool
author: Kim Nørgaard (@KimNorgaard)
-requirements: [ "Slackware >= 12.2" ]
-'''
+requirements: ["Slackware >= 12.2"]
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install package foo
community.general.slackpkg:
name: foo
@@ -72,7 +70,7 @@ EXAMPLES = '''
community.general.slackpkg:
name: foo
state: latest
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/smartos_image_info.py b/plugins/modules/smartos_image_info.py
index 1a25b46681..19ad740b72 100644
--- a/plugins/modules/smartos_image_info.py
+++ b/plugins/modules/smartos_image_info.py
@@ -9,31 +9,29 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: smartos_image_info
short_description: Get SmartOS image details
description:
- - Retrieve information about all installed images on SmartOS.
+ - Retrieve information about all installed images on SmartOS.
author: Adam Števko (@xen0l)
extends_documentation_fragment:
- - community.general.attributes
- - community.general.attributes.info_module
+ - community.general.attributes
+ - community.general.attributes.info_module
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- filters:
- description:
- - Criteria for selecting image. Can be any value from image
- manifest and C(published_date), C(published), C(source), C(clones),
- and C(size). More information can be found at U(https://smartos.org/man/1m/imgadm)
- under C(imgadm list).
- type: str
-'''
+ filters:
+ description:
+ - Criteria for selecting image. Can be any value from image manifest and V(published_date), V(published), V(source),
+ V(clones), and V(size).
+ - More information can be found at U(https://smartos.org/man/1m/imgadm) under C(imgadm list).
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Return information about all installed images
community.general.smartos_image_info:
register: result
@@ -49,19 +47,17 @@ EXAMPLES = '''
- name: Print information
ansible.builtin.debug:
- msg: "{{ result.smartos_images[item]['name'] }}-{{ result.smartos_images[item]['version'] }}
- has {{ result.smartos_images[item]['clones'] }} VM(s)"
+ msg: "{{ result.smartos_images[item]['name'] }}-{{ result.smartos_images[item]['version'] }} has {{ result.smartos_images[item]['clones'] }} VM(s)"
with_items: "{{ result.smartos_images.keys() | list }}"
- name: Print information
ansible.builtin.debug:
- msg: "{{ smartos_images[item]['name'] }}-{{ smartos_images[item]['version'] }}
- has {{ smartos_images[item]['clones'] }} VM(s)"
+ msg: "{{ smartos_images[item]['name'] }}-{{ smartos_images[item]['version'] }} has {{ smartos_images[item]['clones'] }} VM(s)"
with_items: "{{ smartos_images.keys() | list }}"
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
import json
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/snap.py b/plugins/modules/snap.py
index 15637f3315..29fd08394f 100644
--- a/plugins/modules/snap.py
+++ b/plugins/modules/snap.py
@@ -13,96 +13,88 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: snap
short_description: Manages snaps
description:
- - Manages snaps packages.
+ - Manages snaps packages.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of the snaps to be installed.
- - Any named snap accepted by the C(snap) command is valid.
- - >
- O(dangerous=true) may be necessary when installing `.snap` files. See O(dangerous) for more details.
- required: true
- type: list
- elements: str
- state:
- description:
- - Desired state of the package.
- - >
- When O(state=present) the module will use C(snap install) if the snap is not installed,
- and C(snap refresh) if it is installed but from a different channel.
- default: present
- choices: [ absent, present, enabled, disabled ]
- type: str
- classic:
- description:
- - Install a snap that has classic confinement.
- - This option corresponds to the C(--classic) argument of the C(snap install) command.
- - This level of confinement is permissive, granting full system access,
- similar to that of traditionally packaged applications that do not use sandboxing mechanisms.
- This option can only be specified when the task involves a single snap.
- - See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels.
-
- type: bool
- required: false
- default: false
- channel:
- description:
- - Define which release of a snap is installed and tracked for updates.
- This option can only be specified if there is a single snap in the task.
- - If not passed, the C(snap) command will default to V(stable).
- - If the value passed does not contain the C(track), it will default to C(latest).
- For example, if V(edge) is passed, the module will assume the channel to be V(latest/edge).
- - See U(https://snapcraft.io/docs/channels) for more details about snap channels.
- type: str
- required: false
- options:
- description:
- - Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied
- to that snap only. If the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will
- only be applied to active snaps.
- - Options will only be applied when C(state) is set to V(present).
- This is done after the necessary installation
- or refresh (upgrade/downgrade) of all the snaps listed in O(name).
- - See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options.
-
- required: false
- type: list
- elements: str
- version_added: 4.4.0
- dangerous:
- description:
- - Install the snap in dangerous mode, without validating its assertions and signatures.
- - This is useful when installing local snaps that are either unsigned or have signatures that have not been acknowledged.
- - See U(https://snapcraft.io/docs/install-modes) for more details about installation modes.
- type: bool
- required: false
- default: false
- version_added: 7.2.0
+ name:
+ description:
+ - Name of the snaps to be installed.
+ - Any named snap accepted by the C(snap) command is valid.
+ - O(dangerous=true) may be necessary when installing C(.snap) files. See O(dangerous) for more details.
+ required: true
+ type: list
+ elements: str
+ state:
+ description:
+ - Desired state of the package.
+ - When O(state=present) the module will use C(snap install) if the snap is not installed, and C(snap refresh) if it
+ is installed but from a different channel.
+ default: present
+ choices: [absent, present, enabled, disabled]
+ type: str
+ classic:
+ description:
+ - Install a snap that has classic confinement.
+ - This option corresponds to the C(--classic) argument of the C(snap install) command.
+ - This level of confinement is permissive, granting full system access, similar to that of traditionally packaged applications
+ that do not use sandboxing mechanisms. This option can only be specified when the task involves a single snap.
+ - See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels.
+ type: bool
+ required: false
+ default: false
+ channel:
+ description:
+ - Define which release of a snap is installed and tracked for updates. This option can only be specified if there is
+ a single snap in the task.
+ - If not passed, the C(snap) command will default to V(stable).
+ - If the value passed does not contain the C(track), it will default to C(latest). For example, if V(edge) is passed,
+ the module will assume the channel to be V(latest/edge).
+ - See U(https://snapcraft.io/docs/channels) for more details about snap channels.
+ type: str
+ required: false
+ options:
+ description:
+ - Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied to
+ that snap only. If the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will
+ only be applied to active snaps.
+ - Options will only be applied when C(state) is set to V(present). This is done after the necessary installation or
+ refresh (upgrade/downgrade) of all the snaps listed in O(name).
+ - See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options.
+ required: false
+ type: list
+ elements: str
+ version_added: 4.4.0
+ dangerous:
+ description:
+ - Install the snap in dangerous mode, without validating its assertions and signatures.
+ - This is useful when installing local snaps that are either unsigned or have signatures that have not been acknowledged.
+ - See U(https://snapcraft.io/docs/install-modes) for more details about installation modes.
+ type: bool
+ required: false
+ default: false
+ version_added: 7.2.0
notes:
- - Privileged operations, such as installing and configuring snaps, require root priviledges.
- This is only the case if the user has not logged in to the Snap Store.
-
+ - Privileged operations, such as installing and configuring snaps, require root priviledges. This is only the case if the
+ user has not logged in to the Snap Store.
author:
- - Victor Carceler (@vcarceler)
- - Stanislas Lange (@angristan)
+ - Victor Carceler (@vcarceler)
+ - Stanislas Lange (@angristan)
seealso:
- - module: community.general.snap_alias
-'''
+ - module: community.general.snap_alias
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Install "foo" and "bar" snap
- name: Install foo
community.general.snap:
@@ -147,35 +139,40 @@ EXAMPLES = '''
community.general.snap:
name: foo
channel: latest/edge
-'''
+"""
-RETURN = '''
+RETURN = r"""
classic:
- description: Whether or not the snaps were installed with the classic confinement
- type: bool
- returned: When snaps are installed
+ description: Whether or not the snaps were installed with the classic confinement.
+ type: bool
+ returned: When snaps are installed
channel:
- description: The channel the snaps were installed from
- type: str
- returned: When snaps are installed
+ description: The channel the snaps were installed from.
+ type: str
+ returned: When snaps are installed
cmd:
- description: The command that was executed on the host
- type: str
- returned: When changed is true
+ description: The command that was executed on the host.
+ type: str
+ returned: When changed is true
snaps_installed:
- description: The list of actually installed snaps
- type: list
- returned: When any snaps have been installed
+ description: The list of actually installed snaps.
+ type: list
+ returned: When any snaps have been installed
snaps_removed:
- description: The list of actually removed snaps
- type: list
- returned: When any snaps have been removed
+ description: The list of actually removed snaps.
+ type: list
+ returned: When any snaps have been removed
options_changed:
- description: The list of options set/changed in format C(snap:key=value).
- type: list
- returned: When any options have been changed/set
- version_added: 4.4.0
-'''
+ description: The list of options set/changed in format C(snap:key=value).
+ type: list
+ returned: When any options have been changed/set
+ version_added: 4.4.0
+version:
+ description: Versions of snap components as reported by C(snap version).
+ type: dict
+ returned: always
+ version_added: 10.3.0
+"""
import re
import json
@@ -184,7 +181,7 @@ import numbers
from ansible.module_utils.common.text.converters import to_native
from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper
-from ansible_collections.community.general.plugins.module_utils.snap import snap_runner
+from ansible_collections.community.general.plugins.module_utils.snap import snap_runner, get_version
class Snap(StateModuleHelper):
@@ -218,6 +215,7 @@ class Snap(StateModuleHelper):
def __init_module__(self):
self.runner = snap_runner(self.module)
+ self.vars.version = get_version(self.runner)
# if state=present there might be file names passed in 'name', in
# which case they must be converted to their actual snap names, which
# is done using the names_from_snaps() method calling 'snap info'.
diff --git a/plugins/modules/snap_alias.py b/plugins/modules/snap_alias.py
index ba54a9e155..b7244ed74d 100644
--- a/plugins/modules/snap_alias.py
+++ b/plugins/modules/snap_alias.py
@@ -9,46 +9,45 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: snap_alias
short_description: Manages snap aliases
version_added: 4.0.0
description:
- - "Manages snaps aliases."
+ - Manages snaps aliases.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: full
+ check_mode:
+ support: full
+ diff_mode:
+ support: full
options:
- state:
- description:
- - Desired state of the alias.
- type: str
- choices: [ absent, present ]
- default: present
- name:
- description:
- - Name of the snap.
- type: str
- alias:
- description:
- - Aliases to be created or removed.
- type: list
- elements: str
- aliases: [aliases]
+ state:
+ description:
+ - Desired state of the alias.
+ type: str
+ choices: [absent, present]
+ default: present
+ name:
+ description:
+ - Name of the snap.
+ type: str
+ alias:
+ description:
+ - Aliases to be created or removed.
+ type: list
+ elements: str
+ aliases: [aliases]
author:
- - Alexei Znamensky (@russoz)
+ - Alexei Znamensky (@russoz)
seealso:
- - module: community.general.snap
-'''
+ - module: community.general.snap
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
# Install "foo" and "bar" snap
- name: Create snap alias
community.general.snap_alias:
@@ -62,7 +61,7 @@ EXAMPLES = '''
- hw
- hw2
- hw3
- state: present # optional
+ state: present # optional
- name: Remove one specific aliases
community.general.snap_alias:
@@ -73,21 +72,26 @@ EXAMPLES = '''
community.general.snap_alias:
name: hello-world
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
snap_aliases:
- description: The snap aliases after execution. If called in check mode, then the list represents the state before execution.
- type: list
- elements: str
- returned: always
-'''
+ description: The snap aliases after execution. If called in check mode, then the list represents the state before execution.
+ type: list
+ elements: str
+ returned: always
+version:
+ description: Versions of snap components as reported by C(snap version).
+ type: dict
+ returned: always
+ version_added: 10.3.0
+"""
import re
from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper
-from ansible_collections.community.general.plugins.module_utils.snap import snap_runner
+from ansible_collections.community.general.plugins.module_utils.snap import snap_runner, get_version
class SnapAlias(StateModuleHelper):
@@ -113,6 +117,7 @@ class SnapAlias(StateModuleHelper):
def __init_module__(self):
self.runner = snap_runner(self.module)
+ self.vars.version = get_version(self.runner)
self.vars.set("snap_aliases", self._aliases(), change=True, diff=True)
def __quit_module__(self):
diff --git a/plugins/modules/snmp_facts.py b/plugins/modules/snmp_facts.py
index d561f93f02..74aca27c40 100644
--- a/plugins/modules/snmp_facts.py
+++ b/plugins/modules/snmp_facts.py
@@ -9,87 +9,85 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: snmp_facts
author:
-- Patrick Ogenstad (@ogenstad)
+ - Patrick Ogenstad (@ogenstad)
short_description: Retrieve facts for a device using SNMP
description:
- - Retrieve facts for a device using SNMP, the facts will be
- inserted to the ansible_facts key.
+ - Retrieve facts for a device using SNMP, the facts will be inserted to the C(ansible_facts) key.
requirements:
- - pysnmp
+ - pysnmp
extends_documentation_fragment:
- - community.general.attributes
- - community.general.attributes.facts
- - community.general.attributes.facts_module
+ - community.general.attributes
+ - community.general.attributes.facts
+ - community.general.attributes.facts_module
attributes:
- check_mode:
- version_added: 3.3.0
- # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
+ check_mode:
+ version_added: 3.3.0
+ # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
- host:
- description:
- - Set to target SNMP server (normally C({{ inventory_hostname }})).
- type: str
- required: true
- version:
- description:
- - SNMP Version to use, V(v2), V(v2c) or V(v3).
- type: str
- required: true
- choices: [ v2, v2c, v3 ]
- community:
- description:
- - The SNMP community string, required if O(version) is V(v2) or V(v2c).
- type: str
- level:
- description:
- - Authentication level.
- - Required if O(version=v3).
- type: str
- choices: [ authNoPriv, authPriv ]
- username:
- description:
- - Username for SNMPv3.
- - Required if O(version=v3).
- type: str
- integrity:
- description:
- - Hashing algorithm.
- - Required if O(version=v3).
- type: str
- choices: [ md5, sha ]
- authkey:
- description:
- - Authentication key.
- - Required O(version=v3).
- type: str
- privacy:
- description:
- - Encryption algorithm.
- - Required if O(level=authPriv).
- type: str
- choices: [ aes, des ]
- privkey:
- description:
- - Encryption key.
- - Required if O(level=authPriv).
- type: str
- timeout:
- description:
- - Response timeout in seconds.
- type: int
- version_added: 2.3.0
- retries:
- description:
- - Maximum number of request retries, 0 retries means just a single request.
- type: int
- version_added: 2.3.0
-'''
+ host:
+ description:
+ - Set to target SNMP server (normally C({{ inventory_hostname }})).
+ type: str
+ required: true
+ version:
+ description:
+ - SNMP Version to use, V(v2), V(v2c) or V(v3).
+ type: str
+ required: true
+ choices: [v2, v2c, v3]
+ community:
+ description:
+ - The SNMP community string, required if O(version) is V(v2) or V(v2c).
+ type: str
+ level:
+ description:
+ - Authentication level.
+ - Required if O(version=v3).
+ type: str
+ choices: [authNoPriv, authPriv]
+ username:
+ description:
+ - Username for SNMPv3.
+ - Required if O(version=v3).
+ type: str
+ integrity:
+ description:
+ - Hashing algorithm.
+ - Required if O(version=v3).
+ type: str
+ choices: [md5, sha]
+ authkey:
+ description:
+ - Authentication key.
+ - Required O(version=v3).
+ type: str
+ privacy:
+ description:
+ - Encryption algorithm.
+ - Required if O(level=authPriv).
+ type: str
+ choices: [aes, des]
+ privkey:
+ description:
+ - Encryption key.
+ - Required if O(level=authPriv).
+ type: str
+ timeout:
+ description:
+ - Response timeout in seconds.
+ type: int
+ version_added: 2.3.0
+ retries:
+ description:
+ - Maximum number of request retries, 0 retries means just a single request.
+ type: int
+ version_added: 2.3.0
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Gather facts with SNMP version 2
community.general.snmp_facts:
host: '{{ inventory_hostname }}'
@@ -108,9 +106,9 @@ EXAMPLES = r'''
authkey: abc12345
privkey: def6789
delegate_to: localhost
-'''
+"""
-RETURN = r'''
+RETURN = r"""
ansible_sysdescr:
description: A textual description of the entity.
returned: success
@@ -127,7 +125,8 @@ ansible_sysuptime:
type: int
sample: 42388
ansible_syscontact:
- description: The textual identification of the contact person for this managed node, together with information on how to contact this person.
+ description: The textual identification of the contact person for this managed node, together with information on how to
+ contact this person.
returned: success
type: str
sample: Me
@@ -152,39 +151,39 @@ ansible_interfaces:
type: dict
sample: {
"1": {
- "adminstatus": "up",
- "description": "",
- "ifindex": "1",
- "ipv4": [
- {
- "address": "127.0.0.1",
- "netmask": "255.0.0.0"
- }
- ],
- "mac": "",
- "mtu": "65536",
- "name": "lo",
- "operstatus": "up",
- "speed": "65536"
+ "adminstatus": "up",
+ "description": "",
+ "ifindex": "1",
+ "ipv4": [
+ {
+ "address": "127.0.0.1",
+ "netmask": "255.0.0.0"
+ }
+ ],
+ "mac": "",
+ "mtu": "65536",
+ "name": "lo",
+ "operstatus": "up",
+ "speed": "65536"
},
"2": {
- "adminstatus": "up",
- "description": "",
- "ifindex": "2",
- "ipv4": [
- {
- "address": "192.168.213.128",
- "netmask": "255.255.255.0"
- }
- ],
- "mac": "000a305a52a1",
- "mtu": "1500",
- "name": "Intel Corporation 82545EM Gigabit Ethernet Controller (Copper)",
- "operstatus": "up",
- "speed": "1500"
+ "adminstatus": "up",
+ "description": "",
+ "ifindex": "2",
+ "ipv4": [
+ {
+ "address": "192.168.213.128",
+ "netmask": "255.255.255.0"
+ }
+ ],
+ "mac": "000a305a52a1",
+ "mtu": "1500",
+ "name": "Intel Corporation 82545EM Gigabit Ethernet Controller (Copper)",
+ "operstatus": "up",
+ "speed": "1500"
}
}
-'''
+"""
import binascii
from collections import defaultdict
diff --git a/plugins/modules/solaris_zone.py b/plugins/modules/solaris_zone.py
index d9f44589dc..31e7919c08 100644
--- a/plugins/modules/solaris_zone.py
+++ b/plugins/modules/solaris_zone.py
@@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: solaris_zone
short_description: Manage Solaris zones
description:
@@ -31,16 +30,15 @@ options:
description:
- V(present), configure and install the zone.
- V(installed), synonym for V(present).
- - V(running), if the zone already exists, boot it, otherwise, configure and install
- the zone first, then boot it.
+ - V(running), if the zone already exists, boot it, otherwise, configure and install the zone first, then boot it.
- V(started), synonym for V(running).
- V(stopped), shutdown a zone.
- V(absent), destroy the zone.
- - V(configured), configure the ready so that it's to be attached.
+ - V(configured), configure the ready so that it is to be attached.
- V(attached), attach a zone, but do not boot it.
- - V(detached), shutdown and detach a zone
+ - V(detached), shutdown and detach a zone.
type: str
- choices: [ absent, attached, configured, detached, installed, present, running, started, stopped ]
+ choices: [absent, attached, configured, detached, installed, present, running, started, stopped]
default: present
name:
description:
@@ -53,8 +51,7 @@ options:
required: true
path:
description:
- - The path where the zone will be created. This is required when the zone is created, but not
- used otherwise.
+ - The path where the zone will be created. This is required when the zone is created, but not used otherwise.
type: str
sparse:
description:
@@ -63,32 +60,30 @@ options:
default: false
root_password:
description:
- - The password hash for the root account. If not specified, the zone's root account
- will not have a password.
+ - The password hash for the root account. If not specified, the zone's root account will not have a password.
type: str
config:
description:
- - 'The zonecfg configuration commands for this zone. See zonecfg(1M) for the valid options
- and syntax. Typically this is a list of options separated by semi-colons or new lines, e.g.
- "set auto-boot=true;add net;set physical=bge0;set address=10.1.1.1;end"'
+ - The C(zonecfg) configuration commands for this zone. See zonecfg(1M) for the valid options and syntax. Typically this
+ is a list of options separated by semi-colons or new lines, for example V(set auto-boot=true;add net;set physical=bge0;set
+ address=10.1.1.1;end).
type: str
default: ''
create_options:
description:
- - 'Extra options to the zonecfg(1M) create command.'
+ - Extra options to the zonecfg(1M) create command.
type: str
default: ''
install_options:
description:
- - 'Extra options to the zoneadm(1M) install command. To automate Solaris 11 zone creation,
- use this to specify the profile XML file, e.g. install_options="-c sc_profile.xml"'
+ - Extra options to the zoneadm(1M) install command. To automate Solaris 11 zone creation, use this to specify the profile
+ XML file, for example O(install_options=-c sc_profile.xml).
type: str
default: ''
attach_options:
description:
- - 'Extra options to the zoneadm attach command. For example, this can be used to specify
- whether a minimum or full update of packages is required and if any packages need to
- be deleted. For valid values, see zoneadm(1M)'
+ - Extra options to the zoneadm attach command. For example, this can be used to specify whether a minimum or full update
+ of packages is required and if any packages need to be deleted. For valid values, see zoneadm(1M).
type: str
default: ''
timeout:
@@ -96,9 +91,9 @@ options:
- Timeout, in seconds, for zone to boot.
type: int
default: 600
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create and install a zone, but don't boot it
community.general.solaris_zone:
name: zone1
@@ -149,7 +144,7 @@ EXAMPLES = '''
name: zone1
state: attached
attach_options: -u
-'''
+"""
import os
import platform
@@ -251,24 +246,22 @@ class Zone(object):
open('%s/root/noautoshutdown' % self.path, 'w').close()
- node = open('%s/root/etc/nodename' % self.path, 'w')
- node.write(self.name)
- node.close()
+ with open('%s/root/etc/nodename' % self.path, 'w') as node:
+ node.write(self.name)
- id = open('%s/root/etc/.sysIDtool.state' % self.path, 'w')
- id.write('1 # System previously configured?\n')
- id.write('1 # Bootparams succeeded?\n')
- id.write('1 # System is on a network?\n')
- id.write('1 # Extended network information gathered?\n')
- id.write('0 # Autobinder succeeded?\n')
- id.write('1 # Network has subnets?\n')
- id.write('1 # root password prompted for?\n')
- id.write('1 # locale and term prompted for?\n')
- id.write('1 # security policy in place\n')
- id.write('1 # NFSv4 domain configured\n')
- id.write('0 # Auto Registration Configured\n')
- id.write('vt100')
- id.close()
+ with open('%s/root/etc/.sysIDtool.state' % self.path, 'w') as id:
+ id.write('1 # System previously configured?\n')
+ id.write('1 # Bootparams succeeded?\n')
+ id.write('1 # System is on a network?\n')
+ id.write('1 # Extended network information gathered?\n')
+ id.write('0 # Autobinder succeeded?\n')
+ id.write('1 # Network has subnets?\n')
+ id.write('1 # root password prompted for?\n')
+ id.write('1 # locale and term prompted for?\n')
+ id.write('1 # security policy in place\n')
+ id.write('1 # NFSv4 domain configured\n')
+ id.write('0 # Auto Registration Configured\n')
+ id.write('vt100')
def configure_ssh_keys(self):
rsa_key_file = '%s/root/etc/ssh/ssh_host_rsa_key' % self.path
@@ -289,9 +282,8 @@ class Zone(object):
def configure_password(self):
shadow = '%s/root/etc/shadow' % self.path
if self.root_password:
- f = open(shadow, 'r')
- lines = f.readlines()
- f.close()
+ with open(shadow, 'r') as f:
+ lines = f.readlines()
for i in range(0, len(lines)):
fields = lines[i].split(':')
@@ -299,10 +291,9 @@ class Zone(object):
fields[1] = self.root_password
lines[i] = ':'.join(fields)
- f = open(shadow, 'w')
- for line in lines:
- f.write(line)
- f.close()
+ with open(shadow, 'w') as f:
+ for line in lines:
+ f.write(line)
def boot(self):
if not self.module.check_mode:
diff --git a/plugins/modules/sorcery.py b/plugins/modules/sorcery.py
index a525bd9ac8..fff3f55e07 100644
--- a/plugins/modules/sorcery.py
+++ b/plugins/modules/sorcery.py
@@ -10,93 +10,87 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: sorcery
short_description: Package manager for Source Mage GNU/Linux
description:
- - Manages "spells" on Source Mage GNU/Linux using I(sorcery) toolchain
+ - Manages "spells" on Source Mage GNU/Linux using I(sorcery) toolchain.
author: "Vlad Glagolev (@vaygr)"
notes:
- - When all three components are selected, the update goes by the sequence --
- Sorcery -> Grimoire(s) -> Spell(s); you cannot override it.
- - Grimoire handling is supported since community.general 7.3.0.
+ - When all three components are selected, the update goes by the sequence -- Sorcery -> Grimoire(s) -> Spell(s); you cannot
+ override it.
+ - Grimoire handling is supported since community.general 7.3.0.
requirements:
- - bash
+ - bash
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of the spell or grimoire.
- - Multiple names can be given, separated by commas.
- - Special value V(*) in conjunction with states V(latest) or
- V(rebuild) will update or rebuild the whole system respectively
- - The alias O(grimoire) was added in community.general 7.3.0.
- aliases: ["spell", "grimoire"]
- type: list
- elements: str
+ name:
+ description:
+ - Name of the spell or grimoire.
+ - Multiple names can be given, separated by commas.
+ - Special value V(*) in conjunction with states V(latest) or V(rebuild) will update or rebuild the whole system respectively.
+ - The alias O(grimoire) was added in community.general 7.3.0.
+ aliases: ["spell", "grimoire"]
+ type: list
+ elements: str
- repository:
- description:
- - Repository location.
- - If specified, O(name) represents grimoire(s) instead of spell(s).
- - Special value V(*) will pull grimoire from the official location.
- - Only single item in O(name) in conjunction with V(*) can be used.
- - O(state=absent) must be used with a special value V(*).
- type: str
- version_added: 7.3.0
+ repository:
+ description:
+ - Repository location.
+ - If specified, O(name) represents grimoire(s) instead of spell(s).
+ - Special value V(*) will pull grimoire from the official location.
+ - Only single item in O(name) in conjunction with V(*) can be used.
+ - O(state=absent) must be used with a special value V(*).
+ type: str
+ version_added: 7.3.0
- state:
- description:
- - Whether to cast, dispel or rebuild a package.
- - State V(cast) is an equivalent of V(present), not V(latest).
- - State V(rebuild) implies cast of all specified spells, not only
- those existed before.
- choices: ["present", "latest", "absent", "cast", "dispelled", "rebuild"]
- default: "present"
- type: str
+ state:
+ description:
+ - Whether to cast, dispel or rebuild a package.
+ - State V(cast) is an equivalent of V(present), not V(latest).
+ - State V(rebuild) implies cast of all specified spells, not only those existed before.
+ choices: ["present", "latest", "absent", "cast", "dispelled", "rebuild"]
+ default: "present"
+ type: str
- depends:
- description:
- - Comma-separated list of _optional_ dependencies to build a spell
- (or make sure it is built) with; use V(+)/V(-) in front of dependency
- to turn it on/off (V(+) is optional though).
- - This option is ignored if O(name) parameter is equal to V(*) or
- contains more than one spell.
- - Providers must be supplied in the form recognized by Sorcery,
- for example 'V(openssl(SSL\))'.
- type: str
+ depends:
+ description:
+ - Comma-separated list of _optional_ dependencies to build a spell (or make sure it is built) with; use V(+)/V(-) in
+ front of dependency to turn it on/off (V(+) is optional though).
+ - This option is ignored if O(name) parameter is equal to V(*) or contains more than one spell.
+ - Providers must be supplied in the form recognized by Sorcery, for example 'V(openssl(SSL\))'.
+ type: str
- update:
- description:
- - Whether or not to update sorcery scripts at the very first stage.
- type: bool
- default: false
+ update:
+ description:
+ - Whether or not to update sorcery scripts at the very first stage.
+ type: bool
+ default: false
- update_cache:
- description:
- - Whether or not to update grimoire collection before casting spells.
- type: bool
- default: false
- aliases: ["update_codex"]
+ update_cache:
+ description:
+ - Whether or not to update grimoire collection before casting spells.
+ type: bool
+ default: false
+ aliases: ["update_codex"]
- cache_valid_time:
- description:
- - Time in seconds to invalidate grimoire collection on update.
- - Especially useful for SCM and rsync grimoires.
- - Makes sense only in pair with O(update_cache).
- type: int
- default: 0
-'''
+ cache_valid_time:
+ description:
+ - Time in seconds to invalidate grimoire collection on update.
+ - Especially useful for SCM and rsync grimoires.
+ - Makes sense only in pair with O(update_cache).
+ type: int
+ default: 0
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Make sure spell foo is installed
community.general.sorcery:
spell: foo
@@ -131,9 +125,9 @@ EXAMPLES = '''
depends: "{{ item.depends | default(None) }}"
state: present
loop:
- - { spell: 'vifm', depends: '+file,-gtk+2' }
- - { spell: 'fwknop', depends: 'gpgme' }
- - { spell: 'pv,tnftp,tor' }
+ - {spell: 'vifm', depends: '+file,-gtk+2'}
+ - {spell: 'fwknop', depends: 'gpgme'}
+ - {spell: 'pv,tnftp,tor'}
- name: Install the latest version of spell foo using regular glossary
community.general.sorcery:
@@ -184,11 +178,11 @@ EXAMPLES = '''
- name: Update only Sorcery itself
community.general.sorcery:
update: true
-'''
+"""
-RETURN = '''
-'''
+RETURN = r"""
+"""
import datetime
@@ -466,15 +460,11 @@ def match_depends(module):
if depends_new:
try:
- try:
- fl = open(sorcery_depends, 'a')
-
+ with open(sorcery_depends, 'a') as fl:
for k in depends_new:
fl.write("%s:%s:%s:optional::\n" % (spell, k, depends[k]))
- except IOError:
- module.fail_json(msg="I/O error on the depends file")
- finally:
- fl.close()
+ except IOError:
+ module.fail_json(msg="I/O error on the depends file")
depends_ok = False
diff --git a/plugins/modules/spectrum_device.py b/plugins/modules/spectrum_device.py
index 7cf7cf9150..8bf4aa41b5 100644
--- a/plugins/modules/spectrum_device.py
+++ b/plugins/modules/spectrum_device.py
@@ -9,88 +9,87 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: spectrum_device
short_description: Creates/deletes devices in CA Spectrum
description:
- - This module allows you to create and delete devices in CA Spectrum U(https://www.ca.com/us/products/ca-spectrum.html).
- - Tested on CA Spectrum 9.4.2, 10.1.1 and 10.2.1
+ - This module allows you to create and delete devices in CA Spectrum U(https://www.ca.com/us/products/ca-spectrum.html).
+ - Tested on CA Spectrum 9.4.2, 10.1.1 and 10.2.1.
author: "Renato Orgito (@orgito)"
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- device:
- type: str
- aliases: [ host, name ]
- required: true
- description:
- - IP address of the device.
- - If a hostname is given, it will be resolved to the IP address.
- community:
- type: str
- description:
- - SNMP community used for device discovery.
- - Required when O(state=present).
- required: true
- landscape:
- type: str
- required: true
- description:
- - Landscape handle of the SpectroServer to which add or remove the device.
- state:
- type: str
- description:
- - On V(present) creates the device when it does not exist.
- - On V(absent) removes the device when it exists.
- choices: ['present', 'absent']
- default: 'present'
- url:
- type: str
- aliases: [ oneclick_url ]
- required: true
- description:
- - HTTP, HTTPS URL of the Oneclick server in the form V((http|https\)://host.domain[:port]).
- url_username:
- type: str
- aliases: [ oneclick_user ]
- required: true
- description:
- - Oneclick user name.
- url_password:
- type: str
- aliases: [ oneclick_password ]
- required: true
- description:
- - Oneclick user password.
- use_proxy:
- description:
- - if V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
- default: true
- type: bool
- validate_certs:
- description:
- - If V(false), SSL certificates will not be validated. This should only be used
- on personally controlled sites using self-signed certificates.
- default: true
- type: bool
- agentport:
- type: int
- required: false
- description:
- - UDP port used for SNMP discovery.
- default: 161
+ device:
+ type: str
+ aliases: [host, name]
+ required: true
+ description:
+ - IP address of the device.
+ - If a hostname is given, it will be resolved to the IP address.
+ community:
+ type: str
+ description:
+ - SNMP community used for device discovery.
+ - Required when O(state=present).
+ required: true
+ landscape:
+ type: str
+ required: true
+ description:
+ - Landscape handle of the SpectroServer to which add or remove the device.
+ state:
+ type: str
+ description:
+ - On V(present) creates the device when it does not exist.
+ - On V(absent) removes the device when it exists.
+ choices: ['present', 'absent']
+ default: 'present'
+ url:
+ type: str
+ aliases: [oneclick_url]
+ required: true
+ description:
+ - HTTP, HTTPS URL of the Oneclick server in the form V((http|https\)://host.domain[:port]).
+ url_username:
+ type: str
+ aliases: [oneclick_user]
+ required: true
+ description:
+ - Oneclick user name.
+ url_password:
+ type: str
+ aliases: [oneclick_password]
+ required: true
+ description:
+ - Oneclick user password.
+ use_proxy:
+ description:
+ - If V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
+ default: true
+ type: bool
+ validate_certs:
+ description:
+ - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
+ self-signed certificates.
+ default: true
+ type: bool
+ agentport:
+ type: int
+ required: false
+ description:
+ - UDP port used for SNMP discovery.
+ default: 161
notes:
- - The devices will be created inside the I(Universe) container of the specified landscape.
- - All the operations will be performed only on the specified landscape.
-'''
+ - The devices will be created inside the I(Universe) container of the specified landscape.
+ - All the operations will be performed only on the specified landscape.
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add device to CA Spectrum
local_action:
module: spectrum_device
@@ -113,15 +112,15 @@ EXAMPLES = '''
oneclick_password: password
use_proxy: false
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
device:
- description: device data when state = present
+ description: Device data when O(state=present).
returned: success
type: dict
sample: {'model_handle': '0x1007ab', 'landscape': '0x100000', 'address': '10.10.5.1'}
-'''
+"""
from socket import gethostbyname, gaierror
import xml.etree.ElementTree as ET
diff --git a/plugins/modules/spectrum_model_attrs.py b/plugins/modules/spectrum_model_attrs.py
index 43983a11a5..9c9fba4deb 100644
--- a/plugins/modules/spectrum_model_attrs.py
+++ b/plugins/modules/spectrum_model_attrs.py
@@ -9,110 +9,108 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: spectrum_model_attrs
short_description: Enforce a model's attributes in CA Spectrum
description:
- - This module can be used to enforce a model's attributes in CA Spectrum.
+ - This module can be used to enforce a model's attributes in CA Spectrum.
version_added: 2.5.0
author:
- - Tyler Gates (@tgates81)
+ - Tyler Gates (@tgates81)
notes:
- - Tested on CA Spectrum version 10.4.2.0.189.
- - Model creation and deletion are not possible with this module. For that use M(community.general.spectrum_device) instead.
+ - Tested on CA Spectrum version 10.4.2.0.189.
+ - Model creation and deletion are not possible with this module. For that use M(community.general.spectrum_device) instead.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- url:
- description:
- - URL of OneClick server.
- type: str
- required: true
- url_username:
- description:
- - OneClick username.
- type: str
- required: true
- aliases: [username]
- url_password:
- description:
- - OneClick password.
- type: str
- required: true
- aliases: [password]
- use_proxy:
- description:
- - if V(false), it will not use a proxy, even if one is defined in
- an environment variable on the target hosts.
- default: true
- required: false
- type: bool
- name:
- description:
- - Model name.
- type: str
- required: true
- type:
- description:
- - Model type.
- type: str
- required: true
- validate_certs:
- description:
- - Validate SSL certificates. Only change this to V(false) if you can guarantee that you are talking to the correct endpoint and there is no
- man-in-the-middle attack happening.
- type: bool
- default: true
- required: false
- attributes:
- description:
- - A list of attribute names and values to enforce.
- - All values and parameters are case sensitive and must be provided as strings only.
- required: true
- type: list
- elements: dict
- suboptions:
- name:
- description:
- - Attribute name OR hex ID.
- - 'Currently defined names are:'
- - ' C(App_Manufacturer) (C(0x230683))'
- - ' C(CollectionsModelNameString) (C(0x12adb))'
- - ' C(Condition) (C(0x1000a))'
- - ' C(Criticality) (C(0x1290c))'
- - ' C(DeviceType) (C(0x23000e))'
- - ' C(isManaged) (C(0x1295d))'
- - ' C(Model_Class) (C(0x11ee8))'
- - ' C(Model_Handle) (C(0x129fa))'
- - ' C(Model_Name) (C(0x1006e))'
- - ' C(Modeltype_Handle) (C(0x10001))'
- - ' C(Modeltype_Name) (C(0x10000))'
- - ' C(Network_Address) (C(0x12d7f))'
- - ' C(Notes) (C(0x11564))'
- - ' C(ServiceDesk_Asset_ID) (C(0x12db9))'
- - ' C(TopologyModelNameString) (C(0x129e7))'
- - ' C(sysDescr) (C(0x10052))'
- - ' C(sysName) (C(0x10b5b))'
- - ' C(Vendor_Name) (C(0x11570))'
- - ' C(Description) (C(0x230017))'
- - Hex IDs are the direct identifiers in Spectrum and will always work.
- - 'To lookup hex IDs go to the UI: Locator -> Devices -> By Model Name -> -> Attributes tab.'
- type: str
- required: true
- value:
- description:
- - Attribute value. Empty strings should be V("") or V(null).
- type: str
- required: true
-'''
+ url:
+ description:
+ - URL of OneClick server.
+ type: str
+ required: true
+ url_username:
+ description:
+ - OneClick username.
+ type: str
+ required: true
+ aliases: [username]
+ url_password:
+ description:
+ - OneClick password.
+ type: str
+ required: true
+ aliases: [password]
+ use_proxy:
+ description:
+ - If V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
+ default: true
+ required: false
+ type: bool
+ name:
+ description:
+ - Model name.
+ type: str
+ required: true
+ type:
+ description:
+ - Model type.
+ type: str
+ required: true
+ validate_certs:
+ description:
+ - Validate SSL certificates. Only change this to V(false) if you can guarantee that you are talking to the correct endpoint
+ and there is no man-in-the-middle attack happening.
+ type: bool
+ default: true
+ required: false
+ attributes:
+ description:
+ - A list of attribute names and values to enforce.
+ - All values and parameters are case sensitive and must be provided as strings only.
+ required: true
+ type: list
+ elements: dict
+ suboptions:
+ name:
+ description:
+ - Attribute name OR hex ID.
+ - 'Currently defined names are:'
+ - C(App_Manufacturer) (C(0x230683));
+ - C(CollectionsModelNameString) (C(0x12adb));
+ - C(Condition) (C(0x1000a));
+ - C(Criticality) (C(0x1290c));
+ - C(DeviceType) (C(0x23000e));
+ - C(isManaged) (C(0x1295d));
+ - C(Model_Class) (C(0x11ee8));
+ - C(Model_Handle) (C(0x129fa));
+ - C(Model_Name) (C(0x1006e));
+ - C(Modeltype_Handle) (C(0x10001));
+ - C(Modeltype_Name) (C(0x10000));
+ - C(Network_Address) (C(0x12d7f));
+ - C(Notes) (C(0x11564));
+ - C(ServiceDesk_Asset_ID) (C(0x12db9));
+ - C(TopologyModelNameString) (C(0x129e7));
+ - C(sysDescr) (C(0x10052));
+ - C(sysName) (C(0x10b5b));
+ - C(Vendor_Name) (C(0x11570));
+ - C(Description) (C(0x230017)).
+ - Hex IDs are the direct identifiers in Spectrum and will always work.
+ - 'To lookup hex IDs go to the UI: Locator -> Devices -> By Model Name -> -> Attributes tab.'
+ type: str
+ required: true
+ value:
+ description:
+ - Attribute value. Empty strings should be V("") or V(null).
+ type: str
+ required: true
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Enforce maintenance mode for modelxyz01 with a note about why
community.general.spectrum_model_attrs:
url: "http://oneclick.url.com"
@@ -128,23 +126,20 @@ EXAMPLES = r'''
value: "MM set on {{ ansible_date_time.iso8601 }} via CO {{ CO }} by {{ tower_user_name | default(ansible_user_id) }}"
delegate_to: localhost
register: spectrum_model_attrs_status
-'''
+"""
-RETURN = r'''
+RETURN = r"""
msg:
- description: Informational message on the job result.
- type: str
- returned: always
- sample: 'Success'
+ description: Informational message on the job result.
+ type: str
+ returned: always
+ sample: 'Success'
changed_attrs:
- description: Dictionary of changed name or hex IDs (whichever was specified) to their new corresponding values.
- type: dict
- returned: always
- sample: {
- "Notes": "MM set on 2021-02-03T22:04:02Z via CO CO9999 by tgates",
- "isManaged": "true"
- }
-'''
+ description: Dictionary of changed name or hex IDs (whichever was specified) to their new corresponding values.
+ type: dict
+ returned: always
+ sample: {"Notes": "MM set on 2021-02-03T22:04:02Z via CO CO9999 by tgates", "isManaged": "true"}
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/spotinst_aws_elastigroup.py b/plugins/modules/spotinst_aws_elastigroup.py
index 45556f621c..959dc6acca 100644
--- a/plugins/modules/spotinst_aws_elastigroup.py
+++ b/plugins/modules/spotinst_aws_elastigroup.py
@@ -5,19 +5,16 @@
# SPDX-License-Identifier: GPL-3.0-or-later
from __future__ import (absolute_import, division, print_function)
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: spotinst_aws_elastigroup
short_description: Create, update or delete Spotinst AWS Elastigroups
author: Spotinst (@talzur)
description:
- - Can create, update, or delete Spotinst AWS Elastigroups
- Launch configuration is part of the elastigroup configuration,
- so no additional modules are necessary for handling the launch configuration.
- You will have to have a credentials file in this location - /.spotinst/credentials
- The credentials file must contain a row that looks like this
- token =
- Full documentation available at https://help.spotinst.com/hc/en-us/articles/115003530285-Ansible-
+ - Can create, update, or delete Spotinst AWS Elastigroups Launch configuration is part of the elastigroup configuration,
+ so no additional modules are necessary for handling the launch configuration. You will have to have a credentials file
+ in this location - C($HOME/.spotinst/credentials). The credentials file must contain a row that looks like this C(token
+ = ).
+ - Full documentation available at U(https://help.spotinst.com/hc/en-us/articles/115003530285-Ansible-).
requirements:
- spotinst_sdk >= 1.0.38
extends_documentation_fragment:
@@ -38,62 +35,44 @@ options:
account_id:
description:
- Optional parameter that allows to set an account-id inside the module configuration.
- By default this is retrieved from the credentials path.
+ - By default this is retrieved from the credentials path.
type: str
token:
description:
- A Personal API Access Token issued by Spotinst.
- - >-
- When not specified, the module will try to obtain it, in that order, from: environment variable E(SPOTINST_TOKEN), or from the credentials path.
+ - 'When not specified, the module will try to obtain it, in that order, from: environment variable E(SPOTINST_TOKEN),
+ or from the credentials path.'
type: str
availability_vs_cost:
description:
- The strategy orientation.
- - "The choices available are: V(availabilityOriented), V(costOriented), V(balanced)."
+ - 'The choices available are: V(availabilityOriented), V(costOriented), V(balanced).'
required: true
type: str
availability_zones:
description:
- - A list of hash/dictionaries of Availability Zones that are configured in the elastigroup;
- '[{"key":"value", "key":"value"}]';
- keys allowed are
- name (String),
- subnet_id (String),
- placement_group_name (String),
+ - A list of hash/dictionaries of Availability Zones that are configured in the elastigroup; '[{"key":"value", "key":"value"}]';
+ keys allowed are name (String), subnet_id (String), placement_group_name (String),.
required: true
type: list
elements: dict
block_device_mappings:
description:
- - A list of hash/dictionaries of Block Device Mappings for elastigroup instances;
- You can specify virtual devices and EBS volumes.;
- '[{"key":"value", "key":"value"}]';
- keys allowed are
- device_name (List of Strings),
- virtual_name (String),
- no_device (String),
- ebs (Object, expects the following keys-
- delete_on_termination(Boolean),
- encrypted(Boolean),
- iops (Integer),
- snapshot_id(Integer),
- volume_type(String),
- volume_size(Integer))
+ - A list of hash/dictionaries of Block Device Mappings for elastigroup instances; You can specify virtual devices and
+ EBS volumes.; '[{"key":"value", "key":"value"}]'; keys allowed are device_name (List of Strings), virtual_name (String),
+ no_device (String), ebs (Object, expects the following keys- delete_on_termination(Boolean), encrypted(Boolean), iops
+ (Integer), snapshot_id(Integer), volume_type(String), volume_size(Integer)).
type: list
elements: dict
chef:
description:
- - The Chef integration configuration.;
- Expects the following keys - chef_server (String),
- organization (String),
- user (String),
- pem_key (String),
- chef_version (String)
+ - The Chef integration configuration.; Expects the following keys - chef_server (String), organization (String), user
+ (String), pem_key (String), chef_version (String).
type: dict
draining_timeout:
@@ -103,36 +82,31 @@ options:
ebs_optimized:
description:
- - Enable EBS optimization for supported instances which are not enabled by default.;
- Note - additional charges will be applied.
+ - Enable EBS optimization for supported instances which are not enabled by default.; Note - additional charges will
+ be applied.
type: bool
ebs_volume_pool:
description:
- - A list of hash/dictionaries of EBS devices to reattach to the elastigroup when available;
- '[{"key":"value", "key":"value"}]';
- keys allowed are -
- volume_ids (List of Strings),
- device_name (String)
+ - A list of hash/dictionaries of EBS devices to reattach to the elastigroup when available; '[{"key":"value", "key":"value"}]';
+ keys allowed are - volume_ids (List of Strings), device_name (String).
type: list
elements: dict
ecs:
description:
- - The ECS integration configuration.;
- Expects the following key -
- cluster_name (String)
+ - The ECS integration configuration.; Expects the following key - cluster_name (String).
type: dict
elastic_ips:
description:
- - List of ElasticIps Allocation Ids (example V(eipalloc-9d4e16f8)) to associate to the group instances
+ - List of ElasticIps Allocation IDs (example V(eipalloc-9d4e16f8)) to associate to the group instances.
type: list
elements: str
fallback_to_od:
description:
- - In case of no spots available, Elastigroup will launch an On-demand instance instead
+ - In case of no spots available, Elastigroup will launch an On-demand instance instead.
type: bool
health_check_grace_period:
@@ -149,159 +123,134 @@ options:
health_check_type:
description:
- The service to use for the health check.
- - "The choices available are: V(ELB), V(HCS), V(TARGET_GROUP), V(MLB), V(EC2)."
+ - 'The choices available are: V(ELB), V(HCS), V(TARGET_GROUP), V(MLB), V(EC2).'
type: str
iam_role_name:
description:
- - The instance profile iamRole name
- - Only use iam_role_arn, or iam_role_name
+ - The instance profile iamRole name.
+ - Only use O(iam_role_arn) or O(iam_role_name).
type: str
iam_role_arn:
description:
- - The instance profile iamRole arn
- - Only use iam_role_arn, or iam_role_name
+ - The instance profile iamRole arn.
+ - Only use O(iam_role_arn) or O(iam_role_name).
type: str
id:
description:
- - The group id if it already exists and you want to update, or delete it.
- This will not work unless the uniqueness_by field is set to id.
- When this is set, and the uniqueness_by field is set, the group will either be updated or deleted, but not created.
+ - The group ID if it already exists and you want to update, or delete it. This will not work unless the uniqueness_by
+ field is set to ID. When this is set, and the uniqueness_by field is set, the group will either be updated or deleted,
+ but not created.
type: str
image_id:
description:
- - The image Id used to launch the instance.;
- In case of conflict between Instance type and image type, an error will be returned
+ - The image ID used to launch the instance.; In case of conflict between Instance type and image type, an error will
+ be returned.
required: true
type: str
key_pair:
description:
- - Specify a Key Pair to attach to the instances
+ - Specify a Key Pair to attach to the instances.
type: str
kubernetes:
description:
- - The Kubernetes integration configuration.
- Expects the following keys -
- api_server (String),
- token (String)
+ - The Kubernetes integration configuration. Expects the following keys - api_server (String), token (String).
type: dict
lifetime_period:
description:
- - Lifetime period
+ - Lifetime period.
type: int
load_balancers:
description:
- - List of classic ELB names
+ - List of classic ELB names.
type: list
elements: str
max_size:
description:
- - The upper limit number of instances that you can scale up to
+ - The upper limit number of instances that you can scale up to.
required: true
type: int
mesosphere:
description:
- - The Mesosphere integration configuration.
- Expects the following key -
- api_server (String)
+ - The Mesosphere integration configuration. Expects the following key - api_server (String).
type: dict
min_size:
description:
- - The lower limit number of instances that you can scale down to
+ - The lower limit number of instances that you can scale down to.
required: true
type: int
monitoring:
description:
- - Describes whether instance Enhanced Monitoring is enabled
+ - Describes whether instance Enhanced Monitoring is enabled.
type: str
name:
description:
- - Unique name for elastigroup to be created, updated or deleted
+ - Unique name for elastigroup to be created, updated or deleted.
required: true
type: str
network_interfaces:
description:
- - A list of hash/dictionaries of network interfaces to add to the elastigroup;
- '[{"key":"value", "key":"value"}]';
- keys allowed are -
- description (String),
- device_index (Integer),
- secondary_private_ip_address_count (Integer),
- associate_public_ip_address (Boolean),
- delete_on_termination (Boolean),
- groups (List of Strings),
- network_interface_id (String),
- private_ip_address (String),
- subnet_id (String),
- associate_ipv6_address (Boolean),
- private_ip_addresses (List of Objects, Keys are privateIpAddress (String, required) and primary (Boolean))
+ - A list of hash/dictionaries of network interfaces to add to the elastigroup; '[{"key":"value", "key":"value"}]'; keys
+ allowed are - description (String), device_index (Integer), secondary_private_ip_address_count (Integer), associate_public_ip_address
+ (Boolean), delete_on_termination (Boolean), groups (List of Strings), network_interface_id (String), private_ip_address
+ (String), subnet_id (String), associate_ipv6_address (Boolean), private_ip_addresses (List of Objects, Keys are privateIpAddress
+ (String, required) and primary (Boolean)).
type: list
elements: dict
on_demand_count:
description:
- - Required if risk is not set
- - Number of on demand instances to launch. All other instances will be spot instances.;
- Either set this parameter or the risk parameter
+ - Required if risk is not set.
+ - Number of on demand instances to launch. All other instances will be spot instances.; Either set this parameter or
+ the risk parameter.
type: int
on_demand_instance_type:
description:
- - On-demand instance type that will be provisioned
+ - On-demand instance type that will be provisioned.
type: str
opsworks:
description:
- - The elastigroup OpsWorks integration configuration.;
- Expects the following key -
- layer_id (String)
+ - The elastigroup OpsWorks integration configuration.; Expects the following key - layer_id (String).
type: dict
persistence:
description:
- - The Stateful elastigroup configuration.;
- Accepts the following keys -
- should_persist_root_device (Boolean),
- should_persist_block_devices (Boolean),
- should_persist_private_ip (Boolean)
+ - The Stateful elastigroup configuration.; Accepts the following keys - should_persist_root_device (Boolean), should_persist_block_devices
+ (Boolean), should_persist_private_ip (Boolean).
type: dict
product:
description:
- Operation system type.
- - "Available choices are: V(Linux/UNIX), V(SUSE Linux), V(Windows), V(Linux/UNIX (Amazon VPC)), V(SUSE Linux (Amazon VPC))."
+ - 'Available choices are: V(Linux/UNIX), V(SUSE Linux), V(Windows), V(Linux/UNIX (Amazon VPC)), V(SUSE Linux (Amazon
+ VPC)).'
required: true
type: str
rancher:
description:
- - The Rancher integration configuration.;
- Expects the following keys -
- version (String),
- access_key (String),
- secret_key (String),
- master_host (String)
+ - The Rancher integration configuration.; Expects the following keys - version (String), access_key (String), secret_key
+ (String), master_host (String).
type: dict
right_scale:
description:
- - The Rightscale integration configuration.;
- Expects the following keys -
- account_id (String),
- refresh_token (String)
+ - The Rightscale integration configuration.; Expects the following keys - account_id (String), refresh_token (String).
type: dict
risk:
@@ -311,59 +260,44 @@ options:
roll_config:
description:
- - Roll configuration.;
- If you would like the group to roll after updating, please use this feature.
- Accepts the following keys -
- batch_size_percentage(Integer, Required),
- grace_period - (Integer, Required),
- health_check_type(String, Optional)
+ - Roll configuration.
+ - If you would like the group to roll after updating, please use this feature.
+ - Accepts the following keys - batch_size_percentage(Integer, Required), grace_period - (Integer, Required), health_check_type(String,
+ Optional).
type: dict
scheduled_tasks:
description:
- - A list of hash/dictionaries of scheduled tasks to configure in the elastigroup;
- '[{"key":"value", "key":"value"}]';
- keys allowed are -
- adjustment (Integer),
- scale_target_capacity (Integer),
- scale_min_capacity (Integer),
- scale_max_capacity (Integer),
- adjustment_percentage (Integer),
- batch_size_percentage (Integer),
- cron_expression (String),
- frequency (String),
- grace_period (Integer),
- task_type (String, required),
- is_enabled (Boolean)
+ - A list of hash/dictionaries of scheduled tasks to configure in the elastigroup, as in V([{"key":"value", "key":"value"}]).
+ - 'Keys allowed are: adjustment (Integer), scale_target_capacity (Integer), scale_min_capacity (Integer), scale_max_capacity
+ (Integer), adjustment_percentage (Integer), batch_size_percentage (Integer), cron_expression (String), frequency (String),
+ grace_period (Integer), task_type (String, required), is_enabled (Boolean).'
type: list
elements: dict
security_group_ids:
description:
- - One or more security group IDs. ;
- In case of update it will override the existing Security Group with the new given array
+ - One or more security group IDs.
+ - In case of update it will override the existing Security Group with the new given array.
required: true
type: list
elements: str
shutdown_script:
description:
- - The Base64-encoded shutdown script that executes prior to instance termination.
- Encode before setting.
+ - The Base64-encoded shutdown script that executes prior to instance termination. Encode before setting.
type: str
signals:
description:
- - A list of hash/dictionaries of signals to configure in the elastigroup;
- keys allowed are -
- name (String, required),
- timeout (Integer)
+ - A list of hash/dictionaries of signals to configure in the elastigroup; keys allowed are - name (String, required),
+ timeout (Integer).
type: list
elements: dict
spin_up_time:
description:
- - Spin up time, in seconds, for the instance
+ - Spin up time, in seconds, for the instance.
type: int
spot_instance_types:
@@ -378,108 +312,73 @@ options:
- present
- absent
description:
- - Create or delete the elastigroup
+ - Create or delete the elastigroup.
default: present
type: str
tags:
description:
- - A list of tags to configure in the elastigroup. Please specify list of keys and values (key colon value);
+ - A list of tags to configure in the elastigroup. Please specify list of keys and values (key colon value).
type: list
elements: dict
target:
description:
- - The number of instances to launch
+ - The number of instances to launch.
required: true
type: int
target_group_arns:
description:
- - List of target group arns instances should be registered to
+ - List of target group arns instances should be registered to.
type: list
elements: str
tenancy:
description:
- - Dedicated vs shared tenancy.
- - "The available choices are: V(default), V(dedicated)."
+ - Dedicated or shared tenancy.
+ - 'The available choices are: V(default), V(dedicated).'
type: str
terminate_at_end_of_billing_hour:
description:
- - Terminate at the end of billing hour
+ - Terminate at the end of billing hour.
type: bool
unit:
description:
- The capacity unit to launch instances by.
- - "The available choices are: V(instance), V(weight)."
+ - 'The available choices are: V(instance), V(weight).'
type: str
up_scaling_policies:
description:
- - A list of hash/dictionaries of scaling policies to configure in the elastigroup;
- '[{"key":"value", "key":"value"}]';
- keys allowed are -
- policy_name (String, required),
- namespace (String, required),
- metric_name (String, required),
- dimensions (List of Objects, Keys allowed are name (String, required) and value (String)),
- statistic (String, required)
- evaluation_periods (String, required),
- period (String, required),
- threshold (String, required),
- cooldown (String, required),
- unit (String, required),
- operator (String, required),
- action_type (String, required),
- adjustment (String),
- min_target_capacity (String),
- target (String),
- maximum (String),
- minimum (String)
+ - A list of hash/dictionaries of scaling policies to configure in the elastigroup; '[{"key":"value", "key":"value"}]';
+ keys allowed are - policy_name (String, required), namespace (String, required), metric_name (String, required), dimensions
+ (List of Objects, Keys allowed are name (String, required) and value (String)), statistic (String, required) evaluation_periods
+ (String, required), period (String, required), threshold (String, required), cooldown (String, required), unit (String,
+ required), operator (String, required), action_type (String, required), adjustment (String), min_target_capacity (String),
+ target (String), maximum (String), minimum (String).
type: list
elements: dict
down_scaling_policies:
description:
- - A list of hash/dictionaries of scaling policies to configure in the elastigroup;
- '[{"key":"value", "key":"value"}]';
- keys allowed are -
- policy_name (String, required),
- namespace (String, required),
- metric_name (String, required),
- dimensions ((List of Objects), Keys allowed are name (String, required) and value (String)),
- statistic (String, required),
- evaluation_periods (String, required),
- period (String, required),
- threshold (String, required),
- cooldown (String, required),
- unit (String, required),
- operator (String, required),
- action_type (String, required),
- adjustment (String),
- max_target_capacity (String),
- target (String),
- maximum (String),
- minimum (String)
+ - A list of hash/dictionaries of scaling policies to configure in the elastigroup; '[{"key":"value", "key":"value"}]';
+ keys allowed are - policy_name (String, required), namespace (String, required), metric_name (String, required), dimensions
+ ((List of Objects), Keys allowed are name (String, required) and value (String)), statistic (String, required), evaluation_periods
+ (String, required), period (String, required), threshold (String, required), cooldown (String, required), unit (String,
+ required), operator (String, required), action_type (String, required), adjustment (String), max_target_capacity (String),
+ target (String), maximum (String), minimum (String).
type: list
elements: dict
target_tracking_policies:
description:
- - A list of hash/dictionaries of target tracking policies to configure in the elastigroup;
- '[{"key":"value", "key":"value"}]';
- keys allowed are -
- policy_name (String, required),
- namespace (String, required),
- source (String, required),
- metric_name (String, required),
- statistic (String, required),
- unit (String, required),
- cooldown (String, required),
- target (String, required)
+ - A list of hash/dictionaries of target tracking policies to configure in the elastigroup; '[{"key":"value", "key":"value"}]';
+ keys allowed are - policy_name (String, required), namespace (String, required), source (String, required), metric_name
+ (String, required), statistic (String, required), unit (String, required), cooldown (String, required), target (String,
+ required).
type: list
elements: dict
@@ -488,8 +387,8 @@ options:
- id
- name
description:
- - If your group names are not unique, you may use this feature to update or delete a specific group.
- Whenever this property is set, you must set a group_id in order to update or delete a group, otherwise a group will be created.
+ - If your group names are not unique, you may use this feature to update or delete a specific group. Whenever this property
+ is set, you must set a group_id in order to update or delete a group, otherwise a group will be created.
default: name
type: str
@@ -500,20 +399,19 @@ options:
utilize_reserved_instances:
description:
- - In case of any available Reserved Instances,
- Elastigroup will utilize your reservations before purchasing Spot instances.
+ - In case of any available Reserved Instances, Elastigroup will utilize your reservations before purchasing Spot instances.
type: bool
wait_for_instances:
description:
- - Whether or not the elastigroup creation / update actions should wait for the instances to spin
+ - Whether or not the elastigroup creation / update actions should wait for the instances to spin.
type: bool
default: false
wait_timeout:
description:
- - How long the module should wait for instances before failing the action.;
- Only works if wait_for_instances is True.
+ - How long the module should wait for instances before failing the action.
+ - Only works if O(wait_for_instances=true).
type: int
do_not_update:
@@ -538,40 +436,39 @@ options:
description:
- Placeholder parameter for future implementation of Elastic Beanstalk configurations.
type: dict
-
-'''
-EXAMPLES = '''
+"""
+EXAMPLES = r"""
# Basic configuration YAML example
- hosts: localhost
tasks:
- name: Create elastigroup
community.general.spotinst_aws_elastigroup:
- state: present
- risk: 100
- availability_vs_cost: balanced
- availability_zones:
- - name: us-west-2a
- subnet_id: subnet-2b68a15c
- image_id: ami-f173cc91
- key_pair: spotinst-oregon
- max_size: 15
- min_size: 0
- target: 0
- unit: instance
- monitoring: true
- name: ansible-group
- on_demand_instance_type: c3.large
- product: Linux/UNIX
- load_balancers:
- - test-lb-1
- security_group_ids:
- - sg-8f4b8fe9
- spot_instance_types:
- - c3.large
- do_not_update:
- - image_id
- - target
+ state: present
+ risk: 100
+ availability_vs_cost: balanced
+ availability_zones:
+ - name: us-west-2a
+ subnet_id: subnet-2b68a15c
+ image_id: ami-f173cc91
+ key_pair: spotinst-oregon
+ max_size: 15
+ min_size: 0
+ target: 0
+ unit: instance
+ monitoring: true
+ name: ansible-group
+ on_demand_instance_type: c3.large
+ product: Linux/UNIX
+ load_balancers:
+ - test-lb-1
+ security_group_ids:
+ - sg-8f4b8fe9
+ spot_instance_types:
+ - c3.large
+ do_not_update:
+ - image_id
+ - target
register: result
- ansible.builtin.debug: var=result
@@ -581,39 +478,39 @@ EXAMPLES = '''
tasks:
- name: Create elastigroup
community.general.spotinst_aws_elastigroup:
- state: present
- account_id: act-1a9dd2b
- risk: 100
- availability_vs_cost: balanced
- availability_zones:
- - name: us-west-2a
- subnet_id: subnet-2b68a15c
- tags:
- - Environment: someEnvValue
- - OtherTagKey: otherValue
- image_id: ami-f173cc91
- key_pair: spotinst-oregon
- max_size: 5
- min_size: 0
- target: 0
- unit: instance
- monitoring: true
- name: ansible-group-tal
- on_demand_instance_type: c3.large
- product: Linux/UNIX
- security_group_ids:
- - sg-8f4b8fe9
- block_device_mappings:
- - device_name: '/dev/sda1'
- ebs:
- volume_size: 100
- volume_type: gp2
- spot_instance_types:
- - c3.large
- do_not_update:
- - image_id
- wait_for_instances: true
- wait_timeout: 600
+ state: present
+ account_id: act-1a9dd2b
+ risk: 100
+ availability_vs_cost: balanced
+ availability_zones:
+ - name: us-west-2a
+ subnet_id: subnet-2b68a15c
+ tags:
+ - Environment: someEnvValue
+ - OtherTagKey: otherValue
+ image_id: ami-f173cc91
+ key_pair: spotinst-oregon
+ max_size: 5
+ min_size: 0
+ target: 0
+ unit: instance
+ monitoring: true
+ name: ansible-group-tal
+ on_demand_instance_type: c3.large
+ product: Linux/UNIX
+ security_group_ids:
+ - sg-8f4b8fe9
+ block_device_mappings:
+ - device_name: '/dev/sda1'
+ ebs:
+ volume_size: 100
+ volume_type: gp2
+ spot_instance_types:
+ - c3.large
+ do_not_update:
+ - image_id
+ wait_for_instances: true
+ wait_timeout: 600
register: result
- name: Store private ips to file
@@ -628,43 +525,43 @@ EXAMPLES = '''
tasks:
- name: Create elastigroup
community.general.spotinst_aws_elastigroup:
- state: present
- account_id: act-1a9dd2b
- risk: 100
- availability_vs_cost: balanced
- availability_zones:
- - name: us-west-2a
- subnet_id: subnet-2b68a15c
- tags:
- - Environment: someEnvValue
- - OtherTagKey: otherValue
- image_id: ami-f173cc91
- key_pair: spotinst-oregon
- max_size: 5
- min_size: 0
- target: 0
- unit: instance
- monitoring: true
- name: ansible-group-tal
- on_demand_instance_type: c3.large
- product: Linux/UNIX
- security_group_ids:
- - sg-8f4b8fe9
- block_device_mappings:
- - device_name: '/dev/xvda'
- ebs:
- volume_size: 60
- volume_type: gp2
- - device_name: '/dev/xvdb'
- ebs:
- volume_size: 120
- volume_type: gp2
- spot_instance_types:
- - c3.large
- do_not_update:
- - image_id
- wait_for_instances: true
- wait_timeout: 600
+ state: present
+ account_id: act-1a9dd2b
+ risk: 100
+ availability_vs_cost: balanced
+ availability_zones:
+ - name: us-west-2a
+ subnet_id: subnet-2b68a15c
+ tags:
+ - Environment: someEnvValue
+ - OtherTagKey: otherValue
+ image_id: ami-f173cc91
+ key_pair: spotinst-oregon
+ max_size: 5
+ min_size: 0
+ target: 0
+ unit: instance
+ monitoring: true
+ name: ansible-group-tal
+ on_demand_instance_type: c3.large
+ product: Linux/UNIX
+ security_group_ids:
+ - sg-8f4b8fe9
+ block_device_mappings:
+ - device_name: '/dev/xvda'
+ ebs:
+ volume_size: 60
+ volume_type: gp2
+ - device_name: '/dev/xvdb'
+ ebs:
+ volume_size: 120
+ volume_type: gp2
+ spot_instance_types:
+ - c3.large
+ do_not_update:
+ - image_id
+ wait_for_instances: true
+ wait_timeout: 600
register: result
- name: Store private ips to file
@@ -678,36 +575,36 @@ EXAMPLES = '''
tasks:
- name: Create elastigroup
community.general.spotinst_aws_elastigroup:
- state: present
- risk: 100
- availability_vs_cost: balanced
- availability_zones:
- - name: us-west-2a
- subnet_id: subnet-2b68a15c
- image_id: ami-f173cc91
- key_pair: spotinst-oregon
- max_size: 15
- min_size: 0
- target: 0
- unit: instance
- block_device_mappings:
- - device_name: '/dev/xvda'
- virtual_name: ephemeral0
- - device_name: '/dev/xvdb/'
- virtual_name: ephemeral1
- monitoring: true
- name: ansible-group
- on_demand_instance_type: c3.large
- product: Linux/UNIX
- load_balancers:
- - test-lb-1
- security_group_ids:
- - sg-8f4b8fe9
- spot_instance_types:
- - c3.large
- do_not_update:
- - image_id
- - target
+ state: present
+ risk: 100
+ availability_vs_cost: balanced
+ availability_zones:
+ - name: us-west-2a
+ subnet_id: subnet-2b68a15c
+ image_id: ami-f173cc91
+ key_pair: spotinst-oregon
+ max_size: 15
+ min_size: 0
+ target: 0
+ unit: instance
+ block_device_mappings:
+ - device_name: '/dev/xvda'
+ virtual_name: ephemeral0
+ - device_name: '/dev/xvdb/'
+ virtual_name: ephemeral1
+ monitoring: true
+ name: ansible-group
+ on_demand_instance_type: c3.large
+ product: Linux/UNIX
+ load_balancers:
+ - test-lb-1
+ security_group_ids:
+ - sg-8f4b8fe9
+ spot_instance_types:
+ - c3.large
+ do_not_update:
+ - image_id
+ - target
register: result
- ansible.builtin.debug: var=result
@@ -718,34 +615,34 @@ EXAMPLES = '''
tasks:
- name: Create elastigroup
community.general.spotinst_aws_elastigroup:
- state: present
- risk: 100
- availability_vs_cost: balanced
- network_interfaces:
- - associate_public_ip_address: true
- device_index: 0
- availability_zones:
- - name: us-west-2a
- subnet_id: subnet-2b68a15c
- image_id: ami-f173cc91
- key_pair: spotinst-oregon
- max_size: 15
- min_size: 0
- target: 0
- unit: instance
- monitoring: true
- name: ansible-group
- on_demand_instance_type: c3.large
- product: Linux/UNIX
- load_balancers:
- - test-lb-1
- security_group_ids:
- - sg-8f4b8fe9
- spot_instance_types:
- - c3.large
- do_not_update:
- - image_id
- - target
+ state: present
+ risk: 100
+ availability_vs_cost: balanced
+ network_interfaces:
+ - associate_public_ip_address: true
+ device_index: 0
+ availability_zones:
+ - name: us-west-2a
+ subnet_id: subnet-2b68a15c
+ image_id: ami-f173cc91
+ key_pair: spotinst-oregon
+ max_size: 15
+ min_size: 0
+ target: 0
+ unit: instance
+ monitoring: true
+ name: ansible-group
+ on_demand_instance_type: c3.large
+ product: Linux/UNIX
+ load_balancers:
+ - test-lb-1
+ security_group_ids:
+ - sg-8f4b8fe9
+ spot_instance_types:
+ - c3.large
+ do_not_update:
+ - image_id
+ - target
register: result
- ansible.builtin.debug: var=result
@@ -756,70 +653,58 @@ EXAMPLES = '''
tasks:
- name: Create elastigroup
community.general.spotinst_aws_elastigroup:
- account_id: act-92d45673
- state: present
- risk: 100
- availability_vs_cost: balanced
- availability_zones:
- - name: us-west-2a
- subnet_id: subnet-79da021e
- image_id: ami-f173cc91
- fallback_to_od: true
- tags:
- - Creator: ValueOfCreatorTag
- - Environment: ValueOfEnvironmentTag
- key_pair: spotinst-labs-oregon
- max_size: 10
- min_size: 0
- target: 2
- unit: instance
- monitoring: true
- name: ansible-group-1
- on_demand_instance_type: c3.large
- product: Linux/UNIX
- security_group_ids:
- - sg-46cdc13d
- spot_instance_types:
- - c3.large
- target_tracking_policies:
- - policy_name: target-tracking-1
- namespace: AWS/EC2
- metric_name: CPUUtilization
- statistic: average
- unit: percent
- target: 50
- cooldown: 120
- do_not_update:
- - image_id
+ account_id: act-92d45673
+ state: present
+ risk: 100
+ availability_vs_cost: balanced
+ availability_zones:
+ - name: us-west-2a
+ subnet_id: subnet-79da021e
+ image_id: ami-f173cc91
+ fallback_to_od: true
+ tags:
+ - Creator: ValueOfCreatorTag
+ - Environment: ValueOfEnvironmentTag
+ key_pair: spotinst-labs-oregon
+ max_size: 10
+ min_size: 0
+ target: 2
+ unit: instance
+ monitoring: true
+ name: ansible-group-1
+ on_demand_instance_type: c3.large
+ product: Linux/UNIX
+ security_group_ids:
+ - sg-46cdc13d
+ spot_instance_types:
+ - c3.large
+ target_tracking_policies:
+ - policy_name: target-tracking-1
+ namespace: AWS/EC2
+ metric_name: CPUUtilization
+ statistic: average
+ unit: percent
+ target: 50
+ cooldown: 120
+ do_not_update:
+ - image_id
register: result
- ansible.builtin.debug: var=result
-'''
+"""
-RETURN = '''
----
+RETURN = r"""
instances:
- description: List of active elastigroup instances and their details.
- returned: success
- type: dict
- sample: [
- {
- "spotInstanceRequestId": "sir-regs25zp",
- "instanceId": "i-09640ad8678234c",
- "instanceType": "m4.large",
- "product": "Linux/UNIX",
- "availabilityZone": "us-west-2b",
- "privateIp": "180.0.2.244",
- "createdAt": "2017-07-17T12:46:18.000Z",
- "status": "fulfilled"
- }
- ]
+ description: List of active elastigroup instances and their details.
+ returned: success
+ type: dict
+ sample: [{"spotInstanceRequestId": "sir-regs25zp", "instanceId": "i-09640ad8678234c", "instanceType": "m4.large", "product": "Linux/UNIX",
+ "availabilityZone": "us-west-2b", "privateIp": "180.0.2.244", "createdAt": "2017-07-17T12:46:18.000Z", "status": "fulfilled"}]
group_id:
- description: Created / Updated group's ID.
- returned: success
- type: str
- sample: "sig-12345"
-
-'''
+ description: Created / Updated group's ID.
+ returned: success
+ type: str
+ sample: "sig-12345"
+"""
HAS_SPOTINST_SDK = False
__metaclass__ = type
diff --git a/plugins/modules/ss_3par_cpg.py b/plugins/modules/ss_3par_cpg.py
index 32c1cd443f..c9c9b4bd90 100644
--- a/plugins/modules/ss_3par_cpg.py
+++ b/plugins/modules/ss_3par_cpg.py
@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
short_description: Manage HPE StoreServ 3PAR CPG
author:
- Farhan Nomani (@farhan7500)
@@ -43,18 +42,15 @@ options:
type: str
growth_increment:
description:
- - Specifies the growth increment(in MiB, GiB or TiB) the amount of logical disk storage
- created on each auto-grow operation.
+ - Specifies the growth increment(in MiB, GiB or TiB) the amount of logical disk storage created on each auto-grow operation.
type: str
growth_limit:
description:
- - Specifies that the autogrow operation is limited to the specified
- storage amount that sets the growth limit(in MiB, GiB or TiB).
+ - Specifies that the autogrow operation is limited to the specified storage amount that sets the growth limit(in MiB, GiB or TiB).
type: str
growth_warning:
description:
- - Specifies that the threshold(in MiB, GiB or TiB) of used logical disk space when exceeded
- results in a warning alert.
+ - Specifies that the threshold(in MiB, GiB or TiB) of used logical disk space when exceeded results in a warning alert.
type: str
high_availability:
choices:
@@ -62,8 +58,7 @@ options:
- CAGE
- MAG
description:
- - Specifies that the layout must support the failure of one port pair,
- one cage, or one magazine.
+ - Specifies that the layout must support the failure of one port pair, one cage, or one magazine.
type: str
raid_type:
choices:
@@ -92,13 +87,12 @@ options:
type: bool
default: false
extends_documentation_fragment:
-- community.general.hpe3par
-- community.general.attributes
-
-'''
+ - community.general.hpe3par
+ - community.general.attributes
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Create CPG sample_cpg
community.general.ss_3par_cpg:
storage_system_ip: 10.10.10.1
@@ -124,10 +118,10 @@ EXAMPLES = r'''
state: absent
cpg_name: sample_cpg
secure: false
-'''
+"""
-RETURN = r'''
-'''
+RETURN = r"""
+"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.storage.hpe3par import hpe3par
diff --git a/plugins/modules/ssh_config.py b/plugins/modules/ssh_config.py
index d974f45373..07637e8003 100644
--- a/plugins/modules/ssh_config.py
+++ b/plugins/modules/ssh_config.py
@@ -11,18 +11,17 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: ssh_config
short_description: Manage SSH config for user
version_added: '2.0.0'
description:
- - Configures SSH hosts with special C(IdentityFile)s and hostnames.
+ - Configures SSH hosts with special C(IdentityFile)s and hostnames.
author:
- - Björn Andersson (@gaqzi)
- - Abhijeet Kasurde (@Akasurde)
+ - Björn Andersson (@gaqzi)
+ - Abhijeet Kasurde (@Akasurde)
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -33,7 +32,7 @@ options:
description:
- Whether a host entry should exist or not.
default: present
- choices: [ 'present', 'absent' ]
+ choices: ['present', 'absent']
type: str
user:
description:
@@ -50,8 +49,7 @@ options:
host:
description:
- The endpoint this configuration is valid for.
- - Can be an actual address on the internet or an alias that will
- connect to the value of O(hostname).
+ - Can be an actual address on the internet or an alias that will connect to the value of O(hostname).
required: true
type: str
hostname:
@@ -68,17 +66,14 @@ options:
type: str
identity_file:
description:
- - The path to an identity file (SSH private key) that will be used
- when connecting to this host.
+ - The path to an identity file (SSH private key) that will be used when connecting to this host.
- File need to exist and have mode V(0600) to be valid.
type: path
identities_only:
description:
- - Specifies that SSH should only use the configured authentication
- identity and certificate files (either the default files, or
- those explicitly configured in the C(ssh_config) files or passed on
- the ssh command-line), even if ssh-agent or a PKCS11Provider or
- SecurityKeyProvider offers more identities.
+ - Specifies that SSH should only use the configured authentication identity and certificate files (either the default
+ files, or those explicitly configured in the C(ssh_config) files or passed on the ssh command-line), even if C(ssh-agent)
+ or a C(PKCS11Provider) or C(SecurityKeyProvider) offers more identities.
type: bool
version_added: 8.2.0
user_known_hosts_file:
@@ -89,7 +84,7 @@ options:
description:
- Whether to strictly check the host key when doing connections to the remote host.
- The value V(accept-new) is supported since community.general 8.6.0.
- choices: [ 'yes', 'no', 'ask', 'accept-new' ]
+ choices: ['yes', 'no', 'ask', 'accept-new']
type: str
proxycommand:
description:
@@ -126,7 +121,7 @@ options:
controlmaster:
description:
- Sets the C(ControlMaster) option.
- choices: [ 'yes', 'no', 'ask', 'auto', 'autoask' ]
+ choices: ['yes', 'no', 'ask', 'auto', 'autoask']
type: str
version_added: 8.1.0
controlpath:
@@ -139,11 +134,23 @@ options:
- Sets the C(ControlPersist) option.
type: str
version_added: 8.1.0
+ dynamicforward:
+ description:
+ - Sets the C(DynamicForward) option.
+ type: str
+ version_added: 10.1.0
+ other_options:
+ description:
+ - Provides the option to specify arbitrary SSH config entry options via a dictionary.
+ - The key names must be lower case. Keys with upper case values are rejected.
+ - The values must be strings. Other values are rejected.
+ type: dict
+ version_added: 10.4.0
requirements:
-- paramiko
-'''
+ - paramiko
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Add a host in the configuration
community.general.ssh_config:
user: akasurde
@@ -152,15 +159,17 @@ EXAMPLES = r'''
identity_file: "/home/akasurde/.ssh/id_rsa"
port: '2223'
state: present
+ other_options:
+ serveraliveinterval: '30'
- name: Delete a host from the configuration
community.general.ssh_config:
ssh_config_file: "{{ ssh_config_test }}"
host: "example.com"
state: absent
-'''
+"""
-RETURN = r'''
+RETURN = r"""
hosts_added:
description: A list of host added.
returned: success
@@ -196,7 +205,7 @@ hosts_change_diff:
}
}
]
-'''
+"""
import os
@@ -204,6 +213,7 @@ from copy import deepcopy
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible.module_utils.common.text.converters import to_native
+from ansible.module_utils.six import string_types
from ansible_collections.community.general.plugins.module_utils._stormssh import ConfigParser, HAS_PARAMIKO, PARAMIKO_IMPORT_ERROR
from ansible_collections.community.general.plugins.module_utils.ssh import determine_config_file
@@ -272,7 +282,19 @@ class SSHConfig(object):
controlmaster=self.params.get('controlmaster'),
controlpath=self.params.get('controlpath'),
controlpersist=fix_bool_str(self.params.get('controlpersist')),
+ dynamicforward=self.params.get('dynamicforward'),
)
+ if self.params.get('other_options'):
+ for key, value in self.params.get('other_options').items():
+ if key.lower() != key:
+ self.module.fail_json(msg="The other_options key {key!r} must be lower case".format(key=key))
+ if key not in args:
+ if not isinstance(value, string_types):
+ self.module.fail_json(msg="The other_options value provided for key {key!r} must be a string, got {type}".format(key=key,
+ type=type(value)))
+ args[key] = value
+ else:
+ self.module.fail_json(msg="Multiple values provided for key {key!r}".format(key=key))
config_changed = False
hosts_changed = []
@@ -360,6 +382,7 @@ def main():
host_key_algorithms=dict(type='str', no_log=False),
identity_file=dict(type='path'),
identities_only=dict(type='bool'),
+ other_options=dict(type='dict'),
port=dict(type='str'),
proxycommand=dict(type='str', default=None),
proxyjump=dict(type='str', default=None),
@@ -376,6 +399,7 @@ def main():
controlmaster=dict(type='str', default=None, choices=['yes', 'no', 'ask', 'auto', 'autoask']),
controlpath=dict(type='str', default=None),
controlpersist=dict(type='str', default=None),
+ dynamicforward=dict(type='str'),
user=dict(default=None, type='str'),
user_known_hosts_file=dict(type='str', default=None),
),
diff --git a/plugins/modules/stacki_host.py b/plugins/modules/stacki_host.py
index 57440a24d0..bfa4cccff5 100644
--- a/plugins/modules/stacki_host.py
+++ b/plugins/modules/stacki_host.py
@@ -8,12 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: stacki_host
short_description: Add or remove host to stacki front-end
description:
- - Use this module to add or remove hosts to a stacki front-end via API.
+ - Use this module to add or remove hosts to a stacki front-end using API.
- Information on stacki can be found at U(https://github.com/StackIQ/stacki).
extends_documentation_fragment:
- community.general.attributes
@@ -30,13 +29,14 @@ options:
type: str
stacki_user:
description:
- - Username for authenticating with Stacki API, but if not specified, the environment variable E(stacki_user) is used instead.
+ - Username for authenticating with Stacki API, but if not specified, the environment variable E(stacki_user) is used
+ instead.
required: true
type: str
stacki_password:
description:
- - Password for authenticating with Stacki API, but if not
- specified, the environment variable E(stacki_password) is used instead.
+ - Password for authenticating with Stacki API, but if not specified, the environment variable E(stacki_password) is
+ used instead.
required: true
type: str
stacki_endpoint:
@@ -68,7 +68,7 @@ options:
description:
- Set value to the desired state for the specified host.
type: str
- choices: [ absent, present ]
+ choices: [absent, present]
default: present
appliance:
description:
@@ -96,10 +96,10 @@ options:
type: str
default: private
author:
-- Hugh Ma (@bbyhuy)
-'''
+ - Hugh Ma (@bbyhuy)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Add a host named test-1
community.general.stacki_host:
name: test-1
@@ -117,27 +117,27 @@ EXAMPLES = '''
stacki_password: pwd
stacki_endpoint: url
state: absent
-'''
+"""
-RETURN = '''
+RETURN = r"""
changed:
- description: response to whether or not the api call completed successfully
+ description: Response to whether or not the API call completed successfully.
returned: always
type: bool
sample: true
stdout:
- description: the set of responses from the commands
+ description: The set of responses from the commands.
returned: always
type: list
sample: ['...', '...']
stdout_lines:
- description: the value of stdout split into a list
+ description: The value of stdout split into a list.
returned: always
type: list
sample: [['...', '...'], ['...'], ['...']]
-'''
+"""
import json
diff --git a/plugins/modules/statsd.py b/plugins/modules/statsd.py
index 8bc0f0b187..dcb3f0252e 100644
--- a/plugins/modules/statsd.py
+++ b/plugins/modules/statsd.py
@@ -7,15 +7,14 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
module: statsd
short_description: Send metrics to StatsD
version_added: 2.1.0
description:
- The C(statsd) module sends metrics to StatsD.
- For more information, see U(https://statsd-metrics.readthedocs.io/en/latest/).
- - Supported metric types are V(counter) and V(gauge).
- Currently unupported metric types are V(timer), V(set), and V(gaugedelta).
+ - Supported metric types are V(counter) and V(gauge). Currently unupported metric types are V(timer), V(set), and V(gaugedelta).
author: "Mark Mercado (@mamercad)"
requirements:
- statsd
@@ -80,9 +79,9 @@ options:
default: false
description:
- If the metric is of type V(gauge), change the value by O(delta).
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Increment the metric my_counter by 1
community.general.statsd:
host: localhost
@@ -100,7 +99,7 @@ EXAMPLES = '''
metric: my_gauge
metric_type: gauge
value: 7
-'''
+"""
from ansible.module_utils.basic import (AnsibleModule, missing_required_lib)
diff --git a/plugins/modules/statusio_maintenance.py b/plugins/modules/statusio_maintenance.py
index 0a96d0fb41..9928267bde 100644
--- a/plugins/modules/statusio_maintenance.py
+++ b/plugins/modules/statusio_maintenance.py
@@ -9,127 +9,123 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
-
+DOCUMENTATION = r"""
module: statusio_maintenance
short_description: Create maintenance windows for your status.io dashboard
description:
- - Creates a maintenance window for status.io
- - Deletes a maintenance window for status.io
+ - Creates or deletes a maintenance window for status.io.
notes:
- - You can use the apiary API url (http://docs.statusio.apiary.io/) to
- capture API traffic
- - Use start_date and start_time with minutes to set future maintenance window
+ - You can use the apiary API URL (U(http://docs.statusio.apiary.io/)) to capture API traffic.
+ - Use start_date and start_time with minutes to set future maintenance window.
author: Benjamin Copeland (@bhcopeland)
extends_documentation_fragment:
- community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- title:
- type: str
- description:
- - A descriptive title for the maintenance window
- default: "A new maintenance window"
- desc:
- type: str
- description:
- - Message describing the maintenance window
- default: "Created by Ansible"
- state:
- type: str
- description:
- - Desired state of the package.
- default: "present"
- choices: ["present", "absent"]
- api_id:
- type: str
- description:
- - Your unique API ID from status.io
- required: true
- api_key:
- type: str
- description:
- - Your unique API Key from status.io
- required: true
- statuspage:
- type: str
- description:
- - Your unique StatusPage ID from status.io
- required: true
- url:
- type: str
- description:
- - Status.io API URL. A private apiary can be used instead.
- default: "https://api.status.io"
- components:
- type: list
- elements: str
- description:
- - The given name of your component (server name)
- aliases: ['component']
- containers:
- type: list
- elements: str
- description:
- - The given name of your container (data center)
- aliases: ['container']
- all_infrastructure_affected:
- description:
- - If it affects all components and containers
- type: bool
- default: false
- automation:
- description:
- - Automatically start and end the maintenance window
- type: bool
- default: false
- maintenance_notify_now:
- description:
- - Notify subscribers now
- type: bool
- default: false
- maintenance_notify_72_hr:
- description:
- - Notify subscribers 72 hours before maintenance start time
- type: bool
- default: false
- maintenance_notify_24_hr:
- description:
- - Notify subscribers 24 hours before maintenance start time
- type: bool
- default: false
- maintenance_notify_1_hr:
- description:
- - Notify subscribers 1 hour before maintenance start time
- type: bool
- default: false
- maintenance_id:
- type: str
- description:
- - The maintenance id number when deleting a maintenance window
- minutes:
- type: int
- description:
- - The length of time in UTC that the maintenance will run
- (starting from playbook runtime)
- default: 10
- start_date:
- type: str
- description:
- - Date maintenance is expected to start (Month/Day/Year) (UTC)
- - End Date is worked out from start_date + minutes
- start_time:
- type: str
- description:
- - Time maintenance is expected to start (Hour:Minutes) (UTC)
- - End Time is worked out from start_time + minutes
-'''
+ title:
+ type: str
+ description:
+ - A descriptive title for the maintenance window.
+ default: "A new maintenance window"
+ desc:
+ type: str
+ description:
+ - Message describing the maintenance window.
+ default: "Created by Ansible"
+ state:
+ type: str
+ description:
+ - Desired state of the package.
+ default: "present"
+ choices: ["present", "absent"]
+ api_id:
+ type: str
+ description:
+ - Your unique API ID from status.io.
+ required: true
+ api_key:
+ type: str
+ description:
+ - Your unique API Key from status.io.
+ required: true
+ statuspage:
+ type: str
+ description:
+ - Your unique StatusPage ID from status.io.
+ required: true
+ url:
+ type: str
+ description:
+ - Status.io API URL. A private apiary can be used instead.
+ default: "https://api.status.io"
+ components:
+ type: list
+ elements: str
+ description:
+ - The given name of your component (server name).
+ aliases: ['component']
+ containers:
+ type: list
+ elements: str
+ description:
+ - The given name of your container (data center).
+ aliases: ['container']
+ all_infrastructure_affected:
+ description:
+ - If it affects all components and containers.
+ type: bool
+ default: false
+ automation:
+ description:
+ - Automatically start and end the maintenance window.
+ type: bool
+ default: false
+ maintenance_notify_now:
+ description:
+ - Notify subscribers now.
+ type: bool
+ default: false
+ maintenance_notify_72_hr:
+ description:
+ - Notify subscribers 72 hours before maintenance start time.
+ type: bool
+ default: false
+ maintenance_notify_24_hr:
+ description:
+ - Notify subscribers 24 hours before maintenance start time.
+ type: bool
+ default: false
+ maintenance_notify_1_hr:
+ description:
+ - Notify subscribers 1 hour before maintenance start time.
+ type: bool
+ default: false
+ maintenance_id:
+ type: str
+ description:
+ - The maintenance ID number when deleting a maintenance window.
+ minutes:
+ type: int
+ description:
+ - The length of time in UTC that the maintenance will run (starting from playbook runtime).
+ default: 10
+ start_date:
+ type: str
+ description:
+ - Date maintenance is expected to start (Month/Day/Year) (UTC).
+ - End Date is worked out from O(start_date) + O(minutes).
+ start_time:
+ type: str
+ description:
+ - Time maintenance is expected to start (Hour:Minutes) (UTC).
+ - End Time is worked out from O(start_time) + O(minutes).
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Create a maintenance window for 10 minutes on server1, with automation to stop the maintenance
community.general.statusio_maintenance:
title: Router Upgrade from ansible
@@ -176,10 +172,9 @@ EXAMPLES = '''
api_id: api_id
api_key: api_key
state: absent
-
-'''
+"""
# TODO: Add RETURN documentation.
-RETURN = ''' # '''
+RETURN = """ # """
import datetime
import json
diff --git a/plugins/modules/sudoers.py b/plugins/modules/sudoers.py
index a392b4adfa..ac1ff91ff5 100644
--- a/plugins/modules/sudoers.py
+++ b/plugins/modules/sudoers.py
@@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: sudoers
short_description: Manage sudoers files
version_added: "4.3.0"
@@ -53,7 +52,7 @@ options:
version_added: 8.4.0
nopassword:
description:
- - Whether a password will be required to run the sudo'd command.
+ - Whether a password is required when command is run with sudo.
default: true
type: bool
setenv:
@@ -98,11 +97,11 @@ options:
- If V(required), visudo must be available to validate the sudoers rule.
type: str
default: detect
- choices: [ absent, detect, required ]
+ choices: [absent, detect, required]
version_added: 5.2.0
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Allow the backup user to sudo /usr/local/bin/backup
community.general.sudoers:
name: allow-backup
@@ -158,7 +157,7 @@ EXAMPLES = '''
user: alice
commands: /usr/bin/less
noexec: true
-'''
+"""
import os
from ansible.module_utils.basic import AnsibleModule
@@ -247,7 +246,7 @@ class Sudoers(object):
rc, stdout, stderr = self.module.run_command(check_command, data=self.content())
if rc != 0:
- raise Exception('Failed to validate sudoers rule:\n{stdout}'.format(stdout=stdout))
+ self.module.fail_json(msg='Failed to validate sudoers rule:\n{stdout}'.format(stdout=stdout or stderr), stdout=stdout, stderr=stderr)
def run(self):
if self.state == 'absent':
diff --git a/plugins/modules/supervisorctl.py b/plugins/modules/supervisorctl.py
index e8d9c89a65..7df1674fea 100644
--- a/plugins/modules/supervisorctl.py
+++ b/plugins/modules/supervisorctl.py
@@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: supervisorctl
-short_description: Manage the state of a program or group of programs running via supervisord
+short_description: Manage the state of a program or group of programs managed by C(supervisord)
description:
- - Manage the state of a program or group of programs running via supervisord
+ - Manage the state of a program or group of programs managed by C(supervisord).
extends_documentation_fragment:
- community.general.attributes
attributes:
@@ -33,29 +32,29 @@ options:
config:
type: path
description:
- - The supervisor configuration file path
+ - The supervisor configuration file path.
server_url:
type: str
description:
- - URL on which supervisord server is listening
+ - URL on which supervisord server is listening.
username:
type: str
description:
- - username to use for authentication
+ - Username to use for authentication.
password:
type: str
description:
- - password to use for authentication
+ - Password to use for authentication.
state:
type: str
description:
- The desired state of program/group.
required: true
- choices: [ "present", "started", "stopped", "restarted", "absent", "signalled" ]
+ choices: ["present", "started", "stopped", "restarted", "absent", "signalled"]
stop_before_removing:
type: bool
description:
- - Use O(stop_before_removing=true) to stop the program/group before removing it
+ - Use O(stop_before_removing=true) to stop the program/group before removing it.
required: false
default: false
version_added: 7.5.0
@@ -66,19 +65,21 @@ options:
supervisorctl_path:
type: path
description:
- - path to supervisorctl executable
+ - Path to C(supervisorctl) executable.
notes:
- - When O(state=present), the module will call C(supervisorctl reread) then C(supervisorctl add) if the program/group does not exist.
+ - When O(state=present), the module will call C(supervisorctl reread) then C(supervisorctl add) if the program/group does
+ not exist.
- When O(state=restarted), the module will call C(supervisorctl update) then call C(supervisorctl restart).
- When O(state=absent), the module will call C(supervisorctl reread) then C(supervisorctl remove) to remove the target program/group.
- If the program/group is still running, the action will fail. If you want to stop the program/group before removing, use O(stop_before_removing=true).
-requirements: [ "supervisorctl" ]
+ If the program/group is still running, the action will fail. If you want to stop the program/group before removing, use
+ O(stop_before_removing=true).
+requirements: ["supervisorctl"]
author:
- - "Matt Wright (@mattupstate)"
- - "Aaron Wang (@inetfuture) "
-'''
+ - "Matt Wright (@mattupstate)"
+ - "Aaron Wang (@inetfuture) "
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Manage the state of program to be in started state
community.general.supervisorctl:
name: my_app
@@ -113,7 +114,7 @@ EXAMPLES = '''
community.general.supervisorctl:
name: all
state: restarted
-'''
+"""
import os
from ansible.module_utils.basic import AnsibleModule, is_executable
diff --git a/plugins/modules/svc.py b/plugins/modules/svc.py
index b327ddfd60..42b6bcbeb9 100644
--- a/plugins/modules/svc.py
+++ b/plugins/modules/svc.py
@@ -8,60 +8,57 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: svc
author:
-- Brian Coca (@bcoca)
-short_description: Manage daemontools services
+ - Brian Coca (@bcoca)
+short_description: Manage C(daemontools) services
description:
- - Controls daemontools services on remote hosts using the svc utility.
+ - Controls C(daemontools) services on remote hosts using the C(svc) utility.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of the service to manage.
- type: str
- required: true
- state:
- description:
- - V(started)/V(stopped) are idempotent actions that will not run
- commands unless necessary. V(restarted) will always bounce the
- svc (svc -t) and V(killed) will always bounce the svc (svc -k).
- V(reloaded) will send a sigusr1 (svc -1).
- V(once) will run a normally downed svc once (svc -o), not really
- an idempotent operation.
- type: str
- choices: [ killed, once, reloaded, restarted, started, stopped ]
- downed:
- description:
- - Should a 'down' file exist or not, if it exists it disables auto startup.
- Defaults to no. Downed does not imply stopped.
- type: bool
- enabled:
- description:
- - Whether the service is enabled or not, if disabled it also implies stopped.
- Take note that a service can be enabled and downed (no auto restart).
- type: bool
- service_dir:
- description:
- - Directory svscan watches for services
- type: str
- default: /service
- service_src:
- description:
- - Directory where services are defined, the source of symlinks to service_dir.
- type: str
- default: /etc/service
-'''
+ name:
+ description:
+ - Name of the service to manage.
+ type: str
+ required: true
+ state:
+ description:
+ - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
+ - V(restarted) will always bounce the svc (svc -t) and V(killed) will always bounce the svc (svc -k).
+ - V(reloaded) will send a sigusr1 (svc -1).
+ - V(once) will run a normally downed svc once (svc -o), not really an idempotent operation.
+ type: str
+ choices: [killed, once, reloaded, restarted, started, stopped]
+ downed:
+ description:
+ - Should a C(down) file exist or not, if it exists it disables auto startup. Defaults to V(false). Downed does not imply
+ stopped.
+ type: bool
+ enabled:
+ description:
+ - Whether the service is enabled or not, if disabled it also implies O(state=stopped). Take note that a service can
+ be enabled and downed (no auto restart).
+ type: bool
+ service_dir:
+ description:
+ - Directory C(svscan) watches for services.
+ type: str
+ default: /service
+ service_src:
+ description:
+ - Directory where services are defined, the source of symlinks to O(service_dir).
+ type: str
+ default: /etc/service
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Start svc dnscache, if not running
community.general.svc:
name: dnscache
@@ -92,7 +89,7 @@ EXAMPLES = '''
name: dnscache
state: reloaded
service_dir: /var/service
-'''
+"""
import os
import re
diff --git a/plugins/modules/svr4pkg.py b/plugins/modules/svr4pkg.py
index 56ded66e62..34aa599e01 100644
--- a/plugins/modules/svr4pkg.py
+++ b/plugins/modules/svr4pkg.py
@@ -10,19 +10,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: svr4pkg
short_description: Manage Solaris SVR4 packages
description:
- - Manages SVR4 packages on Solaris 10 and 11.
- - These were the native packages on Solaris <= 10 and are available
- as a legacy feature in Solaris 11.
- - Note that this is a very basic packaging system. It will not enforce
- dependencies on install or remove.
+ - Manages SVR4 packages on Solaris 10 and 11.
+ - These were the native packages on Solaris <= 10 and are available as a legacy feature in Solaris 11.
+ - Note that this is a very basic packaging system. It will not enforce dependencies on install or remove.
author: "Boyd Adamson (@brontitall)"
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
check_mode:
support: full
@@ -39,7 +36,8 @@ options:
description:
- Whether to install (V(present)), or remove (V(absent)) a package.
- If the package is to be installed, then O(src) is required.
- - The SVR4 package system doesn't provide an upgrade operation. You need to uninstall the old, then install the new package.
+ - The SVR4 package system does not provide an upgrade operation. You need to uninstall the old, then install the new
+ package.
required: true
choices: ["present", "absent"]
type: str
@@ -47,8 +45,10 @@ options:
src:
description:
- Specifies the location to install the package from. Required when O(state=present).
- - "Can be any path acceptable to the C(pkgadd) command's C(-d) option. For example: V(somefile.pkg), V(/dir/with/pkgs), V(http:/server/mypkgs.pkg)."
- - If using a file or directory, they must already be accessible by the host. See the M(ansible.builtin.copy) module for a way to get them there.
+ - "Can be any path acceptable to the C(pkgadd) command's C(-d) option. For example: V(somefile.pkg), V(/dir/with/pkgs),
+ V(http://server/mypkgs.pkg)."
+ - If using a file or directory, they must already be accessible by the host. See the M(ansible.builtin.copy) module
+ for a way to get them there.
type: str
proxy:
description:
@@ -73,9 +73,9 @@ options:
required: false
type: bool
default: false
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install a package from an already copied file
community.general.svr4pkg:
name: CSWcommon
@@ -106,7 +106,7 @@ EXAMPLES = '''
name: FIREFOX
state: absent
category: true
-'''
+"""
import os
diff --git a/plugins/modules/swdepot.py b/plugins/modules/swdepot.py
index 9ba1b02b30..628c63f810 100644
--- a/plugins/modules/swdepot.py
+++ b/plugins/modules/swdepot.py
@@ -12,41 +12,40 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: swdepot
short_description: Manage packages with swdepot package manager (HP-UX)
description:
- - Will install, upgrade and remove packages with swdepot package manager (HP-UX)
+ - Will install, upgrade and remove packages with swdepot package manager (HP-UX).
notes: []
author: "Raul Melo (@melodous)"
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - package name.
- aliases: [pkg]
- required: true
- type: str
- state:
- description:
- - whether to install (V(present), V(latest)), or remove (V(absent)) a package.
- required: true
- choices: [ 'present', 'latest', 'absent']
- type: str
- depot:
- description:
- - The source repository from which install or upgrade a package.
- type: str
-'''
+ name:
+ description:
+ - Package name.
+ aliases: [pkg]
+ required: true
+ type: str
+ state:
+ description:
+ - Whether to install (V(present), V(latest)), or remove (V(absent)) a package.
+ required: true
+ choices: ['present', 'latest', 'absent']
+ type: str
+ depot:
+ description:
+ - The source repository from which install or upgrade a package.
+ type: str
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Install a package
community.general.swdepot:
name: unzip-6.0
@@ -63,7 +62,7 @@ EXAMPLES = '''
community.general.swdepot:
name: unzip
state: absent
-'''
+"""
import re
diff --git a/plugins/modules/swupd.py b/plugins/modules/swupd.py
index 16738c8cb8..5b5dbbc48a 100644
--- a/plugins/modules/swupd.py
+++ b/plugins/modules/swupd.py
@@ -10,13 +10,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
module: swupd
short_description: Manages updates and bundles in ClearLinux systems
description:
- - Manages updates and bundles with the swupd bundle manager, which is used by the
- Clear Linux Project for Intel Architecture.
+ - Manages updates and bundles with the swupd bundle manager, which is used by the Clear Linux Project for Intel Architecture.
author: Alberto Murillo (@albertomurillo)
extends_documentation_fragment:
- community.general.attributes
@@ -28,19 +26,17 @@ attributes:
options:
contenturl:
description:
- - URL pointing to the contents of available bundles.
- If not specified, the contents are retrieved from clearlinux.org.
+ - URL pointing to the contents of available bundles. If not specified, the contents are retrieved from clearlinux.org.
type: str
format:
description:
- - The format suffix for version file downloads. For example [1,2,3,staging,etc].
+ - The format suffix for version file downloads. For example V(1), V(2), V(3), and so on, or the special value V(staging).
If not specified, the default format is used.
type: str
manifest:
description:
- - The manifest contains information about the bundles at certain version of the OS.
- Specify a Manifest version to verify against that version or leave unspecified to
- verify against the current version.
+ - The manifest contains information about the bundles at certain version of the OS. Specify a Manifest version to verify
+ against that version or leave unspecified to verify against the current version.
aliases: [release, version]
type: int
name:
@@ -50,8 +46,8 @@ options:
type: str
state:
description:
- - Indicates the desired (I)bundle state. V(present) ensures the bundle
- is installed while V(absent) ensures the (I)bundle is not installed.
+ - Indicates the desired (I)bundle state. V(present) ensures the bundle is installed while V(absent) ensures the (I)bundle
+ is not installed.
default: present
choices: [present, absent]
type: str
@@ -73,9 +69,9 @@ options:
description:
- URL for version string download.
type: str
-'''
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Update the OS to the latest version
community.general.swupd:
update: true
@@ -98,18 +94,18 @@ EXAMPLES = '''
community.general.swupd:
verify: true
manifest: 12920
-'''
+"""
-RETURN = '''
+RETURN = r"""
stdout:
- description: stdout of swupd
+ description: C(stdout) of C(swupd).
returned: always
type: str
stderr:
- description: stderr of swupd
+ description: C(stderr) of C(swupd).
returned: always
type: str
-'''
+"""
import os
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/syslogger.py b/plugins/modules/syslogger.py
index 3a7abf4fbe..382f1c8422 100644
--- a/plugins/modules/syslogger.py
+++ b/plugins/modules/syslogger.py
@@ -7,55 +7,53 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: syslogger
short_description: Log messages in the syslog
description:
- - Uses syslog to add log entries to the host.
+ - Uses syslog to add log entries to the host.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: none
- diff_mode:
- support: none
+ check_mode:
+ support: none
+ diff_mode:
+ support: none
options:
- msg:
- type: str
- description:
- - This is the message to place in syslog.
- required: true
- priority:
- type: str
- description:
- - Set the log priority.
- choices: [ "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug" ]
- default: "info"
- facility:
- type: str
- description:
- - Set the log facility.
- choices: [ "kern", "user", "mail", "daemon", "auth", "lpr", "news",
- "uucp", "cron", "syslog", "local0", "local1", "local2",
- "local3", "local4", "local5", "local6", "local7" ]
- default: "daemon"
- log_pid:
- description:
- - Log the PID in brackets.
- type: bool
- default: false
- ident:
- description:
- - Specify the name of application name which is sending the log to syslog.
- type: str
- default: 'ansible_syslogger'
- version_added: '0.2.0'
+ msg:
+ type: str
+ description:
+ - This is the message to place in syslog.
+ required: true
+ priority:
+ type: str
+ description:
+ - Set the log priority.
+ choices: ["emerg", "alert", "crit", "err", "warning", "notice", "info", "debug"]
+ default: "info"
+ facility:
+ type: str
+ description:
+ - Set the log facility.
+ choices: ["kern", "user", "mail", "daemon", "auth", "lpr", "news", "uucp", "cron", "syslog", "local0", "local1", "local2",
+ "local3", "local4", "local5", "local6", "local7"]
+ default: "daemon"
+ log_pid:
+ description:
+ - Log the PID in brackets.
+ type: bool
+ default: false
+ ident:
+ description:
+ - Specify the name of application name which is sending the log to syslog.
+ type: str
+ default: 'ansible_syslogger'
+ version_added: '0.2.0'
author:
- - Tim Rightnour (@garbled1)
-'''
+ - Tim Rightnour (@garbled1)
+"""
-EXAMPLES = r'''
+EXAMPLES = r"""
- name: Simple Usage
community.general.syslogger:
msg: "I will end up as daemon.info"
@@ -72,36 +70,36 @@ EXAMPLES = r'''
ident: "MyApp"
msg: "I want to believe"
priority: "alert"
-'''
+"""
-RETURN = r'''
+RETURN = r"""
ident:
- description: Name of application sending the message to log
+ description: Name of application sending the message to log.
returned: always
type: str
sample: "ansible_syslogger"
version_added: '0.2.0'
priority:
- description: Priority level
+ description: Priority level.
returned: always
type: str
sample: "daemon"
facility:
- description: Syslog facility
+ description: Syslog facility.
returned: always
type: str
sample: "info"
log_pid:
- description: Log PID status
+ description: Log PID status.
returned: always
type: bool
sample: true
msg:
- description: Message sent to syslog
+ description: Message sent to syslog.
returned: always
type: str
sample: "Hello from Ansible"
-'''
+"""
import syslog
import traceback
diff --git a/plugins/modules/syspatch.py b/plugins/modules/syspatch.py
index c90ef0d227..3cedc220f7 100644
--- a/plugins/modules/syspatch.py
+++ b/plugins/modules/syspatch.py
@@ -8,37 +8,35 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
module: syspatch
short_description: Manage OpenBSD system patches
description:
- - "Manage OpenBSD system patches using syspatch."
-
+ - Manage OpenBSD system patches using syspatch.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- revert:
- description:
- - Revert system patches.
- type: str
- choices: [ all, one ]
+ revert:
+ description:
+ - Revert system patches.
+ type: str
+ choices: [all, one]
author:
- - Andrew Klaus (@precurse)
-'''
+ - Andrew Klaus (@precurse)
+"""
-EXAMPLES = '''
+EXAMPLES = r"""
- name: Apply all available system patches
community.general.syspatch:
@@ -58,20 +56,20 @@ EXAMPLES = '''
- name: Reboot if patch requires it
ansible.builtin.reboot:
when: syspatch.reboot_needed
-'''
+"""
-RETURN = r'''
+RETURN = r"""
rc:
- description: The command return code (0 means success)
+ description: The command return code (0 means success).
returned: always
type: int
stdout:
- description: syspatch standard output.
+ description: C(syspatch) standard output.
returned: always
type: str
sample: "001_rip6cksum"
stderr:
- description: syspatch standard error.
+ description: C(syspatch) standard error.
returned: always
type: str
sample: "syspatch: need root privileges"
@@ -80,7 +78,7 @@ reboot_needed:
returned: always
type: bool
sample: true
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
diff --git a/plugins/modules/sysrc.py b/plugins/modules/sysrc.py
index 6780975d4f..d93bccd620 100644
--- a/plugins/modules/sysrc.py
+++ b/plugins/modules/sysrc.py
@@ -9,64 +9,62 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
author:
- - David Lundgren (@dlundgren)
+ - David Lundgren (@dlundgren)
module: sysrc
short_description: Manage FreeBSD using sysrc
version_added: '2.0.0'
description:
- - Manages C(/etc/rc.conf) for FreeBSD.
+ - Manages C(/etc/rc.conf) for FreeBSD.
extends_documentation_fragment:
- - community.general.attributes
+ - community.general.attributes
attributes:
- check_mode:
- support: full
- diff_mode:
- support: none
+ check_mode:
+ support: full
+ diff_mode:
+ support: none
options:
- name:
- description:
- - Name of variable in C(/etc/rc.conf) to manage.
- type: str
- required: true
- value:
- description:
- - The value to set when O(state=present).
- - The value to add when O(state=value_present).
- - The value to remove when O(state=value_absent).
- type: str
- state:
- description:
- - Use V(present) to add the variable.
- - Use V(absent) to remove the variable.
- - Use V(value_present) to add the value to the existing variable.
- - Use V(value_absent) to remove the value from the existing variable.
- type: str
- default: "present"
- choices: [ absent, present, value_present, value_absent ]
- path:
- description:
- - Path to file to use instead of V(/etc/rc.conf).
- type: str
- default: "/etc/rc.conf"
- delim:
- description:
- - Delimiter to be used instead of V(" ") (space).
- - Only used when O(state=value_present) or O(state=value_absent).
- default: " "
- type: str
- jail:
- description:
- - Name or ID of the jail to operate on.
- type: str
+ name:
+ description:
+ - Name of variable in C(/etc/rc.conf) to manage.
+ type: str
+ required: true
+ value:
+ description:
+ - The value to set when O(state=present).
+ - The value to add when O(state=value_present).
+ - The value to remove when O(state=value_absent).
+ type: str
+ state:
+ description:
+ - Use V(present) to add the variable.
+ - Use V(absent) to remove the variable.
+ - Use V(value_present) to add the value to the existing variable.
+ - Use V(value_absent) to remove the value from the existing variable.
+ type: str
+ default: "present"
+ choices: [absent, present, value_present, value_absent]
+ path:
+ description:
+ - Path to file to use instead of V(/etc/rc.conf).
+ type: str
+ default: "/etc/rc.conf"
+ delim:
+ description:
+ - Delimiter to be used instead of V(" ") (space).
+ - Only used when O(state=value_present) or O(state=value_absent).
+ default: " "
+ type: str
+ jail:
+ description:
+ - Name or ID of the jail to operate on.
+ type: str
notes:
- The O(name) cannot contain periods as sysrc does not support OID style names.
-'''
+"""
-EXAMPLES = r'''
----
+EXAMPLES = r"""
# enable mysql in the /etc/rc.conf
- name: Configure mysql pid file
community.general.sysrc:
@@ -94,15 +92,15 @@ EXAMPLES = r'''
name: nginx_enable
value: "YES"
jail: testjail
-'''
+"""
-RETURN = r'''
+RETURN = r"""
changed:
description: Return changed for sysrc actions.
returned: always
type: bool
sample: true
-'''
+"""
from ansible.module_utils.basic import AnsibleModule
import re
diff --git a/plugins/modules/systemd_creds_decrypt.py b/plugins/modules/systemd_creds_decrypt.py
new file mode 100644
index 0000000000..fbe80f2f16
--- /dev/null
+++ b/plugins/modules/systemd_creds_decrypt.py
@@ -0,0 +1,151 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024, Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+module: systemd_creds_decrypt
+short_description: C(systemd)'s C(systemd-creds decrypt) plugin
+description:
+ - This module decrypts input using C(systemd)'s C(systemd-creds decrypt).
+author:
+ - Thomas Sjögren (@konstruktoid)
+version_added: '10.2.0'
+extends_documentation_fragment:
+ - community.general.attributes
+attributes:
+ check_mode:
+ support: full
+ details:
+ - This action does not modify state.
+ diff_mode:
+ support: N/A
+ details:
+ - This action does not modify state.
+options:
+ name:
+ description:
+ - The credential name to validate the embedded credential name.
+ type: str
+ required: false
+ newline:
+ description:
+ - Whether to add a trailing newline character to the end of the output, if not present.
+ type: bool
+ required: false
+ default: false
+ secret:
+ description:
+ - The secret to decrypt.
+ type: str
+ required: true
+ timestamp:
+ description:
+ - The timestamp to use to validate the V(not-after) timestamp that was used during encryption.
+ - Takes a timestamp specification in the format described in V(systemd.time(7\)).
+ type: str
+ required: false
+ transcode:
+ description:
+ - Whether to transcode the output before returning it.
+ type: str
+ choices: [base64, unbase64, hex, unhex]
+ required: false
+ user:
+ description:
+ - A user name or numeric UID when decrypting from a specific user context.
+ - If set to the special string V(self) it sets the user to the user of the calling process.
+ - Requires C(systemd) 256 or later.
+ type: str
+ required: false
+notes:
+ - C(systemd-creds) requires C(systemd) 250 or later.
+"""
+
+EXAMPLES = r"""
+- name: Decrypt secret
+ community.general.systemd_creds_decrypt:
+ name: db
+ secret: "WhQZht+JQJax1aZemmGLxmAAAA..."
+ register: decrypted_secret
+
+- name: Print the decrypted secret
+ ansible.builtin.debug:
+ msg: "{{ decrypted_secret }}"
+"""
+
+RETURN = r"""
+value:
+ description:
+ - The decrypted secret.
+ - Note that Ansible only supports returning UTF-8 encoded strings. If the decrypted secret is binary data, or a string
+ encoded in another way, use O(transcode=base64) or O(transcode=hex) to circument this restriction. You then need to
+ decode the data when using it, for example using the P(ansible.builtin.b64decode#filter) filter.
+ type: str
+ returned: always
+ sample: "access_token"
+"""
+
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+ """Decrypt secret using systemd-creds."""
+ module = AnsibleModule(
+ argument_spec=dict(
+ name=dict(type="str", required=False),
+ newline=dict(type="bool", required=False, default=False),
+ secret=dict(type="str", required=True, no_log=True),
+ timestamp=dict(type="str", required=False),
+ transcode=dict(
+ type="str",
+ choices=["base64", "unbase64", "hex", "unhex"],
+ required=False,
+ ),
+ user=dict(type="str", required=False),
+ ),
+ supports_check_mode=True,
+ )
+
+ cmd = module.get_bin_path("systemd-creds", required=True)
+
+ name = module.params["name"]
+ newline = module.params["newline"]
+ secret = module.params["secret"]
+ timestamp = module.params["timestamp"]
+ transcode = module.params["transcode"]
+ user = module.params["user"]
+
+ decrypt_cmd = [cmd, "decrypt"]
+ if name:
+ decrypt_cmd.append("--name=" + name)
+ else:
+ decrypt_cmd.append("--name=")
+ decrypt_cmd.append("--newline=" + ("yes" if newline else "no"))
+ if timestamp:
+ decrypt_cmd.append("--timestamp=" + timestamp)
+ if transcode:
+ decrypt_cmd.append("--transcode=" + transcode)
+ if user:
+ decrypt_cmd.append("--uid=" + user)
+ decrypt_cmd.extend(["-", "-"])
+
+ rc, stdout, stderr = module.run_command(decrypt_cmd, data=secret, binary_data=True)
+
+ module.exit_json(
+ changed=False,
+ value=stdout,
+ rc=rc,
+ stderr=stderr,
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/plugins/modules/systemd_creds_encrypt.py b/plugins/modules/systemd_creds_encrypt.py
new file mode 100644
index 0000000000..6f6e635416
--- /dev/null
+++ b/plugins/modules/systemd_creds_encrypt.py
@@ -0,0 +1,145 @@
+#!/usr/bin/python
+
+# Copyright (c) 2024, Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+
+DOCUMENTATION = r"""
+module: systemd_creds_encrypt
+short_description: C(systemd)'s C(systemd-creds encrypt) plugin
+description:
+ - This module encrypts input using C(systemd)'s C(systemd-creds encrypt).
+author:
+ - Thomas Sjögren (@konstruktoid)
+version_added: '10.2.0'
+extends_documentation_fragment:
+ - community.general.attributes
+attributes:
+ check_mode:
+ support: full
+ details:
+ - This action does not modify state.
+ diff_mode:
+ support: N/A
+ details:
+ - This action does not modify state.
+options:
+ name:
+ description:
+ - The credential name to embed in the encrypted credential data.
+ type: str
+ required: false
+ not_after:
+ description:
+ - The time when the credential shall not be used anymore.
+ - Takes a timestamp specification in the format described in V(systemd.time(7\)).
+ type: str
+ required: false
+ pretty:
+ description:
+ - Pretty print the output so that it may be pasted directly into a unit file.
+ type: bool
+ required: false
+ default: false
+ secret:
+ description:
+ - The secret to encrypt.
+ type: str
+ required: true
+ timestamp:
+ description:
+ - The timestamp to embed into the encrypted credential.
+ - Takes a timestamp specification in the format described in V(systemd.time(7\)).
+ type: str
+ required: false
+ user:
+ description:
+ - A user name or numeric UID to encrypt the credential for.
+ - If set to the special string V(self) it sets the user to the user of the calling process.
+ - Requires C(systemd) 256 or later.
+ type: str
+ required: false
+notes:
+ - C(systemd-creds) requires C(systemd) 250 or later.
+"""
+
+EXAMPLES = r"""
+- name: Encrypt secret
+ become: true
+ community.general.systemd_creds_encrypt:
+ name: db
+ not_after: +48hr
+ secret: access_token
+ register: encrypted_secret
+
+- name: Print the encrypted secret
+ ansible.builtin.debug:
+ msg: "{{ encrypted_secret }}"
+"""
+
+RETURN = r"""
+value:
+ description: The Base64 encoded encrypted secret.
+ type: str
+ returned: always
+ sample: "WhQZht+JQJax1aZemmGLxmAAAA..."
+"""
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+ """Encrypt secret using systemd-creds."""
+ module = AnsibleModule(
+ argument_spec=dict(
+ name=dict(type="str", required=False),
+ not_after=dict(type="str", required=False),
+ pretty=dict(type="bool", default=False),
+ secret=dict(type="str", required=True, no_log=True),
+ timestamp=dict(type="str", required=False),
+ user=dict(type="str", required=False),
+ ),
+ supports_check_mode=True,
+ )
+
+ cmd = module.get_bin_path("systemd-creds", required=True)
+
+ name = module.params["name"]
+ not_after = module.params["not_after"]
+ pretty = module.params["pretty"]
+ secret = module.params["secret"]
+ timestamp = module.params["timestamp"]
+ user = module.params["user"]
+
+ encrypt_cmd = [cmd, "encrypt"]
+ if name:
+ encrypt_cmd.append("--name=" + name)
+ else:
+ encrypt_cmd.append("--name=")
+ if not_after:
+ encrypt_cmd.append("--not-after=" + not_after)
+ if pretty:
+ encrypt_cmd.append("--pretty")
+ if timestamp:
+ encrypt_cmd.append("--timestamp=" + timestamp)
+ if user:
+ encrypt_cmd.append("--uid=" + user)
+ encrypt_cmd.extend(["-", "-"])
+
+ rc, stdout, stderr = module.run_command(encrypt_cmd, data=secret, binary_data=True)
+
+ module.exit_json(
+ changed=False,
+ value=stdout,
+ rc=rc,
+ stderr=stderr,
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/plugins/modules/systemd_info.py b/plugins/modules/systemd_info.py
new file mode 100644
index 0000000000..d87df32780
--- /dev/null
+++ b/plugins/modules/systemd_info.py
@@ -0,0 +1,418 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2025, Marco Noce