From c44118ac3ceb8411c4100849322217d8abf65b93 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 4 Nov 2024 19:14:42 +0100 Subject: [PATCH 001/302] Prepare 10.0.0 release. --- README.md | 8 ++++---- changelogs/fragments/10.0.0.yml | 2 ++ changelogs/fragments/8497-crypt.yml | 3 --- 3 files changed, 6 insertions(+), 7 deletions(-) create mode 100644 changelogs/fragments/10.0.0.yml delete mode 100644 changelogs/fragments/8497-crypt.yml diff --git a/README.md b/README.md index 03dad49f39..be57b6bc2f 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ SPDX-License-Identifier: GPL-3.0-or-later # Community General Collection -[![Build Status](https://dev.azure.com/ansible/community.general/_apis/build/status/CI?branchName=main)](https://dev.azure.com/ansible/community.general/_build?definitionId=31) +[![Build Status](https://dev.azure.com/ansible/community.general/_apis/build/status/CI?branchName=stable-10)](https://dev.azure.com/ansible/community.general/_build?definitionId=31) [![EOL CI](https://github.com/ansible-collections/community.general/workflows/EOL%20CI/badge.svg?event=push)](https://github.com/ansible-collections/community.general/actions) [![Codecov](https://img.shields.io/codecov/c/github/ansible-collections/community.general)](https://codecov.io/gh/ansible-collections/community.general) [![REUSE status](https://api.reuse.software/badge/github.com/ansible-collections/community.general)](https://api.reuse.software/info/github.com/ansible-collections/community.general) @@ -116,7 +116,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 +135,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/fragments/10.0.0.yml b/changelogs/fragments/10.0.0.yml new file mode 100644 index 0000000000..4f75197d43 --- /dev/null +++ b/changelogs/fragments/10.0.0.yml @@ -0,0 +1,2 @@ +release_summary: |- + This is release 10.0.0 of ``community.general``, released on 2024-11-04. 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)." From b05fa358e6b5d881aecc152852c0887056dbce10 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 4 Nov 2024 19:17:50 +0100 Subject: [PATCH 002/302] Release 10.0.0. --- CHANGELOG.md | 377 ++++++++- CHANGELOG.rst | 368 ++++++++- changelogs/changelog.yaml | 743 +++++++++++++++++- changelogs/fragments/10.0.0.yml | 2 - .../8051-Redfish-Wait-For-Service.yml | 3 - ...udosu-not-working-on-some-BSD-machines.yml | 2 - .../8402-add-diif-mode-openbsd-pkg.yml | 2 - ...8403-fix-typeerror-in-keycloak-client.yaml | 2 - .../fragments/8404-ipa_dnsrecord_sshfp.yml | 2 - .../8405-gitlab-remove-basic-auth.yml | 2 - .../8406-fix-homebrew-cask-warning.yaml | 2 - .../fragments/8411-locale-gen-vardict.yml | 11 - changelogs/fragments/8413-galaxy-refactor.yml | 2 - .../fragments/8415-cmd-runner-stack.yml | 2 - ...ign-auth-flow-by-name-keycloak-client.yaml | 2 - ...en-using-logs-with-uri-or-slurp-tasks.yaml | 3 - changelogs/fragments/8431-galaxy-upgrade.yml | 2 - .../8440-allow-api-port-specification.yaml | 2 - .../8444-fix-redfish-gen2-upgrade.yaml | 2 - .../fragments/8452-git_config-absent.yml | 2 - .../8453-git_config-deprecate-read.yml | 3 - .../fragments/8464-redis-add-cluster-info.yml | 2 - .../8471-proxmox-vm-info-network.yml | 2 - .../8476-launchd-check-mode-changed.yaml | 2 - .../fragments/8479-cmdrunner-improvements.yml | 4 - .../8480-directory-feature-cargo.yml | 2 - ...ula-inventory-crash-when-nic-has-no-ip.yml | 2 - ...ycloak_clientscope-add-normalizations.yaml | 2 - .../fragments/8508-virtualbox-inventory.yml | 3 - changelogs/fragments/8512-as-bool-not.yml | 2 - changelogs/fragments/8514-pacman-empty.yml | 2 - .../8516-proxmox-template-refactor.yml | 2 - .../fragments/8517-cmd-runner-lang-auto.yml | 2 - ...8532-expand-opennuebula-inventory-data.yml | 2 - .../fragments/8533-add-ciphers-option.yml | 4 - .../8542-fix-proxmox-volume-handling.yml | 5 - ...cloak-clientscope-remove-id-on-compare.yml | 2 - .../fragments/8557-fix-bug-with-bitwarden.yml | 2 - .../8613-redfish_utils-language.yaml | 2 - .../8614-nsupdate-index-out-of-range.yml | 2 - changelogs/fragments/8623-become-types.yml | 2 - changelogs/fragments/8624-cache-types.yml | 2 - changelogs/fragments/8625-inventory-types.yml | 2 - changelogs/fragments/8626-lookup-types.yml | 2 - .../fragments/8627-connection-types.yml | 2 - changelogs/fragments/8628-callback-types.yml | 2 - .../8632-pkgng-add-option-use_globs.yml | 2 - .../8646-fix-bug-in-proxmox-volumes.yml | 4 - .../8648-fix-gitlab-runner-paused.yaml | 2 - .../8652-Redfish-Password-Change-Required.yml | 2 - .../fragments/8654-add-redis-tls-params.yml | 2 - ...8674-add-gitlab-project-cleanup-policy.yml | 3 - .../fragments/8675-pipx-install-suffix.yml | 2 - .../fragments/8679-fix-cloudflare-srv.yml | 2 - .../fragments/8682-locale-gen-multiple.yaml | 2 - .../8688-gitlab_project-add-new-params.yml | 4 - .../8689-passwordstore-lock-naming.yml | 2 - ...eycloak_user_federation-mapper-removal.yml | 2 - .../8708-homebrew_cask-fix-upgrade-all.yml | 2 - .../fragments/8711-gconftool2-refactor.yml | 2 - .../fragments/8713-proxmox_lxc_interfaces.yml | 2 - .../8719-openiscsi-add-multiple-targets.yaml | 2 - ...r-get-cleartext-secret-from-realm-info.yml | 2 - .../8738-limit-packages-for-copr.yml | 2 - .../8741-fix-opentelemetry-callback.yml | 2 - .../8759-gitlab_project-sort-params.yml | 2 - ...gitlab_project-add-issues-access-level.yml | 2 - ...sort-desired-and-after-mappers-by-name.yml | 2 - ...federation-fix-key-error-when-updating.yml | 2 - ..._federation-make-mapper-removal-optout.yml | 2 - changelogs/fragments/8766-mh-deco-improve.yml | 3 - .../8776-mute-vardict-deprecation.yml | 3 - ...lAttribute-to-empty-string-if-missing.yaml | 2 - ...t-fix-cleanup-policy-on-project-create.yml | 3 - .../8791-mh-cause-changes-param-depr.yml | 4 - changelogs/fragments/8793-pipx-global.yml | 12 - ...4-Fixing-possible-concatination-error.yaml | 2 - .../8796-gitlab-access-token-check-mode.yml | 3 - changelogs/fragments/8809-pipx-new-params.yml | 2 - ...emove-lastSync-param-from-kc-responses.yml | 2 - .../fragments/8814-dict-comprehension.yml | 23 - .../fragments/8822-dict-comprehension.yml | 21 - .../fragments/8823-keycloak-realm-key.yml | 2 - ...1-fix-error-when-mapper-id-is-provided.yml | 2 - .../fragments/8833-dict-comprehension.yml | 23 - .../fragments/8855-gio_mime_vardict.yml | 2 - changelogs/fragments/8856-jira_vardict.yml | 2 - .../fragments/8858-dict-comprehension.yml | 11 - changelogs/fragments/8876-dict-items-loop.yml | 16 - ...lm-sort-lists-before-change-detection.yaml | 2 - .../fragments/8885-add-force-flag-for-nmp.yml | 2 - .../fragments/8887-fix-one_service-unique.yml | 2 - .../8889-refactor-one-image-modules.yml | 6 - .../fragments/8895-fix-comprehension.yaml | 2 - .../8897-nmcli-add-reload-and-up-down.yml | 3 - ...ude-bind-credential-from-change-check.yaml | 2 - .../8900-ipa-hostgroup-fix-states.yml | 2 - changelogs/fragments/8907-fix-one-host-id.yml | 2 - .../8908-add-gitlab-group-params.yml | 2 - .../8909-flatpak-improve-name-parsing.yaml | 2 - .../fragments/8917-proxmox-clean-auth.yml | 2 - .../fragments/8920-ipa-host-fix-state.yml | 2 - ...pty-response-when-fetching-userprofile.yml | 2 - changelogs/fragments/8925-atomic.yml | 6 - .../fragments/8928-cmd-runner-10.0.0.yml | 2 - .../fragments/8929-cmd_runner-bugfix.yml | 2 - ...add-StorageId-RedfishURI-to-disk-facts.yml | 2 - ...8940-keycloak_userprofile-improve-diff.yml | 2 - .../fragments/8944-django-command-fix.yml | 3 - ...ord-store-lookup-create-subkey-support.yml | 2 - ...user-federation-add-referral-parameter.yml | 2 - ...ytes-from-the-required-parameters_list.yml | 2 - .../8964-cmd-runner-argformat-refactor.yml | 2 - .../fragments/8966-dig-add-port-option.yml | 4 - .../8970-fix-dig-multi-nameservers.yml | 2 - .../8973-keycloak_client-add-x509-auth.yml | 2 - .../8979-keycloak_group-fix-subgroups.yml | 2 - changelogs/fragments/8987-legacycrypt.yml | 3 - .../8989-github-app-token-from-fact.yml | 2 - changelogs/fragments/8990.yml | 3 - .../9010-edit-gitlab-label-color.yaml | 2 - ...ton-requires-a-job-initiated-at-reboot.yml | 4 - changelogs/fragments/9019-onevnet-bugfix.yml | 2 - .../fragments/9022-improve-homebrew-perf.yml | 2 - .../fragments/9026-consul_kv-datacenter.yml | 2 - ...upport-organizations-in-keycloak-realm.yml | 2 - ...8-bitwarden-secrets-manager-syntax-fix.yml | 2 - changelogs/fragments/9044-pipx-fixes.yml | 7 - .../fragments/9047-redfish-uri-parsing.yml | 2 - changelogs/fragments/9052-modprobe-bugfix.yml | 2 - .../fragments/9056-fix-one_image-modules.yml | 3 - ...redfish_command-updateuseraccounttypes.yml | 2 - .../9060-ansible-galaxy-install-version.yml | 2 - changelogs/fragments/9061-cpanm-version.yml | 2 - changelogs/fragments/9063-django-version.yml | 5 - .../fragments/9064-gconftool2-version.yml | 4 - .../fragments/9066-proxmox-kvm-ciupgrade.yml | 2 - .../fragments/9067-gio-mime-version.yml | 3 - .../fragments/9075-add-creation-oneimage.yml | 3 - .../9084-collection_version-importlib.yml | 2 - .../9084-jenkins_node-add-offline-message.yml | 8 - .../fragments/9086-gio-mime-version.yml | 2 - .../fragments/9087-mattermost-priority.yaml | 2 - ...ycloak-clientscope-type-fix-check-mode.yml | 2 - .../fragments/9099-proxmox-fix-insecure.yml | 2 - changelogs/fragments/deprecate-hipchat.yml | 2 - changelogs/fragments/deprecations.yml | 8 - changelogs/fragments/removals.yml | 10 - 148 files changed, 1478 insertions(+), 474 deletions(-) delete mode 100644 changelogs/fragments/10.0.0.yml delete mode 100644 changelogs/fragments/8051-Redfish-Wait-For-Service.yml delete mode 100644 changelogs/fragments/8214-sudosu-not-working-on-some-BSD-machines.yml delete mode 100644 changelogs/fragments/8402-add-diif-mode-openbsd-pkg.yml delete mode 100644 changelogs/fragments/8403-fix-typeerror-in-keycloak-client.yaml delete mode 100644 changelogs/fragments/8404-ipa_dnsrecord_sshfp.yml delete mode 100644 changelogs/fragments/8405-gitlab-remove-basic-auth.yml delete mode 100644 changelogs/fragments/8406-fix-homebrew-cask-warning.yaml delete mode 100644 changelogs/fragments/8411-locale-gen-vardict.yml delete mode 100644 changelogs/fragments/8413-galaxy-refactor.yml delete mode 100644 changelogs/fragments/8415-cmd-runner-stack.yml delete mode 100644 changelogs/fragments/8428-assign-auth-flow-by-name-keycloak-client.yaml delete mode 100644 changelogs/fragments/8430-fix-opentelemetry-when-using-logs-with-uri-or-slurp-tasks.yaml delete mode 100644 changelogs/fragments/8431-galaxy-upgrade.yml delete mode 100644 changelogs/fragments/8440-allow-api-port-specification.yaml delete mode 100644 changelogs/fragments/8444-fix-redfish-gen2-upgrade.yaml delete mode 100644 changelogs/fragments/8452-git_config-absent.yml delete mode 100644 changelogs/fragments/8453-git_config-deprecate-read.yml delete mode 100644 changelogs/fragments/8464-redis-add-cluster-info.yml delete mode 100644 changelogs/fragments/8471-proxmox-vm-info-network.yml delete mode 100644 changelogs/fragments/8476-launchd-check-mode-changed.yaml delete mode 100644 changelogs/fragments/8479-cmdrunner-improvements.yml delete mode 100644 changelogs/fragments/8480-directory-feature-cargo.yml delete mode 100644 changelogs/fragments/8489-fix-opennebula-inventory-crash-when-nic-has-no-ip.yml delete mode 100644 changelogs/fragments/8496-keycloak_clientscope-add-normalizations.yaml delete mode 100644 changelogs/fragments/8508-virtualbox-inventory.yml delete mode 100644 changelogs/fragments/8512-as-bool-not.yml delete mode 100644 changelogs/fragments/8514-pacman-empty.yml delete mode 100644 changelogs/fragments/8516-proxmox-template-refactor.yml delete mode 100644 changelogs/fragments/8517-cmd-runner-lang-auto.yml delete mode 100644 changelogs/fragments/8532-expand-opennuebula-inventory-data.yml delete mode 100644 changelogs/fragments/8533-add-ciphers-option.yml delete mode 100644 changelogs/fragments/8542-fix-proxmox-volume-handling.yml delete mode 100644 changelogs/fragments/8545-keycloak-clientscope-remove-id-on-compare.yml delete mode 100644 changelogs/fragments/8557-fix-bug-with-bitwarden.yml delete mode 100644 changelogs/fragments/8613-redfish_utils-language.yaml delete mode 100644 changelogs/fragments/8614-nsupdate-index-out-of-range.yml delete mode 100644 changelogs/fragments/8623-become-types.yml delete mode 100644 changelogs/fragments/8624-cache-types.yml delete mode 100644 changelogs/fragments/8625-inventory-types.yml delete mode 100644 changelogs/fragments/8626-lookup-types.yml delete mode 100644 changelogs/fragments/8627-connection-types.yml delete mode 100644 changelogs/fragments/8628-callback-types.yml delete mode 100644 changelogs/fragments/8632-pkgng-add-option-use_globs.yml delete mode 100644 changelogs/fragments/8646-fix-bug-in-proxmox-volumes.yml delete mode 100644 changelogs/fragments/8648-fix-gitlab-runner-paused.yaml delete mode 100644 changelogs/fragments/8652-Redfish-Password-Change-Required.yml delete mode 100644 changelogs/fragments/8654-add-redis-tls-params.yml delete mode 100644 changelogs/fragments/8674-add-gitlab-project-cleanup-policy.yml delete mode 100644 changelogs/fragments/8675-pipx-install-suffix.yml delete mode 100644 changelogs/fragments/8679-fix-cloudflare-srv.yml delete mode 100644 changelogs/fragments/8682-locale-gen-multiple.yaml delete mode 100644 changelogs/fragments/8688-gitlab_project-add-new-params.yml delete mode 100644 changelogs/fragments/8689-passwordstore-lock-naming.yml delete mode 100644 changelogs/fragments/8695-keycloak_user_federation-mapper-removal.yml delete mode 100644 changelogs/fragments/8708-homebrew_cask-fix-upgrade-all.yml delete mode 100644 changelogs/fragments/8711-gconftool2-refactor.yml delete mode 100644 changelogs/fragments/8713-proxmox_lxc_interfaces.yml delete mode 100644 changelogs/fragments/8719-openiscsi-add-multiple-targets.yaml delete mode 100644 changelogs/fragments/8735-keycloak_identity_provider-get-cleartext-secret-from-realm-info.yml delete mode 100644 changelogs/fragments/8738-limit-packages-for-copr.yml delete mode 100644 changelogs/fragments/8741-fix-opentelemetry-callback.yml delete mode 100644 changelogs/fragments/8759-gitlab_project-sort-params.yml delete mode 100644 changelogs/fragments/8760-gitlab_project-add-issues-access-level.yml delete mode 100644 changelogs/fragments/8761-keycloak_user_federation-sort-desired-and-after-mappers-by-name.yml delete mode 100644 changelogs/fragments/8762-keycloac_user_federation-fix-key-error-when-updating.yml delete mode 100644 changelogs/fragments/8764-keycloak_user_federation-make-mapper-removal-optout.yml delete mode 100644 changelogs/fragments/8766-mh-deco-improve.yml delete mode 100644 changelogs/fragments/8776-mute-vardict-deprecation.yml delete mode 100644 changelogs/fragments/8785-keycloak_user_federation-set-krbPrincipalAttribute-to-empty-string-if-missing.yaml delete mode 100644 changelogs/fragments/8790-gitlab_project-fix-cleanup-policy-on-project-create.yml delete mode 100644 changelogs/fragments/8791-mh-cause-changes-param-depr.yml delete mode 100644 changelogs/fragments/8793-pipx-global.yml delete mode 100644 changelogs/fragments/8794-Fixing-possible-concatination-error.yaml delete mode 100644 changelogs/fragments/8796-gitlab-access-token-check-mode.yml delete mode 100644 changelogs/fragments/8809-pipx-new-params.yml delete mode 100644 changelogs/fragments/8812-keycloak-user-federation-remove-lastSync-param-from-kc-responses.yml delete mode 100644 changelogs/fragments/8814-dict-comprehension.yml delete mode 100644 changelogs/fragments/8822-dict-comprehension.yml delete mode 100644 changelogs/fragments/8823-keycloak-realm-key.yml delete mode 100644 changelogs/fragments/8831-fix-error-when-mapper-id-is-provided.yml delete mode 100644 changelogs/fragments/8833-dict-comprehension.yml delete mode 100644 changelogs/fragments/8855-gio_mime_vardict.yml delete mode 100644 changelogs/fragments/8856-jira_vardict.yml delete mode 100644 changelogs/fragments/8858-dict-comprehension.yml delete mode 100644 changelogs/fragments/8876-dict-items-loop.yml delete mode 100644 changelogs/fragments/8877-keycloak_realm-sort-lists-before-change-detection.yaml delete mode 100644 changelogs/fragments/8885-add-force-flag-for-nmp.yml delete mode 100644 changelogs/fragments/8887-fix-one_service-unique.yml delete mode 100644 changelogs/fragments/8889-refactor-one-image-modules.yml delete mode 100644 changelogs/fragments/8895-fix-comprehension.yaml delete mode 100644 changelogs/fragments/8897-nmcli-add-reload-and-up-down.yml delete mode 100644 changelogs/fragments/8898-add-arg-to-exclude-bind-credential-from-change-check.yaml delete mode 100644 changelogs/fragments/8900-ipa-hostgroup-fix-states.yml delete mode 100644 changelogs/fragments/8907-fix-one-host-id.yml delete mode 100644 changelogs/fragments/8908-add-gitlab-group-params.yml delete mode 100644 changelogs/fragments/8909-flatpak-improve-name-parsing.yaml delete mode 100644 changelogs/fragments/8917-proxmox-clean-auth.yml delete mode 100644 changelogs/fragments/8920-ipa-host-fix-state.yml delete mode 100644 changelogs/fragments/8923-keycloak_userprofile-fix-empty-response-when-fetching-userprofile.yml delete mode 100644 changelogs/fragments/8925-atomic.yml delete mode 100644 changelogs/fragments/8928-cmd-runner-10.0.0.yml delete mode 100644 changelogs/fragments/8929-cmd_runner-bugfix.yml delete mode 100644 changelogs/fragments/8937-add-StorageId-RedfishURI-to-disk-facts.yml delete mode 100644 changelogs/fragments/8940-keycloak_userprofile-improve-diff.yml delete mode 100644 changelogs/fragments/8944-django-command-fix.yml delete mode 100644 changelogs/fragments/8952-password-store-lookup-create-subkey-support.yml delete mode 100644 changelogs/fragments/8954-keycloak-user-federation-add-referral-parameter.yml delete mode 100644 changelogs/fragments/8956-remove-capacitybytes-from-the-required-parameters_list.yml delete mode 100644 changelogs/fragments/8964-cmd-runner-argformat-refactor.yml delete mode 100644 changelogs/fragments/8966-dig-add-port-option.yml delete mode 100644 changelogs/fragments/8970-fix-dig-multi-nameservers.yml delete mode 100644 changelogs/fragments/8973-keycloak_client-add-x509-auth.yml delete mode 100644 changelogs/fragments/8979-keycloak_group-fix-subgroups.yml delete mode 100644 changelogs/fragments/8987-legacycrypt.yml delete mode 100644 changelogs/fragments/8989-github-app-token-from-fact.yml delete mode 100644 changelogs/fragments/8990.yml delete mode 100644 changelogs/fragments/9010-edit-gitlab-label-color.yaml delete mode 100644 changelogs/fragments/9012-dell-pwrbutton-requires-a-job-initiated-at-reboot.yml delete mode 100644 changelogs/fragments/9019-onevnet-bugfix.yml delete mode 100644 changelogs/fragments/9022-improve-homebrew-perf.yml delete mode 100644 changelogs/fragments/9026-consul_kv-datacenter.yml delete mode 100644 changelogs/fragments/9027-support-organizations-in-keycloak-realm.yml delete mode 100644 changelogs/fragments/9028-bitwarden-secrets-manager-syntax-fix.yml delete mode 100644 changelogs/fragments/9044-pipx-fixes.yml delete mode 100644 changelogs/fragments/9047-redfish-uri-parsing.yml delete mode 100644 changelogs/fragments/9052-modprobe-bugfix.yml delete mode 100644 changelogs/fragments/9056-fix-one_image-modules.yml delete mode 100644 changelogs/fragments/9059-redfish_command-updateuseraccounttypes.yml delete mode 100644 changelogs/fragments/9060-ansible-galaxy-install-version.yml delete mode 100644 changelogs/fragments/9061-cpanm-version.yml delete mode 100644 changelogs/fragments/9063-django-version.yml delete mode 100644 changelogs/fragments/9064-gconftool2-version.yml delete mode 100644 changelogs/fragments/9066-proxmox-kvm-ciupgrade.yml delete mode 100644 changelogs/fragments/9067-gio-mime-version.yml delete mode 100644 changelogs/fragments/9075-add-creation-oneimage.yml delete mode 100644 changelogs/fragments/9084-collection_version-importlib.yml delete mode 100644 changelogs/fragments/9084-jenkins_node-add-offline-message.yml delete mode 100644 changelogs/fragments/9086-gio-mime-version.yml delete mode 100644 changelogs/fragments/9087-mattermost-priority.yaml delete mode 100644 changelogs/fragments/9092-keycloak-clientscope-type-fix-check-mode.yml delete mode 100644 changelogs/fragments/9099-proxmox-fix-insecure.yml delete mode 100644 changelogs/fragments/deprecate-hipchat.yml delete mode 100644 changelogs/fragments/deprecations.yml delete mode 100644 changelogs/fragments/removals.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index b35c52441b..1abfba33a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,374 @@ -# 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\.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\.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..f23ce1a35a 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,6 +1,364 @@ -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.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/changelogs/changelog.yaml b/changelogs/changelog.yaml index 5aa97d97e9..b49fe6284a 100644 --- a/changelogs/changelog.yaml +++ b/changelogs/changelog.yaml @@ -1,3 +1,744 @@ --- 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' diff --git a/changelogs/fragments/10.0.0.yml b/changelogs/fragments/10.0.0.yml deleted file mode 100644 index 4f75197d43..0000000000 --- a/changelogs/fragments/10.0.0.yml +++ /dev/null @@ -1,2 +0,0 @@ -release_summary: |- - This is release 10.0.0 of ``community.general``, released on 2024-11-04. 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/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)." From a9755746180b48ea5d04d0e6ca02587edb756fb2 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 4 Nov 2024 19:23:07 +0100 Subject: [PATCH 003/302] Adjust nightly CI schedules. (cherry picked from commit e13d6de2508cc0601d1b7dbb4b51a3b7d50c3c20) --- .azure-pipelines/azure-pipelines.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.azure-pipelines/azure-pipelines.yml b/.azure-pipelines/azure-pipelines.yml index 97f76b3ba9..fe8624872a 100644 --- a/.azure-pipelines/azure-pipelines.yml +++ b/.azure-pipelines/azure-pipelines.yml @@ -29,14 +29,14 @@ 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 From f38d974d42943e79d932079b43638abdcaa69f93 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 4 Nov 2024 19:55:08 +0100 Subject: [PATCH 004/302] The next likely release will be 10.0.1. --- galaxy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/galaxy.yml b/galaxy.yml index 3af5356d06..7e7cd90309 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -5,7 +5,7 @@ namespace: community name: general -version: 10.0.0 +version: 10.0.1 readme: README.md authors: - Ansible (https://github.com/ansible) From 0d02265a23059d6a3ad37779d1c1c9853b272a31 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 5 Nov 2024 18:31:09 +0100 Subject: [PATCH 005/302] Remove superfluous quotation mark. --- CHANGELOG.md | 2 +- CHANGELOG.rst | 2 +- changelogs/changelog.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1abfba33a7..9c2cee7817 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -224,7 +224,7 @@ This is release 10\.0\.0 of community\.general\, released on 2024\- ### 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)\)\.\" +* 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)\)\. diff --git a/CHANGELOG.rst b/CHANGELOG.rst index f23ce1a35a..b47f58670a 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -214,7 +214,7 @@ Minor Changes 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)." +- 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). diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml index b49fe6284a..a76364b0b0 100644 --- a/changelogs/changelog.yaml +++ b/changelogs/changelog.yaml @@ -7,7 +7,7 @@ releases: - 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)." + 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`` From ac0956ed6f2cb3ba27697c985f345a38d32a03b3 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 9 Nov 2024 10:53:42 +0100 Subject: [PATCH 006/302] [PR #9104/195ae4af backport][stable-10] ipa_getkeytab: Fix example task (#9112) ipa_getkeytab: Fix example task (#9104) Fix ipa_getkeytab example task (cherry picked from commit 195ae4afdee6f58b1afe8aca382ccba998e64c0f) Co-authored-by: alexander <79072457+abakanovskii@users.noreply.github.com> --- plugins/modules/ipa_getkeytab.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/plugins/modules/ipa_getkeytab.py b/plugins/modules/ipa_getkeytab.py index 3d4f81d5b1..643e18cf62 100644 --- a/plugins/modules/ipa_getkeytab.py +++ b/plugins/modules/ipa_getkeytab.py @@ -98,11 +98,9 @@ extends_documentation_fragment: ''' EXAMPLES = r''' -- name: Get kerberos ticket - ansible.builtin.shell: kinit admin - args: - stdin: "{{ aldpro_admin_password }}" - changed_when: true +- name: Get Kerberos ticket using default principal + community.general.krb_ticket: + password: "{{ aldpro_admin_password }}" - name: Create keytab community.general.ipa_getkeytab: From a2f377c621f2cf334fe370c57d62b9e5add13da8 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 9 Nov 2024 10:53:57 +0100 Subject: [PATCH 007/302] [PR #9109/04c2ad18 backport][stable-10] Add FreeBSD 13.4 to CI (#9111) Add FreeBSD 13.4 to CI (#9109) * Add FreeBSD 13.4 to CI. * iso_extract won't work. * pkgng: jail won't work either. (cherry picked from commit 04c2ad18da28677590643176e3456f0e7be6ea1d) Co-authored-by: Felix Fontein --- .azure-pipelines/azure-pipelines.yml | 2 ++ tests/integration/targets/iso_extract/aliases | 1 + tests/integration/targets/pkgng/tasks/freebsd.yml | 5 ++++- 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/.azure-pipelines/azure-pipelines.yml b/.azure-pipelines/azure-pipelines.yml index fe8624872a..362b5d59dd 100644 --- a/.azure-pipelines/azure-pipelines.yml +++ b/.azure-pipelines/azure-pipelines.yml @@ -196,6 +196,8 @@ stages: test: rhel/9.4 - name: FreeBSD 14.1 test: freebsd/14.1 + - name: FreeBSD 13.4 + test: freebsd/13.4 groups: - 1 - 2 diff --git a/tests/integration/targets/iso_extract/aliases b/tests/integration/targets/iso_extract/aliases index 27e07941a5..0fee9ee2e1 100644 --- a/tests/integration/targets/iso_extract/aliases +++ b/tests/integration/targets/iso_extract/aliases @@ -15,5 +15,6 @@ skip/rhel9.4 # FIXME skip/freebsd12.4 # FIXME skip/freebsd13.2 # FIXME skip/freebsd13.3 # FIXME +skip/freebsd13.4 # FIXME skip/freebsd14.0 # FIXME skip/freebsd14.1 # FIXME diff --git a/tests/integration/targets/pkgng/tasks/freebsd.yml b/tests/integration/targets/pkgng/tasks/freebsd.yml index e69d26c20d..612e7c4d42 100644 --- a/tests/integration/targets/pkgng/tasks/freebsd.yml +++ b/tests/integration/targets/pkgng/tasks/freebsd.yml @@ -518,6 +518,9 @@ # NOTE: FreeBSD 13.3 fails to update the package catalogue for unknown reasons (someone with FreeBSD # knowledge has to take a look) # + # NOTE: FreeBSD 13.4 fails to update the package catalogue for unknown reasons (someone with FreeBSD + # knowledge has to take a look) + # # NOTE: FreeBSD 14.0 fails to update the package catalogue for unknown reasons (someone with FreeBSD # knowledge has to take a look) # @@ -528,7 +531,7 @@ # https://github.com/ansible-collections/community.general/issues/5795 when: >- (ansible_distribution_version is version('12.01', '>=') and ansible_distribution_version is version('12.3', '<')) - or (ansible_distribution_version is version('13.4', '>=') and ansible_distribution_version is version('14.0', '<')) + or (ansible_distribution_version is version('13.5', '>=') and ansible_distribution_version is version('14.0', '<')) or ansible_distribution_version is version('14.2', '>=') block: - name: Setup testjail From 411c7d4f322123a24f6606adae593c7fbf42d68e Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 11 Nov 2024 20:11:34 +0100 Subject: [PATCH 008/302] [PR #9082/d27d86ec backport][stable-10] keycloak_clientscope: remove code turning attributes dict into list (#9118) keycloak_clientscope: remove code turning attributes dict into list (#9082) * remove code turning attributes dict into list * add changelog fragment (cherry picked from commit d27d86ecb108c391aa7c8153e9944a8369f8d065) Co-authored-by: fgruenbauer --- ...lientscope-fix-attributes-dict-turned-into-list.yml | 2 ++ plugins/modules/keycloak_clientscope.py | 10 ---------- 2 files changed, 2 insertions(+), 10 deletions(-) create mode 100644 changelogs/fragments/9082-keycloak_clientscope-fix-attributes-dict-turned-into-list.yml diff --git a/changelogs/fragments/9082-keycloak_clientscope-fix-attributes-dict-turned-into-list.yml b/changelogs/fragments/9082-keycloak_clientscope-fix-attributes-dict-turned-into-list.yml new file mode 100644 index 0000000000..c9d61780b2 --- /dev/null +++ b/changelogs/fragments/9082-keycloak_clientscope-fix-attributes-dict-turned-into-list.yml @@ -0,0 +1,2 @@ +bugfixes: + - 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). \ No newline at end of file diff --git a/plugins/modules/keycloak_clientscope.py b/plugins/modules/keycloak_clientscope.py index 576a831bdb..35ac3d9500 100644 --- a/plugins/modules/keycloak_clientscope.py +++ b/plugins/modules/keycloak_clientscope.py @@ -317,9 +317,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']: @@ -418,13 +415,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': From 8226ea87cfadddf1d97874a25521990289da1e81 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 11 Nov 2024 20:12:09 +0100 Subject: [PATCH 009/302] [PR #9077/62cb6087 backport][stable-10] keycloak_client: remove code that turns attributes dict into list (#9116) keycloak_client: remove code that turns attributes dict into list (#9077) * remove code that turns attributes dict into list * add changelog fragment * Update changelogs/fragments/9077-keycloak_client-fix-attributes-dict-turned-into-list.yml Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 62cb6087b59064798a51fb90958300827343fdce) Co-authored-by: fgruenbauer --- ...oak_client-fix-attributes-dict-turned-into-list.yml | 2 ++ plugins/modules/keycloak_client.py | 10 ---------- 2 files changed, 2 insertions(+), 10 deletions(-) create mode 100644 changelogs/fragments/9077-keycloak_client-fix-attributes-dict-turned-into-list.yml diff --git a/changelogs/fragments/9077-keycloak_client-fix-attributes-dict-turned-into-list.yml b/changelogs/fragments/9077-keycloak_client-fix-attributes-dict-turned-into-list.yml new file mode 100644 index 0000000000..d693c2e139 --- /dev/null +++ b/changelogs/fragments/9077-keycloak_client-fix-attributes-dict-turned-into-list.yml @@ -0,0 +1,2 @@ +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). \ No newline at end of file diff --git a/plugins/modules/keycloak_client.py b/plugins/modules/keycloak_client.py index d2800be292..62015bc79f 100644 --- a/plugins/modules/keycloak_client.py +++ b/plugins/modules/keycloak_client.py @@ -805,9 +805,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'])) @@ -1024,13 +1021,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': From 5c26387a54261c644c19976803880ded2baaeba5 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 11 Nov 2024 20:12:31 +0100 Subject: [PATCH 010/302] Prepare 10.0.1 release. --- changelogs/fragments/10.0.1.yml | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/fragments/10.0.1.yml diff --git a/changelogs/fragments/10.0.1.yml b/changelogs/fragments/10.0.1.yml new file mode 100644 index 0000000000..efe699002d --- /dev/null +++ b/changelogs/fragments/10.0.1.yml @@ -0,0 +1 @@ +release_summary: Bugfix release for inclusion in Ansible 11.0.0rc1. From 10561e6f302c40a734b8c9a91b3a5d39a570c375 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 11 Nov 2024 20:13:27 +0100 Subject: [PATCH 011/302] [PR #9114/bafb8aca backport][stable-10] redfish_utils: remove undocumented default applytime (#9120) redfish_utils: remove undocumented default applytime (#9114) * redfish_utils: remove undocumented default applytime The `@Redfish.OperationApplyTime` parameter is optional as per Redfish spec version 1.21.0, paragraph 7.11 [1]. Some systems reject the request rather than ignore it, causing failures that can not be workarounded. Removing this default resolves compatibility issues. [1] https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.21.0.html Signed-off-by: Tan Siewert * redfish_utils: fix changelog fragment to bugfix Signed-off-by: Tan Siewert --------- Signed-off-by: Tan Siewert (cherry picked from commit bafb8aca292dfb365a6386cc52e4de40f8e6bfc6) Co-authored-by: Tan Siewert --- .../9114-redfish-utils-update-remove-default-applytime.yml | 2 ++ plugins/module_utils/redfish_utils.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9114-redfish-utils-update-remove-default-applytime.yml diff --git a/changelogs/fragments/9114-redfish-utils-update-remove-default-applytime.yml b/changelogs/fragments/9114-redfish-utils-update-remove-default-applytime.yml new file mode 100644 index 0000000000..672545a0a8 --- /dev/null +++ b/changelogs/fragments/9114-redfish-utils-update-remove-default-applytime.yml @@ -0,0 +1,2 @@ +bugfixes: + - redfish_utils module utils - remove undocumented default applytime (https://github.com/ansible-collections/community.general/pull/9114). diff --git a/plugins/module_utils/redfish_utils.py b/plugins/module_utils/redfish_utils.py index f795eac6cd..9f638c51f4 100644 --- a/plugins/module_utils/redfish_utils.py +++ b/plugins/module_utils/redfish_utils.py @@ -1958,7 +1958,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: From eb4c01260f0ae7dec6f515c09374c93e3577e957 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 11 Nov 2024 20:14:29 +0100 Subject: [PATCH 012/302] Release 10.0.1. --- CHANGELOG.md | 26 ++++++++++++++++--- CHANGELOG.rst | 15 +++++++++++ changelogs/changelog.yaml | 16 ++++++++++++ changelogs/fragments/10.0.1.yml | 1 - ...t-fix-attributes-dict-turned-into-list.yml | 2 -- ...e-fix-attributes-dict-turned-into-list.yml | 2 -- ...-utils-update-remove-default-applytime.yml | 2 -- 7 files changed, 53 insertions(+), 11 deletions(-) delete mode 100644 changelogs/fragments/10.0.1.yml delete mode 100644 changelogs/fragments/9077-keycloak_client-fix-attributes-dict-turned-into-list.yml delete mode 100644 changelogs/fragments/9082-keycloak_clientscope-fix-attributes-dict-turned-into-list.yml delete mode 100644 changelogs/fragments/9114-redfish-utils-update-remove-default-applytime.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c2cee7817..abcdfa6d64 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,13 +2,16 @@ **Topics** -- v10\.0\.0 +- v10\.0\.1 - Release Summary + - Bugfixes +- v10\.0\.0 + - Release Summary - Minor Changes - Breaking Changes / Porting Guide - Deprecated Features - Removed Features \(previously deprecated\) - - Bugfixes + - Bugfixes - Known Issues - New Plugins - Filter @@ -16,10 +19,25 @@ - New Modules This changelog describes changes after version 9\.0\.0\. + +## 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\. @@ -254,7 +272,7 @@ This is release 10\.0\.0 of community\.general\, released on 2024\- * 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)\)\. diff --git a/CHANGELOG.rst b/CHANGELOG.rst index b47f58670a..7e920aa9fb 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -6,6 +6,21 @@ Community General Release Notes This changelog describes changes after version 9.0.0. +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 ======= diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml index a76364b0b0..cbbaa1a49b 100644 --- a/changelogs/changelog.yaml +++ b/changelogs/changelog.yaml @@ -742,3 +742,19 @@ releases: 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' diff --git a/changelogs/fragments/10.0.1.yml b/changelogs/fragments/10.0.1.yml deleted file mode 100644 index efe699002d..0000000000 --- a/changelogs/fragments/10.0.1.yml +++ /dev/null @@ -1 +0,0 @@ -release_summary: Bugfix release for inclusion in Ansible 11.0.0rc1. diff --git a/changelogs/fragments/9077-keycloak_client-fix-attributes-dict-turned-into-list.yml b/changelogs/fragments/9077-keycloak_client-fix-attributes-dict-turned-into-list.yml deleted file mode 100644 index d693c2e139..0000000000 --- a/changelogs/fragments/9077-keycloak_client-fix-attributes-dict-turned-into-list.yml +++ /dev/null @@ -1,2 +0,0 @@ -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). \ No newline at end of file diff --git a/changelogs/fragments/9082-keycloak_clientscope-fix-attributes-dict-turned-into-list.yml b/changelogs/fragments/9082-keycloak_clientscope-fix-attributes-dict-turned-into-list.yml deleted file mode 100644 index c9d61780b2..0000000000 --- a/changelogs/fragments/9082-keycloak_clientscope-fix-attributes-dict-turned-into-list.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - 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). \ No newline at end of file diff --git a/changelogs/fragments/9114-redfish-utils-update-remove-default-applytime.yml b/changelogs/fragments/9114-redfish-utils-update-remove-default-applytime.yml deleted file mode 100644 index 672545a0a8..0000000000 --- a/changelogs/fragments/9114-redfish-utils-update-remove-default-applytime.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - redfish_utils module utils - remove undocumented default applytime (https://github.com/ansible-collections/community.general/pull/9114). From 48db44f199435118ff4d3078f9af09151529c907 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 11 Nov 2024 20:53:44 +0100 Subject: [PATCH 013/302] Next release might be 10.0.2 or 10.1.0. --- galaxy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/galaxy.yml b/galaxy.yml index 7e7cd90309..85b4c896ff 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -5,7 +5,7 @@ namespace: community name: general -version: 10.0.1 +version: 10.0.2 readme: README.md authors: - Ansible (https://github.com/ansible) From 88b1fbbdf013606b444b966eacc17c6f3706ee80 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 16 Nov 2024 19:14:51 +0100 Subject: [PATCH 014/302] [PR #9128/9596995f backport][stable-10] homebrew_cask: add + to valid cask chars (#9135) homebrew_cask: add + to valid cask chars (#9128) * fix(homebrew_cask): add + to valid cask chars * docs(homebrew_cask): add changelog fragment Signed-off-by: Ben Dronen * fix(homebrew_cask): add PR link to changelog fragment Signed-off-by: Ben Dronen * fix: add period to end of changelog fragment Signed-off-by: Ben Dronen * fix: remove blank line from changelog fragment Signed-off-by: Ben Dronen * fix: changelog fragment formatting Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * Update changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml Co-authored-by: Felix Fontein --------- Signed-off-by: Ben Dronen Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> Co-authored-by: Felix Fontein (cherry picked from commit 9596995ffc2972a8edf72e6532d04eb0d83b97c2) Co-authored-by: dronenb --- changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml | 2 ++ plugins/modules/homebrew_cask.py | 1 + 2 files changed, 3 insertions(+) create mode 100644 changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml diff --git a/changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml b/changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml new file mode 100644 index 0000000000..69765958fb --- /dev/null +++ b/changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml @@ -0,0 +1,2 @@ +bugfixes: + - homebrew_cask - allow ``+`` symbol in Homebrew cask name validation regex (https://github.com/ansible-collections/community.general/pull/9128). diff --git a/plugins/modules/homebrew_cask.py b/plugins/modules/homebrew_cask.py index 9902cb1373..83901b4dbe 100644 --- a/plugins/modules/homebrew_cask.py +++ b/plugins/modules/homebrew_cask.py @@ -190,6 +190,7 @@ class HomebrewCask(object): / # slash (for taps) \- # dashes @ # at symbol + \+ # plus symbol ''' INVALID_CASK_REGEX = _create_regex_group_complement(VALID_CASK_CHARS) From c9160521244d503e3a407f937ad88667580fb4d5 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 16 Nov 2024 19:15:02 +0100 Subject: [PATCH 015/302] [PR #9123/1f786a61 backport][stable-10] redfish_command: add update_custom_oem options (#9136) redfish_command: add update_custom_oem options (#9123) * redfish_command: add update_custom_oem options The Multipart HTTP push update implementation allows OEM specific parts that are not part of the `UpdateParameters` body part, but a separate one. This OEM part shall start with `Oem` and is optional. The OEM part implementation is specified in the Redfish spec point 12.6.2.2 [1]. Right now, the implementation will only support JSON as MIME Type, although it is not limited to JSON. [1] https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.21.0.html#oem Signed-off-by: Tan Siewert * redfish_command: add option to set custom mime type The implementation of using a custom MIME type will also remove the default JSON type. Converting the payload to JSON or any other type is up to the user. Signed-off-by: Tan Siewert * redfish_command: apply docs changes from review Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * redfish_command: add mime type option to changelog Co-authored-by: Felix Fontein --------- Signed-off-by: Tan Siewert Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> Co-authored-by: Felix Fontein (cherry picked from commit 1f786a6171c1fc357e50fed2c9d725b51350ec1d) Co-authored-by: Tan Siewert --- ...9123-redfish-command-custom-oem-params.yml | 2 + plugins/module_utils/redfish_utils.py | 8 +++ plugins/modules/redfish_command.py | 54 +++++++++++++++++++ 3 files changed, 64 insertions(+) create mode 100644 changelogs/fragments/9123-redfish-command-custom-oem-params.yml diff --git a/changelogs/fragments/9123-redfish-command-custom-oem-params.yml b/changelogs/fragments/9123-redfish-command-custom-oem-params.yml new file mode 100644 index 0000000000..a09219515a --- /dev/null +++ b/changelogs/fragments/9123-redfish-command-custom-oem-params.yml @@ -0,0 +1,2 @@ +minor_changes: + - 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). diff --git a/plugins/module_utils/redfish_utils.py b/plugins/module_utils/redfish_utils.py index 9f638c51f4..388fc93669 100644 --- a/plugins/module_utils/redfish_utils.py +++ b/plugins/module_utils/redfish_utils.py @@ -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: @@ -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 diff --git a/plugins/modules/redfish_command.py b/plugins/modules/redfish_command.py index 103f9e1d50..829b77897d 100644 --- a/plugins/modules/redfish_command.py +++ b/plugins/modules/redfish_command.py @@ -216,6 +216,36 @@ 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: @@ -654,6 +684,23 @@ EXAMPLES = ''' update_oem_params: PreserveConfiguration: false + - 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: Perform requested operations to continue the update community.general.redfish_command: category: Update @@ -863,6 +910,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 +945,7 @@ def main(): ), required_together=[ ('username', 'password'), + ('update_custom_oem_header', 'update_custom_oem_params'), ], required_one_of=[ ('username', 'auth_token'), @@ -941,6 +992,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'], } From 776374ee789c2fa258f821484896e6506a21526d Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 16 Nov 2024 19:15:12 +0100 Subject: [PATCH 016/302] [PR #9102/737717d0 backport][stable-10] launchd: Add plist option (#9137) launchd: Add plist option (#9102) This allows the module to be used with services such as com.openssh.sshd, when the name of the plist file doesn't match the service name. fixes #5932 (cherry picked from commit 737717d015f5e8ab6878662cacfa82cd39cd0e07) Co-authored-by: Alex Willmer --- changelogs/fragments/5932-launchd-plist.yml | 2 ++ plugins/modules/launchd.py | 31 +++++++++++++++++---- 2 files changed, 27 insertions(+), 6 deletions(-) create mode 100644 changelogs/fragments/5932-launchd-plist.yml diff --git a/changelogs/fragments/5932-launchd-plist.yml b/changelogs/fragments/5932-launchd-plist.yml new file mode 100644 index 0000000000..bf2530841a --- /dev/null +++ b/changelogs/fragments/5932-launchd-plist.yml @@ -0,0 +1,2 @@ +minor_changes: + - 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). diff --git a/plugins/modules/launchd.py b/plugins/modules/launchd.py index a6427bdb2f..9717825c71 100644 --- a/plugins/modules/launchd.py +++ b/plugins/modules/launchd.py @@ -30,6 +30,12 @@ options: - Name of the service. 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 @@ -100,6 +106,12 @@ EXAMPLES = r''' community.general.launchd: name: org.memcached state: unloaded + +- name: restart sshd + community.general.launchd: + name: com.openssh.sshd + plist: ssh.plist + state: restarted ''' RETURN = r''' @@ -145,25 +157,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 +198,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 +478,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 +490,7 @@ def main(): ) service = module.params['name'] + plist_filename = module.params['plist'] action = module.params['state'] rc = 0 out = err = '' @@ -483,7 +502,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. From 5a1c68cb6206d44d6e780a3d765b0523a26a4dbe Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 16 Nov 2024 19:15:22 +0100 Subject: [PATCH 017/302] [PR #9096/523439ab backport][stable-10] alternatives: add support for "family" parameter (#9138) alternatives: add support for "family" parameter (#9096) * alternatives: added parsing and setting of 'family' for an alternative * alternatives: added checks for path nullability * alternatives: added idempotence when setting alternative using family * alternatives: added family to diff mode * alternatives: added tests for family * alternatives: updated documentation and examples * alternatives: added constraints for 'path' and 'family' parameters. in any invariants at least one of the parameters must be specified * alternatives: added changelog fragment * removed unnecessary check * added version Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 523439ab629eb942073de749b1ef2a1e0becd836) Co-authored-by: Stanislav Shamilov --- ...9096-alternatives-add-family-parameter.yml | 2 + plugins/modules/alternatives.py | 60 +++++++++++++---- .../targets/alternatives/tasks/main.yml | 6 ++ .../alternatives/tasks/tests_family.yml | 65 +++++++++++++++++++ 4 files changed, 120 insertions(+), 13 deletions(-) create mode 100644 changelogs/fragments/9096-alternatives-add-family-parameter.yml create mode 100644 tests/integration/targets/alternatives/tasks/tests_family.yml diff --git a/changelogs/fragments/9096-alternatives-add-family-parameter.yml b/changelogs/fragments/9096-alternatives-add-family-parameter.yml new file mode 100644 index 0000000000..a0b021f892 --- /dev/null +++ b/changelogs/fragments/9096-alternatives-add-family-parameter.yml @@ -0,0 +1,2 @@ +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). diff --git a/plugins/modules/alternatives.py b/plugins/modules/alternatives.py index da578276fa..d049c82b11 100644 --- a/plugins/modules/alternatives.py +++ b/plugins/modules/alternatives.py @@ -39,7 +39,11 @@ 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. @@ -98,6 +102,12 @@ EXAMPLES = r''' 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 @@ -182,17 +192,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 +231,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 +248,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 +269,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 +304,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 +352,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 +377,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 +415,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 +431,7 @@ def main(): )), ), supports_check_mode=True, + required_one_of=[('path', 'family')] ) AlternativesModule(module) diff --git a/tests/integration/targets/alternatives/tasks/main.yml b/tests/integration/targets/alternatives/tasks/main.yml index 81d6a7b0df..cd86b085d4 100644 --- a/tests/integration/targets/alternatives/tasks/main.yml +++ b/tests/integration/targets/alternatives/tasks/main.yml @@ -58,6 +58,12 @@ - include_tasks: remove_links.yml - include_tasks: tests_state.yml + # Test for the family parameter + - block: + - include_tasks: remove_links.yml + - include_tasks: tests_family.yml + when: ansible_os_family == 'RedHat' + # Cleanup always: - include_tasks: remove_links.yml diff --git a/tests/integration/targets/alternatives/tasks/tests_family.yml b/tests/integration/targets/alternatives/tasks/tests_family.yml new file mode 100644 index 0000000000..ac4eadebe1 --- /dev/null +++ b/tests/integration/targets/alternatives/tasks/tests_family.yml @@ -0,0 +1,65 @@ +--- +# 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 + +- name: Add an alternative with a family + alternatives: + name: dummy + path: /usr/bin/dummy1 + link: /usr/bin/dummy + family: family1 + priority: 100 + state: selected + +- name: Ensure that the alternative has family assigned + shell: 'grep family1 {{ alternatives_dir }}/dummy' + +- name: Add two alternatives with different families + alternatives: + name: dummy + path: '/usr/bin/dummy{{ item.n }}' + link: /usr/bin/dummy + family: family2 + priority: "{{ item.priority }}" + state: present + loop: + - { n: 2, priority: 20 } + - { n: 3, priority: 10 } + - { n: 4, priority: 5 } + +# Here we select the whole family of alternatives +- name: Set family as an alternatives + alternatives: + name: dummy + family: family2 + state: selected + +- name: Ensure manual mode + shell: 'head -n1 {{ alternatives_dir }}/dummy | grep "^manual"' + +- name: Execute the current dummy command + shell: dummy + register: cmd + +# Despite the fact that there is alternative with higher priority (/usr/bin/dummy1), +# it is not chosen as it doesn't belong to the selected family +- name: Ensure that the alternative from the selected family is used + assert: + that: + - cmd.stdout == "dummy2" + +- name: Remove the alternative with the highest priority that belongs to the family + alternatives: + name: dummy + path: '/usr/bin/dummy2' + state: absent + +- name: Execute the current dummy command + shell: dummy + register: cmd + +- name: Ensure that the next alternative is selected as having the highest priority from the family + assert: + that: + - cmd.stdout == "dummy3" From acb6a2f76d8fcf3abf0ffefc345e0608e48922ba Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 16 Nov 2024 19:15:31 +0100 Subject: [PATCH 018/302] [PR #9076/626c0e10 backport][stable-10] Remove redundant `HomebrewValidate.valid_package` calls in homebrew module. (#9139) Remove redundant `HomebrewValidate.valid_package` calls in homebrew module. (#9076) * Remove redundant `HomebrewValidate.valid_package` calls * Add changelog fragment (cherry picked from commit 626c0e104975f2bfe1c85e8816f4b64594e06bed) Co-authored-by: Thibaut Decombe <68703331+UnknownPlatypus@users.noreply.github.com> --- ...cated-homebrew-package-name-validation.yml | 2 + plugins/modules/homebrew.py | 37 +------------------ 2 files changed, 3 insertions(+), 36 deletions(-) create mode 100644 changelogs/fragments/9076-remove-duplicated-homebrew-package-name-validation.yml diff --git a/changelogs/fragments/9076-remove-duplicated-homebrew-package-name-validation.yml b/changelogs/fragments/9076-remove-duplicated-homebrew-package-name-validation.yml new file mode 100644 index 0000000000..b067625c0c --- /dev/null +++ b/changelogs/fragments/9076-remove-duplicated-homebrew-package-name-validation.yml @@ -0,0 +1,2 @@ +minor_changes: + - homebrew - remove duplicated package name validation (https://github.com/ansible-collections/community.general/pull/9076). diff --git a/plugins/modules/homebrew.py b/plugins/modules/homebrew.py index 58b13f83d4..bc5d8649e7 100644 --- a/plugins/modules/homebrew.py +++ b/plugins/modules/homebrew.py @@ -401,11 +401,6 @@ class Homebrew(object): # 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", @@ -424,9 +419,6 @@ class Homebrew(object): 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', @@ -436,9 +428,7 @@ class Homebrew(object): 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(): + if not self._current_package_is_installed(): return False rc, out, err = self.module.run_command([ @@ -534,11 +524,6 @@ class Homebrew(object): # 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) - if self._current_package_is_installed(): self.unchanged_count += 1 self.unchanged_pkgs.append(self.current_package) @@ -595,11 +580,6 @@ class Homebrew(object): 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' @@ -667,11 +647,6 @@ class Homebrew(object): # 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) - if not self._current_package_is_installed(): self.unchanged_count += 1 self.unchanged_pkgs.append(self.current_package) @@ -716,11 +691,6 @@ class Homebrew(object): # linked --------------------------------- {{{ def _link_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) - if not self._current_package_is_installed(): self.failed = True self.message = 'Package not installed: {0}.'.format(self.current_package) @@ -763,11 +733,6 @@ class Homebrew(object): # unlinked ------------------------------- {{{ def _unlink_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) - if not self._current_package_is_installed(): self.failed = True self.message = 'Package not installed: {0}.'.format(self.current_package) From a20ee0e816d8d7e9f52f5d48202b61594d18d54e Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sun, 17 Nov 2024 20:19:55 +0000 Subject: [PATCH 019/302] [PR #9124/36c7e560 backport][stable-10] dnf_config_manager: use --assumeyes when changing state (#9142) dnf_config_manager: use --assumeyes when changing state (#9124) * dnf_config_manager: use --assumeyesm when changing state * changelog fragment * update tests * format fix * Update changelogs/fragments/9124-dnf_config_manager.yml Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --------- Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> (cherry picked from commit 36c7e56005b2e78dff9bec3b3a605e5834661128) Co-authored-by: Andrew Hyatt <4400272+ahyattdev@users.noreply.github.com> --- changelogs/fragments/9124-dnf_config_manager.yml | 2 ++ plugins/modules/dnf_config_manager.py | 2 +- tests/unit/plugins/modules/test_dnf_config_manager.py | 4 ++-- 3 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/9124-dnf_config_manager.yml diff --git a/changelogs/fragments/9124-dnf_config_manager.yml b/changelogs/fragments/9124-dnf_config_manager.yml new file mode 100644 index 0000000000..9c87f02d64 --- /dev/null +++ b/changelogs/fragments/9124-dnf_config_manager.yml @@ -0,0 +1,2 @@ +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). diff --git a/plugins/modules/dnf_config_manager.py b/plugins/modules/dnf_config_manager.py index 069fd0ddc7..9ec439c225 100644 --- a/plugins/modules/dnf_config_manager.py +++ b/plugins/modules/dnf_config_manager.py @@ -153,7 +153,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): diff --git a/tests/unit/plugins/modules/test_dnf_config_manager.py b/tests/unit/plugins/modules/test_dnf_config_manager.py index 90bffe4365..7b231e10a5 100644 --- a/tests/unit/plugins/modules/test_dnf_config_manager.py +++ b/tests/unit/plugins/modules/test_dnf_config_manager.py @@ -254,8 +254,8 @@ expected_repo_states_crb_disabled = {'disabled': ['appstream-debuginfo', 'rpmfusion-nonfree-updates']} call_get_repo_states = call(['/usr/bin/dnf', 'repolist', '--all', '--verbose'], check_rc=True) -call_disable_crb = call(['/usr/bin/dnf', 'config-manager', '--set-disabled', 'crb'], check_rc=True) -call_enable_crb = call(['/usr/bin/dnf', 'config-manager', '--set-enabled', 'crb'], check_rc=True) +call_disable_crb = call(['/usr/bin/dnf', 'config-manager', '--assumeyes', '--set-disabled', 'crb'], check_rc=True) +call_enable_crb = call(['/usr/bin/dnf', 'config-manager', '--assumeyes', '--set-enabled', 'crb'], check_rc=True) class TestDNFConfigManager(ModuleTestCase): From cd06325f6bd18e1b5f765af01ea0c5c104dec3e0 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 18 Nov 2024 19:49:23 +0100 Subject: [PATCH 020/302] [PR #9143/2a66ac71 backport][stable-10] build(deps): bump fsfe/reuse-action from 4 to 5 (#9148) build(deps): bump fsfe/reuse-action from 4 to 5 (#9143) Bumps [fsfe/reuse-action](https://github.com/fsfe/reuse-action) from 4 to 5. - [Release notes](https://github.com/fsfe/reuse-action/releases) - [Commits](https://github.com/fsfe/reuse-action/compare/v4...v5) --- updated-dependencies: - dependency-name: fsfe/reuse-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> (cherry picked from commit 2a66ac719a618fb24098611263b6aeb3a850ba44) Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/reuse.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/reuse.yml b/.github/workflows/reuse.yml index e5195f6dcf..7c6f76bd5b 100644 --- a/.github/workflows/reuse.yml +++ b/.github/workflows/reuse.yml @@ -31,4 +31,4 @@ jobs: ref: ${{ github.event.pull_request.head.sha || '' }} - name: REUSE Compliance Check - uses: fsfe/reuse-action@v4 + uses: fsfe/reuse-action@v5 From a6f6bcc5557c6e5fa6df242e67a743e1c8d0d019 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 18 Nov 2024 20:58:50 +0100 Subject: [PATCH 021/302] [PR #9145/dc856ab6 backport][stable-10] filters/dict: document the correct return value (#9151) filters/dict: document the correct return value (#9145) (cherry picked from commit dc856ab6fe5667c79621d178dffd31f2e78347d4) Co-authored-by: Max Gautier --- plugins/filter/dict.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/filter/dict.py b/plugins/filter/dict.py index 720c9def96..3e0558bb61 100644 --- a/plugins/filter/dict.py +++ b/plugins/filter/dict.py @@ -57,8 +57,8 @@ EXAMPLES = ''' RETURN = ''' _value: - description: The dictionary having the provided key-value pairs. - type: boolean + description: A dictionary with the provided key-value pairs. + type: dictionary ''' From 06c7ba640ef0397ab6ea4cd1b4ff4187b514d0ed Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 19 Nov 2024 20:17:12 +0100 Subject: [PATCH 022/302] [PR #9144/54194ccb backport][stable-10] modprobe: document when 'persistent' was added. (#9156) modprobe: document when 'persistent' was added. (#9144) This is based on `git tag --contains 29f5033737a7fd86349ff3daab7d7ee7db66ad00`. (cherry picked from commit 54194ccb2427cccf282eea1a20294dd794ce77dc) Co-authored-by: Max Gautier --- plugins/modules/modprobe.py | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/modules/modprobe.py b/plugins/modules/modprobe.py index 57e682245f..3d6a7c2410 100644 --- a/plugins/modules/modprobe.py +++ b/plugins/modules/modprobe.py @@ -46,6 +46,7 @@ options: 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. From 4455df380e606e987987c35c877153ae9c5a8017 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 20 Nov 2024 19:30:35 +0100 Subject: [PATCH 023/302] [PR #9157/4b0d5cb8 backport][stable-10] dnf_config_manager: fix parsing for non-english locales (#9166) dnf_config_manager: fix parsing for non-english locales (#9157) * dnf_config_manager: forces locale to 'C' when the module starts * adds changelog fragment * Apply suggestions from code review Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --------- Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> (cherry picked from commit 4b0d5cb8cfc9722d62ba35de9367109d1bf2f18f) Co-authored-by: Stanislav Shamilov --- changelogs/fragments/9157-fix-dnf_config_manager-locale.yml | 2 ++ plugins/modules/dnf_config_manager.py | 1 + 2 files changed, 3 insertions(+) create mode 100644 changelogs/fragments/9157-fix-dnf_config_manager-locale.yml diff --git a/changelogs/fragments/9157-fix-dnf_config_manager-locale.yml b/changelogs/fragments/9157-fix-dnf_config_manager-locale.yml new file mode 100644 index 0000000000..f2084dfa5f --- /dev/null +++ b/changelogs/fragments/9157-fix-dnf_config_manager-locale.yml @@ -0,0 +1,2 @@ +bugfixes: + - 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). \ No newline at end of file diff --git a/plugins/modules/dnf_config_manager.py b/plugins/modules/dnf_config_manager.py index 9ec439c225..aa2571d9f0 100644 --- a/plugins/modules/dnf_config_manager.py +++ b/plugins/modules/dnf_config_manager.py @@ -186,6 +186,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) From 16d124bbe27f527a48a366f79c53ec1dfa7aa4ab Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 20 Nov 2024 19:31:35 +0100 Subject: [PATCH 024/302] [PR #9152/5a971587 backport][stable-10] Update docs for github_app_access_token.py (#9164) Update docs for github_app_access_token.py (#9152) * Update github_app_access_token.py updating docs - github_token missing {{ }} * Update plugins/lookup/github_app_access_token.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 5a9715874af655d0b3f7180bcd2775987c3fef7f) Co-authored-by: Ian Richardson <126898943+PredatarIan@users.noreply.github.com> --- plugins/lookup/github_app_access_token.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/lookup/github_app_access_token.py b/plugins/lookup/github_app_access_token.py index 1d3c526c33..cee635fc0a 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 = ''' From 653ae1b48ab76346bbc1accde9bdc6a8e77f6197 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 21 Nov 2024 21:42:48 +0100 Subject: [PATCH 025/302] [PR #9113/8078a08f backport][stable-10] Add server-side artifact fetching to proxmox_template module (#9169) Add server-side artifact fetching to proxmox_template module (#9113) * Add server-side artifact fetching to proxmox_template module * Update docs, format per feedback. * Formatting plugins/modules/proxmox_template.py Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --------- Co-authored-by: spencer Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> (cherry picked from commit 8078a08f72eb4b327bdf3cd6c58f87f28e884177) Co-authored-by: Spencer Boyer --- ...support-server-side-artifact-fetching.yaml | 2 + plugins/modules/proxmox_template.py | 75 ++++++++++++++++--- 2 files changed, 65 insertions(+), 12 deletions(-) create mode 100644 changelogs/fragments/7402-proxmox-template-support-server-side-artifact-fetching.yaml diff --git a/changelogs/fragments/7402-proxmox-template-support-server-side-artifact-fetching.yaml b/changelogs/fragments/7402-proxmox-template-support-server-side-artifact-fetching.yaml new file mode 100644 index 0000000000..4a5fefdc96 --- /dev/null +++ b/changelogs/fragments/7402-proxmox-template-support-server-side-artifact-fetching.yaml @@ -0,0 +1,2 @@ +minor_changes: + - proxmox_template - add server side artifact fetching support (https://github.com/ansible-collections/community.general/pull/9113). \ No newline at end of file diff --git a/plugins/modules/proxmox_template.py b/plugins/modules/proxmox_template.py index 134286164c..876e8a6847 100644 --- a/plugins/modules/proxmox_template.py +++ b/plugins/modules/proxmox_template.py @@ -30,8 +30,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. @@ -85,6 +91,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 +119,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 @@ -132,6 +157,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 REQUESTS_TOOLBELT_ERR = None try: @@ -179,6 +205,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) @@ -205,6 +242,7 @@ def main(): 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'), @@ -218,7 +256,8 @@ def main(): argument_spec=module_args, required_together=[('api_token_id', 'api_token_secret')], required_one_of=[('api_password', 'api_token_id')], - required_if=[('state', 'absent', ['template'])] + required_if=[('state', 'absent', ['template'])], + mutually_exclusive=[("src", "url")], ) proxmox = ProxmoxTemplateAnsible(module) @@ -231,9 +270,10 @@ def main(): 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 +285,27 @@ 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 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: From 0ff52abfddd364f6b76ff6fa70cfd6f454b3f200 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 23 Nov 2024 15:18:34 +0100 Subject: [PATCH 026/302] [PR #9171/152339a8 backport][stable-10] gio_mime: fix bug when looking for version (#9177) gio_mime: fix bug when looking for version (#9171) * gio_mime: fix bug when looking for version * add changelog frag (cherry picked from commit 152339a8f9e7c3986399b7c4eeab86a617d0ae54) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9171-gio-mime-fix-version.yml | 2 ++ plugins/module_utils/gio_mime.py | 5 +++-- plugins/modules/gio_mime.py | 5 ++--- tests/unit/plugins/modules/test_gio_mime.yaml | 6 +++--- 4 files changed, 10 insertions(+), 8 deletions(-) create mode 100644 changelogs/fragments/9171-gio-mime-fix-version.yml diff --git a/changelogs/fragments/9171-gio-mime-fix-version.yml b/changelogs/fragments/9171-gio-mime-fix-version.yml new file mode 100644 index 0000000000..ca9dbddd7f --- /dev/null +++ b/changelogs/fragments/9171-gio-mime-fix-version.yml @@ -0,0 +1,2 @@ +bugfixes: + - 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). 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/modules/gio_mime.py b/plugins/modules/gio_mime.py index 587aaec427..a3b340b677 100644 --- a/plugins/modules/gio_mime.py +++ b/plugins/modules/gio_mime.py @@ -108,12 +108,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/tests/unit/plugins/modules/test_gio_mime.yaml b/tests/unit/plugins/modules/test_gio_mime.yaml index f71e595701..3645446291 100644 --- a/tests/unit/plugins/modules/test_gio_mime.yaml +++ b/tests/unit/plugins/modules/test_gio_mime.yaml @@ -13,7 +13,7 @@ changed: true mocks: run_command: - - command: [/testbin/gio, mime, --version] + - command: [/testbin/gio, --version] environ: &env-def {environ_update: {LANGUAGE: C, LC_ALL: C}, check_rc: true} rc: 0 out: "2.80.0\n" @@ -40,7 +40,7 @@ skip: test helper does not support check mode yet mocks: run_command: - - command: [/testbin/gio, mime, --version] + - command: [/testbin/gio, --version] environ: *env-def rc: 0 out: "2.80.0\n" @@ -65,7 +65,7 @@ changed: false mocks: run_command: - - command: [/testbin/gio, mime, --version] + - command: [/testbin/gio, --version] environ: *env-def rc: 0 out: "2.80.0\n" From 5fe39082d58e59112766064f3f4b11c38516a570 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 23 Nov 2024 15:41:07 +0100 Subject: [PATCH 027/302] Prepare 10.1.0 release. --- changelogs/fragments/10.1.0.yml | 1 + galaxy.yml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/10.1.0.yml diff --git a/changelogs/fragments/10.1.0.yml b/changelogs/fragments/10.1.0.yml new file mode 100644 index 0000000000..4b1469c9fe --- /dev/null +++ b/changelogs/fragments/10.1.0.yml @@ -0,0 +1 @@ +release_summary: Regular bugfix and feature release. diff --git a/galaxy.yml b/galaxy.yml index 85b4c896ff..4daf0e0ac0 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -5,7 +5,7 @@ namespace: community name: general -version: 10.0.2 +version: 10.1.0 readme: README.md authors: - Ansible (https://github.com/ansible) From 0b64fc1ee40a946ae1f2c1dd8d9f55ad942fdf82 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 25 Nov 2024 19:49:12 +0100 Subject: [PATCH 028/302] [PR #9179/a3bd49c0 backport][stable-10] deps module utils: unit tests + minor improvement (#9182) deps module utils: unit tests + minor improvement (#9179) * deps module utils: unit tests + minor improvement * deps.clear() calls dict.clear() instead of creating new dict * add changelog frag (cherry picked from commit a3bd49c01064fc68a505081e4dd78997b41e0fa9) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9179-deps-tests.yml | 2 + plugins/module_utils/deps.py | 4 ++ tests/unit/plugins/module_utils/test_deps.py | 69 +++++++++++++++++++ .../module_utils/test_module_helper.py | 5 ++ tests/unit/plugins/modules/conftest.py | 2 +- 5 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9179-deps-tests.yml create mode 100644 tests/unit/plugins/module_utils/test_deps.py diff --git a/changelogs/fragments/9179-deps-tests.yml b/changelogs/fragments/9179-deps-tests.yml new file mode 100644 index 0000000000..1ddf109033 --- /dev/null +++ b/changelogs/fragments/9179-deps-tests.yml @@ -0,0 +1,2 @@ +minor_changes: + - deps module utils - add ``deps.clear()`` to clear out previously declared dependencies (https://github.com/ansible-collections/community.general/pull/9179). 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/tests/unit/plugins/module_utils/test_deps.py b/tests/unit/plugins/module_utils/test_deps.py new file mode 100644 index 0000000000..70f0eac0fd --- /dev/null +++ b/tests/unit/plugins/module_utils/test_deps.py @@ -0,0 +1,69 @@ +# -*- coding: utf-8 -*- +# (c) 2024, Alexei Znamensky +# 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 + +from ansible_collections.community.general.tests.unit.compat.mock import MagicMock + +import pytest + +from ansible_collections.community.general.plugins.module_utils import deps + + +@pytest.fixture +def module(): + m = MagicMock() + m.fail_json.side_effect = RuntimeError + return m + + +def test_wrong_name(module): + with deps.declare("sys") as sys_dep: + import sys # noqa: F401, pylint: disable=unused-import + + with pytest.raises(KeyError): + deps.validate(module, "wrong_name") + + +def test_fail_potatoes(module): + with deps.declare("potatoes", reason="Must have potatoes") as potatoes_dep: + import potatoes_that_will_never_be_there # noqa: F401, pylint: disable=unused-import + + with pytest.raises(RuntimeError): + deps.validate(module) + + assert potatoes_dep.failed is True + assert potatoes_dep.message.startswith("Failed to import the required Python library") + + +def test_sys(module): + with deps.declare("sys") as sys_dep: + import sys # noqa: F401, pylint: disable=unused-import + + deps.validate(module) + + assert sys_dep.failed is False + + +def test_multiple(module): + with deps.declare("mpotatoes", reason="Must have mpotatoes"): + import potatoes_that_will_never_be_there # noqa: F401, pylint: disable=unused-import + + with deps.declare("msys", reason="Must have msys"): + import sys # noqa: F401, pylint: disable=unused-import + + deps.validate(module, "msys") + deps.validate(module, "-mpotatoes") + + with pytest.raises(RuntimeError): + deps.validate(module) + + with pytest.raises(RuntimeError): + deps.validate(module, "-msys") + + with pytest.raises(RuntimeError): + deps.validate(module, "mpotatoes") diff --git a/tests/unit/plugins/module_utils/test_module_helper.py b/tests/unit/plugins/module_utils/test_module_helper.py index b1e2eafc7f..cbcdaae788 100644 --- a/tests/unit/plugins/module_utils/test_module_helper.py +++ b/tests/unit/plugins/module_utils/test_module_helper.py @@ -14,6 +14,7 @@ from ansible_collections.community.general.plugins.module_utils.module_helper im ) +# remove in 11.0.0 def test_dependency_ctxmgr(): ctx = DependencyCtxMgr("POTATOES", "Potatoes must be installed") with ctx: @@ -36,6 +37,7 @@ def test_dependency_ctxmgr(): assert ctx.has_it +# remove in 11.0.0 def test_variable_meta(): meta = VarMeta() assert meta.output is True @@ -51,6 +53,7 @@ def test_variable_meta(): assert meta.diff_result is None +# remove in 11.0.0 def test_variable_meta_diff(): meta = VarMeta(diff=True) assert meta.output is True @@ -70,6 +73,7 @@ def test_variable_meta_diff(): assert meta.diff_result == {"before": "abc", "after": "ghi"} +# remove in 11.0.0 def test_vardict(): vd = VarDict() vd.set('a', 123) @@ -99,6 +103,7 @@ def test_vardict(): assert vd.diff() == {'before': {'a': 123}, 'after': {'a': 'new_a'}}, "diff={0}".format(vd.diff()) +# remove in 11.0.0 def test_variable_meta_change(): vd = VarDict() vd.set('a', 123, change=True) diff --git a/tests/unit/plugins/modules/conftest.py b/tests/unit/plugins/modules/conftest.py index 6e96c58316..d357137651 100644 --- a/tests/unit/plugins/modules/conftest.py +++ b/tests/unit/plugins/modules/conftest.py @@ -48,4 +48,4 @@ def patch_ansible_module(request, mocker): @pytest.fixture(autouse=True) def deps_cleanup(): - deps._deps.clear() + deps.clear() From 74cd18b68202574bcdf69e72447bc5b317655359 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 25 Nov 2024 19:49:25 +0100 Subject: [PATCH 029/302] [PR #9180/a9449ccc backport][stable-10] pipx/pipx_info: add return value version (#9183) pipx/pipx_info: add return value version (#9180) * pipx/pipx_info: add return value version * add changelog frag (cherry picked from commit a9449ccc2e97a37348f65a8280c1ee71ec97c117) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9180-pipx-version.yml | 3 ++ plugins/module_utils/pipx.py | 37 ++++++++++--------- plugins/modules/pipx.py | 13 +++++++ plugins/modules/pipx_info.py | 10 +++++ tests/integration/targets/pipx/tasks/main.yml | 1 + 5 files changed, 46 insertions(+), 18 deletions(-) create mode 100644 changelogs/fragments/9180-pipx-version.yml diff --git a/changelogs/fragments/9180-pipx-version.yml b/changelogs/fragments/9180-pipx-version.yml new file mode 100644 index 0000000000..f07d66c83c --- /dev/null +++ b/changelogs/fragments/9180-pipx-version.yml @@ -0,0 +1,3 @@ +minor_changes: + - 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). 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/modules/pipx.py b/plugins/modules/pipx.py index 9bde0f180c..1706f125d9 100644 --- a/plugins/modules/pipx.py +++ b/plugins/modules/pipx.py @@ -190,6 +190,15 @@ EXAMPLES = """ with_items: "{{ pipx_packages }}" """ +RETURN = """ +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() diff --git a/plugins/modules/pipx_info.py b/plugins/modules/pipx_info.py index 33fbad0e5d..24a6739024 100644 --- a/plugins/modules/pipx_info.py +++ b/plugins/modules/pipx_info.py @@ -119,6 +119,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 +156,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/tests/integration/targets/pipx/tasks/main.yml b/tests/integration/targets/pipx/tasks/main.yml index e764f17f68..314e9dfa52 100644 --- a/tests/integration/targets/pipx/tasks/main.yml +++ b/tests/integration/targets/pipx/tasks/main.yml @@ -57,6 +57,7 @@ assert: that: - install_tox is changed + - "'version' in install_tox" - "'tox' in install_tox.application" - install_tox_again is not changed - install_tox_again_force is changed From 6f9b954048663f93488ec0bce0c2cab2d3daaecb Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 25 Nov 2024 19:49:33 +0100 Subject: [PATCH 030/302] [PR #9132/3c23ce4a backport][stable-10] `cloudflare_dns`: add support for `comment` and `tags` (#9184) `cloudflare_dns`: add support for `comment` and `tags` (#9132) * `cloudflare_dns`: add support for `comment` and `tags` * `cloudflare_dns`: add return values for `comment`/`tags` fields * `cloudflare_dns`: fix return values samples * `cloudflare_dns`: changelog fragment formatting * `cloudflare_dns`: add missing `version_added` * `cloudflare_dns`: remove explicit `required: false` * `cloudflare_dns`: empty `comment` idempotency fix (cherry picked from commit 3c23ce4a7bcdd08e172a58669842d4faec63d7c5) Co-authored-by: Sergio <45396489+Sergio-IME@users.noreply.github.com> --- .../9132-cloudflare_dns-comment-and-tags.yml | 2 + plugins/modules/cloudflare_dns.py | 66 +++++++++++++++++-- 2 files changed, 63 insertions(+), 5 deletions(-) create mode 100644 changelogs/fragments/9132-cloudflare_dns-comment-and-tags.yml diff --git a/changelogs/fragments/9132-cloudflare_dns-comment-and-tags.yml b/changelogs/fragments/9132-cloudflare_dns-comment-and-tags.yml new file mode 100644 index 0000000000..b601e39f55 --- /dev/null +++ b/changelogs/fragments/9132-cloudflare_dns-comment-and-tags.yml @@ -0,0 +1,2 @@ +minor_changes: + - cloudflare_dns - add support for ``comment`` and ``tags`` (https://github.com/ansible-collections/community.general/pull/9132). diff --git a/plugins/modules/cloudflare_dns.py b/plugins/modules/cloudflare_dns.py index 86550966be..a2bcc79f8e 100644 --- a/plugins/modules/cloudflare_dns.py +++ b/plugins/modules/cloudflare_dns.py @@ -31,7 +31,6 @@ options: - "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: @@ -39,13 +38,11 @@ options: - 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 ] account_email: description: - Account email. Required for API keys authentication. type: str - required: false algorithm: description: - Algorithm number. @@ -57,6 +54,11 @@ options: - Required for O(type=TLSA) when O(state=present). type: int 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. @@ -134,6 +136,12 @@ options: type: str 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. @@ -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 @@ -299,6 +319,18 @@ record: 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 @@ -333,7 +365,7 @@ record: type: bool sample: false meta: - description: No documentation available. + description: Extra Cloudflare-specific information about the record. returned: success type: dict sample: { auto_added: false } @@ -362,6 +394,19 @@ record: 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 @@ -410,9 +455,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'] @@ -662,7 +709,7 @@ class CloudflareAPI(object): 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 +845,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 +876,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 +910,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), From ecc9afab0b1fdf4ec8c957af0c6c993e6f2da268 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 26 Nov 2024 06:40:54 +0100 Subject: [PATCH 031/302] [PR #9191/fa7c2df4 backport][stable-10] ufw: add note to docs about concurrency (#9195) ufw: add note to docs about concurrency (#9191) * ufw: add note to docs about concurrency * wordsmithing (cherry picked from commit fa7c2df4b861dd49b7176b8e48662fee9910c41f) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/ufw.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/plugins/modules/ufw.py b/plugins/modules/ufw.py index 7a90647979..fba0ef5fe2 100644 --- a/plugins/modules/ufw.py +++ b/plugins/modules/ufw.py @@ -23,6 +23,10 @@ author: - Ahti Kitsik (@ahtik) notes: - See C(man ufw) for more examples. + - > + B(Warning:) Whilst the module itself can be run using concurrent strategies, C(ufw) does not support concurrency, + as firewall rules are meant to be ordered and parallel executions do not guarantee order. + B(Do not use concurrency:) The results are unpredictable and the module may fail silently if you do. requirements: - C(ufw) package extends_documentation_fragment: From 41527702810afb046b7ba2234ac8efbebd04419f Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 26 Nov 2024 06:41:02 +0100 Subject: [PATCH 032/302] [PR #9189/b4983086 backport][stable-10] scaleway_lb: simplify function logic (#9196) scaleway_lb: simplify function logic (#9189) * scaleway_lb: simplify function logic * add changelog frag (cherry picked from commit b49830861cfbba4d513ef61a832440f20e11aaef) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9189-scalway-lb-simplify-return.yml | 2 ++ plugins/modules/scaleway_lb.py | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/9189-scalway-lb-simplify-return.yml diff --git a/changelogs/fragments/9189-scalway-lb-simplify-return.yml b/changelogs/fragments/9189-scalway-lb-simplify-return.yml new file mode 100644 index 0000000000..39d161f06b --- /dev/null +++ b/changelogs/fragments/9189-scalway-lb-simplify-return.yml @@ -0,0 +1,2 @@ +minor_changes: + - scaleway_lb - minor simplification in the code (https://github.com/ansible-collections/community.general/pull/9189). diff --git a/plugins/modules/scaleway_lb.py b/plugins/modules/scaleway_lb.py index 1083b6da9e..6cc947755d 100644 --- a/plugins/modules/scaleway_lb.py +++ b/plugins/modules/scaleway_lb.py @@ -228,8 +228,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): From 163f3ee305691d1bb0d837ca2913ac43247ae5e6 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 28 Nov 2024 20:06:38 +0100 Subject: [PATCH 033/302] [PR #9186/a863b628 backport][stable-10] fixing broken check mode in the github_key (#9205) fixing broken check mode in the github_key (#9186) * fixing datetime.strftime() * added changelog fragment * Update changelogs/fragments/9186-fix-broken-check-mode-in-github-key.yml Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit a863b62859541f03d04e9feaaedd4cef9d2e9ff5) Co-authored-by: tomcperry <99128358+tomcperry@users.noreply.github.com> --- .../fragments/9186-fix-broken-check-mode-in-github-key.yml | 2 ++ plugins/modules/github_key.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9186-fix-broken-check-mode-in-github-key.yml diff --git a/changelogs/fragments/9186-fix-broken-check-mode-in-github-key.yml b/changelogs/fragments/9186-fix-broken-check-mode-in-github-key.yml new file mode 100644 index 0000000000..dbf1f145d5 --- /dev/null +++ b/changelogs/fragments/9186-fix-broken-check-mode-in-github-key.yml @@ -0,0 +1,2 @@ +bugfixes: + - 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). \ No newline at end of file diff --git a/plugins/modules/github_key.py b/plugins/modules/github_key.py index a74ead9848..b071e7b339 100644 --- a/plugins/modules/github_key.py +++ b/plugins/modules/github_key.py @@ -162,7 +162,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 } From 5491ff7c6a9961decd86db82579149603ee12e5f Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 28 Nov 2024 20:06:51 +0100 Subject: [PATCH 034/302] [PR #9187/f828bdee backport][stable-10] flatpak: force locale language to be C (#9207) flatpak: force locale language to be C (#9187) * flatpak: force locale langauge to be C * add changelog frag (cherry picked from commit f828bdee2287d603158407bd7ea3f843240dfefa) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9187-flatpak-lang.yml | 2 ++ plugins/modules/flatpak.py | 2 ++ 2 files changed, 4 insertions(+) create mode 100644 changelogs/fragments/9187-flatpak-lang.yml diff --git a/changelogs/fragments/9187-flatpak-lang.yml b/changelogs/fragments/9187-flatpak-lang.yml new file mode 100644 index 0000000000..159923cbdc --- /dev/null +++ b/changelogs/fragments/9187-flatpak-lang.yml @@ -0,0 +1,2 @@ +bugfixes: + - 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). diff --git a/plugins/modules/flatpak.py b/plugins/modules/flatpak.py index 09e49e5575..84e4ea8374 100644 --- a/plugins/modules/flatpak.py +++ b/plugins/modules/flatpak.py @@ -419,6 +419,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) From 09f99e66fe71ad4259c46c91422f5c07afc20573 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 28 Nov 2024 20:06:59 +0100 Subject: [PATCH 035/302] [PR #9167/420f78de backport][stable-10] Add the options apply_live to rpm_ostree_pkg (#9208) Add the options apply_live to rpm_ostree_pkg (#9167) rpm_ostree_pkg: add support for `apply_live` and return value `needs_reboot` #9167 (cherry picked from commit 420f78de2fea14de761b4e326fa500544139e3a9) Co-authored-by: shios86 <17804953+shios86@users.noreply.github.com> --- .../9167-rpm_ostree_pkg-apply_live.yml | 3 ++ plugins/modules/rpm_ostree_pkg.py | 37 ++++++++++++++++++- 2 files changed, 38 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/9167-rpm_ostree_pkg-apply_live.yml diff --git a/changelogs/fragments/9167-rpm_ostree_pkg-apply_live.yml b/changelogs/fragments/9167-rpm_ostree_pkg-apply_live.yml new file mode 100644 index 0000000000..e473dedd0b --- /dev/null +++ b/changelogs/fragments/9167-rpm_ostree_pkg-apply_live.yml @@ -0,0 +1,3 @@ +minor_changes: +- 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). diff --git a/plugins/modules/rpm_ostree_pkg.py b/plugins/modules/rpm_ostree_pkg.py index 1a02b2d71c..8c5c693f60 100644 --- a/plugins/modules/rpm_ostree_pkg.py +++ b/plugins/modules/rpm_ostree_pkg.py @@ -40,6 +40,14 @@ options: 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) @@ -56,6 +64,12 @@ EXAMPLES = r''' name: nfs-utils state: absent +- name: Apply the overlay package live + community.general.rpm_ostree: + 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 @@ -104,6 +118,12 @@ cmd: 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 +144,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 +170,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 +209,10 @@ def main(): type='list', elements='str', ), + apply_live=dict( + type='bool', + default=False, + ), ), ) From e31999f3694de9472d7b12519ae5bdba58ad2355 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:33:38 +0100 Subject: [PATCH 036/302] [PR #9197/c38b4749 backport][stable-10] Add backup module for proxmox (#9210) Add backup module for proxmox (#9197) * Defined configuration variables, main backup function todo * Defined configuration variables, main backup function todo * wip * permission checks and basic flow done, final request missing * ansible-test and unit test open * Improve documentation * fix pep8 errors * remove f-string and fix bugs through manual testing * longer full example * improve docs * error message for fail + timeout * move sleep location * remove residual debugger * include newline for better readability * more linting errors fixed * Include UPIDs as return value * Output logs as comma separated value, move exception and create new abstraction for api calls * pretter logs * Update project to final version * Remove accidential placeholder for integration test * Fix missing explizit string in docstring * Reorder imports below docstrings * remove type annotations and fix indendation of options dict * prettier idendation and aplhabetic ordering of options dict * aplhabetic ordering of docstring options * Remove the rest of type hinting as well :( * fix version * improve documentation * add change detection mode * refactor list comprehension to filter function * remove storage availability check for node * refactor to quotation marks * Fix trailing newline and incorrect RV usage * rollback filter plugin * Remove action_group reference and add proxmox_backup to meta/runtime.yml * Include note about missing idempotency --------- Co-authored-by: IamLunchbox (cherry picked from commit c38b4749825ec83c88226537dccd1bc1f71af077) Co-authored-by: IamLunchbox <56757745+IamLunchbox@users.noreply.github.com> --- .github/BOTMETA.yml | 2 + meta/runtime.yml | 1 + plugins/modules/proxmox_backup.py | 635 ++++++++++++++++++ .../plugins/modules/test_proxmox_backup.py | 366 ++++++++++ 4 files changed, 1004 insertions(+) create mode 100644 plugins/modules/proxmox_backup.py create mode 100644 tests/unit/plugins/modules/test_proxmox_backup.py diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 989752a0a7..594f01349a 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -1117,6 +1117,8 @@ files: $modules/proxmox_kvm.py: ignore: skvidal maintainers: helldorado krauthosting + $modules/proxmox_backup.py: + maintainers: IamLunchbox $modules/proxmox_nic.py: maintainers: Kogelvis krauthosting $modules/proxmox_node_info.py: diff --git a/meta/runtime.yml b/meta/runtime.yml index f5adb64712..387ab0f22b 100644 --- a/meta/runtime.yml +++ b/meta/runtime.yml @@ -16,6 +16,7 @@ action_groups: - consul_token proxmox: - proxmox + - proxmox_backup - proxmox_disk - proxmox_domain_info - proxmox_group_info diff --git a/plugins/modules/proxmox_backup.py b/plugins/modules/proxmox_backup.py new file mode 100644 index 0000000000..fb5750383e --- /dev/null +++ b/plugins/modules/proxmox_backup.py @@ -0,0 +1,635 @@ +#!/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). + - > + 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")). + - 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 target 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, + e.g. due to no matching targets. + returned: on success + type: str +''' + +from ansible_collections.community.general.plugins.module_utils.proxmox import ( + proxmox_auth_argument_spec, ProxmoxAnsible) +from ansible.module_utils.common.text.converters import to_native +from ansible.module_utils.basic import AnsibleModule + +import time + + +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 "/" in permissions.keys() and permissions["/"].get( + "Datastore.AllocateSpace", 0) == 1: + pass + elif "/storage" in permissions.keys() and permissions["/storage"].get("Datastore.AllocateSpace", 0) == 1: + pass + elif "/storage/" + storage in permissions.keys() and permissions["/storage/" + storage].get("Datastore.AllocateSpace", 0) == 1: + pass + else: + self.module.fail_json( + changed=False, + msg="Insufficient permission: Datastore.AllocateSpace is missing") + if (bandwidth or performance) and permissions["/"].get( + "Sys.Modify", 0) == 0: + self.module.fail_json( + changed=False, + msg="Insufficient permission: Performance_tweaks and bandwidth require 'Sys.Modify' permission for '/'") + if retention: + if "/" in permissions.keys() and permissions["/"].get( + "Datastore.Allocate", 0) == 1: + pass + elif "/storage" in permissions.keys() and permissions["/storage"].get("Datastore.Allocate", 0) == 1: + pass + elif "/storage/" + storage in permissions.keys() and permissions["/storage/" + storage].get("Datastore.Allocate", 0) == 1: + pass + else: + 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 = False + if "/" in permissions.keys() and permissions["/"].get( + "VM.Backup", 0) == 1: + sufficient_permissions = True + elif "/vms" in permissions.keys() and permissions["/"].get( + "VM.Backup", 0) == 1: + sufficient_permissions = True + elif pool and "/pool/" + pool in permissions.keys() and permissions["/pool/" + pool].get( + "VM.Backup", 0) == 1: + sufficient_permissions = True + elif pool and "/pool/" + pool + "/vms" in permissions.keys() and permissions["/pool/" + pool + "/vms"].get( + "VM.Backup", 0) == 1: + sufficient_permissions = True + + 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: + if "/vms/" + \ + str(vm) in permissions.keys() and permissions["/vms/" + str(vm)].get("VM.Backup", 1) == 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 "/" in permissions.keys() and permissions["/"].get( + "VM.Backup", 0) == 1: + pass + elif "/vms" in permissions.keys() and permissions["/vms"].get("VM.Backup", 0) == 1: + pass + elif pool and "/pool/" + pool in permissions.keys() and permissions["/pool/" + pool].get( + "VM.Backup", 0) == 1: + pass + 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"] in ( + "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"] = "%s" % 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.get("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/tests/unit/plugins/modules/test_proxmox_backup.py b/tests/unit/plugins/modules/test_proxmox_backup.py new file mode 100644 index 0000000000..8da4de4dee --- /dev/null +++ b/tests/unit/plugins/modules/test_proxmox_backup.py @@ -0,0 +1,366 @@ +# -*- coding: utf-8 -*- +# +# Copyright (c) 2019, 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) +import \ + ansible_collections.community.general.plugins.module_utils.proxmox as proxmox_utils +from ansible_collections.community.general.plugins.modules import proxmox_backup +from ansible_collections.community.general.tests.unit.plugins.modules.utils import ( + AnsibleExitJson, AnsibleFailJson, set_module_args, ModuleTestCase) +from ansible_collections.community.general.tests.unit.compat.mock import patch + +__metaclass__ = type + +import pytest + +proxmoxer = pytest.importorskip('proxmoxer') + + +MINIMAL_PERMISSIONS = { + '/sdn/zones': {'Datastore.AllocateSpace': 1, 'Datastore.Audit': 1}, + '/nodes': {'Datastore.AllocateSpace': 1, 'Datastore.Audit': 1}, + '/sdn': {'Datastore.AllocateSpace': 1, 'Datastore.Audit': 1}, + '/vms': {'VM.Audit': 1, + 'Sys.Audit': 1, + 'Mapping.Audit': 1, + 'VM.Backup': 1, + 'Datastore.Audit': 1, + 'SDN.Audit': 1, + 'Pool.Audit': 1}, + '/': {'Datastore.Audit': 1, 'Datastore.AllocateSpace': 1}, + '/storage/local-zfs': {'Datastore.AllocateSpace': 1, + 'Datastore.Audit': 1}, + '/storage': {'Datastore.AllocateSpace': 1, 'Datastore.Audit': 1}, + '/access': {'Datastore.AllocateSpace': 1, 'Datastore.Audit': 1}, + '/vms/101': {'VM.Backup': 1, + 'Mapping.Audit': 1, + 'Datastore.AllocateSpace': 0, + 'Sys.Audit': 1, + 'VM.Audit': 1, + 'SDN.Audit': 1, + 'Pool.Audit': 1, + 'Datastore.Audit': 1}, + '/vms/100': {'VM.Backup': 1, + 'Mapping.Audit': 1, + 'Datastore.AllocateSpace': 0, + 'Sys.Audit': 1, + 'VM.Audit': 1, + 'SDN.Audit': 1, + 'Pool.Audit': 1, + 'Datastore.Audit': 1}, + '/pool': {'Datastore.Audit': 1, 'Datastore.AllocateSpace': 1}, } + +STORAGE = [{'type': 'pbs', + 'username': 'test@pbs', + 'datastore': 'Backup-Pool', + 'server': '10.0.0.1', + 'shared': 1, + 'fingerprint': '94:fd:ac:e7:d5:36:0e:11:5b:23:05:40:d2:a4:e1:8a:c1:52:41:01:07:28:c0:4d:c5:ee:df:7f:7c:03:ab:41', + 'prune-backups': 'keep-all=1', + 'storage': 'backup', + 'content': 'backup', + 'digest': 'ca46a68d7699de061c139d714892682ea7c9d681'}, + {'nodes': 'node1,node2,node3', + 'sparse': 1, + 'type': 'zfspool', + 'content': 'rootdir,images', + 'digest': 'ca46a68d7699de061c139d714892682ea7c9d681', + 'pool': 'rpool/data', + 'storage': 'local-zfs'}] + + +VMS = [{"diskwrite": 0, + "vmid": 100, + "node": "node1", + "id": "lxc/100", + "maxdisk": 10000, + "template": 0, + "disk": 10000, + "uptime": 10000, + "maxmem": 10000, + "maxcpu": 1, + "netin": 10000, + "type": "lxc", + "netout": 10000, + "mem": 10000, + "diskread": 10000, + "cpu": 0.01, + "name": "test-lxc", + "status": "running"}, + {"diskwrite": 0, + "vmid": 101, + "node": "node2", + "id": "kvm/101", + "maxdisk": 10000, + "template": 0, + "disk": 10000, + "uptime": 10000, + "maxmem": 10000, + "maxcpu": 1, + "netin": 10000, + "type": "lxc", + "netout": 10000, + "mem": 10000, + "diskread": 10000, + "cpu": 0.01, + "name": "test-kvm", + "status": "running"} + ] + +NODES = [{'level': '', + 'type': 'node', + 'node': 'node1', + 'status': 'online', + 'id': 'node/node1', + 'cgroup-mode': 2}, + {'status': 'online', + 'id': 'node/node2', + 'cgroup-mode': 2, + 'level': '', + 'node': 'node2', + 'type': 'node'}, + {'status': 'online', + 'id': 'node/node3', + 'cgroup-mode': 2, + 'level': '', + 'node': 'node3', + 'type': 'node'}, + ] + +TASK_API_RETURN = { + "node1": { + 'starttime': 1732606253, + 'status': 'stopped', + 'type': 'vzdump', + 'pstart': 517463911, + 'upid': 'UPID:node1:003F8C63:1E7FB79C:67449780:vzdump:100:root@pam:', + 'id': '100', + 'node': 'hypervisor', + 'pid': 541669, + 'user': 'test@pve', + 'exitstatus': 'OK'}, + "node2": { + 'starttime': 1732606253, + 'status': 'stopped', + 'type': 'vzdump', + 'pstart': 517463911, + 'upid': 'UPID:node2:000029DD:1599528B:6108F068:vzdump:101:root@pam:', + 'id': '101', + 'node': 'hypervisor', + 'pid': 541669, + 'user': 'test@pve', + 'exitstatus': 'OK'}, +} + + +VZDUMP_API_RETURN = { + "node1": "UPID:node1:003F8C63:1E7FB79C:67449780:vzdump:100:root@pam:", + "node2": "UPID:node2:000029DD:1599528B:6108F068:vzdump:101:root@pam:", + "node3": "OK", +} + + +TASKLOG_API_RETURN = {"node1": [{'n': 1, + 't': "INFO: starting new backup job: vzdump 100 --mode snapshot --node node1 " + "--notes-template '{{guestname}}' --storage backup --notification-mode auto"}, + {'t': 'INFO: Starting Backup of VM 100 (lxc)', + 'n': 2}, + {'n': 23, 't': 'INFO: adding notes to backup'}, + {'n': 24, + 't': 'INFO: Finished Backup of VM 100 (00:00:03)'}, + {'n': 25, + 't': 'INFO: Backup finished at 2024-11-25 16:28:03'}, + {'t': 'INFO: Backup job finished successfully', + 'n': 26}, + {'n': 27, 't': 'TASK OK'}], + "node2": [{'n': 1, + 't': "INFO: starting new backup job: vzdump 101 --mode snapshot --node node2 " + "--notes-template '{{guestname}}' --storage backup --notification-mode auto"}, + {'t': 'INFO: Starting Backup of VM 101 (kvm)', + 'n': 2}, + {'n': 24, + 't': 'INFO: Finished Backup of VM 100 (00:00:03)'}, + {'n': 25, + 't': 'INFO: Backup finished at 2024-11-25 16:28:03'}, + {'t': 'INFO: Backup job finished successfully', + 'n': 26}, + {'n': 27, 't': 'TASK OK'}], + } + + +def return_valid_resources(resource_type, *args, **kwargs): + if resource_type == "vm": + return VMS + if resource_type == "node": + return NODES + + +def return_vzdump_api(node, *args, **kwargs): + if node in ("node1", "node2", "node3"): + return VZDUMP_API_RETURN[node] + + +def return_logs_api(node, *args, **kwargs): + if node in ("node1", "node2"): + return TASKLOG_API_RETURN[node] + + +def return_task_status_api(node, *args, **kwargs): + if node in ("node1", "node2"): + return TASK_API_RETURN[node] + + +class TestProxmoxBackup(ModuleTestCase): + def setUp(self): + super(TestProxmoxBackup, self).setUp() + proxmox_utils.HAS_PROXMOXER = True + self.module = proxmox_backup + self.connect_mock = patch( + "ansible_collections.community.general.plugins.module_utils.proxmox.ProxmoxAnsible._connect", + ).start() + self.mock_get_permissions = patch.object( + proxmox_backup.ProxmoxBackupAnsible, "_get_permissions").start() + self.mock_get_storages = patch.object(proxmox_utils.ProxmoxAnsible, + "get_storages").start() + self.mock_get_resources = patch.object( + proxmox_backup.ProxmoxBackupAnsible, "_get_resources").start() + self.mock_get_tasklog = patch.object( + proxmox_backup.ProxmoxBackupAnsible, "_get_tasklog").start() + self.mock_post_vzdump = patch.object( + proxmox_backup.ProxmoxBackupAnsible, "_post_vzdump").start() + self.mock_get_taskok = patch.object( + proxmox_backup.ProxmoxBackupAnsible, "_get_taskok").start() + self.mock_get_permissions.return_value = MINIMAL_PERMISSIONS + self.mock_get_storages.return_value = STORAGE + self.mock_get_resources.side_effect = return_valid_resources + self.mock_get_taskok.side_effect = return_task_status_api + self.mock_get_tasklog.side_effect = return_logs_api + self.mock_post_vzdump.side_effect = return_vzdump_api + + def tearDown(self): + self.connect_mock.stop() + self.mock_get_permissions.stop() + self.mock_get_storages.stop() + self.mock_get_resources.stop() + super(TestProxmoxBackup, self).tearDown() + + def test_proxmox_backup_without_argument(self): + set_module_args({}) + with pytest.raises(AnsibleFailJson): + proxmox_backup.main() + + def test_create_backup_check_mode(self): + set_module_args({"api_user": "root@pam", + "api_password": "secret", + "api_host": "127.0.0.1", + "mode": "all", + "storage": "backup", + "_ansible_check_mode": True, + }) + with pytest.raises(AnsibleExitJson) as exc_info: + proxmox_backup.main() + + result = exc_info.value.args[0] + + assert result["changed"] is True + assert result["msg"] == "Backups would be created" + assert len(result["backups"]) == 0 + assert self.mock_get_taskok.call_count == 0 + assert self.mock_get_tasklog.call_count == 0 + assert self.mock_post_vzdump.call_count == 0 + + def test_create_backup_all_mode(self): + set_module_args({"api_user": "root@pam", + "api_password": "secret", + "api_host": "127.0.0.1", + "mode": "all", + "storage": "backup", + }) + with pytest.raises(AnsibleExitJson) as exc_info: + proxmox_backup.main() + + result = exc_info.value.args[0] + assert result["changed"] is True + assert result["msg"] == "Backup tasks created" + for backup_result in result["backups"]: + assert backup_result["upid"] in { + VZDUMP_API_RETURN[key] for key in VZDUMP_API_RETURN} + assert self.mock_get_taskok.call_count == 0 + assert self.mock_post_vzdump.call_count == 3 + + def test_create_backup_include_mode_with_wait(self): + set_module_args({"api_user": "root@pam", + "api_password": "secret", + "api_host": "127.0.0.1", + "mode": "include", + "node": "node1", + "storage": "backup", + "vmids": [100], + "wait": True + }) + with pytest.raises(AnsibleExitJson) as exc_info: + proxmox_backup.main() + + result = exc_info.value.args[0] + assert result["changed"] is True + assert result["msg"] == "Backups succeeded" + for backup_result in result["backups"]: + assert backup_result["upid"] in { + VZDUMP_API_RETURN[key] for key in VZDUMP_API_RETURN} + assert self.mock_get_taskok.call_count == 1 + assert self.mock_post_vzdump.call_count == 1 + + def test_fail_insufficient_permissions(self): + set_module_args({"api_user": "root@pam", + "api_password": "secret", + "api_host": "127.0.0.1", + "mode": "include", + "storage": "backup", + "performance_tweaks": "max-workers=2", + "vmids": [100], + "wait": True + }) + with pytest.raises(AnsibleFailJson) as exc_info: + proxmox_backup.main() + + result = exc_info.value.args[0] + assert result["msg"] == "Insufficient permission: Performance_tweaks and bandwidth require 'Sys.Modify' permission for '/'" + assert self.mock_get_taskok.call_count == 0 + assert self.mock_post_vzdump.call_count == 0 + + def test_fail_missing_node(self): + set_module_args({"api_user": "root@pam", + "api_password": "secret", + "api_host": "127.0.0.1", + "mode": "include", + "storage": "backup", + "node": "nonexistingnode", + "vmids": [100], + "wait": True + }) + with pytest.raises(AnsibleFailJson) as exc_info: + proxmox_backup.main() + + result = exc_info.value.args[0] + assert result["msg"] == "Node nonexistingnode was specified, but does not exist on the cluster" + assert self.mock_get_taskok.call_count == 0 + assert self.mock_post_vzdump.call_count == 0 + + def test_fail_missing_storage(self): + set_module_args({"api_user": "root@pam", + "api_password": "secret", + "api_host": "127.0.0.1", + "mode": "include", + "storage": "nonexistingstorage", + "vmids": [100], + "wait": True + }) + with pytest.raises(AnsibleFailJson) as exc_info: + proxmox_backup.main() + + result = exc_info.value.args[0] + assert result["msg"] == "Storage nonexistingstorage does not exist in the cluster" + assert self.mock_get_taskok.call_count == 0 + assert self.mock_post_vzdump.call_count == 0 From 6d6d3e8039570e145267c7e4b13ea0c89fe44067 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:33:47 +0100 Subject: [PATCH 037/302] [PR #9198/f2dbe08d backport][stable-10] Fail if Slack API response is not OK with error message (#9212) Fail if Slack API response is not OK with error message (#9198) * Fails if slack api return is not ok * add changelog * show all error * add doc * Update plugins/modules/slack.py Co-authored-by: Felix Fontein * Update changelogs/fragments/9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit f2dbe08d0e86dcbcb78bba52d9d19d5094089cbb) Co-authored-by: Matthieu Bourgain --- ...il-if-slack-api-response-is-not-ok-with-error-message.yml | 2 ++ plugins/modules/slack.py | 5 ++++- 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml diff --git a/changelogs/fragments/9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml b/changelogs/fragments/9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml new file mode 100644 index 0000000000..56ab25f578 --- /dev/null +++ b/changelogs/fragments/9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml @@ -0,0 +1,2 @@ +bugfixes: + - slack - fail if Slack API response is not OK with error message (https://github.com/ansible-collections/community.general/pull/9198). diff --git a/plugins/modules/slack.py b/plugins/modules/slack.py index 41dd4f5dba..58893b0f42 100644 --- a/plugins/modules/slack.py +++ b/plugins/modules/slack.py @@ -76,7 +76,8 @@ options: 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 @@ -391,6 +392,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: From bbd67b50176539ca286dc7e30882348a538b4342 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:34:01 +0100 Subject: [PATCH 038/302] [PR #9175/41b6a281 backport][stable-10] Add decompress module (#9213) Add decompress module (#9175) * adds simple implementation of `decompress` module * adds simple test, fixes src and dest arg types * minor refactoring * adds support for common file operations adds integration test for gz decompressing * makes tests parametrized to test all supported compression formats * checks that target file exists * writes to decompressed file now uses atomic_move * adds idempotency for decompression * refactoring, removed classes * adds support for check mode * adds check for destination file. If it exists and it is a directory, the module returns error * refactoring, moves code to a class. Also, simplifies tests (now only tests related to the module core functionality run as parametrized, tests for idempotency and check mode run only for one format) * adds 'remove' parameter that deletes original compressed file after decompression * adds documentation * fixes bug with 'remove' parameter in check mode * makes dest argument not required. Dest filename now can be produced from the src filename * adds dest to output * updates the documentation, adds "RETURN" block * fixes test * adds support for python2 * removes some of the test files that can be generated during testing. Adds copyright header to test files * adds maintainer * apply minor suggestions from code review Co-authored-by: Felix Fontein * fixes code review comments (idempotency issue with non existing src, existing dest and remove=true; fixes the issue and adds test) * refactors the module to use ModuleHelper * refactors lzma dependency manual check to use 'deps.validate' * minor fix * removes registered handlers check * minor refactoring * adds aliases * changes setup for tests * tests: ignores macos and fixes tests for FreeBSD * tests: reverts ignore for macos and fixes issue with centos7 * tests: adds liblzma dependency for python2 * tests: adds backports.lzma * fixes bz2 decompression for python2 * tests: install xz for osx * tests: install xz for osx (2) * fixes code review comments --------- Co-authored-by: Felix Fontein (cherry picked from commit 41b6a281e17572f886cbae6c585a1541a62657f1) Co-authored-by: Stanislav Shamilov --- .github/BOTMETA.yml | 2 + plugins/modules/decompress.py | 213 ++++++++++++++++++ tests/integration/targets/decompress/aliases | 7 + .../targets/decompress/files/file.txt | 5 + .../targets/decompress/files/second_file.txt | 5 + .../targets/decompress/handlers/main.yml | 9 + .../targets/decompress/meta/main.yml | 7 + .../targets/decompress/tasks/cleanup.yml | 12 + .../targets/decompress/tasks/core.yml | 29 +++ .../targets/decompress/tasks/dest.yml | 51 +++++ .../targets/decompress/tasks/main.yml | 115 ++++++++++ .../targets/decompress/tasks/misc.yml | 74 ++++++ 12 files changed, 529 insertions(+) create mode 100644 plugins/modules/decompress.py create mode 100644 tests/integration/targets/decompress/aliases create mode 100644 tests/integration/targets/decompress/files/file.txt create mode 100644 tests/integration/targets/decompress/files/second_file.txt create mode 100644 tests/integration/targets/decompress/handlers/main.yml create mode 100644 tests/integration/targets/decompress/meta/main.yml create mode 100644 tests/integration/targets/decompress/tasks/cleanup.yml create mode 100644 tests/integration/targets/decompress/tasks/core.yml create mode 100644 tests/integration/targets/decompress/tasks/dest.yml create mode 100644 tests/integration/targets/decompress/tasks/main.yml create mode 100644 tests/integration/targets/decompress/tasks/misc.yml diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 594f01349a..9650fd0ef3 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -506,6 +506,8 @@ files: ignore: skornehl $modules/dconf.py: maintainers: azaghal + $modules/decompress.py: + maintainers: shamilovstas $modules/deploy_helper.py: maintainers: ramondelafuente $modules/dimensiondata_network.py: diff --git a/plugins/modules/decompress.py b/plugins/modules/decompress.py new file mode 100644 index 0000000000..818213fb0d --- /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/tests/integration/targets/decompress/aliases b/tests/integration/targets/decompress/aliases new file mode 100644 index 0000000000..f4049c7dc2 --- /dev/null +++ b/tests/integration/targets/decompress/aliases @@ -0,0 +1,7 @@ +# 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 + +azp/posix/2 +needs/root +destructive \ No newline at end of file diff --git a/tests/integration/targets/decompress/files/file.txt b/tests/integration/targets/decompress/files/file.txt new file mode 100644 index 0000000000..5d2e0d1458 --- /dev/null +++ b/tests/integration/targets/decompress/files/file.txt @@ -0,0 +1,5 @@ +# 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 + +This is sample file \ No newline at end of file diff --git a/tests/integration/targets/decompress/files/second_file.txt b/tests/integration/targets/decompress/files/second_file.txt new file mode 100644 index 0000000000..bd04eca21c --- /dev/null +++ b/tests/integration/targets/decompress/files/second_file.txt @@ -0,0 +1,5 @@ +# 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 + +Content of this file must differ from the 'file.txt' \ No newline at end of file diff --git a/tests/integration/targets/decompress/handlers/main.yml b/tests/integration/targets/decompress/handlers/main.yml new file mode 100644 index 0000000000..8c92cc4f81 --- /dev/null +++ b/tests/integration/targets/decompress/handlers/main.yml @@ -0,0 +1,9 @@ +--- +# 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 + +- name: delete backports.lzma + pip: + name: backports.lzma + state: absent diff --git a/tests/integration/targets/decompress/meta/main.yml b/tests/integration/targets/decompress/meta/main.yml new file mode 100644 index 0000000000..982de6eb03 --- /dev/null +++ b/tests/integration/targets/decompress/meta/main.yml @@ -0,0 +1,7 @@ +--- +# 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 + +dependencies: + - setup_remote_tmp_dir diff --git a/tests/integration/targets/decompress/tasks/cleanup.yml b/tests/integration/targets/decompress/tasks/cleanup.yml new file mode 100644 index 0000000000..95db42104f --- /dev/null +++ b/tests/integration/targets/decompress/tasks/cleanup.yml @@ -0,0 +1,12 @@ +--- +# 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 + +- name: Delete decompressed files + file: + path: "{{ remote_tmp_dir }}/file_from_{{ format }}.txt" + state: absent + loop: "{{ formats }}" + loop_control: + loop_var: format \ No newline at end of file diff --git a/tests/integration/targets/decompress/tasks/core.yml b/tests/integration/targets/decompress/tasks/core.yml new file mode 100644 index 0000000000..a92ae21b78 --- /dev/null +++ b/tests/integration/targets/decompress/tasks/core.yml @@ -0,0 +1,29 @@ +--- +# 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 + +- name: Set mode for decompressed file ({{ format }} test) + set_fact: + decompressed_mode: "0640" + +- name: Simple decompress ({{ format }} test) + decompress: + src: "{{ remote_tmp_dir }}/file.txt.{{ format }}" + dest: "{{ remote_tmp_dir }}/file_from_{{ format }}.txt" + format: "{{ format }}" + mode: "{{ decompressed_mode }}" + register: first_decompression + +- name: Stat decompressed file ({{ format }} test) + stat: + path: "{{ remote_tmp_dir }}/file_from_{{ format }}.txt" + register: decompressed_file_stat + +- name: Check that file was decompressed correctly ({{ format }} test) + assert: + that: + - first_decompression.changed + - decompressed_file_stat.stat.exists + - decompressed_file_stat.stat.mode == decompressed_mode + - orig_file_stat.stat.checksum == decompressed_file_stat.stat.checksum diff --git a/tests/integration/targets/decompress/tasks/dest.yml b/tests/integration/targets/decompress/tasks/dest.yml new file mode 100644 index 0000000000..9a7bbe499f --- /dev/null +++ b/tests/integration/targets/decompress/tasks/dest.yml @@ -0,0 +1,51 @@ +--- +# 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 + +- name: Copy a compressed file + copy: + src: "{{ item.orig }}" + dest: "{{ item.new }}" + remote_src: true + loop: + - { orig: "{{ remote_tmp_dir }}/file.txt.gz", new: "{{ remote_tmp_dir }}/dest.txt.gz" } + - { orig: "{{ remote_tmp_dir }}/file.txt.gz", new: "{{ remote_tmp_dir }}/dest" } + +- name: Decompress a file without specifying destination + decompress: + src: "{{ remote_tmp_dir }}/dest.txt.gz" + remove: true + +- name: Decompress a file which lacks extension without specifying destination + decompress: + src: "{{ remote_tmp_dir }}/dest" + remove: true + +- name: Stat result files + stat: + path: "{{ remote_tmp_dir }}/{{ filename }}" + loop: + - dest.txt + - dest_decompressed + loop_control: + loop_var: filename + register: result_files_stat + +- name: Test that file exists + assert: + that: "{{ item.stat.exists }}" + quiet: true + loop: "{{ result_files_stat.results }}" + loop_control: + label: "{{ item.stat.path }}" + +- name: Delete test files + file: + path: "{{ filename }}" + state: absent + loop: + - "dest.txt" + - "dest_decompressed" + loop_control: + loop_var: filename diff --git a/tests/integration/targets/decompress/tasks/main.yml b/tests/integration/targets/decompress/tasks/main.yml new file mode 100644 index 0000000000..f14f2d5593 --- /dev/null +++ b/tests/integration/targets/decompress/tasks/main.yml @@ -0,0 +1,115 @@ +--- +# 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 + +- name: Copy test files + copy: + src: "files/" + dest: "{{ remote_tmp_dir }}" + +- name: Get original file stat + stat: + path: "{{ remote_tmp_dir }}/file.txt" + register: orig_file_stat + +- name: Set supported formats + set_fact: + formats: + - bz2 + - gz + - xz + +- name: Ensure xz is present to create compressed files (not Debian) + package: + name: + - xz + - bzip2 + state: latest + when: + - ansible_system != 'FreeBSD' + - ansible_os_family != 'Darwin' + - ansible_os_family != 'Debian' + +- name: Ensure xz is present to create compressed files (Debian) + package: + name: xz-utils + state: latest + when: ansible_os_family == 'Debian' + +- name: Install prerequisites for backports.lzma when using python2 (non OSX) + block: + - name: Set liblzma package name depending on the OS + set_fact: + liblzma_dev_package: + Debian: liblzma-dev + RedHat: xz-devel + Suse: xz-devel + - name: Ensure liblzma-dev is present to install backports-lzma + package: + name: "{{ liblzma_dev_package[ansible_os_family] }}" + state: latest + when: ansible_os_family in liblzma_dev_package.keys() + when: + - ansible_python_version.split('.')[0] == '2' + - ansible_os_family != 'Darwin' + +- name: Install prerequisites for backports.lzma when using python2 (OSX) + block: + - name: Find brew binary + command: which brew + register: brew_which + - name: Get owner of brew binary + stat: + path: "{{ brew_which.stdout }}" + register: brew_stat + - name: "Install package" + homebrew: + name: xz + state: present + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + # Newer versions of brew want to compile a package which takes a long time. Do not upgrade homebrew until a + # proper solution can be found + environment: + HOMEBREW_NO_AUTO_UPDATE: "True" + when: + - ansible_os_family == 'Darwin' + +- name: Ensure backports.lzma is present to create test archive (pip) + pip: + name: backports.lzma + state: latest + when: ansible_python_version.split('.')[0] == '2' + notify: + - delete backports.lzma + +- name: Generate compressed files + shell: | + gzip < {{ item }} > {{ item }}.gz + bzip2 < {{ item }} > {{ item }}.bz2 + xz < {{ item }} > {{ item }}.xz + loop: + - "{{ remote_tmp_dir }}/file.txt" + - "{{ remote_tmp_dir }}/second_file.txt" + +# Run tests +- name: Run core tests + block: + - include_tasks: core.yml + loop: "{{ formats }}" + loop_control: + loop_var: format + - import_tasks: cleanup.yml + + +- name: Run idempotency and check mode tests + block: + - import_tasks: misc.yml + - import_tasks: cleanup.yml + +- name: Run tests for destination file + block: + - import_tasks: dest.yml + - import_tasks: cleanup.yml diff --git a/tests/integration/targets/decompress/tasks/misc.yml b/tests/integration/targets/decompress/tasks/misc.yml new file mode 100644 index 0000000000..1514e55030 --- /dev/null +++ b/tests/integration/targets/decompress/tasks/misc.yml @@ -0,0 +1,74 @@ +--- +# 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 + +- name: Decompress with check mode enabled + decompress: + src: "{{ remote_tmp_dir }}/file.txt.gz" + dest: "{{ remote_tmp_dir }}/file_from_gz.txt" + format: gz + check_mode: true + register: decompressed_check_mode + +- name: Decompress second time with check mode enabled + decompress: + src: "{{ remote_tmp_dir }}/file.txt.gz" + dest: "{{ remote_tmp_dir }}/file_from_gz.txt" + format: gz + remove: true + check_mode: true + register: decompressed_check_mode_2 + +- name: Stat original compressed file + stat: + path: "{{ remote_tmp_dir }}/file.txt.gz" + register: original_file + +- name: Stat non-existing file + stat: + path: "{{ remote_tmp_dir }}/file_from_gz.txt" + register: nonexisting_stat + +- name: Check mode test + assert: + that: + - decompressed_check_mode.changed + - decompressed_check_mode_2.changed + - original_file.stat.exists + - not nonexisting_stat.stat.exists + +- name: Copy compressed file + copy: + src: "{{ remote_tmp_dir }}/file.txt.gz" + dest: "{{ remote_tmp_dir }}/file_copied.txt.gz" + remote_src: true + +- name: Decompress, deleting original file + decompress: + src: "{{ remote_tmp_dir }}/file_copied.txt.gz" + dest: "{{ remote_tmp_dir }}/file_copied.txt" + remove: true + +- name: Decompress non existing src + decompress: + src: "{{ remote_tmp_dir }}/file_copied.txt.gz" + dest: "{{ remote_tmp_dir }}/file_copied.txt" + remove: true + register: decompress_non_existing_src + +- name: Stat compressed file + stat: + path: "{{ remote_tmp_dir }}/file_copied.txt.gz" + register: compressed_stat + +- name: Run tests + assert: + that: + - not compressed_stat.stat.exists + - not decompress_non_existing_src.changed + +- name: Delete decompressed file + file: + path: "{{ remote_tmp_dir }}/file_copied.txt" + state: absent From 54291ab1d10c386f54c03c72f6dc1f6c60a42a7a Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:34:22 +0100 Subject: [PATCH 039/302] [PR #9159/da97e220 backport][stable-10] iso_extract: Add password argument (#9214) iso_extract: Add password argument (#9159) * iso_extract: Add password argument * Update iso_extract.py * Update iso_extract.py * Update plugins/modules/iso_extract.py Co-authored-by: Felix Fontein * Create 9159-iso-extract_add_password.yml * Update 9159-iso-extract_add_password.yml * Remove default value for password * Use password with 7z only * Apply suggestions from code review Co-authored-by: Felix Fontein * Fix indentation * Update plugins/modules/iso_extract.py Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * iso_extract: add password warning * Update plugins/modules/iso_extract.py Co-authored-by: Felix Fontein * Shorten a docs line. * Fix formatting. --------- Co-authored-by: Felix Fontein Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> (cherry picked from commit da97e220ef3e859230c35f0fe8802245cb21f40b) Co-authored-by: jurelou --- .../fragments/9159-iso-extract_add_password.yml | 2 ++ plugins/modules/iso_extract.py | 16 +++++++++++++++- 2 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9159-iso-extract_add_password.yml diff --git a/changelogs/fragments/9159-iso-extract_add_password.yml b/changelogs/fragments/9159-iso-extract_add_password.yml new file mode 100644 index 0000000000..f1b2650d4f --- /dev/null +++ b/changelogs/fragments/9159-iso-extract_add_password.yml @@ -0,0 +1,2 @@ +minor_changes: + - iso_extract - adds ``password`` parameter that is passed to 7z (https://github.com/ansible-collections/community.general/pull/9159). diff --git a/plugins/modules/iso_extract.py b/plugins/modules/iso_extract.py index 087ef2843f..9ef046ede4 100644 --- a/plugins/modules/iso_extract.py +++ b/plugins/modules/iso_extract.py @@ -67,6 +67,15 @@ options: - 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. @@ -100,6 +109,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 +118,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 +165,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] From c4373d5ed508fbe427d62a6a092481d03f393380 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:34:31 +0100 Subject: [PATCH 040/302] [PR #9181/fddccea9 backport][stable-10] Greatly speed up homebrew module when multiple packages are passed in the `name` key (#9215) Greatly speed up homebrew module when multiple packages are passed in the `name` key (#9181) * Increase test coverage and assert output more strictly * Remove unused `_current_package_is_installed_from_head` * Remove `un/changed_count` and infer from un/changed_pkgs length * Track `installed` & `outdated` package state once * Validate package names beforehand * Install packages in 1 brew call instead of N This also has the side effect of fixing the check message so that it prints every packages that will be installed instead of only the first one. * Uninstall packages in 1 brew call instead of N * Link packages in 1 brew call instead of N * Unlink packages in 1 brew call instead of N * Upgrade packages in 1 brew call instead of N * Remove dangling checks * Remove `_status` method and directly return the tuple * Add changelog fragment * Fix invalid format string (nice catch pylint!) * Update changelogs/fragments/9181-improve-homebrew-module-performance.yml Co-authored-by: Felix Fontein * Update brew info parsing for casks * Update changelogs/fragments/9181-improve-homebrew-module-performance.yml Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --------- Co-authored-by: Felix Fontein Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> (cherry picked from commit fddccea9403d76fc514bba3f87c1eedc1c0c8b8e) Co-authored-by: Thibaut Decombe <68703331+UnknownPlatypus@users.noreply.github.com> --- ...81-improve-homebrew-module-performance.yml | 2 + plugins/modules/homebrew.py | 372 +++++++++--------- .../targets/homebrew/tasks/formulae.yml | 226 +++++++++++ 3 files changed, 409 insertions(+), 191 deletions(-) create mode 100644 changelogs/fragments/9181-improve-homebrew-module-performance.yml diff --git a/changelogs/fragments/9181-improve-homebrew-module-performance.yml b/changelogs/fragments/9181-improve-homebrew-module-performance.yml new file mode 100644 index 0000000000..b3b6ba2ca4 --- /dev/null +++ b/changelogs/fragments/9181-improve-homebrew-module-performance.yml @@ -0,0 +1,2 @@ +minor_changes: + - homebrew - greatly speed up module when multiple packages are passed in the ``name`` option (https://github.com/ansible-collections/community.general/pull/9181). \ No newline at end of file diff --git a/plugins/modules/homebrew.py b/plugins/modules/homebrew.py index bc5d8649e7..8eb1b9d689 100644 --- a/plugins/modules/homebrew.py +++ b/plugins/modules/homebrew.py @@ -308,21 +308,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 +332,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 +365,48 @@ 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 _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", []): + if bool(package_detail.get("installed")): + self.installed_packages.add(package_detail["name"]) + if bool(package_detail.get("outdated")): + self.outdated_packages.add(package_detail["name"]) + + for package_detail in data.get("casks", []): + if bool(package_detail.get("installed")): + self.installed_packages.add(package_detail["token"]) + if bool(package_detail.get("outdated")): + self.outdated_packages.add(package_detail["token"]) # /prep -------------------------------------------------------- }}} def run(self): @@ -390,60 +415,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): - 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): - 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 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): @@ -454,6 +433,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': @@ -523,19 +504,22 @@ class Homebrew(object): # /_upgrade_all -------------------------- }}} # installed ------------------------------ {{{ - def _install_current_package(self): - 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, + def _install_packages(self): + packages_to_install = set(self.packages) - self.installed_packages + + 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) @@ -552,72 +536,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' - - 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'] @@ -639,138 +579,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 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, + def _uninstall_packages(self): + packages_to_uninstall = self.installed_packages & set(self.packages) + + 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 self._current_package_is_installed(): + def _link_packages(self): + missing_packages = set(self.packages) - self.installed_packages + if missing_packages: 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 self._current_package_is_installed(): + def _unlink_packages(self): + missing_packages = set(self.packages) - self.installed_packages + if missing_packages: 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 ---------------------------------------------------- }}} diff --git a/tests/integration/targets/homebrew/tasks/formulae.yml b/tests/integration/targets/homebrew/tasks/formulae.yml index 1ca8d753e7..21276e3a2e 100644 --- a/tests/integration/targets/homebrew/tasks/formulae.yml +++ b/tests/integration/targets/homebrew/tasks/formulae.yml @@ -56,6 +56,9 @@ - assert: that: - package_result.changed + - "package_result.msg == 'Package installed: gnu-tar'" + - "package_result.changed_pkgs == ['gnu-tar']" + - "package_result.unchanged_pkgs == []" - name: Again install {{ package_name }} package using homebrew homebrew: @@ -69,6 +72,41 @@ - assert: that: - not package_result.changed + - "package_result.msg == 'Package already installed: gnu-tar'" + - "package_result.changed_pkgs == []" + - "package_result.unchanged_pkgs == ['gnu-tar']" + + - name: Unlink {{ package_name }} package using homebrew + homebrew: + name: "{{ package_name }}" + state: unlinked + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - package_result.changed + - "package_result.msg == 'Package unlinked: gnu-tar'" + - "package_result.changed_pkgs == ['gnu-tar']" + - "package_result.unchanged_pkgs == []" + + - name: Link {{ package_name }} package using homebrew + homebrew: + name: "{{ package_name }}" + state: linked + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - package_result.changed + - "package_result.msg == 'Package linked: gnu-tar'" + - "package_result.changed_pkgs == ['gnu-tar']" + - "package_result.unchanged_pkgs == []" - name: Uninstall {{ package_name }} package using homebrew homebrew: @@ -82,6 +120,9 @@ - assert: that: - package_result.changed + - "package_result.msg == 'Package uninstalled: gnu-tar'" + - "package_result.changed_pkgs == ['gnu-tar']" + - "package_result.unchanged_pkgs == []" - name: Again uninstall {{ package_name }} package using homebrew homebrew: @@ -95,3 +136,188 @@ - assert: that: - not package_result.changed + - "package_result.msg == 'Package already uninstalled: gnu-tar'" + - "package_result.changed_pkgs == []" + - "package_result.unchanged_pkgs == ['gnu-tar']" + + - name: Upgrade {{ package_name }} package using homebrew + homebrew: + name: "{{ package_name }}" + state: latest + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - package_result.changed + - "package_result.msg == 'Package upgraded: gnu-tar'" + - "package_result.changed_pkgs == ['gnu-tar']" + - "package_result.unchanged_pkgs == []" + + - name: Again upgrade {{ package_name }} package using homebrew + homebrew: + name: "{{ package_name }}" + state: latest + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - not package_result.changed + - "package_result.msg == 'Package already upgraded: gnu-tar'" + - "package_result.changed_pkgs == []" + - "package_result.unchanged_pkgs == ['gnu-tar']" + +- vars: + package_names: + - gnu-tar + - gnu-time + + block: + - name: Make sure {{ package_names }} packages are not installed + homebrew: + name: "{{ package_names }}" + state: absent + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + + - name: Install only {{ package_names[0] }} package using homebrew + homebrew: + name: "{{ package_names[0] }}" + state: present + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + + - name: Install {{ package_names }} packages using homebrew (one is already installed) + homebrew: + name: "{{ package_names }}" + state: present + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - package_result.changed + - "package_result.msg == 'Changed: 1, Unchanged: 1'" + - "package_result.changed_pkgs == ['gnu-time']" + - "package_result.unchanged_pkgs == ['gnu-tar']" + + - name: Again install {{ package_names }} packages using homebrew + homebrew: + name: "{{ package_names }}" + state: present + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - not package_result.changed + - "package_result.msg == 'Changed: 0, Unchanged: 2'" + - "package_result.changed_pkgs == []" + - "package_result.unchanged_pkgs | sort == ['gnu-tar', 'gnu-time']" + + - name: Unlink {{ package_names }} packages using homebrew + homebrew: + name: "{{ package_names }}" + state: unlinked + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - package_result.changed + - "package_result.msg == 'Changed: 2, Unchanged: 0'" + - "package_result.changed_pkgs | sort == ['gnu-tar', 'gnu-time']" + - "package_result.unchanged_pkgs == []" + + - name: Link {{ package_names }} packages using homebrew + homebrew: + name: "{{ package_names }}" + state: linked + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - package_result.changed + - "package_result.msg == 'Changed: 2, Unchanged: 0'" + - "package_result.changed_pkgs | sort == ['gnu-tar', 'gnu-time']" + - "package_result.unchanged_pkgs == []" + + - name: Uninstall {{ package_names }} packages using homebrew + homebrew: + name: "{{ package_names }}" + state: absent + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - package_result.changed + - "package_result.msg == 'Changed: 2, Unchanged: 0'" + - "package_result.changed_pkgs | sort == ['gnu-tar', 'gnu-time']" + - "package_result.unchanged_pkgs == []" + + - name: Again uninstall {{ package_names }} packages using homebrew + homebrew: + name: "{{ package_names }}" + state: absent + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - not package_result.changed + - "package_result.msg == 'Changed: 0, Unchanged: 2'" + - "package_result.changed_pkgs == []" + - "package_result.unchanged_pkgs | sort == ['gnu-tar', 'gnu-time']" + + - name: Upgrade {{ package_names }} packages using homebrew + homebrew: + name: "{{ package_names }}" + state: latest + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - package_result.changed + - "package_result.msg == 'Changed: 2, Unchanged: 0'" + - "package_result.changed_pkgs | sort == ['gnu-tar', 'gnu-time']" + - "package_result.unchanged_pkgs == []" + + - name: Again upgrade {{ package_names }} packages using homebrew + homebrew: + name: "{{ package_names }}" + state: latest + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: package_result + + - assert: + that: + - not package_result.changed + - "package_result.msg == 'Changed: 0, Unchanged: 2'" + - "package_result.changed_pkgs == []" + - "package_result.unchanged_pkgs | sort == ['gnu-tar', 'gnu-time']" From fbada0026ec493e2447aa388b68a4193df5646eb Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:34:40 +0100 Subject: [PATCH 041/302] [PR #9190/ab095948 backport][stable-10] redfish_utils module utils: remove redundant code (#9216) redfish_utils module utils: remove redundant code (#9190) deprecate method instead (cherry picked from commit ab0959480ec93be2490b1f7d277ad7da32841bef) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9190-redfish-utils-unused-code.yml | 4 ++++ plugins/module_utils/redfish_utils.py | 3 +-- 2 files changed, 5 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/9190-redfish-utils-unused-code.yml diff --git a/changelogs/fragments/9190-redfish-utils-unused-code.yml b/changelogs/fragments/9190-redfish-utils-unused-code.yml new file mode 100644 index 0000000000..47f7588b96 --- /dev/null +++ b/changelogs/fragments/9190-redfish-utils-unused-code.yml @@ -0,0 +1,4 @@ +minor_changes: + - redfish_utils module utils - remove redundant code (https://github.com/ansible-collections/community.general/pull/9190). +deprecated_features: + - redfish_utils module utils - deprecate method ``RedfishUtils._init_session()`` (https://github.com/ansible-collections/community.general/pull/9190). diff --git a/plugins/module_utils/redfish_utils.py b/plugins/module_utils/redfish_utils.py index 388fc93669..dd559921ae 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): """ @@ -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 From 5727f1afd48106003dbf9aa552906efa548a63da Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:34:49 +0100 Subject: [PATCH 042/302] [PR #9168/82462e40 backport][stable-10] Add SR-IOV support to nmcli module (#9217) Add SR-IOV support to nmcli module (#9168) * Add SR-IOV support to nmcli module (#9168) * Add SR-IOV support to nmcli module (#9168) Fixes * Add SR-IOV support to nmcli module (#9168) Add test * Update changelogs/fragments/9168-nmcli-add-sriov-parameter.yml Co-authored-by: Felix Fontein * Update plugins/modules/nmcli.py Co-authored-by: Felix Fontein * Update plugins/modules/nmcli.py Co-authored-by: Felix Fontein * Update plugins/modules/nmcli.py Co-authored-by: Felix Fontein * Populate sriov options --------- Co-authored-by: Felix Fontein (cherry picked from commit 82462e407e06e32d7b3a694e174a54d6852ac38f) Co-authored-by: Ian Bishop <151477169+ianb-mp@users.noreply.github.com> --- .../9168-nmcli-add-sriov-parameter.yml | 2 + plugins/modules/nmcli.py | 41 ++++++++++++ tests/unit/plugins/modules/test_nmcli.py | 64 +++++++++++++++++++ 3 files changed, 107 insertions(+) create mode 100644 changelogs/fragments/9168-nmcli-add-sriov-parameter.yml diff --git a/changelogs/fragments/9168-nmcli-add-sriov-parameter.yml b/changelogs/fragments/9168-nmcli-add-sriov-parameter.yml new file mode 100644 index 0000000000..77f28e73bf --- /dev/null +++ b/changelogs/fragments/9168-nmcli-add-sriov-parameter.yml @@ -0,0 +1,2 @@ +minor_changes: + - nmcli - add ``sriov`` parameter that enables support for SR-IOV settings (https://github.com/ansible-collections/community.general/pull/9168). diff --git a/plugins/modules/nmcli.py b/plugins/modules/nmcli.py index e2803432a9..4ea6799577 100644 --- a/plugins/modules/nmcli.py +++ b/plugins/modules/nmcli.py @@ -1058,6 +1058,38 @@ options: 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 + eswitch-encap-mode: + description: + - Select the eswitch encapsulation support. + type: int + eswitch-inline-mode: + description: + - 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 ''' EXAMPLES = r''' @@ -1687,6 +1719,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 @@ -1952,6 +1985,13 @@ class Nmcli(object): 'infiniband.transport-mode': self.transport_mode, }) + 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(): setting_type = self.settings_type(setting) @@ -2607,6 +2647,7 @@ def main(): wireguard=dict(type='dict'), vpn=dict(type='dict'), transport_mode=dict(type='str', choices=['datagram', 'connected']), + sriov=dict(type='dict'), ), mutually_exclusive=[['never_default4', 'gw4'], ['routes4_extended', 'routes4'], diff --git a/tests/unit/plugins/modules/test_nmcli.py b/tests/unit/plugins/modules/test_nmcli.py index 570b04d56f..89e8de6d64 100644 --- a/tests/unit/plugins/modules/test_nmcli.py +++ b/tests/unit/plugins/modules/test_nmcli.py @@ -357,6 +357,28 @@ ipv6.ignore-auto-dns: no ipv6.ignore-auto-routes: no """ +TESTCASE_ETHERNET_ADD_SRIOV_VFS = [ + { + 'type': 'ethernet', + 'conn_name': 'non_existent_nw_device', + 'ifname': 'ethernet_non_existant', + 'sriov': { + 'total-vfs': 16, + 'vfs': '0 spoof-check=true vlans=100', + }, + 'state': 'present', + '_ansible_check_mode': False, + } +] + +TESTCASE_ETHERNET_ADD_SRIOV_VFS_SHOW_OUTPUT = """\ +connection.id: non_existent_nw_device +connection.interface-name: ethernet_non_existant +connection.autoconnect: yes +sriov.total-vfs: 16 +sriov.vfs: 0 spoof-check=true vlans=100 +""" + TESTCASE_ETHERNET_ADD_IPV6_INT_WITH_ROUTE_AND_METRIC = [ { 'type': 'ethernet', @@ -1806,6 +1828,12 @@ def mocked_ethernet_connection_with_ipv6_static_address_multiple_static_routes_c )) +@pytest.fixture +def mocked_ethernet_connection_with_sriov_vfs_create(mocker): + mocker_set(mocker, + execute_return=(0, TESTCASE_ETHERNET_ADD_SRIOV_VFS_SHOW_OUTPUT, "")) + + @pytest.fixture def mocked_ethernet_connection_with_ipv6_static_address_static_route_with_metric_create(mocker): mocker_set(mocker, @@ -3312,6 +3340,41 @@ def test_ethernet_connection_static_ipv6_address_multiple_static_routes_with_met assert results['changed'] +@pytest.mark.parametrize('patch_ansible_module', TESTCASE_ETHERNET_ADD_SRIOV_VFS, indirect=['patch_ansible_module']) +def test_ethernet_connection_sriov_vfs_create( + mocked_ethernet_connection_with_sriov_vfs_create, capfd): + """ + Test : Create ethernet connection with SR-IOV VFs + """ + with pytest.raises(SystemExit): + nmcli.main() + + assert nmcli.Nmcli.execute_command.call_count == 1 + arg_list = nmcli.Nmcli.execute_command.call_args_list + add_args, add_kw = arg_list[0] + + assert add_args[0][0] == '/usr/bin/nmcli' + assert add_args[0][1] == 'con' + assert add_args[0][2] == 'add' + assert add_args[0][3] == 'type' + assert add_args[0][4] == 'ethernet' + assert add_args[0][5] == 'con-name' + assert add_args[0][6] == 'non_existent_nw_device' + + add_args_text = list(map(to_text, add_args[0])) + + for param in ['connection.interface-name', 'ethernet_non_existant', + 'con-name', 'non_existent_nw_device', + 'sriov.total-vfs', '16', + 'sriov.vfs', '0 spoof-check=true vlans=100']: + assert param in add_args_text + + out, err = capfd.readouterr() + results = json.loads(out) + assert not results.get('failed') + assert results['changed'] + + @pytest.mark.parametrize('patch_ansible_module', TESTCASE_ETHERNET_ADD_IPV6_INT_WITH_ROUTE_AND_METRIC, indirect=['patch_ansible_module']) def test_ethernet_connection_static_ipv6_address_static_route_with_metric_create( mocked_ethernet_connection_with_ipv6_static_address_static_route_with_metric_create, capfd): @@ -4384,6 +4447,7 @@ def test_bond_connection_unchanged(mocked_generic_connection_diff_check, capfd): wireguard=dict(type='dict'), vpn=dict(type='dict'), transport_mode=dict(type='str', choices=['datagram', 'connected']), + sriov=dict(type='dict'), ), mutually_exclusive=[['never_default4', 'gw4'], ['routes4_extended', 'routes4'], From fcf1cb7fbcc5ad644ce24920b316fd94543a09ef Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:34:58 +0100 Subject: [PATCH 043/302] [PR #9192/34010a78 backport][stable-10] Add dynamicforward option (#9218) Add dynamicforward option (#9192) * Add dynamicforward option * Add fragment * Modify fragment (cherry picked from commit 34010a788a1089f1d402f1ccfce2ec1b617ae98e) Co-authored-by: ONODERA Masaru <46081939+masa-orca@users.noreply.github.com> --- .../ssh_config_add_dynamicforward_option.yml | 2 ++ plugins/modules/ssh_config.py | 7 +++++++ .../targets/ssh_config/tasks/options.yml | 20 ++++++++++++++++++- 3 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/ssh_config_add_dynamicforward_option.yml diff --git a/changelogs/fragments/ssh_config_add_dynamicforward_option.yml b/changelogs/fragments/ssh_config_add_dynamicforward_option.yml new file mode 100644 index 0000000000..0252c94c46 --- /dev/null +++ b/changelogs/fragments/ssh_config_add_dynamicforward_option.yml @@ -0,0 +1,2 @@ +minor_changes: + - ssh_config - add ``dynamicforward`` option (https://github.com/ansible-collections/community.general/pull/9192). \ No newline at end of file diff --git a/plugins/modules/ssh_config.py b/plugins/modules/ssh_config.py index d974f45373..1f8098b25f 100644 --- a/plugins/modules/ssh_config.py +++ b/plugins/modules/ssh_config.py @@ -139,6 +139,11 @@ 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 requirements: - paramiko ''' @@ -272,6 +277,7 @@ 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'), ) config_changed = False @@ -376,6 +382,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/tests/integration/targets/ssh_config/tasks/options.yml b/tests/integration/targets/ssh_config/tasks/options.yml index f88f99081f..203c782487 100644 --- a/tests/integration/targets/ssh_config/tasks/options.yml +++ b/tests/integration/targets/ssh_config/tasks/options.yml @@ -21,6 +21,7 @@ controlmaster: "auto" controlpath: "~/.ssh/sockets/%r@%h-%p" controlpersist: yes + dynamicforward: '10080' state: present register: options_add check_mode: true @@ -55,6 +56,7 @@ controlmaster: "auto" controlpath: "~/.ssh/sockets/%r@%h-%p" controlpersist: yes + dynamicforward: '10080' state: present register: options_add @@ -78,6 +80,7 @@ controlmaster: "auto" controlpath: "~/.ssh/sockets/%r@%h-%p" controlpersist: yes + dynamicforward: '10080' state: present register: options_add_again @@ -105,6 +108,7 @@ - "'controlmaster auto' in slurp_ssh_config['content'] | b64decode" - "'controlpath ~/.ssh/sockets/%r@%h-%p' in slurp_ssh_config['content'] | b64decode" - "'controlpersist yes' in slurp_ssh_config['content'] | b64decode" + - "'dynamicforward 10080' in slurp_ssh_config['content'] | b64decode" - name: Options - Update host community.general.ssh_config: @@ -118,6 +122,7 @@ controlmaster: no controlpath: "~/.ssh/new-sockets/%r@%h-%p" controlpersist: "600" + dynamicforward: '11080' state: present register: options_update @@ -143,6 +148,7 @@ controlmaster: no controlpath: "~/.ssh/new-sockets/%r@%h-%p" controlpersist: "600" + dynamicforward: '11080' state: present register: options_update @@ -171,6 +177,7 @@ - "'controlmaster no' in slurp_ssh_config['content'] | b64decode" - "'controlpath ~/.ssh/new-sockets/%r@%h-%p' in slurp_ssh_config['content'] | b64decode" - "'controlpersist 600' in slurp_ssh_config['content'] | b64decode" + - "'dynamicforward 11080' in slurp_ssh_config['content'] | b64decode" - name: Options - Ensure no update in case option exist in ssh_config file but wasn't defined in playbook community.general.ssh_config: @@ -204,6 +211,7 @@ - "'controlmaster no' in slurp_ssh_config['content'] | b64decode" - "'controlpath ~/.ssh/new-sockets/%r@%h-%p' in slurp_ssh_config['content'] | b64decode" - "'controlpersist 600' in slurp_ssh_config['content'] | b64decode" + - "'dynamicforward 11080' in slurp_ssh_config['content'] | b64decode" - name: Debug debug: @@ -255,8 +263,9 @@ - "'controlmaster auto' not in slurp_ssh_config['content'] | b64decode" - "'controlpath ~/.ssh/sockets/%r@%h-%p' not in slurp_ssh_config['content'] | b64decode" - "'controlpersist yes' not in slurp_ssh_config['content'] | b64decode" + - "'dynamicforward 10080' not in slurp_ssh_config['content'] | b64decode" -# Proxycommand and ProxyJump are mutually exclusive. +# Proxycommand and ProxyJump are mutually exclusive. # Reset ssh_config before testing options with proxyjump - name: Copy sample config file @@ -276,6 +285,7 @@ controlmaster: "auto" controlpath: "~/.ssh/sockets/%r@%h-%p" controlpersist: yes + dynamicforward: '10080' state: present register: options_add check_mode: true @@ -310,6 +320,7 @@ controlmaster: "auto" controlpath: "~/.ssh/sockets/%r@%h-%p" controlpersist: yes + dynamicforward: '10080' state: present register: options_add @@ -333,6 +344,7 @@ controlmaster: "auto" controlpath: "~/.ssh/sockets/%r@%h-%p" controlpersist: yes + dynamicforward: '10080' state: present register: options_add_again @@ -360,6 +372,7 @@ - "'controlmaster auto' in slurp_ssh_config['content'] | b64decode" - "'controlpath ~/.ssh/sockets/%r@%h-%p' in slurp_ssh_config['content'] | b64decode" - "'controlpersist yes' in slurp_ssh_config['content'] | b64decode" + - "'dynamicforward 10080' in slurp_ssh_config['content'] | b64decode" - name: Options - Update host community.general.ssh_config: @@ -373,6 +386,7 @@ controlmaster: no controlpath: "~/.ssh/new-sockets/%r@%h-%p" controlpersist: "600" + dynamicforward: '11080' state: present register: options_update @@ -398,6 +412,7 @@ controlmaster: no controlpath: "~/.ssh/new-sockets/%r@%h-%p" controlpersist: "600" + dynamicforward: '11080' state: present register: options_update @@ -426,6 +441,7 @@ - "'controlmaster no' in slurp_ssh_config['content'] | b64decode" - "'controlpath ~/.ssh/new-sockets/%r@%h-%p' in slurp_ssh_config['content'] | b64decode" - "'controlpersist 600' in slurp_ssh_config['content'] | b64decode" + - "'dynamicforward 11080' in slurp_ssh_config['content'] | b64decode" - name: Options - Ensure no update in case option exist in ssh_config file but wasn't defined in playbook community.general.ssh_config: @@ -459,6 +475,7 @@ - "'controlmaster no' in slurp_ssh_config['content'] | b64decode" - "'controlpath ~/.ssh/new-sockets/%r@%h-%p' in slurp_ssh_config['content'] | b64decode" - "'controlpersist 600' in slurp_ssh_config['content'] | b64decode" + - "'dynamicforward 11080' in slurp_ssh_config['content'] | b64decode" - name: Debug debug: @@ -510,3 +527,4 @@ - "'controlmaster auto' not in slurp_ssh_config['content'] | b64decode" - "'controlpath ~/.ssh/sockets/%r@%h-%p' not in slurp_ssh_config['content'] | b64decode" - "'controlpersist yes' not in slurp_ssh_config['content'] | b64decode" + - "'dynamicforward 10080' not in slurp_ssh_config['content'] | b64decode" From d9436069f15d35ef4162940f3c8b769b8e4d8f0c Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:35:06 +0100 Subject: [PATCH 044/302] [PR #9172/d826dd1c backport][stable-10] opkg: deprecate value "" for force (#9219) opkg: deprecate value "" for force (#9172) * opkg: deprecate value "" for force * fix sanity plus wording * add comments for future removal * add changelog frag (cherry picked from commit d826dd1c8826fd87ea642d0c8c855bcc2b10180e) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9172-opkg-deprecate-force-none.yml | 2 ++ plugins/modules/opkg.py | 9 ++++++--- 2 files changed, 8 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/9172-opkg-deprecate-force-none.yml diff --git a/changelogs/fragments/9172-opkg-deprecate-force-none.yml b/changelogs/fragments/9172-opkg-deprecate-force-none.yml new file mode 100644 index 0000000000..1b11419c5a --- /dev/null +++ b/changelogs/fragments/9172-opkg-deprecate-force-none.yml @@ -0,0 +1,2 @@ +deprecated_features: + - opkg - deprecate value ``""`` for parameter ``force`` (https://github.com/ansible-collections/community.general/pull/9172). diff --git a/plugins/modules/opkg.py b/plugins/modules/opkg.py index da51755efb..32cb2753f5 100644 --- a/plugins/modules/opkg.py +++ b/plugins/modules/opkg.py @@ -46,8 +46,7 @@ options: 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. + - 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" @@ -152,7 +151,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 +167,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"), ), From 459b9f3f9a70bbba79ef766c4a58b1e9c0de12ad Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:35:15 +0100 Subject: [PATCH 045/302] [PR #9133/a789bd12 backport][stable-10] Add the accumulate filter (#9220) Add the accumulate filter (#9133) * Add the accumulate filter - Add myself as a maintainer for it. - Some integration tests. * accumulate: fix documentation and add test aliases The aliases file was copied over from tests/integrations/targets/filter_dict/aliases as the documentation[1] suggests to use the same group as existing similar tests. [1]: https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/integration-aliases.html Suggested-by: Felix Fontein * accumulate: documentation: markup consistency with other plugins Suggested-by: Felix Fontein Suggested-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * filter/accumulate: Validate input is a Sequence Accepting arbitrary iterables might lead to surprising behavior so we are stricter on what we accept in the filter. Relaxing those requirements is easier than retrofitting them, in terms of backwards compatibility. Suggested-by: Felix Fontein Signed-off-by: Max Gautier * filter/accumulate: Document the behavior with a string Signed-off-by: Max Gautier --------- Signed-off-by: Max Gautier (cherry picked from commit a789bd128f9c88022084d82378fa28f3bdf24748) Co-authored-by: Max Gautier --- .github/BOTMETA.yml | 2 + plugins/filter/accumulate.py | 62 +++++++++++++++++++ .../targets/filter_accumulate/aliases | 5 ++ .../targets/filter_accumulate/tasks/main.yml | 35 +++++++++++ 4 files changed, 104 insertions(+) create mode 100644 plugins/filter/accumulate.py create mode 100644 tests/integration/targets/filter_accumulate/aliases create mode 100644 tests/integration/targets/filter_accumulate/tasks/main.yml diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 9650fd0ef3..ec9b9b7ddc 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -135,6 +135,8 @@ files: $doc_fragments/xenserver.py: labels: xenserver maintainers: bvitnik + $filters/accumulate.py: + maintainers: VannTen $filters/counter.py: maintainers: keilr $filters/crc32.py: diff --git a/plugins/filter/accumulate.py b/plugins/filter/accumulate.py new file mode 100644 index 0000000000..9400936e1d --- /dev/null +++ b/plugins/filter/accumulate.py @@ -0,0 +1,62 @@ +# 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 = ''' + 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 = ''' + _value: + description: A list of cumulated sums of the elements of the input list. + type: list + elements: any +''' + +EXAMPLES = ''' +- 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/tests/integration/targets/filter_accumulate/aliases b/tests/integration/targets/filter_accumulate/aliases new file mode 100644 index 0000000000..343f119da8 --- /dev/null +++ b/tests/integration/targets/filter_accumulate/aliases @@ -0,0 +1,5 @@ +# 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 + +azp/posix/3 diff --git a/tests/integration/targets/filter_accumulate/tasks/main.yml b/tests/integration/targets/filter_accumulate/tasks/main.yml new file mode 100644 index 0000000000..8fe854228a --- /dev/null +++ b/tests/integration/targets/filter_accumulate/tasks/main.yml @@ -0,0 +1,35 @@ +--- +# 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 + +- name: Filter | Accumulate | Test valid values + assert: + that: + - "'abc' | community.general.accumulate == ['a', 'ab', 'abc']" + - "['a', 'b'] | community.general.accumulate == ['a', 'ab']" + - "[1, 2, 3] | community.general.accumulate == [1, 3, 6]" + - "[['foo'],['bar'],['foobar']] | community.general.accumulate == [['foo'], ['foo', 'bar'], ['foo', 'bar', 'foobar']]" + - "'path/to/file' | split('/') | map('split', '/') | community.general.accumulate | map('join', '/') == ['path', 'path/to', 'path/to/file']" + - "[{'foo':1}, {'bar':2}] | map('dict2items') | community.general.accumulate | map('items2dict') == [{'foo':1}, {'foo':1, 'bar':2}]" + + +- name: Filter | Accumulate | Test invalid values | Integer + debug: + var: "1 | community.general.accumulate" + register: integer_result + ignore_errors: true + +- name: Filter | Accumulate | Test invalid values | Non uniform list + debug: + var: "['aa', 1] | community.general.accumulate" + register: non_uniform_list_result + ignore_errors: true + +- name: Filter | Accumulate | Test invalid values | Check errors + assert: + that: + - integer_result is failed + - integer_result.msg is match('Invalid value type.*') + - non_uniform_list_result is failed + - non_uniform_list_result.msg is match('Unexpected templating type error.*can only concatenate str.*') From 0a6c57bc4dc40f55a1749d5612a4918b4e20e955 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 2 Dec 2024 20:35:25 +0100 Subject: [PATCH 046/302] [PR #9202/55d714da backport][stable-10] keycloak_clientscope_type: sort default and optional clientscope lists before diff (#9222) keycloak_clientscope_type: sort default and optional clientscope lists before diff (#9202) * sort default and optional clientscope lists before diff * add changelog fragment (cherry picked from commit 55d714da81fb6caa018cada300315b6086042c8e) Co-authored-by: fgruenbauer --- .../9202-keycloak_clientscope_type-sort-lists.yml | 2 ++ plugins/modules/keycloak_clientscope_type.py | 11 ++++++++++- 2 files changed, 12 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9202-keycloak_clientscope_type-sort-lists.yml diff --git a/changelogs/fragments/9202-keycloak_clientscope_type-sort-lists.yml b/changelogs/fragments/9202-keycloak_clientscope_type-sort-lists.yml new file mode 100644 index 0000000000..ef9fc7a6f7 --- /dev/null +++ b/changelogs/fragments/9202-keycloak_clientscope_type-sort-lists.yml @@ -0,0 +1,2 @@ +bugfixes: + - keycloak_clientscope_type - sort the default and optional clientscope lists to improve the diff (https://github.com/ansible-collections/community.general/pull/9202). \ No newline at end of file diff --git a/plugins/modules/keycloak_clientscope_type.py b/plugins/modules/keycloak_clientscope_type.py index 0c919afdad..1fb9a0813c 100644 --- a/plugins/modules/keycloak_clientscope_type.py +++ b/plugins/modules/keycloak_clientscope_type.py @@ -190,6 +190,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 +253,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) From 770bae70db4eb9005593089852d68e6d68d27b59 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 2 Dec 2024 21:13:38 +0100 Subject: [PATCH 047/302] Release 10.1.0. --- CHANGELOG.md | 107 ++++++++++++++---- CHANGELOG.rst | 61 ++++++++++ changelogs/changelog.yaml | 89 +++++++++++++++ changelogs/fragments/10.1.0.yml | 1 - changelogs/fragments/5932-launchd-plist.yml | 2 - ...support-server-side-artifact-fetching.yaml | 2 - ...cated-homebrew-package-name-validation.yml | 2 - ...9096-alternatives-add-family-parameter.yml | 2 - ...9123-redfish-command-custom-oem-params.yml | 2 - .../fragments/9124-dnf_config_manager.yml | 2 - .../9128-homebrew_cask-name-regex-fix.yml | 2 - .../9132-cloudflare_dns-comment-and-tags.yml | 2 - .../9157-fix-dnf_config_manager-locale.yml | 2 - .../9159-iso-extract_add_password.yml | 2 - .../9167-rpm_ostree_pkg-apply_live.yml | 3 - .../9168-nmcli-add-sriov-parameter.yml | 2 - .../fragments/9171-gio-mime-fix-version.yml | 2 - .../9172-opkg-deprecate-force-none.yml | 2 - changelogs/fragments/9179-deps-tests.yml | 2 - changelogs/fragments/9180-pipx-version.yml | 3 - ...81-improve-homebrew-module-performance.yml | 2 - ...86-fix-broken-check-mode-in-github-key.yml | 2 - changelogs/fragments/9187-flatpak-lang.yml | 2 - .../9189-scalway-lb-simplify-return.yml | 2 - .../9190-redfish-utils-unused-code.yml | 4 - ...-response-is-not-ok-with-error-message.yml | 2 - ...2-keycloak_clientscope_type-sort-lists.yml | 2 - .../ssh_config_add_dynamicforward_option.yml | 2 - 28 files changed, 238 insertions(+), 72 deletions(-) delete mode 100644 changelogs/fragments/10.1.0.yml delete mode 100644 changelogs/fragments/5932-launchd-plist.yml delete mode 100644 changelogs/fragments/7402-proxmox-template-support-server-side-artifact-fetching.yaml delete mode 100644 changelogs/fragments/9076-remove-duplicated-homebrew-package-name-validation.yml delete mode 100644 changelogs/fragments/9096-alternatives-add-family-parameter.yml delete mode 100644 changelogs/fragments/9123-redfish-command-custom-oem-params.yml delete mode 100644 changelogs/fragments/9124-dnf_config_manager.yml delete mode 100644 changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml delete mode 100644 changelogs/fragments/9132-cloudflare_dns-comment-and-tags.yml delete mode 100644 changelogs/fragments/9157-fix-dnf_config_manager-locale.yml delete mode 100644 changelogs/fragments/9159-iso-extract_add_password.yml delete mode 100644 changelogs/fragments/9167-rpm_ostree_pkg-apply_live.yml delete mode 100644 changelogs/fragments/9168-nmcli-add-sriov-parameter.yml delete mode 100644 changelogs/fragments/9171-gio-mime-fix-version.yml delete mode 100644 changelogs/fragments/9172-opkg-deprecate-force-none.yml delete mode 100644 changelogs/fragments/9179-deps-tests.yml delete mode 100644 changelogs/fragments/9180-pipx-version.yml delete mode 100644 changelogs/fragments/9181-improve-homebrew-module-performance.yml delete mode 100644 changelogs/fragments/9186-fix-broken-check-mode-in-github-key.yml delete mode 100644 changelogs/fragments/9187-flatpak-lang.yml delete mode 100644 changelogs/fragments/9189-scalway-lb-simplify-return.yml delete mode 100644 changelogs/fragments/9190-redfish-utils-unused-code.yml delete mode 100644 changelogs/fragments/9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml delete mode 100644 changelogs/fragments/9202-keycloak_clientscope_type-sort-lists.yml delete mode 100644 changelogs/fragments/ssh_config_add_dynamicforward_option.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index abcdfa6d64..e61f2f6cc5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,34 +2,103 @@ **Topics** -- v10\.0\.1 +- v10\.1\.0 - Release Summary - - Bugfixes -- v10\.0\.0 - - Release Summary - Minor Changes - - Breaking Changes / Porting Guide - Deprecated Features - - Removed Features \(previously deprecated\) - - Bugfixes - - Known Issues + - Bugfixes - New Plugins - Filter - - Test - 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\.0\.1 + +## v10\.1\.0 ### Release Summary -Bugfix release for inclusion in Ansible 11\.0\.0rc1\. +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)\)\. @@ -37,12 +106,12 @@ Bugfix release for inclusion in Ansible 11\.0\.0rc1\. ## 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)\)\. @@ -247,7 +316,7 @@ This is release 10\.0\.0 of community\.general\, released on 2024\- * 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)\)\. @@ -272,7 +341,7 @@ This is release 10\.0\.0 of community\.general\, released on 2024\- * 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)\)\. @@ -357,10 +426,10 @@ This is release 10\.0\.0 of community\.general\, released on 2024\- * 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\. @@ -373,7 +442,7 @@ This is release 10\.0\.0 of community\.general\, released on 2024\- * community\.general\.ansible\_type \- Validate input type\. - + ### New Modules * community\.general\.bootc\_manage \- Bootc Switch and Upgrade\. diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 7e920aa9fb..d8acb56285 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -6,6 +6,67 @@ Community General Release Notes This changelog describes changes after version 9.0.0. +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 ======= diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml index cbbaa1a49b..bfd4e9cd9a 100644 --- a/changelogs/changelog.yaml +++ b/changelogs/changelog.yaml @@ -758,3 +758,92 @@ releases: - 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' diff --git a/changelogs/fragments/10.1.0.yml b/changelogs/fragments/10.1.0.yml deleted file mode 100644 index 4b1469c9fe..0000000000 --- a/changelogs/fragments/10.1.0.yml +++ /dev/null @@ -1 +0,0 @@ -release_summary: Regular bugfix and feature release. diff --git a/changelogs/fragments/5932-launchd-plist.yml b/changelogs/fragments/5932-launchd-plist.yml deleted file mode 100644 index bf2530841a..0000000000 --- a/changelogs/fragments/5932-launchd-plist.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - 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). diff --git a/changelogs/fragments/7402-proxmox-template-support-server-side-artifact-fetching.yaml b/changelogs/fragments/7402-proxmox-template-support-server-side-artifact-fetching.yaml deleted file mode 100644 index 4a5fefdc96..0000000000 --- a/changelogs/fragments/7402-proxmox-template-support-server-side-artifact-fetching.yaml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - proxmox_template - add server side artifact fetching support (https://github.com/ansible-collections/community.general/pull/9113). \ No newline at end of file diff --git a/changelogs/fragments/9076-remove-duplicated-homebrew-package-name-validation.yml b/changelogs/fragments/9076-remove-duplicated-homebrew-package-name-validation.yml deleted file mode 100644 index b067625c0c..0000000000 --- a/changelogs/fragments/9076-remove-duplicated-homebrew-package-name-validation.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - homebrew - remove duplicated package name validation (https://github.com/ansible-collections/community.general/pull/9076). diff --git a/changelogs/fragments/9096-alternatives-add-family-parameter.yml b/changelogs/fragments/9096-alternatives-add-family-parameter.yml deleted file mode 100644 index a0b021f892..0000000000 --- a/changelogs/fragments/9096-alternatives-add-family-parameter.yml +++ /dev/null @@ -1,2 +0,0 @@ -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). diff --git a/changelogs/fragments/9123-redfish-command-custom-oem-params.yml b/changelogs/fragments/9123-redfish-command-custom-oem-params.yml deleted file mode 100644 index a09219515a..0000000000 --- a/changelogs/fragments/9123-redfish-command-custom-oem-params.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - 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). diff --git a/changelogs/fragments/9124-dnf_config_manager.yml b/changelogs/fragments/9124-dnf_config_manager.yml deleted file mode 100644 index 9c87f02d64..0000000000 --- a/changelogs/fragments/9124-dnf_config_manager.yml +++ /dev/null @@ -1,2 +0,0 @@ -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). diff --git a/changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml b/changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml deleted file mode 100644 index 69765958fb..0000000000 --- a/changelogs/fragments/9128-homebrew_cask-name-regex-fix.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - homebrew_cask - allow ``+`` symbol in Homebrew cask name validation regex (https://github.com/ansible-collections/community.general/pull/9128). diff --git a/changelogs/fragments/9132-cloudflare_dns-comment-and-tags.yml b/changelogs/fragments/9132-cloudflare_dns-comment-and-tags.yml deleted file mode 100644 index b601e39f55..0000000000 --- a/changelogs/fragments/9132-cloudflare_dns-comment-and-tags.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - cloudflare_dns - add support for ``comment`` and ``tags`` (https://github.com/ansible-collections/community.general/pull/9132). diff --git a/changelogs/fragments/9157-fix-dnf_config_manager-locale.yml b/changelogs/fragments/9157-fix-dnf_config_manager-locale.yml deleted file mode 100644 index f2084dfa5f..0000000000 --- a/changelogs/fragments/9157-fix-dnf_config_manager-locale.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - 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). \ No newline at end of file diff --git a/changelogs/fragments/9159-iso-extract_add_password.yml b/changelogs/fragments/9159-iso-extract_add_password.yml deleted file mode 100644 index f1b2650d4f..0000000000 --- a/changelogs/fragments/9159-iso-extract_add_password.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - iso_extract - adds ``password`` parameter that is passed to 7z (https://github.com/ansible-collections/community.general/pull/9159). diff --git a/changelogs/fragments/9167-rpm_ostree_pkg-apply_live.yml b/changelogs/fragments/9167-rpm_ostree_pkg-apply_live.yml deleted file mode 100644 index e473dedd0b..0000000000 --- a/changelogs/fragments/9167-rpm_ostree_pkg-apply_live.yml +++ /dev/null @@ -1,3 +0,0 @@ -minor_changes: -- 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). diff --git a/changelogs/fragments/9168-nmcli-add-sriov-parameter.yml b/changelogs/fragments/9168-nmcli-add-sriov-parameter.yml deleted file mode 100644 index 77f28e73bf..0000000000 --- a/changelogs/fragments/9168-nmcli-add-sriov-parameter.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - nmcli - add ``sriov`` parameter that enables support for SR-IOV settings (https://github.com/ansible-collections/community.general/pull/9168). diff --git a/changelogs/fragments/9171-gio-mime-fix-version.yml b/changelogs/fragments/9171-gio-mime-fix-version.yml deleted file mode 100644 index ca9dbddd7f..0000000000 --- a/changelogs/fragments/9171-gio-mime-fix-version.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - 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). diff --git a/changelogs/fragments/9172-opkg-deprecate-force-none.yml b/changelogs/fragments/9172-opkg-deprecate-force-none.yml deleted file mode 100644 index 1b11419c5a..0000000000 --- a/changelogs/fragments/9172-opkg-deprecate-force-none.yml +++ /dev/null @@ -1,2 +0,0 @@ -deprecated_features: - - opkg - deprecate value ``""`` for parameter ``force`` (https://github.com/ansible-collections/community.general/pull/9172). diff --git a/changelogs/fragments/9179-deps-tests.yml b/changelogs/fragments/9179-deps-tests.yml deleted file mode 100644 index 1ddf109033..0000000000 --- a/changelogs/fragments/9179-deps-tests.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - deps module utils - add ``deps.clear()`` to clear out previously declared dependencies (https://github.com/ansible-collections/community.general/pull/9179). diff --git a/changelogs/fragments/9180-pipx-version.yml b/changelogs/fragments/9180-pipx-version.yml deleted file mode 100644 index f07d66c83c..0000000000 --- a/changelogs/fragments/9180-pipx-version.yml +++ /dev/null @@ -1,3 +0,0 @@ -minor_changes: - - 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). diff --git a/changelogs/fragments/9181-improve-homebrew-module-performance.yml b/changelogs/fragments/9181-improve-homebrew-module-performance.yml deleted file mode 100644 index b3b6ba2ca4..0000000000 --- a/changelogs/fragments/9181-improve-homebrew-module-performance.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - homebrew - greatly speed up module when multiple packages are passed in the ``name`` option (https://github.com/ansible-collections/community.general/pull/9181). \ No newline at end of file diff --git a/changelogs/fragments/9186-fix-broken-check-mode-in-github-key.yml b/changelogs/fragments/9186-fix-broken-check-mode-in-github-key.yml deleted file mode 100644 index dbf1f145d5..0000000000 --- a/changelogs/fragments/9186-fix-broken-check-mode-in-github-key.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - 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). \ No newline at end of file diff --git a/changelogs/fragments/9187-flatpak-lang.yml b/changelogs/fragments/9187-flatpak-lang.yml deleted file mode 100644 index 159923cbdc..0000000000 --- a/changelogs/fragments/9187-flatpak-lang.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - 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). diff --git a/changelogs/fragments/9189-scalway-lb-simplify-return.yml b/changelogs/fragments/9189-scalway-lb-simplify-return.yml deleted file mode 100644 index 39d161f06b..0000000000 --- a/changelogs/fragments/9189-scalway-lb-simplify-return.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - scaleway_lb - minor simplification in the code (https://github.com/ansible-collections/community.general/pull/9189). diff --git a/changelogs/fragments/9190-redfish-utils-unused-code.yml b/changelogs/fragments/9190-redfish-utils-unused-code.yml deleted file mode 100644 index 47f7588b96..0000000000 --- a/changelogs/fragments/9190-redfish-utils-unused-code.yml +++ /dev/null @@ -1,4 +0,0 @@ -minor_changes: - - redfish_utils module utils - remove redundant code (https://github.com/ansible-collections/community.general/pull/9190). -deprecated_features: - - redfish_utils module utils - deprecate method ``RedfishUtils._init_session()`` (https://github.com/ansible-collections/community.general/pull/9190). diff --git a/changelogs/fragments/9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml b/changelogs/fragments/9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml deleted file mode 100644 index 56ab25f578..0000000000 --- a/changelogs/fragments/9198-fail-if-slack-api-response-is-not-ok-with-error-message.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - slack - fail if Slack API response is not OK with error message (https://github.com/ansible-collections/community.general/pull/9198). diff --git a/changelogs/fragments/9202-keycloak_clientscope_type-sort-lists.yml b/changelogs/fragments/9202-keycloak_clientscope_type-sort-lists.yml deleted file mode 100644 index ef9fc7a6f7..0000000000 --- a/changelogs/fragments/9202-keycloak_clientscope_type-sort-lists.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - keycloak_clientscope_type - sort the default and optional clientscope lists to improve the diff (https://github.com/ansible-collections/community.general/pull/9202). \ No newline at end of file diff --git a/changelogs/fragments/ssh_config_add_dynamicforward_option.yml b/changelogs/fragments/ssh_config_add_dynamicforward_option.yml deleted file mode 100644 index 0252c94c46..0000000000 --- a/changelogs/fragments/ssh_config_add_dynamicforward_option.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ssh_config - add ``dynamicforward`` option (https://github.com/ansible-collections/community.general/pull/9192). \ No newline at end of file From b3f669a5745b68ff13a3bd35ad22bd69248e26e3 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 2 Dec 2024 21:49:20 +0100 Subject: [PATCH 048/302] The next expected release will be 10.2.0. --- galaxy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/galaxy.yml b/galaxy.yml index 4daf0e0ac0..4ff0768938 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -5,7 +5,7 @@ namespace: community name: general -version: 10.1.0 +version: 10.2.0 readme: README.md authors: - Ansible (https://github.com/ansible) From 859039c47ac85610d1dc2d6004e4395f3650bfa9 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 9 Dec 2024 19:38:40 +0100 Subject: [PATCH 049/302] [PR #9223/6f87bf2b backport][stable-10] Fix incorrect key lookup (#9232) Fix incorrect key lookup (#9223) * Fix incorrect key lookup * Create changelog fragment (cherry picked from commit 6f87bf2bade07f5ef47f15700b7d0ae89c78145a) Co-authored-by: IamLunchbox <56757745+IamLunchbox@users.noreply.github.com> --- changelogs/fragments/9223-proxmox-backup-bugfixes.yml | 2 ++ plugins/modules/proxmox_backup.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9223-proxmox-backup-bugfixes.yml diff --git a/changelogs/fragments/9223-proxmox-backup-bugfixes.yml b/changelogs/fragments/9223-proxmox-backup-bugfixes.yml new file mode 100644 index 0000000000..559e1f45bc --- /dev/null +++ b/changelogs/fragments/9223-proxmox-backup-bugfixes.yml @@ -0,0 +1,2 @@ +bugfixes: + - proxmox_backup - fix incorrect key lookup in vmid permission check (https://github.com/ansible-collections/community.general/pull/9223). diff --git a/plugins/modules/proxmox_backup.py b/plugins/modules/proxmox_backup.py index fb5750383e..575d492bf9 100644 --- a/plugins/modules/proxmox_backup.py +++ b/plugins/modules/proxmox_backup.py @@ -325,7 +325,7 @@ class ProxmoxBackupAnsible(ProxmoxAnsible): if "/" in permissions.keys() and permissions["/"].get( "VM.Backup", 0) == 1: sufficient_permissions = True - elif "/vms" in permissions.keys() and permissions["/"].get( + elif "/vms" in permissions.keys() and permissions["/vms"].get( "VM.Backup", 0) == 1: sufficient_permissions = True elif pool and "/pool/" + pool in permissions.keys() and permissions["/pool/" + pool].get( From a1c39cc8820efa6c52658065d5b9c5c4c89ee0ee Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 9 Dec 2024 19:38:50 +0100 Subject: [PATCH 050/302] [PR #9174/d7ad7c2d backport][stable-10] xbps: support --rootdir and --repository (#9233) xbps: support --rootdir and --repository (#9174) * xbps: support --rootdir and --repository * please the robot * rename repository arg to repositories * skip repo flag when querying package state * add accept_pubkey param, detect pubkey import fail * add example for manually copying signing keys * bugfix package removal * fix typos * change root param type to path * fix "root" type, bump version_added * lintfix (cherry picked from commit d7ad7c2dcad5bde031ffd969059ebd0e77c90b2c) Co-authored-by: snailed --- ...74-xbps-support-rootdir-and-repository.yml | 2 + plugins/modules/xbps.py | 74 ++++++++++++++++++- 2 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9174-xbps-support-rootdir-and-repository.yml diff --git a/changelogs/fragments/9174-xbps-support-rootdir-and-repository.yml b/changelogs/fragments/9174-xbps-support-rootdir-and-repository.yml new file mode 100644 index 0000000000..9197607684 --- /dev/null +++ b/changelogs/fragments/9174-xbps-support-rootdir-and-repository.yml @@ -0,0 +1,2 @@ +minor_changes: + - xbps - add ``root`` and ``repository`` options to enable bootstrapping new void installations (https://github.com/ansible-collections/community.general/pull/9174). diff --git a/plugins/modules/xbps.py b/plugins/modules/xbps.py index bcbbb3f021..cd34029eba 100644 --- a/plugins/modules/xbps.py +++ b/plugins/modules/xbps.py @@ -67,6 +67,26 @@ options: type: bool default: true version_added: '0.2.0' + root: + description: + - The full path for the target root directory. + type: path + version_added: '10.2.0' + repositories: + description: + - Repository URL(s) to prepend to the repository list for the + package installation. + The URL can be a URL to a repository for + remote repositories or a path for local repositories. + type: list + elements: str + version_added: '10.2.0' + accept_pubkey: + description: + - Whether or not repository signing keys should be automatically accepted. + type: bool + default: false + version_added: '10.2.0' ''' EXAMPLES = ''' @@ -107,6 +127,30 @@ EXAMPLES = ''' name: foo state: present upgrade_xbps: false + +- name: Find repository keys to install into a new void system on a mounted partition + ansible.builtin.find: + path: /var/db/xbps/keys + pattern: "*.plist" + register: xbps_keys + +- name: Copy repository keys to into a new void system on a mounted partition + ansible.builtin.copy: + remote_src: true + src: "{{ item }}" + dest: "/mnt/{{ item }}" + owner: root + group: root + mode: "0644" + when: xbps_keys.matched > 0 + loop: "{{ xbps_keys.files | map(attribute='path') }}" + +- name: Install a new void system on a mounted partition + community.general.xbps: + name: base-system + state: present + repositories: https://repo-default.voidlinux.org/current + root: /mnt ''' RETURN = ''' @@ -133,16 +177,29 @@ def is_installed(xbps_output): return bool(len(xbps_output)) +def append_flags(module, xbps_path, cmd, skip_repo=False): + """Appends the repository/root flags when needed""" + if module.params["root"]: + cmd = "%s -r %s" % (cmd, module.params["root"]) + if module.params["repositories"] and not cmd.startswith(xbps_path["remove"]) and not skip_repo: + for repo in module.params["repositories"]: + cmd = "%s --repository=%s" % (cmd, repo) + + return cmd + + def query_package(module, xbps_path, name, state="present"): """Returns Package info""" if state == "present": lcmd = "%s %s" % (xbps_path['query'], name) + lcmd = append_flags(module, xbps_path, lcmd, skip_repo=True) lrc, lstdout, lstderr = module.run_command(lcmd, check_rc=False) if not is_installed(lstdout): # package is not installed locally return False, False rcmd = "%s -Sun" % (xbps_path['install']) + rcmd = append_flags(module, xbps_path, rcmd) rrc, rstdout, rstderr = module.run_command(rcmd, check_rc=False) if rrc == 0 or rrc == 17: """Return True to indicate that the package is installed locally, @@ -156,8 +213,15 @@ def query_package(module, xbps_path, name, state="present"): def update_package_db(module, xbps_path): """Returns True if update_package_db changed""" cmd = "%s -S" % (xbps_path['install']) - rc, stdout, stderr = module.run_command(cmd, check_rc=False) + cmd = append_flags(module, xbps_path, cmd) + if module.params['accept_pubkey']: + stdin = "y\n" + else: + stdin = "n\n" + rc, stdout, stderr = module.run_command(cmd, check_rc=False, data=stdin) + if "Failed to import pubkey" in stderr: + module.fail_json(msg="Failed to import pubkey for repository") if rc != 0: module.fail_json(msg="Could not update package db") if "avg rate" in stdout: @@ -168,6 +232,7 @@ def update_package_db(module, xbps_path): def upgrade_xbps(module, xbps_path, exit_on_success=False): cmdupgradexbps = "%s -uy xbps" % (xbps_path['install']) + cmdupgradexbps = append_flags(module, xbps_path, cmdupgradexbps) rc, stdout, stderr = module.run_command(cmdupgradexbps, check_rc=False) if rc != 0: module.fail_json(msg='Could not upgrade xbps itself') @@ -177,6 +242,8 @@ def upgrade(module, xbps_path): """Returns true is full upgrade succeeds""" cmdupgrade = "%s -uy" % (xbps_path['install']) cmdneedupgrade = "%s -un" % (xbps_path['install']) + cmdupgrade = append_flags(module, xbps_path, cmdupgrade) + cmdneedupgrade = append_flags(module, xbps_path, cmdneedupgrade) rc, stdout, stderr = module.run_command(cmdneedupgrade, check_rc=False) if rc == 0: @@ -210,6 +277,7 @@ def remove_packages(module, xbps_path, packages): continue cmd = "%s -y %s" % (xbps_path['remove'], package) + cmd = append_flags(module, xbps_path, cmd, skip_repo=True) rc, stdout, stderr = module.run_command(cmd, check_rc=False) if rc != 0: @@ -242,6 +310,7 @@ def install_packages(module, xbps_path, state, packages): module.exit_json(changed=False, msg="Nothing to Install") cmd = "%s -y %s" % (xbps_path['install'], " ".join(toInstall)) + cmd = append_flags(module, xbps_path, cmd) rc, stdout, stderr = module.run_command(cmd, check_rc=False) if rc == 16 and module.params['upgrade_xbps']: @@ -308,6 +377,9 @@ def main(): upgrade=dict(default=False, type='bool'), update_cache=dict(default=True, type='bool'), upgrade_xbps=dict(default=True, type='bool'), + root=dict(type='path'), + repositories=dict(type='list', elements='str'), + accept_pubkey=dict(default=False, type='bool') ), required_one_of=[['name', 'update_cache', 'upgrade']], supports_check_mode=True) From 7bc937b5e8f603f9a52ffa35816eed2a59763c06 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 13 Dec 2024 22:41:07 +0100 Subject: [PATCH 051/302] [PR #9243/9df4ef9a backport][stable-10] sysrc: add another exclusion for ezjail (#9246) sysrc: add another exclusion for ezjail (#9243) Add another exclusion. (cherry picked from commit 9df4ef9a9c4120eeebf9ed7a25e2e1154aa3f3b1) Co-authored-by: Felix Fontein --- tests/integration/targets/sysrc/tasks/main.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/integration/targets/sysrc/tasks/main.yml b/tests/integration/targets/sysrc/tasks/main.yml index ace38202f2..25d7ca4d59 100644 --- a/tests/integration/targets/sysrc/tasks/main.yml +++ b/tests/integration/targets/sysrc/tasks/main.yml @@ -141,10 +141,12 @@ # # NOTE: currently fails with FreeBSD 12 with minor version less than 4 # NOTE: currently fails with FreeBSD 13 with minor version less than 2 + # NOTE: currently fails with FreeBSD 14 with minor version less than 1 # when: >- ansible_distribution_version is version('12.4', '>=') and ansible_distribution_version is version('13', '<') - or ansible_distribution_version is version('13.2', '>=') + or ansible_distribution_version is version('13.2', '>=') and ansible_distribution_version is version('14', '<') + or ansible_distribution_version is version('14.1', '>=') block: - name: Setup testjail include_tasks: setup-testjail.yml From a89990ab9bbe3f1078c1e4e45da2c7ecc65f14ad Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 14 Dec 2024 10:44:16 +0100 Subject: [PATCH 052/302] [PR #9242/88ea025d backport][stable-10] test helper improvements (#9247) test helper improvements (#9242) (cherry picked from commit 88ea025d1293312a4c74cfd3f795785f7e46653a) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- tests/unit/plugins/modules/helper.py | 65 ++++++++++++------- tests/unit/plugins/modules/test_snap.py | 2 +- .../unit/plugins/modules/test_xfconf_info.py | 4 +- .../plugins/modules/test_xfconf_info.yaml | 5 +- 4 files changed, 50 insertions(+), 26 deletions(-) diff --git a/tests/unit/plugins/modules/helper.py b/tests/unit/plugins/modules/helper.py index 0626e39f1c..8071bc2aa9 100644 --- a/tests/unit/plugins/modules/helper.py +++ b/tests/unit/plugins/modules/helper.py @@ -13,20 +13,25 @@ import yaml import pytest +from ansible.module_utils.common._collections_compat import Sequence + + class Helper(object): + TEST_SPEC_VALID_SECTIONS = ["anchors", "test_cases"] + @staticmethod - def from_list(test_module, ansible_module, test_cases): - helper = Helper(test_module, ansible_module, test_cases=test_cases) + def from_spec(test_module, ansible_module, test_spec, mocks=None): + helper = Helper(test_module, ansible_module, test_spec=test_spec, mocks=mocks) return helper @staticmethod - def from_file(test_module, ansible_module, filename): + def from_file(test_module, ansible_module, filename, mocks=None): with open(filename, "r") as test_cases: - test_cases_data = yaml.safe_load(test_cases) - return Helper.from_list(test_module, ansible_module, test_cases_data) + test_spec = yaml.safe_load(test_cases) + return Helper.from_spec(test_module, ansible_module, test_spec, mocks) @staticmethod - def from_module(ansible_module, test_module_name, test_spec=None): + def from_module(ansible_module, test_module_name, test_spec=None, mocks=None): test_module = sys.modules[test_module_name] if test_spec is None: test_spec = test_module.__file__.replace('.py', '.yaml') @@ -35,14 +40,22 @@ class Helper(object): def add_func_to_test_module(self, name, func): setattr(self.test_module, name, func) - def __init__(self, test_module, ansible_module, test_cases): + def __init__(self, test_module, ansible_module, test_spec, mocks=None): self.test_module = test_module self.ansible_module = ansible_module self.test_cases = [] self.fixtures = {} + if isinstance(test_spec, Sequence): + test_cases = test_spec + else: # it is a dict + test_cases = test_spec['test_cases'] + spec_diff = set(test_spec.keys()) - set(self.TEST_SPEC_VALID_SECTIONS) + if spec_diff: + raise ValueError("Test specification contain unknown keys: {0}".format(", ".join(spec_diff))) + self.mocks_map = {m.name: m for m in mocks} if mocks else {} for test_case in test_cases: - tc = ModuleTestCase.make_test_case(test_case, test_module) + tc = ModuleTestCase.make_test_case(test_case, test_module, self.mocks_map) self.test_cases.append(tc) self.fixtures.update(tc.fixtures) self.set_test_func() @@ -99,7 +112,7 @@ class ModuleTestCase: self.id = id self.input = input self.output = output - self._mocks = mocks + self.mock_specs = mocks self.mocks = {} self.flags = flags @@ -124,23 +137,23 @@ class ModuleTestCase: ) @staticmethod - def make_test_case(test_case, test_module): + def make_test_case(test_case_spec, test_module, mocks_map): tc = ModuleTestCase( - id=test_case["id"], - input=test_case.get("input", {}), - output=test_case.get("output", {}), - mocks=test_case.get("mocks", {}), - flags=test_case.get("flags", {}) + id=test_case_spec["id"], + input=test_case_spec.get("input", {}), + output=test_case_spec.get("output", {}), + mocks=test_case_spec.get("mocks", {}), + flags=test_case_spec.get("flags", {}) ) - tc.build_mocks(test_module) + tc.build_mocks(test_module, mocks_map) return tc - def build_mocks(self, test_module): - for mock, mock_spec in self._mocks.items(): - mock_class = self.get_mock_class(test_module, mock) - self.mocks[mock] = mock_class.build_mock(mock_spec) + def build_mocks(self, test_module, mocks_map): + for mock_name, mock_spec in self.mock_specs.items(): + mock_class = mocks_map.get(mock_name, self.get_mock_class(test_module, mock_name)) + self.mocks[mock_name] = mock_class.build_mock(mock_spec) - self._fixtures.update(self.mocks[mock].fixtures()) + self._fixtures.update(self.mocks[mock_name].fixtures()) @staticmethod def get_mock_class(test_module, mock): @@ -187,6 +200,10 @@ class ModuleTestCase: class TestCaseMock: + @property + def name(self): + raise NotImplementedError() + @classmethod def build_mock(cls, mock_specs): return cls(mock_specs) @@ -205,6 +222,10 @@ class TestCaseMock: class RunCommandMock(TestCaseMock): + @property + def name(self): + return "run_command" + def __str__(self): return "".format(specs=self.mock_specs) @@ -214,7 +235,7 @@ class RunCommandMock(TestCaseMock): def fixtures(self): @pytest.fixture def patch_bin(mocker): - def mockie(self, path, *args, **kwargs): + def mockie(self_, path, *args, **kwargs): return "/testbin/{0}".format(path) mocker.patch('ansible.module_utils.basic.AnsibleModule.get_bin_path', mockie) diff --git a/tests/unit/plugins/modules/test_snap.py b/tests/unit/plugins/modules/test_snap.py index d70094551a..de7f35353a 100644 --- a/tests/unit/plugins/modules/test_snap.py +++ b/tests/unit/plugins/modules/test_snap.py @@ -475,4 +475,4 @@ TEST_CASES = [ ), ] -Helper.from_list(sys.modules[__name__], snap, TEST_CASES) +Helper.from_spec(sys.modules[__name__], snap, TEST_CASES) diff --git a/tests/unit/plugins/modules/test_xfconf_info.py b/tests/unit/plugins/modules/test_xfconf_info.py index 308f075490..4cdb92b305 100644 --- a/tests/unit/plugins/modules/test_xfconf_info.py +++ b/tests/unit/plugins/modules/test_xfconf_info.py @@ -7,7 +7,7 @@ __metaclass__ = type from ansible_collections.community.general.plugins.modules import xfconf_info -from .helper import Helper, RunCommandMock # pylint: disable=unused-import +from .helper import Helper, RunCommandMock -Helper.from_module(xfconf_info, __name__) +Helper.from_module(xfconf_info, __name__, mocks=[RunCommandMock]) diff --git a/tests/unit/plugins/modules/test_xfconf_info.yaml b/tests/unit/plugins/modules/test_xfconf_info.yaml index 26f77ce474..535e50602f 100644 --- a/tests/unit/plugins/modules/test_xfconf_info.yaml +++ b/tests/unit/plugins/modules/test_xfconf_info.yaml @@ -4,6 +4,9 @@ # SPDX-License-Identifier: GPL-3.0-or-later --- +anchors: + environ: &env-def {environ_update: {LANGUAGE: C, LC_ALL: C}, check_rc: true} +test_cases: - id: test_simple_property_get input: channel: xfwm4 @@ -14,7 +17,7 @@ mocks: run_command: - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/inactive_opacity] - environ: &env-def {environ_update: {LANGUAGE: C, LC_ALL: C}, check_rc: true} + environ: *env-def rc: 0 out: "100\n" err: "" From 3f2968319168f50a2ac33e8d3fa22941929c3062 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 14 Dec 2024 11:13:39 +0100 Subject: [PATCH 053/302] [PR #9234/34e8e8e5 backport][stable-10] Fix VerifyBiosAttributes command on Systems with multiple entries (#9249) Fix VerifyBiosAttributes command on Systems with multiple entries (#9234) * Fix verify_bios_attributes command * Add changelog fragment * Update changelogs/fragments/9234-fix-verify-bios-attributes-multi-system.yml Improve fragment Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --------- Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> (cherry picked from commit 34e8e8e5d18ab339556c922c28967d77faa0084c) Co-authored-by: Scott Seekamp --- .../9234-fix-verify-bios-attributes-multi-system.yml | 2 ++ plugins/module_utils/redfish_utils.py | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/9234-fix-verify-bios-attributes-multi-system.yml diff --git a/changelogs/fragments/9234-fix-verify-bios-attributes-multi-system.yml b/changelogs/fragments/9234-fix-verify-bios-attributes-multi-system.yml new file mode 100644 index 0000000000..95bafed8d8 --- /dev/null +++ b/changelogs/fragments/9234-fix-verify-bios-attributes-multi-system.yml @@ -0,0 +1,2 @@ +bugfixes: + - redfish_utils module utils - Fix ``VerifyBiosAttributes`` command on multi system resource nodes (https://github.com/ansible-collections/community.general/pull/9234). diff --git a/plugins/module_utils/redfish_utils.py b/plugins/module_utils/redfish_utils.py index dd559921ae..253395ea93 100644 --- a/plugins/module_utils/redfish_utils.py +++ b/plugins/module_utils/redfish_utils.py @@ -3616,7 +3616,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 @@ -3625,8 +3625,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}) From 8f76c847fe05c937a476849ac0e283fb06a4821c Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 14 Dec 2024 15:17:05 +0100 Subject: [PATCH 054/302] [PR #9250/f6dae1fc backport][stable-10] CI: Fix some issues pointed out by zizmor (#9253) CI: Fix some issues pointed out by zizmor (#9250) Fix some issues pointed out by zizmor. (cherry picked from commit f6dae1fc4d2edbb44871045e573c781d0911fa06) Co-authored-by: Felix Fontein --- .github/workflows/codeql-analysis.yml | 2 ++ .github/workflows/reuse.yml | 1 + 2 files changed, 3 insertions(+) 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 7c6f76bd5b..3c5e986e57 100644 --- a/.github/workflows/reuse.yml +++ b/.github/workflows/reuse.yml @@ -28,6 +28,7 @@ jobs: steps: - uses: actions/checkout@v4 with: + persist-credentials: false ref: ${{ github.event.pull_request.head.sha || '' }} - name: REUSE Compliance Check From 161539729d3f2d46934939a3d42c72ecc98e66d8 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 16 Dec 2024 20:58:52 +0100 Subject: [PATCH 055/302] [PR #9259/65827bdc backport][stable-10] Drop myself from team_suse (#9266) Drop myself from team_suse (#9259) I no longer work with ansible and/or SUSE so drop me from the team. (cherry picked from commit 65827bdc965006a3448d6f2702320dd07914155e) Co-authored-by: Thomas Bechtold --- .github/BOTMETA.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index ec9b9b7ddc..6896106906 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -1565,6 +1565,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 From 6e42e442bca06e4def07497bc44660f1e512be8b Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 17 Dec 2024 21:33:34 +0100 Subject: [PATCH 056/302] [PR #9271/50b25f8c backport][stable-10] random_words integration tests: avoid test failure due to valid result (#9274) random_words integration tests: avoid test failure due to valid result (#9271) Avoid test failure due to valid result. (cherry picked from commit 50b25f8c01f86e6467cd7228881163bdfeff2dbb) Co-authored-by: Felix Fontein --- tests/integration/targets/lookup_random_words/test.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/integration/targets/lookup_random_words/test.yml b/tests/integration/targets/lookup_random_words/test.yml index 90c6727304..e1b6fde13b 100644 --- a/tests/integration/targets/lookup_random_words/test.yml +++ b/tests/integration/targets/lookup_random_words/test.yml @@ -27,6 +27,7 @@ - result4[0] | length >= 17 - result4[0] | length <= 29 - result4[0] | regex_findall("[A-Z]") | length == 3 - - result4[0].count("-") == 2 + # If one of the random words is 't-shirt', there are more than 2 dashes... + - result4[0].count("-") == 2 or "t-shirt" in result4[0].lower() - result5 | length == 1 - result5[0] | length == 15 From 7537674d4b6aa53a0ba7601074fb9cd601daeaa3 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 20 Dec 2024 22:40:24 +0100 Subject: [PATCH 057/302] [PR #9282/dcdec6ee backport][stable-10] mh guide: update exception handling (#9285) mh guide: update exception handling (#9282) (cherry picked from commit dcdec6ee4e35891c7092e8222e5fccbedab3f481) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- docs/docsite/rst/guide_modulehelper.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/docsite/rst/guide_modulehelper.rst b/docs/docsite/rst/guide_modulehelper.rst index 68b46e6c94..e3c7a124cf 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 From 910fb933a7bed3cf521b05bfb9b4b5e2f1afa332 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 20 Dec 2024 22:51:13 +0100 Subject: [PATCH 058/302] [PR #9279/d629a50b backport][stable-10] yarn: adjust docs (#9287) yarn: adjust docs (#9279) (cherry picked from commit d629a50b17f7087c9be85bc0eaa6867dbeb4697f) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/yarn.py | 134 ++++++++++++++++------------------------ 1 file changed, 53 insertions(+), 81 deletions(-) diff --git a/plugins/modules/yarn.py b/plugins/modules/yarn.py index c278951d5e..a2a3c471b7 100644 --- a/plugins/modules/yarn.py +++ b/plugins/modules/yarn.py @@ -11,12 +11,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: yarn -short_description: Manage node.js packages with Yarn +short_description: Manage Node.js packages with Yarn description: - - Manage node.js packages with the Yarn package manager (https://yarnpkg.com/) + - Manage Node.js packages with the Yarn package manager U(https://yarnpkg.com/). author: - "David Gunter (@verkaufer)" - "Chris Hoffman (@chrishoffman), creator of NPM Ansible module)" @@ -31,25 +30,25 @@ options: name: type: str description: - - The name of a node.js library to install + - The name of a Node.js library to install. - If omitted all packages in package.json are installed. - - To globally install from local node.js library. Prepend "file:" to the path of the node.js library. + - To globally install from local Node.js library. Prepend C(file:) to the path of the Node.js library. required: false path: type: path description: - The base path where Node.js libraries will be installed. - - This is where the node_modules folder lives. + - This is where the C(node_modules) folder lives. required: false version: type: str description: - The version of the library to be installed. - - Must be in semver format. If "latest" is desired, use "state" arg instead + - Must be in semver format. If "latest" is desired, use O(state) arg instead. required: false global: description: - - Install the node.js library globally + - Install the Node.js library globally. required: false default: false type: bool @@ -60,14 +59,14 @@ options: required: false ignore_scripts: description: - - Use the --ignore-scripts flag when installing. + - Use the C(--ignore-scripts) flag when installing. required: false type: bool default: false production: description: - Install dependencies in production mode. - - Yarn will ignore any dependencies under devDependencies in package.json + - Yarn will ignore any dependencies under devDependencies in C(package.json). required: false type: bool default: false @@ -79,88 +78,61 @@ options: state: type: str description: - - Installation state of the named node.js library - - If absent is selected, a name option must be provided + - Installation state of the named Node.js library. + - If V(absent) is selected, a O(name) option must be provided. required: false default: present - choices: [ "present", "absent", "latest" ] + choices: ["present", "absent", "latest"] requirements: - - Yarn installed in bin path (typically /usr/local/bin) -''' + - Yarn installed in bin path (typically C(/usr/local/bin)) +""" -EXAMPLES = ''' -- name: Install "imagemin" node.js package. - community.general.yarn: - name: imagemin - path: /app/location +EXAMPLES = r""" + - name: Install "imagemin" Node.js package. + community.general.yarn: + name: imagemin + path: /app/location -- name: Install "imagemin" node.js package on version 5.3.1 - community.general.yarn: - name: imagemin - version: '5.3.1' - path: /app/location + - name: Install "imagemin" Node.js package on version 5.3.1 + community.general.yarn: + name: imagemin + version: '5.3.1' + path: /app/location -- name: Install "imagemin" node.js package globally. - community.general.yarn: - name: imagemin - global: true + - name: Install "imagemin" Node.js package globally. + community.general.yarn: + name: imagemin + global: true -- name: Remove the globally-installed package "imagemin". - community.general.yarn: - name: imagemin - global: true - state: absent + - name: Remove the globally-installed package "imagemin". + community.general.yarn: + name: imagemin + global: true + state: absent -- name: Install "imagemin" node.js package from custom registry. - community.general.yarn: - name: imagemin - registry: 'http://registry.mysite.com' + - name: Install "imagemin" Node.js package from custom registry. + community.general.yarn: + name: imagemin + registry: 'http://registry.mysite.com' -- name: Install packages based on package.json. - community.general.yarn: - path: /app/location + - name: Install packages based on package.json. + community.general.yarn: + path: /app/location -- name: Update all packages in package.json to their latest version. - community.general.yarn: - path: /app/location - state: latest -''' + - name: Update all packages in package.json to their latest version. + community.general.yarn: + path: /app/location + state: latest +""" -RETURN = ''' -changed: - description: Whether Yarn changed any package data - returned: always - type: bool - sample: true -msg: - description: Provides an error message if Yarn syntax was incorrect - returned: failure - type: str - sample: "Package must be explicitly named when uninstalling." -invocation: - description: Parameters and values used during execution - returned: success - type: dict - sample: { - "module_args": { - "executable": null, - "globally": false, - "ignore_scripts": false, - "name": null, - "path": "/some/path/folder", - "production": false, - "registry": null, - "state": "present", - "version": null - } - } +RETURN = r""" out: - description: Output generated from Yarn. - returned: always - type: str - sample: "yarn add v0.16.1[1/4] Resolving packages...[2/4] Fetching packages...[3/4] Linking dependencies...[4/4] - Building fresh packages...success Saved lockfile.success Saved 1 new dependency..left-pad@1.1.3 Done in 0.59s." -''' + description: Output generated from Yarn. + returned: always + type: str + sample: "yarn add v0.16.1[1/4] Resolving packages...[2/4] Fetching packages...[3/4] Linking dependencies...[4/4] Building fresh packages...success + Saved lockfile.success Saved 1 new dependency..left-pad@1.1.3 Done in 0.59s." +""" import os import json From 5ab43f0ff16feb3cadc84c59081f9d664ecc3fc6 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 20 Dec 2024 23:06:31 +0100 Subject: [PATCH 059/302] [PR #9263/2682ec47 backport][stable-10] keycloak_authentication: Fix priority attribute during execution updates (#9292) keycloak_authentication: Fix priority attribute during execution updates (#9263) keycloak_authentication: Fix priority attribute during execution updates. (cherry picked from commit 2682ec47d9edf21a1ea4ed99a81c00cf857e636a) Co-authored-by: Florian Apolloner --- .../9263-kc_authentication-api-priority.yaml | 2 ++ plugins/modules/keycloak_authentication.py | 11 +++++++---- 2 files changed, 9 insertions(+), 4 deletions(-) create mode 100644 changelogs/fragments/9263-kc_authentication-api-priority.yaml diff --git a/changelogs/fragments/9263-kc_authentication-api-priority.yaml b/changelogs/fragments/9263-kc_authentication-api-priority.yaml new file mode 100644 index 0000000000..a943e659ad --- /dev/null +++ b/changelogs/fragments/9263-kc_authentication-api-priority.yaml @@ -0,0 +1,2 @@ +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). \ No newline at end of file diff --git a/plugins/modules/keycloak_authentication.py b/plugins/modules/keycloak_authentication.py index bc2898d9be..5945890bb7 100644 --- a/plugins/modules/keycloak_authentication.py +++ b/plugins/modules/keycloak_authentication.py @@ -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) From 01dce04e334d6fdf122dcb26af9a3a1470988d06 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 20 Dec 2024 23:06:41 +0100 Subject: [PATCH 060/302] =?UTF-8?q?[PR=20#9228/c5855d1a=20backport][stable?= =?UTF-8?q?-10]=20Clean=20up=20Proxmox=20API=20token=20handling=20by=20str?= =?UTF-8?q?ipping=20whitespace=20and=20forma=E2=80=A6=20(#9288)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clean up Proxmox API token handling by stripping whitespace and forma… (#9228) * Clean up Proxmox API token handling by stripping whitespace and formatting the token string * Update plugins/inventory/proxmox.py Co-authored-by: Felix Fontein * Update plugins/inventory/proxmox.py Co-authored-by: Felix Fontein * Update changelogs/fragments/9228-fix-issue-header.yml Co-authored-by: Felix Fontein * Update changelogs/fragments/9228-fix-issue-header.yml Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit c5855d1a58d91994105d7ea07e23fa8554c7fa38) Co-authored-by: xilmen --- changelogs/fragments/9228-fix-issue-header.yml | 2 ++ plugins/inventory/proxmox.py | 17 +++++++++-------- 2 files changed, 11 insertions(+), 8 deletions(-) create mode 100644 changelogs/fragments/9228-fix-issue-header.yml diff --git a/changelogs/fragments/9228-fix-issue-header.yml b/changelogs/fragments/9228-fix-issue-header.yml new file mode 100644 index 0000000000..450a23f8e5 --- /dev/null +++ b/changelogs/fragments/9228-fix-issue-header.yml @@ -0,0 +1,2 @@ +minor_changes: + - 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/). diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py index 3ce4f789a3..38877b895c 100644 --- a/plugins/inventory/proxmox.py +++ b/plugins/inventory/proxmox.py @@ -275,7 +275,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,24 +282,26 @@ 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) - 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']) } - 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): From 69aea38683bd96eda1e36abdfd9a7332b76441e2 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 20 Dec 2024 23:27:05 +0100 Subject: [PATCH 061/302] [PR #9236/2b2872f0 backport][stable-10] Add android sdk module (#9293) Add android sdk module (#9236) * adds simple implementation of adding and removing android sdk packages * adds package update * adds simple installed packages parsing * moves parsing logic to a separate class * adds absent state for sdkmanager packages and setup for tests * adds output for installing and removing packages * removes version from Package object since it is not possible to specify version for a package while using sdkmanager * adds 'latest' state * adds tests * fixes crash when sdkmanager is invoked from python with LC_ALL=C * fixes latest state * adds sdk_root parameter * adds channel parameter * simplifies regexps, removes unused named groups * minor refactoring of sdkmanager parsing * adds java dependency variable for different distributions * adds RETURN documentation * adds check for nonexisting package * adds check for non-accepted licenses * removes excessive methods from sdkmanager * removes unused 'update' module parameter, packages may be updated using 'latest' state * minor refactoring * adds EXAMPLES doc section * adds DOCUMENTATION section and license headers * fixes formatting issues * removes diff_params * adds maintainer * fixes sanity check issues in sdkmanager * adds java dependency for macos and moves some tests to a separate FreeBSD configuration * fixes dependencies setup for OSX * fixes dependencies setup for OSX (2) * fixes dependencies setup for OSX (3) * Apply minor suggestions from code review Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * applies code review suggestions * changes force_lang from C.UTF-8 to auto in sdkmanager (as per discussion https://github.com/ansible-collections/community.general/pull/9236#discussion_r1881114326) * Revert "changes force_lang from C.UTF-8 to auto in sdkmanager (as per discussion https://github.com/ansible-collections/community.general/pull/9236#discussion_r1881114326)" This reverts commit 619f28dd58db005e466a19b98604221da82b7ecc. * fixes some more comments from review * minor sanity issue fix * uses the 'changed' test instead of checking the 'changed' attribute * adds 'accept_licenses' parameter. Installation is now performed independently for each package specified. * removes "Accept licenses" task from examples * fixes docs sanity issues * applies minor suggestions from code review * fixes regexps. The previous version didn't match versions like "32.1.0 rc1". Also, this allows to simplify the parsing logic as there is no need to skip table headers anymore. * renamed sdkmanager.py to android_sdkmanager.py * applies minor suggestions from code review Co-authored-by: Felix Fontein * updates BOTMETA * reordered BOTMETA --------- Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> Co-authored-by: Felix Fontein (cherry picked from commit 2b2872f0efe7f2fcf2c8c0e2b40764d940c79dff) Co-authored-by: Stanislav Shamilov --- .github/BOTMETA.yml | 4 + plugins/module_utils/android_sdkmanager.py | 148 ++++++++++++ plugins/modules/android_sdk.py | 213 ++++++++++++++++++ tests/integration/targets/android_sdk/aliases | 7 + .../targets/android_sdk/meta/main.yml | 8 + .../android_sdk/tasks/default-tests.yml | 92 ++++++++ .../android_sdk/tasks/freebsd-tests.yml | 72 ++++++ .../targets/android_sdk/tasks/main.yml | 31 +++ .../targets/android_sdk/tasks/setup.yml | 86 +++++++ .../targets/android_sdk/vars/Alpine.yml | 6 + .../targets/android_sdk/vars/Archlinux.yml | 6 + .../targets/android_sdk/vars/Darwin.yml | 6 + .../targets/android_sdk/vars/Debian.yml | 6 + .../targets/android_sdk/vars/FreeBSD.yml | 6 + .../targets/android_sdk/vars/RedHat.yml | 6 + .../targets/android_sdk/vars/Suse.yml | 6 + .../targets/android_sdk/vars/main.yml | 8 + 17 files changed, 711 insertions(+) create mode 100644 plugins/module_utils/android_sdkmanager.py create mode 100644 plugins/modules/android_sdk.py create mode 100644 tests/integration/targets/android_sdk/aliases create mode 100644 tests/integration/targets/android_sdk/meta/main.yml create mode 100644 tests/integration/targets/android_sdk/tasks/default-tests.yml create mode 100644 tests/integration/targets/android_sdk/tasks/freebsd-tests.yml create mode 100644 tests/integration/targets/android_sdk/tasks/main.yml create mode 100644 tests/integration/targets/android_sdk/tasks/setup.yml create mode 100644 tests/integration/targets/android_sdk/vars/Alpine.yml create mode 100644 tests/integration/targets/android_sdk/vars/Archlinux.yml create mode 100644 tests/integration/targets/android_sdk/vars/Darwin.yml create mode 100644 tests/integration/targets/android_sdk/vars/Debian.yml create mode 100644 tests/integration/targets/android_sdk/vars/FreeBSD.yml create mode 100644 tests/integration/targets/android_sdk/vars/RedHat.yml create mode 100644 tests/integration/targets/android_sdk/vars/Suse.yml create mode 100644 tests/integration/targets/android_sdk/vars/main.yml diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 6896106906..2be4619ecb 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -309,6 +309,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: @@ -420,6 +422,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: 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/modules/android_sdk.py b/plugins/modules/android_sdk.py new file mode 100644 index 0000000000..9851a84fc2 --- /dev/null +++ b/plugins/modules/android_sdk.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: 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 B(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 is 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 is 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/tests/integration/targets/android_sdk/aliases b/tests/integration/targets/android_sdk/aliases new file mode 100644 index 0000000000..bb79889366 --- /dev/null +++ b/tests/integration/targets/android_sdk/aliases @@ -0,0 +1,7 @@ +# 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 + +azp/posix/3 +destructive +needs/root \ No newline at end of file diff --git a/tests/integration/targets/android_sdk/meta/main.yml b/tests/integration/targets/android_sdk/meta/main.yml new file mode 100644 index 0000000000..d7c152feeb --- /dev/null +++ b/tests/integration/targets/android_sdk/meta/main.yml @@ -0,0 +1,8 @@ +--- +# 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 + +dependencies: + - setup_pkg_mgr + - setup_remote_tmp_dir \ No newline at end of file diff --git a/tests/integration/targets/android_sdk/tasks/default-tests.yml b/tests/integration/targets/android_sdk/tasks/default-tests.yml new file mode 100644 index 0000000000..b8cb6df54d --- /dev/null +++ b/tests/integration/targets/android_sdk/tasks/default-tests.yml @@ -0,0 +1,92 @@ +--- +#################################################################### +# WARNING: These are designed specifically for Ansible tests # +# and should not be used as examples of how to write Ansible roles # +#################################################################### + +# 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 + +- name: Install build-tools;34.0.0 + android_sdk: + accept_licenses: true + name: build-tools;34.0.0 + state: present + register: build_tools_installed + +- name: Install build-tools;34.0.0 second time + android_sdk: + name: build-tools;34.0.0 + state: present + register: build_tools_installed2 + +- name: Stat build-tools + stat: + path: "{{ android_sdk_location }}/build-tools/34.0.0" + register: build_tools_34_0_0 + +- name: Delete build-tools;34.0.0 + android_sdk: + name: build-tools;34.0.0 + state: absent + register: build_tools_deleted + +- name: Delete build-tools;34.0.0 second time + android_sdk: + name: build-tools;34.0.0 + state: absent + register: build_tools_deleted2 + +- name: Download old platform-tools + unarchive: + src: https://dl.google.com/android/repository/platform-tools_r27.0.0-linux.zip + remote_src: true + dest: "{{ android_sdk_location }}" + +- name: Try installing platform-tools from sdkmanager + android_sdk: + name: platform-tools + accept_licenses: true + state: present + register: platform_tools_present + +- name: Install (update) platform-tools + android_sdk: + name: platform-tools + state: latest + register: platform_tools_updated + +- name: Install a package to a new root + android_sdk: + name: build-tools;34.0.0 + accept_licenses: true + state: present + sdk_root: "{{ remote_tmp_dir }}" + register: new_root_package + +- name: Check package is installed + stat: + path: "{{ remote_tmp_dir }}/build-tools/34.0.0" + register: new_root_package_stat + +- name: Install a package from canary channel + android_sdk: + name: build-tools;33.0.0 + state: present + channel: canary + register: package_canary + +- name: Run tests + assert: + that: + - build_tools_34_0_0.stat.exists + - build_tools_installed is changed + - build_tools_installed2 is not changed + - build_tools_deleted is changed + - build_tools_deleted2 is not changed + - platform_tools_present is not changed + - platform_tools_updated is changed + - new_root_package is changed + - new_root_package_stat.stat.exists + - package_canary is changed \ No newline at end of file diff --git a/tests/integration/targets/android_sdk/tasks/freebsd-tests.yml b/tests/integration/targets/android_sdk/tasks/freebsd-tests.yml new file mode 100644 index 0000000000..f1886f245d --- /dev/null +++ b/tests/integration/targets/android_sdk/tasks/freebsd-tests.yml @@ -0,0 +1,72 @@ +--- +#################################################################### +# WARNING: These are designed specifically for Ansible tests # +# and should not be used as examples of how to write Ansible roles # +#################################################################### + +# 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 + +- name: Install sources;android-26 (FreeBSD) + android_sdk: + name: sources;android-26 + accept_licenses: true + state: present + register: sources_android_26_installed + +- name: Install sources;android-26 (FreeBSD) + android_sdk: + name: sources;android-26 + state: present + register: sources_android_26_installed2 + +- name: Stat build-tools (FreeBSD) + stat: + path: "{{ android_sdk_location }}/sources/android-26" + register: sources_android_26 + +- name: Delete sources;android-26 (FreeBSD) + android_sdk: + name: sources;android-26 + state: absent + register: sources_android_26_deleted + +- name: Delete sources;android-26 second time (FreeBSD) + android_sdk: + name: sources;android-26 + state: absent + register: sources_android_26_deleted2 + +- name: Install a package to a new root (FreeBSD) + android_sdk: + name: sources;android-26 + accept_licenses: true + state: present + sdk_root: "{{ remote_tmp_dir }}" + register: new_root_package + +- name: Check package is installed (FreeBSD) + stat: + path: "{{ remote_tmp_dir }}/sources/android-26" + register: new_root_package_stat + +- name: Install a package from canary channel (FreeBSD) + android_sdk: + name: sources;android-26 + accept_licenses: true + state: present + channel: canary + register: package_canary + +- name: Run tests (FreeBSD) + assert: + that: + - sources_android_26.stat.exists + - sources_android_26_installed is changed + - sources_android_26_installed2 is not changed + - sources_android_26_deleted is changed + - sources_android_26_deleted2 is not changed + - new_root_package is changed + - new_root_package_stat.stat.exists + - package_canary is changed diff --git a/tests/integration/targets/android_sdk/tasks/main.yml b/tests/integration/targets/android_sdk/tasks/main.yml new file mode 100644 index 0000000000..46cf3192e1 --- /dev/null +++ b/tests/integration/targets/android_sdk/tasks/main.yml @@ -0,0 +1,31 @@ +--- +#################################################################### +# WARNING: These are designed specifically for Ansible tests # +# and should not be used as examples of how to write Ansible roles # +#################################################################### + +# 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 + +# java >= 17 is not available in RHEL and CentOS7 repos, which is required for sdkmanager to run +- name: Bail out if not supported + when: + - "ansible_os_family == 'RedHat' and ansible_distribution_version is version('8.0', '<')" + ansible.builtin.meta: end_play + +- name: Run android_sdk tests + environment: + PATH: '{{ ansible_env.PATH }}:{{ android_sdk_location }}/cmdline-tools/latest/bin' + block: + - import_tasks: setup.yml + + - name: Run default tests + import_tasks: default-tests.yml + when: ansible_os_family != 'FreeBSD' + + # Most of the important Android SDK packages are not available on FreeBSD (like, build-tools, platform-tools and so on), + # but at least some of the functionality can be tested (like, downloading sources) + - name: Run FreeBSD tests + import_tasks: freebsd-tests.yml + when: ansible_os_family == 'FreeBSD' diff --git a/tests/integration/targets/android_sdk/tasks/setup.yml b/tests/integration/targets/android_sdk/tasks/setup.yml new file mode 100644 index 0000000000..ff2e3eb3cf --- /dev/null +++ b/tests/integration/targets/android_sdk/tasks/setup.yml @@ -0,0 +1,86 @@ +--- +#################################################################### +# WARNING: These are designed specifically for Ansible tests # +# and should not be used as examples of how to write Ansible roles # +#################################################################### + +# 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 + +- name: Include OS-specific variables + include_vars: '{{ ansible_os_family }}.yml' + +- name: Install dependencies + become: true + package: + name: + - "{{ openjdk_pkg }}" + - unzip + state: present + when: ansible_os_family != 'Darwin' + +- name: Install dependencies (OSX) + block: + - name: Find brew binary + command: which brew + register: brew_which + - name: Get owner of brew binary + stat: + path: "{{ brew_which.stdout }}" + register: brew_stat + - name: "Install package" + homebrew: + name: + - "{{ openjdk_pkg }}" + - unzip + state: present + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + environment: + HOMEBREW_NO_AUTO_UPDATE: "True" + - name: Symlink java + become: true + file: + src: "/usr/local/opt/openjdk@17/libexec/openjdk.jdk" + dest: "/Library/Java/JavaVirtualMachines/openjdk-17.jdk" + state: link + when: + - ansible_os_family == 'Darwin' + +- name: Create Android SDK directory + file: + path: "{{ android_sdk_location }}" + state: directory + +- name: Check that sdkmanager is installed + stat: + path: "{{ android_sdk_location }}/cmdline-tools/latest/bin/sdkmanager" + register: sdkmanager_installed + +- name: Install Android command line tools + when: not sdkmanager_installed.stat.exists + block: + - name: Create Android SDK dir structure + file: + path: "{{ item.path }}" + state: "{{ item.state }}" + with_items: + - { path: "{{ android_cmdline_temp_dir }}", state: "directory" } + - { path: "{{ android_sdk_location }}/cmdline-tools/latest", state: "directory" } + + - name: Download Android command line tools + unarchive: + src: "{{ commandline_tools_link }}" + dest: "{{ android_cmdline_temp_dir }}" + remote_src: yes + creates: "{{ android_cmdline_temp_dir }}/cmdline-tools" + when: not sdkmanager_installed.stat.exists + + + - name: Fix directory structure + copy: + src: "{{ android_cmdline_temp_dir }}/cmdline-tools/" + dest: "{{ android_sdk_location }}/cmdline-tools/latest" + remote_src: yes diff --git a/tests/integration/targets/android_sdk/vars/Alpine.yml b/tests/integration/targets/android_sdk/vars/Alpine.yml new file mode 100644 index 0000000000..593925f043 --- /dev/null +++ b/tests/integration/targets/android_sdk/vars/Alpine.yml @@ -0,0 +1,6 @@ +--- +# 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 + +openjdk_pkg: openjdk17-jre-headless diff --git a/tests/integration/targets/android_sdk/vars/Archlinux.yml b/tests/integration/targets/android_sdk/vars/Archlinux.yml new file mode 100644 index 0000000000..ff46870671 --- /dev/null +++ b/tests/integration/targets/android_sdk/vars/Archlinux.yml @@ -0,0 +1,6 @@ +--- +# 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 + +openjdk_pkg: jre17-openjdk-headless diff --git a/tests/integration/targets/android_sdk/vars/Darwin.yml b/tests/integration/targets/android_sdk/vars/Darwin.yml new file mode 100644 index 0000000000..696bf39a75 --- /dev/null +++ b/tests/integration/targets/android_sdk/vars/Darwin.yml @@ -0,0 +1,6 @@ +--- +# 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 + +openjdk_pkg: openjdk@17 diff --git a/tests/integration/targets/android_sdk/vars/Debian.yml b/tests/integration/targets/android_sdk/vars/Debian.yml new file mode 100644 index 0000000000..ddcfaaf1e3 --- /dev/null +++ b/tests/integration/targets/android_sdk/vars/Debian.yml @@ -0,0 +1,6 @@ +--- +# 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 + +openjdk_pkg: openjdk-17-jre-headless diff --git a/tests/integration/targets/android_sdk/vars/FreeBSD.yml b/tests/integration/targets/android_sdk/vars/FreeBSD.yml new file mode 100644 index 0000000000..61c1858423 --- /dev/null +++ b/tests/integration/targets/android_sdk/vars/FreeBSD.yml @@ -0,0 +1,6 @@ +--- +# 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 + +openjdk_pkg: openjdk17-jre diff --git a/tests/integration/targets/android_sdk/vars/RedHat.yml b/tests/integration/targets/android_sdk/vars/RedHat.yml new file mode 100644 index 0000000000..40f44bd773 --- /dev/null +++ b/tests/integration/targets/android_sdk/vars/RedHat.yml @@ -0,0 +1,6 @@ +--- +# 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 + +openjdk_pkg: java-17-openjdk-headless diff --git a/tests/integration/targets/android_sdk/vars/Suse.yml b/tests/integration/targets/android_sdk/vars/Suse.yml new file mode 100644 index 0000000000..40f44bd773 --- /dev/null +++ b/tests/integration/targets/android_sdk/vars/Suse.yml @@ -0,0 +1,6 @@ +--- +# 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 + +openjdk_pkg: java-17-openjdk-headless diff --git a/tests/integration/targets/android_sdk/vars/main.yml b/tests/integration/targets/android_sdk/vars/main.yml new file mode 100644 index 0000000000..9ba619a6d5 --- /dev/null +++ b/tests/integration/targets/android_sdk/vars/main.yml @@ -0,0 +1,8 @@ +--- +# 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 + +android_cmdline_temp_dir: "/tmp/cmdlinetools" +android_sdk_location: "/tmp/androidsdk" +commandline_tools_link: https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip From df5818282b703a692ca77cba4ec9b593ca65ad2f Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 20 Dec 2024 23:27:15 +0100 Subject: [PATCH 062/302] [PR #9255/9452a2c8 backport][stable-10] homebrew: fix incorrect handling of aliases (#9289) homebrew: fix incorrect handling of aliases (#9255) * Add failing test (See commit description) Second assert returns this: changed: [localhost] => changed=true changed_pkgs: - sqlite3 msg: 'Changed: 1, Unchanged: 1' unchanged_pkgs: - sqlite * Extract proper package_name from brew info using alisases * Add changelog fragment * Fix pep8 * Make sure sqlite is uninstalled beforehand * Use `package_result is (not) changed` syntax in assertions * Register more explicit names * Fix handling of casks (cherry picked from commit 9452a2c8ac06cd12446d5fe500d6c24506f62075) Co-authored-by: Thibaut Decombe <68703331+UnknownPlatypus@users.noreply.github.com> --- ...-handling-of-aliased-homebrew-packages.yml | 2 + plugins/modules/homebrew.py | 27 +++++-- .../targets/homebrew/tasks/casks.yml | 8 +- .../targets/homebrew/tasks/formulae.yml | 74 +++++++++++++++---- 4 files changed, 83 insertions(+), 28 deletions(-) create mode 100644 changelogs/fragments/9255-fix-handling-of-aliased-homebrew-packages.yml diff --git a/changelogs/fragments/9255-fix-handling-of-aliased-homebrew-packages.yml b/changelogs/fragments/9255-fix-handling-of-aliased-homebrew-packages.yml new file mode 100644 index 0000000000..350e81af8e --- /dev/null +++ b/changelogs/fragments/9255-fix-handling-of-aliased-homebrew-packages.yml @@ -0,0 +1,2 @@ +bugfixes: + - 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). \ No newline at end of file diff --git a/plugins/modules/homebrew.py b/plugins/modules/homebrew.py index 8eb1b9d689..980b5cf656 100644 --- a/plugins/modules/homebrew.py +++ b/plugins/modules/homebrew.py @@ -379,6 +379,20 @@ class Homebrew(object): ) 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): + canonical_name = package_detail["token"] if is_cask else package_detail["name"] # For ex: 'sqlite' + all_valid_names = set(package_detail.get("aliases", [])) # For ex: {'sqlite3'} + all_valid_names.add(canonical_name) + + # Then make sure the user provided name resurface. + return (all_valid_names & set(self.packages)).pop() + def _get_packages_info(self): cmd = [ "{brew_path}".format(brew_path=self.brew_path), @@ -397,16 +411,13 @@ class Homebrew(object): data = json.loads(out) for package_detail in data.get("formulae", []): - if bool(package_detail.get("installed")): - self.installed_packages.add(package_detail["name"]) - if bool(package_detail.get("outdated")): - self.outdated_packages.add(package_detail["name"]) + 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", []): - if bool(package_detail.get("installed")): - self.installed_packages.add(package_detail["token"]) - if bool(package_detail.get("outdated")): - self.outdated_packages.add(package_detail["token"]) + package_name = self._extract_package_name(package_detail, is_cask=True) + self._save_package_info(package_detail, package_name) + # /prep -------------------------------------------------------- }}} def run(self): diff --git a/tests/integration/targets/homebrew/tasks/casks.yml b/tests/integration/targets/homebrew/tasks/casks.yml index ffbe67d158..50824a9e9f 100644 --- a/tests/integration/targets/homebrew/tasks/casks.yml +++ b/tests/integration/targets/homebrew/tasks/casks.yml @@ -55,7 +55,7 @@ - assert: that: - - package_result.changed + - package_result is changed - name: Again install {{ package_name }} package using homebrew homebrew: @@ -68,7 +68,7 @@ - assert: that: - - not package_result.changed + - package_result is not changed - name: Uninstall {{ package_name }} package using homebrew homebrew: @@ -81,7 +81,7 @@ - assert: that: - - package_result.changed + - package_result is changed - name: Again uninstall {{ package_name }} package using homebrew homebrew: @@ -94,4 +94,4 @@ - assert: that: - - not package_result.changed + - package_result is not changed diff --git a/tests/integration/targets/homebrew/tasks/formulae.yml b/tests/integration/targets/homebrew/tasks/formulae.yml index 21276e3a2e..1559ba5dd8 100644 --- a/tests/integration/targets/homebrew/tasks/formulae.yml +++ b/tests/integration/targets/homebrew/tasks/formulae.yml @@ -55,7 +55,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Package installed: gnu-tar'" - "package_result.changed_pkgs == ['gnu-tar']" - "package_result.unchanged_pkgs == []" @@ -71,7 +71,7 @@ - assert: that: - - not package_result.changed + - package_result is not changed - "package_result.msg == 'Package already installed: gnu-tar'" - "package_result.changed_pkgs == []" - "package_result.unchanged_pkgs == ['gnu-tar']" @@ -87,7 +87,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Package unlinked: gnu-tar'" - "package_result.changed_pkgs == ['gnu-tar']" - "package_result.unchanged_pkgs == []" @@ -103,7 +103,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Package linked: gnu-tar'" - "package_result.changed_pkgs == ['gnu-tar']" - "package_result.unchanged_pkgs == []" @@ -119,7 +119,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Package uninstalled: gnu-tar'" - "package_result.changed_pkgs == ['gnu-tar']" - "package_result.unchanged_pkgs == []" @@ -135,7 +135,7 @@ - assert: that: - - not package_result.changed + - package_result is not changed - "package_result.msg == 'Package already uninstalled: gnu-tar'" - "package_result.changed_pkgs == []" - "package_result.unchanged_pkgs == ['gnu-tar']" @@ -151,7 +151,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Package upgraded: gnu-tar'" - "package_result.changed_pkgs == ['gnu-tar']" - "package_result.unchanged_pkgs == []" @@ -167,7 +167,7 @@ - assert: that: - - not package_result.changed + - package_result is not changed - "package_result.msg == 'Package already upgraded: gnu-tar'" - "package_result.changed_pkgs == []" - "package_result.unchanged_pkgs == ['gnu-tar']" @@ -205,7 +205,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Changed: 1, Unchanged: 1'" - "package_result.changed_pkgs == ['gnu-time']" - "package_result.unchanged_pkgs == ['gnu-tar']" @@ -221,7 +221,7 @@ - assert: that: - - not package_result.changed + - package_result is not changed - "package_result.msg == 'Changed: 0, Unchanged: 2'" - "package_result.changed_pkgs == []" - "package_result.unchanged_pkgs | sort == ['gnu-tar', 'gnu-time']" @@ -237,7 +237,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Changed: 2, Unchanged: 0'" - "package_result.changed_pkgs | sort == ['gnu-tar', 'gnu-time']" - "package_result.unchanged_pkgs == []" @@ -253,7 +253,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Changed: 2, Unchanged: 0'" - "package_result.changed_pkgs | sort == ['gnu-tar', 'gnu-time']" - "package_result.unchanged_pkgs == []" @@ -269,7 +269,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Changed: 2, Unchanged: 0'" - "package_result.changed_pkgs | sort == ['gnu-tar', 'gnu-time']" - "package_result.unchanged_pkgs == []" @@ -285,7 +285,7 @@ - assert: that: - - not package_result.changed + - package_result is not changed - "package_result.msg == 'Changed: 0, Unchanged: 2'" - "package_result.changed_pkgs == []" - "package_result.unchanged_pkgs | sort == ['gnu-tar', 'gnu-time']" @@ -301,7 +301,7 @@ - assert: that: - - package_result.changed + - package_result is changed - "package_result.msg == 'Changed: 2, Unchanged: 0'" - "package_result.changed_pkgs | sort == ['gnu-tar', 'gnu-time']" - "package_result.unchanged_pkgs == []" @@ -317,7 +317,49 @@ - assert: that: - - not package_result.changed + - package_result is not changed - "package_result.msg == 'Changed: 0, Unchanged: 2'" - "package_result.changed_pkgs == []" - "package_result.unchanged_pkgs | sort == ['gnu-tar', 'gnu-time']" + +# Test alias handling with sqlite (that is aliased to sqlite3) +- block: + - name: Make sure sqlite package is not installed + homebrew: + name: "sqlite" + state: absent + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + + - name: Install sqlite package using alias (sqlite3) + homebrew: + name: "sqlite3" + state: present + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: install_result + + - assert: + that: + - install_result is changed + - "install_result.msg == 'Package installed: sqlite3'" + - "install_result.changed_pkgs == ['sqlite3']" + - "install_result.unchanged_pkgs == []" + + - name: Again install sqlite package using alias (sqlite3) + homebrew: + name: "sqlite3" + state: present + update_homebrew: false + become: true + become_user: "{{ brew_stat.stat.pw_name }}" + register: reinstall_result + + - assert: + that: + - reinstall_result is not changed + - "reinstall_result.msg == 'Package already installed: sqlite3'" + - "reinstall_result.changed_pkgs == []" + - "reinstall_result.unchanged_pkgs == ['sqlite3']" From 5c2e9e0c5bb11ec02fc94e84328446abf1e2be34 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 21 Dec 2024 17:02:30 +0100 Subject: [PATCH 063/302] [PR #9297/d2088ccf backport][stable-10] Polish botmeta extra sanity test and make it work without warnings on Python 3.13 (#9300) Polish botmeta extra sanity test and make it work without warnings on Python 3.13 (#9297) Polish botmeta and make it work without warnings on Python 3.13. (cherry picked from commit d2088ccfcc22e3893b1a3507dda4918573ddd9ef) Co-authored-by: Felix Fontein --- tests/sanity/extra/botmeta.py | 76 +++++++++++++++++------------------ 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/tests/sanity/extra/botmeta.py b/tests/sanity/extra/botmeta.py index 07ca189e81..9f7e977ea2 100755 --- a/tests/sanity/extra/botmeta.py +++ b/tests/sanity/extra/botmeta.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 """Check BOTMETA file.""" -from __future__ import (absolute_import, division, print_function) -__metaclass__ = type -import ast +from __future__ import annotations + import os import re import sys @@ -65,26 +64,27 @@ AUTHOR_REGEX = re.compile(r'^\w.*\(@([\w-]+)\)(?![\w.])') def read_authors(filename): data = {} try: - with open(filename, 'rb') as b_module_data: - M = ast.parse(b_module_data.read()) + documentation = [] + in_docs = False + with open(filename, 'r', encoding='utf-8') as f: + for line in f: + if line.startswith('DOCUMENTATION ='): + in_docs = True + elif line.startswith(("'''", '"""')) and in_docs: + in_docs = False + elif in_docs: + documentation.append(line) + if in_docs: + print(f'{filename}: cannot find DOCUMENTATION end') + return [] + if not documentation: + print(f'{filename}: cannot find DOCUMENTATION') + return [] - for child in M.body: - if isinstance(child, ast.Assign): - for t in child.targets: - try: - theid = t.id - except AttributeError: - # skip errors can happen when trying to use the normal code - continue - - if theid == 'DOCUMENTATION': - if isinstance(child.value, ast.Dict): - data = ast.literal_eval(child.value) - else: - data = yaml.safe_load(child.value.s) + data = yaml.safe_load('\n'.join(documentation)) except Exception as e: - print('%s:%d:%d: Cannot load DOCUMENTATION: %s' % (filename, 0, 0, e)) + print(f'{filename}:0:0: Cannot load DOCUMENTATION: {e}') return [] author = data.get('author') or [] @@ -107,21 +107,21 @@ def validate(filename, filedata): return if filename.startswith(('plugins/doc_fragments/', 'plugins/module_utils/')): return - # Compile lis tof all active and inactive maintainers + # Compile list of all active and inactive maintainers all_maintainers = filedata['maintainers'] + filedata['ignore'] - if not filename.startswith('plugins/filter/'): + if not filename.startswith(('plugins/action/', 'plugins/doc_fragments/', 'plugins/filter/', 'plugins/module_utils/', 'plugins/plugin_utils/')): maintainers = read_authors(filename) for maintainer in maintainers: maintainer = extract_author_name(maintainer) if maintainer is not None and maintainer not in all_maintainers: - msg = 'Author %s not mentioned as active or inactive maintainer for %s (mentioned are: %s)' % ( - maintainer, filename, ', '.join(all_maintainers)) - print('%s:%d:%d: %s' % (FILENAME, 0, 0, msg)) + others = ', '.join(all_maintainers) + msg = f'Author {maintainer} not mentioned as active or inactive maintainer for {filename} (mentioned are: {others})' + print(f'{FILENAME}:0:0: {msg}') should_have_no_maintainer = filename in IGNORE_NO_MAINTAINERS if not all_maintainers and not should_have_no_maintainer: - print('%s:%d:%d: %s' % (FILENAME, 0, 0, 'No (active or inactive) maintainer mentioned for %s' % filename)) + print(f'{FILENAME}:0:0: No (active or inactive) maintainer mentioned for {filename}') if all_maintainers and should_have_no_maintainer: - print('%s:%d:%d: %s' % (FILENAME, 0, 0, 'Please remove %s from the ignore list of %s' % (filename, sys.argv[0]))) + print(f'{FILENAME}:0:0: Please remove {filename} from the ignore list of {sys.argv[0]}') def main(): @@ -130,12 +130,12 @@ def main(): with open(FILENAME, 'rb') as f: botmeta = yaml.safe_load(f) except yaml.error.MarkedYAMLError as ex: - print('%s:%d:%d: YAML load failed: %s' % (FILENAME, ex.context_mark.line + - 1, ex.context_mark.column + 1, re.sub(r'\s+', ' ', str(ex)))) + msg = re.sub(r'\s+', ' ', str(ex)) + print('f{FILENAME}:{ex.context_mark.line + 1}:{ex.context_mark.column + 1}: YAML load failed: {msg}') return except Exception as ex: # pylint: disable=broad-except - print('%s:%d:%d: YAML load failed: %s' % - (FILENAME, 0, 0, re.sub(r'\s+', ' ', str(ex)))) + msg = re.sub(r'\s+', ' ', str(ex)) + print(f'{FILENAME}:0:0: YAML load failed: {msg}') return # Validate schema @@ -168,7 +168,7 @@ def main(): except MultipleInvalid as ex: for error in ex.errors: # No way to get line/column numbers - print('%s:%d:%d: %s' % (FILENAME, 0, 0, humanize_error(botmeta, error))) + print(f'{FILENAME}:0:0: {humanize_error(botmeta, error)}') return # Preprocess (substitute macros, convert to lists) @@ -180,7 +180,7 @@ def main(): macro = m.group(1) replacement = (macros[macro] or '') if macro == 'team_ansible_core': - return '$team_ansible_core %s' % replacement + return f'$team_ansible_core {replacement}' return replacement return macro_re.sub(f, text) @@ -195,13 +195,13 @@ def main(): if k in LIST_ENTRIES: filedata[k] = v.split() except KeyError as e: - print('%s:%d:%d: %s' % (FILENAME, 0, 0, 'Found unknown macro %s' % e)) + print(f'{FILENAME}:0:0: Found unknown macro {e}') return # Scan all files unmatched = set(files) for dirs in ('docs/docsite/rst', 'plugins', 'tests', 'changelogs'): - for dirpath, dirnames, filenames in os.walk(dirs): + for dirpath, _dirnames, filenames in os.walk(dirs): for file in sorted(filenames): if file.endswith('.pyc'): continue @@ -216,10 +216,10 @@ def main(): if file in unmatched: unmatched.remove(file) if not matching_files: - print('%s:%d:%d: %s' % (FILENAME, 0, 0, 'Did not find any entry for %s' % filename)) + print(f'{FILENAME}:0:0: Did not find any entry for {filename}') matching_files.sort(key=lambda kv: kv[0]) - filedata = dict() + filedata = {} for k in LIST_ENTRIES: filedata[k] = [] for dummy, data in matching_files: @@ -230,7 +230,7 @@ def main(): validate(filename, filedata) for file in unmatched: - print('%s:%d:%d: %s' % (FILENAME, 0, 0, 'Entry %s was not used' % file)) + print(f'{FILENAME}:0:0: Entry {file} was not used') if __name__ == '__main__': From a56cec85824f16429c6fcbb61435abb17827f6fd Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 21 Dec 2024 19:26:33 +0100 Subject: [PATCH 064/302] [PR #9280/afa5716e backport][stable-10] yum_versionlock: adjust docs (#9303) yum_versionlock: adjust docs (#9280) * yum_versionlock: adjust docs * fix examples indentation (cherry picked from commit afa5716e0baf9ce428216cb50b30f8c125c153ab) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/yum_versionlock.py | 59 +++++++++++++++--------------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/plugins/modules/yum_versionlock.py b/plugins/modules/yum_versionlock.py index 0cbf9be393..4a618a9d17 100644 --- a/plugins/modules/yum_versionlock.py +++ b/plugins/modules/yum_versionlock.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: yum_versionlock version_added: 2.0.0 short_description: Locks / unlocks a installed package(s) from being updated by yum package manager @@ -32,62 +31,62 @@ options: elements: str state: description: - - If state is V(present), package(s) will be added to yum versionlock list. - - If state is V(absent), package(s) will be removed from yum versionlock list. - choices: [ 'absent', 'present' ] + - If state is V(present), package(s) will be added to yum versionlock list. + - If state is V(absent), package(s) will be removed from yum versionlock list. + choices: ['absent', 'present'] type: str default: present notes: - - Requires yum-plugin-versionlock package on the remote node. + - Requires yum-plugin-versionlock package on the remote node. requirements: -- yum -- yum-versionlock + - yum + - yum-versionlock author: - - Florian Paul Azim Hoberg (@gyptazy) - - Amin Vakil (@aminvakil) -''' + - Florian Paul Azim Hoberg (@gyptazy) + - Amin Vakil (@aminvakil) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Prevent Apache / httpd from being updated community.general.yum_versionlock: state: present name: - - httpd + - httpd - name: Prevent Apache / httpd version 2.4.57-2 from being updated community.general.yum_versionlock: state: present name: - - httpd-0:2.4.57-2.el9 + - httpd-0:2.4.57-2.el9 - name: Prevent multiple packages from being updated community.general.yum_versionlock: state: present name: - - httpd - - nginx - - haproxy - - curl + - httpd + - nginx + - haproxy + - curl - name: Remove lock from Apache / httpd to be updated again community.general.yum_versionlock: state: absent name: httpd -''' +""" -RETURN = r''' +RETURN = r""" packages: - description: A list of package(s) in versionlock list. - returned: success - type: list - elements: str - sample: [ 'httpd' ] + description: A list of package(s) in versionlock list. + returned: success + type: list + elements: str + sample: ['httpd'] state: - description: State of package(s). - returned: success - type: str - sample: present -''' + description: State of package(s). + returned: success + type: str + sample: present +""" import re from ansible.module_utils.basic import AnsibleModule From 07124473cca075d2d4681558b43d59b028064430 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sat, 21 Dec 2024 19:26:42 +0100 Subject: [PATCH 065/302] [PR #9295/1ee244f0 backport][stable-10] fix examples indentation (#9301) fix examples indentation (#9295) (cherry picked from commit 1ee244f02dbf85f5348a9b03007f78446d28c76a) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/yarn.py | 58 ++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/plugins/modules/yarn.py b/plugins/modules/yarn.py index a2a3c471b7..7109145ce8 100644 --- a/plugins/modules/yarn.py +++ b/plugins/modules/yarn.py @@ -88,41 +88,41 @@ requirements: """ EXAMPLES = r""" - - name: Install "imagemin" Node.js package. - community.general.yarn: - name: imagemin - path: /app/location +- name: Install "imagemin" Node.js package. + community.general.yarn: + name: imagemin + path: /app/location - - name: Install "imagemin" Node.js package on version 5.3.1 - community.general.yarn: - name: imagemin - version: '5.3.1' - path: /app/location +- name: Install "imagemin" Node.js package on version 5.3.1 + community.general.yarn: + name: imagemin + version: '5.3.1' + path: /app/location - - name: Install "imagemin" Node.js package globally. - community.general.yarn: - name: imagemin - global: true +- name: Install "imagemin" Node.js package globally. + community.general.yarn: + name: imagemin + global: true - - name: Remove the globally-installed package "imagemin". - community.general.yarn: - name: imagemin - global: true - state: absent +- name: Remove the globally-installed package "imagemin". + community.general.yarn: + name: imagemin + global: true + state: absent - - name: Install "imagemin" Node.js package from custom registry. - community.general.yarn: - name: imagemin - registry: 'http://registry.mysite.com' +- name: Install "imagemin" Node.js package from custom registry. + community.general.yarn: + name: imagemin + registry: 'http://registry.mysite.com' - - name: Install packages based on package.json. - community.general.yarn: - path: /app/location +- name: Install packages based on package.json. + community.general.yarn: + path: /app/location - - name: Update all packages in package.json to their latest version. - community.general.yarn: - path: /app/location - state: latest +- name: Update all packages in package.json to their latest version. + community.general.yarn: + path: /app/location + state: latest """ RETURN = r""" From f2196d452f38c7773501280f2c185c7957d26cd7 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sun, 22 Dec 2024 12:32:24 +0100 Subject: [PATCH 066/302] [PR #9281/1b6c0517 backport][stable-10] zfs modules: adjust docs (#9305) zfs modules: adjust docs (#9281) * zfs modules: adjust docs * Apply suggestions from code review * fix examples indentation * Update plugins/modules/zfs.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 1b6c05176b0ce705eaf7d0c5d72a69ffd889a716) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/zfs.py | 30 ++-- plugins/modules/zfs_delegate_admin.py | 29 ++-- plugins/modules/zfs_facts.py | 230 +++++++++++++------------- 3 files changed, 140 insertions(+), 149 deletions(-) diff --git a/plugins/modules/zfs.py b/plugins/modules/zfs.py index f23cc4580d..1b00010d8a 100644 --- a/plugins/modules/zfs.py +++ b/plugins/modules/zfs.py @@ -9,23 +9,20 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: zfs -short_description: Manage zfs +short_description: Manage ZFS description: - - Manages ZFS file systems, volumes, clones and snapshots + - Manages ZFS file systems, volumes, clones and snapshots. extends_documentation_fragment: - community.general.attributes attributes: check_mode: support: partial details: - - In certain situations it may report a task as changed that will not be reported - as changed when C(check_mode) is disabled. - - For example, this might occur when the zpool C(altroot) option is set or when - a size is written using human-readable notation, such as V(1M) or V(1024K), - instead of as an unqualified byte count, such as V(1048576). + - In certain situations it may report a task as changed that will not be reported as changed when C(check_mode) is disabled. + - For example, this might occur when the zpool C(altroot) option is set or when a size is written using human-readable notation, such as + V(1M) or V(1024K), instead of as an unqualified byte count, such as V(1048576). diff_mode: support: full options: @@ -36,10 +33,9 @@ options: type: str state: description: - - Whether to create (V(present)), or remove (V(absent)) a - file system, snapshot or volume. All parents/children - will be created/destroyed as needed to reach the desired state. - choices: [ absent, present ] + - Whether to create (V(present)), or remove (V(absent)) a file system, snapshot or volume. All parents/children will be created/destroyed + as needed to reach the desired state. + choices: [absent, present] required: true type: str origin: @@ -53,10 +49,10 @@ options: type: dict default: {} author: -- Johan Wiren (@johanwiren) -''' + - Johan Wiren (@johanwiren) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a new file system called myfs in pool rpool with the setuid property turned off community.general.zfs: name: rpool/myfs @@ -93,7 +89,7 @@ EXAMPLES = ''' community.general.zfs: name: rpool/myfs state: absent -''' +""" import os diff --git a/plugins/modules/zfs_delegate_admin.py b/plugins/modules/zfs_delegate_admin.py index 24f7422206..796cbd4595 100644 --- a/plugins/modules/zfs_delegate_admin.py +++ b/plugins/modules/zfs_delegate_admin.py @@ -8,18 +8,17 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: zfs_delegate_admin short_description: Manage ZFS delegated administration (user admin privileges) description: - - Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS - operations normally restricted to the superuser. + - Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS operations normally restricted + to the superuser. - See the C(zfs allow) section of V(zfs(1M\)) for detailed explanations of options. - This module attempts to adhere to the behavior of the command line tool as much as possible. requirements: - - "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all - versions), FreeBSD >= 8.0R, ZFS on Linux >= 0.7.0." + - "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all versions), FreeBSD >= 8.0R, + ZFS on Linux >= 0.7.0." extends_documentation_fragment: - community.general.attributes attributes: @@ -38,7 +37,7 @@ options: - Whether to allow (V(present)), or unallow (V(absent)) a permission. - When set to V(present), at least one "entity" param of O(users), O(groups), or O(everyone) are required. - When set to V(absent), removes permissions from the specified entities, or removes all permissions if no entity params are specified. - choices: [ absent, present ] + choices: [absent, present] default: present type: str users: @@ -59,8 +58,8 @@ options: permissions: description: - The list of permission(s) to delegate (required if O(state=present)). - - Supported permissions depend on the ZFS version in use. See for example - U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html) for OpenZFS. + - Supported permissions depend on the ZFS version in use. See for example U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html) + for OpenZFS. type: list elements: str local: @@ -77,10 +76,10 @@ options: type: bool default: false author: -- Nate Coraor (@natefoo) -''' + - Nate Coraor (@natefoo) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Grant `zfs allow` and `unallow` permission to the `adm` user with the default local+descendents scope community.general.zfs_delegate_admin: name: rpool/myfs @@ -106,12 +105,12 @@ EXAMPLES = r''' name: rpool/myfs everyone: true state: absent -''' +""" # This module does not return anything other than the standard # changed/state/msg/stdout -RETURN = ''' -''' +RETURN = r""" +""" from itertools import product diff --git a/plugins/modules/zfs_facts.py b/plugins/modules/zfs_facts.py index bb4530c473..25fd10099b 100644 --- a/plugins/modules/zfs_facts.py +++ b/plugins/modules/zfs_facts.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: zfs_facts short_description: Gather facts about ZFS datasets description: @@ -21,45 +20,42 @@ extends_documentation_fragment: - community.general.attributes.facts - community.general.attributes.facts_module options: - name: - description: - - ZFS dataset name. - required: true - aliases: [ "ds", "dataset" ] - type: str - recurse: - description: - - Specifies if properties for any children should be recursively - displayed. - type: bool - default: false - parsable: - description: - - Specifies if property values should be displayed in machine - friendly format. - type: bool - default: false - properties: - description: - - Specifies which dataset properties should be queried in comma-separated format. - For more information about dataset properties, check zfs(1M) man page. - default: all - type: str - type: - description: - - Specifies which datasets types to display. Multiple values have to be - provided in comma-separated form. - choices: [ 'all', 'filesystem', 'volume', 'snapshot', 'bookmark' ] - default: all - type: str - depth: - description: - - Specifies recursion depth. - type: int - default: 0 -''' + name: + description: + - ZFS dataset name. + required: true + aliases: ["ds", "dataset"] + type: str + recurse: + description: + - Specifies if properties for any children should be recursively displayed. + type: bool + default: false + parsable: + description: + - Specifies if property values should be displayed in machine friendly format. + type: bool + default: false + properties: + description: + - Specifies which dataset properties should be queried in comma-separated format. For more information about dataset properties, check zfs(1M) + man page. + default: all + type: str + type: + description: + - Specifies which datasets types to display. Multiple values have to be provided in comma-separated form. + choices: ['all', 'filesystem', 'volume', 'snapshot', 'bookmark'] + default: all + type: str + depth: + description: + - Specifies recursion depth. + type: int + default: 0 +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Gather facts about ZFS dataset rpool/export/home community.general.zfs_facts: dataset: rpool/export/home @@ -73,88 +69,88 @@ EXAMPLES = ''' - ansible.builtin.debug: msg: 'ZFS dataset {{ item.name }} consumes {{ item.used }} of disk space.' with_items: '{{ ansible_zfs_datasets }}' -''' +""" -RETURN = ''' +RETURN = r""" name: - description: ZFS dataset name - returned: always - type: str - sample: rpool/var/spool + description: ZFS dataset name + returned: always + type: str + sample: rpool/var/spool parsable: - description: if parsable output should be provided in machine friendly format. - returned: if 'parsable' is set to True - type: bool - sample: true + description: if parsable output should be provided in machine friendly format. + returned: if O(parsable=True) + type: bool + sample: true recurse: - description: if we should recurse over ZFS dataset - returned: if 'recurse' is set to True - type: bool - sample: true + description: if we should recurse over ZFS dataset + returned: if O(recurse=True) + type: bool + sample: true zfs_datasets: - description: ZFS dataset facts - returned: always - type: str - sample: - { - "aclinherit": "restricted", - "aclmode": "discard", - "atime": "on", - "available": "43.8G", - "canmount": "on", - "casesensitivity": "sensitive", - "checksum": "on", - "compression": "off", - "compressratio": "1.00x", - "copies": "1", - "creation": "Thu Jun 16 11:37 2016", - "dedup": "off", - "devices": "on", - "exec": "on", - "filesystem_count": "none", - "filesystem_limit": "none", - "logbias": "latency", - "logicalreferenced": "18.5K", - "logicalused": "3.45G", - "mlslabel": "none", - "mounted": "yes", - "mountpoint": "/rpool", - "name": "rpool", - "nbmand": "off", - "normalization": "none", - "org.openindiana.caiman:install": "ready", - "primarycache": "all", - "quota": "none", - "readonly": "off", - "recordsize": "128K", - "redundant_metadata": "all", - "refcompressratio": "1.00x", - "referenced": "29.5K", - "refquota": "none", - "refreservation": "none", - "reservation": "none", - "secondarycache": "all", - "setuid": "on", - "sharenfs": "off", - "sharesmb": "off", - "snapdir": "hidden", - "snapshot_count": "none", - "snapshot_limit": "none", - "sync": "standard", - "type": "filesystem", - "used": "4.41G", - "usedbychildren": "4.41G", - "usedbydataset": "29.5K", - "usedbyrefreservation": "0", - "usedbysnapshots": "0", - "utf8only": "off", - "version": "5", - "vscan": "off", - "written": "29.5K", - "xattr": "on", - "zoned": "off" - } -''' + description: ZFS dataset facts + returned: always + type: str + sample: + { + "aclinherit": "restricted", + "aclmode": "discard", + "atime": "on", + "available": "43.8G", + "canmount": "on", + "casesensitivity": "sensitive", + "checksum": "on", + "compression": "off", + "compressratio": "1.00x", + "copies": "1", + "creation": "Thu Jun 16 11:37 2016", + "dedup": "off", + "devices": "on", + "exec": "on", + "filesystem_count": "none", + "filesystem_limit": "none", + "logbias": "latency", + "logicalreferenced": "18.5K", + "logicalused": "3.45G", + "mlslabel": "none", + "mounted": "yes", + "mountpoint": "/rpool", + "name": "rpool", + "nbmand": "off", + "normalization": "none", + "org.openindiana.caiman:install": "ready", + "primarycache": "all", + "quota": "none", + "readonly": "off", + "recordsize": "128K", + "redundant_metadata": "all", + "refcompressratio": "1.00x", + "referenced": "29.5K", + "refquota": "none", + "refreservation": "none", + "reservation": "none", + "secondarycache": "all", + "setuid": "on", + "sharenfs": "off", + "sharesmb": "off", + "snapdir": "hidden", + "snapshot_count": "none", + "snapshot_limit": "none", + "sync": "standard", + "type": "filesystem", + "used": "4.41G", + "usedbychildren": "4.41G", + "usedbydataset": "29.5K", + "usedbyrefreservation": "0", + "usedbysnapshots": "0", + "utf8only": "off", + "version": "5", + "vscan": "off", + "written": "29.5K", + "xattr": "on", + "zoned": "off" + } +""" from collections import defaultdict From 28fed38757acd48c34b0d9c50b9bdf8b41fc9d16 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Sun, 22 Dec 2024 22:23:33 +0100 Subject: [PATCH 067/302] [PR #9310/2adcc34d backport][stable-10] CI: Arch Linux updated to Python 3.13 (#9314) CI: Arch Linux updated to Python 3.13 (#9310) * Arch Linux updated to Python 3.13. * Skip lmdb_kv lookup on Arch Linux. Ref: https://github.com/jnwatson/py-lmdb/issues/362 (cherry picked from commit 2adcc34dd551f54d2f81a34d6a7b299b290f9430) Co-authored-by: Felix Fontein --- .azure-pipelines/azure-pipelines.yml | 2 +- tests/integration/targets/lookup_lmdb_kv/runme.sh | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.azure-pipelines/azure-pipelines.yml b/.azure-pipelines/azure-pipelines.yml index 362b5d59dd..b9d428f2b0 100644 --- a/.azure-pipelines/azure-pipelines.yml +++ b/.azure-pipelines/azure-pipelines.yml @@ -345,7 +345,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/tests/integration/targets/lookup_lmdb_kv/runme.sh b/tests/integration/targets/lookup_lmdb_kv/runme.sh index 71faa439d1..286ec6b16d 100755 --- a/tests/integration/targets/lookup_lmdb_kv/runme.sh +++ b/tests/integration/targets/lookup_lmdb_kv/runme.sh @@ -4,6 +4,10 @@ # SPDX-License-Identifier: GPL-3.0-or-later set -eux +if grep -Fq 'NAME="Arch Linux"' /etc/os-release; then + exit 0 +fi + ANSIBLE_ROLES_PATH=../ \ ansible-playbook dependencies.yml -v "$@" From 3fe559b88fbdcf2b15a83e6df568362643d510a7 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 12:25:07 +0100 Subject: [PATCH 068/302] [PR #9318/79bef1a1 backport][stable-10] action plugins: use f-strings (#9333) action plugins: use f-strings (#9318) * action plugins: use f-strings * add changelog frag * adjustment from review (cherry picked from commit 79bef1a14c09f652f0d2833cd0eea3251309c373) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- .../fragments/9318-fstr-actionplugins.yml | 3 + plugins/action/iptables_state.py | 58 +++++++++-------- plugins/action/shutdown.py | 62 ++++++++----------- 3 files changed, 62 insertions(+), 61 deletions(-) create mode 100644 changelogs/fragments/9318-fstr-actionplugins.yml diff --git a/changelogs/fragments/9318-fstr-actionplugins.yml b/changelogs/fragments/9318-fstr-actionplugins.yml new file mode 100644 index 0000000000..7df54f3c19 --- /dev/null +++ b/changelogs/fragments/9318-fstr-actionplugins.yml @@ -0,0 +1,3 @@ +minor_changes: + - iptables_state action plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9318). + - shutdown action plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9318). diff --git a/plugins/action/iptables_state.py b/plugins/action/iptables_state.py index 5ea55af58c..39ee85d778 100644 --- a/plugins/action/iptables_state.py +++ b/plugins/action/iptables_state.py @@ -22,25 +22,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 +103,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 +127,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..9505cc2155 100644 --- a/plugins/action/shutdown.py +++ b/plugins/action/shutdown.py @@ -18,6 +18,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 +88,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 +129,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 +168,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 +177,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: {to_text(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 +196,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: From 2499c1132d8a3c8826f0455062abe79ae3e85b0d Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 12:25:16 +0100 Subject: [PATCH 069/302] [PR #9323/1d8f0b29 backport][stable-10] inventory plugins: use f-strings (#9332) inventory plugins: use f-strings (#9323) * inventory plugins: use f-strings * add changelog frag (cherry picked from commit 1d8f0b294216971fd596c1582990e888b33e76c0) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- .../fragments/9323-fstr-inventory-plugins.yml | 14 ++++ plugins/inventory/cobbler.py | 40 +++++----- plugins/inventory/gitlab_runners.py | 2 +- plugins/inventory/icinga2.py | 28 +++---- plugins/inventory/linode.py | 2 +- plugins/inventory/lxd.py | 78 +++++++++---------- plugins/inventory/nmap.py | 8 +- plugins/inventory/online.py | 6 +- plugins/inventory/opennebula.py | 8 +- plugins/inventory/proxmox.py | 56 +++++++------ plugins/inventory/scaleway.py | 4 +- plugins/inventory/stackpath_compute.py | 22 +++--- plugins/inventory/virtualbox.py | 2 +- plugins/inventory/xen_orchestra.py | 27 +++---- 14 files changed, 148 insertions(+), 149 deletions(-) create mode 100644 changelogs/fragments/9323-fstr-inventory-plugins.yml diff --git a/changelogs/fragments/9323-fstr-inventory-plugins.yml b/changelogs/fragments/9323-fstr-inventory-plugins.yml new file mode 100644 index 0000000000..03ded1f0ec --- /dev/null +++ b/changelogs/fragments/9323-fstr-inventory-plugins.yml @@ -0,0 +1,14 @@ +minor_changes: + - cobbler inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - gitlab_runners inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - icinga2 inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - linode inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - lxd inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - nmap inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - online inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - opennebula inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - proxmox inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - scaleway inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - stackpath_compute inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - virtualbox inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). + - xen_orchestra inventory plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9323). diff --git a/plugins/inventory/cobbler.py b/plugins/inventory/cobbler.py index 664380da8f..ef88dae18c 100644 --- a/plugins/inventory/cobbler.py +++ b/plugins/inventory/cobbler.py @@ -160,7 +160,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 +211,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 +243,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 +260,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 +273,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 +286,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 +303,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 +327,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 +377,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}: {to_text(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..a5f53b8b14 100644 --- a/plugins/inventory/gitlab_runners.py +++ b/plugins/inventory/gitlab_runners.py @@ -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: {to_native(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..527a329173 100644 --- a/plugins/inventory/icinga2.py +++ b/plugins/inventory/icinga2.py @@ -141,7 +141,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 +151,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 +160,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 +298,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/linode.py b/plugins/inventory/linode.py index 5c9a4718f5..46f2faeace 100644 --- a/plugins/inventory/linode.py +++ b/plugins/inventory/linode.py @@ -161,7 +161,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..1e135f7415 100644 --- a/plugins/inventory/lxd.py +++ b/plugins/inventory/lxd.py @@ -211,7 +211,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)}: {to_native(err)}') def save_json_data(self, path, file_name=None): """save data as json @@ -241,7 +241,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: {to_native(err)}') def verify_file(self, path): """Check the config @@ -281,7 +281,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: {to_native(url)}') return True def _connect_to_socket(self): @@ -306,7 +306,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: {to_native(error_storage)}') def _get_networks(self): """Get Networknames @@ -355,7 +355,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 +383,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 +449,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 +462,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 +479,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 +516,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 +579,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: {to_native(err)}") def extract_information_from_instance_configs(self): """Process configuration information @@ -600,24 +600,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 +651,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 +670,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 +691,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 +703,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 +792,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')}: {to_native(err)}") for instance_name in self.inventory.hosts: if self.data['inventory'][instance_name].get('network_interfaces') is not None: @@ -997,12 +997,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 +1039,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 +1120,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: {to_native(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..fbc8a76173 100644 --- a/plugins/inventory/nmap.py +++ b/plugins/inventory/nmap.py @@ -178,7 +178,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: {to_native(e)}') super(InventoryModule, self).parse(inventory, loader, path, cache=cache) @@ -248,7 +248,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 +259,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: {to_native(e)}') for line in t_stdout.splitlines(): hits = self.find_host.match(line) @@ -300,7 +300,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)}: {to_native(e)} ") if cache_needs_update: self._cache[cache_key] = results diff --git a/plugins/inventory/online.py b/plugins/inventory/online.py index 70b8d14192..9475049c08 100644 --- a/plugins/inventory/online.py +++ b/plugins/inventory/online.py @@ -138,7 +138,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 +245,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..2750d4d370 100644 --- a/plugins/inventory/opennebula.py +++ b/plugins/inventory/opennebula.py @@ -128,9 +128,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 +166,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: {to_native(e)}") return vm_pool diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py index 38877b895c..e4a39df3d7 100644 --- a/plugins/inventory/proxmox.py +++ b/plugins/inventory/proxmox.py @@ -284,12 +284,12 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable): 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 @@ -341,23 +341,23 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable): return make_unsafe(self._cache[self.cache_key][url]) 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: @@ -371,7 +371,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 @@ -398,9 +398,7 @@ 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: @@ -418,7 +416,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 @@ -426,7 +424,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 @@ -442,13 +440,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 @@ -464,7 +462,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': @@ -489,13 +487,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 @@ -509,11 +507,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 @@ -525,7 +523,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} - {to_native(e)}" if self.strict: raise AnsibleError(message) display.warning(message) @@ -566,8 +564,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'] @@ -575,7 +573,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 @@ -586,7 +584,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): @@ -603,7 +601,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) @@ -636,7 +634,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 @@ -665,7 +663,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('/') diff --git a/plugins/inventory/scaleway.py b/plugins/inventory/scaleway.py index 4205caeca7..7fc5f12c44 100644 --- a/plugins/inventory/scaleway.py +++ b/plugins/inventory/scaleway.py @@ -140,7 +140,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}: {to_native(e)}") try: raw_json = json.loads(to_text(response.read())) except ValueError: @@ -161,7 +161,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..c87d0e5277 100644 --- a/plugins/inventory/stackpath_compute.py +++ b/plugins/inventory/stackpath_compute.py @@ -139,7 +139,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 +155,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 +184,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 +194,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 +251,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 +283,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..e6f401ca86 100644 --- a/plugins/inventory/virtualbox.py +++ b/plugins/inventory/virtualbox.py @@ -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): diff --git a/plugins/inventory/xen_orchestra.py b/plugins/inventory/xen_orchestra.py index 4094af2468..0a050d0bf9 100644 --- a/plugins/inventory/xen_orchestra.py +++ b/plugins/inventory/xen_orchestra.py @@ -138,7 +138,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 +162,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 +170,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'] @@ -252,8 +249,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable): def _add_hosts(self, hosts, pools): for host in hosts.values(): entry_name = host['uuid'] - group_name = 'xo_host_{0}'.format( - clean_group_name(host['name_label'])) + 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 +272,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 +286,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 From 3c6131b45170cbd9d5becca55674d29f80f12608 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 12:25:24 +0100 Subject: [PATCH 070/302] [PR #9320/cb2cd00c backport][stable-10] cache plugins: use f-strings (#9331) cache plugins: use f-strings (#9320) * cache plugins: use f-strings * add changelog frag (cherry picked from commit cb2cd00cd17492207aad2280b40455fe0aa5a034) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9320-fstr-cache-plugins.yml | 3 +++ plugins/cache/memcached.py | 2 +- plugins/cache/redis.py | 6 +++--- 3 files changed, 7 insertions(+), 4 deletions(-) create mode 100644 changelogs/fragments/9320-fstr-cache-plugins.yml diff --git a/changelogs/fragments/9320-fstr-cache-plugins.yml b/changelogs/fragments/9320-fstr-cache-plugins.yml new file mode 100644 index 0000000000..cc1aa6ea2e --- /dev/null +++ b/changelogs/fragments/9320-fstr-cache-plugins.yml @@ -0,0 +1,3 @@ +minor_changes: + - memcached cache plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9320). + - redis cache plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9320). diff --git a/plugins/cache/memcached.py b/plugins/cache/memcached.py index 93131172c5..a70c3cb121 100644 --- a/plugins/cache/memcached.py +++ b/plugins/cache/memcached.py @@ -191,7 +191,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/redis.py b/plugins/cache/redis.py index f96aafaa84..aa0243b9dd 100644 --- a/plugins/cache/redis.py +++ b/plugins/cache/redis.py @@ -131,7 +131,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 +164,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: {to_native(exc)}') def _make_key(self, key): return self._prefix + key From 4c26dc07606e751f175acbcd9a14d3bb60db40e6 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 12:25:34 +0100 Subject: [PATCH 071/302] [PR #9319/c7edf0a8 backport][stable-10] become plugins: use f-strings (#9330) become plugins: use f-strings (#9319) * become plugins: use f-strings * add changelog frag (cherry picked from commit c7edf0a87b38fc8ef2058638efd9c2d5a0bdf492) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9319-fstr-become-plugins.yml | 10 ++++++++++ plugins/become/doas.py | 4 ++-- plugins/become/dzdo.py | 8 ++++---- plugins/become/ksu.py | 2 +- plugins/become/machinectl.py | 2 +- plugins/become/pbrun.py | 4 ++-- plugins/become/pfexec.py | 2 +- plugins/become/pmrun.py | 2 +- plugins/become/sesu.py | 2 +- plugins/become/sudosu.py | 10 +++++----- 10 files changed, 28 insertions(+), 18 deletions(-) create mode 100644 changelogs/fragments/9319-fstr-become-plugins.yml diff --git a/changelogs/fragments/9319-fstr-become-plugins.yml b/changelogs/fragments/9319-fstr-become-plugins.yml new file mode 100644 index 0000000000..dcdc4b3f52 --- /dev/null +++ b/changelogs/fragments/9319-fstr-become-plugins.yml @@ -0,0 +1,10 @@ +minor_changes: + - doas become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319). + - dzdo become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319). + - ksu become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319). + - machinectl become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319). + - 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). + - sesu become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319). + - sudosu become plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9319). diff --git a/plugins/become/doas.py b/plugins/become/doas.py index 761e5e1e95..9d3a73b5b0 100644 --- a/plugins/become/doas.py +++ b/plugins/become/doas.py @@ -125,9 +125,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..323d1b7395 100644 --- a/plugins/become/dzdo.py +++ b/plugins/become/dzdo.py @@ -92,10 +92,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..8ee8f89512 100644 --- a/plugins/become/ksu.py +++ b/plugins/become/ksu.py @@ -124,4 +124,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..1dd648e6e0 100644 --- a/plugins/become/machinectl.py +++ b/plugins/become/machinectl.py @@ -123,7 +123,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..ccba615a85 100644 --- a/plugins/become/pbrun.py +++ b/plugins/become/pbrun.py @@ -103,7 +103,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..d3b98a6317 100644 --- a/plugins/become/pfexec.py +++ b/plugins/become/pfexec.py @@ -106,4 +106,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..093906214d 100644 --- a/plugins/become/pmrun.py +++ b/plugins/become/pmrun.py @@ -78,4 +78,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/sesu.py b/plugins/become/sesu.py index 4dcb837e70..08dfdfca54 100644 --- a/plugins/become/sesu.py +++ b/plugins/become/sesu.py @@ -93,4 +93,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..5dae85a192 100644 --- a/plugins/become/sudosu.py +++ b/plugins/become/sudosu.py @@ -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)}" From 977f53f8232178891e8db7917b58718fd878ce89 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 12:25:42 +0100 Subject: [PATCH 072/302] [PR #9306/d05d067f backport][stable-10] z mods adjust docs (#9329) z mods adjust docs (#9306) z* modules: adjust docs (re-commiting with adjustment from PR) (cherry picked from commit d05d067f3b84622c8c9db3dec667b56b16d05df6) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/zfs_facts.py | 76 ++++--------------- plugins/modules/znode.py | 134 ++++++++++++++++----------------- plugins/modules/zpool_facts.py | 134 ++++++++++++--------------------- 3 files changed, 128 insertions(+), 216 deletions(-) diff --git a/plugins/modules/zfs_facts.py b/plugins/modules/zfs_facts.py index 25fd10099b..115e8e3e7a 100644 --- a/plugins/modules/zfs_facts.py +++ b/plugins/modules/zfs_facts.py @@ -73,83 +73,33 @@ EXAMPLES = r""" RETURN = r""" name: - description: ZFS dataset name + description: ZFS dataset name. returned: always type: str sample: rpool/var/spool parsable: - description: if parsable output should be provided in machine friendly format. + description: If parsable output should be provided in machine friendly format. returned: if O(parsable=True) type: bool sample: true recurse: - description: if we should recurse over ZFS dataset + description: If we should recurse over ZFS dataset. returned: if O(recurse=True) type: bool sample: true zfs_datasets: - description: ZFS dataset facts + description: ZFS dataset facts. returned: always type: str - sample: - { - "aclinherit": "restricted", - "aclmode": "discard", - "atime": "on", - "available": "43.8G", - "canmount": "on", - "casesensitivity": "sensitive", - "checksum": "on", - "compression": "off", - "compressratio": "1.00x", - "copies": "1", - "creation": "Thu Jun 16 11:37 2016", - "dedup": "off", - "devices": "on", - "exec": "on", - "filesystem_count": "none", - "filesystem_limit": "none", - "logbias": "latency", - "logicalreferenced": "18.5K", - "logicalused": "3.45G", - "mlslabel": "none", - "mounted": "yes", - "mountpoint": "/rpool", - "name": "rpool", - "nbmand": "off", - "normalization": "none", - "org.openindiana.caiman:install": "ready", - "primarycache": "all", - "quota": "none", - "readonly": "off", - "recordsize": "128K", - "redundant_metadata": "all", - "refcompressratio": "1.00x", - "referenced": "29.5K", - "refquota": "none", - "refreservation": "none", - "reservation": "none", - "secondarycache": "all", - "setuid": "on", - "sharenfs": "off", - "sharesmb": "off", - "snapdir": "hidden", - "snapshot_count": "none", - "snapshot_limit": "none", - "sync": "standard", - "type": "filesystem", - "used": "4.41G", - "usedbychildren": "4.41G", - "usedbydataset": "29.5K", - "usedbyrefreservation": "0", - "usedbysnapshots": "0", - "utf8only": "off", - "version": "5", - "vscan": "off", - "written": "29.5K", - "xattr": "on", - "zoned": "off" - } + sample: {"aclinherit": "restricted", "aclmode": "discard", "atime": "on", "available": "43.8G", "canmount": "on", "casesensitivity": "sensitive", + "checksum": "on", "compression": "off", "compressratio": "1.00x", "copies": "1", "creation": "Thu Jun 16 11:37 2016", "dedup": "off", "devices": "on", + "exec": "on", "filesystem_count": "none", "filesystem_limit": "none", "logbias": "latency", "logicalreferenced": "18.5K", "logicalused": "3.45G", + "mlslabel": "none", "mounted": "yes", "mountpoint": "/rpool", "name": "rpool", "nbmand": "off", "normalization": "none", "org.openindiana.caiman:install": + "ready", "primarycache": "all", "quota": "none", "readonly": "off", "recordsize": "128K", "redundant_metadata": "all", "refcompressratio": "1.00x", + "referenced": "29.5K", "refquota": "none", "refreservation": "none", "reservation": "none", "secondarycache": "all", "setuid": "on", "sharenfs": "off", + "sharesmb": "off", "snapdir": "hidden", "snapshot_count": "none", "snapshot_limit": "none", "sync": "standard", "type": "filesystem", "used": "4.41G", + "usedbychildren": "4.41G", "usedbydataset": "29.5K", "usedbyrefreservation": "0", "usedbysnapshots": "0", "utf8only": "off", "version": "5", + "vscan": "off", "written": "29.5K", "xattr": "on", "zoned": "off"} """ from collections import defaultdict diff --git a/plugins/modules/znode.py b/plugins/modules/znode.py index e8f7f1dc76..ca59704d12 100644 --- a/plugins/modules/znode.py +++ b/plugins/modules/znode.py @@ -8,83 +8,81 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: znode short_description: Create, delete, retrieve, and update znodes using ZooKeeper description: - - Create, delete, retrieve, and update znodes using ZooKeeper. + - Create, delete, retrieve, and update znodes using ZooKeeper. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none extends_documentation_fragment: - - community.general.attributes + - community.general.attributes options: - hosts: - description: - - A list of ZooKeeper servers (format '[server]:[port]'). - required: true - type: str - name: - description: - - The path of the znode. - required: true - type: str - value: - description: - - The value assigned to the znode. - type: str - op: - description: - - An operation to perform. Mutually exclusive with state. - choices: [ get, wait, list ] - type: str - state: - description: - - The state to enforce. Mutually exclusive with op. - choices: [ present, absent ] - type: str - timeout: - description: - - The amount of time to wait for a node to appear. - default: 300 - type: int - recursive: - description: - - Recursively delete node and all its children. - type: bool - default: false - auth_scheme: - description: - - 'Authentication scheme.' - choices: [ digest, sasl ] - type: str - default: "digest" - required: false - version_added: 5.8.0 - auth_credential: - description: - - The authentication credential value. Depends on O(auth_scheme). - - The format for O(auth_scheme=digest) is C(user:password), - and the format for O(auth_scheme=sasl) is C(user:password). - type: str - required: false - version_added: 5.8.0 - use_tls: - description: - - Using TLS/SSL or not. - type: bool - default: false - required: false - version_added: '6.5.0' + hosts: + description: + - A list of ZooKeeper servers (format V([server]:[port])). + required: true + type: str + name: + description: + - The path of the znode. + required: true + type: str + value: + description: + - The value assigned to the znode. + type: str + op: + description: + - An operation to perform. Mutually exclusive with state. + choices: [get, wait, list] + type: str + state: + description: + - The state to enforce. Mutually exclusive with op. + choices: [present, absent] + type: str + timeout: + description: + - The amount of time to wait for a node to appear. + default: 300 + type: int + recursive: + description: + - Recursively delete node and all its children. + type: bool + default: false + auth_scheme: + description: + - 'Authentication scheme.' + choices: [digest, sasl] + type: str + default: "digest" + required: false + version_added: 5.8.0 + auth_credential: + description: + - The authentication credential value. Depends on O(auth_scheme). + - The format for O(auth_scheme=digest) is C(user:password), and the format for O(auth_scheme=sasl) is C(user:password). + type: str + required: false + version_added: 5.8.0 + use_tls: + description: + - Using TLS/SSL or not. + type: bool + default: false + required: false + version_added: '6.5.0' requirements: - - kazoo >= 2.1 + - kazoo >= 2.1 author: "Trey Perry (@treyperry)" -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Creating or updating a znode with a given value community.general.znode: hosts: 'localhost:2181' diff --git a/plugins/modules/zpool_facts.py b/plugins/modules/zpool_facts.py index 2477a920b0..e0b87b570c 100644 --- a/plugins/modules/zpool_facts.py +++ b/plugins/modules/zpool_facts.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: zpool_facts short_description: Gather facts about ZFS pools description: @@ -21,29 +20,28 @@ extends_documentation_fragment: - community.general.attributes.facts - community.general.attributes.facts_module options: - name: - description: - - ZFS pool name. - type: str - aliases: [ "pool", "zpool" ] - required: false - parsable: - description: - - Specifies if property values should be displayed in machine - friendly format. - type: bool - default: false - required: false - properties: - description: - - Specifies which dataset properties should be queried in comma-separated format. - For more information about dataset properties, check zpool(1M) man page. - type: str - default: all - required: false -''' + name: + description: + - ZFS pool name. + type: str + aliases: ["pool", "zpool"] + required: false + parsable: + description: + - Specifies if property values should be displayed in machine friendly format. + type: bool + default: false + required: false + properties: + description: + - Specifies which dataset properties should be queried in comma-separated format. For more information about dataset properties, check zpool(1M) + man page. + type: str + default: all + required: false +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Gather facts about ZFS pool rpool community.general.zpool_facts: pool=rpool @@ -54,71 +52,37 @@ EXAMPLES = ''' ansible.builtin.debug: msg: 'ZFS pool {{ item.name }} has {{ item.free }} free space out of {{ item.size }}.' with_items: '{{ ansible_zfs_pools }}' -''' +""" -RETURN = ''' +RETURN = r""" ansible_facts: - description: Dictionary containing all the detailed information about the ZFS pool facts - returned: always - type: complex - contains: - ansible_zfs_pools: - description: ZFS pool facts - returned: always - type: str - sample: - { - "allocated": "3.46G", - "altroot": "-", - "autoexpand": "off", - "autoreplace": "off", - "bootfs": "rpool/ROOT/openindiana", - "cachefile": "-", - "capacity": "6%", - "comment": "-", - "dedupditto": "0", - "dedupratio": "1.00x", - "delegation": "on", - "expandsize": "-", - "failmode": "wait", - "feature@async_destroy": "enabled", - "feature@bookmarks": "enabled", - "feature@edonr": "enabled", - "feature@embedded_data": "active", - "feature@empty_bpobj": "active", - "feature@enabled_txg": "active", - "feature@extensible_dataset": "enabled", - "feature@filesystem_limits": "enabled", - "feature@hole_birth": "active", - "feature@large_blocks": "enabled", - "feature@lz4_compress": "active", - "feature@multi_vdev_crash_dump": "enabled", - "feature@sha512": "enabled", - "feature@skein": "enabled", - "feature@spacemap_histogram": "active", - "fragmentation": "3%", - "free": "46.3G", - "freeing": "0", - "guid": "15729052870819522408", - "health": "ONLINE", - "leaked": "0", - "listsnapshots": "off", - "name": "rpool", - "readonly": "off", - "size": "49.8G", - "version": "-" - } + description: Dictionary containing all the detailed information about the ZFS pool facts. + returned: always + type: complex + contains: + ansible_zfs_pools: + description: ZFS pool facts. + returned: always + type: str + sample: {"allocated": "3.46G", "altroot": "-", "autoexpand": "off", "autoreplace": "off", "bootfs": "rpool/ROOT/openindiana", "cachefile": "-", + "capacity": "6%", "comment": "-", "dedupditto": "0", "dedupratio": "1.00x", "delegation": "on", "expandsize": "-", "failmode": "wait", + "feature@async_destroy": "enabled", "feature@bookmarks": "enabled", "feature@edonr": "enabled", "feature@embedded_data": "active", + "feature@empty_bpobj": "active", "feature@enabled_txg": "active", "feature@extensible_dataset": "enabled", "feature@filesystem_limits": "enabled", + "feature@hole_birth": "active", "feature@large_blocks": "enabled", "feature@lz4_compress": "active", "feature@multi_vdev_crash_dump": "enabled", + "feature@sha512": "enabled", "feature@skein": "enabled", "feature@spacemap_histogram": "active", "fragmentation": "3%", "free": "46.3G", + "freeing": "0", "guid": "15729052870819522408", "health": "ONLINE", "leaked": "0", "listsnapshots": "off", "name": "rpool", "readonly": "off", + "size": "49.8G", "version": "-"} name: - description: ZFS pool name - returned: always - type: str - sample: rpool + description: ZFS pool name. + returned: always + type: str + sample: rpool parsable: - description: if parsable output should be provided in machine friendly format. - returned: if 'parsable' is set to True - type: bool - sample: true -''' + description: If parsable output should be provided in machine friendly format. + returned: if O(parsable=true) + type: bool + sample: true +""" from collections import defaultdict From b3ad22f33fa5b3248ec991d0d90d0cc972739b95 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 12:25:51 +0100 Subject: [PATCH 073/302] [PR #9309/b57fef20 backport][stable-10] [vw]*: adjust docs (#9326) [vw]*: adjust docs (#9309) [vm]*: adjust docs (cherry picked from commit b57fef201e282937c8772ec9246e3fb61d06dbbc) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/vdo.py | 439 +++++++++-------------- plugins/modules/vertica_configuration.py | 41 +-- plugins/modules/vertica_info.py | 26 +- plugins/modules/vertica_role.py | 23 +- plugins/modules/vertica_schema.py | 37 +- plugins/modules/vertica_user.py | 38 +- plugins/modules/vexata_eg.py | 35 +- plugins/modules/vexata_volume.py | 24 +- plugins/modules/vmadm.py | 78 ++-- plugins/modules/wakeonlan.py | 27 +- plugins/modules/wdc_redfish_command.py | 35 +- plugins/modules/wdc_redfish_info.py | 57 ++- 12 files changed, 353 insertions(+), 507 deletions(-) diff --git a/plugins/modules/vdo.py b/plugins/modules/vdo.py index 8b0e745960..c7df2d234c 100644 --- a/plugins/modules/vdo.py +++ b/plugins/modules/vdo.py @@ -8,10 +8,9 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: - - Bryan Gurney (@bgurney-rh) + - Bryan Gurney (@bgurney-rh) module: vdo @@ -19,277 +18,189 @@ short_description: Module to control VDO description: - - This module controls the VDO dedupe and compression device. - - VDO, or Virtual Data Optimizer, is a device-mapper target that - provides inline block-level deduplication, compression, and - thin provisioning capabilities to primary storage. - + - This module controls the VDO dedupe and compression device. + - VDO, or Virtual Data Optimizer, is a device-mapper target that provides inline block-level deduplication, compression, and thin provisioning + capabilities to primary storage. 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: - - The name of the VDO volume. - type: str - required: true - state: - description: - - Whether this VDO volume should be "present" or "absent". - If a "present" VDO volume does not exist, it will be - created. If a "present" VDO volume already exists, it - will be modified, by updating the configuration, which - will take effect when the VDO volume is restarted. - Not all parameters of an existing VDO volume can be - modified; the "statusparamkeys" list contains the - parameters that can be modified after creation. If an - "absent" VDO volume does not exist, it will not be - removed. - type: str - choices: [ absent, present ] - default: present - activated: - description: - - The "activate" status for a VDO volume. If this is set - to V(false), the VDO volume cannot be started, and it will - not start on system startup. However, on initial - creation, a VDO volume with "activated" set to "off" - will be running, until stopped. This is the default - behavior of the "vdo create" command; it provides the - user an opportunity to write a base amount of metadata - (filesystem, LVM headers, etc.) to the VDO volume prior - to stopping the volume, and leaving it deactivated - until ready to use. - type: bool - running: - description: - - Whether this VDO volume is running. - - A VDO volume must be activated in order to be started. - type: bool - device: - description: - - The full path of the device to use for VDO storage. - - This is required if "state" is "present". - type: str - logicalsize: - description: - - The logical size of the VDO volume (in megabytes, or - LVM suffix format). If not specified for a new volume, - this defaults to the same size as the underlying storage - device, which is specified in the 'device' parameter. - Existing volumes will maintain their size if the - logicalsize parameter is not specified, or is smaller - than or identical to the current size. If the specified - size is larger than the current size, a growlogical - operation will be performed. - type: str - deduplication: - description: - - Configures whether deduplication is enabled. The - default for a created volume is 'enabled'. Existing - volumes will maintain their previously configured - setting unless a different value is specified in the - playbook. - type: str - choices: [ disabled, enabled ] - compression: - description: - - Configures whether compression is enabled. The default - for a created volume is 'enabled'. Existing volumes - will maintain their previously configured setting unless - a different value is specified in the playbook. - type: str - choices: [ disabled, enabled ] - blockmapcachesize: - description: - - The amount of memory allocated for caching block map - pages, in megabytes (or may be issued with an LVM-style - suffix of K, M, G, or T). The default (and minimum) - value is 128M. The value specifies the size of the - cache; there is a 15% memory usage overhead. Each 1.25G - of block map covers 1T of logical blocks, therefore a - small amount of block map cache memory can cache a - significantly large amount of block map data. Existing - volumes will maintain their previously configured - setting unless a different value is specified in the - playbook. - type: str - readcache: - description: - - Enables or disables the read cache. The default is - 'disabled'. Choosing 'enabled' enables a read cache - which may improve performance for workloads of high - deduplication, read workloads with a high level of - compression, or on hard disk storage. Existing - volumes will maintain their previously configured - setting unless a different value is specified in the - playbook. - - The read cache feature is available in VDO 6.1 and older. - type: str - choices: [ disabled, enabled ] - readcachesize: - description: - - Specifies the extra VDO device read cache size in - megabytes. This is in addition to a system-defined - minimum. Using a value with a suffix of K, M, G, or T - is optional. The default value is 0. 1.125 MB of - memory per bio thread will be used per 1 MB of read - cache specified (for example, a VDO volume configured - with 4 bio threads will have a read cache memory usage - overhead of 4.5 MB per 1 MB of read cache specified). - Existing volumes will maintain their previously - configured setting unless a different value is specified - in the playbook. - - The read cache feature is available in VDO 6.1 and older. - type: str - emulate512: - description: - - Enables 512-byte emulation mode, allowing drivers or - filesystems to access the VDO volume at 512-byte - granularity, instead of the default 4096-byte granularity. - Default is 'disabled'; only recommended when a driver - or filesystem requires 512-byte sector level access to - a device. This option is only available when creating - a new volume, and cannot be changed for an existing - volume. - type: bool - default: false - growphysical: - description: - - Specifies whether to attempt to execute a growphysical - operation, if there is enough unused space on the - device. A growphysical operation will be executed if - there is at least 64 GB of free space, relative to the - previous physical size of the affected VDO volume. - type: bool - default: false - slabsize: - description: - - The size of the increment by which the physical size of - a VDO volume is grown, in megabytes (or may be issued - with an LVM-style suffix of K, M, G, or T). Must be a - power of two between 128M and 32G. The default is 2G, - which supports volumes having a physical size up to 16T. - The maximum, 32G, supports a physical size of up to 256T. - This option is only available when creating a new - volume, and cannot be changed for an existing volume. - type: str - writepolicy: - description: - - Specifies the write policy of the VDO volume. The - 'sync' mode acknowledges writes only after data is on - stable storage. The 'async' mode acknowledges writes - when data has been cached for writing to stable - storage. The default (and highly recommended) 'auto' - mode checks the storage device to determine whether it - supports flushes. Devices that support flushes will - result in a VDO volume in 'async' mode, while devices - that do not support flushes will run in sync mode. - Existing volumes will maintain their previously - configured setting unless a different value is - specified in the playbook. - type: str - choices: [ async, auto, sync ] - indexmem: - description: - - Specifies the amount of index memory in gigabytes. The - default is 0.25. The special decimal values 0.25, 0.5, - and 0.75 can be used, as can any positive integer. - This option is only available when creating a new - volume, and cannot be changed for an existing volume. - type: str - indexmode: - description: - - Specifies the index mode of the Albireo index. The - default is 'dense', which has a deduplication window of - 1 GB of index memory per 1 TB of incoming data, - requiring 10 GB of index data on persistent storage. - The 'sparse' mode has a deduplication window of 1 GB of - index memory per 10 TB of incoming data, but requires - 100 GB of index data on persistent storage. This option - is only available when creating a new volume, and cannot - be changed for an existing volume. - type: str - choices: [ dense, sparse ] - ackthreads: - description: - - Specifies the number of threads to use for - acknowledging completion of requested VDO I/O operations. - Valid values are integer values from 1 to 100 (lower - numbers are preferable due to overhead). The default is - 1. Existing volumes will maintain their previously - configured setting unless a different value is specified - in the playbook. - type: str - biothreads: - description: - - Specifies the number of threads to use for submitting I/O - operations to the storage device. Valid values are - integer values from 1 to 100 (lower numbers are - preferable due to overhead). The default is 4. - Existing volumes will maintain their previously - configured setting unless a different value is specified - in the playbook. - type: str - cputhreads: - description: - - Specifies the number of threads to use for CPU-intensive - work such as hashing or compression. Valid values are - integer values from 1 to 100 (lower numbers are - preferable due to overhead). The default is 2. - Existing volumes will maintain their previously - configured setting unless a different value is specified - in the playbook. - type: str - logicalthreads: - description: - - Specifies the number of threads across which to - subdivide parts of the VDO processing based on logical - block addresses. Valid values are integer values from - 1 to 100 (lower numbers are preferable due to overhead). - The default is 1. Existing volumes will maintain their - previously configured setting unless a different value - is specified in the playbook. - type: str - physicalthreads: - description: - - Specifies the number of threads across which to - subdivide parts of the VDO processing based on physical - block addresses. Valid values are integer values from - 1 to 16 (lower numbers are preferable due to overhead). - The physical space used by the VDO volume must be - larger than (slabsize * physicalthreads). The default - is 1. Existing volumes will maintain their previously - configured setting unless a different value is specified - in the playbook. - type: str - force: - description: - - When creating a volume, ignores any existing file system - or VDO signature already present in the storage device. - When stopping or removing a VDO volume, first unmounts - the file system stored on the device if mounted. - - "B(Warning:) Since this parameter removes all safety - checks it is important to make sure that all parameters - provided are accurate and intentional." - type: bool - default: false - version_added: 2.4.0 + name: + description: + - The name of the VDO volume. + type: str + required: true + state: + description: + - Whether this VDO volume should be V(present) or V(absent). If a V(present) VDO volume does not exist, it will be created. If a V(present) + VDO volume already exists, it will be modified, by updating the configuration, which will take effect when the VDO volume is restarted. + Not all parameters of an existing VDO volume can be modified; the C(statusparamkeys) list in the code contains the parameters that can + be modified after creation. If an V(absent) VDO volume does not exist, it will not be removed. + type: str + choices: [absent, present] + default: present + activated: + description: + - The C(activate) status for a VDO volume. If this is set to V(false), the VDO volume cannot be started, and it will not start on system + startup. However, on initial creation, a VDO volume with "activated" set to "off" will be running, until stopped. This is the default + behavior of the C(vdo create) command; it provides the user an opportunity to write a base amount of metadata (filesystem, LVM headers, + etc.) to the VDO volume prior to stopping the volume, and leaving it deactivated until ready to use. + type: bool + running: + description: + - Whether this VDO volume is running. + - A VDO volume must be activated in order to be started. + type: bool + device: + description: + - The full path of the device to use for VDO storage. + - This is required if O(state=present). + type: str + logicalsize: + description: + - The logical size of the VDO volume (in megabytes, or LVM suffix format). If not specified for a new volume, this defaults to the same + size as the underlying storage device, which is specified in the O(device) parameter. Existing volumes will maintain their size if the + logicalsize parameter is not specified, or is smaller than or identical to the current size. If the specified size is larger than the + current size, a C(growlogical) operation will be performed. + type: str + deduplication: + description: + - Configures whether deduplication is enabled. The default for a created volume is V(enabled). Existing volumes will maintain their previously + configured setting unless a different value is specified in the playbook. + type: str + choices: [disabled, enabled] + compression: + description: + - Configures whether compression is enabled. The default for a created volume is V(enabled). Existing volumes will maintain their previously + configured setting unless a different value is specified in the playbook. + type: str + choices: [disabled, enabled] + blockmapcachesize: + description: + - The amount of memory allocated for caching block map pages, in megabytes (or may be issued with an LVM-style suffix of K, M, G, or T). + The default (and minimum) value is V(128M). The value specifies the size of the cache; there is a 15% memory usage overhead. Each 1.25G + of block map covers 1T of logical blocks, therefore a small amount of block map cache memory can cache a significantly large amount of + block map data. + - Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. + type: str + readcache: + description: + - Enables or disables the read cache. The default is V(disabled). Choosing V(enabled) enables a read cache which may improve performance + for workloads of high deduplication, read workloads with a high level of compression, or on hard disk storage. Existing volumes will maintain + their previously configured setting unless a different value is specified in the playbook. + - The read cache feature is available in VDO 6.1 and older. + type: str + choices: [disabled, enabled] + readcachesize: + description: + - Specifies the extra VDO device read cache size in megabytes. This is in addition to a system-defined minimum. Using a value with a suffix + of K, M, G, or T is optional. The default value is V(0). 1.125 MB of memory per bio thread will be used per 1 MB of read cache specified + (for example, a VDO volume configured with 4 bio threads will have a read cache memory usage overhead of 4.5 MB per 1 MB of read cache + specified). Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. + - The read cache feature is available in VDO 6.1 and older. + type: str + emulate512: + description: + - Enables 512-byte emulation mode, allowing drivers or filesystems to access the VDO volume at 512-byte granularity, instead of the default + 4096-byte granularity. + - Only recommended when a driver or filesystem requires 512-byte sector level access to a device. + - This option is only available when creating a new volume, and cannot be changed for an existing volume. + type: bool + default: false + growphysical: + description: + - Specifies whether to attempt to execute a C(growphysical) operation, if there is enough unused space on the device. A C(growphysical) + operation will be executed if there is at least 64 GB of free space, relative to the previous physical size of the affected VDO volume. + type: bool + default: false + slabsize: + description: + - The size of the increment by which the physical size of a VDO volume is grown, in megabytes (or may be issued with an LVM-style suffix + of K, M, G, or T). Must be a power of two between 128M and 32G. The default is V(2G), which supports volumes having a physical size up + to 16T. The maximum, V(32G), supports a physical size of up to 256T. This option is only available when creating a new volume, and cannot + be changed for an existing volume. + type: str + writepolicy: + description: + - Specifies the write policy of the VDO volume. + - The V(sync) mode acknowledges writes only after data is on stable storage. + - The V(async) mode acknowledges writes when data has been cached for writing to stable storage. + - The default (and highly recommended) V(auto) mode checks the storage device to determine whether it supports flushes. Devices that support + flushes will result in a VDO volume in V(async) mode, while devices that do not support flushes will run in V(sync) mode. + - Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. + type: str + choices: [async, auto, sync] + indexmem: + description: + - Specifies the amount of index memory in gigabytes. The default is V(0.25). The special decimal values V(0.25), V(0.5), and V(0.75) can + be used, as can any positive integer. This option is only available when creating a new volume, and cannot be changed for an existing + volume. + type: str + indexmode: + description: + - Specifies the index mode of the Albireo index. + - The default is V(dense), which has a deduplication window of 1 GB of index memory per 1 TB of incoming data, requiring 10 GB of index + data on persistent storage. + - The V(sparse) mode has a deduplication window of 1 GB of index memory per 10 TB of incoming data, but requires 100 GB of index data on + persistent storage. + - This option is only available when creating a new volume, and cannot be changed for an existing volume. + type: str + choices: [dense, sparse] + ackthreads: + description: + - Specifies the number of threads to use for acknowledging completion of requested VDO I/O operations. Valid values are integer values from + V(1) to V(100) (lower numbers are preferable due to overhead). The default is V(1). Existing volumes will maintain their previously configured + setting unless a different value is specified in the playbook. + type: str + biothreads: + description: + - Specifies the number of threads to use for submitting I/O operations to the storage device. Valid values are integer values from V(1) + to V(100) (lower numbers are preferable due to overhead). The default is V(4). Existing volumes will maintain their previously configured + setting unless a different value is specified in the playbook. + type: str + cputhreads: + description: + - Specifies the number of threads to use for CPU-intensive work such as hashing or compression. Valid values are integer values from V(1) + to V(100) (lower numbers are preferable due to overhead). The default is V(2). Existing volumes will maintain their previously configured + setting unless a different value is specified in the playbook. + type: str + logicalthreads: + description: + - Specifies the number of threads across which to subdivide parts of the VDO processing based on logical block addresses. Valid values are + integer values from V(1) to V(100) (lower numbers are preferable due to overhead). The default is V(1). Existing volumes will maintain + their previously configured setting unless a different value is specified in the playbook. + type: str + physicalthreads: + description: + - Specifies the number of threads across which to subdivide parts of the VDO processing based on physical block addresses. Valid values + are integer values from V(1) to V(16) (lower numbers are preferable due to overhead). The physical space used by the VDO volume must be + larger than (O(slabsize) * O(physicalthreads)). The default is V(1). Existing volumes will maintain their previously configured setting + unless a different value is specified in the playbook. + type: str + force: + description: + - When creating a volume, ignores any existing file system or VDO signature already present in the storage device. When stopping or removing + a VDO volume, first unmounts the file system stored on the device if mounted. + - B(Warning:) Since this parameter removes all safety checks it is important to make sure that all parameters provided are accurate and + intentional. + type: bool + default: false + version_added: 2.4.0 notes: - In general, the default thread configuration should be used. requirements: - PyYAML - kmod-kvdo - vdo -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create 2 TB VDO volume vdo1 on device /dev/md0 community.general.vdo: name: vdo1 @@ -301,9 +212,9 @@ EXAMPLES = r''' community.general.vdo: name: vdo1 state: absent -''' +""" -RETURN = r'''# ''' +RETURN = r"""# """ from ansible.module_utils.basic import AnsibleModule, missing_required_lib import re diff --git a/plugins/modules/vertica_configuration.py b/plugins/modules/vertica_configuration.py index 09b80df3d7..9ce2e42d15 100644 --- a/plugins/modules/vertica_configuration.py +++ b/plugins/modules/vertica_configuration.py @@ -8,14 +8,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: vertica_configuration short_description: Updates Vertica configuration parameters description: - - Updates Vertica configuration parameters. + - Updates Vertica configuration parameters. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -24,51 +23,49 @@ attributes: options: parameter: description: - - Name of the parameter to update. + - Name of the parameter to update. required: true aliases: [name] type: str value: description: - - Value of the parameter to be set. + - Value of the parameter to be set. type: str db: description: - - Name of the Vertica database. + - Name of the Vertica database. type: str cluster: description: - - Name of the Vertica cluster. + - Name of the Vertica cluster. default: localhost type: str port: description: - - Vertica cluster port to connect to. + - Vertica cluster port to connect to. default: '5433' type: str login_user: description: - - The username used to authenticate with. + - The username used to authenticate with. default: dbadmin type: str login_password: description: - - The password used to authenticate with. + - The password used to authenticate with. type: str notes: - - The default authentication assumes that you are either logging in as or sudo'ing - to the C(dbadmin) account on the host. - - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure - that C(unixODBC) and C(pyodbc) is installed on the host and properly configured. - - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) - to be added to the C(Vertica) section of either C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) - and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) - to be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). -requirements: [ 'unixODBC', 'pyodbc' ] + - The default authentication assumes that you are either logging in as or sudo'ing to the C(dbadmin) account on the host. + - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure that C(unixODBC) and C(pyodbc) is installed on the host and properly + configured. + - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) to be added to the C(Vertica) section of either + C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) to + be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). +requirements: ['unixODBC', 'pyodbc'] author: "Dariusz Owczarek (@dareko)" -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Updating load_balance_policy community.general.vertica_configuration: name=failovertostandbyafter value='8 hours' """ diff --git a/plugins/modules/vertica_info.py b/plugins/modules/vertica_info.py index 93ccc68445..bfb99552a0 100644 --- a/plugins/modules/vertica_info.py +++ b/plugins/modules/vertica_info.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: vertica_info short_description: Gathers Vertica database facts description: @@ -25,8 +24,7 @@ options: default: localhost type: str port: - description: - Database port to connect to. + description: Database port to connect to. default: '5433' type: str db: @@ -43,19 +41,17 @@ options: - The password used to authenticate with. type: str notes: - - The default authentication assumes that you are either logging in as or sudo'ing - to the C(dbadmin) account on the host. - - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure - that C(unixODBC) and C(pyodbc) are installed on the host and properly configured. - - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) - to be added to the C(Vertica) section of either C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) - and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) - to be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). -requirements: [ 'unixODBC', 'pyodbc' ] + - The default authentication assumes that you are either logging in as or sudo'ing to the C(dbadmin) account on the host. + - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure that C(unixODBC) and C(pyodbc) are installed on the host and properly + configured. + - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) to be added to the C(Vertica) section of either + C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) to + be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). +requirements: ['unixODBC', 'pyodbc'] author: "Dariusz Owczarek (@dareko)" -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Gathering vertica facts community.general.vertica_info: db=db_name register: result diff --git a/plugins/modules/vertica_role.py b/plugins/modules/vertica_role.py index a1ef40c7a5..c3e15b4b95 100644 --- a/plugins/modules/vertica_role.py +++ b/plugins/modules/vertica_role.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: vertica_role short_description: Adds or removes Vertica database roles and assigns roles to them description: @@ -64,19 +63,17 @@ options: - The password used to authenticate with. type: str notes: - - The default authentication assumes that you are either logging in as or sudo'ing - to the C(dbadmin) account on the host. - - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure - that C(unixODBC) and C(pyodbc) is installed on the host and properly configured. - - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) - to be added to the C(Vertica) section of either C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) - and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) - to be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). -requirements: [ 'unixODBC', 'pyodbc' ] + - The default authentication assumes that you are either logging in as or sudo'ing to the C(dbadmin) account on the host. + - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure that C(unixODBC) and C(pyodbc) is installed on the host and properly + configured. + - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) to be added to the C(Vertica) section of either + C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) to + be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). +requirements: ['unixODBC', 'pyodbc'] author: "Dariusz Owczarek (@dareko)" -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Creating a new vertica role community.general.vertica_role: name=role_name db=db_name state=present diff --git a/plugins/modules/vertica_schema.py b/plugins/modules/vertica_schema.py index 95e434ef3a..b9e243ec7b 100644 --- a/plugins/modules/vertica_schema.py +++ b/plugins/modules/vertica_schema.py @@ -9,17 +9,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: vertica_schema short_description: Adds or removes Vertica database schema and roles description: - - Adds or removes Vertica database schema and, optionally, roles - with schema access privileges. + - Adds or removes Vertica database schema and, optionally, roles with schema access privileges. - A schema will not be removed until all the objects have been dropped. - - In such a situation, if the module tries to remove the schema it - will fail and only remove roles created for the schema if they have - no dependencies. + - In such a situation, if the module tries to remove the schema it will fail and only remove roles created for the schema if they have no dependencies. extends_documentation_fragment: - community.general.attributes attributes: @@ -78,19 +74,17 @@ options: - The password used to authenticate with. type: str notes: - - The default authentication assumes that you are either logging in as or sudo'ing - to the C(dbadmin) account on the host. - - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure - that C(unixODBC) and C(pyodbc) is installed on the host and properly configured. - - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) - to be added to the C(Vertica) section of either C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) - and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) - to be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). -requirements: [ 'unixODBC', 'pyodbc' ] + - The default authentication assumes that you are either logging in as or sudo'ing to the C(dbadmin) account on the host. + - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure that C(unixODBC) and C(pyodbc) is installed on the host and properly + configured. + - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) to be added to the C(Vertica) section of either + C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) to + be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). +requirements: ['unixODBC', 'pyodbc'] author: "Dariusz Owczarek (@dareko)" -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Creating a new vertica schema community.general.vertica_schema: name=schema_name db=db_name state=present @@ -98,12 +92,7 @@ EXAMPLES = """ community.general.vertica_schema: name=schema_name owner=dbowner db=db_name state=present - name: Creating a new schema with roles - community.general.vertica_schema: - name=schema_name - create_roles=schema_name_all - usage_roles=schema_name_ro,schema_name_rw - db=db_name - state=present + community.general.vertica_schema: name=schema_name create_roles=schema_name_all usage_roles=schema_name_ro,schema_name_rw db=db_name state=present """ import traceback diff --git a/plugins/modules/vertica_user.py b/plugins/modules/vertica_user.py index 7a62bec44c..c73e0d54fd 100644 --- a/plugins/modules/vertica_user.py +++ b/plugins/modules/vertica_user.py @@ -8,15 +8,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: vertica_user short_description: Adds or removes Vertica database users and assigns roles description: - Adds or removes Vertica database user and, optionally, assigns roles. - A user will not be removed until all the dependencies have been dropped. - - In such a situation, if the module tries to remove the user it - will fail and only remove roles granted to the user. + - In such a situation, if the module tries to remove the user it will fail and only remove roles granted to the user. extends_documentation_fragment: - community.general.attributes attributes: @@ -42,9 +40,8 @@ options: password: description: - The user's password encrypted by the MD5 algorithm. - - The password must be generated with the format C("md5" + md5[password + username]), - resulting in a total of 35 characters. An easy way to do this is by querying - the Vertica database with select V('md5'||md5(''\)). + - The password must be generated with the format C("md5" + md5[password + username]), resulting in a total of 35 characters. An easy way + to do this is by querying the Vertica database with select V('md5'||md5(''\)). type: str expired: description: @@ -90,29 +87,22 @@ options: - The password used to authenticate with. type: str notes: - - The default authentication assumes that you are either logging in as or sudo'ing - to the C(dbadmin) account on the host. - - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure - that C(unixODBC) and C(pyodbc) is installed on the host and properly configured. - - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) - to be added to the C(Vertica) section of either C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) - and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) - to be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). -requirements: [ 'unixODBC', 'pyodbc' ] + - The default authentication assumes that you are either logging in as or sudo'ing to the C(dbadmin) account on the host. + - This module uses C(pyodbc), a Python ODBC database adapter. You must ensure that C(unixODBC) and C(pyodbc) is installed on the host and properly + configured. + - Configuring C(unixODBC) for Vertica requires C(Driver = /opt/vertica/lib64/libverticaodbc.so) to be added to the C(Vertica) section of either + C(/etc/odbcinst.ini) or C($HOME/.odbcinst.ini) and both C(ErrorMessagesPath = /opt/vertica/lib64) and C(DriverManagerEncoding = UTF-16) to + be added to the C(Driver) section of either C(/etc/vertica.ini) or C($HOME/.vertica.ini). +requirements: ['unixODBC', 'pyodbc'] author: "Dariusz Owczarek (@dareko)" -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Creating a new vertica user with password community.general.vertica_user: name=user_name password=md5 db=db_name state=present - name: Creating a new vertica user authenticated via ldap with roles assigned - community.general.vertica_user: - name=user_name - ldap=true - db=db_name - roles=schema_name_ro - state=present + community.general.vertica_user: name=user_name ldap=true db=db_name roles=schema_name_ro state=present """ import traceback diff --git a/plugins/modules/vexata_eg.py b/plugins/modules/vexata_eg.py index 457d1fa9ed..f7184d68b0 100644 --- a/plugins/modules/vexata_eg.py +++ b/plugins/modules/vexata_eg.py @@ -9,15 +9,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: vexata_eg short_description: Manage export groups on Vexata VX100 storage arrays description: - - Create or delete export groups on a Vexata VX100 array. - - An export group is a tuple of a volume group, initiator group and port - group that allows a set of volumes to be exposed to one or more hosts - through specific array ports. + - Create or delete export groups on a Vexata VX100 array. + - An export group is a tuple of a volume group, initiator group and port group that allows a set of volumes to be exposed to one or more hosts + through specific array ports. author: - Sandeep Kasargod (@vexata) attributes: @@ -33,29 +31,28 @@ options: type: str state: description: - - Creates export group when present or delete when absent. + - Creates export group when present or delete when absent. default: present - choices: [ present, absent ] + choices: [present, absent] type: str vg: description: - - Volume group name. + - Volume group name. type: str ig: description: - - Initiator group name. + - Initiator group name. type: str pg: description: - - Port group name. + - Port group name. type: str extends_documentation_fragment: -- community.general.vexata.vx100 -- community.general.attributes + - community.general.vexata.vx100 + - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Create export group named db_export. community.general.vexata_eg: name: db_export @@ -74,10 +71,10 @@ EXAMPLES = r''' array: vx100_ultra.test.com user: admin password: secret -''' +""" -RETURN = r''' -''' +RETURN = r""" +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.vexata import ( diff --git a/plugins/modules/vexata_volume.py b/plugins/modules/vexata_volume.py index 7fdfc7e5fa..29136eb31e 100644 --- a/plugins/modules/vexata_volume.py +++ b/plugins/modules/vexata_volume.py @@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: vexata_volume short_description: Manage volumes on Vexata VX100 storage arrays description: - - Create, deletes or extend volumes on a Vexata VX100 array. + - Create, deletes or extend volumes on a Vexata VX100 array. author: -- Sandeep Kasargod (@vexata) + - Sandeep Kasargod (@vexata) attributes: check_mode: support: full @@ -32,19 +31,18 @@ options: description: - Creates/Modifies volume when present or removes when absent. default: present - choices: [ present, absent ] + choices: [present, absent] type: str size: description: - Volume size in M, G, T units. M=2^20, G=2^30, T=2^40 bytes. type: str extends_documentation_fragment: -- community.general.vexata.vx100 -- community.general.attributes + - community.general.vexata.vx100 + - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Create new 2 TiB volume named foo community.general.vexata_volume: name: foo @@ -70,10 +68,10 @@ EXAMPLES = r''' array: vx100_ultra.test.com user: admin password: secret -''' +""" -RETURN = r''' -''' +RETURN = r""" +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.vexata import ( diff --git a/plugins/modules/vmadm.py b/plugins/modules/vmadm.py index 923a902bcf..148ca18b86 100644 --- a/plugins/modules/vmadm.py +++ b/plugins/modules/vmadm.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: vmadm short_description: Manage SmartOS virtual machines and zones description: @@ -27,8 +26,7 @@ options: archive_on_delete: required: false description: - - When enabled, the zone dataset will be mounted on C(/zones/archive) - upon removal. + - When enabled, the zone dataset will be mounted on C(/zones/archive) upon removal. type: bool autoboot: required: false @@ -36,7 +34,7 @@ options: - Whether or not a VM is booted when the system is rebooted. type: bool brand: - choices: [ joyent, joyent-minimal, lx, kvm, bhyve ] + choices: [joyent, joyent-minimal, lx, kvm, bhyve] default: joyent description: - Type of virtual machine. The V(bhyve) option was added in community.general 0.2.0. @@ -49,18 +47,16 @@ options: cpu_cap: required: false description: - - Sets a limit on the amount of CPU time that can be used by a VM. - Use V(0) for no cap. + - Sets a limit on the amount of CPU time that can be used by a VM. Use V(0) for no cap. type: int cpu_shares: required: false description: - - Sets a limit on the number of fair share scheduler (FSS) CPU shares for - a VM. This limit is relative to all other VMs on the system. + - Sets a limit on the number of fair share scheduler (FSS) CPU shares for a VM. This limit is relative to all other VMs on the system. type: int cpu_type: required: false - choices: [ qemu64, host ] + choices: [qemu64, host] default: qemu64 description: - Control the type of virtual CPU exposed to KVM VMs. @@ -68,8 +64,7 @@ options: customer_metadata: required: false description: - - Metadata to be set and associated with this VM, this contain customer - modifiable keys. + - Metadata to be set and associated with this VM, this contain customer modifiable keys. type: dict delegate_dataset: required: false @@ -141,14 +136,12 @@ options: internal_metadata: required: false description: - - Metadata to be set and associated with this VM, this contains operator - generated keys. + - Metadata to be set and associated with this VM, this contains operator generated keys. type: dict internal_metadata_namespace: required: false description: - - List of namespaces to be set as C(internal_metadata-only); these namespaces - will come from O(internal_metadata) rather than O(customer_metadata). + - List of namespaces to be set as C(internal_metadata-only); these namespaces will come from O(internal_metadata) rather than O(customer_metadata). type: str kernel_version: required: false @@ -163,8 +156,7 @@ options: maintain_resolvers: required: false description: - - Resolvers in C(/etc/resolv.conf) will be updated when updating - the O(resolvers) property. + - Resolvers in C(/etc/resolv.conf) will be updated when updating the O(resolvers) property. type: bool max_locked_memory: required: false @@ -189,12 +181,11 @@ options: mdata_exec_timeout: required: false description: - - Timeout in seconds (or 0 to disable) for the C(svc:/smartdc/mdata:execute) service - that runs user-scripts in the zone. + - Timeout in seconds (or 0 to disable) for the C(svc:/smartdc/mdata:execute) service that runs user-scripts in the zone. type: int name: required: false - aliases: [ alias ] + aliases: [alias] description: - Name of the VM. vmadm(1M) uses this as an optional name. type: str @@ -212,14 +203,12 @@ options: nowait: required: false description: - - Consider the provisioning complete when the VM first starts, rather than - when the VM has rebooted. + - Consider the provisioning complete when the VM first starts, rather than when the VM has rebooted. type: bool qemu_opts: required: false description: - - Additional qemu arguments for KVM guests. This overwrites the default arguments - provided by vmadm(1M) and should only be used for debugging. + - Additional qemu arguments for KVM guests. This overwrites the default arguments provided by vmadm(1M) and should only be used for debugging. type: str qemu_extra_opts: required: false @@ -245,8 +234,7 @@ options: routes: required: false description: - - Dictionary that maps destinations to gateways, these will be set as static - routes in the VM. + - Dictionary that maps destinations to gateways, these will be set as static routes in the VM. type: dict spice_opts: required: false @@ -256,19 +244,15 @@ options: spice_password: required: false description: - - Password required to connect to SPICE. By default no password is set. - Please note this can be read from the Global Zone. + - Password required to connect to SPICE. By default no password is set. Please note this can be read from the Global Zone. type: str state: - choices: [ present, running, absent, deleted, stopped, created, restarted, rebooted ] + choices: [present, running, absent, deleted, stopped, created, restarted, rebooted] default: running description: - - States for the VM to be in. Please note that V(present), V(stopped) and V(restarted) - operate on a VM that is currently provisioned. V(present) means that the VM will be - created if it was absent, and that it will be in a running state. V(absent) will - shutdown the zone before removing it. - V(stopped) means the zone will be created if it does not exist already, before shutting - it down. + - States for the VM to be in. Please note that V(present), V(stopped) and V(restarted) operate on a VM that is currently provisioned. V(present) + means that the VM will be created if it was absent, and that it will be in a running state. V(absent) will shutdown the zone before removing + it. V(stopped) means the zone will be created if it does not exist already, before shutting it down. type: str tmpfs: required: false @@ -303,20 +287,17 @@ options: vnc_password: required: false description: - - Password required to connect to VNC. By default no password is set. - Please note this can be read from the Global Zone. + - Password required to connect to VNC. By default no password is set. Please note this can be read from the Global Zone. type: str vnc_port: required: false description: - - TCP port to listen of the VNC server. Or set V(0) for random, - or V(-1) to disable. + - TCP port to listen of the VNC server. Or set V(0) for random, or V(-1) to disable. type: int zfs_data_compression: required: false description: - - Specifies compression algorithm used for this VMs data dataset. This option - only has effect on delegated datasets. + - Specifies compression algorithm used for this VMs data dataset. This option only has effect on delegated datasets. type: str zfs_data_recsize: required: false @@ -336,8 +317,7 @@ options: zfs_root_compression: required: false description: - - Specifies compression algorithm used for this VMs root dataset. This option - only has effect on the zoneroot dataset. + - Specifies compression algorithm used for this VMs root dataset. This option only has effect on the zoneroot dataset. type: str zfs_root_recsize: required: false @@ -354,9 +334,9 @@ options: description: - ZFS pool the VM's zone dataset will be created in. type: str -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create SmartOS zone community.general.vmadm: brand: joyent @@ -382,9 +362,9 @@ EXAMPLES = ''' community.general.vmadm: uuid: '*' state: stopped -''' +""" -RETURN = ''' +RETURN = r""" uuid: description: UUID of the managed VM. returned: always @@ -400,7 +380,7 @@ state: returned: success type: str sample: 'running' -''' +""" import json import os diff --git a/plugins/modules/wakeonlan.py b/plugins/modules/wakeonlan.py index 6d7e094527..235be741a7 100644 --- a/plugins/modules/wakeonlan.py +++ b/plugins/modules/wakeonlan.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: wakeonlan short_description: Send a magic Wake-on-LAN (WoL) broadcast packet description: @@ -25,17 +24,17 @@ attributes: options: mac: description: - - MAC address to send Wake-on-LAN broadcast packet for. + - MAC address to send Wake-on-LAN broadcast packet for. required: true type: str broadcast: description: - - Network broadcast address to use for broadcasting magic Wake-on-LAN packet. + - Network broadcast address to use for broadcasting magic Wake-on-LAN packet. default: 255.255.255.255 type: str port: description: - - UDP port to use for magic Wake-on-LAN packet. + - UDP port to use for magic Wake-on-LAN packet. default: 7 type: int todo: @@ -43,16 +42,16 @@ todo: - Enable check-mode support (when we have arping support) - Does not have SecureOn password support notes: - - This module sends a magic packet, without knowing whether it worked - - Only works if the target system was properly configured for Wake-on-LAN (in the BIOS and/or the OS) + - This module sends a magic packet, without knowing whether it worked. + - Only works if the target system was properly configured for Wake-on-LAN (in the BIOS and/or the OS). - Some BIOSes have a different (configurable) Wake-on-LAN boot order (i.e. PXE first). seealso: -- module: community.windows.win_wakeonlan + - module: community.windows.win_wakeonlan author: -- Dag Wieers (@dagwieers) -''' + - Dag Wieers (@dagwieers) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Send a magic Wake-on-LAN packet to 00:00:5E:00:53:66 community.general.wakeonlan: mac: '00:00:5E:00:53:66' @@ -63,11 +62,11 @@ EXAMPLES = r''' mac: 00:00:5E:00:53:66 port: 9 delegate_to: localhost -''' +""" -RETURN = r''' +RETURN = r""" # Default return values -''' +""" import socket import struct import traceback diff --git a/plugins/modules/wdc_redfish_command.py b/plugins/modules/wdc_redfish_command.py index 93c4811afe..680bd4b3f9 100644 --- a/plugins/modules/wdc_redfish_command.py +++ b/plugins/modules/wdc_redfish_command.py @@ -8,14 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: wdc_redfish_command short_description: Manages WDC UltraStar Data102 Out-Of-Band controllers using Redfish APIs version_added: 5.4.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. - Manages OOB controller firmware. For example, Firmware Activate, Update and Activate. extends_documentation_fragment: - community.general.attributes @@ -38,11 +36,11 @@ options: elements: str baseuri: description: - - Base URI of OOB controller. Must include this or O(ioms). + - Base URI of OOB controller. Must include this or O(ioms). type: str ioms: description: - - List of IOM FQDNs for the enclosure. Must include this or O(baseuri). + - List of IOM FQDNs for the enclosure. Must include this or O(baseuri). type: list elements: str username: @@ -90,14 +88,12 @@ options: - The password for retrieving the update image. type: str notes: - - In the inventory, you can specify baseuri or ioms. See the EXAMPLES section. - - ioms is a list of FQDNs for the enclosure's IOMs. - - + - In the inventory, you can specify baseuri or ioms. See the EXAMPLES section. + - Ioms is a list of FQDNs for the enclosure's IOMs. author: Mike Moerk (@mikemoerk) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Firmware Activate (required after SimpleUpdate to apply the new firmware) community.general.wdc_redfish_command: category: Update @@ -188,16 +184,15 @@ EXAMPLES = ''' category: Chassis resource_id: Enclosure command: PowerModeNormal +""" -''' - -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_collections.community.general.plugins.module_utils.wdc_redfish_utils import WdcRedfishUtils from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/wdc_redfish_info.py b/plugins/modules/wdc_redfish_info.py index 03ae67fcfe..caaa9c7fd9 100644 --- a/plugins/modules/wdc_redfish_info.py +++ b/plugins/modules/wdc_redfish_info.py @@ -8,14 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: wdc_redfish_info short_description: Manages WDC UltraStar Data102 Out-Of-Band controllers using Redfish APIs version_added: 5.4.0 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. extends_documentation_fragment: - community.general.attributes - community.general.attributes.info_module @@ -33,11 +31,11 @@ options: elements: str baseuri: description: - - Base URI of OOB controller. Must include this or O(ioms). + - Base URI of OOB controller. Must include this or O(ioms). type: str ioms: description: - - List of IOM FQDNs for the enclosure. Must include this or O(baseuri). + - List of IOM FQDNs for the enclosure. Must include this or O(baseuri). type: list elements: str username: @@ -59,13 +57,12 @@ options: type: int notes: - - In the inventory, you can specify baseuri or ioms. See the EXAMPLES section. - - ioms is a list of FQDNs for the enclosure's IOMs. - + - In the inventory, you can specify baseuri or ioms. See the EXAMPLES section. + - Ioms is a list of FQDNs for the enclosure's IOMs. author: Mike Moerk (@mikemoerk) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get Simple Update Status with individual IOMs specified community.general.wdc_redfish_info: category: Update @@ -93,30 +90,30 @@ EXAMPLES = ''' - name: Print fetched information ansible.builtin.debug: msg: "{{ result.redfish_facts.simple_update_status.entries | to_nice_json }}" -''' +""" -RETURN = ''' +RETURN = r""" Description: - description: Firmware update status description. - returned: always - type: str - sample: Ready for FW update + description: Firmware update status description. + returned: always + type: str + sample: Ready for FW update ErrorCode: - description: Numeric error code for firmware update status. Non-zero indicates an error condition. - returned: always - type: int - sample: 0 + description: Numeric error code for firmware update status. Non-zero indicates an error condition. + returned: always + type: int + sample: 0 EstimatedRemainingMinutes: - description: Estimated number of minutes remaining in firmware update operation. - returned: always - type: int - sample: 20 + description: Estimated number of minutes remaining in firmware update operation. + returned: always + type: int + sample: 20 StatusCode: - description: Firmware update status code. - returned: always - type: int - sample: 2 -''' + description: Firmware update status code. + returned: always + type: int + sample: 2 +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.common.text.converters import to_native From 97ea891377c4becf847917b42b356d27b6c629ed Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 12:26:00 +0100 Subject: [PATCH 074/302] [PR #9307/e809a254 backport][stable-10] zypper: adjust docs (#9327) zypper: adjust docs (#9307) * adjust docs * Update plugins/modules/zypper.py Co-authored-by: Felix Fontein * Update plugins/modules/zypper.py Co-authored-by: Felix Fontein * Update plugins/modules/zypper_repository.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit e809a2548653f3904b346b51ac549872e53bd771) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/zypper.py | 252 +++++++++++----------- plugins/modules/zypper_repository.py | 145 ++++++------- plugins/modules/zypper_repository_info.py | 97 ++++----- 3 files changed, 242 insertions(+), 252 deletions(-) diff --git a/plugins/modules/zypper.py b/plugins/modules/zypper.py index fae859fe74..ac5b6657ba 100644 --- a/plugins/modules/zypper.py +++ b/plugins/modules/zypper.py @@ -18,143 +18,141 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: zypper author: - - "Patrick Callahan (@dirtyharrycallahan)" - - "Alexander Gubin (@alxgu)" - - "Thomas O'Donnell (@andytom)" - - "Robin Roth (@robinro)" - - "Andrii Radyk (@AnderEnder)" + - "Patrick Callahan (@dirtyharrycallahan)" + - "Alexander Gubin (@alxgu)" + - "Thomas O'Donnell (@andytom)" + - "Robin Roth (@robinro)" + - "Andrii Radyk (@AnderEnder)" short_description: Manage packages on SUSE and openSUSE description: - - Manage packages on SUSE and openSUSE using the zypper and rpm tools. - - Also supports transactional updates, by running zypper inside C(/sbin/transactional-update --continue --drop-if-no-change --quiet run). + - Manage packages on SUSE and openSUSE using the zypper and rpm tools. + - Also supports transactional updates, by running zypper inside C(/sbin/transactional-update --continue --drop-if-no-change --quiet run). extends_documentation_fragment: - - community.general.attributes - - community.general.attributes + - 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: - - Package name V(name) or package specifier or a list of either. - - Can include a version like V(name=1.0), V(name>3.4) or V(name<=2.7). If a version is given, V(oldpackage) is implied and zypper is allowed to - update the package within the version range given. - - You can also pass a url or a local path to a rpm file. - - When using O(state=latest), this can be '*', which updates all installed packages. - required: true - aliases: [ 'pkg' ] - 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. - V(dist-upgrade) will make sure the latest version of all installed packages from all enabled repositories is installed. - - When using V(dist-upgrade), O(name) should be V('*'). - required: false - choices: [ present, latest, absent, dist-upgrade, installed, removed ] - default: "present" - type: str - type: - description: - - The type of package to be operated on. - required: false - choices: [ package, patch, pattern, product, srcpackage, application ] - default: "package" - type: str - extra_args_precommand: - required: false - description: - - Add additional global target options to C(zypper). - - Options should be supplied in a single line as if given in the command line. - type: str - disable_gpg_check: - description: - - Whether to disable to GPG signature checking of the package - signature being installed. Has an effect only if O(state) is - V(present) or V(latest). - required: false - default: false - type: bool - disable_recommends: - description: - - Corresponds to the C(--no-recommends) option for I(zypper). Default behavior (V(true)) modifies zypper's default behavior; V(false) does - install recommended packages. - required: false - default: true - type: bool - force: - description: - - Adds C(--force) option to I(zypper). Allows to downgrade packages and change vendor or architecture. - required: false - default: false - type: bool - force_resolution: - description: - - Adds C(--force-resolution) option to I(zypper). Allows to (un)install packages with conflicting requirements (resolver will choose a solution). - required: false - default: false - type: bool - version_added: '0.2.0' - update_cache: - description: - - Run the equivalent of C(zypper refresh) before the operation. Disabled in check mode. - required: false - default: false - type: bool - aliases: [ "refresh" ] - oldpackage: - description: - - Adds C(--oldpackage) option to I(zypper). Allows to downgrade packages with less side-effects than force. This is implied as soon as a - version is specified as part of the package name. - required: false - default: false - type: bool - extra_args: - required: false - description: - - Add additional options to C(zypper) command. - - Options should be supplied in a single line as if given in the command line. - type: str - allow_vendor_change: - type: bool - required: false - default: false - description: - - Adds C(--allow_vendor_change) option to I(zypper) dist-upgrade command. - version_added: '0.2.0' - replacefiles: - type: bool - required: false - default: false - description: - - Adds C(--replacefiles) option to I(zypper) install/update command. - version_added: '0.2.0' - clean_deps: - type: bool - required: false - default: false - description: - - Adds C(--clean-deps) option to I(zypper) remove command. - version_added: '4.6.0' + name: + description: + - Package name V(name) or package specifier or a list of either. + - Can include a version like V(name=1.0), V(name>3.4) or V(name<=2.7). If a version is given, V(oldpackage) is implied and zypper is allowed + to update the package within the version range given. + - You can also pass a url or a local path to a rpm file. + - When using O(state=latest), this can be V(*), which updates all installed packages. + required: true + aliases: ['pkg'] + 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. + - V(dist-upgrade) will make sure the latest version of all installed packages from all enabled repositories is installed. + - When using V(dist-upgrade), O(name) should be V(*). + required: false + choices: [present, latest, absent, dist-upgrade, installed, removed] + default: "present" + type: str + type: + description: + - The type of package to be operated on. + required: false + choices: [package, patch, pattern, product, srcpackage, application] + default: "package" + type: str + extra_args_precommand: + required: false + description: + - Add additional global target options to C(zypper). + - Options should be supplied in a single line as if given in the command line. + type: str + disable_gpg_check: + description: + - Whether to disable to GPG signature checking of the package signature being installed. Has an effect only if O(state) is V(present) or + V(latest). + required: false + default: false + type: bool + disable_recommends: + description: + - Corresponds to the C(--no-recommends) option for I(zypper). Default behavior (V(true)) modifies zypper's default behavior; V(false) does + install recommended packages. + required: false + default: true + type: bool + force: + description: + - Adds C(--force) option to I(zypper). Allows to downgrade packages and change vendor or architecture. + required: false + default: false + type: bool + force_resolution: + description: + - Adds C(--force-resolution) option to I(zypper). Allows to (un)install packages with conflicting requirements (resolver will choose a solution). + required: false + default: false + type: bool + version_added: '0.2.0' + update_cache: + description: + - Run the equivalent of C(zypper refresh) before the operation. Disabled in check mode. + required: false + default: false + type: bool + aliases: ["refresh"] + oldpackage: + description: + - Adds C(--oldpackage) option to I(zypper). Allows to downgrade packages with less side-effects than force. This is implied as soon as a + version is specified as part of the package name. + required: false + default: false + type: bool + extra_args: + required: false + description: + - Add additional options to C(zypper) command. + - Options should be supplied in a single line as if given in the command line. + type: str + allow_vendor_change: + type: bool + required: false + default: false + description: + - Adds C(--allow_vendor_change) option to I(zypper) dist-upgrade command. + version_added: '0.2.0' + replacefiles: + type: bool + required: false + default: false + description: + - Adds C(--replacefiles) option to I(zypper) install/update command. + version_added: '0.2.0' + clean_deps: + type: bool + required: false + default: false + description: + - Adds C(--clean-deps) option to I(zypper) remove command. + version_added: '4.6.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. # informational: requirements for nodes requirements: - - "zypper >= 1.0 # included in openSUSE >= 11.1 or SUSE Linux Enterprise Server/Desktop >= 11.0" - - python-xml - - rpm -''' + - "zypper >= 1.0 # included in openSUSE >= 11.1 or SUSE Linux Enterprise Server/Desktop >= 11.0" + - python-xml + - rpm +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install nmap community.general.zypper: name: nmap @@ -228,7 +226,7 @@ EXAMPLES = ''' state: present environment: ZYPP_LOCK_TIMEOUT: 20 -''' +""" import os.path import xml diff --git a/plugins/modules/zypper_repository.py b/plugins/modules/zypper_repository.py index 5a0356cc37..18f9ff0824 100644 --- a/plugins/modules/zypper_repository.py +++ b/plugins/modules/zypper_repository.py @@ -11,91 +11,88 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: zypper_repository author: "Matthias Vogelgesang (@matze)" short_description: Add and remove Zypper repositories description: - - Add or remove Zypper repositories on SUSE and openSUSE + - Add or remove Zypper repositories on SUSE and openSUSE. 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 name for the repository. Not required when adding repofiles. - type: str - repo: - description: - - URI of the repository or .repo file. Required when state=present. - type: str - state: - description: - - A source string state. - choices: [ "absent", "present" ] - default: "present" - type: str + name: description: - description: - - A description of the repository - type: str - disable_gpg_check: - description: - - Whether to disable GPG signature checking of - all packages. Has an effect only if O(state=present). - - Needs zypper version >= 1.6.2. - type: bool - default: false - autorefresh: - description: - - Enable autorefresh of the repository. - type: bool - default: true - aliases: [ "refresh" ] - priority: - description: - - Set priority of repository. Packages will always be installed - from the repository with the smallest priority number. - - Needs zypper version >= 1.12.25. - type: int - overwrite_multiple: - description: - - Overwrite multiple repository entries, if repositories with both name and - URL already exist. - type: bool - default: false - auto_import_keys: - description: - - Automatically import the gpg signing key of the new or changed repository. - - Has an effect only if O(state=present). Has no effect on existing (unchanged) repositories or in combination with O(state=absent). - - Implies runrefresh. - - Only works with C(.repo) files if `name` is given explicitly. - type: bool - default: false - runrefresh: - description: - - Refresh the package list of the given repository. - - Can be used with repo=* to refresh all repositories. - type: bool - default: false - enabled: - description: - - Set repository to enabled (or disabled). - type: bool - default: true + - A name for the repository. Not required when adding repofiles. + type: str + repo: + description: + - URI of the repository or full path of a C(.repo) file. Required when O(state=present). + type: str + state: + description: + - Whether the repository should exist or not. + - A source string state. + choices: ["absent", "present"] + default: "present" + type: str + description: + description: + - A description of the repository. + type: str + disable_gpg_check: + description: + - Whether to disable GPG signature checking of all packages. Has an effect only if O(state=present). + - Needs C(zypper) version >= 1.6.2. + type: bool + default: false + autorefresh: + description: + - Enable autorefresh of the repository. + type: bool + default: true + aliases: ["refresh"] + priority: + description: + - Set priority of repository. Packages will always be installed from the repository with the smallest priority number. + - Needs C(zypper) version >= 1.12.25. + type: int + overwrite_multiple: + description: + - Overwrite multiple repository entries, if repositories with both name and URL already exist. + type: bool + default: false + auto_import_keys: + description: + - Automatically import the gpg signing key of the new or changed repository. + - Has an effect only if O(state=present). Has no effect on existing (unchanged) repositories or in combination with O(state=absent). + - Implies O(runrefresh). + - Only works with C(.repo) files if O(name) is given explicitly. + type: bool + default: false + runrefresh: + description: + - Refresh the package list of the given repository. + - Can be used with O(repo=*) to refresh all repositories. + type: bool + default: false + enabled: + description: + - Set repository to enabled (or disabled). + type: bool + default: true requirements: - - "zypper >= 1.0 # included in openSUSE >= 11.1 or SUSE Linux Enterprise Server/Desktop >= 11.0" - - python-xml -''' + - "zypper >= 1.0 # included in openSUSE >= 11.1 or SUSE Linux Enterprise Server/Desktop >= 11.0" + - python-xml +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Add NVIDIA repository for graphics drivers community.general.zypper_repository: name: nvidia-repo @@ -128,7 +125,7 @@ EXAMPLES = ''' name: my_ci_repo state: present runrefresh: true -''' +""" import traceback diff --git a/plugins/modules/zypper_repository_info.py b/plugins/modules/zypper_repository_info.py index dab4b9bbe5..9512d32eed 100644 --- a/plugins/modules/zypper_repository_info.py +++ b/plugins/modules/zypper_repository_info.py @@ -10,72 +10,67 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: zypper_repository_info author: "Tobias Zeuch (@TobiasZeuch181)" version_added: 10.0.0 short_description: List Zypper repositories description: - - List Zypper repositories on SUSE and openSUSE. + - List Zypper repositories on SUSE and openSUSE. extends_documentation_fragment: - - community.general.attributes - - community.general.attributes.info_module + - community.general.attributes + - community.general.attributes.info_module requirements: - - "zypper >= 1.0 (included in openSUSE >= 11.1 or SUSE Linux Enterprise Server/Desktop >= 11.0)" - - python-xml + - "zypper >= 1.0 (included in openSUSE >= 11.1 or SUSE Linux Enterprise Server/Desktop >= 11.0)" + - python-xml notes: - - "For info about packages, use the module M(ansible.builtin.package_facts)." -''' + - "For info about packages, use the module M(ansible.builtin.package_facts)." +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List registered repositories and store in variable repositories community.general.zypper_repository_info: {} register: repodatalist -''' +""" -RETURN = ''' +RETURN = r""" repodatalist: - description: - - A list of repository descriptions like it is returned by the command C(zypper repos). - type: list - returned: always - elements: dict - contains: - alias: - description: The alias of the repository. - type: str - autorefresh: - description: Indicates, if autorefresh is enabled on the repository. - type: int - enabled: - description: indicates, if the repository is enabled - type: int - gpgcheck: - description: indicates, if the GPG signature of the repository meta data is checked - type: int - name: - description: the name of the repository - type: str - priority: - description: the priority of the repository - type: int - url: - description: The URL of the repository on the internet. - type: str - sample: [ - { - "alias": "SLE-Product-SLES", - "autorefresh": "1", - "enabled": "1", - "gpgcheck": "1", - "name": "SLE-Product-SLES", - "priority": "99", - "url": "http://repo:50000/repo/SUSE/Products/SLE-Product-SLES/15-SP2/x86_64/product" - } - ] -''' + description: + - A list of repository descriptions like it is returned by the command C(zypper repos). + type: list + returned: always + elements: dict + contains: + alias: + description: The alias of the repository. + type: str + sample: "SLE-Product-SLES" + autorefresh: + description: Indicates, if autorefresh is enabled on the repository. + type: int + sample: "1" + enabled: + description: Indicates, if the repository is enabled. + type: int + sample: "1" + gpgcheck: + description: Indicates, if the GPG signature of the repository meta data is checked. + type: int + sample: "1" + name: + description: The name of the repository. + type: str + sample: "SLE-Product-SLES" + priority: + description: The priority of the repository. + type: int + sample: "99" + url: + description: The URL of the repository on the internet. + type: str + sample: "http://repo:50000/repo/SUSE/Products/SLE-Product-SLES/15-SP2/x86_64/product" +""" from ansible_collections.community.general.plugins.module_utils import deps From eec5c82a558461c5d9d7c30617cb25f0b76c5d09 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 12:28:24 +0100 Subject: [PATCH 075/302] [PR #9334/da51594f backport][stable-10] qubes connection plugin: fix display stmt (#9337) qubes connection plugin: fix display stmt (#9334) * qubes connection plugin: fix display stmt * add changelog frag (cherry picked from commit da51594f9d626f0b3b0e62fcf2c3e0f857195eec) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9334-qubes-conn.yml | 2 ++ plugins/connection/qubes.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9334-qubes-conn.yml diff --git a/changelogs/fragments/9334-qubes-conn.yml b/changelogs/fragments/9334-qubes-conn.yml new file mode 100644 index 0000000000..3faa8d7981 --- /dev/null +++ b/changelogs/fragments/9334-qubes-conn.yml @@ -0,0 +1,2 @@ +bugfixes: + - qubes connection plugin - fix the printing of debug information (https://github.com/ansible-collections/community.general/pull/9334). diff --git a/plugins/connection/qubes.py b/plugins/connection/qubes.py index b54eeb3a84..8860fbb777 100644 --- a/plugins/connection/qubes.py +++ b/plugins/connection/qubes.py @@ -118,7 +118,7 @@ class Connection(ConnectionBase): rc, stdout, stderr = self._qubes(cmd) - display.vvvvv("STDOUT %r STDERR %r" % (stderr, stderr)) + display.vvvvv("STDOUT %r STDERR %r" % (stdout, stderr)) return rc, stdout, stderr def put_file(self, in_path, out_path): From 434032080e47ce6aeedd1ed20f91cabc917adb57 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 19:19:44 +0100 Subject: [PATCH 076/302] [PR #9284/28f36ae2 backport][stable-10] Add action group for keycloak (#9340) Add action group for keycloak (#9284) * Create group for keycloak This will allows keycloak authentication details to be set as a module_defaults rather than repeated on each task * add documentation to keycloak modules to note creation of action_group * add changelog for keycloak action_group creation * exclude keycloak_realm_info from action group, as it does not share same set of base parameters * fix formatting on changelog entry for adding Keycloak action group Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 28f36ae25c233d294e266c250e8cf34e02445857) Co-authored-by: Chris Northwood --- .../9284-add-keycloak-action-group.yml | 2 ++ meta/runtime.yml | 28 +++++++++++++++++++ plugins/doc_fragments/keycloak.py | 10 +++++++ plugins/modules/keycloak_authentication.py | 3 ++ ...eycloak_authentication_required_actions.py | 3 ++ .../keycloak_authz_authorization_scope.py | 3 ++ .../modules/keycloak_authz_custom_policy.py | 3 ++ plugins/modules/keycloak_authz_permission.py | 3 ++ .../modules/keycloak_authz_permission_info.py | 5 ++++ plugins/modules/keycloak_client.py | 3 ++ .../modules/keycloak_client_rolemapping.py | 3 ++ plugins/modules/keycloak_client_rolescope.py | 3 ++ plugins/modules/keycloak_clientscope.py | 3 ++ plugins/modules/keycloak_clientscope_type.py | 3 ++ plugins/modules/keycloak_clientsecret_info.py | 5 ++++ .../keycloak_clientsecret_regenerate.py | 3 ++ plugins/modules/keycloak_clienttemplate.py | 3 ++ plugins/modules/keycloak_component.py | 3 ++ plugins/modules/keycloak_component_info.py | 6 ++++ plugins/modules/keycloak_group.py | 3 ++ plugins/modules/keycloak_identity_provider.py | 3 ++ plugins/modules/keycloak_realm.py | 3 ++ plugins/modules/keycloak_realm_key.py | 3 ++ .../keycloak_realm_keys_metadata_info.py | 5 ++++ plugins/modules/keycloak_realm_rolemapping.py | 3 ++ plugins/modules/keycloak_role.py | 3 ++ plugins/modules/keycloak_user.py | 3 ++ plugins/modules/keycloak_user_federation.py | 3 ++ plugins/modules/keycloak_user_rolemapping.py | 3 ++ plugins/modules/keycloak_userprofile.py | 3 ++ 30 files changed, 130 insertions(+) create mode 100644 changelogs/fragments/9284-add-keycloak-action-group.yml diff --git a/changelogs/fragments/9284-add-keycloak-action-group.yml b/changelogs/fragments/9284-add-keycloak-action-group.yml new file mode 100644 index 0000000000..b25c370346 --- /dev/null +++ b/changelogs/fragments/9284-add-keycloak-action-group.yml @@ -0,0 +1,2 @@ +minor_changes: + - 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). diff --git a/meta/runtime.yml b/meta/runtime.yml index 387ab0f22b..5b3bb0b6f0 100644 --- a/meta/runtime.yml +++ b/meta/runtime.yml @@ -32,6 +32,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: diff --git a/plugins/doc_fragments/keycloak.py b/plugins/doc_fragments/keycloak.py index 9b21ce52c9..b64a23b088 100644 --- a/plugins/doc_fragments/keycloak.py +++ b/plugins/doc_fragments/keycloak.py @@ -77,3 +77,13 @@ options: 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/modules/keycloak_authentication.py b/plugins/modules/keycloak_authentication.py index 5945890bb7..fa2ae1e974 100644 --- a/plugins/modules/keycloak_authentication.py +++ b/plugins/modules/keycloak_authentication.py @@ -24,6 +24,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: realm: @@ -102,6 +104,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_authentication_required_actions.py b/plugins/modules/keycloak_authentication_required_actions.py index 5ffbd2033c..c992e05d2d 100644 --- a/plugins/modules/keycloak_authentication_required_actions.py +++ b/plugins/modules/keycloak_authentication_required_actions.py @@ -26,6 +26,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: realm: @@ -77,6 +79,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_authz_authorization_scope.py b/plugins/modules/keycloak_authz_authorization_scope.py index 5eef9ac765..146a37bf51 100644 --- a/plugins/modules/keycloak_authz_authorization_scope.py +++ b/plugins/modules/keycloak_authz_authorization_scope.py @@ -35,6 +35,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -74,6 +76,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_authz_custom_policy.py b/plugins/modules/keycloak_authz_custom_policy.py index 8363c252e2..2205a184f5 100644 --- a/plugins/modules/keycloak_authz_custom_policy.py +++ b/plugins/modules/keycloak_authz_custom_policy.py @@ -36,6 +36,8 @@ attributes: support: full diff_mode: support: none + action_group: + version_added: 10.2.0 options: state: @@ -71,6 +73,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_authz_permission.py b/plugins/modules/keycloak_authz_permission.py index ef81fb8c31..08b5ae6295 100644 --- a/plugins/modules/keycloak_authz_permission.py +++ b/plugins/modules/keycloak_authz_permission.py @@ -43,6 +43,8 @@ attributes: support: full diff_mode: support: none + action_group: + version_added: 10.2.0 options: state: @@ -121,6 +123,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_authz_permission_info.py b/plugins/modules/keycloak_authz_permission_info.py index 8b4e96b416..4c1a6ddf66 100644 --- a/plugins/modules/keycloak_authz_permission_info.py +++ b/plugins/modules/keycloak_authz_permission_info.py @@ -31,6 +31,10 @@ description: 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: @@ -51,6 +55,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes - community.general.attributes.info_module diff --git a/plugins/modules/keycloak_client.py b/plugins/modules/keycloak_client.py index 62015bc79f..c65105ec23 100644 --- a/plugins/modules/keycloak_client.py +++ b/plugins/modules/keycloak_client.py @@ -35,6 +35,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -595,6 +597,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_client_rolemapping.py b/plugins/modules/keycloak_client_rolemapping.py index be419904a7..ebc60b9fd0 100644 --- a/plugins/modules/keycloak_client_rolemapping.py +++ b/plugins/modules/keycloak_client_rolemapping.py @@ -38,6 +38,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -130,6 +132,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_client_rolescope.py b/plugins/modules/keycloak_client_rolescope.py index cca72f0ddd..cd4f0fa80e 100644 --- a/plugins/modules/keycloak_client_rolescope.py +++ b/plugins/modules/keycloak_client_rolescope.py @@ -34,6 +34,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -76,6 +78,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_clientscope.py b/plugins/modules/keycloak_clientscope.py index 35ac3d9500..87437b6df0 100644 --- a/plugins/modules/keycloak_clientscope.py +++ b/plugins/modules/keycloak_clientscope.py @@ -38,6 +38,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -158,6 +160,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_clientscope_type.py b/plugins/modules/keycloak_clientscope_type.py index 1fb9a0813c..d95ab0b44d 100644 --- a/plugins/modules/keycloak_clientscope_type.py +++ b/plugins/modules/keycloak_clientscope_type.py @@ -30,6 +30,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: realm: @@ -59,6 +61,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_clientsecret_info.py b/plugins/modules/keycloak_clientsecret_info.py index c772620351..58786a5364 100644 --- a/plugins/modules/keycloak_clientsecret_info.py +++ b/plugins/modules/keycloak_clientsecret_info.py @@ -32,6 +32,10 @@ description: - "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: type: str @@ -57,6 +61,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes - community.general.attributes.info_module diff --git a/plugins/modules/keycloak_clientsecret_regenerate.py b/plugins/modules/keycloak_clientsecret_regenerate.py index 7e8b295433..fc279f6a9d 100644 --- a/plugins/modules/keycloak_clientsecret_regenerate.py +++ b/plugins/modules/keycloak_clientsecret_regenerate.py @@ -37,6 +37,8 @@ attributes: support: full diff_mode: support: none + action_group: + version_added: 10.2.0 options: realm: @@ -63,6 +65,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_clienttemplate.py b/plugins/modules/keycloak_clienttemplate.py index 7bffb5cbb6..63bb32f972 100644 --- a/plugins/modules/keycloak_clienttemplate.py +++ b/plugins/modules/keycloak_clienttemplate.py @@ -33,6 +33,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -168,6 +170,7 @@ notes: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_component.py b/plugins/modules/keycloak_component.py index 375953c3e8..6c345700ae 100644 --- a/plugins/modules/keycloak_component.py +++ b/plugins/modules/keycloak_component.py @@ -32,6 +32,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -72,6 +74,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_component_info.py b/plugins/modules/keycloak_component_info.py index a788735d98..cc0c4d31d9 100644 --- a/plugins/modules/keycloak_component_info.py +++ b/plugins/modules/keycloak_component_info.py @@ -18,6 +18,11 @@ version_added: 8.2.0 description: - This module retrive information on component from Keycloak. + +attributes: + action_group: + version_added: 10.2.0 + options: realm: description: @@ -46,6 +51,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes - community.general.attributes.info_module diff --git a/plugins/modules/keycloak_group.py b/plugins/modules/keycloak_group.py index 5398a4b5d0..24564f2d4d 100644 --- a/plugins/modules/keycloak_group.py +++ b/plugins/modules/keycloak_group.py @@ -36,6 +36,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -114,6 +116,7 @@ notes: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_identity_provider.py b/plugins/modules/keycloak_identity_provider.py index 609673653b..0ef67ee385 100644 --- a/plugins/modules/keycloak_identity_provider.py +++ b/plugins/modules/keycloak_identity_provider.py @@ -31,6 +31,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -277,6 +279,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_realm.py b/plugins/modules/keycloak_realm.py index 747acf3081..e190e7ad7b 100644 --- a/plugins/modules/keycloak_realm.py +++ b/plugins/modules/keycloak_realm.py @@ -37,6 +37,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -516,6 +518,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_realm_key.py b/plugins/modules/keycloak_realm_key.py index edc8a6068e..159fb77d4b 100644 --- a/plugins/modules/keycloak_realm_key.py +++ b/plugins/modules/keycloak_realm_key.py @@ -43,6 +43,8 @@ attributes: support: full diff_mode: support: partial + action_group: + version_added: 10.2.0 options: state: @@ -138,6 +140,7 @@ notes: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_realm_keys_metadata_info.py b/plugins/modules/keycloak_realm_keys_metadata_info.py index ef4048b891..9b490fad58 100644 --- a/plugins/modules/keycloak_realm_keys_metadata_info.py +++ b/plugins/modules/keycloak_realm_keys_metadata_info.py @@ -23,6 +23,10 @@ description: - 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 @@ -32,6 +36,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes - community.general.attributes.info_module diff --git a/plugins/modules/keycloak_realm_rolemapping.py b/plugins/modules/keycloak_realm_rolemapping.py index 693cf9894a..0c24b2f949 100644 --- a/plugins/modules/keycloak_realm_rolemapping.py +++ b/plugins/modules/keycloak_realm_rolemapping.py @@ -40,6 +40,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -118,6 +120,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_role.py b/plugins/modules/keycloak_role.py index f3e01483f8..3978260189 100644 --- a/plugins/modules/keycloak_role.py +++ b/plugins/modules/keycloak_role.py @@ -35,6 +35,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -116,6 +118,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_user.py b/plugins/modules/keycloak_user.py index 1aeff0da5f..cb63707402 100644 --- a/plugins/modules/keycloak_user.py +++ b/plugins/modules/keycloak_user.py @@ -212,12 +212,15 @@ options: default: false extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes attributes: 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. author: diff --git a/plugins/modules/keycloak_user_federation.py b/plugins/modules/keycloak_user_federation.py index 215aa7f4ca..4533fa800d 100644 --- a/plugins/modules/keycloak_user_federation.py +++ b/plugins/modules/keycloak_user_federation.py @@ -31,6 +31,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -513,6 +515,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_user_rolemapping.py b/plugins/modules/keycloak_user_rolemapping.py index 59727a346e..40e3b38d5c 100644 --- a/plugins/modules/keycloak_user_rolemapping.py +++ b/plugins/modules/keycloak_user_rolemapping.py @@ -37,6 +37,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -110,6 +112,7 @@ options: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: diff --git a/plugins/modules/keycloak_userprofile.py b/plugins/modules/keycloak_userprofile.py index 57e1c42e96..ba9cae8554 100644 --- a/plugins/modules/keycloak_userprofile.py +++ b/plugins/modules/keycloak_userprofile.py @@ -28,6 +28,8 @@ attributes: support: full diff_mode: support: full + action_group: + version_added: 10.2.0 options: state: @@ -270,6 +272,7 @@ notes: extends_documentation_fragment: - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak - community.general.attributes author: From 474c7a7240b8b1b4c7f05863f1cd7d08592aee6c Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 19:20:19 +0100 Subject: [PATCH 077/302] [PR #9308/f9bfe4e4 backport][stable-10] x*: adjust docs (#9342) x*: adjust docs (#9308) * adjust docs * Update plugins/modules/xml.py Co-authored-by: Felix Fontein * fix capitalisation * add markup to references of the xe command (xenserver) * add missing markup * Update plugins/modules/xml.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit f9bfe4e4a6838c7a9a7aedde72be32611fcff7f6) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/xattr.py | 33 +- plugins/modules/xbps.py | 158 +++-- plugins/modules/xcc_redfish_command.py | 325 +++++----- plugins/modules/xenserver_facts.py | 11 +- plugins/modules/xenserver_guest.py | 585 +++++++++--------- plugins/modules/xenserver_guest_info.py | 62 +- plugins/modules/xenserver_guest_powerstate.py | 79 ++- plugins/modules/xfconf.py | 97 ++- plugins/modules/xfconf_info.py | 91 ++- plugins/modules/xfs_quota.py | 52 +- plugins/modules/xml.py | 197 +++--- 11 files changed, 827 insertions(+), 863 deletions(-) diff --git a/plugins/modules/xattr.py b/plugins/modules/xattr.py index 7a5f3b431f..11b036ff66 100644 --- a/plugins/modules/xattr.py +++ b/plugins/modules/xattr.py @@ -8,14 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: xattr short_description: Manage user defined extended attributes description: - Manages filesystem user defined extended attributes. - - Requires that extended attributes are enabled on the target filesystem - and that the setfattr/getfattr utilities are present. + - Requires that extended attributes are enabled on the target filesystem and that the C(setfattr)/C(getfattr) utilities are present. extends_documentation_fragment: - community.general.attributes attributes: @@ -29,7 +27,7 @@ options: - The full path of the file/object to get the facts of. type: path required: true - aliases: [ name ] + aliases: [name] namespace: description: - Namespace of the named name/key. @@ -45,27 +43,26 @@ options: type: str state: description: - - defines which state you want to do. - V(read) retrieves the current value for a O(key) (default) - V(present) sets O(path) to O(value), default if value is set - V(all) dumps all data - V(keys) retrieves all keys - V(absent) deletes the key + - Defines which state you want to do. + - V(read) retrieves the current value for a O(key). + - V(present) sets O(path) to O(value), default if value is set. + - V(all) dumps all data. + - V(keys) retrieves all keys. + - V(absent) deletes the key. type: str - choices: [ absent, all, keys, present, read ] + choices: [absent, all, keys, present, read] default: read follow: description: - - If V(true), dereferences symlinks and sets/gets attributes on symlink target, - otherwise acts on symlink itself. + - If V(true), dereferences symlinks and sets/gets attributes on symlink target, otherwise acts on symlink itself. type: bool default: true author: - Brian Coca (@bcoca) -''' +""" -EXAMPLES = ''' -- name: Obtain the extended attributes of /etc/foo.conf +EXAMPLES = r""" +- name: Obtain the extended attributes of /etc/foo.conf community.general.xattr: path: /etc/foo.conf @@ -94,7 +91,7 @@ EXAMPLES = ''' namespace: trusted key: glusterfs.volume-id state: absent -''' +""" import os diff --git a/plugins/modules/xbps.py b/plugins/modules/xbps.py index cd34029eba..9f6cb59d98 100644 --- a/plugins/modules/xbps.py +++ b/plugins/modules/xbps.py @@ -10,86 +10,78 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: xbps short_description: Manage packages with XBPS description: - - Manage packages with the XBPS package manager. + - Manage packages with the XBPS package manager. author: - - "Dino Occhialini (@dinoocch)" - - "Michael Aldridge (@the-maldridge)" + - "Dino Occhialini (@dinoocch)" + - "Michael Aldridge (@the-maldridge)" 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 package to install, upgrade, or remove. - aliases: [pkg,package] - type: list - elements: str - state: - description: - - Desired state of the package. - default: "present" - choices: ["present", "absent", "latest", "installed", "removed"] - type: str - recurse: - description: - - When removing a package, also remove its dependencies, provided - that they are not required by other packages and were not - explicitly installed by a user. - type: bool - default: false - 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. - type: bool - default: true - upgrade: - description: - - Whether or not to upgrade whole system - type: bool - default: false - upgrade_xbps: - description: - - Whether or not to upgrade the xbps package when necessary. - Before installing new packages, - xbps requires the user to update the xbps package itself. - Thus when this option is set to V(false), - upgrades and installations will fail when xbps is not up to date. - type: bool - default: true - version_added: '0.2.0' - root: - description: - - The full path for the target root directory. - type: path - version_added: '10.2.0' - repositories: - description: - - Repository URL(s) to prepend to the repository list for the - package installation. - The URL can be a URL to a repository for - remote repositories or a path for local repositories. - type: list - elements: str - version_added: '10.2.0' - accept_pubkey: - description: - - Whether or not repository signing keys should be automatically accepted. - type: bool - default: false - version_added: '10.2.0' -''' + name: + description: + - Name of the package to install, upgrade, or remove. + aliases: [pkg, package] + type: list + elements: str + state: + description: + - Desired state of the package. + default: "present" + choices: ["present", "absent", "latest", "installed", "removed"] + type: str + recurse: + description: + - When removing a package, also remove its dependencies, provided that they are not required by other packages and were not explicitly installed + by a user. + type: bool + default: false + 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. + type: bool + default: true + upgrade: + description: + - Whether or not to upgrade whole system. + type: bool + default: false + upgrade_xbps: + description: + - Whether or not to upgrade the xbps package when necessary. Before installing new packages, xbps requires the user to update the xbps package + itself. Thus when this option is set to V(false), upgrades and installations will fail when xbps is not up to date. + type: bool + default: true + version_added: '0.2.0' + root: + description: + - The full path for the target root directory. + type: path + version_added: '10.2.0' + repositories: + description: + - Repository URL(s) to prepend to the repository list for the package installation. The URL can be a URL to a repository for remote repositories + or a path for local repositories. + type: list + elements: str + version_added: '10.2.0' + accept_pubkey: + description: + - Whether or not repository signing keys should be automatically accepted. + type: bool + default: false + version_added: '10.2.0' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install package foo (automatically updating the xbps package if needed) community.general.xbps: name: foo @@ -151,20 +143,20 @@ EXAMPLES = ''' state: present repositories: https://repo-default.voidlinux.org/current root: /mnt -''' +""" -RETURN = ''' +RETURN = r""" msg: - description: Message about results - returned: success - type: str - sample: "System Upgraded" + description: Message about results. + returned: success + type: str + sample: "System Upgraded" packages: - description: Packages that are affected/would be affected - type: list - sample: ["ansible"] - returned: success -''' + description: Packages that are affected/would be affected. + type: list + sample: ["ansible"] + returned: success +""" import os diff --git a/plugins/modules/xcc_redfish_command.py b/plugins/modules/xcc_redfish_command.py index 1e77d0f8db..a5b2ff57c2 100644 --- a/plugins/modules/xcc_redfish_command.py +++ b/plugins/modules/xcc_redfish_command.py @@ -8,14 +8,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: xcc_redfish_command short_description: Manages Lenovo Out-Of-Band controllers using Redfish APIs version_added: 2.4.0 description: - - Builds Redfish URIs locally and sends them to remote OOB controllers to - perform an action or get information back or update a configuration attribute. + - Builds Redfish URIs locally and sends them to remote OOB controllers to perform an action or get information back or update a configuration + attribute. - Manages virtual media. - Supports getting information back via GET method. - Supports updating a configuration attribute via PATCH method. @@ -54,7 +53,7 @@ options: type: str auth_token: description: - - Security token for authentication with OOB controller + - Security token for authentication with OOB controller. type: str timeout: description: @@ -120,181 +119,181 @@ options: type: dict author: "Yuyan Pan (@panyy3)" -''' +""" -EXAMPLES = ''' - - name: Insert Virtual Media - community.general.xcc_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: "1" +EXAMPLES = r""" +- name: Insert Virtual Media + community.general.xcc_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: "1" - - name: Eject Virtual Media - community.general.xcc_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: "1" +- name: Eject Virtual Media + community.general.xcc_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: "1" - - name: Eject all Virtual Media - community.general.xcc_redfish_command: - category: Manager - command: VirtualMediaEject - baseuri: "{{ baseuri }}" - username: "{{ username }}" - password: "{{ password }}" - resource_id: "1" +- name: Eject all Virtual Media + community.general.xcc_redfish_command: + category: Manager + command: VirtualMediaEject + baseuri: "{{ baseuri }}" + username: "{{ username }}" + password: "{{ password }}" + resource_id: "1" - - name: Get ComputeSystem Oem property SystemStatus via GetResource command - community.general.xcc_redfish_command: - category: Raw - command: GetResource - baseuri: "{{ baseuri }}" - username: "{{ username }}" - password: "{{ password }}" - resource_uri: "/redfish/v1/Systems/1" - register: result - - ansible.builtin.debug: - msg: "{{ result.redfish_facts.data.Oem.Lenovo.SystemStatus }}" +- name: Get ComputeSystem Oem property SystemStatus via GetResource command + community.general.xcc_redfish_command: + category: Raw + command: GetResource + baseuri: "{{ baseuri }}" + username: "{{ username }}" + password: "{{ password }}" + resource_uri: "/redfish/v1/Systems/1" + register: result +- ansible.builtin.debug: + msg: "{{ result.redfish_facts.data.Oem.Lenovo.SystemStatus }}" - - name: Get Oem DNS setting via GetResource command - community.general.xcc_redfish_command: - category: Raw - command: GetResource - baseuri: "{{ baseuri }}" - username: "{{ username }}" - password: "{{ password }}" - resource_uri: "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS" - register: result +- name: Get Oem DNS setting via GetResource command + community.general.xcc_redfish_command: + category: Raw + command: GetResource + baseuri: "{{ baseuri }}" + username: "{{ username }}" + password: "{{ password }}" + resource_uri: "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS" + register: result - - name: Print fetched information - ansible.builtin.debug: - msg: "{{ result.redfish_facts.data }}" +- name: Print fetched information + ansible.builtin.debug: + msg: "{{ result.redfish_facts.data }}" - - name: Get Lenovo FoD key collection resource via GetCollectionResource command - community.general.xcc_redfish_command: - category: Raw - command: GetCollectionResource - baseuri: "{{ baseuri }}" - username: "{{ username }}" - password: "{{ password }}" - resource_uri: "/redfish/v1/Managers/1/Oem/Lenovo/FoD/Keys" - register: result +- name: Get Lenovo FoD key collection resource via GetCollectionResource command + community.general.xcc_redfish_command: + category: Raw + command: GetCollectionResource + baseuri: "{{ baseuri }}" + username: "{{ username }}" + password: "{{ password }}" + resource_uri: "/redfish/v1/Managers/1/Oem/Lenovo/FoD/Keys" + register: result - - name: Print fetched information - ansible.builtin.debug: - msg: "{{ result.redfish_facts.data_list }}" +- name: Print fetched information + ansible.builtin.debug: + msg: "{{ result.redfish_facts.data_list }}" - - name: Update ComputeSystem property AssetTag via PatchResource command - community.general.xcc_redfish_command: - category: Raw - command: PatchResource - baseuri: "{{ baseuri }}" - username: "{{ username }}" - password: "{{ password }}" - resource_uri: "/redfish/v1/Systems/1" - request_body: - AssetTag: "new_asset_tag" +- name: Update ComputeSystem property AssetTag via PatchResource command + community.general.xcc_redfish_command: + category: Raw + command: PatchResource + baseuri: "{{ baseuri }}" + username: "{{ username }}" + password: "{{ password }}" + resource_uri: "/redfish/v1/Systems/1" + request_body: + AssetTag: "new_asset_tag" - - name: Perform BootToBIOSSetup action via PostResource command - community.general.xcc_redfish_command: - category: Raw - command: PostResource - baseuri: "{{ baseuri }}" - username: "{{ username }}" - password: "{{ password }}" - resource_uri: "/redfish/v1/Systems/1/Actions/Oem/LenovoComputerSystem.BootToBIOSSetup" - request_body: {} +- name: Perform BootToBIOSSetup action via PostResource command + community.general.xcc_redfish_command: + category: Raw + command: PostResource + baseuri: "{{ baseuri }}" + username: "{{ username }}" + password: "{{ password }}" + resource_uri: "/redfish/v1/Systems/1/Actions/Oem/LenovoComputerSystem.BootToBIOSSetup" + request_body: {} - - name: Perform SecureBoot.ResetKeys action via PostResource command - community.general.xcc_redfish_command: - category: Raw - command: PostResource - baseuri: "{{ baseuri }}" - username: "{{ username }}" - password: "{{ password }}" - resource_uri: "/redfish/v1/Systems/1/SecureBoot/Actions/SecureBoot.ResetKeys" - request_body: - ResetKeysType: DeleteAllKeys +- name: Perform SecureBoot.ResetKeys action via PostResource command + community.general.xcc_redfish_command: + category: Raw + command: PostResource + baseuri: "{{ baseuri }}" + username: "{{ username }}" + password: "{{ password }}" + resource_uri: "/redfish/v1/Systems/1/SecureBoot/Actions/SecureBoot.ResetKeys" + request_body: + ResetKeysType: DeleteAllKeys - - 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: Update Manager DateTimeLocalOffset property using security token for auth - community.general.xcc_redfish_command: - category: Raw - command: PatchResource - baseuri: "{{ baseuri }}" - auth_token: "{{ result.session.token }}" - resource_uri: "/redfish/v1/Managers/1" - request_body: - DateTimeLocalOffset: "+08:00" +- name: Update Manager DateTimeLocalOffset property using security token for auth + community.general.xcc_redfish_command: + category: Raw + command: PatchResource + baseuri: "{{ baseuri }}" + auth_token: "{{ result.session.token }}" + resource_uri: "/redfish/v1/Managers/1" + request_body: + DateTimeLocalOffset: "+08:00" - - 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 }}" +""" -RETURN = ''' +RETURN = r""" msg: - description: A message related to the performed action(s). - returned: when failure or action/update success - type: str - sample: "Action was successful" + description: A message related to the performed action(s). + returned: when failure or action/update success + type: str + sample: "Action was successful" redfish_facts: - description: Resource content. - returned: when command == GetResource or command == GetCollectionResource - type: dict - sample: '{ - "redfish_facts": { - "data": { - "@odata.etag": "\"3179bf00d69f25a8b3c\"", - "@odata.id": "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS", - "@odata.type": "#LenovoDNS.v1_0_0.LenovoDNS", - "DDNS": [ - { - "DDNSEnable": true, - "DomainName": "", - "DomainNameSource": "DHCP" - } - ], - "DNSEnable": true, - "Description": "This resource is used to represent a DNS resource for a Redfish implementation.", - "IPv4Address1": "10.103.62.178", - "IPv4Address2": "0.0.0.0", - "IPv4Address3": "0.0.0.0", - "IPv6Address1": "::", - "IPv6Address2": "::", - "IPv6Address3": "::", - "Id": "LenovoDNS", - "PreferredAddresstype": "IPv4" - }, - "ret": true - } - }' -''' + description: Resource content. + returned: when command == GetResource or command == GetCollectionResource + type: dict + sample: '{ + "redfish_facts": { + "data": { + "@odata.etag": "\"3179bf00d69f25a8b3c\"", + "@odata.id": "/redfish/v1/Managers/1/NetworkProtocol/Oem/Lenovo/DNS", + "@odata.type": "#LenovoDNS.v1_0_0.LenovoDNS", + "DDNS": [ + { + "DDNSEnable": true, + "DomainName": "", + "DomainNameSource": "DHCP" + } + ], + "DNSEnable": true, + "Description": "This resource is used to represent a DNS resource for a Redfish implementation.", + "IPv4Address1": "10.103.62.178", + "IPv4Address2": "0.0.0.0", + "IPv4Address3": "0.0.0.0", + "IPv6Address1": "::", + "IPv6Address2": "::", + "IPv6Address3": "::", + "Id": "LenovoDNS", + "PreferredAddresstype": "IPv4" + }, + "ret": true + } + }' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.common.text.converters import to_native diff --git a/plugins/modules/xenserver_facts.py b/plugins/modules/xenserver_facts.py index 685522f499..a3840e0e57 100644 --- a/plugins/modules/xenserver_facts.py +++ b/plugins/modules/xenserver_facts.py @@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: xenserver_facts short_description: Get facts reported on xenserver description: - - Reads data out of XenAPI, can be used instead of multiple xe commands. + - Reads data out of XenAPI, can be used instead of multiple C(xe) commands. author: - Andy Hill (@andyhky) - Tim Rupp (@caphrim007) @@ -28,9 +27,9 @@ attributes: version_added: 3.3.0 # This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix options: {} -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Gather facts from xenserver community.general.xenserver_facts: @@ -48,7 +47,7 @@ EXAMPLES = ''' # "item": "Control domain on host: 10.0.13.22", # "msg": "Control domain on host: 10.0.13.22" # } -''' +""" HAVE_XENAPI = False diff --git a/plugins/modules/xenserver_guest.py b/plugins/modules/xenserver_guest.py index 110bc88751..16d928874c 100644 --- a/plugins/modules/xenserver_guest.py +++ b/plugins/modules/xenserver_guest.py @@ -8,43 +8,41 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: xenserver_guest short_description: Manages virtual machines running on Citrix Hypervisor/XenServer host or pool -description: > - This module can be used to create new virtual machines from templates or other virtual machines, - modify various virtual machine components like network and disk, rename a virtual machine and - remove a virtual machine with associated components. +description: >- + This module can be used to create new virtual machines from templates or other virtual machines, modify various virtual machine components like + network and disk, rename a virtual machine and remove a virtual machine with associated components. author: -- Bojan Vitnik (@bvitnik) + - Bojan Vitnik (@bvitnik) notes: -- Minimal supported version of XenServer is 5.6. -- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. -- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside - Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your - Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: - U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)' -- 'If no scheme is specified in O(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are - accessing XenServer host in trusted environment or use C(https://) scheme explicitly.' -- 'To use C(https://) scheme for O(hostname) you have to either import host certificate to your OS certificate store or use O(validate_certs=false) - which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.' -- 'Network configuration inside a guest OS, by using O(networks[].type), O(networks[].ip), O(networks[].gateway) etc. parameters, is supported on - XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try to - detect if such support is available and utilize it, else it will use a custom method of configuration via xenstore. Since XenServer Guest - agent only support None and Static types of network configuration, where None means DHCP configured interface, O(networks[].type) and O(networks[].type6) - values V(none) and V(dhcp) have same effect. More info here: - U(https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html)' -- 'On platforms without official support for network configuration inside a guest OS, network parameters will be written to xenstore - C(vm-data/networks/) key. Parameters can be inspected by using C(xenstore ls) and C(xenstore read) tools on \*nix guests or through - WMI interface on Windows guests. They can also be found in VM facts C(instance.xenstore_data) key as returned by the module. It is up to the user - to implement a boot time scripts or custom agent that will read the parameters from xenstore and configure network with given parameters. - Take note that for xenstore data to become available inside a guest, a VM restart is needed hence module will require VM restart if any - parameter is changed. This is a limitation of XenAPI and xenstore. Considering these limitations, network configuration through xenstore is most - useful for bootstrapping newly deployed VMs, much less for reconfiguring existing ones. More info here: - U(https://support.citrix.com/article/CTX226713)' + - Minimal supported version of XenServer is 5.6. + - Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. + - 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix + Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible + Control Node to use it. Latest version of the library can also be acquired from GitHub: + U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py).' + - 'If no scheme is specified in O(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you + are accessing XenServer host in trusted environment or use C(https://) scheme explicitly.' + - 'To use C(https://) scheme for O(hostname) you have to either import host certificate to your OS certificate store or use O(validate_certs=false) + which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.' + - 'Network configuration inside a guest OS, by using O(networks[].type), O(networks[].ip), O(networks[].gateway) etc. parameters, is supported + on XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try + to detect if such support is available and utilize it, else it will use a custom method of configuration via xenstore. Since XenServer Guest + agent only support None and Static types of network configuration, where None means DHCP configured interface, O(networks[].type) and O(networks[].type6) + values V(none) and V(dhcp) have same effect. More info here: + U(https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html).' + - 'On platforms without official support for network configuration inside a guest OS, network parameters will be written to xenstore + C(vm-data/networks/) key. Parameters can be inspected by using C(xenstore ls) and C(xenstore read) tools on \*nix guests or through WMI + interface on Windows guests. + They can also be found in VM facts C(instance.xenstore_data) key as returned by the module. It is up to the user to implement a boot time + scripts or custom agent that will read the parameters from xenstore and configure network with given parameters. Take note that for xenstore + data to become available inside a guest, a VM restart is needed hence module will require VM restart if any parameter is changed. This is + a limitation of XenAPI and xenstore. Considering these limitations, network configuration through xenstore is most useful for bootstrapping + newly deployed VMs, much less for reconfiguring existing ones. More info here: U(https://support.citrix.com/article/CTX226713).' requirements: -- XenAPI + - XenAPI attributes: check_mode: support: full @@ -53,248 +51,249 @@ attributes: options: state: description: - - Specify the state VM should be in. - - If O(state) is set to V(present) and VM exists, ensure the VM configuration conforms to given parameters. - - If O(state) is set to V(present) and VM does not exist, then VM is deployed with given parameters. - - If O(state) is set to V(absent) and VM exists, then VM is removed with its associated components. - - If O(state) is set to V(poweredon) and VM does not exist, then VM is deployed with given parameters and powered on automatically. + - Specify the state VM should be in. + - If O(state) is set to V(present) and VM exists, ensure the VM configuration conforms to given parameters. + - If O(state) is set to V(present) and VM does not exist, then VM is deployed with given parameters. + - If O(state) is set to V(absent) and VM exists, then VM is removed with its associated components. + - If O(state) is set to V(poweredon) and VM does not exist, then VM is deployed with given parameters and powered on automatically. type: str default: present - choices: [ present, absent, poweredon ] + choices: [present, absent, poweredon] name: description: - - Name of the VM to work with. - - VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found. - - In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage. - - This parameter is case sensitive. + - Name of the VM to work with. + - VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found. + - In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage. + - This parameter is case sensitive. type: str - aliases: [ name_label ] + aliases: [name_label] name_desc: description: - - VM description. + - VM description. type: str uuid: description: - - UUID of the VM to manage if known. This is XenServer's unique identifier. - - It is required if name is not unique. - - Please note that a supplied UUID will be ignored on VM creation, as XenServer creates the UUID internally. + - UUID of the VM to manage if known. This is XenServer's unique identifier. + - It is required if name is not unique. + - Please note that a supplied UUID will be ignored on VM creation, as XenServer creates the UUID internally. type: str template: description: - - Name of a template, an existing VM (must be shut down) or a snapshot that should be used to create VM. - - Templates/VMs/snapshots on XenServer do not necessarily have unique names. The module will fail if multiple templates with same name are found. - - In case of multiple templates/VMs/snapshots with same name, use O(template_uuid) to uniquely specify source template. - - If VM already exists, this setting will be ignored. - - This parameter is case sensitive. + - Name of a template, an existing VM (must be shut down) or a snapshot that should be used to create VM. + - Templates/VMs/snapshots on XenServer do not necessarily have unique names. The module will fail if multiple templates with same name are + found. + - In case of multiple templates/VMs/snapshots with same name, use O(template_uuid) to uniquely specify source template. + - If VM already exists, this setting will be ignored. + - This parameter is case sensitive. type: str - aliases: [ template_src ] + aliases: [template_src] template_uuid: description: - - UUID of a template, an existing VM or a snapshot that should be used to create VM. - - It is required if template name is not unique. + - UUID of a template, an existing VM or a snapshot that should be used to create VM. + - It is required if template name is not unique. type: str is_template: description: - - Convert VM to template. + - Convert VM to template. type: bool default: false folder: description: - - Destination folder for VM. - - This parameter is case sensitive. - - 'Example:' - - ' folder: /folder1/folder2' + - Destination folder for VM. + - This parameter is case sensitive. + - 'Example:' + - ' folder: /folder1/folder2' type: str hardware: description: - - Manage VM's hardware parameters. VM needs to be shut down to reconfigure these parameters. + - Manage VM's hardware parameters. VM needs to be shut down to reconfigure these parameters. type: dict suboptions: num_cpus: description: - - Number of CPUs. + - Number of CPUs. type: int num_cpu_cores_per_socket: description: - - Number of Cores Per Socket. O(hardware.num_cpus) has to be a multiple of O(hardware.num_cpu_cores_per_socket). + - Number of Cores Per Socket. O(hardware.num_cpus) has to be a multiple of O(hardware.num_cpu_cores_per_socket). type: int memory_mb: description: - - Amount of memory in MB. + - Amount of memory in MB. type: int disks: description: - - A list of disks to add to VM. - - All parameters are case sensitive. - - Removing or detaching existing disks of VM is not supported. - - New disks are required to have either a O(disks[].size) or one of O(ignore:disks[].size_[tb,gb,mb,kb,b]) parameters specified. - - VM needs to be shut down to reconfigure disk size. + - A list of disks to add to VM. + - All parameters are case sensitive. + - Removing or detaching existing disks of VM is not supported. + - New disks are required to have either a O(disks[].size) or one of O(ignore:disks[].size_[tb,gb,mb,kb,b]) parameters specified. + - VM needs to be shut down to reconfigure disk size. type: list elements: dict - aliases: [ disk ] + aliases: [disk] suboptions: size: description: - - 'Disk size with unit. Unit must be: V(b), V(kb), V(mb), V(gb), V(tb). VM needs to be shut down to reconfigure this parameter.' - - If no unit is specified, size is assumed to be in bytes. + - 'Disk size with unit. Unit must be: V(b), V(kb), V(mb), V(gb), V(tb). VM needs to be shut down to reconfigure this parameter.' + - If no unit is specified, size is assumed to be in bytes. type: str size_b: description: - - Disk size in bytes. + - Disk size in bytes. type: str size_kb: description: - - Disk size in kilobytes. + - Disk size in kilobytes. type: str size_mb: description: - - Disk size in megabytes. + - Disk size in megabytes. type: str size_gb: description: - - Disk size in gigabytes. + - Disk size in gigabytes. type: str size_tb: description: - - Disk size in terabytes. + - Disk size in terabytes. type: str name: description: - - Disk name. + - Disk name. type: str - aliases: [ name_label ] + aliases: [name_label] name_desc: description: - - Disk description. + - Disk description. type: str sr: description: - - Storage Repository to create disk on. If not specified, will use default SR. Cannot be used for moving disk to other SR. + - Storage Repository to create disk on. If not specified, will use default SR. Cannot be used for moving disk to other SR. type: str sr_uuid: description: - - UUID of a SR to create disk on. Use if SR name is not unique. + - UUID of a SR to create disk on. Use if SR name is not unique. type: str cdrom: description: - - A CD-ROM configuration for the VM. - - All parameters are case sensitive. + - A CD-ROM configuration for the VM. + - All parameters are case sensitive. type: dict suboptions: type: description: - - The type of CD-ROM. With V(none) the CD-ROM device will be present but empty. + - The type of CD-ROM. With V(none) the CD-ROM device will be present but empty. type: str - choices: [ none, iso ] + choices: [none, iso] iso_name: description: - - 'The file name of an ISO image from one of the XenServer ISO Libraries (implies O(cdrom.type=iso)).' - - Required if O(cdrom.type) is set to V(iso). + - 'The file name of an ISO image from one of the XenServer ISO Libraries (implies O(cdrom.type=iso)).' + - Required if O(cdrom.type) is set to V(iso). type: str networks: description: - - A list of networks (in the order of the NICs). - - All parameters are case sensitive. - - Name is required for new NICs. Other parameters are optional in all cases. + - A list of networks (in the order of the NICs). + - All parameters are case sensitive. + - Name is required for new NICs. Other parameters are optional in all cases. type: list elements: dict - aliases: [ network ] + aliases: [network] suboptions: - name: - description: + name: + description: - Name of a XenServer network to attach the network interface to. - type: str - aliases: [ name_label ] - mac: - description: + type: str + aliases: [name_label] + mac: + description: - Customize MAC address of the interface. - type: str - type: - description: - - Type of IPv4 assignment. Value V(none) means whatever is default for OS. - - On some operating systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g. Linux). - type: str - choices: [ none, dhcp, static ] - ip: - description: - - 'Static IPv4 address (implies O(networks[].type=static)). Can include prefix in format C(/) instead of using C(netmask).' - type: str - netmask: - description: + type: str + type: + description: + - Type of IPv4 assignment. Value V(none) means whatever is default for OS. + - On some operating systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g. Linux). + type: str + choices: [none, dhcp, static] + ip: + description: + - Static IPv4 address (implies O(networks[].type=static)). Can include prefix in format C(/) instead of using + C(netmask). + type: str + netmask: + description: - Static IPv4 netmask required for O(networks[].ip) if prefix is not specified. - type: str - gateway: - description: + type: str + gateway: + description: - Static IPv4 gateway. - type: str - type6: - description: + type: str + type6: + description: - Type of IPv6 assignment. Value V(none) means whatever is default for OS. - type: str - choices: [ none, dhcp, static ] - ip6: - description: + type: str + choices: [none, dhcp, static] + ip6: + description: - 'Static IPv6 address (implies O(networks[].type6=static)) with prefix in format C(/).' - type: str - gateway6: - description: + type: str + gateway6: + description: - Static IPv6 gateway. - type: str + type: str home_server: description: - - Name of a XenServer host that will be a Home Server for the VM. - - This parameter is case sensitive. + - Name of a XenServer host that will be a Home Server for the VM. + - This parameter is case sensitive. type: str custom_params: description: - - Define a list of custom VM params to set on VM. - - Useful for advanced users familiar with managing VM params through xe CLI. - - A custom value object takes two fields O(custom_params[].key) and O(custom_params[].value) (see example below). + - Define a list of custom VM params to set on VM. + - Useful for advanced users familiar with managing VM params through C(xe) CLI. + - A custom value object takes two fields O(custom_params[].key) and O(custom_params[].value) (see example below). type: list elements: dict suboptions: key: description: - - VM param name. + - VM param name. type: str required: true value: description: - - VM param value. + - VM param value. type: raw required: true wait_for_ip_address: description: - - Wait until XenServer detects an IP address for the VM. If O(state) is set to V(absent), this parameter is ignored. - - This requires XenServer Tools to be preinstalled on the VM to work properly. + - Wait until XenServer detects an IP address for the VM. If O(state) is set to V(absent), this parameter is ignored. + - This requires XenServer Tools to be preinstalled on the VM to work properly. type: bool default: false state_change_timeout: description: - - 'By default, module will wait indefinitely for VM to acquire an IP address if O(wait_for_ip_address=true).' - - If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change. - - In case of timeout, module will generate an error message. + - 'By default, module will wait indefinitely for VM to acquire an IP address if O(wait_for_ip_address=true).' + - If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change. + - In case of timeout, module will generate an error message. type: int default: 0 linked_clone: description: - - Whether to create a Linked Clone from the template, existing VM or snapshot. If no, will create a full copy. - - This is equivalent to C(Use storage-level fast disk clone) option in XenCenter. + - Whether to create a Linked Clone from the template, existing VM or snapshot. If no, will create a full copy. + - This is equivalent to C(Use storage-level fast disk clone) option in XenCenter. type: bool default: false force: description: - - Ignore warnings and complete the actions. - - This parameter is useful for removing VM in running state or reconfiguring VM params that require VM to be shut down. + - Ignore warnings and complete the actions. + - This parameter is useful for removing VM in running state or reconfiguring VM params that require VM to be shut down. type: bool default: false extends_documentation_fragment: -- community.general.xenserver.documentation -- community.general.attributes + - community.general.xenserver.documentation + - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a VM from a template community.general.xenserver_guest: hostname: "{{ xenserver_hostname }}" @@ -305,8 +304,8 @@ EXAMPLES = r''' state: poweredon template: CentOS 7 disks: - - size_gb: 10 - sr: my_sr + - size_gb: 10 + sr: my_sr hardware: num_cpus: 6 num_cpu_cores_per_socket: 3 @@ -315,8 +314,8 @@ EXAMPLES = r''' type: iso iso_name: guest-tools.iso networks: - - name: VM Network - mac: aa:bb:dd:aa:00:14 + - name: VM Network + mac: aa:bb:dd:aa:00:14 wait_for_ip_address: true delegate_to: localhost register: deploy @@ -330,8 +329,8 @@ EXAMPLES = r''' name: testvm_6 is_template: true disk: - - size_gb: 10 - sr: my_sr + - size_gb: 10 + sr: my_sr hardware: memory_mb: 512 num_cpus: 1 @@ -365,8 +364,8 @@ EXAMPLES = r''' name: testvm_8 state: present custom_params: - - key: HVM_boot_params - value: { "order": "ndc" } + - key: HVM_boot_params + value: {"order": "ndc"} delegate_to: localhost - name: Customize network parameters @@ -376,154 +375,154 @@ EXAMPLES = r''' password: "{{ xenserver_password }}" name: testvm_10 networks: - - name: VM Network - ip: 192.168.1.100/24 - gateway: 192.168.1.1 - - type: dhcp + - name: VM Network + ip: 192.168.1.100/24 + gateway: 192.168.1.1 + - type: dhcp delegate_to: localhost -''' +""" -RETURN = r''' +RETURN = r""" instance: - description: Metadata about the VM - returned: always - type: dict - sample: { - "cdrom": { - "type": "none" - }, - "customization_agent": "native", - "disks": [ - { - "name": "testvm_11-0", - "name_desc": "", - "os_device": "xvda", - "size": 42949672960, - "sr": "Local storage", - "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", - "vbd_userdevice": "0" - }, - { - "name": "testvm_11-1", - "name_desc": "", - "os_device": "xvdb", - "size": 42949672960, - "sr": "Local storage", - "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", - "vbd_userdevice": "1" - } - ], - "domid": "56", - "folder": "", - "hardware": { - "memory_mb": 8192, - "num_cpu_cores_per_socket": 2, - "num_cpus": 4 - }, - "home_server": "", - "is_template": false, - "name": "testvm_11", + description: Metadata about the VM. + returned: always + type: dict + sample: { + "cdrom": { + "type": "none" + }, + "customization_agent": "native", + "disks": [ + { + "name": "testvm_11-0", "name_desc": "", - "networks": [ - { - "gateway": "192.168.0.254", - "gateway6": "fc00::fffe", - "ip": "192.168.0.200", - "ip6": [ - "fe80:0000:0000:0000:e9cb:625a:32c5:c291", - "fc00:0000:0000:0000:0000:0000:0000:0001" - ], - "mac": "ba:91:3a:48:20:76", - "mtu": "1500", - "name": "Pool-wide network associated with eth1", - "netmask": "255.255.255.128", - "prefix": "25", - "prefix6": "64", - "vif_device": "0" - } + "os_device": "xvda", + "size": 42949672960, + "sr": "Local storage", + "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", + "vbd_userdevice": "0" + }, + { + "name": "testvm_11-1", + "name_desc": "", + "os_device": "xvdb", + "size": 42949672960, + "sr": "Local storage", + "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", + "vbd_userdevice": "1" + } + ], + "domid": "56", + "folder": "", + "hardware": { + "memory_mb": 8192, + "num_cpu_cores_per_socket": 2, + "num_cpus": 4 + }, + "home_server": "", + "is_template": false, + "name": "testvm_11", + "name_desc": "", + "networks": [ + { + "gateway": "192.168.0.254", + "gateway6": "fc00::fffe", + "ip": "192.168.0.200", + "ip6": [ + "fe80:0000:0000:0000:e9cb:625a:32c5:c291", + "fc00:0000:0000:0000:0000:0000:0000:0001" ], - "other_config": { - "base_template_name": "Windows Server 2016 (64-bit)", - "import_task": "OpaqueRef:e43eb71c-45d6-5351-09ff-96e4fb7d0fa5", - "install-methods": "cdrom", - "instant": "true", - "mac_seed": "f83e8d8a-cfdc-b105-b054-ef5cb416b77e" - }, - "platform": { - "acpi": "1", - "apic": "true", - "cores-per-socket": "2", - "device_id": "0002", - "hpet": "true", - "nx": "true", - "pae": "true", - "timeoffset": "-25200", - "vga": "std", - "videoram": "8", - "viridian": "true", - "viridian_reference_tsc": "true", - "viridian_time_ref_count": "true" - }, - "state": "poweredon", - "uuid": "e3c0b2d5-5f05-424e-479c-d3df8b3e7cda", - "xenstore_data": { - "vm-data": "" - } + "mac": "ba:91:3a:48:20:76", + "mtu": "1500", + "name": "Pool-wide network associated with eth1", + "netmask": "255.255.255.128", + "prefix": "25", + "prefix6": "64", + "vif_device": "0" + } + ], + "other_config": { + "base_template_name": "Windows Server 2016 (64-bit)", + "import_task": "OpaqueRef:e43eb71c-45d6-5351-09ff-96e4fb7d0fa5", + "install-methods": "cdrom", + "instant": "true", + "mac_seed": "f83e8d8a-cfdc-b105-b054-ef5cb416b77e" + }, + "platform": { + "acpi": "1", + "apic": "true", + "cores-per-socket": "2", + "device_id": "0002", + "hpet": "true", + "nx": "true", + "pae": "true", + "timeoffset": "-25200", + "vga": "std", + "videoram": "8", + "viridian": "true", + "viridian_reference_tsc": "true", + "viridian_time_ref_count": "true" + }, + "state": "poweredon", + "uuid": "e3c0b2d5-5f05-424e-479c-d3df8b3e7cda", + "xenstore_data": { + "vm-data": "" } + } changes: - description: Detected or made changes to VM - returned: always - type: list - sample: [ + description: Detected or made changes to VM. + returned: always + type: list + sample: [ + { + "hardware": [ + "num_cpus" + ] + }, + { + "disks_changed": [ + [], + [ + "size" + ] + ] + }, + { + "disks_new": [ { - "hardware": [ - "num_cpus" - ] - }, + "name": "new-disk", + "name_desc": "", + "position": 2, + "size_gb": "4", + "vbd_userdevice": "2" + } + ] + }, + { + "cdrom": [ + "type", + "iso_name" + ] + }, + { + "networks_changed": [ + [ + "mac" + ], + ] + }, + { + "networks_new": [ { - "disks_changed": [ - [], - [ - "size" - ] - ] - }, - { - "disks_new": [ - { - "name": "new-disk", - "name_desc": "", - "position": 2, - "size_gb": "4", - "vbd_userdevice": "2" - } - ] - }, - { - "cdrom": [ - "type", - "iso_name" - ] - }, - { - "networks_changed": [ - [ - "mac" - ], - ] - }, - { - "networks_new": [ - { - "name": "Pool-wide network associated with eth2", - "position": 1, - "vif_device": "1" - } - ] - }, - "need_poweredoff" - ] -''' + "name": "Pool-wide network associated with eth2", + "position": 1, + "vif_device": "1" + } + ] + }, + "need_poweredoff" + ] +""" import re diff --git a/plugins/modules/xenserver_guest_info.py b/plugins/modules/xenserver_guest_info.py index 68050f9509..10cd11839c 100644 --- a/plugins/modules/xenserver_guest_info.py +++ b/plugins/modules/xenserver_guest_info.py @@ -8,48 +8,46 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: xenserver_guest_info short_description: Gathers information for virtual machines running on Citrix Hypervisor/XenServer host or pool -description: > - This module can be used to gather essential VM facts. +description: This module can be used to gather essential VM facts. author: -- Bojan Vitnik (@bvitnik) + - Bojan Vitnik (@bvitnik) notes: -- Minimal supported version of XenServer is 5.6. -- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. -- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside - Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your - Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: - U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)' -- 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are - accessing XenServer host in trusted environment or use C(https://) scheme explicitly.' -- 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs: no) - which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.' + - Minimal supported version of XenServer is 5.6. + - Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. + - 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix + Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible + Control Node to use it. Latest version of the library can also be acquired from GitHub: + U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)' + - 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you + are accessing XenServer host in trusted environment or use C(https://) scheme explicitly.' + - 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use O(validate_certs=no) which + requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.' requirements: -- XenAPI + - XenAPI options: name: description: - - Name of the VM to gather facts from. - - VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found. - - In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage. - - This parameter is case sensitive. + - Name of the VM to gather facts from. + - VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found. + - In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage. + - This parameter is case sensitive. type: str - aliases: [ name_label ] + aliases: [name_label] uuid: description: - - UUID of the VM to gather fact of. This is XenServer's unique identifier. - - It is required if name is not unique. + - UUID of the VM to gather fact of. This is XenServer's unique identifier. + - It is required if name is not unique. type: str extends_documentation_fragment: -- community.general.xenserver.documentation -- community.general.attributes -- community.general.attributes.info_module -''' + - community.general.xenserver.documentation + - community.general.attributes + - community.general.attributes.info_module +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Gather facts community.general.xenserver_guest_info: hostname: "{{ xenserver_hostname }}" @@ -58,11 +56,11 @@ EXAMPLES = r''' name: testvm_11 delegate_to: localhost register: facts -''' +""" -RETURN = r''' +RETURN = r""" instance: - description: Metadata about the VM + description: Metadata about the VM. returned: always type: dict sample: { @@ -147,7 +145,7 @@ instance: "vm-data": "" } } -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/xenserver_guest_powerstate.py b/plugins/modules/xenserver_guest_powerstate.py index c4e4f5976f..86a21b56dc 100644 --- a/plugins/modules/xenserver_guest_powerstate.py +++ b/plugins/modules/xenserver_guest_powerstate.py @@ -8,27 +8,25 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: xenserver_guest_powerstate short_description: Manages power states of virtual machines running on Citrix Hypervisor/XenServer host or pool -description: > - This module can be used to power on, power off, restart or suspend virtual machine and gracefully reboot or shutdown guest OS of virtual machine. +description: This module can be used to power on, power off, restart or suspend virtual machine and gracefully reboot or shutdown guest OS of virtual machine. author: -- Bojan Vitnik (@bvitnik) + - Bojan Vitnik (@bvitnik) notes: -- Minimal supported version of XenServer is 5.6. -- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. -- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside - Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your - Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: - U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)' -- 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are - accessing XenServer host in trusted environment or use C(https://) scheme explicitly.' -- 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs: no) - which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.' + - Minimal supported version of XenServer is 5.6. + - Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0. + - 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix + Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(XenAPI.py) file from the SDK to your Python site-packages on your Ansible + Control Node to use it. Latest version of the library can also be acquired from GitHub: + U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py).' + - 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you + are accessing XenServer host in trusted environment or use C(https://) scheme explicitly.' + - 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs: + no) which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.' requirements: -- XenAPI + - XenAPI attributes: check_mode: support: full @@ -37,45 +35,44 @@ attributes: options: state: description: - - Specify the state VM should be in. - - If O(state) is set to value other than V(present), then VM is transitioned into required state and facts are returned. - - If O(state) is set to V(present), then VM is just checked for existence and facts are returned. + - Specify the state VM should be in. + - If O(state) is set to value other than V(present), then VM is transitioned into required state and facts are returned. + - If O(state) is set to V(present), then VM is just checked for existence and facts are returned. type: str default: present - choices: [ powered-on, powered-off, restarted, shutdown-guest, reboot-guest, suspended, present ] + choices: [powered-on, powered-off, restarted, shutdown-guest, reboot-guest, suspended, present] name: description: - - Name of the VM to manage. - - VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found. - - In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage. - - This parameter is case sensitive. + - Name of the VM to manage. + - VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found. + - In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage. + - This parameter is case sensitive. type: str - aliases: [ name_label ] + aliases: [name_label] uuid: description: - - UUID of the VM to manage if known. This is XenServer's unique identifier. - - It is required if name is not unique. + - UUID of the VM to manage if known. This is XenServer's unique identifier. + - It is required if name is not unique. type: str wait_for_ip_address: description: - - Wait until XenServer detects an IP address for the VM. - - This requires XenServer Tools to be preinstalled on the VM to work properly. + - Wait until XenServer detects an IP address for the VM. + - This requires XenServer Tools to be preinstalled on the VM to work properly. type: bool default: false state_change_timeout: description: - - 'By default, module will wait indefinitely for VM to change state or acquire an IP address if O(wait_for_ip_address=true).' - - If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change. - - In case of timeout, module will generate an error message. + - 'By default, module will wait indefinitely for VM to change state or acquire an IP address if O(wait_for_ip_address=true).' + - If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change. + - In case of timeout, module will generate an error message. type: int default: 0 extends_documentation_fragment: -- community.general.xenserver.documentation -- community.general.attributes + - community.general.xenserver.documentation + - community.general.attributes +""" -''' - -EXAMPLES = r''' +EXAMPLES = r""" - name: Power on VM community.general.xenserver_guest_powerstate: hostname: "{{ xenserver_hostname }}" @@ -85,11 +82,11 @@ EXAMPLES = r''' state: powered-on delegate_to: localhost register: facts -''' +""" -RETURN = r''' +RETURN = r""" instance: - description: Metadata about the VM + description: Metadata about the VM. returned: always type: dict sample: { @@ -174,7 +171,7 @@ instance: "vm-data": "" } } -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/xfconf.py b/plugins/modules/xfconf.py index 8bb0abc273..b925e624c8 100644 --- a/plugins/modules/xfconf.py +++ b/plugins/modules/xfconf.py @@ -8,26 +8,25 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: xfconf author: -- "Joseph Benden (@jbenden)" -- "Alexei Znamensky (@russoz)" + - "Joseph Benden (@jbenden)" + - "Alexei Znamensky (@russoz)" short_description: Edit XFCE4 Configurations description: -- This module allows for the manipulation of Xfce 4 Configuration with the help of C(xfconf-query). + - This module allows for the manipulation of Xfce 4 Configuration with the help of C(xfconf-query). seealso: -- name: xfconf-query(1) man page - description: Manual page of the C(xfconf-query) tool at the XFCE documentation site. - link: 'https://docs.xfce.org/xfce/xfconf/xfconf-query' + - name: xfconf-query(1) man page + description: Manual page of the C(xfconf-query) tool at the XFCE documentation site. + link: 'https://docs.xfce.org/xfce/xfconf/xfconf-query' -- name: xfconf - Configuration Storage System - description: XFCE documentation for the Xfconf configuration system. - link: 'https://docs.xfce.org/xfce/xfconf/start' + - name: xfconf - Configuration Storage System + description: XFCE documentation for the Xfconf configuration system. + link: 'https://docs.xfce.org/xfce/xfconf/start' extends_documentation_fragment: -- community.general.attributes + - community.general.attributes attributes: check_mode: @@ -38,50 +37,49 @@ attributes: options: channel: description: - - A Xfconf preference channel is a top-level tree key, inside of the Xfconf repository that corresponds to the location for which all application - properties/keys are stored. See man xfconf-query(1). + - A Xfconf preference channel is a top-level tree key, inside of the Xfconf repository that corresponds to the location for which all application + properties/keys are stored. See man xfconf-query(1). required: true type: str property: description: - - A Xfce preference key is an element in the Xfconf repository that corresponds to an application preference. See man xfconf-query(1). + - A Xfce preference key is an element in the Xfconf repository that corresponds to an application preference. See man xfconf-query(1). required: true type: str value: description: - - Preference properties typically have simple values such as strings, integers, or lists of strings and integers. See man xfconf-query(1). + - Preference properties typically have simple values such as strings, integers, or lists of strings and integers. See man xfconf-query(1). type: list elements: raw value_type: description: - - The type of value being set. - - When providing more than one O(value_type), the length of the list must be equal to the length of O(value). - - If only one O(value_type) is provided, but O(value) contains more than on element, that O(value_type) will be applied to all elements of - O(value). - - If the O(property) being set is an array and it can possibly have only one element in the array, then O(force_array=true) must be used to - ensure that C(xfconf-query) will interpret the value as an array rather than a scalar. - - Support for V(uchar), V(char), V(uint64), and V(int64) has been added in community.general 4.8.0. + - The type of value being set. + - When providing more than one O(value_type), the length of the list must be equal to the length of O(value). + - If only one O(value_type) is provided, but O(value) contains more than on element, that O(value_type) will be applied to all elements + of O(value). + - If the O(property) being set is an array and it can possibly have only one element in the array, then O(force_array=true) must be used + to ensure that C(xfconf-query) will interpret the value as an array rather than a scalar. + - Support for V(uchar), V(char), V(uint64), and V(int64) has been added in community.general 4.8.0. type: list elements: str choices: [string, int, double, bool, uint, uchar, char, uint64, int64, float] state: type: str description: - - The action to take upon the property/value. - - The state V(get) has been removed in community.general 5.0.0. Please use the module M(community.general.xfconf_info) instead. + - The action to take upon the property/value. + - The state V(get) has been removed in community.general 5.0.0. Please use the module M(community.general.xfconf_info) instead. choices: [present, absent] default: "present" force_array: description: - - Force array even if only one element. + - Force array even if only one element. type: bool default: false aliases: ['array'] version_added: 1.0.0 """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Change the DPI to "192" xfconf: channel: "xsettings" @@ -105,57 +103,56 @@ EXAMPLES = """ force_array: true """ -RETURN = """ ---- +RETURN = r""" channel: - description: The channel specified in the module parameters + description: The channel specified in the module parameters. returned: success type: str sample: "xsettings" property: - description: The property specified in the module parameters + description: The property specified in the module parameters. returned: success type: str sample: "/Xft/DPI" value_type: description: - - The type of the value that was changed (V(none) for O(state=reset)). Either a single string value or a list of strings for array types. - - This is a string or a list of strings. + - The type of the value that was changed (V(none) for O(state=reset)). Either a single string value or a list of strings for array types. + - This is a string or a list of strings. returned: success type: any sample: '"int" or ["str", "str", "str"]' value: description: - - The value of the preference key after executing the module. Either a single string value or a list of strings for array types. - - This is a string or a list of strings. + - The value of the preference key after executing the module. Either a single string value or a list of strings for array types. + - This is a string or a list of strings. returned: success type: any - sample: '"192" or ["orange", "yellow", "violet"]' + sample: "'192' or ['orange', 'yellow', 'violet']" previous_value: description: - - The value of the preference key before executing the module. Either a single string value or a list of strings for array types. - - This is a string or a list of strings. + - The value of the preference key before executing the module. Either a single string value or a list of strings for array types. + - This is a string or a list of strings. returned: success type: any sample: '"96" or ["red", "blue", "green"]' cmd: description: - - A list with the resulting C(xfconf-query) command executed by the module. + - A list with the resulting C(xfconf-query) command executed by the module. returned: success type: list elements: str version_added: 5.4.0 sample: - - /usr/bin/xfconf-query - - --channel - - xfce4-panel - - --property - - /plugins/plugin-19/timezone - - --create - - --type - - string - - --set - - Pacific/Auckland + - /usr/bin/xfconf-query + - --channel + - xfce4-panel + - --property + - /plugins/plugin-19/timezone + - --create + - --type + - string + - --set + - Pacific/Auckland """ from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper diff --git a/plugins/modules/xfconf_info.py b/plugins/modules/xfconf_info.py index aba0d912ff..d8e6acc50d 100644 --- a/plugins/modules/xfconf_info.py +++ b/plugins/modules/xfconf_info.py @@ -7,18 +7,17 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: xfconf_info author: -- "Alexei Znamensky (@russoz)" + - "Alexei Znamensky (@russoz)" short_description: Retrieve XFCE4 configurations version_added: 3.5.0 description: -- This module allows retrieving Xfce 4 configurations with the help of C(xfconf-query). + - This module allows retrieving Xfce 4 configurations with the help of C(xfconf-query). 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 @@ -26,26 +25,21 @@ attributes: options: channel: description: - - > - A Xfconf preference channel is a top-level tree key, inside of the - Xfconf repository that corresponds to the location for which all - application properties/keys are stored. - - If not provided, the module will list all available channels. + - "A Xfconf preference channel is a top-level tree key, inside of the Xfconf repository that corresponds to the location for which all application + properties/keys are stored." + - If not provided, the module will list all available channels. type: str property: description: - - > - A Xfce preference key is an element in the Xfconf repository - that corresponds to an application preference. - - If provided, then O(channel) is required. - - If not provided and a O(channel) is provided, then the module will list all available properties in that O(channel). + - "A Xfce preference key is an element in the Xfconf repository that corresponds to an application preference." + - If provided, then O(channel) is required. + - If not provided and a O(channel) is provided, then the module will list all available properties in that O(channel). type: str notes: -- See man xfconf-query(1) for more details. + - See man xfconf-query(1) for more details. """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Get list of all available channels community.general.xfconf_info: {} register: result @@ -68,63 +62,62 @@ EXAMPLES = """ register: result """ -RETURN = """ ---- +RETURN = r""" channels: description: - - List of available channels. - - Returned when the module receives no parameter at all. + - List of available channels. + - Returned when the module receives no parameter at all. returned: success type: list elements: str sample: - - xfce4-desktop - - displays - - xsettings - - xfwm4 + - xfce4-desktop + - displays + - xsettings + - xfwm4 properties: description: - - List of available properties for a specific channel. - - Returned by passing only the O(channel) parameter to the module. + - List of available properties for a specific channel. + - Returned by passing only the O(channel) parameter to the module. returned: success type: list elements: str sample: - - /Gdk/WindowScalingFactor - - /Gtk/ButtonImages - - /Gtk/CursorThemeSize - - /Gtk/DecorationLayout - - /Gtk/FontName - - /Gtk/MenuImages - - /Gtk/MonospaceFontName - - /Net/DoubleClickTime - - /Net/IconThemeName - - /Net/ThemeName - - /Xft/Antialias - - /Xft/Hinting - - /Xft/HintStyle - - /Xft/RGBA + - /Gdk/WindowScalingFactor + - /Gtk/ButtonImages + - /Gtk/CursorThemeSize + - /Gtk/DecorationLayout + - /Gtk/FontName + - /Gtk/MenuImages + - /Gtk/MonospaceFontName + - /Net/DoubleClickTime + - /Net/IconThemeName + - /Net/ThemeName + - /Xft/Antialias + - /Xft/Hinting + - /Xft/HintStyle + - /Xft/RGBA is_array: description: - - Flag indicating whether the property is an array or not. + - Flag indicating whether the property is an array or not. returned: success type: bool value: description: - - The value of the property. Empty if the property is of array type. + - The value of the property. Empty if the property is of array type. returned: success type: str sample: Monospace 10 value_array: description: - - The array value of the property. Empty if the property is not of array type. + - The array value of the property. Empty if the property is not of array type. returned: success type: list elements: str sample: - - Main - - Work - - Tmp + - Main + - Work + - Tmp """ from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper diff --git a/plugins/modules/xfs_quota.py b/plugins/modules/xfs_quota.py index 6d05219905..3b0b2bd19e 100644 --- a/plugins/modules/xfs_quota.py +++ b/plugins/modules/xfs_quota.py @@ -12,7 +12,6 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = r""" ---- module: xfs_quota short_description: Manage quotas on XFS filesystems description: @@ -85,7 +84,7 @@ options: - absent requirements: - - xfsprogs + - xfsprogs """ EXAMPLES = r""" @@ -109,40 +108,39 @@ EXAMPLES = r""" mountpoint: /home isoft: 1024 ihard: 2048 - """ RETURN = r""" bhard: - description: the current bhard setting in bytes - returned: always - type: int - sample: 1024 + description: The current C(bhard) setting in bytes. + returned: always + type: int + sample: 1024 bsoft: - description: the current bsoft setting in bytes - returned: always - type: int - sample: 1024 + description: The current C(bsoft) setting in bytes. + returned: always + type: int + sample: 1024 ihard: - description: the current ihard setting in bytes - returned: always - type: int - sample: 100 + description: The current C(ihard) setting in bytes. + returned: always + type: int + sample: 100 isoft: - description: the current isoft setting in bytes - returned: always - type: int - sample: 100 + description: The current C(isoft) setting in bytes. + returned: always + type: int + sample: 100 rtbhard: - description: the current rtbhard setting in bytes - returned: always - type: int - sample: 1024 + description: The current C(rtbhard) setting in bytes. + returned: always + type: int + sample: 1024 rtbsoft: - description: the current rtbsoft setting in bytes - returned: always - type: int - sample: 1024 + description: The current C(rtbsoft) setting in bytes. + returned: always + type: int + sample: 1024 """ import grp diff --git a/plugins/modules/xml.py b/plugins/modules/xml.py index f5cdbeac38..b06b8051a2 100644 --- a/plugins/modules/xml.py +++ b/plugins/modules/xml.py @@ -11,8 +11,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: xml short_description: Manage bits and pieces of XML files or strings description: @@ -27,96 +26,94 @@ attributes: options: path: description: - - Path to the file to operate on. - - This file must exist ahead of time. - - This parameter is required, unless O(xmlstring) is given. + - Path to the file to operate on. + - This file must exist ahead of time. + - This parameter is required, unless O(xmlstring) is given. type: path - aliases: [ dest, file ] + aliases: [dest, file] xmlstring: description: - - A string containing XML on which to operate. - - This parameter is required, unless O(path) is given. + - A string containing XML on which to operate. + - This parameter is required, unless O(path) is given. type: str xpath: description: - - A valid XPath expression describing the item(s) you want to manipulate. - - Operates on the document root, V(/), by default. + - A valid XPath expression describing the item(s) you want to manipulate. + - Operates on the document root, V(/), by default. type: str namespaces: description: - - The namespace C(prefix:uri) mapping for the XPath expression. - - Needs to be a C(dict), not a C(list) of items. + - The namespace C(prefix:uri) mapping for the XPath expression. + - Needs to be a C(dict), not a C(list) of items. type: dict default: {} state: description: - - Set or remove an xpath selection (node(s), attribute(s)). + - Set or remove an xpath selection (node(s), attribute(s)). type: str - choices: [ absent, present ] + choices: [absent, present] default: present - aliases: [ ensure ] + aliases: [ensure] attribute: description: - - The attribute to select when using parameter O(value). - - This is a string, not prepended with V(@). + - The attribute to select when using parameter O(value). + - This is a string, not prepended with V(@). type: raw value: description: - - Desired state of the selected attribute. - - Either a string, or to unset a value, the Python V(None) keyword (YAML Equivalent, V(null)). - - Elements default to no value (but present). - - Attributes default to an empty string. + - Desired state of the selected attribute. + - Either a string, or to unset a value, the Python V(None) keyword (YAML Equivalent, V(null)). + - Elements default to no value (but present). + - Attributes default to an empty string. type: raw add_children: description: - - Add additional child-element(s) to a selected element for a given O(xpath). - - Child elements must be given in a list and each item may be either a string - (for example C(children=ansible) to add an empty C() child element), - or a hash where the key is an element name and the value is the element value. - - This parameter requires O(xpath) to be set. + - Add additional child-element(s) to a selected element for a given O(xpath). + - Child elements must be given in a list and each item may be either a string (for example C(children=ansible) to add an empty C() + child element), or a hash where the key is an element name and the value is the element value. + - This parameter requires O(xpath) to be set. type: list elements: raw set_children: description: - - Set the child-element(s) of a selected element for a given O(xpath). - - Removes any existing children. - - Child elements must be specified as in O(add_children). - - This parameter requires O(xpath) to be set. + - Set the child-element(s) of a selected element for a given O(xpath). + - Removes any existing children. + - Child elements must be specified as in O(add_children). + - This parameter requires O(xpath) to be set. type: list elements: raw count: description: - - Search for a given O(xpath) and provide the count of any matches. - - This parameter requires O(xpath) to be set. + - Search for a given O(xpath) and provide the count of any matches. + - This parameter requires O(xpath) to be set. type: bool default: false print_match: description: - - Search for a given O(xpath) and print out any matches. - - This parameter requires O(xpath) to be set. + - Search for a given O(xpath) and print out any matches. + - This parameter requires O(xpath) to be set. type: bool default: false pretty_print: description: - - Pretty print XML output. + - Pretty print XML output. type: bool default: false content: description: - - Search for a given O(xpath) and get content. - - This parameter requires O(xpath) to be set. + - Search for a given O(xpath) and get content. + - This parameter requires O(xpath) to be set. type: str - choices: [ attribute, text ] + choices: [attribute, text] input_type: description: - - Type of input for O(add_children) and O(set_children). + - Type of input for O(add_children) and O(set_children). type: str - choices: [ xml, yaml ] + choices: [xml, yaml] default: yaml 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 strip_cdata_tags: @@ -128,46 +125,44 @@ options: insertbefore: description: - Add additional child-element(s) before the first selected element for a given O(xpath). - - Child elements must be given in a list and each item may be either a string - (for example C(children=ansible) to add an empty C() child element), - or a hash where the key is an element name and the value is the element value. + - Child elements must be given in a list and each item may be either a string (for example C(children=ansible) to add an empty C() + child element), or a hash where the key is an element name and the value is the element value. - This parameter requires O(xpath) to be set. type: bool default: false insertafter: description: - Add additional child-element(s) after the last selected element for a given O(xpath). - - Child elements must be given in a list and each item may be either a string - (for example C(children=ansible) to add an empty C() child element), - or a hash where the key is an element name and the value is the element value. + - Child elements must be given in a list and each item may be either a string (for example C(children=ansible) to add an empty C() + child element), or a hash where the key is an element name and the value is the element value. - This parameter requires O(xpath) to be set. type: bool default: false requirements: -- lxml >= 2.3.0 + - lxml >= 2.3.0 notes: -- Use the C(--check) and C(--diff) options when testing your expressions. -- The diff output is automatically pretty-printed, so may not reflect the actual file content, only the file structure. -- This module does not handle complicated xpath expressions, so limit xpath selectors to simple expressions. -- Beware that in case your XML elements are namespaced, you need to use the O(namespaces) parameter, see the examples. -- Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them. + - Use the C(--check) and C(--diff) options when testing your expressions. + - The diff output is automatically pretty-printed, so may not reflect the actual file content, only the file structure. + - This module does not handle complicated xpath expressions, so limit xpath selectors to simple expressions. + - Beware that in case your XML elements are namespaced, you need to use the O(namespaces) parameter, see the examples. + - Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them. seealso: -- name: Xml module development community wiki - description: More information related to the development of this xml module. - link: https://github.com/ansible/community/wiki/Module:-xml -- name: Introduction to XPath - description: A brief tutorial on XPath (w3schools.com). - link: https://www.w3schools.com/xml/xpath_intro.asp -- name: XPath Reference document - description: The reference documentation on XSLT/XPath (developer.mozilla.org). - link: https://developer.mozilla.org/en-US/docs/Web/XPath + - name: XML module development community wiki (archived) + description: More information related to the development of this xml module. + link: https://github.com/ansible/community/wiki/Module:-xml + - name: Introduction to XPath + description: A brief tutorial on XPath (w3schools.com). + link: https://www.w3schools.com/xml/xpath_intro.asp + - name: XPath Reference document + description: The reference documentation on XSLT/XPath (developer.mozilla.org). + link: https://developer.mozilla.org/en-US/docs/Web/XPath author: -- Tim Bielawa (@tbielawa) -- Magnus Hedemark (@magnus919) -- Dag Wieers (@dagwieers) -''' + - Tim Bielawa (@tbielawa) + - Magnus Hedemark (@magnus919) + - Dag Wieers (@dagwieers) +""" -EXAMPLES = r''' +EXAMPLES = r""" # Consider the following XML file: # # @@ -219,9 +214,9 @@ EXAMPLES = r''' path: /foo/bar.xml xpath: /business/beers add_children: - - beer: Old Rasputin - - beer: Old Motor Oil - - beer: Old Curmudgeon + - beer: Old Rasputin + - beer: Old Motor Oil + - beer: Old Curmudgeon - name: Add several more beers to the 'beers' element and add them before the 'Rochefort 10' element community.general.xml: @@ -229,9 +224,9 @@ EXAMPLES = r''' xpath: '/business/beers/beer[text()="Rochefort 10"]' insertbefore: true add_children: - - beer: Old Rasputin - - beer: Old Motor Oil - - beer: Old Curmudgeon + - beer: Old Rasputin + - beer: Old Motor Oil + - beer: Old Curmudgeon # NOTE: The 'state' defaults to 'present' and 'value' defaults to 'null' for elements - name: Add a 'validxhtml' element to the 'website' element @@ -301,14 +296,14 @@ EXAMPLES = r''' xpath: /business add_children: - building: - # Attributes + # Attributes name: Scumm bar location: Monkey island - # Subnodes + # Subnodes _: - floor: Pirate hall - floor: Grog storage - - construction_date: "1990" # Only strings are valid + - construction_date: "1990" # Only strings are valid - building: Grog factory # Consider this XML for following example - @@ -327,37 +322,37 @@ EXAMPLES = r''' path: bar.xml xpath: /config/element[@name='test1'] state: absent -''' +""" -RETURN = r''' +RETURN = r""" actions: - description: A dictionary with the original xpath, namespaces and state. - type: dict - returned: success - sample: {xpath: xpath, namespaces: [namespace1, namespace2], state=present} + description: A dictionary with the original xpath, namespaces and state. + type: dict + returned: success + sample: {xpath: xpath, namespaces: [namespace1, namespace2], state: present} backup_file: - description: The name of the backup file that was created - type: str - returned: when O(backup=true) - sample: /path/to/file.xml.1942.2017-08-24@14:16:01~ + description: The name of the backup file that was created. + type: str + returned: when O(backup=true) + sample: /path/to/file.xml.1942.2017-08-24@14:16:01~ count: - description: The count of xpath matches. - type: int - returned: when parameter 'count' is set - sample: 2 + description: The count of xpath matches. + type: int + returned: when parameter O(count) is set + sample: 2 matches: - description: The xpath matches found. - type: list - returned: when parameter 'print_match' is set + description: The xpath matches found. + type: list + returned: when parameter O(print_match) is set msg: - description: A message related to the performed action(s). - type: str - returned: always + description: A message related to the performed action(s). + type: str + returned: always xmlstring: - description: An XML string of the resulting output. - type: str - returned: when parameter 'xmlstring' is set -''' + description: An XML string of the resulting output. + type: str + returned: when parameter O(xmlstring) is set +""" import copy import json From 2d12c6678c06ad8098a73c1d795c4dbcc95a48e8 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 19:20:29 +0100 Subject: [PATCH 078/302] [PR #9239/005c8f50 backport][stable-10] proxmox_backup: refactor permission checking (#9341) proxmox_backup: refactor permission checking (#9239) * proxmox_backup: refactor permission checking * add changelog frag * Update plugins/modules/proxmox_backup.py * Update plugins/modules/proxmox_backup.py * Update plugins/modules/proxmox_backup.py * Update plugins/modules/proxmox_backup.py For consistency * Update plugins/modules/proxmox_backup.py * yet another missing slash (cherry picked from commit 005c8f50db934624b6884d0dd12d47225a8b1301) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- .../9239-proxmox-backup-refactor.yml | 2 + plugins/modules/proxmox_backup.py | 173 ++++++------------ 2 files changed, 61 insertions(+), 114 deletions(-) create mode 100644 changelogs/fragments/9239-proxmox-backup-refactor.yml diff --git a/changelogs/fragments/9239-proxmox-backup-refactor.yml b/changelogs/fragments/9239-proxmox-backup-refactor.yml new file mode 100644 index 0000000000..4f73fe6dde --- /dev/null +++ b/changelogs/fragments/9239-proxmox-backup-refactor.yml @@ -0,0 +1,2 @@ +minor_changes: + - proxmox_backup - refactor permission checking to improve code readability and maintainability (https://github.com/ansible-collections/community.general/pull/9239). diff --git a/plugins/modules/proxmox_backup.py b/plugins/modules/proxmox_backup.py index 575d492bf9..0db2c4ad0e 100644 --- a/plugins/modules/proxmox_backup.py +++ b/plugins/modules/proxmox_backup.py @@ -6,6 +6,7 @@ # SPDX-License-Identifier: GPL-3.0-or-later from __future__ import absolute_import, division, print_function + __metaclass__ = type @@ -230,13 +231,16 @@ backups: type: str ''' -from ansible_collections.community.general.plugins.module_utils.proxmox import ( - proxmox_auth_argument_spec, ProxmoxAnsible) -from ansible.module_utils.common.text.converters import to_native -from ansible.module_utils.basic import AnsibleModule - 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): @@ -264,21 +268,20 @@ class ProxmoxBackupAnsible(ProxmoxAnsible): 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)]) + 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}]) + 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"] + 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) + self.module.fail_json(msg="Node %s was specified, but does not exist on the cluster" % node) elif node: return [node] return nodes @@ -291,57 +294,28 @@ class ProxmoxBackupAnsible(ProxmoxAnsible): performance, retention): # Check for Datastore.AllocateSpace in the permission tree - if "/" in permissions.keys() and permissions["/"].get( - "Datastore.AllocateSpace", 0) == 1: - pass - elif "/storage" in permissions.keys() and permissions["/storage"].get("Datastore.AllocateSpace", 0) == 1: - pass - elif "/storage/" + storage in permissions.keys() and permissions["/storage/" + storage].get("Datastore.AllocateSpace", 0) == 1: - pass - else: - self.module.fail_json( - changed=False, - msg="Insufficient permission: Datastore.AllocateSpace is missing") - if (bandwidth or performance) and permissions["/"].get( - "Sys.Modify", 0) == 0: - self.module.fail_json( - changed=False, - msg="Insufficient permission: Performance_tweaks and bandwidth require 'Sys.Modify' permission for '/'") + 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 "/" in permissions.keys() and permissions["/"].get( - "Datastore.Allocate", 0) == 1: - pass - elif "/storage" in permissions.keys() and permissions["/storage"].get("Datastore.Allocate", 0) == 1: - pass - elif "/storage/" + storage in permissions.keys() and permissions["/storage/" + storage].get("Datastore.Allocate", 0) == 1: - pass - else: - self.module.fail_json( - changed=False, - msg="Insufficient permissions: Custom retention was requested, but Datastore.Allocate is missing") + 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 = False - if "/" in permissions.keys() and permissions["/"].get( - "VM.Backup", 0) == 1: - sufficient_permissions = True - elif "/vms" in permissions.keys() and permissions["/vms"].get( - "VM.Backup", 0) == 1: - sufficient_permissions = True - elif pool and "/pool/" + pool in permissions.keys() and permissions["/pool/" + pool].get( - "VM.Backup", 0) == 1: - sufficient_permissions = True - elif pool and "/pool/" + pool + "/vms" in permissions.keys() and permissions["/pool/" + pool + "/vms"].get( - "VM.Backup", 0) == 1: - sufficient_permissions = True + 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: - if "/vms/" + \ - str(vm) in permissions.keys() and permissions["/vms/" + str(vm)].get("VM.Backup", 1) == 0: + 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( @@ -351,23 +325,11 @@ class ProxmoxBackupAnsible(ProxmoxAnsible): 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") + 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 "/" in permissions.keys() and permissions["/"].get( - "VM.Backup", 0) == 1: - pass - elif "/vms" in permissions.keys() and permissions["/vms"].get("VM.Backup", 0) == 1: - pass - elif pool and "/pool/" + pool in permissions.keys() and permissions["/pool/" + pool].get( - "VM.Backup", 0) == 1: - pass - else: - self.module.fail_json( - changed=False, - msg="Insufficient permissions: You dont have the VM.Backup permission") + 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) @@ -413,21 +375,19 @@ class ProxmoxBackupAnsible(ProxmoxAnsible): 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"] in ( - "job errors",): + 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): + 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"] + 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. " @@ -443,8 +403,7 @@ class ProxmoxBackupAnsible(ProxmoxAnsible): error_logs = [] for node in tasks: if node["status"] == "failed": - tasklog = ", ".join([logentry["t"] for logentry in self._get_tasklog( - node["node"], node["upid"])]) + 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( @@ -453,9 +412,8 @@ class ProxmoxBackupAnsible(ProxmoxAnsible): ", ".join(error_logs)) for node in tasks: - tasklog = ", ".join([logentry["t"] for logentry in self._get_tasklog( - node["node"], node["upid"])]) - node["log"] = "%s" % tasklog + 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) @@ -516,8 +474,7 @@ class ProxmoxBackupAnsible(ProxmoxAnsible): # 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.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"): @@ -550,26 +507,16 @@ class ProxmoxBackupAnsible(ProxmoxAnsible): def main(): module_args = proxmox_auth_argument_spec() backup_args = { - "backup_mode": {"type": "str", "default": "snapshot", "choices": [ - "snapshot", "suspend", "stop" - ]}, + "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" - ]}, + "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" - ]}, + "mode": {"type": "str", "required": True, "choices": ["include", "all", "pool"]}, "node": {"type": "str"}, - "notification_mode": {"type": "str", "default": "auto", "choices": [ - "auto", "legacy-sendmail", "notification-system" - ]}, + "notification_mode": {"type": "str", "default": "auto", "choices": ["auto", "legacy-sendmail", "notification-system"]}, "performance_tweaks": {"type": "str"}, "pool": {"type": "str"}, "protected": {"type": "bool"}, @@ -611,21 +558,19 @@ def main(): 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) + 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)) + 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") + 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") + 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") From 429b4b14a821f63528b578793dc320f83a4b1816 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 19:45:13 +0100 Subject: [PATCH 079/302] [PR #9294/d5237ee4 backport][stable-10] Add sanity test for action groups (#9343) Add sanity test for action groups (#9294) * Add sanity test for action groups. * Fix interpolation. * Fix message. Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * Improve regex. * Add entry for new 'keycloak' action group. Ref: https://github.com/ansible-collections/community.general/pull/9284 --------- Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> (cherry picked from commit d5237ee4869afa42efab8c255d701422916e07c3) Co-authored-by: Felix Fontein --- tests/sanity/extra/action-group.json | 12 ++ tests/sanity/extra/action-group.json.license | 3 + tests/sanity/extra/action-group.py | 134 +++++++++++++++++++ 3 files changed, 149 insertions(+) create mode 100644 tests/sanity/extra/action-group.json create mode 100644 tests/sanity/extra/action-group.json.license create mode 100755 tests/sanity/extra/action-group.py diff --git a/tests/sanity/extra/action-group.json b/tests/sanity/extra/action-group.json new file mode 100644 index 0000000000..db6a92bcb7 --- /dev/null +++ b/tests/sanity/extra/action-group.json @@ -0,0 +1,12 @@ +{ + "include_symlinks": true, + "prefixes": [ + "meta/runtime.yml", + "plugins/modules/", + "tests/sanity/extra/action-group." + ], + "output": "path-message", + "requirements": [ + "pyyaml" + ] +} diff --git a/tests/sanity/extra/action-group.json.license b/tests/sanity/extra/action-group.json.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/sanity/extra/action-group.json.license @@ -0,0 +1,3 @@ +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 +SPDX-FileCopyrightText: Ansible Project diff --git a/tests/sanity/extra/action-group.py b/tests/sanity/extra/action-group.py new file mode 100755 index 0000000000..9c82ff8619 --- /dev/null +++ b/tests/sanity/extra/action-group.py @@ -0,0 +1,134 @@ +#!/usr/bin/env python +# Copyright (c) 2024, Felix Fontein +# 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 +"""Make sure all modules that should show up in the action group.""" + +from __future__ import annotations + +import os +import re +import yaml + + +ACTION_GROUPS = { + # The format is as follows: + # * 'pattern': a regular expression matching all module names potentially belonging to the action group; + # * 'exclusions': a list of modules that are not part of the action group; all other modules matching 'pattern' must be part of it; + # * 'doc_fragment': the docs fragment that documents membership of the action group. + 'consul': { + 'pattern': re.compile('^consul_.*$'), + 'exclusions': [ + 'consul_acl_bootstrap', + 'consul_kv', + ], + 'doc_fragment': 'community.general.consul.actiongroup_consul', + }, + 'keycloak': { + 'pattern': re.compile('^keycloak_.*$'), + 'exclusions': [ + 'keycloak_realm_info', + ], + 'doc_fragment': 'community.general.keycloak.actiongroup_keycloak', + }, + 'proxmox': { + 'pattern': re.compile('^proxmox(_.*)?$'), + 'exclusions': [], + 'doc_fragment': 'community.general.proxmox.actiongroup_proxmox', + }, +} + + +def main(): + """Main entry point.""" + + # Load redirects + meta_runtime = 'meta/runtime.yml' + self_path = 'tests/sanity/extra/action-group.py' + try: + with open(meta_runtime, 'rb') as f: + data = yaml.safe_load(f) + action_groups = data['action_groups'] + except Exception as exc: + print(f'{meta_runtime}: cannot load action groups: {exc}') + return + + for action_group in action_groups: + if action_group not in ACTION_GROUPS: + print(f'{meta_runtime}: found unknown action group {action_group!r}; likely {self_path} needs updating') + for action_group, action_group_data in list(ACTION_GROUPS.items()): + if action_group not in action_groups: + print(f'{meta_runtime}: cannot find action group {action_group!r}; likely {self_path} needs updating') + + modules_directory = 'plugins/modules/' + modules_suffix = '.py' + + for file in os.listdir(modules_directory): + if not file.endswith(modules_suffix): + continue + module_name = file[:-len(modules_suffix)] + + for action_group, action_group_data in ACTION_GROUPS.items(): + action_group_content = action_groups.get(action_group) or [] + path = os.path.join(modules_directory, file) + + if not action_group_data['pattern'].match(module_name): + if module_name in action_group_content: + print(f'{path}: module is in action group {action_group!r} despite not matching its pattern as defined in {self_path}') + continue + + should_be_in_action_group = module_name not in action_group_data['exclusions'] + + if should_be_in_action_group: + if module_name not in action_group_content: + print(f'{meta_runtime}: module {module_name!r} is not part of {action_group!r} action group') + else: + action_group_content.remove(module_name) + + documentation = [] + in_docs = False + with open(path, 'r', encoding='utf-8') as f: + for line in f: + if line.startswith('DOCUMENTATION ='): + in_docs = True + elif line.startswith(("'''", '"""')) and in_docs: + in_docs = False + elif in_docs: + documentation.append(line) + if in_docs: + print(f'{path}: cannot find DOCUMENTATION end') + if not documentation: + print(f'{path}: cannot find DOCUMENTATION') + continue + + try: + docs = yaml.safe_load('\n'.join(documentation)) + if not isinstance(docs, dict): + raise Exception('is not a top-level dictionary') + except Exception as exc: + print(f'{path}: cannot load DOCUMENTATION as YAML: {exc}') + continue + + docs_fragments = docs.get('extends_documentation_fragment') or [] + is_in_action_group = action_group_data['doc_fragment'] in docs_fragments + + if should_be_in_action_group != is_in_action_group: + if should_be_in_action_group: + print( + f'{path}: module does not document itself as part of action group {action_group!r}, but it should;' + f' you need to add {action_group_data["doc_fragment"]} to "extends_documentation_fragment" in DOCUMENTATION' + ) + else: + print(f'{path}: module documents itself as part of action group {action_group!r}, but it should not be') + + for action_group, action_group_data in ACTION_GROUPS.items(): + action_group_content = action_groups.get(action_group) or [] + for module_name in action_group_content: + print( + f'{meta_runtime}: module {module_name} mentioned in {action_group!r} action group' + f' does not exist or does not match pattern defined in {self_path}' + ) + + +if __name__ == '__main__': + main() From e3f72bca4fe187c13716120366668fe2868f6fa2 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 23 Dec 2024 21:40:49 +0100 Subject: [PATCH 080/302] [PR #9335/c141f868 backport][stable-10] utm*: normalize docs (#9346) utm*: normalize docs (#9335) * utm*: normalize docs * Update plugins/modules/utm_aaa_group.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit c141f8688305c78c0dc53636f6906dc879221915) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/utm_aaa_group.py | 311 ++++++----- plugins/modules/utm_aaa_group_info.py | 147 +++--- plugins/modules/utm_ca_host_key_cert.py | 164 +++--- plugins/modules/utm_ca_host_key_cert_info.py | 104 ++-- plugins/modules/utm_dns_host.py | 191 ++++--- .../modules/utm_network_interface_address.py | 148 +++--- .../utm_network_interface_address_info.py | 98 ++-- plugins/modules/utm_proxy_auth_profile.py | 494 +++++++++--------- plugins/modules/utm_proxy_exception.py | 337 ++++++------ plugins/modules/utm_proxy_frontend.py | 397 +++++++------- plugins/modules/utm_proxy_frontend_info.py | 182 ++++--- plugins/modules/utm_proxy_location.py | 293 +++++------ plugins/modules/utm_proxy_location_info.py | 146 +++--- 13 files changed, 1487 insertions(+), 1525 deletions(-) diff --git a/plugins/modules/utm_aaa_group.py b/plugins/modules/utm_aaa_group.py index 9c595284da..b29f3d50af 100644 --- a/plugins/modules/utm_aaa_group.py +++ b/plugins/modules/utm_aaa_group.py @@ -8,120 +8,117 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_aaa_group author: - - Johannes Brunswicker (@MatrixCrawler) + - Johannes Brunswicker (@MatrixCrawler) short_description: Create, update or destroy an aaa group object in Sophos UTM description: - - Create, update or destroy an aaa group object in Sophos UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy an aaa group object in Sophos UTM. + - This module needs to have the REST Ability of the UTM to be activated. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - description: - - The name of the object. Will be used to identify the entry. - type: str - required: true - adirectory_groups: - description: - - List of adirectory group strings. - type: list - elements: str - default: [] - adirectory_groups_sids: - description: - - Dictionary of group sids. - type: dict - default: {} - backend_match: - description: - - The backend for the group. - type: str - choices: - - none - - adirectory - - edirectory - - radius - - tacacs - - ldap - default: none - comment: - description: - - Comment that describes the AAA group. - type: str - default: '' - dynamic: - description: - - Group type. Is static if none is selected. - type: str - default: none - choices: - - none - - ipsec_dn - - directory_groups - edirectory_groups: - description: - - List of edirectory group strings. - type: list - elements: str - default: [] - ipsec_dn: - description: - - The ipsec dn string. - type: str - default: '' - ldap_attribute: - description: - - The ldap attribute to check against. - type: str - default: '' - ldap_attribute_value: - description: - - The ldap attribute value to check against. - type: str - default: '' - members: - description: - - A list of user ref names (aaa/user). - type: list - elements: str - default: [] - network: - description: - - The network reference name. The objects contains the known ip addresses for the authentication object (network/aaa). - type: str - default: "" - radius_groups: - description: - - A list of radius group strings. - type: list - elements: str - default: [] - tacacs_groups: - description: - - A list of tacacs group strings. - type: list - elements: str - default: [] + name: + description: + - The name of the object. Will be used to identify the entry. + type: str + required: true + adirectory_groups: + description: + - List of adirectory group strings. + type: list + elements: str + default: [] + adirectory_groups_sids: + description: + - Dictionary of group sids. + type: dict + default: {} + backend_match: + description: + - The backend for the group. + type: str + choices: + - none + - adirectory + - edirectory + - radius + - tacacs + - ldap + default: none + comment: + description: + - Comment that describes the AAA group. + type: str + default: '' + dynamic: + description: + - Group type. Is static if none is selected. + type: str + default: none + choices: + - none + - ipsec_dn + - directory_groups + edirectory_groups: + description: + - List of edirectory group strings. + type: list + elements: str + default: [] + ipsec_dn: + description: + - The ipsec dn string. + type: str + default: '' + ldap_attribute: + description: + - The ldap attribute to check against. + type: str + default: '' + ldap_attribute_value: + description: + - The ldap attribute value to check against. + type: str + default: '' + members: + description: + - A list of user ref names (aaa/user). + type: list + elements: str + default: [] + network: + description: + - The network reference name. The objects contains the known IP addresses for the authentication object (network/aaa). + type: str + default: "" + radius_groups: + description: + - A list of radius group strings. + type: list + elements: str + default: [] + tacacs_groups: + description: + - A list of tacacs group strings. + type: list + elements: str + default: [] extends_documentation_fragment: -- community.general.utm -- community.general.attributes + - community.general.utm + - community.general.attributes +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Create UTM aaa_group community.general.utm_aaa_group: utm_host: sophos.host.name @@ -142,63 +139,63 @@ EXAMPLES = """ state: absent """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created. - returned: success - type: complex - contains: - _ref: - description: The reference name of the object. - type: str - _locked: - description: Whether or not the object is currently locked. - type: bool - _type: - description: The type of the object. - type: str - name: - description: The name of the object. - type: str - adirectory_groups: - description: List of Active Directory Groups. - type: str - adirectory_groups_sids: - description: List of Active Directory Groups SIDS. - type: list - backend_match: - description: The backend to use. - type: str - comment: - description: The comment string. - type: str - dynamic: - description: Whether the group match is ipsec_dn or directory_group. - type: str - edirectory_groups: - description: List of eDirectory Groups. - type: str - ipsec_dn: - description: ipsec_dn identifier to match. - type: str - ldap_attribute: - description: The LDAP Attribute to match against. - type: str - ldap_attribute_value: - description: The LDAP Attribute Value to match against. - type: str - members: - description: List of member identifiers of the group. - type: list - network: - description: The identifier of the network (network/aaa). - type: str - radius_group: - description: The radius group identifier. - type: str - tacacs_group: - description: The tacacs group identifier. - type: str + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + adirectory_groups: + description: List of Active Directory Groups. + type: str + adirectory_groups_sids: + description: List of Active Directory Groups SIDS. + type: list + backend_match: + description: The backend to use. + type: str + comment: + description: The comment string. + type: str + dynamic: + description: Whether the group match is ipsec_dn or directory_group. + type: str + edirectory_groups: + description: List of eDirectory Groups. + type: str + ipsec_dn: + description: Ipsec_dn identifier to match. + type: str + ldap_attribute: + description: The LDAP Attribute to match against. + type: str + ldap_attribute_value: + description: The LDAP Attribute Value to match against. + type: str + members: + description: List of member identifiers of the group. + type: list + network: + description: The identifier of the network (network/aaa). + type: str + radius_group: + description: The radius group identifier. + type: str + tacacs_group: + description: The tacacs group identifier. + type: str """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_aaa_group_info.py b/plugins/modules/utm_aaa_group_info.py index 37e01c736c..4f073176f2 100644 --- a/plugins/modules/utm_aaa_group_info.py +++ b/plugins/modules/utm_aaa_group_info.py @@ -10,38 +10,35 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_aaa_group_info author: - - Johannes Brunswicker (@MatrixCrawler) + - Johannes Brunswicker (@MatrixCrawler) short_description: Get info for reverse_proxy frontend entry in Sophos UTM description: - - get info for a reverse_proxy frontend entry in SOPHOS UTM. - + - Get info for a reverse_proxy frontend entry in SOPHOS UTM. 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: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true extends_documentation_fragment: - - community.general.utm - - community.general.attributes - - community.general.attributes.info_module + - community.general.utm + - community.general.attributes + - community.general.attributes.info_module +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Remove UTM aaa_group community.general.utm_aaa_group_info: utm_host: sophos.host.name @@ -49,63 +46,63 @@ EXAMPLES = """ name: TestAAAGroupEntry """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - adirectory_groups: - description: List of Active Directory Groups - type: str - adirectory_groups_sids: - description: List of Active Directory Groups SIDS - type: list - backend_match: - description: The backend to use - type: str - comment: - description: The comment string - type: str - dynamic: - description: Whether the group match is ipsec_dn or directory_group - type: str - edirectory_groups: - description: List of eDirectory Groups - type: str - ipsec_dn: - description: ipsec_dn identifier to match - type: str - ldap_attribute: - description: The LDAP Attribute to match against - type: str - ldap_attribute_value: - description: The LDAP Attribute Value to match against - type: str - members: - description: List of member identifiers of the group - type: list - network: - description: The identifier of the network (network/aaa) - type: str - radius_group: - description: The radius group identifier - type: str - tacacs_group: - description: The tacacs group identifier - type: str + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + adirectory_groups: + description: List of Active Directory Groups. + type: str + adirectory_groups_sids: + description: List of Active Directory Groups SIDS. + type: list + backend_match: + description: The backend to use. + type: str + comment: + description: The comment string. + type: str + dynamic: + description: Whether the group match is ipsec_dn or directory_group. + type: str + edirectory_groups: + description: List of eDirectory Groups. + type: str + ipsec_dn: + description: Ipsec_dn identifier to match. + type: str + ldap_attribute: + description: The LDAP Attribute to match against. + type: str + ldap_attribute_value: + description: The LDAP Attribute Value to match against. + type: str + members: + description: List of member identifiers of the group. + type: list + network: + description: The identifier of the network (network/aaa). + type: str + radius_group: + description: The radius group identifier. + type: str + tacacs_group: + description: The tacacs group identifier. + type: str """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_ca_host_key_cert.py b/plugins/modules/utm_ca_host_key_cert.py index b944e83124..b67531c061 100644 --- a/plugins/modules/utm_ca_host_key_cert.py +++ b/plugins/modules/utm_ca_host_key_cert.py @@ -9,67 +9,64 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_ca_host_key_cert author: - - Stephan Schwarz (@stearz) + - Stephan Schwarz (@stearz) short_description: Create, update or destroy ca host_key_cert entry in Sophos UTM description: - - Create, update or destroy a ca host_key_cert entry in SOPHOS UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy a ca host_key_cert entry in SOPHOS UTM. + - This module needs to have the REST Ability of the UTM to be activated. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - description: - - The name of the object. Will be used to identify the entry. - required: true - type: str - ca: - description: - - A reference to an existing utm_ca_signing_ca or utm_ca_verification_ca object. - required: true - type: str - meta: - description: - - A reference to an existing utm_ca_meta_x509 object. - required: true - type: str - certificate: - description: - - The certificate in PEM format. - required: true - type: str - comment: - description: - - Optional comment string. - type: str - encrypted: - description: - - Optionally enable encryption. - default: false - type: bool - key: - description: - - Optional private key in PEM format. - type: str + name: + description: + - The name of the object. Will be used to identify the entry. + required: true + type: str + ca: + description: + - A reference to an existing utm_ca_signing_ca or utm_ca_verification_ca object. + required: true + type: str + meta: + description: + - A reference to an existing utm_ca_meta_x509 object. + required: true + type: str + certificate: + description: + - The certificate in PEM format. + required: true + type: str + comment: + description: + - Optional comment string. + type: str + encrypted: + description: + - Optionally enable encryption. + default: false + type: bool + key: + description: + - Optional private key in PEM format. + type: str extends_documentation_fragment: -- community.general.utm -- community.general.attributes + - community.general.utm + - community.general.attributes +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Create a ca_host_key_cert entry community.general.utm_ca_host_key_cert: utm_host: sophos.host.name @@ -98,45 +95,44 @@ EXAMPLES = """ utm_token: abcdefghijklmno1234 name: TestHostKeyCertEntry state: info - """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - ca: - description: A reference to an existing utm_ca_signing_ca or utm_ca_verification_ca object. - type: str - meta: - description: A reference to an existing utm_ca_meta_x509 object. - type: str - certificate: - description: The certificate in PEM format - type: str - comment: - description: Comment string (may be empty string) - type: str - encrypted: - description: If encryption is enabled - type: bool - key: - description: Private key in PEM format (may be empty string) - type: str + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + ca: + description: A reference to an existing utm_ca_signing_ca or utm_ca_verification_ca object. + type: str + meta: + description: A reference to an existing utm_ca_meta_x509 object. + type: str + certificate: + description: The certificate in PEM format. + type: str + comment: + description: Comment string (may be empty string). + type: str + encrypted: + description: If encryption is enabled. + type: bool + key: + description: Private key in PEM format (may be empty string). + type: str """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_ca_host_key_cert_info.py b/plugins/modules/utm_ca_host_key_cert_info.py index d81eede69f..cab6657ab6 100644 --- a/plugins/modules/utm_ca_host_key_cert_info.py +++ b/plugins/modules/utm_ca_host_key_cert_info.py @@ -9,37 +9,35 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_ca_host_key_cert_info author: - - Stephan Schwarz (@stearz) + - Stephan Schwarz (@stearz) short_description: Get info for a ca host_key_cert entry in Sophos UTM description: - - Get info for a ca host_key_cert entry in SOPHOS UTM. - + - Get info for a ca host_key_cert entry in SOPHOS UTM. 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: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true extends_documentation_fragment: - - community.general.utm - - community.general.attributes - - community.general.attributes.info_module -''' + - community.general.utm + - community.general.attributes + - community.general.attributes.info_module +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Get info for a ca host_key_cert entry community.general.utm_ca_host_key_cert_info: utm_host: sophos.host.name @@ -47,42 +45,42 @@ EXAMPLES = """ name: TestHostKeyCertEntry """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - ca: - description: A reference to an existing utm_ca_signing_ca or utm_ca_verification_ca object. - type: str - meta: - description: A reference to an existing utm_ca_meta_x509 object. - type: str - certificate: - description: The certificate in PEM format - type: str - comment: - description: Comment string (may be empty string) - type: str - encrypted: - description: If encryption is enabled - type: bool - key: - description: Private key in PEM format (may be empty string) - type: str + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + ca: + description: A reference to an existing utm_ca_signing_ca or utm_ca_verification_ca object. + type: str + meta: + description: A reference to an existing utm_ca_meta_x509 object. + type: str + certificate: + description: The certificate in PEM format. + type: str + comment: + description: Comment string (may be empty string). + type: str + encrypted: + description: If encryption is enabled. + type: bool + key: + description: Private key in PEM format (may be empty string). + type: str """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_dns_host.py b/plugins/modules/utm_dns_host.py index 6b3725557b..bbb93e9eb0 100644 --- a/plugins/modules/utm_dns_host.py +++ b/plugins/modules/utm_dns_host.py @@ -8,78 +8,75 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_dns_host author: - - Johannes Brunswicker (@MatrixCrawler) + - Johannes Brunswicker (@MatrixCrawler) short_description: Create, update or destroy dns entry in Sophos UTM description: - - Create, update or destroy a dns entry in SOPHOS UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy a dns entry in SOPHOS UTM. + - This module needs to have the REST Ability of the UTM to be activated. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true - address: - type: str - description: - - The IPV4 Address of the entry. Can be left empty for automatic resolving. - default: 0.0.0.0 - address6: - type: str - description: - - The IPV6 Address of the entry. Can be left empty for automatic resolving. - default: "::" - comment: - type: str - description: - - An optional comment to add to the dns host object - default: '' - hostname: - type: str - description: - - The hostname for the dns host object - interface: - type: str - description: - - The reference name of the interface to use. If not provided the default interface will be used - default: '' - resolved: - description: - - whether the hostname's ipv4 address is already resolved or not - default: false - type: bool - resolved6: - description: - - whether the hostname's ipv6 address is already resolved or not - default: false - type: bool - timeout: - type: int - description: - - the timeout for the utm to resolve the ip address for the hostname again - default: 0 + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true + address: + type: str + description: + - The IPV4 Address of the entry. Can be left empty for automatic resolving. + default: 0.0.0.0 + address6: + type: str + description: + - The IPV6 Address of the entry. Can be left empty for automatic resolving. + default: "::" + comment: + type: str + description: + - An optional comment to add to the dns host object. + default: '' + hostname: + type: str + description: + - The hostname for the dns host object. + interface: + type: str + description: + - The reference name of the interface to use. If not provided the default interface will be used. + default: '' + resolved: + description: + - Whether the hostname's ipv4 address is already resolved or not. + default: false + type: bool + resolved6: + description: + - Whether the hostname's ipv6 address is already resolved or not. + default: false + type: bool + timeout: + type: int + description: + - The timeout for the utm to resolve the ip address for the hostname again. + default: 0 extends_documentation_fragment: -- community.general.utm -- community.general.attributes + - community.general.utm + - community.general.attributes +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Create UTM dns host entry community.general.utm_dns_host: utm_host: sophos.host.name @@ -96,45 +93,45 @@ EXAMPLES = """ state: absent """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - name: - description: The name of the object - type: str - address: - description: The ipv4 address of the object - type: str - address6: - description: The ipv6 address of the object - type: str - comment: - description: The comment string - type: str - hostname: - description: The hostname of the object - type: str - interface: - description: The reference name of the interface the object is associated with - type: str - resolved: - description: Whether the ipv4 address is resolved or not - type: bool - resolved6: - description: Whether the ipv6 address is resolved or not - type: bool - timeout: - description: The timeout until a new resolving will be attempted - type: int + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + name: + description: The name of the object. + type: str + address: + description: The ipv4 address of the object. + type: str + address6: + description: The ipv6 address of the object. + type: str + comment: + description: The comment string. + type: str + hostname: + description: The hostname of the object. + type: str + interface: + description: The reference name of the interface the object is associated with. + type: str + resolved: + description: Whether the ipv4 address is resolved or not. + type: bool + resolved6: + description: Whether the ipv6 address is resolved or not. + type: bool + timeout: + description: The timeout until a new resolving will be attempted. + type: int """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_network_interface_address.py b/plugins/modules/utm_network_interface_address.py index a85a46aeab..1e3d2ee5c3 100644 --- a/plugins/modules/utm_network_interface_address.py +++ b/plugins/modules/utm_network_interface_address.py @@ -8,62 +8,58 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_network_interface_address author: - - Juergen Wiebe (@steamx) + - Juergen Wiebe (@steamx) short_description: Create, update or destroy network/interface_address object description: - - Create, update or destroy a network/interface_address object in SOPHOS UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy a network/interface_address object in SOPHOS UTM. + - This module needs to have the REST Ability of the UTM to be activated. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true - address: - type: str - description: - - The ip4 address of the network/interface_address object. - required: true - address6: - type: str - description: - - The ip6 address of the network/interface_address object. - required: false - comment: - type: str - description: - - An optional comment to add to the object - default: '' - resolved: - type: bool - description: - - Whether or not the object is resolved - resolved6: - type: bool - description: - - Whether or not the object is resolved - + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true + address: + type: str + description: + - The ip4 address of the network/interface_address object. + required: true + address6: + type: str + description: + - The ip6 address of the network/interface_address object. + required: false + comment: + type: str + description: + - An optional comment to add to the object. + default: '' + resolved: + type: bool + description: + - Whether or not the object is resolved. + resolved6: + type: bool + description: + - Whether or not the object is resolved. extends_documentation_fragment: -- community.general.utm -- community.general.attributes + - community.general.utm + - community.general.attributes +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Create a network interface address utm_proxy_backend: utm_host: sophos.host.name @@ -81,39 +77,39 @@ EXAMPLES = """ state: absent """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - address: - description: The ip4 address of the network/interface_address object - type: str - address6: - description: The ip6 address of the network/interface_address object - type: str - comment: - description: The comment string - type: str - resolved: - description: Whether or not the object is resolved - type: bool - resolved6: - description: Whether or not the object is resolved - type: bool + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + address: + description: The ip4 address of the network/interface_address object. + type: str + address6: + description: The ip6 address of the network/interface_address object. + type: str + comment: + description: The comment string. + type: str + resolved: + description: Whether or not the object is resolved. + type: bool + resolved6: + description: Whether or not the object is resolved. + type: bool """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_network_interface_address_info.py b/plugins/modules/utm_network_interface_address_info.py index 9dc08ad094..b9c394c848 100644 --- a/plugins/modules/utm_network_interface_address_info.py +++ b/plugins/modules/utm_network_interface_address_info.py @@ -8,37 +8,35 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_network_interface_address_info author: - - Juergen Wiebe (@steamx) + - Juergen Wiebe (@steamx) short_description: Get info for a network/interface_address object description: - - Get info for a network/interface_address object in SOPHOS UTM. - + - Get info for a network/interface_address object in SOPHOS UTM. 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: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true extends_documentation_fragment: - - community.general.utm - - community.general.attributes - - community.general.attributes.info_module -''' + - community.general.utm + - community.general.attributes + - community.general.attributes.info_module +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Get network interface address info utm_proxy_interface_address_info: utm_host: sophos.host.name @@ -46,39 +44,39 @@ EXAMPLES = """ name: TestNetworkInterfaceAddress """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - address: - description: The ip4 address of the network/interface_address object - type: str - address6: - description: The ip6 address of the network/interface_address object - type: str - comment: - description: The comment string - type: str - resolved: - description: Whether or not the object is resolved - type: bool - resolved6: - description: Whether or not the object is resolved - type: bool + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + address: + description: The ip4 address of the network/interface_address object. + type: str + address6: + description: The ip6 address of the network/interface_address object. + type: str + comment: + description: The comment string. + type: str + resolved: + description: Whether or not the object is resolved. + type: bool + resolved6: + description: Whether or not the object is resolved. + type: bool """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_proxy_auth_profile.py b/plugins/modules/utm_proxy_auth_profile.py index 3b482483bf..207c4ba156 100644 --- a/plugins/modules/utm_proxy_auth_profile.py +++ b/plugins/modules/utm_proxy_auth_profile.py @@ -9,183 +9,180 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_proxy_auth_profile author: - - Stephan Schwarz (@stearz) + - Stephan Schwarz (@stearz) short_description: Create, update or destroy reverse_proxy auth_profile entry in Sophos UTM description: - - Create, update or destroy a reverse_proxy auth_profile entry in SOPHOS UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy a reverse_proxy auth_profile entry in SOPHOS UTM. + - This module needs to have the REST Ability of the UTM to be activated. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true - aaa: - type: list - elements: str - description: - - List of references to utm_aaa objects (allowed users or groups) - required: true - basic_prompt: - type: str - description: - - The message in the basic authentication prompt - required: true - backend_mode: - type: str - description: - - Specifies if the backend server needs authentication ([Basic|None]) - default: None - choices: - - Basic - - None - backend_strip_basic_auth: - description: - - Should the login data be stripped when proxying the request to the backend host - type: bool - default: true - backend_user_prefix: - type: str - description: - - Prefix string to prepend to the username for backend authentication - default: "" - backend_user_suffix: - type: str - description: - - Suffix string to append to the username for backend authentication - default: "" - comment: - type: str - description: - - Optional comment string - default: "" - frontend_cookie: - type: str - description: - - Frontend cookie name - frontend_cookie_secret: - type: str - description: - - Frontend cookie secret - frontend_form: - type: str - description: - - Frontend authentication form name - frontend_form_template: - type: str - description: - - Frontend authentication form template - default: "" - frontend_login: - type: str - description: - - Frontend login name - frontend_logout: - type: str - description: - - Frontend logout name - frontend_mode: - type: str - description: - - Frontend authentication mode (Form|Basic) - default: Basic - choices: - - Basic - - Form - frontend_realm: - type: str - description: - - Frontend authentication realm - frontend_session_allow_persistency: - description: - - Allow session persistency - type: bool - default: false - frontend_session_lifetime: - type: int - description: - - session lifetime - required: true - frontend_session_lifetime_limited: - description: - - Specifies if limitation of session lifetime is active - type: bool - default: true - frontend_session_lifetime_scope: - type: str - description: - - scope for frontend_session_lifetime (days|hours|minutes) - default: hours - choices: - - days - - hours - - minutes - frontend_session_timeout: - type: int - description: - - session timeout - required: true - frontend_session_timeout_enabled: - description: - - Specifies if session timeout is active - type: bool - default: true - frontend_session_timeout_scope: - type: str - description: - - scope for frontend_session_timeout (days|hours|minutes) - default: minutes - choices: - - days - - hours - - minutes - logout_delegation_urls: - type: list - elements: str - description: - - List of logout URLs that logouts are delegated to - default: [] - logout_mode: - type: str - description: - - Mode of logout (None|Delegation) - default: None - choices: - - None - - Delegation - redirect_to_requested_url: - description: - - Should a redirect to the requested URL be made - type: bool - default: false + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true + aaa: + type: list + elements: str + description: + - List of references to utm_aaa objects (allowed users or groups). + required: true + basic_prompt: + type: str + description: + - The message in the basic authentication prompt. + required: true + backend_mode: + type: str + description: + - Specifies if the backend server needs authentication ([Basic|None]). + default: None + choices: + - Basic + - None + backend_strip_basic_auth: + description: + - Should the login data be stripped when proxying the request to the backend host. + type: bool + default: true + backend_user_prefix: + type: str + description: + - Prefix string to prepend to the username for backend authentication. + default: "" + backend_user_suffix: + type: str + description: + - Suffix string to append to the username for backend authentication. + default: "" + comment: + type: str + description: + - Optional comment string. + default: "" + frontend_cookie: + type: str + description: + - Frontend cookie name. + frontend_cookie_secret: + type: str + description: + - Frontend cookie secret. + frontend_form: + type: str + description: + - Frontend authentication form name. + frontend_form_template: + type: str + description: + - Frontend authentication form template. + default: "" + frontend_login: + type: str + description: + - Frontend login name. + frontend_logout: + type: str + description: + - Frontend logout name. + frontend_mode: + type: str + description: + - Frontend authentication mode (Form|Basic). + default: Basic + choices: + - Basic + - Form + frontend_realm: + type: str + description: + - Frontend authentication realm. + frontend_session_allow_persistency: + description: + - Allow session persistency. + type: bool + default: false + frontend_session_lifetime: + type: int + description: + - Session lifetime. + required: true + frontend_session_lifetime_limited: + description: + - Specifies if limitation of session lifetime is active. + type: bool + default: true + frontend_session_lifetime_scope: + type: str + description: + - Scope for frontend_session_lifetime (days|hours|minutes). + default: hours + choices: + - days + - hours + - minutes + frontend_session_timeout: + type: int + description: + - Session timeout. + required: true + frontend_session_timeout_enabled: + description: + - Specifies if session timeout is active. + type: bool + default: true + frontend_session_timeout_scope: + type: str + description: + - Scope for frontend_session_timeout (days|hours|minutes). + default: minutes + choices: + - days + - hours + - minutes + logout_delegation_urls: + type: list + elements: str + description: + - List of logout URLs that logouts are delegated to. + default: [] + logout_mode: + type: str + description: + - Mode of logout (None|Delegation). + default: None + choices: + - None + - Delegation + redirect_to_requested_url: + description: + - Should a redirect to the requested URL be made. + type: bool + default: false extends_documentation_fragment: -- community.general.utm -- community.general.attributes + - community.general.utm + - community.general.attributes +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Create UTM proxy_auth_profile community.general.utm_proxy_auth_profile: utm_host: sophos.host.name utm_token: abcdefghijklmno1234 name: TestAuthProfileEntry - aaa: [REF_OBJECT_STRING,REF_ANOTHEROBJECT_STRING] + aaa: [REF_OBJECT_STRING, REF_ANOTHEROBJECT_STRING] basic_prompt: "Authentication required: Please login" frontend_session_lifetime: 1 frontend_session_timeout: 1 @@ -204,99 +201,98 @@ EXAMPLES = """ utm_token: abcdefghijklmno1234 name: TestAuthProfileEntry state: info - """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - aaa: - description: List of references to utm_aaa objects (allowed users or groups) - type: list - basic_prompt: - description: The message in the basic authentication prompt - type: str - backend_mode: - description: Specifies if the backend server needs authentication ([Basic|None]) - type: str - backend_strip_basic_auth: - description: Should the login data be stripped when proxying the request to the backend host - type: bool - backend_user_prefix: - description: Prefix string to prepend to the username for backend authentication - type: str - backend_user_suffix: - description: Suffix string to append to the username for backend authentication - type: str - comment: - description: Optional comment string - type: str - frontend_cookie: - description: Frontend cookie name - type: str - frontend_form: - description: Frontend authentication form name - type: str - frontend_form_template: - description: Frontend authentication form template - type: str - frontend_login: - description: Frontend login name - type: str - frontend_logout: - description: Frontend logout name - type: str - frontend_mode: - description: Frontend authentication mode (Form|Basic) - type: str - frontend_realm: - description: Frontend authentication realm - type: str - frontend_session_allow_persistency: - description: Allow session persistency - type: bool - frontend_session_lifetime: - description: session lifetime - type: int - frontend_session_lifetime_limited: - description: Specifies if limitation of session lifetime is active - type: bool - frontend_session_lifetime_scope: - description: scope for frontend_session_lifetime (days|hours|minutes) - type: str - frontend_session_timeout: - description: session timeout - type: int - frontend_session_timeout_enabled: - description: Specifies if session timeout is active - type: bool - frontend_session_timeout_scope: - description: scope for frontend_session_timeout (days|hours|minutes) - type: str - logout_delegation_urls: - description: List of logout URLs that logouts are delegated to - type: list - logout_mode: - description: Mode of logout (None|Delegation) - type: str - redirect_to_requested_url: - description: Should a redirect to the requested URL be made - type: bool + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + aaa: + description: List of references to utm_aaa objects (allowed users or groups). + type: list + basic_prompt: + description: The message in the basic authentication prompt. + type: str + backend_mode: + description: Specifies if the backend server needs authentication ([Basic|None]). + type: str + backend_strip_basic_auth: + description: Should the login data be stripped when proxying the request to the backend host. + type: bool + backend_user_prefix: + description: Prefix string to prepend to the username for backend authentication. + type: str + backend_user_suffix: + description: Suffix string to append to the username for backend authentication. + type: str + comment: + description: Optional comment string. + type: str + frontend_cookie: + description: Frontend cookie name. + type: str + frontend_form: + description: Frontend authentication form name. + type: str + frontend_form_template: + description: Frontend authentication form template. + type: str + frontend_login: + description: Frontend login name. + type: str + frontend_logout: + description: Frontend logout name. + type: str + frontend_mode: + description: Frontend authentication mode (Form|Basic). + type: str + frontend_realm: + description: Frontend authentication realm. + type: str + frontend_session_allow_persistency: + description: Allow session persistency. + type: bool + frontend_session_lifetime: + description: Session lifetime. + type: int + frontend_session_lifetime_limited: + description: Specifies if limitation of session lifetime is active. + type: bool + frontend_session_lifetime_scope: + description: Scope for frontend_session_lifetime (days|hours|minutes). + type: str + frontend_session_timeout: + description: Session timeout. + type: int + frontend_session_timeout_enabled: + description: Specifies if session timeout is active. + type: bool + frontend_session_timeout_scope: + description: Scope for frontend_session_timeout (days|hours|minutes). + type: str + logout_delegation_urls: + description: List of logout URLs that logouts are delegated to. + type: list + logout_mode: + description: Mode of logout (None|Delegation). + type: str + redirect_to_requested_url: + description: Should a redirect to the requested URL be made. + type: bool """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_proxy_exception.py b/plugins/modules/utm_proxy_exception.py index a0a3f85b5b..96cb592e59 100644 --- a/plugins/modules/utm_proxy_exception.py +++ b/plugins/modules/utm_proxy_exception.py @@ -9,130 +9,127 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_proxy_exception author: - - Sebastian Schenzel (@RickS-C137) + - Sebastian Schenzel (@RickS-C137) short_description: Create, update or destroy reverse_proxy exception entry in Sophos UTM description: - - Create, update or destroy a reverse_proxy exception entry in SOPHOS UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy a reverse_proxy exception entry in SOPHOS UTM. + - This module needs to have the REST Ability of the UTM to be activated. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - description: - - The name of the object. Will be used to identify the entry - required: true - type: str - op: - description: - - The operand to be used with the entries of the path parameter - default: 'AND' - choices: - - 'AND' - - 'OR' - required: false - type: str - path: - description: - - The paths the exception in the reverse proxy is defined for - type: list - elements: str - default: [] - required: false - skip_custom_threats_filters: - description: - - A list of threats to be skipped - type: list - elements: str - default: [] - required: false - skip_threats_filter_categories: - description: - - Define which categories of threats are skipped - type: list - elements: str - default: [] - required: false - skipav: - description: - - Skip the Antivirus Scanning - default: false - type: bool - required: false - skipbadclients: - description: - - Block clients with bad reputation - default: false - type: bool - required: false - skipcookie: - description: - - Skip the Cookie Signing check - default: false - type: bool - required: false - skipform: - description: - - Enable form hardening - default: false - type: bool - required: false - skipform_missingtoken: - description: - - Enable form hardening with missing tokens - default: false - type: bool - required: false - skiphtmlrewrite: - description: - - Protection against SQL - default: false - type: bool - required: false - skiptft: - description: - - Enable true file type control - default: false - type: bool - required: false - skipurl: - description: - - Enable static URL hardening - default: false - type: bool - required: false - source: - description: - - Define which categories of threats are skipped - type: list - elements: str - default: [] - required: false - status: - description: - - Status of the exception rule set - default: true - type: bool - required: false + name: + description: + - The name of the object. Will be used to identify the entry. + required: true + type: str + op: + description: + - The operand to be used with the entries of the path parameter. + default: 'AND' + choices: + - 'AND' + - 'OR' + required: false + type: str + path: + description: + - The paths the exception in the reverse proxy is defined for. + type: list + elements: str + default: [] + required: false + skip_custom_threats_filters: + description: + - A list of threats to be skipped. + type: list + elements: str + default: [] + required: false + skip_threats_filter_categories: + description: + - Define which categories of threats are skipped. + type: list + elements: str + default: [] + required: false + skipav: + description: + - Skip the Antivirus Scanning. + default: false + type: bool + required: false + skipbadclients: + description: + - Block clients with bad reputation. + default: false + type: bool + required: false + skipcookie: + description: + - Skip the Cookie Signing check. + default: false + type: bool + required: false + skipform: + description: + - Enable form hardening. + default: false + type: bool + required: false + skipform_missingtoken: + description: + - Enable form hardening with missing tokens. + default: false + type: bool + required: false + skiphtmlrewrite: + description: + - Protection against SQL. + default: false + type: bool + required: false + skiptft: + description: + - Enable true file type control. + default: false + type: bool + required: false + skipurl: + description: + - Enable static URL hardening. + default: false + type: bool + required: false + source: + description: + - Define which categories of threats are skipped. + type: list + elements: str + default: [] + required: false + status: + description: + - Status of the exception rule set. + default: true + type: bool + required: false extends_documentation_fragment: -- community.general.utm -- community.general.attributes + - community.general.utm + - community.general.attributes +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Create UTM proxy_exception community.general.utm_proxy_exception: utm_host: sophos.host.name @@ -149,66 +146,66 @@ EXAMPLES = """ state: absent """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - comment: - description: The optional comment string - type: str - op: - description: The operand to be used with the entries of the path parameter - type: str - path: - description: The paths the exception in the reverse proxy is defined for - type: list - skip_custom_threats_filters: - description: A list of threats to be skipped - type: list - skip_threats_filter_categories: - description: Define which categories of threats are skipped - type: list - skipav: - description: Skip the Antivirus Scanning - type: bool - skipbadclients: - description: Block clients with bad reputation - type: bool - skipcookie: - description: Skip the Cookie Signing check - type: bool - skipform: - description: Enable form hardening - type: bool - skipform_missingtoken: - description: Enable form hardening with missing tokens - type: bool - skiphtmlrewrite: - description: Protection against SQL - type: bool - skiptft: - description: Enable true file type control - type: bool - skipurl: - description: Enable static URL hardening - type: bool - source: - description: Define which categories of threats are skipped - type: list + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + comment: + description: The optional comment string. + type: str + op: + description: The operand to be used with the entries of the path parameter. + type: str + path: + description: The paths the exception in the reverse proxy is defined for. + type: list + skip_custom_threats_filters: + description: A list of threats to be skipped. + type: list + skip_threats_filter_categories: + description: Define which categories of threats are skipped. + type: list + skipav: + description: Skip the Antivirus Scanning. + type: bool + skipbadclients: + description: Block clients with bad reputation. + type: bool + skipcookie: + description: Skip the Cookie Signing check. + type: bool + skipform: + description: Enable form hardening. + type: bool + skipform_missingtoken: + description: Enable form hardening with missing tokens. + type: bool + skiphtmlrewrite: + description: Protection against SQL. + type: bool + skiptft: + description: Enable true file type control. + type: bool + skipurl: + description: Enable static URL hardening. + type: bool + source: + description: Define which categories of threats are skipped. + type: list """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_proxy_frontend.py b/plugins/modules/utm_proxy_frontend.py index 22a773fef8..1c3489f493 100644 --- a/plugins/modules/utm_proxy_frontend.py +++ b/plugins/modules/utm_proxy_frontend.py @@ -9,145 +9,142 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_proxy_frontend author: - - Johannes Brunswicker (@MatrixCrawler) + - Johannes Brunswicker (@MatrixCrawler) short_description: Create, update or destroy reverse_proxy frontend entry in Sophos UTM description: - - Create, update or destroy a reverse_proxy frontend entry in Sophos UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy a reverse_proxy frontend entry in Sophos UTM. + - This module needs to have the REST Ability of the UTM to be activated. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true - add_content_type_header : - description: - - Whether to add the content type header or not - type: bool - default: false - address: - type: str - description: - - The reference name of the network/interface_address object. - default: REF_DefaultInternalAddress - allowed_networks: - type: list - elements: str - description: - - A list of reference names for the allowed networks. - default: ['REF_NetworkAny'] - certificate: - type: str - description: - - The reference name of the ca/host_key_cert object. - default: "" - comment: - type: str - description: - - An optional comment to add to the object - default: "" - disable_compression: - description: - - Whether to enable the compression - type: bool - default: false - domain: - type: list - elements: str - description: - - A list of domain names for the frontend object - exceptions: - type: list - elements: str - description: - - A list of exception ref names (reverse_proxy/exception) - default: [] - htmlrewrite: - description: - - Whether to enable html rewrite or not - type: bool - default: false - htmlrewrite_cookies: - description: - - Whether to enable html rewrite cookie or not - type: bool - default: false - implicitredirect: - description: - - Whether to enable implicit redirection or not - type: bool - default: false - lbmethod: - type: str - description: - - Which loadbalancer method should be used - choices: - - "" - - bybusyness - - bytraffic - - byrequests - default: bybusyness - locations: - type: list - elements: str - description: - - A list of location ref names (reverse_proxy/location) - default: [] - port: - type: int - description: - - The frontend http port - default: 80 - preservehost: - description: - - Whether to preserve host header - type: bool - default: false - profile: - type: str - description: - - The reference string of the reverse_proxy/profile - default: "" - status: - description: - - Whether to activate the frontend entry or not - type: bool - default: true - type: - type: str - description: - - Which protocol should be used - choices: - - http - - https - default: http - xheaders: - description: - - Whether to pass the host header or not - type: bool - default: false + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true + add_content_type_header: + description: + - Whether to add the content type header or not. + type: bool + default: false + address: + type: str + description: + - The reference name of the network/interface_address object. + default: REF_DefaultInternalAddress + allowed_networks: + type: list + elements: str + description: + - A list of reference names for the allowed networks. + default: ['REF_NetworkAny'] + certificate: + type: str + description: + - The reference name of the ca/host_key_cert object. + default: "" + comment: + type: str + description: + - An optional comment to add to the object. + default: "" + disable_compression: + description: + - Whether to enable the compression. + type: bool + default: false + domain: + type: list + elements: str + description: + - A list of domain names for the frontend object. + exceptions: + type: list + elements: str + description: + - A list of exception ref names (reverse_proxy/exception). + default: [] + htmlrewrite: + description: + - Whether to enable html rewrite or not. + type: bool + default: false + htmlrewrite_cookies: + description: + - Whether to enable html rewrite cookie or not. + type: bool + default: false + implicitredirect: + description: + - Whether to enable implicit redirection or not. + type: bool + default: false + lbmethod: + type: str + description: + - Which loadbalancer method should be used. + choices: + - "" + - bybusyness + - bytraffic + - byrequests + default: bybusyness + locations: + type: list + elements: str + description: + - A list of location ref names (reverse_proxy/location). + default: [] + port: + type: int + description: + - The frontend http port. + default: 80 + preservehost: + description: + - Whether to preserve host header. + type: bool + default: false + profile: + type: str + description: + - The reference string of the reverse_proxy/profile. + default: "" + status: + description: + - Whether to activate the frontend entry or not. + type: bool + default: true + type: + type: str + description: + - Which protocol should be used. + choices: + - http + - https + default: http + xheaders: + description: + - Whether to pass the host header or not. + type: bool + default: false extends_documentation_fragment: -- community.general.utm -- community.general.attributes + - community.general.utm + - community.general.attributes +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Create utm proxy_frontend community.general.utm_proxy_frontend: utm_host: sophos.host.name @@ -164,81 +161,81 @@ EXAMPLES = """ state: absent """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - add_content_type_header: - description: Whether to add the content type header - type: bool - address: - description: The reference name of the address - type: str - allowed_networks: - description: List of reference names of networks associated - type: list - certificate: - description: Reference name of certificate (ca/host_key_cert) - type: str - comment: - description: The comment string - type: str - disable_compression: - description: State of compression support - type: bool - domain: - description: List of hostnames - type: list - exceptions: - description: List of associated proxy exceptions - type: list - htmlrewrite: - description: State of html rewrite - type: bool - htmlrewrite_cookies: - description: Whether the html rewrite cookie will be set - type: bool - implicitredirect: - description: Whether to use implicit redirection - type: bool - lbmethod: - description: The method of loadbalancer to use - type: str - locations: - description: The reference names of reverse_proxy/locations associated with the object - type: list - port: - description: The port of the frontend connection - type: int - preservehost: - description: Preserve host header - type: bool - profile: - description: The associated reverse_proxy/profile - type: str - status: - description: Whether the frontend object is active or not - type: bool - type: - description: The connection type - type: str - xheaders: - description: The xheaders state - type: bool + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + add_content_type_header: + description: Whether to add the content type header. + type: bool + address: + description: The reference name of the address. + type: str + allowed_networks: + description: List of reference names of networks associated. + type: list + certificate: + description: Reference name of certificate (ca/host_key_cert). + type: str + comment: + description: The comment string. + type: str + disable_compression: + description: State of compression support. + type: bool + domain: + description: List of hostnames. + type: list + exceptions: + description: List of associated proxy exceptions. + type: list + htmlrewrite: + description: State of html rewrite. + type: bool + htmlrewrite_cookies: + description: Whether the html rewrite cookie will be set. + type: bool + implicitredirect: + description: Whether to use implicit redirection. + type: bool + lbmethod: + description: The method of loadbalancer to use. + type: str + locations: + description: The reference names of reverse_proxy/locations associated with the object. + type: list + port: + description: The port of the frontend connection. + type: int + preservehost: + description: Preserve host header. + type: bool + profile: + description: The associated reverse_proxy/profile. + type: str + status: + description: Whether the frontend object is active or not. + type: bool + type: + description: The connection type. + type: str + xheaders: + description: The xheaders state. + type: bool """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_proxy_frontend_info.py b/plugins/modules/utm_proxy_frontend_info.py index 0435ef9494..0709cad01e 100644 --- a/plugins/modules/utm_proxy_frontend_info.py +++ b/plugins/modules/utm_proxy_frontend_info.py @@ -9,38 +9,36 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_proxy_frontend_info author: - - Johannes Brunswicker (@MatrixCrawler) + - Johannes Brunswicker (@MatrixCrawler) short_description: Create, update or destroy reverse_proxy frontend entry in Sophos UTM description: - - Create, update or destroy a reverse_proxy frontend entry in SOPHOS UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy a reverse_proxy frontend entry in SOPHOS UTM. + - This module needs to have the REST Ability of the UTM to be activated. 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: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true extends_documentation_fragment: - - community.general.utm - - community.general.attributes - - community.general.attributes.info_module -''' + - community.general.utm + - community.general.attributes + - community.general.attributes.info_module +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Get utm proxy_frontend community.general.utm_proxy_frontend_info: utm_host: sophos.host.name @@ -49,81 +47,81 @@ EXAMPLES = """ host: REF_OBJECT_STRING """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - add_content_type_header: - description: Whether to add the content type header - type: bool - address: - description: The reference name of the address - type: str - allowed_networks: - description: List of reference names of networks associated - type: list - certificate: - description: Reference name of certificate (ca/host_key_cert) - type: str - comment: - description: The comment string - type: str - disable_compression: - description: State of compression support - type: bool - domain: - description: List of hostnames - type: list - exceptions: - description: List of associated proxy exceptions - type: list - htmlrewrite: - description: State of html rewrite - type: bool - htmlrewrite_cookies: - description: whether the html rewrite cookie will be set - type: bool - implicitredirect: - description: whether to use implicit redirection - type: bool - lbmethod: - description: The method of loadbalancer to use - type: str - locations: - description: The reference names of reverse_proxy/locations associated with the object - type: list - port: - description: The port of the frontend connection - type: int - preservehost: - description: Preserve host header - type: bool - profile: - description: The associated reverse_proxy/profile - type: str - status: - description: Whether the frontend object is active or not - type: bool - type: - description: The connection type - type: str - xheaders: - description: The xheaders state - type: bool + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + add_content_type_header: + description: Whether to add the content type header. + type: bool + address: + description: The reference name of the address. + type: str + allowed_networks: + description: List of reference names of networks associated. + type: list + certificate: + description: Reference name of certificate (ca/host_key_cert). + type: str + comment: + description: The comment string. + type: str + disable_compression: + description: State of compression support. + type: bool + domain: + description: List of hostnames. + type: list + exceptions: + description: List of associated proxy exceptions. + type: list + htmlrewrite: + description: State of html rewrite. + type: bool + htmlrewrite_cookies: + description: Whether the html rewrite cookie will be set. + type: bool + implicitredirect: + description: Whether to use implicit redirection. + type: bool + lbmethod: + description: The method of loadbalancer to use. + type: str + locations: + description: The reference names of reverse_proxy/locations associated with the object. + type: list + port: + description: The port of the frontend connection. + type: int + preservehost: + description: Preserve host header. + type: bool + profile: + description: The associated reverse_proxy/profile. + type: str + status: + description: Whether the frontend object is active or not. + type: bool + type: + description: The connection type. + type: str + xheaders: + description: The xheaders state. + type: bool """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_proxy_location.py b/plugins/modules/utm_proxy_location.py index 736f564d58..944050bfb6 100644 --- a/plugins/modules/utm_proxy_location.py +++ b/plugins/modules/utm_proxy_location.py @@ -9,111 +9,108 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_proxy_location author: - - Johannes Brunswicker (@MatrixCrawler) + - Johannes Brunswicker (@MatrixCrawler) short_description: Create, update or destroy reverse_proxy location entry in Sophos UTM description: - - Create, update or destroy a reverse_proxy location entry in SOPHOS UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy a reverse_proxy location entry in SOPHOS UTM. + - This module needs to have the REST Ability of the UTM to be activated. attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true - access_control: - description: - - whether to activate the access control for the location - type: str - default: '0' - choices: - - '0' - - '1' - allowed_networks: - description: - - A list of allowed networks - type: list - elements: str - default: - - REF_NetworkAny - auth_profile: - type: str - description: - - The reference name of the auth profile - default: '' - backend: - type: list - elements: str - description: - - A list of backends that are connected with this location declaration - default: [] - be_path: - type: str - description: - - The path of the backend - default: '' - comment: - type: str - description: - - The optional comment string - default: '' - denied_networks: - type: list - elements: str - description: - - A list of denied network references - default: [] - hot_standby: - description: - - Activate hot standby mode - type: bool - default: false - path: - type: str - description: - - The path of the location - default: "/" - status: - description: - - Whether the location is active or not - type: bool - default: true - stickysession_id: - type: str - description: - - The stickysession id - default: ROUTEID - stickysession_status: - description: - - Enable the stickysession - type: bool - default: false - websocket_passthrough: - description: - - Enable the websocket passthrough - type: bool - default: false + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true + access_control: + description: + - Whether to activate the access control for the location. + type: str + default: '0' + choices: + - '0' + - '1' + allowed_networks: + description: + - A list of allowed networks. + type: list + elements: str + default: + - REF_NetworkAny + auth_profile: + type: str + description: + - The reference name of the auth profile. + default: '' + backend: + type: list + elements: str + description: + - A list of backends that are connected with this location declaration. + default: [] + be_path: + type: str + description: + - The path of the backend. + default: '' + comment: + type: str + description: + - The optional comment string. + default: '' + denied_networks: + type: list + elements: str + description: + - A list of denied network references. + default: [] + hot_standby: + description: + - Activate hot standby mode. + type: bool + default: false + path: + type: str + description: + - The path of the location. + default: "/" + status: + description: + - Whether the location is active or not. + type: bool + default: true + stickysession_id: + type: str + description: + - The stickysession id. + default: ROUTEID + stickysession_status: + description: + - Enable the stickysession. + type: bool + default: false + websocket_passthrough: + description: + - Enable the websocket passthrough. + type: bool + default: false extends_documentation_fragment: -- community.general.utm -- community.general.attributes + - community.general.utm + - community.general.attributes +""" -''' - -EXAMPLES = """ +EXAMPLES = r""" - name: Create UTM proxy_location utm_proxy_backend: utm_host: sophos.host.name @@ -130,63 +127,63 @@ EXAMPLES = """ state: absent """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - access_control: - description: Whether to use access control state - type: str - allowed_networks: - description: List of allowed network reference names - type: list - auth_profile: - description: The auth profile reference name - type: str - backend: - description: The backend reference name - type: str - be_path: - description: The backend path - type: str - comment: - description: The comment string - type: str - denied_networks: - description: The list of the denied network names - type: list - hot_standby: - description: Use hot standby - type: bool - path: - description: Path name - type: str - status: - description: Whether the object is active or not - type: bool - stickysession_id: - description: The identifier of the stickysession - type: str - stickysession_status: - description: Whether to use stickysession or not - type: bool - websocket_passthrough: - description: Whether websocket passthrough will be used or not - type: bool + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + access_control: + description: Whether to use access control state. + type: str + allowed_networks: + description: List of allowed network reference names. + type: list + auth_profile: + description: The auth profile reference name. + type: str + backend: + description: The backend reference name. + type: str + be_path: + description: The backend path. + type: str + comment: + description: The comment string. + type: str + denied_networks: + description: The list of the denied network names. + type: list + hot_standby: + description: Use hot standby. + type: bool + path: + description: Path name. + type: str + status: + description: Whether the object is active or not. + type: bool + stickysession_id: + description: The identifier of the stickysession. + type: str + stickysession_status: + description: Whether to use stickysession or not. + type: bool + websocket_passthrough: + description: Whether websocket passthrough will be used or not. + type: bool """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule diff --git a/plugins/modules/utm_proxy_location_info.py b/plugins/modules/utm_proxy_location_info.py index 4e4ba9b139..a7ea37ea79 100644 --- a/plugins/modules/utm_proxy_location_info.py +++ b/plugins/modules/utm_proxy_location_info.py @@ -9,38 +9,36 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: utm_proxy_location_info author: - - Johannes Brunswicker (@MatrixCrawler) + - Johannes Brunswicker (@MatrixCrawler) short_description: Create, update or destroy reverse_proxy location entry in Sophos UTM description: - - Create, update or destroy a reverse_proxy location entry in SOPHOS UTM. - - This module needs to have the REST Ability of the UTM to be activated. - + - Create, update or destroy a reverse_proxy location entry in SOPHOS UTM. + - This module needs to have the REST Ability of the UTM to be activated. 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: - type: str - description: - - The name of the object. Will be used to identify the entry - required: true + name: + type: str + description: + - The name of the object. Will be used to identify the entry. + required: true extends_documentation_fragment: - - community.general.utm - - community.general.attributes - - community.general.attributes.info_module -''' + - community.general.utm + - community.general.attributes + - community.general.attributes.info_module +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Remove UTM proxy_location community.general.utm_proxy_location_info: utm_host: sophos.host.name @@ -48,63 +46,63 @@ EXAMPLES = """ name: TestLocationEntry """ -RETURN = """ +RETURN = r""" result: - description: The utm object that was created - returned: success - type: complex - contains: - _ref: - description: The reference name of the object - type: str - _locked: - description: Whether or not the object is currently locked - type: bool - _type: - description: The type of the object - type: str - name: - description: The name of the object - type: str - access_control: - description: Whether to use access control state - type: str - allowed_networks: - description: List of allowed network reference names - type: list - auth_profile: - description: The auth profile reference name - type: str - backend: - description: The backend reference name - type: str - be_path: - description: The backend path - type: str - comment: - description: The comment string - type: str - denied_networks: - description: The list of the denied network names - type: list - hot_standby: - description: Use hot standby - type: bool - path: - description: Path name - type: str - status: - description: Whether the object is active or not - type: bool - stickysession_id: - description: The identifier of the stickysession - type: str - stickysession_status: - description: Whether to use stickysession or not - type: bool - websocket_passthrough: - description: Whether websocket passthrough will be used or not - type: bool + description: The utm object that was created. + returned: success + type: complex + contains: + _ref: + description: The reference name of the object. + type: str + _locked: + description: Whether or not the object is currently locked. + type: bool + _type: + description: The type of the object. + type: str + name: + description: The name of the object. + type: str + access_control: + description: Whether to use access control state. + type: str + allowed_networks: + description: List of allowed network reference names. + type: list + auth_profile: + description: The auth profile reference name. + type: str + backend: + description: The backend reference name. + type: str + be_path: + description: The backend path. + type: str + comment: + description: The comment string. + type: str + denied_networks: + description: The list of the denied network names. + type: list + hot_standby: + description: Use hot standby. + type: bool + path: + description: Path name. + type: str + status: + description: Whether the object is active or not. + type: bool + stickysession_id: + description: The identifier of the stickysession. + type: str + stickysession_status: + description: Whether to use stickysession or not. + type: bool + websocket_passthrough: + description: Whether websocket passthrough will be used or not. + type: bool """ from ansible_collections.community.general.plugins.module_utils.utm_utils import UTM, UTMModule From 12f2d719502565e8eca74b2b42a44235cac9a1a2 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 24 Dec 2024 13:04:53 +0000 Subject: [PATCH 081/302] [PR #9338/2005125a backport][stable-10] u[a-s]*: normalize docs (#9361) u[a-s]*: normalize docs (#9338) * u[a-s]*: normalize docs * Update plugins/modules/udm_dns_record.py Co-authored-by: Felix Fontein * Update plugins/modules/udm_dns_record.py Co-authored-by: Felix Fontein * Update plugins/modules/udm_dns_record.py Co-authored-by: Felix Fontein * Update plugins/modules/udm_dns_zone.py Co-authored-by: Felix Fontein * Update plugins/modules/ufw.py Co-authored-by: Felix Fontein * Apply suggestions from code review Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 2005125af4bfc7b45a729151f7a5e202d20369be) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/udm_dns_record.py | 99 +++-- plugins/modules/udm_dns_zone.py | 152 ++++--- plugins/modules/udm_group.py | 96 +++-- plugins/modules/udm_share.py | 630 +++++++++++++++--------------- plugins/modules/udm_user.py | 550 +++++++++++++------------- plugins/modules/ufw.py | 112 +++--- plugins/modules/uptimerobot.py | 57 ++- plugins/modules/urpmi.py | 25 +- plugins/modules/usb_facts.py | 13 +- 9 files changed, 846 insertions(+), 888 deletions(-) diff --git a/plugins/modules/udm_dns_record.py b/plugins/modules/udm_dns_record.py index 857792993d..a87ce5fede 100644 --- a/plugins/modules/udm_dns_record.py +++ b/plugins/modules/udm_dns_record.py @@ -10,63 +10,60 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: udm_dns_record author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage dns entries on a univention corporate server description: - - "This module allows to manage dns records on a univention corporate server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage dns records on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object + or edit it. requirements: - - Univention - - ipaddress (for O(type=ptr_record)) + - Univention + - ipaddress (for O(type=ptr_record)) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - type: str - default: "present" - choices: [ present, absent ] - description: - - Whether the dns record is present or not. - name: - type: str - required: true - description: - - "Name of the record, this is also the DNS record. E.g. www for - www.example.com." - - For PTR records this has to be the IP address. - zone: - type: str - required: true - description: - - Corresponding DNS zone for this record, e.g. example.com. - - For PTR records this has to be the full reverse zone (for example V(1.1.192.in-addr.arpa)). - type: - type: str - required: true - description: - - "Define the record type. V(host_record) is a A or AAAA record, - V(alias) is a CNAME, V(ptr_record) is a PTR record, V(srv_record) - is a SRV record and V(txt_record) is a TXT record." - - "The available choices are: V(host_record), V(alias), V(ptr_record), V(srv_record), V(txt_record)." - data: - type: dict - default: {} - description: - - "Additional data for this record, for example V({'a': '192.0.2.1'})." - - Required if O(state=present). -''' + state: + type: str + default: "present" + choices: [present, absent] + description: + - Whether the dns record is present or not. + name: + type: str + required: true + description: + - Name of the record, this is also the DNS record. For example V(www) for www.example.com. + - For PTR records this has to be the IP address. + zone: + type: str + required: true + description: + - Corresponding DNS zone for this record, for example V(example.com). + - For PTR records this has to be the full reverse zone (for example V(1.1.192.in-addr.arpa)). + type: + type: str + required: true + description: + - Define the record type. V(host_record) is a A or AAAA record, V(alias) is a CNAME, V(ptr_record) is a PTR record, V(srv_record) is a SRV + record and V(txt_record) is a TXT record. + - 'The available choices are: V(host_record), V(alias), V(ptr_record), V(srv_record), V(txt_record).' + data: + type: dict + default: {} + description: + - "Additional data for this record, for example V({'a': '192.0.2.1'})." + - Required if O(state=present). +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a DNS record on a UCS community.general.udm_dns_record: name: www @@ -74,8 +71,8 @@ EXAMPLES = ''' type: host_record data: a: - - 192.0.2.1 - - 2001:0db8::42 + - 192.0.2.1 + - 2001:0db8::42 - name: Create a DNS v4 PTR record on a UCS community.general.udm_dns_record: @@ -92,10 +89,10 @@ EXAMPLES = ''' type: ptr_record data: ptr_record: "www.example.com." -''' +""" -RETURN = '''#''' +RETURN = """#""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/udm_dns_zone.py b/plugins/modules/udm_dns_zone.py index 387d5cc45b..765f996aba 100644 --- a/plugins/modules/udm_dns_zone.py +++ b/plugins/modules/udm_dns_zone.py @@ -10,91 +10,87 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: udm_dns_zone author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage dns zones on a univention corporate server description: - - "This module allows to manage dns zones on a univention corporate server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage dns zones on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object or + edit it. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - type: str - default: "present" - choices: [ present, absent ] - description: - - Whether the dns zone is present or not. - type: - type: str - required: true - description: - - Define if the zone is a forward or reverse DNS zone. - - "The available choices are: V(forward_zone), V(reverse_zone)." - zone: - type: str - required: true - description: - - DNS zone name, for example V(example.com). - aliases: [name] - nameserver: - type: list - elements: str - default: [] - description: - - List of appropriate name servers. Required if O(state=present). - interfaces: - type: list - elements: str - default: [] - description: - - List of interface IP addresses, on which the server should - response this zone. Required if O(state=present). - - refresh: - type: int - default: 3600 - description: - - Interval before the zone should be refreshed. - retry: - type: int - default: 1800 - description: - - Interval that should elapse before a failed refresh should be retried. - expire: - type: int - default: 604800 - description: - - Specifies the upper limit on the time interval that can elapse before the zone is no longer authoritative. - ttl: - type: int - default: 600 - description: - - Minimum TTL field that should be exported with any RR from this zone. - - contact: - type: str - default: '' - description: - - Contact person in the SOA record. - mx: - type: list - elements: str - default: [] - description: - - List of MX servers. (Must declared as A or AAAA records). -''' + state: + type: str + default: "present" + choices: [present, absent] + description: + - Whether the DNS zone is present or not. + type: + type: str + required: true + description: + - Define if the zone is a forward or reverse DNS zone. + - 'The available choices are: V(forward_zone), V(reverse_zone).' + zone: + type: str + required: true + description: + - DNS zone name, for example V(example.com). + aliases: [name] + nameserver: + type: list + elements: str + default: [] + description: + - List of appropriate name servers. Required if O(state=present). + interfaces: + type: list + elements: str + default: [] + description: + - List of interface IP addresses, on which the server should response this zone. Required if O(state=present). + refresh: + type: int + default: 3600 + description: + - Interval before the zone should be refreshed. + retry: + type: int + default: 1800 + description: + - Interval that should elapse before a failed refresh should be retried. + expire: + type: int + default: 604800 + description: + - Specifies the upper limit on the time interval that can elapse before the zone is no longer authoritative. + ttl: + type: int + default: 600 + description: + - Minimum TTL field that should be exported with any RR from this zone. + contact: + type: str + default: '' + description: + - Contact person in the SOA record. + mx: + type: list + elements: str + default: [] + description: + - List of MX servers. (Must declared as A or AAAA records). +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a DNS zone on a UCS community.general.udm_dns_zone: zone: example.com @@ -103,10 +99,10 @@ EXAMPLES = ''' - ucs.example.com interfaces: - 192.0.2.1 -''' +""" -RETURN = '''# ''' +RETURN = """# """ from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.univention_umc import ( diff --git a/plugins/modules/udm_group.py b/plugins/modules/udm_group.py index 5fe2422f8b..238b0182ed 100644 --- a/plugins/modules/udm_group.py +++ b/plugins/modules/udm_group.py @@ -10,63 +10,61 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: udm_group author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage of the posix group description: - - "This module allows to manage user groups on a univention corporate server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage user groups on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object + or edit it. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - required: false - default: "present" - choices: [ present, absent ] - description: - - Whether the group is present or not. - type: str - name: - required: true - description: - - Name of the posix group. - type: str + state: + required: false + default: "present" + choices: [present, absent] description: - required: false - description: - - Group description. - type: str - position: - required: false - description: - - define the whole ldap position of the group, e.g. - C(cn=g123m-1A,cn=classes,cn=schueler,cn=groups,ou=schule,dc=example,dc=com). - type: str - default: '' - ou: - required: false - description: - - LDAP OU, e.g. school for LDAP OU C(ou=school,dc=example,dc=com). - type: str - default: '' - subpath: - required: false - description: - - Subpath inside the OU, e.g. C(cn=classes,cn=students,cn=groups). - type: str - default: "cn=groups" -''' + - Whether the group is present or not. + type: str + name: + required: true + description: + - Name of the POSIX group. + type: str + description: + required: false + description: + - Group description. + type: str + position: + required: false + description: + - Define the whole LDAP position of the group, for example V(cn=g123m-1A,cn=classes,cn=schueler,cn=groups,ou=schule,dc=example,dc=com). + type: str + default: '' + ou: + required: false + description: + - LDAP OU, for example V(school) for LDAP OU V(ou=school,dc=example,dc=com). + type: str + default: '' + subpath: + required: false + description: + - Subpath inside the OU, for example V(cn=classes,cn=students,cn=groups). + type: str + default: "cn=groups" +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a POSIX group community.general.udm_group: name: g123m-1A @@ -84,10 +82,10 @@ EXAMPLES = ''' community.general.udm_group: name: g123m-1A position: 'cn=classes,cn=students,cn=groups,ou=school,dc=school,dc=example,dc=com' -''' +""" -RETURN = '''# ''' +RETURN = """# """ from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.univention_umc import ( diff --git a/plugins/modules/udm_share.py b/plugins/modules/udm_share.py index 8ae243b3de..3489607b09 100644 --- a/plugins/modules/udm_share.py +++ b/plugins/modules/udm_share.py @@ -10,339 +10,337 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: udm_share author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage samba shares on a univention corporate server description: - - "This module allows to manage samba shares on a univention corporate - server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage samba shares on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object + or edit it. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - default: "present" - choices: [ present, absent ] - description: - - Whether the share is present or not. - type: str - name: - required: true - description: - - Name - type: str - host: - required: false - description: - - Host FQDN (server which provides the share), for example V({{ ansible_fqdn }}). Required if O(state=present). - type: str - path: - required: false - description: - - Directory on the providing server, for example V(/home). Required if O(state=present). - type: path - sambaName: - required: false - description: - - Windows name. Required if O(state=present). - type: str - aliases: [ samba_name ] - ou: - required: true - description: - - Organisational unit, inside the LDAP Base DN. - type: str - owner: - default: '0' - description: - - Directory owner of the share's root directory. - type: str - group: - default: '0' - description: - - Directory owner group of the share's root directory. - type: str - directorymode: - default: '00755' - description: - - Permissions for the share's root directory. - type: str - root_squash: - default: true - description: - - Modify user ID for root user (root squashing). - type: bool - subtree_checking: - default: true - description: - - Subtree checking. - type: bool - sync: - default: 'sync' - description: - - NFS synchronisation. - type: str - writeable: - default: true - description: - - NFS write access. - type: bool - sambaBlockSize: - description: - - Blocking size. - type: str - aliases: [ samba_block_size ] - sambaBlockingLocks: - default: true - description: - - Blocking locks. - type: bool - aliases: [ samba_blocking_locks ] - sambaBrowseable: - description: - - Show in Windows network environment. - type: bool - default: true - aliases: [ samba_browsable ] - sambaCreateMode: - default: '0744' - description: - - File mode. - type: str - aliases: [ samba_create_mode ] - sambaCscPolicy: - default: 'manual' - description: - - Client-side caching policy. - type: str - aliases: [ samba_csc_policy ] - sambaCustomSettings: - default: [] - description: - - Option name in smb.conf and its value. - type: list - elements: dict - aliases: [ samba_custom_settings ] - sambaDirectoryMode: - default: '0755' - description: - - Directory mode. - type: str - aliases: [ samba_directory_mode ] - sambaDirectorySecurityMode: - default: '0777' - description: - - Directory security mode. - type: str - aliases: [ samba_directory_security_mode ] - sambaDosFilemode: - default: false - description: - - Users with write access may modify permissions. - type: bool - aliases: [ samba_dos_filemode ] - sambaFakeOplocks: - default: false - description: - - Fake oplocks. - type: bool - aliases: [ samba_fake_oplocks ] - sambaForceCreateMode: - default: false - description: - - Force file mode. - type: bool - aliases: [ samba_force_create_mode ] - sambaForceDirectoryMode: - default: false - description: - - Force directory mode. - type: bool - aliases: [ samba_force_directory_mode ] - sambaForceDirectorySecurityMode: - default: false - description: - - Force directory security mode. - type: bool - aliases: [ samba_force_directory_security_mode ] - sambaForceGroup: - description: - - Force group. - type: str - aliases: [ samba_force_group ] - sambaForceSecurityMode: - default: false - description: - - Force security mode. - type: bool - aliases: [ samba_force_security_mode ] - sambaForceUser: - description: - - Force user. - type: str - aliases: [ samba_force_user ] - sambaHideFiles: - description: - - Hide files. - type: str - aliases: [ samba_hide_files ] - sambaHideUnreadable: - default: false - description: - - Hide unreadable files/directories. - type: bool - aliases: [ samba_hide_unreadable ] - sambaHostsAllow: - default: [] - description: - - Allowed host/network. - type: list - elements: str - aliases: [ samba_hosts_allow ] - sambaHostsDeny: - default: [] - description: - - Denied host/network. - type: list - elements: str - aliases: [ samba_hosts_deny ] - sambaInheritAcls: - default: true - description: - - Inherit ACLs. - type: bool - aliases: [ samba_inherit_acls ] - sambaInheritOwner: - default: false - description: - - Create files/directories with the owner of the parent directory. - type: bool - aliases: [ samba_inherit_owner ] - sambaInheritPermissions: - default: false - description: - - Create files/directories with permissions of the parent directory. - type: bool - aliases: [ samba_inherit_permissions ] - sambaInvalidUsers: - description: - - Invalid users or groups. - type: str - aliases: [ samba_invalid_users ] - sambaLevel2Oplocks: - default: true - description: - - Level 2 oplocks. - type: bool - aliases: [ samba_level_2_oplocks ] - sambaLocking: - default: true - description: - - Locking. - type: bool - aliases: [ samba_locking ] - sambaMSDFSRoot: - default: false - description: - - MSDFS root. - type: bool - aliases: [ samba_msdfs_root ] - sambaNtAclSupport: - default: true - description: - - NT ACL support. - type: bool - aliases: [ samba_nt_acl_support ] - sambaOplocks: - default: true - description: - - Oplocks. - type: bool - aliases: [ samba_oplocks ] - sambaPostexec: - description: - - Postexec script. - type: str - aliases: [ samba_postexec ] - sambaPreexec: - description: - - Preexec script. - type: str - aliases: [ samba_preexec ] - sambaPublic: - default: false - description: - - Allow anonymous read-only access with a guest user. - type: bool - aliases: [ samba_public ] - sambaSecurityMode: - default: '0777' - description: - - Security mode. - type: str - aliases: [ samba_security_mode ] - sambaStrictLocking: - default: 'Auto' - description: - - Strict locking. - type: str - aliases: [ samba_strict_locking ] - sambaVFSObjects: - description: - - VFS objects. - type: str - aliases: [ samba_vfs_objects ] - sambaValidUsers: - description: - - Valid users or groups. - type: str - aliases: [ samba_valid_users ] - sambaWriteList: - description: - - Restrict write access to these users/groups. - type: str - aliases: [ samba_write_list ] - sambaWriteable: - default: true - description: - - Samba write access. - type: bool - aliases: [ samba_writeable ] - nfs_hosts: - default: [] - description: - - Only allow access for this host, IP address or network. - type: list - elements: str - nfsCustomSettings: - default: [] - description: - - Option name in exports file. - type: list - elements: str - aliases: [ nfs_custom_settings ] -''' + state: + default: "present" + choices: [present, absent] + description: + - Whether the share is present or not. + type: str + name: + required: true + description: + - Name. + type: str + host: + required: false + description: + - Host FQDN (server which provides the share), for example V({{ ansible_fqdn }}). Required if O(state=present). + type: str + path: + required: false + description: + - Directory on the providing server, for example V(/home). Required if O(state=present). + type: path + sambaName: + required: false + description: + - Windows name. Required if O(state=present). + type: str + aliases: [samba_name] + ou: + required: true + description: + - Organisational unit, inside the LDAP Base DN. + type: str + owner: + default: '0' + description: + - Directory owner of the share's root directory. + type: str + group: + default: '0' + description: + - Directory owner group of the share's root directory. + type: str + directorymode: + default: '00755' + description: + - Permissions for the share's root directory. + type: str + root_squash: + default: true + description: + - Modify user ID for root user (root squashing). + type: bool + subtree_checking: + default: true + description: + - Subtree checking. + type: bool + sync: + default: 'sync' + description: + - NFS synchronisation. + type: str + writeable: + default: true + description: + - NFS write access. + type: bool + sambaBlockSize: + description: + - Blocking size. + type: str + aliases: [samba_block_size] + sambaBlockingLocks: + default: true + description: + - Blocking locks. + type: bool + aliases: [samba_blocking_locks] + sambaBrowseable: + description: + - Show in Windows network environment. + type: bool + default: true + aliases: [samba_browsable] + sambaCreateMode: + default: '0744' + description: + - File mode. + type: str + aliases: [samba_create_mode] + sambaCscPolicy: + default: 'manual' + description: + - Client-side caching policy. + type: str + aliases: [samba_csc_policy] + sambaCustomSettings: + default: [] + description: + - Option name in smb.conf and its value. + type: list + elements: dict + aliases: [samba_custom_settings] + sambaDirectoryMode: + default: '0755' + description: + - Directory mode. + type: str + aliases: [samba_directory_mode] + sambaDirectorySecurityMode: + default: '0777' + description: + - Directory security mode. + type: str + aliases: [samba_directory_security_mode] + sambaDosFilemode: + default: false + description: + - Users with write access may modify permissions. + type: bool + aliases: [samba_dos_filemode] + sambaFakeOplocks: + default: false + description: + - Fake oplocks. + type: bool + aliases: [samba_fake_oplocks] + sambaForceCreateMode: + default: false + description: + - Force file mode. + type: bool + aliases: [samba_force_create_mode] + sambaForceDirectoryMode: + default: false + description: + - Force directory mode. + type: bool + aliases: [samba_force_directory_mode] + sambaForceDirectorySecurityMode: + default: false + description: + - Force directory security mode. + type: bool + aliases: [samba_force_directory_security_mode] + sambaForceGroup: + description: + - Force group. + type: str + aliases: [samba_force_group] + sambaForceSecurityMode: + default: false + description: + - Force security mode. + type: bool + aliases: [samba_force_security_mode] + sambaForceUser: + description: + - Force user. + type: str + aliases: [samba_force_user] + sambaHideFiles: + description: + - Hide files. + type: str + aliases: [samba_hide_files] + sambaHideUnreadable: + default: false + description: + - Hide unreadable files/directories. + type: bool + aliases: [samba_hide_unreadable] + sambaHostsAllow: + default: [] + description: + - Allowed host/network. + type: list + elements: str + aliases: [samba_hosts_allow] + sambaHostsDeny: + default: [] + description: + - Denied host/network. + type: list + elements: str + aliases: [samba_hosts_deny] + sambaInheritAcls: + default: true + description: + - Inherit ACLs. + type: bool + aliases: [samba_inherit_acls] + sambaInheritOwner: + default: false + description: + - Create files/directories with the owner of the parent directory. + type: bool + aliases: [samba_inherit_owner] + sambaInheritPermissions: + default: false + description: + - Create files/directories with permissions of the parent directory. + type: bool + aliases: [samba_inherit_permissions] + sambaInvalidUsers: + description: + - Invalid users or groups. + type: str + aliases: [samba_invalid_users] + sambaLevel2Oplocks: + default: true + description: + - Level 2 oplocks. + type: bool + aliases: [samba_level_2_oplocks] + sambaLocking: + default: true + description: + - Locking. + type: bool + aliases: [samba_locking] + sambaMSDFSRoot: + default: false + description: + - MSDFS root. + type: bool + aliases: [samba_msdfs_root] + sambaNtAclSupport: + default: true + description: + - NT ACL support. + type: bool + aliases: [samba_nt_acl_support] + sambaOplocks: + default: true + description: + - Oplocks. + type: bool + aliases: [samba_oplocks] + sambaPostexec: + description: + - Postexec script. + type: str + aliases: [samba_postexec] + sambaPreexec: + description: + - Preexec script. + type: str + aliases: [samba_preexec] + sambaPublic: + default: false + description: + - Allow anonymous read-only access with a guest user. + type: bool + aliases: [samba_public] + sambaSecurityMode: + default: '0777' + description: + - Security mode. + type: str + aliases: [samba_security_mode] + sambaStrictLocking: + default: 'Auto' + description: + - Strict locking. + type: str + aliases: [samba_strict_locking] + sambaVFSObjects: + description: + - VFS objects. + type: str + aliases: [samba_vfs_objects] + sambaValidUsers: + description: + - Valid users or groups. + type: str + aliases: [samba_valid_users] + sambaWriteList: + description: + - Restrict write access to these users/groups. + type: str + aliases: [samba_write_list] + sambaWriteable: + default: true + description: + - Samba write access. + type: bool + aliases: [samba_writeable] + nfs_hosts: + default: [] + description: + - Only allow access for this host, IP address or network. + type: list + elements: str + nfsCustomSettings: + default: [] + description: + - Option name in exports file. + type: list + elements: str + aliases: [nfs_custom_settings] +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a share named home on the server ucs.example.com with the path /home community.general.udm_share: name: home path: /home host: ucs.example.com sambaName: Home -''' +""" -RETURN = '''# ''' +RETURN = """# """ from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.univention_umc import ( diff --git a/plugins/modules/udm_user.py b/plugins/modules/udm_user.py index 5257a22028..bb431ca75f 100644 --- a/plugins/modules/udm_user.py +++ b/plugins/modules/udm_user.py @@ -10,297 +10,285 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: udm_user author: - - Tobias Rüetschi (@keachi) + - Tobias Rüetschi (@keachi) short_description: Manage posix users on a univention corporate server description: - - "This module allows to manage posix users on a univention corporate - server (UCS). - It uses the python API of the UCS to create a new object or edit it." + - This module allows to manage posix users on a univention corporate server (UCS). It uses the Python API of the UCS to create a new object + or edit it. 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: partial + check_mode: + support: full + diff_mode: + support: partial options: - state: - default: "present" - choices: [ present, absent ] - description: - - Whether the user is present or not. - type: str - username: - required: true - description: - - User name - aliases: ['name'] - type: str - firstname: - description: - - First name. Required if O(state=present). - type: str - lastname: - description: - - Last name. Required if O(state=present). - type: str - password: - description: - - Password. Required if O(state=present). - type: str - birthday: - description: - - Birthday - type: str - city: - description: - - City of users business address. - type: str - country: - description: - - Country of users business address. - type: str - department_number: - description: - - Department number of users business address. - aliases: [ departmentNumber ] - type: str + state: + default: "present" + choices: [present, absent] description: - description: - - Description (not gecos) - type: str - display_name: - description: - - Display name (not gecos) - aliases: [ displayName ] - type: str - email: - default: [''] - description: - - A list of e-mail addresses. - type: list - elements: str - employee_number: - description: - - Employee number - aliases: [ employeeNumber ] - type: str - employee_type: - description: - - Employee type - aliases: [ employeeType ] - type: str - gecos: - description: - - GECOS - type: str - groups: - default: [] - description: - - "POSIX groups, the LDAP DNs of the groups will be found with the - LDAP filter for each group as $GROUP: - V((&(objectClass=posixGroup\\)(cn=$GROUP\\)\\))." - type: list - elements: str - home_share: - description: - - "Home NFS share. Must be a LDAP DN, e.g. - V(cn=home,cn=shares,ou=school,dc=example,dc=com)." - aliases: [ homeShare ] - type: str - home_share_path: - description: - - Path to home NFS share, inside the homeShare. - aliases: [ homeSharePath ] - type: str - home_telephone_number: - default: [] - description: - - List of private telephone numbers. - aliases: [ homeTelephoneNumber ] - type: list - elements: str - homedrive: - description: - - Windows home drive, for example V("H:"). - type: str - mail_alternative_address: - default: [] - description: - - List of alternative e-mail addresses. - aliases: [ mailAlternativeAddress ] - type: list - elements: str - mail_home_server: - description: - - FQDN of mail server - aliases: [ mailHomeServer ] - type: str - mail_primary_address: - description: - - Primary e-mail address - aliases: [ mailPrimaryAddress ] - type: str - mobile_telephone_number: - default: [] - description: - - Mobile phone number - aliases: [ mobileTelephoneNumber ] - type: list - elements: str - organisation: - description: - - Organisation - aliases: [ organization ] - type: str - overridePWHistory: - type: bool - default: false - description: - - Override password history - aliases: [ override_pw_history ] - overridePWLength: - type: bool - default: false - description: - - Override password check - aliases: [ override_pw_length ] - pager_telephonenumber: - default: [] - description: - - List of pager telephone numbers. - aliases: [ pagerTelephonenumber ] - type: list - elements: str - phone: - description: - - List of telephone numbers. - type: list - elements: str - default: [] - postcode: - description: - - Postal code of users business address. - type: str - primary_group: - description: - - Primary group. This must be the group LDAP DN. - - If not specified, it defaults to V(cn=Domain Users,cn=groups,$LDAP_BASE_DN). - aliases: [ primaryGroup ] - type: str - profilepath: - description: - - Windows profile directory - type: str - pwd_change_next_login: - choices: [ '0', '1' ] - description: - - Change password on next login. - aliases: [ pwdChangeNextLogin ] - type: str - room_number: - description: - - Room number of users business address. - aliases: [ roomNumber ] - type: str - samba_privileges: - description: - - "Samba privilege, like allow printer administration, do domain - join." - aliases: [ sambaPrivileges ] - type: list - elements: str - default: [] - samba_user_workstations: - description: - - Allow the authentication only on this Microsoft Windows host. - aliases: [ sambaUserWorkstations ] - type: list - elements: str - default: [] - sambahome: - description: - - Windows home path, for example V('\\\\$FQDN\\$USERNAME'). - type: str - scriptpath: - description: - - Windows logon script. - type: str - secretary: - default: [] - description: - - A list of superiors as LDAP DNs. - type: list - elements: str - serviceprovider: - default: [''] - description: - - Enable user for the following service providers. - type: list - elements: str - shell: - default: '/bin/bash' - description: - - Login shell - type: str - street: - description: - - Street of users business address. - type: str - title: - description: - - Title, for example V(Prof.). - type: str - unixhome: - description: - - Unix home directory - - If not specified, it defaults to C(/home/$USERNAME). - type: str - userexpiry: - description: - - Account expiry date, for example V(1999-12-31). - - If not specified, it defaults to the current day plus one year. - type: str - position: - default: '' - description: - - "Define the whole position of users object inside the LDAP tree, - for example V(cn=employee,cn=users,ou=school,dc=example,dc=com)." - type: str - update_password: - default: always - choices: [ always, on_create ] - description: - - "V(always) will update passwords if they differ. - V(on_create) will only set the password for newly created users." - type: str - ou: - default: '' - description: - - "Organizational Unit inside the LDAP Base DN, for example V(school) for - LDAP OU C(ou=school,dc=example,dc=com)." - type: str - subpath: - default: 'cn=users' - description: - - "LDAP subpath inside the organizational unit, for example - V(cn=teachers,cn=users) for LDAP container - C(cn=teachers,cn=users,dc=example,dc=com)." - type: str -''' + - Whether the user is present or not. + type: str + username: + required: true + description: + - User name. + aliases: ['name'] + type: str + firstname: + description: + - First name. Required if O(state=present). + type: str + lastname: + description: + - Last name. Required if O(state=present). + type: str + password: + description: + - Password. Required if O(state=present). + type: str + birthday: + description: + - Birthday. + type: str + city: + description: + - City of users business address. + type: str + country: + description: + - Country of users business address. + type: str + department_number: + description: + - Department number of users business address. + aliases: [departmentNumber] + type: str + description: + description: + - Description (not gecos). + type: str + display_name: + description: + - Display name (not gecos). + aliases: [displayName] + type: str + email: + default: [''] + description: + - A list of e-mail addresses. + type: list + elements: str + employee_number: + description: + - Employee number. + aliases: [employeeNumber] + type: str + employee_type: + description: + - Employee type. + aliases: [employeeType] + type: str + gecos: + description: + - GECOS. + type: str + groups: + default: [] + description: + - 'POSIX groups, the LDAP DNs of the groups will be found with the LDAP filter for each group as $GROUP: V((&(objectClass=posixGroup\)(cn=$GROUP\)\)).' + type: list + elements: str + home_share: + description: + - Home NFS share. Must be a LDAP DN, for example V(cn=home,cn=shares,ou=school,dc=example,dc=com). + aliases: [homeShare] + type: str + home_share_path: + description: + - Path to home NFS share, inside the homeShare. + aliases: [homeSharePath] + type: str + home_telephone_number: + default: [] + description: + - List of private telephone numbers. + aliases: [homeTelephoneNumber] + type: list + elements: str + homedrive: + description: + - Windows home drive, for example V("H:"). + type: str + mail_alternative_address: + default: [] + description: + - List of alternative e-mail addresses. + aliases: [mailAlternativeAddress] + type: list + elements: str + mail_home_server: + description: + - FQDN of mail server. + aliases: [mailHomeServer] + type: str + mail_primary_address: + description: + - Primary e-mail address. + aliases: [mailPrimaryAddress] + type: str + mobile_telephone_number: + default: [] + description: + - Mobile phone number. + aliases: [mobileTelephoneNumber] + type: list + elements: str + organisation: + description: + - Organisation. + aliases: [organization] + type: str + overridePWHistory: + type: bool + default: false + description: + - Override password history. + aliases: [override_pw_history] + overridePWLength: + type: bool + default: false + description: + - Override password check. + aliases: [override_pw_length] + pager_telephonenumber: + default: [] + description: + - List of pager telephone numbers. + aliases: [pagerTelephonenumber] + type: list + elements: str + phone: + description: + - List of telephone numbers. + type: list + elements: str + default: [] + postcode: + description: + - Postal code of users business address. + type: str + primary_group: + description: + - Primary group. This must be the group LDAP DN. + - If not specified, it defaults to V(cn=Domain Users,cn=groups,$LDAP_BASE_DN). + aliases: [primaryGroup] + type: str + profilepath: + description: + - Windows profile directory. + type: str + pwd_change_next_login: + choices: ['0', '1'] + description: + - Change password on next login. + aliases: [pwdChangeNextLogin] + type: str + room_number: + description: + - Room number of users business address. + aliases: [roomNumber] + type: str + samba_privileges: + description: + - Samba privilege, like allow printer administration, do domain join. + aliases: [sambaPrivileges] + type: list + elements: str + default: [] + samba_user_workstations: + description: + - Allow the authentication only on this Microsoft Windows host. + aliases: [sambaUserWorkstations] + type: list + elements: str + default: [] + sambahome: + description: + - Windows home path, for example V('\\\\$FQDN\\$USERNAME'). + type: str + scriptpath: + description: + - Windows logon script. + type: str + secretary: + default: [] + description: + - A list of superiors as LDAP DNs. + type: list + elements: str + serviceprovider: + default: [''] + description: + - Enable user for the following service providers. + type: list + elements: str + shell: + default: '/bin/bash' + description: + - Login shell. + type: str + street: + description: + - Street of users business address. + type: str + title: + description: + - Title, for example V(Prof.). + type: str + unixhome: + description: + - Unix home directory. + - If not specified, it defaults to C(/home/$USERNAME). + type: str + userexpiry: + description: + - Account expiry date, for example V(1999-12-31). + - If not specified, it defaults to the current day plus one year. + type: str + position: + default: '' + description: + - Define the whole position of users object inside the LDAP tree, for example V(cn=employee,cn=users,ou=school,dc=example,dc=com). + type: str + update_password: + default: always + choices: [always, on_create] + description: + - V(always) will update passwords if they differ. V(on_create) will only set the password for newly created users. + type: str + ou: + default: '' + description: + - Organizational Unit inside the LDAP Base DN, for example V(school) for LDAP OU C(ou=school,dc=example,dc=com). + type: str + subpath: + default: 'cn=users' + description: + - LDAP subpath inside the organizational unit, for example V(cn=teachers,cn=users) for LDAP container C(cn=teachers,cn=users,dc=example,dc=com). + type: str +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a user on a UCS community.general.udm_user: name: FooBar @@ -325,10 +313,10 @@ EXAMPLES = ''' firstname: Foo lastname: Bar position: 'cn=teachers,cn=users,ou=school,dc=school,dc=example,dc=com' -''' +""" -RETURN = '''# ''' +RETURN = """# """ from datetime import date, timedelta import traceback diff --git a/plugins/modules/ufw.py b/plugins/modules/ufw.py index fba0ef5fe2..e0d765eeac 100644 --- a/plugins/modules/ufw.py +++ b/plugins/modules/ufw.py @@ -11,26 +11,24 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: ufw short_description: Manage firewall with UFW description: - - Manage firewall with UFW. + - Manage firewall with UFW. author: - - Aleksey Ovcharenko (@ovcharenko) - - Jarno Keskikangas (@pyykkis) - - Ahti Kitsik (@ahtik) + - Aleksey Ovcharenko (@ovcharenko) + - Jarno Keskikangas (@pyykkis) + - Ahti Kitsik (@ahtik) notes: - - See C(man ufw) for more examples. - - > - B(Warning:) Whilst the module itself can be run using concurrent strategies, C(ufw) does not support concurrency, - as firewall rules are meant to be ordered and parallel executions do not guarantee order. - B(Do not use concurrency:) The results are unpredictable and the module may fail silently if you do. + - See C(man ufw) for more examples. + - "B(Warning:) Whilst the module itself can be run using concurrent strategies, C(ufw) does not support concurrency, as firewall rules are meant + to be ordered and parallel executions do not guarantee order. B(Do not use concurrency:) The results are unpredictable and the module may + fail silently if you do." requirements: - - C(ufw) package + - C(ufw) package extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -44,59 +42,52 @@ options: - V(reloaded) reloads firewall. - V(reset) disables and resets firewall to installation defaults. type: str - choices: [ disabled, enabled, reloaded, reset ] + choices: [disabled, enabled, reloaded, reset] default: description: - Change the default policy for incoming or outgoing traffic. type: str - choices: [ allow, deny, reject ] - aliases: [ policy ] + choices: [allow, deny, reject] + aliases: [policy] direction: description: - - Select direction for a rule or default policy command. Mutually - exclusive with O(interface_in) and O(interface_out). + - Select direction for a rule or default policy command. Mutually exclusive with O(interface_in) and O(interface_out). type: str - choices: [ in, incoming, out, outgoing, routed ] + choices: [in, incoming, out, outgoing, routed] logging: description: - Toggles logging. Logged packets use the LOG_KERN syslog facility. type: str - choices: [ 'on', 'off', low, medium, high, full ] + choices: ['on', 'off', low, medium, high, full] insert: description: - Insert the corresponding rule as rule number NUM. - Note that ufw numbers rules starting with 1. - - If O(delete=true) and a value is provided for O(insert), - then O(insert) is ignored. + - If O(delete=true) and a value is provided for O(insert), then O(insert) is ignored. type: int insert_relative_to: description: - Allows to interpret the index in O(insert) relative to a position. - - V(zero) interprets the rule number as an absolute index (i.e. 1 is - the first rule). - - V(first-ipv4) interprets the rule number relative to the index of the - first IPv4 rule, or relative to the position where the first IPv4 rule + - V(zero) interprets the rule number as an absolute index (that is, 1 is the first rule). + - V(first-ipv4) interprets the rule number relative to the index of the first IPv4 rule, or relative to the position where the first IPv4 + rule would be if there is currently none. + - V(last-ipv4) interprets the rule number relative to the index of the last IPv4 rule, or relative to the position where the last IPv4 rule would be if there is currently none. - - V(last-ipv4) interprets the rule number relative to the index of the - last IPv4 rule, or relative to the position where the last IPv4 rule - would be if there is currently none. - - V(first-ipv6) interprets the rule number relative to the index of the - first IPv6 rule, or relative to the position where the first IPv6 rule - would be if there is currently none. - - V(last-ipv6) interprets the rule number relative to the index of the - last IPv6 rule, or relative to the position where the last IPv6 rule + - V(first-ipv6) interprets the rule number relative to the index of the first IPv6 rule, or relative to the position where the first IPv6 + rule would be if there is currently none. + - V(last-ipv6) interprets the rule number relative to the index of the last IPv6 rule, or relative to the position where the last IPv6 rule would be if there is currently none. type: str - choices: [ first-ipv4, first-ipv6, last-ipv4, last-ipv6, zero ] + choices: [first-ipv4, first-ipv6, last-ipv4, last-ipv6, zero] default: zero rule: description: - - Add firewall rule + - Add firewall rule. type: str - choices: [ allow, deny, limit, reject ] + choices: [allow, deny, limit, reject] log: description: - - Log new connections matched to this rule + - Log new connections matched to this rule. type: bool default: false from_ip: @@ -104,7 +95,7 @@ options: - Source IP address. type: str default: any - aliases: [ from, src ] + aliases: [from, src] from_port: description: - Source port. @@ -114,54 +105,49 @@ options: - Destination IP address. type: str default: any - aliases: [ dest, to] + aliases: [dest, to] to_port: description: - Destination port. type: str - aliases: [ port ] + aliases: [port] proto: description: - TCP/IP protocol. type: str - choices: [ any, tcp, udp, ipv6, esp, ah, gre, igmp ] - aliases: [ protocol ] + choices: [any, tcp, udp, ipv6, esp, ah, gre, igmp] + aliases: [protocol] name: description: - Use profile located in C(/etc/ufw/applications.d). type: str - aliases: [ app ] + aliases: [app] delete: description: - Delete rule. - - If O(delete=true) and a value is provided for O(insert), - then O(insert) is ignored. + - If O(delete=true) and a value is provided for O(insert), then O(insert) is ignored. type: bool default: false interface: description: - - Specify interface for the rule. The direction (in or out) used - for the interface depends on the value of O(direction). See - O(interface_in) and O(interface_out) for routed rules that needs - to supply both an input and output interface. Mutually - exclusive with O(interface_in) and O(interface_out). + - Specify interface for the rule. The direction (in or out) used for the interface depends on the value of O(direction). See O(interface_in) + and O(interface_out) for routed rules that needs to supply both an input and output interface. Mutually exclusive with O(interface_in) + and O(interface_out). type: str - aliases: [ if ] + aliases: [if] interface_in: description: - - Specify input interface for the rule. This is mutually - exclusive with O(direction) and O(interface). However, it is - compatible with O(interface_out) for routed rules. + - Specify input interface for the rule. This is mutually exclusive with O(direction) and O(interface). However, it is compatible with O(interface_out) + for routed rules. type: str - aliases: [ if_in ] + aliases: [if_in] version_added: '0.2.0' interface_out: description: - - Specify output interface for the rule. This is mutually - exclusive with O(direction) and O(interface). However, it is - compatible with O(interface_in) for routed rules. + - Specify output interface for the rule. This is mutually exclusive with O(direction) and O(interface). However, it is compatible with O(interface_in) + for routed rules. type: str - aliases: [ if_out ] + aliases: [if_out] version_added: '0.2.0' route: description: @@ -172,9 +158,9 @@ options: description: - Add a comment to the rule. Requires UFW version >=0.35. type: str -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Allow everything and enable UFW community.general.ufw: state: enabled @@ -299,7 +285,7 @@ EXAMPLES = r''' route: true src: 192.0.2.0/24 dest: 198.51.100.0/24 -''' +""" import re diff --git a/plugins/modules/uptimerobot.py b/plugins/modules/uptimerobot.py index c1894e90a0..ed6b6431f1 100644 --- a/plugins/modules/uptimerobot.py +++ b/plugins/modules/uptimerobot.py @@ -8,44 +8,43 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: uptimerobot short_description: Pause and start Uptime Robot monitoring description: - - This module will let you start and pause Uptime Robot Monitoring + - This module will let you start and pause Uptime Robot Monitoring. author: "Nate Kingsley (@nate-kingsley)" requirements: - - Valid Uptime Robot API Key + - Valid Uptime Robot API Key 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 monitor should be running or paused. - required: true - choices: [ "started", "paused" ] - monitorid: - type: str - description: - - ID of the monitor to check. - required: true - apikey: - type: str - description: - - Uptime Robot API key. - required: true + state: + type: str + description: + - Define whether or not the monitor should be running or paused. + required: true + choices: ["started", "paused"] + monitorid: + type: str + description: + - ID of the monitor to check. + required: true + apikey: + type: str + description: + - Uptime Robot API key. + required: true notes: - - Support for adding and removing monitors and alert contacts has not yet been implemented. -''' + - Support for adding and removing monitors and alert contacts has not yet been implemented. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Pause the monitor with an ID of 12345 community.general.uptimerobot: monitorid: 12345 @@ -57,7 +56,7 @@ EXAMPLES = ''' monitorid: 12345 apikey: 12345-1234512345 state: started -''' +""" import json diff --git a/plugins/modules/urpmi.py b/plugins/modules/urpmi.py index 75c0af90fc..9c08a22c21 100644 --- a/plugins/modules/urpmi.py +++ b/plugins/modules/urpmi.py @@ -11,12 +11,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: urpmi short_description: Urpmi manager description: - - Manages packages with C(urpmi) (such as for Mageia or Mandriva) + - Manages packages with C(urpmi) (such as for Mageia or Mandriva). extends_documentation_fragment: - community.general.attributes attributes: @@ -29,13 +28,13 @@ options: description: - A list of package names to install, upgrade or remove. required: true - aliases: [ package, pkg ] + aliases: [package, pkg] type: list elements: str state: description: - Indicates the desired package state. - choices: [ absent, present, installed, removed ] + choices: [absent, present, installed, removed] default: present type: str update_cache: @@ -50,21 +49,19 @@ options: default: true force: description: - - Assume "yes" is the answer to any question urpmi has to ask. - Corresponds to the C(--force) option for C(urpmi). + - Assume "yes" is the answer to any question urpmi has to ask. Corresponds to the C(--force) option for C(urpmi). type: bool default: true root: description: - - Specifies an alternative install root, relative to which all packages will be installed. - Corresponds to the C(--root) option for C(urpmi). - aliases: [ installroot ] + - Specifies an alternative install root, relative to which all packages will be installed. Corresponds to the C(--root) option for C(urpmi). + aliases: [installroot] type: str author: -- Philippe Makowski (@pmakowski) -''' + - Philippe Makowski (@pmakowski) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install package foo community.general.urpmi: pkg: foo @@ -85,7 +82,7 @@ EXAMPLES = ''' name: bar state: present update_cache: true -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/usb_facts.py b/plugins/modules/usb_facts.py index 340c71ee54..4f0195bde3 100644 --- a/plugins/modules/usb_facts.py +++ b/plugins/modules/usb_facts.py @@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: usb_facts short_description: Allows listing information about USB devices version_added: 8.5.0 @@ -25,9 +24,9 @@ extends_documentation_fragment: - community.general.attributes.facts_module requirements: - lsusb binary on PATH (usually installed through the package usbutils and preinstalled on many systems) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get information about USB devices community.general.usb_facts: @@ -35,9 +34,9 @@ EXAMPLES = ''' ansible.builtin.debug: msg: "On bus {{ item.bus }} device {{ item.device }} with id {{ item.id }} is {{ item.name }}" loop: "{{ ansible_facts.usb_devices }}" -''' +""" -RETURN = r''' +RETURN = r""" ansible_facts: description: Dictionary containing details of connected USB devices. returned: always @@ -69,7 +68,7 @@ ansible_facts: returned: always type: str sample: Linux Foundation 2.0 root hub -''' +""" import re from ansible.module_utils.basic import AnsibleModule From 92e4bd184dc590f62210008657831e7615865527 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 24 Dec 2024 14:05:31 +0100 Subject: [PATCH 082/302] [PR #9226/b429e8a2 backport][stable-10] xfconf/xfconf_info: add return value version (#9359) xfconf/xfconf_info: add return value version (#9226) * xfconf/xfconf_info: add return value version * add changelog frag * adapt test to helper improvements * rollback copyright update * replace tab with spaces in test yamls (cherry picked from commit b429e8a2cf643fcf8aac3e154babb961c4573f18) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- changelogs/fragments/9226-xfconf-version.yml | 3 ++ plugins/module_utils/xfconf.py | 25 +++++++---- plugins/modules/xfconf.py | 19 +++++--- plugins/modules/xfconf_info.py | 10 ++++- tests/unit/plugins/modules/test_xfconf.yaml | 44 ++++++++++++++++++- .../plugins/modules/test_xfconf_info.yaml | 41 +++++++++++++++-- 6 files changed, 121 insertions(+), 21 deletions(-) create mode 100644 changelogs/fragments/9226-xfconf-version.yml diff --git a/changelogs/fragments/9226-xfconf-version.yml b/changelogs/fragments/9226-xfconf-version.yml new file mode 100644 index 0000000000..517beb9b96 --- /dev/null +++ b/changelogs/fragments/9226-xfconf-version.yml @@ -0,0 +1,3 @@ +minor_changes: + - 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). 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/xfconf.py b/plugins/modules/xfconf.py index b925e624c8..c13f7b7f45 100644 --- a/plugins/modules/xfconf.py +++ b/plugins/modules/xfconf.py @@ -153,10 +153,17 @@ cmd: - string - --set - Pacific/Auckland +version: + description: + - The version of the C(xfconf-query) command. + returned: success + type: str + sample: 4.18.1 + version_added: 10.2.0 """ from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper -from ansible_collections.community.general.plugins.module_utils.xfconf import xfconf_runner +from ansible_collections.community.general.plugins.module_utils.xfconf import xfconf_runner, get_xfconf_version class XFConfProperty(StateModuleHelper): @@ -183,8 +190,8 @@ class XFConfProperty(StateModuleHelper): def __init_module__(self): self.runner = xfconf_runner(self.module) - self.does_not = 'Property "{0}" does not exist on channel "{1}".'.format(self.vars.property, - self.vars.channel) + self.vars.version = get_xfconf_version(self.runner) + self.does_not = 'Property "{0}" does not exist on channel "{1}".'.format(self.vars.property, self.vars.channel) self.vars.set('previous_value', self._get()) self.vars.set('type', self.vars.value_type) self.vars.set_meta('value', initial_value=self.vars.previous_value) @@ -213,8 +220,7 @@ class XFConfProperty(StateModuleHelper): self.vars.stdout = ctx.results_out self.vars.stderr = ctx.results_err self.vars.cmd = ctx.cmd - if self.verbosity >= 4: - self.vars.run_info = ctx.run_info + self.vars.set("run_info", ctx.run_info, verbosity=4) self.vars.value = None def state_present(self): @@ -244,8 +250,7 @@ class XFConfProperty(StateModuleHelper): self.vars.stdout = ctx.results_out self.vars.stderr = ctx.results_err self.vars.cmd = ctx.cmd - if self.verbosity >= 4: - self.vars.run_info = ctx.run_info + self.vars.set("run_info", ctx.run_info, verbosity=4) if not self.vars.is_array: self.vars.value = self.vars.value[0] diff --git a/plugins/modules/xfconf_info.py b/plugins/modules/xfconf_info.py index d8e6acc50d..36de7daecc 100644 --- a/plugins/modules/xfconf_info.py +++ b/plugins/modules/xfconf_info.py @@ -118,10 +118,17 @@ value_array: - Main - Work - Tmp +version: + description: + - The version of the C(xfconf-query) command. + returned: success + type: str + sample: 4.18.1 + version_added: 10.2.0 """ from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper -from ansible_collections.community.general.plugins.module_utils.xfconf import xfconf_runner +from ansible_collections.community.general.plugins.module_utils.xfconf import xfconf_runner, get_xfconf_version class XFConfInfo(ModuleHelper): @@ -139,6 +146,7 @@ class XFConfInfo(ModuleHelper): def __init_module__(self): self.runner = xfconf_runner(self.module, check_rc=True) + self.vars.version = get_xfconf_version(self.runner) self.vars.set("list_arg", False, output=False) self.vars.set("is_array", False) diff --git a/tests/unit/plugins/modules/test_xfconf.yaml b/tests/unit/plugins/modules/test_xfconf.yaml index 481b090e94..c52c8f7c1b 100644 --- a/tests/unit/plugins/modules/test_xfconf.yaml +++ b/tests/unit/plugins/modules/test_xfconf.yaml @@ -21,11 +21,23 @@ previous_value: '100' type: int value: '90' + version: "4.18.1" mocks: run_command: - - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/inactive_opacity] + - command: [/testbin/xfconf-query, --version] environ: &env-def {environ_update: {LANGUAGE: C, LC_ALL: C}, check_rc: false} rc: 0 + out: &version-output | + xfconf-query 4.18.1 + + Copyright (c) 2008-2023 + The Xfce development team. All rights reserved. + + Please report bugs to . + err: "" + - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/inactive_opacity] + environ: *env-def + rc: 0 out: "100\n" err: "" - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/inactive_opacity, --create, --type, int, --set, '90'] @@ -45,8 +57,14 @@ previous_value: '90' type: int value: '90' + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/inactive_opacity] environ: *env-def rc: 0 @@ -69,8 +87,14 @@ previous_value: 'true' type: bool value: 'False' + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --channel, xfce4-session, --property, /general/SaveOnExit] environ: *env-def rc: 0 @@ -93,8 +117,14 @@ previous_value: [Main, Work, Tmp] type: [string, string, string] value: [A, B, C] + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/workspace_names] environ: *env-def rc: 0 @@ -136,8 +166,14 @@ previous_value: [A, B, C] type: [string, string, string] value: [A, B, C] + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/workspace_names] environ: *env-def rc: 0 @@ -177,8 +213,14 @@ previous_value: [A, B, C] type: value: + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/workspace_names] environ: *env-def rc: 0 diff --git a/tests/unit/plugins/modules/test_xfconf_info.yaml b/tests/unit/plugins/modules/test_xfconf_info.yaml index 535e50602f..8e7ae667c4 100644 --- a/tests/unit/plugins/modules/test_xfconf_info.yaml +++ b/tests/unit/plugins/modules/test_xfconf_info.yaml @@ -6,6 +6,13 @@ --- anchors: environ: &env-def {environ_update: {LANGUAGE: C, LC_ALL: C}, check_rc: true} + out: &version-output | + xfconf-query 4.18.1 + + Copyright (c) 2008-2023 + The Xfce development team. All rights reserved. + + Please report bugs to . test_cases: - id: test_simple_property_get input: @@ -14,8 +21,14 @@ test_cases: output: value: '100' is_array: false + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/inactive_opacity] environ: *env-def rc: 0 @@ -25,9 +38,15 @@ test_cases: input: channel: xfwm4 property: /general/i_dont_exist - output: {} + output: + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/i_dont_exist] environ: *env-def rc: 1 @@ -39,8 +58,6 @@ test_cases: output: failed: true msg: "missing parameter(s) required by 'property': channel" - mocks: - run_command: [] - id: test_property_get_array input: channel: xfwm4 @@ -48,8 +65,14 @@ test_cases: output: is_array: true value_array: [Main, Work, Tmp] + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --channel, xfwm4, --property, /general/workspace_names] environ: *env-def rc: 0 @@ -59,8 +82,14 @@ test_cases: input: {} output: channels: [a, b, c] + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --list] environ: *env-def rc: 0 @@ -77,8 +106,14 @@ test_cases: - /general/wrap_windows - /general/wrap_workspaces - /general/zoom_desktop + version: "4.18.1" mocks: run_command: + - command: [/testbin/xfconf-query, --version] + environ: *env-def + rc: 0 + out: *version-output + err: "" - command: [/testbin/xfconf-query, --list, --channel, xfwm4] environ: *env-def rc: 0 From 122086e83b8edd70541cb5ff2765e937dd06e424 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 24 Dec 2024 14:05:44 +0100 Subject: [PATCH 083/302] [PR #9339/6e84c137 backport][stable-10] t*: normalize docs (#9356) t*: normalize docs (#9339) * t*: normalize docs * Apply suggestions from code review Co-authored-by: Felix Fontein * break long line to regain sanity --------- Co-authored-by: Felix Fontein (cherry picked from commit 6e84c1375e23264e835f51610d0e9e2241104051) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/taiga_issue.py | 14 +++--- plugins/modules/telegram.py | 28 +++++------ plugins/modules/terraform.py | 88 +++++++++++++++------------------- plugins/modules/timezone.py | 50 +++++++++---------- plugins/modules/twilio.py | 42 ++++++++-------- plugins/modules/typetalk.py | 21 ++++---- 6 files changed, 109 insertions(+), 134 deletions(-) diff --git a/plugins/modules/taiga_issue.py b/plugins/modules/taiga_issue.py index e80ff43b89..b66db29dba 100644 --- a/plugins/modules/taiga_issue.py +++ b/plugins/modules/taiga_issue.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: taiga_issue short_description: Creates/deletes an issue in a Taiga Project Management Platform description: @@ -89,10 +88,11 @@ options: author: Alejandro Guirao (@lekum) requirements: [python-taiga] notes: -- The authentication is achieved either by the environment variable TAIGA_TOKEN or by the pair of environment variables TAIGA_USERNAME and TAIGA_PASSWORD -''' + - The authentication is achieved either by the environment variable E(TAIGA_TOKEN) or by the pair + of environment variables E(TAIGA_USERNAME) and E(TAIGA_PASSWORD). +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create an issue in the my hosted Taiga environment and attach an error log community.general.taiga_issue: taiga_host: https://mytaigahost.example.com @@ -117,9 +117,9 @@ EXAMPLES = ''' subject: An error has been found issue_type: Bug state: absent -''' +""" -RETURN = '''# ''' +RETURN = """# """ import traceback from os import getenv diff --git a/plugins/modules/telegram.py b/plugins/modules/telegram.py index 963c66353f..c2fee153ff 100644 --- a/plugins/modules/telegram.py +++ b/plugins/modules/telegram.py @@ -9,22 +9,21 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: telegram author: - - "Artem Feofanov (@tyouxa)" - - "Nikolai Lomov (@lomserman)" + - "Artem Feofanov (@tyouxa)" + - "Nikolai Lomov (@lomserman)" short_description: Send notifications via telegram description: - - Send notifications via telegram bot, to a verified group or user. - - Also, the user may try to use any other telegram bot API method, if you specify O(api_method) argument. + - Send notifications via telegram bot, to a verified group or user. + - Also, the user may try to use any other telegram bot API method, if you specify O(api_method) argument. notes: - - You will require a telegram account and create telegram bot to use this module. + - You will require a telegram account and create telegram bot to use this module. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -49,11 +48,9 @@ options: - Any parameters for the method. - For reference to default method, V(SendMessage), see U(https://core.telegram.org/bots/api#sendmessage). version_added: 2.0.0 +""" -''' - -EXAMPLES = """ - +EXAMPLES = r""" - name: Send notify to Telegram community.general.telegram: token: '9999999:XXXXXXXXXXXXXXXXXXXXXXX' @@ -75,15 +72,14 @@ EXAMPLES = """ message_id: '{{ saved_msg_id }}' """ -RETURN = """ - +RETURN = r""" msg: - description: The message you attempted to send + description: The message you attempted to send. returned: success type: str sample: "Ansible task finished" telegram_error: - description: Error message gotten from Telegram API + description: Error message gotten from Telegram API. returned: failure type: str sample: "Bad Request: message text is empty" diff --git a/plugins/modules/terraform.py b/plugins/modules/terraform.py index 5906657c66..cf2d07fc71 100644 --- a/plugins/modules/terraform.py +++ b/plugins/modules/terraform.py @@ -8,13 +8,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: terraform short_description: Manages a Terraform deployment (and plans) description: - - Provides support for deploying resources with Terraform and pulling - resource information back into Ansible. + - Provides support for deploying resources with Terraform and pulling resource information back into Ansible. extends_documentation_fragment: - community.general.attributes attributes: @@ -27,18 +25,16 @@ options: state: choices: ['planned', 'present', 'absent'] description: - - Goal state of given stage/project + - Goal state of given stage/project. type: str default: present binary_path: description: - - The path of a terraform binary to use, relative to the 'service_path' - unless you supply an absolute path. + - The path of a C(terraform) binary to use, relative to the 'service_path' unless you supply an absolute path. type: path project_path: description: - - The path to the root of the Terraform directory with the - vars.tf/main.tf/etc to use. + - The path to the root of the Terraform directory with the C(vars.tf)/C(main.tf)/etc to use. type: path required: true plugin_paths: @@ -48,88 +44,80 @@ options: - When set, the plugin discovery and auto-download behavior of Terraform is disabled. - The directory structure in the plugin path can be tricky. The Terraform docs U(https://learn.hashicorp.com/tutorials/terraform/automate-terraform#pre-installed-plugins) - show a simple directory of files, but actually, the directory structure - has to follow the same structure you would see if Terraform auto-downloaded the plugins. - See the examples below for a tree output of an example plugin directory. + show a simple directory of files, but actually, the directory structure has to follow the same structure you would see if Terraform auto-downloaded + the plugins. See the examples below for a tree output of an example plugin directory. type: list elements: path version_added: 3.0.0 workspace: description: - - The terraform workspace to work with. This sets the E(TF_WORKSPACE) environmental variable - that is used to override workspace selection. For more information about workspaces - have a look at U(https://developer.hashicorp.com/terraform/language/state/workspaces). + - The terraform workspace to work with. This sets the E(TF_WORKSPACE) environmental variable that is used to override workspace selection. + For more information about workspaces have a look at U(https://developer.hashicorp.com/terraform/language/state/workspaces). type: str default: default purge_workspace: description: - - Only works with state = absent + - Only works with state = absent. - If true, the workspace will be deleted after the "terraform destroy" action. - The 'default' workspace will not be deleted. default: false type: bool plan_file: description: - - The path to an existing Terraform plan file to apply. If this is not - specified, Ansible will build a new TF plan and execute it. - Note that this option is required if 'state' has the 'planned' value. + - The path to an existing Terraform plan file to apply. If this is not specified, Ansible will build a new TF plan and execute it. Note + that this option is required if 'state' has the 'planned' value. type: path state_file: description: - - The path to an existing Terraform state file to use when building plan. - If this is not specified, the default C(terraform.tfstate) will be used. + - The path to an existing Terraform state file to use when building plan. If this is not specified, the default C(terraform.tfstate) will + be used. - This option is ignored when plan is specified. type: path variables_files: description: - - The path to a variables file for Terraform to fill into the TF - configurations. This can accept a list of paths to multiple variables files. + - The path to a variables file for Terraform to fill into the TF configurations. This can accept a list of paths to multiple variables files. type: list elements: path - aliases: [ 'variables_file' ] + aliases: ['variables_file'] variables: description: - - A group of key-values pairs to override template variables or those in variables files. - By default, only string and number values are allowed, which are passed on unquoted. + - A group of key-values pairs to override template variables or those in variables files. By default, only string and number values are + allowed, which are passed on unquoted. - Support complex variable structures (lists, dictionaries, numbers, and booleans) to reflect terraform variable syntax when O(complex_vars=true). - Ansible integers or floats are mapped to terraform numbers. - Ansible strings are mapped to terraform strings. - Ansible dictionaries are mapped to terraform objects. - Ansible lists are mapped to terraform lists. - Ansible booleans are mapped to terraform booleans. - - "B(Note) passwords passed as variables will be visible in the log output. Make sure to use C(no_log=true) in production!" + - B(Note) passwords passed as variables will be visible in the log output. Make sure to use C(no_log=true) in production!. type: dict complex_vars: description: - Enable/disable capability to handle complex variable structures for C(terraform). - - If V(true) the O(variables) also accepts dictionaries, lists, and booleans to be passed to C(terraform). - Strings that are passed are correctly quoted. + - If V(true) the O(variables) also accepts dictionaries, lists, and booleans to be passed to C(terraform). Strings that are passed are correctly + quoted. - When disabled, supports only simple variables (strings, integers, and floats), and passes them on unquoted. type: bool default: false version_added: 5.7.0 targets: description: - - A list of specific resources to target in this plan/application. The - resources selected here will also auto-include any dependencies. + - A list of specific resources to target in this plan/application. The resources selected here will also auto-include any dependencies. type: list elements: str default: [] lock: description: - - Enable statefile locking, if you use a service that accepts locks (such - as S3+DynamoDB) to store your statefile. + - Enable statefile locking, if you use a service that accepts locks (such as S3+DynamoDB) to store your statefile. type: bool default: true lock_timeout: description: - - How long to maintain the lock on the statefile, if you use a service - that accepts locks (such as S3+DynamoDB). + - How long to maintain the lock on the statefile, if you use a service that accepts locks (such as S3+DynamoDB). type: int force_init: description: - - To avoid duplicating infra, if a state file can't be found this will - force a C(terraform init). Generally, this should be turned off unless + - To avoid duplicating infra, if a state file can't be found this will force a C(terraform init). Generally, this should be turned off unless you intend to provision an entirely new Terraform deployment. default: false type: bool @@ -145,8 +133,8 @@ options: type: dict backend_config_files: description: - - The path to a configuration file to provide at init state to the -backend-config parameter. - This can accept a list of paths to multiple configuration files. + - The path to a configuration file to provide at init state to the -backend-config parameter. This can accept a list of paths to multiple + configuration files. type: list elements: path version_added: '0.2.0' @@ -164,8 +152,8 @@ options: version_added: '1.3.0' check_destroy: description: - - Apply only when no resources are destroyed. Note that this only prevents "destroy" actions, - but not "destroy and re-create" actions. This option is ignored when O(state=absent). + - Apply only when no resources are destroyed. Note that this only prevents "destroy" actions, but not "destroy and re-create" actions. This + option is ignored when O(state=absent). type: bool default: false version_added: '3.3.0' @@ -175,12 +163,12 @@ options: type: int version_added: '3.8.0' notes: - - To just run a C(terraform plan), use check mode. -requirements: [ "terraform" ] + - To just run a C(terraform plan), use check mode. +requirements: ["terraform"] author: "Ryan Scott Brown (@ryansb)" -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Basic deploy of a service community.general.terraform: project_path: '{{ project_dir }}' @@ -248,7 +236,7 @@ EXAMPLES = """ # └── terraform-provider-vsphere_v1.26.0_x4 """ -RETURN = """ +RETURN = r""" outputs: type: complex description: A dictionary of all the TF outputs by their assigned name. Use RV(ignore:outputs.MyOutputName.value) to access the value. @@ -258,18 +246,18 @@ outputs: sensitive: type: bool returned: always - description: Whether Terraform has marked this value as sensitive + description: Whether Terraform has marked this value as sensitive. type: type: str returned: always - description: The type of the value (string, int, etc) + description: The type of the value (string, int, etc). value: type: str returned: always - description: The value of the output as interpolated by Terraform + description: The value of the output as interpolated by Terraform. stdout: type: str - description: Full C(terraform) command stdout, in case you want to display it or examine the event log + description: Full C(terraform) command stdout, in case you want to display it or examine the event log. returned: always sample: '' command: diff --git a/plugins/modules/timezone.py b/plugins/modules/timezone.py index cd823e6115..78df0cd45f 100644 --- a/plugins/modules/timezone.py +++ b/plugins/modules/timezone.py @@ -8,20 +8,18 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: timezone short_description: Configure timezone setting description: - - This module configures the timezone setting, both of the system clock and of the hardware clock. - If you want to set up the NTP, use M(ansible.builtin.service) module. + - This module configures the timezone setting, both of the system clock and of the hardware clock. If you want to set up the NTP, use + M(ansible.builtin.service) module. - It is recommended to restart C(crond) after changing the timezone, otherwise the jobs may run at the wrong time. - - Several different tools are used depending on the OS/Distribution involved. - For Linux it can use C(timedatectl) or edit C(/etc/sysconfig/clock) or C(/etc/timezone) and C(hwclock). - On SmartOS, C(sm-set-timezone), for macOS, C(systemsetup), for BSD, C(/etc/localtime) is modified. - On AIX, C(chtz) is used. - - Make sure that the zoneinfo files are installed with the appropriate OS package, like C(tzdata) (usually always installed, - when not using a minimal installation like Alpine Linux). + - Several different tools are used depending on the OS/Distribution involved. For Linux it can use C(timedatectl) or edit C(/etc/sysconfig/clock) + or C(/etc/timezone) and C(hwclock). On SmartOS, C(sm-set-timezone), for macOS, C(systemsetup), for BSD, C(/etc/localtime) is modified. On + AIX, C(chtz) is used. + - Make sure that the zoneinfo files are installed with the appropriate OS package, like C(tzdata) (usually always installed, when not using + a minimal installation like Alpine Linux). - Windows and HPUX are not supported, please let us know if you find any other OS/distro in which this fails. extends_documentation_fragment: - community.general.attributes @@ -35,51 +33,49 @@ options: description: - Name of the timezone for the system clock. - Default is to keep current setting. - - B(At least one of name and hwclock are required.) + - B(At least one) of O(name) and O(hwclock) are required. type: str hwclock: description: - Whether the hardware clock is in UTC or in local timezone. - Default is to keep current setting. - - Note that this option is recommended not to change and may fail - to configure, especially on virtual environments such as AWS. - - B(At least one of name and hwclock are required.) - - I(Only used on Linux.) + - Note that this option is recommended not to change and may fail to configure, especially on virtual environments such as AWS. + - B(At least one) of O(name) and O(hwclock) are required. + - I(Only used on Linux). type: str - aliases: [ rtc ] - choices: [ local, UTC ] + aliases: [rtc] + choices: [local, UTC] notes: - On Ubuntu 24.04 the C(util-linux-extra) package is required to provide the C(hwclock) command. - On SmartOS the C(sm-set-timezone) utility (part of the smtools package) is required to set the zone timezone. - - On AIX only Olson/tz database timezones are usable (POSIX is not supported). - An OS reboot is also required on AIX for the new timezone setting to take effect. - Note that AIX 6.1+ is needed (OS level 61 or newer). + - On AIX only Olson/tz database timezones are usable (POSIX is not supported). An OS reboot is also required on AIX for the new timezone setting + to take effect. Note that AIX 6.1+ is needed (OS level 61 or newer). author: - Shinichi TAMURA (@tmshn) - Jasper Lievisse Adriaanse (@jasperla) - Indrajit Raychaudhuri (@indrajitr) -''' +""" -RETURN = r''' +RETURN = r""" diff: description: The differences about the given arguments. returned: success type: complex contains: before: - description: The values before change + description: The values before change. type: dict after: - description: The values after change + description: The values after change. type: dict -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Set timezone to Asia/Tokyo become: true community.general.timezone: name: Asia/Tokyo -''' +""" import errno import os diff --git a/plugins/modules/twilio.py b/plugins/modules/twilio.py index 270320c465..dc397d4831 100644 --- a/plugins/modules/twilio.py +++ b/plugins/modules/twilio.py @@ -9,20 +9,17 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: twilio short_description: Sends a text message to a mobile phone through Twilio description: - - Sends a text message to a phone number through the Twilio messaging API. + - Sends a text message to a phone number through the Twilio messaging API. 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 a Twilio account with - a purchased or verified phone number to send the text message. + - 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 a Twilio account with a purchased + or verified phone number to send the text message. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -50,7 +47,7 @@ options: description: - One or more phone numbers to send the text message to, format C(+15551112222). required: true - aliases: [ to_number ] + aliases: [to_number] from_number: type: str description: @@ -59,14 +56,13 @@ options: media_url: type: str description: - - A URL with a picture, video or sound clip to send with an MMS - (multimedia message) instead of a plain SMS. + - A URL with a picture, video or sound clip to send with an MMS (multimedia message) instead of a plain SMS. required: false author: "Matt Makai (@makaimc)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # send an SMS about the build status to (555) 303 5681 # note: replace account_sid and auth_token values with your credentials # and you have to have the 'from_number' on your Twilio account @@ -75,8 +71,8 @@ EXAMPLES = ''' msg: All servers with webserver role are now configured. account_sid: ACXXXXXXXXXXXXXXXXX auth_token: ACXXXXXXXXXXXXXXXXX - from_number: +15552014545 - to_number: +15553035681 + from_number: "+15552014545" + to_number: "+15553035681" delegate_to: localhost # send an SMS to multiple phone numbers about the deployment @@ -87,11 +83,11 @@ EXAMPLES = ''' msg: This server configuration is now complete. account_sid: ACXXXXXXXXXXXXXXXXX auth_token: ACXXXXXXXXXXXXXXXXX - from_number: +15553258899 + from_number: "+15553258899" to_numbers: - - +15551113232 - - +12025551235 - - +19735559010 + - "+15551113232" + - "+12025551235" + - "+19735559010" delegate_to: localhost # send an MMS to a single recipient with an update on the deployment @@ -103,11 +99,11 @@ EXAMPLES = ''' msg: Deployment complete! account_sid: ACXXXXXXXXXXXXXXXXX auth_token: ACXXXXXXXXXXXXXXXXX - from_number: +15552014545 - to_number: +15553035681 + from_number: "+15552014545" + to_number: "+15553035681" media_url: https://demo.twilio.com/logo.png delegate_to: localhost -''' +""" # ======================================= # twilio module support methods diff --git a/plugins/modules/typetalk.py b/plugins/modules/typetalk.py index ddf9f35605..6364cdc45b 100644 --- a/plugins/modules/typetalk.py +++ b/plugins/modules/typetalk.py @@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: typetalk short_description: Send a message to typetalk description: - - Send a message to typetalk using typetalk API + - Send a message to typetalk using typetalk API. extends_documentation_fragment: - community.general.attributes attributes: @@ -26,35 +25,35 @@ options: client_id: type: str description: - - OAuth2 client ID + - OAuth2 client ID. required: true client_secret: type: str description: - - OAuth2 client secret + - OAuth2 client secret. required: true topic: type: int description: - - topic id to post message + - Topic id to post message. required: true msg: type: str description: - - message body + - Message body. required: true -requirements: [ json ] +requirements: [json] author: "Takashi Someda (@tksmd)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Send a message to typetalk community.general.typetalk: client_id: 12345 client_secret: 12345 topic: 1 msg: install completed -''' +""" import json From a13a6d284cec9256f6f725384c48c33a6b0c2a32 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 24 Dec 2024 14:45:24 +0100 Subject: [PATCH 084/302] [PR #9322/d539b00d backport][stable-10] connection plugins: use f-strings (#9358) connection plugins: use f-strings (#9322) * connection plugins: use f-strings * add changelog frag (cherry picked from commit d539b00d4c415235ff20ea4d575a47f41ef6511d) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- .../9322-fstr-connection-plugins.yml | 11 ++++++++ plugins/connection/chroot.py | 24 ++++++++-------- plugins/connection/funcd.py | 6 ++-- plugins/connection/incus.py | 24 ++++++---------- plugins/connection/iocage.py | 11 ++++---- plugins/connection/jail.py | 28 +++++++++---------- plugins/connection/lxc.py | 20 ++++++------- plugins/connection/lxd.py | 22 +++++++-------- plugins/connection/qubes.py | 22 +++++++-------- plugins/connection/saltstack.py | 10 +++---- plugins/connection/zone.py | 26 ++++++++--------- 11 files changed, 105 insertions(+), 99 deletions(-) create mode 100644 changelogs/fragments/9322-fstr-connection-plugins.yml diff --git a/changelogs/fragments/9322-fstr-connection-plugins.yml b/changelogs/fragments/9322-fstr-connection-plugins.yml new file mode 100644 index 0000000000..4b3e264cfb --- /dev/null +++ b/changelogs/fragments/9322-fstr-connection-plugins.yml @@ -0,0 +1,11 @@ +minor_changes: + - chroot connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322). + - funcd connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322). + - 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). + - jail connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322). + - 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). + - qubes connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322). + - saltstack connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322). + - zone connection plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9322). diff --git a/plugins/connection/chroot.py b/plugins/connection/chroot.py index 3567912359..2586109669 100644 --- a/plugins/connection/chroot.py +++ b/plugins/connection/chroot.py @@ -120,7 +120,7 @@ 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. @@ -128,7 +128,7 @@ class Connection(ConnectionBase): # 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 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 """ @@ -161,7 +161,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) @@ -195,7 +195,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 +205,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 +237,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..6184d946e0 100644 --- a/plugins/connection/funcd.py +++ b/plugins/connection/funcd.py @@ -72,7 +72,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 +87,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..097b3b800f 100644 --- a/plugins/connection/incus.py +++ b/plugins/connection/incus.py @@ -93,14 +93,14 @@ 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()), + f"{self.get_option('remote')}:{self._instance()}", "--", self._play_context.executable, "-c", cmd] @@ -114,12 +114,10 @@ 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 @@ -127,20 +125,18 @@ class Connection(ConnectionBase): """ 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)] + f"{self.get_option('remote')}:{self._instance()}/{out_path}"] local_cmd = [to_bytes(i, errors='surrogate_or_strict') for i in local_cmd] @@ -150,16 +146,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..411a81b0d9 100644 --- a/plugins/connection/iocage.py +++ b/plugins/connection/iocage.py @@ -55,11 +55,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 +82,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..1ebe5b26ef 100644 --- a/plugins/connection/jail.py +++ b/plugins/connection/jail.py @@ -75,14 +75,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 +97,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 +115,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) @@ -153,7 +153,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 +163,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 +195,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..5a6d3575a4 100644 --- a/plugins/connection/lxc.py +++ b/plugins/connection/lxc.py @@ -82,7 +82,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 +144,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 +174,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 +194,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 +202,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 +210,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 +225,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..5fa40c3636 100644 --- a/plugins/connection/lxd.py +++ b/plugins/connection/lxd.py @@ -93,19 +93,19 @@ class Connection(ConnectionBase): """ 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()), + f"{self.get_option('remote')}:{self._host()}", "--", self.get_option("executable"), "-c", cmd ]) - self._display.vvvvv(u"EXEC {0}".format(local_cmd), host=self._host()) + 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,13 +116,13 @@ 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 @@ -130,10 +130,10 @@ class Connection(ConnectionBase): """ 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"): @@ -141,7 +141,7 @@ class Connection(ConnectionBase): local_cmd.extend([ "file", "push", in_path, - "%s:%s/%s" % (self.get_option("remote"), self._host(), out_path) + f"{self.get_option('remote')}:{self._host()}/{out_path}" ]) local_cmd = [to_bytes(i, errors='surrogate_or_strict') for i in local_cmd] @@ -153,14 +153,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/qubes.py b/plugins/connection/qubes.py index 8860fbb777..0b8e61f574 100644 --- a/plugins/connection/qubes.py +++ b/plugins/connection/qubes.py @@ -78,7 +78,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 +95,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 +114,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" % (stdout, 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..da993dfec4 100644 --- a/plugins/connection/saltstack.py +++ b/plugins/connection/saltstack.py @@ -59,11 +59,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 +81,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 +93,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..77d85ad0ee 100644 --- a/plugins/connection/zone.py +++ b/plugins/connection/zone.py @@ -62,14 +62,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 +94,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 +117,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) @@ -149,7 +149,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 +159,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 +191,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 """ From 3c7f05c42d0c46d698cfe173eaafb6cf42b51228 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Tue, 24 Dec 2024 14:45:32 +0100 Subject: [PATCH 085/302] [PR #9321/c3ed2144 backport][stable-10] callback plugins: use f-strings (#9357) callback plugins: use f-strings (#9321) * callback plugins: use f-strings * add changelog frag * manual change for few occurrences * manual change for few occurrences * adjustment from review * adjustment from review * adjustment from review * Update plugins/callback/splunk.py Co-authored-by: Felix Fontein * replace str templating with JSON templating --------- Co-authored-by: Felix Fontein (cherry picked from commit c3ed2144e2585ee7c91761f666767154e299c734) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- .../fragments/9321-fstr-callback-plugins.yml | 22 +++++ plugins/callback/cgroup_memory_recap.py | 4 +- plugins/callback/context_demo.py | 6 +- plugins/callback/counter_enabled.py | 86 +++++++++---------- plugins/callback/dense.py | 54 ++++++------ plugins/callback/diy.py | 6 +- plugins/callback/elastic.py | 10 +-- plugins/callback/jabber.py | 6 +- plugins/callback/log_plays.py | 19 ++-- plugins/callback/loganalytics.py | 7 +- plugins/callback/logdna.py | 4 +- plugins/callback/logentries.py | 12 +-- plugins/callback/mail.py | 52 +++++------ plugins/callback/nrdp.py | 19 ++-- plugins/callback/opentelemetry.py | 15 ++-- plugins/callback/say.py | 16 ++-- plugins/callback/selective.py | 42 ++++----- plugins/callback/slack.py | 31 ++++--- plugins/callback/splunk.py | 5 +- plugins/callback/timestamp.py | 4 +- plugins/callback/unixy.py | 80 ++++++++--------- plugins/callback/yaml.py | 4 +- 22 files changed, 251 insertions(+), 253 deletions(-) create mode 100644 changelogs/fragments/9321-fstr-callback-plugins.yml diff --git a/changelogs/fragments/9321-fstr-callback-plugins.yml b/changelogs/fragments/9321-fstr-callback-plugins.yml new file mode 100644 index 0000000000..d79d3cbfa0 --- /dev/null +++ b/changelogs/fragments/9321-fstr-callback-plugins.yml @@ -0,0 +1,22 @@ +minor_changes: + - cgroup_memory_recap callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - 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). + - dense callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - diy callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - elastic callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - jabber callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - 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 - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - mail callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - nrdp callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - opentelemetry callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - say callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - selective callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - 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). + - timestamp callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - unixy callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). + - yaml callback plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9321). diff --git a/plugins/callback/cgroup_memory_recap.py b/plugins/callback/cgroup_memory_recap.py index 643f0f0b88..e8599aad49 100644 --- a/plugins/callback/cgroup_memory_recap.py +++ b/plugins/callback/cgroup_memory_recap.py @@ -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..94dfdf45ad 100644 --- a/plugins/callback/context_demo.py +++ b/plugins/callback/context_demo.py @@ -38,15 +38,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..9bb1df07d4 100644 --- a/plugins/callback/counter_enabled.py +++ b/plugins/callback/counter_enabled.py @@ -71,7 +71,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 +91,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(u'ok', stat['ok'], C.COLOR_OK)} {colorize(u'changed', stat['changed'], C.COLOR_CHANGED)} " + f"{colorize(u'unreachable', stat['unreachable'], C.COLOR_UNREACHABLE)} {colorize(u'failed', stat['failures'], C.COLOR_ERROR)} " + f"{colorize(u'rescued', stat['rescued'], C.COLOR_OK)} {colorize(u'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(u'ok', stat['ok'], None)} {colorize(u'changed', stat['changed'], None)} " + f"{colorize(u'unreachable', stat['unreachable'], None)} {colorize(u'failed', stat['failures'], None)} " + f"{colorize(u'rescued', stat['rescued'], None)} {colorize(u'ignored', stat['ignored'], None)}", log_only=True ) @@ -124,12 +116,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 +137,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 +160,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 +179,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 +200,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 +227,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 +240,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/dense.py b/plugins/callback/dense.py index 490705fd27..e0419644ef 100644 --- a/plugins/callback/dense.py +++ b/plugins/callback/dense.py @@ -195,7 +195,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() @@ -252,7 +252,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 +260,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 +274,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 +284,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 +309,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 +327,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 +341,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 +365,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 +388,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 +451,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 +465,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 +476,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(u'ok', t['ok'], C.COLOR_OK)} {colorize(u'changed', t['changed'], C.COLOR_CHANGED)} " + f"{colorize(u'unreachable', t['unreachable'], C.COLOR_UNREACHABLE)} {colorize(u'failed', t['failures'], C.COLOR_ERROR)} " + f"{colorize(u'rescued', t['rescued'], C.COLOR_OK)} {colorize(u'ignored', t['ignored'], C.COLOR_WARN)}", screen_only=True ) diff --git a/plugins/callback/diy.py b/plugins/callback/diy.py index cf9369e4b4..e3cda4ac7c 100644 --- a/plugins/callback/diy.py +++ b/plugins/callback/diy.py @@ -828,9 +828,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 +867,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..9b5942d962 100644 --- a/plugins/callback/elastic.py +++ b/plugins/callback/elastic.py @@ -118,7 +118,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 +166,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 +225,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 +259,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 +288,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..f63f07b4f5 100644 --- a/plugins/callback/jabber.py +++ b/plugins/callback/jabber.py @@ -102,7 +102,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 +118,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..190e1c60c4 100644 --- a/plugins/callback/log_plays.py +++ b/plugins/callback/log_plays.py @@ -57,7 +57,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 +85,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..98ceb1e7a3 100644 --- a/plugins/callback/loganalytics.py +++ b/plugins/callback/loganalytics.py @@ -84,18 +84,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..cbf9df4b1c 100644 --- a/plugins/callback/logdna.py +++ b/plugins/callback/logdna.py @@ -73,7 +73,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 +161,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..bc8b1cb5bd 100644 --- a/plugins/callback/logentries.py +++ b/plugins/callback/logentries.py @@ -153,7 +153,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: {to_text(e)}") root_delay *= 2 if root_delay > self.MAX_DELAY: @@ -162,7 +162,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 @@ -249,7 +249,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: {to_text(e)}") self.disabled = True try: @@ -268,10 +268,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 +284,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/mail.py b/plugins/callback/mail.py index 1b847ea34c..2e26fe84eb 100644 --- a/plugins/callback/mail.py +++ b/plugins/callback/mail.py @@ -135,14 +135,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 +159,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 +190,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 +228,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 +257,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..b937049dc3 100644 --- a/plugins/callback/nrdp.py +++ b/plugins/callback/nrdp.py @@ -132,10 +132,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 += "%s\n" % msg + xmldata += f"{self.hostname}\n" + xmldata += f"{self.servicename}\n" + xmldata += f"{state}\n" + xmldata += f"{msg}\n" xmldata += "\n" xmldata += "\n" @@ -152,7 +152,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 +170,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/opentelemetry.py b/plugins/callback/opentelemetry.py index 8dc627c214..44c563019c 100644 --- a/plugins/callback/opentelemetry.py +++ b/plugins/callback/opentelemetry.py @@ -209,7 +209,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 +347,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 +470,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 +482,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 +535,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..357f84ae08 100644 --- a/plugins/callback/say.py +++ b/plugins/callback/say.py @@ -50,7 +50,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 +69,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 +78,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 +87,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 +103,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..3cea24ff1a 100644 --- a/plugins/callback/selective.py +++ b/plugins/callback/selective.py @@ -48,13 +48,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 +73,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 +106,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 +147,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 +239,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 +254,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..0e58628c35 100644 --- a/plugins/callback/slack.py +++ b/plugins/callback/slack.py @@ -138,14 +138,13 @@ class CallbackModule(CallbackBase): headers=headers) 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: {to_text(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 +155,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 +191,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 +227,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 +236,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..966170594c 100644 --- a/plugins/callback/splunk.py +++ b/plugins/callback/splunk.py @@ -153,15 +153,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/timestamp.py b/plugins/callback/timestamp.py index 07cd8d239c..d8737b9e4c 100644 --- a/plugins/callback/timestamp.py +++ b/plugins/callback/timestamp.py @@ -85,7 +85,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 +98,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..de0c79088b 100644 --- a/plugins/callback/unixy.py +++ b/plugins/callback/unixy.py @@ -67,24 +67,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,28 +92,28 @@ 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 -" 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"---" @@ -126,7 +126,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 +136,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 +149,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 +173,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 +195,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(u'ok', t['ok'], C.COLOR_OK)} {colorize(u'changed', t['changed'], C.COLOR_CHANGED)} " + f"{colorize(u'unreachable', t['unreachable'], C.COLOR_UNREACHABLE)} {colorize(u'failed', t['failures'], C.COLOR_ERROR)} " + f"{colorize(u'rescued', t['rescued'], C.COLOR_OK)} {colorize(u'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(u'ok', t['ok'], None)} {colorize(u'changed', t['changed'], None)} " + f"{colorize(u'unreachable', t['unreachable'], None)} {colorize(u'failed', t['failures'], None)} {colorize(u'rescued', t['rescued'], None)} " + f"{colorize(u'ignored', t['ignored'], None)}", log_only=True ) if stats.custom and self.get_option('show_custom_stats'): @@ -223,12 +215,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 +233,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..1daf4572d5 100644 --- a/plugins/callback/yaml.py +++ b/plugins/callback/yaml.py @@ -113,11 +113,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 From 7e6514b4d4d3b1ba956a8794414980161042db2a Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 25 Dec 2024 16:46:34 +0100 Subject: [PATCH 086/302] [PR #9351/4b23e5ec backport][stable-10] s[o-y]*: normalize docs (#9369) s[o-y]*: normalize docs (#9351) * s[o-y]*: normalize docs * Apply suggestions from code review Co-authored-by: Felix Fontein * Update plugins/modules/spectrum_model_attrs.py --------- Co-authored-by: Felix Fontein (cherry picked from commit 4b23e5ecffa0b12d97797d9deb007a635d56818d) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/solaris_zone.py | 38 +- plugins/modules/sorcery.py | 145 ++-- plugins/modules/spectrum_device.py | 152 ++--- plugins/modules/spectrum_model_attrs.py | 211 +++--- plugins/modules/spotinst_aws_elastigroup.py | 722 ++++++++------------ plugins/modules/ss_3par_cpg.py | 30 +- plugins/modules/ssh_config.py | 43 +- plugins/modules/stacki_host.py | 26 +- plugins/modules/statsd.py | 11 +- plugins/modules/statusio_maintenance.py | 223 +++--- plugins/modules/sudoers.py | 11 +- plugins/modules/supervisorctl.py | 35 +- plugins/modules/svc.py | 89 ++- plugins/modules/svr4pkg.py | 24 +- plugins/modules/swdepot.py | 53 +- plugins/modules/swupd.py | 34 +- plugins/modules/syslogger.py | 96 ++- plugins/modules/syspatch.py | 44 +- plugins/modules/sysrc.py | 98 ++- plugins/modules/sysupgrade.py | 83 ++- 20 files changed, 994 insertions(+), 1174 deletions(-) diff --git a/plugins/modules/solaris_zone.py b/plugins/modules/solaris_zone.py index d9f44589dc..9f8f774cbe 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(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,29 @@ 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 +90,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 +143,7 @@ EXAMPLES = ''' name: zone1 state: attached attach_options: -u -''' +""" import os import platform diff --git a/plugins/modules/sorcery.py b/plugins/modules/sorcery.py index a525bd9ac8..9ad3d30f3b 100644 --- a/plugins/modules/sorcery.py +++ b/plugins/modules/sorcery.py @@ -10,93 +10,86 @@ 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 +124,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 +177,11 @@ EXAMPLES = ''' - name: Update only Sorcery itself community.general.sorcery: update: true -''' +""" -RETURN = ''' -''' +RETURN = r""" +""" import datetime diff --git a/plugins/modules/spectrum_device.py b/plugins/modules/spectrum_device.py index 7cf7cf9150..bb9761d37d 100644 --- a/plugins/modules/spectrum_device.py +++ b/plugins/modules/spectrum_device.py @@ -9,88 +9,86 @@ 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 +111,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..3057f04c15 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..d07761ee05 100644 --- a/plugins/modules/spotinst_aws_elastigroup.py +++ b/plugins/modules/spotinst_aws_elastigroup.py @@ -5,19 +5,15 @@ # 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 +34,43 @@ 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 +80,30 @@ 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 +120,129 @@ 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. + - 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 +252,42 @@ 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 +302,70 @@ 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)." + - '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 +374,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 +386,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 +423,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 +465,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 +512,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 +562,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 +602,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 +640,68 @@ 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 1f8098b25f..582d7c127e 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 ssh-agent or a PKCS11Provider or 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: @@ -145,10 +140,10 @@ options: type: str version_added: 10.1.0 requirements: -- paramiko -''' + - paramiko +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Add a host in the configuration community.general.ssh_config: user: akasurde @@ -163,9 +158,9 @@ EXAMPLES = r''' 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 @@ -201,7 +196,7 @@ hosts_change_diff: } } ] -''' +""" import os diff --git a/plugins/modules/stacki_host.py b/plugins/modules/stacki_host.py index 57440a24d0..4b37d256cb 100644 --- a/plugins/modules/stacki_host.py +++ b/plugins/modules/stacki_host.py @@ -8,8 +8,7 @@ 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: @@ -35,8 +34,7 @@ options: 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 +66,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 +94,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 +115,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..6f17523e25 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..2735ce72cd 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" @@ -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 diff --git a/plugins/modules/supervisorctl.py b/plugins/modules/supervisorctl.py index e8d9c89a65..9e6900e234 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 description: - - Manage the state of a program or group of programs running via supervisord + - Manage the state of a program or group of programs running via 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,19 @@ 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=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" ] + - 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"] 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 +112,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..17667c2cc8 100644 --- a/plugins/modules/svc.py +++ b/plugins/modules/svc.py @@ -8,60 +8,55 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: svc author: -- Brian Coca (@bcoca) + - Brian Coca (@bcoca) short_description: Manage daemontools services description: - - Controls daemontools services on remote hosts using the svc utility. + - Controls daemontools services on remote hosts using the 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 '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 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 +87,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..ac919d749b 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 @@ -47,8 +44,9 @@ 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 +71,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 +104,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..9b13a4e658 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,16 @@ 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]. - If not specified, the default format is used. + - The format suffix for version file downloads. For example [1,2,3,staging,etc]. 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 +45,7 @@ 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 +67,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 +92,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..ca9aebfcfc 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/sysupgrade.py b/plugins/modules/sysupgrade.py index 639fa345ad..26232cd98d 100644 --- a/plugins/modules/sysupgrade.py +++ b/plugins/modules/sysupgrade.py @@ -8,54 +8,53 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: sysupgrade short_description: Manage OpenBSD system upgrades version_added: 1.1.0 description: - - Manage OpenBSD system upgrades using sysupgrade. + - Manage OpenBSD system upgrades using C(sysupgrade). 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: - snapshot: - description: - - Apply the latest snapshot. - - Otherwise release will be applied. - default: false - type: bool - force: - description: - - Force upgrade (for snapshots only). - default: false - type: bool - keep_files: - description: - - Keep the files under /home/_sysupgrade. - - By default, the files will be deleted after the upgrade. - default: false - type: bool - fetch_only: - description: - - Fetch and verify files and create /bsd.upgrade but do not reboot. - - Set to V(false) if you want sysupgrade to reboot. This will cause Ansible to error, as it expects the module to exit gracefully. See the examples. - default: true - type: bool - installurl: - description: - - OpenBSD mirror top-level URL for fetching an upgrade. - - By default, the mirror URL is pulled from /etc/installurl. - type: str + snapshot: + description: + - Apply the latest snapshot. + - Otherwise release will be applied. + default: false + type: bool + force: + description: + - Force upgrade (for snapshots only). + default: false + type: bool + keep_files: + description: + - Keep the files under C(/home/_sysupgrade). + - By default, the files will be deleted after the upgrade. + default: false + type: bool + fetch_only: + description: + - Fetch and verify files and create C(/bsd.upgrade) but do not reboot. + - Set to V(false) if you want C(sysupgrade) to reboot. This will cause Ansible to error, as it expects the module to exit gracefully. See the examples. + default: true + type: bool + installurl: + description: + - OpenBSD mirror top-level URL for fetching an upgrade. + - By default, the mirror URL is pulled from C(/etc/installurl). + type: str author: - - Andrew Klaus (@precurse) -''' + - Andrew Klaus (@precurse) +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Upgrade to latest release community.general.sysupgrade: register: sysupgrade @@ -77,9 +76,9 @@ EXAMPLES = r''' community.general.sysupgrade: fetch_only: false ignore_errors: true -''' +""" -RETURN = r''' +RETURN = r""" rc: description: The command return code (0 means success). returned: always @@ -93,7 +92,7 @@ stderr: returned: always type: str sample: "sysupgrade: need root privileges" -''' +""" from ansible.module_utils.basic import AnsibleModule From 74bd7f14712ab88f1f022ba5411301393d542061 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 25 Dec 2024 16:46:47 +0100 Subject: [PATCH 087/302] [PR #9270/825e0ee3 backport][stable-10] zypper: add simple_errors option - fixes #8416 (#9370) zypper: add simple_errors option - fixes #8416 (#9270) * zypper: add simple_errors option -fixes #8416 * Fix style issues * Apply suggestions from code review Co-authored-by: Felix Fontein * Fix indentation * Add changelog fragment * Apply suggestions from code review Co-authored-by: Felix Fontein * Updated as per code review recommendations * Fix whitespace * Add quiet option, fix logic, update changelog * Fix trailing whitespace * Update plugins/modules/zypper.py Co-authored-by: Felix Fontein * Add suggested improvements --------- Co-authored-by: Eric Hoogeveen Co-authored-by: Felix Fontein (cherry picked from commit 825e0ee377f3bfaea9528d9e76c6041cc9ab193c) Co-authored-by: Eric <8869330+erichoog@users.noreply.github.com> --- .../9270-zypper-add-simple_errors.yaml | 3 ++ plugins/modules/zypper.py | 48 ++++++++++++++++++- 2 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/9270-zypper-add-simple_errors.yaml diff --git a/changelogs/fragments/9270-zypper-add-simple_errors.yaml b/changelogs/fragments/9270-zypper-add-simple_errors.yaml new file mode 100644 index 0000000000..9fcdf3403c --- /dev/null +++ b/changelogs/fragments/9270-zypper-add-simple_errors.yaml @@ -0,0 +1,3 @@ +minor_changes: + - zypper - add ``simple_errors`` option (https://github.com/ansible-collections/community.general/pull/9270). + - zypper - add ``quiet`` option (https://github.com/ansible-collections/community.general/pull/9270). \ No newline at end of file diff --git a/plugins/modules/zypper.py b/plugins/modules/zypper.py index ac5b6657ba..5bc6c766a0 100644 --- a/plugins/modules/zypper.py +++ b/plugins/modules/zypper.py @@ -142,6 +142,20 @@ options: description: - Adds C(--clean-deps) option to I(zypper) remove command. version_added: '4.6.0' + simple_errors: + type: bool + required: false + default: false + description: + - When set to V(true), provide a simplified error output (parses only the C() tag text in the XML output). + version_added: '10.2.0' + quiet: + type: bool + required: false + default: true + description: + - Adds C(--quiet) option to I(zypper) install/update command. + version_added: '10.2.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. @@ -190,6 +204,13 @@ EXAMPLES = r""" name: '*' state: latest +- name: Install latest packages but dump error messages in a simplified format + community.general.zypper: + name: '*' + state: latest + simple_errors: true + quiet: false + - name: Apply all available patches community.general.zypper: name: '*' @@ -347,15 +368,38 @@ def parse_zypper_xml(m, cmd, fail_not_found=True, packages=None): # run zypper again with the same command to complete update return parse_zypper_xml(m, cmd, fail_not_found=fail_not_found, packages=packages) + # apply simple_errors logic to rc 0,102,103,106 + if m.params['simple_errors']: + stdout = get_simple_errors(dom) or stdout + return packages, rc, stdout, stderr + + # apply simple_errors logic to rc other than 0,102,103,106 + if m.params['simple_errors']: + stdout = get_simple_errors(dom) or stdout + m.fail_json(msg='Zypper run command failed with return code %s.' % rc, rc=rc, stdout=stdout, stderr=stderr, cmd=cmd) +def get_simple_errors(dom): + simple_errors = [] + message_xml_tags = dom.getElementsByTagName('message') + + if message_xml_tags is None: + return None + + for x in message_xml_tags: + simple_errors.append(x.firstChild.data) + return " \n".join(simple_errors) + + def get_cmd(m, subcommand): "puts together the basic zypper command arguments with those passed to the module" is_install = subcommand in ['install', 'update', 'patch', 'dist-upgrade'] is_refresh = subcommand == 'refresh' - cmd = [m.get_bin_path('zypper', required=True), '--quiet', '--non-interactive', '--xmlout'] + cmd = [m.get_bin_path('zypper', required=True), '--non-interactive', '--xmlout'] + if m.params['quiet']: + cmd.append('--quiet') if transactional_updates(): cmd = [m.get_bin_path('transactional-update', required=True), '--continue', '--drop-if-no-change', '--quiet', 'run'] + cmd if m.params['extra_args_precommand']: @@ -555,6 +599,8 @@ def main(): allow_vendor_change=dict(required=False, default=False, type='bool'), replacefiles=dict(required=False, default=False, type='bool'), clean_deps=dict(required=False, default=False, type='bool'), + simple_errors=dict(required=False, default=False, type='bool'), + quiet=dict(required=False, default=True, type='bool'), ), supports_check_mode=True ) From a5c448d6e844e51a85518fb9a5afbeef7286127b Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 25 Dec 2024 16:46:55 +0100 Subject: [PATCH 088/302] [PR #9324/6cd3f79e backport][stable-10] lookup plugins: use f-strings (#9367) lookup plugins: use f-strings (#9324) * lookup plugins: use f-strings * add changelog frag * manual change for few occurrences * Update plugins/lookup/dependent.py Co-authored-by: Felix Fontein * adjustment from review * no f-string for you * Update plugins/lookup/dependent.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 6cd3f79e19b00a485132a4e6281656b8e5e6e10c) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- .../fragments/9324-fstr-lookup-plugins.yml | 29 +++++++++++ plugins/lookup/bitwarden.py | 2 +- plugins/lookup/chef_databag.py | 4 +- plugins/lookup/collection_version.py | 6 +-- plugins/lookup/consul_kv.py | 4 +- plugins/lookup/credstash.py | 4 +- plugins/lookup/cyberarkpassword.py | 14 +++--- plugins/lookup/dependent.py | 17 +++---- plugins/lookup/dig.py | 20 ++++---- plugins/lookup/dnstxt.py | 2 +- plugins/lookup/dsv.py | 8 ++-- plugins/lookup/etcd.py | 4 +- plugins/lookup/etcd3.py | 8 ++-- plugins/lookup/filetree.py | 10 ++-- plugins/lookup/github_app_access_token.py | 10 ++-- plugins/lookup/hiera.py | 3 +- plugins/lookup/keyring.py | 6 +-- plugins/lookup/lastpass.py | 4 +- plugins/lookup/lmdb_kv.py | 2 +- plugins/lookup/manifold.py | 40 ++++++++-------- plugins/lookup/merge_variables.py | 9 ++-- plugins/lookup/onepassword.py | 24 +++++----- plugins/lookup/onepassword_doc.py | 2 +- plugins/lookup/passwordstore.py | 48 ++++++++----------- plugins/lookup/random_pet.py | 2 +- plugins/lookup/redis.py | 2 +- plugins/lookup/revbitspss.py | 4 +- plugins/lookup/shelvefile.py | 6 +-- plugins/lookup/tss.py | 18 +++---- tests/sanity/ignore-2.15.txt | 1 + tests/sanity/ignore-2.16.txt | 1 + 31 files changed, 165 insertions(+), 149 deletions(-) create mode 100644 changelogs/fragments/9324-fstr-lookup-plugins.yml diff --git a/changelogs/fragments/9324-fstr-lookup-plugins.yml b/changelogs/fragments/9324-fstr-lookup-plugins.yml new file mode 100644 index 0000000000..a448ae0d48 --- /dev/null +++ b/changelogs/fragments/9324-fstr-lookup-plugins.yml @@ -0,0 +1,29 @@ +minor_changes: + - bitwarden lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - chef_databag lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - 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). + - credstash lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - cyberarkpassword lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - dependent lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - dig lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - dnstxt lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - dsv lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - etcd lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - 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). + - github_app_access_token lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - hiera lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - keyring lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - lastpass lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - lmdb_kv lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - manifold lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - merge_variables lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - 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). + - passwordstore lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - random_pet lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - 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). + - shelvefile lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). + - tss lookup plugin - use f-strings instead of interpolations or ``format`` (https://github.com/ansible-collections/community.general/pull/9324). diff --git a/plugins/lookup/bitwarden.py b/plugins/lookup/bitwarden.py index 5e31cc6f89..9a8b5749c2 100644 --- a/plugins/lookup/bitwarden.py +++ b/plugins/lookup/bitwarden.py @@ -207,7 +207,7 @@ 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 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..e6701c9fb8 100644 --- a/plugins/lookup/cyberarkpassword.py +++ b/plugins/lookup/cyberarkpassword.py @@ -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=({to_text(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..b03619e15e 100644 --- a/plugins/lookup/dig.py +++ b/plugins/lookup/dig.py @@ -345,7 +345,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: {to_native(e)}") myres.retry_servfail = self.get_option('retry_servfail') for t in terms: @@ -363,7 +363,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: {to_native(e)}") continue if '=' in t: try: @@ -379,7 +379,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: {to_native(e)}") elif opt == 'retry_servfail': myres.retry_servfail = boolean(arg) elif opt == 'fail_on_error': @@ -400,7 +400,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 +416,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 {to_native(e)}") domains = reversed_domains if len(domains) > 1: @@ -445,25 +445,25 @@ 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: {str(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: {str(err)}") if not real_empty: ret.append('NXDOMAIN') except dns.resolver.NoAnswer as err: if fail_on_error: - raise AnsibleError("Lookup failed: %s" % str(err)) + raise AnsibleError(f"Lookup failed: {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: {str(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 {to_native(err)}") return ret diff --git a/plugins/lookup/dnstxt.py b/plugins/lookup/dnstxt.py index 1ce511b849..296d916368 100644 --- a/plugins/lookup/dnstxt.py +++ b/plugins/lookup/dnstxt.py @@ -108,7 +108,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 {to_native(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..3bbeb06bb3 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: {to_native(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: {to_native(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: {to_native(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/github_app_access_token.py b/plugins/lookup/github_app_access_token.py index cee635fc0a..73fd09a0a9 100644 --- a/plugins/lookup/github_app_access_token.py +++ b/plugins/lookup/github_app_access_token.py @@ -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..65a3301f2d 100644 --- a/plugins/lookup/keyring.py +++ b/plugins/lookup/keyring.py @@ -61,13 +61,13 @@ class LookupModule(LookupBase): 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..7ff3930bed 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 can't open database {db}: {to_native(e)}") ret = [] if len(terms) == 0: diff --git a/plugins/lookup/manifold.py b/plugins/lookup/manifold.py index 049d453e4f..0240aa442b 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: {str(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} : {str(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}: {str(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}: {str(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: {str(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..2d9f01e3de 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 @@ -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", ] @@ -560,7 +560,7 @@ class OnePassCLIv2(OnePassCLIBase): 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: @@ -627,7 +627,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..b1728fce89 100644 --- a/plugins/lookup/onepassword_doc.py +++ b/plugins/lookup/onepassword_doc.py @@ -55,7 +55,7 @@ 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)] + args = [*args, f"--vault={vault}"] if self.service_account_token: if vault is None: diff --git a/plugins/lookup/passwordstore.py b/plugins/lookup/passwordstore.py index f35d268995..584690c175 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]] 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..344fa01678 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"{str(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 {str(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 {str(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/tests/sanity/ignore-2.15.txt b/tests/sanity/ignore-2.15.txt index 667c6cee4d..f624f28e01 100644 --- a/tests/sanity/ignore-2.15.txt +++ b/tests/sanity/ignore-2.15.txt @@ -1,4 +1,5 @@ .azure-pipelines/scripts/publish-codecov.py replace-urlopen +plugins/lookup/dependent.py validate-modules:unidiomatic-typecheck plugins/modules/consul_session.py validate-modules:parameter-state-invalid-choice plugins/modules/homectl.py import-3.11 # Uses deprecated stdlib library 'crypt' plugins/modules/iptables_state.py validate-modules:undocumented-parameter # params _back and _timeout used by action plugin diff --git a/tests/sanity/ignore-2.16.txt b/tests/sanity/ignore-2.16.txt index f6b058ec69..665101becf 100644 --- a/tests/sanity/ignore-2.16.txt +++ b/tests/sanity/ignore-2.16.txt @@ -1,3 +1,4 @@ +plugins/lookup/dependent.py validate-modules:unidiomatic-typecheck plugins/modules/consul_session.py validate-modules:parameter-state-invalid-choice plugins/modules/homectl.py import-3.11 # Uses deprecated stdlib library 'crypt' plugins/modules/homectl.py import-3.12 # Uses deprecated stdlib library 'crypt' From 899fcb87494a813fb2df418d586980f3a67435a0 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 25 Dec 2024 21:40:55 +0100 Subject: [PATCH 089/302] [PR #9353/70b62ed7 backport][stable-10] s[a-c]*: normalize docs (#9376) s[a-c]*: normalize docs (#9353) * s[a-c]*: normalize docs * Apply suggestions from code review Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 70b62ed7453efc286bb912e888dd59643d39e40e) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/say.py | 17 ++- plugins/modules/scaleway_compute.py | 53 ++++---- .../scaleway_compute_private_network.py | 31 ++--- plugins/modules/scaleway_container.py | 18 +-- plugins/modules/scaleway_container_info.py | 13 +- .../modules/scaleway_container_namespace.py | 15 +-- .../scaleway_container_namespace_info.py | 15 +-- .../modules/scaleway_container_registry.py | 13 +- .../scaleway_container_registry_info.py | 13 +- plugins/modules/scaleway_database_backup.py | 125 +++++++++--------- plugins/modules/scaleway_function.py | 20 +-- plugins/modules/scaleway_function_info.py | 15 +-- .../modules/scaleway_function_namespace.py | 15 +-- .../scaleway_function_namespace_info.py | 15 +-- plugins/modules/scaleway_image_info.py | 16 +-- plugins/modules/scaleway_ip.py | 38 +++--- plugins/modules/scaleway_ip_info.py | 16 +-- plugins/modules/scaleway_lb.py | 28 ++-- plugins/modules/scaleway_organization_info.py | 15 +-- plugins/modules/scaleway_private_network.py | 29 ++-- plugins/modules/scaleway_security_group.py | 25 ++-- .../modules/scaleway_security_group_info.py | 17 +-- .../modules/scaleway_security_group_rule.py | 37 +++--- plugins/modules/scaleway_server_info.py | 16 +-- plugins/modules/scaleway_snapshot_info.py | 16 +-- plugins/modules/scaleway_sshkey.py | 23 ++-- plugins/modules/scaleway_user_data.py | 29 ++-- plugins/modules/scaleway_volume.py | 19 ++- plugins/modules/scaleway_volume_info.py | 16 +-- 29 files changed, 336 insertions(+), 382 deletions(-) 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..5cdd12da5d 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..28cf40ac50 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 @@ -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..a5e81c37e4 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,8 @@ 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 +120,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 +133,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 +155,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 +186,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..4fad2faf61 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 don't 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..b597c7c42b 100644 --- a/plugins/modules/scaleway_ip_info.py +++ b/plugins/modules/scaleway_ip_info.py @@ -8,8 +8,7 @@ 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 description: @@ -37,9 +36,9 @@ options: - EMEA-FR-PAR2 - waw1 - EMEA-PL-WAW1 -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Gather Scaleway ips information community.general.scaleway_ip_info: region: par1 @@ -47,14 +46,13 @@ EXAMPLES = r''' - 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 6cc947755d..7e13c3843f 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,7 +111,7 @@ EXAMPLES = ''' state: absent organization_id: 951df375-e094-4d26-97c1-ba548eeb9c42 region: fr-par -''' +""" RETURNS = ''' { 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 ( From f6fa7fb2736b3400b54914fc85d9b8b15c174d80 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 25 Dec 2024 21:41:05 +0100 Subject: [PATCH 090/302] [PR #9354/97514612 backport][stable-10] r*: normalize docs (#9377) r*: normalize docs (#9354) * r*: normalize docs * Apply suggestions from code review Co-authored-by: Felix Fontein * Apply suggestions from code review --------- Co-authored-by: Felix Fontein (cherry picked from commit 97514612956083d585c1141ec3dbb57483519162) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/read_csv.py | 68 +- plugins/modules/redfish_command.py | 957 +++++++++--------- plugins/modules/redfish_config.py | 369 ++++--- plugins/modules/redfish_info.py | 542 +++++----- plugins/modules/redhat_subscription.py | 323 +++--- plugins/modules/redis.py | 144 ++- plugins/modules/redis_data.py | 106 +- plugins/modules/redis_data_incr.py | 37 +- plugins/modules/redis_data_info.py | 13 +- plugins/modules/redis_info.py | 23 +- plugins/modules/rhevm.py | 377 ++++--- plugins/modules/rhsm_release.py | 25 +- plugins/modules/rhsm_repository.py | 38 +- plugins/modules/riak.py | 27 +- plugins/modules/rocketchat.py | 41 +- plugins/modules/rollbar_deployment.py | 47 +- plugins/modules/rpm_ostree_pkg.py | 127 ++- plugins/modules/rundeck_acl_policy.py | 129 ++- .../modules/rundeck_job_executions_info.py | 102 +- plugins/modules/rundeck_job_run.py | 125 ++- plugins/modules/rundeck_project.py | 107 +- plugins/modules/runit.py | 78 +- 22 files changed, 1858 insertions(+), 1947 deletions(-) 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 829b77897d..edbbb18e5f 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,32 @@ 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. 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 +93,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 +107,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 +128,7 @@ options: type: str update_username: required: false - aliases: [ account_updatename ] + aliases: [account_updatename] description: - New user name for updating account_username. type: str @@ -219,11 +216,9 @@ options: 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) + - 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' @@ -232,18 +227,15 @@ options: 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. + - 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. + - MIME Type for custom OEM properties for HTTP Multipart Push updates. type: str version_added: '10.1.0' virtual_media: @@ -299,10 +291,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 @@ -316,7 +306,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 @@ -336,9 +326,8 @@ 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(:).' - - See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT) - for more details. + - 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. type: list elements: str @@ -347,514 +336,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: 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: 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: 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: 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: 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: 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: 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: 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: Systems - command: VirtualMediaEject - baseuri: "{{ baseuri }}" - username: "{{ username }}" - password: "{{ password }}" - virtual_media: - image_url: 'http://example.com/images/SomeLinux-current.iso' - 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: 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: 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 - 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: GracefulRestart + resource_id: BMC + baseuri: "{{ baseuri }}" + username: "{{ username }}" + password: "{{ password }}" - - 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 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: PowerGracefulRestart - resource_id: BMC +- name: Restart manager power gracefully + community.general.redfish_command: + category: Manager + command: PowerGracefulRestart + resource_id: BMC - - name: Turn manager power off - community.general.redfish_command: - category: Manager - command: PowerForceOff - resource_id: BMC +- name: Turn manager power off + community.general.redfish_command: + category: Manager + command: PowerForceOff + resource_id: BMC - - name: Restart manager power forcefully - community.general.redfish_command: - category: Manager - command: PowerForceRestart - resource_id: BMC +- name: Restart manager power forcefully + community.general.redfish_command: + category: Manager + command: PowerForceRestart + resource_id: BMC - - name: Shutdown manager power gracefully - community.general.redfish_command: - category: Manager - command: PowerGracefulShutdown - resource_id: BMC +- name: Shutdown manager power gracefully + community.general.redfish_command: + category: Manager + command: PowerGracefulShutdown + resource_id: BMC - - name: Turn manager power on - community.general.redfish_command: - category: Manager - command: PowerOn - resource_id: BMC +- name: Turn manager power on + community.general.redfish_command: + category: Manager + command: PowerOn + resource_id: BMC - - name: Reboot manager power - community.general.redfish_command: - category: Manager - command: PowerReboot - resource_id: BMC +- name: Reboot manager power + community.general.redfish_command: + category: Manager + command: PowerReboot + 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: Factory reset manager to defaults + community.general.redfish_command: + category: Manager + command: ResetToDefaults + resource_id: BMC + reset_to_defaults_mode: ResetAll - - 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: 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 = ''' +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 diff --git a/plugins/modules/redfish_config.py b/plugins/modules/redfish_config.py index 5b9caecc64..e47597f73f 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 @@ -165,15 +160,14 @@ 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' @@ -181,9 +175,8 @@ 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(:).' - - See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT) - for more details. + - 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. type: list elements: str @@ -192,195 +185,195 @@ 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 service identification to {{ service_id }} + community.general.redfish_config: + category: Manager + command: SetServiceIdentification + service_id: "{{ service_id }}" + 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_collections.community.general.plugins.module_utils.redfish_utils import RedfishUtils diff --git a/plugins/modules/redfish_info.py b/plugins/modules/redfish_info.py index b1b4a45ee5..e4e909ad48 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,318 +74,317 @@ 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(:).' - - See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT) - for more details. + - 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. type: list elements: str 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 default system inventory and user information + community.general.redfish_info: + category: Systems,Accounts + 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, user and firmware information + community.general.redfish_info: + category: ["Systems", "Accounts", "Update"] + 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 Manager NIC inventory information + community.general.redfish_info: + category: Manager + command: GetManagerNicInventory + 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 boot override information + community.general.redfish_info: + category: Systems + command: GetBootOverride + 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 chassis inventory + community.general.redfish_info: + category: Chassis + command: GetChassisInventory + 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 all information available in the Manager category + community.general.redfish_info: + category: Manager + command: all + 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 firmware update capability information + community.general.redfish_info: + category: Update + command: GetFirmwareUpdateCapabilities + 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 inventory + community.general.redfish_info: + category: Update + command: GetFirmwareInventory + 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 service identification + community.general.redfish_info: + category: Manager + command: GetServiceIdentification + manager: "{{ manager }}" + 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 software inventory + community.general.redfish_info: + category: Update + command: GetSoftwareInventory + 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 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 Manager Services - community.general.redfish_info: - category: Manager - command: GetNetworkProtocols - 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 all information available in all categories - community.general.redfish_info: - category: all - command: all - 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 system health report - community.general.redfish_info: - category: Systems - 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 chassis health report - community.general.redfish_info: - category: Chassis - 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 health report - community.general.redfish_info: - category: Manager - 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 manager Redfish Host Interface inventory - community.general.redfish_info: - category: Manager - command: GetHostInterfaces - 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 Inventory - community.general.redfish_info: - category: Manager - command: GetManagerInventory - 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 Thermal Config - community.general.redfish_info: - category: Chassis - command: GetHPEThermalConfig - 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 HPE Fan Percent Minimum - community.general.redfish_info: - category: Chassis - command: GetHPEFanPercentMin - 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 BIOS registry - community.general.redfish_info: - category: Systems - command: GetBiosRegistries - 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: 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: 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 = ''' +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 diff --git a/plugins/modules/redhat_subscription.py b/plugins/modules/redhat_subscription.py index 338fb92ebd..d9f791e5cf 100644 --- a/plugins/modules/redhat_subscription.py +++ b/plugins/modules/redhat_subscription.py @@ -10,16 +10,15 @@ 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. @@ -42,171 +41,161 @@ notes: 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 +264,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 diff --git a/plugins/modules/redis.py b/plugins/modules/redis.py index a30b89922c..716f5f1851 100644 --- a/plugins/modules/redis.py +++ b/plugins/modules/redis.py @@ -8,91 +8,85 @@ 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 +136,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..0f0aa92974 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..ca3a0d03d9 100644 --- a/plugins/modules/rhsm_release.py +++ b/plugins/modules/rhsm_release.py @@ -8,18 +8,15 @@ 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 +34,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 +50,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..3e95e69425 100644 --- a/plugins/modules/rhsm_repository.py +++ b/plugins/modules/rhsm_repository.py @@ -8,20 +8,16 @@ 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 +30,27 @@ 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 +69,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..cd3a3f4e8f 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,12 @@ 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 +80,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..82de3f829f 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,12 @@ 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 +51,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 +66,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 +79,13 @@ 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 +97,17 @@ options: elements: dict description: - Define a list of attachments. -''' +""" -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 @@ -151,12 +146,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 diff --git a/plugins/modules/rollbar_deployment.py b/plugins/modules/rollbar_deployment.py index 4bce9ab980..e9bfc239b0 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 + - 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 8c5c693f60..3d5ba865c9 100644 --- a/plugins/modules/rpm_ostree_pkg.py +++ b/plugins/modules/rpm_ostree_pkg.py @@ -10,50 +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 - apply_live: - description: + 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 + 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 @@ -80,51 +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 -''' + 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 diff --git a/plugins/modules/rundeck_acl_policy.py b/plugins/modules/rundeck_acl_policy.py index 8f21a32680..29b31a6642 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's 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 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..221b87b0dd 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 From 60ba39da58db3b516772b0542ad38b4ad4aa0972 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 25 Dec 2024 22:00:31 +0100 Subject: [PATCH 091/302] [PR #9262/23d97fa4 backport][stable-10] Add inventory plugin iocage (#9378) Add inventory plugin iocage (#9262) * Add inventory plugin iocage #9261 * inventory/iocage.py BOTMETA entry added. * Remove missing methods from the test. * Avoid shell mode. * Parameter host is optional default=localhost * Fix AnsibleError calls. * Update plugins/inventory/iocage.py Co-authored-by: Felix Fontein * Update plugins/inventory/iocage.py Co-authored-by: Felix Fontein * Update plugins/inventory/iocage.py Co-authored-by: Felix Fontein * Update plugins/inventory/iocage.py Co-authored-by: Felix Fontein * Update plugins/inventory/iocage.py Co-authored-by: Felix Fontein * Update plugins/inventory/iocage.py Co-authored-by: Felix Fontein * Update plugins/inventory/iocage.py Co-authored-by: Felix Fontein * iocage_data removed. Not necessarily defined at this point. * Description mentions that remote hosts are contacted via SSH. * test inventory iocage * Create get_jails and get_properties in iocage plugin to simplify testing. * Update test_iocage.py * Add fixtures iocage_* * Update documentation. * Update documentation. * Update documentation. * Fix localhost environment. * Update plugins/inventory/iocage.py Co-authored-by: Felix Fontein * Update plugins/inventory/iocage.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 23d97fa4b0dc0956e392772617401d08a05d6932) Co-authored-by: Vladimir Botka --- .github/BOTMETA.yml | 2 + plugins/inventory/iocage.py | 266 ++++++++++ .../inventory/fixtures/iocage_inventory.yml | 460 ++++++++++++++++++ .../fixtures/iocage_inventory.yml.license | 3 + .../inventory/fixtures/iocage_jails.txt | 3 + .../fixtures/iocage_jails.txt.license | 3 + .../inventory/fixtures/iocage_jails.yml | 32 ++ .../fixtures/iocage_jails.yml.license | 3 + .../inventory/fixtures/iocage_properties.txt | 11 + .../fixtures/iocage_properties.txt.license | 3 + .../inventory/fixtures/iocage_properties.yml | 458 +++++++++++++++++ .../fixtures/iocage_properties.yml.license | 3 + .../fixtures/iocage_properties_test_101.txt | 141 ++++++ .../iocage_properties_test_101.txt.license | 3 + .../fixtures/iocage_properties_test_102.txt | 141 ++++++ .../iocage_properties_test_102.txt.license | 3 + .../fixtures/iocage_properties_test_103.txt | 141 ++++++ .../iocage_properties_test_103.txt.license | 3 + tests/unit/plugins/inventory/test_iocage.py | 112 +++++ 19 files changed, 1791 insertions(+) create mode 100644 plugins/inventory/iocage.py create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_inventory.yml create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_inventory.yml.license create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_jails.txt create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_jails.txt.license create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_jails.yml create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_jails.yml.license create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties.txt create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties.txt.license create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties.yml create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties.yml.license create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties_test_101.txt create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties_test_101.txt.license create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties_test_102.txt create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties_test_102.txt.license create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties_test_103.txt create mode 100644 tests/unit/plugins/inventory/fixtures/iocage_properties_test_103.txt.license create mode 100644 tests/unit/plugins/inventory/test_iocage.py diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 2be4619ecb..dbe3c9cfe1 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -213,6 +213,8 @@ files: maintainers: opoplawski $inventories/gitlab_runners.py: maintainers: morph027 + $inventories/iocage.py: + maintainers: vbotka $inventories/icinga2.py: maintainers: BongoEADGC6 $inventories/linode.py: diff --git a/plugins/inventory/iocage.py b/plugins/inventory/iocage.py new file mode 100644 index 0000000000..6b51bb346e --- /dev/null +++ b/plugins/inventory/iocage.py @@ -0,0 +1,266 @@ +# -*- 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 (absolute_import, division, print_function) +__metaclass__ = type + +DOCUMENTATION = ''' + 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 + get_properties: + description: + - Get jails' properties. + Creates dictionary C(iocage_properties) for each added host. + type: boolean + default: false + env: + description: O(user)'s environment on O(host). + type: dict + default: {} + 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. +''' + +EXAMPLES = ''' +# 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 + +# 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 +''' + +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): + if ip4 == '-': + return ip4 + return re.split('\\||/', ip4)[1] + + +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') + env = self.get_option('env') + get_properties = self.get_option('get_properties') + + 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.append(self.IOCAGE) + + cmd_list = cmd.copy() + cmd_list.append('list') + cmd_list.append('--header') + 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('Failed to run cmd=%s, rc=%s, stderr=%s' % + (cmd_list, p.returncode, to_native(stderr))) + + try: + t_stdout = to_text(stdout, errors='surrogate_or_strict') + except UnicodeError as e: + raise AnsibleError('Invalid (non unicode) input returned: %s' % to_native(e)) from e + + except Exception as e: + raise AnsibleParserError('Failed to parse %s: %s' % + (to_native(path), to_native(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("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('Failed to run cmd=%s, rc=%s, stderr=%s' % + (cmd_get_properties, p.returncode, to_native(stderr))) + + try: + t_stdout = to_text(stdout, errors='surrogate_or_strict') + except UnicodeError as e: + raise AnsibleError('Invalid (non unicode) input returned: %s' % to_native(e)) from e + + except Exception as e: + raise AnsibleError('Failed to get properties: %s' % to_native(e)) from e + + self.get_properties(t_stdout, results, hostname) + + return results + + def get_jails(self, t_stdout, results): + jails = [x.split() for x in t_stdout.splitlines()] + for jail in jails: + iocage_name = jail[1] + 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'] = _parse_ip4(jail[6]) + 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/tests/unit/plugins/inventory/fixtures/iocage_inventory.yml b/tests/unit/plugins/inventory/fixtures/iocage_inventory.yml new file mode 100644 index 0000000000..850a54f549 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_inventory.yml @@ -0,0 +1,460 @@ +all: + children: + test: + hosts: + test_101: + iocage_basejail: 'yes' + iocage_boot: 'off' + iocage_ip4: 10.1.0.101 + iocage_ip6: '-' + iocage_jid: '-' + iocage_properties: + CONFIG_VERSION: '28' + allow_chflags: '0' + allow_mlock: '0' + allow_mount: '0' + allow_mount_devfs: '0' + allow_mount_fusefs: '0' + allow_mount_nullfs: '0' + allow_mount_procfs: '0' + allow_mount_tmpfs: '0' + allow_mount_zfs: '0' + allow_quotas: '0' + allow_raw_sockets: '0' + allow_set_hostname: '1' + allow_socket_af: '0' + allow_sysvipc: '0' + allow_tun: '0' + allow_vmm: '0' + assign_localhost: '0' + available: readonly + basejail: '1' + boot: '0' + bpf: '0' + children_max: '0' + comment: none + compression: lz4 + compressratio: readonly + coredumpsize: 'off' + count: '1' + cpuset: 'off' + cputime: 'off' + datasize: 'off' + dedup: 'off' + defaultrouter: 10.1.0.10 + defaultrouter6: auto + depends: none + devfs_ruleset: '4' + dhcp: '0' + enforce_statfs: '2' + exec_clean: '1' + exec_created: /usr/bin/true + exec_fib: '0' + exec_jail_user: root + exec_poststart: /usr/bin/true + exec_poststop: /usr/bin/true + exec_prestart: /usr/bin/true + exec_prestop: /usr/bin/true + exec_start: /bin/sh /etc/rc + exec_stop: /bin/sh /etc/rc.shutdown + exec_system_jail_user: '0' + exec_system_user: root + exec_timeout: '60' + host_domainname: none + host_hostname: ansible-client + host_hostuuid: test_101 + host_time: '1' + hostid: 34333834-3734-5a43-3331-313342464631 + hostid_strict_check: '0' + interfaces: vnet0:bridge0 + ip4: new + ip4_addr: vnet0|10.1.0.101/24 + ip4_saddrsel: '1' + ip6: new + ip6_addr: none + ip6_saddrsel: '1' + ip_hostname: '0' + jail_zfs: '0' + jail_zfs_dataset: iocage/jails/test_101/data + jail_zfs_mountpoint: none + last_started: none + localhost_ip: none + login_flags: -f root + mac_prefix: 3e4a92 + maxproc: 'off' + memorylocked: 'off' + memoryuse: 'off' + min_dyn_devfs_ruleset: '1000' + mount_devfs: '1' + mount_fdescfs: '1' + mount_linprocfs: '0' + mount_procfs: '0' + mountpoint: readonly + msgqqueued: 'off' + msgqsize: 'off' + nat: '0' + nat_backend: ipfw + nat_forwards: none + nat_interface: none + nat_prefix: '172.16' + nmsgq: 'off' + notes: vmm=iocage_01 + nsem: 'off' + nsemop: 'off' + nshm: 'off' + nthr: 'off' + openfiles: 'off' + origin: readonly + owner: root + pcpu: 'off' + plugin_name: none + plugin_repository: none + priority: '99' + pseudoterminals: 'off' + quota: none + readbps: 'off' + readiops: 'off' + release: 13.4-RELEASE-p2 + reservation: none + resolver: /etc/resolv.conf + rlimits: 'off' + rtsold: '0' + securelevel: '2' + shmsize: 'off' + stacksize: 'off' + state: down + stop_timeout: '30' + swapuse: 'off' + sync_state: none + sync_target: none + sync_tgt_zpool: none + sysvmsg: new + sysvsem: new + sysvshm: new + template: '0' + type: jail + used: readonly + vmemoryuse: 'off' + vnet: '1' + vnet0_mac: none + vnet0_mtu: auto + vnet1_mac: none + vnet1_mtu: auto + vnet2_mac: none + vnet2_mtu: auto + vnet3_mac: none + vnet3_mtu: auto + vnet_default_interface: auto + vnet_default_mtu: '1500' + vnet_interfaces: none + wallclock: 'off' + writebps: 'off' + writeiops: 'off' + iocage_release: 13.4-RELEASE-p2 + iocage_state: down + iocage_template: ansible_client + iocage_type: jail + test_102: + iocage_basejail: 'yes' + iocage_boot: 'off' + iocage_ip4: 10.1.0.102 + iocage_ip6: '-' + iocage_jid: '-' + iocage_properties: + CONFIG_VERSION: '28' + allow_chflags: '0' + allow_mlock: '0' + allow_mount: '0' + allow_mount_devfs: '0' + allow_mount_fusefs: '0' + allow_mount_nullfs: '0' + allow_mount_procfs: '0' + allow_mount_tmpfs: '0' + allow_mount_zfs: '0' + allow_quotas: '0' + allow_raw_sockets: '0' + allow_set_hostname: '1' + allow_socket_af: '0' + allow_sysvipc: '0' + allow_tun: '0' + allow_vmm: '0' + assign_localhost: '0' + available: readonly + basejail: '1' + boot: '0' + bpf: '0' + children_max: '0' + comment: none + compression: lz4 + compressratio: readonly + coredumpsize: 'off' + count: '1' + cpuset: 'off' + cputime: 'off' + datasize: 'off' + dedup: 'off' + defaultrouter: 10.1.0.10 + defaultrouter6: auto + depends: none + devfs_ruleset: '4' + dhcp: '0' + enforce_statfs: '2' + exec_clean: '1' + exec_created: /usr/bin/true + exec_fib: '0' + exec_jail_user: root + exec_poststart: /usr/bin/true + exec_poststop: /usr/bin/true + exec_prestart: /usr/bin/true + exec_prestop: /usr/bin/true + exec_start: /bin/sh /etc/rc + exec_stop: /bin/sh /etc/rc.shutdown + exec_system_jail_user: '0' + exec_system_user: root + exec_timeout: '60' + host_domainname: none + host_hostname: ansible-client + host_hostuuid: test_102 + host_time: '1' + hostid: 34333834-3734-5a43-3331-313342464631 + hostid_strict_check: '0' + interfaces: vnet0:bridge0 + ip4: new + ip4_addr: vnet0|10.1.0.102/24 + ip4_saddrsel: '1' + ip6: new + ip6_addr: none + ip6_saddrsel: '1' + ip_hostname: '0' + jail_zfs: '0' + jail_zfs_dataset: iocage/jails/test_102/data + jail_zfs_mountpoint: none + last_started: none + localhost_ip: none + login_flags: -f root + mac_prefix: 3e4a92 + maxproc: 'off' + memorylocked: 'off' + memoryuse: 'off' + min_dyn_devfs_ruleset: '1000' + mount_devfs: '1' + mount_fdescfs: '1' + mount_linprocfs: '0' + mount_procfs: '0' + mountpoint: readonly + msgqqueued: 'off' + msgqsize: 'off' + nat: '0' + nat_backend: ipfw + nat_forwards: none + nat_interface: none + nat_prefix: '172.16' + nmsgq: 'off' + notes: vmm=iocage_01 + nsem: 'off' + nsemop: 'off' + nshm: 'off' + nthr: 'off' + openfiles: 'off' + origin: readonly + owner: root + pcpu: 'off' + plugin_name: none + plugin_repository: none + priority: '99' + pseudoterminals: 'off' + quota: none + readbps: 'off' + readiops: 'off' + release: 13.4-RELEASE-p2 + reservation: none + resolver: /etc/resolv.conf + rlimits: 'off' + rtsold: '0' + securelevel: '2' + shmsize: 'off' + stacksize: 'off' + state: down + stop_timeout: '30' + swapuse: 'off' + sync_state: none + sync_target: none + sync_tgt_zpool: none + sysvmsg: new + sysvsem: new + sysvshm: new + template: '0' + type: jail + used: readonly + vmemoryuse: 'off' + vnet: '1' + vnet0_mac: none + vnet0_mtu: auto + vnet1_mac: none + vnet1_mtu: auto + vnet2_mac: none + vnet2_mtu: auto + vnet3_mac: none + vnet3_mtu: auto + vnet_default_interface: auto + vnet_default_mtu: '1500' + vnet_interfaces: none + wallclock: 'off' + writebps: 'off' + writeiops: 'off' + iocage_release: 13.4-RELEASE-p2 + iocage_state: down + iocage_template: ansible_client + iocage_type: jail + test_103: + iocage_basejail: 'yes' + iocage_boot: 'off' + iocage_ip4: 10.1.0.103 + iocage_ip6: '-' + iocage_jid: '-' + iocage_properties: + CONFIG_VERSION: '28' + allow_chflags: '0' + allow_mlock: '0' + allow_mount: '0' + allow_mount_devfs: '0' + allow_mount_fusefs: '0' + allow_mount_nullfs: '0' + allow_mount_procfs: '0' + allow_mount_tmpfs: '0' + allow_mount_zfs: '0' + allow_quotas: '0' + allow_raw_sockets: '0' + allow_set_hostname: '1' + allow_socket_af: '0' + allow_sysvipc: '0' + allow_tun: '0' + allow_vmm: '0' + assign_localhost: '0' + available: readonly + basejail: '1' + boot: '0' + bpf: '0' + children_max: '0' + comment: none + compression: lz4 + compressratio: readonly + coredumpsize: 'off' + count: '1' + cpuset: 'off' + cputime: 'off' + datasize: 'off' + dedup: 'off' + defaultrouter: 10.1.0.10 + defaultrouter6: auto + depends: none + devfs_ruleset: '4' + dhcp: '0' + enforce_statfs: '2' + exec_clean: '1' + exec_created: /usr/bin/true + exec_fib: '0' + exec_jail_user: root + exec_poststart: /usr/bin/true + exec_poststop: /usr/bin/true + exec_prestart: /usr/bin/true + exec_prestop: /usr/bin/true + exec_start: /bin/sh /etc/rc + exec_stop: /bin/sh /etc/rc.shutdown + exec_system_jail_user: '0' + exec_system_user: root + exec_timeout: '60' + host_domainname: none + host_hostname: ansible-client + host_hostuuid: test_103 + host_time: '1' + hostid: 34333834-3734-5a43-3331-313342464631 + hostid_strict_check: '0' + interfaces: vnet0:bridge0 + ip4: new + ip4_addr: vnet0|10.1.0.103/24 + ip4_saddrsel: '1' + ip6: new + ip6_addr: none + ip6_saddrsel: '1' + ip_hostname: '0' + jail_zfs: '0' + jail_zfs_dataset: iocage/jails/test_103/data + jail_zfs_mountpoint: none + last_started: none + localhost_ip: none + login_flags: -f root + mac_prefix: 3e4a92 + maxproc: 'off' + memorylocked: 'off' + memoryuse: 'off' + min_dyn_devfs_ruleset: '1000' + mount_devfs: '1' + mount_fdescfs: '1' + mount_linprocfs: '0' + mount_procfs: '0' + mountpoint: readonly + msgqqueued: 'off' + msgqsize: 'off' + nat: '0' + nat_backend: ipfw + nat_forwards: none + nat_interface: none + nat_prefix: '172.16' + nmsgq: 'off' + notes: vmm=iocage_01 + nsem: 'off' + nsemop: 'off' + nshm: 'off' + nthr: 'off' + openfiles: 'off' + origin: readonly + owner: root + pcpu: 'off' + plugin_name: none + plugin_repository: none + priority: '99' + pseudoterminals: 'off' + quota: none + readbps: 'off' + readiops: 'off' + release: 13.4-RELEASE-p2 + reservation: none + resolver: /etc/resolv.conf + rlimits: 'off' + rtsold: '0' + securelevel: '2' + shmsize: 'off' + stacksize: 'off' + state: down + stop_timeout: '30' + swapuse: 'off' + sync_state: none + sync_target: none + sync_tgt_zpool: none + sysvmsg: new + sysvsem: new + sysvshm: new + template: '0' + type: jail + used: readonly + vmemoryuse: 'off' + vnet: '1' + vnet0_mac: none + vnet0_mtu: auto + vnet1_mac: none + vnet1_mtu: auto + vnet2_mac: none + vnet2_mtu: auto + vnet3_mac: none + vnet3_mtu: auto + vnet_default_interface: auto + vnet_default_mtu: '1500' + vnet_interfaces: none + wallclock: 'off' + writebps: 'off' + writeiops: 'off' + iocage_release: 13.4-RELEASE-p2 + iocage_state: down + iocage_template: ansible_client + iocage_type: jail diff --git a/tests/unit/plugins/inventory/fixtures/iocage_inventory.yml.license b/tests/unit/plugins/inventory/fixtures/iocage_inventory.yml.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_inventory.yml.license @@ -0,0 +1,3 @@ +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 +SPDX-FileCopyrightText: Ansible Project diff --git a/tests/unit/plugins/inventory/fixtures/iocage_jails.txt b/tests/unit/plugins/inventory/fixtures/iocage_jails.txt new file mode 100644 index 0000000000..5152110550 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_jails.txt @@ -0,0 +1,3 @@ +- test_101 off down jail 13.4-RELEASE-p2 vnet0|10.1.0.101/24 - ansible_client yes +- test_102 off down jail 13.4-RELEASE-p2 vnet0|10.1.0.102/24 - ansible_client yes +- test_103 off down jail 13.4-RELEASE-p2 vnet0|10.1.0.103/24 - ansible_client yes diff --git a/tests/unit/plugins/inventory/fixtures/iocage_jails.txt.license b/tests/unit/plugins/inventory/fixtures/iocage_jails.txt.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_jails.txt.license @@ -0,0 +1,3 @@ +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 +SPDX-FileCopyrightText: Ansible Project diff --git a/tests/unit/plugins/inventory/fixtures/iocage_jails.yml b/tests/unit/plugins/inventory/fixtures/iocage_jails.yml new file mode 100644 index 0000000000..08eaa2dce4 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_jails.yml @@ -0,0 +1,32 @@ +_meta: + hostvars: + test_101: + iocage_basejail: 'yes' + iocage_boot: 'off' + iocage_ip4: 10.1.0.101 + iocage_ip6: '-' + iocage_jid: '-' + iocage_release: 13.4-RELEASE-p2 + iocage_state: down + iocage_template: ansible_client + iocage_type: jail + test_102: + iocage_basejail: 'yes' + iocage_boot: 'off' + iocage_ip4: 10.1.0.102 + iocage_ip6: '-' + iocage_jid: '-' + iocage_release: 13.4-RELEASE-p2 + iocage_state: down + iocage_template: ansible_client + iocage_type: jail + test_103: + iocage_basejail: 'yes' + iocage_boot: 'off' + iocage_ip4: 10.1.0.103 + iocage_ip6: '-' + iocage_jid: '-' + iocage_release: 13.4-RELEASE-p2 + iocage_state: down + iocage_template: ansible_client + iocage_type: jail diff --git a/tests/unit/plugins/inventory/fixtures/iocage_jails.yml.license b/tests/unit/plugins/inventory/fixtures/iocage_jails.yml.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_jails.yml.license @@ -0,0 +1,3 @@ +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 +SPDX-FileCopyrightText: Ansible Project diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties.txt b/tests/unit/plugins/inventory/fixtures/iocage_properties.txt new file mode 100644 index 0000000000..a24c8959ee --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties.txt @@ -0,0 +1,11 @@ +CONFIG_VERSION:28 +notes:abbridged_properties +allow_chflags:0 +allow_mlock:0 +allow_mount:0 +allow_mount_devfs:0 +allow_mount_fusefs:0 +allow_mount_nullfs:0 +allow_mount_procfs:0 +allow_mount_tmpfs:0 +allow_mount_zfs:0 diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties.txt.license b/tests/unit/plugins/inventory/fixtures/iocage_properties.txt.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties.txt.license @@ -0,0 +1,3 @@ +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 +SPDX-FileCopyrightText: Ansible Project diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties.yml b/tests/unit/plugins/inventory/fixtures/iocage_properties.yml new file mode 100644 index 0000000000..ffae1bf9d1 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties.yml @@ -0,0 +1,458 @@ +_meta: + hostvars: + test_101: + iocage_basejail: 'yes' + iocage_boot: 'off' + iocage_ip4: 10.1.0.101 + iocage_ip6: '-' + iocage_jid: '-' + iocage_properties: + CONFIG_VERSION: '28' + allow_chflags: '0' + allow_mlock: '0' + allow_mount: '0' + allow_mount_devfs: '0' + allow_mount_fusefs: '0' + allow_mount_nullfs: '0' + allow_mount_procfs: '0' + allow_mount_tmpfs: '0' + allow_mount_zfs: '0' + allow_quotas: '0' + allow_raw_sockets: '0' + allow_set_hostname: '1' + allow_socket_af: '0' + allow_sysvipc: '0' + allow_tun: '0' + allow_vmm: '0' + assign_localhost: '0' + available: readonly + basejail: '1' + boot: '0' + bpf: '0' + children_max: '0' + comment: none + compression: lz4 + compressratio: readonly + coredumpsize: 'off' + count: '1' + cpuset: 'off' + cputime: 'off' + datasize: 'off' + dedup: 'off' + defaultrouter: 10.1.0.10 + defaultrouter6: auto + depends: none + devfs_ruleset: '4' + dhcp: '0' + enforce_statfs: '2' + exec_clean: '1' + exec_created: /usr/bin/true + exec_fib: '0' + exec_jail_user: root + exec_poststart: /usr/bin/true + exec_poststop: /usr/bin/true + exec_prestart: /usr/bin/true + exec_prestop: /usr/bin/true + exec_start: /bin/sh /etc/rc + exec_stop: /bin/sh /etc/rc.shutdown + exec_system_jail_user: '0' + exec_system_user: root + exec_timeout: '60' + host_domainname: none + host_hostname: ansible-client + host_hostuuid: test_101 + host_time: '1' + hostid: 34333834-3734-5a43-3331-313342464631 + hostid_strict_check: '0' + interfaces: vnet0:bridge0 + ip4: new + ip4_addr: vnet0|10.1.0.101/24 + ip4_saddrsel: '1' + ip6: new + ip6_addr: none + ip6_saddrsel: '1' + ip_hostname: '0' + jail_zfs: '0' + jail_zfs_dataset: iocage/jails/test_101/data + jail_zfs_mountpoint: none + last_started: none + localhost_ip: none + login_flags: -f root + mac_prefix: 3e4a92 + maxproc: 'off' + memorylocked: 'off' + memoryuse: 'off' + min_dyn_devfs_ruleset: '1000' + mount_devfs: '1' + mount_fdescfs: '1' + mount_linprocfs: '0' + mount_procfs: '0' + mountpoint: readonly + msgqqueued: 'off' + msgqsize: 'off' + nat: '0' + nat_backend: ipfw + nat_forwards: none + nat_interface: none + nat_prefix: '172.16' + nmsgq: 'off' + notes: vmm=iocage_01 + nsem: 'off' + nsemop: 'off' + nshm: 'off' + nthr: 'off' + openfiles: 'off' + origin: readonly + owner: root + pcpu: 'off' + plugin_name: none + plugin_repository: none + priority: '99' + pseudoterminals: 'off' + quota: none + readbps: 'off' + readiops: 'off' + release: 13.4-RELEASE-p2 + reservation: none + resolver: /etc/resolv.conf + rlimits: 'off' + rtsold: '0' + securelevel: '2' + shmsize: 'off' + stacksize: 'off' + state: down + stop_timeout: '30' + swapuse: 'off' + sync_state: none + sync_target: none + sync_tgt_zpool: none + sysvmsg: new + sysvsem: new + sysvshm: new + template: '0' + type: jail + used: readonly + vmemoryuse: 'off' + vnet: '1' + vnet0_mac: none + vnet0_mtu: auto + vnet1_mac: none + vnet1_mtu: auto + vnet2_mac: none + vnet2_mtu: auto + vnet3_mac: none + vnet3_mtu: auto + vnet_default_interface: auto + vnet_default_mtu: '1500' + vnet_interfaces: none + wallclock: 'off' + writebps: 'off' + writeiops: 'off' + iocage_release: 13.4-RELEASE-p2 + iocage_state: down + iocage_template: ansible_client + iocage_type: jail + test_102: + iocage_basejail: 'yes' + iocage_boot: 'off' + iocage_ip4: 10.1.0.102 + iocage_ip6: '-' + iocage_jid: '-' + iocage_properties: + CONFIG_VERSION: '28' + allow_chflags: '0' + allow_mlock: '0' + allow_mount: '0' + allow_mount_devfs: '0' + allow_mount_fusefs: '0' + allow_mount_nullfs: '0' + allow_mount_procfs: '0' + allow_mount_tmpfs: '0' + allow_mount_zfs: '0' + allow_quotas: '0' + allow_raw_sockets: '0' + allow_set_hostname: '1' + allow_socket_af: '0' + allow_sysvipc: '0' + allow_tun: '0' + allow_vmm: '0' + assign_localhost: '0' + available: readonly + basejail: '1' + boot: '0' + bpf: '0' + children_max: '0' + comment: none + compression: lz4 + compressratio: readonly + coredumpsize: 'off' + count: '1' + cpuset: 'off' + cputime: 'off' + datasize: 'off' + dedup: 'off' + defaultrouter: 10.1.0.10 + defaultrouter6: auto + depends: none + devfs_ruleset: '4' + dhcp: '0' + enforce_statfs: '2' + exec_clean: '1' + exec_created: /usr/bin/true + exec_fib: '0' + exec_jail_user: root + exec_poststart: /usr/bin/true + exec_poststop: /usr/bin/true + exec_prestart: /usr/bin/true + exec_prestop: /usr/bin/true + exec_start: /bin/sh /etc/rc + exec_stop: /bin/sh /etc/rc.shutdown + exec_system_jail_user: '0' + exec_system_user: root + exec_timeout: '60' + host_domainname: none + host_hostname: ansible-client + host_hostuuid: test_102 + host_time: '1' + hostid: 34333834-3734-5a43-3331-313342464631 + hostid_strict_check: '0' + interfaces: vnet0:bridge0 + ip4: new + ip4_addr: vnet0|10.1.0.102/24 + ip4_saddrsel: '1' + ip6: new + ip6_addr: none + ip6_saddrsel: '1' + ip_hostname: '0' + jail_zfs: '0' + jail_zfs_dataset: iocage/jails/test_102/data + jail_zfs_mountpoint: none + last_started: none + localhost_ip: none + login_flags: -f root + mac_prefix: 3e4a92 + maxproc: 'off' + memorylocked: 'off' + memoryuse: 'off' + min_dyn_devfs_ruleset: '1000' + mount_devfs: '1' + mount_fdescfs: '1' + mount_linprocfs: '0' + mount_procfs: '0' + mountpoint: readonly + msgqqueued: 'off' + msgqsize: 'off' + nat: '0' + nat_backend: ipfw + nat_forwards: none + nat_interface: none + nat_prefix: '172.16' + nmsgq: 'off' + notes: vmm=iocage_01 + nsem: 'off' + nsemop: 'off' + nshm: 'off' + nthr: 'off' + openfiles: 'off' + origin: readonly + owner: root + pcpu: 'off' + plugin_name: none + plugin_repository: none + priority: '99' + pseudoterminals: 'off' + quota: none + readbps: 'off' + readiops: 'off' + release: 13.4-RELEASE-p2 + reservation: none + resolver: /etc/resolv.conf + rlimits: 'off' + rtsold: '0' + securelevel: '2' + shmsize: 'off' + stacksize: 'off' + state: down + stop_timeout: '30' + swapuse: 'off' + sync_state: none + sync_target: none + sync_tgt_zpool: none + sysvmsg: new + sysvsem: new + sysvshm: new + template: '0' + type: jail + used: readonly + vmemoryuse: 'off' + vnet: '1' + vnet0_mac: none + vnet0_mtu: auto + vnet1_mac: none + vnet1_mtu: auto + vnet2_mac: none + vnet2_mtu: auto + vnet3_mac: none + vnet3_mtu: auto + vnet_default_interface: auto + vnet_default_mtu: '1500' + vnet_interfaces: none + wallclock: 'off' + writebps: 'off' + writeiops: 'off' + iocage_release: 13.4-RELEASE-p2 + iocage_state: down + iocage_template: ansible_client + iocage_type: jail + test_103: + iocage_basejail: 'yes' + iocage_boot: 'off' + iocage_ip4: 10.1.0.103 + iocage_ip6: '-' + iocage_jid: '-' + iocage_properties: + CONFIG_VERSION: '28' + allow_chflags: '0' + allow_mlock: '0' + allow_mount: '0' + allow_mount_devfs: '0' + allow_mount_fusefs: '0' + allow_mount_nullfs: '0' + allow_mount_procfs: '0' + allow_mount_tmpfs: '0' + allow_mount_zfs: '0' + allow_quotas: '0' + allow_raw_sockets: '0' + allow_set_hostname: '1' + allow_socket_af: '0' + allow_sysvipc: '0' + allow_tun: '0' + allow_vmm: '0' + assign_localhost: '0' + available: readonly + basejail: '1' + boot: '0' + bpf: '0' + children_max: '0' + comment: none + compression: lz4 + compressratio: readonly + coredumpsize: 'off' + count: '1' + cpuset: 'off' + cputime: 'off' + datasize: 'off' + dedup: 'off' + defaultrouter: 10.1.0.10 + defaultrouter6: auto + depends: none + devfs_ruleset: '4' + dhcp: '0' + enforce_statfs: '2' + exec_clean: '1' + exec_created: /usr/bin/true + exec_fib: '0' + exec_jail_user: root + exec_poststart: /usr/bin/true + exec_poststop: /usr/bin/true + exec_prestart: /usr/bin/true + exec_prestop: /usr/bin/true + exec_start: /bin/sh /etc/rc + exec_stop: /bin/sh /etc/rc.shutdown + exec_system_jail_user: '0' + exec_system_user: root + exec_timeout: '60' + host_domainname: none + host_hostname: ansible-client + host_hostuuid: test_103 + host_time: '1' + hostid: 34333834-3734-5a43-3331-313342464631 + hostid_strict_check: '0' + interfaces: vnet0:bridge0 + ip4: new + ip4_addr: vnet0|10.1.0.103/24 + ip4_saddrsel: '1' + ip6: new + ip6_addr: none + ip6_saddrsel: '1' + ip_hostname: '0' + jail_zfs: '0' + jail_zfs_dataset: iocage/jails/test_103/data + jail_zfs_mountpoint: none + last_started: none + localhost_ip: none + login_flags: -f root + mac_prefix: 3e4a92 + maxproc: 'off' + memorylocked: 'off' + memoryuse: 'off' + min_dyn_devfs_ruleset: '1000' + mount_devfs: '1' + mount_fdescfs: '1' + mount_linprocfs: '0' + mount_procfs: '0' + mountpoint: readonly + msgqqueued: 'off' + msgqsize: 'off' + nat: '0' + nat_backend: ipfw + nat_forwards: none + nat_interface: none + nat_prefix: '172.16' + nmsgq: 'off' + notes: vmm=iocage_01 + nsem: 'off' + nsemop: 'off' + nshm: 'off' + nthr: 'off' + openfiles: 'off' + origin: readonly + owner: root + pcpu: 'off' + plugin_name: none + plugin_repository: none + priority: '99' + pseudoterminals: 'off' + quota: none + readbps: 'off' + readiops: 'off' + release: 13.4-RELEASE-p2 + reservation: none + resolver: /etc/resolv.conf + rlimits: 'off' + rtsold: '0' + securelevel: '2' + shmsize: 'off' + stacksize: 'off' + state: down + stop_timeout: '30' + swapuse: 'off' + sync_state: none + sync_target: none + sync_tgt_zpool: none + sysvmsg: new + sysvsem: new + sysvshm: new + template: '0' + type: jail + used: readonly + vmemoryuse: 'off' + vnet: '1' + vnet0_mac: none + vnet0_mtu: auto + vnet1_mac: none + vnet1_mtu: auto + vnet2_mac: none + vnet2_mtu: auto + vnet3_mac: none + vnet3_mtu: auto + vnet_default_interface: auto + vnet_default_mtu: '1500' + vnet_interfaces: none + wallclock: 'off' + writebps: 'off' + writeiops: 'off' + iocage_release: 13.4-RELEASE-p2 + iocage_state: down + iocage_template: ansible_client + iocage_type: jail diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties.yml.license b/tests/unit/plugins/inventory/fixtures/iocage_properties.yml.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties.yml.license @@ -0,0 +1,3 @@ +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 +SPDX-FileCopyrightText: Ansible Project diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties_test_101.txt b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_101.txt new file mode 100644 index 0000000000..881f347911 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_101.txt @@ -0,0 +1,141 @@ +CONFIG_VERSION:28 +allow_chflags:0 +allow_mlock:0 +allow_mount:0 +allow_mount_devfs:0 +allow_mount_fusefs:0 +allow_mount_nullfs:0 +allow_mount_procfs:0 +allow_mount_tmpfs:0 +allow_mount_zfs:0 +allow_quotas:0 +allow_raw_sockets:0 +allow_set_hostname:1 +allow_socket_af:0 +allow_sysvipc:0 +allow_tun:0 +allow_vmm:0 +assign_localhost:0 +available:readonly +basejail:1 +boot:0 +bpf:0 +children_max:0 +comment:none +compression:lz4 +compressratio:readonly +coredumpsize:off +count:1 +cpuset:off +cputime:off +datasize:off +dedup:off +defaultrouter:10.1.0.10 +defaultrouter6:auto +depends:none +devfs_ruleset:4 +dhcp:0 +enforce_statfs:2 +exec_clean:1 +exec_created:/usr/bin/true +exec_fib:0 +exec_jail_user:root +exec_poststart:/usr/bin/true +exec_poststop:/usr/bin/true +exec_prestart:/usr/bin/true +exec_prestop:/usr/bin/true +exec_start:/bin/sh /etc/rc +exec_stop:/bin/sh /etc/rc.shutdown +exec_system_jail_user:0 +exec_system_user:root +exec_timeout:60 +host_domainname:none +host_hostname:ansible-client +host_hostuuid:test_101 +host_time:1 +hostid:34333834-3734-5a43-3331-313342464631 +hostid_strict_check:0 +interfaces:vnet0:bridge0 +ip4:new +ip4_addr:vnet0|10.1.0.101/24 +ip4_saddrsel:1 +ip6:new +ip6_addr:none +ip6_saddrsel:1 +ip_hostname:0 +jail_zfs:0 +jail_zfs_dataset:iocage/jails/test_101/data +jail_zfs_mountpoint:none +last_started:none +localhost_ip:none +login_flags:-f root +mac_prefix:3e4a92 +maxproc:off +memorylocked:off +memoryuse:off +min_dyn_devfs_ruleset:1000 +mount_devfs:1 +mount_fdescfs:1 +mount_linprocfs:0 +mount_procfs:0 +mountpoint:readonly +msgqqueued:off +msgqsize:off +nat:0 +nat_backend:ipfw +nat_forwards:none +nat_interface:none +nat_prefix:172.16 +nmsgq:off +notes:vmm=iocage_01 +nsem:off +nsemop:off +nshm:off +nthr:off +openfiles:off +origin:readonly +owner:root +pcpu:off +plugin_name:none +plugin_repository:none +priority:99 +pseudoterminals:off +quota:none +readbps:off +readiops:off +release:13.4-RELEASE-p2 +reservation:none +resolver:/etc/resolv.conf +rlimits:off +rtsold:0 +securelevel:2 +shmsize:off +stacksize:off +state:down +stop_timeout:30 +swapuse:off +sync_state:none +sync_target:none +sync_tgt_zpool:none +sysvmsg:new +sysvsem:new +sysvshm:new +template:0 +type:jail +used:readonly +vmemoryuse:off +vnet:1 +vnet0_mac:none +vnet0_mtu:auto +vnet1_mac:none +vnet1_mtu:auto +vnet2_mac:none +vnet2_mtu:auto +vnet3_mac:none +vnet3_mtu:auto +vnet_default_interface:auto +vnet_default_mtu:1500 +vnet_interfaces:none +wallclock:off +writebps:off +writeiops:off diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties_test_101.txt.license b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_101.txt.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_101.txt.license @@ -0,0 +1,3 @@ +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 +SPDX-FileCopyrightText: Ansible Project diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties_test_102.txt b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_102.txt new file mode 100644 index 0000000000..065c777b9c --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_102.txt @@ -0,0 +1,141 @@ +CONFIG_VERSION:28 +allow_chflags:0 +allow_mlock:0 +allow_mount:0 +allow_mount_devfs:0 +allow_mount_fusefs:0 +allow_mount_nullfs:0 +allow_mount_procfs:0 +allow_mount_tmpfs:0 +allow_mount_zfs:0 +allow_quotas:0 +allow_raw_sockets:0 +allow_set_hostname:1 +allow_socket_af:0 +allow_sysvipc:0 +allow_tun:0 +allow_vmm:0 +assign_localhost:0 +available:readonly +basejail:1 +boot:0 +bpf:0 +children_max:0 +comment:none +compression:lz4 +compressratio:readonly +coredumpsize:off +count:1 +cpuset:off +cputime:off +datasize:off +dedup:off +defaultrouter:10.1.0.10 +defaultrouter6:auto +depends:none +devfs_ruleset:4 +dhcp:0 +enforce_statfs:2 +exec_clean:1 +exec_created:/usr/bin/true +exec_fib:0 +exec_jail_user:root +exec_poststart:/usr/bin/true +exec_poststop:/usr/bin/true +exec_prestart:/usr/bin/true +exec_prestop:/usr/bin/true +exec_start:/bin/sh /etc/rc +exec_stop:/bin/sh /etc/rc.shutdown +exec_system_jail_user:0 +exec_system_user:root +exec_timeout:60 +host_domainname:none +host_hostname:ansible-client +host_hostuuid:test_102 +host_time:1 +hostid:34333834-3734-5a43-3331-313342464631 +hostid_strict_check:0 +interfaces:vnet0:bridge0 +ip4:new +ip4_addr:vnet0|10.1.0.102/24 +ip4_saddrsel:1 +ip6:new +ip6_addr:none +ip6_saddrsel:1 +ip_hostname:0 +jail_zfs:0 +jail_zfs_dataset:iocage/jails/test_102/data +jail_zfs_mountpoint:none +last_started:none +localhost_ip:none +login_flags:-f root +mac_prefix:3e4a92 +maxproc:off +memorylocked:off +memoryuse:off +min_dyn_devfs_ruleset:1000 +mount_devfs:1 +mount_fdescfs:1 +mount_linprocfs:0 +mount_procfs:0 +mountpoint:readonly +msgqqueued:off +msgqsize:off +nat:0 +nat_backend:ipfw +nat_forwards:none +nat_interface:none +nat_prefix:172.16 +nmsgq:off +notes:vmm=iocage_01 +nsem:off +nsemop:off +nshm:off +nthr:off +openfiles:off +origin:readonly +owner:root +pcpu:off +plugin_name:none +plugin_repository:none +priority:99 +pseudoterminals:off +quota:none +readbps:off +readiops:off +release:13.4-RELEASE-p2 +reservation:none +resolver:/etc/resolv.conf +rlimits:off +rtsold:0 +securelevel:2 +shmsize:off +stacksize:off +state:down +stop_timeout:30 +swapuse:off +sync_state:none +sync_target:none +sync_tgt_zpool:none +sysvmsg:new +sysvsem:new +sysvshm:new +template:0 +type:jail +used:readonly +vmemoryuse:off +vnet:1 +vnet0_mac:none +vnet0_mtu:auto +vnet1_mac:none +vnet1_mtu:auto +vnet2_mac:none +vnet2_mtu:auto +vnet3_mac:none +vnet3_mtu:auto +vnet_default_interface:auto +vnet_default_mtu:1500 +vnet_interfaces:none +wallclock:off +writebps:off +writeiops:off diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties_test_102.txt.license b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_102.txt.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_102.txt.license @@ -0,0 +1,3 @@ +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 +SPDX-FileCopyrightText: Ansible Project diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties_test_103.txt b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_103.txt new file mode 100644 index 0000000000..0050a989f5 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_103.txt @@ -0,0 +1,141 @@ +CONFIG_VERSION:28 +allow_chflags:0 +allow_mlock:0 +allow_mount:0 +allow_mount_devfs:0 +allow_mount_fusefs:0 +allow_mount_nullfs:0 +allow_mount_procfs:0 +allow_mount_tmpfs:0 +allow_mount_zfs:0 +allow_quotas:0 +allow_raw_sockets:0 +allow_set_hostname:1 +allow_socket_af:0 +allow_sysvipc:0 +allow_tun:0 +allow_vmm:0 +assign_localhost:0 +available:readonly +basejail:1 +boot:0 +bpf:0 +children_max:0 +comment:none +compression:lz4 +compressratio:readonly +coredumpsize:off +count:1 +cpuset:off +cputime:off +datasize:off +dedup:off +defaultrouter:10.1.0.10 +defaultrouter6:auto +depends:none +devfs_ruleset:4 +dhcp:0 +enforce_statfs:2 +exec_clean:1 +exec_created:/usr/bin/true +exec_fib:0 +exec_jail_user:root +exec_poststart:/usr/bin/true +exec_poststop:/usr/bin/true +exec_prestart:/usr/bin/true +exec_prestop:/usr/bin/true +exec_start:/bin/sh /etc/rc +exec_stop:/bin/sh /etc/rc.shutdown +exec_system_jail_user:0 +exec_system_user:root +exec_timeout:60 +host_domainname:none +host_hostname:ansible-client +host_hostuuid:test_103 +host_time:1 +hostid:34333834-3734-5a43-3331-313342464631 +hostid_strict_check:0 +interfaces:vnet0:bridge0 +ip4:new +ip4_addr:vnet0|10.1.0.103/24 +ip4_saddrsel:1 +ip6:new +ip6_addr:none +ip6_saddrsel:1 +ip_hostname:0 +jail_zfs:0 +jail_zfs_dataset:iocage/jails/test_103/data +jail_zfs_mountpoint:none +last_started:none +localhost_ip:none +login_flags:-f root +mac_prefix:3e4a92 +maxproc:off +memorylocked:off +memoryuse:off +min_dyn_devfs_ruleset:1000 +mount_devfs:1 +mount_fdescfs:1 +mount_linprocfs:0 +mount_procfs:0 +mountpoint:readonly +msgqqueued:off +msgqsize:off +nat:0 +nat_backend:ipfw +nat_forwards:none +nat_interface:none +nat_prefix:172.16 +nmsgq:off +notes:vmm=iocage_01 +nsem:off +nsemop:off +nshm:off +nthr:off +openfiles:off +origin:readonly +owner:root +pcpu:off +plugin_name:none +plugin_repository:none +priority:99 +pseudoterminals:off +quota:none +readbps:off +readiops:off +release:13.4-RELEASE-p2 +reservation:none +resolver:/etc/resolv.conf +rlimits:off +rtsold:0 +securelevel:2 +shmsize:off +stacksize:off +state:down +stop_timeout:30 +swapuse:off +sync_state:none +sync_target:none +sync_tgt_zpool:none +sysvmsg:new +sysvsem:new +sysvshm:new +template:0 +type:jail +used:readonly +vmemoryuse:off +vnet:1 +vnet0_mac:none +vnet0_mtu:auto +vnet1_mac:none +vnet1_mtu:auto +vnet2_mac:none +vnet2_mtu:auto +vnet3_mac:none +vnet3_mtu:auto +vnet_default_interface:auto +vnet_default_mtu:1500 +vnet_interfaces:none +wallclock:off +writebps:off +writeiops:off diff --git a/tests/unit/plugins/inventory/fixtures/iocage_properties_test_103.txt.license b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_103.txt.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/unit/plugins/inventory/fixtures/iocage_properties_test_103.txt.license @@ -0,0 +1,3 @@ +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 +SPDX-FileCopyrightText: Ansible Project diff --git a/tests/unit/plugins/inventory/test_iocage.py b/tests/unit/plugins/inventory/test_iocage.py new file mode 100644 index 0000000000..1a0aa22d16 --- /dev/null +++ b/tests/unit/plugins/inventory/test_iocage.py @@ -0,0 +1,112 @@ +# -*- 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 (absolute_import, division, print_function) +__metaclass__ = type + +import pytest +import yaml + +from ansible.inventory.data import InventoryData +from ansible.template import Templar +from ansible_collections.community.general.plugins.inventory.iocage import InventoryModule + + +@pytest.fixture +def inventory(): + inv = InventoryModule() + inv.inventory = InventoryData() + inv.templar = Templar(None) + inv.jails = load_txt_data('tests/unit/plugins/inventory/fixtures/iocage_jails.txt') + inv.js_ok = load_yml_data('tests/unit/plugins/inventory/fixtures/iocage_jails.yml') + prpts_101 = load_txt_data('tests/unit/plugins/inventory/fixtures/iocage_properties_test_101.txt') + prpts_102 = load_txt_data('tests/unit/plugins/inventory/fixtures/iocage_properties_test_102.txt') + prpts_103 = load_txt_data('tests/unit/plugins/inventory/fixtures/iocage_properties_test_103.txt') + inv.prpts = {'test_101': prpts_101, 'test_102': prpts_102, 'test_103': prpts_103} + inv.ps_ok = load_yml_data('tests/unit/plugins/inventory/fixtures/iocage_properties.yml') + inv.ok = load_yml_data('tests/unit/plugins/inventory/fixtures/iocage_inventory.yml') + return inv + + +def load_txt_data(path): + f = open(path, 'r') + s = f.read() + f.close() + return s + + +def load_yml_data(path): + f = open(path, 'r') + d = yaml.safe_load(f) + f.close() + return d + + +def get_option(option): + groups = {} + groups['test'] = "inventory_hostname.startswith('test')" + + if option == 'groups': + return groups + elif option == 'keyed_groups': + return [] + elif option == 'compose': + return {} + elif option == 'strict': + return False + else: + return None + + +def test_verify_file_bad_config(inventory): + assert inventory.verify_file('foobar.iocage.yml') is False + + +def test_verify_file(tmp_path, inventory): + file = tmp_path / "foobar.iocage.yml" + file.touch() + assert inventory.verify_file(str(file)) + + +def test_get_jails(inventory): + results = {'_meta': {'hostvars': {}}} + inventory.get_jails(inventory.jails, results) + assert results == inventory.js_ok + + +def test_get_properties(inventory): + results = {'_meta': {'hostvars': {}}} + inventory.get_jails(inventory.jails, results) + for hostname, host_vars in results['_meta']['hostvars'].items(): + inventory.get_properties(inventory.prpts[hostname], results, hostname) + assert results == inventory.ps_ok + + +def test_populate(inventory, mocker): + results = {'_meta': {'hostvars': {}}} + inventory.get_jails(inventory.jails, results) + for hostname, host_vars in results['_meta']['hostvars'].items(): + inventory.get_properties(inventory.prpts[hostname], results, hostname) + inventory.get_option = mocker.MagicMock(side_effect=get_option) + inventory.populate(results) + + # test + hosts = ('test_101', 'test_102', 'test_103') + vars = ('iocage_basejail', 'iocage_boot', 'iocage_ip4', 'iocage_ip6', 'iocage_properties', + 'iocage_release', 'iocage_state', 'iocage_template', 'iocage_type') + + # test host_vars + for host in hosts: + h = inventory.inventory.get_host(host) + for var in vars: + assert inventory.ok['all']['children']['test']['hosts'][host][var] == h.get_vars()[var] + + # test groups + test_101_info = inventory.inventory.get_host('test_101') + test_102_info = inventory.inventory.get_host('test_102') + test_103_info = inventory.inventory.get_host('test_103') + g = inventory.inventory.groups['test'] + assert g.hosts == [test_101_info, test_102_info, test_103_info] From e38f9e5cfc895927980741190b224e4e1a405a47 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 25 Dec 2024 22:56:20 +0100 Subject: [PATCH 092/302] [PR #9373/d96e5604 backport][stable-10] [onev ... ovh]*.py: normalize docs (#9381) [onev ... ovh]*.py: normalize docs (#9373) * [onev ... ovh]*.py: normalize docs * Apply suggestions from code review Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit d96e56048f1b2e269f3a274fa81be42b77976887) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/oneview_datacenter_info.py | 62 +++---- plugins/modules/oneview_enclosure_info.py | 86 +++++---- plugins/modules/oneview_ethernet_network.py | 88 +++++---- .../modules/oneview_ethernet_network_info.py | 68 ++++--- plugins/modules/oneview_fc_network.py | 64 ++++--- plugins/modules/oneview_fc_network_info.py | 44 +++-- plugins/modules/oneview_fcoe_network.py | 66 ++++--- plugins/modules/oneview_fcoe_network_info.py | 44 +++-- .../oneview_logical_interconnect_group.py | 84 +++++---- ...oneview_logical_interconnect_group_info.py | 44 +++-- plugins/modules/oneview_network_set.py | 76 ++++---- plugins/modules/oneview_network_set_info.py | 61 +++--- plugins/modules/oneview_san_manager.py | 73 ++++---- plugins/modules/oneview_san_manager_info.py | 62 +++---- plugins/modules/online_server_info.py | 18 +- plugins/modules/online_user_info.py | 14 +- plugins/modules/open_iscsi.py | 174 +++++++++--------- plugins/modules/openbsd_pkg.py | 120 ++++++------ plugins/modules/opendj_backendprop.py | 157 ++++++++-------- plugins/modules/openwrt_init.py | 76 ++++---- plugins/modules/opkg.py | 113 ++++++------ plugins/modules/osx_defaults.py | 24 ++- plugins/modules/ovh_ip_failover.py | 141 +++++++------- .../modules/ovh_ip_loadbalancing_backend.py | 139 +++++++------- plugins/modules/ovh_monthly_billing.py | 79 ++++---- 25 files changed, 956 insertions(+), 1021 deletions(-) diff --git a/plugins/modules/oneview_datacenter_info.py b/plugins/modules/oneview_datacenter_info.py index ed04e2279f..831bd59f61 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..21feee769b 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 @@ -125,12 +122,11 @@ EXAMPLES = ''' ansible.builtin.debug: 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" +- name: "Gather information about an Enclosure with temperature data at a resolution of one sample per day, between two 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 +148,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..6eb4f46a19 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..866dabc6b8 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,15 +55,15 @@ 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 + # Alternatively you can inform permittedInterconnectTypeUri delegate_to: localhost - name: Ensure that the Logical Interconnect Group has the specified scopes @@ -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..f3a4ace3da 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..8c03bda463 100644 --- a/plugins/modules/oneview_san_manager.py +++ b/plugins/modules/oneview_san_manager.py @@ -7,47 +7,46 @@ 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 +122,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..15e20a241a 100644 --- a/plugins/modules/open_iscsi.py +++ b/plugins/modules/open_iscsi.py @@ -8,103 +8,99 @@ 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 +140,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..394a5b75e2 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 @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 @@ -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..7b48587faf 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 = ''' +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 -''' + 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..aa708f08f8 100644 --- a/plugins/modules/openwrt_init.py +++ b/plugins/modules/openwrt_init.py @@ -8,52 +8,50 @@ 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 +71,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 32cb2753f5..40c48f3800 100644 --- a/plugins/modules/opkg.py +++ b/plugins/modules/opkg.py @@ -11,71 +11,68 @@ 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. - - 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 + 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. + - 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 @@ -109,9 +106,9 @@ EXAMPLES = ''' name: foo state: present force: overwrite -''' +""" -RETURN = """ +RETURN = r""" version: description: Version of opkg. type: str diff --git a/plugins/modules/osx_defaults.py b/plugins/modules/osx_defaults.py index db5d889a37..1cc541377c 100644 --- a/plugins/modules/osx_defaults.py +++ b/plugins/modules/osx_defaults.py @@ -10,18 +10,16 @@ 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 +46,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 +70,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 +78,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 +133,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..d69c176fbd 100644 --- a/plugins/modules/ovh_ip_failover.py +++ b/plugins/modules/ovh_ip_failover.py @@ -9,88 +9,79 @@ 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 +107,10 @@ EXAMPLES = ''' application_key: yourkey application_secret: yoursecret consumer_key: yourconsumerkey -''' +""" -RETURN = ''' -''' +RETURN = r""" +""" import time diff --git a/plugins/modules/ovh_ip_loadbalancing_backend.py b/plugins/modules/ovh_ip_loadbalancing_backend.py index f70b5804a7..0f0ad2f09e 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 (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 +""" -''' - -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 From 45a3396ab0b66f2c13626a2e3ae358f859db916e Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Wed, 25 Dec 2024 22:58:57 +0100 Subject: [PATCH 093/302] [PR #9371/13e2097f backport][stable-10] [pi ... prof]*: normalize docs (#9380) [pi ... prof]*: normalize docs (#9371) * [pi ... prof]*: normalize docs * Update plugins/modules/pkg5_publisher.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 13e2097f378771d18df58b741d96020d56d5197c) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/pids.py | 21 +- plugins/modules/pingdom.py | 81 ++++---- plugins/modules/pip_package_info.py | 25 +-- plugins/modules/pipx.py | 138 +++++++------- plugins/modules/pipx_info.py | 35 ++-- plugins/modules/pkg5.py | 19 +- plugins/modules/pkg5_publisher.py | 19 +- plugins/modules/pkgin.py | 108 +++++------ plugins/modules/pkgng.py | 179 +++++++++--------- plugins/modules/pkgutil.py | 49 +++-- plugins/modules/pmem.py | 148 +++++++-------- plugins/modules/pnpm.py | 34 ++-- plugins/modules/portage.py | 82 ++++---- plugins/modules/portinstall.py | 59 +++--- plugins/modules/pritunl_org.py | 71 ++++--- plugins/modules/pritunl_org_info.py | 33 ++-- plugins/modules/pritunl_user.py | 154 +++++++-------- plugins/modules/pritunl_user_info.py | 59 +++--- plugins/modules/profitbricks.py | 40 ++-- plugins/modules/profitbricks_datacenter.py | 27 ++- plugins/modules/profitbricks_nic.py | 27 ++- plugins/modules/profitbricks_volume.py | 35 ++-- .../profitbricks_volume_attachments.py | 25 ++- 23 files changed, 702 insertions(+), 766 deletions(-) diff --git a/plugins/modules/pids.py b/plugins/modules/pids.py index 99b52ef1dd..aea4d82d37 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..0bc08e7ce1 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 1706f125d9..aa4309ce6c 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,128 @@ 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,16 +177,16 @@ 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 = """ +RETURN = r""" version: description: Version of pipx. type: str diff --git a/plugins/modules/pipx_info.py b/plugins/modules/pipx_info.py index 24a6739024..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: 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..76423f8135 100644 --- a/plugins/modules/pkgin.py +++ b/plugins/modules/pkgin.py @@ -16,70 +16,66 @@ 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 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 +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install package foo community.general.pkgin: name: foo @@ -125,7 +121,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..ae333b492b 100644 --- a/plugins/modules/pkgng.py +++ b/plugins/modules/pkgng.py @@ -14,107 +14,100 @@ 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 +142,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..ce85308651 100644 --- a/plugins/modules/pkgutil.py +++ b/plugins/modules/pkgutil.py @@ -12,19 +12,18 @@ 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 @@ -35,40 +34,40 @@ attributes: 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's 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 +87,8 @@ EXAMPLES = r''' - name: Install several packages community.general.pkgutil: name: - - CSWsudo - - CSWtop + - CSWsudo + - CSWtop state: present - name: Update all packages @@ -102,9 +101,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..4e6edfeb06 100644 --- a/plugins/modules/pmem.py +++ b/plugins/modules/pmem.py @@ -7,21 +7,19 @@ 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 +28,31 @@ 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 +62,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 +82,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 +201,7 @@ EXAMPLES = r''' - size: 320MB type: pmem mode: sector -''' +""" import json import re 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..f0b7220836 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,13 @@ 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 +185,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 +244,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..d97f9567cd 100644 --- a/plugins/modules/pritunl_org.py +++ b/plugins/modules/pritunl_org.py @@ -8,54 +8,47 @@ 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 +60,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..932c4c1322 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..e912db6985 100644 --- a/plugins/modules/profitbricks.py +++ b/plugins/modules/profitbricks.py @@ -8,13 +8,12 @@ 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. extends_documentation_fragment: - community.general.attributes attributes: @@ -34,7 +33,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 +64,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 +75,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 +92,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 +105,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 +190,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..93c27b5d8d 100644 --- a/plugins/modules/profitbricks_datacenter.py +++ b/plugins/modules/profitbricks_datacenter.py @@ -8,13 +8,12 @@ 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. extends_documentation_fragment: - community.general.attributes attributes: @@ -38,41 +37,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 +82,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..0b559a6fed 100644 --- a/plugins/modules/profitbricks_nic.py +++ b/plugins/modules/profitbricks_nic.py @@ -8,12 +8,11 @@ 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. extends_documentation_fragment: - community.general.attributes attributes: @@ -39,42 +38,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 +89,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..48bacb2061 100644 --- a/plugins/modules/profitbricks_volume.py +++ b/plugins/modules/profitbricks_volume.py @@ -8,12 +8,11 @@ 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. extends_documentation_fragment: - community.general.attributes attributes: @@ -42,10 +41,10 @@ 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 +63,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 +84,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 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 +121,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 +143,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..63ca6775ab 100644 --- a/plugins/modules/profitbricks_volume_attachments.py +++ b/plugins/modules/profitbricks_volume_attachments.py @@ -8,12 +8,11 @@ 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. extends_documentation_fragment: - community.general.attributes attributes: @@ -36,38 +35,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 +82,7 @@ EXAMPLES = ''' volume: vol01 wait_timeout: 500 state: absent -''' +""" import re import time From 641b0693b4b09d7d98757b529f0df1aa86f38a12 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 25 Dec 2024 23:01:11 +0100 Subject: [PATCH 094/302] Prepare 10.2.0 release. --- changelogs/fragments/10.2.0.yml | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/fragments/10.2.0.yml diff --git a/changelogs/fragments/10.2.0.yml b/changelogs/fragments/10.2.0.yml new file mode 100644 index 0000000000..4b1469c9fe --- /dev/null +++ b/changelogs/fragments/10.2.0.yml @@ -0,0 +1 @@ +release_summary: Regular bugfix and feature release. From 872bc91096b8ab84a1b767a71e9cc5340d5c3b27 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 08:39:08 +0100 Subject: [PATCH 095/302] [PR #9372/bef82e28 backport][stable-10] p[a-e]*: normalize docs (#9397) p[a-e]*: normalize docs (#9372) * p[a-e]*: normalize docs * Update plugins/modules/packet_volume.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit bef82e28a295dcc9f932fe972d1b79f8c2f7d44b) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/pacemaker_cluster.py | 88 +++---- plugins/modules/packet_device.py | 202 +++++++------- plugins/modules/packet_ip_subnet.py | 65 +++-- plugins/modules/packet_project.py | 33 ++- plugins/modules/packet_sshkey.py | 52 ++-- plugins/modules/packet_volume.py | 58 ++-- plugins/modules/packet_volume_attachment.py | 46 ++-- plugins/modules/pacman.py | 277 ++++++++++---------- plugins/modules/pacman_key.py | 137 +++++----- plugins/modules/pagerduty.py | 138 +++++----- plugins/modules/pagerduty_alert.py | 271 ++++++++++--------- plugins/modules/pagerduty_change.py | 15 +- plugins/modules/pagerduty_user.py | 99 ++++--- plugins/modules/pam_limits.py | 60 ++--- plugins/modules/pamd.py | 97 +++---- plugins/modules/parted.py | 75 +++--- plugins/modules/pear.py | 99 ++++--- 17 files changed, 867 insertions(+), 945 deletions(-) diff --git a/plugins/modules/pacemaker_cluster.py b/plugins/modules/pacemaker_cluster.py index 60d8656ac3..af8bb5ff56 100644 --- a/plugins/modules/pacemaker_cluster.py +++ b/plugins/modules/pacemaker_cluster.py @@ -8,71 +8,59 @@ 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 diff --git a/plugins/modules/packet_device.py b/plugins/modules/packet_device.py index 519a7031e1..13dbbb9ff3 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 @@ -122,7 +119,7 @@ options: user_data: description: - - Userdata blob made available to the machine + - Userdata blob made available to the machine. type: str wait_for_public_IPv: @@ -130,7 +127,7 @@ 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: @@ -156,11 +153,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,13 +165,13 @@ 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 # ready for other API operations). Fail if the device is not "active" in @@ -184,64 +180,64 @@ EXAMPLES = ''' - 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 +245,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..c2c9fcead4 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,7 +75,8 @@ 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=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. choices: ['present', 'absent'] @@ -85,10 +84,10 @@ options: 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 +95,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 +139,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 +152,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..f6acdec152 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: @@ -55,9 +53,9 @@ options: 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..0423cc879d 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..a4a9370ae0 100644 --- a/plugins/modules/pacman.py +++ b/plugins/modules/pacman.py @@ -12,172 +12,161 @@ 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..8d83374c34 100644 --- a/plugins/modules/pagerduty.py +++ b/plugins/modules/pagerduty.py @@ -9,84 +9,82 @@ 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 +141,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..050dcd17e9 100644 --- a/plugins/modules/pagerduty_alert.py +++ b/plugins/modules/pagerduty_alert.py @@ -8,150 +8,149 @@ 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. + 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 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. + 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 O(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 +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Trigger an incident with just the basic options community.general.pagerduty_alert: name: companyabc @@ -226,7 +225,7 @@ EXAMPLES = ''' integration_key: xxx incident_key: somekey state: resolved -''' +""" import json from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/pagerduty_change.py b/plugins/modules/pagerduty_change.py index acd31fb447..39353f7575 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,7 @@ 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 +81,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 +105,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..516b61fec1 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,21 @@ 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 +105,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 +137,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..6502922bc1 100644 --- a/plugins/modules/pamd.py +++ b/plugins/modules/pamd.py @@ -9,15 +9,14 @@ 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 +29,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 +38,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 +54,49 @@ 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 +124,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 @@ -193,8 +183,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 +194,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 +216,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..43c34ff9e5 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,14 @@ 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 +49,40 @@ 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 + - 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%). + - 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 +98,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 +114,15 @@ 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 +133,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 +164,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 +191,7 @@ EXAMPLES = r''' community.general.parted: device: /dev/sdb number: 2 - flags: [ lvm ] + flags: [lvm] state: present part_start: 1GiB @@ -235,7 +222,7 @@ EXAMPLES = r''' part_end: "100%" resize: true state: present -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/pear.py b/plugins/modules/pear.py index 36770de6c5..ba8f5f9ca2 100644 --- a/plugins/modules/pear.py +++ b/plugins/modules/pear.py @@ -12,54 +12,53 @@ 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,19 +74,18 @@ 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. - If there is more packages than prompts, additional prompts will be ignored. +- 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 state: present @@ -95,10 +93,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 +112,7 @@ EXAMPLES = r''' community.general.pear: name: Net_URL2,pecl/json_post state: absent -''' +""" import os From 4f9e7bd793252ae5789e7cea08c7f86a5baf65c2 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 08:39:21 +0100 Subject: [PATCH 096/302] [PR #9352/9fc3092b backport][stable-10] s[e-n]*: normalize docs (#9399) s[e-n]*: normalize docs (#9352) * s[e-n]*: normalize docs * Apply suggestions from code review Co-authored-by: Felix Fontein * quote line with : and remove extraneous notes * Update plugins/modules/slack.py Co-authored-by: Felix Fontein * Update plugins/modules/seport.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 9fc3092bb3e8cd7f96dce273b9f19b0efa51bd49) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/sefcontext.py | 94 ++++++------ plugins/modules/selinux_permissive.py | 27 ++-- plugins/modules/selogin.py | 37 +++-- plugins/modules/sendgrid.py | 38 ++--- plugins/modules/sensu_check.py | 65 ++++---- plugins/modules/sensu_client.py | 26 ++-- plugins/modules/sensu_handler.py | 33 ++--- plugins/modules/sensu_silence.py | 30 ++-- plugins/modules/sensu_subscription.py | 35 +++-- plugins/modules/seport.py | 31 ++-- plugins/modules/serverless.py | 26 ++-- plugins/modules/shutdown.py | 33 +++-- plugins/modules/simpleinit_msb.py | 20 +-- plugins/modules/sl_vm.py | 163 ++++++++++---------- plugins/modules/slack.py | 83 +++++------ plugins/modules/slackpkg.py | 64 ++++---- plugins/modules/smartos_image_info.py | 43 +++--- plugins/modules/snap.py | 193 ++++++++++++------------ plugins/modules/snap_alias.py | 71 +++++---- plugins/modules/snmp_facts.py | 204 +++++++++++++------------- 20 files changed, 627 insertions(+), 689 deletions(-) diff --git a/plugins/modules/sefcontext.py b/plugins/modules/sefcontext.py index 19c128fa7b..eeba491f5d 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,82 @@ 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 +128,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..c964fa8c23 100644 --- a/plugins/modules/sendgrid.py +++ b/plugins/modules/sendgrid.py @@ -9,21 +9,15 @@ 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: @@ -98,9 +92,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 +108,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..018bb75db3 100644 --- a/plugins/modules/sensu_check.py +++ b/plugins/modules/sensu_check.py @@ -9,15 +9,14 @@ 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. + they are simply specified for your convenience. extends_documentation_fragment: - community.general.attributes attributes: @@ -29,127 +28,127 @@ 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. - 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. + 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 via 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 + making it available via 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 can't rewrite others 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). 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 +176,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..0de0340f33 100644 --- a/plugins/modules/sensu_client.py +++ b/plugins/modules/sensu_client.py @@ -8,8 +8,7 @@ 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 @@ -27,8 +26,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 @@ -49,7 +48,8 @@ options: - 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: @@ -99,11 +99,9 @@ options: type: dict description: - The servicenow definition scope, used to configure the Sensu Enterprise ServiceNow integration (Sensu Enterprise users only). -notes: - - Check mode is supported -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # Minimum possible configuration - name: Configure Sensu client community.general.sensu_client: @@ -146,20 +144,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 diff --git a/plugins/modules/sensu_handler.py b/plugins/modules/sensu_handler.py index bbb8dc6129..bd1014f2dd 100644 --- a/plugins/modules/sensu_handler.py +++ b/plugins/modules/sensu_handler.py @@ -8,13 +8,12 @@ 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 + - Manages Sensu handler configuration. - 'For more information, refer to the Sensu documentation: U(https://sensuapp.org/docs/latest/reference/handlers.html)' extends_documentation_fragment: - community.general.attributes @@ -27,8 +26,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 +37,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: @@ -98,12 +97,10 @@ options: 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 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 +143,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 diff --git a/plugins/modules/sensu_silence.py b/plugins/modules/sensu_silence.py index 25dfc239eb..bcb70f9bd1 100644 --- a/plugins/modules/sensu_silence.py +++ b/plugins/modules/sensu_silence.py @@ -9,14 +9,12 @@ 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 via the Sensu API for subscriptions and checks. extends_documentation_fragment: - community.general.attributes attributes: @@ -36,30 +34,26 @@ 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 via 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 +61,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 +92,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..e7c78c3290 100644 --- a/plugins/modules/sensu_subscription.py +++ b/plugins/modules/sensu_subscription.py @@ -9,12 +9,11 @@ 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. extends_documentation_fragment: - community.general.attributes attributes: @@ -26,41 +25,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. + 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 +67,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..6f2dac14b1 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 will attempt + to shutdown the system by calling C(systemctl shutdown). description: - Shut downs a machine. version_added: "1.1.0" @@ -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 will be 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..2b1b865d2c 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 will not run commands unless necessary. V(restarted) will always bounce the service. + V(reloaded) will always reload. - 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) will start 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..3216fded8b 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: @@ -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: @@ -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 58893b0f42..b4e637f591 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) via the Incoming WebHook integration. author: "Ramon de la Fuente (@ramondelafuente)" extends_documentation_fragment: - community.general.attributes @@ -32,51 +32,42 @@ 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 }}) to get RV(ignore:channel) 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 @@ -107,14 +98,13 @@ 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: @@ -140,11 +130,10 @@ 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. choices: - 'always' - 'never' @@ -153,7 +142,7 @@ options: version_added: 6.1.0 """ -EXAMPLES = """ +EXAMPLES = r""" - name: Send notification message via Slack community.general.slack: token: thetoken/generatedby/slack @@ -215,14 +204,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: 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..96bf9b0575 100644 --- a/plugins/modules/smartos_image_info.py +++ b/plugins/modules/smartos_image_info.py @@ -9,31 +9,28 @@ 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 +46,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..1de829801d 100644 --- a/plugins/modules/snap.py +++ b/plugins/modules/snap.py @@ -13,96 +13,87 @@ 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 +138,35 @@ 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 +""" import re import json diff --git a/plugins/modules/snap_alias.py b/plugins/modules/snap_alias.py index ba54a9e155..81a968730d 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,15 +72,15 @@ 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 +""" import re diff --git a/plugins/modules/snmp_facts.py b/plugins/modules/snmp_facts.py index d561f93f02..af0abf9479 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 @@ -152,39 +150,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 From 7a44dbfe45d996adb119f35f382d3a31bd55233a Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 08:39:32 +0100 Subject: [PATCH 097/302] [PR #9364/6b7ea344 backport][stable-10] [prox ... pyth]*: normalize docs (#9400) [prox ... pyth]*: normalize docs (#9364) * [prox ... pyth]*: normalize docs * Apply suggestions from code review Co-authored-by: IamLunchbox <56757745+IamLunchbox@users.noreply.github.com> * Update plugins/modules/pushbullet.py Co-authored-by: Felix Fontein * Update plugins/modules/pushbullet.py Co-authored-by: Felix Fontein --------- Co-authored-by: IamLunchbox <56757745+IamLunchbox@users.noreply.github.com> Co-authored-by: Felix Fontein (cherry picked from commit 6b7ea3443d7f48aec832f781e5fb2a335ff3d466) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/proxmox.py | 71 ++++---- plugins/modules/proxmox_backup.py | 53 +++--- plugins/modules/proxmox_disk.py | 60 +++---- plugins/modules/proxmox_domain_info.py | 55 +++--- plugins/modules/proxmox_group_info.py | 51 +++--- plugins/modules/proxmox_kvm.py | 166 +++++++++--------- plugins/modules/proxmox_nic.py | 19 +- plugins/modules/proxmox_node_info.py | 127 +++++++------- plugins/modules/proxmox_pool.py | 11 +- plugins/modules/proxmox_pool_member.py | 9 +- plugins/modules/proxmox_snap.py | 24 +-- .../modules/proxmox_storage_contents_info.py | 7 +- plugins/modules/proxmox_storage_info.py | 29 ++- plugins/modules/proxmox_tasks_info.py | 119 +++++++------ plugins/modules/proxmox_template.py | 15 +- plugins/modules/proxmox_user_info.py | 159 +++++++++-------- plugins/modules/proxmox_vm_info.py | 7 +- plugins/modules/pubnub_blocks.py | 100 ++++------- plugins/modules/pulp_repo.py | 82 ++++----- plugins/modules/puppet.py | 45 +++-- plugins/modules/pushbullet.py | 96 +++++----- plugins/modules/pushover.py | 19 +- plugins/modules/python_requirements_info.py | 38 ++-- 23 files changed, 633 insertions(+), 729 deletions(-) diff --git a/plugins/modules/proxmox.py b/plugins/modules/proxmox.py index 52d5a849f3..3925eec090 100644 --- a/plugins/modules/proxmox.py +++ b/plugins/modules/proxmox.py @@ -8,8 +8,7 @@ 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,28 +25,26 @@ 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=] [,quota=<1|0>] [,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). type: str @@ -93,19 +90,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: @@ -177,11 +174,11 @@ 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: @@ -199,15 +196,15 @@ options: 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,7 +216,7 @@ options: version_added: 6.2.0 timeout: description: - - timeout for operations + - Timeout for operations. type: int default: 30 update: @@ -232,8 +229,8 @@ options: 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 +244,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: @@ -292,8 +289,8 @@ options: - Type of the clone created. - V(full) creates a full clone, and O(storage) must be specified. - V(linked) creates a linked clone, and the cloned container must be a template container. - - V(opportunistic) creates a linked clone if the cloned container is a template container, and a full clone if not. - O(storage) may be specified, if not it will fall back to the default. + - V(opportunistic) creates a linked clone if the cloned container is a template container, and a full clone if not. O(storage) may be specified, + if not it will fall back to the default. type: str choices: ['full', 'linked', 'opportunistic'] default: opportunistic @@ -306,9 +303,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 +491,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,7 +596,7 @@ EXAMPLES = r''' api_password: 1q2w3e api_host: node1 state: absent -''' +""" import re import time diff --git a/plugins/modules/proxmox_backup.py b/plugins/modules/proxmox_backup.py index 0db2c4ad0e..b14dd529e8 100644 --- a/plugins/modules/proxmox_backup.py +++ b/plugins/modules/proxmox_backup.py @@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: proxmox_backup author: "Raphael Grieger (@IamLunchbox) " short_description: Start a VM backup in Proxmox VE cluster @@ -42,11 +41,9 @@ options: change_detection_mode: description: - Set the change detection mode (available from Proxmox VE 8.3). - - > - Is only used when backing up containers, - Proxmox silently ignores this option when applied to kvm guests. + - It is only used when backing up containers, Proxmox silently ignores this option when applied to kvm guests. type: str - choices: ["legacy", "data", "metadata"] + choices: ["legacy", "data", "metadata"] compress: description: - Enable additional compression of the backup archive. @@ -63,13 +60,9 @@ options: 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. + - 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: @@ -93,13 +86,13 @@ options: description: - Determine which notification system to use. type: str - choices: ["auto","legacy-sendmail", "notification-system"] + 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)." + - 'For example: V(max-workers=2,pbs-entries-max=2).' type: str pool: description: @@ -110,19 +103,14 @@ options: 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)" + - '"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")). + - 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 target due to your specified timeframe. + - 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: @@ -153,9 +141,9 @@ extends_documentation_fragment: - community.general.proxmox.actiongroup_proxmox - community.general.proxmox.documentation - community.general.attributes -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Backup all vms in the Proxmox cluster to storage mypbs community.general.proxmox_backup: api_user: root@pam @@ -204,9 +192,9 @@ EXAMPLES = r''' vmids: - 100 - 101 -''' +""" -RETURN = r''' +RETURN = r""" backups: description: List of nodes and their task IDs. returned: on success @@ -223,13 +211,12 @@ backups: 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, - e.g. due to no matching targets. + 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 diff --git a/plugins/modules/proxmox_disk.py b/plugins/modules/proxmox_disk.py index a4a9dd8791..289933915e 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,21 @@ 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 +73,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 +163,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 +210,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 +249,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 +316,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 +423,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,7 +436,7 @@ 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.proxmox import (proxmox_auth_argument_spec, 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..d495b08694 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: @@ -66,21 +65,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,12 +87,12 @@ 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: @@ -110,13 +109,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 +143,22 @@ 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 +171,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 +186,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,11 +198,11 @@ 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. + - 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: @@ -223,21 +219,21 @@ 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.' + - '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.' + - 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. @@ -265,7 +261,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 +290,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 @@ -307,7 +303,8 @@ options: - 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'. + - 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: @@ -361,23 +358,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 +383,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 @@ -407,20 +404,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 +429,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,7 +446,7 @@ 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. type: str choices: ['present', 'started', 'absent', 'stopped', 'restarted', 'current', 'template'] @@ -473,7 +470,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: @@ -512,7 +509,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 @@ -520,16 +517,16 @@ options: update: 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). + - 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 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 @@ -545,13 +542,13 @@ options: 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. 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 watchdog: description: @@ -564,9 +561,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 +843,7 @@ EXAMPLES = ''' cores: 8 memory: 16384 net: - net0: virtio,bridge=vmbr1 + net0: virtio,bridge=vmbr1 update: true update_unsafe: true @@ -886,10 +883,9 @@ EXAMPLES = ''' node: sabrewulf hookscript: local:snippets/hookscript.pl update: true +""" -''' - -RETURN = ''' +RETURN = r""" vmid: description: The VM vmid. returned: success @@ -901,11 +897,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 diff --git a/plugins/modules/proxmox_nic.py b/plugins/modules/proxmox_nic.py index 6e94ed0bb6..bcf23bc5a1 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..57dad92413 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 @@ -35,8 +34,8 @@ options: 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 876e8a6847..c994eff1f8 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 @@ -34,7 +33,7 @@ options: type: path url: description: - - URL to file to download + - 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 @@ -68,7 +67,7 @@ options: default: false state: description: - - Indicate desired state of the template. + - Indicate desired state of the template. type: str choices: ['present', 'absent'] default: present @@ -80,9 +79,9 @@ 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 @@ -148,7 +147,7 @@ EXAMPLES = ''' storage: local content_type: vztmpl template: ubuntu-20.04-standard_20.04-1_amd64.tar.gz -''' +""" import os import time 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..36ddea9db8 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 diff --git a/plugins/modules/pubnub_blocks.py b/plugins/modules/pubnub_blocks.py index 34098873a1..598b6b5af3 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 admin.pubnub.com. Used only if block doesn't exists and won't 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 + - 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..142c5f66f4 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,68 @@ 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 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 +113,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 +129,21 @@ 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) + - 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 +152,13 @@ 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 +181,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 diff --git a/plugins/modules/puppet.py b/plugins/modules/puppet.py index 46326c667f..cf4cfae47c 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,8 @@ 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 +118,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 +161,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 +183,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 diff --git a/plugins/modules/pushbullet.py b/plugins/modules/pushbullet.py index 673f30cc36..32a659922a 100644 --- a/plugins/modules/pushbullet.py +++ b/plugins/modules/pushbullet.py @@ -9,65 +9,59 @@ 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 +88,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..17432583e3 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,17 @@ 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 +38,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 +83,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 + 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 +110,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 From 92a07f1794fde40530d8a520995a96d7523a6b63 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 09:25:49 +0100 Subject: [PATCH 098/302] [PR #9390/cea6eeef backport][stable-10] l*.py: normalize docs (#9402) l*.py: normalize docs (#9390) (cherry picked from commit cea6eeef371d6751220679459ed9ee77c157ffa3) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/launchd.py | 90 +++--- plugins/modules/layman.py | 26 +- plugins/modules/lbu.py | 30 +- plugins/modules/ldap_attrs.py | 122 ++++---- plugins/modules/ldap_entry.py | 73 ++--- plugins/modules/ldap_passwd.py | 28 +- plugins/modules/ldap_search.py | 30 +- plugins/modules/librato_annotation.py | 117 ++++---- plugins/modules/linode.py | 216 +++++++------- plugins/modules/linode_v4.py | 66 ++--- plugins/modules/listen_ports_facts.py | 34 +-- plugins/modules/lldp.py | 28 +- plugins/modules/locale_gen.py | 51 ++-- plugins/modules/logentries.py | 72 ++--- plugins/modules/logentries_msg.py | 21 +- plugins/modules/logstash_plugin.py | 78 +++-- plugins/modules/lvg.py | 59 ++-- plugins/modules/lvg_rename.py | 19 +- plugins/modules/lvol.py | 61 ++-- plugins/modules/lxc_container.py | 411 +++++++++++++------------- plugins/modules/lxca_cmms.py | 59 ++-- plugins/modules/lxca_nodes.py | 63 ++-- plugins/modules/lxd_container.py | 370 +++++++++++------------ plugins/modules/lxd_profile.py | 244 ++++++++------- plugins/modules/lxd_project.py | 176 ++++++----- 25 files changed, 1194 insertions(+), 1350 deletions(-) diff --git a/plugins/modules/launchd.py b/plugins/modules/launchd.py index 9717825c71..ea2163964b 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,57 +19,52 @@ 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 - plist: - 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: + 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 @@ -112,11 +106,11 @@ EXAMPLES = r''' name: com.openssh.sshd plist: ssh.plist state: restarted -''' +""" -RETURN = r''' +RETURN = r""" status: - description: Metadata about service status + description: Metadata about service status. returned: always type: dict sample: @@ -126,7 +120,7 @@ status: "previous_pid": "82636", "previous_state": "running" } -''' +""" import os import plistlib diff --git a/plugins/modules/layman.py b/plugins/modules/layman.py index 13d514274b..21b4eba9a4 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,13 @@ 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 +46,13 @@ 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. Prior to 1.9.3 the + code defaulted to V(false). 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..8f1e0a0ea9 100644 --- a/plugins/modules/ldap_attrs.py +++ b/plugins/modules/ldap_attrs.py @@ -12,27 +12,19 @@ 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). + - 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). + - 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 +45,38 @@ 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 - this attribute will be removed. + - 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 + - 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 +84,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 +102,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 +120,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 +146,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..d3ce90433a 100644 --- a/plugins/modules/ldap_entry.py +++ b/plugins/modules/ldap_entry.py @@ -11,21 +11,16 @@ 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). + - 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). + - 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: - Jiri Tyr (@jtyr) requirements: @@ -38,24 +33,18 @@ 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 +55,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 +90,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 +130,7 @@ EXAMPLES = """ """ -RETURN = """ +RETURN = r""" # Default return values """ diff --git a/plugins/modules/ldap_passwd.py b/plugins/modules/ldap_passwd.py index 5044586b0f..ab2c9a890b 100644 --- a/plugins/modules/ldap_passwd.py +++ b/plugins/modules/ldap_passwd.py @@ -9,21 +9,16 @@ 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). + - 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). + - 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: - Keller Fuchs (@KellerFuchs) requirements: @@ -41,10 +36,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 +50,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..6c47c2f7e0 100644 --- a/plugins/modules/ldap_search.py +++ b/plugins/modules/ldap_search.py @@ -10,19 +10,15 @@ 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). + - 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 +51,26 @@ 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 diff --git a/plugins/modules/librato_annotation.py b/plugins/modules/librato_annotation.py index ebfb751546..b4f7dd54cc 100644 --- a/plugins/modules/librato_annotation.py +++ b/plugins/modules/librato_annotation.py @@ -9,74 +9,73 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: librato_annotation 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 +104,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..9d907c898b 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,32 @@ 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 +58,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 +181,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..cac890f79b 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..baefb09d91 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: @@ -26,25 +25,24 @@ attributes: options: {} 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 diff --git a/plugins/modules/locale_gen.py b/plugins/modules/locale_gen.py index 8886cdc9cd..6c0412f464 100644 --- a/plugins/modules/locale_gen.py +++ b/plugins/modules/locale_gen.py @@ -8,40 +8,39 @@ 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 by editing /etc/locale.gen and invoking C(locale-gen). 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 locale shall be present. + choices: [absent, present] + default: present notes: - - This module does not support RHEL-based systems. -''' + - This module does not support RHEL-based systems. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Ensure a locale exists community.general.locale_gen: name: de_CH.UTF-8 @@ -53,7 +52,7 @@ EXAMPLES = ''' - en_GB.UTF-8 - nl_NL.UTF-8 state: present -''' +""" import os import re 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..f6f8abc020 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,76 @@ 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. 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 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). 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 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 +151,7 @@ EXAMPLES = r''' pvs: /dev/sdb1,/dev/sdc5 reset_vg_uuid: true reset_pv_uuid: true -''' +""" import itertools import os 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..34b24f7570 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,69 @@ 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) --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 that filesystems get never 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 will fail. 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 +226,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..9b44c4fc89 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,171 @@ 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 @@ -382,45 +369,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 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..3f0ab2607e 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,180 @@ 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). - See the first example below. - - linuxcontainers.org has phased out LXC/LXD support with March 2024 + - 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). See the first + example below. + - 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 +260,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" @@ -400,12 +381,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 +407,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..c46559298b 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. 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: - - 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 + - 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..ee90b88168 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 + - 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 From d3badc6d43403f312cba64f4ddc239e908c1618d Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 14:01:05 +0100 Subject: [PATCH 099/302] [PR #9382/88330575 backport][stable-10] [oc ... onep]*.py: normalize docs (#9408) [oc ... onep]*.py: normalize docs (#9382) * [oc ... onep]*.py: normalize docs * Apply suggestions from code review Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 88330575ff648276f37112f8a5eff7c0fc686add) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/ocapi_command.py | 187 +++--- plugins/modules/ocapi_info.py | 94 ++- plugins/modules/oci_vcn.py | 80 ++- plugins/modules/odbc.py | 101 ++-- plugins/modules/office_365_connector_card.py | 140 +++-- plugins/modules/ohai.py | 19 +- plugins/modules/omapi_host.py | 178 +++--- plugins/modules/one_host.py | 142 +++-- plugins/modules/one_image.py | 505 ++++++++-------- plugins/modules/one_image_info.py | 401 +++++++------ plugins/modules/one_service.py | 106 ++-- plugins/modules/one_template.py | 78 ++- plugins/modules/one_vm.py | 548 ++++++++---------- plugins/modules/one_vnet.py | 306 +++++----- plugins/modules/oneandone_firewall_policy.py | 95 ++- plugins/modules/oneandone_load_balancer.py | 104 ++-- .../modules/oneandone_monitoring_policy.py | 293 +++++----- plugins/modules/oneandone_private_network.py | 47 +- plugins/modules/oneandone_public_ip.py | 39 +- plugins/modules/oneandone_server.py | 81 ++- plugins/modules/onepassword_info.py | 197 ++++--- 21 files changed, 1807 insertions(+), 1934 deletions(-) diff --git a/plugins/modules/ocapi_command.py b/plugins/modules/ocapi_command.py index b6b9b6b98e..001d113ca3 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,103 @@ 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..f2d708965c 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,63 @@ 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 +137,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..aba8b0e73e 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'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, V(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'] 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..949fdcdce4 100644 --- a/plugins/modules/office_365_connector_card.py +++ b/plugins/modules/office_365_connector_card.py @@ -8,17 +8,15 @@ 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 - U(https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#connector-card-for-microsoft-365-groups). + - 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 +35,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 +49,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 +74,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..9a182e99a5 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..8e7e4b92ad 100644 --- a/plugins/modules/one_host.py +++ b/plugins/modules/one_host.py @@ -10,87 +10,85 @@ 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 +100,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..399cfadec8 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..af47e16bdb 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: @@ -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..b9146eca2a 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..28f4f14cd3 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,8 +20,7 @@ requirements: - pyone description: - - "Manages OpenNebula templates." - + - Manages OpenNebula templates. attributes: check_mode: support: partial @@ -34,14 +32,12 @@ attributes: 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: @@ -61,9 +57,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 +106,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 diff --git a/plugins/modules/one_vm.py b/plugins/modules/one_vm.py index 2f4ee25354..9c1084866e 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,34 +27,30 @@ 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 "~/.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: @@ -67,10 +62,10 @@ options: 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,64 +76,53 @@ 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 'wait_for' example + 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'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: 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: @@ -146,27 +130,25 @@ options: 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 +165,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 +177,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 @@ -441,241 +423,219 @@ 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..baafc39fbb 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 @@ -34,9 +33,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 +51,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 +85,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..72ed4e5594 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,16 +46,14 @@ 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 @@ -73,8 +67,8 @@ options: 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 @@ -88,23 +82,23 @@ options: 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..45ed6157fa 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,36 +69,35 @@ 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 update state. type: list elements: str required: false @@ -116,8 +111,8 @@ options: 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 update state. type: list elements: dict required: false @@ -131,30 +126,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 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..0ba653b414 100644 --- a/plugins/modules/oneandone_monitoring_policy.py +++ b/plugins/modules/oneandone_monitoring_policy.py @@ -7,14 +7,11 @@ 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 +26,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 +50,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 +96,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 +120,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 +185,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 +204,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 +217,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 +277,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 +320,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 +332,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 +350,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 +358,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 +369,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 +385,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 +394,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 +403,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..17fb210a98 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: @@ -28,20 +26,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 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..e47da5baba 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,29 @@ 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 cores_per_processor, ram, and 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 vcore, ram, and 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 vcore, cores_per_processor, and 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 "size" and "is_main" properties. It must be provided with vcore, cores_per_processor, and ram parameters. type: list elements: dict private_network: @@ -119,30 +110,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 +138,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 +188,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 diff --git a/plugins/modules/onepassword_info.py b/plugins/modules/onepassword_info.py index b63352790f..c49dd15e17 100644 --- a/plugins/modules/onepassword_info.py +++ b/plugins/modules/onepassword_info.py @@ -12,108 +12,108 @@ 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 +121,38 @@ 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 From 11ba71c802755b9405ec89b999e927ba60e5cf18 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 14:01:16 +0100 Subject: [PATCH 100/302] [PR #9391/49ed3d4a backport][stable-10] k*.py: normalize docs (#9407) k*.py: normalize docs (#9391) * k*.py: normalize docs * Update plugins/modules/keycloak_realm_keys_metadata_info.py Co-authored-by: Felix Fontein * Update plugins/modules/kibana_plugin.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 49ed3d4acfcef1959e1fa8730b328ba4c6793845) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/kdeconfig.py | 15 +- plugins/modules/kernel_blacklist.py | 56 +- plugins/modules/keycloak_authentication.py | 191 ++- ...eycloak_authentication_required_actions.py | 203 ++- .../keycloak_authz_authorization_scope.py | 177 ++- .../modules/keycloak_authz_custom_policy.py | 150 ++- plugins/modules/keycloak_authz_permission.py | 321 +++-- .../modules/keycloak_authz_permission_info.py | 149 ++- plugins/modules/keycloak_client.py | 1083 ++++++++-------- .../modules/keycloak_client_rolemapping.py | 260 ++-- plugins/modules/keycloak_client_rolescope.py | 168 ++- plugins/modules/keycloak_clientscope.py | 321 +++-- plugins/modules/keycloak_clientscope_type.py | 84 +- plugins/modules/keycloak_clientsecret_info.py | 45 +- .../keycloak_clientsecret_regenerate.py | 44 +- plugins/modules/keycloak_clienttemplate.py | 329 +++-- plugins/modules/keycloak_component.py | 183 ++- plugins/modules/keycloak_component_info.py | 144 +-- plugins/modules/keycloak_group.py | 303 +++-- plugins/modules/keycloak_identity_provider.py | 489 ++++--- plugins/modules/keycloak_realm.py | 1048 ++++++++------- plugins/modules/keycloak_realm_info.py | 135 +- plugins/modules/keycloak_realm_key.py | 297 ++--- .../keycloak_realm_keys_metadata_info.py | 77 +- plugins/modules/keycloak_realm_rolemapping.py | 242 ++-- plugins/modules/keycloak_role.py | 260 ++-- plugins/modules/keycloak_user.py | 474 +++---- plugins/modules/keycloak_user_federation.py | 1124 ++++++++--------- plugins/modules/keycloak_user_rolemapping.py | 228 ++-- plugins/modules/keycloak_userprofile.py | 486 ++++--- plugins/modules/keyring.py | 5 +- plugins/modules/keyring_info.py | 33 +- plugins/modules/kibana_plugin.py | 143 ++- plugins/modules/krb_ticket.py | 17 +- 34 files changed, 4402 insertions(+), 4882 deletions(-) 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 fa2ae1e974..1b47542bb3 100644 --- a/plugins/modules/keycloak_authentication.py +++ b/plugins/modules/keycloak_authentication.py @@ -7,112 +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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -126,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 @@ -150,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 @@ -184,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. @@ -222,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 diff --git a/plugins/modules/keycloak_authentication_required_actions.py b/plugins/modules/keycloak_authentication_required_actions.py index c992e05d2d..60b47d7a6a 100644 --- a/plugins/modules/keycloak_authentication_required_actions.py +++ b/plugins/modules/keycloak_authentication_required_actions.py @@ -9,84 +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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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" @@ -126,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 diff --git a/plugins/modules/keycloak_authz_authorization_scope.py b/plugins/modules/keycloak_authz_authorization_scope.py index 146a37bf51..cd1ff57afc 100644 --- a/plugins/modules/keycloak_authz_authorization_scope.py +++ b/plugins/modules/keycloak_authz_authorization_scope.py @@ -9,81 +9,75 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -95,41 +89,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 diff --git a/plugins/modules/keycloak_authz_custom_policy.py b/plugins/modules/keycloak_authz_custom_policy.py index 2205a184f5..ef6c9b0973 100644 --- a/plugins/modules/keycloak_authz_custom_policy.py +++ b/plugins/modules/keycloak_authz_custom_policy.py @@ -9,78 +9,71 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -92,31 +85,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 diff --git a/plugins/modules/keycloak_authz_permission.py b/plugins/modules/keycloak_authz_permission.py index 08b5ae6295..e4ab9fe14d 100644 --- a/plugins/modules/keycloak_authz_permission.py +++ b/plugins/modules/keycloak_authz_permission.py @@ -9,128 +9,119 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -164,68 +155,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 diff --git a/plugins/modules/keycloak_authz_permission_info.py b/plugins/modules/keycloak_authz_permission_info.py index 4c1a6ddf66..6851abb311 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,52 +17,46 @@ 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 + 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.keycloak.actiongroup_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 @@ -73,48 +66,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 diff --git a/plugins/modules/keycloak_client.py b/plugins/modules/keycloak_client.py index c65105ec23..6b19711e3d 100644 --- a/plugins/modules/keycloak_client.py +++ b/plugins/modules/keycloak_client.py @@ -8,603 +8,532 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -705,7 +634,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 @@ -744,45 +673,33 @@ 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 diff --git a/plugins/modules/keycloak_client_rolemapping.py b/plugins/modules/keycloak_client_rolemapping.py index ebc60b9fd0..23dad803d7 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,129 +16,113 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -209,50 +192,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, diff --git a/plugins/modules/keycloak_client_rolescope.py b/plugins/modules/keycloak_client_rolescope.py index cd4f0fa80e..ff91a0fe78 100644 --- a/plugins/modules/keycloak_client_rolescope.py +++ b/plugins/modules/keycloak_client_rolescope.py @@ -8,84 +8,74 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -96,8 +86,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: @@ -109,7 +99,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 @@ -121,16 +111,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. @@ -138,22 +128,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 87437b6df0..ed82e0c0f7 100644 --- a/plugins/modules/keycloak_clientscope.py +++ b/plugins/modules/keycloak_clientscope.py @@ -8,166 +8,151 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -254,54 +239,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 diff --git a/plugins/modules/keycloak_clientscope_type.py b/plugins/modules/keycloak_clientscope_type.py index d95ab0b44d..ef4233fea4 100644 --- a/plugins/modules/keycloak_clientscope_type.py +++ b/plugins/modules/keycloak_clientscope_type.py @@ -9,29 +9,24 @@ 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 - action_group: - version_added: 10.2.0 + check_mode: + support: full + diff_mode: + support: full + action_group: + version_added: 10.2.0 options: realm: @@ -66,9 +61,9 @@ extends_documentation_fragment: 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 @@ -91,42 +86,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 diff --git a/plugins/modules/keycloak_clientsecret_info.py b/plugins/modules/keycloak_clientsecret_info.py index 58786a5364..d0f6297037 100644 --- a/plugins/modules/keycloak_clientsecret_info.py +++ b/plugins/modules/keycloak_clientsecret_info.py @@ -9,29 +9,20 @@ 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 @@ -46,14 +37,12 @@ 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 @@ -68,9 +57,9 @@ extends_documentation_fragment: 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' @@ -102,16 +91,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: @@ -125,7 +114,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 fc279f6a9d..4bd48e90ad 100644 --- a/plugins/modules/keycloak_clientsecret_regenerate.py +++ b/plugins/modules/keycloak_clientsecret_regenerate.py @@ -9,29 +9,20 @@ 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 @@ -50,14 +41,12 @@ 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 @@ -71,9 +60,9 @@ extends_documentation_fragment: 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' @@ -105,16 +94,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: @@ -128,8 +117,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 63bb32f972..bfd138c3f2 100644 --- a/plugins/modules/keycloak_clienttemplate.py +++ b/plugins/modules/keycloak_clienttemplate.py @@ -8,176 +8,163 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -236,47 +223,33 @@ 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 diff --git a/plugins/modules/keycloak_component.py b/plugins/modules/keycloak_component.py index 6c345700ae..2b402ddb62 100644 --- a/plugins/modules/keycloak_component.py +++ b/plugins/modules/keycloak_component.py @@ -8,80 +8,75 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -97,42 +92,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 diff --git a/plugins/modules/keycloak_component_info.py b/plugins/modules/keycloak_component_info.py index cc0c4d31d9..a1f2c1f0ef 100644 --- a/plugins/modules/keycloak_component_info.py +++ b/plugins/modules/keycloak_component_info.py @@ -8,106 +8,100 @@ 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 + 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.keycloak.actiongroup_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 24564f2d4d..796f5fc56f 100644 --- a/plugins/modules/keycloak_group.py +++ b/plugins/modules/keycloak_group.py @@ -8,122 +8,102 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -191,14 +171,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) @@ -258,64 +238,63 @@ 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 @@ -372,7 +351,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 0ef67ee385..ee631bf19c 100644 --- a/plugins/modules/keycloak_identity_provider.py +++ b/plugins/modules/keycloak_identity_provider.py @@ -8,285 +8,280 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -347,14 +342,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. @@ -428,7 +423,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 diff --git a/plugins/modules/keycloak_realm.py b/plugins/modules/keycloak_realm.py index e190e7ad7b..d2ae4f33c8 100644 --- a/plugins/modules/keycloak_realm.py +++ b/plugins/modules/keycloak_realm.py @@ -9,523 +9,516 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -546,46 +539,33 @@ EXAMPLES = ''' auth_password: PASSWORD id: test 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: {id: "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 diff --git a/plugins/modules/keycloak_realm_info.py b/plugins/modules/keycloak_realm_info.py index 5c2ebb4c9e..e3e4f08248 100644 --- a/plugins/modules/keycloak_realm_info.py +++ b/plugins/modules/keycloak_realm_info.py @@ -8,98 +8,93 @@ 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 159fb77d4b..0f7c5ae114 100644 --- a/plugins/modules/keycloak_realm_key.py +++ b/plugins/modules/keycloak_realm_key.py @@ -9,145 +9,123 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -182,54 +160,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 diff --git a/plugins/modules/keycloak_realm_keys_metadata_info.py b/plugins/modules/keycloak_realm_keys_metadata_info.py index 9b490fad58..d116e3435b 100644 --- a/plugins/modules/keycloak_realm_keys_metadata_info.py +++ b/plugins/modules/keycloak_realm_keys_metadata_info.py @@ -9,42 +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 + 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.keycloak.actiongroup_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 @@ -67,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 diff --git a/plugins/modules/keycloak_realm_rolemapping.py b/plugins/modules/keycloak_realm_rolemapping.py index 0c24b2f949..bed65057a4 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,119 +16,104 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -195,49 +179,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, diff --git a/plugins/modules/keycloak_role.py b/plugins/modules/keycloak_role.py index 3978260189..3e7644bf6c 100644 --- a/plugins/modules/keycloak_role.py +++ b/plugins/modules/keycloak_role.py @@ -8,124 +8,114 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -181,60 +171,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 @@ -290,7 +264,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 cb63707402..65880548ab 100644 --- a/plugins/modules/keycloak_user.py +++ b/plugins/modules/keycloak_user.py @@ -9,225 +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.keycloak.actiongroup_keycloak - - community.general.attributes + - community.general.keycloak + - community.general.keycloak.actiongroup_keycloak + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: full - action_group: - version_added: 10.2.0 + 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 @@ -241,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 @@ -271,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 @@ -301,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 @@ -327,9 +326,9 @@ EXAMPLES = ''' realm: master username: user1 state: absent -''' +""" -RETURN = ''' +RETURN = r""" msg: description: Message as to what action was taken. returned: always @@ -344,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 diff --git a/plugins/modules/keycloak_user_federation.py b/plugins/modules/keycloak_user_federation.py index 4533fa800d..7c49510fd6 100644 --- a/plugins/modules/keycloak_user_federation.py +++ b/plugins/modules/keycloak_user_federation.py @@ -8,623 +8,583 @@ 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 - action_group: - version_added: 10.2.0 + 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'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 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.keycloak.actiongroup_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. @@ -744,7 +704,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 diff --git a/plugins/modules/keycloak_user_rolemapping.py b/plugins/modules/keycloak_user_rolemapping.py index 40e3b38d5c..319aa5350b 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,110 +15,93 @@ 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -189,49 +171,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 diff --git a/plugins/modules/keycloak_userprofile.py b/plugins/modules/keycloak_userprofile.py index ba9cae8554..1338c8154b 100644 --- a/plugins/modules/keycloak_userprofile.py +++ b/plugins/modules/keycloak_userprofile.py @@ -8,278 +8,274 @@ 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). + - 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 - action_group: - version_added: 10.2.0 + 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.keycloak.actiongroup_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 @@ -397,9 +393,9 @@ EXAMPLES = ''' config: kc_user_profile_config: - unmanagedAttributePolicy: ADMIN_VIEW -''' +""" -RETURN = ''' +RETURN = r""" msg: description: The output message generated by the module. returned: always @@ -409,8 +405,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 diff --git a/plugins/modules/keyring.py b/plugins/modules/keyring.py index 8329b727bd..e96d01ac44 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..9fcd4d5d92 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..3d5b4d6413 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 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..d93966e501 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 @@ -56,8 +55,9 @@ options: 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 @@ -73,7 +73,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 @@ -125,9 +126,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 +180,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 From 29e9afcbf47fd6af38e9138836f89666a2184d61 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 14:01:25 +0100 Subject: [PATCH 101/302] [PR #9389/a9fca563 backport][stable-10] ma*.py: normalize docs (#9405) ma*.py: normalize docs (#9389) * ma*.py: normalize docs * Update plugins/modules/matrix.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit a9fca563746c361f7fcb558c257412a9793f7714) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/macports.py | 88 +++--- plugins/modules/mail.py | 111 ++++---- plugins/modules/make.py | 13 +- plugins/modules/manageiq_alert_profiles.py | 32 +-- plugins/modules/manageiq_alerts.py | 59 ++-- plugins/modules/manageiq_group.py | 102 ++++--- plugins/modules/manageiq_policies.py | 27 +- plugins/modules/manageiq_policies_info.py | 19 +- plugins/modules/manageiq_provider.py | 94 +++---- plugins/modules/manageiq_tags.py | 51 ++-- plugins/modules/manageiq_tags_info.py | 19 +- plugins/modules/manageiq_tenant.py | 70 ++--- plugins/modules/manageiq_user.py | 32 +-- plugins/modules/mas.py | 80 +++--- plugins/modules/matrix.py | 91 +++--- plugins/modules/mattermost.py | 39 ++- plugins/modules/maven_artifact.py | 308 ++++++++++----------- 17 files changed, 596 insertions(+), 639 deletions(-) diff --git a/plugins/modules/macports.py b/plugins/modules/macports.py index cd620687d7..3777b86c2f 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 diff --git a/plugins/modules/mail.py b/plugins/modules/mail.py index 1916c140c3..0cca8646ca 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,105 @@ 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 +140,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 +167,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 +215,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..33ca05df3b 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,8 +29,8 @@ 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: @@ -43,23 +41,21 @@ options: 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 diff --git a/plugins/modules/manageiq_alerts.py b/plugins/modules/manageiq_alerts.py index 53f40fb00c..9dd50af846 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 diff --git a/plugins/modules/manageiq_group.py b/plugins/modules/manageiq_group.py index e060b9a01a..9858dd5947 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..e53388f293 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,13 +84,13 @@ 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: '{ @@ -122,7 +119,7 @@ manageiq_policies: } ] }' -''' +""" 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..f4235203ab 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..bae59353cf 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..5d32104e7a 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..4700e46356 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..8a9fcf175c 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..4b39c64170 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,16 @@ 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 +114,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..7193626999 100644 --- a/plugins/modules/maven_artifact.py +++ b/plugins/modules/maven_artifact.py @@ -11,171 +11,165 @@ 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: + - 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 +230,7 @@ EXAMPLES = ''' artifact_id: junit version_by_spec: "[3.8,4.0)" dest: /tmp/ -''' +""" import hashlib import os From 03f3b7493435ab53a82fe8e5f8d74776c37f2bd5 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 14:01:34 +0100 Subject: [PATCH 102/302] [PR #9392/a99f72fc backport][stable-10] [ip ... j]*.py: normalize docs (#9404) [ip ... j]*.py: normalize docs (#9392) * [ip ... j]*.py: normalize docs * Update plugins/modules/ip_netns.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit a99f72fc367410e20ea44df4aa3640448022ce2d) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/ip_netns.py | 51 +++--- plugins/modules/ipa_config.py | 14 +- plugins/modules/ipa_dnsrecord.py | 82 ++++----- plugins/modules/ipa_dnszone.py | 20 +- plugins/modules/ipa_getkeytab.py | 12 +- plugins/modules/ipa_group.py | 110 ++++++----- plugins/modules/ipa_hbacrule.py | 84 +++++---- plugins/modules/ipa_host.py | 60 +++--- plugins/modules/ipa_hostgroup.py | 51 +++--- plugins/modules/ipa_otpconfig.py | 14 +- plugins/modules/ipa_otptoken.py | 63 ++++--- plugins/modules/ipa_pwpolicy.py | 251 +++++++++++++------------- plugins/modules/ipa_role.py | 84 +++++---- plugins/modules/ipa_service.py | 32 ++-- plugins/modules/ipa_subca.py | 26 ++- plugins/modules/ipa_sudocmd.py | 22 +-- plugins/modules/ipa_sudocmdgroup.py | 30 ++- plugins/modules/ipa_sudorule.py | 111 ++++++------ plugins/modules/ipa_user.py | 83 +++++---- plugins/modules/ipa_vault.py | 140 +++++++------- plugins/modules/ipbase_info.py | 29 ++- plugins/modules/ipify_facts.py | 16 +- plugins/modules/ipinfoio_facts.py | 39 ++-- plugins/modules/ipmi_boot.py | 70 ++++--- plugins/modules/ipmi_power.py | 73 ++++---- plugins/modules/iptables_state.py | 75 +++----- plugins/modules/ipwcli_dns.py | 217 +++++++++++----------- plugins/modules/irc.py | 61 +++---- plugins/modules/iso_create.py | 173 +++++++++--------- plugins/modules/iso_customize.py | 36 ++-- plugins/modules/iso_extract.py | 58 +++--- plugins/modules/jabber.py | 27 ++- plugins/modules/java_cert.py | 30 ++- plugins/modules/java_keystore.py | 67 +++---- plugins/modules/jboss.py | 20 +- plugins/modules/jenkins_build.py | 18 +- plugins/modules/jenkins_build_info.py | 18 +- plugins/modules/jenkins_job.py | 25 ++- plugins/modules/jenkins_job_info.py | 34 ++-- plugins/modules/jenkins_node.py | 34 ++-- plugins/modules/jenkins_plugin.py | 76 ++++---- plugins/modules/jenkins_script.py | 59 +++--- plugins/modules/jira.py | 124 ++++++------- 43 files changed, 1290 insertions(+), 1429 deletions(-) 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 643e18cf62..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,9 +95,9 @@ requirements: - Managed host is FreeIPA client extends_documentation_fragment: - community.general.attributes -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Get Kerberos ticket using default principal community.general.krb_ticket: password: "{{ aldpro_admin_password }}" @@ -121,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..b2f76ac8f3 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 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..5aba671edf 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 @@ -31,21 +30,21 @@ options: 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..039cf3cb70 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 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..45c86e0491 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 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..e4fb5544d6 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: @@ -52,14 +51,14 @@ options: 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" + - "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..3cb6d501ea 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: @@ -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 9ef046ede4..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,60 +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. + - 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 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..a205ecc789 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 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..a909eab690 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 @@ -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..f539e569e8 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 @@ -161,7 +158,7 @@ url: 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..40aa416968 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 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..2663b4fe35 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 @@ -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..0f6064eeca 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's important to set + 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..cc3136c3bf 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,28 +35,24 @@ 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: @@ -70,56 +65,54 @@ options: 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 +121,59 @@ 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. 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 +187,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 +201,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 +235,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 +348,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 +362,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 +392,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 From 7732d64abb4ce9838e90cf02b37dd93db081b940 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 17:06:05 +0100 Subject: [PATCH 103/302] [PR #9388/6aadcc72 backport][stable-10] [mem ... n]*.py: normalize docs (#9406) [mem ... n]*.py: normalize docs (#9388) * [mem ... n]*.py: normalize docs * Update plugins/modules/netcup_dns.py Co-authored-by: Felix Fontein * netcup_dns: change type of RV(records) From complex to list of dicts. --------- Co-authored-by: Felix Fontein (cherry picked from commit 6aadcc72d13d37f17dead369395b51c0f8680757) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/memset_dns_reload.py | 56 +- plugins/modules/memset_memstore_info.py | 73 +- plugins/modules/memset_server_info.py | 67 +- plugins/modules/memset_zone.py | 99 +- plugins/modules/memset_zone_domain.py | 81 +- plugins/modules/memset_zone_record.py | 137 +- plugins/modules/mksysb.py | 41 +- plugins/modules/modprobe.py | 91 +- plugins/modules/monit.py | 26 +- plugins/modules/mqtt.py | 66 +- plugins/modules/mssql_db.py | 41 +- plugins/modules/mssql_script.py | 248 ++- plugins/modules/nagios.py | 38 +- plugins/modules/netcup_dns.py | 84 +- plugins/modules/newrelic_deployment.py | 28 +- plugins/modules/nexmo.py | 24 +- plugins/modules/nginx_status_info.py | 17 +- plugins/modules/nictagadm.py | 43 +- plugins/modules/nmcli.py | 2416 +++++++++++------------ plugins/modules/nomad_job.py | 75 +- plugins/modules/nomad_job_info.py | 28 +- plugins/modules/nomad_token.py | 89 +- plugins/modules/nosh.py | 498 +++-- plugins/modules/npm.py | 13 +- plugins/modules/nsupdate.py | 208 +- 25 files changed, 2245 insertions(+), 2342 deletions(-) diff --git a/plugins/modules/memset_dns_reload.py b/plugins/modules/memset_dns_reload.py index 8cff51ade1..100f81fc05 100644 --- a/plugins/modules/memset_dns_reload.py +++ b/plugins/modules/memset_dns_reload.py @@ -8,53 +8,47 @@ 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 +79,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..4d8804e3be 100644 --- a/plugins/modules/memset_zone.py +++ b/plugins/modules/memset_zone.py @@ -8,60 +8,55 @@ 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 +74,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..ca4b07aaaf 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 diff --git a/plugins/modules/memset_zone_record.py b/plugins/modules/memset_zone_record.py index 349240b84e..553cd66926 100644 --- a/plugins/modules/memset_zone_record.py +++ b/plugins/modules/memset_zone_record.py @@ -8,83 +8,78 @@ 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 +113,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 +163,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 3d6a7c2410..b7b93cce2b 100644 --- a/plugins/modules/modprobe.py +++ b/plugins/modules/modprobe.py @@ -8,59 +8,58 @@ 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 - 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)." -''' + 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 @@ -78,7 +77,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..f97cd12e64 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 diff --git a/plugins/modules/mqtt.py b/plugins/modules/mqtt.py index f8d64e6a00..462f809ade 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,67 @@ 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) + - 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 +112,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..95f529aff3 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,54 @@ 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 +89,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..045cafde88 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,74 @@ 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 +136,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 +157,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 '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..7a0c26b48e 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). + - 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..370aaa5dca 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,12 +25,12 @@ 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: @@ -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..99ff996670 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,48 @@ 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..3293362ec3 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,40 @@ 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..7fa681d6d8 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 4ea6799577..a8784e870c 100644 --- a/plugins/modules/nmcli.py +++ b/plugins/modules/nmcli.py @@ -9,1090 +9,1067 @@ 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. + - 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: + 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 [-][-]. + - 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 + 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 + 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