From f833982d6f686063288b9be2c3721aac8d35d521 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 9 May 2023 21:45:10 +0200 Subject: [PATCH 0001/1451] After branching stable-7, prepare for the next major release cycle. --- changelogs/changelog.yaml | 2 +- .../2090-idrac-redfish-resource-id-fix.yml | 2 -- .../3216-nmcli-bridge-idempotency-fix.yml | 2 -- ...-operation-apply-time-to-simple-update.yml | 2 -- .../3935-add-gitlab-group-runner.yml | 2 -- .../4028-modprobe-persistent-option.yml | 3 -- ...pdates-for-full-simple-update-workflow.yml | 4 --- ...4387-nmcli-mtu-for-vlan-connection-fix.yml | 2 -- .../473-nmcli-slave-type-implemented.yml | 2 -- .../5143-fix-xfs-quota-project-init.yml | 3 -- changelogs/fragments/5431-nmcli-wifi.yml | 4 --- .../fragments/5486-snap-alias-cmd-runner.yml | 2 -- .../5489-nonetype-in-get-vm-by-label.yml | 2 -- .../5490-adding-put-functionality.yml | 2 -- changelogs/fragments/5493-proxmox.yml | 2 -- .../5502-xfconf-facts-deprecation.yml | 6 ---- .../5506-onepassword_raw-missing-param.yml | 2 -- ...gical-flaw-when-deleting-jenkins-build.yml | 2 -- .../fragments/5538-cmd-runner-as-fixed.yml | 3 -- .../fragments/5543-dependent-template.yml | 2 -- .../fragments/5545-gconftool-cmd-runner.yml | 2 -- .../fragments/5549-lxd-project-sanity.yml | 2 -- ...50-java_certs-not-enough-info-on-error.yml | 2 -- .../5553-spotinst-aws-elasticgroup-sanity.yml | 2 -- .../fragments/5557-udm-share-sanity.yml | 2 -- changelogs/fragments/5559-udm-user-sanity.yml | 2 -- .../5563-rax-scaling-group-sanity.yml | 2 -- .../fragments/5565-jenkins-plugin-sanity.yml | 2 -- .../fragments/5566-additional-flags-nmap.yml | 3 -- ...-plugin-fix-default-inventory_hostname.yml | 2 -- ...hat_subscription-subscribe-parameters.yaml | 3 -- .../5592-redirect-remove-sap-modules.yml | 13 --------- ...5601-unixy-callback-use-config-manager.yml | 2 -- changelogs/fragments/5602-proxmox-tags.yml | 2 -- .../5603-redfish-idrac-job-id-in-response.yml | 2 -- ...05-ssh-config-add-host-key-algorithms.yaml | 2 -- .../fragments/5612-puppet-cmd-runner.yml | 2 -- .../5615-zypper-transactional-update.yml | 2 -- .../fragments/5619-keycloak-improvements.yml | 3 -- ...t_subscription-subscribe-parameters-2.yaml | 3 -- .../fragments/5628-fix-vmadm-off-by-one.yml | 2 -- ...add-prepend-hash-option-for-channel-id.yml | 2 -- ...se-yaml-safe-load-instead-of-yaml-load.yml | 2 -- .../5640-fix-typo-proxmox-inventory.yml | 2 -- .../5647-cmd-runner-as-bool-false.yml | 2 -- .../5659-fix-lxc_container-command.yml | 2 -- ...dhat_subscription-server_proxy_scheme.yaml | 3 -- ..._subscription-credentials-when-needed.yaml | 4 --- .../fragments/5666-gitlab-variables.yml | 3 -- changelogs/fragments/5672-proxmox.yml | 3 -- ...5680-ansible_galaxy_install-fx-locale.yaml | 3 -- ...88-opkg-module-install-certain-version.yml | 2 -- .../5694-add-custom-fields-to-bitwarden.yml | 2 -- .../fragments/5703-sudoers-host-support.yml | 2 -- .../5705-opkg-fix-force-reinstall.yml | 2 -- ...06-add-builds-forks-container-registry.yml | 2 -- .../5714-proxmox-lxc-tag-support.yml | 3 -- changelogs/fragments/5718-opkg-refactor.yaml | 2 -- .../5719-xfconf-facts-deprecation.yml | 6 ---- .../5720-ssh_config-plugin-sanity.yml | 2 -- ...anageiq-policies-deprecate-list-state.yaml | 2 -- ...hat_subscription-add-red-hat-api-token.yml | 2 -- ...27-manageiq-tags-deprecate-list-state.yaml | 2 -- ...32-bugfix-keycloak-userfed-idempotency.yml | 6 ---- ...-when-default-workspace-doesnt-exists.yaml | 3 -- ...unixy-callback-fix-config-manager-typo.yml | 2 -- ...n-update-default-mapper-simultaneously.yml | 7 ----- .../fragments/5751-gem-fix-uninstall-hang.yml | 2 -- changelogs/fragments/5752-rax-deprecation.yml | 28 ------------------- .../fragments/5755-mh-fix-output-conflict.yml | 2 -- changelogs/fragments/5761-callback-types.yml | 7 ----- .../fragments/5765-mh-lax-output-conflict.yml | 9 ------ ...72-consul-deprecate-params-when-absent.yml | 2 -- changelogs/fragments/5773-snap-mh-execute.yml | 2 -- .../5793-apache2-module-npm-warnings.yml | 2 -- .../fragments/5794-alternatives-fedora37.yml | 2 -- .../fragments/5803-proxmox-read-timeout.yml | 2 -- ...04-minor-changes-to-hpe-ilo-collection.yml | 2 -- ...-xml-children-parameter-does-not-exist.yml | 2 -- .../5811-clarify-bitwarden-error.yml | 2 -- .../5812-implement-updateconf-api-call.yml | 2 -- .../5814-support-keycloak-subgroups.yml | 2 -- .../5818-nsupdate-fix-zone-lookup.yml | 2 -- .../fragments/5822-gem-uninstall-force.yml | 2 -- changelogs/fragments/5829-fix-yarn-global.yml | 4 --- .../fragments/5830-sefcontext-path-subs.yml | 2 -- .../5843-terraform-validate-no-color.yml | 2 -- .../5844-iptables-state-refactor.yml | 2 -- ...-add-filter-by-collection-id-parameter.yml | 2 -- ...ype-defaulted-keycloak_userfed-mappers.yml | 2 -- ...5866-lxd_container-diff-and-check-mode.yml | 2 -- .../5867-apt_rpm-add-clean-and-upgrade.yml | 2 -- ...doers-add-support-for-setenv-parameter.yml | 2 -- ...t-basic-auth-usage-on-session-creation.yml | 2 -- .../fragments/5888-update-key-title.yml | 2 -- .../5897-ipa_group-add-external-users.yml | 2 -- ...reboot-functionality-to-redfish-config.yml | 2 -- ...ibute-fucntionality-to-redfish-command.yml | 2 -- .../5907-fix-gitlab_runner-not-idempotent.yml | 4 --- changelogs/fragments/5913-dig-caa.yml | 2 -- changelogs/fragments/5914-dig-dnskey.yml | 2 -- ...ress-urllib3-insecure-request-warnings.yml | 2 -- ...unner_access_level_default_with_gitlab.yml | 2 -- .../fragments/5926-flatpak-remote-enabled.yml | 2 -- .../5927-set-user-agent-dnsimple.yml | 2 -- changelogs/fragments/5928-fix-favicon-url.yml | 2 -- changelogs/fragments/5933-linting.yml | 2 -- .../5934-fix-keycloak-sanitize_cr.yml | 2 -- ...word-ignore-errors-from-op-account-get.yml | 2 -- ...zfs-allow-cannot-parse-unknown-uid-gid.yml | 2 -- ...970-add-proxyjump-option-to-ssh-config.yml | 2 -- .../5972-cloudflare-dns-srv-record.yml | 3 -- ...4-nmcli_add_new_addr_gen_mode6_options.yml | 2 -- .../5985-add-new-gitlab-api-features.yml | 2 -- .../fragments/5994-github-webhook-secret.yml | 2 -- .../fragments/6011-osx-defaults-errors.yml | 2 -- changelogs/fragments/6034-lxd-tls.yml | 2 -- .../6043-jc_plugin_parser_support.yml | 2 -- .../fragments/6045-xorder-discovery.yml | 2 -- .../fragments/6048-nmcli-addres-order.yml | 2 -- changelogs/fragments/6049-dconf-strings.yml | 2 -- ...6065-nmcli-add-runner-fast-rate-option.yml | 2 -- .../fragments/6074-loader_in_listify.yml.yml | 2 -- changelogs/fragments/6100-jenkins_plugin.yml | 2 -- ...106-nmcli-ipv4-mayfail-idempotency-fix.yml | 2 -- .../6111-influxdb_user-check-mode.yaml | 2 -- ...error_in_gitlab_runner_creation_update.yml | 2 -- .../6114-memset-add-url-error-handling.yml | 2 -- .../fragments/6117-remove-stormssh-depend.yml | 2 -- ...-plugin-fix-default-inventory_hostname.yml | 2 -- changelogs/fragments/6119-opkg-update.yaml | 2 -- ...edhat_subscription-subscribe-via-dbus.yaml | 4 --- .../fragments/6127-yarn-ignore-warnings.yml | 2 -- ...-interfaces_file-for-no-leading-spaces.yml | 2 -- changelogs/fragments/6138-fix-yarn-global.yml | 2 -- .../fragments/6149-openbsd_pkg-term.yml | 2 -- .../fragments/6154-znode-optional-tls.yml | 2 -- .../6158-create-proxmox-vm-from-archive.yml | 2 -- .../6160-add-command-make-output.yml | 2 -- changelogs/fragments/6165-nmap-port.yml | 2 -- .../fragments/6171-shutdown-using-systemd.yml | 2 -- .../6180-replace-deprecated-badzipfile.yml | 2 -- .../fragments/6192-allow-empty-resultsets.yml | 4 --- .../6198-pipx-inject-install-apps.yml | 2 -- ...99-archive-generate-checksum-in-chunks.yml | 2 -- .../6200-adding-open-option-to-nmap.yml | 2 -- ...203-add-append-option-to-ipa-hostgroup.yml | 2 -- changelogs/fragments/6206-dconf-booleans.yml | 2 -- .../6208-hpe-thermal-fan-percent.yaml | 2 -- ...6210-add-worklog-functionality-to-jira.yml | 2 -- .../fragments/6211-rhsm-require-root.yml | 6 ---- .../fragments/6212-pipx-include-injected.yml | 2 -- ...24-download-certificate-via-api-bugfix.yml | 2 -- .../6227-xen-orchestra-check-response-id.yml | 2 -- .../6259-redhat_subscription-fix-force.yaml | 4 --- .../6267-homebrew-cask-upgrade-all-greedy.yml | 2 -- changelogs/fragments/6269-mksysb-output.yml | 2 -- .../fragments/6270-gconftool2-changed.yml | 5 ---- ..._subscription-fix-environments-centos.yaml | 4 --- .../6277-add-topics-gitlab-project.yml | 2 -- ...cinga2_host-template-and-template-vars.yml | 2 -- ...fix-flatpak-check-if-already-installed.yml | 2 -- .../6293-add-puppet-skip-tags-option.yaml | 3 -- .../6294-fix-one_vm-instantiation.yml | 2 -- ...96-LanceNero-Terraform_statefile_check.yml | 2 -- ...rundeck-modules-fixes-and-improvements.yml | 8 ------ ...te-latest-and-add-system-site-packages.yml | 2 -- .../6308-pipx-add-system-site-packages.yml | 2 -- ...6312-nmcli-add-macvlan-connection-type.yml | 2 -- changelogs/fragments/6318-add-form-flow.yml | 5 ---- ...ubscription-fix-environment-parameter.yaml | 5 ---- .../6334-dig-support-multiple-domains.yml | 3 -- changelogs/fragments/6336-dconf-refactor.yml | 2 -- ...-variables-to-nmap-dynamic-inventoiry.yaml | 2 -- .../6361-snap-alias-regex-bugfix.yml | 2 -- .../6382-udm-dns-record-refactor.yml | 2 -- changelogs/fragments/6383-deps-failed.yml | 2 -- changelogs/fragments/6384-gitlab-refactor.yml | 2 -- changelogs/fragments/6385-cpan-mh-feat.yml | 2 -- .../fragments/6401-rhsm_release-required.yml | 2 -- .../fragments/6404-ini_file-section.yml | 2 -- changelogs/fragments/6428-removals.yml | 8 ------ .../fragments/6440-dnsimple-info-refactor.yml | 2 -- .../fragments/6441-snap_alias-refactor.yml | 2 -- .../6448-proxmox-kvm-migration-support.yml | 2 -- .../6456-fix-portage-withbdeps-false.yml | 2 -- changelogs/fragments/6458-puppet-noop.yml | 2 -- changelogs/fragments/6464-mh-imports.yml | 2 -- .../fragments/6465-mh-deps-deprecation.yml | 2 -- changelogs/fragments/6468-snap-cmdrunner.yml | 2 -- changelogs/fragments/6473-ldap_search.yml | 4 --- changelogs/fragments/6491-dconf-respawn.yml | 2 -- .../fragments/6493-deprecate-rhn-modules.yml | 10 ------- changelogs/fragments/6497-terraform-fix.yml | 2 -- changelogs/fragments/deps.yml | 2 -- changelogs/fragments/passwordstore-lock.yml | 2 -- .../fragments/remove-unneeded-imports.yml | 2 -- .../fragments/xxxx-ldap-ca-cert-file.yml | 2 -- galaxy.yml | 2 +- 199 files changed, 2 insertions(+), 531 deletions(-) delete mode 100644 changelogs/fragments/2090-idrac-redfish-resource-id-fix.yml delete mode 100644 changelogs/fragments/3216-nmcli-bridge-idempotency-fix.yml delete mode 100644 changelogs/fragments/3910-redfish-add-operation-apply-time-to-simple-update.yml delete mode 100644 changelogs/fragments/3935-add-gitlab-group-runner.yml delete mode 100644 changelogs/fragments/4028-modprobe-persistent-option.yml delete mode 100644 changelogs/fragments/4276-redfish-command-updates-for-full-simple-update-workflow.yml delete mode 100644 changelogs/fragments/4387-nmcli-mtu-for-vlan-connection-fix.yml delete mode 100644 changelogs/fragments/473-nmcli-slave-type-implemented.yml delete mode 100644 changelogs/fragments/5143-fix-xfs-quota-project-init.yml delete mode 100644 changelogs/fragments/5431-nmcli-wifi.yml delete mode 100644 changelogs/fragments/5486-snap-alias-cmd-runner.yml delete mode 100644 changelogs/fragments/5489-nonetype-in-get-vm-by-label.yml delete mode 100644 changelogs/fragments/5490-adding-put-functionality.yml delete mode 100644 changelogs/fragments/5493-proxmox.yml delete mode 100644 changelogs/fragments/5502-xfconf-facts-deprecation.yml delete mode 100644 changelogs/fragments/5506-onepassword_raw-missing-param.yml delete mode 100644 changelogs/fragments/5514-fix-logical-flaw-when-deleting-jenkins-build.yml delete mode 100644 changelogs/fragments/5538-cmd-runner-as-fixed.yml delete mode 100644 changelogs/fragments/5543-dependent-template.yml delete mode 100644 changelogs/fragments/5545-gconftool-cmd-runner.yml delete mode 100644 changelogs/fragments/5549-lxd-project-sanity.yml delete mode 100644 changelogs/fragments/5550-java_certs-not-enough-info-on-error.yml delete mode 100644 changelogs/fragments/5553-spotinst-aws-elasticgroup-sanity.yml delete mode 100644 changelogs/fragments/5557-udm-share-sanity.yml delete mode 100644 changelogs/fragments/5559-udm-user-sanity.yml delete mode 100644 changelogs/fragments/5563-rax-scaling-group-sanity.yml delete mode 100644 changelogs/fragments/5565-jenkins-plugin-sanity.yml delete mode 100644 changelogs/fragments/5566-additional-flags-nmap.yml delete mode 100644 changelogs/fragments/5570-chroot-plugin-fix-default-inventory_hostname.yml delete mode 100644 changelogs/fragments/5583-redhat_subscription-subscribe-parameters.yaml delete mode 100644 changelogs/fragments/5592-redirect-remove-sap-modules.yml delete mode 100644 changelogs/fragments/5601-unixy-callback-use-config-manager.yml delete mode 100644 changelogs/fragments/5602-proxmox-tags.yml delete mode 100644 changelogs/fragments/5603-redfish-idrac-job-id-in-response.yml delete mode 100644 changelogs/fragments/5605-ssh-config-add-host-key-algorithms.yaml delete mode 100644 changelogs/fragments/5612-puppet-cmd-runner.yml delete mode 100644 changelogs/fragments/5615-zypper-transactional-update.yml delete mode 100644 changelogs/fragments/5619-keycloak-improvements.yml delete mode 100644 changelogs/fragments/5627-redhat_subscription-subscribe-parameters-2.yaml delete mode 100644 changelogs/fragments/5628-fix-vmadm-off-by-one.yml delete mode 100644 changelogs/fragments/5629-add-prepend-hash-option-for-channel-id.yml delete mode 100644 changelogs/fragments/5632-vdo-Use-yaml-safe-load-instead-of-yaml-load.yml delete mode 100644 changelogs/fragments/5640-fix-typo-proxmox-inventory.yml delete mode 100644 changelogs/fragments/5647-cmd-runner-as-bool-false.yml delete mode 100644 changelogs/fragments/5659-fix-lxc_container-command.yml delete mode 100644 changelogs/fragments/5662-redhat_subscription-server_proxy_scheme.yaml delete mode 100644 changelogs/fragments/5664-redhat_subscription-credentials-when-needed.yaml delete mode 100644 changelogs/fragments/5666-gitlab-variables.yml delete mode 100644 changelogs/fragments/5672-proxmox.yml delete mode 100644 changelogs/fragments/5680-ansible_galaxy_install-fx-locale.yaml delete mode 100644 changelogs/fragments/5688-opkg-module-install-certain-version.yml delete mode 100644 changelogs/fragments/5694-add-custom-fields-to-bitwarden.yml delete mode 100644 changelogs/fragments/5703-sudoers-host-support.yml delete mode 100644 changelogs/fragments/5705-opkg-fix-force-reinstall.yml delete mode 100644 changelogs/fragments/5706-add-builds-forks-container-registry.yml delete mode 100644 changelogs/fragments/5714-proxmox-lxc-tag-support.yml delete mode 100644 changelogs/fragments/5718-opkg-refactor.yaml delete mode 100644 changelogs/fragments/5719-xfconf-facts-deprecation.yml delete mode 100644 changelogs/fragments/5720-ssh_config-plugin-sanity.yml delete mode 100644 changelogs/fragments/5721-manageiq-policies-deprecate-list-state.yaml delete mode 100644 changelogs/fragments/5725-redhat_subscription-add-red-hat-api-token.yml delete mode 100644 changelogs/fragments/5727-manageiq-tags-deprecate-list-state.yaml delete mode 100644 changelogs/fragments/5732-bugfix-keycloak-userfed-idempotency.yml delete mode 100644 changelogs/fragments/5735-terraform-init-fix-when-default-workspace-doesnt-exists.yaml delete mode 100644 changelogs/fragments/5744-unixy-callback-fix-config-manager-typo.yml delete mode 100644 changelogs/fragments/5750-bugfixing-keycloak-usrfed-fail-when-update-default-mapper-simultaneously.yml delete mode 100644 changelogs/fragments/5751-gem-fix-uninstall-hang.yml delete mode 100644 changelogs/fragments/5752-rax-deprecation.yml delete mode 100644 changelogs/fragments/5755-mh-fix-output-conflict.yml delete mode 100644 changelogs/fragments/5761-callback-types.yml delete mode 100644 changelogs/fragments/5765-mh-lax-output-conflict.yml delete mode 100644 changelogs/fragments/5772-consul-deprecate-params-when-absent.yml delete mode 100644 changelogs/fragments/5773-snap-mh-execute.yml delete mode 100644 changelogs/fragments/5793-apache2-module-npm-warnings.yml delete mode 100644 changelogs/fragments/5794-alternatives-fedora37.yml delete mode 100644 changelogs/fragments/5803-proxmox-read-timeout.yml delete mode 100644 changelogs/fragments/5804-minor-changes-to-hpe-ilo-collection.yml delete mode 100644 changelogs/fragments/5808-xml-children-parameter-does-not-exist.yml delete mode 100644 changelogs/fragments/5811-clarify-bitwarden-error.yml delete mode 100644 changelogs/fragments/5812-implement-updateconf-api-call.yml delete mode 100644 changelogs/fragments/5814-support-keycloak-subgroups.yml delete mode 100644 changelogs/fragments/5818-nsupdate-fix-zone-lookup.yml delete mode 100644 changelogs/fragments/5822-gem-uninstall-force.yml delete mode 100644 changelogs/fragments/5829-fix-yarn-global.yml delete mode 100644 changelogs/fragments/5830-sefcontext-path-subs.yml delete mode 100644 changelogs/fragments/5843-terraform-validate-no-color.yml delete mode 100644 changelogs/fragments/5844-iptables-state-refactor.yml delete mode 100644 changelogs/fragments/5851-lookup-bitwarden-add-filter-by-collection-id-parameter.yml delete mode 100644 changelogs/fragments/5863-providerType-defaulted-keycloak_userfed-mappers.yml delete mode 100644 changelogs/fragments/5866-lxd_container-diff-and-check-mode.yml delete mode 100644 changelogs/fragments/5867-apt_rpm-add-clean-and-upgrade.yml delete mode 100644 changelogs/fragments/5883-sudoers-add-support-for-setenv-parameter.yml delete mode 100644 changelogs/fragments/5886-redfish-correct-basic-auth-usage-on-session-creation.yml delete mode 100644 changelogs/fragments/5888-update-key-title.yml delete mode 100644 changelogs/fragments/5897-ipa_group-add-external-users.yml delete mode 100644 changelogs/fragments/5899-adding-enablesecureboot-functionality-to-redfish-config.yml delete mode 100644 changelogs/fragments/5900-adding-verifybiosattribute-fucntionality-to-redfish-command.yml delete mode 100644 changelogs/fragments/5907-fix-gitlab_runner-not-idempotent.yml delete mode 100644 changelogs/fragments/5913-dig-caa.yml delete mode 100644 changelogs/fragments/5914-dig-dnskey.yml delete mode 100644 changelogs/fragments/5915-suppress-urllib3-insecure-request-warnings.yml delete mode 100644 changelogs/fragments/5925-align_gitlab_runner_access_level_default_with_gitlab.yml delete mode 100644 changelogs/fragments/5926-flatpak-remote-enabled.yml delete mode 100644 changelogs/fragments/5927-set-user-agent-dnsimple.yml delete mode 100644 changelogs/fragments/5928-fix-favicon-url.yml delete mode 100644 changelogs/fragments/5933-linting.yml delete mode 100644 changelogs/fragments/5934-fix-keycloak-sanitize_cr.yml delete mode 100644 changelogs/fragments/5942-onepassword-ignore-errors-from-op-account-get.yml delete mode 100644 changelogs/fragments/5943-zfs_delegate_admin-fix-zfs-allow-cannot-parse-unknown-uid-gid.yml delete mode 100644 changelogs/fragments/5970-add-proxyjump-option-to-ssh-config.yml delete mode 100644 changelogs/fragments/5972-cloudflare-dns-srv-record.yml delete mode 100644 changelogs/fragments/5974-nmcli_add_new_addr_gen_mode6_options.yml delete mode 100644 changelogs/fragments/5985-add-new-gitlab-api-features.yml delete mode 100644 changelogs/fragments/5994-github-webhook-secret.yml delete mode 100644 changelogs/fragments/6011-osx-defaults-errors.yml delete mode 100644 changelogs/fragments/6034-lxd-tls.yml delete mode 100644 changelogs/fragments/6043-jc_plugin_parser_support.yml delete mode 100644 changelogs/fragments/6045-xorder-discovery.yml delete mode 100644 changelogs/fragments/6048-nmcli-addres-order.yml delete mode 100644 changelogs/fragments/6049-dconf-strings.yml delete mode 100644 changelogs/fragments/6065-nmcli-add-runner-fast-rate-option.yml delete mode 100644 changelogs/fragments/6074-loader_in_listify.yml.yml delete mode 100644 changelogs/fragments/6100-jenkins_plugin.yml delete mode 100644 changelogs/fragments/6106-nmcli-ipv4-mayfail-idempotency-fix.yml delete mode 100644 changelogs/fragments/6111-influxdb_user-check-mode.yaml delete mode 100644 changelogs/fragments/6112-fix_key_error_in_gitlab_runner_creation_update.yml delete mode 100644 changelogs/fragments/6114-memset-add-url-error-handling.yml delete mode 100644 changelogs/fragments/6117-remove-stormssh-depend.yml delete mode 100644 changelogs/fragments/6118-jail-plugin-fix-default-inventory_hostname.yml delete mode 100644 changelogs/fragments/6119-opkg-update.yaml delete mode 100644 changelogs/fragments/6122-redhat_subscription-subscribe-via-dbus.yaml delete mode 100644 changelogs/fragments/6127-yarn-ignore-warnings.yml delete mode 100644 changelogs/fragments/6131-fix-interfaces_file-for-no-leading-spaces.yml delete mode 100644 changelogs/fragments/6138-fix-yarn-global.yml delete mode 100644 changelogs/fragments/6149-openbsd_pkg-term.yml delete mode 100644 changelogs/fragments/6154-znode-optional-tls.yml delete mode 100644 changelogs/fragments/6158-create-proxmox-vm-from-archive.yml delete mode 100644 changelogs/fragments/6160-add-command-make-output.yml delete mode 100644 changelogs/fragments/6165-nmap-port.yml delete mode 100644 changelogs/fragments/6171-shutdown-using-systemd.yml delete mode 100644 changelogs/fragments/6180-replace-deprecated-badzipfile.yml delete mode 100644 changelogs/fragments/6192-allow-empty-resultsets.yml delete mode 100644 changelogs/fragments/6198-pipx-inject-install-apps.yml delete mode 100644 changelogs/fragments/6199-archive-generate-checksum-in-chunks.yml delete mode 100644 changelogs/fragments/6200-adding-open-option-to-nmap.yml delete mode 100644 changelogs/fragments/6203-add-append-option-to-ipa-hostgroup.yml delete mode 100644 changelogs/fragments/6206-dconf-booleans.yml delete mode 100644 changelogs/fragments/6208-hpe-thermal-fan-percent.yaml delete mode 100644 changelogs/fragments/6210-add-worklog-functionality-to-jira.yml delete mode 100644 changelogs/fragments/6211-rhsm-require-root.yml delete mode 100644 changelogs/fragments/6212-pipx-include-injected.yml delete mode 100644 changelogs/fragments/6224-download-certificate-via-api-bugfix.yml delete mode 100644 changelogs/fragments/6227-xen-orchestra-check-response-id.yml delete mode 100644 changelogs/fragments/6259-redhat_subscription-fix-force.yaml delete mode 100644 changelogs/fragments/6267-homebrew-cask-upgrade-all-greedy.yml delete mode 100644 changelogs/fragments/6269-mksysb-output.yml delete mode 100644 changelogs/fragments/6270-gconftool2-changed.yml delete mode 100644 changelogs/fragments/6275-redhat_subscription-fix-environments-centos.yaml delete mode 100644 changelogs/fragments/6277-add-topics-gitlab-project.yml delete mode 100644 changelogs/fragments/6286-icinga2_host-template-and-template-vars.yml delete mode 100644 changelogs/fragments/6289-bugfix-flatpak-check-if-already-installed.yml delete mode 100644 changelogs/fragments/6293-add-puppet-skip-tags-option.yaml delete mode 100644 changelogs/fragments/6294-fix-one_vm-instantiation.yml delete mode 100644 changelogs/fragments/6296-LanceNero-Terraform_statefile_check.yml delete mode 100644 changelogs/fragments/6300-rundeck-modules-fixes-and-improvements.yml delete mode 100644 changelogs/fragments/6303-pipx-fix-state-latest-and-add-system-site-packages.yml delete mode 100644 changelogs/fragments/6308-pipx-add-system-site-packages.yml delete mode 100644 changelogs/fragments/6312-nmcli-add-macvlan-connection-type.yml delete mode 100644 changelogs/fragments/6318-add-form-flow.yml delete mode 100644 changelogs/fragments/6319-redhat_subscription-fix-environment-parameter.yaml delete mode 100644 changelogs/fragments/6334-dig-support-multiple-domains.yml delete mode 100644 changelogs/fragments/6336-dconf-refactor.yml delete mode 100644 changelogs/fragments/6351-support-env-variables-to-nmap-dynamic-inventoiry.yaml delete mode 100644 changelogs/fragments/6361-snap-alias-regex-bugfix.yml delete mode 100644 changelogs/fragments/6382-udm-dns-record-refactor.yml delete mode 100644 changelogs/fragments/6383-deps-failed.yml delete mode 100644 changelogs/fragments/6384-gitlab-refactor.yml delete mode 100644 changelogs/fragments/6385-cpan-mh-feat.yml delete mode 100644 changelogs/fragments/6401-rhsm_release-required.yml delete mode 100644 changelogs/fragments/6404-ini_file-section.yml delete mode 100644 changelogs/fragments/6428-removals.yml delete mode 100644 changelogs/fragments/6440-dnsimple-info-refactor.yml delete mode 100644 changelogs/fragments/6441-snap_alias-refactor.yml delete mode 100644 changelogs/fragments/6448-proxmox-kvm-migration-support.yml delete mode 100644 changelogs/fragments/6456-fix-portage-withbdeps-false.yml delete mode 100644 changelogs/fragments/6458-puppet-noop.yml delete mode 100644 changelogs/fragments/6464-mh-imports.yml delete mode 100644 changelogs/fragments/6465-mh-deps-deprecation.yml delete mode 100644 changelogs/fragments/6468-snap-cmdrunner.yml delete mode 100644 changelogs/fragments/6473-ldap_search.yml delete mode 100644 changelogs/fragments/6491-dconf-respawn.yml delete mode 100644 changelogs/fragments/6493-deprecate-rhn-modules.yml delete mode 100644 changelogs/fragments/6497-terraform-fix.yml delete mode 100644 changelogs/fragments/deps.yml delete mode 100644 changelogs/fragments/passwordstore-lock.yml delete mode 100644 changelogs/fragments/remove-unneeded-imports.yml delete mode 100644 changelogs/fragments/xxxx-ldap-ca-cert-file.yml diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml index 28411f7413..b5f3e72456 100644 --- a/changelogs/changelog.yaml +++ b/changelogs/changelog.yaml @@ -1,2 +1,2 @@ -ancestor: 6.0.0 +ancestor: 7.0.0 releases: {} diff --git a/changelogs/fragments/2090-idrac-redfish-resource-id-fix.yml b/changelogs/fragments/2090-idrac-redfish-resource-id-fix.yml deleted file mode 100644 index e386cb1416..0000000000 --- a/changelogs/fragments/2090-idrac-redfish-resource-id-fix.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - idrac_redfish_command - allow user to specify ``resource_id`` for ``CreateBiosConfigJob`` to specify an exact manager (https://github.com/ansible-collections/community.general/issues/2090). diff --git a/changelogs/fragments/3216-nmcli-bridge-idempotency-fix.yml b/changelogs/fragments/3216-nmcli-bridge-idempotency-fix.yml deleted file mode 100644 index 130800b6da..0000000000 --- a/changelogs/fragments/3216-nmcli-bridge-idempotency-fix.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - nmcli - fixed idempotency issue for bridge connections. Module forced default value of ``bridge.priority`` to nmcli if not set; if ``bridge.stp`` is disabled nmcli ignores it and keep default (https://github.com/ansible-collections/community.general/issues/3216, https://github.com/ansible-collections/community.general/issues/4683). diff --git a/changelogs/fragments/3910-redfish-add-operation-apply-time-to-simple-update.yml b/changelogs/fragments/3910-redfish-add-operation-apply-time-to-simple-update.yml deleted file mode 100644 index d52438ca45..0000000000 --- a/changelogs/fragments/3910-redfish-add-operation-apply-time-to-simple-update.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - redfish_command - add ``update_apply_time`` to ``SimpleUpdate`` command (https://github.com/ansible-collections/community.general/issues/3910). diff --git a/changelogs/fragments/3935-add-gitlab-group-runner.yml b/changelogs/fragments/3935-add-gitlab-group-runner.yml deleted file mode 100644 index eba390180a..0000000000 --- a/changelogs/fragments/3935-add-gitlab-group-runner.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - 'gitlab_runner - allow to register group runner (https://github.com/ansible-collections/community.general/pull/3935).' diff --git a/changelogs/fragments/4028-modprobe-persistent-option.yml b/changelogs/fragments/4028-modprobe-persistent-option.yml deleted file mode 100644 index 78c812bcbd..0000000000 --- a/changelogs/fragments/4028-modprobe-persistent-option.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -minor_changes: - - modprobe - add ``persistent`` option (https://github.com/ansible-collections/community.general/issues/4028, https://github.com/ansible-collections/community.general/pull/542). diff --git a/changelogs/fragments/4276-redfish-command-updates-for-full-simple-update-workflow.yml b/changelogs/fragments/4276-redfish-command-updates-for-full-simple-update-workflow.yml deleted file mode 100644 index 2f5da1467b..0000000000 --- a/changelogs/fragments/4276-redfish-command-updates-for-full-simple-update-workflow.yml +++ /dev/null @@ -1,4 +0,0 @@ -minor_changes: - - redfish_command - add ``update_status`` to output of ``SimpleUpdate`` command to allow a user monitor the update in progress (https://github.com/ansible-collections/community.general/issues/4276). - - redfish_info - add ``GetUpdateStatus`` command to check the progress of a previous update request (https://github.com/ansible-collections/community.general/issues/4276). - - redfish_command - add ``PerformRequestedOperations`` command to perform any operations necessary to continue the update flow (https://github.com/ansible-collections/community.general/issues/4276). diff --git a/changelogs/fragments/4387-nmcli-mtu-for-vlan-connection-fix.yml b/changelogs/fragments/4387-nmcli-mtu-for-vlan-connection-fix.yml deleted file mode 100644 index e867135b2a..0000000000 --- a/changelogs/fragments/4387-nmcli-mtu-for-vlan-connection-fix.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - nmcli - implemented changing mtu value on vlan interfaces (https://github.com/ansible-collections/community.general/issues/4387). diff --git a/changelogs/fragments/473-nmcli-slave-type-implemented.yml b/changelogs/fragments/473-nmcli-slave-type-implemented.yml deleted file mode 100644 index aa9dabe12e..0000000000 --- a/changelogs/fragments/473-nmcli-slave-type-implemented.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - nmcli - new module option ``slave_type`` added to allow creation of various types of slave devices (https://github.com/ansible-collections/community.general/issues/473, https://github.com/ansible-collections/community.general/pull/6108). diff --git a/changelogs/fragments/5143-fix-xfs-quota-project-init.yml b/changelogs/fragments/5143-fix-xfs-quota-project-init.yml deleted file mode 100644 index 6915cb14e3..0000000000 --- a/changelogs/fragments/5143-fix-xfs-quota-project-init.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -bugfixes: - - xfs_quota - in case of a project quota, the call to ``xfs_quota`` did not initialize/reset the project (https://github.com/ansible-collections/community.general/issues/5143). diff --git a/changelogs/fragments/5431-nmcli-wifi.yml b/changelogs/fragments/5431-nmcli-wifi.yml deleted file mode 100644 index 0f6f4edde5..0000000000 --- a/changelogs/fragments/5431-nmcli-wifi.yml +++ /dev/null @@ -1,4 +0,0 @@ -bugfixes: - - nmcli - fix failure to handle WIFI settings when connection type not specified (https://github.com/ansible-collections/community.general/pull/5431). - - nmcli - fix improper detection of changes to ``wifi.wake-on-wlan`` (https://github.com/ansible-collections/community.general/pull/5431). - - nmcli - fix change handling of values specified as an integer 0 (https://github.com/ansible-collections/community.general/pull/5431). diff --git a/changelogs/fragments/5486-snap-alias-cmd-runner.yml b/changelogs/fragments/5486-snap-alias-cmd-runner.yml deleted file mode 100644 index 59ae0c5abf..0000000000 --- a/changelogs/fragments/5486-snap-alias-cmd-runner.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - snap_alias - refactored module to use ``CmdRunner`` to execute ``snap`` (https://github.com/ansible-collections/community.general/pull/5486). diff --git a/changelogs/fragments/5489-nonetype-in-get-vm-by-label.yml b/changelogs/fragments/5489-nonetype-in-get-vm-by-label.yml deleted file mode 100644 index 8b0d92ec40..0000000000 --- a/changelogs/fragments/5489-nonetype-in-get-vm-by-label.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - one_vm - avoid splitting labels that are ``None`` (https://github.com/ansible-collections/community.general/pull/5489). \ No newline at end of file diff --git a/changelogs/fragments/5490-adding-put-functionality.yml b/changelogs/fragments/5490-adding-put-functionality.yml deleted file mode 100644 index 09141d2822..0000000000 --- a/changelogs/fragments/5490-adding-put-functionality.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - redfish_utils module utils - added PUT (``put_request()``) functionality (https://github.com/ansible-collections/community.general/pull/5490). diff --git a/changelogs/fragments/5493-proxmox.yml b/changelogs/fragments/5493-proxmox.yml deleted file mode 100644 index a14b7767e6..0000000000 --- a/changelogs/fragments/5493-proxmox.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "proxmox_disk - avoid duplicate ``vmid`` reference (https://github.com/ansible-collections/community.general/issues/5492, https://github.com/ansible-collections/community.general/pull/5493)." diff --git a/changelogs/fragments/5502-xfconf-facts-deprecation.yml b/changelogs/fragments/5502-xfconf-facts-deprecation.yml deleted file mode 100644 index 776d852700..0000000000 --- a/changelogs/fragments/5502-xfconf-facts-deprecation.yml +++ /dev/null @@ -1,6 +0,0 @@ -removed_features: - - > - xfconf - generating facts was deprecated in community.general 3.0.0, - however two factoids, ``previous_value`` and ``type`` continued to be generated by mistake. This behaviour - has been removed and ``xfconf`` generate no facts whatsoever - (https://github.com/ansible-collections/community.general/pull/5502). diff --git a/changelogs/fragments/5506-onepassword_raw-missing-param.yml b/changelogs/fragments/5506-onepassword_raw-missing-param.yml deleted file mode 100644 index f10ff28d28..0000000000 --- a/changelogs/fragments/5506-onepassword_raw-missing-param.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - onepassword_raw - add missing parameter to plugin documentation (https://github.com/ansible-collections/community.general/issues/5506). diff --git a/changelogs/fragments/5514-fix-logical-flaw-when-deleting-jenkins-build.yml b/changelogs/fragments/5514-fix-logical-flaw-when-deleting-jenkins-build.yml deleted file mode 100644 index 818ee95146..0000000000 --- a/changelogs/fragments/5514-fix-logical-flaw-when-deleting-jenkins-build.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - jenkins_build - fix the logical flaw when deleting a Jenkins build (https://github.com/ansible-collections/community.general/pull/5514). \ No newline at end of file diff --git a/changelogs/fragments/5538-cmd-runner-as-fixed.yml b/changelogs/fragments/5538-cmd-runner-as-fixed.yml deleted file mode 100644 index 714564b09f..0000000000 --- a/changelogs/fragments/5538-cmd-runner-as-fixed.yml +++ /dev/null @@ -1,3 +0,0 @@ -bugfixes: - - cmd_runner module utils - formatting arguments ``cmd_runner_fmt.as_fixed()`` was expecting an non-existing argument (https://github.com/ansible-collections/community.general/pull/5538). - - cmd_runner module utils - fixed bug when handling default cases in ``cmd_runner_fmt.as_map()`` (https://github.com/ansible-collections/community.general/pull/5538). diff --git a/changelogs/fragments/5543-dependent-template.yml b/changelogs/fragments/5543-dependent-template.yml deleted file mode 100644 index 63e8f67d63..0000000000 --- a/changelogs/fragments/5543-dependent-template.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "dependent lookup plugin - avoid warning on deprecated parameter for ``Templar.template()`` (https://github.com/ansible-collections/community.general/pull/5543)." diff --git a/changelogs/fragments/5545-gconftool-cmd-runner.yml b/changelogs/fragments/5545-gconftool-cmd-runner.yml deleted file mode 100644 index a41d5c3657..0000000000 --- a/changelogs/fragments/5545-gconftool-cmd-runner.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - gconftool2 - refactor using ``ModuleHelper`` and ``CmdRunner`` (https://github.com/ansible-collections/community.general/pull/5545). diff --git a/changelogs/fragments/5549-lxd-project-sanity.yml b/changelogs/fragments/5549-lxd-project-sanity.yml deleted file mode 100644 index 0a5e328e1c..0000000000 --- a/changelogs/fragments/5549-lxd-project-sanity.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - lxd_project - refactored code out to module utils to clear sanity check (https://github.com/ansible-collections/community.general/pull/5549). diff --git a/changelogs/fragments/5550-java_certs-not-enough-info-on-error.yml b/changelogs/fragments/5550-java_certs-not-enough-info-on-error.yml deleted file mode 100644 index c2b2be0418..0000000000 --- a/changelogs/fragments/5550-java_certs-not-enough-info-on-error.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - java_certs - add more detailed error output when extracting certificate from PKCS12 fails (https://github.com/ansible-collections/community.general/pull/5550). diff --git a/changelogs/fragments/5553-spotinst-aws-elasticgroup-sanity.yml b/changelogs/fragments/5553-spotinst-aws-elasticgroup-sanity.yml deleted file mode 100644 index 1213f5412a..0000000000 --- a/changelogs/fragments/5553-spotinst-aws-elasticgroup-sanity.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - spotinst_aws_elastigroup - add ``elements`` attribute when missing in ``list`` parameters (https://github.com/ansible-collections/community.general/pull/5553). diff --git a/changelogs/fragments/5557-udm-share-sanity.yml b/changelogs/fragments/5557-udm-share-sanity.yml deleted file mode 100644 index 12bd3d026e..0000000000 --- a/changelogs/fragments/5557-udm-share-sanity.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - udm_share - added ``elements`` attribute to ``list`` type parameters (https://github.com/ansible-collections/community.general/pull/5557). diff --git a/changelogs/fragments/5559-udm-user-sanity.yml b/changelogs/fragments/5559-udm-user-sanity.yml deleted file mode 100644 index 1501591f81..0000000000 --- a/changelogs/fragments/5559-udm-user-sanity.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - udm_user - add ``elements`` attribute when missing in ``list`` parameters (https://github.com/ansible-collections/community.general/pull/5559). diff --git a/changelogs/fragments/5563-rax-scaling-group-sanity.yml b/changelogs/fragments/5563-rax-scaling-group-sanity.yml deleted file mode 100644 index 310257f293..0000000000 --- a/changelogs/fragments/5563-rax-scaling-group-sanity.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - rax_scaling_group - refactored out code to the ``rax`` module utils to clear the sanity check (https://github.com/ansible-collections/community.general/pull/5563). diff --git a/changelogs/fragments/5565-jenkins-plugin-sanity.yml b/changelogs/fragments/5565-jenkins-plugin-sanity.yml deleted file mode 100644 index ea72d90615..0000000000 --- a/changelogs/fragments/5565-jenkins-plugin-sanity.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - jenkins_plugin - refactor code to module util to fix sanity check (https://github.com/ansible-collections/community.general/pull/5565). diff --git a/changelogs/fragments/5566-additional-flags-nmap.yml b/changelogs/fragments/5566-additional-flags-nmap.yml deleted file mode 100644 index d42f3a4695..0000000000 --- a/changelogs/fragments/5566-additional-flags-nmap.yml +++ /dev/null @@ -1,3 +0,0 @@ -minor_changes: - - nmap inventory plugin - add new options ``udp_scan``, ``icmp_timestamp``, and ``dns_resolve`` for different types of scans (https://github.com/ansible-collections/community.general/pull/5566). - diff --git a/changelogs/fragments/5570-chroot-plugin-fix-default-inventory_hostname.yml b/changelogs/fragments/5570-chroot-plugin-fix-default-inventory_hostname.yml deleted file mode 100644 index fc0c074f84..0000000000 --- a/changelogs/fragments/5570-chroot-plugin-fix-default-inventory_hostname.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "chroot connection plugin - add ``inventory_hostname`` to vars under ``remote_addr``. This is needed for compatibility with ansible-core 2.13 (https://github.com/ansible-collections/community.general/pull/5570)." \ No newline at end of file diff --git a/changelogs/fragments/5583-redhat_subscription-subscribe-parameters.yaml b/changelogs/fragments/5583-redhat_subscription-subscribe-parameters.yaml deleted file mode 100644 index bef3676c3b..0000000000 --- a/changelogs/fragments/5583-redhat_subscription-subscribe-parameters.yaml +++ /dev/null @@ -1,3 +0,0 @@ -bugfixes: - - redhat_subscription - do not pass arguments to ``subscription-manager register`` for things already configured; now a specified ``rhsm_baseurl`` is properly set for subscription-manager - (https://github.com/ansible-collections/community.general/pull/5583). diff --git a/changelogs/fragments/5592-redirect-remove-sap-modules.yml b/changelogs/fragments/5592-redirect-remove-sap-modules.yml deleted file mode 100644 index 0d6cc2bf39..0000000000 --- a/changelogs/fragments/5592-redirect-remove-sap-modules.yml +++ /dev/null @@ -1,13 +0,0 @@ -removed_features: - - | - All ``sap`` modules have been removed from this collection. - They have been migrated to the `community.sap_libs `_ collection. - Redirections have been provided. - Following modules are affected: - - sapcar_extract - - sap_task_list_execute - - hana_query -breaking_changes: - - | - If you are not using this collection as part of Ansible, but installed (and/or upgraded) community.general manually, you need to make sure to also install ``community.sap_libs`` if you are using any of the ``sapcar_extract``, ``sap_task_list_execute``, and ``hana_query`` modules. - Without that collection installed, the redirects for these modules do not work. diff --git a/changelogs/fragments/5601-unixy-callback-use-config-manager.yml b/changelogs/fragments/5601-unixy-callback-use-config-manager.yml deleted file mode 100644 index f3d0362f8f..0000000000 --- a/changelogs/fragments/5601-unixy-callback-use-config-manager.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - unixy callback plugin - fix plugin to work with ansible-core 2.14 by using Ansible's configuration manager for handling options (https://github.com/ansible-collections/community.general/issues/5600). diff --git a/changelogs/fragments/5602-proxmox-tags.yml b/changelogs/fragments/5602-proxmox-tags.yml deleted file mode 100644 index 32498f0366..0000000000 --- a/changelogs/fragments/5602-proxmox-tags.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "proxmox inventory plugin - handle tags delimited by semicolon instead of comma, which happens from Proxmox 7.3 on (https://github.com/ansible-collections/community.general/pull/5602)." diff --git a/changelogs/fragments/5603-redfish-idrac-job-id-in-response.yml b/changelogs/fragments/5603-redfish-idrac-job-id-in-response.yml deleted file mode 100644 index 5987d193b1..0000000000 --- a/changelogs/fragments/5603-redfish-idrac-job-id-in-response.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - idrac_redfish_command - add ``job_id`` to ``CreateBiosConfigJob`` response (https://github.com/ansible-collections/community.general/issues/5603). diff --git a/changelogs/fragments/5605-ssh-config-add-host-key-algorithms.yaml b/changelogs/fragments/5605-ssh-config-add-host-key-algorithms.yaml deleted file mode 100644 index 1535d9b13d..0000000000 --- a/changelogs/fragments/5605-ssh-config-add-host-key-algorithms.yaml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ssh_config - add ``host_key_algorithms`` option (https://github.com/ansible-collections/community.general/pull/5605). diff --git a/changelogs/fragments/5612-puppet-cmd-runner.yml b/changelogs/fragments/5612-puppet-cmd-runner.yml deleted file mode 100644 index a2d14bf5fc..0000000000 --- a/changelogs/fragments/5612-puppet-cmd-runner.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - puppet - refactored module to use ``CmdRunner`` for executing ``puppet`` (https://github.com/ansible-collections/community.general/pull/5612). diff --git a/changelogs/fragments/5615-zypper-transactional-update.yml b/changelogs/fragments/5615-zypper-transactional-update.yml deleted file mode 100644 index 5eb6bb8405..0000000000 --- a/changelogs/fragments/5615-zypper-transactional-update.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "zypper - make package managing work on readonly filesystem of openSUSE MicroOS (https://github.com/ansible-collections/community.general/pull/5615)." diff --git a/changelogs/fragments/5619-keycloak-improvements.yml b/changelogs/fragments/5619-keycloak-improvements.yml deleted file mode 100644 index 2e5a739dad..0000000000 --- a/changelogs/fragments/5619-keycloak-improvements.yml +++ /dev/null @@ -1,3 +0,0 @@ -bugfixes: - - "keycloak_client_rolemapping - remove only listed mappings with ``state=absent`` (https://github.com/ansible-collections/community.general/pull/5619)." - - "keycloak_client_rolemapping - calculate ``proposed`` and ``after`` return values properly (https://github.com/ansible-collections/community.general/pull/5619)." diff --git a/changelogs/fragments/5627-redhat_subscription-subscribe-parameters-2.yaml b/changelogs/fragments/5627-redhat_subscription-subscribe-parameters-2.yaml deleted file mode 100644 index c76f6871d8..0000000000 --- a/changelogs/fragments/5627-redhat_subscription-subscribe-parameters-2.yaml +++ /dev/null @@ -1,3 +0,0 @@ -bugfixes: - - redhat_subscription - do not ignore ``consumer_name`` and other variables if ``activationkey`` is specified - (https://github.com/ansible-collections/community.general/issues/3486, https://github.com/ansible-collections/community.general/pull/5627). diff --git a/changelogs/fragments/5628-fix-vmadm-off-by-one.yml b/changelogs/fragments/5628-fix-vmadm-off-by-one.yml deleted file mode 100644 index bcb7bf63e6..0000000000 --- a/changelogs/fragments/5628-fix-vmadm-off-by-one.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - vmadm - fix for index out of range error in ``get_vm_uuid`` (https://github.com/ansible-collections/community.general/pull/5628). diff --git a/changelogs/fragments/5629-add-prepend-hash-option-for-channel-id.yml b/changelogs/fragments/5629-add-prepend-hash-option-for-channel-id.yml deleted file mode 100644 index f38a6b4e13..0000000000 --- a/changelogs/fragments/5629-add-prepend-hash-option-for-channel-id.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - "slack - add option ``prepend_hash`` which allows to control whether a ``#`` is prepended to ``channel_id``. The current behavior (value ``auto``) is to prepend ``#`` unless some specific prefixes are found. That list of prefixes is incomplete, and there does not seem to exist a documented condition on when exactly ``#`` must not be prepended. We recommend to explicitly set ``prepend_hash=always`` or ``prepend_hash=never`` to avoid any ambiguity (https://github.com/ansible-collections/community.general/pull/5629)." \ No newline at end of file diff --git a/changelogs/fragments/5632-vdo-Use-yaml-safe-load-instead-of-yaml-load.yml b/changelogs/fragments/5632-vdo-Use-yaml-safe-load-instead-of-yaml-load.yml deleted file mode 100644 index c2b0756eca..0000000000 --- a/changelogs/fragments/5632-vdo-Use-yaml-safe-load-instead-of-yaml-load.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - vdo - now uses ``yaml.safe_load()`` to parse command output instead of the deprecated ``yaml.load()`` which is potentially unsafe. Using ``yaml.load()`` without explicitely setting a ``Loader=`` is also an error in pyYAML 6.0 (https://github.com/ansible-collections/community.general/pull/5632). diff --git a/changelogs/fragments/5640-fix-typo-proxmox-inventory.yml b/changelogs/fragments/5640-fix-typo-proxmox-inventory.yml deleted file mode 100644 index d5b8de5aea..0000000000 --- a/changelogs/fragments/5640-fix-typo-proxmox-inventory.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "proxmox inventory plugin - fix bug while templating when using templates for the ``url``, ``user``, ``password``, ``token_id``, or ``token_secret`` options (https://github.com/ansible-collections/community.general/pull/5640)." diff --git a/changelogs/fragments/5647-cmd-runner-as-bool-false.yml b/changelogs/fragments/5647-cmd-runner-as-bool-false.yml deleted file mode 100644 index 5dc447d235..0000000000 --- a/changelogs/fragments/5647-cmd-runner-as-bool-false.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - cmd_runner module utils - ``cmd_runner_fmt.as_bool()`` can now take an extra parameter to format when value is false (https://github.com/ansible-collections/community.general/pull/5647). diff --git a/changelogs/fragments/5659-fix-lxc_container-command.yml b/changelogs/fragments/5659-fix-lxc_container-command.yml deleted file mode 100644 index 450d889808..0000000000 --- a/changelogs/fragments/5659-fix-lxc_container-command.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - lxc_container - fix the arguments of the lxc command which broke the creation and cloning of containers (https://github.com/ansible-collections/community.general/issues/5578). diff --git a/changelogs/fragments/5662-redhat_subscription-server_proxy_scheme.yaml b/changelogs/fragments/5662-redhat_subscription-server_proxy_scheme.yaml deleted file mode 100644 index 293e18311a..0000000000 --- a/changelogs/fragments/5662-redhat_subscription-server_proxy_scheme.yaml +++ /dev/null @@ -1,3 +0,0 @@ -minor_changes: - - redhat_subscription - add a ``server_proxy_scheme`` parameter to configure the scheme for the proxy server - (https://github.com/ansible-collections/community.general/pull/5662). diff --git a/changelogs/fragments/5664-redhat_subscription-credentials-when-needed.yaml b/changelogs/fragments/5664-redhat_subscription-credentials-when-needed.yaml deleted file mode 100644 index c300b957ce..0000000000 --- a/changelogs/fragments/5664-redhat_subscription-credentials-when-needed.yaml +++ /dev/null @@ -1,4 +0,0 @@ -minor_changes: - - redhat_subscription - credentials (``username``, ``activationkey``, and so on) are required now - only if a system needs to be registered, or ``force_register`` is specified - (https://github.com/ansible-collections/community.general/pull/5664). diff --git a/changelogs/fragments/5666-gitlab-variables.yml b/changelogs/fragments/5666-gitlab-variables.yml deleted file mode 100644 index 2070fa8e4a..0000000000 --- a/changelogs/fragments/5666-gitlab-variables.yml +++ /dev/null @@ -1,3 +0,0 @@ -bugfixes: - - gitlab_group_variables - fix dropping variables accidentally when GitLab introduced new properties (https://github.com/ansible-collections/community.general/pull/5667). - - gitlab_project_variables - fix dropping variables accidentally when GitLab introduced new properties (https://github.com/ansible-collections/community.general/pull/5667). \ No newline at end of file diff --git a/changelogs/fragments/5672-proxmox.yml b/changelogs/fragments/5672-proxmox.yml deleted file mode 100644 index 4fafe53d14..0000000000 --- a/changelogs/fragments/5672-proxmox.yml +++ /dev/null @@ -1,3 +0,0 @@ -bugfixes: - - "proxmox_disk - fixed possible issues with redundant ``vmid`` parameter (https://github.com/ansible-collections/community.general/issues/5492, https://github.com/ansible-collections/community.general/pull/5672)." - - "proxmox_nic - fixed possible issues with redundant ``vmid`` parameter (https://github.com/ansible-collections/community.general/issues/5492, https://github.com/ansible-collections/community.general/pull/5672)." diff --git a/changelogs/fragments/5680-ansible_galaxy_install-fx-locale.yaml b/changelogs/fragments/5680-ansible_galaxy_install-fx-locale.yaml deleted file mode 100644 index 35fd88bc25..0000000000 --- a/changelogs/fragments/5680-ansible_galaxy_install-fx-locale.yaml +++ /dev/null @@ -1,3 +0,0 @@ -bugfixes: - - ansible_galaxy_install - try ``C.UTF-8`` and then fall back to ``en_US.UTF-8`` before failing (https://github.com/ansible-collections/community.general/pull/5680). - - ansible_galaxy_install - set default to raise exception if command's return code is different from zero (https://github.com/ansible-collections/community.general/pull/5680). diff --git a/changelogs/fragments/5688-opkg-module-install-certain-version.yml b/changelogs/fragments/5688-opkg-module-install-certain-version.yml deleted file mode 100644 index 88168bd202..0000000000 --- a/changelogs/fragments/5688-opkg-module-install-certain-version.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - opkg - allow installing a package in a certain version (https://github.com/ansible-collections/community.general/pull/5688). diff --git a/changelogs/fragments/5694-add-custom-fields-to-bitwarden.yml b/changelogs/fragments/5694-add-custom-fields-to-bitwarden.yml deleted file mode 100644 index 55006f06a9..0000000000 --- a/changelogs/fragments/5694-add-custom-fields-to-bitwarden.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - bitwarden lookup plugin - can now retrieve secrets from custom fields (https://github.com/ansible-collections/community.general/pull/5694). diff --git a/changelogs/fragments/5703-sudoers-host-support.yml b/changelogs/fragments/5703-sudoers-host-support.yml deleted file mode 100644 index 1aaa30d8d9..0000000000 --- a/changelogs/fragments/5703-sudoers-host-support.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - sudoers - adds ``host`` parameter for setting hostname restrictions in sudoers rules (https://github.com/ansible-collections/community.general/issues/5702). diff --git a/changelogs/fragments/5705-opkg-fix-force-reinstall.yml b/changelogs/fragments/5705-opkg-fix-force-reinstall.yml deleted file mode 100644 index 27a188ab9e..0000000000 --- a/changelogs/fragments/5705-opkg-fix-force-reinstall.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - opkg - fix issue that ``force=reinstall`` would not reinstall an existing package (https://github.com/ansible-collections/community.general/pull/5705). diff --git a/changelogs/fragments/5706-add-builds-forks-container-registry.yml b/changelogs/fragments/5706-add-builds-forks-container-registry.yml deleted file mode 100644 index 5635241b64..0000000000 --- a/changelogs/fragments/5706-add-builds-forks-container-registry.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - gitlab_project - add ``builds_access_level``, ``container_registry_access_level`` and ``forking_access_level`` options (https://github.com/ansible-collections/community.general/pull/5706). diff --git a/changelogs/fragments/5714-proxmox-lxc-tag-support.yml b/changelogs/fragments/5714-proxmox-lxc-tag-support.yml deleted file mode 100644 index 5e3dcc8fcf..0000000000 --- a/changelogs/fragments/5714-proxmox-lxc-tag-support.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -minor_changes: -- proxmox - added new module parameter ``tags`` for use with PVE 7+ (https://github.com/ansible-collections/community.general/pull/5714). diff --git a/changelogs/fragments/5718-opkg-refactor.yaml b/changelogs/fragments/5718-opkg-refactor.yaml deleted file mode 100644 index fb8b5680da..0000000000 --- a/changelogs/fragments/5718-opkg-refactor.yaml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - opkg - refactored module to use ``CmdRunner`` for executing ``opkg`` (https://github.com/ansible-collections/community.general/pull/5718). diff --git a/changelogs/fragments/5719-xfconf-facts-deprecation.yml b/changelogs/fragments/5719-xfconf-facts-deprecation.yml deleted file mode 100644 index 353c0f3730..0000000000 --- a/changelogs/fragments/5719-xfconf-facts-deprecation.yml +++ /dev/null @@ -1,6 +0,0 @@ -removed_features: - - > - xfconf - generating facts was deprecated in community.general 3.0.0, - however three factoids, ``property``, ``channel`` and ``value`` continued to be generated by mistake. - This behaviour has been removed and ``xfconf`` generate no facts whatsoever - (https://github.com/ansible-collections/community.general/pull/5502). diff --git a/changelogs/fragments/5720-ssh_config-plugin-sanity.yml b/changelogs/fragments/5720-ssh_config-plugin-sanity.yml deleted file mode 100644 index 19d57ea145..0000000000 --- a/changelogs/fragments/5720-ssh_config-plugin-sanity.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ssh_config - refactor code to module util to fix sanity check (https://github.com/ansible-collections/community.general/pull/5720). diff --git a/changelogs/fragments/5721-manageiq-policies-deprecate-list-state.yaml b/changelogs/fragments/5721-manageiq-policies-deprecate-list-state.yaml deleted file mode 100644 index 109a2103e4..0000000000 --- a/changelogs/fragments/5721-manageiq-policies-deprecate-list-state.yaml +++ /dev/null @@ -1,2 +0,0 @@ -deprecated_features: - - manageiq_policies - deprecate ``state=list`` in favour of using ``community.general.manageiq_policies_info`` (https://github.com/ansible-collections/community.general/pull/5721). diff --git a/changelogs/fragments/5725-redhat_subscription-add-red-hat-api-token.yml b/changelogs/fragments/5725-redhat_subscription-add-red-hat-api-token.yml deleted file mode 100644 index 980e91ceb2..0000000000 --- a/changelogs/fragments/5725-redhat_subscription-add-red-hat-api-token.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - redhat_subscription - adds ``token`` parameter for subscription-manager authentication using Red Hat API token (https://github.com/ansible-collections/community.general/pull/5725). diff --git a/changelogs/fragments/5727-manageiq-tags-deprecate-list-state.yaml b/changelogs/fragments/5727-manageiq-tags-deprecate-list-state.yaml deleted file mode 100644 index fe1c49fbf5..0000000000 --- a/changelogs/fragments/5727-manageiq-tags-deprecate-list-state.yaml +++ /dev/null @@ -1,2 +0,0 @@ -deprecated_features: - - manageiq_tags - deprecate ``state=list`` in favour of using ``community.general.manageiq_tags_info`` (https://github.com/ansible-collections/community.general/pull/5727). diff --git a/changelogs/fragments/5732-bugfix-keycloak-userfed-idempotency.yml b/changelogs/fragments/5732-bugfix-keycloak-userfed-idempotency.yml deleted file mode 100644 index c50a105c3f..0000000000 --- a/changelogs/fragments/5732-bugfix-keycloak-userfed-idempotency.yml +++ /dev/null @@ -1,6 +0,0 @@ -bugfixes: - - > - keycloak_user_federation - fixes idempotency detection issues. In some - cases the module could fail to properly detect already existing user - federations because of a buggy seemingly superflous extra query parameter - (https://github.com/ansible-collections/community.general/pull/5732). diff --git a/changelogs/fragments/5735-terraform-init-fix-when-default-workspace-doesnt-exists.yaml b/changelogs/fragments/5735-terraform-init-fix-when-default-workspace-doesnt-exists.yaml deleted file mode 100644 index 3ec348aed9..0000000000 --- a/changelogs/fragments/5735-terraform-init-fix-when-default-workspace-doesnt-exists.yaml +++ /dev/null @@ -1,3 +0,0 @@ -bugfixes: - - terraform - fix ``current`` workspace never getting appended to the ``all`` key in the ``workspace_ctf`` object (https://github.com/ansible-collections/community.general/pull/5735). - - terraform - fix ``terraform init`` failure when there are multiple workspaces on the remote backend and when ``default`` workspace is missing by setting ``TF_WORKSPACE`` environmental variable to the value of ``workspace`` when used (https://github.com/ansible-collections/community.general/pull/5735). diff --git a/changelogs/fragments/5744-unixy-callback-fix-config-manager-typo.yml b/changelogs/fragments/5744-unixy-callback-fix-config-manager-typo.yml deleted file mode 100644 index d60b43d3d4..0000000000 --- a/changelogs/fragments/5744-unixy-callback-fix-config-manager-typo.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - unixy callback plugin - fix typo introduced when updating to use Ansible's configuration manager for handling options (https://github.com/ansible-collections/community.general/issues/5600). diff --git a/changelogs/fragments/5750-bugfixing-keycloak-usrfed-fail-when-update-default-mapper-simultaneously.yml b/changelogs/fragments/5750-bugfixing-keycloak-usrfed-fail-when-update-default-mapper-simultaneously.yml deleted file mode 100644 index 93cfc3adcb..0000000000 --- a/changelogs/fragments/5750-bugfixing-keycloak-usrfed-fail-when-update-default-mapper-simultaneously.yml +++ /dev/null @@ -1,7 +0,0 @@ -bugfixes: - - >- - keycloak_user_federation - fixes federation creation issue. When a new - federation was created and at the same time a default / standard mapper - was also changed / updated the creation process failed as a bad None - set variable led to a bad malformed url request - (https://github.com/ansible-collections/community.general/pull/5750). diff --git a/changelogs/fragments/5751-gem-fix-uninstall-hang.yml b/changelogs/fragments/5751-gem-fix-uninstall-hang.yml deleted file mode 100644 index 3fdd0056de..0000000000 --- a/changelogs/fragments/5751-gem-fix-uninstall-hang.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - gem - fix hang due to interactive prompt for confirmation on specific version uninstall (https://github.com/ansible-collections/community.general/pull/5751). diff --git a/changelogs/fragments/5752-rax-deprecation.yml b/changelogs/fragments/5752-rax-deprecation.yml deleted file mode 100644 index 4db8412208..0000000000 --- a/changelogs/fragments/5752-rax-deprecation.yml +++ /dev/null @@ -1,28 +0,0 @@ -deprecated_features: - - rax_cbs_attachments - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_cbs - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_cdb_database - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_cdb - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_cdb_user - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_clb_nodes - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_clb - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_clb_ssl - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_dns - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_dns_record - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_facts - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_files_objects - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_files - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_identity - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_keypair - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_meta - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_mon_alarm - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_mon_check - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_mon_entity - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_mon_notification_plan - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_mon_notification - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_network - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_queue - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_scaling_group - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax_scaling_policy - module relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). - - rax module utils - module utils code relies on deprecated library ``pyrax`` and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5752). diff --git a/changelogs/fragments/5755-mh-fix-output-conflict.yml b/changelogs/fragments/5755-mh-fix-output-conflict.yml deleted file mode 100644 index f433cc0290..0000000000 --- a/changelogs/fragments/5755-mh-fix-output-conflict.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - ModuleHelper - fix bug when adjusting the name of reserved output variables (https://github.com/ansible-collections/community.general/pull/5755). diff --git a/changelogs/fragments/5761-callback-types.yml b/changelogs/fragments/5761-callback-types.yml deleted file mode 100644 index 62466f46a5..0000000000 --- a/changelogs/fragments/5761-callback-types.yml +++ /dev/null @@ -1,7 +0,0 @@ -bugfixes: - - "loganalytics callback plugin - adjust type of callback to ``notification``, it was incorrectly classified as ``aggregate`` before (https://github.com/ansible-collections/community.general/pull/5761)." - - "logdna callback plugin - adjust type of callback to ``notification``, it was incorrectly classified as ``aggregate`` before (https://github.com/ansible-collections/community.general/pull/5761)." - - "logstash callback plugin - adjust type of callback to ``notification``, it was incorrectly classified as ``aggregate`` before (https://github.com/ansible-collections/community.general/pull/5761)." - - "splunk callback plugin - adjust type of callback to ``notification``, it was incorrectly classified as ``aggregate`` before (https://github.com/ansible-collections/community.general/pull/5761)." - - "sumologic callback plugin - adjust type of callback to ``notification``, it was incorrectly classified as ``aggregate`` before (https://github.com/ansible-collections/community.general/pull/5761)." - - "syslog_json callback plugin - adjust type of callback to ``notification``, it was incorrectly classified as ``aggregate`` before (https://github.com/ansible-collections/community.general/pull/5761)." diff --git a/changelogs/fragments/5765-mh-lax-output-conflict.yml b/changelogs/fragments/5765-mh-lax-output-conflict.yml deleted file mode 100644 index 2e8cc292bd..0000000000 --- a/changelogs/fragments/5765-mh-lax-output-conflict.yml +++ /dev/null @@ -1,9 +0,0 @@ -breaking_changes: - - > - ModuleHelper module utils - when the module sets output variables named ``msg``, ``exception``, ``output``, ``vars``, or ``changed``, - the actual output will prefix those names with ``_`` (underscore symbol) only when they clash with output variables generated by ModuleHelper - itself, which only occurs when handling exceptions. Please note that this breaking - change does not require a new major release since before this release, it was not possible - to add such variables to the output - `due to a bug `__ - (https://github.com/ansible-collections/community.general/pull/5765). diff --git a/changelogs/fragments/5772-consul-deprecate-params-when-absent.yml b/changelogs/fragments/5772-consul-deprecate-params-when-absent.yml deleted file mode 100644 index 44d681765f..0000000000 --- a/changelogs/fragments/5772-consul-deprecate-params-when-absent.yml +++ /dev/null @@ -1,2 +0,0 @@ -deprecated_features: - - consul - deprecate using parameters unused for ``state=absent`` (https://github.com/ansible-collections/community.general/pull/5772). diff --git a/changelogs/fragments/5773-snap-mh-execute.yml b/changelogs/fragments/5773-snap-mh-execute.yml deleted file mode 100644 index 43b9b6a1ac..0000000000 --- a/changelogs/fragments/5773-snap-mh-execute.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - snap - minor refactor when executing module (https://github.com/ansible-collections/community.general/pull/5773). diff --git a/changelogs/fragments/5793-apache2-module-npm-warnings.yml b/changelogs/fragments/5793-apache2-module-npm-warnings.yml deleted file mode 100644 index a4750790a4..0000000000 --- a/changelogs/fragments/5793-apache2-module-npm-warnings.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - apache2_module - add module argument ``warn_mpm_absent`` to control whether warning are raised in some edge cases (https://github.com/ansible-collections/community.general/pull/5793). \ No newline at end of file diff --git a/changelogs/fragments/5794-alternatives-fedora37.yml b/changelogs/fragments/5794-alternatives-fedora37.yml deleted file mode 100644 index bfb77142cc..0000000000 --- a/changelogs/fragments/5794-alternatives-fedora37.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "alternatives - support subcommands on Fedora 37, which uses ``follower`` instead of ``slave`` (https://github.com/ansible-collections/community.general/pull/5794)." diff --git a/changelogs/fragments/5803-proxmox-read-timeout.yml b/changelogs/fragments/5803-proxmox-read-timeout.yml deleted file mode 100644 index fc29605e4f..0000000000 --- a/changelogs/fragments/5803-proxmox-read-timeout.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - proxmox_disk - fixed issue with read timeout on import action (https://github.com/ansible-collections/community.general/pull/5803). diff --git a/changelogs/fragments/5804-minor-changes-to-hpe-ilo-collection.yml b/changelogs/fragments/5804-minor-changes-to-hpe-ilo-collection.yml deleted file mode 100644 index b53bd9eecf..0000000000 --- a/changelogs/fragments/5804-minor-changes-to-hpe-ilo-collection.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ilo_redfish_utils module utils - change implementation of DNS Server IP and NTP Server IP update (https://github.com/ansible-collections/community.general/pull/5804). diff --git a/changelogs/fragments/5808-xml-children-parameter-does-not-exist.yml b/changelogs/fragments/5808-xml-children-parameter-does-not-exist.yml deleted file mode 100644 index 2bad2c9886..0000000000 --- a/changelogs/fragments/5808-xml-children-parameter-does-not-exist.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: -- xml - fixed a bug where empty ``children`` list would not be set (https://github.com/ansible-collections/community.general/pull/5808). \ No newline at end of file diff --git a/changelogs/fragments/5811-clarify-bitwarden-error.yml b/changelogs/fragments/5811-clarify-bitwarden-error.yml deleted file mode 100644 index ee9a3c72b1..0000000000 --- a/changelogs/fragments/5811-clarify-bitwarden-error.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - bitwarden lookup plugin - clarify what to do, if the bitwarden vault is not unlocked (https://github.com/ansible-collections/community.general/pull/5811). diff --git a/changelogs/fragments/5812-implement-updateconf-api-call.yml b/changelogs/fragments/5812-implement-updateconf-api-call.yml deleted file mode 100644 index 09058f044e..0000000000 --- a/changelogs/fragments/5812-implement-updateconf-api-call.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - one_vm - add a new ``updateconf`` option which implements the ``one.vm.updateconf`` API call (https://github.com/ansible-collections/community.general/pull/5812). diff --git a/changelogs/fragments/5814-support-keycloak-subgroups.yml b/changelogs/fragments/5814-support-keycloak-subgroups.yml deleted file mode 100644 index a369db4422..0000000000 --- a/changelogs/fragments/5814-support-keycloak-subgroups.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - keycloak_group - add new optional module parameter ``parents`` to properly handle keycloak subgroups (https://github.com/ansible-collections/community.general/pull/5814). diff --git a/changelogs/fragments/5818-nsupdate-fix-zone-lookup.yml b/changelogs/fragments/5818-nsupdate-fix-zone-lookup.yml deleted file mode 100644 index 4f6ed6a125..0000000000 --- a/changelogs/fragments/5818-nsupdate-fix-zone-lookup.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - nsupdate - fix zone lookup. The SOA record for an existing zone is returned as an answer RR and not as an authority RR (https://github.com/ansible-collections/community.general/issues/5817, https://github.com/ansible-collections/community.general/pull/5818). diff --git a/changelogs/fragments/5822-gem-uninstall-force.yml b/changelogs/fragments/5822-gem-uninstall-force.yml deleted file mode 100644 index 7b8a0efbda..0000000000 --- a/changelogs/fragments/5822-gem-uninstall-force.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - gem - fix force parameter not being passed to gem command when uninstalling (https://github.com/ansible-collections/community.general/pull/5822). diff --git a/changelogs/fragments/5829-fix-yarn-global.yml b/changelogs/fragments/5829-fix-yarn-global.yml deleted file mode 100644 index fade7d97f6..0000000000 --- a/changelogs/fragments/5829-fix-yarn-global.yml +++ /dev/null @@ -1,4 +0,0 @@ -bugfixes: - - yarn - fix ``state=latest`` not working with ``global=true`` (https://github.com/ansible-collections/community.general/issues/5712). - - yarn - fix ``global=true`` to check for the configured global folder instead of assuming the default (https://github.com/ansible-collections/community.general/pull/5829) - - yarn - fix ``state=absent`` not working with ``global=true`` when the package does not include a binary (https://github.com/ansible-collections/community.general/pull/5829) diff --git a/changelogs/fragments/5830-sefcontext-path-subs.yml b/changelogs/fragments/5830-sefcontext-path-subs.yml deleted file mode 100644 index 51fb554fab..0000000000 --- a/changelogs/fragments/5830-sefcontext-path-subs.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - sefcontext - add support for path substitutions (https://github.com/ansible-collections/community.general/issues/1193). diff --git a/changelogs/fragments/5843-terraform-validate-no-color.yml b/changelogs/fragments/5843-terraform-validate-no-color.yml deleted file mode 100644 index 25cc6045ad..0000000000 --- a/changelogs/fragments/5843-terraform-validate-no-color.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: -- terraform module - disable ANSI escape sequences during validation phase (https://github.com/ansible-collections/community.general/pull/5843). \ No newline at end of file diff --git a/changelogs/fragments/5844-iptables-state-refactor.yml b/changelogs/fragments/5844-iptables-state-refactor.yml deleted file mode 100644 index a69b88de24..0000000000 --- a/changelogs/fragments/5844-iptables-state-refactor.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - iptables_state - minor refactoring within the module (https://github.com/ansible-collections/community.general/pull/5844). diff --git a/changelogs/fragments/5851-lookup-bitwarden-add-filter-by-collection-id-parameter.yml b/changelogs/fragments/5851-lookup-bitwarden-add-filter-by-collection-id-parameter.yml deleted file mode 100644 index 28b878a5b0..0000000000 --- a/changelogs/fragments/5851-lookup-bitwarden-add-filter-by-collection-id-parameter.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - bitwarden lookup plugin - implement filtering results by ``collection_id`` parameter (https://github.com/ansible-collections/community.general/issues/5849). \ No newline at end of file diff --git a/changelogs/fragments/5863-providerType-defaulted-keycloak_userfed-mappers.yml b/changelogs/fragments/5863-providerType-defaulted-keycloak_userfed-mappers.yml deleted file mode 100644 index 6532ea92d9..0000000000 --- a/changelogs/fragments/5863-providerType-defaulted-keycloak_userfed-mappers.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - keycloak_user_federation - make ``org.keycloak.storage.ldap.mappers.LDAPStorageMapper`` the default value for mappers ``providerType`` (https://github.com/ansible-collections/community.general/pull/5863). diff --git a/changelogs/fragments/5866-lxd_container-diff-and-check-mode.yml b/changelogs/fragments/5866-lxd_container-diff-and-check-mode.yml deleted file mode 100644 index eb337cd42a..0000000000 --- a/changelogs/fragments/5866-lxd_container-diff-and-check-mode.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - lxd_container - add diff and check mode (https://github.com/ansible-collections/community.general/pull/5866). diff --git a/changelogs/fragments/5867-apt_rpm-add-clean-and-upgrade.yml b/changelogs/fragments/5867-apt_rpm-add-clean-and-upgrade.yml deleted file mode 100644 index b8d8272115..0000000000 --- a/changelogs/fragments/5867-apt_rpm-add-clean-and-upgrade.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - apt_rpm - adds ``clean``, ``dist_upgrade`` and ``update_kernel`` parameters for clear caches, complete upgrade system, and upgrade kernel packages (https://github.com/ansible-collections/community.general/pull/5867). diff --git a/changelogs/fragments/5883-sudoers-add-support-for-setenv-parameter.yml b/changelogs/fragments/5883-sudoers-add-support-for-setenv-parameter.yml deleted file mode 100644 index f713428136..0000000000 --- a/changelogs/fragments/5883-sudoers-add-support-for-setenv-parameter.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - sudoers - add ``setenv`` parameters to support passing environment variables via sudo. (https://github.com/ansible-collections/community.general/pull/5883) diff --git a/changelogs/fragments/5886-redfish-correct-basic-auth-usage-on-session-creation.yml b/changelogs/fragments/5886-redfish-correct-basic-auth-usage-on-session-creation.yml deleted file mode 100644 index 25ec0746a6..0000000000 --- a/changelogs/fragments/5886-redfish-correct-basic-auth-usage-on-session-creation.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - redfish_utils - removed basic auth HTTP header when performing a GET on the service root resource and when performing a POST to the session collection (https://github.com/ansible-collections/community.general/issues/5886). diff --git a/changelogs/fragments/5888-update-key-title.yml b/changelogs/fragments/5888-update-key-title.yml deleted file mode 100644 index d98dcc4c17..0000000000 --- a/changelogs/fragments/5888-update-key-title.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - gitlab_deploy_key - also update ``title`` and not just ``can_push`` (https://github.com/ansible-collections/community.general/pull/5888). diff --git a/changelogs/fragments/5897-ipa_group-add-external-users.yml b/changelogs/fragments/5897-ipa_group-add-external-users.yml deleted file mode 100644 index e41ea7a97c..0000000000 --- a/changelogs/fragments/5897-ipa_group-add-external-users.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ipa_group - allow to add and remove external users with the ``external_user`` option (https://github.com/ansible-collections/community.general/pull/5897). \ No newline at end of file diff --git a/changelogs/fragments/5899-adding-enablesecureboot-functionality-to-redfish-config.yml b/changelogs/fragments/5899-adding-enablesecureboot-functionality-to-redfish-config.yml deleted file mode 100644 index fba75df0eb..0000000000 --- a/changelogs/fragments/5899-adding-enablesecureboot-functionality-to-redfish-config.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - redfish_command - adding ``EnableSecureBoot`` functionality (https://github.com/ansible-collections/community.general/pull/5899). diff --git a/changelogs/fragments/5900-adding-verifybiosattribute-fucntionality-to-redfish-command.yml b/changelogs/fragments/5900-adding-verifybiosattribute-fucntionality-to-redfish-command.yml deleted file mode 100644 index bbbb464534..0000000000 --- a/changelogs/fragments/5900-adding-verifybiosattribute-fucntionality-to-redfish-command.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - redfish_command - adding ``VerifyBiosAttributes`` functionality (https://github.com/ansible-collections/community.general/pull/5900). diff --git a/changelogs/fragments/5907-fix-gitlab_runner-not-idempotent.yml b/changelogs/fragments/5907-fix-gitlab_runner-not-idempotent.yml deleted file mode 100644 index a7386b8c73..0000000000 --- a/changelogs/fragments/5907-fix-gitlab_runner-not-idempotent.yml +++ /dev/null @@ -1,4 +0,0 @@ -minor_changes: - - gitlab_runner - add new boolean option ``access_level_on_creation``. It controls, whether the value of ``access_level`` is used for runner registration or not. The option ``access_level`` has been ignored on registration so far and was only used on updates (https://github.com/ansible-collections/community.general/issues/5907, https://github.com/ansible-collections/community.general/pull/5908). -deprecated_features: - - gitlab_runner - the default of the new option ``access_level_on_creation`` will change from ``false`` to ``true`` in community.general 7.0.0. This will cause ``access_level`` to be used during runner registration as well, and not only during updates (https://github.com/ansible-collections/community.general/pull/5908). diff --git a/changelogs/fragments/5913-dig-caa.yml b/changelogs/fragments/5913-dig-caa.yml deleted file mode 100644 index 62ff698737..0000000000 --- a/changelogs/fragments/5913-dig-caa.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - "dig lookup plugin - support CAA record type (https://github.com/ansible-collections/community.general/pull/5913)." diff --git a/changelogs/fragments/5914-dig-dnskey.yml b/changelogs/fragments/5914-dig-dnskey.yml deleted file mode 100644 index d6a26388d2..0000000000 --- a/changelogs/fragments/5914-dig-dnskey.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "dig lookup plugin - correctly handle DNSKEY record type's ``algorithm`` field (https://github.com/ansible-collections/community.general/pull/5914)." diff --git a/changelogs/fragments/5915-suppress-urllib3-insecure-request-warnings.yml b/changelogs/fragments/5915-suppress-urllib3-insecure-request-warnings.yml deleted file mode 100644 index 9fa285154a..0000000000 --- a/changelogs/fragments/5915-suppress-urllib3-insecure-request-warnings.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - proxmox - suppress urllib3 ``InsecureRequestWarnings`` when ``validate_certs`` option is ``false`` (https://github.com/ansible-collections/community.general/pull/5931). diff --git a/changelogs/fragments/5925-align_gitlab_runner_access_level_default_with_gitlab.yml b/changelogs/fragments/5925-align_gitlab_runner_access_level_default_with_gitlab.yml deleted file mode 100644 index a14561f07e..0000000000 --- a/changelogs/fragments/5925-align_gitlab_runner_access_level_default_with_gitlab.yml +++ /dev/null @@ -1,2 +0,0 @@ -deprecated_features: - - gitlab_runner - the option ``access_level`` will lose its default value in community.general 8.0.0. From that version on, you have set this option to ``ref_protected`` explicitly, if you want to have a protected runner (https://github.com/ansible-collections/community.general/issues/5925). diff --git a/changelogs/fragments/5926-flatpak-remote-enabled.yml b/changelogs/fragments/5926-flatpak-remote-enabled.yml deleted file mode 100644 index 95185e613e..0000000000 --- a/changelogs/fragments/5926-flatpak-remote-enabled.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - flatpak_remote - add new boolean option ``enabled``. It controls, whether the remote is enabled or not (https://github.com/ansible-collections/community.general/pull/5926). diff --git a/changelogs/fragments/5927-set-user-agent-dnsimple.yml b/changelogs/fragments/5927-set-user-agent-dnsimple.yml deleted file mode 100644 index 1082b41481..0000000000 --- a/changelogs/fragments/5927-set-user-agent-dnsimple.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - "dnsimple - set custom User-Agent for API requests to DNSimple (https://github.com/ansible-collections/community.general/pull/5927)." diff --git a/changelogs/fragments/5928-fix-favicon-url.yml b/changelogs/fragments/5928-fix-favicon-url.yml deleted file mode 100644 index eccb9f4a0f..0000000000 --- a/changelogs/fragments/5928-fix-favicon-url.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - mattermost, rocketchat, slack - replace missing default favicon with docs.ansible.com favicon (https://github.com/ansible-collections/community.general/pull/5928). diff --git a/changelogs/fragments/5933-linting.yml b/changelogs/fragments/5933-linting.yml deleted file mode 100644 index d0c46542bf..0000000000 --- a/changelogs/fragments/5933-linting.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "terraform and timezone - slight refactoring to avoid linter reporting potentially undefined variables (https://github.com/ansible-collections/community.general/pull/5933)." diff --git a/changelogs/fragments/5934-fix-keycloak-sanitize_cr.yml b/changelogs/fragments/5934-fix-keycloak-sanitize_cr.yml deleted file mode 100644 index 1c3163023c..0000000000 --- a/changelogs/fragments/5934-fix-keycloak-sanitize_cr.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "keycloak_client - fix accidental replacement of value for attribute ``saml.signing.private.key`` with ``no_log`` in wrong contexts (https://github.com/ansible-collections/community.general/pull/5934)." \ No newline at end of file diff --git a/changelogs/fragments/5942-onepassword-ignore-errors-from-op-account-get.yml b/changelogs/fragments/5942-onepassword-ignore-errors-from-op-account-get.yml deleted file mode 100644 index e6b774dd35..0000000000 --- a/changelogs/fragments/5942-onepassword-ignore-errors-from-op-account-get.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: -- onepassword lookup plugin - Changed to ignore errors from "op account get" calls. Previously, errors would prevent auto-signin code from executing (https://github.com/ansible-collections/community.general/pull/5942). diff --git a/changelogs/fragments/5943-zfs_delegate_admin-fix-zfs-allow-cannot-parse-unknown-uid-gid.yml b/changelogs/fragments/5943-zfs_delegate_admin-fix-zfs-allow-cannot-parse-unknown-uid-gid.yml deleted file mode 100644 index f07ca8a9a5..0000000000 --- a/changelogs/fragments/5943-zfs_delegate_admin-fix-zfs-allow-cannot-parse-unknown-uid-gid.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - zfs_delegate_admin - zfs allow output can now be parsed when uids/gids are not known to the host system (https://github.com/ansible-collections/community.general/pull/5943). diff --git a/changelogs/fragments/5970-add-proxyjump-option-to-ssh-config.yml b/changelogs/fragments/5970-add-proxyjump-option-to-ssh-config.yml deleted file mode 100644 index a8594ed69f..0000000000 --- a/changelogs/fragments/5970-add-proxyjump-option-to-ssh-config.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ssh_config - add ``proxyjump`` option (https://github.com/ansible-collections/community.general/pull/5970). diff --git a/changelogs/fragments/5972-cloudflare-dns-srv-record.yml b/changelogs/fragments/5972-cloudflare-dns-srv-record.yml deleted file mode 100644 index a331b49d23..0000000000 --- a/changelogs/fragments/5972-cloudflare-dns-srv-record.yml +++ /dev/null @@ -1,3 +0,0 @@ -bugfixes: - - "cloudflare_dns - fixed the possiblity of setting a root-level SRV DNS record (https://github.com/ansible-collections/community.general/pull/5972)." - - "cloudflare_dns - fixed the idempotency for SRV DNS records (https://github.com/ansible-collections/community.general/pull/5972)." diff --git a/changelogs/fragments/5974-nmcli_add_new_addr_gen_mode6_options.yml b/changelogs/fragments/5974-nmcli_add_new_addr_gen_mode6_options.yml deleted file mode 100644 index 275ed8b584..0000000000 --- a/changelogs/fragments/5974-nmcli_add_new_addr_gen_mode6_options.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - nmcli - add ``default`` and ``default-or-eui64`` to the list of valid choices for ``addr_gen_mode6`` parameter (https://github.com/ansible-collections/community.general/pull/5974). diff --git a/changelogs/fragments/5985-add-new-gitlab-api-features.yml b/changelogs/fragments/5985-add-new-gitlab-api-features.yml deleted file mode 100644 index 7033a80bec..0000000000 --- a/changelogs/fragments/5985-add-new-gitlab-api-features.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - gitlab_project - add ``releases_access_level``, ``environments_access_level``, ``feature_flags_access_level``, ``infrastructure_access_level``, ``monitor_access_level``, and ``security_and_compliance_access_level`` options (https://github.com/ansible-collections/community.general/pull/5986). diff --git a/changelogs/fragments/5994-github-webhook-secret.yml b/changelogs/fragments/5994-github-webhook-secret.yml deleted file mode 100644 index 700703840c..0000000000 --- a/changelogs/fragments/5994-github-webhook-secret.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - github_webhook - fix always changed state when no secret is provided (https://github.com/ansible-collections/community.general/pull/5994). \ No newline at end of file diff --git a/changelogs/fragments/6011-osx-defaults-errors.yml b/changelogs/fragments/6011-osx-defaults-errors.yml deleted file mode 100644 index 49915d51a7..0000000000 --- a/changelogs/fragments/6011-osx-defaults-errors.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - "osx_defaults - include stderr in error messages (https://github.com/ansible-collections/community.general/pull/6011)." diff --git a/changelogs/fragments/6034-lxd-tls.yml b/changelogs/fragments/6034-lxd-tls.yml deleted file mode 100644 index 975215f3e5..0000000000 --- a/changelogs/fragments/6034-lxd-tls.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "lxd_* modules, lxd inventory plugin - fix TLS/SSL certificate validation problems by using the correct purpose when creating the TLS context (https://github.com/ansible-collections/community.general/issues/5616, https://github.com/ansible-collections/community.general/pull/6034)." diff --git a/changelogs/fragments/6043-jc_plugin_parser_support.yml b/changelogs/fragments/6043-jc_plugin_parser_support.yml deleted file mode 100644 index 3684f32fe4..0000000000 --- a/changelogs/fragments/6043-jc_plugin_parser_support.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - jc filter plugin - added the ability to use parser plugins (https://github.com/ansible-collections/community.general/pull/6043). diff --git a/changelogs/fragments/6045-xorder-discovery.yml b/changelogs/fragments/6045-xorder-discovery.yml deleted file mode 100644 index 5e7fb5a031..0000000000 --- a/changelogs/fragments/6045-xorder-discovery.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ldap modules - add ``xorder_discovery`` option (https://github.com/ansible-collections/community.general/issues/6045, https://github.com/ansible-collections/community.general/pull/6109). diff --git a/changelogs/fragments/6048-nmcli-addres-order.yml b/changelogs/fragments/6048-nmcli-addres-order.yml deleted file mode 100644 index 4de15cf084..0000000000 --- a/changelogs/fragments/6048-nmcli-addres-order.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - nmcli - order is significant for lists of addresses (https://github.com/ansible-collections/community.general/pull/6048). diff --git a/changelogs/fragments/6049-dconf-strings.yml b/changelogs/fragments/6049-dconf-strings.yml deleted file mode 100644 index 1d194b3389..0000000000 --- a/changelogs/fragments/6049-dconf-strings.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - dconf - parse GVariants for equality comparison when the Python module ``gi.repository`` is available (https://github.com/ansible-collections/community.general/pull/6049). diff --git a/changelogs/fragments/6065-nmcli-add-runner-fast-rate-option.yml b/changelogs/fragments/6065-nmcli-add-runner-fast-rate-option.yml deleted file mode 100644 index f49a10bc9e..0000000000 --- a/changelogs/fragments/6065-nmcli-add-runner-fast-rate-option.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - nmcli - add support for ``team.runner-fast-rate`` parameter for ``team`` connections (https://github.com/ansible-collections/community.general/issues/6065). diff --git a/changelogs/fragments/6074-loader_in_listify.yml.yml b/changelogs/fragments/6074-loader_in_listify.yml.yml deleted file mode 100644 index 9a0852a88e..0000000000 --- a/changelogs/fragments/6074-loader_in_listify.yml.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - cartesian and flattened lookup plugins - adjust to parameter deprecation in ansible-core 2.14's ``listify_lookup_plugin_terms`` helper function (https://github.com/ansible-collections/community.general/pull/6074). diff --git a/changelogs/fragments/6100-jenkins_plugin.yml b/changelogs/fragments/6100-jenkins_plugin.yml deleted file mode 100644 index 1f01d26083..0000000000 --- a/changelogs/fragments/6100-jenkins_plugin.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "jenkins_plugin - fix error due to undefined variable when updates file is not downloaded (https://github.com/ansible-collections/community.general/pull/6100)." diff --git a/changelogs/fragments/6106-nmcli-ipv4-mayfail-idempotency-fix.yml b/changelogs/fragments/6106-nmcli-ipv4-mayfail-idempotency-fix.yml deleted file mode 100644 index a444176155..0000000000 --- a/changelogs/fragments/6106-nmcli-ipv4-mayfail-idempotency-fix.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - nmcli - fixed idempotency issue when module params is set to ``may_fail4=false`` and ``method4=disabled``; in this case nmcli ignores change and keeps their own default value ``yes`` (https://github.com/ansible-collections/community.general/pull/6106). diff --git a/changelogs/fragments/6111-influxdb_user-check-mode.yaml b/changelogs/fragments/6111-influxdb_user-check-mode.yaml deleted file mode 100644 index 4789c2ba76..0000000000 --- a/changelogs/fragments/6111-influxdb_user-check-mode.yaml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - influxdb_user - fix running in check mode when the user does not exist yet (https://github.com/ansible-collections/community.general/pull/6111). diff --git a/changelogs/fragments/6112-fix_key_error_in_gitlab_runner_creation_update.yml b/changelogs/fragments/6112-fix_key_error_in_gitlab_runner_creation_update.yml deleted file mode 100644 index d752aed347..0000000000 --- a/changelogs/fragments/6112-fix_key_error_in_gitlab_runner_creation_update.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - gitlab_runner - fix ``KeyError`` on runner creation and update (https://github.com/ansible-collections/community.general/issues/6112). diff --git a/changelogs/fragments/6114-memset-add-url-error-handling.yml b/changelogs/fragments/6114-memset-add-url-error-handling.yml deleted file mode 100644 index 25dd869d19..0000000000 --- a/changelogs/fragments/6114-memset-add-url-error-handling.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "memset - fix memset urlerror handling (https://github.com/ansible-collections/community.general/pull/6114)." diff --git a/changelogs/fragments/6117-remove-stormssh-depend.yml b/changelogs/fragments/6117-remove-stormssh-depend.yml deleted file mode 100644 index f84ac6ac2e..0000000000 --- a/changelogs/fragments/6117-remove-stormssh-depend.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ssh_config - vendored StormSSH's config parser to avoid having to install StormSSH to use the module (https://github.com/ansible-collections/community.general/pull/6117). diff --git a/changelogs/fragments/6118-jail-plugin-fix-default-inventory_hostname.yml b/changelogs/fragments/6118-jail-plugin-fix-default-inventory_hostname.yml deleted file mode 100644 index ac2cb5cf43..0000000000 --- a/changelogs/fragments/6118-jail-plugin-fix-default-inventory_hostname.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "jail connection plugin - add ``inventory_hostname`` to vars under ``remote_addr``. This is needed for compatibility with ansible-core 2.13 (https://github.com/ansible-collections/community.general/pull/6118)." diff --git a/changelogs/fragments/6119-opkg-update.yaml b/changelogs/fragments/6119-opkg-update.yaml deleted file mode 100644 index b7450074d1..0000000000 --- a/changelogs/fragments/6119-opkg-update.yaml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - opkg - fixes bug when using ``update_cache=true`` (https://github.com/ansible-collections/community.general/issues/6004). diff --git a/changelogs/fragments/6122-redhat_subscription-subscribe-via-dbus.yaml b/changelogs/fragments/6122-redhat_subscription-subscribe-via-dbus.yaml deleted file mode 100644 index ee39d2b5b6..0000000000 --- a/changelogs/fragments/6122-redhat_subscription-subscribe-via-dbus.yaml +++ /dev/null @@ -1,4 +0,0 @@ -minor_changes: - - redhat_subscription - the registration is done using the D-Bus ``rhsm`` service instead of spawning a ``subscription-manager register`` command, if possible; - this avoids passing plain-text credentials as arguments to ``subscription-manager register``, which can be seen while that command runs - (https://github.com/ansible-collections/community.general/pull/6122). diff --git a/changelogs/fragments/6127-yarn-ignore-warnings.yml b/changelogs/fragments/6127-yarn-ignore-warnings.yml deleted file mode 100644 index f094838edb..0000000000 --- a/changelogs/fragments/6127-yarn-ignore-warnings.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - yarn - fixes bug where yarn module tasks would fail when warnings were emitted from Yarn. The ``yarn.list`` method was not filtering out warnings (https://github.com/ansible-collections/community.general/issues/6127). diff --git a/changelogs/fragments/6131-fix-interfaces_file-for-no-leading-spaces.yml b/changelogs/fragments/6131-fix-interfaces_file-for-no-leading-spaces.yml deleted file mode 100644 index c975d4e624..0000000000 --- a/changelogs/fragments/6131-fix-interfaces_file-for-no-leading-spaces.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - interfaces_file - fix reading options in lines not starting with a space (https://github.com/ansible-collections/community.general/issues/6120). diff --git a/changelogs/fragments/6138-fix-yarn-global.yml b/changelogs/fragments/6138-fix-yarn-global.yml deleted file mode 100644 index 30203ead6c..0000000000 --- a/changelogs/fragments/6138-fix-yarn-global.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - yarn - fix ``global=true`` to not fail when `executable` wasn't specified (https://github.com/ansible-collections/community.general/pull/6132) diff --git a/changelogs/fragments/6149-openbsd_pkg-term.yml b/changelogs/fragments/6149-openbsd_pkg-term.yml deleted file mode 100644 index 5fe1e5a6db..0000000000 --- a/changelogs/fragments/6149-openbsd_pkg-term.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - openbsd_pkg - set ``TERM`` to ``'dumb'`` in ``execute_command()`` to make module less dependant on the ``TERM`` environment variable set on the Ansible controller (https://github.com/ansible-collections/community.general/pull/6149). diff --git a/changelogs/fragments/6154-znode-optional-tls.yml b/changelogs/fragments/6154-znode-optional-tls.yml deleted file mode 100644 index 92570d4623..0000000000 --- a/changelogs/fragments/6154-znode-optional-tls.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - znode module - optional ``use_tls`` parameter added for encrypted communication (https://github.com/ansible-collections/community.general/issues/6154). diff --git a/changelogs/fragments/6158-create-proxmox-vm-from-archive.yml b/changelogs/fragments/6158-create-proxmox-vm-from-archive.yml deleted file mode 100644 index 2c66110792..0000000000 --- a/changelogs/fragments/6158-create-proxmox-vm-from-archive.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - "proxmox_kvm - add new ``archive`` parameter. This is needed to create a VM from an archive (backup) (https://github.com/ansible-collections/community.general/pull/6159)." diff --git a/changelogs/fragments/6160-add-command-make-output.yml b/changelogs/fragments/6160-add-command-make-output.yml deleted file mode 100644 index cf43107919..0000000000 --- a/changelogs/fragments/6160-add-command-make-output.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - make - add ``command`` return value to the module output (https://github.com/ansible-collections/community.general/pull/6160). diff --git a/changelogs/fragments/6165-nmap-port.yml b/changelogs/fragments/6165-nmap-port.yml deleted file mode 100644 index 4daf2790ba..0000000000 --- a/changelogs/fragments/6165-nmap-port.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - nmap inventory plugin - add new option ``port`` for port specific scan (https://github.com/ansible-collections/community.general/pull/6165). \ No newline at end of file diff --git a/changelogs/fragments/6171-shutdown-using-systemd.yml b/changelogs/fragments/6171-shutdown-using-systemd.yml deleted file mode 100644 index e5af7c937c..0000000000 --- a/changelogs/fragments/6171-shutdown-using-systemd.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - shutdown - if no shutdown commands are found in the ``search_paths`` then the module will attempt to shutdown the system using ``systemctl shutdown`` (https://github.com/ansible-collections/community.general/issues/4269, https://github.com/ansible-collections/community.general/pull/6171). diff --git a/changelogs/fragments/6180-replace-deprecated-badzipfile.yml b/changelogs/fragments/6180-replace-deprecated-badzipfile.yml deleted file mode 100644 index 7e0916a8d9..0000000000 --- a/changelogs/fragments/6180-replace-deprecated-badzipfile.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "archive - avoid deprecated exception class on Python 3 (https://github.com/ansible-collections/community.general/pull/6180)." diff --git a/changelogs/fragments/6192-allow-empty-resultsets.yml b/changelogs/fragments/6192-allow-empty-resultsets.yml deleted file mode 100644 index 9085d460c8..0000000000 --- a/changelogs/fragments/6192-allow-empty-resultsets.yml +++ /dev/null @@ -1,4 +0,0 @@ -minor_changes: - - mssql_script - handle error condition for empty resultsets to allow for non-returning SQL statements (for example ``UPDATE`` and ``INSERT``) (https://github.com/ansible-collections/community.general/pull/6457). - - mssql_script - allow for ``GO`` statement to be mixed-case for scripts not using strict syntax (https://github.com/ansible-collections/community.general/pull/6457). - - mssql_script - improve batching logic to allow a wider variety of input scripts. For example, SQL scripts slurped from Windows machines which may contain carriage return (''\r'') characters (https://github.com/ansible-collections/community.general/pull/6457). \ No newline at end of file diff --git a/changelogs/fragments/6198-pipx-inject-install-apps.yml b/changelogs/fragments/6198-pipx-inject-install-apps.yml deleted file mode 100644 index 59cf0b94fc..0000000000 --- a/changelogs/fragments/6198-pipx-inject-install-apps.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - pipx - optional ``install_apps`` parameter added to install applications from injected packages (https://github.com/ansible-collections/community.general/pull/6198). diff --git a/changelogs/fragments/6199-archive-generate-checksum-in-chunks.yml b/changelogs/fragments/6199-archive-generate-checksum-in-chunks.yml deleted file mode 100644 index ed0a1e2dca..0000000000 --- a/changelogs/fragments/6199-archive-generate-checksum-in-chunks.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - archive - reduce RAM usage by generating CRC32 checksum over chunks (https://github.com/ansible-collections/community.general/pull/6274). diff --git a/changelogs/fragments/6200-adding-open-option-to-nmap.yml b/changelogs/fragments/6200-adding-open-option-to-nmap.yml deleted file mode 100644 index 876a92394c..0000000000 --- a/changelogs/fragments/6200-adding-open-option-to-nmap.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - nmap inventory plugin - add new option ``open`` for only returning open ports (https://github.com/ansible-collections/community.general/pull/6200). \ No newline at end of file diff --git a/changelogs/fragments/6203-add-append-option-to-ipa-hostgroup.yml b/changelogs/fragments/6203-add-append-option-to-ipa-hostgroup.yml deleted file mode 100644 index 1de6853efc..0000000000 --- a/changelogs/fragments/6203-add-append-option-to-ipa-hostgroup.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ipa_hostgroup - add ``append`` parameter for adding a new hosts to existing hostgroups without changing existing hostgroup members (https://github.com/ansible-collections/community.general/pull/6203). diff --git a/changelogs/fragments/6206-dconf-booleans.yml b/changelogs/fragments/6206-dconf-booleans.yml deleted file mode 100644 index 92c4c930cb..0000000000 --- a/changelogs/fragments/6206-dconf-booleans.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - "dconf - be forgiving about boolean values: convert them to GVariant booleans automatically (https://github.com/ansible-collections/community.general/pull/6206)." diff --git a/changelogs/fragments/6208-hpe-thermal-fan-percent.yaml b/changelogs/fragments/6208-hpe-thermal-fan-percent.yaml deleted file mode 100644 index 61ce97aa03..0000000000 --- a/changelogs/fragments/6208-hpe-thermal-fan-percent.yaml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - redfish_info - adds commands to retrieve the HPE ThermalConfiguration and FanPercentMinimum settings from iLO (https://github.com/ansible-collections/community.general/pull/6208). diff --git a/changelogs/fragments/6210-add-worklog-functionality-to-jira.yml b/changelogs/fragments/6210-add-worklog-functionality-to-jira.yml deleted file mode 100644 index baceedb249..0000000000 --- a/changelogs/fragments/6210-add-worklog-functionality-to-jira.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - jira - add worklog functionality (https://github.com/ansible-collections/community.general/issues/6209, https://github.com/ansible-collections/community.general/pull/6210). diff --git a/changelogs/fragments/6211-rhsm-require-root.yml b/changelogs/fragments/6211-rhsm-require-root.yml deleted file mode 100644 index 4172484513..0000000000 --- a/changelogs/fragments/6211-rhsm-require-root.yml +++ /dev/null @@ -1,6 +0,0 @@ -bugfixes: - - redhat_subscription, rhsm_release, rhsm_repository - cleanly fail when not running as root, - rather than hanging on an interactive ``console-helper`` prompt; they all interact with - ``subscription-manager``, which already requires to be run as root - (https://github.com/ansible-collections/community.general/issues/734, - https://github.com/ansible-collections/community.general/pull/6211). diff --git a/changelogs/fragments/6212-pipx-include-injected.yml b/changelogs/fragments/6212-pipx-include-injected.yml deleted file mode 100644 index cfe85d9326..0000000000 --- a/changelogs/fragments/6212-pipx-include-injected.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - pipx - ensure ``include_injected`` parameter works with ``state=upgrade`` and ``state=latest`` (https://github.com/ansible-collections/community.general/pull/6212). diff --git a/changelogs/fragments/6224-download-certificate-via-api-bugfix.yml b/changelogs/fragments/6224-download-certificate-via-api-bugfix.yml deleted file mode 100644 index 6e377c223c..0000000000 --- a/changelogs/fragments/6224-download-certificate-via-api-bugfix.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - tss lookup plugin - allow to download secret attachments. Previously, we could not download secret attachments but now use ``fetch_attachments`` and ``file_download_path`` variables to download attachments (https://github.com/ansible-collections/community.general/issues/6224). diff --git a/changelogs/fragments/6227-xen-orchestra-check-response-id.yml b/changelogs/fragments/6227-xen-orchestra-check-response-id.yml deleted file mode 100644 index 972caa7d60..0000000000 --- a/changelogs/fragments/6227-xen-orchestra-check-response-id.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - xenorchestra inventory plugin - fix failure to receive objects from server due to not checking the id of the response (https://github.com/ansible-collections/community.general/pull/6227). diff --git a/changelogs/fragments/6259-redhat_subscription-fix-force.yaml b/changelogs/fragments/6259-redhat_subscription-fix-force.yaml deleted file mode 100644 index 1d320cb217..0000000000 --- a/changelogs/fragments/6259-redhat_subscription-fix-force.yaml +++ /dev/null @@ -1,4 +0,0 @@ -bugfixes: - - redhat_subscription - try to unregister only when already registered when ``force_register`` is specified - (https://github.com/ansible-collections/community.general/issues/6258, - https://github.com/ansible-collections/community.general/pull/6259). diff --git a/changelogs/fragments/6267-homebrew-cask-upgrade-all-greedy.yml b/changelogs/fragments/6267-homebrew-cask-upgrade-all-greedy.yml deleted file mode 100644 index c470cf3a7c..0000000000 --- a/changelogs/fragments/6267-homebrew-cask-upgrade-all-greedy.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - homebrew_cask - allows passing ``--greedy`` option to ``upgrade_all`` (https://github.com/ansible-collections/community.general/pull/6267). diff --git a/changelogs/fragments/6269-mksysb-output.yml b/changelogs/fragments/6269-mksysb-output.yml deleted file mode 100644 index 16ba6257cf..0000000000 --- a/changelogs/fragments/6269-mksysb-output.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - mksysb - improved the output of the module in case of errors (https://github.com/ansible-collections/community.general/issues/6263). diff --git a/changelogs/fragments/6270-gconftool2-changed.yml b/changelogs/fragments/6270-gconftool2-changed.yml deleted file mode 100644 index dff6d71748..0000000000 --- a/changelogs/fragments/6270-gconftool2-changed.yml +++ /dev/null @@ -1,5 +0,0 @@ -bugfixes: - - gconftool2 - fix ``changed`` result always being ``true`` (https://github.com/ansible-collections/community.general/issues/6028). - - gconftool2 - remove requirement of parameter ``value`` when ``state=absent`` (https://github.com/ansible-collections/community.general/issues/6028). -breaking_changes: - - gconftool2 - fix processing of ``gconftool-2`` when ``key`` does not exist, returning ``null`` instead of empty string for both ``value`` and ``previous_value`` return values (https://github.com/ansible-collections/community.general/issues/6028). diff --git a/changelogs/fragments/6275-redhat_subscription-fix-environments-centos.yaml b/changelogs/fragments/6275-redhat_subscription-fix-environments-centos.yaml deleted file mode 100644 index e6780dd70a..0000000000 --- a/changelogs/fragments/6275-redhat_subscription-fix-environments-centos.yaml +++ /dev/null @@ -1,4 +0,0 @@ -bugfixes: - - redhat_subscription - use the right D-Bus options for environments when registering - a CentOS Stream 8 system and using ``environment`` - (https://github.com/ansible-collections/community.general/pull/6275). diff --git a/changelogs/fragments/6277-add-topics-gitlab-project.yml b/changelogs/fragments/6277-add-topics-gitlab-project.yml deleted file mode 100644 index 2e3ead05a0..0000000000 --- a/changelogs/fragments/6277-add-topics-gitlab-project.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - gitlab_project - add new option ``topics`` for adding topics to GitLab projects (https://github.com/ansible-collections/community.general/pull/6278). diff --git a/changelogs/fragments/6286-icinga2_host-template-and-template-vars.yml b/changelogs/fragments/6286-icinga2_host-template-and-template-vars.yml deleted file mode 100644 index 7ddeea37f7..0000000000 --- a/changelogs/fragments/6286-icinga2_host-template-and-template-vars.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "icinga2_host - fix the data structure sent to Icinga to make use of host templates and template vars (https://github.com/ansible-collections/community.general/pull/6286)." diff --git a/changelogs/fragments/6289-bugfix-flatpak-check-if-already-installed.yml b/changelogs/fragments/6289-bugfix-flatpak-check-if-already-installed.yml deleted file mode 100644 index e331250035..0000000000 --- a/changelogs/fragments/6289-bugfix-flatpak-check-if-already-installed.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - flatpak - fixes idempotency detection issues. In some cases the module could fail to properly detect already existing Flatpaks because of a parameter witch only checks the installed apps (https://github.com/ansible-collections/community.general/pull/6289). diff --git a/changelogs/fragments/6293-add-puppet-skip-tags-option.yaml b/changelogs/fragments/6293-add-puppet-skip-tags-option.yaml deleted file mode 100644 index fbf1dca599..0000000000 --- a/changelogs/fragments/6293-add-puppet-skip-tags-option.yaml +++ /dev/null @@ -1,3 +0,0 @@ -minor_changes: - - puppet - add new options ``skip_tags`` to exclude certain tagged resources during a puppet agent or apply (https://github.com/ansible-collections/community.general/pull/6293). - diff --git a/changelogs/fragments/6294-fix-one_vm-instantiation.yml b/changelogs/fragments/6294-fix-one_vm-instantiation.yml deleted file mode 100644 index 493ef1c10f..0000000000 --- a/changelogs/fragments/6294-fix-one_vm-instantiation.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - one_vm - fix syntax error when creating VMs with a more complex template (https://github.com/ansible-collections/community.general/issues/6225). diff --git a/changelogs/fragments/6296-LanceNero-Terraform_statefile_check.yml b/changelogs/fragments/6296-LanceNero-Terraform_statefile_check.yml deleted file mode 100644 index f55129db82..0000000000 --- a/changelogs/fragments/6296-LanceNero-Terraform_statefile_check.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - terraform - remove state file check condition and error block, because in the native implementation of terraform will not cause errors due to the non-existent file (https://github.com/ansible-collections/community.general/pull/6296). diff --git a/changelogs/fragments/6300-rundeck-modules-fixes-and-improvements.yml b/changelogs/fragments/6300-rundeck-modules-fixes-and-improvements.yml deleted file mode 100644 index 3f6f3957bc..0000000000 --- a/changelogs/fragments/6300-rundeck-modules-fixes-and-improvements.yml +++ /dev/null @@ -1,8 +0,0 @@ -bugfixes: - - rundeck_acl_policy - fix ``TypeError - byte indices must be integers or slices, not str`` error caused by empty API response. Update the module to use ``module_utils.rundeck`` functions - (https://github.com/ansible-collections/community.general/pull/5887, - https://github.com/ansible-collections/community.general/pull/6300). - - rundeck_project - update the module to use ``module_utils.rundeck`` functions - (https://github.com/ansible-collections/community.general/issues/5742) - (https://github.com/ansible-collections/community.general/pull/6300) - - rundeck module utils - fix errors caused by the API empty responses (https://github.com/ansible-collections/community.general/pull/6300) diff --git a/changelogs/fragments/6303-pipx-fix-state-latest-and-add-system-site-packages.yml b/changelogs/fragments/6303-pipx-fix-state-latest-and-add-system-site-packages.yml deleted file mode 100644 index 1600c8252c..0000000000 --- a/changelogs/fragments/6303-pipx-fix-state-latest-and-add-system-site-packages.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - pipx - fixed handling of ``install_deps=true`` with ``state=latest`` and ``state=upgrade`` (https://github.com/ansible-collections/community.general/pull/6303). diff --git a/changelogs/fragments/6308-pipx-add-system-site-packages.yml b/changelogs/fragments/6308-pipx-add-system-site-packages.yml deleted file mode 100644 index 7660ec5f1a..0000000000 --- a/changelogs/fragments/6308-pipx-add-system-site-packages.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - pipx - add ``system_site_packages`` parameter to give application access to system-wide packages (https://github.com/ansible-collections/community.general/pull/6308). diff --git a/changelogs/fragments/6312-nmcli-add-macvlan-connection-type.yml b/changelogs/fragments/6312-nmcli-add-macvlan-connection-type.yml deleted file mode 100644 index 65f2021f3c..0000000000 --- a/changelogs/fragments/6312-nmcli-add-macvlan-connection-type.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - nmcli - add ``macvlan`` connection type (https://github.com/ansible-collections/community.general/pull/6312). diff --git a/changelogs/fragments/6318-add-form-flow.yml b/changelogs/fragments/6318-add-form-flow.yml deleted file mode 100644 index db567f4faf..0000000000 --- a/changelogs/fragments/6318-add-form-flow.yml +++ /dev/null @@ -1,5 +0,0 @@ -bugfixes: - - "keycloak - improve error messages (https://github.com/ansible-collections/community.general/pull/6318)." - -minor_changes: - - "keycloak_authentication - add flow type option to sub flows to allow the creation of 'form-flow' sub flows like in Keycloak's built-in registration flow (https://github.com/ansible-collections/community.general/pull/6318)." diff --git a/changelogs/fragments/6319-redhat_subscription-fix-environment-parameter.yaml b/changelogs/fragments/6319-redhat_subscription-fix-environment-parameter.yaml deleted file mode 100644 index 672d8dc03e..0000000000 --- a/changelogs/fragments/6319-redhat_subscription-fix-environment-parameter.yaml +++ /dev/null @@ -1,5 +0,0 @@ -bugfixes: - - redhat_subscription - do not use D-Bus for registering when ``environment`` is specified, - so it possible to specify again the environment names for registering, - as the D-Bus APIs work only with IDs - (https://github.com/ansible-collections/community.general/pull/6319). diff --git a/changelogs/fragments/6334-dig-support-multiple-domains.yml b/changelogs/fragments/6334-dig-support-multiple-domains.yml deleted file mode 100644 index db9b5222b6..0000000000 --- a/changelogs/fragments/6334-dig-support-multiple-domains.yml +++ /dev/null @@ -1,3 +0,0 @@ -minor_changes: - - dig lookup plugin - Support multiple domains to be queried as indicated in docs - (https://github.com/ansible-collections/community.general/pull/6334). diff --git a/changelogs/fragments/6336-dconf-refactor.yml b/changelogs/fragments/6336-dconf-refactor.yml deleted file mode 100644 index 3e7ddfccd6..0000000000 --- a/changelogs/fragments/6336-dconf-refactor.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - dconf - minor refactoring improving parameters and dependencies validation (https://github.com/ansible-collections/community.general/pull/6336). diff --git a/changelogs/fragments/6351-support-env-variables-to-nmap-dynamic-inventoiry.yaml b/changelogs/fragments/6351-support-env-variables-to-nmap-dynamic-inventoiry.yaml deleted file mode 100644 index 043f725387..0000000000 --- a/changelogs/fragments/6351-support-env-variables-to-nmap-dynamic-inventoiry.yaml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - nmap inventory plugin - added environment variables for configure ``address`` and ``exclude`` (https://github.com/ansible-collections/community.general/issues/6351). diff --git a/changelogs/fragments/6361-snap-alias-regex-bugfix.yml b/changelogs/fragments/6361-snap-alias-regex-bugfix.yml deleted file mode 100644 index 712ef1893d..0000000000 --- a/changelogs/fragments/6361-snap-alias-regex-bugfix.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - snap_alias - module would only recognize snap names containing letter, numbers or the underscore character, failing to identify valid snap names such as ``lxd.lxc`` (https://github.com/ansible-collections/community.general/pull/6361). diff --git a/changelogs/fragments/6382-udm-dns-record-refactor.yml b/changelogs/fragments/6382-udm-dns-record-refactor.yml deleted file mode 100644 index 78a18e0714..0000000000 --- a/changelogs/fragments/6382-udm-dns-record-refactor.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - udm_dns_record - minor refactor to the code (https://github.com/ansible-collections/community.general/pull/6382). diff --git a/changelogs/fragments/6383-deps-failed.yml b/changelogs/fragments/6383-deps-failed.yml deleted file mode 100644 index bcd35a7207..0000000000 --- a/changelogs/fragments/6383-deps-failed.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - deps module utils - add function ``failed()`` providing the ability to check the dependency check result without triggering an exception (https://github.com/ansible-collections/community.general/pull/6383). diff --git a/changelogs/fragments/6384-gitlab-refactor.yml b/changelogs/fragments/6384-gitlab-refactor.yml deleted file mode 100644 index fbc56ea691..0000000000 --- a/changelogs/fragments/6384-gitlab-refactor.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - gitlab_group_variable, gitlab_project_variable - refactor function out to module utils (https://github.com/ansible-collections/community.general/pull/6384). diff --git a/changelogs/fragments/6385-cpan-mh-feat.yml b/changelogs/fragments/6385-cpan-mh-feat.yml deleted file mode 100644 index 41944b60f8..0000000000 --- a/changelogs/fragments/6385-cpan-mh-feat.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - cpanm - minor change, use feature from ``ModuleHelper`` (https://github.com/ansible-collections/community.general/pull/6385). diff --git a/changelogs/fragments/6401-rhsm_release-required.yml b/changelogs/fragments/6401-rhsm_release-required.yml deleted file mode 100644 index bf47fa8237..0000000000 --- a/changelogs/fragments/6401-rhsm_release-required.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "rhsm_release - make ``release`` parameter not required so it is possible to pass ``null`` as a value. This only was possible in the past due to a bug in ansible-core that now has been fixed (https://github.com/ansible-collections/community.general/pull/6401)." diff --git a/changelogs/fragments/6404-ini_file-section.yml b/changelogs/fragments/6404-ini_file-section.yml deleted file mode 100644 index b9e8a10e76..0000000000 --- a/changelogs/fragments/6404-ini_file-section.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "ini_file - make ``section`` parameter not required so it is possible to pass ``null`` as a value. This only was possible in the past due to a bug in ansible-core that now has been fixed (https://github.com/ansible-collections/community.general/pull/6404)." diff --git a/changelogs/fragments/6428-removals.yml b/changelogs/fragments/6428-removals.yml deleted file mode 100644 index 5aa4d3b0f0..0000000000 --- a/changelogs/fragments/6428-removals.yml +++ /dev/null @@ -1,8 +0,0 @@ -breaking_changes: - - "gitlab_runner - the default of ``access_level_on_creation`` changed from ``false`` to ``true`` (https://github.com/ansible-collections/community.general/pull/6428)." - - "nmcli - the default of the ``hairpin`` option changed from ``true`` to ``false`` (https://github.com/ansible-collections/community.general/pull/6428)." - - "proxmox - the default of the ``unprivileged`` option changed from ``false`` to ``true`` (https://github.com/ansible-collections/community.general/pull/6428)." -removed_features: - - "newrelic_deployment - the ``appname`` and ``environment`` options have been removed. They did not do anything (https://github.com/ansible-collections/community.general/pull/6428)." - - "puppet - the alias ``show-diff`` of the ``show_diff`` option has been removed. Use ``show_diff`` instead (https://github.com/ansible-collections/community.general/pull/6428)." - - "cmd_runner module utils - the ``fmt`` alias of ``cmd_runner_fmt`` has been removed. Use ``cmd_runner_fmt`` instead (https://github.com/ansible-collections/community.general/pull/6428)." diff --git a/changelogs/fragments/6440-dnsimple-info-refactor.yml b/changelogs/fragments/6440-dnsimple-info-refactor.yml deleted file mode 100644 index f94b3de440..0000000000 --- a/changelogs/fragments/6440-dnsimple-info-refactor.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - dnsimple_info - minor refactor in the code (https://github.com/ansible-collections/community.general/pull/6440). diff --git a/changelogs/fragments/6441-snap_alias-refactor.yml b/changelogs/fragments/6441-snap_alias-refactor.yml deleted file mode 100644 index 34b30044d3..0000000000 --- a/changelogs/fragments/6441-snap_alias-refactor.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - snap_alias - refactor code to module utils (https://github.com/ansible-collections/community.general/pull/6441). diff --git a/changelogs/fragments/6448-proxmox-kvm-migration-support.yml b/changelogs/fragments/6448-proxmox-kvm-migration-support.yml deleted file mode 100644 index b613d3b362..0000000000 --- a/changelogs/fragments/6448-proxmox-kvm-migration-support.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - proxmox_kvm - adds ``migrate`` parameter to manage online migrations between hosts (https://github.com/ansible-collections/community.general/pull/6448) diff --git a/changelogs/fragments/6456-fix-portage-withbdeps-false.yml b/changelogs/fragments/6456-fix-portage-withbdeps-false.yml deleted file mode 100644 index 5227d3ff19..0000000000 --- a/changelogs/fragments/6456-fix-portage-withbdeps-false.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "portage - update the logic for generating the emerge command arguments to ensure that ``withbdeps: false`` results in a passing an ``n`` argument with the ``--with-bdeps`` emerge flag (https://github.com/ansible-collections/community.general/issues/6451, https://github.com/ansible-collections/community.general/pull/6456)." diff --git a/changelogs/fragments/6458-puppet-noop.yml b/changelogs/fragments/6458-puppet-noop.yml deleted file mode 100644 index 85e65aca40..0000000000 --- a/changelogs/fragments/6458-puppet-noop.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - puppet - handling ``noop`` parameter was not working at all, now it is has been fixed (https://github.com/ansible-collections/community.general/issues/6452, https://github.com/ansible-collections/community.general/issues/6458). diff --git a/changelogs/fragments/6464-mh-imports.yml b/changelogs/fragments/6464-mh-imports.yml deleted file mode 100644 index 7651dca1da..0000000000 --- a/changelogs/fragments/6464-mh-imports.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - module_helper module utils - updated the imports to make more MH features available at ``plugins/module_utils/module_helper.py`` (https://github.com/ansible-collections/community.general/pull/6464). diff --git a/changelogs/fragments/6465-mh-deps-deprecation.yml b/changelogs/fragments/6465-mh-deps-deprecation.yml deleted file mode 100644 index 2115f8207a..0000000000 --- a/changelogs/fragments/6465-mh-deps-deprecation.yml +++ /dev/null @@ -1,2 +0,0 @@ -deprecated_features: - - ModuleHelper module_utils - ``deps`` mixin for MH classes deprecated in favour of using the ``deps`` module_utils (https://github.com/ansible-collections/community.general/pull/6465). diff --git a/changelogs/fragments/6468-snap-cmdrunner.yml b/changelogs/fragments/6468-snap-cmdrunner.yml deleted file mode 100644 index e5247ffbd0..0000000000 --- a/changelogs/fragments/6468-snap-cmdrunner.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - snap - refactor module to use ``CmdRunner`` to execute external commands (https://github.com/ansible-collections/community.general/pull/6468). diff --git a/changelogs/fragments/6473-ldap_search.yml b/changelogs/fragments/6473-ldap_search.yml deleted file mode 100644 index e58e062bb9..0000000000 --- a/changelogs/fragments/6473-ldap_search.yml +++ /dev/null @@ -1,4 +0,0 @@ -breaking_changes: - - "ldap_search - convert all string-like values to UTF-8 (https://github.com/ansible-collections/community.general/issues/5704, https://github.com/ansible-collections/community.general/pull/6473)." -minor_changes: - - "ldap_search - the new ``base64_attributes`` allows to specify which attribute values should be Base64 encoded (https://github.com/ansible-collections/community.general/pull/6473)." diff --git a/changelogs/fragments/6491-dconf-respawn.yml b/changelogs/fragments/6491-dconf-respawn.yml deleted file mode 100644 index 54eec9fa1a..0000000000 --- a/changelogs/fragments/6491-dconf-respawn.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - dconf - if ``gi.repository.GLib`` is missing, try to respawn in a Python interpreter that has it (https://github.com/ansible-collections/community.general/pull/6491). diff --git a/changelogs/fragments/6493-deprecate-rhn-modules.yml b/changelogs/fragments/6493-deprecate-rhn-modules.yml deleted file mode 100644 index 5f328707da..0000000000 --- a/changelogs/fragments/6493-deprecate-rhn-modules.yml +++ /dev/null @@ -1,10 +0,0 @@ -deprecated_features: - - | - rhn_channel, rhn_register - RHN hosted at redhat.com was discontinued years - ago, and Spacewalk 5 (which uses RHN) is EOL since 2020, May 31st; - while these modules could work on Uyuni / SUSE Manager (fork of Spacewalk 5), - we have not heard about anyone using them in those setups. Hence, these - modules are deprecated, and will be removed in community.general 10.0.0 - in case there are no reports about being still useful, and potentially - noone that steps up to maintain them - (https://github.com/ansible-collections/community.general/pull/6493). diff --git a/changelogs/fragments/6497-terraform-fix.yml b/changelogs/fragments/6497-terraform-fix.yml deleted file mode 100644 index 8b5119722c..0000000000 --- a/changelogs/fragments/6497-terraform-fix.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "terraform - fix broken ``warn()`` call (https://github.com/ansible-collections/community.general/pull/6497)." diff --git a/changelogs/fragments/deps.yml b/changelogs/fragments/deps.yml deleted file mode 100644 index 2ad1b7e2c3..0000000000 --- a/changelogs/fragments/deps.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "deps module utils - do not fail when dependency cannot be found (https://github.com/ansible-collections/community.general/pull/6479)." diff --git a/changelogs/fragments/passwordstore-lock.yml b/changelogs/fragments/passwordstore-lock.yml deleted file mode 100644 index 0d1f3cc9c3..0000000000 --- a/changelogs/fragments/passwordstore-lock.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "passwordstore lookup plugin - make compatible with ansible-core 2.16 (https://github.com/ansible-collections/community.general/pull/6447)." diff --git a/changelogs/fragments/remove-unneeded-imports.yml b/changelogs/fragments/remove-unneeded-imports.yml deleted file mode 100644 index a5fed1d93e..0000000000 --- a/changelogs/fragments/remove-unneeded-imports.yml +++ /dev/null @@ -1,2 +0,0 @@ -bugfixes: - - "various plugins and modules - remove unnecessary imports (https://github.com/ansible-collections/community.general/pull/5940)." diff --git a/changelogs/fragments/xxxx-ldap-ca-cert-file.yml b/changelogs/fragments/xxxx-ldap-ca-cert-file.yml deleted file mode 100644 index 9730e08271..0000000000 --- a/changelogs/fragments/xxxx-ldap-ca-cert-file.yml +++ /dev/null @@ -1,2 +0,0 @@ -minor_changes: - - ldap modules - add ``ca_path`` option (https://github.com/ansible-collections/community.general/pull/6185). diff --git a/galaxy.yml b/galaxy.yml index 8d70635445..5a0a5c9dd0 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -5,7 +5,7 @@ namespace: community name: general -version: 7.0.0 +version: 7.1.0 readme: README.md authors: - Ansible (https://github.com/ansible) From ddca52ee15715c3460868be283cebd258a138c20 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Fri, 19 May 2023 20:25:04 +0200 Subject: [PATCH 0002/1451] CI: include has finally been removed in ansible-core devel (#6535) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit include: → include_tasks:. --- .../targets/apache2_module/tasks/main.yml | 4 ++-- .../integration/targets/influxdb_user/tasks/main.yml | 2 +- tests/integration/targets/locale_gen/tasks/main.yml | 2 +- tests/integration/targets/mqtt/tasks/main.yml | 2 +- tests/integration/targets/pacman/tasks/main.yml | 12 ++++++------ tests/integration/targets/pkgng/tasks/freebsd.yml | 2 +- tests/integration/targets/sefcontext/tasks/main.yml | 2 +- .../integration/targets/sensu_handler/tasks/main.yml | 10 +++++----- .../targets/setup_influxdb/tasks/main.yml | 2 +- .../targets/setup_mosquitto/tasks/main.yml | 2 +- .../integration/targets/setup_pkg_mgr/tasks/main.yml | 2 +- tests/integration/targets/ssh_config/tasks/main.yml | 2 +- tests/integration/targets/sysrc/tasks/main.yml | 2 +- tests/integration/targets/xattr/tasks/main.yml | 4 ++-- tests/integration/targets/yarn/tasks/main.yml | 2 +- tests/integration/targets/zypper/tasks/main.yml | 2 +- .../targets/zypper_repository/tasks/main.yml | 2 +- .../targets/zypper_repository/tasks/test.yml | 2 +- 18 files changed, 29 insertions(+), 29 deletions(-) diff --git a/tests/integration/targets/apache2_module/tasks/main.yml b/tests/integration/targets/apache2_module/tasks/main.yml index 70ba14ea24..6f2f718ad0 100644 --- a/tests/integration/targets/apache2_module/tasks/main.yml +++ b/tests/integration/targets/apache2_module/tasks/main.yml @@ -29,7 +29,7 @@ shell: apache2ctl -M | sort register: modules_before - name: include only on supported systems - include: actualtest.yml + include_tasks: actualtest.yml always: - name: get list of enabled modules shell: apache2ctl -M | sort @@ -47,6 +47,6 @@ # centos/RHEL does not have a2enmod/a2dismod - name: include misleading warning test - include: 635-apache2-misleading-warning.yml + include_tasks: 635-apache2-misleading-warning.yml when: ansible_os_family in ['Debian'] # Suse has mpm_event module compiled within the base apache2 \ No newline at end of file diff --git a/tests/integration/targets/influxdb_user/tasks/main.yml b/tests/integration/targets/influxdb_user/tasks/main.yml index 23c37b7960..7da2f85e5f 100644 --- a/tests/integration/targets/influxdb_user/tasks/main.yml +++ b/tests/integration/targets/influxdb_user/tasks/main.yml @@ -8,5 +8,5 @@ # 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 -- include: tests.yml +- include_tasks: tests.yml when: ansible_distribution == 'Ubuntu' and ansible_distribution_release == 'trusty' diff --git a/tests/integration/targets/locale_gen/tasks/main.yml b/tests/integration/targets/locale_gen/tasks/main.yml index 1616f8fc32..de3e673beb 100644 --- a/tests/integration/targets/locale_gen/tasks/main.yml +++ b/tests/integration/targets/locale_gen/tasks/main.yml @@ -8,5 +8,5 @@ # 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 -- include: 'locale_gen.yml' +- include_tasks: 'locale_gen.yml' when: ansible_distribution in ('Ubuntu', 'Debian') diff --git a/tests/integration/targets/mqtt/tasks/main.yml b/tests/integration/targets/mqtt/tasks/main.yml index 6403b20181..0beb1b3b27 100644 --- a/tests/integration/targets/mqtt/tasks/main.yml +++ b/tests/integration/targets/mqtt/tasks/main.yml @@ -8,7 +8,7 @@ # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) # SPDX-License-Identifier: GPL-3.0-or-later -- include: ubuntu.yml +- include_tasks: ubuntu.yml when: - ansible_distribution == 'Ubuntu' - ansible_distribution_release not in ['focal', 'jammy'] diff --git a/tests/integration/targets/pacman/tasks/main.yml b/tests/integration/targets/pacman/tasks/main.yml index 95f4374b75..12d28a2d3e 100644 --- a/tests/integration/targets/pacman/tasks/main.yml +++ b/tests/integration/targets/pacman/tasks/main.yml @@ -11,9 +11,9 @@ - when: ansible_os_family == 'Archlinux' block: # Add more tests here by including more task files: - - include: 'basic.yml' - - include: 'package_urls.yml' - - include: 'remove_nosave.yml' - - include: 'update_cache.yml' - - include: 'locally_installed_package.yml' - - include: 'reason.yml' + - include_tasks: 'basic.yml' + - include_tasks: 'package_urls.yml' + - include_tasks: 'remove_nosave.yml' + - include_tasks: 'update_cache.yml' + - include_tasks: 'locally_installed_package.yml' + - include_tasks: 'reason.yml' diff --git a/tests/integration/targets/pkgng/tasks/freebsd.yml b/tests/integration/targets/pkgng/tasks/freebsd.yml index bac5f62942..0c8001899f 100644 --- a/tests/integration/targets/pkgng/tasks/freebsd.yml +++ b/tests/integration/targets/pkgng/tasks/freebsd.yml @@ -522,7 +522,7 @@ or ansible_distribution_version is version('13.3', '>=') block: - name: Setup testjail - include: setup-testjail.yml + include_tasks: setup-testjail.yml - name: Install package in jail as rootdir include_tasks: install_single_package.yml diff --git a/tests/integration/targets/sefcontext/tasks/main.yml b/tests/integration/targets/sefcontext/tasks/main.yml index 8eeac62fb5..04143d1cbc 100644 --- a/tests/integration/targets/sefcontext/tasks/main.yml +++ b/tests/integration/targets/sefcontext/tasks/main.yml @@ -17,5 +17,5 @@ msg: SELinux is {{ ansible_selinux.status }} when: ansible_selinux is defined and ansible_selinux != False -- include: sefcontext.yml +- include_tasks: sefcontext.yml when: ansible_selinux is defined and ansible_selinux != False and ansible_selinux.status == 'enabled' diff --git a/tests/integration/targets/sensu_handler/tasks/main.yml b/tests/integration/targets/sensu_handler/tasks/main.yml index 606be6b789..ec73a14c44 100644 --- a/tests/integration/targets/sensu_handler/tasks/main.yml +++ b/tests/integration/targets/sensu_handler/tasks/main.yml @@ -122,8 +122,8 @@ - failure is failed - "'the following are missing: type' in failure['msg']" -- include: pipe.yml -- include: tcp.yml -- include: udp.yml -- include: set.yml -- include: transport.yml +- include_tasks: pipe.yml +- include_tasks: tcp.yml +- include_tasks: udp.yml +- include_tasks: set.yml +- include_tasks: transport.yml diff --git a/tests/integration/targets/setup_influxdb/tasks/main.yml b/tests/integration/targets/setup_influxdb/tasks/main.yml index 939a49da73..bc64ab319d 100644 --- a/tests/integration/targets/setup_influxdb/tasks/main.yml +++ b/tests/integration/targets/setup_influxdb/tasks/main.yml @@ -8,5 +8,5 @@ # 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 -- include: setup.yml +- include_tasks: setup.yml when: ansible_distribution == 'Ubuntu' and ansible_distribution_release == 'trusty' diff --git a/tests/integration/targets/setup_mosquitto/tasks/main.yml b/tests/integration/targets/setup_mosquitto/tasks/main.yml index 836d94529e..2dd0674dc2 100644 --- a/tests/integration/targets/setup_mosquitto/tasks/main.yml +++ b/tests/integration/targets/setup_mosquitto/tasks/main.yml @@ -8,5 +8,5 @@ # 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 -- include: ubuntu.yml +- include_tasks: ubuntu.yml when: ansible_distribution == 'Ubuntu' diff --git a/tests/integration/targets/setup_pkg_mgr/tasks/main.yml b/tests/integration/targets/setup_pkg_mgr/tasks/main.yml index 7c6ab4ef9f..5bff53b3b1 100644 --- a/tests/integration/targets/setup_pkg_mgr/tasks/main.yml +++ b/tests/integration/targets/setup_pkg_mgr/tasks/main.yml @@ -36,4 +36,4 @@ - when: ansible_os_family == "Archlinux" block: - name: ArchLinux specific setup - include: archlinux.yml + include_tasks: archlinux.yml diff --git a/tests/integration/targets/ssh_config/tasks/main.yml b/tests/integration/targets/ssh_config/tasks/main.yml index 290639e83e..c8b96d0c09 100644 --- a/tests/integration/targets/ssh_config/tasks/main.yml +++ b/tests/integration/targets/ssh_config/tasks/main.yml @@ -242,4 +242,4 @@ - short_name.hosts_removed == [] - name: Include integration tests for additional options (e.g. proxycommand, proxyjump) - include: 'options.yml' + include_tasks: 'options.yml' diff --git a/tests/integration/targets/sysrc/tasks/main.yml b/tests/integration/targets/sysrc/tasks/main.yml index 83e7fe9ed0..2c45c3b1c2 100644 --- a/tests/integration/targets/sysrc/tasks/main.yml +++ b/tests/integration/targets/sysrc/tasks/main.yml @@ -147,7 +147,7 @@ or ansible_distribution_version is version('13.1', '>=') block: - name: Setup testjail - include: setup-testjail.yml + include_tasks: setup-testjail.yml - name: Enable nginx in test jail sysrc: diff --git a/tests/integration/targets/xattr/tasks/main.yml b/tests/integration/targets/xattr/tasks/main.yml index b6e93d92bc..6c1c02b3e9 100644 --- a/tests/integration/targets/xattr/tasks/main.yml +++ b/tests/integration/targets/xattr/tasks/main.yml @@ -9,7 +9,7 @@ # SPDX-License-Identifier: GPL-3.0-or-later - name: Setup - include: setup.yml + include_tasks: setup.yml - name: Check availability of xattr support command: setfattr -n user.foo {{ test_file }} @@ -17,5 +17,5 @@ register: xattr - name: Test - include: test.yml + include_tasks: test.yml when: xattr is not failed diff --git a/tests/integration/targets/yarn/tasks/main.yml b/tests/integration/targets/yarn/tasks/main.yml index e8f4d0e6a2..e12d891c29 100644 --- a/tests/integration/targets/yarn/tasks/main.yml +++ b/tests/integration/targets/yarn/tasks/main.yml @@ -11,7 +11,7 @@ # ============================================================ -- include: run.yml +- include_tasks: run.yml vars: nodejs_version: '{{ item.node_version }}' nodejs_path: 'node-v{{ nodejs_version }}-{{ ansible_system|lower }}-x{{ ansible_userspace_bits }}' diff --git a/tests/integration/targets/zypper/tasks/main.yml b/tests/integration/targets/zypper/tasks/main.yml index e12c64839d..185f2f90ab 100644 --- a/tests/integration/targets/zypper/tasks/main.yml +++ b/tests/integration/targets/zypper/tasks/main.yml @@ -11,5 +11,5 @@ # 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 -- include: 'zypper.yml' +- include_tasks: 'zypper.yml' when: ansible_os_family == 'Suse' diff --git a/tests/integration/targets/zypper_repository/tasks/main.yml b/tests/integration/targets/zypper_repository/tasks/main.yml index 67fd4dde35..1d655a56fc 100644 --- a/tests/integration/targets/zypper_repository/tasks/main.yml +++ b/tests/integration/targets/zypper_repository/tasks/main.yml @@ -9,5 +9,5 @@ # 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 -- include: 'test.yml' +- include_tasks: 'test.yml' when: ansible_os_family == 'Suse' diff --git a/tests/integration/targets/zypper_repository/tasks/test.yml b/tests/integration/targets/zypper_repository/tasks/test.yml index 2f030daf48..739b4c2642 100644 --- a/tests/integration/targets/zypper_repository/tasks/test.yml +++ b/tests/integration/targets/zypper_repository/tasks/test.yml @@ -11,7 +11,7 @@ command: zypper -n ref - block: - - include: 'zypper_repository.yml' + - include_tasks: 'zypper_repository.yml' always: - name: remove repositories added during test community.general.zypper_repository: From dca7fd45528ade60c572df8aa38a3b409c29df35 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 20 May 2023 13:05:44 +0200 Subject: [PATCH 0003/1451] Enable using semantic markup (#6539) Enable using semantic markup. --- changelogs/fragments/6539-semantic-markup.yml | 7 +++++++ tests/sanity/extra/extra-docs.py | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/6539-semantic-markup.yml diff --git a/changelogs/fragments/6539-semantic-markup.yml b/changelogs/fragments/6539-semantic-markup.yml new file mode 100644 index 0000000000..9619cd3bee --- /dev/null +++ b/changelogs/fragments/6539-semantic-markup.yml @@ -0,0 +1,7 @@ +--- +minor_changes: + - "The collection will start using semantic markup (https://github.com/ansible-collections/community.general/pull/6539)." +known_issues: + - "Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the + documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on + https://docs.ansible.com/ansible/devel/collections/community/general/ (https://github.com/ansible-collections/community.general/pull/6539)." diff --git a/tests/sanity/extra/extra-docs.py b/tests/sanity/extra/extra-docs.py index c636beb08e..251e6d70f5 100755 --- a/tests/sanity/extra/extra-docs.py +++ b/tests/sanity/extra/extra-docs.py @@ -17,7 +17,7 @@ def main(): suffix = ':{env}'.format(env=env["ANSIBLE_COLLECTIONS_PATH"]) if 'ANSIBLE_COLLECTIONS_PATH' in env else '' env['ANSIBLE_COLLECTIONS_PATH'] = '{root}{suffix}'.format(root=os.path.dirname(os.path.dirname(os.path.dirname(os.getcwd()))), suffix=suffix) p = subprocess.run( - ['antsibull-docs', 'lint-collection-docs', '--plugin-docs', '--disallow-semantic-markup', '--skip-rstcheck', '.'], + ['antsibull-docs', 'lint-collection-docs', '--plugin-docs', '--skip-rstcheck', '.'], env=env, check=False, ) From 08377df7a5801b26fce498681180a23a2fdaeda3 Mon Sep 17 00:00:00 2001 From: Tamerlan Bimzhanov Date: Sat, 20 May 2023 18:33:00 +0600 Subject: [PATCH 0004/1451] Fix code formatting in documentation of dconf.py (#6538) * Fix code formatting in documentation of dconf.py * Update plugins/modules/dconf.py Co-authored-by: Felix Fontein * Update plugins/modules/dconf.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- plugins/modules/dconf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/modules/dconf.py b/plugins/modules/dconf.py index aefc716005..8c325486cc 100644 --- a/plugins/modules/dconf.py +++ b/plugins/modules/dconf.py @@ -49,8 +49,8 @@ notes: I(value="'myvalue'") - with single quotes as part of the Ansible parameter value. - When using loops in combination with a value like - :code:`"[('xkb', 'us'), ('xkb', 'se')]"`, you need to be aware of possible - type conversions. Applying a filter :code:`"{{ item.value | string }}"` + "[('xkb', 'us'), ('xkb', 'se')]", you need to be aware of possible + type conversions. Applying a filter C({{ item.value | string }}) to the parameter variable can avoid potential conversion problems. - The easiest way to figure out exact syntax/value you need to provide for a key is by making the configuration change in application affected by the From d643bd5794b98f579c4a90fa2cc02ab872edd0e4 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 21 May 2023 14:06:36 +0200 Subject: [PATCH 0005/1451] Switch to Ansible Galaxy compatible requirements files for tests (#6549) Switch to Ansible Galaxy compatible requirements files for tests. --- tests/{ => integration}/requirements.yml | 4 +--- tests/unit/requirements.yml | 7 +++++++ 2 files changed, 8 insertions(+), 3 deletions(-) rename tests/{ => integration}/requirements.yml (73%) create mode 100644 tests/unit/requirements.yml diff --git a/tests/requirements.yml b/tests/integration/requirements.yml similarity index 73% rename from tests/requirements.yml rename to tests/integration/requirements.yml index adedb17bda..b772fc82d1 100644 --- a/tests/requirements.yml +++ b/tests/integration/requirements.yml @@ -3,9 +3,7 @@ # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) # SPDX-License-Identifier: GPL-3.0-or-later -integration_tests_dependencies: +collections: - ansible.posix - community.crypto - community.docker -unit_tests_dependencies: -- community.internal_test_tools diff --git a/tests/unit/requirements.yml b/tests/unit/requirements.yml new file mode 100644 index 0000000000..586a6a1b37 --- /dev/null +++ b/tests/unit/requirements.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 + +collections: +- community.internal_test_tools From cb1e6376db322f68a44f3681f6c3c3cdcc78019a Mon Sep 17 00:00:00 2001 From: Sergey Putko Date: Sun, 21 May 2023 18:03:38 +0300 Subject: [PATCH 0006/1451] nmcli: Fix bond option xmit_hash_policy (#6527) * nmcli_bond_xmit_fix * Create 6527-nmcli-bond-fix-xmit_hash_policy.yml add changelog * Update changelogs/fragments/6527-nmcli-bond-fix-xmit_hash_policy.yml Co-authored-by: Felix Fontein * unit tests extend --------- Co-authored-by: Felix Fontein --- .../fragments/6527-nmcli-bond-fix-xmit_hash_policy.yml | 2 ++ plugins/modules/nmcli.py | 3 +++ tests/unit/plugins/modules/test_nmcli.py | 6 ++++-- 3 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/6527-nmcli-bond-fix-xmit_hash_policy.yml diff --git a/changelogs/fragments/6527-nmcli-bond-fix-xmit_hash_policy.yml b/changelogs/fragments/6527-nmcli-bond-fix-xmit_hash_policy.yml new file mode 100644 index 0000000000..5133920b73 --- /dev/null +++ b/changelogs/fragments/6527-nmcli-bond-fix-xmit_hash_policy.yml @@ -0,0 +1,2 @@ +bugfixes: + - nmcli - fix bond option ``xmit_hash_policy`` (https://github.com/ansible-collections/community.general/pull/6527). diff --git a/plugins/modules/nmcli.py b/plugins/modules/nmcli.py index 053182c2c0..af7bea6cb2 100644 --- a/plugins/modules/nmcli.py +++ b/plugins/modules/nmcli.py @@ -2119,6 +2119,9 @@ class Nmcli(object): if key in self.SECRET_OPTIONS: self.edit_commands += ['set %s %s' % (key, value)] continue + if key == 'xmit_hash_policy': + cmd.extend(['+bond.options', 'xmit_hash_policy=%s' % value]) + continue cmd.extend([key, value]) return self.execute_command(cmd) diff --git a/tests/unit/plugins/modules/test_nmcli.py b/tests/unit/plugins/modules/test_nmcli.py index 577d30e97d..ccb6ececcd 100644 --- a/tests/unit/plugins/modules/test_nmcli.py +++ b/tests/unit/plugins/modules/test_nmcli.py @@ -500,6 +500,7 @@ TESTCASE_BOND = [ 'conn_name': 'non_existent_nw_device', 'ifname': 'bond_non_existant', 'mode': 'active-backup', + 'xmit_hash_policy': 'layer3+4', 'ip4': '10.10.10.10/24', 'gw4': '10.10.10.1', 'state': 'present', @@ -522,7 +523,7 @@ ipv4.may-fail: yes ipv6.method: auto ipv6.ignore-auto-dns: no ipv6.ignore-auto-routes: no -bond.options: mode=active-backup,primary=non_existent_primary +bond.options: mode=active-backup,primary=non_existent_primary,xmit_hash_policy=layer3+4 """ TESTCASE_BRIDGE = [ @@ -1897,7 +1898,8 @@ def test_bond_connection_create(mocked_generic_connection_create, capfd): for param in ['ipv4.gateway', 'primary', 'connection.autoconnect', 'connection.interface-name', 'bond_non_existant', - 'mode', 'active-backup', 'ipv4.addresses']: + 'mode', 'active-backup', 'ipv4.addresses', + '+bond.options', 'xmit_hash_policy=layer3+4']: assert param in args[0] out, err = capfd.readouterr() From 5f968fb075cf2a150b5ea98451c54481233d103f Mon Sep 17 00:00:00 2001 From: s-hamann <10639154+s-hamann@users.noreply.github.com> Date: Sun, 21 May 2023 19:36:46 +0000 Subject: [PATCH 0007/1451] portage: fix changed_use and newuse not triggering rebuilds (#6008) (#6548) * portage: fix changed_use and newuse not triggering rebuilds (#6008) * Add changelog fragment * Update changelogs/fragments/6548-portage-changed_use-newuse.yml Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- changelogs/fragments/6548-portage-changed_use-newuse.yml | 3 +++ plugins/modules/portage.py | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/6548-portage-changed_use-newuse.yml diff --git a/changelogs/fragments/6548-portage-changed_use-newuse.yml b/changelogs/fragments/6548-portage-changed_use-newuse.yml new file mode 100644 index 0000000000..0d1ba55e09 --- /dev/null +++ b/changelogs/fragments/6548-portage-changed_use-newuse.yml @@ -0,0 +1,3 @@ +--- +bugfixes: + - portage - fix ``changed_use`` and ``newuse`` not triggering rebuilds (https://github.com/ansible-collections/community.general/issues/6008, https://github.com/ansible-collections/community.general/pull/6548). diff --git a/plugins/modules/portage.py b/plugins/modules/portage.py index c732e7f56f..1c6b365376 100644 --- a/plugins/modules/portage.py +++ b/plugins/modules/portage.py @@ -333,9 +333,9 @@ def emerge_packages(module, packages): """Run emerge command against given list of atoms.""" p = module.params - if p['noreplace'] and not (p['update'] or p['state'] == 'latest'): + if p['noreplace'] and not p['changed_use'] and not p['newuse'] and not (p['update'] or p['state'] == 'latest'): for package in packages: - if p['noreplace'] and not query_package(module, package, 'emerge'): + if p['noreplace'] and not p['changed_use'] and not p['newuse'] and not query_package(module, package, 'emerge'): break else: module.exit_json(changed=False, msg='Packages already present.') From a9fd9f8982a1f2ff7de3939bb885c9a7d8174439 Mon Sep 17 00:00:00 2001 From: tover99 <101673769+tover99@users.noreply.github.com> Date: Mon, 22 May 2023 06:24:53 +0200 Subject: [PATCH 0008/1451] added handling of zypper exitcode 102: ZYPPER_EXIT_INF_REBOOT_NEEDED (#6534) * added handling of zypper exitcode 102: ZYPPER_EXIT_INF_REBOOT_NEEDED - Returned after a successful installation of a patch which requires reboot of computer. The exitcode 102 will be treated exactly like 0 by the module internally now, and the changed status will be reported correctly. However, since I preserve the rc 102 in the retvals to allow the playbook to react to the requested reboot, the task must still include a "failed_when: zypper_cmd.rc not in [0, 102]" to not fail in this case. * removed trailing whitespaces * added changelogs fragment * Fix typo. Co-authored-by: Alex * Add URL. --------- Co-authored-by: Felix Fontein Co-authored-by: Alex --- changelogs/fragments/6534-zypper-exitcode-102-handled.yaml | 2 ++ plugins/modules/zypper.py | 7 ++++--- 2 files changed, 6 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/6534-zypper-exitcode-102-handled.yaml diff --git a/changelogs/fragments/6534-zypper-exitcode-102-handled.yaml b/changelogs/fragments/6534-zypper-exitcode-102-handled.yaml new file mode 100644 index 0000000000..baed17cae5 --- /dev/null +++ b/changelogs/fragments/6534-zypper-exitcode-102-handled.yaml @@ -0,0 +1,2 @@ +bugfixes: + - zypper - added handling of zypper exitcode 102. Changed state is set correctly now and rc 102 is still preserved to be evaluated by the playbook (https://github.com/ansible-collections/community.general/pull/6534). \ No newline at end of file diff --git a/plugins/modules/zypper.py b/plugins/modules/zypper.py index 9ba5555e20..b47131d3d1 100644 --- a/plugins/modules/zypper.py +++ b/plugins/modules/zypper.py @@ -324,10 +324,11 @@ def parse_zypper_xml(m, cmd, fail_not_found=True, packages=None): m.fail_json(msg=errmsg, rc=rc, stdout=stdout, stderr=stderr, cmd=cmd) else: return {}, rc, stdout, stderr - elif rc in [0, 106, 103]: + elif rc in [0, 102, 103, 106]: # zypper exit codes # 0: success # 106: signature verification failed + # 102: ZYPPER_EXIT_INF_REBOOT_NEEDED - Returned after a successful installation of a patch which requires reboot of computer. # 103: zypper was upgraded, run same command again if packages is None: firstrun = True @@ -587,12 +588,12 @@ def main(): elif state in ['installed', 'present', 'latest']: packages_changed, retvals = package_present(module, name, state == 'latest') - retvals['changed'] = retvals['rc'] == 0 and bool(packages_changed) + retvals['changed'] = retvals['rc'] in [0, 102] and bool(packages_changed) if module._diff: set_diff(module, retvals, packages_changed) - if retvals['rc'] != 0: + if retvals['rc'] not in [0, 102]: module.fail_json(msg="Zypper run failed.", **retvals) if not retvals['changed']: From 29790df583ff5b7c6d0487bde57e27e37e9c423f Mon Sep 17 00:00:00 2001 From: Sergei Antipov Date: Mon, 22 May 2023 00:32:26 -0400 Subject: [PATCH 0009/1451] Don't require api_password when api_token_id is used in proxmox_tasks_info (#6554) * Don't require api_password when api_token_id is used in proxmox_tasks_info * Add changelog fragment * Fix casing. --------- Co-authored-by: Felix Fontein --- .../6554-proxmox-tasks-info-fix-required-password.yaml | 3 +++ plugins/modules/proxmox_tasks_info.py | 3 +-- 2 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/6554-proxmox-tasks-info-fix-required-password.yaml diff --git a/changelogs/fragments/6554-proxmox-tasks-info-fix-required-password.yaml b/changelogs/fragments/6554-proxmox-tasks-info-fix-required-password.yaml new file mode 100644 index 0000000000..6edfa475c1 --- /dev/null +++ b/changelogs/fragments/6554-proxmox-tasks-info-fix-required-password.yaml @@ -0,0 +1,3 @@ +--- +bugfixes: + - proxmox_tasks_info - remove ``api_user`` + ``api_password`` constraint from ``required_together`` as it causes to require ``api_password`` even when API token param is used (https://github.com/ansible-collections/community.general/issues/6201). diff --git a/plugins/modules/proxmox_tasks_info.py b/plugins/modules/proxmox_tasks_info.py index 183fb3bf0f..a2e66b38dc 100644 --- a/plugins/modules/proxmox_tasks_info.py +++ b/plugins/modules/proxmox_tasks_info.py @@ -160,8 +160,7 @@ def main(): module = AnsibleModule( argument_spec=module_args, - required_together=[('api_token_id', 'api_token_secret'), - ('api_user', 'api_password')], + required_together=[('api_token_id', 'api_token_secret')], required_one_of=[('api_password', 'api_token_id')], supports_check_mode=True) result = dict(changed=False) From ab046755bb8cc3a59029d3e97725c106d50b56f6 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 29 May 2023 15:27:27 +0200 Subject: [PATCH 0010/1451] CI: restrict to python-nomad < 2.0.0 for Python < 3.7 (#6578) Restrict to python-nomad < 2.0.0 for Python < 3.7. --- tests/utils/constraints.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/utils/constraints.txt b/tests/utils/constraints.txt index 87db256f41..4fb5276e23 100644 --- a/tests/utils/constraints.txt +++ b/tests/utils/constraints.txt @@ -21,6 +21,7 @@ pycrypto >= 2.6 # Need features found in 2.6 and greater ncclient >= 0.5.2 # Need features added in 0.5.2 and greater idna < 2.6, >= 2.5 # linode requires idna < 2.9, >= 2.5, requests requires idna < 2.6, but cryptography will cause the latest version to be installed instead paramiko < 2.4.0 ; python_version < '2.7' # paramiko 2.4.0 drops support for python 2.6 +python-nomad < 2.0.0 ; python_version <= '3.7' # python-nomad 2.0.0 needs Python 3.7+ pytest < 3.3.0 ; python_version < '2.7' # pytest 3.3.0 drops support for python 2.6 pytest < 5.0.0 ; python_version == '2.7' # pytest 5.0.0 and later will no longer support python 2.7 pytest-forked < 1.0.2 ; python_version < '2.7' # pytest-forked 1.0.2 and later require python 2.7 or later From 27fe14bfc12aa5ce312eaaa72383b62a3b781e90 Mon Sep 17 00:00:00 2001 From: Philippe Gauthier Date: Mon, 29 May 2023 09:32:15 -0400 Subject: [PATCH 0011/1451] Fix get_user_by_username in keycloak library (#6568) * Fix get_user_by_username in keycloak library for keycloak_user_rolemapping module * Add changelog fragment for keycloak.py bug fix --- ...-get-user-by-username-in-keycloak-module-utils.yml | 2 ++ plugins/module_utils/identity/keycloak/keycloak.py | 11 +++++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/6568-fix-get-user-by-username-in-keycloak-module-utils.yml diff --git a/changelogs/fragments/6568-fix-get-user-by-username-in-keycloak-module-utils.yml b/changelogs/fragments/6568-fix-get-user-by-username-in-keycloak-module-utils.yml new file mode 100644 index 0000000000..4983c507c5 --- /dev/null +++ b/changelogs/fragments/6568-fix-get-user-by-username-in-keycloak-module-utils.yml @@ -0,0 +1,2 @@ +bugfixes: + - keycloak module utils - the function ``get_user_by_username`` now return the user representation or ``None`` as stated in the documentation (https://github.com/ansible-collections/community.general/pull/6758). diff --git a/plugins/module_utils/identity/keycloak/keycloak.py b/plugins/module_utils/identity/keycloak/keycloak.py index 5443811d0b..c35ca43c2c 100644 --- a/plugins/module_utils/identity/keycloak/keycloak.py +++ b/plugins/module_utils/identity/keycloak/keycloak.py @@ -747,8 +747,15 @@ class KeycloakAPI(object): users_url = URL_USERS.format(url=self.baseurl, realm=realm) users_url += '?username=%s&exact=true' % username try: - return json.loads(to_native(open_url(users_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout, - validate_certs=self.validate_certs).read())) + userrep = None + users = json.loads(to_native(open_url(users_url, method='GET', headers=self.restheaders, timeout=self.connection_timeout, + validate_certs=self.validate_certs).read())) + for user in users: + if user['username'] == username: + userrep = user + break + return userrep + except ValueError as e: self.module.fail_json(msg='API returned incorrect JSON when trying to obtain the user for realm %s and username %s: %s' % (realm, username, str(e))) From a6dd7d789bbcbd7489eaaa8f5fc852b55b075e75 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 29 May 2023 17:27:42 +0200 Subject: [PATCH 0012/1451] Move ansible-core 2.12 to EOL CI (#6584) * https://github.com/ansible/ansible/pull/79734 has been merged and backported for all branches but stable-2.10 and stable-2.11. * Move ansible-core 2.12 to EOL CI. --- .azure-pipelines/azure-pipelines.yml | 73 ---------------------------- .github/workflows/ansible-test.yml | 55 +++++++++++++++++++-- 2 files changed, 51 insertions(+), 77 deletions(-) diff --git a/.azure-pipelines/azure-pipelines.yml b/.azure-pipelines/azure-pipelines.yml index 2d55bb8e55..2604e9ff84 100644 --- a/.azure-pipelines/azure-pipelines.yml +++ b/.azure-pipelines/azure-pipelines.yml @@ -112,19 +112,6 @@ stages: - test: 2 - test: 3 - test: 4 - - stage: Sanity_2_12 - displayName: Sanity 2.12 - dependsOn: [] - jobs: - - template: templates/matrix.yml - parameters: - nameFormat: Test {0} - testFormat: 2.12/sanity/{0} - targets: - - test: 1 - - test: 2 - - test: 3 - - test: 4 ### Units - stage: Units_devel displayName: Units devel @@ -174,17 +161,6 @@ stages: targets: - test: 2.7 - test: 3.8 - - stage: Units_2_12 - displayName: Units 2.12 - dependsOn: [] - jobs: - - template: templates/matrix.yml - parameters: - nameFormat: Python {0} - testFormat: 2.12/units/{0}/1 - targets: - - test: 2.6 - - test: 3.8 ## Remote - stage: Remote_devel_extra_vms @@ -269,22 +245,6 @@ stages: test: macos/12.0 - name: RHEL 8.5 test: rhel/8.5 - groups: - - 1 - - 2 - - 3 - - stage: Remote_2_12 - displayName: Remote 2.12 - dependsOn: [] - jobs: - - template: templates/matrix.yml - parameters: - testFormat: 2.12/{0} - targets: - - name: macOS 11.1 - test: macos/11.1 - - name: RHEL 8.4 - test: rhel/8.4 - name: FreeBSD 13.0 test: freebsd/13.0 groups: @@ -361,24 +321,6 @@ stages: - 1 - 2 - 3 - - stage: Docker_2_12 - displayName: Docker 2.12 - dependsOn: [] - jobs: - - template: templates/matrix.yml - parameters: - testFormat: 2.12/linux/{0} - targets: - - name: CentOS 6 - test: centos6 - - name: Fedora 34 - test: fedora34 - - name: Ubuntu 18.04 - test: ubuntu1804 - groups: - - 1 - - 2 - - 3 ### Community Docker - stage: Docker_community_devel @@ -442,45 +384,30 @@ stages: testFormat: 2.13/generic/{0}/1 targets: - test: 3.9 - - stage: Generic_2_12 - displayName: Generic 2.12 - dependsOn: [] - jobs: - - template: templates/matrix.yml - parameters: - nameFormat: Python {0} - testFormat: 2.12/generic/{0}/1 - targets: - - test: 3.8 - stage: Summary condition: succeededOrFailed() dependsOn: - Sanity_devel - - Sanity_2_12 - Sanity_2_13 - Sanity_2_14 - Sanity_2_15 - Units_devel - - Units_2_12 - Units_2_13 - Units_2_14 - Units_2_15 - Remote_devel_extra_vms - Remote_devel - - Remote_2_12 - Remote_2_13 - Remote_2_14 - Remote_2_15 - Docker_devel - - Docker_2_12 - Docker_2_13 - Docker_2_14 - Docker_2_15 - Docker_community_devel # Right now all generic tests are disabled. Uncomment when at least one of them is re-enabled. # - Generic_devel -# - Generic_2_12 # - Generic_2_13 # - Generic_2_14 # - Generic_2_15 diff --git a/.github/workflows/ansible-test.yml b/.github/workflows/ansible-test.yml index ef170347c3..09e17dd82f 100644 --- a/.github/workflows/ansible-test.yml +++ b/.github/workflows/ansible-test.yml @@ -30,6 +30,7 @@ jobs: matrix: ansible: - '2.11' + - '2.12' # Ansible-test on various stable branches does not yet work well with cgroups v2. # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04 # image for these stable branches. The list of branches where this is necessary will @@ -43,7 +44,7 @@ jobs: - name: Perform sanity testing uses: felixfontein/ansible-test-gh-action@main with: - ansible-core-github-repository-slug: felixfontein/ansible + ansible-core-github-repository-slug: ${{ contains(fromJson('["2.10", "2.11"]'), matrix.ansible) && 'felixfontein/ansible' || 'ansible/ansible' }} ansible-core-version: stable-${{ matrix.ansible }} coverage: ${{ github.event_name == 'schedule' && 'always' || 'never' }} pull-request-change-detection: 'true' @@ -75,6 +76,10 @@ jobs: python: '2.7' - ansible: '2.11' python: '3.5' + - ansible: '2.12' + python: '2.6' + - ansible: '2.12' + python: '3.8' steps: - name: >- @@ -82,7 +87,7 @@ jobs: Ansible version ${{ matrix.ansible }} uses: felixfontein/ansible-test-gh-action@main with: - ansible-core-github-repository-slug: felixfontein/ansible + ansible-core-github-repository-slug: ${{ contains(fromJson('["2.10", "2.11"]'), matrix.ansible) && 'felixfontein/ansible' || 'ansible/ansible' }} ansible-core-version: stable-${{ matrix.ansible }} coverage: ${{ github.event_name == 'schedule' && 'always' || 'never' }} pre-test-cmd: >- @@ -163,7 +168,49 @@ jobs: # - ansible: '2.11' # docker: default # python: '3.5' - # target: azp/generic/2/ + # target: azp/generic/1/ + # 2.12 + - ansible: '2.12' + docker: centos6 + python: '' + target: azp/posix/1/ + - ansible: '2.12' + docker: centos6 + python: '' + target: azp/posix/2/ + - ansible: '2.12' + docker: centos6 + python: '' + target: azp/posix/3/ + - ansible: '2.12' + docker: fedora34 + python: '' + target: azp/posix/1/ + - ansible: '2.12' + docker: fedora34 + python: '' + target: azp/posix/2/ + - ansible: '2.12' + docker: fedora34 + python: '' + target: azp/posix/3/ + - ansible: '2.12' + docker: ubuntu1804 + python: '' + target: azp/posix/1/ + - ansible: '2.12' + docker: ubuntu1804 + python: '' + target: azp/posix/2/ + - ansible: '2.12' + docker: ubuntu1804 + python: '' + target: azp/posix/3/ + # Right now all generic tests are disabled. Uncomment when at least one of them is re-enabled. + # - ansible: '2.12' + # docker: default + # python: '3.8' + # target: azp/generic/1/ steps: - name: >- @@ -172,7 +219,7 @@ jobs: under Python ${{ matrix.python }} uses: felixfontein/ansible-test-gh-action@main with: - ansible-core-github-repository-slug: felixfontein/ansible + ansible-core-github-repository-slug: ${{ contains(fromJson('["2.10", "2.11"]'), matrix.ansible) && 'felixfontein/ansible' || 'ansible/ansible' }} ansible-core-version: stable-${{ matrix.ansible }} coverage: ${{ github.event_name == 'schedule' && 'always' || 'never' }} docker-image: ${{ matrix.docker }} From ee47497e977a1ff0d906c15dcd1010b2b79b1db2 Mon Sep 17 00:00:00 2001 From: day4me Date: Mon, 29 May 2023 19:51:43 +0300 Subject: [PATCH 0013/1451] datadog_monitor: Added notification preset name and renotify options (#6523) * added notification_preset_name to datadog_monitor module * added renotify optiond * fix renotify_interval * remove renotify_interval, it's already there * add renotify_status only if renotify_interval not None * add default for renotify_occurrences * fix renotify_occurrences * set renotify_occurrences default to 1 * fix renotify_occurrences * fix renotify_occurrences * fix renotify_occurrences * fix renotify_occurrences * fix renotify_statuses * fix renotify_statuses * fix renotify_statuses * fix renotify_statuses * final changes * added changelog fragment * added choices for renotify_statuses and changed version * remove choices duplication Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- ...notification-preset-name-and-renotify.yaml | 2 ++ plugins/modules/datadog_monitor.py | 36 +++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 changelogs/fragments/6523-datadog-monitor-notification-preset-name-and-renotify.yaml diff --git a/changelogs/fragments/6523-datadog-monitor-notification-preset-name-and-renotify.yaml b/changelogs/fragments/6523-datadog-monitor-notification-preset-name-and-renotify.yaml new file mode 100644 index 0000000000..dbcf255364 --- /dev/null +++ b/changelogs/fragments/6523-datadog-monitor-notification-preset-name-and-renotify.yaml @@ -0,0 +1,2 @@ +minor_changes: + - datadog_monitor - adds ``notification_preset_name``, ``renotify_occurrences`` and ``renotify_statuses`` parameters (https://github.com/ansible-collections/community.general/issues/6521,https://github.com/ansible-collections/community.general/issues/5823). \ No newline at end of file diff --git a/plugins/modules/datadog_monitor.py b/plugins/modules/datadog_monitor.py index f58df358b7..d1ad288ccc 100644 --- a/plugins/modules/datadog_monitor.py +++ b/plugins/modules/datadog_monitor.py @@ -167,6 +167,32 @@ options: - Integer from 1 (high) to 5 (low) indicating alert severity. type: int version_added: 4.6.0 + notification_preset_name: + description: + - Toggles the display of additional content sent in the monitor notification. + choices: + - show_all + - hide_query + - hide_handles + - hide_all + type: str + version_added: 7.1.0 + renotify_occurrences: + description: + - The number of times re-notification messages should be sent on the current status at the provided re-notification interval. + type: int + version_added: 7.1.0 + renotify_statuses: + description: + - The types of monitor statuses for which re-notification messages are sent. + choices: + - alert + - warn + - no data + type: list + elements: str + version_added: 7.1.0 + ''' EXAMPLES = ''' @@ -175,6 +201,10 @@ EXAMPLES = ''' type: "metric alert" name: "Test monitor" state: "present" + renotify_interval: 30 + renotify_occurrences: 1 + renotify_statuses: ["warn"] + notification_preset_name: "show_all" query: "datadog.agent.up.over('host:host1').last(2).count_by_status()" notification_message: "Host [[host.name]] with IP [[host.ip]] is failing to report to datadog." api_key: "9775a026f1ca7d1c6c5af9d94d9595a4" @@ -254,6 +284,9 @@ def main(): id=dict(), include_tags=dict(required=False, default=True, type='bool'), priority=dict(type='int'), + notification_preset_name=dict(choices=['show_all', 'hide_query', 'hide_handles', 'hide_all']), + renotify_occurrences=dict(type='int'), + renotify_statuses=dict(type='list', elements='str', choices=['alert', 'warn', 'no data']), ) ) @@ -368,6 +401,9 @@ def install_monitor(module): "new_host_delay": module.params['new_host_delay'], "evaluation_delay": module.params['evaluation_delay'], "include_tags": module.params['include_tags'], + "notification_preset_name": module.params['notification_preset_name'], + "renotify_occurrences": module.params['renotify_occurrences'], + "renotify_statuses": module.params['renotify_statuses'], } if module.params['type'] == "service check": From 64f74e122834b069b9fb5171a503a25a13fbe139 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Tue, 30 May 2023 04:52:02 +1200 Subject: [PATCH 0014/1451] cpanm: deprecate default mode (#6512) * cpanm: deprecate default mode * add changelog frag --- changelogs/fragments/6512-cpanm-default-mode.yml | 2 ++ plugins/modules/cpanm.py | 12 ++++++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/6512-cpanm-default-mode.yml diff --git a/changelogs/fragments/6512-cpanm-default-mode.yml b/changelogs/fragments/6512-cpanm-default-mode.yml new file mode 100644 index 0000000000..55490905a1 --- /dev/null +++ b/changelogs/fragments/6512-cpanm-default-mode.yml @@ -0,0 +1,2 @@ +deprecated_features: + - cpanm - value ``compatibility`` is deprecated as default for parameter ``mode`` (https://github.com/ansible-collections/community.general/pull/6512). diff --git a/plugins/modules/cpanm.py b/plugins/modules/cpanm.py index 6260992dfe..c78d58d12b 100644 --- a/plugins/modules/cpanm.py +++ b/plugins/modules/cpanm.py @@ -68,9 +68,9 @@ options: mode: description: - Controls the module behavior. See notes below for more details. + - Default is C(compatibility) but that behavior is deprecated and will be changed to C(new) in community.general 9.0.0. type: str choices: [compatibility, new] - default: compatibility version_added: 3.0.0 name_check: description: @@ -158,7 +158,7 @@ class CPANMinus(ModuleHelper): mirror_only=dict(type='bool', default=False), installdeps=dict(type='bool', default=False), executable=dict(type='path'), - mode=dict(type='str', choices=['compatibility', 'new'], default='compatibility'), + mode=dict(type='str', choices=['compatibility', 'new']), name_check=dict(type='str') ), required_one_of=[('name', 'from_path')], @@ -176,6 +176,14 @@ class CPANMinus(ModuleHelper): def __init_module__(self): v = self.vars + if v.mode is None: + self.deprecate( + "The default value 'compatibility' for parameter 'mode' is being deprecated " + "and it will be replaced by 'new'", + version="9.0.0", + collection_name="community.general" + ) + v.mode = "compatibility" if v.mode == "compatibility": if v.name_check: self.do_raise("Parameter name_check can only be used with mode=new") From e588e675d96b2a9d806e52ea1e06ec4172d403ae Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Tue, 30 May 2023 04:52:29 +1200 Subject: [PATCH 0015/1451] opkg: remove useless default value for force (#6513) * opkg: remove useless default value for force * add changelog frag * Update changelogs/fragments/6513-opkg-default-force.yml Co-authored-by: Felix Fontein * add to force param description * typo --------- Co-authored-by: Felix Fontein --- changelogs/fragments/6513-opkg-default-force.yml | 2 ++ plugins/modules/opkg.py | 7 ++++--- 2 files changed, 6 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/6513-opkg-default-force.yml diff --git a/changelogs/fragments/6513-opkg-default-force.yml b/changelogs/fragments/6513-opkg-default-force.yml new file mode 100644 index 0000000000..1313473bc2 --- /dev/null +++ b/changelogs/fragments/6513-opkg-default-force.yml @@ -0,0 +1,2 @@ +minor_changes: + - opkg - remove default value ``""`` for parameter ``force`` as it causes the same behaviour of not having that parameter (https://github.com/ansible-collections/community.general/pull/6513). diff --git a/plugins/modules/opkg.py b/plugins/modules/opkg.py index d2ac314d03..308e1e85ec 100644 --- a/plugins/modules/opkg.py +++ b/plugins/modules/opkg.py @@ -46,6 +46,8 @@ options: force: description: - The C(opkg --force) parameter used. + - Passing C("") as value and not passing any value at all have both + the same effect of B(not) using any C(--force-) parameter. choices: - "" - "depends" @@ -58,7 +60,6 @@ options: - "remove" - "checksum" - "removal-of-dependent-packages" - default: "" type: str update_cache: description: @@ -114,8 +115,8 @@ class Opkg(StateModuleHelper): argument_spec=dict( name=dict(aliases=["pkg"], required=True, type="list", elements="str"), state=dict(default="present", choices=["present", "installed", "absent", "removed"]), - force=dict(default="", choices=["", "depends", "maintainer", "reinstall", "overwrite", "downgrade", "space", "postinstall", "remove", - "checksum", "removal-of-dependent-packages"]), + force=dict(choices=["", "depends", "maintainer", "reinstall", "overwrite", "downgrade", "space", + "postinstall", "remove", "checksum", "removal-of-dependent-packages"]), update_cache=dict(default=False, type='bool'), ), ) From bd6cec2105c8d575d20d1e3889a6d26b5ce0377e Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Mon, 29 May 2023 11:52:50 -0500 Subject: [PATCH 0016/1451] respawn copr module when dnf is missing (#6522) * respawn copr module when dnf is missing Fixes: https://bugzilla.redhat.com/2203513 * don't guard common.respawn module_util import --- changelogs/fragments/6522-copr-respawn.yaml | 4 ++++ plugins/modules/copr.py | 16 ++++++++++++++++ tests/integration/targets/copr/tasks/main.yml | 6 ------ 3 files changed, 20 insertions(+), 6 deletions(-) create mode 100644 changelogs/fragments/6522-copr-respawn.yaml diff --git a/changelogs/fragments/6522-copr-respawn.yaml b/changelogs/fragments/6522-copr-respawn.yaml new file mode 100644 index 0000000000..8d5922e4c9 --- /dev/null +++ b/changelogs/fragments/6522-copr-respawn.yaml @@ -0,0 +1,4 @@ +--- +minor_changes: + - "copr - respawn module to use the system python interpreter when the ``dnf`` python module is not available in ``ansible_python_interpreter`` + (https://github.com/ansible-collections/community.general/pull/6522)." diff --git a/plugins/modules/copr.py b/plugins/modules/copr.py index 965c2a935d..1311de849d 100644 --- a/plugins/modules/copr.py +++ b/plugins/modules/copr.py @@ -97,6 +97,7 @@ except ImportError: DNF_IMP_ERR = traceback.format_exc() HAS_DNF_PACKAGES = False +from ansible.module_utils.common import respawn from ansible.module_utils.six.moves.urllib.error import HTTPError from ansible.module_utils.basic import missing_required_lib from ansible.module_utils import distro # pylint: disable=import-error @@ -104,6 +105,20 @@ from ansible.module_utils.basic import AnsibleModule # pylint: disable=import-e from ansible.module_utils.urls import open_url # pylint: disable=import-error +def _respawn_dnf(): + if respawn.has_respawned(): + return + system_interpreters = ( + "/usr/libexec/platform-python", + "/usr/bin/python3", + "/usr/bin/python2", + "/usr/bin/python", + ) + interpreter = respawn.probe_interpreters_for_module(system_interpreters, "dnf") + if interpreter: + respawn.respawn_module(interpreter) + + class CoprModule(object): """The class represents a copr module. @@ -460,6 +475,7 @@ def run_module(): params = module.params if not HAS_DNF_PACKAGES: + _respawn_dnf() module.fail_json(msg=missing_required_lib("dnf"), exception=DNF_IMP_ERR) CoprModule.ansible_module = module diff --git a/tests/integration/targets/copr/tasks/main.yml b/tests/integration/targets/copr/tasks/main.yml index 0e46517240..0d66378112 100644 --- a/tests/integration/targets/copr/tasks/main.yml +++ b/tests/integration/targets/copr/tasks/main.yml @@ -10,12 +10,6 @@ ansible_distribution == 'Fedora' or (ansible_os_family == 'RedHat' and ansible_distribution != 'Fedora' and ansible_distribution_major_version | int >= 8) - # The copr module imports dnf which is only available for the system Python - # interpreter. - - > - not (ansible_distribution == 'CentOS' and - ansible_distribution_major_version | int == 8 and not - ansible_python_version.startswith('3.6')) block: - debug: var=copr_chroot - name: enable copr project From 4373f2f33b8e89fa87613aeb60d07b0a07c972c8 Mon Sep 17 00:00:00 2001 From: Justine Jose <59870720+justinpjose@users.noreply.github.com> Date: Mon, 29 May 2023 17:53:20 +0100 Subject: [PATCH 0017/1451] mas: disable sign-in check for macOS 12+ (#6520) * disable sign-in check for macOS 12+ * move is_version_greater func outside class Mas * fix formatting * remove trailing whitespace * make use of LooseVersion to compare versions * update requirement description Co-authored-by: Felix Fontein * update requirement description link Co-authored-by: Felix Fontein * update constant of macOS version Co-authored-by: Felix Fontein * use updated constant Co-authored-by: Felix Fontein * update getting macOS version Co-authored-by: Felix Fontein * add changelog fragment --------- Co-authored-by: Felix Fontein --- .../fragments/6520-mas-disable-signin.yaml | 3 +++ plugins/modules/mas.py | 18 +++++++++++++----- 2 files changed, 16 insertions(+), 5 deletions(-) create mode 100644 changelogs/fragments/6520-mas-disable-signin.yaml diff --git a/changelogs/fragments/6520-mas-disable-signin.yaml b/changelogs/fragments/6520-mas-disable-signin.yaml new file mode 100644 index 0000000000..0cd6caa626 --- /dev/null +++ b/changelogs/fragments/6520-mas-disable-signin.yaml @@ -0,0 +1,3 @@ +--- +minor_changes: + - "mas - disable sign-in check for macOS 12+ as ``mas account`` is non-functional (https://github.com/ansible-collections/community.general/pull/6520)." diff --git a/plugins/modules/mas.py b/plugins/modules/mas.py index 5b8958beb0..532f6a2dc1 100644 --- a/plugins/modules/mas.py +++ b/plugins/modules/mas.py @@ -53,6 +53,8 @@ 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). ''' EXAMPLES = ''' @@ -106,6 +108,9 @@ import os from ansible_collections.community.general.plugins.module_utils.version import LooseVersion +import platform +NOT_WORKING_MAC_VERSION_MAS_ACCOUNT = '12.0' + class Mas(object): @@ -115,6 +120,7 @@ class Mas(object): # Initialize data properties self.mas_path = self.module.get_bin_path('mas') self._checked_signin = False + self._mac_version = platform.mac_ver()[0] or '0.0' self._installed = None # Populated only if needed self._outdated = None # Populated only if needed self.count_install = 0 @@ -156,14 +162,16 @@ class Mas(object): def check_signin(self): ''' Verifies that the user is signed in to the Mac App Store ''' - # Only check this once per execution if self._checked_signin: return - - rc, out, err = self.run(['account']) - if out.split("\n", 1)[0].rstrip() == 'Not signed in': - self.module.fail_json(msg='You must be signed in to the Mac App Store') + if LooseVersion(self._mac_version) >= LooseVersion(NOT_WORKING_MAC_VERSION_MAS_ACCOUNT): + # Checking if user is signed-in is disabled due to https://github.com/mas-cli/mas/issues/417 + self.module.log('WARNING: You must be signed in via the Mac App Store GUI beforehand else error will occur') + else: + rc, out, err = self.run(['account']) + if out.split("\n", 1)[0].rstrip() == 'Not signed in': + self.module.fail_json(msg='You must be signed in to the Mac App Store') self._checked_signin = True From 8586adcd518803ec7d874f65c4d6b75092e8345c Mon Sep 17 00:00:00 2001 From: Orion Poplawski Date: Mon, 29 May 2023 10:53:56 -0600 Subject: [PATCH 0018/1451] plugins/inventory/cobbler: Add option to use system name for inventory (#6502) * plugins/inventory/cobbler: Add option to use system name for inventory hostname (#6492) * plugins/inventory/cobbler: Add warning for systems with empty profiles --- .../6502-cobbler-inventory_hostname.yml | 3 +++ plugins/inventory/cobbler.py | 22 ++++++++++++++++--- 2 files changed, 22 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/6502-cobbler-inventory_hostname.yml diff --git a/changelogs/fragments/6502-cobbler-inventory_hostname.yml b/changelogs/fragments/6502-cobbler-inventory_hostname.yml new file mode 100644 index 0000000000..5a2a76f2bf --- /dev/null +++ b/changelogs/fragments/6502-cobbler-inventory_hostname.yml @@ -0,0 +1,3 @@ +minor_changes: + - cobbler inventory plugin - add ``inventory_hostname`` option to allow using the system name for the inventory hostname (https://github.com/ansible-collections/community.general/pull/6502). + - cobbler inventory plugin - add warning for systems with empty profiles (https://github.com/ansible-collections/community.general/pull/6502). diff --git a/plugins/inventory/cobbler.py b/plugins/inventory/cobbler.py index 936a409aeb..1b8382e331 100644 --- a/plugins/inventory/cobbler.py +++ b/plugins/inventory/cobbler.py @@ -56,6 +56,15 @@ DOCUMENTATION = ''' default: [] elements: str version_added: 4.4.0 + inventory_hostname: + description: + - What to use for the ansible inventory hostname. + - By default the networking hostname is used if defined, otherwise the DNS name of the management or first non-static interface. + - If set to I(system), the cobbler system name is used. + type: str + choices: [ 'hostname', 'system' ] + default: hostname + version_added: 7.1.0 group_by: description: Keys to group hosts by type: list @@ -201,6 +210,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable): self.exclude_profiles = self.get_option('exclude_profiles') self.include_profiles = self.get_option('include_profiles') self.group_by = self.get_option('group_by') + self.inventory_hostname = self.get_option('inventory_hostname') for profile in self._get_profiles(): if profile['parent']: @@ -238,7 +248,10 @@ class InventoryModule(BaseInventoryPlugin, Cacheable): for host in self._get_systems(): # Get the FQDN for the host and add it to the right groups - hostname = host['hostname'] # None + if self.inventory_hostname == 'system': + hostname = host['name'] # None + else: + hostname = host['hostname'] # None interfaces = host['interfaces'] if self._exclude_profile(host['profile']): @@ -262,8 +275,11 @@ class InventoryModule(BaseInventoryPlugin, Cacheable): self.display.vvvv('Added host %s hostname %s\n' % (host['name'], hostname)) # Add host to profile group - 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)) + 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)) + else: + self.display.warning('Host %s has an empty profile\n' % (hostname)) # Add host to groups specified by group_by fields for group_by in self.group_by: From 486f6553f5b7f04e424c9d29c2792411da1b75a3 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Tue, 30 May 2023 04:54:17 +1200 Subject: [PATCH 0019/1451] VarDict module utils (#6511) * vardict: easy hadling of module variables * fix copyright year * initial tests passing * small adjustments * add tests * add to BOTMETA * remove unused import pytest * Update plugins/module_utils/vardict.py Co-authored-by: Felix Fontein * minor refactor and documentation * minor adjustments * rename VarDict.var() to VarDict._var() - plus add more docs * fix method name in tests --------- Co-authored-by: Felix Fontein --- .github/BOTMETA.yml | 3 + plugins/module_utils/vardict.py | 175 ++++++++++++++++++ .../unit/plugins/module_utils/test_vardict.py | 124 +++++++++++++ 3 files changed, 302 insertions(+) create mode 100644 plugins/module_utils/vardict.py create mode 100644 tests/unit/plugins/module_utils/test_vardict.py diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 66269e3b20..9c724fd571 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -333,6 +333,9 @@ files: $module_utils/utm_utils.py: labels: utm_utils maintainers: $team_e_spirit + $module_utils/vardict.py: + labels: vardict + maintainers: russoz $module_utils/wdc_redfish_utils.py: labels: wdc_redfish_utils maintainers: $team_wdc diff --git a/plugins/module_utils/vardict.py b/plugins/module_utils/vardict.py new file mode 100644 index 0000000000..e5754425fc --- /dev/null +++ b/plugins/module_utils/vardict.py @@ -0,0 +1,175 @@ +# -*- coding: utf-8 -*- +# (c) 2023, Alexei Znamensky +# Copyright (c) 2023, Ansible Project +# Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause) +# SPDX-License-Identifier: BSD-2-Clause + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + +import copy + + +class _Variable(object): + NOTHING = object() + + def __init__(self, diff=False, output=True, change=None, fact=False, verbosity=0): + self.init = False + self.initial_value = None + self.value = None + + self.diff = None + self._change = None + self.output = None + self.fact = None + self._verbosity = None + self.set_meta(output=output, diff=diff, change=change, fact=fact, verbosity=verbosity) + + def getchange(self): + return self.diff if self._change is None else self._change + + def setchange(self, value): + self._change = value + + def getverbosity(self): + return self._verbosity + + def setverbosity(self, v): + if not (0 <= v <= 4): + raise ValueError("verbosity must be an int in the range 0 to 4") + self._verbosity = v + + change = property(getchange, setchange) + verbosity = property(getverbosity, setverbosity) + + def set_meta(self, output=None, diff=None, change=None, fact=None, initial_value=NOTHING, verbosity=None): + """Set the metadata for the variable + + Args: + output (bool, optional): flag indicating whether the variable should be in the output of the module. Defaults to None. + diff (bool, optional): flag indicating whether to generate diff mode output for this variable. Defaults to None. + change (bool, optional): flag indicating whether to track if changes happened to this variable. Defaults to None. + fact (bool, optional): flag indicating whether the varaiable should be exposed as a fact of the module. Defaults to None. + initial_value (any, optional): initial value of the variable, to be used with `change`. Defaults to NOTHING. + verbosity (int, optional): level of verbosity in which this variable is reported by the module as `output`, `fact` or `diff`. Defaults to None. + """ + if output is not None: + self.output = output + if change is not None: + self.change = change + if diff is not None: + self.diff = diff + if fact is not None: + self.fact = fact + if initial_value is not _Variable.NOTHING: + self.initial_value = copy.deepcopy(initial_value) + if verbosity is not None: + self.verbosity = verbosity + + def set_value(self, value): + if not self.init: + self.initial_value = copy.deepcopy(value) + self.init = True + self.value = value + return self + + def is_visible(self, verbosity): + return self.verbosity <= verbosity + + @property + def has_changed(self): + return self.change and (self.initial_value != self.value) + + @property + def diff_result(self): + if self.diff and self.has_changed: + return {'before': self.initial_value, 'after': self.value} + return + + def __str__(self): + return "<_Variable: value={0!r}, initial={1!r}, diff={2}, output={3}, change={4}, verbosity={5}>".format( + self.value, self.initial_value, self.diff, self.output, self.change, self.verbosity + ) + + +class VarDict(object): + reserved_names = ('__vars__', 'var', 'set_meta', 'set', 'output', 'diff', 'facts', 'has_changed') + + def __init__(self): + self.__vars__ = dict() + + def __getitem__(self, item): + return self.__vars__[item].value + + def __setitem__(self, key, value): + self.set(key, value) + + def __getattr__(self, item): + try: + return self.__vars__[item].value + except KeyError: + return getattr(super(VarDict, self), item) + + def __setattr__(self, key, value): + if key == '__vars__': + super(VarDict, self).__setattr__(key, value) + else: + self.set(key, value) + + def _var(self, name): + return self.__vars__[name] + + def set_meta(self, name, **kwargs): + """Set the metadata for the variable + + Args: + name (str): name of the variable having its metadata changed + output (bool, optional): flag indicating whether the variable should be in the output of the module. Defaults to None. + diff (bool, optional): flag indicating whether to generate diff mode output for this variable. Defaults to None. + change (bool, optional): flag indicating whether to track if changes happened to this variable. Defaults to None. + fact (bool, optional): flag indicating whether the varaiable should be exposed as a fact of the module. Defaults to None. + initial_value (any, optional): initial value of the variable, to be used with `change`. Defaults to NOTHING. + verbosity (int, optional): level of verbosity in which this variable is reported by the module as `output`, `fact` or `diff`. Defaults to None. + """ + self._var(name).set_meta(**kwargs) + + def set(self, name, value, **kwargs): + """Set the value and optionally metadata for a variable. The variable is not required to exist prior to calling `set`. + + For details on the accepted metada see the documentation for method `set_meta`. + + Args: + name (str): name of the variable being changed + value (any): the value of the variable, it can be of any type + + Raises: + ValueError: Raised if trying to set a variable with a reserved name. + """ + if name in self.reserved_names: + raise ValueError("Name {0} is reserved".format(name)) + if name in self.__vars__: + var = self._var(name) + var.set_meta(**kwargs) + else: + var = _Variable(**kwargs) + var.set_value(value) + self.__vars__[name] = var + + def output(self, verbosity=0): + return dict((n, v.value) for n, v in self.__vars__.items() if v.output and v.is_visible(verbosity)) + + def diff(self, verbosity=0): + diff_results = [(n, v.diff_result) for n, v in self.__vars__.items() if v.diff_result and v.is_visible(verbosity)] + if diff_results: + before = dict((n, dr['before']) for n, dr in diff_results) + after = dict((n, dr['after']) for n, dr in diff_results) + return {'before': before, 'after': after} + return None + + def facts(self, verbosity=0): + facts_result = dict((n, v.value) for n, v in self.__vars__.items() if v.fact and v.is_visible(verbosity)) + return facts_result if facts_result else None + + @property + def has_changed(self): + return any(True for var in self.__vars__.values() if var.has_changed) diff --git a/tests/unit/plugins/module_utils/test_vardict.py b/tests/unit/plugins/module_utils/test_vardict.py new file mode 100644 index 0000000000..8b6f16226d --- /dev/null +++ b/tests/unit/plugins/module_utils/test_vardict.py @@ -0,0 +1,124 @@ +# -*- coding: utf-8 -*- +# (c) 2023, Alexei Znamensky +# Copyright (c) 2023 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.plugins.module_utils.vardict import VarDict + + +def test_var_simple(): + vd = VarDict() + vd["a"] = 123 + + var = vd._var("a") + assert var.output is True + assert var.diff is False + assert var.change is False + assert var.fact is False + assert var.initial_value == 123 + assert var.value == 123 + + vd.a = 456 + assert var.output is True + assert var.diff is False + assert var.change is False + assert var.fact is False + assert var.initial_value == 123 + assert var.value == 456 + + +def test_var_diff_scalar(): + vd = VarDict() + vd.set("aa", 123, diff=True) + + var = vd._var("aa") + assert var.output is True + assert var.diff is True + assert var.change is True + assert var.fact is False + assert var.initial_value == 123 + assert var.value == 123 + assert vd.diff() is None + + vd.aa = 456 + assert var.output is True + assert var.diff is True + assert var.change is True + assert var.fact is False + assert var.initial_value == 123 + assert var.value == 456 + assert vd.diff() == {"before": {"aa": 123}, "after": {"aa": 456}}, "actual={0}".format(vd.diff()) + + +def test_var_diff_dict(): + val_before = dict(x=0, y=10, z=10) + val_after = dict(x=0, y=30, z=10) + + vd = VarDict() + vd.set("dd", val_before, diff=True) + + var = vd._var("dd") + assert var.output is True + assert var.diff is True + assert var.change is True + assert var.fact is False + assert var.initial_value == val_before + assert var.value == val_before + assert vd.diff() is None + + vd.dd = val_after + assert var.output is True + assert var.diff is True + assert var.change is True + assert var.fact is False + assert var.initial_value == val_before + assert var.value == val_after + assert vd.diff() == {"before": {"dd": val_before}, "after": {"dd": val_after}}, "actual={0}".format(vd.diff()) + + vd.set("aa", 123, diff=True) + vd.aa = 456 + assert vd.diff() == {"before": {"aa": 123, "dd": val_before}, "after": {"aa": 456, "dd": val_after}}, "actual={0}".format(vd.diff()) + + +def test_vardict_set_meta(): + vd = VarDict() + vd["jj"] = 123 + + var = vd._var("jj") + assert var.output is True + assert var.diff is False + assert var.change is False + assert var.fact is False + assert var.initial_value == 123 + assert var.value == 123 + + vd.set_meta("jj", diff=True) + assert var.diff is True + assert var.change is True + + vd.set_meta("jj", diff=False) + assert var.diff is False + assert var.change is False + + vd.set_meta("jj", change=False) + vd.set_meta("jj", diff=True) + assert var.diff is True + assert var.change is False + + +def test_vardict_change(): + vd = VarDict() + vd.set("xx", 123, change=True) + vd.set("yy", 456, change=True) + vd.set("zz", 789, change=True) + + vd.xx = 123 + vd.yy = 456 + assert vd.has_changed is False + vd.xx = 12345 + assert vd.has_changed is True From 4c0eff02e52b80701a59a2677ff857b20ddf1e25 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Tue, 30 May 2023 04:54:35 +1200 Subject: [PATCH 0020/1451] sorcery: moved import to top (#6525) * sorcery: moved import to top * add changelog frag * Update changelogs/fragments/6525-sorcery-import.yaml Co-authored-by: Vlad Glagolev --------- Co-authored-by: Vlad Glagolev --- changelogs/fragments/6525-sorcery-import.yaml | 2 ++ plugins/modules/sorcery.py | 5 ++--- 2 files changed, 4 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/6525-sorcery-import.yaml diff --git a/changelogs/fragments/6525-sorcery-import.yaml b/changelogs/fragments/6525-sorcery-import.yaml new file mode 100644 index 0000000000..efc170cd74 --- /dev/null +++ b/changelogs/fragments/6525-sorcery-import.yaml @@ -0,0 +1,2 @@ +minor_changes: + - sorcery - minor refactor (https://github.com/ansible-collections/community.general/pull/6525). diff --git a/plugins/modules/sorcery.py b/plugins/modules/sorcery.py index 3278ce0abd..538d91de11 100644 --- a/plugins/modules/sorcery.py +++ b/plugins/modules/sorcery.py @@ -165,6 +165,8 @@ import re import shutil import sys +from ansible.module_utils.basic import AnsibleModule + # auto-filled at module init SORCERY = { @@ -646,8 +648,5 @@ def main(): manage_spells(module) -# import module snippets -from ansible.module_utils.basic import AnsibleModule - if __name__ == '__main__': main() From 57f8d8477616b5f632b3ee8706404ec1bd4c1b63 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 29 May 2023 18:55:12 +0200 Subject: [PATCH 0021/1451] Improve/fix dconf documentation using semantic markup (#6544) Improve/fix dconf documentation using semantic markup. --- plugins/modules/dconf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/modules/dconf.py b/plugins/modules/dconf.py index 8c325486cc..8fa884ea91 100644 --- a/plugins/modules/dconf.py +++ b/plugins/modules/dconf.py @@ -46,11 +46,11 @@ notes: - Keep in mind that the C(dconf) CLI tool, which this module wraps around, utilises an unusual syntax for the values (GVariant). For example, if you wanted to provide a string value, the correct syntax would be - I(value="'myvalue'") - with single quotes as part of the Ansible parameter + O(value="'myvalue'") - with single quotes as part of the Ansible parameter value. - When using loops in combination with a value like - "[('xkb', 'us'), ('xkb', 'se')]", you need to be aware of possible - type conversions. Applying a filter C({{ item.value | string }}) + V("[('xkb', 'us'\), ('xkb', 'se'\)]"), you need to be aware of possible + type conversions. Applying a filter V({{ item.value | string }}) to the parameter variable can avoid potential conversion problems. - The easiest way to figure out exact syntax/value you need to provide for a key is by making the configuration change in application affected by the @@ -76,7 +76,7 @@ options: - Value to set for the specified dconf key. Value should be specified in GVariant format. Due to complexity of this format, it is best to have a look at existing values in the dconf database. - - Required for I(state=present). + - Required for O(state=present). - Although the type is specified as "raw", it should typically be specified as a string. However, boolean values in particular are handled properly even when specified as booleans rather than strings From 0c96d22994f0f97144cb9cb355d3c3eb42588ae7 Mon Sep 17 00:00:00 2001 From: Benibr Date: Mon, 29 May 2023 18:55:42 +0200 Subject: [PATCH 0022/1451] gitlab modules: added instance variable (#6524) * gitlab modules: added instance variable * fixup * first review * renamed to variables (groups->instance) * added 'version_added' * better disscription of 'updated' return value * removed unneccessary import error check * removed environment scope * added vars_to_variables import * added maintainer to .github/BOTMETA.yml * second review * removed vars * readded postprocessing * added integration test --------- Co-authored-by: Benedikt Braunger --- .github/BOTMETA.yml | 2 + plugins/modules/gitlab_instance_variable.py | 367 +++++++++++ .../targets/gitlab_instance_variable/aliases | 5 + .../gitlab_instance_variable/tasks/main.yml | 606 ++++++++++++++++++ 4 files changed, 980 insertions(+) create mode 100644 plugins/modules/gitlab_instance_variable.py create mode 100644 tests/integration/targets/gitlab_instance_variable/aliases create mode 100644 tests/integration/targets/gitlab_instance_variable/tasks/main.yml diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 9c724fd571..9bb819b660 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -534,6 +534,8 @@ files: maintainers: paytroff $modules/gitlab_project_variable.py: maintainers: markuman + $modules/gitlab_instance_variable.py: + maintainers: benibr $modules/gitlab_runner.py: maintainers: SamyCoenen $modules/gitlab_user.py: diff --git a/plugins/modules/gitlab_instance_variable.py b/plugins/modules/gitlab_instance_variable.py new file mode 100644 index 0000000000..9b5db36883 --- /dev/null +++ b/plugins/modules/gitlab_instance_variable.py @@ -0,0 +1,367 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright (c) 2023, Benedikt Braunger (bebr@adm.ku.dk) +# Based on code: +# Copyright (c) 2020, Florent Madiot (scodeman@scode.io) +# Copyright (c) 2019, Markus Bergholz (markuman@gmail.com) +# 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: gitlab_instance_variable +short_description: Creates, updates, or deletes GitLab instance variables +version_added: 7.1.0 +description: + - Creates a instance variable if it does not exist. + - When a instance variable does exist, its value will be updated if the values are different. + - Support for instance variables requires GitLab >= 13.0. + - Variables which are not mentioned in the modules options, but are present on the GitLab instance, + will either stay (I(purge=false)) or will be deleted (I(purge=true)). +author: + - Benedikt Braunger (@benibr) +requirements: + - python >= 2.7 + - python-gitlab python module +extends_documentation_fragment: + - community.general.auth_basic + - community.general.gitlab + - community.general.attributes + +attributes: + check_mode: + support: full + diff_mode: + support: none + +options: + state: + description: + - Create or delete instance variable. + default: present + type: str + choices: ["present", "absent"] + purge: + description: + - When set to C(true), delete all variables which are not mentioned in the task. + default: false + type: bool + variables: + description: + - A list of dictionaries that represents CI/CD variables. + default: [] + type: list + elements: dict + suboptions: + name: + description: + - The name of the variable. + type: str + required: true + value: + description: + - The variable value. + - Required when I(state=present). + type: str + masked: + description: + - Wether variable value is masked or not. + type: bool + default: false + protected: + description: + - Wether variable value is protected or not. + type: bool + default: false + variable_type: + description: + - Wether a variable is an environment variable (C(env_var)) or a file (C(file)). + type: str + choices: [ "env_var", "file" ] + default: env_var +''' + + +EXAMPLES = r''' +- name: Set or update some CI/CD variables + community.general.gitlab_instance_variable: + api_url: https://gitlab.com + api_token: secret_access_token + purge: false + variables: + - name: ACCESS_KEY_ID + value: abc1312cba + - name: SECRET_ACCESS_KEY + value: 1337 + masked: true + protected: true + variable_type: env_var + +- name: Delete one variable + community.general.gitlab_instance_variable: + api_url: https://gitlab.com + api_token: secret_access_token + state: absent + variables: + - name: ACCESS_KEY_ID +''' + +RETURN = r''' +instance_variable: + description: Four lists of the variablenames which were added, updated, removed or exist. + returned: always + type: dict + contains: + added: + description: A list of variables which were created. + returned: always + type: list + sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY'] + untouched: + description: A list of variables which exist. + returned: always + type: list + sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY'] + removed: + description: A list of variables which were deleted. + returned: always + type: list + sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY'] + updated: + description: A list pre-existing variables whose values have been set. + returned: always + type: list + sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY'] +''' + +from ansible.module_utils.basic import AnsibleModule +from ansible.module_utils.api import basic_auth_argument_spec +from ansible_collections.community.general.plugins.module_utils.gitlab import ( + auth_argument_spec, gitlab_authentication, ensure_gitlab_package, filter_returned_variables +) + + +class GitlabInstanceVariables(object): + + def __init__(self, module, gitlab_instance): + self.instance = gitlab_instance + self._module = module + + def list_all_instance_variables(self): + page_nb = 1 + variables = [] + gl_varibales_page = self.instance.variables.list(page=page_nb) + while len(gl_varibales_page) > 0: + variables += gl_varibales_page + page_nb += 1 + gl_varibales_page = self.instance.variables.list(page=page_nb) + return variables + + def create_variable(self, var_obj): + if self._module.check_mode: + return True + var = { + "key": var_obj.get('key'), + "value": var_obj.get('value'), + "masked": var_obj.get('masked'), + "protected": var_obj.get('protected'), + "variable_type": var_obj.get('variable_type'), + } + + self.instance.variables.create(var) + return True + + def update_variable(self, var_obj): + if self._module.check_mode: + return True + self.delete_variable(var_obj) + self.create_variable(var_obj) + return True + + def delete_variable(self, var_obj): + if self._module.check_mode: + return True + self.instance.variables.delete(var_obj.get('key')) + return True + + +def compare(requested_variables, existing_variables, state): + # we need to do this, because it was determined in a previous version - more or less buggy + # basically it is not necessary and might results in more/other bugs! + # but it is required and only relevant for check mode!! + # logic represents state 'present' when not purge. all other can be derived from that + # untouched => equal in both + # updated => name and scope are equal + # added => name and scope does not exist + untouched = list() + updated = list() + added = list() + + if state == 'present': + existing_key_scope_vars = list() + for item in existing_variables: + existing_key_scope_vars.append({'key': item.get('key')}) + + for var in requested_variables: + if var in existing_variables: + untouched.append(var) + else: + compare_item = {'key': var.get('name')} + if compare_item in existing_key_scope_vars: + updated.append(var) + else: + added.append(var) + + return untouched, updated, added + + +def native_python_main(this_gitlab, purge, requested_variables, state, module): + + change = False + return_value = dict(added=list(), updated=list(), removed=list(), untouched=list()) + + gitlab_keys = this_gitlab.list_all_instance_variables() + before = [x.attributes for x in gitlab_keys] + + existing_variables = filter_returned_variables(gitlab_keys) + + for item in requested_variables: + item['key'] = item.pop('name') + item['value'] = str(item.get('value')) + if item.get('protected') is None: + item['protected'] = False + if item.get('masked') is None: + item['masked'] = False + if item.get('variable_type') is None: + item['variable_type'] = 'env_var' + + if module.check_mode: + untouched, updated, added = compare(requested_variables, existing_variables, state) + + if state == 'present': + add_or_update = [x for x in requested_variables if x not in existing_variables] + for item in add_or_update: + try: + if this_gitlab.create_variable(item): + return_value['added'].append(item) + + except Exception: + if this_gitlab.update_variable(item): + return_value['updated'].append(item) + + if purge: + # refetch and filter + gitlab_keys = this_gitlab.list_all_instance_variables() + existing_variables = filter_returned_variables(gitlab_keys) + + remove = [x for x in existing_variables if x not in requested_variables] + for item in remove: + if this_gitlab.delete_variable(item): + return_value['removed'].append(item) + + elif state == 'absent': + # value does not matter on removing variables. + # key and environment scope are sufficient + for item in existing_variables: + item.pop('value') + item.pop('variable_type') + for item in requested_variables: + item.pop('value') + item.pop('variable_type') + + if not purge: + remove_requested = [x for x in requested_variables if x in existing_variables] + for item in remove_requested: + if this_gitlab.delete_variable(item): + return_value['removed'].append(item) + + else: + for item in existing_variables: + if this_gitlab.delete_variable(item): + return_value['removed'].append(item) + + if module.check_mode: + return_value = dict(added=added, updated=updated, removed=return_value['removed'], untouched=untouched) + + if len(return_value['added'] + return_value['removed'] + return_value['updated']) > 0: + change = True + + gitlab_keys = this_gitlab.list_all_instance_variables() + after = [x.attributes for x in gitlab_keys] + + return change, return_value, before, after + + +def main(): + argument_spec = basic_auth_argument_spec() + argument_spec.update(auth_argument_spec()) + argument_spec.update( + purge=dict(type='bool', required=False, default=False), + variables=dict(type='list', elements='dict', required=False, default=list(), options=dict( + name=dict(type='str', required=True), + value=dict(type='str', no_log=True), + masked=dict(type='bool', default=False), + protected=dict(type='bool', default=False), + variable_type=dict(type='str', default='env_var', choices=["env_var", "file"]) + )), + state=dict(type='str', default="present", choices=["absent", "present"]), + ) + + module = AnsibleModule( + argument_spec=argument_spec, + mutually_exclusive=[ + ['api_username', 'api_token'], + ['api_username', 'api_oauth_token'], + ['api_username', 'api_job_token'], + ['api_token', 'api_oauth_token'], + ['api_token', 'api_job_token'], + ], + required_together=[ + ['api_username', 'api_password'], + ], + required_one_of=[ + ['api_username', 'api_token', 'api_oauth_token', 'api_job_token'] + ], + supports_check_mode=True + ) + ensure_gitlab_package(module) + + purge = module.params['purge'] + state = module.params['state'] + + variables = module.params['variables'] + + if state == 'present': + if any(x['value'] is None for x in variables): + module.fail_json(msg='value parameter is required in state present') + + gitlab_instance = gitlab_authentication(module) + + this_gitlab = GitlabInstanceVariables(module=module, gitlab_instance=gitlab_instance) + + changed, raw_return_value, before, after = native_python_main(this_gitlab, purge, variables, state, module) + + # postprocessing + for item in after: + item['name'] = item.pop('key') + for item in before: + item['name'] = item.pop('key') + + untouched_key_name = 'key' + if not module.check_mode: + untouched_key_name = 'name' + raw_return_value['untouched'] = [x for x in before if x in after] + + added = [x.get('key') for x in raw_return_value['added']] + updated = [x.get('key') for x in raw_return_value['updated']] + removed = [x.get('key') for x in raw_return_value['removed']] + untouched = [x.get(untouched_key_name) for x in raw_return_value['untouched']] + return_value = dict(added=added, updated=updated, removed=removed, untouched=untouched) + + module.exit_json(changed=changed, instance_variable=return_value) + + +if __name__ == '__main__': + main() diff --git a/tests/integration/targets/gitlab_instance_variable/aliases b/tests/integration/targets/gitlab_instance_variable/aliases new file mode 100644 index 0000000000..bd1f024441 --- /dev/null +++ b/tests/integration/targets/gitlab_instance_variable/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 + +unsupported diff --git a/tests/integration/targets/gitlab_instance_variable/tasks/main.yml b/tests/integration/targets/gitlab_instance_variable/tasks/main.yml new file mode 100644 index 0000000000..94a81698bc --- /dev/null +++ b/tests/integration/targets/gitlab_instance_variable/tasks/main.yml @@ -0,0 +1,606 @@ +--- +#################################################################### +# 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 required libs + pip: + name: python-gitlab + state: present + +- name: purge all variables for check_mode test + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + purge: true + +- name: add a variable value in check_mode + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + check_mode: true + register: gitlab_instance_variable_state + +- name: check_mode state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: apply add value from check_mode test + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + register: gitlab_instance_variable_state + +- name: state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: apply same value again again + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + register: gitlab_instance_variable_state + +- name: state must be not changed + assert: + that: + - gitlab_instance_variable_state is not changed + +- name: change protected attribute + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + protected: true + register: gitlab_instance_variable_state + +- name: state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: revert protected attribute + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + protected: false + register: gitlab_instance_variable_state + +- name: state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: change masked attribute + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + masked: true + register: gitlab_instance_variable_state + +- name: state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: revert masked attribute by not mention it + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + masked: false + register: gitlab_instance_variable_state + +- name: state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: revert again masked attribute by not mention it (idempotent) + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + register: gitlab_instance_variable_state + +- name: state must be not changed + assert: + that: + - gitlab_instance_variable_state is not changed + +- name: set all attributes + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + masked: true + protected: true + variable_type: env_var + register: gitlab_instance_variable_state + +- name: state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: set again all attributes (idempotent) + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + masked: true + protected: true + variable_type: env_var + register: gitlab_instance_variable_state + +- name: state must not be changed + assert: + that: + - gitlab_instance_variable_state is not changed + +- name: revert both (masked and protected) attribute + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + protected: false + register: gitlab_instance_variable_state + +- name: state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: change a variable value in check_mode again + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + check_mode: true + register: gitlab_instance_variable_state + +- name: check_mode state must not be changed + assert: + that: + - gitlab_instance_variable_state is not changed + +- name: apply again the value change from check_mode test + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: checkmode + register: gitlab_instance_variable_state + +- name: state must not be changed + assert: + that: + - gitlab_instance_variable_state is not changed + +- name: purge all variables again + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + purge: true + +- name: set two test variables + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: abc123 + - name: SECRET_ACCESS_KEY + value: 321cba + register: gitlab_instance_variable_state + +- name: set two test variables state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + - gitlab_instance_variable_state.instance_variable.added|length == 2 + - gitlab_instance_variable_state.instance_variable.untouched|length == 0 + - gitlab_instance_variable_state.instance_variable.removed|length == 0 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + +- name: re-set two test variables + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: abc123 + - name: SECRET_ACCESS_KEY + value: 321cba + register: gitlab_instance_variable_state + +- name: re-set two test variables state must not be changed + assert: + that: + - gitlab_instance_variable_state is not changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 2 + - gitlab_instance_variable_state.instance_variable.removed|length == 0 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + +- name: edit one variable + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: changed + purge: false + register: gitlab_instance_variable_state + +- name: edit one variable state must be changed + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 1 + - gitlab_instance_variable_state.instance_variable.removed|length == 0 + - gitlab_instance_variable_state.instance_variable.updated|length == 1 + - gitlab_instance_variable_state.instance_variable.updated[0] == "ACCESS_KEY_ID" + +- name: append one variable + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: some + value: value + purge: false + register: gitlab_instance_variable_state + +- name: append one variable state must be changed + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 1 + - gitlab_instance_variable_state.instance_variable.untouched|length == 2 + - gitlab_instance_variable_state.instance_variable.removed|length == 0 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + - gitlab_instance_variable_state.instance_variable.added[0] == "some" + +- name: re-set all variables + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: ACCESS_KEY_ID + value: changed + - name: SECRET_ACCESS_KEY + value: 321cba + - name: some + value: value + register: gitlab_instance_variable_state + +- name: re-set all variables state must not be changed + assert: + that: + - not gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 3 + - gitlab_instance_variable_state.instance_variable.removed|length == 0 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + +- name: set one variables and purge all others + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: some + value: value + purge: true + register: gitlab_instance_variable_state + +- name: set one variables and purge all others state must be changed + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 1 + - gitlab_instance_variable_state.instance_variable.removed|length == 2 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + +- name: only one variable is left + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: some + value: value + purge: false + register: gitlab_instance_variable_state + +- name: only one variable is left state must not be changed + assert: + that: + - not gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 1 + - gitlab_instance_variable_state.instance_variable.removed|length == 0 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched[0] == "some" + +- name: test integer values + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: some + value: 42 + purge: false + register: gitlab_instance_variable_state + +- name: only one variable is left state must be changed + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 0 + - gitlab_instance_variable_state.instance_variable.removed|length == 0 + - gitlab_instance_variable_state.instance_variable.updated|length == 1 + +- name: test float values + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: some + value: 42.23 + purge: false + register: gitlab_instance_variable_state + +- name: only one variable is left state must be changed + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 0 + - gitlab_instance_variable_state.instance_variable.removed|length == 0 + - gitlab_instance_variable_state.instance_variable.updated|length == 1 + +- name: delete the last left variable + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + state: absent + variables: + - name: some + register: gitlab_instance_variable_state + +- name: no variable is left state must be changed + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 0 + - gitlab_instance_variable_state.instance_variable.removed|length == 1 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + - gitlab_instance_variable_state.instance_variable.removed[0] == "some" + +- name: add one variable with variable_type file + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: my_test_var + value: my_test_value + variable_type: file + purge: false + register: gitlab_instance_variable_state + +- name: append one variable state must be changed + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 1 + - gitlab_instance_variable_state.instance_variable.untouched|length == 0 + - gitlab_instance_variable_state.instance_variable.removed|length == 0 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + # VALUE_SPECIFIED_IN_NO_LOG_PARAMETER + #- gitlab_instance_variable_state.instance_variable.added[0] == "my_test_var" + +- name: change variable_type attribute + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: my_test_var + value: my_test_value + variable_type: env_var + register: gitlab_instance_variable_state + +- name: state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: revert variable_type attribute + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: my_test_var + value: my_test_value + variable_type: file + register: gitlab_instance_variable_state + +- name: state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + +- name: delete the variable_type file variable + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + state: absent + variables: + - name: my_test_var + register: gitlab_instance_variable_state + +- name: no variable is left state must be changed + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 0 + - gitlab_instance_variable_state.instance_variable.removed|length == 1 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + - gitlab_instance_variable_state.instance_variable.removed[0] == "my_test_var" + +- name: set complete page and purge existing ones + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: page1_var01 + value: value + - name: page1_var02 + value: value + - name: page1_var03 + value: value + - name: page1_var04 + value: value + - name: page1_var05 + value: value + - name: page1_var06 + value: value + - name: page1_var07 + value: value + - name: page1_var08 + value: value + - name: page1_var09 + value: value + - name: page1_var10 + value: value + - name: page1_var11 + value: value + - name: page1_var12 + value: value + - name: page1_var13 + value: value + - name: page1_var14 + value: value + - name: page1_var15 + value: value + - name: page1_var16 + value: value + - name: page1_var17 + value: value + - name: page1_var18 + value: value + - name: page1_var19 + value: value + - name: page1_var20 + value: value + purge: true + register: gitlab_instance_variable_state + +- name: complete page added state must be changed + assert: + that: + - gitlab_instance_variable_state is changed + - gitlab_instance_variable_state.instance_variable.added|length == 20 + - gitlab_instance_variable_state.instance_variable.untouched|length == 0 + +- name: check that no variables are left + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + purge: true + register: gitlab_instance_variable_state + +- name: check that no variables are untouched state must be changed + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.added|length == 0 + - gitlab_instance_variable_state.instance_variable.untouched|length == 0 + - gitlab_instance_variable_state.instance_variable.removed|length == 20 + - gitlab_instance_variable_state.instance_variable.updated|length == 0 + +- name: throw error when state is present but no value is given + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + variables: + - name: no_value + register: gitlab_instance_variable_state + ignore_errors: true + +- name: verify fail + assert: + that: + - gitlab_instance_variable_state.failed + - gitlab_instance_variable_state is not changed + +- name: set a new variable to delete it later + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + purge: true + variables: + - name: delete_me + value: ansible + register: gitlab_instance_variable_state + +- name: verify the change + assert: + that: + - gitlab_instance_variable_state.changed + +- name: delete variable without referencing its value + gitlab_instance_variable: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_login_token }}" + state: absent + variables: + - name: delete_me + register: gitlab_instance_variable_state + +- name: verify deletion + assert: + that: + - gitlab_instance_variable_state.changed + - gitlab_instance_variable_state.instance_variable.removed|length == 1 From c76af60a73c9c058524313cf912a0e08e8427975 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gon=C3=A9ri=20Le=20Bouder?= Date: Mon, 29 May 2023 12:56:06 -0400 Subject: [PATCH 0023/1451] ini_file: Don't creates new file instead of following symlink (#6546) * ini_file: Don't creates new file instead of following symlink This is a bug fix that address a situation where `community.general.ini_file` was destroying symlinks instead of updating of updating their targets. Closes: #6470 * ini_file: add the follow parameter If `poth` points on a symlink and `follow` is true, the `ini_file` plugin will preserve the symlink and modify the target file. * adjust the documentation of the new key - yes/no -> true/false. - new key will be introduced in 7.1.0. - clean up the `state=link` part. --- .../fragments/ini_file-preserve-symlink.yml | 3 + plugins/modules/ini_file.py | 34 +++++++---- .../ini_file/tasks/tests/04-symlink.yml | 59 +++++++++++++++++++ 3 files changed, 86 insertions(+), 10 deletions(-) create mode 100644 changelogs/fragments/ini_file-preserve-symlink.yml create mode 100644 tests/integration/targets/ini_file/tasks/tests/04-symlink.yml diff --git a/changelogs/fragments/ini_file-preserve-symlink.yml b/changelogs/fragments/ini_file-preserve-symlink.yml new file mode 100644 index 0000000000..9e49e8a11e --- /dev/null +++ b/changelogs/fragments/ini_file-preserve-symlink.yml @@ -0,0 +1,3 @@ +--- +bugfixes: + - "ini_file - add the ``follow`` paramter to follow the symlinks instead of replacing them (https://github.com/ansible-collections/community.general/pull/6546)." diff --git a/plugins/modules/ini_file.py b/plugins/modules/ini_file.py index 9e4c370dc5..be4a03102b 100644 --- a/plugins/modules/ini_file.py +++ b/plugins/modules/ini_file.py @@ -109,6 +109,13 @@ options: - Allow option without value and without '=' symbol. type: bool default: false + follow: + description: + - This flag indicates that filesystem links, if they exist, should be followed. + - I(follow=true) can modify I(src) when combined with parameters such as I(mode). + type: bool + default: false + version_added: 7.1.0 notes: - While it is possible to add an I(option) without specifying a I(value), this makes no sense. - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well. @@ -191,7 +198,7 @@ def update_section_line(changed, section_lines, index, changed_lines, newline, m def do_ini(module, filename, section=None, option=None, values=None, state='present', exclusive=True, backup=False, no_extra_spaces=False, - create=True, allow_no_value=False): + create=True, allow_no_value=False, follow=False): if section is not None: section = to_text(section) @@ -210,15 +217,20 @@ def do_ini(module, filename, section=None, option=None, values=None, after_header='%s (content)' % filename, ) - if not os.path.exists(filename): + if follow and os.path.islink(filename): + target_filename = os.path.realpath(filename) + else: + target_filename = filename + + if not os.path.exists(target_filename): if not create: - module.fail_json(rc=257, msg='Destination %s does not exist!' % filename) - destpath = os.path.dirname(filename) + module.fail_json(rc=257, msg='Destination %s does not exist!' % target_filename) + destpath = os.path.dirname(target_filename) if not os.path.exists(destpath) and not module.check_mode: os.makedirs(destpath) ini_lines = [] else: - with io.open(filename, 'r', encoding="utf-8-sig") as ini_file: + with io.open(target_filename, 'r', encoding="utf-8-sig") as ini_file: ini_lines = [to_text(line) for line in ini_file.readlines()] if module._diff: @@ -404,7 +416,7 @@ def do_ini(module, filename, section=None, option=None, values=None, backup_file = None if changed and not module.check_mode: if backup: - backup_file = module.backup_local(filename) + backup_file = module.backup_local(target_filename) encoded_ini_lines = [to_bytes(line) for line in ini_lines] try: @@ -416,10 +428,10 @@ def do_ini(module, filename, section=None, option=None, values=None, module.fail_json(msg="Unable to create temporary file %s", traceback=traceback.format_exc()) try: - module.atomic_move(tmpfile, filename) + module.atomic_move(tmpfile, target_filename) except IOError: module.ansible.fail_json(msg='Unable to move temporary \ - file %s to %s, IOError' % (tmpfile, filename), traceback=traceback.format_exc()) + file %s to %s, IOError' % (tmpfile, target_filename), traceback=traceback.format_exc()) return (changed, backup_file, diff, msg) @@ -438,7 +450,8 @@ def main(): exclusive=dict(type='bool', default=True), no_extra_spaces=dict(type='bool', default=False), allow_no_value=dict(type='bool', default=False), - create=dict(type='bool', default=True) + create=dict(type='bool', default=True), + follow=dict(type='bool', default=False) ), mutually_exclusive=[ ['value', 'values'] @@ -458,6 +471,7 @@ def main(): no_extra_spaces = module.params['no_extra_spaces'] allow_no_value = module.params['allow_no_value'] create = module.params['create'] + follow = module.params['follow'] if state == 'present' and not allow_no_value and value is None and not values: module.fail_json(msg="Parameter 'value(s)' must be defined if state=present and allow_no_value=False.") @@ -467,7 +481,7 @@ def main(): elif values is None: values = [] - (changed, backup_file, diff, msg) = do_ini(module, path, section, option, values, state, exclusive, backup, no_extra_spaces, create, allow_no_value) + (changed, backup_file, diff, msg) = do_ini(module, path, section, option, values, state, exclusive, backup, no_extra_spaces, create, allow_no_value, follow) if not module.check_mode and os.path.exists(path): file_args = module.load_file_common_arguments(module.params) diff --git a/tests/integration/targets/ini_file/tasks/tests/04-symlink.yml b/tests/integration/targets/ini_file/tasks/tests/04-symlink.yml new file mode 100644 index 0000000000..de677bffad --- /dev/null +++ b/tests/integration/targets/ini_file/tasks/tests/04-symlink.yml @@ -0,0 +1,59 @@ +--- +# 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 + +- block: &prepare + - name: Create the final file + ansible.builtin.copy: + content: | + [main] + foo=BAR + dest: my_original_file.ini + - name: Clean up symlink.ini + ansible.builtin.file: + path: symlink.ini + state: absent + - name: Create a symbolic link + ansible.builtin.file: + src: my_original_file.ini + dest: symlink.ini + state: link + +- name: Set the proxy key on the symlink which will be converted as a file + community.general.ini_file: + path: symlink.ini + section: main + option: proxy + value: 'http://proxy.myorg.org:3128' +- name: Set the proxy key on the final file that is still unchanged + community.general.ini_file: + path: my_original_file.ini + section: main + option: proxy + value: 'http://proxy.myorg.org:3128' + register: result +- ansible.builtin.assert: + that: + - result is changed + +# With follow +- block: *prepare +- name: Set the proxy key on the symlink which will be preserved + community.general.ini_file: + path: symlink.ini + section: main + option: proxy + value: 'http://proxy.myorg.org:3128' + follow: true + register: result +- name: Set the proxy key on the target directly that was changed in the previous step + community.general.ini_file: + path: my_original_file.ini + section: main + option: proxy + value: 'http://proxy.myorg.org:3128' + register: result +- ansible.builtin.assert: + that: + - "not (result is changed)" From b133aa40c6d0e86c5c3d12c5123bec5d6657f7a0 Mon Sep 17 00:00:00 2001 From: Sergei Antipov Date: Mon, 29 May 2023 12:56:33 -0400 Subject: [PATCH 0024/1451] proxmox_kvm | Expose timeout param to stopped state (#6570) * Expose timeout param to stopped state Forcefully stop virtual machine using timeout param for proxmox vm shutdown api call. * Add changelog fragment * Typo fix in timeout param description * Update changelogs/fragments/6570-handle-shutdown-timeout.yaml Co-authored-by: Felix Fontein * Update plugins/modules/proxmox_kvm.py Co-authored-by: Felix Fontein * Revert back exception message --------- Co-authored-by: Felix Fontein --- .../fragments/6570-handle-shutdown-timeout.yaml | 3 +++ plugins/modules/proxmox_kvm.py | 14 +++++++++----- 2 files changed, 12 insertions(+), 5 deletions(-) create mode 100644 changelogs/fragments/6570-handle-shutdown-timeout.yaml diff --git a/changelogs/fragments/6570-handle-shutdown-timeout.yaml b/changelogs/fragments/6570-handle-shutdown-timeout.yaml new file mode 100644 index 0000000000..944992a1d4 --- /dev/null +++ b/changelogs/fragments/6570-handle-shutdown-timeout.yaml @@ -0,0 +1,3 @@ +--- +minor_changes: + - proxmox_kvm - re-use ``timeout`` module param to forcefully shutdown a virtual machine when ``state`` is ``stopped`` (https://github.com/ansible-collections/community.general/issues/6257). diff --git a/plugins/modules/proxmox_kvm.py b/plugins/modules/proxmox_kvm.py index b34ad82a7f..2de27ce569 100644 --- a/plugins/modules/proxmox_kvm.py +++ b/plugins/modules/proxmox_kvm.py @@ -444,7 +444,7 @@ options: - Indicates desired state of the instance. - If C(current), the current state of the VM will be fetched. You can access it with C(results.status) type: str - choices: ['present', 'started', 'absent', 'stopped', 'restarted','current'] + choices: ['present', 'started', 'absent', 'stopped', 'restarted', 'current'] default: present storage: description: @@ -480,6 +480,7 @@ options: timeout: description: - Timeout for operations. + - When used with I(state=stopped) the option sets a graceful timeout for VM stop after which a VM will be forcefully stopped. type: int default: 30 update: @@ -889,6 +890,9 @@ class ProxmoxKvmAnsible(ProxmoxAnsible): def wait_for_task(self, node, taskid): timeout = self.module.params['timeout'] + if self.module.params['state'] == 'stopped': + # Increase task timeout in case of stopped state to be sure it waits longer than VM stop operation itself + timeout += 10 while timeout: if self.api_task_ok(node, taskid): @@ -1058,10 +1062,10 @@ class ProxmoxKvmAnsible(ProxmoxAnsible): return False return True - def stop_vm(self, vm, force): + def stop_vm(self, vm, force, timeout): vmid = vm['vmid'] proxmox_node = self.proxmox_api.nodes(vm['node']) - taskid = proxmox_node.qemu(vmid).status.shutdown.post(forceStop=(1 if force else 0)) + taskid = proxmox_node.qemu(vmid).status.shutdown.post(forceStop=(1 if force else 0), timeout=timeout) if not self.wait_for_task(vm['node'], taskid): self.module.fail_json(msg='Reached timeout while waiting for stopping VM. Last line in task before timeout: %s' % proxmox_node.tasks(taskid).log.get()[:1]) @@ -1293,7 +1297,7 @@ def main(): elif proxmox.get_vmid(name, ignore_missing=True) and not (update or clone): module.exit_json(changed=False, vmid=proxmox.get_vmid(name), msg="VM with name <%s> already exists" % name) elif not node: - module.fail.json(msg='node is mandatory for creating/updating VM') + module.fail_json(msg='node is mandatory for creating/updating VM') elif update and not any([vmid, name]): module.fail_json(msg='vmid or name is mandatory for updating VM') elif not proxmox.get_node(node): @@ -1409,7 +1413,7 @@ def main(): if vm['status'] == 'stopped': module.exit_json(changed=False, vmid=vmid, msg="VM %s is already stopped" % vmid, **status) - if proxmox.stop_vm(vm, force=module.params['force']): + if proxmox.stop_vm(vm, force=module.params['force'], timeout=module.params['timeout']): module.exit_json(changed=True, vmid=vmid, msg="VM %s is shutting down" % vmid, **status) except Exception as e: module.fail_json(vmid=vmid, msg="stopping of VM %s failed with exception: %s" % (vmid, e), **status) From 01f21b1d4613b4bd49334641750e32da32148a79 Mon Sep 17 00:00:00 2001 From: Jeff Turner Date: Mon, 29 May 2023 13:56:57 -0300 Subject: [PATCH 0025/1451] proxmox_kvm: support for tpmstate0 parameter (#6533) * proxmox_kvm: added support for tmpstate adds hash of options for a TPM state disk, which is required for Windows 11 installations * updated wrong version in docs * bump version 7.1.0 -> 7.1.1 * fixed parameter name typo * updated to pass sanity; assumed version_added to be next major (7.2.0) * replaced 'tpmstate' with 'tpmstate0'; added suboptions to kvm_args * fixed line too long * use get() instead of pop() to preserve verbose invocation.module_args * update comment to include tpmstate0 * added changelog fragment * Revert "bump version 7.1.0 -> 7.1.1" This reverts commit 772ed98dba9a3356a6e4afcc43fa7befc98f54ba. * Include PR link in changelog fragment Co-authored-by: Felix Fontein * Corrected version_added Co-authored-by: Felix Fontein * corrected semantic markup for option name Co-authored-by: Felix Fontein * set suboptions of tpmstate0 to required * set default for tpmstate0.version (2.0) * fixed typo Co-authored-by: Felix Fontein * wrapped default version string in quotes Co-authored-by: Felix Fontein * Improve changelog formatting. --------- Co-authored-by: Felix Fontein --- .../6533-proxmox_kvm-tpmstate0-support.yaml | 2 ++ plugins/modules/proxmox_kvm.py | 35 ++++++++++++++++++- 2 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/6533-proxmox_kvm-tpmstate0-support.yaml diff --git a/changelogs/fragments/6533-proxmox_kvm-tpmstate0-support.yaml b/changelogs/fragments/6533-proxmox_kvm-tpmstate0-support.yaml new file mode 100644 index 0000000000..ce62361f2b --- /dev/null +++ b/changelogs/fragments/6533-proxmox_kvm-tpmstate0-support.yaml @@ -0,0 +1,2 @@ +minor_changes: + - proxmox_kvm - added support for ``tpmstate0`` parameter to configure TPM (Trusted Platform Module) disk. TPM is required for Windows 11 installations (https://github.com/ansible-collections/community.general/pull/6533). diff --git a/plugins/modules/proxmox_kvm.py b/plugins/modules/proxmox_kvm.py index 2de27ce569..d854790d79 100644 --- a/plugins/modules/proxmox_kvm.py +++ b/plugins/modules/proxmox_kvm.py @@ -483,6 +483,24 @@ options: - When used with I(state=stopped) the option sets a graceful timeout for VM stop after which a VM will be forcefully stopped. type: int default: 30 + tpmstate0: + description: + - A hash/dictionary of options for the Trusted Platform Module disk. + - A TPM state disk is required for Windows 11 installations. + suboptions: + storage: + description: + - O(tpmstate0.storage) is the storage identifier where to create the disk. + type: str + required: true + version: + description: + - The TPM version to use. + type: str + choices: ['1.2', '2.0'] + default: '2.0' + type: dict + version_added: 7.1.0 update: description: - If C(true), the VM will be updated with new value. @@ -942,7 +960,7 @@ class ProxmoxKvmAnsible(ProxmoxAnsible): urlencoded_ssh_keys = quote(kwargs['sshkeys'], safe='') kwargs['sshkeys'] = str(urlencoded_ssh_keys) - # If update, don't update disk (virtio, efidisk0, ide, sata, scsi) and network interface + # If update, don't update disk (virtio, efidisk0, tpmstate0, ide, sata, scsi) and network interface # pool parameter not supported by qemu//config endpoint on "update" (PVE 6.2) - only with "create" if update: if 'virtio' in kwargs: @@ -955,6 +973,8 @@ class ProxmoxKvmAnsible(ProxmoxAnsible): del kwargs['ide'] if 'efidisk0' in kwargs: del kwargs['efidisk0'] + if 'tpmstate0' in kwargs: + del kwargs['tpmstate0'] if 'net' in kwargs: del kwargs['net'] if 'force' in kwargs: @@ -982,6 +1002,13 @@ class ProxmoxKvmAnsible(ProxmoxAnsible): if 'storage' != k]) kwargs['efidisk0'] = efidisk0_str + # Flatten tpmstate0 option to a string so that it's a string which is what Proxmoxer and the API expect + if 'tpmstate0' in kwargs: + kwargs['tpmstate0'] = '{storage}:1,version=v{version}'.format( + storage=kwargs['tpmstate0'].get('storage'), + version=kwargs['tpmstate0'].get('version') + ) + # Convert all dict in kwargs to elements. # For hostpci[n], ide[n], net[n], numa[n], parallel[n], sata[n], scsi[n], serial[n], virtio[n], ipconfig[n] for k in list(kwargs.keys()): @@ -1167,6 +1194,11 @@ def main(): tdf=dict(type='bool'), template=dict(type='bool'), timeout=dict(type='int', default=30), + tpmstate0=dict(type='dict', + options=dict( + storage=dict(type='str', required=True), + version=dict(type='str', choices=['2.0', '1.2'], default='2.0') + )), update=dict(type='bool', default=False), vcpus=dict(type='int'), vga=dict(choices=['std', 'cirrus', 'vmware', 'qxl', 'serial0', 'serial1', 'serial2', 'serial3', 'qxl2', 'qxl3', 'qxl4']), @@ -1360,6 +1392,7 @@ def main(): target=module.params['target'], tdf=module.params['tdf'], template=module.params['template'], + tpmstate0=module.params['tpmstate0'], vcpus=module.params['vcpus'], vga=module.params['vga'], virtio=module.params['virtio'], From 47f39675a90de098f6e34a3cfdd815dfec38e517 Mon Sep 17 00:00:00 2001 From: Robert Osowiecki Date: Tue, 30 May 2023 22:00:14 +0200 Subject: [PATCH 0026/1451] Update BOTMETA.yml (#6603) Stepping down from maintaining parted module --- .github/BOTMETA.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 9bb819b660..40b7b783c1 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -934,7 +934,7 @@ files: $modules/pamd.py: maintainers: kevensen $modules/parted.py: - maintainers: ColOfAbRiX rosowiecki jake2184 + maintainers: ColOfAbRiX jake2184 $modules/pear.py: ignore: jle64 labels: pear From c9aae5e45cdf789cd0133346f699ad9ae8cbd432 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Wed, 31 May 2023 17:58:28 +1200 Subject: [PATCH 0027/1451] CmdRunner module utils: deprecate format method `as_default_type()` (#6601) * CmdRunner module utils: deprecate format method `as_default_type()` * add changelog frag --- .../fragments/6601-cmdrunner-deprecate-default-type.yml | 2 ++ plugins/module_utils/cmd_runner.py | 5 +++++ 2 files changed, 7 insertions(+) create mode 100644 changelogs/fragments/6601-cmdrunner-deprecate-default-type.yml diff --git a/changelogs/fragments/6601-cmdrunner-deprecate-default-type.yml b/changelogs/fragments/6601-cmdrunner-deprecate-default-type.yml new file mode 100644 index 0000000000..5bb10dbc29 --- /dev/null +++ b/changelogs/fragments/6601-cmdrunner-deprecate-default-type.yml @@ -0,0 +1,2 @@ +deprecated_features: + - CmdRunner module utils - deprecate ``cmd_runner_fmt.as_default_type()`` formatter (https://github.com/ansible-collections/community.general/pull/6601). diff --git a/plugins/module_utils/cmd_runner.py b/plugins/module_utils/cmd_runner.py index fa4c555d19..846f76f9e3 100644 --- a/plugins/module_utils/cmd_runner.py +++ b/plugins/module_utils/cmd_runner.py @@ -147,6 +147,11 @@ class _Format(object): @staticmethod def as_default_type(_type, arg="", ignore_none=None): + # + # DEPRECATION: This method is deprecated and will be removed in community.general 10.0.0 + # + # Instead of using the implicit formats provided here, use the explicit necessary format method. + # fmt = _Format if _type == "dict": return fmt.as_func(lambda d: ["--{0}={1}".format(*a) for a in iteritems(d)], ignore_none=ignore_none) From 59db302deb345e61551814f91b114ec640339889 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Wed, 31 May 2023 17:58:54 +1200 Subject: [PATCH 0028/1451] VarDict module utils: add `as_dict()` method (#6602) * VarDict module utils: add `as_dict()` method * add changelog frag --- changelogs/fragments/6602-vardict-as-dict.yml | 2 ++ plugins/module_utils/vardict.py | 3 +++ tests/unit/plugins/module_utils/test_vardict.py | 9 +++++++++ 3 files changed, 14 insertions(+) create mode 100644 changelogs/fragments/6602-vardict-as-dict.yml diff --git a/changelogs/fragments/6602-vardict-as-dict.yml b/changelogs/fragments/6602-vardict-as-dict.yml new file mode 100644 index 0000000000..d21952b00b --- /dev/null +++ b/changelogs/fragments/6602-vardict-as-dict.yml @@ -0,0 +1,2 @@ +minor_changes: + - VarDict module utils - add method ``VarDict.as_dict()`` to convert to a plain ``dict`` object (https://github.com/ansible-collections/community.general/pull/6602). diff --git a/plugins/module_utils/vardict.py b/plugins/module_utils/vardict.py index e5754425fc..c94ef669af 100644 --- a/plugins/module_utils/vardict.py +++ b/plugins/module_utils/vardict.py @@ -173,3 +173,6 @@ class VarDict(object): @property def has_changed(self): return any(True for var in self.__vars__.values() if var.has_changed) + + def as_dict(self): + return dict((name, var.value) for name, var in self.__vars__.items()) diff --git a/tests/unit/plugins/module_utils/test_vardict.py b/tests/unit/plugins/module_utils/test_vardict.py index 8b6f16226d..27a5be1a99 100644 --- a/tests/unit/plugins/module_utils/test_vardict.py +++ b/tests/unit/plugins/module_utils/test_vardict.py @@ -122,3 +122,12 @@ def test_vardict_change(): assert vd.has_changed is False vd.xx = 12345 assert vd.has_changed is True + + +def test_vardict_dict(): + vd = VarDict() + vd.set("xx", 123) + vd.set("yy", 456) + vd.set("zz", 789) + + assert vd.as_dict() == {"xx": 123, "yy": 456, "zz": 789} From f71a4747260164ae533d6795cfb0094f025abeb9 Mon Sep 17 00:00:00 2001 From: nxet Date: Wed, 31 May 2023 08:01:47 +0200 Subject: [PATCH 0029/1451] proxmox: support param `timezone` when creating container (#6510) * proxmox: support param `timezone` when creating container * add changelog fragments for #6510 * Apply suggestions from code review Co-authored-by: Felix Fontein * Improved param description * Use major.minor version comparison for options --------- Co-authored-by: Felix Fontein Co-authored-by: Sergei Antipov --- .../6510-proxmox-create-support_timezone.yaml | 3 ++ plugins/modules/proxmox.py | 32 +++++++++++++++---- 2 files changed, 29 insertions(+), 6 deletions(-) create mode 100644 changelogs/fragments/6510-proxmox-create-support_timezone.yaml diff --git a/changelogs/fragments/6510-proxmox-create-support_timezone.yaml b/changelogs/fragments/6510-proxmox-create-support_timezone.yaml new file mode 100644 index 0000000000..5e399c9ebc --- /dev/null +++ b/changelogs/fragments/6510-proxmox-create-support_timezone.yaml @@ -0,0 +1,3 @@ +minor_changes: + - proxmox - support ``timezone`` parameter at container creation + (https://github.com/ansible-collections/community.general/pull/6510). diff --git a/plugins/modules/proxmox.py b/plugins/modules/proxmox.py index 1f685f01b0..2c1d45dd41 100644 --- a/plugins/modules/proxmox.py +++ b/plugins/modules/proxmox.py @@ -168,6 +168,12 @@ options: - Script that will be executed during various steps in the containers lifetime. type: str version_added: '0.2.0' + timezone: + description: + - Timezone used by the container, accepts values like C(Europe/Paris). + - The special value C(host) configures the same timezone used by Proxmox host. + type: str + version_added: '7.1.0' proxmox_default_behavior: description: - As of community.general 4.0.0, various options no longer have default values. @@ -314,6 +320,18 @@ EXAMPLES = r''' ostemplate: local:vztmpl/ubuntu-14.04-x86_64.tar.gz' cores: 2 +- name: Create new container with minimal options and same timezone as proxmox host + community.general.proxmox: + vmid: 100 + node: uk-mc02 + api_user: root@pam + api_password: 1q2w3e + api_host: node1 + password: 123456 + hostname: example.org + ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz' + timezone: host + - name: Create a new container with nesting enabled and allows the use of CIFS/NFS inside the container. community.general.proxmox: vmid: 100 @@ -432,21 +450,21 @@ class ProxmoxLxcAnsible(ProxmoxAnsible): # Version limited features minimum_version = { - 'tags': 7, + 'tags': '6.1', + 'timezone': '6.3' } proxmox_node = self.proxmox_api.nodes(node) # Remove all empty kwarg entries kwargs = dict((k, v) for k, v in kwargs.items() if v is not None) - version = self.version() - pve_major_version = 3 if version < LooseVersion('4.0') else version.version[0] + pve_version = self.version() # Fail on unsupported features for option, version in minimum_version.items(): - if pve_major_version < version and option in kwargs: - self.module.fail_json(changed=False, msg="Feature {option} is only supported in PVE {version}+, and you're using PVE {pve_major_version}". - format(option=option, version=version, pve_major_version=pve_major_version)) + if pve_version < LooseVersion(version) and option in kwargs: + self.module.fail_json(changed=False, msg="Feature {option} is only supported in PVE {version}+, and you're using PVE {pve_version}". + format(option=option, version=version, pve_version=pve_version)) if VZ_TYPE == 'lxc': kwargs['cpulimit'] = cpus @@ -602,6 +620,7 @@ def main(): unprivileged=dict(type='bool', default=True), description=dict(type='str'), hookscript=dict(type='str'), + timezone=dict(type='str'), proxmox_default_behavior=dict(type='str', default='no_defaults', choices=['compatibility', 'no_defaults']), clone=dict(type='int'), clone_type=dict(default='opportunistic', choices=['full', 'linked', 'opportunistic']), @@ -704,6 +723,7 @@ def main(): unprivileged=ansible_to_proxmox_bool(module.params['unprivileged']), description=module.params['description'], hookscript=module.params['hookscript'], + timezone=module.params['timezone'], tags=module.params['tags']) module.exit_json(changed=True, msg="Deployed VM %s from template %s" % (vmid, module.params['ostemplate'])) From 16abb96bd8258aed3bd96dbf8e39617ce917d86a Mon Sep 17 00:00:00 2001 From: Sergei Antipov Date: Mon, 5 Jun 2023 15:17:31 -0400 Subject: [PATCH 0030/1451] New Proxmox VE modules to handle pools and their membership (#6604) * New Proxmox VE modules to handle pools and their membership * Fix pep8 linting errors * Fix pep8 and compatibility errors * Add required fields in the documentation * Typo fix * Fix pylint errors * Fix the last one error * Address review comments * Fix linting error * Add integration tests playbook * Add assert for the diff mode * Address review comments * Fix typo in the word * Fail for non-empty pool even in check_mode --- .github/BOTMETA.yml | 2 +- plugins/module_utils/proxmox.py | 22 ++ plugins/modules/proxmox_pool.py | 180 +++++++++++++ plugins/modules/proxmox_pool_member.py | 238 ++++++++++++++++++ .../integration/targets/proxmox_pool/aliases | 7 + .../targets/proxmox_pool/defaults/main.yml | 7 + .../targets/proxmox_pool/tasks/main.yml | 220 ++++++++++++++++ 7 files changed, 675 insertions(+), 1 deletion(-) create mode 100644 plugins/modules/proxmox_pool.py create mode 100644 plugins/modules/proxmox_pool_member.py create mode 100644 tests/integration/targets/proxmox_pool/aliases create mode 100644 tests/integration/targets/proxmox_pool/defaults/main.yml create mode 100644 tests/integration/targets/proxmox_pool/tasks/main.yml diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 40b7b783c1..926054ae99 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -981,7 +981,7 @@ files: $modules/proxmox: keywords: kvm libvirt proxmox qemu labels: proxmox virt - maintainers: $team_virt + maintainers: $team_virt UnderGreen $modules/proxmox.py: ignore: skvidal maintainers: UnderGreen diff --git a/plugins/module_utils/proxmox.py b/plugins/module_utils/proxmox.py index 58287cec17..9f3a55cac0 100644 --- a/plugins/module_utils/proxmox.py +++ b/plugins/module_utils/proxmox.py @@ -145,3 +145,25 @@ class ProxmoxAnsible(object): def api_task_ok(self, node, taskid): status = self.proxmox_api.nodes(node).tasks(taskid).status.get() return status['status'] == 'stopped' and status['exitstatus'] == 'OK' + + def get_pool(self, poolid): + """Retrieve pool information + + :param poolid: str - name of the pool + :return: dict - pool information + """ + try: + return self.proxmox_api.pools(poolid).get() + except Exception as e: + self.module.fail_json(msg="Unable to retrieve pool %s information: %s" % (poolid, e)) + + def get_storages(self, type): + """Retrieve storages information + + :param type: str, optional - type of storages + :return: list of dicts - array of storages + """ + try: + return self.proxmox_api.storage.get(type=type) + except Exception as e: + self.module.fail_json(msg="Unable to retrieve storages information with type %s: %s" % (type, e)) diff --git a/plugins/modules/proxmox_pool.py b/plugins/modules/proxmox_pool.py new file mode 100644 index 0000000000..7046320700 --- /dev/null +++ b/plugins/modules/proxmox_pool.py @@ -0,0 +1,180 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- +# +# Copyright (c) 2023, Sergei Antipov (UnderGreen) +# 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_pool +short_description: Pool management for Proxmox VE cluster +description: + - Create or delete a pool for Proxmox VE clusters. + - For pool members management please consult M(community.general.proxmox_pool_member) module. +version_added: 7.1.0 +author: "Sergei Antipov (@UnderGreen) " +attributes: + check_mode: + support: full + diff_mode: + support: none +options: + poolid: + description: + - The pool ID. + type: str + aliases: [ "name" ] + required: true + state: + description: + - 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 + comment: + description: + - Specify the description for the pool. + - Parameter is ignored when pool already exists or O(state=absent). + type: str + +extends_documentation_fragment: + - community.general.proxmox.documentation + - community.general.attributes +""" + +EXAMPLES = """ +- name: Create new Proxmox VE pool + community.general.proxmox_pool: + api_host: node1 + api_user: root@pam + api_password: password + poolid: test + comment: 'New pool' + +- name: Delete the Proxmox VE pool + community.general.proxmox_pool: + api_host: node1 + api_user: root@pam + api_password: password + poolid: test + state: absent +""" + +RETURN = """ +poolid: + description: The pool ID. + returned: success + type: str + sample: test +msg: + description: A short message on what the module did. + returned: always + type: str + sample: "Pool test successfully created" +""" + +from ansible.module_utils.basic import AnsibleModule +from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec, ProxmoxAnsible) + + +class ProxmoxPoolAnsible(ProxmoxAnsible): + + def is_pool_existing(self, poolid): + """Check whether pool already exist + + :param poolid: str - name of the pool + :return: bool - is pool exists? + """ + try: + pools = self.proxmox_api.pools.get() + for pool in pools: + if pool['poolid'] == poolid: + return True + return False + except Exception as e: + self.module.fail_json(msg="Unable to retrieve pools: {0}".format(e)) + + def is_pool_empty(self, poolid): + """Check whether pool has members + + :param poolid: str - name of the pool + :return: bool - is pool empty? + """ + return True if not self.get_pool(poolid)['members'] else False + + def create_pool(self, poolid, comment=None): + """Create Proxmox VE pool + + :param poolid: str - name of the pool + :param comment: str, optional - Description of a pool + :return: None + """ + if self.is_pool_existing(poolid): + self.module.exit_json(changed=False, poolid=poolid, msg="Pool {0} already exists".format(poolid)) + + if self.module.check_mode: + return + + try: + self.proxmox_api.pools.post(poolid=poolid, comment=comment) + except Exception as e: + self.module.fail_json(msg="Failed to create pool with ID {0}: {1}".format(poolid, e)) + + def delete_pool(self, poolid): + """Delete Proxmox VE pool + + :param poolid: str - name of the pool + :return: None + """ + if not self.is_pool_existing(poolid): + self.module.exit_json(changed=False, poolid=poolid, msg="Pool {0} doesn't exist".format(poolid)) + + if self.is_pool_empty(poolid): + if self.module.check_mode: + return + + try: + self.proxmox_api.pools(poolid).delete() + except Exception as e: + self.module.fail_json(msg="Failed to delete pool with ID {0}: {1}".format(poolid, e)) + else: + self.module.fail_json(msg="Can't delete pool {0} with members. Please remove members from pool first.".format(poolid)) + + +def main(): + module_args = proxmox_auth_argument_spec() + pools_args = dict( + poolid=dict(type="str", aliases=["name"], required=True), + comment=dict(type="str"), + state=dict(default="present", choices=["present", "absent"]), + ) + + module_args.update(pools_args) + + module = AnsibleModule( + argument_spec=module_args, + required_together=[("api_token_id", "api_token_secret")], + required_one_of=[("api_password", "api_token_id")], + supports_check_mode=True + ) + + poolid = module.params["poolid"] + comment = module.params["comment"] + state = module.params["state"] + + proxmox = ProxmoxPoolAnsible(module) + + if state == "present": + proxmox.create_pool(poolid, comment) + module.exit_json(changed=True, poolid=poolid, msg="Pool {0} successfully created".format(poolid)) + else: + proxmox.delete_pool(poolid) + module.exit_json(changed=True, poolid=poolid, msg="Pool {0} successfully deleted".format(poolid)) + + +if __name__ == "__main__": + main() diff --git a/plugins/modules/proxmox_pool_member.py b/plugins/modules/proxmox_pool_member.py new file mode 100644 index 0000000000..40efb3e1c4 --- /dev/null +++ b/plugins/modules/proxmox_pool_member.py @@ -0,0 +1,238 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- +# +# Copyright (c) 2023, Sergei Antipov (UnderGreen) +# 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_pool_member +short_description: Add or delete members from Proxmox VE cluster pools +description: + - Create or delete a pool member in Proxmox VE clusters. +version_added: 7.1.0 +author: "Sergei Antipov (@UnderGreen) " +attributes: + check_mode: + support: full + diff_mode: + support: full +options: + poolid: + description: + - The pool ID. + type: str + aliases: [ "name" ] + required: true + member: + description: + - Specify the member name. + - For O(type=storage) it is a storage name. + - For O(type=vm) either vmid or vm name could be used. + type: str + required: true + type: + description: + - Member type to add/remove from the pool. + choices: ["vm", "storage"] + default: vm + type: str + state: + description: + - Indicate desired state of the pool member. + choices: ['present', 'absent'] + default: present + type: str + +extends_documentation_fragment: + - community.general.proxmox.documentation + - community.general.attributes +""" + +EXAMPLES = """ +- name: Add new VM to Proxmox VE pool + community.general.proxmox_pool_member: + api_host: node1 + api_user: root@pam + api_password: password + poolid: test + member: 101 + +- name: Add new storage to Proxmox VE pool + community.general.proxmox_pool_member: + api_host: node1 + api_user: root@pam + api_password: password + poolid: test + member: zfs-data + type: storage + +- name: Remove VM from the Proxmox VE pool using VM name + community.general.proxmox_pool_member: + api_host: node1 + api_user: root@pam + api_password: password + poolid: test + member: pxe.home.arpa + state: absent + +- name: Remove storage from the Proxmox VE pool + community.general.proxmox_pool_member: + api_host: node1 + api_user: root@pam + api_password: password + poolid: test + member: zfs-storage + type: storage + state: absent +""" + +RETURN = """ +poolid: + description: The pool ID. + returned: success + type: str + sample: test +member: + description: Member name. + returned: success + type: str + sample: 101 +msg: + description: A short message on what the module did. + returned: always + type: str + sample: "Member 101 deleted from the pool test" +""" + +from ansible.module_utils.basic import AnsibleModule +from ansible_collections.community.general.plugins.module_utils.proxmox import (proxmox_auth_argument_spec, ProxmoxAnsible) + + +class ProxmoxPoolMemberAnsible(ProxmoxAnsible): + + def pool_members(self, poolid): + vms = [] + storage = [] + for member in self.get_pool(poolid)["members"]: + if member["type"] == "storage": + storage.append(member["storage"]) + else: + vms.append(member["vmid"]) + + return (vms, storage) + + def add_pool_member(self, poolid, member, member_type): + current_vms_members, current_storage_members = self.pool_members(poolid) + all_members_before = current_storage_members + current_vms_members + all_members_after = all_members_before.copy() + diff = {"before": {"members": all_members_before}, "after": {"members": all_members_after}} + + try: + if member_type == "storage": + storages = self.get_storages(type=None) + if member not in [storage["storage"] for storage in storages]: + self.module.fail_json(msg="Storage {0} doesn't exist in the cluster".format(member)) + if member in current_storage_members: + self.module.exit_json(changed=False, poolid=poolid, member=member, + diff=diff, msg="Member {0} is already part of the pool {1}".format(member, poolid)) + + all_members_after.append(member) + if self.module.check_mode: + return diff + + self.proxmox_api.pools(poolid).put(storage=[member]) + return diff + else: + try: + vmid = int(member) + except ValueError: + vmid = self.get_vmid(member) + + if vmid in current_vms_members: + self.module.exit_json(changed=False, poolid=poolid, member=member, + diff=diff, msg="VM {0} is already part of the pool {1}".format(member, poolid)) + + all_members_after.append(member) + + if not self.module.check_mode: + self.proxmox_api.pools(poolid).put(vms=[vmid]) + return diff + except Exception as e: + self.module.fail_json(msg="Failed to add a new member ({0}) to the pool {1}: {2}".format(member, poolid, e)) + + def delete_pool_member(self, poolid, member, member_type): + current_vms_members, current_storage_members = self.pool_members(poolid) + all_members_before = current_storage_members + current_vms_members + all_members_after = all_members_before.copy() + diff = {"before": {"members": all_members_before}, "after": {"members": all_members_after}} + + try: + if member_type == "storage": + if member not in current_storage_members: + self.module.exit_json(changed=False, poolid=poolid, member=member, + diff=diff, msg="Member {0} is not part of the pool {1}".format(member, poolid)) + + all_members_after.remove(member) + if self.module.check_mode: + return diff + + self.proxmox_api.pools(poolid).put(storage=[member], delete=1) + return diff + else: + try: + vmid = int(member) + except ValueError: + vmid = self.get_vmid(member) + + if vmid not in current_vms_members: + self.module.exit_json(changed=False, poolid=poolid, member=member, + diff=diff, msg="VM {0} is not part of the pool {1}".format(member, poolid)) + + all_members_after.remove(member) + + if not self.module.check_mode: + self.proxmox_api.pools(poolid).put(vms=[vmid], delete=1) + return diff + except Exception as e: + self.module.fail_json(msg="Failed to delete a member ({0}) from the pool {1}: {2}".format(member, poolid, e)) + + +def main(): + module_args = proxmox_auth_argument_spec() + pool_members_args = dict( + poolid=dict(type="str", aliases=["name"], required=True), + member=dict(type="str", required=True), + type=dict(default="vm", choices=["vm", "storage"]), + state=dict(default="present", choices=["present", "absent"]), + ) + + module_args.update(pool_members_args) + + module = AnsibleModule( + argument_spec=module_args, + required_together=[("api_token_id", "api_token_secret")], + required_one_of=[("api_password", "api_token_id")], + supports_check_mode=True + ) + + poolid = module.params["poolid"] + member = module.params["member"] + member_type = module.params["type"] + state = module.params["state"] + + proxmox = ProxmoxPoolMemberAnsible(module) + + if state == "present": + diff = proxmox.add_pool_member(poolid, member, member_type) + module.exit_json(changed=True, poolid=poolid, member=member, diff=diff, msg="New member {0} added to the pool {1}".format(member, poolid)) + else: + diff = proxmox.delete_pool_member(poolid, member, member_type) + module.exit_json(changed=True, poolid=poolid, member=member, diff=diff, msg="Member {0} deleted from the pool {1}".format(member, poolid)) + + +if __name__ == "__main__": + main() diff --git a/tests/integration/targets/proxmox_pool/aliases b/tests/integration/targets/proxmox_pool/aliases new file mode 100644 index 0000000000..525dcd332b --- /dev/null +++ b/tests/integration/targets/proxmox_pool/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 + +unsupported +proxmox_pool +proxmox_pool_member diff --git a/tests/integration/targets/proxmox_pool/defaults/main.yml b/tests/integration/targets/proxmox_pool/defaults/main.yml new file mode 100644 index 0000000000..5a518ac734 --- /dev/null +++ b/tests/integration/targets/proxmox_pool/defaults/main.yml @@ -0,0 +1,7 @@ +# Copyright (c) 2023, Sergei Antipov +# 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 + +poolid: test +member: local +member_type: storage diff --git a/tests/integration/targets/proxmox_pool/tasks/main.yml b/tests/integration/targets/proxmox_pool/tasks/main.yml new file mode 100644 index 0000000000..2b22960f2c --- /dev/null +++ b/tests/integration/targets/proxmox_pool/tasks/main.yml @@ -0,0 +1,220 @@ +#################################################################### +# WARNING: These are designed specifically for Ansible tests # +# and should not be used as examples of how to write Ansible roles # +#################################################################### + +# Copyright (c) 2023, Sergei Antipov +# 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: Proxmox VE pool and pool membership management + tags: ["pool"] + block: + - name: Make sure poolid parameter is not missing + proxmox_pool: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + ignore_errors: true + register: result + + - assert: + that: + - result is failed + - "'missing required arguments: poolid' in result.msg" + + - name: Create pool (Check) + proxmox_pool: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + check_mode: true + register: result + + - assert: + that: + - result is changed + - result is success + + - name: Create pool + proxmox_pool: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + register: result + + - assert: + that: + - result is changed + - result is success + - result.poolid == "{{ poolid }}" + + - name: Delete pool (Check) + proxmox_pool: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + state: absent + check_mode: true + register: result + + - assert: + that: + - result is changed + - result is success + + - name: Delete non-existing pool should do nothing + proxmox_pool: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "non-existing-poolid" + state: absent + register: result + + - assert: + that: + - result is not changed + - result is success + + - name: Deletion of non-empty pool fails + block: + - name: Add storage into pool + proxmox_pool_member: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + member: "{{ member }}" + type: "{{ member_type }}" + diff: true + register: result + + - assert: + that: + - result is changed + - result is success + - "'{{ member }}' in result.diff.after.members" + + - name: Add non-existing storage into pool should fail + proxmox_pool_member: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + member: "non-existing-storage" + type: "{{ member_type }}" + ignore_errors: true + register: result + + - assert: + that: + - result is failed + - "'Storage non-existing-storage doesn\\'t exist in the cluster' in result.msg" + + - name: Delete non-empty pool + proxmox_pool: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + state: absent + ignore_errors: true + register: result + + - assert: + that: + - result is failed + - "'Please remove members from pool first.' in result.msg" + + - name: Delete storage from the pool + proxmox_pool_member: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + member: "{{ member }}" + type: "{{ member_type }}" + state: absent + register: result + + - assert: + that: + - result is success + - result is changed + + rescue: + - name: Delete storage from the pool if it is added + proxmox_pool_member: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + member: "{{ member }}" + type: "{{ member_type }}" + state: absent + ignore_errors: true + + - name: Delete pool + proxmox_pool: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + state: absent + register: result + + - assert: + that: + - result is changed + - result is success + - result.poolid == "{{ poolid }}" + + rescue: + - name: Delete test pool if it is created + proxmox_pool: + api_host: "{{ api_host }}" + api_user: "{{ user }}@{{ domain }}" + api_password: "{{ api_password | default(omit) }}" + api_token_id: "{{ api_token_id | default(omit) }}" + api_token_secret: "{{ api_token_secret | default(omit) }}" + validate_certs: "{{ validate_certs }}" + poolid: "{{ poolid }}" + state: absent + ignore_errors: true From 36e8653cf73135b0a80a8dd94543a11403c871d0 Mon Sep 17 00:00:00 2001 From: Chris Evich <1183438+cevich@users.noreply.github.com> Date: Mon, 5 Jun 2023 15:18:12 -0400 Subject: [PATCH 0031/1451] Minor bitwarden plugin req. docs addition (#6613) The Bitwarden CLI requires a `login` followed by an `unlock` operation. The later will display a message regarding setting (and exporting) the `$BW_SESSION` env. var. When using the `bitwarden` lookup plugin, having the env. var. set and available (exported) to Ansible is critical. Without it, the plugin will simply return the error: `Bitwarden Vault locked. Run 'bw unlock'.` Make this clearer in the requirement documentation. Signed-off-by: Chris Evich --- plugins/lookup/bitwarden.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/plugins/lookup/bitwarden.py b/plugins/lookup/bitwarden.py index 389fa475bd..27de1afe60 100644 --- a/plugins/lookup/bitwarden.py +++ b/plugins/lookup/bitwarden.py @@ -12,6 +12,8 @@ DOCUMENTATION = """ requirements: - bw (command line utility) - be logged into bitwarden + - bitwarden vault unlocked + - C(BW_SESSION) environment variable set short_description: Retrieve secrets from Bitwarden version_added: 5.4.0 description: From c4e7a943c0bbb40467dd6fadabe99d8833e7abc5 Mon Sep 17 00:00:00 2001 From: Mike Raineri Date: Mon, 5 Jun 2023 15:56:44 -0400 Subject: [PATCH 0032/1451] Redfish: Add MultipartHTTPPushUpdate (#6612) * Redfish: Add MultipartHTTPPushUpdate Signed-off-by: Mike Raineri * Updates based on CI results Signed-off-by: Mike Raineri * Update plugins/modules/redfish_command.py Co-authored-by: Felix Fontein * Update changelogs/fragments/6471-redfish-add-multipart-http-push-command.yml Co-authored-by: Felix Fontein * Update plugins/modules/redfish_command.py Co-authored-by: Felix Fontein * Update plugins/module_utils/redfish_utils.py Co-authored-by: Felix Fontein * Update plugins/module_utils/redfish_utils.py Co-authored-by: Felix Fontein * Update plugins/module_utils/redfish_utils.py Co-authored-by: Felix Fontein * Update plugins/module_utils/redfish_utils.py Co-authored-by: Felix Fontein * Added missing import statement Signed-off-by: Mike Raineri * Added documentation for the usage of 'timeout' Signed-off-by: Mike Raineri --------- Signed-off-by: Mike Raineri Co-authored-by: Felix Fontein --- ...edfish-add-multipart-http-push-command.yml | 2 + plugins/module_utils/redfish_utils.py | 124 +++++++++++++++++- plugins/modules/redfish_command.py | 38 +++++- 3 files changed, 161 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/6471-redfish-add-multipart-http-push-command.yml diff --git a/changelogs/fragments/6471-redfish-add-multipart-http-push-command.yml b/changelogs/fragments/6471-redfish-add-multipart-http-push-command.yml new file mode 100644 index 0000000000..dd863638d0 --- /dev/null +++ b/changelogs/fragments/6471-redfish-add-multipart-http-push-command.yml @@ -0,0 +1,2 @@ +minor_changes: + - redfish_command - add ``MultipartHTTPPushUpdate`` command (https://github.com/ansible-collections/community.general/issues/6471, https://github.com/ansible-collections/community.general/pull/6612). diff --git a/plugins/module_utils/redfish_utils.py b/plugins/module_utils/redfish_utils.py index 9b64703027..027ce56308 100644 --- a/plugins/module_utils/redfish_utils.py +++ b/plugins/module_utils/redfish_utils.py @@ -7,9 +7,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type import json +import os +import random +import string from ansible.module_utils.urls import open_url from ansible.module_utils.common.text.converters import to_native from ansible.module_utils.common.text.converters import to_text +from ansible.module_utils.common.text.converters import to_bytes +from ansible.module_utils.six import text_type from ansible.module_utils.six.moves import http_client from ansible.module_utils.six.moves.urllib.error import URLError, HTTPError from ansible.module_utils.six.moves.urllib.parse import urlparse @@ -153,7 +158,7 @@ class RedfishUtils(object): 'msg': "Failed GET request to '%s': '%s'" % (uri, to_text(e))} return {'ret': True, 'data': data, 'headers': headers, 'resp': resp} - def post_request(self, uri, pyld): + def post_request(self, uri, pyld, multipart=False): req_headers = dict(POST_HEADERS) username, password, basic_auth = self._auth_params(req_headers) try: @@ -162,7 +167,14 @@ class RedfishUtils(object): # header since this can cause conflicts with some services if self.sessions_uri is not None and uri == (self.root_uri + self.sessions_uri): basic_auth = False - resp = open_url(uri, data=json.dumps(pyld), + if multipart: + # Multipart requests require special handling to encode the request body + multipart_encoder = self._prepare_multipart(pyld) + data = multipart_encoder[0] + req_headers['content-type'] = multipart_encoder[1] + else: + data = json.dumps(pyld) + resp = open_url(uri, data=data, headers=req_headers, method="POST", url_username=username, url_password=password, force_basic_auth=basic_auth, validate_certs=False, @@ -298,6 +310,59 @@ class RedfishUtils(object): 'msg': "Failed DELETE request to '%s': '%s'" % (uri, to_text(e))} return {'ret': True, 'resp': resp} + @staticmethod + def _prepare_multipart(fields): + """Prepares a multipart body based on a set of fields provided. + + Ideally it would have been good to use the existing 'prepare_multipart' + found in ansible.module_utils.urls, but it takes files and encodes them + as Base64 strings, which is not expected by Redfish services. It also + adds escaping of certain bytes in the payload, such as inserting '\r' + any time it finds a standlone '\n', which corrupts the image payload + send to the service. This implementation is simplified to Redfish's + usage and doesn't necessarily represent an exhaustive method of + building multipart requests. + """ + + def write_buffer(body, line): + # Adds to the multipart body based on the provided data type + # At this time there is only support for strings, dictionaries, and bytes (default) + if isinstance(line, text_type): + body.append(to_bytes(line, encoding='utf-8')) + elif isinstance(line, dict): + body.append(to_bytes(json.dumps(line), encoding='utf-8')) + else: + body.append(line) + return + + # Generate a random boundary marker; may need to consider probing the + # payload for potential conflicts in the future + boundary = ''.join(random.choice(string.digits + string.ascii_letters) for i in range(30)) + body = [] + for form in fields: + # Fill in the form details + write_buffer(body, '--' + boundary) + + # Insert the headers (Content-Disposition and Content-Type) + if 'filename' in fields[form]: + name = os.path.basename(fields[form]['filename']).replace('"', '\\"') + write_buffer(body, u'Content-Disposition: form-data; name="%s"; filename="%s"' % (to_text(form), to_text(name))) + else: + write_buffer(body, 'Content-Disposition: form-data; name="%s"' % form) + write_buffer(body, 'Content-Type: %s' % fields[form]['mime_type']) + write_buffer(body, '') + + # Insert the payload; read from the file if not given by the caller + if 'content' not in fields[form]: + with open(to_bytes(fields[form]['filename'], errors='surrogate_or_strict'), 'rb') as f: + fields[form]['content'] = f.read() + write_buffer(body, fields[form]['content']) + + # Finalize the entire request + write_buffer(body, '--' + boundary + '--') + write_buffer(body, '') + return (b'\r\n'.join(body), 'multipart/form-data; boundary=' + boundary) + @staticmethod def _get_extended_message(error): """ @@ -1572,6 +1637,61 @@ class RedfishUtils(object): 'msg': "SimpleUpdate requested", 'update_status': self._operation_results(response['resp'], response['data'])} + def multipath_http_push_update(self, update_opts): + """ + Provides a software update via the URI specified by the + MultipartHttpPushUri property. Callers should adjust the 'timeout' + variable in the base object to accommodate the size of the image and + speed of the transfer. For example, a 200MB image will likely take + more than the default 10 second timeout. + + :param update_opts: The parameters for the update operation + :return: dict containing the response of the update request + """ + image_file = update_opts.get('update_image_file') + targets = update_opts.get('update_targets') + apply_time = update_opts.get('update_apply_time') + + # Ensure the image file is provided + if not image_file: + return {'ret': False, 'msg': + 'Must specify update_image_file for the MultipartHTTPPushUpdate command'} + if not os.path.isfile(image_file): + return {'ret': False, 'msg': + 'Must specify a valid file for the MultipartHTTPPushUpdate command'} + try: + with open(image_file, 'rb') as f: + image_payload = f.read() + except Exception as e: + return {'ret': False, 'msg': + 'Could not read file %s' % image_file} + + # Check that multipart HTTP push updates are supported + response = self.get_request(self.root_uri + self.update_uri) + if response['ret'] is False: + return response + data = response['data'] + if 'MultipartHttpPushUri' not in data: + return {'ret': False, 'msg': 'Service does not support MultipartHttpPushUri'} + update_uri = data['MultipartHttpPushUri'] + + # Assemble the JSON payload portion of the request + payload = {"@Redfish.OperationApplyTime": "Immediate"} + if targets: + payload["Targets"] = targets + if apply_time: + payload["@Redfish.OperationApplyTime"] = apply_time + multipart_payload = { + 'UpdateParameters': {'content': json.dumps(payload), 'mime_type': 'application/json'}, + 'UpdateFile': {'filename': image_file, 'content': image_payload, 'mime_type': 'application/octet-stream'} + } + response = self.post_request(self.root_uri + update_uri, multipart_payload, multipart=True) + if response['ret'] is False: + return response + return {'ret': True, 'changed': True, + 'msg': "MultipartHTTPPushUpdate requested", + 'update_status': self._operation_results(response['resp'], response['data'])} + def get_update_status(self, update_handle): """ Gets the status of an update operation. diff --git a/plugins/modules/redfish_command.py b/plugins/modules/redfish_command.py index 400677eabb..715d06fcad 100644 --- a/plugins/modules/redfish_command.py +++ b/plugins/modules/redfish_command.py @@ -137,6 +137,12 @@ options: - URI of the image for the update. type: str version_added: '0.2.0' + update_image_file: + required: false + description: + - Filename, with optional path, of the image for the update. + type: path + version_added: '7.1.0' update_protocol: required: false description: @@ -541,6 +547,30 @@ EXAMPLES = ''' 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 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 + - name: Perform requested operations to continue the update community.general.redfish_command: category: Update @@ -697,7 +727,7 @@ CATEGORY_COMMANDS_ALL = { "Manager": ["GracefulRestart", "ClearLogs", "VirtualMediaInsert", "VirtualMediaEject", "PowerOn", "PowerForceOff", "PowerForceRestart", "PowerGracefulRestart", "PowerGracefulShutdown", "PowerReboot"], - "Update": ["SimpleUpdate", "PerformRequestedOperations"], + "Update": ["SimpleUpdate", "MultipartHTTPPushUpdate", "PerformRequestedOperations"], } @@ -726,6 +756,7 @@ def main(): boot_override_mode=dict(choices=['Legacy', 'UEFI']), resource_id=dict(), update_image_uri=dict(), + update_image_file=dict(type='path'), update_protocol=dict(), update_targets=dict(type='list', elements='str', default=[]), update_creds=dict( @@ -791,6 +822,7 @@ def main(): # update options update_opts = { 'update_image_uri': module.params['update_image_uri'], + 'update_image_file': module.params['update_image_file'], 'update_protocol': module.params['update_protocol'], 'update_targets': module.params['update_targets'], 'update_creds': module.params['update_creds'], @@ -940,6 +972,10 @@ def main(): result = rf_utils.simple_update(update_opts) if 'update_status' in result: return_values['update_status'] = result['update_status'] + elif command == "MultipartHTTPPushUpdate": + result = rf_utils.multipath_http_push_update(update_opts) + if 'update_status' in result: + return_values['update_status'] = result['update_status'] elif command == "PerformRequestedOperations": result = rf_utils.perform_requested_update_operations(update_opts['update_handle']) From 91b692634e546a1b2fbef94d7198a03a39b91d78 Mon Sep 17 00:00:00 2001 From: Tristan Pinaudeau Date: Tue, 6 Jun 2023 05:59:32 +0200 Subject: [PATCH 0033/1451] Fixed typo in record_values documentation (#6620) --- plugins/modules/ipa_dnsrecord.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/ipa_dnsrecord.py b/plugins/modules/ipa_dnsrecord.py index 398f63f8e4..b1a90141b9 100644 --- a/plugins/modules/ipa_dnsrecord.py +++ b/plugins/modules/ipa_dnsrecord.py @@ -59,7 +59,7 @@ options: record_values: description: - Manage DNS record name with this value. - - Mutually exclusive with I(record_values), and exactly one of I(record_value) and I(record_values) has to be specified. + - Mutually exclusive with I(record_value), and exactly one of I(record_value) and I(record_values) has to be specified. - In the case of 'A' or 'AAAA' record types, this will be the IP address. - In the case of 'A6' record type, this will be the A6 Record data. - In the case of 'CNAME' record type, this will be the hostname. From b78d1999e16075b15e4dd036fa432d24026b363b Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Wed, 7 Jun 2023 06:49:12 +1200 Subject: [PATCH 0034/1451] snap: aware of channel in installed snaps (#6435) * [WIP] snap: aware of channel in installed snaps * parse snap list output and assert whether channel matches * undo test * fail rightfully when install with different channel does not work * transparetent refresh * rollback comment in integration test * rollback comment in integration test * add changelog frag * Update plugins/modules/snap.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- .../fragments/6435-snap-channel-aware.yml | 2 + plugins/module_utils/snap.py | 1 + plugins/modules/snap.py | 94 +++++-- tests/integration/targets/snap/tasks/main.yml | 236 +----------------- tests/integration/targets/snap/tasks/test.yml | 235 +++++++++++++++++ .../targets/snap/tasks/test_channel.yml | 46 ++++ 6 files changed, 357 insertions(+), 257 deletions(-) create mode 100644 changelogs/fragments/6435-snap-channel-aware.yml create mode 100644 tests/integration/targets/snap/tasks/test.yml create mode 100644 tests/integration/targets/snap/tasks/test_channel.yml diff --git a/changelogs/fragments/6435-snap-channel-aware.yml b/changelogs/fragments/6435-snap-channel-aware.yml new file mode 100644 index 0000000000..5787de3502 --- /dev/null +++ b/changelogs/fragments/6435-snap-channel-aware.yml @@ -0,0 +1,2 @@ +minor_changes: + - snap - module is now aware of channel when deciding whether to install or refresh the snap (https://github.com/ansible-collections/community.general/pull/6435, https://github.com/ansible-collections/community.general/issues/1606). diff --git a/plugins/module_utils/snap.py b/plugins/module_utils/snap.py index 3ae126dbfd..1b3bdf2fe5 100644 --- a/plugins/module_utils/snap.py +++ b/plugins/module_utils/snap.py @@ -20,6 +20,7 @@ _state_map = dict( absent='remove', enabled='enable', disabled='disable', + refresh='refresh', ) diff --git a/plugins/modules/snap.py b/plugins/modules/snap.py index 359b7fa323..43abe4e913 100644 --- a/plugins/modules/snap.py +++ b/plugins/modules/snap.py @@ -35,7 +35,9 @@ options: state: description: - Desired state of the package. - required: false + - > + When I(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 @@ -52,9 +54,9 @@ options: 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). type: str required: false - default: stable 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 @@ -159,15 +161,20 @@ from ansible_collections.community.general.plugins.module_utils.snap import snap class Snap(StateModuleHelper): + NOT_INSTALLED = 0 + CHANNEL_MISMATCH = 1 + INSTALLED = 2 + __disable_re = re.compile(r'(?:\S+\s+){5}(?P\S+)') __set_param_re = re.compile(r'(?P\S+:)?(?P\S+)\s*=\s*(?P.+)') + __list_re = re.compile(r'^(?P\S+)\s+\S+\s+\S+\s+(?P\S+)') + __install_re = re.compile(r'(?P\S+)\s.+\s(installed|refreshed)') module = dict( argument_spec={ 'name': dict(type='list', elements='str', required=True), - 'state': dict(type='str', default='present', - choices=['absent', 'present', 'enabled', 'disabled']), + 'state': dict(type='str', default='present', choices=['absent', 'present', 'enabled', 'disabled']), 'classic': dict(type='bool', default=False), - 'channel': dict(type='str', default='stable'), + 'channel': dict(type='str'), 'options': dict(type='list', elements='str'), }, supports_check_mode=True, @@ -183,35 +190,47 @@ class Snap(StateModuleHelper): def __init_module__(self): self.runner = snap_runner(self.module) + self.vars.set("snap_status", self.snap_status(self.vars.name, self.vars.channel), output=False) + self.vars.set("snap_status_map", dict(zip(self.vars.name, self.vars.snap_status)), output=False) - def _run_multiple_commands(self, commands, actionable_names, bundle=True): + def _run_multiple_commands(self, commands, actionable_names, bundle=True, refresh=False): results_cmd = [] results_rc = [] results_out = [] results_err = [] + results_run_info = [] + + state = "refresh" if refresh else self.vars.state with self.runner(commands + ["name"]) as ctx: if bundle: - rc, out, err = ctx.run(name=actionable_names) + rc, out, err = ctx.run(state=state, name=actionable_names) results_cmd.append(commands + actionable_names) results_rc.append(rc) results_out.append(out) results_err.append(err) + results_run_info.append(ctx.run_info) else: for name in actionable_names: - rc, out, err = ctx.run(name=name) + rc, out, err = ctx.run(state=state, name=name) results_cmd.append(commands + [name]) results_rc.append(rc) results_out.append(out) results_err.append(err) + results_run_info.append(ctx.run_info) return [ '; '.join([to_native(x) for x in results_cmd]), self._first_non_zero(results_rc), '\n'.join(results_out), '\n'.join(results_err), + results_run_info, ] + def __quit_module__(self): + if self.vars.channel is None: + self.vars.channel = "stable" + def convert_json_subtree_to_map(self, json_subtree, prefix=None): option_map = {} @@ -224,7 +243,6 @@ class Snap(StateModuleHelper): if isinstance(value, (str, float, bool, numbers.Integral)): option_map[full_key] = str(value) - else: option_map.update(self.convert_json_subtree_to_map(json_subtree=value, prefix=full_key)) @@ -248,16 +266,32 @@ class Snap(StateModuleHelper): try: option_map = self.convert_json_to_map(out) - except Exception as e: self.do_raise( msg="Parsing option map returned by 'snap get {0}' triggers exception '{1}', output:\n'{2}'".format(snap_name, str(e), out)) return option_map - def is_snap_installed(self, snap_name): - rc, dummy, dummy = self.runner("_list name").run(name=snap_name) - return rc == 0 + def snap_status(self, snap_name, channel): + def _status_check(name, channel, installed): + match = [c for n, c in installed if n == name] + if not match: + return Snap.NOT_INSTALLED + if channel and channel != match[0]: + return Snap.CHANNEL_MISMATCH + else: + return Snap.INSTALLED + + with self.runner("_list") as ctx: + rc, out, err = ctx.run(check_rc=True) + out = out.split('\n')[1:] + out = [self.__list_re.match(x) for x in out] + out = [(m.group('name'), m.group('channel')) for m in out if m] + if self.verbosity >= 4: + self.vars.status_out = out + self.vars.status_run_info = ctx.run_info + + return [_status_check(n, channel, out) for n in snap_name] def is_snap_enabled(self, snap_name): with self.runner("_list name") as ctx: @@ -271,7 +305,7 @@ class Snap(StateModuleHelper): notes = match.group('notes') return "disabled" not in notes.split(',') - def process_actionable_snaps(self, actionable_snaps): + def _present(self, actionable_snaps, refresh=False): self.changed = True self.vars.snaps_installed = actionable_snaps @@ -283,12 +317,17 @@ class Snap(StateModuleHelper): has_multiple_snaps = len(actionable_snaps) > 1 if has_one_pkg_params and has_multiple_snaps: - self.vars.cmd, rc, out, err = self._run_multiple_commands(params, actionable_snaps, bundle=False) + self.vars.cmd, rc, out, err, run_info = self._run_multiple_commands(params, actionable_snaps, bundle=False, refresh=refresh) else: - self.vars.cmd, rc, out, err = self._run_multiple_commands(params, actionable_snaps) + self.vars.cmd, rc, out, err, run_info = self._run_multiple_commands(params, actionable_snaps, refresh=refresh) + if self.verbosity >= 4: + self.vars.run_info = run_info if rc == 0: - return + match_install = [self.__install_re.match(line) for line in out.split('\n')] + match_install = [m.group('name') in actionable_snaps for m in match_install if m] + if len(match_install) == len(actionable_snaps): + return classic_snap_pattern = re.compile(r'^error: This revision of snap "(?P\w+)"' r' was published using classic confinement') @@ -305,10 +344,13 @@ class Snap(StateModuleHelper): self.vars.meta('classic').set(output=True) self.vars.meta('channel').set(output=True) - actionable_snaps = [s for s in self.vars.name if not self.is_snap_installed(s)] - if actionable_snaps: - self.process_actionable_snaps(actionable_snaps) + actionable_refresh = [snap for snap in self.vars.name if self.vars.snap_status_map[snap] == Snap.CHANNEL_MISMATCH] + if actionable_refresh: + self._present(actionable_refresh, refresh=True) + actionable_install = [snap for snap in self.vars.name if self.vars.snap_status_map[snap] == Snap.NOT_INSTALLED] + if actionable_install: + self._present(actionable_install) self.set_options() @@ -316,7 +358,7 @@ class Snap(StateModuleHelper): if self.vars.options is None: return - actionable_snaps = [s for s in self.vars.name if self.is_snap_installed(s)] + actionable_snaps = [s for s in self.vars.name if self.vars.snap_status_map[s] != Snap.NOT_INSTALLED] overall_options_changed = [] for snap_name in actionable_snaps: @@ -366,7 +408,7 @@ class Snap(StateModuleHelper): if overall_options_changed: self.vars.options_changed = overall_options_changed - def _generic_state_action(self, actionable_func, actionable_var, params=None): + def _generic_state_action(self, actionable_func, actionable_var, params): actionable_snaps = [s for s in self.vars.name if actionable_func(s)] if not actionable_snaps: return @@ -374,9 +416,9 @@ class Snap(StateModuleHelper): self.vars[actionable_var] = actionable_snaps if self.check_mode: return - if params is None: - params = ['state'] - self.vars.cmd, rc, out, err = self._run_multiple_commands(params, actionable_snaps) + self.vars.cmd, rc, out, err, run_info = self._run_multiple_commands(params, actionable_snaps) + if self.verbosity >= 4: + self.vars.run_info = run_info if rc == 0: return msg = "Ooops! Snap operation failed while executing '{cmd}', please examine logs and " \ @@ -384,7 +426,7 @@ class Snap(StateModuleHelper): self.do_raise(msg=msg) def state_absent(self): - self._generic_state_action(self.is_snap_installed, "snaps_removed", ['classic', 'channel', 'state']) + self._generic_state_action(lambda s: self.vars.snap_status_map[s] != Snap.NOT_INSTALLED, "snaps_removed", ['classic', 'channel', 'state']) def state_enabled(self): self._generic_state_action(lambda s: not self.is_snap_enabled(s), "snaps_enabled", ['classic', 'channel', 'state']) diff --git a/tests/integration/targets/snap/tasks/main.yml b/tests/integration/targets/snap/tasks/main.yml index 0f24e69f3d..126c2cbbd5 100644 --- a/tests/integration/targets/snap/tasks/main.yml +++ b/tests/integration/targets/snap/tasks/main.yml @@ -8,236 +8,10 @@ # 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: Has-snap block +- name: Has-snap include when: has_snap block: - - name: Make sure package is not installed (hello-world) - community.general.snap: - name: hello-world - state: absent - - - name: Install package (hello-world) (check mode) - community.general.snap: - name: hello-world - state: present - register: install_check - check_mode: true - - - name: Install package (hello-world) - community.general.snap: - name: hello-world - state: present - register: install - - - name: Install package again (hello-world) (check mode) - community.general.snap: - name: hello-world - state: present - register: install_again_check - check_mode: true - - - name: Install package again (hello-world) - community.general.snap: - name: hello-world - state: present - register: install_again - - - name: Assert package has been installed just once (hello-world) - assert: - that: - - install is changed - - install_check is changed - - install_again is not changed - - install_again_check is not changed - - - name: Check package has been installed correctly (hello-world) - command: hello-world - environment: - PATH: /snap/bin/ - - - name: Remove package (hello-world) (check mode) - community.general.snap: - name: hello-world - state: absent - register: remove_check - check_mode: true - - - name: Remove package (hello-world) - community.general.snap: - name: hello-world - state: absent - register: remove - - - name: Remove package again (hello-world) (check mode) - community.general.snap: - name: hello-world - state: absent - register: remove_again_check - check_mode: true - - - name: Remove package again (hello-world) - community.general.snap: - name: hello-world - state: absent - register: remove_again - - - name: Assert package has been removed just once (hello-world) - assert: - that: - - remove is changed - - remove_check is changed - - remove_again is not changed - - remove_again_check is not changed - - - name: Make sure package from classic snap is not installed (nvim) - community.general.snap: - name: nvim - state: absent - - - name: Install package from classic snap (nvim) - community.general.snap: - name: nvim - state: present - classic: true - register: classic_install - - # testing classic idempotency - - name: Install package from classic snap again (nvim) - community.general.snap: - name: nvim - state: present - classic: true - register: classic_install_again - - - name: Assert package has been installed just once (nvim) - assert: - that: - - classic_install is changed - - classic_install_again is not changed - - # this is just testing if a package which has been installed - # with true classic can be removed without setting classic to true - - name: Remove package from classic snap without setting classic to true (nvim) - community.general.snap: - name: nvim - state: absent - register: classic_remove_without_true_classic - - - name: Remove package from classic snap with setting classic to true (nvim) - community.general.snap: - name: nvim - state: absent - classic: true - register: classic_remove_with_true_classic - - - name: Assert package has been removed without setting classic to true (nvim) - assert: - that: - - classic_remove_without_true_classic is changed - - classic_remove_with_true_classic is not changed - - - - name: Make sure package is not installed (uhttpd) - community.general.snap: - name: uhttpd - state: absent - - - name: Install package (uhttpd) - community.general.snap: - name: uhttpd - state: present - register: install - - - name: Install package (uhttpd) - community.general.snap: - name: uhttpd - state: present - options: - - "listening-port=8080" - register: install_with_option - - - name: Install package again with option (uhttpd) - community.general.snap: - name: uhttpd - state: present - options: - - "listening-port=8080" - register: install_with_option_again - - - name: Install package again with different options (uhttpd) - community.general.snap: - name: uhttpd - state: present - options: - - "listening-port=8088" - - "document-root-dir=/tmp" - register: install_with_option_changed - - - name: Remove package (uhttpd) - community.general.snap: - name: uhttpd - state: absent - register: remove - - - name: Assert package has been installed with options just once and only changed options trigger a change (uhttpd) - assert: - that: - - install is changed - - install_with_option is changed - - "install_with_option.options_changed[0] == 'uhttpd:listening-port=8080'" - - install_with_option_again is not changed - - install_with_option_changed is changed - - "'uhttpd:listening-port=8088' in install_with_option_changed.options_changed" - - "'uhttpd:document-root-dir=/tmp' in install_with_option_changed.options_changed" - - "'uhttpd:listening-port=8080' not in install_with_option_changed.options_changed" - - remove is changed - - - name: Install two packages at the same time - community.general.snap: - name: - - hello-world - - uhttpd - state: present - register: install_two - - - name: Install two packages at the same time (again) - community.general.snap: - name: - - hello-world - - uhttpd - state: present - register: install_two_again - - - name: Remove packages (hello-world & uhttpd) - community.general.snap: - name: - - hello-world - - uhttpd - state: absent - register: install_two_remove - - - name: Remove packages again (hello-world & uhttpd) - community.general.snap: - name: - - hello-world - - uhttpd - state: absent - register: install_two_remove_again - - - name: Assert installation of two packages - assert: - that: - - install_two is changed - - "'hello-world' in install_two.snaps_installed" - - "'uhttpd' in install_two.snaps_installed" - - install_two.snaps_removed is not defined - - install_two_again is not changed - - install_two_again.snaps_installed is not defined - - install_two_again.snaps_removed is not defined - - install_two_remove is changed - - install_two_again.snaps_installed is not defined - - "'hello-world' in install_two_remove.snaps_removed" - - "'uhttpd' in install_two_remove.snaps_removed" - - install_two_remove_again is not changed - - install_two_remove_again.snaps_installed is not defined - - install_two_remove_again.snaps_removed is not defined + - name: Include test + ansible.builtin.include_tasks: test.yml + - name: Include test_channel + ansible.builtin.include_tasks: test_channel.yml diff --git a/tests/integration/targets/snap/tasks/test.yml b/tests/integration/targets/snap/tasks/test.yml new file mode 100644 index 0000000000..3a77704b3e --- /dev/null +++ b/tests/integration/targets/snap/tasks/test.yml @@ -0,0 +1,235 @@ +--- +# 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: Make sure package is not installed (hello-world) + community.general.snap: + name: hello-world + state: absent + +- name: Install package (hello-world) (check mode) + community.general.snap: + name: hello-world + state: present + register: install_check + check_mode: true + +- name: Install package (hello-world) + community.general.snap: + name: hello-world + state: present + register: install + +- name: Install package again (hello-world) (check mode) + community.general.snap: + name: hello-world + state: present + register: install_again_check + check_mode: true + +- name: Install package again (hello-world) + community.general.snap: + name: hello-world + state: present + register: install_again + +- name: Assert package has been installed just once (hello-world) + assert: + that: + - install is changed + - install_check is changed + - install_again is not changed + - install_again_check is not changed + +- name: Check package has been installed correctly (hello-world) + command: hello-world + environment: + PATH: /snap/bin/ + +- name: Remove package (hello-world) (check mode) + community.general.snap: + name: hello-world + state: absent + register: remove_check + check_mode: true + +- name: Remove package (hello-world) + community.general.snap: + name: hello-world + state: absent + register: remove + +- name: Remove package again (hello-world) (check mode) + community.general.snap: + name: hello-world + state: absent + register: remove_again_check + check_mode: true + +- name: Remove package again (hello-world) + community.general.snap: + name: hello-world + state: absent + register: remove_again + +- name: Assert package has been removed just once (hello-world) + assert: + that: + - remove is changed + - remove_check is changed + - remove_again is not changed + - remove_again_check is not changed + +- name: Make sure package from classic snap is not installed (nvim) + community.general.snap: + name: nvim + state: absent + +- name: Install package from classic snap (nvim) + community.general.snap: + name: nvim + state: present + classic: true + register: classic_install + +# testing classic idempotency +- name: Install package from classic snap again (nvim) + community.general.snap: + name: nvim + state: present + classic: true + register: classic_install_again + +- name: Assert package has been installed just once (nvim) + assert: + that: + - classic_install is changed + - classic_install_again is not changed + +# this is just testing if a package which has been installed +# with true classic can be removed without setting classic to true +- name: Remove package from classic snap without setting classic to true (nvim) + community.general.snap: + name: nvim + state: absent + register: classic_remove_without_true_classic + +- name: Remove package from classic snap with setting classic to true (nvim) + community.general.snap: + name: nvim + state: absent + classic: true + register: classic_remove_with_true_classic + +- name: Assert package has been removed without setting classic to true (nvim) + assert: + that: + - classic_remove_without_true_classic is changed + - classic_remove_with_true_classic is not changed + + +- name: Make sure package is not installed (uhttpd) + community.general.snap: + name: uhttpd + state: absent + +- name: Install package (uhttpd) + community.general.snap: + name: uhttpd + state: present + register: install + +- name: Install package (uhttpd) + community.general.snap: + name: uhttpd + state: present + options: + - "listening-port=8080" + register: install_with_option + +- name: Install package again with option (uhttpd) + community.general.snap: + name: uhttpd + state: present + options: + - "listening-port=8080" + register: install_with_option_again + +- name: Install package again with different options (uhttpd) + community.general.snap: + name: uhttpd + state: present + options: + - "listening-port=8088" + - "document-root-dir=/tmp" + register: install_with_option_changed + +- name: Remove package (uhttpd) + community.general.snap: + name: uhttpd + state: absent + register: remove + +- name: Assert package has been installed with options just once and only changed options trigger a change (uhttpd) + assert: + that: + - install is changed + - install_with_option is changed + - "install_with_option.options_changed[0] == 'uhttpd:listening-port=8080'" + - install_with_option_again is not changed + - install_with_option_changed is changed + - "'uhttpd:listening-port=8088' in install_with_option_changed.options_changed" + - "'uhttpd:document-root-dir=/tmp' in install_with_option_changed.options_changed" + - "'uhttpd:listening-port=8080' not in install_with_option_changed.options_changed" + - remove is changed + +- name: Install two packages at the same time + community.general.snap: + name: + - hello-world + - uhttpd + state: present + register: install_two + +- name: Install two packages at the same time (again) + community.general.snap: + name: + - hello-world + - uhttpd + state: present + register: install_two_again + +- name: Remove packages (hello-world & uhttpd) + community.general.snap: + name: + - hello-world + - uhttpd + state: absent + register: install_two_remove + +- name: Remove packages again (hello-world & uhttpd) + community.general.snap: + name: + - hello-world + - uhttpd + state: absent + register: install_two_remove_again + +- name: Assert installation of two packages + assert: + that: + - install_two is changed + - "'hello-world' in install_two.snaps_installed" + - "'uhttpd' in install_two.snaps_installed" + - install_two.snaps_removed is not defined + - install_two_again is not changed + - install_two_again.snaps_installed is not defined + - install_two_again.snaps_removed is not defined + - install_two_remove is changed + - install_two_again.snaps_installed is not defined + - "'hello-world' in install_two_remove.snaps_removed" + - "'uhttpd' in install_two_remove.snaps_removed" + - install_two_remove_again is not changed + - install_two_remove_again.snaps_installed is not defined + - install_two_remove_again.snaps_removed is not defined diff --git a/tests/integration/targets/snap/tasks/test_channel.yml b/tests/integration/targets/snap/tasks/test_channel.yml new file mode 100644 index 0000000000..135ee1825e --- /dev/null +++ b/tests/integration/targets/snap/tasks/test_channel.yml @@ -0,0 +1,46 @@ +--- +# 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: Make sure package is not installed (microk8s) + community.general.snap: + name: microk8s + state: absent + +# Test for https://github.com/ansible-collections/community.general/issues/1606 +- name: Install package (microk8s) + community.general.snap: + name: microk8s + classic: true + state: present + register: install_microk8s + +- name: Install package with channel (microk8s) + community.general.snap: + name: microk8s + classic: true + channel: 1.20/stable + state: present + register: install_microk8s_chan + +- name: Install package with channel (microk8s) again + community.general.snap: + name: microk8s + classic: true + channel: 1.20/stable + state: present + register: install_microk8s_chan_again + +- name: Remove package (microk8s) + community.general.snap: + name: microk8s + state: absent + register: remove_microk8s + +- assert: + that: + - install_microk8s is changed + - install_microk8s_chan is changed + - install_microk8s_chan_again is not changed + - remove_microk8s is changed From 58958fc417c832d024c6a6e0ddf6f7ceaae656e6 Mon Sep 17 00:00:00 2001 From: Victor Martinez Date: Tue, 6 Jun 2023 20:54:58 +0200 Subject: [PATCH 0035/1451] opentelemetry: add span event attributes (#6531) * add span event attributes (task name and host name) * add fragment * refactor: use set_attributes * Add same span attributes to the event * chore: change description in the fragment * as mentioned in the code review * use flag to disable the attributes in logs there are some vendors that might not require those attributes since those details are shown in the UI when accessing the spans, i.e.: jaeger * Update plugins/callback/opentelemetry.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- ...531-opentelemetry-add-event-attributes.yml | 2 + plugins/callback/opentelemetry.py | 61 +++++++++++++------ 2 files changed, 44 insertions(+), 19 deletions(-) create mode 100644 changelogs/fragments/6531-opentelemetry-add-event-attributes.yml diff --git a/changelogs/fragments/6531-opentelemetry-add-event-attributes.yml b/changelogs/fragments/6531-opentelemetry-add-event-attributes.yml new file mode 100644 index 0000000000..9121d9ac5c --- /dev/null +++ b/changelogs/fragments/6531-opentelemetry-add-event-attributes.yml @@ -0,0 +1,2 @@ +minor_changes: + - opentelemetry callback plugin - add span attributes in the span event (https://github.com/ansible-collections/community.general/pull/6531). diff --git a/plugins/callback/opentelemetry.py b/plugins/callback/opentelemetry.py index e00e1d71ad..df2fb5cee6 100644 --- a/plugins/callback/opentelemetry.py +++ b/plugins/callback/opentelemetry.py @@ -73,6 +73,17 @@ DOCUMENTATION = ''' - section: callback_opentelemetry key: disable_logs version_added: 5.8.0 + disable_attributes_in_logs: + default: false + type: bool + description: + - Disable populating span attributes to the logs. + env: + - name: ANSIBLE_OPENTELEMETRY_DISABLE_ATTRIBUTES_IN_LOGS + ini: + - section: callback_opentelemetry + key: disable_attributes_in_logs + version_added: 7.1.0 requirements: - opentelemetry-api (Python library) - opentelemetry-exporter-otlp (Python library) @@ -244,7 +255,7 @@ class OpenTelemetrySource(object): task.dump = dump task.add_host(HostData(host_uuid, host_name, status, result)) - def generate_distributed_traces(self, otel_service_name, ansible_playbook, tasks_data, status, traceparent, disable_logs): + def generate_distributed_traces(self, otel_service_name, ansible_playbook, tasks_data, status, traceparent, disable_logs, disable_attributes_in_logs): """ generate distributed traces from the collected TaskData and HostData """ tasks = [] @@ -280,9 +291,9 @@ class OpenTelemetrySource(object): for task in tasks: for host_uuid, host_data in task.host_data.items(): with tracer.start_as_current_span(task.name, start_time=task.start, end_on_exit=False) as span: - self.update_span_data(task, host_data, span, disable_logs) + self.update_span_data(task, host_data, span, disable_logs, disable_attributes_in_logs) - def update_span_data(self, task_data, host_data, span, disable_logs): + 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) @@ -315,39 +326,47 @@ class OpenTelemetrySource(object): status = Status(status_code=StatusCode.UNSET) span.set_status(status) + + # Create the span and log attributes + attributes = { + "ansible.task.module": task_data.action, + "ansible.task.message": message, + "ansible.task.name": name, + "ansible.task.result": rc, + "ansible.task.host.name": host_data.name, + "ansible.task.host.status": host_data.status + } if isinstance(task_data.args, dict) and "gather_facts" not in task_data.action: names = tuple(self.transform_ansible_unicode_to_str(k) for k in task_data.args.keys()) values = tuple(self.transform_ansible_unicode_to_str(k) for k in task_data.args.values()) - self.set_span_attribute(span, ("ansible.task.args.name"), names) - self.set_span_attribute(span, ("ansible.task.args.value"), values) - self.set_span_attribute(span, "ansible.task.module", task_data.action) - self.set_span_attribute(span, "ansible.task.message", message) - self.set_span_attribute(span, "ansible.task.name", name) - self.set_span_attribute(span, "ansible.task.result", rc) - self.set_span_attribute(span, "ansible.task.host.name", host_data.name) - self.set_span_attribute(span, "ansible.task.host.status", host_data.status) + attributes[("ansible.task.args.name")] = names + attributes[("ansible.task.args.value")] = values + + self.set_span_attributes(span, attributes) + # This will allow to enrich the service map self.add_attributes_for_service_map_if_possible(span, task_data) # Send logs if not disable_logs: - span.add_event(task_data.dump) - span.end(end_time=host_data.finish) + # This will avoid populating span attributes to the logs + span.add_event(task_data.dump, attributes={} if disable_attributes_in_logs else attributes) + span.end(end_time=host_data.finish) - def set_span_attribute(self, span, attributeName, attributeValue): - """ update the span attribute with the given attribute and value if not None """ + def set_span_attributes(self, span, attributes): + """ update the span attributes with the given attributes if not None """ if span is None and self._display is not None: self._display.warning('span object is None. Please double check if that is expected.') else: - if attributeValue is not None: - span.set_attribute(attributeName, attributeValue) + if attributes is not None: + span.set_attributes(attributes) def add_attributes_for_service_map_if_possible(self, span, task_data): """Update the span attributes with the service that the task interacted with, if possible.""" redacted_url = self.parse_and_redact_url_if_possible(task_data.args) if redacted_url: - self.set_span_attribute(span, "http.url", redacted_url.geturl()) + span.set_attribute("http.url", redacted_url.geturl()) @staticmethod def parse_and_redact_url_if_possible(args): @@ -434,6 +453,7 @@ class CallbackModule(CallbackBase): def __init__(self, display=None): super(CallbackModule, self).__init__(display=display) self.hide_task_arguments = None + self.disable_attributes_in_logs = None self.disable_logs = None self.otel_service_name = None self.ansible_playbook = None @@ -465,6 +485,8 @@ class CallbackModule(CallbackBase): self.hide_task_arguments = self.get_option('hide_task_arguments') + self.disable_attributes_in_logs = self.get_option('disable_attributes_in_logs') + self.disable_logs = self.get_option('disable_logs') self.otel_service_name = self.get_option('otel_service_name') @@ -562,7 +584,8 @@ class CallbackModule(CallbackBase): self.tasks_data, status, self.traceparent, - self.disable_logs + self.disable_logs, + self.disable_attributes_in_logs ) def v2_runner_on_async_failed(self, result, **kwargs): From 2cfbcb4efda5412a749b138be2fd85c4de8082ae Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 6 Jun 2023 21:11:54 +0200 Subject: [PATCH 0036/1451] CI: ansible-core devel drops support for Python 3.5 (#6629) ansible-core devel drops support for Python 3.5. --- .azure-pipelines/azure-pipelines.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.azure-pipelines/azure-pipelines.yml b/.azure-pipelines/azure-pipelines.yml index 2604e9ff84..0f49a51c1d 100644 --- a/.azure-pipelines/azure-pipelines.yml +++ b/.azure-pipelines/azure-pipelines.yml @@ -123,7 +123,6 @@ stages: testFormat: devel/units/{0}/1 targets: - test: 2.7 - - test: 3.5 - test: 3.6 - test: 3.7 - test: 3.8 @@ -139,6 +138,7 @@ stages: nameFormat: Python {0} testFormat: 2.15/units/{0}/1 targets: + - test: 3.5 - test: "3.10" - stage: Units_2_14 displayName: Units 2.14 From 07a5f07eaa349dcc603f5fbe5599c154f3e948d3 Mon Sep 17 00:00:00 2001 From: Philippe Gauthier Date: Fri, 9 Jun 2023 00:17:44 -0400 Subject: [PATCH 0037/1451] Inspq keycloak user module (#6476) * Add Keycloak User Module * keycloak_user refactoring * Add changelog fragment for breaking changes * Fix Copyright for keycloak_user module * Add keycloak_user module to BOTMETA * Remove ANSIBLE_METADATA and override aliases for auth_username argument spec * Update plugins/modules/keycloak_user.py Updated short description Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Fix keycloak_user module description Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Dedent and use FQCN's for examples in keycloak_user module * Fix examples in keycloak_user module documentation * keycloak_user refactoring * Add changelog fragment for breaking changes * Remove ANSIBLE_METADATA and override aliases for auth_username argument spec * Fix merge error on keycloak_user module changelogs fragment * Add integration test for keycloak_user module * Fix yamllint errors in keycloak_user integration tests * Add README.md and fix integration tests for keycloak_user module * Add Copyright and license in README.md integration tests keycloak_user module * Update changelogs/fragments/6476-new-keycloak-user.module.yml Co-authored-by: Felix Fontein * Fix argument_spec auth_username aliases for keycloak_user module * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Add units tests for keycloak_user module * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Remove default value for keycloak_user enabled module parameter * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * keycloak_user refactoring * Remove ANSIBLE_METADATA and override aliases for auth_username argument spec * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Dedent and use FQCN's for examples in keycloak_user module * Fix examples in keycloak_user module documentation * keycloak_user refactoring * Add changelog fragment for breaking changes * Remove ANSIBLE_METADATA and override aliases for auth_username argument spec * Fix merge error on keycloak_user module changelogs fragment * Update changelogs/fragments/6476-new-keycloak-user.module.yml Co-authored-by: Felix Fontein * Fix argument_spec auth_username aliases for keycloak_user module * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Remove github Workflow * Remove bugfix from changelog fragment * Fix indentation in examples for keycloak_user module * Fix examples in documentation for keycloak_user module * Remove PR 6476 changelog fragment * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_user.py Co-authored-by: Felix Fontein * Restore ansible-test.yml * Add msg output and RETURN documentation for keycloak_user module * Fix RETURN documentation for keycloak_user module * Fix msg for keycloak_user module --------- Co-authored-by: Felix Fontein --- .github/BOTMETA.yml | 2 + .../identity/keycloak/keycloak.py | 251 ++++++++ plugins/modules/keycloak_user.py | 542 ++++++++++++++++++ .../targets/keycloak_user/README.md | 21 + .../integration/targets/keycloak_user/aliases | 4 + .../targets/keycloak_user/tasks/main.yml | 114 ++++ .../targets/keycloak_user/vars/main.yml | 46 ++ .../plugins/modules/test_keycloak_user.py | 354 ++++++++++++ 8 files changed, 1334 insertions(+) create mode 100644 plugins/modules/keycloak_user.py create mode 100644 tests/integration/targets/keycloak_user/README.md create mode 100644 tests/integration/targets/keycloak_user/aliases create mode 100644 tests/integration/targets/keycloak_user/tasks/main.yml create mode 100644 tests/integration/targets/keycloak_user/vars/main.yml create mode 100644 tests/unit/plugins/modules/test_keycloak_user.py diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 926054ae99..4a0ddf7ab3 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -707,6 +707,8 @@ files: maintainers: fynncfchen $modules/keycloak_role.py: maintainers: laurpaum + $modules/keycloak_user.py: + maintainers: elfelip $modules/keycloak_user_federation.py: maintainers: laurpaum $modules/keycloak_user_rolemapping.py: diff --git a/plugins/module_utils/identity/keycloak/keycloak.py b/plugins/module_utils/identity/keycloak/keycloak.py index c35ca43c2c..20314ede36 100644 --- a/plugins/module_utils/identity/keycloak/keycloak.py +++ b/plugins/module_utils/identity/keycloak/keycloak.py @@ -9,6 +9,7 @@ __metaclass__ = type import json import traceback +import copy from ansible.module_utils.urls import open_url from ansible.module_utils.six.moves.urllib.parse import urlencode, quote @@ -64,6 +65,14 @@ URL_CLIENT_GROUP_ROLEMAPPINGS_AVAILABLE = "{url}/admin/realms/{realm}/groups/{id URL_CLIENT_GROUP_ROLEMAPPINGS_COMPOSITE = "{url}/admin/realms/{realm}/groups/{id}/role-mappings/clients/{client}/composite" URL_USERS = "{url}/admin/realms/{realm}/users" +URL_USER = "{url}/admin/realms/{realm}/users/{id}" +URL_USER_ROLE_MAPPINGS = "{url}/admin/realms/{realm}/users/{id}/role-mappings" +URL_USER_REALM_ROLE_MAPPINGS = "{url}/admin/realms/{realm}/users/{id}/role-mappings/realm" +URL_USER_CLIENTS_ROLE_MAPPINGS = "{url}/admin/realms/{realm}/users/{id}/role-mappings/clients" +URL_USER_CLIENT_ROLE_MAPPINGS = "{url}/admin/realms/{realm}/users/{id}/role-mappings/clients/{client_id}" +URL_USER_GROUPS = "{url}/admin/realms/{realm}/users/{id}/groups" +URL_USER_GROUP = "{url}/admin/realms/{realm}/users/{id}/groups/{group_id}" + URL_CLIENT_SERVICE_ACCOUNT_USER = "{url}/admin/realms/{realm}/clients/{id}/service-account-user" URL_CLIENT_USER_ROLEMAPPINGS = "{url}/admin/realms/{realm}/users/{id}/role-mappings/clients/{client}" URL_CLIENT_USER_ROLEMAPPINGS_AVAILABLE = "{url}/admin/realms/{realm}/users/{id}/role-mappings/clients/{client}/available" @@ -2382,3 +2391,245 @@ class KeycloakAPI(object): validate_certs=self.validate_certs) except Exception as e: self.module.fail_json(msg='Could not delete scope %s for client %s in realm %s: %s' % (id, client_id, realm, str(e))) + + def get_user_by_id(self, user_id, realm='master'): + """ + Get a User by its ID. + :param user_id: ID of the user. + :param realm: Realm + :return: Representation of the user. + """ + try: + user_url = URL_USER.format( + url=self.baseurl, + realm=realm, + id=user_id) + userrep = json.load( + open_url( + user_url, + method='GET', + headers=self.restheaders)) + return userrep + except Exception as e: + self.module.fail_json(msg='Could not get user %s in realm %s: %s' + % (user_id, realm, str(e))) + + def create_user(self, userrep, realm='master'): + """ + Create a new User. + :param userrep: Representation of the user to create + :param realm: Realm + :return: Representation of the user created. + """ + try: + if 'attributes' in userrep and isinstance(userrep['attributes'], list): + attributes = copy.deepcopy(userrep['attributes']) + userrep['attributes'] = self.convert_user_attributes_to_keycloak_dict(attributes=attributes) + users_url = URL_USERS.format( + url=self.baseurl, + realm=realm) + open_url(users_url, + method='POST', + headers=self.restheaders, + data=json.dumps(userrep)) + created_user = self.get_user_by_username( + username=userrep['username'], + realm=realm) + return created_user + except Exception as e: + self.module.fail_json(msg='Could not create user %s in realm %s: %s' + % (userrep['username'], realm, str(e))) + + def convert_user_attributes_to_keycloak_dict(self, attributes): + keycloak_user_attributes_dict = {} + for attribute in attributes: + if ('state' not in attribute or attribute['state'] == 'present') and 'name' in attribute: + keycloak_user_attributes_dict[attribute['name']] = attribute['values'] if 'values' in attribute else [] + return keycloak_user_attributes_dict + + def convert_keycloak_user_attributes_dict_to_module_list(self, attributes): + module_attributes_list = [] + for key in attributes: + attr = {} + attr['name'] = key + attr['values'] = attributes[key] + module_attributes_list.append(attr) + return module_attributes_list + + def update_user(self, userrep, realm='master'): + """ + Update a User. + :param userrep: Representation of the user to update. This representation must include the ID of the user. + :param realm: Realm + :return: Representation of the updated user. + """ + try: + if 'attributes' in userrep and isinstance(userrep['attributes'], list): + attributes = copy.deepcopy(userrep['attributes']) + userrep['attributes'] = self.convert_user_attributes_to_keycloak_dict(attributes=attributes) + user_url = URL_USER.format( + url=self.baseurl, + realm=realm, + id=userrep["id"]) + open_url( + user_url, + method='PUT', + headers=self.restheaders, + data=json.dumps(userrep)) + updated_user = self.get_user_by_id( + user_id=userrep['id'], + realm=realm) + return updated_user + except Exception as e: + self.module.fail_json(msg='Could not update user %s in realm %s: %s' + % (userrep['username'], realm, str(e))) + + def delete_user(self, user_id, realm='master'): + """ + Delete a User. + :param user_id: ID of the user to be deleted + :param realm: Realm + :return: HTTP response. + """ + try: + user_url = URL_USER.format( + url=self.baseurl, + realm=realm, + id=user_id) + return open_url( + user_url, + method='DELETE', + headers=self.restheaders) + except Exception as e: + self.module.fail_json(msg='Could not delete user %s in realm %s: %s' + % (user_id, realm, str(e))) + + def get_user_groups(self, user_id, realm='master'): + """ + Get groups for a user. + :param user_id: User ID + :param realm: Realm + :return: Representation of the client groups. + """ + try: + groups = [] + user_groups_url = URL_USER_GROUPS.format( + url=self.baseurl, + realm=realm, + id=user_id) + user_groups = json.load( + open_url( + user_groups_url, + method='GET', + headers=self.restheaders)) + for user_group in user_groups: + groups.append(user_group["name"]) + return groups + except Exception as e: + self.module.fail_json(msg='Could not get groups for user %s in realm %s: %s' + % (user_id, realm, str(e))) + + def add_user_in_group(self, user_id, group_id, realm='master'): + """ + Add a user to a group. + :param user_id: User ID + :param group_id: Group Id to add the user to. + :param realm: Realm + :return: HTTP Response + """ + try: + user_group_url = URL_USER_GROUP.format( + url=self.baseurl, + realm=realm, + id=user_id, + group_id=group_id) + return open_url( + user_group_url, + method='PUT', + headers=self.restheaders) + except Exception as e: + self.module.fail_json(msg='Could not add user %s in group %s in realm %s: %s' + % (user_id, group_id, realm, str(e))) + + def remove_user_from_group(self, user_id, group_id, realm='master'): + """ + Remove a user from a group for a user. + :param user_id: User ID + :param group_id: Group Id to add the user to. + :param realm: Realm + :return: HTTP response + """ + try: + user_group_url = URL_USER_GROUP.format( + url=self.baseurl, + realm=realm, + id=user_id, + group_id=group_id) + return open_url( + user_group_url, + method='DELETE', + headers=self.restheaders) + except Exception as e: + self.module.fail_json(msg='Could not remove user %s from group %s in realm %s: %s' + % (user_id, group_id, realm, str(e))) + + def update_user_groups_membership(self, userrep, groups, realm='master'): + """ + Update user's group membership + :param userrep: Representation of the user. This representation must include the ID. + :param realm: Realm + :return: True if group membership has been changed. False Otherwise. + """ + changed = False + try: + user_existing_groups = self.get_user_groups( + user_id=userrep['id'], + realm=realm) + groups_to_add_and_remove = self.extract_groups_to_add_to_and_remove_from_user(groups) + # If group membership need to be changed + if not is_struct_included(groups_to_add_and_remove['add'], user_existing_groups): + # Get available goups in the realm + realm_groups = self.get_groups(realm=realm) + for realm_group in realm_groups: + if "name" in realm_group and realm_group["name"] in groups_to_add_and_remove['add']: + self.add_user_in_group( + user_id=userrep["id"], + group_id=realm_group["id"], + realm=realm) + changed = True + elif "name" in realm_group and realm_group['name'] in groups_to_add_and_remove['remove']: + self.remove_user_from_group( + user_id=userrep['id'], + group_id=realm_group['id'], + realm=realm) + changed = True + return changed + except Exception as e: + self.module.fail_json(msg='Could not update group membership for user %s in realm %s: %s' + % (userrep['id]'], realm, str(e))) + + def extract_groups_to_add_to_and_remove_from_user(self, groups): + groups_extract = {} + groups_to_add = [] + groups_to_remove = [] + if isinstance(groups, list) and len(groups) > 0: + for group in groups: + group_name = group['name'] if isinstance(group, dict) and 'name' in group else group + if isinstance(group, dict) and ('state' not in group or group['state'] == 'present'): + groups_to_add.append(group_name) + else: + groups_to_remove.append(group_name) + groups_extract['add'] = groups_to_add + groups_extract['remove'] = groups_to_remove + + return groups_extract + + def convert_user_group_list_of_str_to_list_of_dict(self, groups): + list_of_groups = [] + if isinstance(groups, list) and len(groups) > 0: + for group in groups: + if isinstance(group, str): + group_dict = {} + group_dict['name'] = group + list_of_groups.append(group_dict) + return list_of_groups diff --git a/plugins/modules/keycloak_user.py b/plugins/modules/keycloak_user.py new file mode 100644 index 0000000000..b6d2bfa747 --- /dev/null +++ b/plugins/modules/keycloak_user.py @@ -0,0 +1,542 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright (c) 2019, INSPQ (@elfelip) +# 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 = ''' +--- +module: keycloak_user +short_description: Create and configure a user in Keycloak +description: + - This module creates, removes, or updates Keycloak users. +version_added: 7.1.0 +options: + 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: + - 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 C(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 C(true), allows to remove user and recreate it. + type: bool + default: false +extends_documentation_fragment: + - community.general.keycloak + - community.general.attributes +attributes: + check_mode: + support: full + diff_mode: + support: full +notes: + - The module does not modify the user ID of an existing user. +author: + - Philippe Gauthier (@elfelip) +''' + +EXAMPLES = ''' +- name: Create a user user1 + community.general.keycloak_user: + auth_keycloak_url: http://localhost:8080/auth + auth_username: admin + auth_password: password + realm: master + username: user1 + firstName: user1 + lastName: user1 + email: user1 + enabled: true + emailVerified: false + credentials: + - type: password + value: password + temporary: false + attributes: + - name: attr1 + values: + - value1 + state: present + - name: attr2 + values: + - value2 + state: absent + groups: + - name: group1 + state: present + state: present + +- name: Re-create a User + community.general.keycloak_user: + auth_keycloak_url: http://localhost:8080/auth + auth_username: admin + auth_password: password + realm: master + username: user1 + firstName: user1 + lastName: user1 + email: user1 + enabled: true + emailVerified: false + credentials: + - type: password + value: password + temporary: false + attributes: + - name: attr1 + values: + - value1 + state: present + - name: attr2 + values: + - value2 + state: absent + groups: + - name: group1 + state: present + state: present + +- name: Re-create a User + community.general.keycloak_user: + auth_keycloak_url: http://localhost:8080/auth + auth_username: admin + auth_password: password + realm: master + username: user1 + firstName: user1 + lastName: user1 + email: user1 + enabled: true + emailVerified: false + credentials: + - type: password + value: password + temporary: false + attributes: + - name: attr1 + values: + - value1 + state: present + - name: attr2 + values: + - value2 + state: absent + groups: + - name: group1 + state: present + state: present + force: true + +- name: Remove User + community.general.keycloak_user: + auth_keycloak_url: http://localhost:8080/auth + auth_username: admin + auth_password: password + realm: master + username: user1 + state: absent +''' + +RETURN = ''' +msg: + description: Message as to what action was taken. + returned: always + type: str + sample: User f18c709c-03d6-11ee-970b-c74bf2721112 created +proposed: + description: Representation of the proposed user. + returned: on success + type: dict +existing: + description: Representation of the existing user. + returned: on success + type: dict +end_state: + description: Representation of the user after module execution + returned: on success + type: dict +changed: + description: Return C(true) if the operation changed the user on the keycloak server, C(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 +import copy + + +def main(): + argument_spec = keycloak_argument_spec() + argument_spec['auth_username']['aliases'] = [] + credential_spec = dict( + type=dict(type='str', required=True), + value=dict(type='str', required=True), + temporary=dict(type='bool', default=False) + ) + client_consents_spec = dict( + client_id=dict(type='str', required=True, aliases=['clientId']), + roles=dict(type='list', elements='str', required=True) + ) + attributes_spec = dict( + name=dict(type='str'), + values=dict(type='list', elements='str'), + state=dict(type='str', choices=['present', 'absent'], default='present') + ) + groups_spec = dict( + name=dict(type='str'), + state=dict(type='str', choices=['present', 'absent'], default='present') + ) + meta_args = dict( + realm=dict(type='str', default='master'), + self=dict(type='str'), + id=dict(type='str'), + username=dict(type='str', required=True), + first_name=dict(type='str', aliases=['firstName']), + last_name=dict(type='str', aliases=['lastName']), + email=dict(type='str'), + enabled=dict(type='bool'), + email_verified=dict(type='bool', default=False, aliases=['emailVerified']), + federation_link=dict(type='str', aliases=['federationLink']), + service_account_client_id=dict(type='str', aliases=['serviceAccountClientId']), + attributes=dict(type='list', elements='dict', options=attributes_spec), + access=dict(type='dict'), + groups=dict(type='list', default=[], elements='dict', options=groups_spec), + disableable_credential_types=dict(type='list', default=[], aliases=['disableableCredentialTypes'], elements='str'), + required_actions=dict(type='list', default=[], aliases=['requiredActions'], elements='str'), + credentials=dict(type='list', default=[], elements='dict', options=credential_spec), + federated_identities=dict(type='list', default=[], aliases=['federatedIdentities'], elements='str'), + client_consents=dict(type='list', default=[], aliases=['clientConsents'], elements='dict', options=client_consents_spec), + origin=dict(type='str'), + state=dict(choices=["absent", "present"], default='present'), + force=dict(type='bool', default=False), + ) + argument_spec.update(meta_args) + + module = AnsibleModule(argument_spec=argument_spec, + supports_check_mode=True, + required_one_of=([['token', 'auth_realm', 'auth_username', 'auth_password']]), + required_together=([['auth_realm', 'auth_username', 'auth_password']])) + + result = dict(changed=False, msg='', diff={}, proposed={}, existing={}, end_state={}) + + # Obtain access token, initialize API + try: + connection_header = get_token(module.params) + except KeycloakError as e: + module.fail_json(msg=str(e)) + + kc = KeycloakAPI(module, connection_header) + + realm = module.params.get('realm') + state = module.params.get('state') + force = module.params.get('force') + username = module.params.get('username') + groups = module.params.get('groups') + + # Filter and map the parameters names that apply to the user + user_params = [x for x in module.params + if x not in list(keycloak_argument_spec().keys()) + ['state', 'realm', 'force', 'groups'] and + module.params.get(x) is not None] + + before_user = kc.get_user_by_username(username=username, realm=realm) + + if before_user is None: + before_user = {} + + changeset = {} + + for param in user_params: + new_param_value = module.params.get(param) + if param == 'attributes' and param in before_user: + old_value = kc.convert_keycloak_user_attributes_dict_to_module_list(attributes=before_user['attributes']) + else: + old_value = before_user[param] if param in before_user else None + if new_param_value != old_value: + if old_value is not None and param == 'attributes': + for old_attribute in old_value: + old_attribute_found = False + for new_attribute in new_param_value: + if new_attribute['name'] == old_attribute['name']: + old_attribute_found = True + if not old_attribute_found: + new_param_value.append(copy.deepcopy(old_attribute)) + if isinstance(new_param_value, dict): + changeset[camel(param)] = copy.deepcopy(new_param_value) + else: + changeset[camel(param)] = new_param_value + # Prepare the desired values using the existing values (non-existence results in a dict that is save to use as a basis) + desired_user = copy.deepcopy(before_user) + desired_user.update(changeset) + + result['proposed'] = changeset + result['existing'] = before_user + + changed = False + + # Cater for when it doesn't exist (an empty dict) + if state == 'absent': + if not before_user: + # Do nothing and exit + if module._diff: + result['diff'] = dict(before='', after='') + result['changed'] = False + result['end_state'] = {} + result['msg'] = 'Role does not exist, doing nothing.' + module.exit_json(**result) + else: + # Delete user + kc.delete_user(user_id=before_user['id'], realm=realm) + result["msg"] = 'User %s deleted' % (before_user['username']) + changed = True + + else: + after_user = {} + if force: # If the force option is set to true + # Delete the existing user + kc.delete_user(user_id=before_user["id"], realm=realm) + + if not before_user or force: + # Process a creation + changed = True + + if username is None: + module.fail_json(msg='username must be specified when creating a new user') + + if module._diff: + result['diff'] = dict(before='', after=desired_user) + + if module.check_mode: + module.exit_json(**result) + # Create the user + after_user = kc.create_user(userrep=desired_user, realm=realm) + result["msg"] = 'User %s created' % (desired_user['username']) + # Add user ID to new representation + desired_user['id'] = after_user["id"] + else: + excludes = [ + "access", + "notBefore", + "createdTimestamp", + "totp", + "credentials", + "disableableCredentialTypes", + "groups", + "clientConsents", + "federatedIdentities", + "requiredActions"] + # Add user ID to new representation + desired_user['id'] = before_user["id"] + + # Compare users + if not (is_struct_included(desired_user, before_user, excludes)): # If the new user does not introduce a change to the existing user + # Update the user + after_user = kc.update_user(userrep=desired_user, realm=realm) + changed = True + + # set user groups + if kc.update_user_groups_membership(userrep=desired_user, groups=groups, realm=realm): + changed = True + # Get the user groups + after_user["groups"] = kc.get_user_groups(user_id=desired_user["id"], realm=realm) + result["end_state"] = after_user + if changed: + result["msg"] = 'User %s updated' % (desired_user['username']) + else: + result["msg"] = 'No changes made for user %s' % (desired_user['username']) + + result['changed'] = changed + module.exit_json(**result) + + +if __name__ == '__main__': + main() diff --git a/tests/integration/targets/keycloak_user/README.md b/tests/integration/targets/keycloak_user/README.md new file mode 100644 index 0000000000..07ecc3f83e --- /dev/null +++ b/tests/integration/targets/keycloak_user/README.md @@ -0,0 +1,21 @@ + +# Running keycloak_user module integration test + +To run Keycloak user module's integration test, start a keycloak server using Docker or Podman: + + podman|docker run -d --rm --name mykeycloak -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=password quay.io/keycloak/keycloak:latest start-dev --http-relative-path /auth + +Source Ansible env-setup from ansible github repository + +Run integration tests: + + ansible-test integration keycloak_user --python 3.10 --allow-unsupported + +Cleanup: + + podman|docker stop mykeycloak + diff --git a/tests/integration/targets/keycloak_user/aliases b/tests/integration/targets/keycloak_user/aliases new file mode 100644 index 0000000000..0abc6a4671 --- /dev/null +++ b/tests/integration/targets/keycloak_user/aliases @@ -0,0 +1,4 @@ +# Copyright (c) 2023, INSPQ Philippe Gauthier (@elfelip) +# 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 +unsupported diff --git a/tests/integration/targets/keycloak_user/tasks/main.yml b/tests/integration/targets/keycloak_user/tasks/main.yml new file mode 100644 index 0000000000..0f1fe152d0 --- /dev/null +++ b/tests/integration/targets/keycloak_user/tasks/main.yml @@ -0,0 +1,114 @@ +# Copyright (c) 2022, Dušan Marković (@bratwurzt) +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +- name: Create realm + community.general.keycloak_realm: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + id: "{{ realm }}" + realm: "{{ realm }}" + state: present + +- name: Create new realm role + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + realm: "{{ realm }}" + name: "{{ role }}" + description: "{{ description_1 }}" + state: present + +- name: Create client + community.general.keycloak_client: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + realm: "{{ realm }}" + client_id: "{{ client_id }}" + service_accounts_enabled: true + state: present + register: client + + +- name: Create new client role + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + realm: "{{ realm }}" + client_id: "{{ client_id }}" + name: "{{ keycloak_client_role }}" + description: "{{ description_1 }}" + state: present + +- name: Create new groups + community.general.keycloak_group: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + realm: "{{ realm }}" + name: "{{ item.name }}" + state: present + with_items: "{{ keycloak_user_groups }}" + +- name: Create user + community.general.keycloak_user: + auth_keycloak_url: "{{ url }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + auth_realm: "{{ admin_realm }}" + username: "{{ keycloak_username }}" + realm: "{{ realm }}" + first_name: Ceciestes + last_name: Untestes + email: ceciestuntestes@test.com + groups: "{{ keycloak_user_groups }}" + attributes: "{{ keycloak_user_attributes }}" + state: present + register: create_result + +- name: debug + debug: + var: create_result + +- name: Assert user is created + assert: + that: + - create_result.changed + - create_result.end_state.username == 'test' + - create_result.end_state.attributes | length == 3 + - create_result.end_state.groups | length == 2 + +- name: Delete User + community.general.keycloak_user: + auth_keycloak_url: "{{ url }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + auth_realm: "{{ admin_realm }}" + username: "{{ keycloak_username }}" + realm: "{{ realm }}" + first_name: Ceciestes + last_name: Untestes + email: ceciestuntestes@test.com + groups: "{{ keycloak_user_groups }}" + attributes: "{{ keycloak_user_attributes }}" + state: absent + register: delete_result + +- name: debug + debug: + var: delete_result + +- name: Assert user is deleted + assert: + that: + - delete_result.changed + - delete_result.end_state | length == 0 diff --git a/tests/integration/targets/keycloak_user/vars/main.yml b/tests/integration/targets/keycloak_user/vars/main.yml new file mode 100644 index 0000000000..9962aba548 --- /dev/null +++ b/tests/integration/targets/keycloak_user/vars/main.yml @@ -0,0 +1,46 @@ +--- +# Copyright (c) 2022, Dušan Marković (@bratwurzt) +# 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 + +url: http://localhost:8080/auth +admin_realm: master +admin_user: admin +admin_password: password +realm: myrealm +client_id: myclient +role: myrole +description_1: desc 1 +description_2: desc 2 + +keycloak_username: test +keycloak_service_account_client_id: "{{ client_id }}" +keycloak_user_realm_roles: + - name: offline_access + - name: "{{ role }}" +keycloak_client_role: test +keycloak_user_client_roles: + - client_id: "{{ client_id }}" + roles: + - name: "{{ keycloak_client_role }}" + - client_id: "{{ realm }}-realm" + roles: + - name: view-users + - name: query-users +keycloak_user_attributes: + - name: attr1 + values: + - value1s + state: present + - name: attr2 + values: + - value2s + state: present + - name: attr3 + values: + - value3s + state: present +keycloak_user_groups: + - name: test + state: present + - name: test2 diff --git a/tests/unit/plugins/modules/test_keycloak_user.py b/tests/unit/plugins/modules/test_keycloak_user.py new file mode 100644 index 0000000000..f5a4e26f8a --- /dev/null +++ b/tests/unit/plugins/modules/test_keycloak_user.py @@ -0,0 +1,354 @@ +# -*- coding: utf-8 -*- + +# Copyright (c) 2021, Ansible Project +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +from __future__ import absolute_import, division, print_function + +__metaclass__ = type + +from contextlib import contextmanager + +from ansible_collections.community.general.tests.unit.compat import unittest +from ansible_collections.community.general.tests.unit.compat.mock import patch +from ansible_collections.community.general.tests.unit.plugins.modules.utils import AnsibleExitJson, ModuleTestCase, set_module_args + +from ansible_collections.community.general.plugins.modules import keycloak_user + +from itertools import count + +from ansible.module_utils.six import StringIO + + +@contextmanager +def patch_keycloak_api(get_user_by_username=None, + create_user=None, + update_user_groups_membership=None, + get_user_groups=None, + delete_user=None, + update_user=None): + """Mock context manager for patching the methods in KeycloakAPI that contact the Keycloak server + + Patches the `get_user_by_username` and `create_user` methods + + """ + + obj = keycloak_user.KeycloakAPI + with patch.object(obj, 'get_user_by_username', side_effect=get_user_by_username) as mock_get_user_by_username: + with patch.object(obj, 'create_user', side_effect=create_user) as mock_create_user: + with patch.object(obj, 'update_user_groups_membership', side_effect=update_user_groups_membership) as mock_update_user_groups_membership: + with patch.object(obj, 'get_user_groups', side_effect=get_user_groups) as mock_get_user_groups: + with patch.object(obj, 'delete_user', side_effect=delete_user) as mock_delete_user: + with patch.object(obj, 'update_user', side_effect=update_user) as mock_update_user: + yield mock_get_user_by_username, mock_create_user, mock_update_user_groups_membership,\ + mock_get_user_groups, mock_delete_user, mock_update_user + + +def get_response(object_with_future_response, method, get_id_call_count): + if callable(object_with_future_response): + return object_with_future_response() + if isinstance(object_with_future_response, dict): + return get_response( + object_with_future_response[method], method, get_id_call_count) + if isinstance(object_with_future_response, list): + call_number = next(get_id_call_count) + return get_response( + object_with_future_response[call_number], method, get_id_call_count) + return object_with_future_response + + +def build_mocked_request(get_id_user_count, response_dict): + def _mocked_requests(*args, **kwargs): + url = args[0] + method = kwargs['method'] + future_response = response_dict.get(url, None) + return get_response(future_response, method, get_id_user_count) + + return _mocked_requests + + +def create_wrapper(text_as_string): + """Allow to mock many times a call to one address. + Without this function, the StringIO is empty for the second call. + """ + + def _create_wrapper(): + return StringIO(text_as_string) + + return _create_wrapper + + +def mock_good_connection(): + token_response = { + 'http://keycloak.url/auth/realms/master/protocol/openid-connect/token': create_wrapper( + '{"access_token": "alongtoken"}'), } + return patch( + 'ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak.open_url', + side_effect=build_mocked_request(count(), token_response), + autospec=True + ) + + +class TestKeycloakUser(ModuleTestCase): + def setUp(self): + super(TestKeycloakUser, self).setUp() + self.module = keycloak_user + + def test_add_new_user(self): + """Add a new user""" + + module_args = { + 'auth_keycloak_url': 'https: // auth.example.com / auth', + 'token': '{{ access_token }}', + 'state': 'present', + 'realm': 'master', + 'username': 'test', + 'groups': [] + } + return_value_get_user_by_username = [None] + return_value_update_user_groups_membership = [False] + return_get_user_groups = [[]] + return_create_user = [{'id': '123eqwdawer24qwdqw4'}] + return_delete_user = None + return_update_user = None + changed = True + + set_module_args(module_args) + + # Run the module + + with mock_good_connection(): + with patch_keycloak_api(get_user_by_username=return_value_get_user_by_username, + create_user=return_create_user, + update_user_groups_membership=return_value_update_user_groups_membership, + get_user_groups=return_get_user_groups, + update_user=return_update_user, + delete_user=return_delete_user) \ + as (mock_get_user_by_username, + mock_create_user, + mock_update_user_groups_membership, + mock_get_user_groups, + mock_delete_user, + mock_update_user): + with self.assertRaises(AnsibleExitJson) as exec_info: + self.module.main() + + self.assertEqual(mock_get_user_by_username.call_count, 1) + self.assertEqual(mock_create_user.call_count, 1) + self.assertEqual(mock_update_user_groups_membership.call_count, 1) + self.assertEqual(mock_get_user_groups.call_count, 1) + self.assertEqual(mock_update_user.call_count, 0) + self.assertEqual(mock_delete_user.call_count, 0) + + # Verify that the module's changed status matches what is expected + self.assertIs(exec_info.exception.args[0]['changed'], changed) + + def test_add_exiting_user_no_change(self): + """Add a new user""" + + module_args = { + 'auth_keycloak_url': 'https: // auth.example.com / auth', + 'token': '{{ access_token }}', + 'state': 'present', + 'realm': 'master', + 'username': 'test', + 'groups': [] + } + return_value_get_user_by_username = [ + { + 'id': '123eqwdawer24qwdqw4', + 'username': 'test', + 'groups': [], + 'enabled': True, + 'emailVerified': False, + 'disableableCredentialTypes': [], + 'requiredActions': [], + 'credentials': [], + 'federatedIdentities': [], + 'clientConsents': [] + } + ] + return_value_update_user_groups_membership = [False] + return_get_user_groups = [[]] + return_create_user = None + return_delete_user = None + return_update_user = None + changed = False + + set_module_args(module_args) + + # Run the module + + with mock_good_connection(): + with patch_keycloak_api(get_user_by_username=return_value_get_user_by_username, + create_user=return_create_user, + update_user_groups_membership=return_value_update_user_groups_membership, + get_user_groups=return_get_user_groups, + update_user=return_update_user, + delete_user=return_delete_user) \ + as (mock_get_user_by_username, + mock_create_user, + mock_update_user_groups_membership, + mock_get_user_groups, + mock_delete_user, + mock_update_user): + with self.assertRaises(AnsibleExitJson) as exec_info: + self.module.main() + + self.assertEqual(mock_get_user_by_username.call_count, 1) + self.assertEqual(mock_create_user.call_count, 0) + self.assertEqual(mock_update_user_groups_membership.call_count, 1) + self.assertEqual(mock_get_user_groups.call_count, 1) + self.assertEqual(mock_update_user.call_count, 0) + self.assertEqual(mock_delete_user.call_count, 0) + + # Verify that the module's changed status matches what is expected + self.assertIs(exec_info.exception.args[0]['changed'], changed) + + def test_update_user_with_group_changes(self): + """Update groups for a user""" + + module_args = { + 'auth_keycloak_url': 'https: // auth.example.com / auth', + 'token': '{{ access_token }}', + 'state': 'present', + 'realm': 'master', + 'username': 'test', + 'first_name': 'test', + 'last_name': 'user', + 'groups': [{ + 'name': 'group1', + 'state': 'present' + }] + } + return_value_get_user_by_username = [ + { + 'id': '123eqwdawer24qwdqw4', + 'username': 'test', + 'groups': [], + 'enabled': True, + 'emailVerified': False, + 'disableableCredentialTypes': [], + 'requiredActions': [], + 'credentials': [], + 'federatedIdentities': [], + 'clientConsents': [] + } + ] + return_value_update_user_groups_membership = [True] + return_get_user_groups = [['group1']] + return_create_user = None + return_delete_user = None + return_update_user = [ + { + 'id': '123eqwdawer24qwdqw4', + 'username': 'test', + 'first_name': 'test', + 'last_name': 'user', + 'enabled': True, + 'emailVerified': False, + 'disableableCredentialTypes': [], + 'requiredActions': [], + 'credentials': [], + 'federatedIdentities': [], + 'clientConsents': [] + } + ] + changed = True + + set_module_args(module_args) + + # Run the module + + with mock_good_connection(): + with patch_keycloak_api(get_user_by_username=return_value_get_user_by_username, + create_user=return_create_user, + update_user_groups_membership=return_value_update_user_groups_membership, + get_user_groups=return_get_user_groups, + update_user=return_update_user, + delete_user=return_delete_user) \ + as (mock_get_user_by_username, + mock_create_user, + mock_update_user_groups_membership, + mock_get_user_groups, + mock_delete_user, + mock_update_user): + with self.assertRaises(AnsibleExitJson) as exec_info: + self.module.main() + + self.assertEqual(mock_get_user_by_username.call_count, 1) + self.assertEqual(mock_create_user.call_count, 0) + self.assertEqual(mock_update_user_groups_membership.call_count, 1) + self.assertEqual(mock_get_user_groups.call_count, 1) + self.assertEqual(mock_update_user.call_count, 1) + self.assertEqual(mock_delete_user.call_count, 0) + + # Verify that the module's changed status matches what is expected + self.assertIs(exec_info.exception.args[0]['changed'], changed) + + def test_delete_user(self): + """Delete a user""" + + module_args = { + 'auth_keycloak_url': 'https: // auth.example.com / auth', + 'token': '{{ access_token }}', + 'state': 'absent', + 'realm': 'master', + 'username': 'test', + 'groups': [] + } + return_value_get_user_by_username = [ + { + 'id': '123eqwdawer24qwdqw4', + 'username': 'test', + 'groups': [], + 'enabled': True, + 'emailVerified': False, + 'disableableCredentialTypes': [], + 'requiredActions': [], + 'credentials': [], + 'federatedIdentities': [], + 'clientConsents': [] + } + ] + return_value_update_user_groups_membership = None + return_get_user_groups = None + return_create_user = None + return_delete_user = None + return_update_user = None + changed = True + + set_module_args(module_args) + + # Run the module + + with mock_good_connection(): + with patch_keycloak_api(get_user_by_username=return_value_get_user_by_username, + create_user=return_create_user, + update_user_groups_membership=return_value_update_user_groups_membership, + get_user_groups=return_get_user_groups, + update_user=return_update_user, + delete_user=return_delete_user) \ + as (mock_get_user_by_username, + mock_create_user, + mock_update_user_groups_membership, + mock_get_user_groups, + mock_delete_user, + mock_update_user): + with self.assertRaises(AnsibleExitJson) as exec_info: + self.module.main() + + self.assertEqual(mock_get_user_by_username.call_count, 1) + self.assertEqual(mock_create_user.call_count, 0) + self.assertEqual(mock_update_user_groups_membership.call_count, 0) + self.assertEqual(mock_get_user_groups.call_count, 0) + self.assertEqual(mock_update_user.call_count, 0) + self.assertEqual(mock_delete_user.call_count, 1) + + # Verify that the module's changed status matches what is expected + self.assertIs(exec_info.exception.args[0]['changed'], changed) + + +if __name__ == '__main__': + unittest.main() From 494909aba535d3f35d2f3aeca0129cd5cb97efcf Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Fri, 9 Jun 2023 22:56:10 +1200 Subject: [PATCH 0038/1451] MH mh/mixins/deps.py: prevent deprecation warning when no deps are specified (#6644) * MH mh/mixins/deps.py: prevent deprecation warning when no deps are specified * rollback empty "patch" on license markers to prevent test error * disable test in ansible 2.12 * add changelog frag --- .../fragments/6644-dependencymixin-fix.yml | 2 ++ plugins/module_utils/mh/mixins/deps.py | 2 ++ .../targets/kernel_blacklist/tasks/main.yml | 18 +++++++++++++++--- 3 files changed, 19 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/6644-dependencymixin-fix.yml diff --git a/changelogs/fragments/6644-dependencymixin-fix.yml b/changelogs/fragments/6644-dependencymixin-fix.yml new file mode 100644 index 0000000000..3b75758303 --- /dev/null +++ b/changelogs/fragments/6644-dependencymixin-fix.yml @@ -0,0 +1,2 @@ +bugfixes: + - MH DependencyMixin module utils - deprecation notice was popping up for modules not using dependencies (https://github.com/ansible-collections/community.general/pull/6644, https://github.com/ansible-collections/community.general/issues/6639). diff --git a/plugins/module_utils/mh/mixins/deps.py b/plugins/module_utils/mh/mixins/deps.py index 2a5b2a716c..772df8c0e9 100644 --- a/plugins/module_utils/mh/mixins/deps.py +++ b/plugins/module_utils/mh/mixins/deps.py @@ -52,6 +52,8 @@ class DependencyMixin(ModuleHelperBase): return cls._dependencies[-1] def fail_on_missing_deps(self): + if not self._dependencies: + return self.module.deprecate( 'The DependencyMixin is being deprecated. ' 'Modules should use community.general.plugins.module_utils.deps instead.', diff --git a/tests/integration/targets/kernel_blacklist/tasks/main.yml b/tests/integration/targets/kernel_blacklist/tasks/main.yml index e169d5479e..45136e119c 100644 --- a/tests/integration/targets/kernel_blacklist/tasks/main.yml +++ b/tests/integration/targets/kernel_blacklist/tasks/main.yml @@ -36,6 +36,13 @@ path: '{{ bl_file }}' register: stat_test_1 +- name: show bl_test_1 + ansible.builtin.debug: + var: bl_test_1_depr_msgs + vars: + bl_test_1_depr_msgs: "{{ (bl_test_1.deprecations | default([])) | map(attribute='msg') }}" + # q('ansible.builtin.subelements', bl_test_1, 'deprecations', {'skip_missing': True}) }}" + - name: assert file is unchanged assert: that: @@ -49,12 +56,17 @@ expected_content: | # 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 + # SPDX{{ '' }}-License-Identifier: GPL-3.0-or-later blacklist aaaa blacklist bbbb blacklist cccc +- name: test deprecation + assert: + that: + - "'deprecations' not in bl_test_1 or (ansible_version.major == 2 and ansible_version.minor == 12)" + - name: add new item to list community.general.kernel_blacklist: blacklist_file: '{{ bl_file }}' @@ -76,7 +88,7 @@ content: | # 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 + # SPDX{{ '' }}-License-Identifier: GPL-3.0-or-later blacklist aaaa blacklist bbbb @@ -104,7 +116,7 @@ content: | # 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 + # SPDX{{ '' }}-License-Identifier: GPL-3.0-or-later blacklist aaaa blacklist cccc From 72162864664e85aa7f8c0043e5b5ec3131019097 Mon Sep 17 00:00:00 2001 From: Alexander Petermann Date: Fri, 9 Jun 2023 12:56:22 +0200 Subject: [PATCH 0039/1451] proxmox_snap: allow set retention for snapshots (#6577) * proxmox_snap: allow to trim snapshots * proxmox_snap: add changelog fragment for trim parameter * proxmox_snap: fix linter issues * Update plugins/modules/proxmox_snap.py Co-authored-by: Felix Fontein * Update changelogs/fragments/6576-proxmox-snap-allow-trimming.yml Co-authored-by: Felix Fontein * proxmox_snap: rename 'trim' into 'retention' * proxmox_snap: improve docu, as suggested by felixfontein * proxmox_snap: rename 'trim' in changelog * Update plugins/modules/proxmox_snap.py Co-authored-by: Felix Fontein * Update plugins/modules/proxmox_snap.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- ...mox-snap-allow-to-remove-old-snapshots.yml | 3 ++ plugins/modules/proxmox_snap.py | 41 ++++++++++++++++--- 2 files changed, 38 insertions(+), 6 deletions(-) create mode 100644 changelogs/fragments/6576-proxmox-snap-allow-to-remove-old-snapshots.yml diff --git a/changelogs/fragments/6576-proxmox-snap-allow-to-remove-old-snapshots.yml b/changelogs/fragments/6576-proxmox-snap-allow-to-remove-old-snapshots.yml new file mode 100644 index 0000000000..be6ab5ea31 --- /dev/null +++ b/changelogs/fragments/6576-proxmox-snap-allow-to-remove-old-snapshots.yml @@ -0,0 +1,3 @@ +--- +minor_changes: + - "proxmox_snap - add ``retention`` parameter to delete old snapshots (https://github.com/ansible-collections/community.general/pull/6576)." diff --git a/plugins/modules/proxmox_snap.py b/plugins/modules/proxmox_snap.py index 0c17f83763..39d869336b 100644 --- a/plugins/modules/proxmox_snap.py +++ b/plugins/modules/proxmox_snap.py @@ -74,6 +74,15 @@ options: - Name of the snapshot that has to be created/deleted/restored. default: 'ansible_snap' type: str + retention: + 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. + default: 0 + type: int + version_added: 7.1.0 notes: - Requires proxmoxer and requests modules on host. These modules can be installed with pip. @@ -94,6 +103,16 @@ EXAMPLES = r''' state: present snapname: pre-updates +- name: Create new container snapshot and keep only the 2 newest snapshots + community.general.proxmox_snap: + api_user: root@pam + api_password: 1q2w3e + api_host: node1 + vmid: 100 + state: present + snapname: snapshot-42 + retention: 2 + - name: Create new snapshot for a container with configured mountpoints community.general.proxmox_snap: api_user: root@pam @@ -190,7 +209,15 @@ class ProxmoxSnapAnsible(ProxmoxAnsible): time.sleep(1) return False - def snapshot_create(self, vm, vmid, timeout, snapname, description, vmstate, unbind): + def snapshot_retention(self, vm, vmid, retention): + # ignore the last snapshot, which is the current state + snapshots = self.snapshot(vm, vmid).get()[:-1] + if retention > 0 and len(snapshots) > retention: + # sort by age, oldest first + for snap in sorted(snapshots, key=lambda x: x['snaptime'])[:len(snapshots) - retention]: + self.snapshot(vm, vmid)(snap['name']).delete() + + def snapshot_create(self, vm, vmid, timeout, snapname, description, vmstate, unbind, retention): if self.module.check_mode: return True @@ -217,9 +244,7 @@ class ProxmoxSnapAnsible(ProxmoxAnsible): while timeout: if self.api_task_ok(vm['node'], taskid): - if vm['type'] == 'lxc' and unbind is True and mountpoints: - self._container_mp_restore(vm, vmid, timeout, unbind, mountpoints, vmstatus) - return True + break if timeout == 0: self.module.fail_json(msg='Reached timeout while waiting for creating VM snapshot. Last line in task before timeout: %s' % self.proxmox_api.nodes(vm['node']).tasks(taskid).log.get()[:1]) @@ -228,7 +253,9 @@ class ProxmoxSnapAnsible(ProxmoxAnsible): timeout -= 1 if vm['type'] == 'lxc' and unbind is True and mountpoints: self._container_mp_restore(vm, vmid, timeout, unbind, mountpoints, vmstatus) - return False + + self.snapshot_retention(vm, vmid, retention) + return timeout > 0 def snapshot_remove(self, vm, vmid, timeout, snapname, force): if self.module.check_mode: @@ -275,6 +302,7 @@ def main(): force=dict(type='bool', default=False), unbind=dict(type='bool', default=False), vmstate=dict(type='bool', default=False), + retention=dict(type='int', default=0), ) module_args.update(snap_args) @@ -294,6 +322,7 @@ def main(): force = module.params['force'] unbind = module.params['unbind'] vmstate = module.params['vmstate'] + retention = module.params['retention'] # If hostname is set get the VM id from ProxmoxAPI if not vmid and hostname: @@ -309,7 +338,7 @@ def main(): if i['name'] == snapname: module.exit_json(changed=False, msg="Snapshot %s is already present" % snapname) - if proxmox.snapshot_create(vm, vmid, timeout, snapname, description, vmstate, unbind): + if proxmox.snapshot_create(vm, vmid, timeout, snapname, description, vmstate, unbind, retention): if module.check_mode: module.exit_json(changed=False, msg="Snapshot %s would be created" % snapname) else: From 621bedf7517cbea7863959435eaf1c4032250b00 Mon Sep 17 00:00:00 2001 From: Pino Toscano Date: Fri, 9 Jun 2023 13:20:40 +0200 Subject: [PATCH 0040/1451] redhat_subscription: officially deprecate "autosubscribe" (#6646) The "autosubscribe" alias for the "auto_attach" option has been deprecated for many years, although only in the documentation. Officially mark it as deprecated also in the module parameters spec, slating it for removal in 9.0.0. --- ...hat_subscription-deprecate-autosubscribe.yml | 6 ++++++ plugins/modules/redhat_subscription.py | 17 +++++++++++++++-- 2 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/6646-redhat_subscription-deprecate-autosubscribe.yml diff --git a/changelogs/fragments/6646-redhat_subscription-deprecate-autosubscribe.yml b/changelogs/fragments/6646-redhat_subscription-deprecate-autosubscribe.yml new file mode 100644 index 0000000000..491ea7cef7 --- /dev/null +++ b/changelogs/fragments/6646-redhat_subscription-deprecate-autosubscribe.yml @@ -0,0 +1,6 @@ +deprecated_features: +- | + redhat_subscription - the ``autosubscribe`` alias for the ``auto_attach`` option has been + deprecated for many years, although only in the documentation. Officially mark this alias + as deprecated, and it will be removed in community.general 9.0.0 + (https://github.com/ansible-collections/community.general/pull/6646). diff --git a/plugins/modules/redhat_subscription.py b/plugins/modules/redhat_subscription.py index 79b0d4b4c9..3340a3c9cf 100644 --- a/plugins/modules/redhat_subscription.py +++ b/plugins/modules/redhat_subscription.py @@ -122,7 +122,10 @@ options: auto_attach: description: - Upon successful registration, auto-consume available subscriptions - - Added in favor of deprecated autosubscribe in 2.5. + - | + Added in favor of the deprecated I(autosubscribe) option in + Ansible 2.5; please note that I(autosubscribe) will be removed in + community.general 9.0.0. type: bool aliases: [autosubscribe] activationkey: @@ -1074,7 +1077,17 @@ def main(): 'server_port': {}, 'rhsm_baseurl': {}, 'rhsm_repo_ca_cert': {}, - 'auto_attach': {'aliases': ['autosubscribe'], 'type': 'bool'}, + 'auto_attach': { + 'type': 'bool', + 'aliases': ['autosubscribe'], + 'deprecated_aliases': [ + { + 'name': 'autosubscribe', + 'version': '9.0.0', + 'collection_name': 'community.general', + }, + ], + }, 'activationkey': {'no_log': True}, 'org_id': {}, 'environment': {}, From 994f08b37a72f78f923088318cfb7cce550d123a Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Fri, 9 Jun 2023 23:27:22 +1200 Subject: [PATCH 0041/1451] MH VarsMixin deprecation (#6649) * MH VarsMixin deprecation * add changelog frag --- .../fragments/6649-varsmixin-deprecation.yml | 2 ++ plugins/module_utils/mh/mixins/vars.py | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 changelogs/fragments/6649-varsmixin-deprecation.yml diff --git a/changelogs/fragments/6649-varsmixin-deprecation.yml b/changelogs/fragments/6649-varsmixin-deprecation.yml new file mode 100644 index 0000000000..475617893d --- /dev/null +++ b/changelogs/fragments/6649-varsmixin-deprecation.yml @@ -0,0 +1,2 @@ +deprecated_features: + - MH VarsMixin module utils - deprecates ``VarsMixin`` and supporting classes in favor of plain ``vardict`` module util (https://github.com/ansible-collections/community.general/pull/6649). diff --git a/plugins/module_utils/mh/mixins/vars.py b/plugins/module_utils/mh/mixins/vars.py index 6dfb29bab8..91f4e4a189 100644 --- a/plugins/module_utils/mh/mixins/vars.py +++ b/plugins/module_utils/mh/mixins/vars.py @@ -11,6 +11,13 @@ import copy class VarMeta(object): + """ + DEPRECATION WARNING + + This class is deprecated and will be removed in community.general 10.0.0 + Modules should use the VarDict from plugins/module_utils/vardict.py instead. + """ + NOTHING = object() def __init__(self, diff=False, output=True, change=None, fact=False): @@ -60,6 +67,12 @@ class VarMeta(object): class VarDict(object): + """ + DEPRECATION WARNING + + This class is deprecated and will be removed in community.general 10.0.0 + Modules should use the VarDict from plugins/module_utils/vardict.py instead. + """ def __init__(self): self._data = dict() self._meta = dict() @@ -123,7 +136,12 @@ class VarDict(object): class VarsMixin(object): + """ + DEPRECATION WARNING + This class is deprecated and will be removed in community.general 10.0.0 + Modules should use the VarDict from plugins/module_utils/vardict.py instead. + """ def __init__(self, module=None): self.vars = VarDict() super(VarsMixin, self).__init__(module) From 61b889749e6cb955c75a773ce708eabc8765e1fe Mon Sep 17 00:00:00 2001 From: Pino Toscano Date: Fri, 9 Jun 2023 13:27:38 +0200 Subject: [PATCH 0042/1451] redhat_subscription: deprecate "pool" (#6650) The "pool" option is slower to use, and the regexp may expand to broader results than wanted. Because of that, deprecate it in favour of the "pool_ids" options (which is much better), slating it for removal in community.general 10.0.0. --- ...6650-redhat_subscription-deprecate-pool.yml | 5 +++++ plugins/modules/redhat_subscription.py | 18 +++++++++++++++--- 2 files changed, 20 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/6650-redhat_subscription-deprecate-pool.yml diff --git a/changelogs/fragments/6650-redhat_subscription-deprecate-pool.yml b/changelogs/fragments/6650-redhat_subscription-deprecate-pool.yml new file mode 100644 index 0000000000..3bcffa5a48 --- /dev/null +++ b/changelogs/fragments/6650-redhat_subscription-deprecate-pool.yml @@ -0,0 +1,5 @@ +deprecated_features: +- | + redhat_subscription - the ``pool`` option is deprecated in favour of the + more precise and flexible ``pool_ids`` option + (https://github.com/ansible-collections/community.general/pull/6650). diff --git a/plugins/modules/redhat_subscription.py b/plugins/modules/redhat_subscription.py index 3340a3c9cf..87c805fe92 100644 --- a/plugins/modules/redhat_subscription.py +++ b/plugins/modules/redhat_subscription.py @@ -143,8 +143,16 @@ options: pool: description: - | - Specify a subscription pool name to consume. Regular expressions accepted. Use I(pool_ids) instead if - possible, as it is much faster. Mutually exclusive with I(pool_ids). + Specify a subscription pool name to consume. Regular expressions accepted. + Mutually exclusive with I(pool_ids). + - | + Please use I(pool_ids) instead: specifying pool IDs is much faster, + and it avoids to match new pools that become available for the + system and are not explicitly wanted. Also, this option does not + support quantities. + - | + This option is deprecated for the reasons mentioned above, + and it will be removed in community.general 10.0.0. default: '^$' type: str pool_ids: @@ -1091,7 +1099,11 @@ def main(): 'activationkey': {'no_log': True}, 'org_id': {}, 'environment': {}, - 'pool': {'default': '^$'}, + 'pool': { + 'default': '^$', + 'removed_in_version': '10.0.0', + 'removed_from_collection': 'community.general', + }, 'pool_ids': {'default': [], 'type': 'list', 'elements': 'raw'}, 'consumer_type': {}, 'consumer_name': {}, From eddd1ba4f2070dc5e6c5be10371984116a95a7d6 Mon Sep 17 00:00:00 2001 From: delinea-sagar <131447653+delinea-sagar@users.noreply.github.com> Date: Fri, 9 Jun 2023 11:14:05 -0400 Subject: [PATCH 0043/1451] Fetch secret id's which are in folder by folder id (#6652) Added function to fetch secret id's by folder id --- .../6223-get-secret-ids-by-folderid.yml | 2 + plugins/lookup/tss.py | 56 ++++++++++++++++++- 2 files changed, 55 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/6223-get-secret-ids-by-folderid.yml diff --git a/changelogs/fragments/6223-get-secret-ids-by-folderid.yml b/changelogs/fragments/6223-get-secret-ids-by-folderid.yml new file mode 100644 index 0000000000..d439b89723 --- /dev/null +++ b/changelogs/fragments/6223-get-secret-ids-by-folderid.yml @@ -0,0 +1,2 @@ +minor_changes: + - tss lookup plugin - allow to fetch secret IDs which are in a folder based on folder ID. Previously, we could not fetch secrets based on folder ID but now use ``fetch_secret_ids_from_folder`` option to indicate to fetch secret IDs based on folder ID (https://github.com/ansible-collections/community.general/issues/6223). \ No newline at end of file diff --git a/plugins/lookup/tss.py b/plugins/lookup/tss.py index 756629f8b8..df7d57993b 100644 --- a/plugins/lookup/tss.py +++ b/plugins/lookup/tss.py @@ -26,6 +26,13 @@ options: description: The integer ID of the secret. required: true type: int + fetch_secret_ids_from_folder: + description: + - Boolean flag which indicates whether secret ids are in a folder is fetched by folder ID or not. + - V(true) then the terms will be considered as a folder IDs. Otherwise (default), they are considered as secret IDs. + required: false + type: bool + version_added: 7.1.0 fetch_attachments: description: - Boolean flag which indicates whether attached files will get downloaded or not. @@ -194,6 +201,26 @@ EXAMPLES = r""" | items2dict(key_name='slug', value_name='itemValue'))['private-key'] }} + +# If fetch_secret_ids_from_folder=true then secret IDs are in a folder is fetched based on folder ID +- hosts: localhost + vars: + secret: >- + {{ + lookup( + 'community.general.tss', + 102, + fetch_secret_ids_from_folder=true, + base_url='https://secretserver.domain.com/SecretServer/', + token='thycotic_access_token' + ) + }} + tasks: + - ansible.builtin.debug: + msg: > + the secret id's are {{ + secret + }} """ import abc @@ -204,18 +231,21 @@ from ansible.plugins.lookup import LookupBase from ansible.utils.display import Display try: - from thycotic.secrets.server import SecretServer, SecretServerError + from delinea.secrets.server import SecretServer, SecretServerError HAS_TSS_SDK = True + HAS_DELINEA_SS_SDK = True except ImportError: try: - from delinea.secrets.server import SecretServer, SecretServerError + from thycotic.secrets.server import SecretServer, SecretServerError HAS_TSS_SDK = True + HAS_DELINEA_SS_SDK = False except ImportError: SecretServer = None SecretServerError = None HAS_TSS_SDK = False + HAS_DELINEA_SS_SDK = False try: from thycotic.secrets.server import PasswordGrantAuthorizer, DomainPasswordGrantAuthorizer, AccessTokenAuthorizer @@ -270,6 +300,13 @@ class TSSClient(object): else: return self._client.get_secret_json(secret_id) + def get_secret_ids_by_folderid(self, term): + display.debug("tss_lookup term: %s" % 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) + + return self._client.get_secret_ids_by_folderid(folder_id) + @staticmethod def _term_to_secret_id(term): try: @@ -277,6 +314,13 @@ class TSSClient(object): except ValueError: raise AnsibleOptionsError("Secret ID must be an integer") + @staticmethod + def _term_to_folder_id(term): + try: + return int(term) + except ValueError: + raise AnsibleOptionsError("Folder ID must be an integer") + class TSSClientV0(TSSClient): def __init__(self, **server_parameters): @@ -345,6 +389,12 @@ class LookupModule(LookupBase): ) try: - return [tss.get_secret(term, self.get_option("fetch_attachments"), self.get_option("file_download_path")) for term in terms] + if self.get_option("fetch_secret_ids_from_folder"): + if HAS_DELINEA_SS_SDK: + return [tss.get_secret_ids_by_folderid(term) for term in terms] + else: + raise AnsibleError("latest python-tss-sdk must be installed to use this plugin") + else: + return [tss.get_secret(term, self.get_option("fetch_attachments"), self.get_option("file_download_path")) for term in terms] except SecretServerError as error: raise AnsibleError("Secret Server lookup failure: %s" % error.message) From 011b2f8bdc2a042f0eb44739ff51ce425f391afa Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 10 Jun 2023 09:28:40 +0200 Subject: [PATCH 0044/1451] Start using semantic markup (#6627) * Start using semantic markup. * Forgot some places. * Fix typo. * Use 'ignore:' prefix until https://github.com/ansible-community/antsibull-docs/pull/155 is out. * Break too long line. --- plugins/become/machinectl.py | 2 +- plugins/become/pfexec.py | 2 +- plugins/cache/redis.py | 6 +-- plugins/callback/cgroup_memory_recap.py | 4 +- plugins/callback/diy.py | 52 +++++++++---------- plugins/callback/opentelemetry.py | 4 +- plugins/callback/splunk.py | 4 +- plugins/callback/sumologic.py | 6 +-- plugins/doc_fragments/alicloud.py | 4 +- plugins/doc_fragments/bitbucket.py | 2 +- plugins/doc_fragments/dimensiondata.py | 4 +- plugins/doc_fragments/dimensiondata_wait.py | 4 +- plugins/doc_fragments/influxdb.py | 10 ++-- plugins/doc_fragments/ipa.py | 6 +-- plugins/doc_fragments/keycloak.py | 4 +- plugins/doc_fragments/ldap.py | 18 +++---- plugins/doc_fragments/manageiq.py | 8 +-- plugins/doc_fragments/online.py | 4 +- plugins/doc_fragments/opennebula.py | 10 ++-- plugins/doc_fragments/openswitch.py | 18 +++---- plugins/doc_fragments/oracle.py | 26 +++++----- .../oracle_creatable_resource.py | 4 +- .../oracle_display_name_option.py | 2 +- plugins/doc_fragments/oracle_name_option.py | 2 +- plugins/doc_fragments/oracle_wait_options.py | 6 +-- plugins/doc_fragments/pritunl.py | 2 +- plugins/doc_fragments/proxmox.py | 4 +- plugins/doc_fragments/purestorage.py | 4 +- plugins/doc_fragments/rackspace.py | 20 +++---- plugins/doc_fragments/redis.py | 4 +- plugins/doc_fragments/scaleway.py | 4 +- plugins/doc_fragments/utm.py | 4 +- plugins/doc_fragments/vexata.py | 4 +- plugins/doc_fragments/xenserver.py | 2 +- plugins/filter/from_csv.py | 8 +-- plugins/filter/jc.py | 6 +-- plugins/filter/lists_mergeby.py | 4 +- plugins/filter/to_days.yml | 10 ++-- plugins/filter/to_hours.yml | 10 ++-- plugins/filter/to_milliseconds.yml | 10 ++-- plugins/filter/to_minutes.yml | 10 ++-- plugins/filter/to_months.yml | 10 ++-- plugins/filter/to_seconds.yml | 10 ++-- plugins/filter/to_time_unit.yml | 10 ++-- plugins/filter/to_weeks.yml | 10 ++-- plugins/filter/to_years.yml | 10 ++-- plugins/inventory/cobbler.py | 10 ++-- plugins/inventory/icinga2.py | 2 +- plugins/inventory/lxd.py | 10 ++-- plugins/inventory/nmap.py | 14 ++--- plugins/inventory/opennebula.py | 16 +++--- plugins/inventory/proxmox.py | 38 +++++++------- plugins/inventory/scaleway.py | 2 +- plugins/inventory/xen_orchestra.py | 8 +-- plugins/lookup/bitwarden.py | 2 +- plugins/lookup/collection_version.py | 18 +++---- plugins/lookup/consul_kv.py | 13 +++-- plugins/lookup/dig.py | 18 +++---- plugins/lookup/dnstxt.py | 4 +- plugins/lookup/dsv.py | 10 ++-- plugins/lookup/etcd3.py | 18 +++---- plugins/lookup/filetree.py | 2 +- plugins/lookup/lmdb_kv.py | 2 +- plugins/lookup/merge_variables.py | 8 +-- plugins/lookup/onepassword.py | 6 +-- plugins/lookup/onepassword_raw.py | 8 +-- plugins/lookup/passwordstore.py | 38 +++++++------- plugins/lookup/random_string.py | 12 ++--- plugins/lookup/revbitspss.py | 2 +- plugins/lookup/tss.py | 14 ++--- plugins/modules/ufw.py | 44 ++++++++-------- 71 files changed, 342 insertions(+), 345 deletions(-) diff --git a/plugins/become/machinectl.py b/plugins/become/machinectl.py index 461a3f635d..53d562e598 100644 --- a/plugins/become/machinectl.py +++ b/plugins/become/machinectl.py @@ -68,7 +68,7 @@ DOCUMENTATION = ''' - section: machinectl_become_plugin key: password notes: - - When not using this plugin with user C(root), it only works correctly with a polkit rule which will alter + - When not using this plugin with user V(root), it only works correctly with a polkit rule which will alter the behaviour of machinectl. This rule must alter the prompt behaviour to ask directly for the user credentials, if the user is allowed to perform the action (take a look at the examples section). If such a rule is not present the plugin only work if it is used in context with the root user, diff --git a/plugins/become/pfexec.py b/plugins/become/pfexec.py index 392ee961f5..2468a28a94 100644 --- a/plugins/become/pfexec.py +++ b/plugins/become/pfexec.py @@ -82,7 +82,7 @@ DOCUMENTATION = ''' env: - name: ANSIBLE_PFEXEC_WRAP_EXECUTION notes: - - This plugin ignores I(become_user) as pfexec uses it's own C(exec_attr) to figure this out. + - This plugin ignores O(become_user) as pfexec uses it's own C(exec_attr) to figure this out. ''' from ansible.plugins.become import BecomeBase diff --git a/plugins/cache/redis.py b/plugins/cache/redis.py index 8c06217176..01c67fd521 100644 --- a/plugins/cache/redis.py +++ b/plugins/cache/redis.py @@ -18,9 +18,9 @@ DOCUMENTATION = ''' _uri: description: - A colon separated string of connection information for Redis. - - The format is C(host:port:db:password), for example C(localhost:6379:0:changeme). - - To use encryption in transit, prefix the connection with C(tls://), as in C(tls://localhost:6379:0:changeme). - - To use redis sentinel, use separator C(;), for example C(localhost:26379;localhost:26379;0:changeme). Requires redis>=2.9.0. + - The format is V(host:port:db:password), for example V(localhost:6379:0:changeme). + - To use encryption in transit, prefix the connection with V(tls://), as in V(tls://localhost:6379:0:changeme). + - To use redis sentinel, use separator V(;), for example V(localhost:26379;localhost:26379;0:changeme). Requires redis>=2.9.0. required: true env: - name: ANSIBLE_CACHE_PLUGIN_CONNECTION diff --git a/plugins/callback/cgroup_memory_recap.py b/plugins/callback/cgroup_memory_recap.py index ccdbcc9cf0..d3961bf0c8 100644 --- a/plugins/callback/cgroup_memory_recap.py +++ b/plugins/callback/cgroup_memory_recap.py @@ -24,7 +24,7 @@ DOCUMENTATION = ''' options: max_mem_file: required: true - description: Path to cgroups C(memory.max_usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes). + description: Path to cgroups C(memory.max_usage_in_bytes) file. Example V(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes). env: - name: CGROUP_MAX_MEM_FILE ini: @@ -32,7 +32,7 @@ DOCUMENTATION = ''' key: max_mem_file cur_mem_file: required: true - description: Path to C(memory.usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes). + description: Path to C(memory.usage_in_bytes) file. Example V(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes). env: - name: CGROUP_CUR_MEM_FILE ini: diff --git a/plugins/callback/diy.py b/plugins/callback/diy.py index 75b3f4e24b..cf9369e4b4 100644 --- a/plugins/callback/diy.py +++ b/plugins/callback/diy.py @@ -18,7 +18,7 @@ DOCUMENTATION = r''' extends_documentation_fragment: - default_callback notes: - - Uses the C(default) callback plugin output when a custom callback message(C(msg)) is not provided. + - Uses the P(ansible.builtin.default#callback) callback plugin output when a custom callback V(message(msg\)) is not provided. - Makes the callback event data available via the C(ansible_callback_diy) dictionary, which can be used in the templating context for the options. The dictionary is only available in the templating context for the options. It is not a variable that is available via the other various execution contexts, such as playbook, play, task etc. @@ -40,8 +40,8 @@ DOCUMENTATION = r''' if value C(is not None and not omit and length is greater than 0), then the option is being used with output. **Effect**: render value as template and output" - - "Valid color values: C(black), C(bright gray), C(blue), C(white), C(green), C(bright blue), C(cyan), C(bright green), C(red), C(bright cyan), - C(purple), C(bright red), C(yellow), C(bright purple), C(dark gray), C(bright yellow), C(magenta), C(bright magenta), C(normal)" + - "Valid color values: V(black), V(bright gray), V(blue), V(white), V(green), V(bright blue), V(cyan), V(bright green), V(red), V(bright cyan), + V(purple), V(bright red), V(yellow), V(bright purple), V(dark gray), V(bright yellow), V(magenta), V(bright magenta), V(normal)" seealso: - name: default – default Ansible screen output description: The official documentation on the B(default) callback plugin. @@ -62,7 +62,7 @@ DOCUMENTATION = r''' on_any_msg_color: description: - - Output color to be used for I(on_any_msg). + - Output color to be used for O(on_any_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -86,7 +86,7 @@ DOCUMENTATION = r''' runner_on_failed_msg_color: description: - - Output color to be used for I(runner_on_failed_msg). + - Output color to be used for O(runner_on_failed_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -110,7 +110,7 @@ DOCUMENTATION = r''' runner_on_ok_msg_color: description: - - Output color to be used for I(runner_on_ok_msg). + - Output color to be used for O(runner_on_ok_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -134,7 +134,7 @@ DOCUMENTATION = r''' runner_on_skipped_msg_color: description: - - Output color to be used for I(runner_on_skipped_msg). + - Output color to be used for O(runner_on_skipped_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -158,7 +158,7 @@ DOCUMENTATION = r''' runner_on_unreachable_msg_color: description: - - Output color to be used for I(runner_on_unreachable_msg). + - Output color to be used for O(runner_on_unreachable_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -182,7 +182,7 @@ DOCUMENTATION = r''' playbook_on_start_msg_color: description: - - Output color to be used for I(playbook_on_start_msg). + - Output color to be used for O(playbook_on_start_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -206,7 +206,7 @@ DOCUMENTATION = r''' playbook_on_notify_msg_color: description: - - Output color to be used for I(playbook_on_notify_msg). + - Output color to be used for O(playbook_on_notify_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -230,7 +230,7 @@ DOCUMENTATION = r''' playbook_on_no_hosts_matched_msg_color: description: - - Output color to be used for I(playbook_on_no_hosts_matched_msg). + - Output color to be used for O(playbook_on_no_hosts_matched_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -254,7 +254,7 @@ DOCUMENTATION = r''' playbook_on_no_hosts_remaining_msg_color: description: - - Output color to be used for I(playbook_on_no_hosts_remaining_msg). + - Output color to be used for O(playbook_on_no_hosts_remaining_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -278,7 +278,7 @@ DOCUMENTATION = r''' playbook_on_task_start_msg_color: description: - - Output color to be used for I(playbook_on_task_start_msg). + - Output color to be used for O(playbook_on_task_start_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -302,7 +302,7 @@ DOCUMENTATION = r''' playbook_on_handler_task_start_msg_color: description: - - Output color to be used for I(playbook_on_handler_task_start_msg). + - Output color to be used for O(playbook_on_handler_task_start_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -326,7 +326,7 @@ DOCUMENTATION = r''' playbook_on_vars_prompt_msg_color: description: - - Output color to be used for I(playbook_on_vars_prompt_msg). + - Output color to be used for O(playbook_on_vars_prompt_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -350,7 +350,7 @@ DOCUMENTATION = r''' playbook_on_play_start_msg_color: description: - - Output color to be used for I(playbook_on_play_start_msg). + - Output color to be used for O(playbook_on_play_start_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -374,7 +374,7 @@ DOCUMENTATION = r''' playbook_on_stats_msg_color: description: - - Output color to be used for I(playbook_on_stats_msg). + - Output color to be used for O(playbook_on_stats_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -398,7 +398,7 @@ DOCUMENTATION = r''' on_file_diff_msg_color: description: - - Output color to be used for I(on_file_diff_msg). + - Output color to be used for O(on_file_diff_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -422,7 +422,7 @@ DOCUMENTATION = r''' playbook_on_include_msg_color: description: - - Output color to be used for I(playbook_on_include_msg). + - Output color to be used for O(playbook_on_include_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -446,7 +446,7 @@ DOCUMENTATION = r''' runner_item_on_ok_msg_color: description: - - Output color to be used for I(runner_item_on_ok_msg). + - Output color to be used for O(runner_item_on_ok_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -470,7 +470,7 @@ DOCUMENTATION = r''' runner_item_on_failed_msg_color: description: - - Output color to be used for I(runner_item_on_failed_msg). + - Output color to be used for O(runner_item_on_failed_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -494,7 +494,7 @@ DOCUMENTATION = r''' runner_item_on_skipped_msg_color: description: - - Output color to be used for I(runner_item_on_skipped_msg). + - Output color to be used for O(runner_item_on_skipped_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -518,7 +518,7 @@ DOCUMENTATION = r''' runner_retry_msg_color: description: - - Output color to be used for I(runner_retry_msg). + - Output color to be used for O(runner_retry_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -542,7 +542,7 @@ DOCUMENTATION = r''' runner_on_start_msg_color: description: - - Output color to be used for I(runner_on_start_msg). + - Output color to be used for O(runner_on_start_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -566,7 +566,7 @@ DOCUMENTATION = r''' runner_on_no_hosts_msg_color: description: - - Output color to be used for I(runner_on_no_hosts_msg). + - Output color to be used for O(runner_on_no_hosts_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy @@ -590,7 +590,7 @@ DOCUMENTATION = r''' playbook_on_setup_msg_color: description: - - Output color to be used for I(playbook_on_setup_msg). + - Output color to be used for O(playbook_on_setup_msg). - Template should render a L(valid color value,#notes). ini: - section: callback_diy diff --git a/plugins/callback/opentelemetry.py b/plugins/callback/opentelemetry.py index df2fb5cee6..492e420716 100644 --- a/plugins/callback/opentelemetry.py +++ b/plugins/callback/opentelemetry.py @@ -32,10 +32,10 @@ DOCUMENTATION = ''' enable_from_environment: type: str description: - - Whether to enable this callback only if the given environment variable exists and it is set to C(true). + - Whether to enable this callback only if the given environment variable exists and it is set to V(true). - This is handy when you use Configuration as Code and want to send distributed traces if running in the CI rather when running Ansible locally. - - For such, it evaluates the given I(enable_from_environment) value as environment variable + - For such, it evaluates the given O(enable_from_environment) value as environment variable and if set to true this plugin will be enabled. env: - name: ANSIBLE_OPENTELEMETRY_ENABLE_FROM_ENVIRONMENT diff --git a/plugins/callback/splunk.py b/plugins/callback/splunk.py index 67ad944d2e..d15547f44b 100644 --- a/plugins/callback/splunk.py +++ b/plugins/callback/splunk.py @@ -36,8 +36,8 @@ DOCUMENTATION = ''' key: authtoken validate_certs: description: Whether to validate certificates for connections to HEC. It is not recommended to set to - C(false) except when you are sure that nobody can intercept the connection - between this plugin and HEC, as setting it to C(false) allows man-in-the-middle attacks! + V(false) except when you are sure that nobody can intercept the connection + between this plugin and HEC, as setting it to V(false) allows man-in-the-middle attacks! env: - name: SPLUNK_VALIDATE_CERTS ini: diff --git a/plugins/callback/sumologic.py b/plugins/callback/sumologic.py index 998081c35b..46ab3f0f7c 100644 --- a/plugins/callback/sumologic.py +++ b/plugins/callback/sumologic.py @@ -6,7 +6,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r''' name: sumologic type: notification short_description: Sends task result events to Sumologic @@ -15,8 +15,8 @@ description: - This callback plugin will send task results as JSON formatted events to a Sumologic HTTP collector source. requirements: - Whitelisting this callback plugin - - 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of C(yyyy-MM-dd HH:mm:ss ZZZZ) and a custom timestamp locator - of C("timestamp": "(.*)")' + - 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of V(yyyy-MM-dd HH:mm:ss ZZZZ) and a custom timestamp locator + of V("timestamp": "(.*\)")' options: url: description: URL to the Sumologic HTTP collector source. diff --git a/plugins/doc_fragments/alicloud.py b/plugins/doc_fragments/alicloud.py index f464e178c7..cce24c944a 100644 --- a/plugins/doc_fragments/alicloud.py +++ b/plugins/doc_fragments/alicloud.py @@ -41,8 +41,8 @@ options: alicloud_assume_role: description: - If provided with a role ARN, Ansible will attempt to assume this role using the supplied credentials. - - The nested assume_role block supports I(alicloud_assume_role_arn), I(alicloud_assume_role_session_name), - I(alicloud_assume_role_session_expiration) and I(alicloud_assume_role_policy) + - The nested assume_role block supports C(alicloud_assume_role_arn), C(alicloud_assume_role_session_name), + C(alicloud_assume_role_session_expiration) and C(alicloud_assume_role_policy). type: dict aliases: ['assume_role'] alicloud_assume_role_arn: diff --git a/plugins/doc_fragments/bitbucket.py b/plugins/doc_fragments/bitbucket.py index 703bb412a1..269c8dee8d 100644 --- a/plugins/doc_fragments/bitbucket.py +++ b/plugins/doc_fragments/bitbucket.py @@ -27,7 +27,7 @@ options: description: - The username. - If not set the environment variable C(BITBUCKET_USERNAME) will be used. - - I(username) is an alias of I(user) since community.genreal 6.0.0. It was an alias of I(workspace) before. + - O(ignore:username) is an alias of O(user) since community.general 6.0.0. It was an alias of O(workspace) before. type: str version_added: 4.0.0 aliases: [ username ] diff --git a/plugins/doc_fragments/dimensiondata.py b/plugins/doc_fragments/dimensiondata.py index f8372431e0..24a4f483c9 100644 --- a/plugins/doc_fragments/dimensiondata.py +++ b/plugins/doc_fragments/dimensiondata.py @@ -35,7 +35,7 @@ options: description: - The password used to authenticate to the CloudControl API. - If not specified, will fall back to C(MCP_PASSWORD) from environment variable or C(~/.dimensiondata). - - Required if I(mcp_user) is specified. + - Required if O(mcp_user) is specified. type: str location: description: @@ -44,7 +44,7 @@ options: required: true validate_certs: description: - - If C(false), SSL certificates will not be validated. + - If V(false), SSL certificates will not be validated. - This should only be used on private instances of the CloudControl API that use self-signed certificates. type: bool default: true diff --git a/plugins/doc_fragments/dimensiondata_wait.py b/plugins/doc_fragments/dimensiondata_wait.py index d371528396..929139df32 100644 --- a/plugins/doc_fragments/dimensiondata_wait.py +++ b/plugins/doc_fragments/dimensiondata_wait.py @@ -25,13 +25,13 @@ options: wait_time: description: - The maximum amount of time (in seconds) to wait for the task to complete. - - Only applicable if I(wait=true). + - Only applicable if O(wait=true). type: int default: 600 wait_poll_interval: description: - The amount of time (in seconds) to wait between checks for task completion. - - Only applicable if I(wait=true). + - Only applicable if O(wait=true). type: int default: 2 ''' diff --git a/plugins/doc_fragments/influxdb.py b/plugins/doc_fragments/influxdb.py index 6aedd5ad39..882f8f00a6 100644 --- a/plugins/doc_fragments/influxdb.py +++ b/plugins/doc_fragments/influxdb.py @@ -22,14 +22,14 @@ options: username: description: - Username that will be used to authenticate against InfluxDB server. - - Alias C(login_username) added in Ansible 2.5. + - Alias O(ignore:login_username) added in Ansible 2.5. type: str default: root aliases: [ login_username ] password: description: - Password that will be used to authenticate against InfluxDB server. - - Alias C(login_password) added in Ansible 2.5. + - Alias O(ignore:login_password) added in Ansible 2.5. type: str default: root aliases: [ login_password ] @@ -47,8 +47,8 @@ options: version_added: '0.2.0' validate_certs: description: - - If set to C(false), the SSL certificates will not be validated. - - This should only set to C(false) used on personally controlled sites using self-signed certificates. + - If set to V(false), the SSL certificates will not be validated. + - This should only set to V(false) used on personally controlled sites using self-signed certificates. type: bool default: true ssl: @@ -63,7 +63,7 @@ options: retries: description: - Number of retries client will try before aborting. - - C(0) indicates try until success. + - V(0) indicates try until success. - Only available when using python-influxdb >= 4.1.0 type: int default: 3 diff --git a/plugins/doc_fragments/ipa.py b/plugins/doc_fragments/ipa.py index 5051c55390..fdc63dc728 100644 --- a/plugins/doc_fragments/ipa.py +++ b/plugins/doc_fragments/ipa.py @@ -60,9 +60,9 @@ options: default: https validate_certs: description: - - This only applies if C(ipa_prot) is I(https). - - If set to C(false), the SSL certificates will not be validated. - - This should only set to C(false) used on personally controlled sites using self-signed certificates. + - This only applies if O(ipa_prot) is V(https). + - If set to V(false), the SSL certificates will not be validated. + - This should only set to V(false) used on personally controlled sites using self-signed certificates. type: bool default: true ipa_timeout: diff --git a/plugins/doc_fragments/keycloak.py b/plugins/doc_fragments/keycloak.py index 5d79fad7c0..b7f12c6ca2 100644 --- a/plugins/doc_fragments/keycloak.py +++ b/plugins/doc_fragments/keycloak.py @@ -23,7 +23,7 @@ options: auth_client_id: description: - - OpenID Connect I(client_id) to authenticate to the API with. + - OpenID Connect C(client_id) to authenticate to the API with. type: str default: admin-cli @@ -34,7 +34,7 @@ options: auth_client_secret: description: - - Client Secret to use in conjunction with I(auth_client_id) (if required). + - Client Secret to use in conjunction with O(auth_client_id) (if required). type: str auth_username: diff --git a/plugins/doc_fragments/ldap.py b/plugins/doc_fragments/ldap.py index b321c75eb8..451b3f3e06 100644 --- a/plugins/doc_fragments/ldap.py +++ b/plugins/doc_fragments/ldap.py @@ -21,7 +21,7 @@ options: type: str bind_pw: description: - - The password to use with I(bind_dn). + - The password to use with O(bind_dn). type: str default: '' ca_path: @@ -40,12 +40,12 @@ options: type: str description: - Set the referrals chasing behavior. - - C(anonymous) follow referrals anonymously. This is the default behavior. - - C(disabled) disable referrals chasing. This sets C(OPT_REFERRALS) to off. + - V(anonymous) follow referrals anonymously. This is the default behavior. + - V(disabled) disable referrals chasing. This sets C(OPT_REFERRALS) to off. version_added: 2.0.0 server_uri: description: - - The I(server_uri) parameter may be a comma- or whitespace-separated list of URIs containing only the schema, the host, and the port fields. + - The O(server_uri) parameter may be a comma- or whitespace-separated list of URIs containing only the schema, the host, and the port fields. - The default value lets the underlying LDAP client library look for a UNIX domain socket in its default location. - Note that when using multiple URIs you cannot determine to which URI your client gets connected. - For URIs containing additional fields, particularly when using commas, behavior is undefined. @@ -58,14 +58,13 @@ options: default: false validate_certs: description: - - If set to C(false), SSL certificates will not be validated. + - If set to V(false), SSL certificates will not be validated. - This should only be used on sites using self-signed certificates. type: bool default: true sasl_class: description: - The class to use for SASL authentication. - - Possible choices are C(external), C(gssapi). type: str choices: ['external', 'gssapi'] default: external @@ -73,10 +72,9 @@ options: xorder_discovery: description: - Set the behavior on how to process Xordered DNs. - - C(enable) will perform a C(ONELEVEL) search below the superior RDN to find the matching DN. - - C(disable) will always use the DN unmodified (as passed by the I(dn) parameter). - - C(auto) will only perform a search if the first RDN does not contain an index number (C({x})). - - Possible choices are C(enable), C(auto), C(disable). + - V(enable) will perform a C(ONELEVEL) search below the superior RDN to find the matching DN. + - V(disable) will always use the DN unmodified (as passed by the O(dn) parameter). + - V(auto) will only perform a search if the first RDN does not contain an index number (C({x})). type: str choices: ['enable', 'auto', 'disable'] default: auto diff --git a/plugins/doc_fragments/manageiq.py b/plugins/doc_fragments/manageiq.py index 030d682385..c20a519b0d 100644 --- a/plugins/doc_fragments/manageiq.py +++ b/plugins/doc_fragments/manageiq.py @@ -21,20 +21,20 @@ options: suboptions: url: description: - - ManageIQ environment url. C(MIQ_URL) env var if set. otherwise, it is required to pass it. + - ManageIQ environment URL. C(MIQ_URL) environment variable if set. otherwise, it is required to pass it. type: str required: false username: description: - - ManageIQ username. C(MIQ_USERNAME) env var if set. otherwise, required if no token is passed in. + - ManageIQ username. C(MIQ_USERNAME) environment variable if set. otherwise, required if no token is passed in. type: str password: description: - - ManageIQ password. C(MIQ_PASSWORD) env var if set. otherwise, required if no token is passed in. + - ManageIQ password. C(MIQ_PASSWORD) environment variable if set. otherwise, required if no token is passed in. type: str token: description: - - ManageIQ token. C(MIQ_TOKEN) env var if set. otherwise, required if no username or password is passed in. + - ManageIQ token. C(MIQ_TOKEN) environment variable if set. otherwise, required if no username or password is passed in. type: str validate_certs: description: diff --git a/plugins/doc_fragments/online.py b/plugins/doc_fragments/online.py index d7e13765b0..a8a472bca3 100644 --- a/plugins/doc_fragments/online.py +++ b/plugins/doc_fragments/online.py @@ -37,9 +37,9 @@ options: default: true notes: - Also see the API documentation on U(https://console.online.net/en/api/) - - If C(api_token) is not set within the module, the following + - If O(api_token) is not set within the module, the following environment variables can be used in decreasing order of precedence C(ONLINE_TOKEN), C(ONLINE_API_KEY), C(ONLINE_OAUTH_TOKEN), C(ONLINE_API_TOKEN) - - If one wants to use a different C(api_url) one can also set the C(ONLINE_API_URL) + - If one wants to use a different O(api_url) one can also set the C(ONLINE_API_URL) environment variable. ''' diff --git a/plugins/doc_fragments/opennebula.py b/plugins/doc_fragments/opennebula.py index 0fc323271a..e034192501 100644 --- a/plugins/doc_fragments/opennebula.py +++ b/plugins/doc_fragments/opennebula.py @@ -15,26 +15,26 @@ options: api_url: description: - The ENDPOINT URL of the XMLRPC server. - - If not specified then the value of the ONE_URL environment variable, if any, is used. + - If not specified then the value of the C(ONE_URL) environment variable, if any, is used. type: str aliases: - api_endpoint api_username: description: - The name of the user for XMLRPC authentication. - - If not specified then the value of the ONE_USERNAME environment variable, if any, is used. + - If not specified then the value of the C(ONE_USERNAME) environment variable, if any, is used. type: str api_password: description: - The password or token for XMLRPC authentication. - - If not specified then the value of the ONE_PASSWORD environment variable, if any, is used. + - If not specified then the value of the C(ONE_PASSWORD) environment variable, if any, is used. type: str aliases: - api_token validate_certs: description: - - Whether to validate the SSL certificates or not. - - This parameter is ignored if PYTHONHTTPSVERIFY environment variable is used. + - Whether to validate the TLS/SSL certificates or not. + - This parameter is ignored if C(PYTHONHTTPSVERIFY) environment variable is used. type: bool default: true wait_timeout: diff --git a/plugins/doc_fragments/openswitch.py b/plugins/doc_fragments/openswitch.py index 9d5f0be742..e212fd1579 100644 --- a/plugins/doc_fragments/openswitch.py +++ b/plugins/doc_fragments/openswitch.py @@ -23,7 +23,7 @@ options: port: description: - Specifies the port to use when building the connection to the remote - device. This value applies to either I(cli) or I(rest). The port + device. This value applies to either O(transport=cli) or O(transport=rest). The port value will default to the appropriate transport common port if none is provided in the task. (cli=22, http=80, https=443). Note this argument does not affect the SSH transport. @@ -41,8 +41,8 @@ options: password: description: - Specifies the password to use to authenticate the connection to - the remote device. This is a common argument used for either I(cli) - or I(rest) transports. Note this argument does not affect the SSH + the remote device. This is a common argument used for either O(transport=cli) + or O(transport=rest). Note this argument does not affect the SSH transport. If the value is not specified in the task, the value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead. type: str @@ -56,8 +56,8 @@ options: ssh_keyfile: description: - Specifies the SSH key to use to authenticate the connection to - the remote device. This argument is only used for the I(cli) - transports. If the value is not specified in the task, the value of + the remote device. This argument is only used for O(transport=cli). + If the value is not specified in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE) will be used instead. type: path transport: @@ -71,14 +71,14 @@ options: default: ssh use_ssl: description: - - Configures the I(transport) to use SSL if set to C(true) only when the - I(transport) argument is configured as rest. If the transport - argument is not I(rest), this value is ignored. + - Configures the O(transport) to use SSL if set to V(true) only when the + O(transport) argument is configured as rest. If the transport + argument is not V(rest), this value is ignored. type: bool default: true provider: description: - - Convenience method that allows all I(openswitch) arguments to be passed as + - Convenience method that allows all C(openswitch) arguments to be passed as a dict object. All constraints (required, choices, etc) must be met either by individual arguments or values in this dict. type: dict diff --git a/plugins/doc_fragments/oracle.py b/plugins/doc_fragments/oracle.py index 9ca4706baa..c3a93fc131 100644 --- a/plugins/doc_fragments/oracle.py +++ b/plugins/doc_fragments/oracle.py @@ -23,23 +23,23 @@ class ModuleDocFragment(object): type: str config_profile_name: description: - - The profile to load from the config file referenced by C(config_file_location). If not set, then the + - The profile to load from the config file referenced by O(config_file_location). If not set, then the value of the OCI_CONFIG_PROFILE environment variable, if any, is used. Otherwise, defaults to the - "DEFAULT" profile in C(config_file_location). + "DEFAULT" profile in O(config_file_location). default: "DEFAULT" type: str api_user: description: - The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the OCI_USER_OCID environment variable, if any, is used. This option is required if the user - is not specified through a configuration file (See C(config_file_location)). To get the user's OCID, + is not specified through a configuration file (See O(config_file_location)). To get the user's OCID, please refer U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm). type: str api_user_fingerprint: description: - Fingerprint for the key pair being used. If not set, then the value of the OCI_USER_FINGERPRINT environment variable, if any, is used. This option is required if the key fingerprint is not - specified through a configuration file (See C(config_file_location)). To get the key pair's + specified through a configuration file (See O(config_file_location)). To get the key pair's fingerprint value please refer U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm). type: str @@ -47,21 +47,21 @@ class ModuleDocFragment(object): description: - Full path and filename of the private key (in PEM format). If not set, then the value of the OCI_USER_KEY_FILE variable, if any, is used. This option is required if the private key is - not specified through a configuration file (See C(config_file_location)). If the key is encrypted - with a pass-phrase, the C(api_user_key_pass_phrase) option must also be provided. + not specified through a configuration file (See O(config_file_location)). If the key is encrypted + with a pass-phrase, the O(api_user_key_pass_phrase) option must also be provided. type: path api_user_key_pass_phrase: description: - - Passphrase used by the key referenced in C(api_user_key_file), if it is encrypted. If not set, then + - Passphrase used by the key referenced in O(api_user_key_file), if it is encrypted. If not set, then the value of the OCI_USER_KEY_PASS_PHRASE variable, if any, is used. This option is required if the - key passphrase is not specified through a configuration file (See C(config_file_location)). + key passphrase is not specified through a configuration file (See O(config_file_location)). type: str auth_type: description: - - The type of authentication to use for making API requests. By default C(auth_type="api_key") based - authentication is performed and the API key (see I(api_user_key_file)) in your config file will be + - The type of authentication to use for making API requests. By default O(auth_type=api_key) based + authentication is performed and the API key (see O(api_user_key_file)) in your config file will be used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE, - if any, is used. Use C(auth_type="instance_principal") to use instance principal based authentication + if any, is used. Use O(auth_type=instance_principal) to use instance principal based authentication when running ansible playbooks within an OCI compute instance. choices: ['api_key', 'instance_principal'] default: 'api_key' @@ -70,14 +70,14 @@ class ModuleDocFragment(object): description: - OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is used. This option is required if the tenancy OCID is not specified through a configuration file - (See C(config_file_location)). To get the tenancy OCID, please refer + (See O(config_file_location)). To get the tenancy OCID, please refer U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm) type: str region: description: - The Oracle Cloud Infrastructure region to use for all OCI API requests. If not set, then the value of the OCI_REGION variable, if any, is used. This option is required if the region is - not specified through a configuration file (See C(config_file_location)). Please refer to + not specified through a configuration file (See O(config_file_location)). Please refer to U(https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm) for more information on OCI regions. type: str diff --git a/plugins/doc_fragments/oracle_creatable_resource.py b/plugins/doc_fragments/oracle_creatable_resource.py index 5293819199..9d2cc07c9f 100644 --- a/plugins/doc_fragments/oracle_creatable_resource.py +++ b/plugins/doc_fragments/oracle_creatable_resource.py @@ -14,13 +14,13 @@ class ModuleDocFragment(object): description: Whether to attempt non-idempotent creation of a resource. By default, create resource is an idempotent operation, and doesn't create the resource if it already exists. Setting this option to true, forcefully creates a copy of the resource, even if it already exists.This option is - mutually exclusive with I(key_by). + mutually exclusive with O(key_by). default: false type: bool key_by: description: The list of comma-separated attributes of this resource which should be used to uniquely identify an instance of the resource. By default, all the attributes of a resource except - I(freeform_tags) are used to uniquely identify a resource. + O(freeform_tags) are used to uniquely identify a resource. type: list elements: str """ diff --git a/plugins/doc_fragments/oracle_display_name_option.py b/plugins/doc_fragments/oracle_display_name_option.py index eae5f44593..b6bc0f2297 100644 --- a/plugins/doc_fragments/oracle_display_name_option.py +++ b/plugins/doc_fragments/oracle_display_name_option.py @@ -11,7 +11,7 @@ class ModuleDocFragment(object): DOCUMENTATION = """ options: display_name: - description: Use I(display_name) along with the other options to return only resources that match the given + description: Use O(display_name) along with the other options to return only resources that match the given display name exactly. type: str """ diff --git a/plugins/doc_fragments/oracle_name_option.py b/plugins/doc_fragments/oracle_name_option.py index 362071f946..523eed702f 100644 --- a/plugins/doc_fragments/oracle_name_option.py +++ b/plugins/doc_fragments/oracle_name_option.py @@ -11,7 +11,7 @@ class ModuleDocFragment(object): DOCUMENTATION = """ options: name: - description: Use I(name) along with the other options to return only resources that match the given name + description: Use O(name) along with the other options to return only resources that match the given name exactly. type: str """ diff --git a/plugins/doc_fragments/oracle_wait_options.py b/plugins/doc_fragments/oracle_wait_options.py index ce7ea776e2..3a857d4f77 100644 --- a/plugins/doc_fragments/oracle_wait_options.py +++ b/plugins/doc_fragments/oracle_wait_options.py @@ -15,12 +15,12 @@ class ModuleDocFragment(object): default: true type: bool wait_timeout: - description: Time, in seconds, to wait when I(wait=true). + description: Time, in seconds, to wait when O(wait=true). default: 1200 type: int wait_until: - description: The lifecycle state to wait for the resource to transition into when I(wait=true). By default, - when I(wait=true), we wait for the resource to get into ACTIVE/ATTACHED/AVAILABLE/PROVISIONED/ + description: The lifecycle state to wait for the resource to transition into when O(wait=true). By default, + when O(wait=true), we wait for the resource to get into ACTIVE/ATTACHED/AVAILABLE/PROVISIONED/ RUNNING applicable lifecycle state during create operation & to get into DELETED/DETACHED/ TERMINATED lifecycle state during delete operation. type: str diff --git a/plugins/doc_fragments/pritunl.py b/plugins/doc_fragments/pritunl.py index 51ab979b54..396ee0866a 100644 --- a/plugins/doc_fragments/pritunl.py +++ b/plugins/doc_fragments/pritunl.py @@ -38,7 +38,7 @@ options: default: true description: - If certificates should be validated or not. - - This should never be set to C(false), except if you are very sure that + - This should never be set to V(false), except if you are very sure that your connection to the server can not be subject to a Man In The Middle attack. """ diff --git a/plugins/doc_fragments/proxmox.py b/plugins/doc_fragments/proxmox.py index e39af4f3a6..15d6555bb4 100644 --- a/plugins/doc_fragments/proxmox.py +++ b/plugins/doc_fragments/proxmox.py @@ -38,7 +38,7 @@ options: version_added: 1.3.0 validate_certs: description: - - If C(false), SSL certificates will not be validated. + - 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: false @@ -55,7 +55,7 @@ options: node: description: - Proxmox VE node on which to operate. - - Only required for I(state=present). + - Only required for O(state=present). - For every other states it will be autodiscovered. type: str pool: diff --git a/plugins/doc_fragments/purestorage.py b/plugins/doc_fragments/purestorage.py index 8db8c3b3da..2411245733 100644 --- a/plugins/doc_fragments/purestorage.py +++ b/plugins/doc_fragments/purestorage.py @@ -34,7 +34,7 @@ options: notes: - This module requires the C(purity_fb) Python library - You must set C(PUREFB_URL) and C(PUREFB_API) environment variables - if I(fb_url) and I(api_token) arguments are not passed to the module directly + if O(fb_url) and O(api_token) arguments are not passed to the module directly requirements: - python >= 2.7 - purity_fb >= 1.1 @@ -56,7 +56,7 @@ options: notes: - This module requires the C(purestorage) Python library - You must set C(PUREFA_URL) and C(PUREFA_API) environment variables - if I(fa_url) and I(api_token) arguments are not passed to the module directly + if O(fa_url) and O(api_token) arguments are not passed to the module directly requirements: - python >= 2.7 - purestorage diff --git a/plugins/doc_fragments/rackspace.py b/plugins/doc_fragments/rackspace.py index 6f902a2395..e68f2bfe85 100644 --- a/plugins/doc_fragments/rackspace.py +++ b/plugins/doc_fragments/rackspace.py @@ -15,18 +15,18 @@ class ModuleDocFragment(object): options: api_key: description: - - Rackspace API key, overrides I(credentials). + - Rackspace API key, overrides O(credentials). type: str aliases: [ password ] credentials: description: - - File to find the Rackspace credentials in. Ignored if I(api_key) and - I(username) are provided. + - File to find the Rackspace credentials in. Ignored if O(api_key) and + O(username) are provided. type: path aliases: [ creds_file ] env: description: - - Environment as configured in I(~/.pyrax.cfg), + - Environment as configured in C(~/.pyrax.cfg), see U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#pyrax-configuration). type: str region: @@ -35,7 +35,7 @@ options: type: str username: description: - - Rackspace username, overrides I(credentials). + - Rackspace username, overrides O(credentials). type: str validate_certs: description: @@ -61,7 +61,7 @@ options: api_key: type: str description: - - Rackspace API key, overrides I(credentials). + - Rackspace API key, overrides O(credentials). aliases: [ password ] auth_endpoint: type: str @@ -71,13 +71,13 @@ options: credentials: type: path description: - - File to find the Rackspace credentials in. Ignored if I(api_key) and - I(username) are provided. + - File to find the Rackspace credentials in. Ignored if O(api_key) and + O(username) are provided. aliases: [ creds_file ] env: type: str description: - - Environment as configured in I(~/.pyrax.cfg), + - Environment as configured in C(~/.pyrax.cfg), see U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#pyrax-configuration). identity_type: type: str @@ -99,7 +99,7 @@ options: username: type: str description: - - Rackspace username, overrides I(credentials). + - Rackspace username, overrides O(credentials). validate_certs: description: - Whether or not to require SSL validation of API endpoints. diff --git a/plugins/doc_fragments/redis.py b/plugins/doc_fragments/redis.py index 2d40330519..fafb52c86c 100644 --- a/plugins/doc_fragments/redis.py +++ b/plugins/doc_fragments/redis.py @@ -46,8 +46,8 @@ options: default: true ca_certs: description: - - Path to root certificates file. If not set and I(tls) is - set to C(true), certifi ca-certificates will be used. + - Path to root certificates file. If not set and O(tls) is + set to V(true), certifi ca-certificates will be used. type: str requirements: [ "redis", "certifi" ] diff --git a/plugins/doc_fragments/scaleway.py b/plugins/doc_fragments/scaleway.py index b08d11dbb0..34b0769092 100644 --- a/plugins/doc_fragments/scaleway.py +++ b/plugins/doc_fragments/scaleway.py @@ -43,9 +43,9 @@ options: default: true notes: - Also see the API documentation on U(https://developer.scaleway.com/) - - If C(api_token) is not set within the module, the following + - If O(api_token) is not set within the module, the following environment variables can be used in decreasing order of precedence C(SCW_TOKEN), C(SCW_API_KEY), C(SCW_OAUTH_TOKEN) or C(SCW_API_TOKEN). - - If one wants to use a different C(api_url) one can also set the C(SCW_API_URL) + - If one wants to use a different O(api_url) one can also set the C(SCW_API_URL) environment variable. ''' diff --git a/plugins/doc_fragments/utm.py b/plugins/doc_fragments/utm.py index 73ad805035..980a43e9bb 100644 --- a/plugins/doc_fragments/utm.py +++ b/plugins/doc_fragments/utm.py @@ -48,8 +48,8 @@ options: state: description: - The desired state of the object. - - C(present) will create or update an object - - C(absent) will delete an object if it was present + - V(present) will create or update an object + - V(absent) will delete an object if it was present type: str choices: [ absent, present ] default: present diff --git a/plugins/doc_fragments/vexata.py b/plugins/doc_fragments/vexata.py index ff79613eec..69349172c2 100644 --- a/plugins/doc_fragments/vexata.py +++ b/plugins/doc_fragments/vexata.py @@ -39,8 +39,8 @@ options: type: str validate_certs: description: - - Allows connection when SSL certificates are not valid. Set to C(false) when certificates are not trusted. - - If set to C(true), please make sure Python >= 2.7.9 is installed on the given machine. + - Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted. + - If set to V(true), please make sure Python >= 2.7.9 is installed on the given machine. required: false type: bool default: false diff --git a/plugins/doc_fragments/xenserver.py b/plugins/doc_fragments/xenserver.py index eaee173849..2a33c91451 100644 --- a/plugins/doc_fragments/xenserver.py +++ b/plugins/doc_fragments/xenserver.py @@ -34,7 +34,7 @@ options: aliases: [ pass, pwd ] validate_certs: description: - - Allows connection when SSL certificates are not valid. Set to C(false) when certificates are not trusted. + - Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted. - If the value is not specified in the task, the value of environment variable C(XENSERVER_VALIDATE_CERTS) will be used instead. type: bool default: true diff --git a/plugins/filter/from_csv.py b/plugins/filter/from_csv.py index 6472b67b1a..7af655d6f7 100644 --- a/plugins/filter/from_csv.py +++ b/plugins/filter/from_csv.py @@ -23,7 +23,7 @@ DOCUMENTATION = ''' dialect: description: - The CSV dialect to use when parsing the CSV file. - - Possible values include C(excel), C(excel-tab) or C(unix). + - Possible values include V(excel), V(excel-tab) or V(unix). type: str default: excel fieldnames: @@ -35,19 +35,19 @@ DOCUMENTATION = ''' delimiter: description: - A one-character string used to separate fields. - - When using this parameter, you change the default value used by I(dialect). + - 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 I(dialect). + - 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 I(dialect). + - When using this parameter, you change the default value used by O(dialect). - The default value depends on the dialect used. type: bool ''' diff --git a/plugins/filter/jc.py b/plugins/filter/jc.py index 3aa8d20a5f..2fe3ef9d73 100644 --- a/plugins/filter/jc.py +++ b/plugins/filter/jc.py @@ -25,17 +25,17 @@ DOCUMENTATION = ''' parser: description: - The correct parser for the input data. - - For example C(ifconfig). + - For example V(ifconfig). - "Note: use underscores instead of dashes (if any) in the parser module name." - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers. type: string required: true quiet: - description: Set to C(false) to not suppress warnings. + description: Set to V(false) to not suppress warnings. type: boolean default: true raw: - description: Set to C(true) to return pre-processed JSON. + description: Set to V(true) to return pre-processed JSON. type: boolean default: false requirements: diff --git a/plugins/filter/lists_mergeby.py b/plugins/filter/lists_mergeby.py index 036dfe4d7c..caf183492c 100644 --- a/plugins/filter/lists_mergeby.py +++ b/plugins/filter/lists_mergeby.py @@ -12,9 +12,9 @@ DOCUMENTATION = ''' version_added: 2.0.0 author: Vladimir Botka (@vbotka) description: - - Merge two or more lists by attribute I(index). Optional parameters 'recursive' and 'list_merge' + - Merge two or more lists by attribute O(index). Optional parameters O(recursive) and O(list_merge) control the merging of the lists in values. The function merge_hash from ansible.utils.vars - is used. To learn details on how to use the parameters 'recursive' and 'list_merge' see + is used. To learn details on how to use the parameters O(recursive) and O(list_merge) see Ansible User's Guide chapter "Using filters to manipulate data" section "Combining hashes/dictionaries". positional: another_list, index diff --git a/plugins/filter/to_days.yml b/plugins/filter/to_days.yml index 19bc8faf23..b5f6424fa3 100644 --- a/plugins/filter/to_days.yml +++ b/plugins/filter/to_days.yml @@ -13,12 +13,12 @@ DOCUMENTATION: _input: description: - The time string to convert. - - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week, - C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec) - and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s) - can be added to a unit as well, so C(seconds) is the same as C(second). + - Can use the units V(y) and V(year) for a year, V(mo) and V(month) for a month, V(w) and V(week) for a week, + V(d) and V(day) for a day, V(h) and V(hour) for a hour, V(m), V(min) and V(minute) for minutes, V(s), V(sec) + and V(second) for seconds, V(ms), V(msec), V(msecond) and V(millisecond) for milliseconds. The suffix V(s) + can be added to a unit as well, so V(seconds) is the same as V(second). - Valid strings are space separated combinations of an integer with an optional minus sign and a unit. - - Examples are C(1h), C(-5m), and C(3h -5m 6s). + - Examples are V(1h), V(-5m), and V(3h -5m 6s). type: string required: true year: diff --git a/plugins/filter/to_hours.yml b/plugins/filter/to_hours.yml index 83826a5908..353fdfc317 100644 --- a/plugins/filter/to_hours.yml +++ b/plugins/filter/to_hours.yml @@ -13,12 +13,12 @@ DOCUMENTATION: _input: description: - The time string to convert. - - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week, - C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec) - and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s) - can be added to a unit as well, so C(seconds) is the same as C(second). + - Can use the units V(y) and V(year) for a year, V(mo) and V(month) for a month, V(w) and V(week) for a week, + V(d) and V(day) for a day, V(h) and V(hour) for a hour, V(m), V(min) and V(minute) for minutes, V(s), V(sec) + and V(second) for seconds, V(ms), V(msec), V(msecond) and V(millisecond) for milliseconds. The suffix V(s) + can be added to a unit as well, so V(seconds) is the same as V(second). - Valid strings are space separated combinations of an integer with an optional minus sign and a unit. - - Examples are C(1h), C(-5m), and C(3h -5m 6s). + - Examples are V(1h), V(-5m), and V(3h -5m 6s). type: string required: true year: diff --git a/plugins/filter/to_milliseconds.yml b/plugins/filter/to_milliseconds.yml index b6bb7e4be0..19ed02438c 100644 --- a/plugins/filter/to_milliseconds.yml +++ b/plugins/filter/to_milliseconds.yml @@ -13,12 +13,12 @@ DOCUMENTATION: _input: description: - The time string to convert. - - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week, - C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec) - and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s) - can be added to a unit as well, so C(seconds) is the same as C(second). + - Can use the units V(y) and V(year) for a year, V(mo) and V(month) for a month, V(w) and V(week) for a week, + V(d) and V(day) for a day, V(h) and V(hour) for a hour, V(m), V(min) and V(minute) for minutes, V(s), V(sec) + and V(second) for seconds, V(ms), V(msec), V(msecond) and V(millisecond) for milliseconds. The suffix V(s) + can be added to a unit as well, so V(seconds) is the same as V(second). - Valid strings are space separated combinations of an integer with an optional minus sign and a unit. - - Examples are C(1h), C(-5m), and C(3h -5m 6s). + - Examples are V(1h), V(-5m), and V(3h -5m 6s). type: string required: true year: diff --git a/plugins/filter/to_minutes.yml b/plugins/filter/to_minutes.yml index 3b85dadc43..e8d6f763a8 100644 --- a/plugins/filter/to_minutes.yml +++ b/plugins/filter/to_minutes.yml @@ -13,12 +13,12 @@ DOCUMENTATION: _input: description: - The time string to convert. - - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week, - C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec) - and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s) - can be added to a unit as well, so C(seconds) is the same as C(second). + - Can use the units V(y) and V(year) for a year, V(mo) and V(month) for a month, V(w) and V(week) for a week, + V(d) and V(day) for a day, V(h) and V(hour) for a hour, V(m), V(min) and V(minute) for minutes, V(s), V(sec) + and V(second) for seconds, V(ms), V(msec), V(msecond) and V(millisecond) for milliseconds. The suffix V(s) + can be added to a unit as well, so V(seconds) is the same as V(second). - Valid strings are space separated combinations of an integer with an optional minus sign and a unit. - - Examples are C(1h), C(-5m), and C(3h -5m 6s). + - Examples are V(1h), V(-5m), and V(3h -5m 6s). type: string required: true year: diff --git a/plugins/filter/to_months.yml b/plugins/filter/to_months.yml index f13cee918e..1f1cd661d8 100644 --- a/plugins/filter/to_months.yml +++ b/plugins/filter/to_months.yml @@ -13,12 +13,12 @@ DOCUMENTATION: _input: description: - The time string to convert. - - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week, - C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec) - and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s) - can be added to a unit as well, so C(seconds) is the same as C(second). + - Can use the units V(y) and V(year) for a year, V(mo) and V(month) for a month, V(w) and V(week) for a week, + V(d) and V(day) for a day, V(h) and V(hour) for a hour, V(m), V(min) and V(minute) for minutes, V(s), V(sec) + and V(second) for seconds, V(ms), V(msec), V(msecond) and V(millisecond) for milliseconds. The suffix V(s) + can be added to a unit as well, so V(seconds) is the same as V(second). - Valid strings are space separated combinations of an integer with an optional minus sign and a unit. - - Examples are C(1h), C(-5m), and C(3h -5m 6s). + - Examples are V(1h), V(-5m), and V(3h -5m 6s). type: string required: true year: diff --git a/plugins/filter/to_seconds.yml b/plugins/filter/to_seconds.yml index d6e6c4e467..d858e062a3 100644 --- a/plugins/filter/to_seconds.yml +++ b/plugins/filter/to_seconds.yml @@ -13,12 +13,12 @@ DOCUMENTATION: _input: description: - The time string to convert. - - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week, - C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec) - and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s) - can be added to a unit as well, so C(seconds) is the same as C(second). + - Can use the units V(y) and V(year) for a year, V(mo) and V(month) for a month, V(w) and V(week) for a week, + V(d) and V(day) for a day, V(h) and V(hour) for a hour, V(m), V(min) and V(minute) for minutes, V(s), V(sec) + and V(second) for seconds, V(ms), V(msec), V(msecond) and V(millisecond) for milliseconds. The suffix V(s) + can be added to a unit as well, so V(seconds) is the same as V(second). - Valid strings are space separated combinations of an integer with an optional minus sign and a unit. - - Examples are C(1h), C(-5m), and C(3h -5m 6s). + - Examples are V(1h), V(-5m), and V(3h -5m 6s). type: string required: true year: diff --git a/plugins/filter/to_time_unit.yml b/plugins/filter/to_time_unit.yml index c0149f0acd..bda124865c 100644 --- a/plugins/filter/to_time_unit.yml +++ b/plugins/filter/to_time_unit.yml @@ -14,12 +14,12 @@ DOCUMENTATION: _input: description: - The time string to convert. - - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week, - C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec) - and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s) - can be added to a unit as well, so C(seconds) is the same as C(second). + - Can use the units V(y) and V(year) for a year, V(mo) and V(month) for a month, V(w) and V(week) for a week, + V(d) and V(day) for a day, V(h) and V(hour) for a hour, V(m), V(min) and V(minute) for minutes, V(s), V(sec) + and V(second) for seconds, V(ms), V(msec), V(msecond) and V(millisecond) for milliseconds. The suffix V(s) + can be added to a unit as well, so V(seconds) is the same as V(second). - Valid strings are space separated combinations of an integer with an optional minus sign and a unit. - - Examples are C(1h), C(-5m), and C(3h -5m 6s). + - Examples are V(1h), V(-5m), and V(3h -5m 6s). type: string required: true unit: diff --git a/plugins/filter/to_weeks.yml b/plugins/filter/to_weeks.yml index 499c386276..7bf31bb65c 100644 --- a/plugins/filter/to_weeks.yml +++ b/plugins/filter/to_weeks.yml @@ -13,12 +13,12 @@ DOCUMENTATION: _input: description: - The time string to convert. - - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week, - C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec) - and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s) - can be added to a unit as well, so C(seconds) is the same as C(second). + - Can use the units V(y) and V(year) for a year, V(mo) and V(month) for a month, V(w) and V(week) for a week, + V(d) and V(day) for a day, V(h) and V(hour) for a hour, V(m), V(min) and V(minute) for minutes, V(s), V(sec) + and V(second) for seconds, V(ms), V(msec), V(msecond) and V(millisecond) for milliseconds. The suffix V(s) + can be added to a unit as well, so V(seconds) is the same as V(second). - Valid strings are space separated combinations of an integer with an optional minus sign and a unit. - - Examples are C(1h), C(-5m), and C(3h -5m 6s). + - Examples are V(1h), V(-5m), and V(3h -5m 6s). type: string required: true year: diff --git a/plugins/filter/to_years.yml b/plugins/filter/to_years.yml index 1a244a276f..33c85a3ece 100644 --- a/plugins/filter/to_years.yml +++ b/plugins/filter/to_years.yml @@ -13,12 +13,12 @@ DOCUMENTATION: _input: description: - The time string to convert. - - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week, - C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec) - and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s) - can be added to a unit as well, so C(seconds) is the same as C(second). + - Can use the units V(y) and V(year) for a year, V(mo) and V(month) for a month, V(w) and V(week) for a week, + V(d) and V(day) for a day, V(h) and V(hour) for a hour, V(m), V(min) and V(minute) for minutes, V(s), V(sec) + and V(second) for seconds, V(ms), V(msec), V(msecond) and V(millisecond) for milliseconds. The suffix V(s) + can be added to a unit as well, so V(seconds) is the same as V(second). - Valid strings are space separated combinations of an integer with an optional minus sign and a unit. - - Examples are C(1h), C(-5m), and C(3h -5m 6s). + - Examples are V(1h), V(-5m), and V(3h -5m 6s). type: string required: true year: diff --git a/plugins/inventory/cobbler.py b/plugins/inventory/cobbler.py index 1b8382e331..a5c68e18af 100644 --- a/plugins/inventory/cobbler.py +++ b/plugins/inventory/cobbler.py @@ -18,7 +18,7 @@ DOCUMENTATION = ''' - inventory_cache options: plugin: - description: The name of this plugin, it should always be set to C(community.general.cobbler) for this plugin to recognize it as it's own. + description: The name of this plugin, it should always be set to V(community.general.cobbler) for this plugin to recognize it as it's own. required: true choices: [ 'cobbler', 'community.general.cobbler' ] url: @@ -43,7 +43,7 @@ DOCUMENTATION = ''' exclude_profiles: description: - Profiles to exclude from inventory. - - Ignored if I(include_profiles) is specified. + - Ignored if O(include_profiles) is specified. type: list default: [] elements: str @@ -51,7 +51,7 @@ DOCUMENTATION = ''' description: - Profiles to include from inventory. - If specified, all other profiles will be excluded. - - I(exclude_profiles) is ignored if I(include_profiles) is specified. + - O(exclude_profiles) is ignored if O(include_profiles) is specified. type: list default: [] elements: str @@ -60,7 +60,7 @@ DOCUMENTATION = ''' description: - What to use for the ansible inventory hostname. - By default the networking hostname is used if defined, otherwise the DNS name of the management or first non-static interface. - - If set to I(system), the cobbler system name is used. + - If set to V(system), the cobbler system name is used. type: str choices: [ 'hostname', 'system' ] default: hostname @@ -77,7 +77,7 @@ DOCUMENTATION = ''' description: Prefix to apply to cobbler groups default: cobbler_ want_facts: - description: Toggle, if C(true) the plugin will retrieve host facts from the server + description: Toggle, if V(true) the plugin will retrieve host facts from the server type: boolean default: true ''' diff --git a/plugins/inventory/icinga2.py b/plugins/inventory/icinga2.py index 70e0f57332..39c0c7e893 100644 --- a/plugins/inventory/icinga2.py +++ b/plugins/inventory/icinga2.py @@ -58,7 +58,7 @@ DOCUMENTATION = ''' description: - Allows the override of the inventory name based on different attributes. - This allows for changing the way limits are used. - - The current default, C(address), is sometimes not unique or present. We recommend to use C(name) instead. + - The current default, V(address), is sometimes not unique or present. We recommend to use V(name) instead. type: string default: address choices: ['name', 'display_name', 'address'] diff --git a/plugins/inventory/lxd.py b/plugins/inventory/lxd.py index bd0a6ce008..6b661d9f2f 100644 --- a/plugins/inventory/lxd.py +++ b/plugins/inventory/lxd.py @@ -48,7 +48,7 @@ DOCUMENTATION = r''' 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 I(trust_password) is set, this module send a request for authentication before sending any requests. + - If O(trust_password) is set, this module send a request for authentication before sending any requests. type: str state: description: Filter the instance according to the current status. @@ -62,7 +62,7 @@ DOCUMENTATION = r''' version_added: 6.2.0 type_filter: description: - - Filter the instances by type C(virtual-machine), C(container) or C(both). + - Filter the instances by type V(virtual-machine), V(container) or V(both). - The first version of the inventory only supported containers. type: str default: container @@ -72,8 +72,8 @@ DOCUMENTATION = r''' description: - If an instance has multiple network interfaces, select which one is the prefered as pattern. - Combined with the first number that can be found e.g. 'eth' + 0. - - The option has been renamed from I(prefered_container_network_interface) to I(prefered_instance_network_interface) in community.general 3.8.0. - The old name still works as an alias. + - The option has been renamed from O(ignore:prefered_container_network_interface) to O(prefered_instance_network_interface) + in community.general 3.8.0. The old name still works as an alias. type: str default: eth aliases: @@ -81,7 +81,7 @@ DOCUMENTATION = r''' prefered_instance_network_family: description: - If an instance has multiple network interfaces, which one is the prefered by family. - - Specify C(inet) for IPv4 and C(inet6) for IPv6. + - Specify V(inet) for IPv4 and V(inet6) for IPv6. type: str default: inet choices: [ 'inet', 'inet6' ] diff --git a/plugins/inventory/nmap.py b/plugins/inventory/nmap.py index a03cf3e6fa..6e09e026a8 100644 --- a/plugins/inventory/nmap.py +++ b/plugins/inventory/nmap.py @@ -23,7 +23,7 @@ DOCUMENTATION = ''' required: true choices: ['nmap', 'community.general.nmap'] sudo: - description: Set to C(true) to execute a C(sudo nmap) plugin scan. + description: Set to V(true) to execute a C(sudo nmap) plugin scan. version_added: 4.8.0 default: false type: boolean @@ -36,7 +36,7 @@ DOCUMENTATION = ''' exclude: description: - List of addresses to exclude. - - For example C(10.2.2.15-25) or C(10.2.2.15,10.2.2.16). + - For example V(10.2.2.15-25) or V(10.2.2.15,10.2.2.16). type: list elements: string env: @@ -45,8 +45,8 @@ DOCUMENTATION = ''' port: description: - Only scan specific port or port range (C(-p)). - - For example, you could pass C(22) for a single port, C(1-65535) for a range of ports, - or C(U:53,137,T:21-25,139,8080,S:9) to check port 53 with UDP, ports 21-25 with TCP, port 9 with SCTP, and ports 137, 139, and 8080 with all. + - For example, you could pass V(22) for a single port, V(1-65535) for a range of ports, + or V(U:53,137,T:21-25,139,8080,S:9) to check port 53 with UDP, ports 21-25 with TCP, port 9 with SCTP, and ports 137, 139, and 8080 with all. type: string version_added: 6.5.0 ports: @@ -64,14 +64,14 @@ DOCUMENTATION = ''' udp_scan: description: - Scan via UDP. - - Depending on your system you might need I(sudo=true) for this to work. + - Depending on your system you might need O(sudo=true) for this to work. type: boolean default: false version_added: 6.1.0 icmp_timestamp: description: - Scan via ICMP Timestamp (C(-PP)). - - Depending on your system you might need I(sudo=true) for this to work. + - Depending on your system you might need O(sudo=true) for this to work. type: boolean default: false version_added: 6.1.0 @@ -81,7 +81,7 @@ DOCUMENTATION = ''' default: false version_added: 6.5.0 dns_resolve: - description: Whether to always (C(true)) or never (C(false)) do DNS resolution. + description: Whether to always (V(true)) or never (V(false)) do DNS resolution. type: boolean default: false version_added: 6.1.0 diff --git a/plugins/inventory/opennebula.py b/plugins/inventory/opennebula.py index 603920edc2..01c0f02485 100644 --- a/plugins/inventory/opennebula.py +++ b/plugins/inventory/opennebula.py @@ -17,9 +17,9 @@ DOCUMENTATION = r''' - constructed description: - Get inventory hosts from OpenNebula cloud. - - Uses an YAML configuration file ending with either I(opennebula.yml) or I(opennebula.yaml) + - Uses an YAML configuration file ending with either C(opennebula.yml) or C(opennebula.yaml) to set parameter values. - - Uses I(api_authfile), C(~/.one/one_auth), or C(ONE_AUTH) pointing to a OpenNebula credentials file. + - Uses O(api_authfile), C(~/.one/one_auth), or E(ONE_AUTH) pointing to a OpenNebula credentials file. options: plugin: description: Token that ensures this is a source file for the 'opennebula' plugin. @@ -31,7 +31,7 @@ DOCUMENTATION = r''' - URL of the OpenNebula RPC server. - 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 C(ONE_URL) environment variable is used. + - If not set then the value of the E(ONE_URL) environment variable is used. env: - name: ONE_URL required: true @@ -39,29 +39,29 @@ DOCUMENTATION = r''' api_username: description: - Name of the user to login into the OpenNebula RPC server. If not set - then the value of the C(ONE_USERNAME) environment variable is used. + then the value of the E(ONE_USERNAME) environment variable is used. env: - name: ONE_USERNAME type: string api_password: description: - Password or a token of the user to login into OpenNebula RPC server. - - If not set, the value of the C(ONE_PASSWORD) environment variable is used. + - If not set, the value of the E(ONE_PASSWORD) environment variable is used. env: - name: ONE_PASSWORD required: false type: string api_authfile: description: - - If both I(api_username) or I(api_password) are not set, then it will try + - If both O(api_username) or O(api_password) are not set, then it will try authenticate with ONE auth file. Default path is C(~/.one/one_auth). - - Set environment variable C(ONE_AUTH) to override this path. + - Set environment variable E(ONE_AUTH) to override this path. env: - name: ONE_AUTH required: false type: string hostname: - description: Field to match the hostname. Note C(v4_first_ip) corresponds to the first IPv4 found on VM. + description: Field to match the hostname. Note V(v4_first_ip) corresponds to the first IPv4 found on VM. type: string default: v4_first_ip choices: diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py index dc2e1febca..1389f9ee26 100644 --- a/plugins/inventory/proxmox.py +++ b/plugins/inventory/proxmox.py @@ -25,15 +25,15 @@ DOCUMENTATION = ''' - inventory_cache options: plugin: - description: The name of this plugin, it should always be set to C(community.general.proxmox) for this plugin to recognize it as it's own. + description: The name of this plugin, it should always be set to V(community.general.proxmox) for this plugin to recognize it as it's own. required: true choices: ['community.general.proxmox'] type: str url: description: - URL to Proxmox cluster. - - If the value is not specified in the inventory configuration, the value of environment variable C(PROXMOX_URL) will be used instead. - - Since community.general 4.7.0 you can also use templating to specify the value of the I(url). + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_URL) will be used instead. + - Since community.general 4.7.0 you can also use templating to specify the value of the O(url). default: 'http://localhost:8006' type: str env: @@ -42,8 +42,8 @@ DOCUMENTATION = ''' user: description: - Proxmox authentication user. - - If the value is not specified in the inventory configuration, the value of environment variable C(PROXMOX_USER) will be used instead. - - Since community.general 4.7.0 you can also use templating to specify the value of the I(user). + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_USER) will be used instead. + - Since community.general 4.7.0 you can also use templating to specify the value of the O(user). required: true type: str env: @@ -52,9 +52,9 @@ DOCUMENTATION = ''' password: description: - Proxmox authentication password. - - If the value is not specified in the inventory configuration, the value of environment variable C(PROXMOX_PASSWORD) will be used instead. - - Since community.general 4.7.0 you can also use templating to specify the value of the I(password). - - If you do not specify a password, you must set I(token_id) and I(token_secret) instead. + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_PASSWORD) will be used instead. + - Since community.general 4.7.0 you can also use templating to specify the value of the O(password). + - If you do not specify a password, you must set O(token_id) and O(token_secret) instead. type: str env: - name: PROXMOX_PASSWORD @@ -62,8 +62,8 @@ DOCUMENTATION = ''' token_id: description: - Proxmox authentication token ID. - - If the value is not specified in the inventory configuration, the value of environment variable C(PROXMOX_TOKEN_ID) will be used instead. - - To use token authentication, you must also specify I(token_secret). If you do not specify I(token_id) and I(token_secret), + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_ID) will be used instead. + - To use token authentication, you must also specify O(token_secret). If you do not specify O(token_id) and O(token_secret), you must set a password instead. - Make sure to grant explicit pve permissions to the token or disable 'privilege separation' to use the users' privileges instead. version_added: 4.8.0 @@ -73,8 +73,8 @@ DOCUMENTATION = ''' token_secret: description: - Proxmox authentication token secret. - - If the value is not specified in the inventory configuration, the value of environment variable C(PROXMOX_TOKEN_SECRET) will be used instead. - - To use token authentication, you must also specify I(token_id). If you do not specify I(token_id) and I(token_secret), + - If the value is not specified in the inventory configuration, the value of environment variable E(PROXMOX_TOKEN_SECRET) will be used instead. + - To use token authentication, you must also specify O(token_id). If you do not specify O(token_id) and O(token_secret), you must set a password instead. version_added: 4.8.0 type: str @@ -95,25 +95,25 @@ DOCUMENTATION = ''' want_facts: description: - Gather LXC/QEMU configuration facts. - - When I(want_facts) is set to C(true) more details about QEMU VM status are possible, besides the running and stopped states. + - When O(want_facts) is set to V(true) more details about QEMU VM status are possible, besides the running and stopped states. Currently if the VM is running and it is suspended, the status will be running and the machine will be in C(running) group, - but its actual state will be paused. See I(qemu_extended_statuses) for how to retrieve the real status. + but its actual state will be paused. See O(qemu_extended_statuses) for how to retrieve the real status. default: false type: bool qemu_extended_statuses: description: - - Requires I(want_facts) to be set to C(true) to function. This will allow you to differentiate betweend C(paused) and C(prelaunch) + - Requires O(want_facts) to be set to V(true) to function. This will allow you to differentiate betweend C(paused) and C(prelaunch) statuses of the QEMU VMs. - - This introduces multiple groups [prefixed with I(group_prefix)] C(prelaunch) and C(paused). + - This introduces multiple groups [prefixed with O(group_prefix)] C(prelaunch) and C(paused). default: false type: bool version_added: 5.1.0 want_proxmox_nodes_ansible_host: version_added: 3.0.0 description: - - Whether to set C(ansbile_host) for proxmox nodes. - - When set to C(true) (default), will use the first available interface. This can be different from what you expect. - - The default of this option changed from C(true) to C(false) in community.general 6.0.0. + - Whether to set C(ansible_host) for proxmox nodes. + - When set to V(true) (default), will use the first available interface. This can be different from what you expect. + - The default of this option changed from V(true) to V(false) in community.general 6.0.0. type: bool default: false filters: diff --git a/plugins/inventory/scaleway.py b/plugins/inventory/scaleway.py index 6aacc9f665..632f08402f 100644 --- a/plugins/inventory/scaleway.py +++ b/plugins/inventory/scaleway.py @@ -37,7 +37,7 @@ DOCUMENTATION = r''' scw_profile: description: - The config profile to use in config file. - - By default uses the one specified as C(active_profile) in the config file, or falls back to C(default) if that is not defined. + - By default uses the one specified as C(active_profile) in the config file, or falls back to V(default) if that is not defined. type: string version_added: 4.4.0 oauth_token: diff --git a/plugins/inventory/xen_orchestra.py b/plugins/inventory/xen_orchestra.py index ddbdd9bb04..3004ab3432 100644 --- a/plugins/inventory/xen_orchestra.py +++ b/plugins/inventory/xen_orchestra.py @@ -23,21 +23,21 @@ DOCUMENTATION = ''' - inventory_cache options: plugin: - description: The name of this plugin, it should always be set to C(community.general.xen_orchestra) for this plugin to recognize it as its own. + description: The name of this plugin, it should always be set to V(community.general.xen_orchestra) for this plugin to recognize it as its own. required: true choices: ['community.general.xen_orchestra'] type: str api_host: description: - API host to XOA API. - - If the value is not specified in the inventory configuration, the value of environment variable C(ANSIBLE_XO_HOST) will be used instead. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_HOST) will be used instead. type: str env: - name: ANSIBLE_XO_HOST user: description: - Xen Orchestra user. - - If the value is not specified in the inventory configuration, the value of environment variable C(ANSIBLE_XO_USER) will be used instead. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_USER) will be used instead. required: true type: str env: @@ -45,7 +45,7 @@ DOCUMENTATION = ''' password: description: - Xen Orchestra password. - - If the value is not specified in the inventory configuration, the value of environment variable C(ANSIBLE_XO_PASSWORD) will be used instead. + - If the value is not specified in the inventory configuration, the value of environment variable E(ANSIBLE_XO_PASSWORD) will be used instead. required: true type: str env: diff --git a/plugins/lookup/bitwarden.py b/plugins/lookup/bitwarden.py index 27de1afe60..489b0d5d9c 100644 --- a/plugins/lookup/bitwarden.py +++ b/plugins/lookup/bitwarden.py @@ -25,7 +25,7 @@ DOCUMENTATION = """ type: list elements: str search: - description: Field to retrieve, for example C(name) or C(id). + description: Field to retrieve, for example V(name) or V(id). type: str default: name version_added: 5.7.0 diff --git a/plugins/lookup/collection_version.py b/plugins/lookup/collection_version.py index 4d25585b81..0e2388a181 100644 --- a/plugins/lookup/collection_version.py +++ b/plugins/lookup/collection_version.py @@ -13,22 +13,22 @@ short_description: Retrieves the version of an installed collection description: - This lookup allows to query the version of an installed collection, and to determine whether a collection is installed at all. - - By default it returns C(none) for non-existing collections and C(*) for collections without a + - By default it returns V(none) for non-existing collections and V(*) for collections without a version number. The latter should only happen in development environments, or when installing a collection from git which has no version in its C(galaxy.yml). This behavior can be adjusted - by providing other values with I(result_not_found) and I(result_no_version). + by providing other values with O(result_not_found) and O(result_no_version). options: _terms: description: - The collections to look for. - - For example C(community.general). + - For example V(community.general). type: list elements: str required: true result_not_found: description: - The value to return when the collection could not be found. - - By default, C(none) is returned. + - By default, V(none) is returned. type: string default: ~ result_no_version: @@ -36,7 +36,7 @@ options: - The value to return when the collection has no version number. - This can happen for collections installed from git which do not have a version number in C(galaxy.yml). - - By default, C(*) is returned. + - By default, V(*) is returned. type: string default: '*' """ @@ -51,11 +51,11 @@ RETURN = """ _raw: description: - The version number of the collections listed as input. - - If a collection can not be found, it will return the value provided in I(result_not_found). - By default, this is C(none). + - If a collection can not be found, it will return the value provided in O(result_not_found). + By default, this is V(none). - If a collection can be found, but the version not identified, it will return the value provided in - I(result_no_version). By default, this is C(*). This can happen for collections installed - from git which do not have a version number in C(galaxy.yml). + O(result_no_version). By default, this is V(*). This can happen for collections installed + from git which do not have a version number in V(galaxy.yml). type: list elements: str """ diff --git a/plugins/lookup/consul_kv.py b/plugins/lookup/consul_kv.py index f17f1b2694..f8aadadc19 100644 --- a/plugins/lookup/consul_kv.py +++ b/plugins/lookup/consul_kv.py @@ -38,23 +38,20 @@ DOCUMENTATION = ''' default: localhost description: - The target to connect to, must be a resolvable address. - Will be determined from C(ANSIBLE_CONSUL_URL) if that is set. - - "C(ANSIBLE_CONSUL_URL) should look like this: C(https://my.consul.server:8500)" - env: - - name: ANSIBLE_CONSUL_URL + - Will be determined from E(ANSIBLE_CONSUL_URL) if that is set. ini: - section: lookup_consul key: host port: description: - The port of the target host to connect to. - - If you use C(ANSIBLE_CONSUL_URL) this value will be used from there. + - If you use E(ANSIBLE_CONSUL_URL) this value will be used from there. default: 8500 scheme: default: http description: - Whether to use http or https. - - If you use C(ANSIBLE_CONSUL_URL) this value will be used from there. + - If you use E(ANSIBLE_CONSUL_URL) this value will be used from there. validate_certs: default: true description: Whether to verify the ssl connection or not. @@ -71,7 +68,9 @@ DOCUMENTATION = ''' - section: lookup_consul key: client_cert url: - description: "The target to connect to, should look like this: C(https://my.consul.server:8500)." + description: + - The target to connect to. + - "Should look like this: V(https://my.consul.server:8500)." type: str version_added: 1.0.0 env: diff --git a/plugins/lookup/dig.py b/plugins/lookup/dig.py index fa915220b3..afeab28f44 100644 --- a/plugins/lookup/dig.py +++ b/plugins/lookup/dig.py @@ -21,7 +21,7 @@ DOCUMENTATION = ''' - In addition to (default) A record, it is also possible to specify a different record type that should be queried. This can be done by either passing-in additional parameter of format qtype=TYPE to the dig lookup, or by appending /TYPE to the FQDN being queried. - If multiple values are associated with the requested record, the results will be returned as a comma-separated list. - In such cases you may want to pass option I(wantlist=true) to the lookup call, or alternatively use C(query) instead of C(lookup), + In such cases you may want to pass option C(wantlist=true) to the lookup call, or alternatively use C(query) instead of C(lookup), which will result in the record values being returned as a list over which you can iterate later on. - By default, the lookup will rely on system-wide configured DNS servers for performing the query. It is also possible to explicitly specify DNS servers to query using the @DNS_SERVER_1,DNS_SERVER_2,...,DNS_SERVER_N notation. @@ -34,8 +34,8 @@ DOCUMENTATION = ''' qtype: description: - Record type to query. - - C(DLV) has been removed in community.general 6.0.0. - - C(CAA) has been added in community.general 6.3.0. + - V(DLV) has been removed in community.general 6.0.0. + - V(CAA) has been added in community.general 6.3.0. type: str default: 'A' choices: [A, ALL, AAAA, CAA, CNAME, DNAME, DNSKEY, DS, HINFO, LOC, MX, NAPTR, NS, NSEC3PARAM, PTR, RP, RRSIG, SOA, SPF, SRV, SSHFP, TLSA, TXT] @@ -51,17 +51,17 @@ DOCUMENTATION = ''' fail_on_error: description: - Abort execution on lookup errors. - - The default for this option will likely change to C(true) in the future. - The current default, C(false), is used for backwards compatibility, and will result in empty strings - or the string C(NXDOMAIN) in the result in case of errors. + - The default for this option will likely change to V(true) in the future. + The current default, V(false), is used for backwards compatibility, and will result in empty strings + or the string V(NXDOMAIN) in the result in case of errors. default: false type: bool version_added: 5.4.0 real_empty: description: - - Return empty result without empty strings, and return empty list instead of C(NXDOMAIN). - - The default for this option will likely change to C(true) in the future. - - This option will be forced to C(true) if multiple domains to be queried are specified. + - Return empty result without empty strings, and return empty list instead of V(NXDOMAIN). + - The default for this option will likely change to V(true) in the future. + - This option will be forced to V(true) if multiple domains to be queried are specified. default: false type: bool version_added: 6.0.0 diff --git a/plugins/lookup/dnstxt.py b/plugins/lookup/dnstxt.py index 55067dc82b..1ce511b849 100644 --- a/plugins/lookup/dnstxt.py +++ b/plugins/lookup/dnstxt.py @@ -22,8 +22,8 @@ DOCUMENTATION = ''' elements: string real_empty: description: - - Return empty result without empty strings, and return empty list instead of C(NXDOMAIN). - - The default for this option will likely change to C(true) in the future. + - Return empty result without empty strings, and return empty list instead of V(NXDOMAIN). + - The default for this option will likely change to V(true) in the future. default: false type: bool version_added: 6.0.0 diff --git a/plugins/lookup/dsv.py b/plugins/lookup/dsv.py index 91a9d99212..2dbb7db3ea 100644 --- a/plugins/lookup/dsv.py +++ b/plugins/lookup/dsv.py @@ -13,15 +13,15 @@ short_description: Get secrets from Thycotic DevOps Secrets Vault version_added: 1.0.0 description: - Uses the Thycotic DevOps Secrets Vault Python SDK to get Secrets from a - DSV I(tenant) using a I(client_id) and I(client_secret). + DSV O(tenant) using a O(client_id) and O(client_secret). requirements: - python-dsv-sdk - https://pypi.org/project/python-dsv-sdk/ options: _terms: - description: The path to the secret, e.g. C(/staging/servers/web1). + description: The path to the secret, for example V(/staging/servers/web1). required: true tenant: - description: The first format parameter in the default I(url_template). + description: The first format parameter in the default O(url_template). env: - name: DSV_TENANT ini: @@ -31,7 +31,7 @@ options: tld: default: com description: The top-level domain of the tenant; the second format - parameter in the default I(url_template). + parameter in the default O(url_template). env: - name: DSV_TLD ini: @@ -47,7 +47,7 @@ options: key: client_id required: true client_secret: - description: The client secret associated with the specific I(client_id). + description: The client secret associated with the specific O(client_id). env: - name: DSV_CLIENT_SECRET ini: diff --git a/plugins/lookup/etcd3.py b/plugins/lookup/etcd3.py index 7f0a0cf90e..2d71902c6d 100644 --- a/plugins/lookup/etcd3.py +++ b/plugins/lookup/etcd3.py @@ -32,10 +32,10 @@ DOCUMENTATION = ''' default: false endpoints: description: - - Counterpart of C(ETCDCTL_ENDPOINTS) environment variable. - Specify the etcd3 connection with and URL form eg. C(https://hostname:2379) or C(:) form. - - The C(host) part is overwritten by I(host) option, if defined. - - The C(port) part is overwritten by I(port) option, if defined. + - Counterpart of E(ETCDCTL_ENDPOINTS) environment variable. + Specify the etcd3 connection with and URL form, for example V(https://hostname:2379), or V(:) form. + - The V(host) part is overwritten by O(host) option, if defined. + - The V(port) part is overwritten by O(port) option, if defined. env: - name: ETCDCTL_ENDPOINTS default: '127.0.0.1:2379' @@ -43,12 +43,12 @@ DOCUMENTATION = ''' host: description: - etcd3 listening client host. - - Takes precedence over I(endpoints). + - Takes precedence over O(endpoints). type: str port: description: - etcd3 listening client port. - - Takes precedence over I(endpoints). + - Takes precedence over O(endpoints). type: int ca_cert: description: @@ -89,9 +89,9 @@ DOCUMENTATION = ''' type: str notes: - - I(host) and I(port) options take precedence over (endpoints) option. - - The recommended way to connect to etcd3 server is using C(ETCDCTL_ENDPOINT) - environment variable and keep I(endpoints), I(host), and I(port) unused. + - O(host) and O(port) options take precedence over (endpoints) option. + - The recommended way to connect to etcd3 server is using E(ETCDCTL_ENDPOINT) + environment variable and keep O(endpoints), O(host), and O(port) unused. seealso: - module: community.general.etcd3 - ref: ansible_collections.community.general.etcd_lookup diff --git a/plugins/lookup/filetree.py b/plugins/lookup/filetree.py index f12cc45192..2131de99a5 100644 --- a/plugins/lookup/filetree.py +++ b/plugins/lookup/filetree.py @@ -65,7 +65,7 @@ RETURN = r""" src: description: - Full path to file. - - Not returned when I(item.state) is set to C(directory). + - Not returned when RV(_raw[].state) is set to V(directory). type: path root: description: Allows filtering by original location. diff --git a/plugins/lookup/lmdb_kv.py b/plugins/lookup/lmdb_kv.py index 0950249dc8..a37cff9569 100644 --- a/plugins/lookup/lmdb_kv.py +++ b/plugins/lookup/lmdb_kv.py @@ -15,7 +15,7 @@ DOCUMENTATION = ''' description: - This lookup returns a list of results from an LMDB DB corresponding to a list of items given to it. requirements: - - lmdb (python library https://lmdb.readthedocs.io/en/release/) + - lmdb (Python library U(https://lmdb.readthedocs.io/en/release/)) options: _terms: description: List of keys to query. diff --git a/plugins/lookup/merge_variables.py b/plugins/lookup/merge_variables.py index cd5fa5b7df..dbd9401b10 100644 --- a/plugins/lookup/merge_variables.py +++ b/plugins/lookup/merge_variables.py @@ -19,7 +19,7 @@ DOCUMENTATION = """ options: _terms: description: - - Depending on the value of I(pattern_type), this is a list of prefixes, suffixes, or regular expressions + - Depending on the value of O(pattern_type), this is a list of prefixes, suffixes, or regular expressions that will be used to match all variables that should be merged. required: true type: list @@ -45,11 +45,11 @@ DOCUMENTATION = """ override: description: - Return an error, print a warning or ignore it when a key will be overwritten. - - The default behavior C(error) makes the plugin fail when a key would be overwritten. - - When C(warn) and C(ignore) are used, note that it is important to know that the variables + - The default behavior V(error) makes the plugin fail when a key would be overwritten. + - When V(warn) and V(ignore) are used, note that it is important to know that the variables are sorted by name before being merged. Keys for later variables in this order will overwrite keys of the same name for variables earlier in this order. To avoid potential confusion, - better use I(override=error) whenever possible. + better use O(override=error) whenever possible. type: str default: 'error' choices: diff --git a/plugins/lookup/onepassword.py b/plugins/lookup/onepassword.py index 0e78e4b1a0..3a939f3d95 100644 --- a/plugins/lookup/onepassword.py +++ b/plugins/lookup/onepassword.py @@ -18,7 +18,7 @@ DOCUMENTATION = ''' - C(op) 1Password command line utility. See U(https://support.1password.com/command-line/) short_description: fetch field values from 1Password description: - - C(onepassword) wraps the C(op) command line utility to fetch specific field values from 1Password. + - P(community.general.onepassword#lookup) wraps the C(op) command line utility to fetch specific field values from 1Password. options: _terms: description: identifier(s) (UUID, name, or subdomain; case-insensitive) of item(s) to retrieve. @@ -47,8 +47,8 @@ DOCUMENTATION = ''' notes: - This lookup will use an existing 1Password session if one exists. If not, and you have already performed an initial sign in (meaning C(~/.op/config), C(~/.config/op/config) or C(~/.config/.op/config) exists), then only the - C(master_password) is required. You may optionally specify C(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op). - - This lookup can perform an initial login by providing C(subdomain), C(username), C(secret_key), and C(master_password). + C(master_password) is required. You may optionally specify O(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op). + - This lookup can perform an initial login by providing O(subdomain), O(username), O(secret_key), and O(master_password). - Due to the B(very) sensitive nature of these credentials, it is B(highly) recommended that you only pass in the minimal credentials needed at any given time. Also, store these credentials in an Ansible Vault using a key that is equal to or greater in strength to the 1Password master password. diff --git a/plugins/lookup/onepassword_raw.py b/plugins/lookup/onepassword_raw.py index 9b87a3f619..4322d5174a 100644 --- a/plugins/lookup/onepassword_raw.py +++ b/plugins/lookup/onepassword_raw.py @@ -18,7 +18,7 @@ DOCUMENTATION = ''' - C(op) 1Password command line utility. See U(https://support.1password.com/command-line/) short_description: fetch an entire item from 1Password description: - - C(onepassword_raw) wraps C(op) command line utility to fetch an entire item from 1Password + - P(community.general.onepassword_raw#lookup) wraps C(op) command line utility to fetch an entire item from 1Password. options: _terms: description: identifier(s) (UUID, name, or domain; case-insensitive) of item(s) to retrieve. @@ -43,9 +43,9 @@ DOCUMENTATION = ''' description: Vault containing the item to retrieve (case-insensitive). If absent will search all vaults. notes: - This lookup will use an existing 1Password session if one exists. If not, and you have already - performed an initial sign in (meaning C(~/.op/config exists)), then only the C(master_password) is required. - You may optionally specify C(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op). - - This lookup can perform an initial login by providing C(subdomain), C(username), C(secret_key), and C(master_password). + performed an initial sign in (meaning C(~/.op/config exists)), then only the O(master_password) is required. + You may optionally specify O(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op). + - This lookup can perform an initial login by providing O(subdomain), O(username), O(secret_key), and O(master_password). - Due to the B(very) sensitive nature of these credentials, it is B(highly) recommended that you only pass in the minimal credentials needed at any given time. Also, store these credentials in an Ansible Vault using a key that is equal to or greater in strength to the 1Password master password. diff --git a/plugins/lookup/passwordstore.py b/plugins/lookup/passwordstore.py index 7e37a37855..4a1ff1320b 100644 --- a/plugins/lookup/passwordstore.py +++ b/plugins/lookup/passwordstore.py @@ -16,7 +16,7 @@ DOCUMENTATION = ''' - Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility. It also retrieves YAML style keys stored as multilines in the passwordfile. - To avoid problems when accessing multiple secrets at once, add C(auto-expand-secmem) to - C(~/.gnupg/gpg-agent.conf). Where this is not possible, consider using I(lock=readwrite) instead. + C(~/.gnupg/gpg-agent.conf). Where this is not possible, consider using O(lock=readwrite) instead. options: _terms: description: query key. @@ -24,16 +24,16 @@ DOCUMENTATION = ''' directory: description: - The directory of the password store. - - If I(backend=pass), the default is C(~/.password-store) is used. - - If I(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml), - falling back to C(~/.local/share/gopass/stores/root) if C(path) is not defined in the gopass config. + - If O(backend=pass), the default is V(~/.password-store) is used. + - If O(backend=gopass), then the default is the C(path) field in C(~/.config/gopass/config.yml), + falling back to V(~/.local/share/gopass/stores/root) if C(path) is not defined in the gopass config. type: path vars: - name: passwordstore env: - name: PASSWORD_STORE_DIR create: - description: Create the password if it does not already exist. Takes precedence over C(missing). + description: Create the password if it does not already exist. Takes precedence over O(missing). type: bool default: false overwrite: @@ -43,7 +43,7 @@ DOCUMENTATION = ''' umask: description: - Sets the umask for the created .gpg files. The first octed must be greater than 3 (user readable). - - Note pass' default value is C('077'). + - Note pass' default value is V('077'). env: - name: PASSWORD_STORE_UMASK version_added: 1.3.0 @@ -52,7 +52,7 @@ DOCUMENTATION = ''' type: bool default: false subkey: - description: Return a specific subkey of the password. When set to C(password), always returns the first line. + description: Return a specific subkey of the password. When set to V(password), always returns the first line. type: str default: password userpass: @@ -63,7 +63,7 @@ DOCUMENTATION = ''' type: integer default: 16 backup: - description: Used with C(overwrite=true). Backup the previous password in a subkey. + description: Used with O(overwrite=true). Backup the previous password in a subkey. type: bool default: false nosymbols: @@ -73,10 +73,10 @@ DOCUMENTATION = ''' missing: description: - List of preference about what to do if the password file is missing. - - If I(create=true), the value for this option is ignored and assumed to be C(create). - - If set to C(error), the lookup will error out if the passname does not exist. - - If set to C(create), the passname will be created with the provided length I(length) if it does not exist. - - If set to C(empty) or C(warn), will return a C(none) in case the passname does not exist. + - If O(create=true), the value for this option is ignored and assumed to be V(create). + - If set to V(error), the lookup will error out if the passname does not exist. + - If set to V(create), the passname will be created with the provided length O(length) if it does not exist. + - If set to V(empty) or V(warn), will return a V(none) in case the passname does not exist. When using C(lookup) and not C(query), this will be translated to an empty string. version_added: 3.1.0 type: str @@ -89,9 +89,9 @@ DOCUMENTATION = ''' lock: description: - How to synchronize operations. - - The default of C(write) only synchronizes write operations. - - C(readwrite) synchronizes all operations (including read). This makes sure that gpg-agent is never called in parallel. - - C(none) does not do any synchronization. + - The default of V(write) only synchronizes write operations. + - V(readwrite) synchronizes all operations (including read). This makes sure that gpg-agent is never called in parallel. + - V(none) does not do any synchronization. ini: - section: passwordstore_lookup key: lock @@ -104,8 +104,8 @@ DOCUMENTATION = ''' version_added: 4.5.0 locktimeout: description: - - Lock timeout applied when I(lock) is not C(none). - - Time with a unit suffix, C(s), C(m), C(h) for seconds, minutes, and hours, respectively. For example, C(900s) equals C(15m). + - Lock timeout applied when O(lock) is not V(none). + - Time with a unit suffix, V(s), V(m), V(h) for seconds, minutes, and hours, respectively. For example, V(900s) equals V(15m). - Correlates with C(pinentry-timeout) in C(~/.gnupg/gpg-agent.conf), see C(man gpg-agent) for details. ini: - section: passwordstore_lookup @@ -116,8 +116,8 @@ DOCUMENTATION = ''' backend: description: - Specify which backend to use. - - Defaults to C(pass), passwordstore.org's original pass utility. - - C(gopass) support is incomplete. + - Defaults to V(pass), passwordstore.org's original pass utility. + - V(gopass) support is incomplete. ini: - section: passwordstore_lookup key: backend diff --git a/plugins/lookup/random_string.py b/plugins/lookup/random_string.py index 199aa13964..89333492ad 100644 --- a/plugins/lookup/random_string.py +++ b/plugins/lookup/random_string.py @@ -42,25 +42,25 @@ DOCUMENTATION = r""" - Special characters are taken from Python standard library C(string). See L(the documentation of string.punctuation,https://docs.python.org/3/library/string.html#string.punctuation) for which characters will be used. - - The choice of special characters can be changed to setting I(override_special). + - The choice of special characters can be changed to setting O(override_special). default: true type: bool min_numeric: description: - Minimum number of numeric characters in the string. - - If set, overrides I(numbers=false). + - If set, overrides O(numbers=false). default: 0 type: int min_upper: description: - Minimum number of uppercase alphabets in the string. - - If set, overrides I(upper=false). + - If set, overrides O(upper=false). default: 0 type: int min_lower: description: - Minimum number of lowercase alphabets in the string. - - If set, overrides I(lower=false). + - If set, overrides O(lower=false). default: 0 type: int min_special: @@ -71,11 +71,11 @@ DOCUMENTATION = r""" override_special: description: - Overide a list of special characters to use in the string. - - If set I(min_special) should be set to a non-default value. + - If set O(min_special) should be set to a non-default value. type: str override_all: description: - - Override all values of I(numbers), I(upper), I(lower), and I(special) with + - Override all values of O(numbers), O(upper), O(lower), and O(special) with the given list of characters. type: str base64: diff --git a/plugins/lookup/revbitspss.py b/plugins/lookup/revbitspss.py index 552970804e..9912400b70 100644 --- a/plugins/lookup/revbitspss.py +++ b/plugins/lookup/revbitspss.py @@ -25,7 +25,7 @@ options: elements: string base_url: description: - - This will be the base URL of the server, for example C(https://server-url-here). + - This will be the base URL of the server, for example V(https://server-url-here). required: true type: string api_key: diff --git a/plugins/lookup/tss.py b/plugins/lookup/tss.py index df7d57993b..1fe87b31ec 100644 --- a/plugins/lookup/tss.py +++ b/plugins/lookup/tss.py @@ -13,8 +13,8 @@ short_description: Get secrets from Thycotic Secret Server version_added: 1.0.0 description: - Uses the Thycotic Secret Server Python SDK to get Secrets from Secret - Server using token authentication with I(username) and I(password) on - the REST API at I(base_url). + Server using token authentication with O(username) and O(password) on + the REST API at O(base_url). - When using self-signed certificates the environment variable C(REQUESTS_CA_BUNDLE) can be set to a file containing the trusted certificates (in C(.pem) format). @@ -36,7 +36,7 @@ options: fetch_attachments: description: - Boolean flag which indicates whether attached files will get downloaded or not. - - The download will only happen if I(file_download_path) has been provided. + - The download will only happen if O(file_download_path) has been provided. required: false type: bool version_added: 7.0.0 @@ -46,7 +46,7 @@ options: type: path version_added: 7.0.0 base_url: - description: The base URL of the server, e.g. C(https://localhost/SecretServer). + description: The base URL of the server, for example V(https://localhost/SecretServer). env: - name: TSS_BASE_URL ini: @@ -63,7 +63,7 @@ options: password: description: - The password associated with the supplied username. - - Required when I(token) is not provided. + - Required when O(token) is not provided. env: - name: TSS_PASSWORD ini: @@ -73,7 +73,7 @@ options: default: "" description: - The domain with which to request the OAuth2 Access Grant. - - Optional when I(token) is not provided. + - Optional when O(token) is not provided. - Requires C(python-tss-sdk) version 1.0.0 or greater. env: - name: TSS_DOMAIN @@ -85,7 +85,7 @@ options: token: description: - Existing token for Thycotic authorizer. - - If provided, I(username) and I(password) are not needed. + - If provided, O(username) and O(password) are not needed. - Requires C(python-tss-sdk) version 1.0.0 or greater. env: - name: TSS_TOKEN diff --git a/plugins/modules/ufw.py b/plugins/modules/ufw.py index 45c98fd639..5d187793bd 100644 --- a/plugins/modules/ufw.py +++ b/plugins/modules/ufw.py @@ -35,10 +35,10 @@ attributes: options: state: description: - - C(enabled) reloads firewall and enables firewall on boot. - - C(disabled) unloads firewall and disables firewall on boot. - - C(reloaded) reloads firewall. - - C(reset) disables and resets firewall to installation defaults. + - V(enabled) reloads firewall and enables firewall on boot. + - V(disabled) unloads firewall and disables firewall on boot. + - V(reloaded) reloads firewall. + - V(reset) disables and resets firewall to installation defaults. type: str choices: [ disabled, enabled, reloaded, reset ] default: @@ -50,7 +50,7 @@ options: direction: description: - Select direction for a rule or default policy command. Mutually - exclusive with I(interface_in) and I(interface_out). + exclusive with O(interface_in) and O(interface_out). type: str choices: [ in, incoming, out, outgoing, routed ] logging: @@ -62,24 +62,24 @@ options: description: - Insert the corresponding rule as rule number NUM. - Note that ufw numbers rules starting with 1. - - If I(delete=true) and a value is provided for I(insert), - then I(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 I(insert) relative to a position. - - C(zero) interprets the rule number as an absolute index (i.e. 1 is + - 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). - - C(first-ipv4) interprets the rule number relative to the index of the + - 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. - - C(last-ipv4) interprets the rule number relative to the index of the + - 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. - - C(first-ipv6) interprets the rule number relative to the index of the + - 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. - - C(last-ipv6) interprets the rule number relative to the index of the + - 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 @@ -130,32 +130,32 @@ options: delete: description: - Delete rule. - - If I(delete=true) and a value is provided for I(insert), - then I(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 I(direction). See - I(interface_in) and I(interface_out) for routed rules that needs + 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 I(interface_in) and I(interface_out). + exclusive with O(interface_in) and O(interface_out). type: str aliases: [ if ] interface_in: description: - Specify input interface for the rule. This is mutually - exclusive with I(direction) and I(interface). However, it is - compatible with I(interface_out) for routed rules. + exclusive with O(direction) and O(interface). However, it is + compatible with O(interface_out) for routed rules. type: str aliases: [ if_in ] version_added: '0.2.0' interface_out: description: - Specify output interface for the rule. This is mutually - exclusive with I(direction) and I(interface). However, it is - compatible with I(interface_in) for routed rules. + exclusive with O(direction) and O(interface). However, it is + compatible with O(interface_in) for routed rules. type: str aliases: [ if_out ] version_added: '0.2.0' From 78c42def04931339e231fddf549b5e65cf67ae4f Mon Sep 17 00:00:00 2001 From: Pino Toscano Date: Sat, 10 Jun 2023 13:26:14 +0200 Subject: [PATCH 0045/1451] Deprecate module_utils.redhat (#6663) This module contains bits that are either unused (the Rhsm* classes), or used only by deprecated modules (the RegistrationBase class). Considering that the bits here have not seen updates in years, it is unlikely that anyone is actually using them as "library". Hence, deprecate the whole module altogether: - the Rhsm* classes, as not used by anything, are slated for removal in 9.0.0 - the RegistrationBase class is slated for removal in 10.0.0, together with its only user (i.e. the rhn_register module) --- .../6663-deprecate-module_utils-redhat.yml | 11 ++++ plugins/module_utils/redhat.py | 52 +++++++++++++++++-- 2 files changed, 59 insertions(+), 4 deletions(-) create mode 100644 changelogs/fragments/6663-deprecate-module_utils-redhat.yml diff --git a/changelogs/fragments/6663-deprecate-module_utils-redhat.yml b/changelogs/fragments/6663-deprecate-module_utils-redhat.yml new file mode 100644 index 0000000000..b36d43742f --- /dev/null +++ b/changelogs/fragments/6663-deprecate-module_utils-redhat.yml @@ -0,0 +1,11 @@ +deprecated_features: + - | + redhat module utils - the ``module_utils.redhat`` module is deprecated, as + effectively unused: the ``Rhsm``, ``RhsmPool``, and ``RhsmPools`` classes + will be removed in community.general 9.0.0; the ``RegistrationBase`` class + will be removed in community.general 10.0.0 together with the + ``rhn_register`` module, as it is the only user of this class; this means + that the whole ``module_utils.redhat`` module will be dropped in + community.general 10.0.0, so importing it without even using anything of it + will fail + (https://github.com/ansible-collections/community.general/pull/6663). diff --git a/plugins/module_utils/redhat.py b/plugins/module_utils/redhat.py index f82cffaa0d..110159ddfc 100644 --- a/plugins/module_utils/redhat.py +++ b/plugins/module_utils/redhat.py @@ -24,6 +24,14 @@ from ansible.module_utils.six.moves import configparser class RegistrationBase(object): + """ + DEPRECATION WARNING + + This class is deprecated and will be removed in community.general 10.0.0. + There is no replacement for it; please contact the community.general + maintainers in case you are using it. + """ + def __init__(self, module, username=None, password=None): self.module = module self.username = username @@ -71,10 +79,23 @@ class RegistrationBase(object): class Rhsm(RegistrationBase): + """ + DEPRECATION WARNING + + This class is deprecated and will be removed in community.general 9.0.0. + There is no replacement for it; please contact the community.general + maintainers in case you are using it. + """ + def __init__(self, module, username=None, password=None): RegistrationBase.__init__(self, module, username, password) self.config = self._read_config() self.module = module + self.module.deprecate( + 'The Rhsm class is deprecated with no replacement.', + version='9.0.0', + collection_name='community.general', + ) def _read_config(self, rhsm_conf='/etc/rhsm/rhsm.conf'): ''' @@ -200,14 +221,25 @@ class Rhsm(RegistrationBase): class RhsmPool(object): - ''' - Convenience class for housing subscription information - ''' + """ + Convenience class for housing subscription information + + DEPRECATION WARNING + + This class is deprecated and will be removed in community.general 9.0.0. + There is no replacement for it; please contact the community.general + maintainers in case you are using it. + """ def __init__(self, module, **kwargs): self.module = module for k, v in kwargs.items(): setattr(self, k, v) + self.module.deprecate( + 'The RhsmPool class is deprecated with no replacement.', + version='9.0.0', + collection_name='community.general', + ) def __str__(self): return str(self.__getattribute__('_name')) @@ -223,11 +255,23 @@ class RhsmPool(object): class RhsmPools(object): """ - This class is used for manipulating pools subscriptions with RHSM + This class is used for manipulating pools subscriptions with RHSM + + DEPRECATION WARNING + + This class is deprecated and will be removed in community.general 9.0.0. + There is no replacement for it; please contact the community.general + maintainers in case you are using it. """ + def __init__(self, module): self.module = module self.products = self._load_product_list() + self.module.deprecate( + 'The RhsmPools class is deprecated with no replacement.', + version='9.0.0', + collection_name='community.general', + ) def __iter__(self): return self.products.__iter__() From 42f7531f212c6401ca351de62bde0369916d8e58 Mon Sep 17 00:00:00 2001 From: Pino Toscano Date: Sat, 10 Jun 2023 15:03:34 +0200 Subject: [PATCH 0046/1451] redhat_subscription: refactor of internal Rhsm class (#6658) The two RegistrationBase & Rhsm classes were copied from the ones in the shared module_utils.redhat module; that said: - the versions here got improvements over the years - the RegistrationBase in module_utils.redhat is used only by the RHN modules, which are deprecated and slated for removal Hence, the classes here can be kept and simplified a bit: - fold the non-dummy content of RegistrationBase into Rhsm: there is no more need for the separate RegistrationBase base class - drop the init arguments "username", "password", and "token": the instance variables of them are not used anywhere, as the needed credentials (together with other variables) are passed to the register() method - create the Rhsm object later in main(), after the AnsibleModule creation and the uid check: this avoids the creation of Rhsm with a null module variable, changing it later There should be no behaviour change. --- ...at_subscription-internal-rhsm-refactor.yml | 6 +++ plugins/modules/redhat_subscription.py | 44 ++++--------------- .../modules/test_redhat_subscription.py | 2 +- 3 files changed, 15 insertions(+), 37 deletions(-) create mode 100644 changelogs/fragments/6658-redhat_subscription-internal-rhsm-refactor.yml diff --git a/changelogs/fragments/6658-redhat_subscription-internal-rhsm-refactor.yml b/changelogs/fragments/6658-redhat_subscription-internal-rhsm-refactor.yml new file mode 100644 index 0000000000..ad0f4742a1 --- /dev/null +++ b/changelogs/fragments/6658-redhat_subscription-internal-rhsm-refactor.yml @@ -0,0 +1,6 @@ +minor_changes: + - | + redhat_subscription - the internal ``RegistrationBase`` class was folded + into the other internal ``Rhsm`` class, as the separation had no purpose + anymore + (https://github.com/ansible-collections/community.general/pull/6658). diff --git a/plugins/modules/redhat_subscription.py b/plugins/modules/redhat_subscription.py index 87c805fe92..685c07a968 100644 --- a/plugins/modules/redhat_subscription.py +++ b/plugins/modules/redhat_subscription.py @@ -334,32 +334,12 @@ from ansible.module_utils import distro SUBMAN_CMD = None -class RegistrationBase(object): +class Rhsm(object): REDHAT_REPO = "/etc/yum.repos.d/redhat.repo" - def __init__(self, module, username=None, password=None, token=None): + def __init__(self, module): self.module = module - self.username = username - self.password = password - self.token = token - - def configure(self): - raise NotImplementedError("Must be implemented by a sub-class") - - def enable(self): - # Remove any existing redhat.repo - if isfile(self.REDHAT_REPO): - unlink(self.REDHAT_REPO) - - def register(self): - raise NotImplementedError("Must be implemented by a sub-class") - - def unregister(self): - raise NotImplementedError("Must be implemented by a sub-class") - - def unsubscribe(self): - raise NotImplementedError("Must be implemented by a sub-class") def update_plugin_conf(self, plugin, enabled=True): plugin_conf = '/etc/yum/pluginconf.d/%s.conf' % plugin @@ -380,22 +360,15 @@ class RegistrationBase(object): fd.close() self.module.atomic_move(tmpfile, plugin_conf) - def subscribe(self, **kwargs): - raise NotImplementedError("Must be implemented by a sub-class") - - -class Rhsm(RegistrationBase): - def __init__(self, module, username=None, password=None, token=None): - RegistrationBase.__init__(self, module, username, password, token) - self.module = module - def enable(self): ''' Enable the system to receive updates from subscription-manager. This involves updating affected yum plugins and removing any conflicting yum repositories. ''' - RegistrationBase.enable(self) + # Remove any existing redhat.repo + if isfile(self.REDHAT_REPO): + unlink(self.REDHAT_REPO) self.update_plugin_conf('rhnplugin', False) self.update_plugin_conf('subscription-manager', True) @@ -1067,9 +1040,6 @@ class SysPurpose(object): def main(): - # Load RHSM configuration from file - rhsm = Rhsm(None) - # Note: the default values for parameters are: # 'type': 'str', 'default': None, 'required': False # So there is no need to repeat these values for each parameter. @@ -1144,7 +1114,9 @@ def main(): msg="Interacting with subscription-manager requires root permissions ('become: true')" ) - rhsm.module = module + # Load RHSM configuration from file + rhsm = Rhsm(module) + state = module.params['state'] username = module.params['username'] password = module.params['password'] diff --git a/tests/unit/plugins/modules/test_redhat_subscription.py b/tests/unit/plugins/modules/test_redhat_subscription.py index 4bf2729163..e80b04f734 100644 --- a/tests/unit/plugins/modules/test_redhat_subscription.py +++ b/tests/unit/plugins/modules/test_redhat_subscription.py @@ -22,7 +22,7 @@ def patch_redhat_subscription(mocker): """ Function used for mocking some parts of redhat_subscription module """ - mocker.patch('ansible_collections.community.general.plugins.modules.redhat_subscription.RegistrationBase.REDHAT_REPO') + mocker.patch('ansible_collections.community.general.plugins.modules.redhat_subscription.Rhsm.REDHAT_REPO') mocker.patch('ansible_collections.community.general.plugins.modules.redhat_subscription.isfile', return_value=False) mocker.patch('ansible_collections.community.general.plugins.modules.redhat_subscription.unlink', return_value=True) mocker.patch('ansible_collections.community.general.plugins.modules.redhat_subscription.AnsibleModule.get_bin_path', From 2bd8469a92cf01b37c07cf2202c5f8ac51b68d8e Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Sun, 11 Jun 2023 20:34:06 +1200 Subject: [PATCH 0047/1451] VarDict: convenience methods (#6647) * vardict module util: add methods as_dict and get_meta * add test for get_meta() * update reserved named in VarDict * add changelog frag * add breaking change to changelog frag --- changelogs/fragments/6647-vardict-methods.yml | 4 ++++ plugins/module_utils/vardict.py | 23 +++++++++++++++++-- .../unit/plugins/module_utils/test_vardict.py | 1 + 3 files changed, 26 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/6647-vardict-methods.yml diff --git a/changelogs/fragments/6647-vardict-methods.yml b/changelogs/fragments/6647-vardict-methods.yml new file mode 100644 index 0000000000..75c2c8ccf4 --- /dev/null +++ b/changelogs/fragments/6647-vardict-methods.yml @@ -0,0 +1,4 @@ +minor_changes: + - vardict module utils - added convenience methods to ``VarDict`` (https://github.com/ansible-collections/community.general/pull/6647). +breaking_changes: + - vardict module utils - ``VarDict`` will no longer accept variables named ``_var``, ``get_meta``, and ``as_dict`` (https://github.com/ansible-collections/community.general/pull/6647). diff --git a/plugins/module_utils/vardict.py b/plugins/module_utils/vardict.py index c94ef669af..517b112bb4 100644 --- a/plugins/module_utils/vardict.py +++ b/plugins/module_utils/vardict.py @@ -66,6 +66,19 @@ class _Variable(object): if verbosity is not None: self.verbosity = verbosity + def as_dict(self, meta_only=False): + d = { + "diff": self.diff, + "change": self.change, + "output": self.output, + "fact": self.fact, + "verbosity": self.verbosity, + } + if not meta_only: + d["initial_value"] = copy.deepcopy(self.initial_value) + d["value"] = self.value + return d + def set_value(self, value): if not self.init: self.initial_value = copy.deepcopy(value) @@ -93,7 +106,7 @@ class _Variable(object): class VarDict(object): - reserved_names = ('__vars__', 'var', 'set_meta', 'set', 'output', 'diff', 'facts', 'has_changed') + reserved_names = ('__vars__', '_var', 'var', 'set_meta', 'get_meta', 'set', 'output', 'diff', 'facts', 'has_changed', 'as_dict') def __init__(self): self.__vars__ = dict() @@ -119,6 +132,9 @@ class VarDict(object): def _var(self, name): return self.__vars__[name] + def var(self, name): + return self._var(name).as_dict() + def set_meta(self, name, **kwargs): """Set the metadata for the variable @@ -133,6 +149,9 @@ class VarDict(object): """ self._var(name).set_meta(**kwargs) + def get_meta(self, name): + return self._var(name).as_dict(meta_only=True) + def set(self, name, value, **kwargs): """Set the value and optionally metadata for a variable. The variable is not required to exist prior to calling `set`. @@ -172,7 +191,7 @@ class VarDict(object): @property def has_changed(self): - return any(True for var in self.__vars__.values() if var.has_changed) + return any(var.has_changed for var in self.__vars__.values()) def as_dict(self): return dict((name, var.value) for name, var in self.__vars__.items()) diff --git a/tests/unit/plugins/module_utils/test_vardict.py b/tests/unit/plugins/module_utils/test_vardict.py index 27a5be1a99..01d710b445 100644 --- a/tests/unit/plugins/module_utils/test_vardict.py +++ b/tests/unit/plugins/module_utils/test_vardict.py @@ -131,3 +131,4 @@ def test_vardict_dict(): vd.set("zz", 789) assert vd.as_dict() == {"xx": 123, "yy": 456, "zz": 789} + assert vd.get_meta("xx") == {"output": True, "change": False, "diff": False, "fact": False, "verbosity": 0} From 74ffb29573491798b889a53d6cc57444ad37f630 Mon Sep 17 00:00:00 2001 From: Pino Toscano Date: Sun, 11 Jun 2023 10:34:25 +0200 Subject: [PATCH 0048/1451] rhsm_release: improve the execution of subscription-manager (#6669) - pass the arguments to run_command() directly as list, rather than joining the arguments to string, which run_command() will need to split again - disable the expansions of variables, as there are none Adapt the unit test to the different way run_command() is called, factorizing the kwargs for run_command() so there is less repetition. There should be no behaviour changes. --- .../6669-rhsm_release-internal-sub-man-exec.yml | 5 +++++ plugins/modules/rhsm_release.py | 4 ++-- tests/unit/plugins/modules/test_rhsm_release.py | 14 ++++++++------ 3 files changed, 15 insertions(+), 8 deletions(-) create mode 100644 changelogs/fragments/6669-rhsm_release-internal-sub-man-exec.yml diff --git a/changelogs/fragments/6669-rhsm_release-internal-sub-man-exec.yml b/changelogs/fragments/6669-rhsm_release-internal-sub-man-exec.yml new file mode 100644 index 0000000000..a332a14151 --- /dev/null +++ b/changelogs/fragments/6669-rhsm_release-internal-sub-man-exec.yml @@ -0,0 +1,5 @@ +minor_changes: + - | + rhsm_release - improve/harden the way ``subscription-manager`` is run; + no behaviour change is expected + (https://github.com/ansible-collections/community.general/pull/6669). diff --git a/plugins/modules/rhsm_release.py b/plugins/modules/rhsm_release.py index 6ac4da6e4f..4e14dff39d 100644 --- a/plugins/modules/rhsm_release.py +++ b/plugins/modules/rhsm_release.py @@ -77,9 +77,9 @@ def _sm_release(module, *args): # pass args to s-m release, e.g. _sm_release(module, '--set', '0.1') becomes # "subscription-manager release --set 0.1" sm_bin = module.get_bin_path('subscription-manager', required=True) - cmd = '{0} release {1}'.format(sm_bin, " ".join(args)) + cmd = [sm_bin, 'release'] + list(args) # delegate nonzero rc handling to run_command - return module.run_command(cmd, check_rc=True) + return module.run_command(cmd, check_rc=True, expand_user_and_vars=False) def get_release(module): diff --git a/tests/unit/plugins/modules/test_rhsm_release.py b/tests/unit/plugins/modules/test_rhsm_release.py index c5696962b5..e8b2db6fdc 100644 --- a/tests/unit/plugins/modules/test_rhsm_release.py +++ b/tests/unit/plugins/modules/test_rhsm_release.py @@ -14,6 +14,8 @@ from ansible_collections.community.general.tests.unit.plugins.modules.utils impo class RhsmRepositoryReleaseModuleTestCase(ModuleTestCase): module = rhsm_release + SUBMAN_KWARGS = dict(check_rc=True, expand_user_and_vars=False) + def setUp(self): super(RhsmRepositoryReleaseModuleTestCase, self).setUp() @@ -63,8 +65,8 @@ class RhsmRepositoryReleaseModuleTestCase(ModuleTestCase): self.assertTrue(result['changed']) self.assertEqual('7.5', result['current_release']) self.module_main_command.assert_has_calls([ - call('/testbin/subscription-manager release --show', check_rc=True), - call('/testbin/subscription-manager release --set 7.5', check_rc=True), + call(['/testbin/subscription-manager', 'release', '--show'], **self.SUBMAN_KWARGS), + call(['/testbin/subscription-manager', 'release', '--set', '7.5'], **self.SUBMAN_KWARGS), ]) def test_release_set_idempotent(self): @@ -81,7 +83,7 @@ class RhsmRepositoryReleaseModuleTestCase(ModuleTestCase): self.assertFalse(result['changed']) self.assertEqual('7.5', result['current_release']) self.module_main_command.assert_has_calls([ - call('/testbin/subscription-manager release --show', check_rc=True), + call(['/testbin/subscription-manager', 'release', '--show'], **self.SUBMAN_KWARGS), ]) def test_release_unset(self): @@ -100,8 +102,8 @@ class RhsmRepositoryReleaseModuleTestCase(ModuleTestCase): self.assertTrue(result['changed']) self.assertIsNone(result['current_release']) self.module_main_command.assert_has_calls([ - call('/testbin/subscription-manager release --show', check_rc=True), - call('/testbin/subscription-manager release --unset', check_rc=True), + call(['/testbin/subscription-manager', 'release', '--show'], **self.SUBMAN_KWARGS), + call(['/testbin/subscription-manager', 'release', '--unset'], **self.SUBMAN_KWARGS), ]) def test_release_unset_idempotent(self): @@ -118,7 +120,7 @@ class RhsmRepositoryReleaseModuleTestCase(ModuleTestCase): self.assertFalse(result['changed']) self.assertIsNone(result['current_release']) self.module_main_command.assert_has_calls([ - call('/testbin/subscription-manager release --show', check_rc=True), + call(['/testbin/subscription-manager', 'release', '--show'], **self.SUBMAN_KWARGS), ]) def test_release_insane(self): From 2dbe529a90c605fa67167a6e96379f3f66b1c9aa Mon Sep 17 00:00:00 2001 From: Pino Toscano Date: Sun, 11 Jun 2023 10:38:09 +0200 Subject: [PATCH 0049/1451] rhsm_repository: deprecate "state=present" and "state=absent" (#6673) "state=present" is broken, and acts like "disabled"; also, the subscription repositories cannot be really "added" or "removed", which is what "present" and "absent" would imply, but only enabled or disabled. Hence, deprecate both these states, slating them for removal in community.general 10.0.0. --- ...6673-rhsm_repository-deprecate-present-absent.yml | 8 ++++++++ plugins/modules/rhsm_repository.py | 12 ++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 changelogs/fragments/6673-rhsm_repository-deprecate-present-absent.yml diff --git a/changelogs/fragments/6673-rhsm_repository-deprecate-present-absent.yml b/changelogs/fragments/6673-rhsm_repository-deprecate-present-absent.yml new file mode 100644 index 0000000000..77f0f18bbc --- /dev/null +++ b/changelogs/fragments/6673-rhsm_repository-deprecate-present-absent.yml @@ -0,0 +1,8 @@ +deprecated_features: +- | + rhsm_repository - ``state=present`` has not been working as expected for many years, + and it seems it was not noticed so far; also, "presence" is not really a valid concept + for subscription repositories, which can only be enabled or disabled. Hence, mark the + ``present`` and ``absent`` values of the ``state`` option as deprecated, slating them + for removal in community.general 10.0.0 + (https://github.com/ansible-collections/community.general/pull/6673). diff --git a/plugins/modules/rhsm_repository.py b/plugins/modules/rhsm_repository.py index eea6e38579..3225161e85 100644 --- a/plugins/modules/rhsm_repository.py +++ b/plugins/modules/rhsm_repository.py @@ -36,6 +36,10 @@ options: description: - If state is equal to present or disabled, indicates the desired repository state. + - | + Please note that V(present) and V(absent) are deprecated, and will be + removed in community.general 10.0.0; please use V(enabled) and + V(disabled) instead. choices: [present, enabled, absent, disabled] default: "enabled" type: str @@ -253,6 +257,14 @@ def main(): state = module.params['state'] purge = module.params['purge'] + if state in ['present', 'absent']: + replacement = 'enabled' if state == 'present' else 'disabled' + module.deprecate( + 'state=%s is deprecated; please use state=%s instead' % (state, replacement), + version='10.0.0', + collection_name='community.general', + ) + repository_modify(module, state, name, purge) From 1f6d404debe6896d64d629f03af9af81f370e05e Mon Sep 17 00:00:00 2001 From: Paul Levytskyi <25350788+levytskyip@users.noreply.github.com> Date: Mon, 12 Jun 2023 15:44:26 -0400 Subject: [PATCH 0050/1451] Proxmox inventory plugin: support composite variables (#6641) * Added composite var support for proxmox inventory plugin * Composite variables support for Proxmox nodes in dynamic inventory plugin Fixes #6640 * Composite variables support for Proxmox nodes in dynamic inventory plugin Fixes #6640 * Added composite var support for proxmox inventory plugin * Added composite var support for proxmox inventory plugin * Update changelogs/fragments/6640-proxmox-composite-variables-support.yml Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- .../fragments/6640-proxmox-composite-variables-support.yml | 3 +++ plugins/inventory/proxmox.py | 4 ++++ 2 files changed, 7 insertions(+) create mode 100644 changelogs/fragments/6640-proxmox-composite-variables-support.yml diff --git a/changelogs/fragments/6640-proxmox-composite-variables-support.yml b/changelogs/fragments/6640-proxmox-composite-variables-support.yml new file mode 100644 index 0000000000..bce33c01ba --- /dev/null +++ b/changelogs/fragments/6640-proxmox-composite-variables-support.yml @@ -0,0 +1,3 @@ +--- +minor_changes: + - proxmox inventory plugin - add composite variables support for Proxmox nodes (https://github.com/ansible-collections/community.general/issues/6640). diff --git a/plugins/inventory/proxmox.py b/plugins/inventory/proxmox.py index 1389f9ee26..d0053afbd7 100644 --- a/plugins/inventory/proxmox.py +++ b/plugins/inventory/proxmox.py @@ -590,6 +590,10 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable): ip = self._get_node_ip(node['node']) self.inventory.set_variable(node['node'], 'ansible_host', ip) + # Setting composite variables + variables = self.inventory.get_host(node['node']).get_vars() + self._set_composite_vars(self.get_option('compose'), variables, node['node'], strict=self.strict) + # add LXC/Qemu groups for the node for ittype in ('lxc', 'qemu'): node_type_group = self._group('%s_%s' % (node['node'], ittype)) From 032996e0052a514a17775c4492532c3505a7e142 Mon Sep 17 00:00:00 2001 From: Philippe Gauthier Date: Wed, 14 Jun 2023 16:34:45 -0400 Subject: [PATCH 0051/1451] =?UTF-8?q?Fix=20composites=20comparison=20for?= =?UTF-8?q?=20role=20in=20is=5Fstruct=5Fincluded=20keycloak.py=20=E2=80=A6?= =?UTF-8?q?=20(#6688)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix composites comparison for role in is_struct_included keycloak.py function * Add changelog fragment and unit tests * Update changelogs/fragments/6688-is-struct-included-bug-in-keycloak-py.yml Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- ...-is-struct-included-bug-in-keycloak-py.yml | 2 + .../identity/keycloak/keycloak.py | 12 +- .../keycloak/test_keycloak_module_utils.py | 103 ++++++++++++++++++ 3 files changed, 114 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/6688-is-struct-included-bug-in-keycloak-py.yml create mode 100644 tests/unit/plugins/module_utils/identity/keycloak/test_keycloak_module_utils.py diff --git a/changelogs/fragments/6688-is-struct-included-bug-in-keycloak-py.yml b/changelogs/fragments/6688-is-struct-included-bug-in-keycloak-py.yml new file mode 100644 index 0000000000..92546d8eca --- /dev/null +++ b/changelogs/fragments/6688-is-struct-included-bug-in-keycloak-py.yml @@ -0,0 +1,2 @@ +bugfixes: + - keycloak module utils - fix ``is_struct_included`` handling of lists of lists/dictionaries (https://github.com/ansible-collections/community.general/pull/6688). \ No newline at end of file diff --git a/plugins/module_utils/identity/keycloak/keycloak.py b/plugins/module_utils/identity/keycloak/keycloak.py index 20314ede36..a08e8613e4 100644 --- a/plugins/module_utils/identity/keycloak/keycloak.py +++ b/plugins/module_utils/identity/keycloak/keycloak.py @@ -216,24 +216,30 @@ def is_struct_included(struct1, struct2, exclude=None): Return True if all element of dict 1 are present in dict 2, return false otherwise. """ if isinstance(struct1, list) and isinstance(struct2, list): + if not struct1 and not struct2: + return True for item1 in struct1: if isinstance(item1, (list, dict)): for item2 in struct2: - if not is_struct_included(item1, item2, exclude): - return False + if is_struct_included(item1, item2, exclude): + break + else: + return False else: if item1 not in struct2: return False return True elif isinstance(struct1, dict) and isinstance(struct2, dict): + if not struct1 and not struct2: + return True try: for key in struct1: if not (exclude and key in exclude): if not is_struct_included(struct1[key], struct2[key], exclude): return False - return True except KeyError: return False + return True elif isinstance(struct1, bool) and isinstance(struct2, bool): return struct1 == struct2 else: diff --git a/tests/unit/plugins/module_utils/identity/keycloak/test_keycloak_module_utils.py b/tests/unit/plugins/module_utils/identity/keycloak/test_keycloak_module_utils.py new file mode 100644 index 0000000000..dc0f8d3f9a --- /dev/null +++ b/tests/unit/plugins/module_utils/identity/keycloak/test_keycloak_module_utils.py @@ -0,0 +1,103 @@ +# 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 + +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +import unittest + +from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import is_struct_included + + +class KeycloakIsStructIncludedTestCase(unittest.TestCase): + dict1 = dict( + test1='test1', + test2=dict( + test1='test1', + test2='test2' + ), + test3=['test1', dict(test='test1', test2='test2')] + ) + dict2 = dict( + test1='test1', + test2=dict( + test1='test1', + test2='test2', + test3='test3' + ), + test3=['test1', dict(test='test1', test2='test2'), 'test3'], + test4='test4' + ) + dict3 = dict( + test1='test1', + test2=dict( + test1='test1', + test2='test23', + test3='test3' + ), + test3=['test1', dict(test='test1', test2='test23'), 'test3'], + test4='test4' + ) + + dict5 = dict( + test1='test1', + test2=dict( + test1=True, + test2='test23', + test3='test3' + ), + test3=['test1', dict(test='test1', test2='test23'), 'test3'], + test4='test4' + ) + + dict6 = dict( + test1='test1', + test2=dict( + test1='true', + test2='test23', + test3='test3' + ), + test3=['test1', dict(test='test1', test2='test23'), 'test3'], + test4='test4' + ) + dict7 = [ + { + 'roles': ['view-clients', 'view-identity-providers', 'view-users', 'query-realms', 'manage-users'], + 'clientid': 'master-realm' + }, + { + 'roles': ['manage-account', 'view-profile', 'manage-account-links'], + 'clientid': 'account' + } + ] + dict8 = [ + { + 'roles': ['view-clients', 'query-realms', 'view-users'], + 'clientid': 'master-realm' + }, + { + 'roles': ['manage-account-links', 'view-profile', 'manage-account'], + 'clientid': 'account' + } + ] + + def test_trivial(self): + self.assertTrue(is_struct_included(self.dict1, self.dict1)) + + def test_equals_with_dict2_bigger_than_dict1(self): + self.assertTrue(is_struct_included(self.dict1, self.dict2)) + + def test_not_equals_with_dict2_bigger_than_dict1(self): + self.assertFalse(is_struct_included(self.dict2, self.dict1)) + + def test_not_equals_with_dict1_different_than_dict3(self): + self.assertFalse(is_struct_included(self.dict1, self.dict3)) + + def test_equals_with_dict5_contain_bool_and_dict6_contain_true_string(self): + self.assertFalse(is_struct_included(self.dict5, self.dict6)) + self.assertFalse(is_struct_included(self.dict6, self.dict5)) + + def test_not_equals_dict7_dict8_compare_dict7_with_list_bigger_than_dict8_but_reverse_equals(self): + self.assertFalse(is_struct_included(self.dict7, self.dict8)) + self.assertTrue(is_struct_included(self.dict8, self.dict7)) From 9f47cdde32fe75830bc18d8f968cdb11a97a33ea Mon Sep 17 00:00:00 2001 From: Ondrej Zvara Date: Thu, 15 Jun 2023 06:55:49 +0200 Subject: [PATCH 0052/1451] New module: gitlab_merge_request.py (#6605) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(gitlab_merge_request): initial module version * feat(gitlab_merge_request): adding assignees & reviewers * fix(gitlab_merge_request): sanity fixes * chore(gitlab_merge_request): adding BOTMETA record * chore(gitlab_merge_request): integration tests * docs(gitlab_merge_request): updating modules documentation * fix(gitlab_merge_request): proper module return values * fix(gitlab_merge_request): remove duplicate target_branch query * docs(gitlab_merge_request): apply improvements suggested from code review Co-authored-by: Felix Fontein * docs(gitlab_merge_request): updates to description and minor fixes based on code review Co-authored-by: Felix Fontein * chore(gitlab_merge_request): add aliases file for integration tests * fix(gitlab_merge_request): use with syntax for IOErrors handling Co-authored-by: Léo GATELLIER <26511053+lgatellier@users.noreply.github.com> * fix(gitlab_merge_request): inverted message parameters * refactor(gitlab_merge_request): use shared find_project method * refactor(gitlab_merge_request): use username filter for user retrieval * fix(gitlab_merge_request): handling of empty user search result * test(gitlab_merge_request): extends integration tests suite for merge request changes * chore(gitlab_merge_request): sanity validation & licensing fixes * docs(gitlab_merge_request): formatting changes to documentation Co-authored-by: Felix Fontein * chore(gitlab_merge_request): licensing of test files fixed Co-authored-by: Felix Fontein * docs(gitlab_merge_request): extends description & adds code comments --------- Co-authored-by: Felix Fontein Co-authored-by: Léo GATELLIER <26511053+lgatellier@users.noreply.github.com> --- .github/BOTMETA.yml | 2 + plugins/modules/gitlab_merge_request.py | 417 ++++++++++++++++++ .../targets/gitlab_merge_request/aliases | 6 + .../gitlab_merge_request/defaults/main.yml | 14 + .../gitlab_merge_request/files/description.md | 9 + .../gitlab_merge_request/tasks/main.yml | 129 ++++++ 6 files changed, 577 insertions(+) create mode 100644 plugins/modules/gitlab_merge_request.py create mode 100644 tests/integration/targets/gitlab_merge_request/aliases create mode 100644 tests/integration/targets/gitlab_merge_request/defaults/main.yml create mode 100644 tests/integration/targets/gitlab_merge_request/files/description.md create mode 100644 tests/integration/targets/gitlab_merge_request/tasks/main.yml diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 4a0ddf7ab3..ffe0985039 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -532,6 +532,8 @@ files: notify: jlozadad $modules/gitlab_branch.py: maintainers: paytroff + $modules/gitlab_merge_request.py: + maintainers: zvaraondrej $modules/gitlab_project_variable.py: maintainers: markuman $modules/gitlab_instance_variable.py: diff --git a/plugins/modules/gitlab_merge_request.py b/plugins/modules/gitlab_merge_request.py new file mode 100644 index 0000000000..6cdeca6466 --- /dev/null +++ b/plugins/modules/gitlab_merge_request.py @@ -0,0 +1,417 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright (c) 2023, Ondrej Zvara (ozvara1@gmail.com) +# Based on code: +# Copyright (c) 2021, Lennert Mertens (lennert@nubera.be) +# Copyright (c) 2021, Werner Dijkerman (ikben@werner-dijkerman.nl) +# Copyright (c) 2015, Werner Dijkerman (ikben@werner-dijkerman.nl) +# Copyright (c) 2019, Guillaume Martinez (lunik@tiwabbit.fr) +# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later +from __future__ import absolute_import, division, print_function +__metaclass__ = type + +DOCUMENTATION = ''' +module: gitlab_merge_request +short_description: Create, update, or delete GitLab merge requests +version_added: 7.1.0 +description: + - Creates a merge request if it does not exist. + - When a single merge request does exist, it will be updated if the provided parameters are different. + - When a single merge request does exist and O(state=absent), the merge request will be deleted. + - When multiple merge requests are detected, the task fails. + - Existing merge requests are matched based on O(title), O(source_branch), O(target_branch), + and O(state_filter) filters. +author: + - zvaraondrej (@zvaraondrej) +requirements: + - Python >= 2.7 + - python-gitlab >= 2.3.0 +extends_documentation_fragment: + - community.general.auth_basic + - community.general.gitlab + - community.general.attributes + +attributes: + check_mode: + support: full + diff_mode: + support: none + +options: + state: + description: + - Create or delete merge request. + default: present + type: str + choices: ["present", "absent"] + project: + description: + - The path or name of the project. + required: true + type: str + source_branch: + description: + - Merge request's source branch. + - Ignored while updating existing merge request. + required: true + type: str + target_branch: + description: + - Merge request's target branch. + required: true + type: str + title: + description: + - A title for the merge request. + type: str + required: true + description: + description: + - A description for the merge request. + - Gets overriden by a content of file specified at O(description_path), if found. + type: str + description_path: + description: + - A path of file containing merge request's description. + - Accepts MarkDown formatted files. + type: path + labels: + description: + - Comma separated list of label names. + type: str + default: "" + remove_source_branch: + description: + - Flag indicating if a merge request should remove the source branch when merging. + type: bool + default: false + state_filter: + description: + - Filter specifying state of merge requests while searching. + type: str + choices: ["opened", "closed", "locked", "merged"] + default: opened + assignee_ids: + description: + - Comma separated list of assignees usernames omitting C(@) character. + - Set to empty string to unassign all assignees. + type: str + reviewer_ids: + description: + - Comma separated list of reviewers usernames omitting C(@) character. + - Set to empty string to unassign all reviewers. + type: str +''' + + +EXAMPLES = ''' +- name: Create Merge Request from branch1 to branch2 + community.general.gitlab_merge_request: + api_url: https://gitlab.com + api_token: secret_access_token + project: "group1/project1" + source_branch: branch1 + target_branch: branch2 + title: "Ansible demo MR" + description: "Demo MR description" + labels: "Ansible,Demo" + state_filter: "opened" + remove_source_branch: True + state: present + +- name: Delete Merge Request from branch1 to branch2 + community.general.gitlab_merge_request: + api_url: https://gitlab.com + api_token: secret_access_token + project: "group1/project1" + source_branch: branch1 + target_branch: branch2 + title: "Ansible demo MR" + state_filter: "opened" + state: absent +''' + +RETURN = r''' +msg: + description: Success or failure message. + returned: always + type: str + sample: "Success" + +mr: + description: API object. + returned: success + type: dict +''' + +from ansible.module_utils.basic import AnsibleModule +from ansible.module_utils.api import basic_auth_argument_spec +from ansible.module_utils.common.text.converters import to_native, to_text + +from ansible_collections.community.general.plugins.module_utils.version import LooseVersion +from ansible_collections.community.general.plugins.module_utils.gitlab import ( + auth_argument_spec, gitlab_authentication, gitlab, ensure_gitlab_package, find_project +) + + +class GitlabMergeRequest(object): + + def __init__(self, module, project, gitlab_instance): + self._gitlab = gitlab_instance + self._module = module + self.project = project + + ''' + @param branch Name of the branch + ''' + def get_branch(self, branch): + try: + return self.project.branches.get(branch) + except gitlab.exceptions.GitlabGetError as e: + self._module.fail_json(msg="Failed to get the branch: %s" % to_native(e)) + + ''' + @param title Title of the Merge Request + @param source_branch Merge Request's source branch + @param target_branch Merge Request's target branch + @param state_filter Merge Request's state to filter on + ''' + def get_mr(self, title, source_branch, target_branch, state_filter): + mrs = [] + try: + mrs = self.project.mergerequests.list(search=title, source_branch=source_branch, target_branch=target_branch, state=state_filter) + except gitlab.exceptions.GitlabGetError as e: + self._module.fail_json(msg="Failed to list the Merge Request: %s" % to_native(e)) + + if len(mrs) > 1: + self._module.fail_json(msg="Multiple Merge Requests matched search criteria.") + if len(mrs) == 1: + try: + return self.project.mergerequests.get(id=mrs[0].iid) + except gitlab.exceptions.GitlabGetError as e: + self._module.fail_json(msg="Failed to get the Merge Request: %s" % to_native(e)) + + ''' + @param username Name of the user + ''' + def get_user(self, username): + users = [] + try: + users = [user for user in self.project.users.list(username=username, all=True) if user.username == username] + except gitlab.exceptions.GitlabGetError as e: + self._module.fail_json(msg="Failed to list the users: %s" % to_native(e)) + + if len(users) > 1: + self._module.fail_json(msg="Multiple Users matched search criteria.") + elif len(users) < 1: + self._module.fail_json(msg="No User matched search criteria.") + else: + return users[0] + + ''' + @param users List of usernames + ''' + def get_user_ids(self, users): + return [self.get_user(user).id for user in users] + + ''' + @param options Options of the Merge Request + ''' + def create_mr(self, options): + if self._module.check_mode: + self._module.exit_json(changed=True, msg="Successfully created the Merge Request %s" % options["title"]) + + try: + return self.project.mergerequests.create(options) + except gitlab.exceptions.GitlabCreateError as e: + self._module.fail_json(msg="Failed to create Merge Request: %s " % to_native(e)) + + ''' + @param mr Merge Request object to delete + ''' + def delete_mr(self, mr): + if self._module.check_mode: + self._module.exit_json(changed=True, msg="Successfully deleted the Merge Request %s" % mr["title"]) + + try: + return mr.delete() + except gitlab.exceptions.GitlabDeleteError as e: + self._module.fail_json(msg="Failed to delete Merge Request: %s " % to_native(e)) + + ''' + @param mr Merge Request object to update + ''' + def update_mr(self, mr, options): + if self._module.check_mode: + self._module.exit_json(changed=True, msg="Successfully updated the Merge Request %s" % mr["title"]) + + try: + return self.project.mergerequests.update(mr.iid, options) + except gitlab.exceptions.GitlabUpdateError as e: + self._module.fail_json(msg="Failed to update Merge Request: %s " % to_native(e)) + + ''' + @param mr Merge Request object to evaluate + @param options New options to update MR with + ''' + def mr_has_changed(self, mr, options): + for key, value in options.items(): + if value is not None: + # see https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27355 + if key == 'remove_source_branch': + key = 'force_remove_source_branch' + + if key == 'assignee_ids': + if options[key] != sorted([user["id"] for user in getattr(mr, 'assignees')]): + return True + + elif key == 'reviewer_ids': + if options[key] != sorted([user["id"] for user in getattr(mr, 'reviewers')]): + return True + + elif key == 'labels': + if options[key] != sorted(getattr(mr, key)): + return True + + elif getattr(mr, key) != value: + return True + + return False + + +def main(): + argument_spec = basic_auth_argument_spec() + argument_spec.update(auth_argument_spec()) + argument_spec.update( + project=dict(type='str', required=True), + source_branch=dict(type='str', required=True), + target_branch=dict(type='str', required=True), + title=dict(type='str', required=True), + description=dict(type='str', required=False), + labels=dict(type='str', default="", required=False), + description_path=dict(type='path', required=False), + remove_source_branch=dict(type='bool', default=False, required=False), + state_filter=dict(type='str', default="opened", choices=["opened", "closed", "locked", "merged"]), + assignee_ids=dict(type='str', required=False), + reviewer_ids=dict(type='str', required=False), + state=dict(type='str', default="present", choices=["absent", "present"]), + ) + + module = AnsibleModule( + argument_spec=argument_spec, + mutually_exclusive=[ + ['api_username', 'api_token'], + ['api_username', 'api_oauth_token'], + ['api_username', 'api_job_token'], + ['api_token', 'api_oauth_token'], + ['api_token', 'api_job_token'], + ['description', 'description_path'], + ], + required_together=[ + ['api_username', 'api_password'], + ], + required_one_of=[ + ['api_username', 'api_token', 'api_oauth_token', 'api_job_token'] + ], + required_if=[ + ['state', 'present', ['source_branch', 'target_branch', 'title'], True], + ['state', 'absent', ['source_branch', 'target_branch', 'title'], True], + ], + supports_check_mode=True + ) + ensure_gitlab_package(module) + + project = module.params['project'] + source_branch = module.params['source_branch'] + target_branch = module.params['target_branch'] + title = module.params['title'] + description = module.params['description'] + labels = module.params['labels'] + description_path = module.params['description_path'] + remove_source_branch = module.params['remove_source_branch'] + state_filter = module.params['state_filter'] + assignee_ids = module.params['assignee_ids'] + reviewer_ids = module.params['reviewer_ids'] + state = module.params['state'] + + gitlab_version = gitlab.__version__ + if LooseVersion(gitlab_version) < LooseVersion('2.3.0'): + module.fail_json(msg="community.general.gitlab_merge_request requires python-gitlab Python module >= 2.3.0 (installed version: [%s])." + " Please upgrade python-gitlab to version 2.3.0 or above." % gitlab_version) + + gitlab_instance = gitlab_authentication(module) + + this_project = find_project(gitlab_instance, project) + if this_project is None: + module.fail_json(msg="Failed to get the project: %s" % project) + + this_gitlab = GitlabMergeRequest(module=module, project=this_project, gitlab_instance=gitlab_instance) + + r_source_branch = this_gitlab.get_branch(source_branch) + if not r_source_branch: + module.fail_json(msg="Source branch {b} not exist.".format(b=r_source_branch)) + + r_target_branch = this_gitlab.get_branch(target_branch) + if not r_target_branch: + module.fail_json(msg="Destination branch {b} not exist.".format(b=r_target_branch)) + + this_mr = this_gitlab.get_mr(title, source_branch, target_branch, state_filter) + + if state == "present": + if description_path: + try: + with open(description_path, 'rb') as f: + description = to_text(f.read(), errors='surrogate_or_strict') + except IOError as e: + module.fail_json(msg='Cannot open {0}: {1}'.format(description_path, e)) + + # sorting necessary in order to properly detect changes, as we don't want to get false positive + # results due to differences in ids ordering; see `mr_has_changed()` + assignee_ids = sorted(this_gitlab.get_user_ids(assignee_ids.split(","))) if assignee_ids else [] + reviewer_ids = sorted(this_gitlab.get_user_ids(reviewer_ids.split(","))) if reviewer_ids else [] + labels = sorted(labels.split(",")) if labels else [] + + options = { + "target_branch": target_branch, + "title": title, + "description": description, + "labels": labels, + "remove_source_branch": remove_source_branch, + "reviewer_ids": reviewer_ids, + "assignee_ids": assignee_ids, + } + + if not this_mr: + options["source_branch"] = source_branch + + mr = this_gitlab.create_mr(options) + module.exit_json( + changed=True, msg="Created the Merge Request {t} from branch {s} to branch {d}.".format(t=title, d=target_branch, s=source_branch), + mr=mr.asdict() + ) + else: + if this_gitlab.mr_has_changed(this_mr, options): + mr = this_gitlab.update_mr(this_mr, options) + module.exit_json( + changed=True, msg="Merge Request {t} from branch {s} to branch {d} updated.".format(t=title, d=target_branch, s=source_branch), + mr=mr + ) + else: + module.exit_json( + changed=False, msg="Merge Request {t} from branch {s} to branch {d} already exist".format(t=title, d=target_branch, s=source_branch), + mr=this_mr.asdict() + ) + elif this_mr and state == "absent": + mr = this_gitlab.delete_mr(this_mr) + module.exit_json( + changed=True, msg="Merge Request {t} from branch {s} to branch {d} deleted.".format(t=title, d=target_branch, s=source_branch), + mr=mr + ) + else: + module.exit_json(changed=False, msg="No changes are needed.", mr=this_mr.asdict()) + + +if __name__ == '__main__': + main() diff --git a/tests/integration/targets/gitlab_merge_request/aliases b/tests/integration/targets/gitlab_merge_request/aliases new file mode 100644 index 0000000000..4f4e3dcc93 --- /dev/null +++ b/tests/integration/targets/gitlab_merge_request/aliases @@ -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 + +gitlab/ci +disabled diff --git a/tests/integration/targets/gitlab_merge_request/defaults/main.yml b/tests/integration/targets/gitlab_merge_request/defaults/main.yml new file mode 100644 index 0000000000..eb27b0b686 --- /dev/null +++ b/tests/integration/targets/gitlab_merge_request/defaults/main.yml @@ -0,0 +1,14 @@ +--- +# 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 + +gitlab_source_branch: ansible_test_source_branch +gitlab_target_branch: ansible_test_target_project +gitlab_project_name: ansible_test_project +gitlab_project_group: ansible_test_group +gitlab_host: ansible_test_host +gitlab_api_token: ansible_test_api_token +gitlab_labels: ansible_test_label +gitlab_assignee_ids: ansible_test_assignee_ids +gitlab_description_path: ansible_test_description_path \ No newline at end of file diff --git a/tests/integration/targets/gitlab_merge_request/files/description.md b/tests/integration/targets/gitlab_merge_request/files/description.md new file mode 100644 index 0000000000..3f662eff8c --- /dev/null +++ b/tests/integration/targets/gitlab_merge_request/files/description.md @@ -0,0 +1,9 @@ + + +### Description + +Merge Request test description \ No newline at end of file diff --git a/tests/integration/targets/gitlab_merge_request/tasks/main.yml b/tests/integration/targets/gitlab_merge_request/tasks/main.yml new file mode 100644 index 0000000000..18da900a2d --- /dev/null +++ b/tests/integration/targets/gitlab_merge_request/tasks/main.yml @@ -0,0 +1,129 @@ +--- +#################################################################### +# 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 required libs + pip: + name: python-gitlab + state: present + +- block: + - name: Create {{ gitlab_project_name }} + gitlab_project: + api_url: "{{ gitlab_host }}" + validate_certs: true + api_token: "{{ gitlab_api_token }}" + name: "{{ gitlab_project_name }}" + group: "{{ gitlab_project_group }}" + default_branch: "{{ gitlab_target_branch }}" + initialize_with_readme: true + state: present + + - name: Create branch {{ gitlab_source_branch }} + gitlab_branch: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_api_token }}" + project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}" + branch: "{{ gitlab_source_branch }}" + ref_branch: "{{ gitlab_target_branch }}" + state: present + + - name: Create Merge Request + gitlab_merge_request: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_api_token }}" + project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}" + source_branch: "{{gitlab_source_branch}}" + target_branch: "{{gitlab_target_branch}}" + title: "Ansible test merge request" + description: "Test description" + labels: "" + state_filter: "opened" + assignee_ids: "" + reviewer_ids: "" + remove_source_branch: True + state: present + register: gitlab_merge_request_create + + - name: Test Merge Request Created + assert: + that: + - gitlab_merge_request_create is changed + + - name: Create Merge Request ( Idempotency test ) + gitlab_merge_request: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_api_token }}" + project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}" + source_branch: "{{gitlab_source_branch}}" + target_branch: "{{gitlab_target_branch}}" + title: "Ansible test merge request" + description: "Test description" + labels: "" + state_filter: "opened" + assignee_ids: "" + reviewer_ids: "" + remove_source_branch: True + state: present + register: gitlab_merge_request_create_idempotence + + - name: Test module is idempotent + assert: + that: + - gitlab_merge_request_create_idempotence is not changed + + - name: Update Merge Request Test + gitlab_merge_request: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_api_token }}" + project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}" + source_branch: "{{gitlab_source_branch}}" + target_branch: "{{gitlab_target_branch}}" + title: "Ansible test merge request" + description_path: "{{gitlab_description_path}}" + labels: "{{ gitlab_labels }}" + state_filter: "opened" + assignee_ids: "{{ gitlab_assignee_ids }}" + reviewer_ids: "" + remove_source_branch: True + state: present + register: gitlab_merge_request_udpate + + - name: Test merge request updated + assert: + that: + - gitlab_merge_request_udpate.mr.labels[0] == "{{ gitlab_labels }}" + - gitlab_merge_request_udpate.mr.assignees[0].username == "{{ gitlab_assignee_ids }}" + - "'### Description\n\nMerge Request test description' in gitlab_merge_request_udpate.mr.description" + + - name: Delete Merge Request + gitlab_merge_request: + api_url: "{{ gitlab_host }}" + api_token: "{{ gitlab_api_token }}" + project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}" + source_branch: "{{gitlab_source_branch}}" + target_branch: "{{gitlab_target_branch}}" + title: "Ansible test merge request" + state: absent + register: gitlab_merge_request_delete + + - name: Test merge request is deleted + assert: + that: + - gitlab_merge_request_delete is changed + + always: + - name: Clean up {{ gitlab_project_name }} + gitlab_project: + api_url: "{{ gitlab_host }}" + validate_certs: false + api_token: "{{ gitlab_api_token }}" + name: "{{ gitlab_project_name }}" + group: "{{ gitlab_project_group }}" + state: absent From 9395df1c6f95e2b7075f72f62ccf8410e4a2cf60 Mon Sep 17 00:00:00 2001 From: Philippe Gauthier Date: Thu, 15 Jun 2023 00:57:30 -0400 Subject: [PATCH 0053/1451] Inspq keycloak role composites (#6469) * Add composites to keycloak_role module * Add composites support for realm role in keycloak module_utils * Clean f.write from keycloak_role module * keycloak_role support state for realm role composites * Add support for composites in client role for keycloak_role module * Add changelog fragment for keycloak role composites PR * Fix pep8 and validate-modules tests errors * Update changelogs/fragments/6469-add-composites-support-for-keycloak-role.yml Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_role.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_role.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_role.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_role.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_role.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_role.py I will try it Co-authored-by: Felix Fontein * Fix test_keycloak_role assertion * Fix role composite compare before update in keycloak_role module * Fix realm problem with update_role_composites in keycloak.py module_utils * Add units tests for composites and client roles in keycloak_role module * Update plugins/module_utils/identity/keycloak/keycloak.py Co-authored-by: Felix Fontein * Update plugins/module_utils/identity/keycloak/keycloak.py Co-authored-by: Felix Fontein * Change try in is_struct_included and add unit tests for keycloak.py module_utils * Add integration tests for composites roles and fix bug with non master roles in keycloak_role module * Update plugins/modules/keycloak_role.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_role.py Co-authored-by: Felix Fontein * Update plugins/modules/keycloak_role.py Co-authored-by: Felix Fontein * Update plugins/module_utils/identity/keycloak/keycloak.py Co-authored-by: Felix Fontein * Update plugins/module_utils/identity/keycloak/keycloak.py Co-authored-by: Felix Fontein * is_struct_included refactor --------- Co-authored-by: Felix Fontein --- ...d-composites-support-for-keycloak-role.yml | 2 + .../identity/keycloak/keycloak.py | 148 ++++++- plugins/modules/keycloak_role.py | 77 +++- .../targets/keycloak_role/README.md | 20 + .../targets/keycloak_role/tasks/main.yml | 233 +++++++++++ .../targets/keycloak_role/vars/main.yml | 27 ++ .../plugins/modules/test_keycloak_role.py | 370 +++++++++++++++++- 7 files changed, 860 insertions(+), 17 deletions(-) create mode 100644 changelogs/fragments/6469-add-composites-support-for-keycloak-role.yml create mode 100644 tests/integration/targets/keycloak_role/README.md diff --git a/changelogs/fragments/6469-add-composites-support-for-keycloak-role.yml b/changelogs/fragments/6469-add-composites-support-for-keycloak-role.yml new file mode 100644 index 0000000000..ae883ec2b7 --- /dev/null +++ b/changelogs/fragments/6469-add-composites-support-for-keycloak-role.yml @@ -0,0 +1,2 @@ +minor_changes: + - keycloak_role - add composite roles support for realm and client roles (https://github.com/ansible-collections/community.general/pull/6469). \ No newline at end of file diff --git a/plugins/module_utils/identity/keycloak/keycloak.py b/plugins/module_utils/identity/keycloak/keycloak.py index a08e8613e4..b1b76845f5 100644 --- a/plugins/module_utils/identity/keycloak/keycloak.py +++ b/plugins/module_utils/identity/keycloak/keycloak.py @@ -1680,6 +1680,9 @@ class KeycloakAPI(object): """ roles_url = URL_REALM_ROLES.format(url=self.baseurl, realm=realm) try: + if "composites" in rolerep: + keycloak_compatible_composites = self.convert_role_composites(rolerep["composites"]) + rolerep["composites"] = keycloak_compatible_composites return open_url(roles_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout, data=json.dumps(rolerep), validate_certs=self.validate_certs) except Exception as e: @@ -1694,12 +1697,124 @@ class KeycloakAPI(object): """ role_url = URL_REALM_ROLE.format(url=self.baseurl, realm=realm, name=quote(rolerep['name'])) try: - return open_url(role_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout, - data=json.dumps(rolerep), validate_certs=self.validate_certs) + composites = None + if "composites" in rolerep: + composites = copy.deepcopy(rolerep["composites"]) + del rolerep["composites"] + role_response = open_url(role_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout, + data=json.dumps(rolerep), validate_certs=self.validate_certs) + if composites is not None: + self.update_role_composites(rolerep=rolerep, composites=composites, realm=realm) + return role_response except Exception as e: self.module.fail_json(msg='Could not update role %s in realm %s: %s' % (rolerep['name'], realm, str(e))) + def get_role_composites(self, rolerep, clientid=None, realm='master'): + composite_url = '' + try: + if clientid is not None: + client = self.get_client_by_clientid(client_id=clientid, realm=realm) + cid = client['id'] + composite_url = URL_CLIENT_ROLE_COMPOSITES.format(url=self.baseurl, realm=realm, id=cid, name=quote(rolerep["name"])) + else: + composite_url = URL_REALM_ROLE_COMPOSITES.format(url=self.baseurl, realm=realm, name=quote(rolerep["name"])) + # Get existing composites + return json.loads(to_native(open_url( + composite_url, + method='GET', + http_agent=self.http_agent, + headers=self.restheaders, + timeout=self.connection_timeout, + validate_certs=self.validate_certs).read())) + except Exception as e: + self.module.fail_json(msg='Could not get role %s composites in realm %s: %s' + % (rolerep['name'], realm, str(e))) + + def create_role_composites(self, rolerep, composites, clientid=None, realm='master'): + composite_url = '' + try: + if clientid is not None: + client = self.get_client_by_clientid(client_id=clientid, realm=realm) + cid = client['id'] + composite_url = URL_CLIENT_ROLE_COMPOSITES.format(url=self.baseurl, realm=realm, id=cid, name=quote(rolerep["name"])) + else: + composite_url = URL_REALM_ROLE_COMPOSITES.format(url=self.baseurl, realm=realm, name=quote(rolerep["name"])) + # Get existing composites + # create new composites + return open_url(composite_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout, + data=json.dumps(composites), validate_certs=self.validate_certs) + except Exception as e: + self.module.fail_json(msg='Could not create role %s composites in realm %s: %s' + % (rolerep['name'], realm, str(e))) + + def delete_role_composites(self, rolerep, composites, clientid=None, realm='master'): + composite_url = '' + try: + if clientid is not None: + client = self.get_client_by_clientid(client_id=clientid, realm=realm) + cid = client['id'] + composite_url = URL_CLIENT_ROLE_COMPOSITES.format(url=self.baseurl, realm=realm, id=cid, name=quote(rolerep["name"])) + else: + composite_url = URL_REALM_ROLE_COMPOSITES.format(url=self.baseurl, realm=realm, name=quote(rolerep["name"])) + # Get existing composites + # create new composites + return open_url(composite_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout, + data=json.dumps(composites), validate_certs=self.validate_certs) + except Exception as e: + self.module.fail_json(msg='Could not create role %s composites in realm %s: %s' + % (rolerep['name'], realm, str(e))) + + def update_role_composites(self, rolerep, composites, clientid=None, realm='master'): + # Get existing composites + existing_composites = self.get_role_composites(rolerep=rolerep, clientid=clientid, realm=realm) + composites_to_be_created = [] + composites_to_be_deleted = [] + for composite in composites: + composite_found = False + existing_composite_client = None + for existing_composite in existing_composites: + if existing_composite["clientRole"]: + existing_composite_client = self.get_client_by_id(existing_composite["containerId"], realm=realm) + if ("client_id" in composite + and composite['client_id'] is not None + and existing_composite_client["clientId"] == composite["client_id"] + and composite["name"] == existing_composite["name"]): + composite_found = True + break + else: + if (("client_id" not in composite or composite['client_id'] is None) + and composite["name"] == existing_composite["name"]): + composite_found = True + break + if (not composite_found and ('state' not in composite or composite['state'] == 'present')): + if "client_id" in composite and composite['client_id'] is not None: + client_roles = self.get_client_roles(clientid=composite['client_id'], realm=realm) + for client_role in client_roles: + if client_role['name'] == composite['name']: + composites_to_be_created.append(client_role) + break + else: + realm_role = self.get_realm_role(name=composite["name"], realm=realm) + composites_to_be_created.append(realm_role) + elif composite_found and 'state' in composite and composite['state'] == 'absent': + if "client_id" in composite and composite['client_id'] is not None: + client_roles = self.get_client_roles(clientid=composite['client_id'], realm=realm) + for client_role in client_roles: + if client_role['name'] == composite['name']: + composites_to_be_deleted.append(client_role) + break + else: + realm_role = self.get_realm_role(name=composite["name"], realm=realm) + composites_to_be_deleted.append(realm_role) + + if len(composites_to_be_created) > 0: + # create new composites + self.create_role_composites(rolerep=rolerep, composites=composites_to_be_created, clientid=clientid, realm=realm) + if len(composites_to_be_deleted) > 0: + # delete new composites + self.delete_role_composites(rolerep=rolerep, composites=composites_to_be_deleted, clientid=clientid, realm=realm) + def delete_realm_role(self, name, realm='master'): """ Delete a realm role. @@ -1778,12 +1893,30 @@ class KeycloakAPI(object): % (clientid, realm)) roles_url = URL_CLIENT_ROLES.format(url=self.baseurl, realm=realm, id=cid) try: + if "composites" in rolerep: + keycloak_compatible_composites = self.convert_role_composites(rolerep["composites"]) + rolerep["composites"] = keycloak_compatible_composites return open_url(roles_url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout, data=json.dumps(rolerep), validate_certs=self.validate_certs) except Exception as e: self.module.fail_json(msg='Could not create role %s for client %s in realm %s: %s' % (rolerep['name'], clientid, realm, str(e))) + def convert_role_composites(self, composites): + keycloak_compatible_composites = { + 'client': {}, + 'realm': [] + } + for composite in composites: + if 'state' not in composite or composite['state'] == 'present': + if "client_id" in composite and composite["client_id"] is not None: + if composite["client_id"] not in keycloak_compatible_composites["client"]: + keycloak_compatible_composites["client"][composite["client_id"]] = [] + keycloak_compatible_composites["client"][composite["client_id"]].append(composite["name"]) + else: + keycloak_compatible_composites["realm"].append(composite["name"]) + return keycloak_compatible_composites + def update_client_role(self, rolerep, clientid, realm="master"): """ Update an existing client role. @@ -1798,8 +1931,15 @@ class KeycloakAPI(object): % (clientid, realm)) role_url = URL_CLIENT_ROLE.format(url=self.baseurl, realm=realm, id=cid, name=quote(rolerep['name'])) try: - return open_url(role_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout, - data=json.dumps(rolerep), validate_certs=self.validate_certs) + composites = None + if "composites" in rolerep: + composites = copy.deepcopy(rolerep["composites"]) + del rolerep['composites'] + update_role_response = open_url(role_url, method='PUT', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout, + data=json.dumps(rolerep), validate_certs=self.validate_certs) + if composites is not None: + self.update_role_composites(rolerep=rolerep, clientid=clientid, composites=composites, realm=realm) + return update_role_response except Exception as e: self.module.fail_json(msg='Could not update role %s for client %s in realm %s: %s' % (rolerep['name'], clientid, realm, str(e))) diff --git a/plugins/modules/keycloak_role.py b/plugins/modules/keycloak_role.py index bbec5f5919..46758a7621 100644 --- a/plugins/modules/keycloak_role.py +++ b/plugins/modules/keycloak_role.py @@ -77,6 +77,42 @@ options: 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 extends_documentation_fragment: - community.general.keycloak @@ -198,8 +234,9 @@ end_state: ''' from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, camel, \ - keycloak_argument_spec, get_token, KeycloakError + keycloak_argument_spec, get_token, KeycloakError, is_struct_included from ansible.module_utils.basic import AnsibleModule +import copy def main(): @@ -210,6 +247,12 @@ def main(): """ argument_spec = keycloak_argument_spec() + composites_spec = dict( + name=dict(type='str', required=True), + client_id=dict(type='str', aliases=['clientId'], required=False), + state=dict(type='str', default='present', choices=['present', 'absent']) + ) + meta_args = dict( state=dict(type='str', default='present', choices=['present', 'absent']), name=dict(type='str', required=True), @@ -217,6 +260,8 @@ def main(): realm=dict(type='str', default='master'), client_id=dict(type='str'), attributes=dict(type='dict'), + composites=dict(type='list', default=[], options=composites_spec, elements='dict'), + composite=dict(type='bool', default=False), ) argument_spec.update(meta_args) @@ -250,7 +295,7 @@ def main(): # Filter and map the parameters names that apply to the role role_params = [x for x in module.params - if x not in list(keycloak_argument_spec().keys()) + ['state', 'realm', 'client_id', 'composites'] and + if x not in list(keycloak_argument_spec().keys()) + ['state', 'realm', 'client_id'] and module.params.get(x) is not None] # See if it already exists in Keycloak @@ -269,10 +314,10 @@ def main(): new_param_value = module.params.get(param) old_value = before_role[param] if param in before_role else None if new_param_value != old_value: - changeset[camel(param)] = new_param_value + changeset[camel(param)] = copy.deepcopy(new_param_value) # Prepare the desired values using the existing values (non-existence results in a dict that is save to use as a basis) - desired_role = before_role.copy() + desired_role = copy.deepcopy(before_role) desired_role.update(changeset) result['proposed'] = changeset @@ -309,6 +354,9 @@ def main(): kc.create_client_role(desired_role, clientid, realm) after_role = kc.get_client_role(name, clientid, realm) + if after_role['composite']: + after_role['composites'] = kc.get_role_composites(rolerep=after_role, clientid=clientid, realm=realm) + result['end_state'] = after_role result['msg'] = 'Role {name} has been created'.format(name=name) @@ -316,10 +364,25 @@ def main(): else: if state == 'present': + compare_exclude = [] + if 'composites' in desired_role and isinstance(desired_role['composites'], list) and len(desired_role['composites']) > 0: + composites = kc.get_role_composites(rolerep=before_role, clientid=clientid, realm=realm) + before_role['composites'] = [] + for composite in composites: + before_composite = {} + if composite['clientRole']: + composite_client = kc.get_client_by_id(id=composite['containerId'], realm=realm) + before_composite['client_id'] = composite_client['clientId'] + else: + before_composite['client_id'] = None + before_composite['name'] = composite['name'] + before_composite['state'] = 'present' + before_role['composites'].append(before_composite) + else: + compare_exclude.append('composites') # Process an update - # no changes - if desired_role == before_role: + if is_struct_included(desired_role, before_role, exclude=compare_exclude): result['changed'] = False result['end_state'] = desired_role result['msg'] = "No changes required to role {name}.".format(name=name) @@ -341,6 +404,8 @@ def main(): else: kc.update_client_role(desired_role, clientid, realm) after_role = kc.get_client_role(name, clientid, realm) + if after_role['composite']: + after_role['composites'] = kc.get_role_composites(rolerep=after_role, clientid=clientid, realm=realm) result['end_state'] = after_role diff --git a/tests/integration/targets/keycloak_role/README.md b/tests/integration/targets/keycloak_role/README.md new file mode 100644 index 0000000000..ccb4c8ffaa --- /dev/null +++ b/tests/integration/targets/keycloak_role/README.md @@ -0,0 +1,20 @@ + +# Running keycloak_user module integration test + +To run Keycloak user module's integration test, start a keycloak server using Docker or Podman: + + podman|docker run -d --rm --name mykeycloak -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=password quay.io/keycloak/keycloak:latest start-dev --http-relative-path /auth + +Source Ansible env-setup from ansible github repository + +Run integration tests: + + ansible-test integration keycloak_role --python 3.10 --allow-unsupported + +Cleanup: + + podman|docker stop mykeycloak diff --git a/tests/integration/targets/keycloak_role/tasks/main.yml b/tests/integration/targets/keycloak_role/tasks/main.yml index 61b62629a4..c649b86808 100644 --- a/tests/integration/targets/keycloak_role/tasks/main.yml +++ b/tests/integration/targets/keycloak_role/tasks/main.yml @@ -248,3 +248,236 @@ that: - result is not changed - result.end_state == {} + +- name: Create realm role with composites + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + name: "{{ keycloak_role_name }}" + realm: "{{ realm }}" + description: "{{ keycloak_role_description }}" + composite: "{{ keycloak_role_composite }}" + composites: "{{ keycloak_role_composites }}" + state: present + register: result + +- name: Debug + debug: + var: result + +- name: Assert realm role is created with composites + assert: + that: + - result is changed + - result.end_state.composites | length == 3 + +- name: Change realm role with composites no change + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + name: "{{ keycloak_role_name }}" + realm: "{{ realm }}" + description: "{{ keycloak_role_description }}" + composite: "{{ keycloak_role_composite }}" + composites: "{{ keycloak_role_composites }}" + state: present + register: result + +- name: Debug + debug: + var: result + +- name: Assert realm role with composites have not changed + assert: + that: + - result is not changed + - result.end_state.composites | length == 3 + +- name: Remove composite from realm role with composites + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + name: "{{ keycloak_role_name }}" + realm: "{{ realm }}" + description: "{{ keycloak_role_description }}" + composite: "{{ keycloak_role_composite }}" + composites: "{{ keycloak_role_composites_with_absent }}" + state: present + register: result + +- name: Debug + debug: + var: result + +- name: Assert composite was removed from realm role with composites + assert: + that: + - result is changed + - result.end_state.composites | length == 2 + +- name: Delete realm role with composites + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + realm: "{{ realm }}" + name: "{{ keycloak_role_name }}" + state: absent + register: result + +- name: Debug + debug: + var: result + +- name: Assert realm role deleted + assert: + that: + - result is changed + - result.end_state == {} + +- name: Delete absent realm role with composites + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + realm: "{{ realm }}" + name: "{{ keycloak_role_name }}" + state: absent + register: result + +- name: Debug + debug: + var: result + +- name: Assert not changed and realm role absent + assert: + that: + - result is not changed + - result.end_state == {} + +- name: Create client role with composites + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + name: "{{ keycloak_role_name }}" + client_id: "{{ client_id }}" + realm: "{{ realm }}" + description: "{{ keycloak_role_description }}" + composite: "{{ keycloak_role_composite }}" + composites: "{{ keycloak_role_composites }}" + state: present + register: result + +- name: Debug + debug: + var: result + +- name: Assert client role is created with composites + assert: + that: + - result is changed + - result.end_state.composites | length == 3 + +- name: Change client role with composites no change + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + name: "{{ keycloak_role_name }}" + client_id: "{{ client_id }}" + realm: "{{ realm }}" + description: "{{ keycloak_role_description }}" + composite: "{{ keycloak_role_composite }}" + composites: "{{ keycloak_role_composites }}" + state: present + register: result + +- name: Debug + debug: + var: result + +- name: Assert client role with composites have not changed + assert: + that: + - result is not changed + - result.end_state.composites | length == 3 + +- name: Remove composite from client role with composites + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + name: "{{ keycloak_role_name }}" + client_id: "{{ client_id }}" + realm: "{{ realm }}" + description: "{{ keycloak_role_description }}" + composite: "{{ keycloak_role_composite }}" + composites: "{{ keycloak_role_composites_with_absent }}" + state: present + register: result + +- name: Debug + debug: + var: result + +- name: Assert composite was removed from client role with composites + assert: + that: + - result is changed + - result.end_state.composites | length == 2 + +- name: Delete client role with composites + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + realm: "{{ realm }}" + name: "{{ keycloak_role_name }}" + client_id: "{{ client_id }}" + state: absent + register: result + +- name: Debug + debug: + var: result + +- name: Assert client role deleted + assert: + that: + - result is changed + - result.end_state == {} + +- name: Delete absent client role with composites + community.general.keycloak_role: + auth_keycloak_url: "{{ url }}" + auth_realm: "{{ admin_realm }}" + auth_username: "{{ admin_user }}" + auth_password: "{{ admin_password }}" + realm: "{{ realm }}" + name: "{{ keycloak_role_name }}" + client_id: "{{ client_id }}" + state: absent + register: result + +- name: Debug + debug: + var: result + +- name: Assert not changed and client role absent + assert: + that: + - result is not changed + - result.end_state == {} \ No newline at end of file diff --git a/tests/integration/targets/keycloak_role/vars/main.yml b/tests/integration/targets/keycloak_role/vars/main.yml index b003311e0f..0af55dfc5c 100644 --- a/tests/integration/targets/keycloak_role/vars/main.yml +++ b/tests/integration/targets/keycloak_role/vars/main.yml @@ -12,3 +12,30 @@ client_id: myclient role: myrole description_1: desc 1 description_2: desc 2 + +keycloak_role_name: test +keycloak_role_description: test +keycloak_role_composite: true +keycloak_role_composites: + - name: view-clients + client_id: "realm-management" + state: present + - name: query-clients + client_id: "realm-management" + state: present + - name: offline_access + state: present +keycloak_client_id: test-client +keycloak_client_name: test-client +keycloak_client_description: This is a client for testing purpose +role_state: present + +keycloak_role_composites_with_absent: + - name: view-clients + client_id: "realm-management" + state: present + - name: query-clients + client_id: "realm-management" + state: present + - name: offline_access + state: absent \ No newline at end of file diff --git a/tests/unit/plugins/modules/test_keycloak_role.py b/tests/unit/plugins/modules/test_keycloak_role.py index c48c9771a5..cc2f6e716b 100644 --- a/tests/unit/plugins/modules/test_keycloak_role.py +++ b/tests/unit/plugins/modules/test_keycloak_role.py @@ -21,7 +21,9 @@ from ansible.module_utils.six import StringIO @contextmanager -def patch_keycloak_api(get_realm_role, create_realm_role=None, update_realm_role=None, delete_realm_role=None): +def patch_keycloak_api(get_realm_role=None, create_realm_role=None, update_realm_role=None, delete_realm_role=None, + get_client_role=None, create_client_role=None, update_client_role=None, delete_client_role=None, + get_client_by_id=None, get_role_composites=None): """Mock context manager for patching the methods in PwPolicyIPAClient that contact the IPA server Patches the `login` and `_post_json` methods @@ -41,7 +43,15 @@ def patch_keycloak_api(get_realm_role, create_realm_role=None, update_realm_role with patch.object(obj, 'create_realm_role', side_effect=create_realm_role) as mock_create_realm_role: with patch.object(obj, 'update_realm_role', side_effect=update_realm_role) as mock_update_realm_role: with patch.object(obj, 'delete_realm_role', side_effect=delete_realm_role) as mock_delete_realm_role: - yield mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role + with patch.object(obj, 'get_client_role', side_effect=get_client_role) as mock_get_client_role: + with patch.object(obj, 'create_client_role', side_effect=create_client_role) as mock_create_client_role: + with patch.object(obj, 'update_client_role', side_effect=update_client_role) as mock_update_client_role: + with patch.object(obj, 'delete_client_role', side_effect=delete_client_role) as mock_delete_client_role: + with patch.object(obj, 'get_client_by_id', side_effect=get_client_by_id) as mock_get_client_by_id: + with patch.object(obj, 'get_role_composites', side_effect=get_role_composites) as mock_get_role_composites: + yield mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role, \ + mock_get_client_role, mock_create_client_role, mock_update_client_role, mock_delete_client_role, \ + mock_get_client_by_id, mock_get_role_composites def get_response(object_with_future_response, method, get_id_call_count): @@ -125,7 +135,9 @@ class TestKeycloakRealmRole(ModuleTestCase): with mock_good_connection(): with patch_keycloak_api(get_realm_role=return_value_absent, create_realm_role=return_value_created) \ - as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role): + as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role, + mock_get_client_role, mock_create_client_role, mock_update_client_role, mock_delete_client_role, + mock_get_client_by_client_id, mock_get_role_composites): with self.assertRaises(AnsibleExitJson) as exec_info: self.module.main() @@ -179,7 +191,9 @@ class TestKeycloakRealmRole(ModuleTestCase): with mock_good_connection(): with patch_keycloak_api(get_realm_role=return_value_present, update_realm_role=return_value_updated) \ - as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role): + as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role, + mock_get_client_role, mock_create_client_role, mock_update_client_role, mock_delete_client_role, + mock_get_client_by_client_id, mock_get_role_composites): with self.assertRaises(AnsibleExitJson) as exec_info: self.module.main() @@ -233,7 +247,9 @@ class TestKeycloakRealmRole(ModuleTestCase): with mock_good_connection(): with patch_keycloak_api(get_realm_role=return_value_present, update_realm_role=return_value_updated) \ - as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role): + as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role, + mock_get_client_role, mock_create_client_role, mock_update_client_role, mock_delete_client_role, + mock_get_client_by_client_id, mock_get_role_composites): with self.assertRaises(AnsibleExitJson) as exec_info: self.module.main() @@ -244,6 +260,140 @@ class TestKeycloakRealmRole(ModuleTestCase): # Verify that the module's changed status matches what is expected self.assertIs(exec_info.exception.args[0]['changed'], changed) + def test_create_with_composites_when_present_no_change(self): + """Update without change a realm role""" + + module_args = { + 'auth_keycloak_url': 'http://keycloak.url/auth', + 'auth_password': 'admin', + 'auth_realm': 'master', + 'auth_username': 'admin', + 'auth_client_id': 'admin-cli', + 'validate_certs': True, + 'realm': 'realm-name', + 'name': 'role-name', + 'description': 'role-description', + 'composite': True, + 'composites': [ + { + 'client_id': 'client_1', + 'name': 'client-role1' + }, + { + 'name': 'realm-role-1' + } + ] + + } + return_value_present = [ + { + "attributes": {}, + "clientRole": False, + "composite": True, + "containerId": "realm-name", + "description": "role-description", + "id": "90f1cdb6-be88-496e-89c6-da1fb6bc6966", + "name": "role-name", + }, + { + "attributes": {}, + "clientRole": False, + "composite": True, + "containerId": "realm-name", + "description": "role-description", + "id": "90f1cdb6-be88-496e-89c6-da1fb6bc6966", + "name": "role-name", + } + ] + return_value_updated = [None] + return_get_role_composites = [ + [ + { + 'clientRole': True, + 'containerId': 'c4367fac-f427-11ed-8e2f-aff070d20f0e', + 'name': 'client-role1' + }, + { + 'clientRole': False, + 'containerId': 'realm-name', + 'name': 'realm-role-1' + } + ] + ] + return_get_client_by_client_id = [ + { + "id": "de152444-f126-4a7a-8273-4ee1544133ad", + "clientId": "client_1", + "name": "client_1", + "description": "client_1", + "surrogateAuthRequired": False, + "enabled": True, + "alwaysDisplayInConsole": False, + "clientAuthenticatorType": "client-secret", + "redirectUris": [ + "http://localhost:8080/*", + ], + "webOrigins": [ + "*" + ], + "notBefore": 0, + "bearerOnly": False, + "consentRequired": False, + "standardFlowEnabled": True, + "implicitFlowEnabled": False, + "directAccessGrantsEnabled": False, + "serviceAccountsEnabled": False, + "publicClient": False, + "frontchannelLogout": False, + "protocol": "openid-connect", + "attributes": { + "backchannel.logout.session.required": "true", + "backchannel.logout.revoke.offline.tokens": "false" + }, + "authenticationFlowBindingOverrides": {}, + "fullScopeAllowed": True, + "nodeReRegistrationTimeout": -1, + "defaultClientScopes": [ + "web-origins", + "acr", + "profile", + "roles", + "email" + ], + "optionalClientScopes": [ + "address", + "phone", + "offline_access", + "microprofile-jwt" + ] + } + ] + + changed = False + + set_module_args(module_args) + + # Run the module + + with mock_good_connection(): + with patch_keycloak_api(get_realm_role=return_value_present, update_realm_role=return_value_updated, + get_client_by_id=return_get_client_by_client_id, + get_role_composites=return_get_role_composites) \ + as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role, + mock_get_client_role, mock_create_client_role, mock_update_client_role, mock_delete_client_role, + mock_get_client_by_client_id, mock_get_role_composites): + with self.assertRaises(AnsibleExitJson) as exec_info: + self.module.main() + + self.assertEqual(len(mock_get_realm_role.mock_calls), 1) + self.assertEqual(len(mock_create_realm_role.mock_calls), 0) + self.assertEqual(len(mock_update_realm_role.mock_calls), 0) + self.assertEqual(len(mock_get_client_by_client_id.mock_calls), 1) + self.assertEqual(len(mock_get_role_composites.mock_calls), 1) + + # Verify that the module's changed status matches what is expected + self.assertIs(exec_info.exception.args[0]['changed'], changed) + def test_delete_when_absent(self): """Remove an absent realm role""" @@ -268,7 +418,9 @@ class TestKeycloakRealmRole(ModuleTestCase): with mock_good_connection(): with patch_keycloak_api(get_realm_role=return_value_absent, delete_realm_role=return_value_deleted) \ - as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role): + as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role, + mock_get_client_role, mock_create_client_role, mock_update_client_role, mock_delete_client_role, + mock_get_client_by_client_id, mock_get_role_composites): with self.assertRaises(AnsibleExitJson) as exec_info: self.module.main() @@ -312,7 +464,9 @@ class TestKeycloakRealmRole(ModuleTestCase): with mock_good_connection(): with patch_keycloak_api(get_realm_role=return_value_absent, delete_realm_role=return_value_deleted) \ - as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role): + as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role, + mock_get_client_role, mock_create_client_role, mock_update_client_role, mock_delete_client_role, + mock_get_client_by_client_id, mock_get_role_composites): with self.assertRaises(AnsibleExitJson) as exec_info: self.module.main() @@ -323,5 +477,207 @@ class TestKeycloakRealmRole(ModuleTestCase): self.assertIs(exec_info.exception.args[0]['changed'], changed) +class TestKeycloakClientRole(ModuleTestCase): + def setUp(self): + super(TestKeycloakClientRole, self).setUp() + self.module = keycloak_role + + def test_create_client_role_with_composites_when_absent(self): + """Update with change a realm role""" + + module_args = { + 'auth_keycloak_url': 'http://keycloak.url/auth', + 'auth_password': 'admin', + 'auth_realm': 'master', + 'auth_username': 'admin', + 'auth_client_id': 'admin-cli', + 'validate_certs': True, + 'realm': 'realm-name', + 'client_id': 'client-name', + 'name': 'role-name', + 'description': 'role-description', + 'composite': True, + 'composites': [ + { + 'client_id': 'client_1', + 'name': 'client-role1' + }, + { + 'name': 'realm-role-1' + } + ] + } + return_get_client_role = [ + None, + { + "attributes": {}, + "clientRole": True, + "composite": True, + "composites": [ + { + 'client': { + 'client1': ['client-role1'] + } + }, + { + 'realm': ['realm-role-1'] + } + ], + "containerId": "9ae25ec2-f40a-11ed-9261-b3bacf720f69", + "description": "role-description", + "id": "90f1cdb6-be88-496e-89c6-da1fb6bc6966", + "name": "role-name", + } + ] + changed = True + + set_module_args(module_args) + + # Run the module + + with mock_good_connection(): + with patch_keycloak_api(get_client_role=return_get_client_role) \ + as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role, + mock_get_client_role, mock_create_client_role, mock_update_client_role, mock_delete_client_role, + mock_get_client_by_client_id, mock_get_role_composites): + with self.assertRaises(AnsibleExitJson) as exec_info: + self.module.main() + + self.assertEqual(len(mock_get_realm_role.mock_calls), 0) + self.assertEqual(len(mock_create_realm_role.mock_calls), 0) + self.assertEqual(len(mock_update_realm_role.mock_calls), 0) + self.assertEqual(len(mock_get_client_role.mock_calls), 2) + self.assertEqual(len(mock_create_client_role.mock_calls), 1) + self.assertEqual(len(mock_update_client_role.mock_calls), 0) + + # Verify that the module's changed status matches what is expected + self.assertIs(exec_info.exception.args[0]['changed'], changed) + + def test_create_client_role_with_composites_when_present_no_change(self): + """Update with change a realm role""" + + module_args = { + 'auth_keycloak_url': 'http://keycloak.url/auth', + 'auth_password': 'admin', + 'auth_realm': 'master', + 'auth_username': 'admin', + 'auth_client_id': 'admin-cli', + 'validate_certs': True, + 'realm': 'realm-name', + 'client_id': 'client-name', + 'name': 'role-name', + 'description': 'role-description', + 'composite': True, + 'composites': [ + { + 'client_id': 'client_1', + 'name': 'client-role1' + }, + { + 'name': 'realm-role-1' + } + ] + } + return_get_client_role = [ + { + "attributes": {}, + "clientRole": True, + "composite": True, + "containerId": "9ae25ec2-f40a-11ed-9261-b3bacf720f69", + "description": "role-description", + "id": "90f1cdb6-be88-496e-89c6-da1fb6bc6966", + "name": "role-name", + } + ] + return_get_role_composites = [ + [ + { + 'clientRole': True, + 'containerId': 'c4367fac-f427-11ed-8e2f-aff070d20f0e', + 'name': 'client-role1' + }, + { + 'clientRole': False, + 'containerId': 'realm-name', + 'name': 'realm-role-1' + } + ] + ] + return_get_client_by_client_id = [ + { + "id": "de152444-f126-4a7a-8273-4ee1544133ad", + "clientId": "client_1", + "name": "client_1", + "description": "client_1", + "surrogateAuthRequired": False, + "enabled": True, + "alwaysDisplayInConsole": False, + "clientAuthenticatorType": "client-secret", + "redirectUris": [ + "http://localhost:8080/*", + ], + "webOrigins": [ + "*" + ], + "notBefore": 0, + "bearerOnly": False, + "consentRequired": False, + "standardFlowEnabled": True, + "implicitFlowEnabled": False, + "directAccessGrantsEnabled": False, + "serviceAccountsEnabled": False, + "publicClient": False, + "frontchannelLogout": False, + "protocol": "openid-connect", + "attributes": { + "backchannel.logout.session.required": "true", + "backchannel.logout.revoke.offline.tokens": "false" + }, + "authenticationFlowBindingOverrides": {}, + "fullScopeAllowed": True, + "nodeReRegistrationTimeout": -1, + "defaultClientScopes": [ + "web-origins", + "acr", + "profile", + "roles", + "email" + ], + "optionalClientScopes": [ + "address", + "phone", + "offline_access", + "microprofile-jwt" + ] + } + ] + changed = False + + set_module_args(module_args) + + # Run the module + + with mock_good_connection(): + with patch_keycloak_api(get_client_role=return_get_client_role, get_client_by_id=return_get_client_by_client_id, + get_role_composites=return_get_role_composites) \ + as (mock_get_realm_role, mock_create_realm_role, mock_update_realm_role, mock_delete_realm_role, + mock_get_client_role, mock_create_client_role, mock_update_client_role, mock_delete_client_role, + mock_get_client_by_client_id, mock_get_role_composites): + with self.assertRaises(AnsibleExitJson) as exec_info: + self.module.main() + + self.assertEqual(len(mock_get_realm_role.mock_calls), 0) + self.assertEqual(len(mock_create_realm_role.mock_calls), 0) + self.assertEqual(len(mock_update_realm_role.mock_calls), 0) + self.assertEqual(len(mock_get_client_role.mock_calls), 1) + self.assertEqual(len(mock_create_client_role.mock_calls), 0) + self.assertEqual(len(mock_update_client_role.mock_calls), 0) + self.assertEqual(len(mock_get_client_by_client_id.mock_calls), 1) + self.assertEqual(len(mock_get_role_composites.mock_calls), 1) + + # Verify that the module's changed status matches what is expected + self.assertIs(exec_info.exception.args[0]['changed'], changed) + + if __name__ == '__main__': unittest.main() From bb2169340d04b70f3a35f6e321ca5dfe444fb3aa Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Thu, 15 Jun 2023 17:19:16 +1200 Subject: [PATCH 0054/1451] csv module utils: detect unicode BOM in content (#6662) * csv module utils: detect unicode BOM in content * fix handling of py2 * fix comment * add changelog frag * add missing link * simplification --- changelogs/fragments/6662-csv-bom.yml | 2 + plugins/module_utils/csv.py | 4 +- .../targets/read_csv/meta/main.yml | 7 +++ .../targets/read_csv/tasks/main.yml | 50 ++++++++++++++----- 4 files changed, 50 insertions(+), 13 deletions(-) create mode 100644 changelogs/fragments/6662-csv-bom.yml create mode 100644 tests/integration/targets/read_csv/meta/main.yml diff --git a/changelogs/fragments/6662-csv-bom.yml b/changelogs/fragments/6662-csv-bom.yml new file mode 100644 index 0000000000..e9c617219c --- /dev/null +++ b/changelogs/fragments/6662-csv-bom.yml @@ -0,0 +1,2 @@ +bugfixes: + - csv module utils - detects and remove unicode BOM markers from incoming CSV content (https://github.com/ansible-collections/community.general/pull/6662). diff --git a/plugins/module_utils/csv.py b/plugins/module_utils/csv.py index 50d2cb3868..200548a46d 100644 --- a/plugins/module_utils/csv.py +++ b/plugins/module_utils/csv.py @@ -55,8 +55,10 @@ def initialize_dialect(dialect, **kwargs): def read_csv(data, dialect, fieldnames=None): - + BOM = to_native(u'\ufeff') data = to_native(data, errors='surrogate_or_strict') + if data.startswith(BOM): + data = data[len(BOM):] if PY3: fake_fh = StringIO(data) diff --git a/tests/integration/targets/read_csv/meta/main.yml b/tests/integration/targets/read_csv/meta/main.yml new file mode 100644 index 0000000000..982de6eb03 --- /dev/null +++ b/tests/integration/targets/read_csv/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/read_csv/tasks/main.yml b/tests/integration/targets/read_csv/tasks/main.yml index a21af95182..c09349dd5b 100644 --- a/tests/integration/targets/read_csv/tasks/main.yml +++ b/tests/integration/targets/read_csv/tasks/main.yml @@ -11,16 +11,16 @@ # Create basic CSV file - name: Create unique CSV file copy: - content: | + content: &users_content | name,uid,gid,gecos dag,500,500,Dag Wieërs jeroen,501,500,Jeroen Hoekx - dest: users_unique.csv + dest: "{{ remote_tmp_dir }}/users_unique.csv" # Read a CSV file and access user 'dag' - name: Read users from CSV file and return a dictionary read_csv: - path: users_unique.csv + path: "{{ remote_tmp_dir }}/users_unique.csv" key: name register: users_unique @@ -35,10 +35,10 @@ - users_unique.dict.jeroen.uid == '501' - users_unique.dict.jeroen.gid == '500' - # Read a CSV file and access the first item +# Read a CSV file and access the first item - name: Read users from CSV file and return a list read_csv: - path: users_unique.csv + path: "{{ remote_tmp_dir }}/users_unique.csv" register: users_unique - assert: @@ -61,12 +61,12 @@ dag;500;500;Dag Wieërs jeroen;501;500;Jeroen Hoekx dag;502;500;Dag Wieers - dest: users_nonunique.csv + dest: "{{ remote_tmp_dir }}/users_nonunique.csv" # Read a CSV file and access user 'dag' - name: Read users from CSV file and return a dictionary read_csv: - path: users_nonunique.csv + path: "{{ remote_tmp_dir }}/users_nonunique.csv" key: name unique: false delimiter: ';' @@ -87,7 +87,7 @@ # Read a CSV file using an non-existing dialect - name: Read users from CSV file and return a dictionary read_csv: - path: users_nonunique.csv + path: "{{ remote_tmp_dir }}/users_nonunique.csv" dialect: placebo register: users_placebo ignore_errors: true @@ -104,12 +104,12 @@ content: | dag,500,500,Dag Wieërs jeroen,501,500,Jeroen Hoekx - dest: users_noheader.csv + dest: "{{ remote_tmp_dir }}/users_noheader.csv" # Read a CSV file and access user 'dag' - name: Read users from CSV file and return a dictionary read_csv: - path: users_noheader.csv + path: "{{ remote_tmp_dir }}/users_noheader.csv" key: name fieldnames: name,uid,gid,gecos register: users_noheader @@ -133,12 +133,12 @@ name,uid,gid,gecos dag,500,500,Dag Wieërs jeroen,501,500,"Jeroen"Hoekx" - dest: users_broken.csv + dest: "{{ remote_tmp_dir }}/users_broken.csv" # Read a broken CSV file using strict - name: Read users from a broken CSV file read_csv: - path: users_broken.csv + path: "{{ remote_tmp_dir }}/users_broken.csv" key: name strict: true register: users_broken @@ -148,3 +148,29 @@ that: - users_broken is failed - "'Unable to process file' in users_broken.msg" + +# Create basic CSV file with BOM +- name: Create unique CSV file with BOM + copy: + content: "{{ bom + content }}" + dest: "{{ remote_tmp_dir }}/users_bom.csv" + vars: + content: *users_content + bom: "{{ '\ufeff' }}" + + # Read a CSV file and access the first item +- name: Read users from CSV file and return a list + read_csv: + path: "{{ remote_tmp_dir }}/users_bom.csv" + register: users_bom + +- assert: + that: + - users_bom.list.0.name == 'dag' + - users_bom.list.0.gecos == 'Dag Wieërs' + - users_bom.list.0.uid == '500' + - users_bom.list.0.gid == '500' + - users_bom.list.1.name == 'jeroen' + - users_bom.list.1.gecos == 'Jeroen Hoekx' + - users_bom.list.1.uid == '501' + - users_bom.list.1.gid == '500' From f3ecf4c7f8041f0653ca9b52b65452bbd899f05a Mon Sep 17 00:00:00 2001 From: Gnonthgol Date: Thu, 15 Jun 2023 07:19:29 +0200 Subject: [PATCH 0055/1451] ldap: Add client certificate support (#6668) * Set up secure ldap server * ldap: Added client cert options Shamelessly copied from https://github.com/andrewshulgin/ldap_search * Added tests for ldap client authentication * Add changelog fragment * Make sure the openssl commands work on older versions of openssl * Apply suggestions from code review Co-authored-by: Felix Fontein * Remove aliases for new arguments * Add required_together to ldap module declerations --------- Co-authored-by: Felix Fontein --- .../fragments/6668-ldap-client-cert.yml | 2 + plugins/doc_fragments/ldap.py | 12 +++++ plugins/module_utils/ldap.py | 12 +++++ plugins/modules/ldap_attrs.py | 3 +- plugins/modules/ldap_entry.py | 3 +- plugins/modules/ldap_passwd.py | 3 +- plugins/modules/ldap_search.py | 3 +- .../targets/ldap_search/tasks/tests/auth.yml | 47 +++++++++++++++++++ .../setup_openldap/files/cert_cnconfig.ldif | 15 ++++++ .../files/cert_cnconfig.ldif.license | 3 ++ .../setup_openldap/files/initial_config.ldif | 1 + .../targets/setup_openldap/tasks/main.yml | 22 ++++++++- 12 files changed, 121 insertions(+), 5 deletions(-) create mode 100644 changelogs/fragments/6668-ldap-client-cert.yml create mode 100644 tests/integration/targets/ldap_search/tasks/tests/auth.yml create mode 100644 tests/integration/targets/setup_openldap/files/cert_cnconfig.ldif create mode 100644 tests/integration/targets/setup_openldap/files/cert_cnconfig.ldif.license diff --git a/changelogs/fragments/6668-ldap-client-cert.yml b/changelogs/fragments/6668-ldap-client-cert.yml new file mode 100644 index 0000000000..e566b4ae13 --- /dev/null +++ b/changelogs/fragments/6668-ldap-client-cert.yml @@ -0,0 +1,2 @@ +minor_changes: + - ldap_* - add new arguments ``client_cert`` and ``client_key`` to the LDAP modules in order to allow certificate authentication (https://github.com/ansible-collections/community.general/pull/6668). diff --git a/plugins/doc_fragments/ldap.py b/plugins/doc_fragments/ldap.py index 451b3f3e06..e11ab065d8 100644 --- a/plugins/doc_fragments/ldap.py +++ b/plugins/doc_fragments/ldap.py @@ -29,6 +29,18 @@ options: - Set the path to PEM file with CA certs. type: path version_added: "6.5.0" + client_cert: + type: path + description: + - PEM formatted certificate chain file to be used for SSL client authentication. + - Required if O(client_key) is defined. + version_added: "7.1.0" + client_key: + type: path + description: + - PEM formatted file that contains your private key to be used for SSL client authentication. + - Required if O(client_cert) is defined. + version_added: "7.1.0" dn: required: true description: diff --git a/plugins/module_utils/ldap.py b/plugins/module_utils/ldap.py index 6553713210..ef444e9778 100644 --- a/plugins/module_utils/ldap.py +++ b/plugins/module_utils/ldap.py @@ -42,11 +42,17 @@ def gen_specs(**specs): 'validate_certs': dict(default=True, type='bool'), 'sasl_class': dict(choices=['external', 'gssapi'], default='external', type='str'), 'xorder_discovery': dict(choices=['enable', 'auto', 'disable'], default='auto', type='str'), + 'client_cert': dict(default=None, type='path'), + 'client_key': dict(default=None, type='path'), }) return specs +def ldap_required_together(): + return [['client_cert', 'client_key']] + + class LdapGeneric(object): def __init__(self, module): # Shortcuts @@ -60,6 +66,8 @@ class LdapGeneric(object): self.verify_cert = self.module.params['validate_certs'] self.sasl_class = self.module.params['sasl_class'] self.xorder_discovery = self.module.params['xorder_discovery'] + self.client_cert = self.module.params['client_cert'] + self.client_key = self.module.params['client_key'] # Establish connection self.connection = self._connect_to_ldap() @@ -102,6 +110,10 @@ class LdapGeneric(object): if self.ca_path: ldap.set_option(ldap.OPT_X_TLS_CACERTFILE, self.ca_path) + if self.client_cert and self.client_key: + ldap.set_option(ldap.OPT_X_TLS_CERTFILE, self.client_cert) + ldap.set_option(ldap.OPT_X_TLS_KEYFILE, self.client_key) + connection = ldap.initialize(self.server_uri) if self.referrals_chasing == 'disabled': diff --git a/plugins/modules/ldap_attrs.py b/plugins/modules/ldap_attrs.py index c2cac86444..d93b4672a4 100644 --- a/plugins/modules/ldap_attrs.py +++ b/plugins/modules/ldap_attrs.py @@ -182,7 +182,7 @@ import traceback from ansible.module_utils.basic import AnsibleModule, missing_required_lib from ansible.module_utils.common.text.converters import to_native, to_bytes, to_text -from ansible_collections.community.general.plugins.module_utils.ldap import LdapGeneric, gen_specs +from ansible_collections.community.general.plugins.module_utils.ldap import LdapGeneric, gen_specs, ldap_required_together import re @@ -300,6 +300,7 @@ def main(): state=dict(type='str', default='present', choices=['absent', 'exact', 'present']), ), supports_check_mode=True, + required_together=ldap_required_together(), ) if not HAS_LDAP: diff --git a/plugins/modules/ldap_entry.py b/plugins/modules/ldap_entry.py index 619bbf9279..11fa5278dc 100644 --- a/plugins/modules/ldap_entry.py +++ b/plugins/modules/ldap_entry.py @@ -151,7 +151,7 @@ import traceback from ansible.module_utils.basic import AnsibleModule, missing_required_lib from ansible.module_utils.common.text.converters import to_native, to_bytes -from ansible_collections.community.general.plugins.module_utils.ldap import LdapGeneric, gen_specs +from ansible_collections.community.general.plugins.module_utils.ldap import LdapGeneric, gen_specs, ldap_required_together LDAP_IMP_ERR = None try: @@ -255,6 +255,7 @@ def main(): ), required_if=[('state', 'present', ['objectClass'])], supports_check_mode=True, + required_together=ldap_required_together(), ) if not HAS_LDAP: diff --git a/plugins/modules/ldap_passwd.py b/plugins/modules/ldap_passwd.py index f47fa330e3..3f9e6ec4ad 100644 --- a/plugins/modules/ldap_passwd.py +++ b/plugins/modules/ldap_passwd.py @@ -72,7 +72,7 @@ modlist: import traceback from ansible.module_utils.basic import AnsibleModule, missing_required_lib -from ansible_collections.community.general.plugins.module_utils.ldap import LdapGeneric, gen_specs +from ansible_collections.community.general.plugins.module_utils.ldap import LdapGeneric, gen_specs, ldap_required_together LDAP_IMP_ERR = None try: @@ -133,6 +133,7 @@ def main(): module = AnsibleModule( argument_spec=gen_specs(passwd=dict(no_log=True)), supports_check_mode=True, + required_together=ldap_required_together(), ) if not HAS_LDAP: diff --git a/plugins/modules/ldap_search.py b/plugins/modules/ldap_search.py index 672ad51347..c6dbac4bf9 100644 --- a/plugins/modules/ldap_search.py +++ b/plugins/modules/ldap_search.py @@ -113,7 +113,7 @@ import traceback from ansible.module_utils.basic import AnsibleModule, missing_required_lib from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text from ansible.module_utils.six import string_types, text_type -from ansible_collections.community.general.plugins.module_utils.ldap import LdapGeneric, gen_specs +from ansible_collections.community.general.plugins.module_utils.ldap import LdapGeneric, gen_specs, ldap_required_together LDAP_IMP_ERR = None try: @@ -136,6 +136,7 @@ def main(): base64_attributes=dict(type='list', elements='str'), ), supports_check_mode=True, + required_together=ldap_required_together(), ) if not HAS_LDAP: diff --git a/tests/integration/targets/ldap_search/tasks/tests/auth.yml b/tests/integration/targets/ldap_search/tasks/tests/auth.yml new file mode 100644 index 0000000000..a8c7a13ee9 --- /dev/null +++ b/tests/integration/targets/ldap_search/tasks/tests/auth.yml @@ -0,0 +1,47 @@ +--- +# 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 + +- debug: + msg: Running tests/auth.yml + +#################################################################### +## Search ########################################################## +#################################################################### +- name: Test simple search for password authenticated user + ldap_search: + dn: "ou=users,dc=example,dc=com" + scope: "onelevel" + filter: "(uid=ldaptest)" + bind_dn: "uid=ldaptest,ou=users,dc=example,dc=com" + bind_pw: "test1pass!" + ignore_errors: true + register: output + +- name: assert that test LDAP user can read its password + assert: + that: + - output is not failed + - output.results | length == 1 + - output.results.0.userPassword is defined + +- name: Test simple search for cert authenticated user + ldap_search: + dn: "ou=users,dc=example,dc=com" + server_uri: "ldap://localhost/" + start_tls: true + ca_path: /usr/local/share/ca-certificates/ca.crt + scope: "onelevel" + filter: "(uid=ldaptest)" + client_cert: "/root/user.crt" + client_key: "/root/user.key" + ignore_errors: true + register: output + +- name: assert that test LDAP user can read its password + assert: + that: + - output is not failed + - output.results | length == 1 + - output.results.0.userPassword is defined diff --git a/tests/integration/targets/setup_openldap/files/cert_cnconfig.ldif b/tests/integration/targets/setup_openldap/files/cert_cnconfig.ldif new file mode 100644 index 0000000000..fc97e5f5c3 --- /dev/null +++ b/tests/integration/targets/setup_openldap/files/cert_cnconfig.ldif @@ -0,0 +1,15 @@ +dn: cn=config +add: olcTLSCACertificateFile +olcTLSCACertificateFile: /usr/local/share/ca-certificates/ca.crt +- +add: olcTLSCertificateFile +olcTLSCertificateFile: /etc/ldap/localhost.crt +- +add: olcTLSCertificateKeyFile +olcTLSCertificateKeyFile: /etc/ldap/localhost.key +- +add: olcAuthzRegexp +olcAuthzRegexp: {0}"UID=([^,]*)" uid=$1,ou=users,dc=example,dc=com +- +add: olcTLSVerifyClient +olcTLSVerifyClient: allow diff --git a/tests/integration/targets/setup_openldap/files/cert_cnconfig.ldif.license b/tests/integration/targets/setup_openldap/files/cert_cnconfig.ldif.license new file mode 100644 index 0000000000..edff8c7685 --- /dev/null +++ b/tests/integration/targets/setup_openldap/files/cert_cnconfig.ldif.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/integration/targets/setup_openldap/files/initial_config.ldif b/tests/integration/targets/setup_openldap/files/initial_config.ldif index 8f8c537bd3..6f2c940c15 100644 --- a/tests/integration/targets/setup_openldap/files/initial_config.ldif +++ b/tests/integration/targets/setup_openldap/files/initial_config.ldif @@ -18,5 +18,6 @@ homeDirectory: /home/ldaptest cn: LDAP Test gecos: LDAP Test displayName: LDAP Test +userPassword: test1pass! mail: ldap.test@example.com sn: Test diff --git a/tests/integration/targets/setup_openldap/tasks/main.yml b/tests/integration/targets/setup_openldap/tasks/main.yml index 25077de166..00f8f6a108 100644 --- a/tests/integration/targets/setup_openldap/tasks/main.yml +++ b/tests/integration/targets/setup_openldap/tasks/main.yml @@ -44,6 +44,22 @@ cmd: "export DEBIAN_FRONTEND=noninteractive; cat /root/debconf-slapd.conf | debconf-set-selections; dpkg-reconfigure -f noninteractive slapd" creates: "/root/slapd_configured" + - name: Enable secure ldap + lineinfile: + path: /etc/default/slapd + regexp: "^SLAPD_SERVICES" + line: 'SLAPD_SERVICES="ldap:/// ldaps:/// ldapi:///"' + + - name: Create certificates + shell: | + openssl req -x509 -batch -sha256 -days 1825 -newkey rsa:2048 -nodes -keyout /root/ca.key -out /usr/local/share/ca-certificates/ca.crt + openssl req -batch -sha256 -days 365 -newkey rsa:2048 -subj "/CN=$(hostname)" -addext "subjectAltName = DNS:localhost" -nodes -keyout /etc/ldap/localhost.key -out /etc/ldap/localhost.csr + openssl x509 -req -CA /usr/local/share/ca-certificates/ca.crt -CAkey /root/ca.key -CAcreateserial -in /etc/ldap/localhost.csr -out /etc/ldap/localhost.crt + chgrp openldap /etc/ldap/localhost.key + chmod 0640 /etc/ldap/localhost.key + openssl req -batch -sha256 -days 365 -newkey rsa:2048 -subj "/UID=ldaptest" -nodes -keyout /root/user.key -out /root/user.csr + openssl x509 -req -CA /usr/local/share/ca-certificates/ca.crt -CAkey /root/ca.key -CAcreateserial -in /root/user.csr -out /root/user.crt + - name: Start OpenLDAP service become: true service: @@ -61,10 +77,14 @@ mode: '0644' loop: - rootpw_cnconfig.ldif + - cert_cnconfig.ldif - initial_config.ldif - name: Configure admin password for cn=config - shell: "ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/rootpw_cnconfig.ldif" + shell: "ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/{{ item }}" + loop: + - rootpw_cnconfig.ldif + - cert_cnconfig.ldif - name: Add initial config become: true From 8801463575d9b3017154e091916e400148b58615 Mon Sep 17 00:00:00 2001 From: Gnonthgol Date: Thu, 15 Jun 2023 07:19:55 +0200 Subject: [PATCH 0056/1451] plugins/modules/ldap_search: Add support for multipage searches (#6648) * Add more integration tests for ldap_search * Add new page_size option to ldap_search * Add changelog fragment * Apply suggestions from code review Co-authored-by: Felix Fontein * Simplify if statement to reduce negatives * Apply suggestions from code review Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- .../fragments/6648_ldap_search_page_size.yml | 2 + plugins/modules/ldap_search.py | 50 +++++++++++++------ .../targets/ldap_search/tasks/tests/basic.yml | 14 ++++++ .../targets/ldap_search/tasks/tests/pages.yml | 24 +++++++++ .../ldap_search/tasks/tests/schema.yml | 25 ++++++++++ .../setup_openldap/files/initial_config.ldif | 18 +++++++ 6 files changed, 118 insertions(+), 15 deletions(-) create mode 100644 changelogs/fragments/6648_ldap_search_page_size.yml create mode 100644 tests/integration/targets/ldap_search/tasks/tests/pages.yml create mode 100644 tests/integration/targets/ldap_search/tasks/tests/schema.yml diff --git a/changelogs/fragments/6648_ldap_search_page_size.yml b/changelogs/fragments/6648_ldap_search_page_size.yml new file mode 100644 index 0000000000..361186db97 --- /dev/null +++ b/changelogs/fragments/6648_ldap_search_page_size.yml @@ -0,0 +1,2 @@ +minor_changes: + - ldap_search - add a new ``page_size`` option to enable paged searches (https://github.com/ansible-collections/community.general/pull/6648). diff --git a/plugins/modules/ldap_search.py b/plugins/modules/ldap_search.py index c6dbac4bf9..d8fa2efd07 100644 --- a/plugins/modules/ldap_search.py +++ b/plugins/modules/ldap_search.py @@ -61,6 +61,14 @@ options: description: - Set to C(true) to return the full attribute schema of entries, not their attribute values. Overrides I(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. + - 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 @@ -133,6 +141,7 @@ def main(): filter=dict(type='str', default='(objectClass=*)'), attrs=dict(type='list', elements='str'), schema=dict(type='bool', default=False), + page_size=dict(type='int', default=0), base64_attributes=dict(type='list', elements='str'), ), supports_check_mode=True, @@ -181,6 +190,7 @@ class LdapSearch(LdapGeneric): self.filterstr = self.module.params['filter'] self.attrlist = [] + self.page_size = self.module.params['page_size'] self._load_scope() self._load_attrs() self._load_schema() @@ -210,22 +220,32 @@ class LdapSearch(LdapGeneric): self.module.exit_json(changed=False, results=results) def perform_search(self): + ldap_entries = [] + controls = [] + if self.page_size > 0: + controls.append(ldap.controls.libldap.SimplePagedResultsControl(True, size=self.page_size, cookie='')) try: - results = self.connection.search_s( - self.dn, - self.scope, - filterstr=self.filterstr, - attrlist=self.attrlist, - attrsonly=self.attrsonly - ) - ldap_entries = [] - for result in results: - if isinstance(result[1], dict): - if self.schema: - ldap_entries.append(dict(dn=result[0], attrs=list(result[1].keys()))) - else: - ldap_entries.append(_extract_entry(result[0], result[1], self._base64_attributes)) - return ldap_entries + while True: + response = self.connection.search_ext( + self.dn, + self.scope, + filterstr=self.filterstr, + attrlist=self.attrlist, + attrsonly=self.attrsonly, + serverctrls=controls, + ) + rtype, results, rmsgid, serverctrls = self.connection.result3(response) + for result in results: + if isinstance(result[1], dict): + if self.schema: + ldap_entries.append(dict(dn=result[0], attrs=list(result[1].keys()))) + else: + ldap_entries.append(_extract_entry(result[0], result[1], self._base64_attributes)) + cookies = [c.cookie for c in serverctrls if c.controlType == ldap.controls.libldap.SimplePagedResultsControl.controlType] + if self.page_size > 0 and cookies and cookies[0]: + controls[0].cookie = cookies[0] + else: + return ldap_entries except ldap.NO_SUCH_OBJECT: self.module.fail_json(msg="Base not found: {0}".format(self.dn)) diff --git a/tests/integration/targets/ldap_search/tasks/tests/basic.yml b/tests/integration/targets/ldap_search/tasks/tests/basic.yml index 36d245d396..11e5d6562c 100644 --- a/tests/integration/targets/ldap_search/tasks/tests/basic.yml +++ b/tests/integration/targets/ldap_search/tasks/tests/basic.yml @@ -23,3 +23,17 @@ - output is not failed - output.results | length == 1 - output.results.0.displayName == "LDAP Test" + +- name: Test simple search for a user with no results + ldap_search: + dn: "ou=users,dc=example,dc=com" + scope: "onelevel" + filter: "(uid=nonexistent)" + ignore_errors: true + register: output + +- name: assert that the output is empty + assert: + that: + - output is not failed + - output.results | length == 0 diff --git a/tests/integration/targets/ldap_search/tasks/tests/pages.yml b/tests/integration/targets/ldap_search/tasks/tests/pages.yml new file mode 100644 index 0000000000..32575854ba --- /dev/null +++ b/tests/integration/targets/ldap_search/tasks/tests/pages.yml @@ -0,0 +1,24 @@ +--- +# 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 + +- debug: + msg: Running tests/pages.yml + +#################################################################### +## Search ########################################################## +#################################################################### +- name: Test paged search for all users + ldap_search: + dn: "ou=users,dc=example,dc=com" + scope: "onelevel" + page_size: 1 + ignore_errors: true + register: output + +- name: assert that the right number of results are returned + assert: + that: + - output is not failed + - output.results | length == 2 diff --git a/tests/integration/targets/ldap_search/tasks/tests/schema.yml b/tests/integration/targets/ldap_search/tasks/tests/schema.yml new file mode 100644 index 0000000000..892eac3cb3 --- /dev/null +++ b/tests/integration/targets/ldap_search/tasks/tests/schema.yml @@ -0,0 +1,25 @@ +--- +# 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 + +- debug: + msg: Running tests/schema.yml + +#################################################################### +## Search ########################################################## +#################################################################### +- name: Test for ldap schema output + ldap_search: + dn: "ou=users,dc=example,dc=com" + scope: "onelevel" + schema: true + ignore_errors: true + register: output + +- name: Assert that the schema output is correct + assert: + that: + - output is not failed + - output.results | length >= 1 + - "{{ 'displayName' in output.results.0.attrs }}" diff --git a/tests/integration/targets/setup_openldap/files/initial_config.ldif b/tests/integration/targets/setup_openldap/files/initial_config.ldif index 6f2c940c15..cb21f2cfdb 100644 --- a/tests/integration/targets/setup_openldap/files/initial_config.ldif +++ b/tests/integration/targets/setup_openldap/files/initial_config.ldif @@ -21,3 +21,21 @@ displayName: LDAP Test userPassword: test1pass! mail: ldap.test@example.com sn: Test + +dn: uid=second,ou=users,dc=example,dc=com +uid: second +uidNumber: 1112 +gidNUmber: 102 +objectClass: top +objectClass: posixAccount +objectClass: shadowAccount +objectClass: person +objectClass: organizationalPerson +objectClass: inetOrgPerson +loginShell: /bin/sh +homeDirectory: /home/second +cn: Second Test +gecos: Second Test +displayName: Second Test +mail: second.test@example.com +sn: Test From 7ae8cc9902534966d92dcc3e98c90620e71d1343 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 15 Jun 2023 09:29:30 +0200 Subject: [PATCH 0057/1451] Semantic markup: use E() in more places (#6699) Use semantic markup. --- plugins/doc_fragments/alicloud.py | 44 +++++++++++++------------- plugins/doc_fragments/bitbucket.py | 8 ++--- plugins/doc_fragments/dimensiondata.py | 4 +-- plugins/doc_fragments/hwc.py | 12 +++---- plugins/doc_fragments/influxdb.py | 4 +-- plugins/doc_fragments/ipa.py | 32 +++++++++---------- plugins/doc_fragments/manageiq.py | 12 +++---- plugins/doc_fragments/online.py | 4 +-- plugins/doc_fragments/opennebula.py | 8 ++--- plugins/doc_fragments/openswitch.py | 6 ++-- plugins/doc_fragments/oracle.py | 8 ++--- plugins/doc_fragments/proxmox.py | 2 +- plugins/doc_fragments/purestorage.py | 4 +-- plugins/doc_fragments/rackspace.py | 20 ++++++------ plugins/doc_fragments/scaleway.py | 4 +-- plugins/doc_fragments/xenserver.py | 8 ++--- plugins/inventory/lxd.py | 2 +- plugins/lookup/bitwarden.py | 2 +- plugins/lookup/etcd.py | 2 +- 19 files changed, 93 insertions(+), 93 deletions(-) diff --git a/plugins/doc_fragments/alicloud.py b/plugins/doc_fragments/alicloud.py index cce24c944a..03841aa136 100644 --- a/plugins/doc_fragments/alicloud.py +++ b/plugins/doc_fragments/alicloud.py @@ -15,27 +15,27 @@ class ModuleDocFragment(object): options: alicloud_access_key: description: - - Alibaba Cloud access key. If not set then the value of environment variable C(ALICLOUD_ACCESS_KEY), - C(ALICLOUD_ACCESS_KEY_ID) will be used instead. + - Alibaba Cloud access key. If not set then the value of environment variable E(ALICLOUD_ACCESS_KEY), + E(ALICLOUD_ACCESS_KEY_ID) will be used instead. aliases: ['access_key_id', 'access_key'] type: str alicloud_secret_key: description: - - Alibaba Cloud secret key. If not set then the value of environment variable C(ALICLOUD_SECRET_KEY), - C(ALICLOUD_SECRET_ACCESS_KEY) will be used instead. + - Alibaba Cloud secret key. If not set then the value of environment variable E(ALICLOUD_SECRET_KEY), + E(ALICLOUD_SECRET_ACCESS_KEY) will be used instead. aliases: ['secret_access_key', 'secret_key'] type: str alicloud_region: description: - The Alibaba Cloud region to use. If not specified then the value of environment variable - C(ALICLOUD_REGION), C(ALICLOUD_REGION_ID) will be used instead. + E(ALICLOUD_REGION), E(ALICLOUD_REGION_ID) will be used instead. aliases: ['region', 'region_id'] required: true type: str alicloud_security_token: description: - The Alibaba Cloud security token. If not specified then the value of environment variable - C(ALICLOUD_SECURITY_TOKEN) will be used instead. + E(ALICLOUD_SECURITY_TOKEN) will be used instead. aliases: ['security_token'] type: str alicloud_assume_role: @@ -48,7 +48,7 @@ options: alicloud_assume_role_arn: description: - The Alibaba Cloud role_arn. The ARN of the role to assume. If ARN is set to an empty string, - it does not perform role switching. It supports environment variable ALICLOUD_ASSUME_ROLE_ARN. + it does not perform role switching. It supports environment variable E(ALICLOUD_ASSUME_ROLE_ARN). ansible will execute with provided credentials. aliases: ['assume_role_arn'] type: str @@ -56,14 +56,14 @@ options: description: - The Alibaba Cloud session_name. The session name to use when assuming the role. If omitted, 'ansible' is passed to the AssumeRole call as session name. It supports environment variable - ALICLOUD_ASSUME_ROLE_SESSION_NAME + E(ALICLOUD_ASSUME_ROLE_SESSION_NAME). aliases: ['assume_role_session_name'] type: str alicloud_assume_role_session_expiration: description: - The Alibaba Cloud session_expiration. The time after which the established session for assuming role expires. Valid value range 900-3600 seconds. Default to 3600 (in this case Alicloud use own default - value). It supports environment variable ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION + value). It supports environment variable E(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION). aliases: ['assume_role_session_expiration'] type: int ecs_role_name: @@ -79,11 +79,11 @@ options: profile: description: - This is the Alicloud profile name as set in the shared credentials file. It can also be sourced from the - ALICLOUD_PROFILE environment variable. + E(ALICLOUD_PROFILE) environment variable. type: str shared_credentials_file: description: - - This is the path to the shared credentials file. It can also be sourced from the ALICLOUD_SHARED_CREDENTIALS_FILE + - This is the path to the shared credentials file. It can also be sourced from the E(ALICLOUD_SHARED_CREDENTIALS_FILE) environment variable. - If this is not set and a profile is specified, ~/.aliyun/config.json will be used. type: str @@ -94,16 +94,16 @@ requirements: notes: - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence - C(ALICLOUD_ACCESS_KEY) or C(ALICLOUD_ACCESS_KEY_ID), - C(ALICLOUD_SECRET_KEY) or C(ALICLOUD_SECRET_ACCESS_KEY), - C(ALICLOUD_REGION) or C(ALICLOUD_REGION_ID), - C(ALICLOUD_SECURITY_TOKEN), - C(ALICLOUD_ECS_ROLE_NAME), - C(ALICLOUD_SHARED_CREDENTIALS_FILE), - C(ALICLOUD_PROFILE), - C(ALICLOUD_ASSUME_ROLE_ARN), - C(ALICLOUD_ASSUME_ROLE_SESSION_NAME), - C(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION), - - C(ALICLOUD_REGION) or C(ALICLOUD_REGION_ID) can be typically be used to specify the + E(ALICLOUD_ACCESS_KEY) or E(ALICLOUD_ACCESS_KEY_ID), + E(ALICLOUD_SECRET_KEY) or E(ALICLOUD_SECRET_ACCESS_KEY), + E(ALICLOUD_REGION) or E(ALICLOUD_REGION_ID), + E(ALICLOUD_SECURITY_TOKEN), + E(ALICLOUD_ECS_ROLE_NAME), + E(ALICLOUD_SHARED_CREDENTIALS_FILE), + E(ALICLOUD_PROFILE), + E(ALICLOUD_ASSUME_ROLE_ARN), + E(ALICLOUD_ASSUME_ROLE_SESSION_NAME), + E(ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION), + - E(ALICLOUD_REGION) or E(ALICLOUD_REGION_ID) can be typically be used to specify the ALICLOUD region, when required, but this can also be configured in the footmark config file ''' diff --git a/plugins/doc_fragments/bitbucket.py b/plugins/doc_fragments/bitbucket.py index 269c8dee8d..0a66ea0a68 100644 --- a/plugins/doc_fragments/bitbucket.py +++ b/plugins/doc_fragments/bitbucket.py @@ -16,17 +16,17 @@ options: client_id: description: - The OAuth consumer key. - - If not set the environment variable C(BITBUCKET_CLIENT_ID) will be used. + - If not set the environment variable E(BITBUCKET_CLIENT_ID) will be used. type: str client_secret: description: - The OAuth consumer secret. - - If not set the environment variable C(BITBUCKET_CLIENT_SECRET) will be used. + - If not set the environment variable E(BITBUCKET_CLIENT_SECRET) will be used. type: str user: description: - The username. - - If not set the environment variable C(BITBUCKET_USERNAME) will be used. + - If not set the environment variable E(BITBUCKET_USERNAME) will be used. - O(ignore:username) is an alias of O(user) since community.general 6.0.0. It was an alias of O(workspace) before. type: str version_added: 4.0.0 @@ -34,7 +34,7 @@ options: password: description: - The App password. - - If not set the environment variable C(BITBUCKET_PASSWORD) will be used. + - If not set the environment variable E(BITBUCKET_PASSWORD) will be used. type: str version_added: 4.0.0 notes: diff --git a/plugins/doc_fragments/dimensiondata.py b/plugins/doc_fragments/dimensiondata.py index 24a4f483c9..e451bff22e 100644 --- a/plugins/doc_fragments/dimensiondata.py +++ b/plugins/doc_fragments/dimensiondata.py @@ -29,12 +29,12 @@ options: mcp_user: description: - The username used to authenticate to the CloudControl API. - - If not specified, will fall back to C(MCP_USER) from environment variable or C(~/.dimensiondata). + - If not specified, will fall back to E(MCP_USER) from environment variable or C(~/.dimensiondata). type: str mcp_password: description: - The password used to authenticate to the CloudControl API. - - If not specified, will fall back to C(MCP_PASSWORD) from environment variable or C(~/.dimensiondata). + - If not specified, will fall back to E(MCP_PASSWORD) from environment variable or C(~/.dimensiondata). - Required if O(mcp_user) is specified. type: str location: diff --git a/plugins/doc_fragments/hwc.py b/plugins/doc_fragments/hwc.py index d3cebb6dbc..fd7deece55 100644 --- a/plugins/doc_fragments/hwc.py +++ b/plugins/doc_fragments/hwc.py @@ -51,16 +51,16 @@ options: type: str notes: - For authentication, you can set identity_endpoint using the - C(ANSIBLE_HWC_IDENTITY_ENDPOINT) env variable. + E(ANSIBLE_HWC_IDENTITY_ENDPOINT) env variable. - For authentication, you can set user using the - C(ANSIBLE_HWC_USER) env variable. - - For authentication, you can set password using the C(ANSIBLE_HWC_PASSWORD) env + E(ANSIBLE_HWC_USER) env variable. + - For authentication, you can set password using the E(ANSIBLE_HWC_PASSWORD) env variable. - - For authentication, you can set domain using the C(ANSIBLE_HWC_DOMAIN) env + - For authentication, you can set domain using the E(ANSIBLE_HWC_DOMAIN) env variable. - - For authentication, you can set project using the C(ANSIBLE_HWC_PROJECT) env + - For authentication, you can set project using the E(ANSIBLE_HWC_PROJECT) env variable. - - For authentication, you can set region using the C(ANSIBLE_HWC_REGION) env variable. + - For authentication, you can set region using the E(ANSIBLE_HWC_REGION) env variable. - Environment variables values will only be used if the playbook values are not set. ''' diff --git a/plugins/doc_fragments/influxdb.py b/plugins/doc_fragments/influxdb.py index 882f8f00a6..c7564c863c 100644 --- a/plugins/doc_fragments/influxdb.py +++ b/plugins/doc_fragments/influxdb.py @@ -22,14 +22,14 @@ options: username: description: - Username that will be used to authenticate against InfluxDB server. - - Alias O(ignore:login_username) added in Ansible 2.5. + - Alias O(login_username) added in Ansible 2.5. type: str default: root aliases: [ login_username ] password: description: - Password that will be used to authenticate against InfluxDB server. - - Alias O(ignore:login_password) added in Ansible 2.5. + - Alias O(login_password) added in Ansible 2.5. type: str default: root aliases: [ login_password ] diff --git a/plugins/doc_fragments/ipa.py b/plugins/doc_fragments/ipa.py index fdc63dc728..59eb801b88 100644 --- a/plugins/doc_fragments/ipa.py +++ b/plugins/doc_fragments/ipa.py @@ -16,44 +16,44 @@ options: ipa_port: description: - Port of FreeIPA / IPA server. - - If the value is not specified in the task, the value of environment variable C(IPA_PORT) will be used instead. - - If both the environment variable C(IPA_PORT) and the value are not specified in the task, then default value is set. + - If the value is not specified in the task, the value of environment variable E(IPA_PORT) will be used instead. + - If both the environment variable E(IPA_PORT) and the value are not specified in the task, then default value is set. - Environment variable fallback mechanism is added in Ansible 2.5. type: int default: 443 ipa_host: description: - IP or hostname of IPA server. - - If the value is not specified in the task, the value of environment variable C(IPA_HOST) will be used instead. - - If both the environment variable C(IPA_HOST) and the value are not specified in the task, then DNS will be used to try to discover the FreeIPA server. + - If the value is not specified in the task, the value of environment variable E(IPA_HOST) will be used instead. + - If both the environment variable E(IPA_HOST) and the value are not specified in the task, then DNS will be used to try to discover the FreeIPA server. - The relevant entry needed in FreeIPA is the 'ipa-ca' entry. - - If neither the DNS entry, nor the environment C(IPA_HOST), nor the value are available in the task, then the default value will be used. + - If neither the DNS entry, nor the environment E(IPA_HOST), nor the value are available in the task, then the default value will be used. - Environment variable fallback mechanism is added in Ansible 2.5. type: str default: ipa.example.com ipa_user: description: - Administrative account used on IPA server. - - If the value is not specified in the task, the value of environment variable C(IPA_USER) will be used instead. - - If both the environment variable C(IPA_USER) and the value are not specified in the task, then default value is set. + - If the value is not specified in the task, the value of environment variable E(IPA_USER) will be used instead. + - If both the environment variable E(IPA_USER) and the value are not specified in the task, then default value is set. - Environment variable fallback mechanism is added in Ansible 2.5. type: str default: admin ipa_pass: description: - Password of administrative user. - - If the value is not specified in the task, the value of environment variable C(IPA_PASS) will be used instead. - - Note that if the 'urllib_gssapi' library is available, it is possible to use GSSAPI to authenticate to FreeIPA. - - If the environment variable C(KRB5CCNAME) is available, the module will use this kerberos credentials cache to authenticate to the FreeIPA server. - - If the environment variable C(KRB5_CLIENT_KTNAME) is available, and C(KRB5CCNAME) is not; the module will use this kerberos keytab to authenticate. - - If GSSAPI is not available, the usage of 'ipa_pass' is required. + - If the value is not specified in the task, the value of environment variable E(IPA_PASS) will be used instead. + - Note that if the C(urllib_gssapi) library is available, it is possible to use GSSAPI to authenticate to FreeIPA. + - If the environment variable E(KRB5CCNAME) is available, the module will use this kerberos credentials cache to authenticate to the FreeIPA server. + - If the environment variable E(KRB5_CLIENT_KTNAME) is available, and E(KRB5CCNAME) is not; the module will use this kerberos keytab to authenticate. + - If GSSAPI is not available, the usage of O(ipa_pass) is required. - Environment variable fallback mechanism is added in Ansible 2.5. type: str ipa_prot: description: - Protocol used by IPA server. - - If the value is not specified in the task, the value of environment variable C(IPA_PROT) will be used instead. - - If both the environment variable C(IPA_PROT) and the value are not specified in the task, then default value is set. + - If the value is not specified in the task, the value of environment variable E(IPA_PROT) will be used instead. + - If both the environment variable E(IPA_PROT) and the value are not specified in the task, then default value is set. - Environment variable fallback mechanism is added in Ansible 2.5. type: str choices: [ http, https ] @@ -69,8 +69,8 @@ options: description: - Specifies idle timeout (in seconds) for the connection. - For bulk operations, you may want to increase this in order to avoid timeout from IPA server. - - If the value is not specified in the task, the value of environment variable C(IPA_TIMEOUT) will be used instead. - - If both the environment variable C(IPA_TIMEOUT) and the value are not specified in the task, then default value is set. + - If the value is not specified in the task, the value of environment variable E(IPA_TIMEOUT) will be used instead. + - If both the environment variable E(IPA_TIMEOUT) and the value are not specified in the task, then default value is set. type: int default: 10 ''' diff --git a/plugins/doc_fragments/manageiq.py b/plugins/doc_fragments/manageiq.py index c20a519b0d..8afc183a5c 100644 --- a/plugins/doc_fragments/manageiq.py +++ b/plugins/doc_fragments/manageiq.py @@ -21,30 +21,30 @@ options: suboptions: url: description: - - ManageIQ environment URL. C(MIQ_URL) environment variable if set. otherwise, it is required to pass it. + - ManageIQ environment URL. E(MIQ_URL) environment variable if set. Otherwise, it is required to pass it. type: str required: false username: description: - - ManageIQ username. C(MIQ_USERNAME) environment variable if set. otherwise, required if no token is passed in. + - ManageIQ username. E(MIQ_USERNAME) environment variable if set. Otherwise, required if no token is passed in. type: str password: description: - - ManageIQ password. C(MIQ_PASSWORD) environment variable if set. otherwise, required if no token is passed in. + - ManageIQ password. E(MIQ_PASSWORD) environment variable if set. Otherwise, required if no token is passed in. type: str token: description: - - ManageIQ token. C(MIQ_TOKEN) environment variable if set. otherwise, required if no username or password is passed in. + - ManageIQ token. E(MIQ_TOKEN) environment variable if set. Otherwise, required if no username or password is passed in. type: str validate_certs: description: - - Whether SSL certificates should be verified for HTTPS requests. defaults to True. + - Whether SSL certificates should be verified for HTTPS requests. type: bool default: true aliases: [ verify_ssl ] ca_cert: description: - - The path to a CA bundle file or directory with certificates. defaults to None. + - The path to a CA bundle file or directory with certificates. type: str aliases: [ ca_bundle_path ] diff --git a/plugins/doc_fragments/online.py b/plugins/doc_fragments/online.py index a8a472bca3..fb803b9d96 100644 --- a/plugins/doc_fragments/online.py +++ b/plugins/doc_fragments/online.py @@ -39,7 +39,7 @@ notes: - Also see the API documentation on U(https://console.online.net/en/api/) - If O(api_token) is not set within the module, the following environment variables can be used in decreasing order of precedence - C(ONLINE_TOKEN), C(ONLINE_API_KEY), C(ONLINE_OAUTH_TOKEN), C(ONLINE_API_TOKEN) - - If one wants to use a different O(api_url) one can also set the C(ONLINE_API_URL) + E(ONLINE_TOKEN), E(ONLINE_API_KEY), E(ONLINE_OAUTH_TOKEN), E(ONLINE_API_TOKEN). + - If one wants to use a different O(api_url) one can also set the E(ONLINE_API_URL) environment variable. ''' diff --git a/plugins/doc_fragments/opennebula.py b/plugins/doc_fragments/opennebula.py index e034192501..567faf1a77 100644 --- a/plugins/doc_fragments/opennebula.py +++ b/plugins/doc_fragments/opennebula.py @@ -15,26 +15,26 @@ options: api_url: description: - The ENDPOINT URL of the XMLRPC server. - - If not specified then the value of the C(ONE_URL) environment variable, if any, is used. + - If not specified then the value of the E(ONE_URL) environment variable, if any, is used. type: str aliases: - api_endpoint api_username: description: - The name of the user for XMLRPC authentication. - - If not specified then the value of the C(ONE_USERNAME) environment variable, if any, is used. + - If not specified then the value of the E(ONE_USERNAME) environment variable, if any, is used. type: str api_password: description: - The password or token for XMLRPC authentication. - - If not specified then the value of the C(ONE_PASSWORD) environment variable, if any, is used. + - If not specified then the value of the E(ONE_PASSWORD) environment variable, if any, is used. type: str aliases: - api_token validate_certs: description: - Whether to validate the TLS/SSL certificates or not. - - This parameter is ignored if C(PYTHONHTTPSVERIFY) environment variable is used. + - This parameter is ignored if E(PYTHONHTTPSVERIFY) environment variable is used. type: bool default: true wait_timeout: diff --git a/plugins/doc_fragments/openswitch.py b/plugins/doc_fragments/openswitch.py index e212fd1579..f613de98c9 100644 --- a/plugins/doc_fragments/openswitch.py +++ b/plugins/doc_fragments/openswitch.py @@ -36,7 +36,7 @@ options: either the CLI login or the eAPI authentication depending on which transport is used. Note this argument does not affect the SSH transport. If the value is not specified in the task, the value of - environment variable C(ANSIBLE_NET_USERNAME) will be used instead. + environment variable E(ANSIBLE_NET_USERNAME) will be used instead. type: str password: description: @@ -44,7 +44,7 @@ options: the remote device. This is a common argument used for either O(transport=cli) or O(transport=rest). Note this argument does not affect the SSH transport. If the value is not specified in the task, the value of - environment variable C(ANSIBLE_NET_PASSWORD) will be used instead. + environment variable E(ANSIBLE_NET_PASSWORD) will be used instead. type: str timeout: description: @@ -58,7 +58,7 @@ options: - Specifies the SSH key to use to authenticate the connection to the remote device. This argument is only used for O(transport=cli). If the value is not specified in the task, the value of - environment variable C(ANSIBLE_NET_SSH_KEYFILE) will be used instead. + environment variable E(ANSIBLE_NET_SSH_KEYFILE) will be used instead. type: path transport: description: diff --git a/plugins/doc_fragments/oracle.py b/plugins/doc_fragments/oracle.py index c3a93fc131..2424b50eff 100644 --- a/plugins/doc_fragments/oracle.py +++ b/plugins/doc_fragments/oracle.py @@ -18,26 +18,26 @@ class ModuleDocFragment(object): options: config_file_location: description: - - Path to configuration file. If not set then the value of the OCI_CONFIG_FILE environment variable, + - Path to configuration file. If not set then the value of the E(OCI_CONFIG_FILE) environment variable, if any, is used. Otherwise, defaults to ~/.oci/config. type: str config_profile_name: description: - The profile to load from the config file referenced by O(config_file_location). If not set, then the - value of the OCI_CONFIG_PROFILE environment variable, if any, is used. Otherwise, defaults to the + value of the E(OCI_CONFIG_PROFILE) environment variable, if any, is used. Otherwise, defaults to the "DEFAULT" profile in O(config_file_location). default: "DEFAULT" type: str api_user: description: - The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the - value of the OCI_USER_OCID environment variable, if any, is used. This option is required if the user + value of the E(OCI_USER_OCID) environment variable, if any, is used. This option is required if the user is not specified through a configuration file (See O(config_file_location)). To get the user's OCID, please refer U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm). type: str api_user_fingerprint: description: - - Fingerprint for the key pair being used. If not set, then the value of the OCI_USER_FINGERPRINT + - Fingerprint for the key pair being used. If not set, then the value of the E(OCI_USER_FINGERPRINT) environment variable, if any, is used. This option is required if the key fingerprint is not specified through a configuration file (See O(config_file_location)). To get the key pair's fingerprint value please refer diff --git a/plugins/doc_fragments/proxmox.py b/plugins/doc_fragments/proxmox.py index 15d6555bb4..148b266222 100644 --- a/plugins/doc_fragments/proxmox.py +++ b/plugins/doc_fragments/proxmox.py @@ -24,7 +24,7 @@ options: api_password: description: - Specify the password to authenticate with. - - You can use C(PROXMOX_PASSWORD) environment variable. + - You can use E(PROXMOX_PASSWORD) environment variable. type: str api_token_id: description: diff --git a/plugins/doc_fragments/purestorage.py b/plugins/doc_fragments/purestorage.py index 2411245733..138d86f6ab 100644 --- a/plugins/doc_fragments/purestorage.py +++ b/plugins/doc_fragments/purestorage.py @@ -33,7 +33,7 @@ options: type: str notes: - This module requires the C(purity_fb) Python library - - You must set C(PUREFB_URL) and C(PUREFB_API) environment variables + - You must set E(PUREFB_URL) and E(PUREFB_API) environment variables if O(fb_url) and O(api_token) arguments are not passed to the module directly requirements: - python >= 2.7 @@ -55,7 +55,7 @@ options: required: true notes: - This module requires the C(purestorage) Python library - - You must set C(PUREFA_URL) and C(PUREFA_API) environment variables + - You must set E(PUREFA_URL) and E(PUREFA_API) environment variables if O(fa_url) and O(api_token) arguments are not passed to the module directly requirements: - python >= 2.7 diff --git a/plugins/doc_fragments/rackspace.py b/plugins/doc_fragments/rackspace.py index e68f2bfe85..b79e43faf5 100644 --- a/plugins/doc_fragments/rackspace.py +++ b/plugins/doc_fragments/rackspace.py @@ -46,12 +46,12 @@ requirements: - python >= 2.6 - pyrax notes: - - The following environment variables can be used, C(RAX_USERNAME), - C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION). - - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file + - The following environment variables can be used, E(RAX_USERNAME), + E(RAX_API_KEY), E(RAX_CREDS_FILE), E(RAX_CREDENTIALS), E(RAX_REGION). + - E(RAX_CREDENTIALS) and E(RAX_CREDS_FILE) point to a credentials file appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating) - - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file - - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...) + - E(RAX_USERNAME) and E(RAX_API_KEY) obviate the use of a credentials file + - E(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...) ''' # Documentation fragment including attributes to enable communication @@ -113,10 +113,10 @@ requirements: - python >= 2.6 - pyrax notes: - - The following environment variables can be used, C(RAX_USERNAME), - C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION). - - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file + - The following environment variables can be used, E(RAX_USERNAME), + E(RAX_API_KEY), E(RAX_CREDS_FILE), E(RAX_CREDENTIALS), E(RAX_REGION). + - E(RAX_CREDENTIALS) and E(RAX_CREDS_FILE) points to a credentials file appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating) - - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file - - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...) + - E(RAX_USERNAME) and E(RAX_API_KEY) obviate the use of a credentials file + - E(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...) ''' diff --git a/plugins/doc_fragments/scaleway.py b/plugins/doc_fragments/scaleway.py index 34b0769092..e737b77345 100644 --- a/plugins/doc_fragments/scaleway.py +++ b/plugins/doc_fragments/scaleway.py @@ -45,7 +45,7 @@ notes: - Also see the API documentation on U(https://developer.scaleway.com/) - If O(api_token) is not set within the module, the following environment variables can be used in decreasing order of precedence - C(SCW_TOKEN), C(SCW_API_KEY), C(SCW_OAUTH_TOKEN) or C(SCW_API_TOKEN). - - If one wants to use a different O(api_url) one can also set the C(SCW_API_URL) + E(SCW_TOKEN), E(SCW_API_KEY), E(SCW_OAUTH_TOKEN) or E(SCW_API_TOKEN). + - If one wants to use a different O(api_url) one can also set the E(SCW_API_URL) environment variable. ''' diff --git a/plugins/doc_fragments/xenserver.py b/plugins/doc_fragments/xenserver.py index 2a33c91451..681d959faa 100644 --- a/plugins/doc_fragments/xenserver.py +++ b/plugins/doc_fragments/xenserver.py @@ -15,27 +15,27 @@ options: hostname: description: - The hostname or IP address of the XenServer host or XenServer pool master. - - If the value is not specified in the task, the value of environment variable C(XENSERVER_HOST) will be used instead. + - If the value is not specified in the task, the value of environment variable E(XENSERVER_HOST) will be used instead. type: str default: localhost aliases: [ host, pool ] username: description: - The username to use for connecting to XenServer. - - If the value is not specified in the task, the value of environment variable C(XENSERVER_USER) will be used instead. + - If the value is not specified in the task, the value of environment variable E(XENSERVER_USER) will be used instead. type: str default: root aliases: [ admin, user ] password: description: - The password to use for connecting to XenServer. - - If the value is not specified in the task, the value of environment variable C(XENSERVER_PASSWORD) will be used instead. + - If the value is not specified in the task, the value of environment variable E(XENSERVER_PASSWORD) will be used instead. type: str aliases: [ pass, pwd ] validate_certs: description: - Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted. - - If the value is not specified in the task, the value of environment variable C(XENSERVER_VALIDATE_CERTS) will be used instead. + - If the value is not specified in the task, the value of environment variable E(XENSERVER_VALIDATE_CERTS) will be used instead. type: bool default: true ''' diff --git a/plugins/inventory/lxd.py b/plugins/inventory/lxd.py index 6b661d9f2f..ffe258a366 100644 --- a/plugins/inventory/lxd.py +++ b/plugins/inventory/lxd.py @@ -72,7 +72,7 @@ DOCUMENTATION = r''' description: - If an instance has multiple network interfaces, select which one is the prefered as pattern. - Combined with the first number that can be found e.g. 'eth' + 0. - - The option has been renamed from O(ignore:prefered_container_network_interface) to O(prefered_instance_network_interface) + - The option has been renamed from O(prefered_container_network_interface) to O(prefered_instance_network_interface) in community.general 3.8.0. The old name still works as an alias. type: str default: eth diff --git a/plugins/lookup/bitwarden.py b/plugins/lookup/bitwarden.py index 489b0d5d9c..727aceef3c 100644 --- a/plugins/lookup/bitwarden.py +++ b/plugins/lookup/bitwarden.py @@ -13,7 +13,7 @@ DOCUMENTATION = """ - bw (command line utility) - be logged into bitwarden - bitwarden vault unlocked - - C(BW_SESSION) environment variable set + - E(BW_SESSION) environment variable set short_description: Retrieve secrets from Bitwarden version_added: 5.4.0 description: diff --git a/plugins/lookup/etcd.py b/plugins/lookup/etcd.py index d6a12293e3..694f72f89b 100644 --- a/plugins/lookup/etcd.py +++ b/plugins/lookup/etcd.py @@ -24,7 +24,7 @@ DOCUMENTATION = ''' required: true url: description: - - Environment variable with the url for the etcd server + - Environment variable with the URL for the etcd server default: 'http://127.0.0.1:4001' env: - name: ANSIBLE_ETCD_URL From 6fc1df9b836802dacc339a12675b9665ebef405f Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 15 Jun 2023 15:46:33 +0200 Subject: [PATCH 0058/1451] Use semantic markup (modules a-c) (#6671) * Use semantic markup. * E() now works better. --- plugins/lookup/dependent.py | 2 +- plugins/lookup/flattened.py | 2 +- plugins/modules/alerta_customer.py | 2 +- plugins/modules/ali_instance.py | 28 +++++------ plugins/modules/ali_instance_info.py | 6 +-- plugins/modules/alternatives.py | 12 ++--- plugins/modules/ansible_galaxy_install.py | 46 +++++++++---------- plugins/modules/apache2_module.py | 2 +- plugins/modules/apk.py | 14 +++--- plugins/modules/apt_repo.py | 2 +- plugins/modules/apt_rpm.py | 2 +- plugins/modules/archive.py | 16 +++---- plugins/modules/awall.py | 6 +-- plugins/modules/bearychat.py | 6 +-- plugins/modules/bitbucket_access_key.py | 2 +- .../modules/bitbucket_pipeline_key_pair.py | 2 +- .../modules/bitbucket_pipeline_known_host.py | 4 +- .../modules/bitbucket_pipeline_variable.py | 4 +- plugins/modules/btrfs_subvolume.py | 14 +++--- plugins/modules/bzr.py | 8 ++-- plugins/modules/cargo.py | 4 +- plugins/modules/circonus_annotation.py | 4 +- plugins/modules/cloudflare_dns.py | 34 +++++++------- plugins/modules/cobbler_system.py | 12 ++--- plugins/modules/composer.py | 4 +- plugins/modules/consul.py | 46 +++++++++---------- plugins/modules/consul_acl.py | 2 +- plugins/modules/consul_kv.py | 28 +++++------ plugins/modules/consul_session.py | 14 +++--- plugins/modules/cpanm.py | 32 +++++-------- plugins/modules/cronvar.py | 13 +++--- plugins/modules/crypttab.py | 20 ++++---- 32 files changed, 193 insertions(+), 200 deletions(-) diff --git a/plugins/lookup/dependent.py b/plugins/lookup/dependent.py index 54714344eb..31634e6e6e 100644 --- a/plugins/lookup/dependent.py +++ b/plugins/lookup/dependent.py @@ -22,7 +22,7 @@ options: The name is the index that is used in the result object. The value is iterated over as described below. - If the value is a list, it is simply iterated over. - If the value is a dictionary, it is iterated over and returned as if they would be processed by the - R(ansible.builtin.dict2items filter,ansible_collections.ansible.builtin.dict2items_filter). + P(ansible.builtin.dict2items#filter) filter. - If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen elements with C(item.). The result must be a list or a dictionary. type: list diff --git a/plugins/lookup/flattened.py b/plugins/lookup/flattened.py index e955b6478e..0071417a0d 100644 --- a/plugins/lookup/flattened.py +++ b/plugins/lookup/flattened.py @@ -19,7 +19,7 @@ DOCUMENTATION = ''' elements: raw required: true notes: - - Unlike the R(items lookup,ansible_collections.ansible.builtin.items_lookup) which only flattens 1 level, + - Unlike the P(ansible.builtin.items#lookup) lookup which only flattens 1 level, this plugin will continue to flatten until it cannot find lists anymore. - Aka highlander plugin, there can only be one (list). ''' diff --git a/plugins/modules/alerta_customer.py b/plugins/modules/alerta_customer.py index 120d989328..5e1a5f86c4 100644 --- a/plugins/modules/alerta_customer.py +++ b/plugins/modules/alerta_customer.py @@ -58,7 +58,7 @@ options: state: description: - Whether the customer should exist or not. - - Both I(customer) and I(match) identify a customer that should be added or removed. + - Both O(customer) and O(match) identify a customer that should be added or removed. type: str choices: [ absent, present ] default: present diff --git a/plugins/modules/ali_instance.py b/plugins/modules/ali_instance.py index 232c21ee0f..d60cff3144 100644 --- a/plugins/modules/ali_instance.py +++ b/plugins/modules/ali_instance.py @@ -51,12 +51,12 @@ options: type: str image_id: description: - - Image ID used to launch instances. Required when I(state=present) and creating new ECS instances. + - Image ID used to launch instances. Required when O(state=present) and creating new ECS instances. aliases: ['image'] type: str instance_type: description: - - Instance type used to launch instances. Required when I(state=present) and creating new ECS instances. + - Instance type used to launch instances. Required when O(state=present) and creating new ECS instances. aliases: ['type'] type: str security_groups: @@ -95,7 +95,7 @@ options: max_bandwidth_out: description: - Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second). - Required when I(allocate_public_ip=true). Ignored when I(allocate_public_ip=false). + Required when O(allocate_public_ip=true). Ignored when O(allocate_public_ip=false). default: 0 type: int host_name: @@ -134,16 +134,16 @@ options: type: str count: description: - - The number of the new instance. An integer value which indicates how many instances that match I(count_tag) + - The number of the new instance. An integer value which indicates how many instances that match O(count_tag) should be running. Instances are either created or terminated based on this value. default: 1 type: int count_tag: description: - - I(count) determines how many instances based on a specific tag criteria should be present. + - O(count) determines how many instances based on a specific tag criteria should be present. This can be expressed in multiple ways and is shown in the EXAMPLES section. - The specified count_tag must already exist or be passed in as the I(tags) option. - If it is not specified, it will be replaced by I(instance_name). + The specified count_tag must already exist or be passed in as the O(tags) option. + If it is not specified, it will be replaced by O(instance_name). type: str allocate_public_ip: description: @@ -159,7 +159,7 @@ options: type: str period: description: - - The charge duration of the instance, in months. Required when I(instance_charge_type=PrePaid). + - The charge duration of the instance, in months. Required when O(instance_charge_type=PrePaid). - The valid value are [1-9, 12, 24, 36]. default: 1 type: int @@ -170,13 +170,13 @@ options: default: false auto_renew_period: description: - - The duration of the automatic renew the charge of the instance. Required when I(auto_renew=true). + - The duration of the automatic renew the charge of the instance. Required when O(auto_renew=true). choices: [1, 2, 3, 6, 12] type: int instance_ids: description: - A list of instance ids. It is required when need to operate existing instances. - If it is specified, I(count) will lose efficacy. + If it is specified, O(count) will lose efficacy. type: list elements: str force: @@ -186,7 +186,7 @@ options: type: bool tags: description: - - A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. C({"key":"value"}) + - A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. V({"key":"value"}) aliases: ["instance_tags"] type: dict version_added: '0.2.0' @@ -229,7 +229,7 @@ options: version_added: '0.2.0' period_unit: description: - - The duration unit that you will buy the resource. It is valid when I(instance_charge_type=PrePaid). + - The duration unit that you will buy the resource. It is valid when O(instance_charge_type=PrePaid). choices: ['Month', 'Week'] default: 'Month' type: str @@ -237,10 +237,10 @@ options: dry_run: description: - Specifies whether to send a dry-run request. - - If I(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the + - If O(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the required parameters are set, and validates the request format, service permissions, and available ECS instances. If the validation fails, the corresponding error code is returned. If the validation succeeds, the DryRunOperation error code is returned. - - If I(dry_run=false), A request is sent. If the validation succeeds, the instance is created. + - If O(dry_run=false), A request is sent. If the validation succeeds, the instance is created. default: false type: bool version_added: '0.2.0' diff --git a/plugins/modules/ali_instance_info.py b/plugins/modules/ali_instance_info.py index e7ec7f3956..30f3ca8ea9 100644 --- a/plugins/modules/ali_instance_info.py +++ b/plugins/modules/ali_instance_info.py @@ -53,9 +53,9 @@ options: description: - A dict of filters to apply. Each dict item consists of a filter key and a filter value. The filter keys can be all of request parameters. See U(https://www.alibabacloud.com/help/doc-detail/25506.htm) for parameter details. - Filter keys can be same as request parameter name or be lower case and use underscore ("_") or dash ("-") to - connect different words in one parameter. 'InstanceIds' should be a list. - 'Tag.n.Key' and 'Tag.n.Value' should be a dict and using I(tags) instead. + Filter keys can be same as request parameter name or be lower case and use underscore (V("_")) or dash (V("-")) to + connect different words in one parameter. C(InstanceIds) should be a list. + C(Tag.n.Key) and C(Tag.n.Value) should be a dict and using O(tags) instead. type: dict version_added: '0.2.0' author: diff --git a/plugins/modules/alternatives.py b/plugins/modules/alternatives.py index 97d4f51fbb..0d1b1e8cbe 100644 --- a/plugins/modules/alternatives.py +++ b/plugins/modules/alternatives.py @@ -44,21 +44,21 @@ options: description: - The path to the symbolic link that should point to the real executable. - This option is always required on RHEL-based distributions. On Debian-based distributions this option is - required when the alternative I(name) is unknown to the system. + required when the alternative O(name) is unknown to the system. type: path priority: description: - - The priority of the alternative. If no priority is given for creation C(50) is used as a fallback. + - The priority of the alternative. If no priority is given for creation V(50) is used as a fallback. type: int state: description: - - C(present) - install the alternative (if not already installed), but do + - V(present) - install the alternative (if not already installed), but do not set it as the currently selected alternative for the group. - - C(selected) - install the alternative (if not already installed), and + - V(selected) - install the alternative (if not already installed), and set it as the currently selected alternative for the group. - - C(auto) - install the alternative (if not already installed), and + - V(auto) - install the alternative (if not already installed), and set the group to auto mode. Added in community.general 5.1.0. - - C(absent) - removes the alternative. Added in community.general 5.1.0. + - V(absent) - removes the alternative. Added in community.general 5.1.0. choices: [ present, selected, auto, absent ] default: selected type: str diff --git a/plugins/modules/ansible_galaxy_install.py b/plugins/modules/ansible_galaxy_install.py index 0f38eabdf6..3328f76d37 100644 --- a/plugins/modules/ansible_galaxy_install.py +++ b/plugins/modules/ansible_galaxy_install.py @@ -37,9 +37,9 @@ options: type: description: - The type of installation performed by C(ansible-galaxy). - - If I(type) is C(both), then I(requirements_file) must be passed and it may contain both roles and collections. - - "Note however that the opposite is not true: if using a I(requirements_file), then I(type) can be any of the three choices." - - "B(Ansible 2.9): The option C(both) will have the same effect as C(role)." + - If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections. + - "Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three choices." + - "B(Ansible 2.9): The option V(both) will have the same effect as V(role)." type: str choices: [collection, role, both] required: true @@ -48,22 +48,22 @@ options: - Name of the collection or role being installed. - > Versions can be specified with C(ansible-galaxy) usual formats. - For example, the collection C(community.docker:1.6.1) or the role C(ansistrano.deploy,3.8.0). - - I(name) and I(requirements_file) are mutually exclusive. + For example, the collection V(community.docker:1.6.1) or the role V(ansistrano.deploy,3.8.0). + - O(name) and O(requirements_file) are mutually exclusive. type: str requirements_file: description: - Path to a file containing a list of requirements to be installed. - - It works for I(type) equals to C(collection) and C(role). - - I(name) and I(requirements_file) are mutually exclusive. - - "B(Ansible 2.9): It can only be used to install either I(type=role) or I(type=collection), but not both at the same run." + - It works for O(type) equals to V(collection) and V(role). + - O(name) and O(requirements_file) are mutually exclusive. + - "B(Ansible 2.9): It can only be used to install either O(type=role) or O(type=collection), but not both at the same run." type: path dest: description: - - The path to the directory containing your collections or roles, according to the value of I(type). + - The path to the directory containing your collections or roles, according to the value of O(type). - > - Please notice that C(ansible-galaxy) will not install collections with I(type=both), when I(requirements_file) - contains both roles and collections and I(dest) is specified. + Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file) + contains both roles and collections and O(dest) is specified. type: path no_deps: description: @@ -74,8 +74,8 @@ options: force: description: - Force overwriting an existing role or collection. - - Using I(force=true) is mandatory when downgrading. - - "B(Ansible 2.9 and 2.10): Must be C(true) to upgrade roles and collections." + - Using O(force=true) is mandatory when downgrading. + - "B(Ansible 2.9 and 2.10): Must be V(true) to upgrade roles and collections." type: bool default: false ack_ansible29: @@ -92,7 +92,7 @@ options: - Support for those versions will be removed in community.general 8.0.0. At the same time, this option will be removed without any deprecation warning! - This option is completely ignored if using a version of ansible-core/ansible-base/Ansible greater than C(2.11). - - For the sake of conciseness, setting this parameter to C(true) implies I(ack_ansible29=true). + - For the sake of conciseness, setting this parameter to V(true) implies O(ack_ansible29=true). type: bool default: false """ @@ -124,29 +124,29 @@ EXAMPLES = """ RETURN = """ type: - description: The value of the I(type) parameter. + description: The value of the O(type) parameter. type: str returned: always name: - description: The value of the I(name) parameter. + description: The value of the O(name) parameter. type: str returned: always dest: - description: The value of the I(dest) parameter. + description: The value of the O(dest) parameter. type: str returned: always requirements_file: - description: The value of the I(requirements_file) parameter. + description: The value of the O(requirements_file) parameter. type: str returned: always force: - description: The value of the I(force) parameter. + description: The value of the O(force) parameter. type: bool returned: always installed_roles: description: - - If I(requirements_file) is specified instead, returns dictionary with all the roles installed per path. - - If I(name) is specified, returns that role name and the version installed per path. + - If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path. + - If O(name) is specified, returns that role name and the version installed per path. - "B(Ansible 2.9): Returns empty because C(ansible-galaxy) has no C(list) subcommand." type: dict returned: always when installing roles @@ -162,8 +162,8 @@ RETURN = """ ansistrano.deploy: 3.8.0 installed_collections: description: - - If I(requirements_file) is specified instead, returns dictionary with all the collections installed per path. - - If I(name) is specified, returns that collection name and the version installed per path. + - If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path. + - If O(name) is specified, returns that collection name and the version installed per path. - "B(Ansible 2.9): Returns empty because C(ansible-galaxy) has no C(list) subcommand." type: dict returned: always when installing collections diff --git a/plugins/modules/apache2_module.py b/plugins/modules/apache2_module.py index 2e2456d741..92b1dde3ce 100644 --- a/plugins/modules/apache2_module.py +++ b/plugins/modules/apache2_module.py @@ -37,7 +37,7 @@ options: description: - Identifier of the module as listed by C(apache2ctl -M). This is optional and usually determined automatically by the common convention of - appending C(_module) to I(name) as well as custom exception for popular modules. + appending V(_module) to O(name) as well as custom exception for popular modules. required: false force: description: diff --git a/plugins/modules/apk.py b/plugins/modules/apk.py index e56b2165dd..b444d137dd 100644 --- a/plugins/modules/apk.py +++ b/plugins/modules/apk.py @@ -17,7 +17,7 @@ DOCUMENTATION = ''' module: apk short_description: Manages apk packages description: - - Manages I(apk) packages for Alpine Linux. + - Manages C(apk) packages for Alpine Linux. author: "Kevin Brebanov (@kbrebanov)" extends_documentation_fragment: - community.general.attributes @@ -35,7 +35,7 @@ options: default: false name: description: - - A package name, like C(foo), or multiple packages, like C(foo, bar). + - A package name, like V(foo), or multiple packages, like V(foo, bar). type: list elements: str no_cache: @@ -53,9 +53,9 @@ options: state: description: - Indicates the desired package(s) state. - - C(present) ensures the package(s) is/are present. C(installed) can be used as an alias. - - C(absent) ensures the package(s) is/are absent. C(removed) can be used as an alias. - - C(latest) ensures the package(s) is/are present and the latest version(s). + - V(present) ensures the package(s) is/are present. V(installed) can be used as an alias. + - V(absent) ensures the package(s) is/are absent. V(removed) can be used as an alias. + - V(latest) ensures the package(s) is/are present and the latest version(s). default: present choices: [ "present", "absent", "latest", "installed", "removed" ] type: str @@ -76,8 +76,8 @@ options: default: /etc/apk/world version_added: 5.4.0 notes: - - 'I(name) and I(upgrade) are mutually exclusive.' - - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the I(name) option. + - 'O(name) and O(upgrade) are mutually exclusive.' + - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option. ''' EXAMPLES = ''' diff --git a/plugins/modules/apt_repo.py b/plugins/modules/apt_repo.py index 5560390271..4c82587d03 100644 --- a/plugins/modules/apt_repo.py +++ b/plugins/modules/apt_repo.py @@ -41,7 +41,7 @@ options: remove_others: description: - Remove other then added repositories - - Used if I(state=present) + - Used if O(state=present) type: bool default: false update: diff --git a/plugins/modules/apt_rpm.py b/plugins/modules/apt_rpm.py index 8749086bbf..4c632a6fd2 100644 --- a/plugins/modules/apt_rpm.py +++ b/plugins/modules/apt_rpm.py @@ -16,7 +16,7 @@ DOCUMENTATION = ''' module: apt_rpm short_description: APT-RPM package manager description: - - Manages packages with I(apt-rpm). Both low-level (I(rpm)) and high-level (I(apt-get)) package manager binaries required. + - Manages packages with C(apt-rpm). Both low-level (C(rpm)) and high-level (C(apt-get)) package manager binaries required. extends_documentation_fragment: - community.general.attributes attributes: diff --git a/plugins/modules/archive.py b/plugins/modules/archive.py index 8748fb8a3e..e6128be6ef 100644 --- a/plugins/modules/archive.py +++ b/plugins/modules/archive.py @@ -20,7 +20,7 @@ extends_documentation_fragment: description: - Creates or extends an archive. - The source and archive are on the remote host, and the archive I(is not) copied to the local host. - - Source files can be deleted after archival by specifying I(remove=True). + - Source files can be deleted after archival by specifying O(remove=True). attributes: check_mode: support: full @@ -43,20 +43,20 @@ options: dest: description: - The file name of the destination archive. The parent directory must exists on the remote host. - - This is required when C(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list. + - This is required when O(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list. - If the destination archive already exists, it will be truncated and overwritten. type: path exclude_path: description: - - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from I(path) list and glob expansion. - - Use I(exclusion_patterns) to instead exclude files or subdirectories below any of the paths from the I(path) list. + - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from O(path) list and glob expansion. + - Use O(exclusion_patterns) to instead exclude files or subdirectories below any of the paths from the O(path) list. type: list elements: path default: [] exclusion_patterns: description: - Glob style patterns to exclude files or directories from the resulting archive. - - This differs from I(exclude_path) which applies only to the source paths from I(path). + - This differs from O(exclude_path) which applies only to the source paths from O(path). type: list elements: path version_added: 3.2.0 @@ -73,7 +73,7 @@ options: type: bool default: false notes: - - Can produce I(gzip), I(bzip2), I(lzma), and I(zip) compressed files or archives. + - Can produce C(gzip), C(bzip2), C(lzma), and C(zip) compressed files or archives. - This module uses C(tarfile), C(zipfile), C(gzip), and C(bz2) packages on the target host to create archives. These are part of the Python standard library for Python 2 and 3. requirements: @@ -149,11 +149,11 @@ state: returned: always dest_state: description: - - The state of the I(dest) file. + - The state of the O(dest) file. - C(absent) when the file does not exist. - C(archive) when the file is an archive. - C(compress) when the file is compressed, but not an archive. - - C(incomplete) when the file is an archive, but some files under I(path) were not found. + - C(incomplete) when the file is an archive, but some files under O(path) were not found. type: str returned: success version_added: 3.4.0 diff --git a/plugins/modules/awall.py b/plugins/modules/awall.py index da1b29f701..f3c2384b5b 100644 --- a/plugins/modules/awall.py +++ b/plugins/modules/awall.py @@ -16,7 +16,7 @@ short_description: Manage awall policies author: Ted Trask (@tdtrask) description: - This modules allows for enable/disable/activate of C(awall) policies. - - Alpine Wall (I(awall)) generates a firewall configuration from the enabled policy files + - Alpine Wall (C(awall)) generates a firewall configuration from the enabled policy files and activates the configuration on the system. extends_documentation_fragment: - community.general.attributes @@ -41,11 +41,11 @@ options: description: - Activate the new firewall rules. - Can be run with other steps or on its own. - - Idempotency is affected if I(activate=true), as the module will always report a changed state. + - Idempotency is affected if O(activate=true), as the module will always report a changed state. type: bool default: false notes: - - At least one of I(name) and I(activate) is required. + - At least one of O(name) and O(activate) is required. ''' EXAMPLES = r''' diff --git a/plugins/modules/bearychat.py b/plugins/modules/bearychat.py index 28f1f8fcd9..f52737facd 100644 --- a/plugins/modules/bearychat.py +++ b/plugins/modules/bearychat.py @@ -27,7 +27,7 @@ options: description: - BearyChat WebHook URL. This authenticates you to the bearychat service. It looks like - C(https://hook.bearychat.com/=ae2CF/incoming/e61bd5c57b164e04b11ac02e66f47f60). + V(https://hook.bearychat.com/=ae2CF/incoming/e61bd5c57b164e04b11ac02e66f47f60). required: true text: type: str @@ -35,14 +35,14 @@ options: - Message to send. markdown: description: - - If C(true), text will be parsed as markdown. + - If V(true), text will be parsed as markdown. default: true type: bool channel: type: str description: - Channel to send the message to. If absent, the message goes to the - default channel selected by the I(url). + default channel selected by the O(url). attachments: type: list elements: dict diff --git a/plugins/modules/bitbucket_access_key.py b/plugins/modules/bitbucket_access_key.py index 5ef199f7a4..29c19b8b3d 100644 --- a/plugins/modules/bitbucket_access_key.py +++ b/plugins/modules/bitbucket_access_key.py @@ -33,7 +33,7 @@ options: workspace: description: - The repository owner. - - I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user). + - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)." type: str required: true key: diff --git a/plugins/modules/bitbucket_pipeline_key_pair.py b/plugins/modules/bitbucket_pipeline_key_pair.py index d39c054b11..3bc41c2987 100644 --- a/plugins/modules/bitbucket_pipeline_key_pair.py +++ b/plugins/modules/bitbucket_pipeline_key_pair.py @@ -33,7 +33,7 @@ options: workspace: description: - The repository owner. - - I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user). + - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)." type: str required: true public_key: diff --git a/plugins/modules/bitbucket_pipeline_known_host.py b/plugins/modules/bitbucket_pipeline_known_host.py index 28ff487398..3e6c4bfbf1 100644 --- a/plugins/modules/bitbucket_pipeline_known_host.py +++ b/plugins/modules/bitbucket_pipeline_known_host.py @@ -14,7 +14,7 @@ module: bitbucket_pipeline_known_host short_description: Manages Bitbucket pipeline known hosts description: - Manages Bitbucket pipeline known hosts under the "SSH Keys" menu. - - The host fingerprint will be retrieved automatically, but in case of an error, one can use I(key) field to specify it manually. + - The host fingerprint will be retrieved automatically, but in case of an error, one can use O(key) field to specify it manually. author: - Evgeniy Krysanov (@catcombo) extends_documentation_fragment: @@ -36,7 +36,7 @@ options: workspace: description: - The repository owner. - - I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user). + - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)." type: str required: true name: diff --git a/plugins/modules/bitbucket_pipeline_variable.py b/plugins/modules/bitbucket_pipeline_variable.py index eac0d18dda..1ff8e43753 100644 --- a/plugins/modules/bitbucket_pipeline_variable.py +++ b/plugins/modules/bitbucket_pipeline_variable.py @@ -33,7 +33,7 @@ options: workspace: description: - The repository owner. - - I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user). + - "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)." type: str required: true name: @@ -58,7 +58,7 @@ options: choices: [ absent, present ] notes: - Check mode is supported. - - For secured values return parameter C(changed) is always C(True). + - For secured values return parameter C(changed) is always V(true). ''' EXAMPLES = r''' diff --git a/plugins/modules/btrfs_subvolume.py b/plugins/modules/btrfs_subvolume.py index cd2ac6f972..864bb65a66 100644 --- a/plugins/modules/btrfs_subvolume.py +++ b/plugins/modules/btrfs_subvolume.py @@ -23,7 +23,7 @@ options: default: false default: description: - - Make the subvolume specified by I(name) the filesystem's default subvolume. + - Make the subvolume specified by O(name) the filesystem's default subvolume. type: bool default: false filesystem_device: @@ -49,7 +49,7 @@ options: recursive: description: - When true, indicates that parent/child subvolumes should be created/removedas necessary - to complete the operation (for I(state=present) and I(state=absent) respectively). + to complete the operation (for O(state=present) and O(state=absent) respectively). type: bool default: false snapshot_source: @@ -60,11 +60,11 @@ options: snapshot_conflict: description: - Policy defining behavior when a subvolume already exists at the path of the requested snapshot. - - C(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that no change is required. + - V(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that no change is required. Warning, this option does not yet verify that the target subvolume was generated from a snapshot of the requested source. - - C(clobber) - If a subvolume already exists at the requested location, delete it first. + - V(clobber) - If a subvolume already exists at the requested location, delete it first. This option is not idempotent and will result in a new snapshot being generated on every execution. - - C(error) - If a subvolume already exists at the requested location, return an error. + - V(error) - If a subvolume already exists at the requested location, return an error. This option is not idempotent and will result in an error on replay of the module. type: str choices: [ skip, clobber, error ] @@ -77,7 +77,7 @@ options: default: present notes: - - If any or all of the options I(filesystem_device), I(filesystem_label) or I(filesystem_uuid) parameters are provided, there is expected + - If any or all of the options O(filesystem_device), O(filesystem_label) or O(filesystem_uuid) parameters are provided, there is expected to be a matching btrfs filesystem. If none are provided and only a single btrfs filesystem exists or only a single btrfs filesystem is mounted, that filesystem will be used; otherwise, the module will take no action and return an error. @@ -201,7 +201,7 @@ modifications: target_subvolume_id: description: - - The ID of the subvolume specified with the I(name) parameter, either pre-existing or created as part of module execution. + - The ID of the subvolume specified with the O(name) parameter, either pre-existing or created as part of module execution. type: int sample: 257 returned: Success and subvolume exists after module execution diff --git a/plugins/modules/bzr.py b/plugins/modules/bzr.py index e7aca7c6bb..6223b1f6d1 100644 --- a/plugins/modules/bzr.py +++ b/plugins/modules/bzr.py @@ -16,7 +16,7 @@ author: - André Paramés (@andreparames) short_description: Deploy software (or files) from bzr branches description: - - Manage I(bzr) branches to deploy files or software. + - Manage C(bzr) branches to deploy files or software. extends_documentation_fragment: - community.general.attributes attributes: @@ -44,9 +44,9 @@ options: type: str force: description: - - If C(true), any modified files in the working - tree will be discarded. Before 1.9 the default - value was C(true). + - If V(true), any modified files in the working + tree will be discarded. Before Ansible 1.9 the default + value was V(true). type: bool default: false executable: diff --git a/plugins/modules/cargo.py b/plugins/modules/cargo.py index 24be43741b..a5fc7c1a59 100644 --- a/plugins/modules/cargo.py +++ b/plugins/modules/cargo.py @@ -35,12 +35,12 @@ options: description: -> The base path where to install the Rust packages. Cargo automatically appends - C(/bin). In other words, C(/usr/local) will become C(/usr/local/bin). + V(/bin). In other words, V(/usr/local) will become V(/usr/local/bin). type: path version: description: -> - The version to install. If I(name) contains multiple values, the module will + The version to install. If O(name) contains multiple values, the module will try to install all of them in this version. type: str required: false diff --git a/plugins/modules/circonus_annotation.py b/plugins/modules/circonus_annotation.py index 9376107761..f3b94a0524 100644 --- a/plugins/modules/circonus_annotation.py +++ b/plugins/modules/circonus_annotation.py @@ -52,12 +52,12 @@ options: type: int description: - Unix timestamp of event start - - If not specified, it defaults to I(now). + - If not specified, it defaults to "now". stop: type: int description: - Unix timestamp of event end - - If not specified, it defaults to I(now) + I(duration). + - If not specified, it defaults to "now" + O(duration). duration: type: int description: diff --git a/plugins/modules/cloudflare_dns.py b/plugins/modules/cloudflare_dns.py index 8f45fcef3b..2c560f4a08 100644 --- a/plugins/modules/cloudflare_dns.py +++ b/plugins/modules/cloudflare_dns.py @@ -31,7 +31,7 @@ options: - API token. - Required for api token authentication. - "You can obtain your API token from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)." - - Can be specified in C(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0. + - Can be specified in E(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0. type: str required: false version_added: '0.2.0' @@ -51,39 +51,39 @@ options: algorithm: description: - Algorithm number. - - Required for I(type=DS) and I(type=SSHFP) when I(state=present). + - Required for O(type=DS) and O(type=SSHFP) when O(state=present). type: int cert_usage: description: - Certificate usage number. - - Required for I(type=TLSA) when I(state=present). + - Required for O(type=TLSA) when O(state=present). type: int choices: [ 0, 1, 2, 3 ] hash_type: description: - Hash type number. - - Required for I(type=DS), I(type=SSHFP) and I(type=TLSA) when I(state=present). + - Required for O(type=DS), O(type=SSHFP) and O(type=TLSA) when O(state=present). type: int choices: [ 1, 2 ] key_tag: description: - DNSSEC key tag. - - Needed for I(type=DS) when I(state=present). + - Needed for O(type=DS) when O(state=present). type: int port: description: - Service port. - - Required for I(type=SRV) and I(type=TLSA). + - Required for O(type=SRV) and O(type=TLSA). type: int priority: description: - Record priority. - - Required for I(type=MX) and I(type=SRV) + - Required for O(type=MX) and O(type=SRV) default: 1 type: int proto: description: - - Service protocol. Required for I(type=SRV) and I(type=TLSA). + - Service protocol. Required for O(type=SRV) and O(type=TLSA). - Common values are TCP and UDP. - Before Ansible 2.6 only TCP and UDP were available. type: str @@ -95,26 +95,26 @@ options: record: description: - Record to add. - - Required if I(state=present). - - Default is C(@) (e.g. the zone name). + - Required if O(state=present). + - Default is V(@) (that is, the zone name). type: str default: '@' aliases: [ name ] selector: description: - Selector number. - - Required for I(type=TLSA) when I(state=present). + - Required for O(type=TLSA) when O(state=present). choices: [ 0, 1 ] type: int service: description: - Record service. - - Required for I(type=SRV). + - Required for O(type=SRV). type: str solo: description: - Whether the record should be the only one for that record type and record name. - - Only use with I(state=present). + - Only use with O(state=present). - This will delete all other records with the same record name and type. type: bool state: @@ -136,20 +136,20 @@ options: default: 1 type: description: - - The type of DNS record to create. Required if I(state=present). - - I(type=DS), I(type=SSHFP) and I(type=TLSA) added in Ansible 2.7. + - The type of DNS record to create. Required if O(state=present). + - O(type=DS), O(type=SSHFP), and O(type=TLSA) were added in Ansible 2.7. type: str choices: [ A, AAAA, CNAME, DS, MX, NS, SPF, SRV, SSHFP, TLSA, TXT ] value: description: - The record value. - - Required for I(state=present). + - Required for O(state=present). type: str aliases: [ content ] weight: description: - Service weight. - - Required for I(type=SRV). + - Required for O(type=SRV). type: int default: 1 zone: diff --git a/plugins/modules/cobbler_system.py b/plugins/modules/cobbler_system.py index c30b4f1c12..834ae1fdf4 100644 --- a/plugins/modules/cobbler_system.py +++ b/plugins/modules/cobbler_system.py @@ -30,7 +30,7 @@ options: port: description: - Port number to be used for REST connection. - - The default value depends on parameter C(use_ssl). + - The default value depends on parameter I(use_ssl). type: int username: description: @@ -43,13 +43,13 @@ options: type: str use_ssl: description: - - If C(false), an HTTP connection will be used instead of the default HTTPS connection. + - If V(false), an HTTP connection will be used instead of the default HTTPS connection. type: bool default: true validate_certs: description: - - If C(false), SSL certificates will not be validated. - - This should only set to C(false) when used on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates will not be validated. + - This should only set to V(false) when used on personally controlled sites using self-signed certificates. type: bool default: true name: @@ -144,11 +144,11 @@ EXAMPLES = r''' RETURN = r''' systems: description: List of systems - returned: I(state=query) and I(name) is not provided + returned: O(state=query) and O(name) is not provided type: list system: description: (Resulting) information about the system we are working with - returned: when I(name) is provided + returned: when O(name) is provided type: dict ''' diff --git a/plugins/modules/composer.py b/plugins/modules/composer.py index 793abcda18..b04b2bfdd6 100644 --- a/plugins/modules/composer.py +++ b/plugins/modules/composer.py @@ -49,7 +49,7 @@ options: description: - Directory of your project (see --working-dir). This is required when the command is not run globally. - - Will be ignored if I(global_command=true). + - Will be ignored if O(global_command=true). global_command: description: - Runs the specified command globally. @@ -111,7 +111,7 @@ options: version_added: 3.2.0 requirements: - php - - composer installed in bin path (recommended /usr/local/bin) or specified in I(composer_executable) + - composer installed in bin path (recommended /usr/local/bin) or specified in O(composer_executable) notes: - Default options that are always appended in each execution are --no-ansi, --no-interaction and --no-progress if available. - We received reports about issues on macOS if composer was installed by Homebrew. Please use the official install method to avoid issues. diff --git a/plugins/modules/consul.py b/plugins/modules/consul.py index cc599be36d..d72218e855 100644 --- a/plugins/modules/consul.py +++ b/plugins/modules/consul.py @@ -21,8 +21,8 @@ description: notify the health of the entire node to the cluster. Service level checks do not require a check name or id as these are derived by Consul from the Service name and id respectively by appending 'service:' - Node level checks require a I(check_name) and optionally a I(check_id)." - - Currently, there is no complete way to retrieve the script, interval or ttl + Node level checks require a O(check_name) and optionally a O(check_id)." + - Currently, there is no complete way to retrieve the script, interval or TTL metadata for a registered check. Without this metadata it is not possible to tell if the data supplied with ansible represents a change to a check. As a result this does not attempt to determine changes and will always report a @@ -56,7 +56,7 @@ options: service_id: type: str description: - - The ID for the service, must be unique per node. If I(state=absent), + - The ID for the service, must be unique per node. If O(state=absent), defaults to the service name if supplied. host: type: str @@ -86,12 +86,12 @@ options: type: int description: - The port on which the service is listening. Can optionally be supplied for - registration of a service, i.e. if I(service_name) or I(service_id) is set. + registration of a service, that is if O(service_name) or O(service_id) is set. service_address: type: str description: - The address to advertise that the service will be listening on. - This value will be passed as the I(address) parameter to Consul's + This value will be passed as the C(address) parameter to Consul's C(/v1/agent/service/register) API method, so refer to the Consul API documentation for further details. tags: @@ -103,19 +103,19 @@ options: type: str description: - The script/command that will be run periodically to check the health of the service. - - Requires I(interval) to be provided. + - Requires O(interval) to be provided. interval: type: str description: - The interval at which the service check will be run. - This is a number with a C(s) or C(m) suffix to signify the units of seconds or minutes e.g C(15s) or C(1m). - If no suffix is supplied C(s) will be used by default, e.g. C(10) will be C(10s). - - Required if one of the parameters I(script), I(http), or I(tcp) is specified. + This is a number with a V(s) or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m). + If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s). + - Required if one of the parameters O(script), O(http), or O(tcp) is specified. check_id: type: str description: - - An ID for the service check. If I(state=absent), defaults to - I(check_name). Ignored if part of a service definition. + - An ID for the service check. If O(state=absent), defaults to + O(check_name). Ignored if part of a service definition. check_name: type: str description: @@ -124,34 +124,34 @@ options: ttl: type: str description: - - Checks can be registered with a ttl instead of a I(script) and I(interval) + - Checks can be registered with a TTL instead of a O(script) and O(interval) this means that the service will check in with the agent before the - ttl expires. If it doesn't the check will be considered failed. + TTL expires. If it doesn't the check will be considered failed. Required if registering a check and the script an interval are missing - Similar to the interval this is a number with a C(s) or C(m) suffix to - signify the units of seconds or minutes e.g C(15s) or C(1m). - If no suffix is supplied C(s) will be used by default, e.g. C(10) will be C(10s). + Similar to the interval this is a number with a V(s) or V(m) suffix to + signify the units of seconds or minutes, for example V(15s) or V(1m). + If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s). tcp: type: str description: - Checks can be registered with a TCP port. This means that consul will check if the connection attempt to that port is successful (that is, the port is currently accepting connections). - The format is C(host:port), for example C(localhost:80). - - Requires I(interval) to be provided. + The format is V(host:port), for example V(localhost:80). + - Requires O(interval) to be provided. version_added: '1.3.0' http: type: str description: - Checks can be registered with an HTTP endpoint. This means that consul will check that the http endpoint returns a successful HTTP status. - - Requires I(interval) to be provided. + - Requires O(interval) to be provided. timeout: type: str description: - A custom HTTP check timeout. The consul default is 10 seconds. - Similar to the interval this is a number with a C(s) or C(m) suffix to - signify the units of seconds or minutes, e.g. C(15s) or C(1m). - If no suffix is supplied C(s) will be used by default, e.g. C(10) will be C(10s). + Similar to the interval this is a number with a V(s) or V(m) suffix to + signify the units of seconds or minutes, for example V(15s) or V(1m). + If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s). token: type: str description: @@ -159,7 +159,7 @@ options: ack_params_state_absent: type: bool description: - - Disable deprecation warning when using parameters incompatible with I(state=absent). + - Disable deprecation warning when using parameters incompatible with O(state=absent). ''' EXAMPLES = ''' diff --git a/plugins/modules/consul_acl.py b/plugins/modules/consul_acl.py index 91f955228a..7be34a6463 100644 --- a/plugins/modules/consul_acl.py +++ b/plugins/modules/consul_acl.py @@ -156,7 +156,7 @@ token: rules: description: the HCL JSON representation of the rules associated to the ACL, in the format described in the Consul documentation (https://www.consul.io/docs/guides/acl.html#rule-specification). - returned: I(status) == "present" + returned: when O(state=present) type: dict sample: { "key": { diff --git a/plugins/modules/consul_kv.py b/plugins/modules/consul_kv.py index a4457f2445..84169fc6b7 100644 --- a/plugins/modules/consul_kv.py +++ b/plugins/modules/consul_kv.py @@ -17,7 +17,7 @@ description: - Allows the retrieval, addition, modification and deletion of key/value entries in a consul cluster via the agent. The entire contents of the record, including the indices, flags and session are returned as C(value). - - If the C(key) represents a prefix then note that when a value is removed, the existing + - If the O(key) represents a prefix then note that when a value is removed, the existing value if any is returned as part of the results. - See http://www.consul.io/docs/agent/http.html#kv for more details. requirements: @@ -36,14 +36,14 @@ attributes: options: state: description: - - The action to take with the supplied key and value. If the state is C(present) and I(value) is set, the key - contents will be set to the value supplied and C(changed) will be set to C(true) only if the value was - different to the current contents. If the state is C(present) and I(value) is not set, the existing value - associated to the key will be returned. The state C(absent) will remove the key/value pair, - again C(changed) will be set to true only if the key actually existed + - The action to take with the supplied key and value. If the state is V(present) and O(value) is set, the key + contents will be set to the value supplied and C(changed) will be set to V(true) only if the value was + different to the current contents. If the state is V(present) and O(value) is not set, the existing value + associated to the key will be returned. The state V(absent) will remove the key/value pair, + again C(changed) will be set to V(true) only if the key actually existed prior to the removal. An attempt can be made to obtain or free the - lock associated with a key/value pair with the states C(acquire) or - C(release) respectively. a valid session must be supplied to make the + lock associated with a key/value pair with the states V(acquire) or + V(release) respectively. a valid session must be supplied to make the attempt changed will be true if the attempt is successful, false otherwise. type: str @@ -56,17 +56,17 @@ options: required: true value: description: - - The value should be associated with the given key, required if C(state) - is C(present). + - The value should be associated with the given key, required if O(state) + is V(present). type: str recurse: description: - If the key represents a prefix, each entry with the prefix can be - retrieved by setting this to C(true). + retrieved by setting this to V(true). type: bool retrieve: description: - - If the I(state) is C(present) and I(value) is set, perform a + - If the O(state) is V(present) and O(value) is set, perform a read after setting the value and return this value. default: true type: bool @@ -82,9 +82,9 @@ options: type: str cas: description: - - Used when acquiring a lock with a session. If the C(cas) is C(0), then + - Used when acquiring a lock with a session. If the O(cas) is V(0), then Consul will only put the key if it does not already exist. If the - C(cas) value is non-zero, then the key is only set if the index matches + O(cas) value is non-zero, then the key is only set if the index matches the ModifyIndex of that key. type: str flags: diff --git a/plugins/modules/consul_session.py b/plugins/modules/consul_session.py index 246d13846f..59c64858ff 100644 --- a/plugins/modules/consul_session.py +++ b/plugins/modules/consul_session.py @@ -31,25 +31,25 @@ attributes: options: id: description: - - ID of the session, required when I(state) is either C(info) or - C(remove). + - ID of the session, required when O(state) is either V(info) or + V(remove). type: str state: description: - Whether the session should be present i.e. created if it doesn't - exist, or absent, removed if present. If created, the I(id) for the - session is returned in the output. If C(absent), I(id) is + exist, or absent, removed if present. If created, the O(id) for the + session is returned in the output. If V(absent), O(id) is required to remove the session. Info for a single session, all the sessions for a node or all available sessions can be retrieved by - specifying C(info), C(node) or C(list) for the I(state); for C(node) - or C(info), the node I(name) or session I(id) is required as parameter. + specifying V(info), V(node) or V(list) for the O(state); for V(node) + or V(info), the node O(name) or session O(id) is required as parameter. choices: [ absent, info, list, node, present ] type: str default: present name: description: - The name that should be associated with the session. Required when - I(state=node) is used. + O(state=node) is used. type: str delay: description: diff --git a/plugins/modules/cpanm.py b/plugins/modules/cpanm.py index c78d58d12b..7aab087ec9 100644 --- a/plugins/modules/cpanm.py +++ b/plugins/modules/cpanm.py @@ -27,8 +27,8 @@ options: name: type: str description: - - The Perl library to install. Valid values change according to the I(mode), see notes for more details. - - Note that for installing from a local path the parameter I(from_path) should be used. + - The Perl library to install. Valid values change according to the O(mode), see notes for more details. + - Note that for installing from a local path the parameter O(from_path) should be used. aliases: [pkg] from_path: type: path @@ -59,7 +59,7 @@ options: default: false version: description: - - Version specification for the perl module. When I(mode) is C(new), C(cpanm) version operators are accepted. + - Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted. type: str executable: description: @@ -68,32 +68,24 @@ options: mode: description: - Controls the module behavior. See notes below for more details. - - Default is C(compatibility) but that behavior is deprecated and will be changed to C(new) in community.general 9.0.0. + - Default is V(compatibility) but that behavior is deprecated and will be changed to V(new) in community.general 9.0.0. type: str choices: [compatibility, new] version_added: 3.0.0 name_check: description: - - When in C(new) mode, this parameter can be used to check if there is a module I(name) installed (at I(version), when specified). + - When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when specified). type: str version_added: 3.0.0 notes: - Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host. - - "This module now comes with a choice of execution I(mode): C(compatibility) or C(new)." - - "C(compatibility) mode:" - - When using C(compatibility) mode, the module will keep backward compatibility. This is the default mode. - - I(name) must be either a module name or a distribution file. - - > - If the perl module given by I(name) is installed (at the exact I(version) when specified), then nothing happens. - Otherwise, it will be installed using the C(cpanm) executable. - - I(name) cannot be an URL, or a git URL. - - C(cpanm) version specifiers do not work in this mode. - - "C(new) mode:" - - "When using C(new) mode, the module will behave differently" - - > - The I(name) parameter may refer to a module name, a distribution file, - a HTTP URL or a git repository URL as described in C(cpanminus) documentation. - - C(cpanm) version specifiers are recognized. + - "This module now comes with a choice of execution O(mode): V(compatibility) or V(new)." + - "O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility. This is the default mode. + O(name) must be either a module name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version) + when specified), then nothing happens. Otherwise, it will be installed using the C(cpanm) executable. O(name) cannot be an URL, or a git URL. + C(cpanm) version specifiers do not work in this mode." + - "O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module name, a distribution file, + a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized." author: - "Franck Cuny (@fcuny)" - "Alexei Znamensky (@russoz)" diff --git a/plugins/modules/cronvar.py b/plugins/modules/cronvar.py index 7effed2ae1..fdcbc7d24b 100644 --- a/plugins/modules/cronvar.py +++ b/plugins/modules/cronvar.py @@ -40,16 +40,16 @@ options: value: description: - The value to set this variable to. - - Required if I(state=present). + - Required if O(state=present). type: str insertafter: description: - If specified, the variable will be inserted after the variable specified. - - Used with I(state=present). + - Used with O(state=present). type: str insertbefore: description: - - Used with I(state=present). If specified, the variable will be inserted + - Used with O(state=present). If specified, the variable will be inserted just before the variable specified. type: str state: @@ -61,18 +61,19 @@ options: user: description: - The specific user whose crontab should be modified. - - This parameter defaults to C(root) when unset. + - This parameter defaults to V(root) when unset. type: str cron_file: description: - If specified, uses this file instead of an individual user's crontab. - - Without a leading C(/), this is assumed to be in I(/etc/cron.d). - - With a leading C(/), this is taken as absolute. + - Without a leading V(/), this is assumed to be in C(/etc/cron.d). + - With a leading V(/), this is taken as absolute. type: str backup: description: - If set, create a backup of the crontab before it is modified. The location of the backup is returned in the C(backup) variable by this module. + # TODO: C() above should be RV(), but return values have not been documented! type: bool default: false requirements: diff --git a/plugins/modules/crypttab.py b/plugins/modules/crypttab.py index 6aea362e74..931a0c930b 100644 --- a/plugins/modules/crypttab.py +++ b/plugins/modules/crypttab.py @@ -25,38 +25,38 @@ options: name: description: - Name of the encrypted block device as it appears in the C(/etc/crypttab) file, or - optionally prefixed with C(/dev/mapper/), as it appears in the filesystem. I(/dev/mapper/) - will be stripped from I(name). + optionally prefixed with V(/dev/mapper/), as it appears in the filesystem. V(/dev/mapper/) + will be stripped from O(name). type: str required: true state: description: - - Use I(present) to add a line to C(/etc/crypttab) or update its definition + - Use V(present) to add a line to C(/etc/crypttab) or update its definition if already present. - - Use I(absent) to remove a line with matching I(name). - - Use I(opts_present) to add options to those already present; options with + - Use V(absent) to remove a line with matching O(name). + - Use V(opts_present) to add options to those already present; options with different values will be updated. - - Use I(opts_absent) to remove options from the existing set. + - Use V(opts_absent) to remove options from the existing set. type: str required: true choices: [ absent, opts_absent, opts_present, present ] backing_device: description: - Path to the underlying block device or file, or the UUID of a block-device - prefixed with I(UUID=). + prefixed with V(UUID=). type: str password: description: - Encryption password, the path to a file containing the password, or - C(-) or unset if the password should be entered at boot. + V(-) or unset if the password should be entered at boot. type: path opts: description: - - A comma-delimited list of options. See C(crypttab(5) ) for details. + - A comma-delimited list of options. See V(crypttab(5\)) for details. type: str path: description: - - Path to file to use instead of C(/etc/crypttab). + - Path to file to use instead of V(/etc/crypttab). - This might be useful in a chroot environment. type: path default: /etc/crypttab From 2ed82e0318b57d9a6f25466a5dc5d4196a23a0c1 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 15 Jun 2023 15:46:44 +0200 Subject: [PATCH 0059/1451] Use semantic markup (modules d-g) (#6672) * Use semantic markup. * 'ignore:' is no longer needed. * E() now works better. --- plugins/modules/datadog_monitor.py | 14 ++--- plugins/modules/deploy_helper.py | 47 +++++++------- plugins/modules/dimensiondata_network.py | 2 +- plugins/modules/dimensiondata_vlan.py | 8 +-- plugins/modules/discord.py | 6 +- plugins/modules/django_manage.py | 70 ++++++++++----------- plugins/modules/dnf_versionlock.py | 16 ++--- plugins/modules/dnsimple.py | 4 +- plugins/modules/dnsimple_info.py | 6 +- plugins/modules/dpkg_divert.py | 26 ++++---- plugins/modules/easy_install.py | 18 +++--- plugins/modules/etcd3.py | 8 +-- plugins/modules/facter.py | 2 +- plugins/modules/filesize.py | 38 +++++------ plugins/modules/filesystem.py | 28 ++++----- plugins/modules/flatpak.py | 14 ++--- plugins/modules/flatpak_remote.py | 22 +++---- plugins/modules/gandi_livedns.py | 4 +- plugins/modules/gconftool2.py | 16 ++--- plugins/modules/git_config.py | 20 +++--- plugins/modules/github_deploy_key.py | 10 +-- plugins/modules/github_key.py | 8 +-- plugins/modules/github_repo.py | 28 ++++----- plugins/modules/gitlab_branch.py | 2 +- plugins/modules/gitlab_group_members.py | 20 +++--- plugins/modules/gitlab_group_variable.py | 16 ++--- plugins/modules/gitlab_instance_variable.py | 8 +-- plugins/modules/gitlab_project.py | 66 +++++++++---------- plugins/modules/gitlab_project_badge.py | 6 +- plugins/modules/gitlab_project_members.py | 18 +++--- plugins/modules/gitlab_project_variable.py | 20 +++--- plugins/modules/gitlab_runner.py | 30 ++++----- plugins/modules/gitlab_user.py | 10 +-- plugins/modules/grove.py | 2 +- 34 files changed, 307 insertions(+), 306 deletions(-) diff --git a/plugins/modules/datadog_monitor.py b/plugins/modules/datadog_monitor.py index d1ad288ccc..75ae8c2332 100644 --- a/plugins/modules/datadog_monitor.py +++ b/plugins/modules/datadog_monitor.py @@ -16,7 +16,6 @@ short_description: Manages Datadog monitors description: - Manages monitors within Datadog. - Options as described on https://docs.datadoghq.com/api/. - - The type C(event-v2) was added in community.general 4.8.0. author: Sebastian Kornehl (@skornehl) requirements: [datadog] extends_documentation_fragment: @@ -34,8 +33,8 @@ options: type: str api_host: description: - - The URL to the Datadog API. Default value is C(https://api.datadoghq.com). - - This value can also be set with the C(DATADOG_HOST) environment variable. + - The URL to the Datadog API. Default value is V(https://api.datadoghq.com). + - This value can also be set with the E(DATADOG_HOST) environment variable. required: false type: str version_added: '0.2.0' @@ -59,8 +58,9 @@ options: type: description: - The type of the monitor. - - The types C(query alert), C(trace-analytics alert) and C(rum alert) were added in community.general 2.1.0. - - The type C(composite) was added in community.general 3.4.0. + - The types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0. + - The type V(composite) was added in community.general 3.4.0. + - The type V(event-v2 alert) was added in community.general 4.8.0. choices: - metric alert - service check @@ -117,7 +117,7 @@ options: escalation_message: description: - A message to include with a re-notification. Supports the '@username' notification we allow elsewhere. - - Not applicable if I(renotify_interval=None). + - Not applicable if O(renotify_interval=none). type: str notify_audit: description: @@ -130,7 +130,7 @@ options: - A dictionary of thresholds by status. - Only available for service checks and metric alerts. - Because each of them can have multiple thresholds, we do not define them directly in the query. - - "If not specified, it defaults to: C({'ok': 1, 'critical': 1, 'warning': 1})." + - "If not specified, it defaults to: V({'ok': 1, 'critical': 1, 'warning': 1})." locked: description: - Whether changes to this monitor should be restricted to the creator or admins. diff --git a/plugins/modules/deploy_helper.py b/plugins/modules/deploy_helper.py index f0246cae63..b47ed82540 100644 --- a/plugins/modules/deploy_helper.py +++ b/plugins/modules/deploy_helper.py @@ -20,8 +20,9 @@ description: - The Deploy Helper manages some of the steps common in deploying software. It creates a folder structure, manages a symlink for the current release and cleans up old releases. - - "Running it with the I(state=query) or I(state=present) will return the C(deploy_helper) fact. - C(project_path), whatever you set in the I(path) parameter, + # TODO: convert below to RETURN documentation! + - "Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact. + C(project_path), whatever you set in the O(path) parameter, C(current_path), the path to the symlink that points to the active release, C(releases_path), the path to the folder to keep releases in, C(shared_path), the path to the folder to keep shared resources in, @@ -50,33 +51,33 @@ options: type: str description: - The state of the project. - C(query) will only gather facts, - C(present) will create the project I(root) folder, and in it the I(releases) and I(shared) folders, - C(finalize) will remove the unfinished_filename file, create a symlink to the newly - deployed release and optionally clean old releases, - C(clean) will remove failed & old releases, - C(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with I(state=absent)). + - V(query) will only gather facts. + - V(present) will create the project C(root) folder, and in it the C(releases) and C(shared) folders. + - V(finalize) will remove the unfinished_filename file, create a symlink to the newly + deployed release and optionally clean old releases. + - V(clean) will remove failed & old releases. + - V(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with O(state=absent)). choices: [ present, finalize, absent, clean, query ] default: present release: type: str description: - - The release version that is being deployed. Defaults to a timestamp format %Y%m%d%H%M%S (i.e. '20141119223359'). - This parameter is optional during I(state=present), but needs to be set explicitly for I(state=finalize). - You can use the generated fact I(release={{ deploy_helper.new_release }}). + - The release version that is being deployed. Defaults to a timestamp format C(%Y%m%d%H%M%S) (for example V(20141119223359)). + This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize). + You can use the generated fact C(release={{ deploy_helper.new_release }}). releases_path: type: str description: - - The name of the folder that will hold the releases. This can be relative to I(path) or absolute. + - The name of the folder that will hold the releases. This can be relative to O(path) or absolute. Returned in the C(deploy_helper.releases_path) fact. default: releases shared_path: type: path description: - - The name of the folder that will hold the shared resources. This can be relative to I(path) or absolute. + - The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute. If this is set to an empty string, no shared folder will be created. Returned in the C(deploy_helper.shared_path) fact. default: shared @@ -84,38 +85,38 @@ options: current_path: type: path description: - - The name of the symlink that is created when the deploy is finalized. Used in I(finalize) and I(clean). + - The name of the symlink that is created when the deploy is finalized. Used in O(state=finalize) and O(state=clean). Returned in the C(deploy_helper.current_path) fact. default: current unfinished_filename: type: str description: - - The name of the file that indicates a deploy has not finished. All folders in the I(releases_path) that - contain this file will be deleted on I(state=finalize) with I(clean=True), or I(state=clean). This file is - automatically deleted from the I(new_release_path) during I(state=finalize). + - The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that + contain this file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is + automatically deleted from the C(new_release_path) during O(state=finalize). default: DEPLOY_UNFINISHED clean: description: - - Whether to run the clean procedure in case of I(state=finalize). + - Whether to run the clean procedure in case of O(state=finalize). type: bool default: true keep_releases: type: int description: - - The number of old releases to keep when cleaning. Used in I(finalize) and I(clean). Any unfinished builds + - The number of old releases to keep when cleaning. Used in O(state=finalize) and O(state=clean). Any unfinished builds will be deleted first, so only correct releases will count. The current version will not count. default: 5 notes: - - Facts are only returned for I(state=query) and I(state=present). If you use both, you should pass any overridden + - Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden parameters to both calls, otherwise the second call will overwrite the facts of the first one. - - When using I(state=clean), the releases are ordered by I(creation date). You should be able to switch to a + - When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a new naming strategy without problems. - - Because of the default behaviour of generating the I(new_release) fact, this module will not be idempotent - unless you pass your own release name with I(release). Due to the nature of deploying software, this should not + - Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent + unless you pass your own release name with O(release). Due to the nature of deploying software, this should not be much of a problem. extends_documentation_fragment: - ansible.builtin.files diff --git a/plugins/modules/dimensiondata_network.py b/plugins/modules/dimensiondata_network.py index 8c1469063c..cfb7d61cd9 100644 --- a/plugins/modules/dimensiondata_network.py +++ b/plugins/modules/dimensiondata_network.py @@ -84,7 +84,7 @@ EXAMPLES = ''' RETURN = ''' network: description: Dictionary describing the network. - returned: On success when I(state=present). + returned: On success when O(state=present). type: complex contains: id: diff --git a/plugins/modules/dimensiondata_vlan.py b/plugins/modules/dimensiondata_vlan.py index 7d83ddc696..9d129f3dea 100644 --- a/plugins/modules/dimensiondata_vlan.py +++ b/plugins/modules/dimensiondata_vlan.py @@ -51,20 +51,20 @@ options: private_ipv4_prefix_size: description: - The size of the IPv4 address space, e.g 24. - - Required, if C(private_ipv4_base_address) is specified. + - Required, if O(private_ipv4_base_address) is specified. type: int default: 0 state: description: - The desired state for the target VLAN. - - C(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist). + - V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist). choices: [present, absent, readonly] default: present type: str allow_expand: description: - Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently possesses. - - If C(False), the module will fail under these conditions. + - If V(false), the module will fail under these conditions. - This is intended to prevent accidental expansion of a VLAN's network (since this operation is not reversible). type: bool default: false @@ -105,7 +105,7 @@ EXAMPLES = ''' RETURN = ''' vlan: description: Dictionary describing the VLAN. - returned: On success when I(state) is 'present' + returned: On success when O(state=present) type: complex contains: id: diff --git a/plugins/modules/discord.py b/plugins/modules/discord.py index 8b5391d44b..130649f076 100644 --- a/plugins/modules/discord.py +++ b/plugins/modules/discord.py @@ -43,7 +43,7 @@ options: content: description: - Content of the message to the Discord channel. - - At least one of I(content) and I(embeds) must be specified. + - At least one of O(content) and O(embeds) must be specified. type: str username: description: @@ -55,7 +55,7 @@ options: type: str tts: description: - - Set this to C(true) if this is a TTS (Text to Speech) message. + - Set this to V(true) if this is a TTS (Text to Speech) message. type: bool default: false embeds: @@ -63,7 +63,7 @@ options: - Send messages as Embeds to the Discord channel. - Embeds can have a colored border, embedded images, text fields and more. - "Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object)" - - At least one of I(content) and I(embeds) must be specified. + - At least one of O(content) and O(embeds) must be specified. type: list elements: dict ''' diff --git a/plugins/modules/django_manage.py b/plugins/modules/django_manage.py index 537cf0fa74..e2de1db3e2 100644 --- a/plugins/modules/django_manage.py +++ b/plugins/modules/django_manage.py @@ -16,7 +16,7 @@ module: django_manage short_description: Manages a Django application description: - Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the - I(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation. + O(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation. extends_documentation_fragment: - community.general.attributes attributes: @@ -29,20 +29,20 @@ options: description: - The name of the Django management command to run. The commands listed below are built in this module and have some basic parameter validation. - > - C(cleanup) - clean up old data from the database (deprecated in Django 1.5). This parameter will be - removed in community.general 9.0.0. Use C(clearsessions) instead. - - C(collectstatic) - Collects the static files into C(STATIC_ROOT). - - C(createcachetable) - Creates the cache tables for use with the database cache backend. - - C(flush) - Removes all data from the database. - - C(loaddata) - Searches for and loads the contents of the named I(fixtures) into the database. - - C(migrate) - Synchronizes the database state with models and migrations. + V(cleanup) - clean up old data from the database (deprecated in Django 1.5). This parameter will be + removed in community.general 9.0.0. Use V(clearsessions) instead. + - V(collectstatic) - Collects the static files into C(STATIC_ROOT). + - V(createcachetable) - Creates the cache tables for use with the database cache backend. + - V(flush) - Removes all data from the database. + - V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database. + - V(migrate) - Synchronizes the database state with models and migrations. - > - C(syncdb) - Synchronizes the database state with models and migrations (deprecated in Django 1.7). - This parameter will be removed in community.general 9.0.0. Use C(migrate) instead. - - C(test) - Runs tests for all installed apps. + V(syncdb) - Synchronizes the database state with models and migrations (deprecated in Django 1.7). + This parameter will be removed in community.general 9.0.0. Use V(migrate) instead. + - V(test) - Runs tests for all installed apps. - > - C(validate) - Validates all installed models (deprecated in Django 1.7). This parameter will be - removed in community.general 9.0.0. Use C(check) instead. + V(validate) - Validates all installed models (deprecated in Django 1.7). This parameter will be + removed in community.general 9.0.0. Use V(check) instead. - Other commands can be entered, but will fail if they are unknown to Django. Other commands that may prompt for user input should be run with the C(--noinput) flag. type: str @@ -55,14 +55,14 @@ options: aliases: [app_path, chdir] settings: description: - - The Python path to the application's settings module, such as C(myapp.settings). + - The Python path to the application's settings module, such as V(myapp.settings). type: path required: false pythonpath: description: - A directory to add to the Python path. Typically used to include the settings module if it is located external to the application directory. - - This would be equivalent to adding I(pythonpath)'s value to the C(PYTHONPATH) environment variable. + - This would be equivalent to adding O(pythonpath)'s value to the C(PYTHONPATH) environment variable. type: path required: false aliases: [python_path] @@ -73,54 +73,54 @@ options: aliases: [virtual_env] apps: description: - - A list of space-delimited apps to target. Used by the C(test) command. + - A list of space-delimited apps to target. Used by the V(test) command. type: str required: false cache_table: description: - - The name of the table used for database-backed caching. Used by the C(createcachetable) command. + - The name of the table used for database-backed caching. Used by the V(createcachetable) command. type: str required: false clear: description: - Clear the existing files before trying to copy or link the original file. - - Used only with the C(collectstatic) command. The C(--noinput) argument will be added automatically. + - Used only with the V(collectstatic) command. The C(--noinput) argument will be added automatically. required: false default: false type: bool database: description: - - The database to target. Used by the C(createcachetable), C(flush), C(loaddata), C(syncdb), - and C(migrate) commands. + - The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb), + and V(migrate) commands. type: str required: false failfast: description: - - Fail the command immediately if a test fails. Used by the C(test) command. + - Fail the command immediately if a test fails. Used by the V(test) command. required: false default: false type: bool aliases: [fail_fast] fixtures: description: - - A space-delimited list of fixture file names to load in the database. B(Required) by the C(loaddata) command. + - A space-delimited list of fixture file names to load in the database. B(Required) by the V(loaddata) command. type: str required: false skip: description: - - Will skip over out-of-order missing migrations, you can only use this parameter with C(migrate) command. + - Will skip over out-of-order missing migrations, you can only use this parameter with V(migrate) command. required: false type: bool merge: description: - Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this - parameter with C(migrate) command. + parameter with V(migrate) command. required: false type: bool link: description: - Will create links to the files instead of copying them, you can only use this parameter with - C(collectstatic) command. + V(collectstatic) command. required: false type: bool testrunner: @@ -133,9 +133,9 @@ options: ack_venv_creation_deprecation: description: - >- - When a I(virtualenv) is set but the virtual environment does not exist, the current behavior is + When a O(virtualenv) is set but the virtual environment does not exist, the current behavior is to create a new virtual environment. That behavior is deprecated and if that case happens it will - generate a deprecation warning. Set this flag to C(true) to suppress the deprecation warning. + generate a deprecation warning. Set this flag to V(true) to suppress the deprecation warning. - Please note that you will receive no further warning about this being removed until the module will start failing in such cases from community.general 9.0.0 on. type: bool @@ -146,19 +146,19 @@ notes: B(ATTENTION - DEPRECATION): Support for Django releases older than 4.1 will be removed in community.general version 9.0.0 (estimated to be released in May 2024). Please notice that Django 4.1 requires Python 3.8 or greater. - - C(virtualenv) (U(http://www.virtualenv.org)) must be installed on the remote host if the I(virtualenv) parameter + - C(virtualenv) (U(http://www.virtualenv.org)) must be installed on the remote host if the O(virtualenv) parameter is specified. This requirement is deprecated and will be removed in community.general version 9.0.0. - - This module will create a virtualenv if the I(virtualenv) parameter is specified and a virtual environment does not already + - This module will create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment does not already exist at the given location. This behavior is deprecated and will be removed in community.general version 9.0.0. - - The parameter I(virtualenv) will remain in use, but it will require the specified virtualenv to exist. + - The parameter O(virtualenv) will remain in use, but it will require the specified virtualenv to exist. The recommended way to create one in Ansible is by using M(ansible.builtin.pip). - - This module assumes English error messages for the C(createcachetable) command to detect table existence, + - This module assumes English error messages for the V(createcachetable) command to detect table existence, unfortunately. - - To be able to use the C(migrate) command with django versions < 1.7, you must have C(south) installed and added + - To be able to use the V(migrate) command with django versions < 1.7, you must have C(south) installed and added as an app in your settings. - - To be able to use the C(collectstatic) command, you must have enabled staticfiles in your settings. - - Your C(manage.py) application must be executable (rwxr-xr-x), and must have a valid shebang, - i.e. C(#!/usr/bin/env python), for invoking the appropriate Python interpreter. + - To be able to use the V(collectstatic) command, you must have enabled staticfiles in your settings. + - Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang, + for example C(#!/usr/bin/env python), for invoking the appropriate Python interpreter. seealso: - name: django-admin and manage.py Reference description: Reference for C(django-admin) or C(manage.py) commands. diff --git a/plugins/modules/dnf_versionlock.py b/plugins/modules/dnf_versionlock.py index fac3ad78d4..3fcf132eaf 100644 --- a/plugins/modules/dnf_versionlock.py +++ b/plugins/modules/dnf_versionlock.py @@ -38,7 +38,7 @@ options: description: - Package name spec to add or exclude to or delete from the C(locklist) using the format expected by the C(dnf repoquery) command. - - This parameter is mutually exclusive with I(state=clean). + - This parameter is mutually exclusive with O(state=clean). type: list required: false elements: str @@ -52,19 +52,19 @@ options: default: false state: description: - - Whether to add (C(present) or C(excluded)) to or remove (C(absent) or - C(clean)) from the C(locklist). - - C(present) will add a package name spec to the C(locklist). If there is a + - Whether to add (V(present) or V(excluded)) to or remove (V(absent) or + V(clean)) from the C(locklist). + - V(present) will add a package name spec to the C(locklist). If there is a installed package that matches, then only that version will be added. Otherwise, all available package versions will be added. - - C(excluded) will add a package name spec as excluded to the + - V(excluded) will add a package name spec as excluded to the C(locklist). It means that packages represented by the package name spec will be excluded from transaction operations. All available package versions will be added. - - C(absent) will delete entries in the C(locklist) that match the + - V(absent) will delete entries in the C(locklist) that match the package name spec. - - C(clean) will delete all entries in the C(locklist). This option is - mutually exclusive with C(name). + - V(clean) will delete all entries in the C(locklist). This option is + mutually exclusive with O(name). choices: [ 'absent', 'clean', 'excluded', 'present' ] type: str default: present diff --git a/plugins/modules/dnsimple.py b/plugins/modules/dnsimple.py index df41f73a69..363b645f80 100644 --- a/plugins/modules/dnsimple.py +++ b/plugins/modules/dnsimple.py @@ -32,7 +32,7 @@ options: type: str account_api_token: description: - - Account API token. See I(account_email) for more information. + - Account API token. See O(account_email) for more information. type: str domain: description: @@ -77,7 +77,7 @@ options: solo: description: - Whether the record should be the only one for that record type and record name. - - Only use with C(state) is set to C(present) on a record. + - Only use with O(state) is set to V(present) on a record. type: 'bool' default: false sandbox: diff --git a/plugins/modules/dnsimple_info.py b/plugins/modules/dnsimple_info.py index 796ff8689c..46c2877f73 100644 --- a/plugins/modules/dnsimple_info.py +++ b/plugins/modules/dnsimple_info.py @@ -83,7 +83,7 @@ dnsimple_domain_info: description: Returns a list of dictionaries of all domains associated with the supplied account ID. type: list elements: dict - returned: success when I(name) is not specified + returned: success when O(name) is not specified sample: - account_id: 1234 created_at: '2021-10-16T21:25:42Z' @@ -120,7 +120,7 @@ dnsimple_records_info: description: Returns a list of dictionaries with all records for the domain supplied. type: list elements: dict - returned: success when I(name) is specified, but I(record) is not + returned: success when O(name) is specified, but O(record) is not sample: - content: ns1.dnsimple.com admin.dnsimple.com created_at: '2021-10-16T19:07:34Z' @@ -174,7 +174,7 @@ dnsimple_records_info: type: str dnsimple_record_info: description: Returns a list of dictionaries that match the record supplied. - returned: success when I(name) and I(record) are specified + returned: success when O(name) and O(record) are specified type: list elements: dict sample: diff --git a/plugins/modules/dpkg_divert.py b/plugins/modules/dpkg_divert.py index 4a1651f517..5f0d924fe2 100644 --- a/plugins/modules/dpkg_divert.py +++ b/plugins/modules/dpkg_divert.py @@ -20,13 +20,13 @@ description: - A diversion is for C(dpkg) the knowledge that only a given package (or the local administrator) is allowed to install a file at a given location. Other packages shipping their own version of this file will - be forced to I(divert) it, i.e. to install it at another location. It + be forced to O(divert) it, that is to install it at another location. It allows one to keep changes in a file provided by a debian package by preventing its overwrite at package upgrade. - This module manages diversions of debian packages files using the C(dpkg-divert) commandline tool. It can either create or remove a diversion for a given file, but also update an existing diversion - to modify its I(holder) and/or its I(divert) location. + to modify its O(holder) and/or its O(divert) location. extends_documentation_fragment: - community.general.attributes attributes: @@ -39,14 +39,14 @@ options: description: - The original and absolute path of the file to be diverted or undiverted. This path is unique, i.e. it is not possible to get - two diversions for the same I(path). + two diversions for the same O(path). required: true type: path state: description: - - When I(state=absent), remove the diversion of the specified - I(path); when I(state=present), create the diversion if it does - not exist, or update its package I(holder) or I(divert) location, + - When O(state=absent), remove the diversion of the specified + O(path); when O(state=present), create the diversion if it does + not exist, or update its package O(holder) or O(divert) location, if it already exists. type: str default: present @@ -59,31 +59,31 @@ options: - The actual package does not have to be installed or even to exist for its name to be valid. If not specified, the diversion is hold by 'LOCAL', that is reserved by/for dpkg for local diversions. - - This parameter is ignored when I(state=absent). + - This parameter is ignored when O(state=absent). type: str divert: description: - The location where the versions of file will be diverted. - Default is to add suffix C(.distrib) to the file path. - - This parameter is ignored when I(state=absent). + - This parameter is ignored when O(state=absent). type: path rename: description: - - Actually move the file aside (when I(state=present)) or back (when - I(state=absent)), but only when changing the state of the diversion. + - Actually move the file aside (when O(state=present)) or back (when + O(state=absent)), but only when changing the state of the diversion. This parameter has no effect when attempting to add a diversion that already exists or when removing an unexisting one. - - Unless I(force=true), renaming fails if the destination file already + - Unless O(force=true), renaming fails if the destination file already exists (this lock being a dpkg-divert feature, and bypassing it being a module feature). type: bool default: false force: description: - - When I(rename=true) and I(force=true), renaming is performed even if + - When O(rename=true) and O(force=true), renaming is performed even if the target of the renaming exists, i.e. the existing contents of the file at this location will be lost. - - This parameter is ignored when I(rename=false). + - This parameter is ignored when O(rename=false). type: bool default: false requirements: diff --git a/plugins/modules/easy_install.py b/plugins/modules/easy_install.py index 564493180a..2e8fc2f4f0 100644 --- a/plugins/modules/easy_install.py +++ b/plugins/modules/easy_install.py @@ -14,7 +14,7 @@ DOCUMENTATION = ''' module: easy_install short_description: Installs Python libraries description: - - Installs Python libraries, optionally in a I(virtualenv) + - Installs Python libraries, optionally in a C(virtualenv) extends_documentation_fragment: - community.general.attributes attributes: @@ -26,13 +26,13 @@ options: name: type: str description: - - A Python library name + - A Python library name. required: true virtualenv: type: str description: - - an optional I(virtualenv) directory path to install into. If the - I(virtualenv) does not exist, it is created automatically + - An optional O(virtualenv) directory path to install into. If the + O(virtualenv) does not exist, it is created automatically. virtualenv_site_packages: description: - Whether the virtual environment will inherit packages from the @@ -46,21 +46,21 @@ options: type: str description: - The command to create the virtual environment with. For example - C(pyvenv), C(virtualenv), C(virtualenv2). + V(pyvenv), V(virtualenv), V(virtualenv2). default: virtualenv executable: type: str description: - The explicit executable or a pathname to the executable to be used to run easy_install for a specific version of Python installed in the - system. For example C(easy_install-3.3), if there are both Python 2.7 + system. For example V(easy_install-3.3), if there are both Python 2.7 and 3.3 installations in the system and you want to run easy_install for the Python 3.3 installation. default: easy_install state: type: str description: - - The desired state of the library. C(latest) ensures that the latest version is installed. + - The desired state of the library. V(latest) ensures that the latest version is installed. choices: [present, latest] default: present notes: @@ -68,8 +68,8 @@ notes: libraries. Thus this module is not able to remove libraries. It is generally recommended to use the M(ansible.builtin.pip) module which you can first install using M(community.general.easy_install). - - Also note that I(virtualenv) must be installed on the remote host if the - C(virtualenv) parameter is specified. + - Also note that C(virtualenv) must be installed on the remote host if the + O(virtualenv) parameter is specified. requirements: [ "virtualenv" ] author: "Matt Wright (@mattupstate)" ''' diff --git a/plugins/modules/etcd3.py b/plugins/modules/etcd3.py index 9cd0274068..2fdc3f2f83 100644 --- a/plugins/modules/etcd3.py +++ b/plugins/modules/etcd3.py @@ -61,22 +61,22 @@ options: type: str description: - The password to use for authentication. - - Required if I(user) is defined. + - Required if O(user) is defined. ca_cert: type: path description: - The Certificate Authority to use to verify the etcd host. - - Required if I(client_cert) and I(client_key) are defined. + - Required if O(client_cert) and O(client_key) are defined. client_cert: type: path description: - PEM formatted certificate chain file to be used for SSL client authentication. - - Required if I(client_key) is defined. + - Required if O(client_key) is defined. client_key: type: path description: - PEM formatted file that contains your private key to be used for SSL client authentication. - - Required if I(client_cert) is defined. + - Required if O(client_cert) is defined. timeout: type: int description: diff --git a/plugins/modules/facter.py b/plugins/modules/facter.py index e7cf52e203..87017246ae 100644 --- a/plugins/modules/facter.py +++ b/plugins/modules/facter.py @@ -11,7 +11,7 @@ __metaclass__ = type DOCUMENTATION = ''' --- module: facter -short_description: Runs the discovery program I(facter) on the remote system +short_description: Runs the discovery program C(facter) on the remote system description: - Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning diff --git a/plugins/modules/filesize.py b/plugins/modules/filesize.py index b3eb90d611..83de682883 100644 --- a/plugins/modules/filesize.py +++ b/plugins/modules/filesize.py @@ -41,20 +41,20 @@ options: description: - Requested size of the file. - The value is a number (either C(int) or C(float)) optionally followed - by a multiplicative suffix, that can be one of C(B) (bytes), C(KB) or - C(kB) (= 1000B), C(MB) or C(mB) (= 1000kB), C(GB) or C(gB) (= 1000MB), - and so on for C(T), C(P), C(E), C(Z) and C(Y); or alternatively one of - C(K), C(k) or C(KiB) (= 1024B); C(M), C(m) or C(MiB) (= 1024KiB); - C(G), C(g) or C(GiB) (= 1024MiB); and so on. + by a multiplicative suffix, that can be one of V(B) (bytes), V(KB) or + V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB), + and so on for V(T), V(P), V(E), V(Z) and V(Y); or alternatively one of + V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB); + V(G), V(g) or V(GiB) (= 1024MiB); and so on. - If the multiplicative suffix is not provided, the value is treated as - an integer number of blocks of I(blocksize) bytes each (float values + an integer number of blocks of O(blocksize) bytes each (float values are rounded to the closest integer). - - When the I(size) value is equal to the current file size, does nothing. - - When the I(size) value is bigger than the current file size, bytes from - I(source) (if I(sparse) is not C(false)) are appended to the file + - When the O(size) value is equal to the current file size, does nothing. + - When the O(size) value is bigger than the current file size, bytes from + O(source) (if O(sparse) is not V(false)) are appended to the file without truncating it, in other words, without modifying the existing bytes of the file. - - When the I(size) value is smaller than the current file size, it is + - When the O(size) value is smaller than the current file size, it is truncated to the requested value without modifying bytes before this value. - That means that a file of any arbitrary size can be grown to any other @@ -65,24 +65,24 @@ options: blocksize: description: - Size of blocks, in bytes if not followed by a multiplicative suffix. - - The numeric value (before the unit) C(MUST) be an integer (or a C(float) + - The numeric value (before the unit) B(MUST) be an integer (or a C(float) if it equals an integer). - If not set, the size of blocks is guessed from the OS and commonly - results in C(512) or C(4096) bytes, that is used internally by the - module or when I(size) has no unit. + results in V(512) or V(4096) bytes, that is used internally by the + module or when O(size) has no unit. type: raw source: description: - Device or file that provides input data to provision the file. - - This parameter is ignored when I(sparse=true). + - This parameter is ignored when O(sparse=true). type: path default: /dev/zero force: description: - Whether or not to overwrite the file if it exists, in other words, to - truncate it from 0. When C(true), the module is not idempotent, that - means it always reports I(changed=true). - - I(force=true) and I(sparse=true) are mutually exclusive. + truncate it from 0. When V(true), the module is not idempotent, that + means it always reports C(changed=true). + - O(force=true) and O(sparse=true) are mutually exclusive. type: bool default: false sparse: @@ -91,7 +91,7 @@ options: - This option is effective only on newly created files, or when growing a file, only for the bytes to append. - This option is not supported on OSes or filesystems not supporting sparse files. - - I(force=true) and I(sparse=true) are mutually exclusive. + - O(force=true) and O(sparse=true) are mutually exclusive. type: bool default: false unsafe_writes: @@ -206,7 +206,7 @@ filesize: type: int sample: 1024 bytes: - description: Size of the file, in bytes, as the product of C(blocks) and C(blocksize). + description: Size of the file, in bytes, as the product of RV(filesize.blocks) and RV(filesize.blocksize). type: int sample: 512000 iec: diff --git a/plugins/modules/filesystem.py b/plugins/modules/filesystem.py index 0e6b815b4e..a336818abf 100644 --- a/plugins/modules/filesystem.py +++ b/plugins/modules/filesystem.py @@ -29,12 +29,12 @@ attributes: options: state: description: - - If I(state=present), the filesystem is created if it doesn't already - exist, that is the default behaviour if I(state) is omitted. - - If I(state=absent), filesystem signatures on I(dev) are wiped if it + - If O(state=present), the filesystem is created if it doesn't already + exist, that is the default behaviour if O(state) is omitted. + - If O(state=absent), filesystem signatures on O(dev) are wiped if it contains a filesystem (as known by C(blkid)). - - When I(state=absent), all other options but I(dev) are ignored, and the - module doesn't fail if the device I(dev) doesn't actually exist. + - When O(state=absent), all other options but O(dev) are ignored, and the + module does not fail if the device O(dev) doesn't actually exist. type: str choices: [ present, absent ] default: present @@ -43,7 +43,7 @@ options: choices: [ btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs ] description: - Filesystem type to be created. This option is required with - I(state=present) (or if I(state) is omitted). + O(state=present) (or if O(state) is omitted). - ufs support has been added in community.general 3.4.0. type: str aliases: [type] @@ -53,20 +53,20 @@ options: regular file (both). - When setting Linux-specific filesystem types on FreeBSD, this module only works when applying to regular files, aka disk images. - - Currently C(lvm) (Linux-only) and C(ufs) (FreeBSD-only) don't support - a regular file as their target I(dev). + - Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support + a regular file as their target O(dev). - Support for character devices on FreeBSD has been added in community.general 3.4.0. type: path required: true aliases: [device] force: description: - - If C(true), allows to create new filesystem on devices that already has filesystem. + - If V(true), allows to create new filesystem on devices that already has filesystem. type: bool default: false resizefs: description: - - If C(true), if the block device and filesystem size differ, grow the filesystem into the space. + - If V(true), if the block device and filesystem size differ, grow the filesystem into the space. - Supported for C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat) filesystems. Attempts to resize other filesystem types will fail. - XFS Will only grow if mounted. Currently, the module is based on commands @@ -80,20 +80,20 @@ options: - List of options to be passed to C(mkfs) command. type: str requirements: - - Uses specific tools related to the I(fstype) for creating or resizing a + - Uses specific tools related to the O(fstype) for creating or resizing a filesystem (from packages e2fsprogs, xfsprogs, dosfstools, and so on). - Uses generic tools mostly related to the Operating System (Linux or FreeBSD) or available on both, as C(blkid). - On FreeBSD, either C(util-linux) or C(e2fsprogs) package is required. notes: - - Potential filesystems on I(dev) are checked using C(blkid). In case C(blkid) + - Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid) is unable to detect a filesystem (and in case C(fstyp) on FreeBSD is also unable to detect a filesystem), this filesystem is overwritten even if - I(force) is C(false). + O(force) is V(false). - On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide a C(blkid) command that is compatible with this module. However, these packages conflict with each other, and only the C(util-linux) package - provides the command required to not fail when I(state=absent). + provides the command required to not fail when O(state=absent). seealso: - module: community.general.filesize - module: ansible.posix.mount diff --git a/plugins/modules/flatpak.py b/plugins/modules/flatpak.py index 40a13736f0..80dbabdfa0 100644 --- a/plugins/modules/flatpak.py +++ b/plugins/modules/flatpak.py @@ -39,8 +39,8 @@ options: method: description: - The installation method to use. - - Defines if the I(flatpak) is supposed to be installed globally for the whole C(system) - or only for the current C(user). + - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) + or only for the current V(user). type: str choices: [ system, user ] default: system @@ -48,14 +48,14 @@ options: description: - The name of the flatpak to manage. To operate on several packages this can accept a list of packages. - - When used with I(state=present), I(name) can be specified as a URL to a + - When used with O(state=present), O(name) can be specified as a URL to a C(flatpakref) file or the unique reverse DNS name that identifies a flatpak. - Both C(https://) and C(http://) URLs are supported. - - When supplying a reverse DNS name, you can use the I(remote) option to specify on what remote + - When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote to look for the flatpak. An example for a reverse DNS name is C(org.gnome.gedit). - - When used with I(state=absent), it is recommended to specify the name in the reverse DNS + - When used with O(state=absent), it is recommended to specify the name in the reverse DNS format. - - When supplying a URL with I(state=absent), the module will try to match the + - When supplying a URL with O(state=absent), the module will try to match the installed flatpak based on the name of the flatpakref to remove it. However, there is no guarantee that the names of the flatpakref file and the reverse DNS name of the installed flatpak do match. @@ -74,7 +74,7 @@ options: remote: description: - The flatpak remote (repository) to install the flatpak from. - - By default, C(flathub) is assumed, but you do need to add the flathub flatpak_remote before + - By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before you can use this. - See the M(community.general.flatpak_remote) module for managing flatpak remotes. type: str diff --git a/plugins/modules/flatpak_remote.py b/plugins/modules/flatpak_remote.py index 9c097c411f..a4eb3ea27c 100644 --- a/plugins/modules/flatpak_remote.py +++ b/plugins/modules/flatpak_remote.py @@ -18,7 +18,7 @@ description: - Allows users to add or remove flatpak remotes. - The flatpak remotes concept is comparable to what is called repositories in other packaging formats. - - Currently, remote addition is only supported via I(flatpakrepo) file URLs. + - Currently, remote addition is only supported via C(flatpakrepo) file URLs. - Existing remotes will not be updated. - See the M(community.general.flatpak) module for managing flatpaks. author: @@ -42,26 +42,26 @@ options: default: flatpak flatpakrepo_url: description: - - The URL to the I(flatpakrepo) file representing the repository remote to add. - - When used with I(state=present), the flatpak remote specified under the I(flatpakrepo_url) - is added using the specified installation C(method). - - When used with I(state=absent), this is not required. - - Required when I(state=present). + - The URL to the C(flatpakrepo) file representing the repository remote to add. + - When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url) + is added using the specified installation O(method). + - When used with O(state=absent), this is not required. + - Required when O(state=present). type: str method: description: - The installation method to use. - - Defines if the I(flatpak) is supposed to be installed globally for the whole C(system) - or only for the current C(user). + - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) + or only for the current V(user). type: str choices: [ system, user ] default: system name: description: - The desired name for the flatpak remote to be registered under on the managed host. - - When used with I(state=present), the remote will be added to the managed host under - the specified I(name). - - When used with I(state=absent) the remote with that name will be removed. + - When used with O(state=present), the remote will be added to the managed host under + the specified O(name). + - When used with O(state=absent) the remote with that name will be removed. type: str required: true state: diff --git a/plugins/modules/gandi_livedns.py b/plugins/modules/gandi_livedns.py index cc9dd630b4..fdb7993a5e 100644 --- a/plugins/modules/gandi_livedns.py +++ b/plugins/modules/gandi_livedns.py @@ -44,7 +44,7 @@ options: ttl: description: - The TTL to give the new record. - - Required when I(state=present). + - Required when O(state=present). type: int type: description: @@ -54,7 +54,7 @@ options: values: description: - The record values. - - Required when I(state=present). + - Required when O(state=present). type: list elements: str domain: diff --git a/plugins/modules/gconftool2.py b/plugins/modules/gconftool2.py index 704bfb18d9..3dd46c3695 100644 --- a/plugins/modules/gconftool2.py +++ b/plugins/modules/gconftool2.py @@ -36,18 +36,18 @@ options: description: - Preference keys typically have simple values such as strings, integers, or lists of strings and integers. - This is ignored unless I(state=present). See man gconftool-2(1). + This is ignored unless O(state=present). See man gconftool-2(1). value_type: type: str description: - The type of value being set. - This is ignored unless I(state=present). See man gconftool-2(1). + This is ignored unless O(state=present). See man gconftool-2(1). choices: [ bool, float, int, string ] state: type: str description: - The action to take upon the key/value. - - State C(get) is deprecated and will be removed in community.general 8.0.0. Please use the module M(community.general.gconftool2_info) instead. + - State V(get) is deprecated and will be removed in community.general 8.0.0. Please use the module M(community.general.gconftool2_info) instead. required: true choices: [ absent, get, present ] config_source: @@ -57,8 +57,8 @@ options: See man gconftool-2(1). direct: description: - - Access the config database directly, bypassing server. If I(direct) is - specified then the I(config_source) must be specified as well. + - Access the config database directly, bypassing server. If O(direct) is + specified then the O(config_source) must be specified as well. See man gconftool-2(1). type: bool default: false @@ -85,15 +85,15 @@ RETURN = ''' sample: string value: description: - - The value of the preference key after executing the module or C(null) if key is removed. - - From community.general 7.0.0 onwards it returns C(null) for a non-existent I(key), and returns C("") before that. + - The value of the preference key after executing the module or V(null) if key is removed. + - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that. returned: success type: str sample: "Serif 12" previous_value: description: - The value of the preference key before executing the module. - - From community.general 7.0.0 onwards it returns C(null) for a non-existent I(key), and returns C("") before that. + - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that. returned: success type: str sample: "Serif 12" diff --git a/plugins/modules/git_config.py b/plugins/modules/git_config.py index d673121748..2c6a679f3f 100644 --- a/plugins/modules/git_config.py +++ b/plugins/modules/git_config.py @@ -20,7 +20,7 @@ author: requirements: ['git'] short_description: Read and write git configuration description: - - The C(git_config) module changes git configuration by invoking 'git config'. + - The M(community.general.git_config) module changes git configuration by invoking 'git config'. This is needed if you do not want to use M(ansible.builtin.template) for the entire git config file (for example because you need to change just C(user.email) in /etc/.git/config). Solutions involving M(ansible.builtin.command) are cumbersome or @@ -35,7 +35,7 @@ attributes: options: list_all: description: - - List all settings (optionally limited to a given I(scope)). + - List all settings (optionally limited to a given O(scope)). type: bool default: false name: @@ -50,23 +50,23 @@ options: type: path file: description: - - Path to an adhoc git configuration file to be managed using the C(file) scope. + - Path to an adhoc git configuration file to be managed using the V(file) scope. type: path version_added: 2.0.0 scope: description: - Specify which scope to read/set values from. - This is required when setting config values. - - If this is set to C(local), you must also specify the C(repo) parameter. - - If this is set to C(file), you must also specify the C(file) parameter. - - It defaults to system only when not using I(list_all)=C(true). + - If this is set to V(local), you must also specify the O(repo) parameter. + - If this is set to V(file), you must also specify the O(file) parameter. + - It defaults to system only when not using O(list_all=true). choices: [ "file", "local", "global", "system" ] type: str state: description: - "Indicates the setting should be set/unset. - This parameter has higher precedence than I(value) parameter: - when I(state)=absent and I(value) is defined, I(value) is discarded." + This parameter has higher precedence than O(value) parameter: + when O(state=absent) and O(value) is defined, O(value) is discarded." choices: [ 'present', 'absent' ] default: 'present' type: str @@ -152,13 +152,13 @@ EXAMPLES = ''' RETURN = ''' --- config_value: - description: When I(list_all=false) and value is not set, a string containing the value of the setting in name + description: When O(list_all=false) and value is not set, a string containing the value of the setting in name returned: success type: str sample: "vim" config_values: - description: When I(list_all=true), a dict containing key/value pairs of multiple configuration settings + description: When O(list_all=true), a dict containing key/value pairs of multiple configuration settings returned: success type: dict sample: diff --git a/plugins/modules/github_deploy_key.py b/plugins/modules/github_deploy_key.py index 322650bf70..b65f635801 100644 --- a/plugins/modules/github_deploy_key.py +++ b/plugins/modules/github_deploy_key.py @@ -58,7 +58,7 @@ options: type: str read_only: description: - - If C(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write. + - If V(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write. type: bool default: true state: @@ -69,7 +69,7 @@ options: type: str force: description: - - If C(true), forcefully adds the deploy key by deleting any existing deploy key with the same public key or title. + - If V(true), forcefully adds the deploy key by deleting any existing deploy key with the same public key or title. type: bool default: false username: @@ -78,15 +78,15 @@ options: type: str password: description: - - The password to authenticate with. Alternatively, a personal access token can be used instead of I(username) and I(password) combination. + - The password to authenticate with. Alternatively, a personal access token can be used instead of O(username) and O(password) combination. type: str token: description: - - The OAuth2 token or personal access token to authenticate with. Mutually exclusive with I(password). + - The OAuth2 token or personal access token to authenticate with. Mutually exclusive with O(password). type: str otp: description: - - The 6 digit One Time Password for 2-Factor Authentication. Required together with I(username) and I(password). + - The 6 digit One Time Password for 2-Factor Authentication. Required together with O(username) and O(password). type: int notes: - "Refer to GitHub's API documentation here: https://developer.github.com/v3/repos/keys/." diff --git a/plugins/modules/github_key.py b/plugins/modules/github_key.py index 683a963a7f..17523eb89f 100644 --- a/plugins/modules/github_key.py +++ b/plugins/modules/github_key.py @@ -34,7 +34,7 @@ options: type: str pubkey: description: - - SSH public key value. Required when I(state=present). + - SSH public key value. Required when O(state=present). type: str state: description: @@ -44,9 +44,9 @@ options: type: str force: description: - - The default is C(true), which will replace the existing remote key - if it's different than C(pubkey). If C(false), the key will only be - set if no key with the given I(name) exists. + - The default is V(true), which will replace the existing remote key + if it is different than O(pubkey). If V(false), the key will only be + set if no key with the given O(name) exists. type: bool default: true diff --git a/plugins/modules/github_repo.py b/plugins/modules/github_repo.py index 97076c58af..f02ad30ac3 100644 --- a/plugins/modules/github_repo.py +++ b/plugins/modules/github_repo.py @@ -15,7 +15,7 @@ short_description: Manage your repositories on Github version_added: 2.2.0 description: - Manages Github repositories using PyGithub library. - - Authentication can be done with I(access_token) or with I(username) and I(password). + - Authentication can be done with O(access_token) or with O(username) and O(password). extends_documentation_fragment: - community.general.attributes attributes: @@ -27,19 +27,19 @@ options: username: description: - Username used for authentication. - - This is only needed when not using I(access_token). + - This is only needed when not using O(access_token). type: str required: false password: description: - Password used for authentication. - - This is only needed when not using I(access_token). + - This is only needed when not using O(access_token). type: str required: false access_token: description: - Token parameter for authentication. - - This is only needed when not using I(username) and I(password). + - This is only needed when not using O(username) and O(password). type: str required: false name: @@ -50,17 +50,17 @@ options: description: description: - Description for the repository. - - Defaults to empty if I(force_defaults=true), which is the default in this module. - - Defaults to empty if I(force_defaults=false) when creating a new repository. - - This is only used when I(state) is C(present). + - Defaults to empty if O(force_defaults=true), which is the default in this module. + - Defaults to empty if O(force_defaults=false) when creating a new repository. + - This is only used when O(state) is V(present). type: str required: false private: description: - Whether the repository should be private or not. - - Defaults to C(false) if I(force_defaults=true), which is the default in this module. - - Defaults to C(false) if I(force_defaults=false) when creating a new repository. - - This is only used when I(state) is C(present). + - Defaults to V(false) if O(force_defaults=true), which is the default in this module. + - Defaults to V(false) if O(force_defaults=false) when creating a new repository. + - This is only used when O(state=present). type: bool required: false state: @@ -73,7 +73,7 @@ options: organization: description: - Organization for the repository. - - When I(state) is C(present), the repository will be created in the current user profile. + - When O(state=present), the repository will be created in the current user profile. type: str required: false api_url: @@ -84,8 +84,8 @@ options: version_added: "3.5.0" force_defaults: description: - - Overwrite current I(description) and I(private) attributes with defaults if set to C(true), which currently is the default. - - The default for this option will be deprecated in a future version of this collection, and eventually change to C(false). + - Overwrite current O(description) and O(private) attributes with defaults if set to V(true), which currently is the default. + - The default for this option will be deprecated in a future version of this collection, and eventually change to V(false). type: bool default: true required: false @@ -125,7 +125,7 @@ EXAMPLES = ''' RETURN = ''' repo: description: Repository information as JSON. See U(https://docs.github.com/en/rest/reference/repos#get-a-repository). - returned: success and I(state) is C(present) + returned: success and O(state=present) type: dict ''' diff --git a/plugins/modules/gitlab_branch.py b/plugins/modules/gitlab_branch.py index d7eecb33fb..c83f21af32 100644 --- a/plugins/modules/gitlab_branch.py +++ b/plugins/modules/gitlab_branch.py @@ -49,7 +49,7 @@ options: ref_branch: description: - Reference branch to create from. - - This must be specified if I(state=present). + - This must be specified if O(state=present). type: str ''' diff --git a/plugins/modules/gitlab_group_members.py b/plugins/modules/gitlab_group_members.py index 66298e882c..8f8b23e0c0 100644 --- a/plugins/modules/gitlab_group_members.py +++ b/plugins/modules/gitlab_group_members.py @@ -40,22 +40,22 @@ options: gitlab_user: description: - A username or a list of usernames to add to/remove from the GitLab group. - - Mutually exclusive with I(gitlab_users_access). + - Mutually exclusive with O(gitlab_users_access). type: list elements: str access_level: description: - The access level for the user. - - Required if I(state=present), user state is set to present. - - Mutually exclusive with I(gitlab_users_access). + - Required if O(state=present), user state is set to present. + - Mutually exclusive with O(gitlab_users_access). type: str choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] gitlab_users_access: description: - Provide a list of user to access level mappings. - Every dictionary in this list specifies a user (by username) and the access level the user should have. - - Mutually exclusive with I(gitlab_user) and I(access_level). - - Use together with I(purge_users) to remove all users not specified here from the group. + - Mutually exclusive with O(gitlab_user) and O(access_level). + - Use together with O(purge_users) to remove all users not specified here from the group. type: list elements: dict suboptions: @@ -66,7 +66,7 @@ options: access_level: description: - The access level for the user. - - Required if I(state=present), user state is set to present. + - Required if O(state=present), user state is set to present. type: str choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] required: true @@ -74,16 +74,16 @@ options: state: description: - State of the member in the group. - - On C(present), it adds a user to a GitLab group. - - On C(absent), it removes a user from a GitLab group. + - On V(present), it adds a user to a GitLab group. + - On V(absent), it removes a user from a GitLab group. choices: ['present', 'absent'] default: 'present' type: str purge_users: description: - - Adds/remove users of the given access_level to match the given I(gitlab_user)/I(gitlab_users_access) list. + - Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list. If omitted do not purge orphaned members. - - Is only used when I(state=present). + - Is only used when O(state=present). type: list elements: str choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] diff --git a/plugins/modules/gitlab_group_variable.py b/plugins/modules/gitlab_group_variable.py index 1a3a0c3c2a..2bba2768f4 100644 --- a/plugins/modules/gitlab_group_variable.py +++ b/plugins/modules/gitlab_group_variable.py @@ -17,7 +17,7 @@ description: - Creates a group variable if it does not exist. - When a group variable does exist, its value will be updated when the values are different. - Variables which are untouched in the playbook, but are not untouched in the GitLab group, - they stay untouched (I(purge) is C(false)) or will be deleted (I(purge) is C(true)). + they stay untouched (O(purge=false)) or will be deleted (O(purge=true)). author: - Florent Madiot (@scodeman) requirements: @@ -48,20 +48,20 @@ options: type: str purge: description: - - When set to C(true), delete all variables which are not untouched in the task. + - When set to V(true), delete all variables which are not untouched in the task. default: false type: bool vars: description: - When the list element is a simple key-value pair, set masked and protected to false. - - When the list element is a dict with the keys I(value), I(masked) and I(protected), the user can + - When the list element is a dict with the keys C(value), C(masked) and C(protected), the user can have full control about whether a value should be masked, protected or both. - Support for group variables requires GitLab >= 9.5. - Support for environment_scope requires GitLab Premium >= 13.11. - Support for protected values requires GitLab >= 9.3. - Support for masked values requires GitLab >= 11.10. - - A I(value) must be a string or a number. - - Field I(variable_type) must be a string with either C(env_var), which is the default, or C(file). + - A C(value) must be a string or a number. + - Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file). - When a value is masked, it must be in Base64 and have a length of at least 8 characters. See GitLab documentation on acceptable values for a masked variable (U(https://docs.gitlab.com/ce/ci/variables/#masked-variables)). default: {} @@ -70,7 +70,7 @@ options: version_added: 4.5.0 description: - A list of dictionaries that represents CI/CD variables. - - This modules works internal with this sructure, even if the older I(vars) parameter is used. + - This modules works internal with this sructure, even if the older O(vars) parameter is used. default: [] type: list elements: dict @@ -83,7 +83,7 @@ options: value: description: - The variable value. - - Required when I(state=present). + - Required when O(state=present). type: str masked: description: @@ -97,7 +97,7 @@ options: default: false variable_type: description: - - Wether a variable is an environment variable (C(env_var)) or a file (C(file)). + - Wether a variable is an environment variable (V(env_var)) or a file (V(file)). type: str choices: [ "env_var", "file" ] default: env_var diff --git a/plugins/modules/gitlab_instance_variable.py b/plugins/modules/gitlab_instance_variable.py index 9b5db36883..0217a1484d 100644 --- a/plugins/modules/gitlab_instance_variable.py +++ b/plugins/modules/gitlab_instance_variable.py @@ -19,7 +19,7 @@ description: - When a instance variable does exist, its value will be updated if the values are different. - Support for instance variables requires GitLab >= 13.0. - Variables which are not mentioned in the modules options, but are present on the GitLab instance, - will either stay (I(purge=false)) or will be deleted (I(purge=true)). + will either stay (O(purge=false)) or will be deleted (O(purge=true)). author: - Benedikt Braunger (@benibr) requirements: @@ -45,7 +45,7 @@ options: choices: ["present", "absent"] purge: description: - - When set to C(true), delete all variables which are not mentioned in the task. + - When set to V(true), delete all variables which are not mentioned in the task. default: false type: bool variables: @@ -63,7 +63,7 @@ options: value: description: - The variable value. - - Required when I(state=present). + - Required when O(state=present). type: str masked: description: @@ -77,7 +77,7 @@ options: default: false variable_type: description: - - Wether a variable is an environment variable (C(env_var)) or a file (C(file)). + - Wether a variable is an environment variable (V(env_var)) or a file (V(file)). type: str choices: [ "env_var", "file" ] default: env_var diff --git a/plugins/modules/gitlab_project.py b/plugins/modules/gitlab_project.py index db360d5789..b10a062577 100644 --- a/plugins/modules/gitlab_project.py +++ b/plugins/modules/gitlab_project.py @@ -15,7 +15,7 @@ module: gitlab_project short_description: Creates/updates/deletes GitLab Projects description: - When the project does not exist in GitLab, it will be created. - - When the project does exists and I(state=absent), the project will be deleted. + - When the project does exists and O(state=absent), the project will be deleted. - When changes are made to the project, the project will be updated. author: - Werner Dijkerman (@dj-wasabi) @@ -84,9 +84,9 @@ options: default: true visibility: description: - - C(private) Project access must be granted explicitly for each user. - - C(internal) The project can be cloned by any logged in user. - - C(public) The project can be cloned without any authentication. + - V(private) Project access must be granted explicitly for each user. + - V(internal) The project can be cloned by any logged in user. + - V(public) The project can be cloned without any authentication. default: private type: str choices: ["private", "internal", "public"] @@ -108,7 +108,7 @@ options: merge_method: description: - What requirements are placed upon merges. - - Possible values are C(merge), C(rebase_merge) merge commit with semi-linear history, C(ff) fast-forward merges only. + - Possible values are V(merge), V(rebase_merge) merge commit with semi-linear history, V(ff) fast-forward merges only. type: str choices: ["ff", "merge", "rebase_merge"] default: merge @@ -176,78 +176,78 @@ options: default_branch: description: - Default branch name for a new project. - - This option is only used on creation, not for updates. This is also only used if I(initialize_with_readme=true). + - This option is only used on creation, not for updates. This is also only used if O(initialize_with_readme=true). type: str version_added: "4.2.0" builds_access_level: description: - - C(private) means that repository CI/CD is allowed only to project members. - - C(disabled) means that repository CI/CD is disabled. - - C(enabled) means that repository CI/CD is enabled. + - V(private) means that repository CI/CD is allowed only to project members. + - V(disabled) means that repository CI/CD is disabled. + - V(enabled) means that repository CI/CD is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.2.0" forking_access_level: description: - - C(private) means that repository forks is allowed only to project members. - - C(disabled) means that repository forks are disabled. - - C(enabled) means that repository forks are enabled. + - V(private) means that repository forks is allowed only to project members. + - V(disabled) means that repository forks are disabled. + - V(enabled) means that repository forks are enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.2.0" container_registry_access_level: description: - - C(private) means that container registry is allowed only to project members. - - C(disabled) means that container registry is disabled. - - C(enabled) means that container registry is enabled. + - V(private) means that container registry is allowed only to project members. + - V(disabled) means that container registry is disabled. + - V(enabled) means that container registry is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.2.0" releases_access_level: description: - - C(private) means that accessing release is allowed only to project members. - - C(disabled) means that accessing release is disabled. - - C(enabled) means that accessing release is enabled. + - V(private) means that accessing release is allowed only to project members. + - V(disabled) means that accessing release is disabled. + - V(enabled) means that accessing release is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" environments_access_level: description: - - C(private) means that deployment to environment is allowed only to project members. - - C(disabled) means that deployment to environment is disabled. - - C(enabled) means that deployment to environment is enabled. + - V(private) means that deployment to environment is allowed only to project members. + - V(disabled) means that deployment to environment is disabled. + - V(enabled) means that deployment to environment is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" feature_flags_access_level: description: - - C(private) means that feature rollout is allowed only to project members. - - C(disabled) means that feature rollout is disabled. - - C(enabled) means that feature rollout is enabled. + - V(private) means that feature rollout is allowed only to project members. + - V(disabled) means that feature rollout is disabled. + - V(enabled) means that feature rollout is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" infrastructure_access_level: description: - - C(private) means that configuring infrastructure is allowed only to project members. - - C(disabled) means that configuring infrastructure is disabled. - - C(enabled) means that configuring infrastructure is enabled. + - V(private) means that configuring infrastructure is allowed only to project members. + - V(disabled) means that configuring infrastructure is disabled. + - V(enabled) means that configuring infrastructure is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" monitor_access_level: description: - - C(private) means that monitoring health is allowed only to project members. - - C(disabled) means that monitoring health is disabled. - - C(enabled) means that monitoring health is enabled. + - V(private) means that monitoring health is allowed only to project members. + - V(disabled) means that monitoring health is disabled. + - V(enabled) means that monitoring health is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" security_and_compliance_access_level: description: - - C(private) means that accessing security and complicance tab is allowed only to project members. - - C(disabled) means that accessing security and complicance tab is disabled. - - C(enabled) means that accessing security and complicance tab is enabled. + - V(private) means that accessing security and complicance tab is allowed only to project members. + - V(disabled) means that accessing security and complicance tab is disabled. + - V(enabled) means that accessing security and complicance tab is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" diff --git a/plugins/modules/gitlab_project_badge.py b/plugins/modules/gitlab_project_badge.py index 5b1a8d3f1c..917534a9b8 100644 --- a/plugins/modules/gitlab_project_badge.py +++ b/plugins/modules/gitlab_project_badge.py @@ -39,8 +39,8 @@ options: state: description: - State of the badge in the project. - - On C(present), it adds a badge to a GitLab project. - - On C(absent), it removes a badge from a GitLab project. + - On V(present), it adds a badge to a GitLab project. + - On V(absent), it removes a badge from a GitLab project. choices: ['present', 'absent'] default: 'present' type: str @@ -82,7 +82,7 @@ EXAMPLES = r''' RETURN = ''' badge: description: The badge information. - returned: when I(state=present) + returned: when O(state=present) type: dict sample: id: 1 diff --git a/plugins/modules/gitlab_project_members.py b/plugins/modules/gitlab_project_members.py index 9053584431..177bec072d 100644 --- a/plugins/modules/gitlab_project_members.py +++ b/plugins/modules/gitlab_project_members.py @@ -42,21 +42,21 @@ options: gitlab_user: description: - A username or a list of usernames to add to/remove from the GitLab project. - - Mutually exclusive with I(gitlab_users_access). + - Mutually exclusive with O(gitlab_users_access). type: list elements: str access_level: description: - The access level for the user. - - Required if I(state=present), user state is set to present. + - Required if O(state=present), user state is set to present. type: str choices: ['guest', 'reporter', 'developer', 'maintainer'] gitlab_users_access: description: - Provide a list of user to access level mappings. - Every dictionary in this list specifies a user (by username) and the access level the user should have. - - Mutually exclusive with I(gitlab_user) and I(access_level). - - Use together with I(purge_users) to remove all users not specified here from the project. + - Mutually exclusive with O(gitlab_user) and O(access_level). + - Use together with O(purge_users) to remove all users not specified here from the project. type: list elements: dict suboptions: @@ -67,7 +67,7 @@ options: access_level: description: - The access level for the user. - - Required if I(state=present), user state is set to present. + - Required if O(state=present), user state is set to present. type: str choices: ['guest', 'reporter', 'developer', 'maintainer'] required: true @@ -75,16 +75,16 @@ options: state: description: - State of the member in the project. - - On C(present), it adds a user to a GitLab project. - - On C(absent), it removes a user from a GitLab project. + - On V(present), it adds a user to a GitLab project. + - On V(absent), it removes a user from a GitLab project. choices: ['present', 'absent'] default: 'present' type: str purge_users: description: - - Adds/remove users of the given access_level to match the given I(gitlab_user)/I(gitlab_users_access) list. + - Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list. If omitted do not purge orphaned members. - - Is only used when I(state=present). + - Is only used when O(state=present). type: list elements: str choices: ['guest', 'reporter', 'developer', 'maintainer'] diff --git a/plugins/modules/gitlab_project_variable.py b/plugins/modules/gitlab_project_variable.py index 7287358a32..6423754e1d 100644 --- a/plugins/modules/gitlab_project_variable.py +++ b/plugins/modules/gitlab_project_variable.py @@ -14,7 +14,7 @@ description: - When a project variable does not exist, it will be created. - When a project variable does exist, its value will be updated when the values are different. - Variables which are untouched in the playbook, but are not untouched in the GitLab project, - they stay untouched (I(purge) is C(false)) or will be deleted (I(purge) is C(true)). + they stay untouched (O(purge=false)) or will be deleted (O(purge=true)). author: - "Markus Bergholz (@markuman)" requirements: @@ -52,15 +52,15 @@ options: vars: description: - When the list element is a simple key-value pair, masked and protected will be set to false. - - When the list element is a dict with the keys I(value), I(masked) and I(protected), the user can + - When the list element is a dict with the keys C(value), C(masked) and C(protected), the user can have full control about whether a value should be masked, protected or both. - Support for protected values requires GitLab >= 9.3. - Support for masked values requires GitLab >= 11.10. - Support for environment_scope requires GitLab Premium >= 13.11. - Support for variable_type requires GitLab >= 11.11. - - A I(value) must be a string or a number. - - Field I(variable_type) must be a string with either C(env_var), which is the default, or C(file). - - Field I(environment_scope) must be a string defined by scope environment. + - A C(value) must be a string or a number. + - Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file). + - Field C(environment_scope) must be a string defined by scope environment. - When a value is masked, it must be in Base64 and have a length of at least 8 characters. See GitLab documentation on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables). default: {} @@ -69,7 +69,7 @@ options: version_added: 4.4.0 description: - A list of dictionaries that represents CI/CD variables. - - This module works internal with this structure, even if the older I(vars) parameter is used. + - This module works internal with this structure, even if the older O(vars) parameter is used. default: [] type: list elements: dict @@ -82,7 +82,7 @@ options: value: description: - The variable value. - - Required when I(state=present). + - Required when O(state=present). type: str masked: description: @@ -98,15 +98,15 @@ options: default: false variable_type: description: - - Wether a variable is an environment variable (C(env_var)) or a file (C(file)). - - Support for I(variable_type) requires GitLab >= 11.11. + - Wether a variable is an environment variable (V(env_var)) or a file (V(file)). + - Support for O(variables[].variable_type) requires GitLab >= 11.11. type: str choices: ["env_var", "file"] default: env_var environment_scope: description: - The scope for the variable. - - Support for I(environment_scope) requires GitLab Premium >= 13.11. + - Support for O(variables[].environment_scope) requires GitLab Premium >= 13.11. type: str default: '*' ''' diff --git a/plugins/modules/gitlab_runner.py b/plugins/modules/gitlab_runner.py index 50f3b3f524..2bfb3bf3d7 100644 --- a/plugins/modules/gitlab_runner.py +++ b/plugins/modules/gitlab_runner.py @@ -24,7 +24,7 @@ description: To create shared runners, you need to ask your administrator to give you this token. It can be found at U(https://$GITLAB_URL/admin/runners/). notes: - - To create a new runner at least the C(api_token), C(description) and C(api_url) options are required. + - To create a new runner at least the O(api_token), O(description) and O(api_url) options are required. - Runners need to have unique descriptions. author: - Samy Coenen (@SamyCoenen) @@ -47,14 +47,14 @@ options: group: description: - ID or full path of the group in the form group/subgroup. - - Mutually exclusive with I(owned) and I(project). + - Mutually exclusive with O(owned) and O(project). type: str version_added: '6.5.0' project: description: - ID or full path of the project in the form of group/name. - - Mutually exclusive with I(owned) since community.general 4.5.0. - - Mutually exclusive with I(group). + - Mutually exclusive with O(owned) since community.general 4.5.0. + - Mutually exclusive with O(group). type: str version_added: '3.7.0' description: @@ -74,13 +74,13 @@ options: registration_token: description: - The registration token is used to register new runners. - - Required if I(state) is C(present). + - Required if O(state=present). type: str owned: description: - Searches only runners available to the user when searching for existing, when false admin token required. - - Mutually exclusive with I(project) since community.general 4.5.0. - - Mutually exclusive with I(group). + - Mutually exclusive with O(project) since community.general 4.5.0. + - Mutually exclusive with O(group). default: false type: bool version_added: 2.0.0 @@ -99,12 +99,12 @@ options: access_level: description: - Determines if a runner can pick up jobs only from protected branches. - - If I(access_level_on_creation) is not explicitly set to C(true), this option is ignored on registration and + - If O(access_level_on_creation) is not explicitly set to V(true), this option is ignored on registration and is only applied on updates. - - If set to C(not_protected), runner can pick up jobs from both protected and unprotected branches. - - If set to C(ref_protected), runner can pick up jobs only from protected branches. - - The current default is C(ref_protected). This will change to no default in community.general 8.0.0. - From that version on, if this option is not specified explicitly, GitLab will use C(not_protected) + - If set to V(not_protected), runner can pick up jobs from both protected and unprotected branches. + - If set to V(ref_protected), runner can pick up jobs only from protected branches. + - The current default is V(ref_protected). This will change to no default in community.general 8.0.0. + From that version on, if this option is not specified explicitly, GitLab will use V(not_protected) on creation, and the value set will not be changed on any updates. required: false choices: ["not_protected", "ref_protected"] @@ -112,9 +112,9 @@ options: access_level_on_creation: description: - Whether the runner should be registered with an access level or not. - - If set to C(true), the value of I(access_level) is used for runner registration. - - If set to C(false), GitLab registers the runner with the default access level. - - The default of this option changed to C(true) in community.general 7.0.0. Before, it was C(false). + - If set to V(true), the value of O(access_level) is used for runner registration. + - If set to V(false), GitLab registers the runner with the default access level. + - The default of this option changed to V(true) in community.general 7.0.0. Before, it was V(false). required: false default: true type: bool diff --git a/plugins/modules/gitlab_user.py b/plugins/modules/gitlab_user.py index 94f3713160..21211cdf35 100644 --- a/plugins/modules/gitlab_user.py +++ b/plugins/modules/gitlab_user.py @@ -45,7 +45,7 @@ options: name: description: - Name of the user you want to create. - - Required only if C(state) is set to C(present). + - Required only if O(state=present). type: str username: description: @@ -66,7 +66,7 @@ options: email: description: - The email that belongs to the user. - - Required only if C(state) is set to C(present). + - Required only if O(state=present). type: str sshkey_name: description: @@ -123,7 +123,7 @@ options: identities: description: - List of identities to be added/updated for this user. - - To remove all other identities from this user, set I(overwrite_identities=true). + - To remove all other identities from this user, set O(overwrite_identities=true). type: list elements: dict suboptions: @@ -139,8 +139,8 @@ options: overwrite_identities: description: - Overwrite identities with identities added in this module. - - This means that all identities that the user has and that are not listed in I(identities) are removed from the user. - - This is only done if a list is provided for I(identities). To remove all identities, provide an empty list. + - This means that all identities that the user has and that are not listed in O(identities) are removed from the user. + - This is only done if a list is provided for O(identities). To remove all identities, provide an empty list. type: bool default: false version_added: 3.3.0 diff --git a/plugins/modules/grove.py b/plugins/modules/grove.py index b3e0508ffa..d1a5f3126a 100644 --- a/plugins/modules/grove.py +++ b/plugins/modules/grove.py @@ -39,7 +39,7 @@ options: type: str description: - Message content. - - The alias I(message) is deprecated and will be removed in community.general 4.0.0. + - The alias O(ignore:message) has been removed in community.general 4.0.0. required: true url: type: str From 3e0d84bddabfa8753400329ec6f891029c8d60ff Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 15 Jun 2023 15:47:00 +0200 Subject: [PATCH 0060/1451] Use semantic markup (modules h-j) (#6677) * Use semantic markup. * Use 'ignore:' until a new version of antsibull-docs is released. * 'ignore:' is no longer needed. * E() now works better. --- plugins/modules/haproxy.py | 12 ++-- plugins/modules/heroku_collaborator.py | 10 ++-- plugins/modules/homebrew.py | 10 ++-- plugins/modules/homebrew_tap.py | 4 +- plugins/modules/homectl.py | 26 ++++----- plugins/modules/htpasswd.py | 14 ++--- plugins/modules/hwc_vpc_private_ip.py | 4 +- plugins/modules/hwc_vpc_route.py | 4 +- plugins/modules/hwc_vpc_security_group.py | 14 ++--- .../modules/hwc_vpc_security_group_rule.py | 6 +- plugins/modules/icinga2_host.py | 14 ++--- plugins/modules/idrac_redfish_config.py | 6 +- plugins/modules/influxdb_retention_policy.py | 6 +- plugins/modules/ini_file.py | 58 +++++++++---------- plugins/modules/interfaces_file.py | 8 +-- plugins/modules/ipa_dnsrecord.py | 8 +-- plugins/modules/ipa_group.py | 18 +++--- plugins/modules/ipa_hostgroup.py | 4 +- plugins/modules/ipa_user.py | 2 +- plugins/modules/ipmi_power.py | 16 ++--- plugins/modules/iptables_state.py | 18 +++--- plugins/modules/ipwcli_dns.py | 16 ++--- plugins/modules/iso_customize.py | 4 +- plugins/modules/iso_extract.py | 8 +-- plugins/modules/java_keystore.py | 32 +++++----- plugins/modules/jboss.py | 6 +- plugins/modules/jenkins_job.py | 14 ++--- plugins/modules/jenkins_job_info.py | 10 ++-- plugins/modules/jenkins_plugin.py | 24 ++++---- plugins/modules/jira.py | 28 ++++----- 30 files changed, 202 insertions(+), 202 deletions(-) diff --git a/plugins/modules/haproxy.py b/plugins/modules/haproxy.py index 56f987d80f..05f52d55c8 100644 --- a/plugins/modules/haproxy.py +++ b/plugins/modules/haproxy.py @@ -65,7 +65,7 @@ options: state: description: - Desired state of the provided backend host. - - Note that C(drain) state was added in version 2.4. + - Note that V(drain) state was added in version 2.4. - It is supported only by HAProxy version 1.5 or later, - When used on versions < 1.5, it will be ignored. type: str @@ -73,13 +73,13 @@ options: choices: [ disabled, drain, enabled ] agent: description: - - Disable/enable agent checks (depending on I(state) value). + - Disable/enable agent checks (depending on O(state) value). type: bool default: false version_added: 1.0.0 health: description: - - Disable/enable health checks (depending on I(state) value). + - Disable/enable health checks (depending on O(state) value). type: bool default: false version_added: "1.0.0" @@ -90,8 +90,8 @@ options: default: false wait: description: - - Wait until the server reports a status of C(UP) when I(state=enabled), - status of C(MAINT) when I(state=disabled) or status of C(DRAIN) when I(state=drain). + - Wait until the server reports a status of C(UP) when O(state=enabled), + status of C(MAINT) when O(state=disabled) or status of C(DRAIN) when O(state=drain). type: bool default: false wait_interval: @@ -107,7 +107,7 @@ options: weight: description: - The value passed in argument. - - If the value ends with the C(%) sign, then the new weight will be + - If the value ends with the V(%) sign, then the new weight will be relative to the initially configured weight. - Relative weights are only permitted between 0 and 100% and absolute weights are permitted between 0 and 256. diff --git a/plugins/modules/heroku_collaborator.py b/plugins/modules/heroku_collaborator.py index e7b0de3f99..e07ae333dd 100644 --- a/plugins/modules/heroku_collaborator.py +++ b/plugins/modules/heroku_collaborator.py @@ -14,9 +14,9 @@ module: heroku_collaborator short_description: Add or delete app collaborators on Heroku description: - Manages collaborators for Heroku apps. - - If set to C(present) and heroku user is already collaborator, then do nothing. - - If set to C(present) and heroku user is not collaborator, then add user to app. - - If set to C(absent) and heroku user is collaborator, then delete user from app. + - If set to V(present) and heroku user is already collaborator, then do nothing. + - If set to V(present) and heroku user is not collaborator, then add user to app. + - If set to V(absent) and heroku user is collaborator, then delete user from app. author: - Marcel Arns (@marns93) requirements: @@ -56,8 +56,8 @@ options: choices: ["present", "absent"] default: "present" notes: - - C(HEROKU_API_KEY) and C(TF_VAR_HEROKU_API_KEY) env variable can be used instead setting C(api_key). - - If you use I(--check), you can also pass the I(-v) flag to see affected apps in C(msg), e.g. ["heroku-example-app"]. + - E(HEROKU_API_KEY) and E(TF_VAR_HEROKU_API_KEY) environment variables can be used instead setting O(api_key). + - If you use C(check_mode), you can also pass the C(-v) flag to see affected apps in C(msg), e.g. ["heroku-example-app"]. ''' EXAMPLES = ''' diff --git a/plugins/modules/homebrew.py b/plugins/modules/homebrew.py index 7592f95a41..a408f4661f 100644 --- a/plugins/modules/homebrew.py +++ b/plugins/modules/homebrew.py @@ -42,9 +42,9 @@ options: elements: str path: description: - - "A C(:) separated list of paths to search for C(brew) executable. - Since a package (I(formula) in homebrew parlance) location is prefixed relative to the actual path of I(brew) command, - providing an alternative I(brew) path enables managing different set of packages in an alternative location in the system." + - "A V(:) separated list of paths to search for C(brew) executable. + Since a package (I(formula) in homebrew parlance) location is prefixed relative to the actual path of C(brew) command, + providing an alternative C(brew) path enables managing different set of packages in an alternative location in the system." default: '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin' type: path state: @@ -78,7 +78,7 @@ options: version_added: '0.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 I(name) option. + it is much more efficient to pass the list directly to the O(name) option. ''' EXAMPLES = ''' @@ -87,7 +87,7 @@ EXAMPLES = ''' name: foo state: present -# Install formula foo with 'brew' in alternate path C(/my/other/location/bin) +# Install formula foo with 'brew' in alternate path (/my/other/location/bin) - community.general.homebrew: name: foo path: /my/other/location/bin diff --git a/plugins/modules/homebrew_tap.py b/plugins/modules/homebrew_tap.py index b230dbb34c..151d09d328 100644 --- a/plugins/modules/homebrew_tap.py +++ b/plugins/modules/homebrew_tap.py @@ -42,7 +42,7 @@ options: - The optional git URL of the repository to tap. The URL is not assumed to be on GitHub, and the protocol doesn't have to be HTTP. Any location and protocol that git can handle is fine. - - I(name) option may not be a list of multiple taps (but a single + - O(name) option may not be a list of multiple taps (but a single tap instead) when this option is provided. required: false type: str @@ -55,7 +55,7 @@ options: type: str path: description: - - "A C(:) separated list of paths to search for C(brew) executable." + - "A V(:) separated list of paths to search for C(brew) executable." default: '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin' type: path version_added: '2.1.0' diff --git a/plugins/modules/homectl.py b/plugins/modules/homectl.py index 301e388d38..9fec817cb0 100644 --- a/plugins/modules/homectl.py +++ b/plugins/modules/homectl.py @@ -37,7 +37,7 @@ options: - Homed requires this value to be in cleartext on user creation and updating a user. - The module takes the password and generates a password hash in SHA-512 with 10000 rounds of salt generation using crypt. - See U(https://systemd.io/USER_RECORD/). - - This is required for I(state=present). When an existing user is updated this is checked against the stored hash in homed. + - This is required for O(state=present). When an existing user is updated this is checked against the stored hash in homed. type: str state: description: @@ -55,11 +55,11 @@ options: disksize: description: - The intended home directory disk space. - - Human readable value such as C(10G), C(10M), or C(10B). + - Human readable value such as V(10G), V(10M), or V(10B). type: str resize: description: - - When used with I(disksize) this will attempt to resize the home directory immediately. + - When used with O(disksize) this will attempt to resize the home directory immediately. default: false type: bool realname: @@ -90,7 +90,7 @@ options: description: - Path to use as home directory for the user. - This is the directory the user's home directory is mounted to while the user is logged in. - - This is not where the user's data is actually stored, see I(imagepath) for that. + - This is not where the user's data is actually stored, see O(imagepath) for that. - Only used when a user is first created. type: path imagepath: @@ -102,25 +102,25 @@ options: uid: description: - Sets the UID of the user. - - If using I(gid) homed requires the value to be the same. + - If using O(gid) homed requires the value to be the same. - Only used when a user is first created. type: int gid: description: - Sets the gid of the user. - - If using I(uid) homed requires the value to be the same. + - If using O(uid) homed requires the value to be the same. - Only used when a user is first created. type: int mountopts: description: - String separated by comma each indicating mount options for a users home directory. - - Valid options are C(nosuid), C(nodev) or C(noexec). - - Homed by default uses C(nodev) and C(nosuid) while C(noexec) is off. + - Valid options are V(nosuid), V(nodev) or V(noexec). + - Homed by default uses V(nodev) and V(nosuid) while V(noexec) is off. type: str umask: description: - Sets the umask for the user's login sessions - - Value from C(0000) to C(0777). + - Value from V(0000) to V(0777). type: int memberof: description: @@ -132,13 +132,13 @@ options: description: - The absolute path to the skeleton directory to populate a new home directory from. - This is only used when a home directory is first created. - - If not specified homed by default uses C(/etc/skel). + - If not specified homed by default uses V(/etc/skel). aliases: [ 'skel' ] type: path shell: description: - Shell binary to use for terminal logins of given user. - - If not specified homed by default uses C(/bin/bash). + - If not specified homed by default uses V(/bin/bash). type: str environment: description: @@ -151,7 +151,7 @@ options: timezone: description: - Preferred timezone to use for the user. - - Should be a tzdata compatible location string such as C(America/New_York). + - Should be a tzdata compatible location string such as V(America/New_York). type: str locked: description: @@ -160,7 +160,7 @@ options: language: description: - The preferred language/locale for the user. - - This should be in a format compatible with the C($LANG) environment variable. + - This should be in a format compatible with the E(LANG) environment variable. type: str passwordhint: description: diff --git a/plugins/modules/htpasswd.py b/plugins/modules/htpasswd.py index 180b020733..36294a0375 100644 --- a/plugins/modules/htpasswd.py +++ b/plugins/modules/htpasswd.py @@ -46,12 +46,12 @@ options: description: - Encryption scheme to be used. As well as the four choices listed here, you can also use any other hash supported by passlib, such as - C(portable_apache22) and C(host_apache24); or C(md5_crypt) and C(sha256_crypt), + V(portable_apache22) and V(host_apache24); or V(md5_crypt) and V(sha256_crypt), which are Linux passwd hashes. Only some schemes in addition to the four choices below will be compatible with Apache or Nginx, and supported schemes depend on passlib version and its dependencies. - See U(https://passlib.readthedocs.io/en/stable/lib/passlib.apache.html#passlib.apache.HtpasswdFile) parameter C(default_scheme). - - 'Some of the available choices might be: C(apr_md5_crypt), C(des_crypt), C(ldap_sha1), C(plaintext).' + - 'Some of the available choices might be: V(apr_md5_crypt), V(des_crypt), V(ldap_sha1), V(plaintext).' state: type: str required: false @@ -64,13 +64,13 @@ options: type: bool default: true description: - - Used with I(state=present). If specified, the file will be created - if it does not already exist. If set to C(false), will fail if the + - Used with O(state=present). If specified, the file will be created + if it does not already exist. If set to V(false), will fail if the file does not exist notes: - - "This module depends on the I(passlib) Python library, which needs to be installed on all target systems." - - "On Debian, Ubuntu, or Fedora: install I(python-passlib)." - - "On RHEL or CentOS: Enable EPEL, then install I(python-passlib)." + - "This module depends on the C(passlib) Python library, which needs to be installed on all target systems." + - "On Debian, Ubuntu, or Fedora: install C(python-passlib)." + - "On RHEL or CentOS: Enable EPEL, then install C(python-passlib)." requirements: [ passlib>=1.6 ] author: "Ansible Core Team" extends_documentation_fragment: diff --git a/plugins/modules/hwc_vpc_private_ip.py b/plugins/modules/hwc_vpc_private_ip.py index c57ddc6708..95e759f6f2 100644 --- a/plugins/modules/hwc_vpc_private_ip.py +++ b/plugins/modules/hwc_vpc_private_ip.py @@ -19,8 +19,8 @@ description: - vpc private ip management. short_description: Creates a resource of Vpc/PrivateIP in Huawei Cloud notes: - - If I(id) option is provided, it takes precedence over I(subnet_id), I(ip_address) for private ip selection. - - I(subnet_id), I(ip_address) are used for private ip selection. If more than one private ip with this options exists, execution is aborted. + - If O(id) option is provided, it takes precedence over O(subnet_id), O(ip_address) for private ip selection. + - O(subnet_id), O(ip_address) are used for private ip selection. If more than one private ip with this options exists, execution is aborted. - No parameter support updating. If one of option is changed, the module will create a new resource. version_added: '0.2.0' author: Huawei Inc. (@huaweicloud) diff --git a/plugins/modules/hwc_vpc_route.py b/plugins/modules/hwc_vpc_route.py index 1612cac50d..091b49b0c8 100644 --- a/plugins/modules/hwc_vpc_route.py +++ b/plugins/modules/hwc_vpc_route.py @@ -19,8 +19,8 @@ description: - vpc route management. short_description: Creates a resource of Vpc/Route in Huawei Cloud notes: - - If I(id) option is provided, it takes precedence over I(destination), I(vpc_id), I(type) and I(next_hop) for route selection. - - I(destination), I(vpc_id), I(type) and I(next_hop) are used for route selection. If more than one route with this options exists, execution is aborted. + - If O(id) option is provided, it takes precedence over O(destination), O(vpc_id), O(type), and O(next_hop) for route selection. + - O(destination), O(vpc_id), O(type) and O(next_hop) are used for route selection. If more than one route with this options exists, execution is aborted. - No parameter support updating. If one of option is changed, the module will create a new resource. version_added: '0.2.0' author: Huawei Inc. (@huaweicloud) diff --git a/plugins/modules/hwc_vpc_security_group.py b/plugins/modules/hwc_vpc_security_group.py index c210b912d4..aa65e801c4 100644 --- a/plugins/modules/hwc_vpc_security_group.py +++ b/plugins/modules/hwc_vpc_security_group.py @@ -19,9 +19,9 @@ description: - vpc security group management. short_description: Creates a resource of Vpc/SecurityGroup in Huawei Cloud notes: - - If I(id) option is provided, it takes precedence over I(name), - I(enterprise_project_id) and I(vpc_id) for security group selection. - - I(name), I(enterprise_project_id) and I(vpc_id) are used for security + - If O(id) option is provided, it takes precedence over O(name), + O(enterprise_project_id), and O(vpc_id) for security group selection. + - O(name), O(enterprise_project_id) and O(vpc_id) are used for security group selection. If more than one security group with this options exists, execution is aborted. - No parameter support updating. If one of option is changed, the module @@ -45,8 +45,8 @@ options: name: description: - Specifies the security group name. The value is a string of 1 to - 64 characters that can contain letters, digits, underscores C(_), - hyphens (-), and periods (.). + 64 characters that can contain letters, digits, underscores (V(_)), + hyphens (V(-)), and periods (V(.)). type: str required: true enterprise_project_id: @@ -79,8 +79,8 @@ RETURN = ''' name: description: - Specifies the security group name. The value is a string of 1 to - 64 characters that can contain letters, digits, underscores C(_), - hyphens (-), and periods (.). + 64 characters that can contain letters, digits, underscores (V(_)), + hyphens (V(-)), and periods (V(.)). type: str returned: success enterprise_project_id: diff --git a/plugins/modules/hwc_vpc_security_group_rule.py b/plugins/modules/hwc_vpc_security_group_rule.py index bfb5d6a615..899647e8ce 100644 --- a/plugins/modules/hwc_vpc_security_group_rule.py +++ b/plugins/modules/hwc_vpc_security_group_rule.py @@ -19,9 +19,9 @@ description: - vpc security group management. short_description: Creates a resource of Vpc/SecurityGroupRule in Huawei Cloud notes: - - If I(id) option is provided, it takes precedence over - I(enterprise_project_id) for security group rule selection. - - I(security_group_id) is used for security group rule selection. If more + - If O(id) option is provided, it takes precedence over + O(security_group_id) for security group rule selection. + - O(security_group_id) is used for security group rule selection. If more than one security group rule with this options exists, execution is aborted. - No parameter support updating. If one of option is changed, the module diff --git a/plugins/modules/icinga2_host.py b/plugins/modules/icinga2_host.py index 7f25c55d99..ce9509cbc6 100644 --- a/plugins/modules/icinga2_host.py +++ b/plugins/modules/icinga2_host.py @@ -31,13 +31,13 @@ options: - HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path use_proxy: description: - - If C(false), it will not use a proxy, even if one is defined in + - If V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts. type: bool default: true validate_certs: description: - - If C(false), SSL certificates will not be validated. This should only be used + - 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 @@ -45,12 +45,12 @@ options: type: str description: - The username for use in HTTP basic authentication. - - This parameter can be used without C(url_password) for sites that allow empty passwords. + - This parameter can be used without O(url_password) for sites that allow empty passwords. url_password: type: str description: - The password for use in HTTP basic authentication. - - If the C(url_username) parameter is not specified, the C(url_password) parameter will not be used. + - If the O(url_username) parameter is not specified, the O(url_password) parameter will not be used. force_basic_auth: description: - httplib2, the library used by the uri module only sends authentication information when a webservice @@ -64,12 +64,12 @@ options: 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, C(client_key) is not required. + the key is included, O(client_key) is not required. client_key: type: path description: - PEM formatted file that contains your private key to be used for SSL - client authentication. If C(client_cert) contains both the certificate + client authentication. If O(client_cert) contains both the certificate and key, this option is not required. state: type: str @@ -101,7 +101,7 @@ options: type: str description: - The name used to display the host. - - If not specified, it defaults to the value of the I(name) parameter. + - If not specified, it defaults to the value of the O(name) parameter. ip: type: str description: diff --git a/plugins/modules/idrac_redfish_config.py b/plugins/modules/idrac_redfish_config.py index cc47e62d2e..0388bf00fb 100644 --- a/plugins/modules/idrac_redfish_config.py +++ b/plugins/modules/idrac_redfish_config.py @@ -33,9 +33,9 @@ options: required: true description: - List of commands to execute on iDRAC. - - I(SetManagerAttributes), I(SetLifecycleControllerAttributes) and - I(SetSystemAttributes) are mutually exclusive commands when C(category) - is I(Manager). + - V(SetManagerAttributes), V(SetLifecycleControllerAttributes) and + V(SetSystemAttributes) are mutually exclusive commands when O(category) + is V(Manager). type: list elements: str baseuri: diff --git a/plugins/modules/influxdb_retention_policy.py b/plugins/modules/influxdb_retention_policy.py index 28d5450ff0..86de4ffe6f 100644 --- a/plugins/modules/influxdb_retention_policy.py +++ b/plugins/modules/influxdb_retention_policy.py @@ -46,14 +46,14 @@ options: duration: description: - Determines how long InfluxDB should keep the data. If specified, it - should be C(INF) or at least one hour. If not specified, C(INF) is + should be V(INF) or at least one hour. If not specified, V(INF) is assumed. Supports complex duration expressions with multiple units. - - Required only if I(state) is set to C(present). + - Required only if O(state) is set to V(present). type: str replication: description: - Determines how many independent copies of each point are stored in the cluster. - - Required only if I(state) is set to C(present). + - Required only if O(state) is set to V(present). type: int default: description: diff --git a/plugins/modules/ini_file.py b/plugins/modules/ini_file.py index be4a03102b..0f2df9f508 100644 --- a/plugins/modules/ini_file.py +++ b/plugins/modules/ini_file.py @@ -34,35 +34,35 @@ options: path: description: - Path to the INI-style file; this file is created if required. - - Before Ansible 2.3 this option was only usable as I(dest). + - Before Ansible 2.3 this option was only usable as O(dest). type: path required: true aliases: [ dest ] section: description: - - Section name in INI file. This is added if I(state=present) automatically when + - Section name in INI file. This is added if O(state=present) automatically when a single value is being set. - - If left empty, being omitted, or being set to C(null), the I(option) will be placed before the first I(section). - - Using C(null) is also required if the config format does not support sections. + - If left empty, being omitted, or being set to V(null), the O(option) will be placed before the first O(section). + - Using V(null) is also required if the config format does not support sections. type: str option: description: - - If set (required for changing a I(value)), this is the name of the option. - - May be omitted if adding/removing a whole I(section). + - If set (required for changing a O(value)), this is the name of the option. + - May be omitted if adding/removing a whole O(section). type: str value: description: - - The string value to be associated with an I(option). - - May be omitted when removing an I(option). - - Mutually exclusive with I(values). - - I(value=v) is equivalent to I(values=[v]). + - The string value to be associated with an O(option). + - May be omitted when removing an O(option). + - Mutually exclusive with O(values). + - O(value=v) is equivalent to O(values=[v]). type: str values: description: - - The string value to be associated with an I(option). - - May be omitted when removing an I(option). - - Mutually exclusive with I(value). - - I(value=v) is equivalent to I(values=[v]). + - The string value to be associated with an O(option). + - May be omitted when removing an O(option). + - Mutually exclusive with O(value). + - O(value=v) is equivalent to O(values=[v]). type: list elements: str version_added: 3.6.0 @@ -74,22 +74,22 @@ options: default: false state: description: - - If set to C(absent) and I(exclusive) set to C(true) all matching I(option) lines are removed. - - If set to C(absent) and I(exclusive) set to C(false) the specified I(option=value) lines are removed, - but the other I(option)s with the same name are not touched. - - If set to C(present) and I(exclusive) set to C(false) the specified I(option=values) lines are added, - but the other I(option)s with the same name are not touched. - - If set to C(present) and I(exclusive) set to C(true) all given I(option=values) lines will be - added and the other I(option)s with the same name are removed. + - If set to V(absent) and O(exclusive) set to V(true) all matching O(option) lines are removed. + - If set to V(absent) and O(exclusive) set to V(false) the specified O(option=value) lines are removed, + but the other O(option)s with the same name are not touched. + - If set to V(present) and O(exclusive) set to V(false) the specified O(option=values) lines are added, + but the other O(option)s with the same name are not touched. + - If set to V(present) and O(exclusive) set to V(true) all given O(option=values) lines will be + added and the other O(option)s with the same name are removed. type: str choices: [ absent, present ] default: present exclusive: description: - - If set to C(true) (default), all matching I(option) lines are removed when I(state=absent), - or replaced when I(state=present). - - If set to C(false), only the specified I(value(s)) are added when I(state=present), - or removed when I(state=absent), and existing ones are not modified. + - If set to V(true) (default), all matching O(option) lines are removed when O(state=absent), + or replaced when O(state=present). + - If set to V(false), only the specified O(value)/O(values) are added when O(state=present), + or removed when O(state=absent), and existing ones are not modified. type: bool default: true version_added: 3.6.0 @@ -100,7 +100,7 @@ options: default: false create: description: - - If set to C(false), the module will fail if the file does not already exist. + - If set to V(false), the module will fail if the file does not already exist. - By default it will create the file if it is missing. type: bool default: true @@ -112,13 +112,13 @@ options: follow: description: - This flag indicates that filesystem links, if they exist, should be followed. - - I(follow=true) can modify I(src) when combined with parameters such as I(mode). + - O(follow=true) can modify O(path) when combined with parameters such as O(mode). type: bool default: false version_added: 7.1.0 notes: - - While it is possible to add an I(option) without specifying a I(value), this makes no sense. - - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well. + - While it is possible to add an O(option) without specifying a O(value), this makes no sense. + - As of Ansible 2.3, the O(dest) option has been changed to O(path) as default, but O(dest) still works as well. - As of community.general 3.2.0, UTF-8 BOM markers are discarded when reading files. author: - Jan-Piet Mens (@jpmens) diff --git a/plugins/modules/interfaces_file.py b/plugins/modules/interfaces_file.py index f19c019f4e..b4b60aefee 100644 --- a/plugins/modules/interfaces_file.py +++ b/plugins/modules/interfaces_file.py @@ -46,9 +46,9 @@ options: value: type: str description: - - If I(option) is not presented for the I(interface) and I(state) is C(present) option will be added. - If I(option) already exists and is not C(pre-up), C(up), C(post-up) or C(down), it's value will be updated. - C(pre-up), C(up), C(post-up) and C(down) options can't be updated, only adding new options, removing existing + - If O(option) is not presented for the O(iface) and O(state) is V(present) option will be added. + If O(option) already exists and is not V(pre-up), V(up), V(post-up) or V(down), it's value will be updated. + V(pre-up), V(up), V(post-up) and V(down) options cannot be updated, only adding new options, removing existing ones or cleaning the whole option set are supported backup: description: @@ -59,7 +59,7 @@ options: state: type: str description: - - If set to C(absent) the option or section will be removed if present instead of created. + - If set to V(absent) the option or section will be removed if present instead of created. default: "present" choices: [ "present", "absent" ] diff --git a/plugins/modules/ipa_dnsrecord.py b/plugins/modules/ipa_dnsrecord.py index b1a90141b9..4c348cc704 100644 --- a/plugins/modules/ipa_dnsrecord.py +++ b/plugins/modules/ipa_dnsrecord.py @@ -45,8 +45,8 @@ options: record_value: description: - Manage DNS record name with this value. - - Mutually exclusive with I(record_values), and exactly one of I(record_value) and I(record_values) has to be specified. - - Use I(record_values) if you need to specify multiple values. + - 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 'A' or 'AAAA' record types, this will be the IP address. - In the case of 'A6' record type, this will be the A6 Record data. - In the case of 'CNAME' record type, this will be the hostname. @@ -59,7 +59,7 @@ options: record_values: description: - Manage DNS record name with this value. - - Mutually exclusive with I(record_value), and exactly one of I(record_value) and I(record_values) has to be specified. + - 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 'A' or 'AAAA' record types, this will be the IP address. - In the case of 'A6' record type, this will be the A6 Record data. - In the case of 'CNAME' record type, this will be the hostname. @@ -73,7 +73,7 @@ options: record_ttl: description: - Set the TTL for the record. - - Applies only when adding a new or changing the value of I(record_value) or I(record_values). + - Applies only when adding a new or changing the value of O(record_value) or O(record_values). required: false type: int state: diff --git a/plugins/modules/ipa_group.py b/plugins/modules/ipa_group.py index 87e7f0e66b..92470606fc 100644 --- a/plugins/modules/ipa_group.py +++ b/plugins/modules/ipa_group.py @@ -22,8 +22,8 @@ attributes: options: append: description: - - If C(true), add the listed I(user) and I(group) to the group members. - - If C(false), only the listed I(user) and I(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 @@ -50,9 +50,9 @@ options: group: description: - List of group names assigned to this group. - - If I(append=false) and an empty list is passed all groups will be removed from 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 I(append=true) the listed groups will be assigned without removing other groups. + - 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 @@ -63,20 +63,20 @@ options: user: description: - List of user names assigned to this group. - - If I(append=false) and an empty list is passed all users will be removed from 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 I(append=true) the listed users will be assigned without removing other users. + - 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 I(user) with respect to I(append) attribute. - - List entries can be in C(DOMAIN\\username) or SID format. + - 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. - - I(external=true) is needed for this option to work. + - O(external=true) is needed for this option to work. type: list elements: str version_added: 6.3.0 diff --git a/plugins/modules/ipa_hostgroup.py b/plugins/modules/ipa_hostgroup.py index 12232de89c..70749c35b3 100644 --- a/plugins/modules/ipa_hostgroup.py +++ b/plugins/modules/ipa_hostgroup.py @@ -22,8 +22,8 @@ attributes: options: append: description: - - If C(true), add the listed I(host) to the I(hostgroup). - - If C(false), only the listed I(host) will be in I(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 diff --git a/plugins/modules/ipa_user.py b/plugins/modules/ipa_user.py index 17b72176ea..768d004a11 100644 --- a/plugins/modules/ipa_user.py +++ b/plugins/modules/ipa_user.py @@ -51,7 +51,7 @@ options: password: description: - Password for a user. - - Will not be set for an existing user unless I(update_password=always), which is the default. + - Will not be set for an existing user unless O(update_password=always), which is the default. type: str sn: description: Surname. diff --git a/plugins/modules/ipmi_power.py b/plugins/modules/ipmi_power.py index e152f35eb4..1079a69859 100644 --- a/plugins/modules/ipmi_power.py +++ b/plugins/modules/ipmi_power.py @@ -58,7 +58,7 @@ options: - shutdown -- Have system request OS proper shutdown - reset -- Request system reset without waiting for OS - boot -- If system is off, then 'on', else 'reset'" - - Either this option or I(machine) is required. + - Either this option or O(machine) is required. choices: ['on', 'off', shutdown, reset, boot] type: str timeout: @@ -70,7 +70,7 @@ options: description: - Provide a list of the remote target address for the bridge IPMI request, and the power status. - - Either this option or I(state) is required. + - Either this option or O(state) is required. required: false type: list elements: dict @@ -83,9 +83,9 @@ options: required: true state: description: - - Whether to ensure that the machine specified by I(targetAddress) in desired state. - - If this option is not set, the power state is set by I(state). - - If both this option and I(state) are set, this option takes precedence over I(state). + - Whether to ensure that the machine specified by O(machine[].targetAddress) in desired state. + - If this option is not set, the power state is set by O(state). + - If both this option and O(state) are set, this option takes precedence over O(state). choices: ['on', 'off', shutdown, reset, boot] type: str @@ -98,18 +98,18 @@ author: "Bulat Gaifullin (@bgaifullin) " RETURN = ''' powerstate: description: The current power state of the machine. - returned: success and I(machine) is not provided + 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 I(machine) is provided + 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 I(targetAddress). + description: The current power state of the machine specified by RV(status[].targetAddress). type: str targetAddress: description: The remote target address. diff --git a/plugins/modules/iptables_state.py b/plugins/modules/iptables_state.py index d0ea7ad798..b034b1f564 100644 --- a/plugins/modules/iptables_state.py +++ b/plugins/modules/iptables_state.py @@ -34,8 +34,8 @@ description: 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 I(poll) to C(0), and I(async) to a value less - or equal to C(ANSIBLE_TIMEOUT). If I(async) is greater, the rollback will + 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. @@ -52,7 +52,7 @@ options: counters: description: - Save or restore the values of all packet and byte counters. - - When C(true), the module is not idempotent. + - When V(true), the module is not idempotent. type: bool default: false ip_version: @@ -65,14 +65,14 @@ options: description: - Specify the path to the C(modprobe) program internally used by iptables related commands to load kernel modules. - - By default, C(/proc/sys/kernel/modprobe) is inspected to determine the + - By default, V(/proc/sys/kernel/modprobe) is inspected to determine the executable's path. type: path noflush: description: - - For I(state=restored), ignored otherwise. - - If C(false), restoring iptables rules from a file flushes (deletes) - all previous contents of the respective table(s). If C(true), the + - 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). type: bool @@ -92,10 +92,10 @@ options: required: true table: description: - - When I(state=restored), restore only the named table even if the input + - 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 I(state=saved), restrict output to the specified table. If not + - 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 ] diff --git a/plugins/modules/ipwcli_dns.py b/plugins/modules/ipwcli_dns.py index 7b05aefb77..3ffad79fb6 100644 --- a/plugins/modules/ipwcli_dns.py +++ b/plugins/modules/ipwcli_dns.py @@ -54,7 +54,7 @@ options: address: description: - The IP address for the A or AAAA record. - - Required for I(type=A) or I(type=AAAA). + - Required for O(type=A) or O(type=AAAA). type: str ttl: description: @@ -80,38 +80,38 @@ options: port: description: - Sets the port of the SRV record. - - Required for I(type=SRV). + - Required for O(type=SRV). type: int target: description: - Sets the target of the SRV record. - - Required for I(type=SRV). + - Required for O(type=SRV). type: str order: description: - Sets the order of the NAPTR record. - - Required for I(type=NAPTR). + - Required for O(type=NAPTR). type: int preference: description: - Sets the preference of the NAPTR record. - - Required for I(type=NAPTR). + - Required for O(type=NAPTR). type: int flags: description: - Sets one of the possible flags of NAPTR record. - - Required for I(type=NAPTR). + - Required for O(type=NAPTR). type: str choices: ['S', 'A', 'U', 'P'] service: description: - Sets the service of the NAPTR record. - - Required for I(type=NAPTR). + - Required for O(type=NAPTR). type: str replacement: description: - Sets the replacement of the NAPTR record. - - Required for I(type=NAPTR). + - Required for O(type=NAPTR). type: str username: description: diff --git a/plugins/modules/iso_customize.py b/plugins/modules/iso_customize.py index 9add080b11..6e01dc0976 100644 --- a/plugins/modules/iso_customize.py +++ b/plugins/modules/iso_customize.py @@ -15,7 +15,7 @@ module: iso_customize short_description: Add/remove/change files in ISO file description: - This module is used to add/remove/change files in ISO file. - - The file inside ISO will be overwritten if it exists by option I(add_files). + - The file inside ISO will be overwritten if it exists by option O(add_files). author: - Yuhua Zou (@ZouYuhua) requirements: @@ -72,7 +72,7 @@ options: notes: - The C(pycdlib) library states it supports Python 2.7 and 3.4 only. - > - The function I(add_file) in pycdlib will overwrite the existing file in ISO with type ISO9660 / Rock Ridge 1.12 / Joliet / UDF. + 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". ''' diff --git a/plugins/modules/iso_extract.py b/plugins/modules/iso_extract.py index 599cbe4de5..fdcbb40bfa 100644 --- a/plugins/modules/iso_extract.py +++ b/plugins/modules/iso_extract.py @@ -58,18 +58,18 @@ options: required: true force: description: - - If C(true), which will replace the remote file when contents are different than the source. - - If C(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 C(7z). + - If not provided, it will assume the value V(7z). type: path notes: - Only the file checksum (content) is taken into account when extracting files - from the ISO image. If I(force=false), only checks the presence of the file. + from the ISO image. If O(force=false), only checks the presence of the file. - In Ansible 2.3 this module was using C(mount) and C(umount) commands only, requiring root access. This is no longer needed with the introduction of 7zip for extraction. diff --git a/plugins/modules/java_keystore.py b/plugins/modules/java_keystore.py index 7c2c4884dc..2aeab75c06 100644 --- a/plugins/modules/java_keystore.py +++ b/plugins/modules/java_keystore.py @@ -36,7 +36,7 @@ options: - 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 I(certificate) or I(certificate_path) is required. + - Exactly one of O(certificate) or O(certificate_path) is required. type: str certificate_path: description: @@ -44,18 +44,18 @@ options: - 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 I(certificate) or I(certificate_path) is required. + - Exactly one of O(certificate) or O(certificate_path) is required. type: path version_added: '3.0.0' private_key: description: - Content of the private key used to create the keystore. - - Exactly one of I(private_key) or I(private_key_path) is required. + - Exactly one of O(private_key) or O(private_key_path) is required. type: str private_key_path: description: - Location of the private key used to create the keystore. - - Exactly one of I(private_key) or I(private_key_path) is required. + - Exactly one of O(private_key) or O(private_key_path) is required. type: path version_added: '3.0.0' private_key_passphrase: @@ -108,13 +108,13 @@ options: - 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; C(pkcs12) since Java 9 and C(jks) prior (may also - be C(pkcs12) if new default has been backported to this version). + 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 I(keystore_type) is set, the keystore is created with this type if - it doesn't already exist, or is overwritten to match the given type in + - 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: @@ -122,9 +122,9 @@ options: - pkcs12 version_added: 3.3.0 requirements: - - openssl in PATH (when I(ssl_backend=openssl)) + - openssl in PATH (when O(ssl_backend=openssl)) - keytool in PATH - - cryptography >= 3.0 (when I(ssl_backend=cryptography)) + - cryptography >= 3.0 (when O(ssl_backend=cryptography)) author: - Guillaume Grossetie (@Mogztter) - quidame (@quidame) @@ -135,13 +135,13 @@ seealso: - module: community.crypto.openssl_pkcs12 - module: community.general.java_cert notes: - - I(certificate) and I(private_key) require that their contents are available - on the controller (either inline in a playbook, or with the C(file) lookup), - while I(certificate_path) and I(private_key_path) require that the files are + - 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 I(keystore_type), I(name) or - I(password), as well as changes of key or certificate materials will cause - the existing I(dest) to be overwritten. + - 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 = ''' diff --git a/plugins/modules/jboss.py b/plugins/modules/jboss.py index b389e7e662..3d07a38d63 100644 --- a/plugins/modules/jboss.py +++ b/plugins/modules/jboss.py @@ -30,8 +30,8 @@ options: src: description: - The remote path of the application ear or war to deploy. - - Required when I(state=present). - - Ignored when I(state=absent). + - Required when O(state=present). + - Ignored when O(state=absent). type: path deploy_path: default: /var/lib/jbossas/standalone/deployments @@ -46,7 +46,7 @@ options: type: str notes: - The JBoss standalone deployment-scanner has to be enabled in standalone.xml - - The module can wait until I(deployment) file is deployed/undeployed by deployment-scanner. + - 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 seealso: diff --git a/plugins/modules/jenkins_job.py b/plugins/modules/jenkins_job.py index 09b006448e..e8301041f2 100644 --- a/plugins/modules/jenkins_job.py +++ b/plugins/modules/jenkins_job.py @@ -30,14 +30,14 @@ options: description: - config in XML format. - Required if job does not yet exist. - - Mutually exclusive with I(enabled). - - Considered if I(state=present). + - Mutually exclusive with O(enabled). + - Considered if O(state=present). required: false enabled: description: - Whether the job should be enabled or disabled. - - Mutually exclusive with I(config). - - Considered if I(state=present). + - Mutually exclusive with O(config). + - Considered if O(state=present). type: bool required: false name: @@ -77,10 +77,10 @@ options: type: bool default: true description: - - If set to C(false), the SSL certificates will not be validated. - This should only set to C(false) used on personally controlled sites + - 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 C(PYTHONHTTPSVERIFY). + - The C(python-jenkins) library only handles this by using the environment variable E(PYTHONHTTPSVERIFY). version_added: 2.3.0 ''' diff --git a/plugins/modules/jenkins_job_info.py b/plugins/modules/jenkins_job_info.py index ba6a531179..71ec8e2637 100644 --- a/plugins/modules/jenkins_job_info.py +++ b/plugins/modules/jenkins_job_info.py @@ -15,7 +15,7 @@ module: jenkins_job_info short_description: Get information about Jenkins jobs description: - This module can be used to query information about which Jenkins jobs which already exists. - - This module was called C(jenkins_job_info) before Ansible 2.9. The usage did not change. + - This module was called C(jenkins_job_facts) before Ansible 2.9. The usage did not change. requirements: - "python-jenkins >= 0.4.12" extends_documentation_fragment: @@ -38,12 +38,12 @@ options: type: str description: - Password to authenticate with the Jenkins server. - - This is mutually exclusive with I(token). + - This is mutually exclusive with O(token). token: type: str description: - API token used to authenticate with the Jenkins server. - - This is mutually exclusive with I(password). + - This is mutually exclusive with O(password). url: type: str description: @@ -55,8 +55,8 @@ options: - User to authenticate with the Jenkins server. validate_certs: description: - - If set to C(False), the SSL certificates will not be validated. - - This should only set to C(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: diff --git a/plugins/modules/jenkins_plugin.py b/plugins/modules/jenkins_plugin.py index 2fbc83e03f..157d70c527 100644 --- a/plugins/modules/jenkins_plugin.py +++ b/plugins/modules/jenkins_plugin.py @@ -53,7 +53,7 @@ options: type: str description: - Desired plugin state. - - If the C(latest) is set, the check for new version will be performed + - 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 @@ -65,18 +65,18 @@ options: updates_expiration: type: int description: - - Number of seconds after which a new copy of the I(update-center.json) + - 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 C(latest) is specified. - - Set it to C(0) if no cache file should be used. In that case, 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 - C(latest) is specified. + O(state=latest) is specified. default: 86400 updates_url: type: list elements: str description: - - A list of base URL(s) to retrieve I(update-center.json), and direct plugin files from. + - A list of base URL(s) to retrieve C(update-center.json), and direct plugin files from. - This can be a list since community.general 3.3.0. default: ['https://updates.jenkins.io', 'http://mirrors.jenkins.io'] update_json_url_segment: @@ -90,14 +90,14 @@ options: type: list elements: str description: - - Path inside the I(updates_url) to get latest plugins from. + - Path inside the O(updates_url) to get latest plugins from. default: ['latest'] version_added: 3.3.0 versioned_plugins_url_segments: type: list elements: str description: - - Path inside the I(updates_url) to get specific version of plugins from. + - Path inside the O(updates_url) to get specific version of plugins from. default: ['download/plugins', 'plugins'] version_added: 3.3.0 url: @@ -114,11 +114,11 @@ options: - 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 C(1.20) would be unquoted, it would become C(1.2). + example if V(1.20) would be unquoted, it would become V(1.2). with_dependencies: description: - Defines whether to install plugin dependencies. - - This option takes effect only if the I(version) is not defined. + - This option takes effect only if the O(version) is not defined. type: bool default: true @@ -127,11 +127,11 @@ notes: 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's necessary to notify the handler or call the I(service) module to + - 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 I(url) + - 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: diff --git a/plugins/modules/jira.py b/plugins/modules/jira.py index 85097c4b76..708a1f328c 100644 --- a/plugins/modules/jira.py +++ b/plugins/modules/jira.py @@ -44,25 +44,25 @@ options: choices: [ attach, comment, create, edit, fetch, link, search, transition, update, worklog ] description: - The operation to perform. - - C(worklog) was added in community.genereal 6.5.0. + - V(worklog) was added in community.genereal 6.5.0. username: type: str description: - The username to log-in with. - - Must be used with I(password). Mutually exclusive with I(token). + - 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 I(username). Mutually exclusive with I(token). + - Must be used with O(username). Mutually exclusive with O(token). token: type: str description: - The personal access token to log-in with. - - Mutually exclusive with I(username) and I(password). + - Mutually exclusive with O(username) and O(password). version_added: 4.2.0 project: @@ -128,20 +128,20 @@ options: type: str required: false description: - - Only used when I(operation) is C(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 I(operation) is C(create), C(transition) or C(edit). - - Recent versions of JIRA no longer accept a user name as a user identifier. In that case, use I(account_id) instead. + - 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 I(operation) is C(create), C(transition) or C(edit). + - 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 @@ -183,8 +183,8 @@ options: maxresults: required: false description: - - Limit the result of I(operation=search). If no value is specified, the default jira limit will be used. - - Used when I(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 +198,7 @@ options: validate_certs: required: false description: - - Require valid SSL certificates (set to C(false) if you'd 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,12 +212,12 @@ options: required: true type: path description: - - The path to the file to upload (from the remote node) or, if I(content) is specified, + - 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 I(filename) will be + - 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 @@ -227,7 +227,7 @@ options: notes: - "Currently this only works with basic-auth, or tokens." - - "To use with JIRA Cloud, pass the login e-mail as the I(username) and the API token as I(password)." + - "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)" From c694abbdf9bd862210c545bbdec24afd596038ae Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 15 Jun 2023 15:47:13 +0200 Subject: [PATCH 0061/1451] Use semantic markup (modules k-l) (#6678) * Use semantic markup. * Use option instead of alias. --- plugins/modules/kdeconfig.py | 8 +- plugins/modules/keycloak_authentication.py | 2 +- .../keycloak_authz_authorization_scope.py | 12 +-- plugins/modules/keycloak_client.py | 101 +++++++++--------- .../modules/keycloak_client_rolemapping.py | 6 +- plugins/modules/keycloak_clientscope.py | 52 ++++----- plugins/modules/keycloak_clientscope_type.py | 2 +- plugins/modules/keycloak_clientsecret_info.py | 6 +- plugins/modules/keycloak_clienttemplate.py | 67 ++++++------ plugins/modules/keycloak_group.py | 10 +- plugins/modules/keycloak_identity_provider.py | 15 +-- plugins/modules/keycloak_realm.py | 4 +- plugins/modules/keycloak_role.py | 4 +- plugins/modules/keycloak_user.py | 6 +- plugins/modules/keycloak_user_federation.py | 49 ++++----- plugins/modules/keycloak_user_rolemapping.py | 8 +- plugins/modules/layman.py | 12 +-- plugins/modules/ldap_attrs.py | 22 ++-- plugins/modules/ldap_entry.py | 12 +-- plugins/modules/ldap_passwd.py | 8 +- plugins/modules/ldap_search.py | 12 +-- plugins/modules/listen_ports_facts.py | 11 +- plugins/modules/lvg.py | 6 +- plugins/modules/lxc_container.py | 20 ++-- plugins/modules/lxd_container.py | 36 +++---- plugins/modules/lxd_project.py | 8 +- 26 files changed, 249 insertions(+), 250 deletions(-) diff --git a/plugins/modules/kdeconfig.py b/plugins/modules/kdeconfig.py index 42a08dd64d..4e8d395215 100644 --- a/plugins/modules/kdeconfig.py +++ b/plugins/modules/kdeconfig.py @@ -35,11 +35,11 @@ options: suboptions: group: description: - - The option's group. One between this and I(groups) is required. + - The option's group. One between this and O(values[].groups) is required. type: str groups: description: - - List of the option's groups. One between this and I(group) is required. + - List of the option's groups. One between this and O(values[].group) is required. type: list elements: str key: @@ -49,12 +49,12 @@ options: required: true value: description: - - The option's value. One between this and I(bool_value) is required. + - The option's value. One between this and O(values[].bool_value) is required. type: str bool_value: description: - Boolean value. - - One between this and I(value) is required. + - One between this and O(values[].value) is required. type: bool required: true backup: diff --git a/plugins/modules/keycloak_authentication.py b/plugins/modules/keycloak_authentication.py index 6143d9d5cd..966d5b20f7 100644 --- a/plugins/modules/keycloak_authentication.py +++ b/plugins/modules/keycloak_authentication.py @@ -97,7 +97,7 @@ options: type: bool default: false description: - - If C(true), allows to remove the authentication flow and recreate it. + - If V(true), allows to remove the authentication flow and recreate it. extends_documentation_fragment: - community.general.keycloak diff --git a/plugins/modules/keycloak_authz_authorization_scope.py b/plugins/modules/keycloak_authz_authorization_scope.py index c451d3751e..5eef9ac765 100644 --- a/plugins/modules/keycloak_authz_authorization_scope.py +++ b/plugins/modules/keycloak_authz_authorization_scope.py @@ -40,8 +40,8 @@ options: state: description: - State of the authorization scope. - - On C(present), the authorization scope will be created (or updated if it exists already). - - On C(absent), the authorization scope will be removed if it exists. + - 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 @@ -108,22 +108,22 @@ end_state: id: description: ID of the authorization scope. type: str - returned: when I(state=present) + returned: when O(state=present) sample: a6ab1cf2-1001-40ec-9f39-48f23b6a0a41 name: description: Name of the authorization scope. type: str - returned: when I(state=present) + returned: when O(state=present) sample: file:delete display_name: description: Display name of the authorization scope. type: str - returned: when I(state=present) + returned: when O(state=present) sample: File delete icon_uri: description: Icon URI for the authorization scope. type: str - returned: when I(state=present) + returned: when O(state=present) sample: http://localhost/icon.png ''' diff --git a/plugins/modules/keycloak_client.py b/plugins/modules/keycloak_client.py index ee687fcb43..6cb0a4ec98 100644 --- a/plugins/modules/keycloak_client.py +++ b/plugins/modules/keycloak_client.py @@ -40,8 +40,8 @@ options: state: description: - State of the client - - On C(present), the client will be created (or updated if it exists already). - - On C(absent), the client will be removed if it exists + - 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 @@ -55,7 +55,7 @@ options: client_id: description: - Client id of client to be worked on. This is usually an alphanumeric name chosen by - you. Either this or I(id) is required. If you specify both, I(id) takes precedence. + 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 @@ -63,13 +63,13 @@ options: id: description: - - Id of client to be worked on. This is usually an UUID. Either this or I(client_id) + - 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 I(client_id)). + - Name of the client (this is not the same as O(client_id)). type: str description: @@ -108,12 +108,12 @@ options: client_authenticator_type: description: - - How do clients authenticate with the auth server? Either C(client-secret) or - C(client-jwt) can be chosen. When using C(client-secret), the module parameter - I(secret) can set it, while for C(client-jwt), you can use the keys C(use.jwks.url), - C(jwks.url), and C(jwt.credential.certificate) in the I(attributes) module parameter + - How do clients authenticate with the auth server? Either V(client-secret) or + V(client-jwt) can be chosen. When using V(client-secret), the module parameter + O(secret) can set it, while 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. - This is 'clientAuthenticatorType' in the Keycloak REST API. + - This is 'clientAuthenticatorType' in the Keycloak REST API. choices: ['client-secret', 'client-jwt'] aliases: - clientAuthenticatorType @@ -121,7 +121,7 @@ options: secret: description: - - When using I(client_authenticator_type) C(client-secret) (the default), you can + - 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). @@ -246,7 +246,7 @@ options: protocol: description: - - Type of client (either C(openid-connect) or C(saml). + - Type of client. type: str choices: ['openid-connect', 'saml'] @@ -286,7 +286,7 @@ options: use_template_config: description: - - Whether or not to use configuration from the I(client_template). + - Whether or not to use configuration from the O(client_template). This is 'useTemplateConfig' in the Keycloak REST API. aliases: - useTemplateConfig @@ -294,7 +294,7 @@ options: use_template_scope: description: - - Whether or not to use scope configuration from the I(client_template). + - Whether or not to use scope configuration from the O(client_template). This is 'useTemplateScope' in the Keycloak REST API. aliases: - useTemplateScope @@ -302,7 +302,7 @@ options: use_template_mappers: description: - - Whether or not to use mapper configuration from the I(client_template). + - Whether or not to use mapper configuration from the O(client_template). This is 'useTemplateMappers' in the Keycloak REST API. aliases: - useTemplateMappers @@ -391,38 +391,37 @@ options: protocol: description: - - This is either C(openid-connect) or C(saml), this specifies for which protocol this protocol mapper. - is active. + - This specifies for which protocol this protocol mapper is active. choices: ['openid-connect', 'saml'] type: str protocolMapper: description: - - The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is + - "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 - - C(docker-v2-allow-all-mapper) - - C(oidc-address-mapper) - - C(oidc-full-name-mapper) - - C(oidc-group-membership-mapper) - - C(oidc-hardcoded-claim-mapper) - - C(oidc-hardcoded-role-mapper) - - C(oidc-role-name-mapper) - - C(oidc-script-based-protocol-mapper) - - C(oidc-sha256-pairwise-sub-mapper) - - C(oidc-usermodel-attribute-mapper) - - C(oidc-usermodel-client-role-mapper) - - C(oidc-usermodel-property-mapper) - - C(oidc-usermodel-realm-role-mapper) - - C(oidc-usersessionmodel-note-mapper) - - C(saml-group-membership-mapper) - - C(saml-hardcode-attribute-mapper) - - C(saml-hardcode-role-mapper) - - C(saml-role-list-mapper) - - C(saml-role-name-mapper) - - C(saml-user-attribute-mapper) - - C(saml-user-property-mapper) - - C(saml-user-session-note-mapper) + 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'. @@ -431,10 +430,10 @@ options: config: description: - Dict specifying the configuration options for the protocol mapper; the - contents differ depending on the value of I(protocolMapper) and are not documented + 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 I(existing) field. + protocol mapper configuration through check-mode in the RV(existing) field. type: dict attributes: @@ -478,7 +477,7 @@ options: saml.signature.algorithm: description: - - Signature algorithm used to sign SAML documents. One of C(RSA_SHA256), C(RSA_SHA1), C(RSA_SHA512), or C(DSA_SHA1). + - 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: @@ -503,15 +502,15 @@ options: saml_name_id_format: description: - - For SAML clients, the NameID format to use (one of C(username), C(email), C(transient), or C(persistent)) + - 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 - C(http://www.w3.org/2001/10/xml-exc-c14n#) for EXCLUSIVE, - C(http://www.w3.org/2001/10/xml-exc-c14n#WithComments) for EXCLUSIVE_WITH_COMMENTS, - C(http://www.w3.org/TR/2001/REC-xml-c14n-20010315) for INCLUSIVE, and - C(http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) for INCLUSIVE_WITH_COMMENTS. + 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: @@ -523,12 +522,12 @@ options: user.info.response.signature.alg: description: - - For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses. One of C(RS256) or C(unsigned). + - 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 C(any), C(none), C(RS256). + OIDC request object. One of V(any), V(none), V(RS256). use.jwks.url: description: diff --git a/plugins/modules/keycloak_client_rolemapping.py b/plugins/modules/keycloak_client_rolemapping.py index 57dcac48de..420ed9c1f5 100644 --- a/plugins/modules/keycloak_client_rolemapping.py +++ b/plugins/modules/keycloak_client_rolemapping.py @@ -43,8 +43,8 @@ options: state: description: - State of the client_rolemapping. - - On C(present), the client_rolemapping will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the client_rolemapping will be removed if it exists. + - 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: @@ -73,7 +73,7 @@ options: client_id: type: str description: - - Name of the client to be mapped (different than I(cid)). + - 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: diff --git a/plugins/modules/keycloak_clientscope.py b/plugins/modules/keycloak_clientscope.py index a23d92867a..d37af5f0cf 100644 --- a/plugins/modules/keycloak_clientscope.py +++ b/plugins/modules/keycloak_clientscope.py @@ -43,8 +43,8 @@ options: state: description: - State of the client_scope. - - On C(present), the client_scope will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the client_scope will be removed if it exists. + - 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: @@ -103,28 +103,28 @@ options: - "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:" - - C(docker-v2-allow-all-mapper) - - C(oidc-address-mapper) - - C(oidc-full-name-mapper) - - C(oidc-group-membership-mapper) - - C(oidc-hardcoded-claim-mapper) - - C(oidc-hardcoded-role-mapper) - - C(oidc-role-name-mapper) - - C(oidc-script-based-protocol-mapper) - - C(oidc-sha256-pairwise-sub-mapper) - - C(oidc-usermodel-attribute-mapper) - - C(oidc-usermodel-client-role-mapper) - - C(oidc-usermodel-property-mapper) - - C(oidc-usermodel-realm-role-mapper) - - C(oidc-usersessionmodel-note-mapper) - - C(saml-group-membership-mapper) - - C(saml-hardcode-attribute-mapper) - - C(saml-hardcode-role-mapper) - - C(saml-role-list-mapper) - - C(saml-role-name-mapper) - - C(saml-user-attribute-mapper) - - C(saml-user-property-mapper) - - C(saml-user-session-note-mapper) + - 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'. @@ -143,10 +143,10 @@ options: config: description: - Dict specifying the configuration options for the protocol mapper; the - contents differ depending on the value of I(protocolMapper) and are not documented + 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 C(existing) return value. + protocol mapper configuration through check-mode in the RV(existing) return value. type: dict attributes: diff --git a/plugins/modules/keycloak_clientscope_type.py b/plugins/modules/keycloak_clientscope_type.py index facf02aa47..0165b1abe8 100644 --- a/plugins/modules/keycloak_clientscope_type.py +++ b/plugins/modules/keycloak_clientscope_type.py @@ -40,7 +40,7 @@ options: client_id: description: - - The I(client_id) of the client. If not set the clientscop types are set as a default for the realm. + - The O(client_id) of the client. If not set the clientscop types are set as a default for the realm. aliases: - clientId type: str diff --git a/plugins/modules/keycloak_clientsecret_info.py b/plugins/modules/keycloak_clientsecret_info.py index 98a41ad20a..c772620351 100644 --- a/plugins/modules/keycloak_clientsecret_info.py +++ b/plugins/modules/keycloak_clientsecret_info.py @@ -26,8 +26,8 @@ description: and a user having the expected roles. - When retrieving a new client secret, where possible provide the client's - I(id) (not I(client_id)) to the module. This removes a lookup to the API to - translate the I(client_id) into the client ID. + 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." @@ -48,7 +48,7 @@ options: client_id: description: - - The I(client_id) of the client. Passing this instead of I(id) results in an + - The O(client_id) of the client. Passing this instead of O(id) results in an extra API call. aliases: - clientId diff --git a/plugins/modules/keycloak_clienttemplate.py b/plugins/modules/keycloak_clienttemplate.py index d2555afc5b..cd7f6c09b7 100644 --- a/plugins/modules/keycloak_clienttemplate.py +++ b/plugins/modules/keycloak_clienttemplate.py @@ -38,8 +38,8 @@ options: state: description: - State of the client template. - - On C(present), the client template will be created (or updated if it exists already). - - On C(absent), the client template will be removed if it exists + - 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 @@ -67,7 +67,7 @@ options: protocol: description: - - Type of client template (either C(openid-connect) or C(saml). + - Type of client template. choices: ['openid-connect', 'saml'] type: str @@ -106,38 +106,37 @@ options: protocol: description: - - This is either C(openid-connect) or C(saml), this specifies for which protocol this protocol mapper. - is active. + - This specifies for which protocol this protocol mapper is active. choices: ['openid-connect', 'saml'] type: str protocolMapper: description: - - The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is + - "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 - - C(docker-v2-allow-all-mapper) - - C(oidc-address-mapper) - - C(oidc-full-name-mapper) - - C(oidc-group-membership-mapper) - - C(oidc-hardcoded-claim-mapper) - - C(oidc-hardcoded-role-mapper) - - C(oidc-role-name-mapper) - - C(oidc-script-based-protocol-mapper) - - C(oidc-sha256-pairwise-sub-mapper) - - C(oidc-usermodel-attribute-mapper) - - C(oidc-usermodel-client-role-mapper) - - C(oidc-usermodel-property-mapper) - - C(oidc-usermodel-realm-role-mapper) - - C(oidc-usersessionmodel-note-mapper) - - C(saml-group-membership-mapper) - - C(saml-hardcode-attribute-mapper) - - C(saml-hardcode-role-mapper) - - C(saml-role-list-mapper) - - C(saml-role-name-mapper) - - C(saml-user-attribute-mapper) - - C(saml-user-property-mapper) - - C(saml-user-session-note-mapper) + 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'. @@ -146,10 +145,10 @@ options: config: description: - Dict specifying the configuration options for the protocol mapper; the - contents differ depending on the value of I(protocolMapper) and are not documented + 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 I(existing) field. + protocol mapper configuration through check-mode in the RV(existing) field. type: dict attributes: @@ -160,9 +159,9 @@ options: type: dict notes: - - The Keycloak REST API defines further fields (namely I(bearerOnly), I(consentRequired), I(standardFlowEnabled), - I(implicitFlowEnabled), I(directAccessGrantsEnabled), I(serviceAccountsEnabled), I(publicClient), and - I(frontchannelLogout)) which, while available with keycloak_client, do not have any effect on + - 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. diff --git a/plugins/modules/keycloak_group.py b/plugins/modules/keycloak_group.py index 399bc5b4fa..5398a4b5d0 100644 --- a/plugins/modules/keycloak_group.py +++ b/plugins/modules/keycloak_group.py @@ -41,9 +41,9 @@ options: state: description: - State of the group. - - On C(present), the group will be created if it does not yet exist, or updated with the parameters you provide. + - On V(present), the group will be created if it does not yet exist, or updated with the parameters you provide. - >- - On C(absent), the group will be removed if it exists. Be aware that absenting + 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 @@ -93,7 +93,7 @@ options: type: str description: - Identify parent by ID. - - Needs less API calls than using I(name). + - 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 @@ -102,14 +102,14 @@ options: type: str description: - Identify parent by name. - - Needs more internal API calls than using I(id) to map names to ID's under the hood. + - 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 I(realmRoles), I(clientRoles) and I(access) attributes returned by the Keycloak API + - 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: diff --git a/plugins/modules/keycloak_identity_provider.py b/plugins/modules/keycloak_identity_provider.py index 0d12ae03a4..a135b16e43 100644 --- a/plugins/modules/keycloak_identity_provider.py +++ b/plugins/modules/keycloak_identity_provider.py @@ -36,8 +36,8 @@ options: state: description: - State of the identity provider. - - On C(present), the identity provider will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the identity provider will be removed if it exists. + - 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: @@ -120,16 +120,16 @@ options: provider_id: description: - - Protocol used by this provider (supported values are C(oidc) or C(saml)). + - 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 I(providerId). - Examples are given below for C(oidc) and C(saml). It is easiest to obtain valid config values by dumping an already-existing - identity provider configuration through check-mode in the I(existing) field. + - 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: @@ -271,7 +271,8 @@ options: config: description: - - Dict specifying the configuration options for the mapper; the contents differ depending on the value of I(identityProviderMapper). + - Dict specifying the configuration options for the mapper; the contents differ depending on the value of + O(mappers[].identityProviderMapper). type: dict extends_documentation_fragment: diff --git a/plugins/modules/keycloak_realm.py b/plugins/modules/keycloak_realm.py index 53f81be489..9f2e72b525 100644 --- a/plugins/modules/keycloak_realm.py +++ b/plugins/modules/keycloak_realm.py @@ -42,8 +42,8 @@ options: state: description: - State of the realm. - - On C(present), the realm will be created (or updated if it exists already). - - On C(absent), the realm will be removed if it exists. + - 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 diff --git a/plugins/modules/keycloak_role.py b/plugins/modules/keycloak_role.py index 46758a7621..f3e01483f8 100644 --- a/plugins/modules/keycloak_role.py +++ b/plugins/modules/keycloak_role.py @@ -40,8 +40,8 @@ options: state: description: - State of the role. - - On C(present), the role will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the role will be removed if it exists. + - 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: diff --git a/plugins/modules/keycloak_user.py b/plugins/modules/keycloak_user.py index b6d2bfa747..61be26e5e2 100644 --- a/plugins/modules/keycloak_user.py +++ b/plugins/modules/keycloak_user.py @@ -135,7 +135,7 @@ options: required: true temporary: description: - - If C(true), the users are required to reset their credentials at next login. + - If V(true), the users are required to reset their credentials at next login. type: bool default: false required_actions: @@ -207,7 +207,7 @@ options: type: str force: description: - - If C(true), allows to remove user and recreate it. + - If V(true), allows to remove user and recreate it. type: bool default: false extends_documentation_fragment: @@ -345,7 +345,7 @@ end_state: returned: on success type: dict changed: - description: Return C(true) if the operation changed the user on the keycloak server, C(false) otherwise. + description: Return V(true) if the operation changed the user on the keycloak server, V(false) otherwise. returned: always type: bool ''' diff --git a/plugins/modules/keycloak_user_federation.py b/plugins/modules/keycloak_user_federation.py index c0dc5d271b..b29cf21859 100644 --- a/plugins/modules/keycloak_user_federation.py +++ b/plugins/modules/keycloak_user_federation.py @@ -36,9 +36,9 @@ options: state: description: - State of the user federation. - - On C(present), the user federation will be created if it does not yet exist, or updated with + - On V(present), the user federation will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the user federation will be removed if it exists. + - On V(absent), the user federation will be removed if it exists. default: 'present' type: str choices: @@ -54,7 +54,7 @@ options: id: description: - The unique ID for this user federation. If left empty, the user federation will be searched - by its I(name). + by its O(name). type: str name: @@ -75,7 +75,7 @@ options: provider_type: description: - - Component type for user federation (only supported value is C(org.keycloak.storage.UserStorageProvider)). + - Component type for user federation (only supported value is V(org.keycloak.storage.UserStorageProvider)). aliases: - providerType default: org.keycloak.storage.UserStorageProvider @@ -91,10 +91,10 @@ options: config: description: - Dict specifying the configuration options for the provider; the contents differ depending on - the value of I(provider_id). Examples are given below for C(ldap), C(kerberos) and C(sssd). + 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 I(existing) field. - - The value C(sssd) has been supported since community.general 4.2.0. + 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: @@ -111,15 +111,15 @@ options: importEnabled: description: - - If C(true), LDAP users will be imported into Keycloak DB and synced by the configured + - If V(true), LDAP users will be imported into Keycloak DB and synced by the configured sync policies. default: true type: bool editMode: description: - - C(READ_ONLY) is a read-only LDAP store. C(WRITABLE) means data will be synced back to LDAP - on demand. C(UNSYNCED) means user data will be imported, but not synced back to LDAP. + - 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 @@ -136,13 +136,13 @@ options: vendor: description: - LDAP vendor (provider). - - Use short name. For instance, write C(rhds) for "Red Hat Directory Server". + - 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 C(uid). For Active directory it can be C(sAMAccountName) or C(cn). + 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 @@ -151,15 +151,15 @@ options: 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 C(cn) as RDN attribute when - username attribute might be C(sAMAccountName). + 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 C(entryUUID); however some are different. - For example for Active directory it should be C(objectGUID). If your LDAP server does + 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 @@ -167,7 +167,7 @@ options: userObjectClasses: description: - All values of LDAP objectClass attribute for users in LDAP divided by comma. - For example C(inetOrgPerson, organizationalPerson). Newly created Keycloak users + 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 @@ -251,8 +251,8 @@ options: useTruststoreSpi: description: - Specifies whether LDAP connection will use the truststore SPI with the truststore - configured in standalone.xml/domain.xml. C(Always) means that it will always use it. - C(Never) means that it will not use it. C(Only for ldaps) means that it will use if + 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. @@ -297,7 +297,7 @@ options: connectionPoolingDebug: description: - A string that indicates the level of debug output to produce. Example valid values are - C(fine) (trace connection creation and removal) and C(all) (all debugging information). + V(fine) (trace connection creation and removal) and V(all) (all debugging information). type: str connectionPoolingInitSize: @@ -321,7 +321,7 @@ options: connectionPoolingProtocol: description: - A list of space-separated protocol types of connections that may be pooled. - Valid types are C(plain) and C(ssl). + Valid types are V(plain) and V(ssl). type: str connectionPoolingTimeout: @@ -345,14 +345,14 @@ options: serverPrincipal: description: - Full name of server principal for HTTP service including server and domain name. For - example C(HTTP/host.foo.org@FOO.ORG). Use C(*) to accept any service principal in the + 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 C(/etc/krb5.keytab). + example V(/etc/krb5.keytab). type: str debug: @@ -451,7 +451,7 @@ options: providerId: description: - - The mapper type for this mapper (for instance C(user-attribute-ldap-mapper)). + - The mapper type for this mapper (for instance V(user-attribute-ldap-mapper)). type: str providerType: @@ -464,6 +464,7 @@ options: 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: diff --git a/plugins/modules/keycloak_user_rolemapping.py b/plugins/modules/keycloak_user_rolemapping.py index d754e313a5..59727a346e 100644 --- a/plugins/modules/keycloak_user_rolemapping.py +++ b/plugins/modules/keycloak_user_rolemapping.py @@ -42,8 +42,8 @@ options: state: description: - State of the user_rolemapping. - - On C(present), the user_rolemapping will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the user_rolemapping will be removed if it exists. + - 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: @@ -79,8 +79,8 @@ options: client_id: type: str description: - - Name of the client to be mapped (different than I(cid)). - - This parameter is required if I(cid) is not provided (can be replaced by I(cid) + - 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: diff --git a/plugins/modules/layman.py b/plugins/modules/layman.py index 940ac30d1b..4371e2bc02 100644 --- a/plugins/modules/layman.py +++ b/plugins/modules/layman.py @@ -32,27 +32,27 @@ 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 I(state=updated)). + Use '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 + This list will be fetched and saved under C(${overlay_defs}/${name}.xml), where C(overlay_defs) is readed from the Layman's configuration. aliases: [url] type: str state: description: - - Whether to install (C(present)), sync (C(updated)), or uninstall (C(absent)) the overlay. + - Whether to install (V(present)), sync (V(updated)), or uninstall (V(absent)) the overlay. default: present choices: [present, absent, updated] type: str validate_certs: description: - - If C(false), SSL certificates will not be validated. This should only be - set to C(false) when no other option exists. Prior to 1.9.3 the code - defaulted to C(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 ''' diff --git a/plugins/modules/ldap_attrs.py b/plugins/modules/ldap_attrs.py index d93b4672a4..8eadf183a5 100644 --- a/plugins/modules/ldap_attrs.py +++ b/plugins/modules/ldap_attrs.py @@ -25,10 +25,10 @@ notes: 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 I(bind_dn) - and I(bind_pw). - - For I(state=present) and I(state=absent), all value comparisons are - performed on the server for maximum accuracy. For I(state=exact), values + 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 @@ -52,11 +52,11 @@ options: choices: [present, absent, exact] default: present description: - - The state of the attribute values. If C(present), all given attribute - values will be added if they're missing. If C(absent), all given - attribute values will be removed if present. If C(exact), the set of + - 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 I(state=exact) and the attribute I(value) is empty, all values for + If O(state=exact) and the attribute value is empty, all values for this attribute will be removed. attributes: required: true @@ -69,16 +69,16 @@ options: 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 C(yes), C(no) (booleans), or C(2.10) (float), make sure to quote them if + 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 C(true), prepend list values with X-ORDERED index numbers in all + - If V(true), prepend list values with X-ORDERED index numbers in all attributes specified in the current task. This is useful mostly with - I(olcAccess) attribute to easily manage LDAP Access Control Lists. + C(olcAccess) attribute to easily manage LDAP Access Control Lists. extends_documentation_fragment: - community.general.ldap.documentation - community.general.attributes diff --git a/plugins/modules/ldap_entry.py b/plugins/modules/ldap_entry.py index 11fa5278dc..350feec887 100644 --- a/plugins/modules/ldap_entry.py +++ b/plugins/modules/ldap_entry.py @@ -24,8 +24,8 @@ notes: 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 I(bind_dn) - and I(bind_pw). + a simple bind to access your server, pass the credentials in O(bind_dn) + and O(bind_pw). author: - Jiri Tyr (@jtyr) requirements: @@ -38,7 +38,7 @@ attributes: options: attributes: description: - - If I(state=present), attributes necessary to create an entry. Existing + - 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 @@ -47,13 +47,13 @@ options: 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 C(yes), C(no) (booleans), or C(2.10) (float), make sure to quote them if + 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 I(state=present), value or list of values to use when creating + - 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 @@ -66,7 +66,7 @@ options: type: str recursive: description: - - If I(state=delete), a flag indicating whether a single entry or the + - If O(state=delete), a flag indicating whether a single entry or the whole branch must be deleted. type: bool default: false diff --git a/plugins/modules/ldap_passwd.py b/plugins/modules/ldap_passwd.py index 3f9e6ec4ad..5044586b0f 100644 --- a/plugins/modules/ldap_passwd.py +++ b/plugins/modules/ldap_passwd.py @@ -20,10 +20,10 @@ description: 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 + 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 I(bind_dn) - and I(bind_pw). + a simple bind to access your server, pass the credentials in O(bind_dn) + and O(bind_pw). author: - Keller Fuchs (@KellerFuchs) requirements: @@ -36,7 +36,7 @@ attributes: options: passwd: description: - - The (plaintext) password to be set for I(dn). + - The (plaintext) password to be set for O(dn). type: str extends_documentation_fragment: - community.general.ldap.documentation diff --git a/plugins/modules/ldap_search.py b/plugins/modules/ldap_search.py index d8fa2efd07..d5e3265f0d 100644 --- a/plugins/modules/ldap_search.py +++ b/plugins/modules/ldap_search.py @@ -21,8 +21,8 @@ notes: 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 I(bind_dn) - and I(bind_pw). + a simple bind to access your server, pass the credentials in O(bind_dn) + and O(bind_pw). author: - Sebastian Pfahl (@eryx12o45) requirements: @@ -59,8 +59,8 @@ options: default: false type: bool description: - - Set to C(true) to return the full attribute schema of entries, not - their attribute values. Overrides I(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 @@ -73,7 +73,7 @@ options: description: - If provided, all attribute values returned that are listed in this option will be Base64 encoded. - - If the special value C(*) appears in this list, all attributes will be + - 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. @@ -110,7 +110,7 @@ results: value is a list. - Note that all values (for single-element lists) and list elements (for multi-valued lists) will be UTF-8 strings. Some might contain Base64-encoded binary data; which - ones is determined by the I(base64_attributes) option. + ones is determined by the O(base64_attributes) option. type: list elements: dict """ diff --git a/plugins/modules/listen_ports_facts.py b/plugins/modules/listen_ports_facts.py index bc630e1d2e..c68e883142 100644 --- a/plugins/modules/listen_ports_facts.py +++ b/plugins/modules/listen_ports_facts.py @@ -40,7 +40,8 @@ options: include_non_listening: description: - Show both listening and non-listening sockets (for TCP this means established connections). - - Adds the return values C(state) and C(foreign_address) to the returned facts. + - 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 @@ -96,13 +97,13 @@ ansible_facts: sample: "0.0.0.0" foreign_address: description: The address of the remote end of the socket. - returned: if I(include_non_listening=true) + returned: if O(include_non_listening=true) type: str sample: "10.80.0.1" version_added: 5.4.0 state: description: The state of the socket. - returned: if I(include_non_listening=true) + returned: if O(include_non_listening=true) type: str sample: "ESTABLISHED" version_added: 5.4.0 @@ -148,13 +149,13 @@ ansible_facts: sample: "0.0.0.0" foreign_address: description: The address of the remote end of the socket. - returned: if I(include_non_listening=true) + returned: if O(include_non_listening=true) type: str sample: "10.80.0.1" version_added: 5.4.0 state: description: The state of the socket. UDP is a connectionless protocol. Shows UCONN or ESTAB. - returned: if I(include_non_listening=true) + returned: if O(include_non_listening=true) type: str sample: "UCONN" version_added: 5.4.0 diff --git a/plugins/modules/lvg.py b/plugins/modules/lvg.py index 60eaaa42b2..860c333218 100644 --- a/plugins/modules/lvg.py +++ b/plugins/modules/lvg.py @@ -39,7 +39,7 @@ options: elements: str pesize: description: - - "The size of the physical extent. I(pesize) must be a power of 2 of at least 1 sector + - "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." - Since Ansible 2.6, pesize can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte. @@ -52,7 +52,7 @@ options: default: '' pvresize: description: - - If C(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' @@ -69,7 +69,7 @@ options: default: present force: description: - - If C(true), allows to remove volume group with logical volumes. + - If V(true), allows to remove volume group with logical volumes. type: bool default: false seealso: diff --git a/plugins/modules/lxc_container.py b/plugins/modules/lxc_container.py index aec8f12dc4..ddc7d3b56e 100644 --- a/plugins/modules/lxc_container.py +++ b/plugins/modules/lxc_container.py @@ -111,7 +111,7 @@ options: - debug - DEBUG description: - - Set the log level for a container where I(container_log) was set. + - Set the log level for a container where O(container_log) was set. type: str required: false default: INFO @@ -158,7 +158,7 @@ options: - clone description: - Define the state of a container. - - If you clone a container using I(clone_name) the newly cloned + - 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 @@ -178,17 +178,17 @@ 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 I(container_command) can be used with any state except C(absent). If - used with state C(stopped) the container will be C(started), the command - executed, and then the container C(stopped) again. Likewise if I(state=stopped) + - 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, - C(started), the command executed, and then C(stopped). If you use a "|" + 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 I(container_command) option will always execute as BASH. - When using I(container_command), a log file is created in the C(/tmp/) directory + 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 I(archive=true) the system will attempt to create a compressed - tarball of the running container. The I(archive) option supports LVM backed + - 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 diff --git a/plugins/modules/lxd_container.py b/plugins/modules/lxd_container.py index f10fc4872f..5cf49ddd95 100644 --- a/plugins/modules/lxd_container.py +++ b/plugins/modules/lxd_container.py @@ -40,26 +40,26 @@ options: version_added: 4.8.0 architecture: description: - - 'The architecture for the instance (for example C(x86_64) or C(i686)). + - 'The architecture for the instance (for example V(x86_64) or V(i686)). See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1).' type: str required: false config: description: - - 'The config for the instance (for example C({"limits.cpu": "2"})). + - 'The config for the instance (for example V({"limits.cpu": "2"})). See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1).' - If the instance already exists and its "config" values in metadata obtained from the LXD API U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#instances-containers-and-virtual-machines) are different, this module tries to apply the configurations. - - The keys starting with C(volatile.) are ignored for this comparison when I(ignore_volatile_options=true). + - 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 C(true), options starting with C(volatile.) are ignored. As a result, + - 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 C(false). - - The default value changed from C(true) to C(false) in community.general 6.0.0. + - 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 @@ -72,26 +72,23 @@ options: devices: description: - 'The devices for the instance - (for example C({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})). + (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})). See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1).' type: dict required: false ephemeral: description: - - Whether or not the instance is ephemeral (for example C(true) or C(false)). + - Whether or not the instance is ephemeral (for example V(true) or V(false)). See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1). required: false type: bool source: description: - 'The source for the instance - (e.g. { "type": "image", - "mode": "pull", - "server": "https://images.linuxcontainers.org", - "protocol": "lxd", - "alias": "ubuntu/xenial/amd64" }).' + (for example V({ "type": "image", "mode": "pull", "server": "https://images.linuxcontainers.org", + "protocol": "lxd", "alias": "ubuntu/xenial/amd64" })).' - 'See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1) for complete API documentation.' - - 'Note that C(protocol) accepts two choices: C(lxd) or C(simplestreams).' + - 'Note that C(protocol) accepts two choices: V(lxd) or V(simplestreams).' required: false type: dict state: @@ -125,7 +122,7 @@ options: type: int type: description: - - Instance type can be either C(virtual-machine) or C(container). + - Instance type can be either V(virtual-machine) or V(container). required: false default: container choices: @@ -135,7 +132,7 @@ options: version_added: 4.1.0 wait_for_ipv4_addresses: description: - - If this is true, the C(lxd_container) waits until IPv4 addresses + - 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 @@ -143,14 +140,14 @@ options: type: bool wait_for_container: description: - - If set to C(true), the tasks will wait till the task reports a + - 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 true, the C(lxd_container) forces to stop the instance + - 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 @@ -201,7 +198,8 @@ notes: 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 C(community.general.lxd) connection plugin. + 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). diff --git a/plugins/modules/lxd_project.py b/plugins/modules/lxd_project.py index 983531fa08..11318ecc6d 100644 --- a/plugins/modules/lxd_project.py +++ b/plugins/modules/lxd_project.py @@ -34,7 +34,7 @@ options: type: str config: description: - - 'The config for the project (for example C({"features.profiles": "true"})). + - 'The config for the project (for example V({"features.profiles": "true"})). See U(https://linuxcontainers.org/lxd/docs/master/projects/).' - If the project already exists and its "config" value in metadata obtained from @@ -98,7 +98,7 @@ options: 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 I(trust_password) is set, this module send a request for + - If O(trust_password) is set, this module send a request for authentication before sending any requests. required: false type: str @@ -146,7 +146,7 @@ logs: elements: dict contains: type: - description: Type of actions performed, currently only C(sent request). + description: Type of actions performed, currently only V(sent request). type: str sample: "sent request" request: @@ -166,7 +166,7 @@ logs: type: str sample: "(too long to be placed here)" timeout: - description: Timeout of HTTP request, C(null) if unset. + description: Timeout of HTTP request, V(null) if unset. type: int sample: null response: From b271dba4bfe172b009b89458bf0c3eba6cff4cd2 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 15 Jun 2023 15:47:40 +0200 Subject: [PATCH 0062/1451] Use semantic markup (modules m-n) (#6679) * Use semantic markup. * Use option instead of alias. * Simplify. * Fix/improve nagios docs. --- plugins/modules/macports.py | 2 +- plugins/modules/make.py | 12 +- plugins/modules/manageiq_policies.py | 14 +- plugins/modules/manageiq_policies_info.py | 4 +- plugins/modules/manageiq_tags.py | 14 +- plugins/modules/manageiq_tags_info.py | 4 +- plugins/modules/mattermost.py | 10 +- plugins/modules/maven_artifact.py | 34 +-- plugins/modules/memset_dns_reload.py | 4 +- plugins/modules/memset_memstore_info.py | 4 +- plugins/modules/memset_server_info.py | 4 +- plugins/modules/memset_zone.py | 2 +- plugins/modules/memset_zone_domain.py | 4 +- plugins/modules/memset_zone_record.py | 4 +- plugins/modules/monit.py | 4 +- plugins/modules/mqtt.py | 6 +- plugins/modules/mssql_script.py | 23 +- plugins/modules/nagios.py | 33 ++- plugins/modules/netcup_dns.py | 6 +- plugins/modules/newrelic_deployment.py | 8 +- plugins/modules/nictagadm.py | 14 +- plugins/modules/nmcli.py | 288 +++++++++++----------- plugins/modules/nomad_job.py | 4 +- plugins/modules/nosh.py | 20 +- 24 files changed, 263 insertions(+), 259 deletions(-) diff --git a/plugins/modules/macports.py b/plugins/modules/macports.py index 6f40d0938e..e81fb9142c 100644 --- a/plugins/modules/macports.py +++ b/plugins/modules/macports.py @@ -55,7 +55,7 @@ options: variant: description: - A port variant specification. - - 'C(variant) is only supported with state: I(installed)/I(present).' + - 'O(variant) is only supported with O(state=installed) and O(state=present).' aliases: ['variants'] type: str ''' diff --git a/plugins/modules/make.py b/plugins/modules/make.py index ebff6cfe11..1bc62925f5 100644 --- a/plugins/modules/make.py +++ b/plugins/modules/make.py @@ -53,7 +53,7 @@ options: target: description: - The target to run. - - Typically this would be something like C(install), C(test), or C(all). + - Typically this would be something like V(install), V(test), or V(all). type: str ''' @@ -86,7 +86,7 @@ EXAMPLES = r''' RETURN = r''' chdir: description: - - The value of the module parameter I(chdir). + - The value of the module parameter O(chdir). type: str returned: success command: @@ -97,22 +97,22 @@ command: version_added: 6.5.0 file: description: - - The value of the module parameter I(file). + - The value of the module parameter O(file). type: str returned: success jobs: description: - - The value of the module parameter I(jobs). + - The value of the module parameter O(jobs). type: int returned: success params: description: - - The value of the module parameter I(params). + - The value of the module parameter O(params). type: dict returned: success target: description: - - The value of the module parameter I(target). + - The value of the module parameter O(target). type: str returned: success ''' diff --git a/plugins/modules/manageiq_policies.py b/plugins/modules/manageiq_policies.py index 7d05f2dfad..1504e2beac 100644 --- a/plugins/modules/manageiq_policies.py +++ b/plugins/modules/manageiq_policies.py @@ -32,10 +32,10 @@ options: state: type: str description: - - C(absent) - policy_profiles should not exist, - - C(present) - policy_profiles should exist, + - V(absent) - policy_profiles should not exist, + - V(present) - policy_profiles should exist, - > - C(list) - list current policy_profiles and policies. + V(list) - list current policy_profiles and policies. This state is deprecated and will be removed 8.0.0. Please use the module M(community.general.manageiq_policies_info) instead. choices: ['absent', 'present', 'list'] @@ -44,8 +44,8 @@ options: type: list elements: dict description: - - List of dictionaries, each includes the policy_profile C(name) key. - - Required if I(state) is C(present) or C(absent). + - List of dictionaries, each includes the policy_profile V(name) key. + - Required if O(state) is V(present) or V(absent). resource_type: type: str description: @@ -58,12 +58,12 @@ options: type: str description: - The name of the resource to which the profile should be [un]assigned. - - Must be specified if I(resource_id) is not set. Both options are mutually exclusive. + - Must be specified if O(resource_id) is not set. Both options are mutually exclusive. resource_id: type: int description: - The ID of the resource to which the profile should be [un]assigned. - - Must be specified if I(resource_name) is not set. Both options are mutually exclusive. + - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. version_added: 2.2.0 ''' diff --git a/plugins/modules/manageiq_policies_info.py b/plugins/modules/manageiq_policies_info.py index 8a75ef6464..fda7dcadfe 100644 --- a/plugins/modules/manageiq_policies_info.py +++ b/plugins/modules/manageiq_policies_info.py @@ -38,12 +38,12 @@ options: type: str description: - The name of the resource to obtain the profile for. - - Must be specified if I(resource_id) is not set. Both options are mutually exclusive. + - Must be specified if O(resource_id) is not set. Both options are mutually exclusive. resource_id: type: int description: - The ID of the resource to obtain the profile for. - - Must be specified if I(resource_name) is not set. Both options are mutually exclusive. + - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. ''' EXAMPLES = ''' diff --git a/plugins/modules/manageiq_tags.py b/plugins/modules/manageiq_tags.py index 8631ac46a4..c4606a51c1 100644 --- a/plugins/modules/manageiq_tags.py +++ b/plugins/modules/manageiq_tags.py @@ -32,10 +32,10 @@ options: state: type: str description: - - C(absent) - tags should not exist. - - C(present) - tags should exist. + - V(absent) - tags should not exist. + - V(present) - tags should exist. - > - C(list) - list current tags. + V(list) - list current tags. This state is deprecated and will be removed 8.0.0. Please use the module M(community.general.manageiq_tags_info) instead. choices: ['absent', 'present', 'list'] @@ -44,8 +44,8 @@ options: type: list elements: dict description: - - C(tags) - list of dictionaries, each includes C(name) and c(category) keys. - - Required if I(state) is C(present) or C(absent). + - V(tags) - list of dictionaries, each includes C(name) and C(category) keys. + - Required if O(state) is V(present) or V(absent). resource_type: type: str description: @@ -58,11 +58,11 @@ options: type: str description: - The name of the resource at which tags will be controlled. - - Must be specified if I(resource_id) is not set. Both options are mutually exclusive. + - Must be specified if O(resource_id) is not set. Both options are mutually exclusive. resource_id: description: - The ID of the resource at which tags will be controlled. - - Must be specified if I(resource_name) is not set. Both options are mutually exclusive. + - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. type: int version_added: 2.2.0 ''' diff --git a/plugins/modules/manageiq_tags_info.py b/plugins/modules/manageiq_tags_info.py index af71e150cb..75e111540b 100644 --- a/plugins/modules/manageiq_tags_info.py +++ b/plugins/modules/manageiq_tags_info.py @@ -36,11 +36,11 @@ options: type: str description: - The name of the resource at which tags will be controlled. - - Must be specified if I(resource_id) is not set. Both options are mutually exclusive. + - Must be specified if O(resource_id) is not set. Both options are mutually exclusive. resource_id: description: - The ID of the resource at which tags will be controlled. - - Must be specified if I(resource_name) is not set. Both options are mutually exclusive. + - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. type: int ''' diff --git a/plugins/modules/mattermost.py b/plugins/modules/mattermost.py index 29894c3a7c..b299747519 100644 --- a/plugins/modules/mattermost.py +++ b/plugins/modules/mattermost.py @@ -39,26 +39,26 @@ options: 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. api_key is the last part. + This will give you full URL. I(api_key) is the last part. http://mattermost.example.com/hooks/C(API_KEY) required: true text: type: str description: - Text to send. Note that the module does not handle escaping characters. - - Required when I(attachments) is not set. + - Required when O(attachments) is not set. attachments: type: list elements: dict description: - Define a list of attachments. - For more information, see U(https://developers.mattermost.com/integrate/admin-guide/admin-message-attachments/). - - Required when I(text) is not set. + - Required when O(text) is not set. version_added: 4.3.0 channel: type: str description: - - Channel to send the message to. If absent, the message goes to the channel selected for the I(api_key). + - Channel to send the message to. If absent, the message goes to the channel selected for the O(api_key). username: type: str description: @@ -71,7 +71,7 @@ options: default: https://docs.ansible.com/favicon.ico validate_certs: description: - - If C(false), SSL certificates will not be validated. This should only be used + - 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 diff --git a/plugins/modules/maven_artifact.py b/plugins/modules/maven_artifact.py index 3f9defa529..125ef5160c 100644 --- a/plugins/modules/maven_artifact.py +++ b/plugins/modules/maven_artifact.py @@ -43,14 +43,14 @@ options: type: str description: - The maven version coordinate - - Mutually exclusive with I(version_by_spec). + - 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 "(,1.0],[1.2,)" and "(,1.1),(1.1,)" is not supported. - - Mutually exclusive with I(version). + - Mutually exclusive with O(version). version_added: '0.2.0' classifier: type: str @@ -111,48 +111,48 @@ options: default: 10 validate_certs: description: - - If C(false), SSL certificates will not be validated. This should only be set to C(false) when no other option exists. + - 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, I(client_key) is not required. + - 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 I(client_cert) contains both the certificate and key, this option is not required. + - 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 C(true), the downloaded artifact's name is preserved, i.e the version number remains part of it. - - This option only has effect when C(dest) is a directory and C(version) is set to C(latest) or C(version_by_spec) + - 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 I(dest) is a directory and I(version) is set to V(latest) or O(version_by_spec) is defined. type: bool default: false verify_checksum: type: str description: - - If C(never), the MD5/SHA1 checksum will never be downloaded and verified. - - If C(download), the MD5/SHA1 checksum will be downloaded and verified only after artifact download. This is the default. - - If C(change), the MD5/SHA1 checksum will be downloaded and verified if the destination already exist, + - 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 C(always) instead - if you deal with a checksum, it is better to + 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. - - C(always) combines C(download) and C(change). + - V(always) combines V(download) and V(change). required: false default: 'download' choices: ['never', 'download', 'change', 'always'] checksum_alg: type: str description: - - If C(md5), checksums will use the MD5 algorithm. This is the default. - - If C(sha1), checksums will use the SHA1 algorithm. This can be used on systems configured to use + - 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'] @@ -162,14 +162,14 @@ options: 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 fetch_url C(fetch_url) function. - - On ansible-core version 2.12 or later, the default of this option is C([Authorization, Cookie]). + - 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 I(dest) when it is a directory. + - Filesystem permission mode applied recursively to O(dest) when it is a directory. extends_documentation_fragment: - ansible.builtin.files - community.general.attributes diff --git a/plugins/modules/memset_dns_reload.py b/plugins/modules/memset_dns_reload.py index a1168724f5..668c8c0bf3 100644 --- a/plugins/modules/memset_dns_reload.py +++ b/plugins/modules/memset_dns_reload.py @@ -18,8 +18,8 @@ notes: 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 - - I(dns.reload). If you wish to poll the job status to wait until the reload has - completed, then I(job.status) is also required. + 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: diff --git a/plugins/modules/memset_memstore_info.py b/plugins/modules/memset_memstore_info.py index 5fc9d79e1f..90df75d911 100644 --- a/plugins/modules/memset_memstore_info.py +++ b/plugins/modules/memset_memstore_info.py @@ -15,7 +15,7 @@ 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 - I(memstore.usage). + following minimum scope - C(memstore.usage). description: - Retrieve Memstore product usage information. - This module was called C(memset_memstore_facts) before Ansible 2.9. The usage did not change. @@ -36,7 +36,7 @@ options: required: true type: str description: - - The Memstore product name (i.e. C(mstestyaa1)). + - The Memstore product name (that is, C(mstestyaa1)). ''' EXAMPLES = ''' diff --git a/plugins/modules/memset_server_info.py b/plugins/modules/memset_server_info.py index ecc0375eb1..cebe5a84a7 100644 --- a/plugins/modules/memset_server_info.py +++ b/plugins/modules/memset_server_info.py @@ -15,7 +15,7 @@ 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 - I(server.info). + following minimum scope - C(server.info). description: - Retrieve server information. - This module was called C(memset_server_facts) before Ansible 2.9. The usage did not change. @@ -36,7 +36,7 @@ options: required: true type: str description: - - The server product name (i.e. C(testyaa1)). + - The server product name (that is, C(testyaa1)). ''' EXAMPLES = ''' diff --git a/plugins/modules/memset_zone.py b/plugins/modules/memset_zone.py index e17472e395..f520d54460 100644 --- a/plugins/modules/memset_zone.py +++ b/plugins/modules/memset_zone.py @@ -17,7 +17,7 @@ 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 - - I(dns.zone_create), I(dns.zone_delete), I(dns.zone_list). + C(dns.zone_create), C(dns.zone_delete), C(dns.zone_list). description: - Manage DNS zones in a Memset account. extends_documentation_fragment: diff --git a/plugins/modules/memset_zone_domain.py b/plugins/modules/memset_zone_domain.py index 172a48be25..e07ac1ff02 100644 --- a/plugins/modules/memset_zone_domain.py +++ b/plugins/modules/memset_zone_domain.py @@ -17,9 +17,9 @@ 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 - - I(dns.zone_domain_create), I(dns.zone_domain_delete), I(dns.zone_domain_list). + 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(with_items). + be created using C(loop). description: - Manage DNS zone domains in a Memset account. extends_documentation_fragment: diff --git a/plugins/modules/memset_zone_record.py b/plugins/modules/memset_zone_record.py index 4e56a11caf..8406d93d21 100644 --- a/plugins/modules/memset_zone_record.py +++ b/plugins/modules/memset_zone_record.py @@ -17,9 +17,9 @@ 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 - - I(dns.zone_create), I(dns.zone_delete), I(dns.zone_list). + 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(with_items). + should be created using C(loop). description: - Manage DNS records in a Memset account. extends_documentation_fragment: diff --git a/plugins/modules/monit.py b/plugins/modules/monit.py index d2a1606789..5475ab1e52 100644 --- a/plugins/modules/monit.py +++ b/plugins/modules/monit.py @@ -14,7 +14,7 @@ DOCUMENTATION = ''' module: monit short_description: Manage the state of a program monitored via Monit description: - - Manage the state of a program monitored via I(Monit). + - Manage the state of a program monitored via Monit. extends_documentation_fragment: - community.general.attributes attributes: @@ -25,7 +25,7 @@ attributes: options: name: description: - - The name of the I(monit) program/process to manage. + - The name of the C(monit) program/process to manage. required: true type: str state: diff --git a/plugins/modules/mqtt.py b/plugins/modules/mqtt.py index 3893826491..f8d64e6a00 100644 --- a/plugins/modules/mqtt.py +++ b/plugins/modules/mqtt.py @@ -40,7 +40,7 @@ options: password: type: str description: - - Password for C(username) to authenticate against the broker. + - Password for O(username) to authenticate against the broker. client_id: type: str description: @@ -54,8 +54,8 @@ options: payload: type: str description: - - Payload. The special string C("None") may be used to send a NULL - (i.e. empty) payload which is useful to simply notify with the I(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: diff --git a/plugins/modules/mssql_script.py b/plugins/modules/mssql_script.py index 715f2faf04..0033cf2e34 100644 --- a/plugins/modules/mssql_script.py +++ b/plugins/modules/mssql_script.py @@ -46,27 +46,28 @@ options: type: str required: true login_port: - description: Port of the MSSQL server. Requires I(login_host) be defined as well. + 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 C(GO) command. + - 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 output: description: - - With C(default) each row will be returned as a list of values. See C(query_results). - - Output format C(dict) will return dictionary with the column names as keys. See C(query_results_dict). - - C(dict) requires named columns to be returned by each query otherwise an error is thrown. + - 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. ('SELECT %(name)s"' with C(example: '{"name": "John Doe"}).)' + 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 @@ -148,17 +149,17 @@ EXAMPLES = r''' RETURN = r''' query_results: - description: List of batches (queries separated by C(GO) keyword). + description: List of batches (queries separated by V(GO) keyword). type: list elements: list - returned: success and I(output=default) + 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 C(GO) keyword in I(script) to separate queries. + - Use the V(GO) keyword in O(script) to separate queries. type: list elements: list contains: @@ -175,10 +176,10 @@ query_results: example: ["Batch 0 - Select 0"] returned: success, if output is default query_results_dict: - description: List of batches (queries separated by C(GO) keyword). + description: List of batches (queries separated by V(GO) keyword). type: list elements: list - returned: success and I(output=dict) + returned: success and O(output=dict) sample: [[[["Batch 0 - Select 0"]], [["Batch 0 - Select 1"]]], [[["Batch 1 - Select 0"]]]] contains: queries: diff --git a/plugins/modules/nagios.py b/plugins/modules/nagios.py index 1831d04961..783aa88e24 100644 --- a/plugins/modules/nagios.py +++ b/plugins/modules/nagios.py @@ -21,13 +21,13 @@ short_description: Perform common tasks in Nagios related to downtime and notifi description: - "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 I(host) parameter to be given explicitly. In playbooks you can use the C({{inventory_hostname}}) variable to refer + - 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. I(services=httpd,nfs,puppet). - - When specifying what service to handle there is a special service value, I(host), which will handle alerts/downtime/acknowledge for the I(host itself), - e.g., I(service=host). This keyword may not be given with other services at the same time. - I(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", e.g., I(service=all). + - 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). extends_documentation_fragment: - community.general.attributes attributes: @@ -41,7 +41,7 @@ options: - Action to take. - servicegroup options were added in 2.0. - delete_downtime options were added in 2.2. - - The C(acknowledge) and C(forced_check) actions were added in community.general 1.2.0. + - 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", @@ -59,12 +59,12 @@ options: author: description: - Author to leave downtime comments as. - Only used when I(action) is C(downtime) or C(acknowledge). + Only used when O(action) is V(downtime) or V(acknowledge). type: str default: Ansible comment: description: - - Comment when I(action) is C(downtime) or C(acknowledge). + - Comment when O(action) is V(downtime) or V(acknowledge). type: str default: Scheduling downtime start: @@ -75,27 +75,24 @@ options: minutes: description: - Minutes to schedule downtime for. - - Only usable with the C(downtime) action. + - Only usable with O(action=downtime). type: int default: 30 services: description: - - > - What to manage downtime/alerts for. Separate multiple services with commas. - I(service) is an alias for I(services). - B(Required) option when I(action) is one of: C(downtime), C(acknowledge), C(forced_check), C(enable_alerts), C(disable_alerts). + - 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" ] type: str servicegroup: description: - The Servicegroup we want to set downtimes/alerts for. - B(Required) option when using the C(servicegroup_service_downtime) amd C(servicegroup_host_downtime). + - B(Required) option when using the V(servicegroup_service_downtime) and V(servicegroup_host_downtime) O(action). type: str command: description: - - The raw command to send to nagios, which - should not include the submitted time header or the line-feed - B(Required) option when using the C(command) action. + - The raw command to send to nagios, which should not include the submitted time header or the line-feed. + - B(Required) option when using the V(command) O(action). type: str author: "Tim Bielawa (@tbielawa)" diff --git a/plugins/modules/netcup_dns.py b/plugins/modules/netcup_dns.py index 77be50b2c6..a3ba8312be 100644 --- a/plugins/modules/netcup_dns.py +++ b/plugins/modules/netcup_dns.py @@ -46,7 +46,7 @@ options: type: str record: description: - - Record to add or delete, supports wildcard (*). Default is C(@) (e.g. the zone name). + - Record to add or delete, supports wildcard (V(*)). Default is V(@) (that is, the zone name). default: "@" aliases: [ name ] type: str @@ -65,11 +65,11 @@ options: type: bool default: false description: - - Whether the record should be the only one for that record type and record name. Only use with I(state=present). + - Whether the record should be the only one for that record type and record name. Only use with O(state=present). - This will delete all other records with the same record name and type. priority: description: - - Record priority. Required for I(type=MX). + - Record priority. Required for O(type=MX). required: false type: int state: diff --git a/plugins/modules/newrelic_deployment.py b/plugins/modules/newrelic_deployment.py index b038af1445..9b52f34557 100644 --- a/plugins/modules/newrelic_deployment.py +++ b/plugins/modules/newrelic_deployment.py @@ -32,14 +32,14 @@ options: app_name: type: str description: - - The value of app_name in the newrelic.yml file used by the application. - - One of I(app_name) or I(application_id) is required. + - The value of C(app_name) in the C(newrelic.yml) file used by the application. + - One of O(app_name) or O(application_id) is required. required: false application_id: type: str description: - The application ID found in the metadata of the application in APM. - - One of I(app_name) or I(application_id) is required. + - One of O(app_name) or O(application_id) is required. required: false changelog: type: str @@ -63,7 +63,7 @@ options: required: false validate_certs: description: - - If C(false), SSL certificates will not be validated. This should only be used + - 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 diff --git a/plugins/modules/nictagadm.py b/plugins/modules/nictagadm.py index 074e09b4ac..5b81861e8f 100644 --- a/plugins/modules/nictagadm.py +++ b/plugins/modules/nictagadm.py @@ -31,23 +31,23 @@ options: type: str mac: description: - - Specifies the I(mac) address to attach the nic tag to when not creating an I(etherstub). - - Parameters I(mac) and I(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 I(etherstub). - - Parameter I(etherstub) is mutually exclusive with both I(mtu), and I(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 I(mtu) of the desired nic tag. - - Parameters I(mtu) and I(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 I(state) is absent set 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: diff --git a/plugins/modules/nmcli.py b/plugins/modules/nmcli.py index af7bea6cb2..c077c4cbf2 100644 --- a/plugins/modules/nmcli.py +++ b/plugins/modules/nmcli.py @@ -52,22 +52,22 @@ options: description: - The interface to bind the connection to. - The connection will only be applicable to this interface name. - - A special value of C('*') can be used for interface-independent connections. + - 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 C(conn_name) when left unset for all connection types except vpn that removes it. + - 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 C(dummy) is added in community.general 3.5.0. - - Type C(generic) is added in Ansible 2.5. - - Type C(infiniband) is added in community.general 2.0.0. - - Type C(gsm) is added in community.general 3.7.0. - - Type C(macvlan) is added in community.general 6.6.0. - - Type C(wireguard) is added in community.general 4.3.0. - - Type C(vpn) is added in community.general 5.1.0. - - Using C(bond-slave), C(bridge-slave) or C(team-slave) implies C(ethernet) connection type with corresponding I(slave_type) option. - - If you want to control non-ethernet connection attached to C(bond), C(bridge) or C(team) consider using C(slave_type) option. + - Type V(dummy) is added in community.general 3.5.0. + - Type V(generic) is added in Ansible 2.5. + - Type V(infiniband) is added in community.general 2.0.0. + - Type V(gsm) is added in community.general 3.7.0. + - Type V(macvlan) is added in community.general 6.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, vpn ] @@ -85,26 +85,26 @@ options: version_added: 5.8.0 slave_type: description: - - Type of the device of this slave's master connection (for example C(bond)). + - Type of the device of this slave's master connection (for example V(bond)). type: str choices: [ 'bond', 'bridge', 'team' ] version_added: 7.0.0 master: description: - Master