diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 4fd9f5dd773..14adfd6894b 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -61,6 +61,8 @@ If there is no appropriate room for your community, please create it. For more information, see the community-hosted `Matrix FAQ `_. +You can add Matrix shields to your repository's ``README.md`` using the shield in the `community-topics `_ repository as a template. + Ansible community on IRC ------------------------ diff --git a/docs/docsite/rst/community/other_tools_and_programs.rst b/docs/docsite/rst/community/other_tools_and_programs.rst index 5a4c4608ec2..3c79ac719ea 100644 --- a/docs/docsite/rst/community/other_tools_and_programs.rst +++ b/docs/docsite/rst/community/other_tools_and_programs.rst @@ -11,22 +11,13 @@ The Ansible community uses a range of tools for working with the Ansible project If you know of any other tools that should be added, this list can be updated by clicking "Edit on GitHub" on the top right of this page. -*************** -Popular editors -*************** - -Atom -==== - -An open-source, free GUI text editor created and maintained by GitHub. You can keep track of git project -changes, commit from the GUI, and see what branch you are on. You can customize the themes for different colors and install syntax highlighting packages for different languages. You can install Atom on Linux, macOS and Windows. Useful Atom plugins include: -* `language-yaml `_ - YAML highlighting for Atom (built-in). -* `linter-js-yaml `_ - parses your YAML files in Atom through js-yaml. +Popular editors +=============== Emacs -===== +----- A free, open-source text editor and IDE that supports auto-indentation, syntax highlighting and built in terminal shell(among other things). @@ -37,13 +28,13 @@ A free, open-source text editor and IDE that supports auto-indentation, syntax h PyCharm -======= +------- -A full IDE (integrated development environment) for Python software development. It ships with everything you need to write python scripts and complete software, including support for YAML syntax highlighting. It's a little overkill for writing roles/playbooks, but it can be a very useful tool if you write modules and submit code for Ansible. Can be used to debug the Ansible engine. +A full IDE (integrated development environment) for Python software development. It ships with everything you need to write python scripts and complete software, including support for YAML syntax highlighting. It's a little overkill for writing roles/playbooks, but it can be a very useful tool if you write modules and submit code for Ansible. Can be used to debug ``ansible-core``. For more information, see `PyCharm `_ Sublime -======= +------- A closed-source, subscription GUI text editor. You can customize the GUI with themes and install packages for language highlighting and other refinements. You can install Sublime on Linux, macOS and Windows. Useful Sublime plugins include: @@ -54,50 +45,46 @@ A closed-source, subscription GUI text editor. You can customize the GUI with th * `Yamllint `_ - a Sublime wrapper around yamllint. +vim +--- + +An open-source, free command-line text editor. Useful vim plugins include: + +* `Ansible vim `_ - vim syntax plugin for Ansible 2.x, it supports YAML playbooks, Jinja2 templates, and Ansible's hosts files. +* `Ansible vim and neovim plugin `_ - vim plugin (lsp client) for Ansible, it supports autocompletion, syntax highlighting, hover, diagnostics, and goto support. + + Visual studio code -================== +------------------ An open-source, free GUI text editor created and maintained by Microsoft. Useful Visual Studio Code plugins include: * `Ansible extension by Red Hat `_ - provides autocompletion, syntax highlighting, hover, diagnostics, goto support, and command to run ansible-playbook and ansible-navigator tool for both local and execution-environment setups. * `YAML Support by Red Hat `_ - provides YAML support through yaml-language-server with built-in Kubernetes and Kedge syntax support. -vim -=== - -An open-source, free command-line text editor. Useful vim plugins include: -* `Ansible vim `_ - vim syntax plugin for Ansible 2.x, it supports YAML playbooks, Jinja2 templates, and Ansible's hosts files. -* `Ansible vim and neovim plugin `_ - vim plugin (lsp client) for Ansible, it supports autocompletion, syntax highlighting, hover, diagnostics, and goto support. +.. note:: -JetBrains -========= + the Visual Studio Code Ansible extension is maintained by the Ansible community and Red Hat. -An open-source Community edition and closed-source Enterprise edition, integrated development environments based on IntelliJ's framework including IDEA, AppCode, CLion, GoLand, PhpStorm, PyCharm and others. Useful JetBrains platform plugins include: -* `Ansible `_ - general Ansible plugin provides auto-completion, role name suggestion and other handy features for working with playbooks and roles. -* `Ansible Vault Editor `_ - Ansible Vault Editor with auto encryption/decryption. -* `Ansible Lint `__ - Ansible Lint integration with automatic/continuous annotation of errors, warnings, and info while editing. - -***************** Development tools -***************** +================= Finding related issues and PRs -============================== +------------------------------ There are various ways to find existing issues and pull requests (PRs) -- `PR by File `_ - shows a current list of all open pull requests by individual file. An essential tool for Ansible module maintainers. - `jctanner's Ansible Tools `_ - miscellaneous collection of useful helper scripts for Ansible development. .. _validate-playbook-tools: -****************************** + Tools for validating playbooks -****************************** +============================== - `Ansible Lint `_ - a highly configurable linter for Ansible playbooks. - `Ansible Review `_ - an extension of Ansible Lint designed for code review. @@ -105,25 +92,17 @@ Tools for validating playbooks - `yamllint `__ - a command-line utility to check syntax validity including key repetition and indentation issues. -*********** + Other tools -*********** +=========== -- `Ansible cmdb `_ - takes the output of Ansible's fact gathering and converts it into a static HTML overview page containing system configuration information. - `Ansible Inventory Grapher `_ - visually displays inventory inheritance hierarchies and at what level a variable is defined in inventory. -- `Ansible Language Server `_ - a server that implements `language server protocol `_ for Ansible. -- `Ansible Playbook Grapher `_ - a command line tool to create a graph representing your Ansible playbook tasks and roles. - `Ansible Shell `_ - an interactive shell for Ansible with built-in tab completion for all the modules. - `Ansible Silo `_ - a self-contained Ansible environment by Docker. - `Ansigenome `_ - a command line tool designed to help you manage your Ansible roles. - `antsibull-changelog `_ - a changelog generator for Ansible collections. - `antsibull-docs `_ - generates docsites for collections and can validate collection documentation. - `ARA `_ - ARA Records Ansible playbooks and makes them easier to understand and troubleshoot with a reporting API, UI and CLI. -- `Awesome Ansible `_ - a collaboratively curated list of awesome Ansible resources. -- `AWX `_ - provides a web-based user interface, REST API, and task engine built on top of Ansible. Red Hat Ansible Automation Platform includes code from AWX. -- `Mitogen for Ansible `_ - uses the `Mitogen `_ library to execute Ansible playbooks in a more efficient way (decreases the execution time). +- `Awesome Ansible `_ - a collaboratively curated list of awesome Ansible resources. - `nanvault `_ - a standalone tool to encrypt and decrypt files in the Ansible Vault format, featuring UNIX-style composability. - `OpsTools-ansible `_ - uses Ansible to configure an environment that provides the support of `OpsTools `_, namely centralized logging and analysis, availability monitoring, and performance monitoring. -- `Steampunk Spotter `_ - provides an Assisted Automation Writing tool that analyzes and offers recommendations for your Ansible Playbooks. -- `TD4A `_ - a template designer for automation. TD4A is a visual design aid for building and testing jinja2 templates. It will combine data in yaml format with a jinja2 template and render the output. -- `PHP-Ansible `_ - an object oriented Ansible wrapper for PHP. diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 25662f018bd..e1143cf4925 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -544,6 +544,19 @@ Include the ``vars_plugin_staging`` documentation fragment to allow users to det - vars_plugin_staging ''' +At times a value provided by a vars plugin will contain unsafe values. The utility function `wrap_var` provided by `ansible.utils.unsafe_proxy` should be used to ensure that Ansible handles the variable and value correctly. The use cases for unsafe data is covered in :ref:`unsafe_strings`. + +.. code-block:: python + + from ansible.plugins.vars import BaseVarsPlugin + from ansible.utils.unsafe_proxy import wrap_var + + class VarsPlugin(BaseVarsPlugin): + def get_vars(self, loader, path, entities): + return dict( + something_unsafe=wrap_var("{{ SOMETHING_UNSAFE }}") + ) + For example vars plugins, see the source code for the `vars plugins included with Ansible Core `_. diff --git a/docs/docsite/rst/installation_guide/installation_distros.rst b/docs/docsite/rst/installation_guide/installation_distros.rst index f7200416cbd..69f1ff490a1 100644 --- a/docs/docsite/rst/installation_guide/installation_distros.rst +++ b/docs/docsite/rst/installation_guide/installation_distros.rst @@ -3,31 +3,70 @@ Installing Ansible on specific operating systems ================================================ +.. note:: These instructions are provided by their respective communities. Any bugs/issues should be filed with that community to update these instructions. Ansible maintains only the ``pip install`` instructions. + The ``ansible`` package can always be :ref:`installed from PyPI using pip ` on most systems but it is also packaged and maintained by the community for a variety of Linux distributions. The following instructions will guide you through installing the ``ansible`` package with your preferred distribution's package manager. +.. note:: For maintainers who wish to add distributions to this guide, installation instructions are included here only for distributions with a reasonably up-to-date version of ``ansible``. The distribution MUST ensure that ``ansible-core`` and ``ansible`` versions are kept in sync to the extent that the distribution build system allows. Maintainers MUST include a way to contact them with their instructions here and are encouraged to join the `Ansible Packaging `_ Matrix room. + .. contents:: :local: -Installing Ansible on Fedora or CentOS --------------------------------------- +Installing Ansible on Fedora Linux +------------------------------------------------- -On Fedora: +To install the batteries included ``ansible`` package on Fedora run .. code-block:: bash $ sudo dnf install ansible -On CentOS: +If you prefer to install the minimal ``ansible-core`` package run + +.. code-block:: bash + + $ sudo dnf install ansible-core + +Several Ansible collections are also available from the Fedora repositories as +standalone packages that users can install alongside ``ansible-core``. +For example, to install the ``community.general`` collection run .. code-block:: bash - $ sudo yum install epel-release - $ sudo yum install ansible + $ sudo dnf install ansible-collection-community-general + +See the `Fedora Packages index `_ +for a full list of Ansible collections packaged in Fedora. + -RPMs for currently supported versions of CentOS are also available from `EPEL `_. +Please `file a bug `_ against the +``Fedora`` product in Red Hat Bugzilla to reach the package maintainers. + +Installing Ansible from EPEL +---------------------------------- + +Users of CentOS Stream, Almalinux, Rocky Linux, and related distributions +can install ``ansible`` or Ansible collections from the community maintained +`EPEL `_ +(Extra Packages for Enterprise Linux) repository. + +After `enabling the EPEL repository `_, +users can use the same ``dnf`` commands as for Fedora Linux. + +Please `file a bug `_ against the +``Fedora EPEL`` product in Red Hat Bugzilla to reach the package maintainers. + + +Installing Ansible on OpenSUSE Tumbleweed/Leap +---------------------------------------------- + +.. code-block:: bash + $ sudo zypper install ansible + +See `OpenSUSE Support Portal ` for additional help with Ansible on OpenSUSE. .. _from_apt: diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index d8627889f62..32aa7bb9195 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -67,6 +67,8 @@ Selecting an Ansible package and version to install Ansible's community packages are distributed in two ways: a minimalist language and runtime package called ``ansible-core``, and a much larger "batteries included" package called ``ansible``, which adds a community-curated selection of :ref:`Ansible Collections ` for automating a wide variety of devices. Choose the package that fits your needs; The following instructions use ``ansible``, but you can substitute ``ansible-core`` if you prefer to start with a more minimal package and separately install only the Ansible Collections you require. The ``ansible`` or ``ansible-core`` packages may be available in your operating systems package manager, and you are free to install these packages with your preferred method. These installation instructions only cover the officially supported means of installing the python package with ``pip``. +See the :ref:`Ansible package release status table` for the ``ansible-core`` version included in the package. + Installing and upgrading Ansible ================================ diff --git a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst index 805045daa38..947d1060225 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst @@ -154,7 +154,7 @@ You can use blocks with ``flush_handlers`` in a rescue task to ensure that all h ansible.builtin.debug: msg: 'I execute normally' changed_when: true - notify: run me even after an error + notify: Run me even after an error - name: Force a failure ansible.builtin.command: /bin/false diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index deff48bd904..e6de2321c9b 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -351,6 +351,12 @@ To run all tasks except those tagged ``packages``: ansible-playbook example.yml --skip-tags "packages" +To run all tasks, even those excluded because are tagged ``never``: + +.. code-block:: bash + + ansible-playbook example.yml --tags "all,never" + Previewing the results of using tags ------------------------------------ diff --git a/docs/docsite/rst/playbook_guide/playbooks_templating.rst b/docs/docsite/rst/playbook_guide/playbooks_templating.rst index 4382f1573b0..ef0836432d6 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_templating.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_templating.rst @@ -19,6 +19,39 @@ Ansible parses templates on the controller and passes only the information neede .. note:: Files and data used by the :ref:`template module ` must be utf-8 encoded. + +Jinja2 Example +================== + +In this example, we want to write the server hostname to its /tmp/hostname. + +Our directory looks like this: + +.. code-block:: + + ├── hostname.yml + ├── templates + └── test.j2 + +Our hostname.yml: + +.. code-block:: yaml + + --- + - name: Write hostname + hosts: all + tasks: + - name: write hostname using jinja2 + ansible.builtin.template: + src: templates/test.j2 + dest: /tmp/hostname + +Our test.j2: + +.. code-block:: yaml + + My name is {{ ansible_facts['hostname'] }} + .. seealso:: diff --git a/docs/docsite/rst/porting_guides/porting_guide_8.rst b/docs/docsite/rst/porting_guides/porting_guide_8.rst new file mode 100644 index 00000000000..a27aaf0ba41 --- /dev/null +++ b/docs/docsite/rst/porting_guides/porting_guide_8.rst @@ -0,0 +1,405 @@ +.. + THIS DOCUMENT IS AUTOMATICALLY GENERATED BY ANTSIBULL! PLEASE DO NOT EDIT MANUALLY! (YOU PROBABLY WANT TO EDIT porting_guide_core_2.15.rst) + +.. _porting_8_guide: + +======================= +Ansible 8 Porting Guide +======================= + +.. contents:: + :local: + :depth: 2 + + +Ansible 8 is based on Ansible-core 2.15. + + +We suggest you read this page along with the `Ansible 8 Changelog `_ to understand what updates you may need to make. + + +Playbook +======== + +No notable changes + + +Command Line +============ + +* The return code of ``ansible-galaxy search`` is now 0 instead of 1 and the stdout is empty when results are empty to align with other ``ansible-galaxy`` commands. + + +Deprecated +========== + +* Providing a list of dictionaries to ``vars:`` is deprecated in favor of supplying a dictionary. + + Instead of: + + .. code-block:: yaml + + vars: + - var1: foo + - var2: bar + + Use: + + .. code-block:: yaml + + vars: + var1: foo + var2: bar + +Modules +======= + +No notable changes + + +Modules removed +--------------- + +The following modules no longer exist: + +* No notable changes + + +Deprecation notices +------------------- + +No notable changes + + +Noteworthy module changes +------------------------- + +No notable changes + + +Plugins +======= + +No notable changes + + +Porting custom scripts +====================== + +No notable changes + + +Networking +========== + +No notable changes + +Porting Guide for v8.0.0a1 +========================== + +Added Collections +----------------- + +- dellemc.powerflex (version 1.6.0) +- dellemc.unity (version 1.6.0) +- grafana.grafana (version 2.0.0) +- microsoft.ad (version 1.0.0) +- servicenow.servicenow (version 1.0.6) + +Known Issues +------------ + +Ansible-core +~~~~~~~~~~~~ + +- ansible-test - Additional configuration may be required for certain container host and container combinations. Further details are available in the testing documentation. +- ansible-test - Custom containers with ``VOLUME`` instructions may be unable to start, when previously the containers started correctly. Remove the ``VOLUME`` instructions to resolve the issue. Containers with this condition will cause ``ansible-test`` to emit a warning. +- ansible-test - Systems with Podman networking issues may be unable to run containers, when previously the issue went unreported. Correct the networking issues to continue using ``ansible-test`` with Podman. +- ansible-test - Unit tests for collections do not support ``pytest`` assertion rewriting on Python 2.7. +- ansible-test - Using Docker on systems with SELinux may require setting SELinux to permissive mode. Podman should work with SELinux in enforcing mode. +- dnf5 - The DNF5 package manager currently does not provide all functionality to ensure feature parity between the existing ``dnf`` and the new ``dnf5`` module. As a result the following ``dnf5`` options are effectively a no-op: ``cacheonly``, ``enable_plugin``, ``disable_plugin`` and ``lock_timeout``. + +cisco.meraki +~~~~~~~~~~~~ + +- meraki_network - Updated documentation for `local_status_page_enabled` and `remote_status_page_enabled` as these no longer work. + +community.routeros +~~~~~~~~~~~~~~~~~~ + +- api_modify - when limits for entries in ``queue tree`` are defined as human readable - for example ``25M`` -, the configuration will be correctly set in ROS, but the module will indicate the item is changed on every run even when there was no change done. This is caused by the ROS API which returns the number in bytes - for example ``25000000`` (which is inconsistent with the CLI behavior). In order to mitigate that, the limits have to be defined in bytes (those will still appear as human readable in the ROS CLI) (https://github.com/ansible-collections/community.routeros/pull/131). +- api_modify, api_info - ``routing ospf area``, ``routing ospf area range``, ``routing ospf instance``, ``routing ospf interface-template`` paths are not fully implemeted for ROS6 due to the significat changes between ROS6 and ROS7 (https://github.com/ansible-collections/community.routeros/pull/131). + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_firmware - Issue(249879) - Firmware update of iDRAC9-based Servers fails if SOCKS proxy with authentication is used. +- idrac_os_deployment- Issue(260496) - OS installation will support only NFS and CIFS share to store the custom ISO in the destination_path, HTTP/HTTPS/FTP not supported +- idrac_redfish_storage_contoller - Issue(256164) - If incorrect value is provided for one of the attributes in the provided attribute list for controller configuration, then this module does not exit with error. +- idrac_user - Issue(192043) The module may error out with the message ``Unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress``. Wait for the job to complete and run the task again. +- idrac_user - Issue(192043) The module may error out with the message ``unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress``. Wait for the job to complete and run the task again. +- ome_application_alerts_syslog - Issue(215374) - The module does not provide a proper error message if the destination_address is more than 255 characters. +- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the following parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. +- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. +- ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` +- ome_inventory - Issue(256257) - All hosts are not retrieved for ``Modular System`` group and corresponding child groups. +- ome_inventory - Issue(256589) - All hosts are not retrieved for ``Custom Groups`` group and corresponding child groups. +- ome_inventory - Issue(256593) - All hosts are not retrieved for ``PLUGIN GROUPS`` group and corresponding child groups. +- ome_smart_fabric_uplink - Issue(186024) - Despite the module supported by OpenManage Enterprise Modular, it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. +- ome_smart_fabric_uplink - Issue(186024) - The module does not allow the creation of multiple uplinks of the same name even though it is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. + +Breaking Changes +---------------- + +Ansible-core +~~~~~~~~~~~~ + +- ansible-doc - no longer treat plugins in collections whose name starts with ``_`` as deprecated (https://github.com/ansible/ansible/pull/79217). +- ansible-test - Integration tests which depend on specific file permissions when running in an ansible-test managed host environment may require changes. Tests that require permissions other than ``755`` or ``644`` may need to be updated to set the necessary permissions as part of the test run. +- ansible-test - The ``vcenter`` test plugin now defaults to using a user-provided static configuration instead of the ``govcsim`` simulator for collections. Set the ``ANSIBLE_VCSIM_CONTAINER`` environment variable to ``govcsim`` to use the simulator. Keep in mind that the simulator is deprecated and will be removed in a future release. +- ansible-test sanity - previously plugins and modules in collections whose name started with ``_`` were treated as deprecated, even when they were not marked as deprecated in ``meta/runtime.yml``. This is no longer the case (https://github.com/ansible/ansible/pull/79362). +- ansible-test validate-modules - Removed the ``missing-python-doc`` error code in validate modules, ``missing-documentation`` is used instead for missing PowerShell module documentation. + +ansible.netcommon +~~~~~~~~~~~~~~~~~ + +- NetworkConnectionBase now inherits from PersistentConnectionBase in ansible.utils. As a result, the minimum ansible.utils version has increased to 2.7.0. +- NetworkTemplate is no longer importable from ansible_collections.ansible.netcommon.plugins.module_utils.network.common and should now be found at its proper location ansible_collections.ansible.netcommon.plugins.module_utils.network.common.rm_base.network_template +- ResourceModule is no longer importable from ansible_collections.ansible.netcommon.plugins.module_utils.network.common and should now be found at its proper location ansible_collections.ansible.netcommon.plugins.module_utils.network.common.rm_base.resource_module +- VALID_MASKS, is_masklen, is_netmask, to_bits, to_ipv6_network, to_masklen, to_netmask, and to_subnet are no longer importable from ansible_collections.ansible.netcommon.plugins.module_utils.network.common.utils and should now be found at their proper location ansible.module_utils.common.network + +community.general +~~~~~~~~~~~~~~~~~ + +- 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). + +hetzner.hcloud +~~~~~~~~~~~~~~ + +- inventory plugin - Python v3.5+ is now required. + +Major Changes +------------- + +Ansible-core +~~~~~~~~~~~~ + +- ansible-test - Docker Desktop on WSL2 is now supported (additional configuration required). +- ansible-test - Docker and Podman are now supported on hosts with cgroup v2 unified. Previously only cgroup v1 and cgroup v2 hybrid were supported. +- ansible-test - Podman now works on container hosts without systemd. Previously only some containers worked, while others required rootfull or rootless Podman, but would not work with both. Some containers did not work at all. +- ansible-test - Podman on WSL2 is now supported. +- ansible-test - When additional cgroup setup is required on the container host, this will be automatically detected. Instructions on how to configure the host will be provided in the error message shown. + +ansible.windows +~~~~~~~~~~~~~~~ + +- Set the minimum Ansible version supported by this collection to Ansible 2.12 + +chocolatey.chocolatey +~~~~~~~~~~~~~~~~~~~~~ + +- win_chocolatey - Allow users to select the TLS versions used for bootstrapping Chocolatey installation. + +cisco.iosxr +~~~~~~~~~~~ + +- iosxr_l3_interfaces - fix issue in ipv4 address formatting. (https://github.com/ansible-collections/cisco.iosxr/issues/311). + +cisco.meraki +~~~~~~~~~~~~ + +- meraki_mr_l7_firewall - New module +- meraki_webhook_payload_template - New module + +community.hrobot +~~~~~~~~~~~~~~~~ + +- firewall - Hetzner added output rules support to the firewall. This change unfortunately means that using old versions of the firewall module will always set the output rule list to empty, thus disallowing the server to send out packets (https://github.com/ansible-collections/community.hrobot/issues/75, https://github.com/ansible-collections/community.hrobot/pull/76). + +community.vmware +~~~~~~~~~~~~~~~~ + +- Use true/false (lowercase) for boolean values in documentation and examples (https://github.com/ansible-collections/community.vmware/issues/1660). + +community.zabbix +~~~~~~~~~~~~~~~~ + +- all modules are opting away from zabbix-api and using httpapi ansible.netcommon plugin. We will support zabbix-api for backwards compatibility until next major release. See our README.md for more information about how to migrate +- zabbix_agent and zabbix_proxy roles are opting away from zabbix-api and use httpapi ansible.netcommon plugin. We will support zabbix-api for backwards compatibility until next major release. See our README.md for more information about how to migrate + +containers.podman +~~~~~~~~~~~~~~~~~ + +- New become plugin - podman_unshare +- Podman generate systemd module + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- Rebranded from Dell EMC to Dell. +- Support for IPv6 address for OMSDK dependent iDRAC modules. +- idrac_firmware - This module is enhanced to support proxy. +- idrac_redfish_storage_controller - This module is enhanced to configure controller attributes and online capacity expansion. +- idrac_server_config_profile - This module is enhanced to support proxy settings, import buffer, include in export, and ignore certificate warning. +- idrac_user_info - This module allows to retrieve iDRAC Local user information details. +- ome_domian_user_groups - This module allows to import the LDAP directory groups. +- ome_inventory - This plugin allows to create a inventory from the group on OpenManage Enterprise. +- ome_inventory - This plugin is enhanced to support inventory retrieval of System and Plugin Groups of OpenManage Enterprise. +- ome_profile_info - This module allows to retrieve profiles with attributes on OpenManage Enterprise or OpenManage Enterprise Modular. +- ome_smart_fabric_info - This module retrieves the list of smart fabrics in the inventory of OpenManage Enterprise Modular. +- ome_smart_fabric_uplink_info - This module retrieve details of fabric uplink on OpenManage Enterprise Modular. +- ome_template_network_vlan_info - This module allows to retrieve the network configuration of a template on OpenManage Enterprise or OpenManage Enterprise Modular. + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Add annotations of member operation for every module. +- Support FortiOS v7.0.6, v7.0.7, v7.0.8, v7.2.1, v7.2.2. +- Update ``fortios.py`` for higher performance; +- supports temporary session key and pre/post login banner; +- update the examples on how to use member operation in Q&A. + +junipernetworks.junos +~~~~~~~~~~~~~~~~~~~~~ + +- change gathered key from junos_acls to acls + +kubernetes.core +~~~~~~~~~~~~~~~ + +- refactor K8sAnsibleMixin into module_utils/k8s/ (https://github.com/ansible-collections/kubernetes.core/pull/481). + +purestorage.fusion +~~~~~~~~~~~~~~~~~~ + +- Patching of resource properties was brought to parity with underlying Python SDK +- fusion_volume - fixed and reorganized, arguments changed + +Removed Collections +------------------- + +- dellemc.os10 (previously included version: 1.1.1) +- dellemc.os6 (previously included version: 1.0.7) +- dellemc.os9 (previously included version: 1.0.4) +- mellanox.onyx (previously included version: 1.0.0) + +Removed Features +---------------- + +- ``dellemc.os10`` was considered unmaintained and removed from Ansible 8 as per the `removal from Ansible process `_. Users can still install this collection with ``ansible-galaxy collection install dellemc.os10``. +- ``dellemc.os6`` was considered unmaintained and removed from Ansible 8 as per the `removal from Ansible process `_. Users can still install this collection with ``ansible-galaxy collection install dellemc.os6``. +- ``dellemc.os9`` was considered unmaintained and removed from Ansible 8 as per the `removal from Ansible process `_. Users can still install this collection with ``ansible-galaxy collection install dellemc.os9``. +- ``mellanox.onyx`` was considered unmaintained and removed from Ansible 8 as per the `removal from Ansible process `_. Users can still install this collection with ``ansible-galaxy collection install mellanox.onyx``. + +Ansible-core +~~~~~~~~~~~~ + +- Remove deprecated ``ANSIBLE_CALLBACK_WHITELIST`` configuration environment variable, use ``ANSIBLE_CALLBACKS_ENABLED`` instead. (https://github.com/ansible/ansible/issues/78821) +- Remove deprecated ``ANSIBLE_COW_WHITELIST`` configuration environment variable, use ``ANSIBLE_COW_ACCEPTLIST`` instead. (https://github.com/ansible/ansible/issues/78819) +- Remove deprecated ``callback_whitelist`` configuration option, use ``callbacks_enabled`` instead. (https://github.com/ansible/ansible/issues/78822) +- Remove deprecated ``cow_whitelist`` configuration option, use ``cowsay_enabled_stencils`` instead. (https://github.com/ansible/ansible/issues/78820) + +ansible.netcommon +~~~~~~~~~~~~~~~~~ + +- cli_parse - This plugin was moved to ansible.utils in version 1.0.0, and the redirect to that collection has now been removed. + +Deprecated Features +------------------- + +- The cisco.nso collection is considered unmaintained and will be removed from Ansible 9 if no one starts maintaining it again before Ansible 9. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/155). +- The community.fortios collection is considered unmaintained and will be removed from Ansible 9 if no one starts maintaining it again before Ansible 9. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/162). +- The community.google collection is considered unmaintained and will be removed from Ansible 9 if no one starts maintaining it again before Ansible 9. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/160). +- The community.skydive collection is considered unmaintained and will be removed from Ansible 9 if no one starts maintaining it again before Ansible 9. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/171). + +Ansible-core +~~~~~~~~~~~~ + +- The ``ConnectionBase()._new_stdin`` attribute is deprecated, use ``display.prompt_until(msg)`` instead. +- ansible-test - The ``foreman`` test plugin is now deprecated. It will be removed in a future release. +- ansible-test - The ``govcsim`` simulator in the ``vcenter`` test plugin is now deprecated. It will be removed in a future release. Users should switch to providing their own test environment through a static configuration file. +- password_hash - deprecate using passlib.hash.hashtype if hashtype isn't in the list of documented choices. +- vars - Specifying a list of dictionaries for ``vars:`` is deprecated in favor of specifying a dictionary. + +amazon.aws +~~~~~~~~~~ + +- support for passing both profile and security tokens through a mix of environment variables and parameters has been deprecated and support will be removed in release 6.0.0. After release 6.0.0 it will only be possible to pass either a profile or security tokens, regardless of mechanism used to pass them. To explicitly block a parameter coming from an environment variable pass an empty string as the parameter value. Support for passing profile and security tokens together was originally deprecated in release 1.2.0, however only partially implemented in release 5.0.0 (https://github.com/ansible-collections/amazon.aws/pull/1355). + +chocolatey.chocolatey +~~~~~~~~~~~~~~~~~~~~~ + +- win_chocolatey - Deprecate side-by-side installs. + +cisco.ios +~~~~~~~~~ + +- ios_bgp_address_family - deprecate neighbors.address/tag/ipv6_adddress with neighbor_address which enables common attributes for facts rendering +- ios_bgp_address_family - deprecate neighbors.password with password_options which allows encryption and password +- ios_bgp_address_family - deprecate slow_peer with slow_peer_options which supports a dict attribute + +community.aws +~~~~~~~~~~~~~ + +- ecs_service - In a release after 2024-06-01, tha default value of ``purge_placement_constraints`` will be change from ``false`` to ``true`` (https://github.com/ansible-collections/community.aws/pull/1716). +- ecs_service - In a release after 2024-06-01, tha default value of ``purge_placement_strategy`` will be change from ``false`` to ``true`` (https://github.com/ansible-collections/community.aws/pull/1716). +- iam_role - All top level return values other than ``iam_role`` and ``changed`` have been deprecated and will be removed in a release after 2023-12-01 (https://github.com/ansible-collections/community.aws/issues/551). +- iam_role - In a release after 2023-12-01 the contents of ``assume_role_policy_document`` will no longer be converted from CamelCase to snake_case. The ``assume_role_policy_document_raw`` return value already returns the policy document in this future format (https://github.com/ansible-collections/community.aws/issues/551). +- iam_role_info - In a release after 2023-12-01 the contents of ``assume_role_policy_document`` will no longer be converted from CamelCase to snake_case. The ``assume_role_policy_document_raw`` return value already returns the policy document in this future format (https://github.com/ansible-collections/community.aws/issues/551). + +community.dns +~~~~~~~~~~~~~ + +- The default of the newly added option ``txt_character_encoding`` will change from ``octal`` to ``decimal`` in community.dns 3.0.0. The new default will be compatible with `RFC 1035 `__ (https://github.com/ansible-collections/community.dns/pull/134). + +community.general +~~~~~~~~~~~~~~~~~ + +- The ``sap`` modules ``sapcar_extract``, ``sap_task_list_execute``, and ``hana_query``, will be removed from this collection in community.general 7.0.0 and replaced with redirects to ``community.sap_libs``. If you want to continue using these modules, make sure to also install ``community.sap_libs`` (it is part of the Ansible package) (https://github.com/ansible-collections/community.general/pull/5614). +- consul - deprecate using parameters unused for ``state=absent`` (https://github.com/ansible-collections/community.general/pull/5772). +- 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). +- 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). +- manageiq_policies - deprecate ``state=list`` in favour of using ``community.general.manageiq_policies_info`` (https://github.com/ansible-collections/community.general/pull/5721). +- rax - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_cbs - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_cbs_attachments - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_cdb - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_cdb_database - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_cdb_user - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_clb - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_clb_nodes - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_clb_ssl - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_dns - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_dns_record - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_facts - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_files - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_files_objects - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_identity - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_keypair - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_meta - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_mon_alarm - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_mon_check - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_mon_entity - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_mon_notification - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_mon_notification_plan - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_network - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_queue - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_scaling_group - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). +- rax_scaling_policy - module relies on deprecates library ``pyrax``. Unless maintainers step up to work on the module, it will be marked as deprecated in community.general 7.0.0 and removed in version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5733). + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- ansible-core - support for ``ansible-core`` versions ``2.11`` and ``2.12`` will be dropped in collection version ``5.0.0``, making ``2.13`` the minimum supported version of ``ansible-core`` (https://github.com/ansible-collections/community.hashi_vault/issues/340). +- hashi_vault lookup - in ``v5.0.0`` duplicate term string options will raise an exception instead of showing a warning (https://github.com/ansible-collections/community.hashi_vault/issues/356). +- hvac - the minimum version of ``hvac`` to be supported in collection version ``5.0.0`` will be at least ``1.0.2``; this minimum may be raised before ``5.0.0`` is released, so please subscribe to the linked issue and look out for new notices in the changelog (https://github.com/ansible-collections/community.hashi_vault/issues/324). + +purestorage.fusion +~~~~~~~~~~~~~~~~~~ + +- fusion_hw - hardware module is being removed as changing hardware type has never been supported by Pure Storage Fusion +- fusion_info - nigs subset is deprecated in favor of network_interface_groups and will be removed in the version 1.7.0 +- fusion_info - placements subset is deprecated in favor of placement_groups and will be removed in the version 1.7.0 +- fusion_pg - placement_engine option is deprecated because Fusion API does not longer support this parameter It will be removed in the version 2.0.0 +- fusion_se - parameters 'addresses', 'gateway' and 'network_interface_groups' are deprecated in favor of 'iscsi' and will be removed in version 2.0.0 +- fusion_tn - tenant networks are being replaced by storage endpoints ```fusion_se``` and Network Interface Groups ```fusion_nig``` diff --git a/docs/docsite/rst/porting_guides/porting_guides.rst b/docs/docsite/rst/porting_guides/porting_guides.rst index 1e8f6a434bd..b97303d0673 100644 --- a/docs/docsite/rst/porting_guides/porting_guides.rst +++ b/docs/docsite/rst/porting_guides/porting_guides.rst @@ -10,6 +10,7 @@ This section lists porting guides that can help you in updating playbooks, plugi :maxdepth: 1 :glob: + porting_guide_8 porting_guide_7 porting_guide_6 porting_guide_5 diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index d81ec0d0bd5..49bf7453841 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -245,8 +245,8 @@ need to install them into the virtualenv. There are two methods: $ cp -v /usr/lib64/python3.*/site-packages/*selinux*.so ./py3-ansible/lib64/python3.*/site-packages/ -Running on macOS ----------------- +Running on macOS as a controller +-------------------------------- When executing Ansible on a system with macOS as a controller machine one might encounter the following error: @@ -261,6 +261,25 @@ In general the recommended workaround is to set the following environment variab $ export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES +.. _macos_as_a_target_faq: + +Running on macOS as a target +---------------------------- + +When managing a system with macOS Monterey 12, macOS Ventura +13 or above over SSH, the following error can occur: + + .. error:: + "eDSPermissionError" DS Error: -14120 (eDSPermissionError) + +This is a good indication that *Allow full disk access for remote users* has not been enabled. + +.. seealso:: + + For more details, check out `the official Apple user guide article + `_. + + Running on BSD -------------- diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 551ff25fd31..f9bdc825485 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -71,6 +71,7 @@ Work in Collections is tracked within the individual Collection repositories. You can refer to the :ref:`Ansible package porting guides` for tips on updating your playbooks to run on newer versions of Ansible. For Ansible 2.10 and later releases, you can install the Ansible package with ``pip``. See :ref:`intro_installation_guide` for details. You can download older Ansible releases from ``_. +.. _ansible_changelogs: Ansible community changelogs ---------------------------- diff --git a/docs/docsite/rst/scenario_guides/guide_vmware_rest.rst b/docs/docsite/rst/scenario_guides/guide_vmware_rest.rst index e93e352254f..bf6838baa4e 100644 --- a/docs/docsite/rst/scenario_guides/guide_vmware_rest.rst +++ b/docs/docsite/rst/scenario_guides/guide_vmware_rest.rst @@ -4,17 +4,4 @@ VMware REST Scenarios **************************** -These scenarios teach you how to accomplish common VMware tasks using the REST API and the Ansible ``vmware.vmware_rest`` collection. To get started, please select the task you want to accomplish. - -.. toctree:: - :maxdepth: 1 - - vmware_rest_scenarios/installation - vmware_rest_scenarios/authentication - vmware_rest_scenarios/collect_information - vmware_rest_scenarios/create_vm - vmware_rest_scenarios/vm_info - vmware_rest_scenarios/vm_hardware_tuning - vmware_rest_scenarios/run_a_vm - vmware_rest_scenarios/vm_tool_information - vmware_rest_scenarios/vm_tool_configuration +The content on this page has moved to :ref:`ansible_collections.vmware.vmware_rest.docsite.guide_vmware_rest`. diff --git a/docs/templates/playbooks_keywords.rst.j2 b/docs/templates/playbooks_keywords.rst.j2 index 8d42267f24b..c52998c1990 100644 --- a/docs/templates/playbooks_keywords.rst.j2 +++ b/docs/templates/playbooks_keywords.rst.j2 @@ -8,7 +8,7 @@ These are the keywords available on common playbook objects. Keywords are one of .. note:: Please note: - * Aliases for the directives are not reflected here, nor are mutable one. For example, + * Aliases for the directives are not reflected here, nor are mutable ones. For example, :term:`action` in task can be substituted by the name of any Ansible module. * The keywords do not have ``version_added`` information at this time * Some keywords set defaults for the objects inside of them rather than for the objects diff --git a/lib/ansible/modules/apt.py b/lib/ansible/modules/apt.py index 2a214392c25..9c62ecd5535 100644 --- a/lib/ansible/modules/apt.py +++ b/lib/ansible/modules/apt.py @@ -445,7 +445,7 @@ class PolicyRcD(object): def __exit__(self, type, value, traceback): """ - This method will be called when we enter the context, before we call `apt-get …` + This method will be called when we exit the context, after `apt-get …` is done """ # if policy_rc_d is null then we don't need to modify policy-rc.d diff --git a/lib/ansible/modules/apt_key.py b/lib/ansible/modules/apt_key.py index 67caf6da716..94b969030d1 100644 --- a/lib/ansible/modules/apt_key.py +++ b/lib/ansible/modules/apt_key.py @@ -86,11 +86,11 @@ EXAMPLES = ''' - name: somerepo |no apt key ansible.builtin.get_url: url: https://download.example.com/linux/ubuntu/gpg - dest: /etc/apt/trusted.gpg.d/somerepo.asc + dest: /etc/apt/keyrings/somerepo.asc - name: somerepo | apt source ansible.builtin.apt_repository: - repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable" + repo: "deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable" state: present - name: Add an apt key by id from a keyserver diff --git a/lib/ansible/modules/apt_repository.py b/lib/ansible/modules/apt_repository.py index 2718137e359..cbd837417e9 100644 --- a/lib/ansible/modules/apt_repository.py +++ b/lib/ansible/modules/apt_repository.py @@ -138,11 +138,11 @@ EXAMPLES = ''' - name: somerepo |no apt key ansible.builtin.get_url: url: https://download.example.com/linux/ubuntu/gpg - dest: /etc/apt/trusted.gpg.d/somerepo.asc + dest: /etc/apt/keyrings/somerepo.asc - name: somerepo | apt source ansible.builtin.apt_repository: - repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable" + repo: "deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable" state: present ''' diff --git a/lib/ansible/modules/group_by.py b/lib/ansible/modules/group_by.py index ef641f2cf82..0d1e0c8e884 100644 --- a/lib/ansible/modules/group_by.py +++ b/lib/ansible/modules/group_by.py @@ -40,7 +40,7 @@ attributes: become: support: none bypass_host_loop: - support: full + support: none bypass_task_loop: support: none check_mode: diff --git a/lib/ansible/modules/systemd_service.py b/lib/ansible/modules/systemd_service.py index bad29bba67a..d142f865b58 100644 --- a/lib/ansible/modules/systemd_service.py +++ b/lib/ansible/modules/systemd_service.py @@ -90,6 +90,8 @@ notes: - Before 2.4 you always required C(name). - Globs are not supported in name, i.e C(postgres*.service). - The service names might vary by specific OS/distribution + - The order of execution when having multiple properties is to first enable/disable, then mask/unmask and then deal with service state. + It has been reported that systemctl can behave differently depending on the order of operations if you do the same manually. requirements: - A system managed by systemd. ''' diff --git a/lib/ansible/modules/uri.py b/lib/ansible/modules/uri.py index 9740bdd1874..03ba66fa87e 100644 --- a/lib/ansible/modules/uri.py +++ b/lib/ansible/modules/uri.py @@ -257,12 +257,12 @@ EXAMPLES = r''' ansible.builtin.uri: url: http://www.example.com -- name: Check that a page returns a status 200 and fail if the word AWESOME is not in the page contents +- name: Check that a page returns successfully but fail if the word AWESOME is not in the page contents ansible.builtin.uri: url: http://www.example.com return_content: true register: this - failed_when: "'AWESOME' not in this.content" + failed_when: this is failed or "'AWESOME' not in this.content" - name: Create a JIRA issue ansible.builtin.uri: diff --git a/lib/ansible/modules/user.py b/lib/ansible/modules/user.py index a8199628d25..0c26cc28bdf 100644 --- a/lib/ansible/modules/user.py +++ b/lib/ansible/modules/user.py @@ -97,6 +97,8 @@ options: state: description: - Whether the account should exist or not, taking action if the state is different from what is stated. + - See this L(FAQ entry,https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#running-on-macos-as-a-target) + for additional requirements when removing users on macOS systems. type: str choices: [ absent, present ] default: present diff --git a/lib/ansible/modules/validate_argument_spec.py b/lib/ansible/modules/validate_argument_spec.py index e223c94689c..744f1457b53 100644 --- a/lib/ansible/modules/validate_argument_spec.py +++ b/lib/ansible/modules/validate_argument_spec.py @@ -69,7 +69,7 @@ EXAMPLES = r''' - name: verify vars needed for this task file are present when included, with spec from a spec file ansible.builtin.validate_argument_spec: - argument_spec: "{{lookup('ansible.builtin.file', 'myargspec.yml')['specname']['options']}}" + argument_spec: "{{(lookup('ansible.builtin.file', 'myargspec.yml') | from_yaml )['specname']['options']}}" - name: verify vars needed for next include and not from inside it, also with params i'll only define there diff --git a/lib/ansible/plugins/doc_fragments/files.py b/lib/ansible/plugins/doc_fragments/files.py index b87fd11d102..8e4f242fdda 100644 --- a/lib/ansible/plugins/doc_fragments/files.py +++ b/lib/ansible/plugins/doc_fragments/files.py @@ -18,10 +18,11 @@ options: description: - The permissions the resulting filesystem object should have. - For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers. - You must either add a leading zero so that Ansible's YAML parser knows it is an octal number - (like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible receives + You must give Ansible enough information to parse them correctly. + For consistent results, quote octal numbers (for example, C('644') or C('1777')) so Ansible receives a string and can do its own conversion from string into number. - - Giving Ansible a number without following one of these rules will end up with a decimal + Adding a leading zero (for example, C(0755)) works sometimes, but can fail in loops and some other circumstances. + - Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. - As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). diff --git a/lib/ansible/plugins/lookup/password.py b/lib/ansible/plugins/lookup/password.py index 437dff6fa7a..e38d9c43cff 100644 --- a/lib/ansible/plugins/lookup/password.py +++ b/lib/ansible/plugins/lookup/password.py @@ -45,6 +45,9 @@ DOCUMENTATION = """ version_added: "1.4" description: - A list of names that compose a custom character set in the generated passwords. + - This parameter defines the possible character sets in the resulting password, not the required character sets. + If you want to require certain character sets for passwords, you can use the C(community.general.random_string lookup) plugin - + P(community.general.random_string#lookup). - 'By default generated passwords contain a random mix of upper and lowercase ASCII letters, the numbers 0-9, and punctuation (". , : - _").' - "They can be either parts of Python's string module attributes or represented literally ( :, -)." - "Though string modules can vary by Python version, valid values for both major releases include: