From e03069a44438753651e1709654d9a0fd75a6130d Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 21 Apr 2022 17:53:52 -0400 Subject: [PATCH] [docs][backport] Docs backports week 4-18-22 (#77557) * Update reporting_bugs_and_features.rst (#77518) (cherry picked from commit fa7c5d9b104fdf82eecd1d3089c6d42256b789c7) * docs: Add porting guide for Ansible 6.0.0a1 (#77526) (cherry picked from commit 0d9a580f24862cab3d29752d1d07760c025b5bc9) * Steering Committee: add new member (#77529) (cherry picked from commit 553a226da5820decb497d835e6e83b81d669efa9) * Update pip example with standard lowercase http[s]_proxy env vars (#77515) (cherry picked from commit 2ba39fcf8c3fb5257fca741567faac6fdd767b78) * Update docs to recommend the TTY for prompts over stderr (#77533) (cherry picked from commit 789d29e89564f6c3e09e807d889b73e029d3edd9) * update python devel docs (#77499) * update python devel docs Co-authored-by: Sandra McCann (cherry picked from commit 2fc73a9dc357e776dbbbfd035c86fe880415e60a) * setup: remove 'any' as seemingly valid option (#77532) fixes #59783 (cherry picked from commit 762d97f1b835d40d1d7b0542f15cb9a4128526e9) * Update developing_collections_shared.rst (#77497) ##### SUMMARY Use of the meta/runtime.yml file to specify the ansible-core version for collections ##### ISSUE TYPE - Docs Pull Request +label: docsite_pr (cherry picked from commit eef0a1cef986ac5e92a5ae00b6b60ba7be5c77d9) * Update developing_collections_structure.rst (#77496) (cherry picked from commit 538a19b748914e4c7099ad92a07022daae54053d) * Fix a broken link and some grammatical errors (#77531) (cherry picked from commit 0c1cb0e9d45bd8f9584e1b4533cd81b9fa281392) * Add contributor path page (#77494) Co-authored-by: Emmanuel Ugwu <32464178+ugwutotheeshoes@users.noreply.github.com> (cherry picked from commit 3b0d74c14592082b4be5cf8e368e251e3bb6e6d0) Co-authored-by: Iheanacho Amarachi Sharon <58210919+Iheanacho-ai@users.noreply.github.com> Co-authored-by: David Moreau Simard Co-authored-by: Andrew Klychkov Co-authored-by: Junegunn Choi Co-authored-by: Matt Martz Co-authored-by: Brian Coca Co-authored-by: Emmanuel Ugwu <32464178+ugwutotheeshoes@users.noreply.github.com> Co-authored-by: Kajsa Gauza --- .../rst/community/contributor_path.rst | 104 ++++ docs/docsite/rst/community/how_can_I_help.rst | 11 +- docs/docsite/rst/community/index.rst | 1 + .../rst/community/maintainers_guidelines.rst | 11 +- .../community/reporting_bugs_and_features.rst | 7 +- .../steering/community_steering_committee.rst | 2 + .../developing_collections_shared.rst | 2 +- .../developing_collections_structure.rst | 4 +- .../rst/dev_guide/developing_python_3.rst | 56 +- .../rst/porting_guides/porting_guide_6.rst | 484 ++++++++++++++++++ .../rst/porting_guides/porting_guides.rst | 1 + docs/docsite/rst/user_guide/vault.rst | 2 +- docs/docsite/rst/user_guide/windows_dsc.rst | 38 +- lib/ansible/modules/pip.py | 5 +- lib/ansible/modules/setup.py | 6 +- 15 files changed, 662 insertions(+), 72 deletions(-) create mode 100644 docs/docsite/rst/community/contributor_path.rst create mode 100644 docs/docsite/rst/porting_guides/porting_guide_6.rst diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst new file mode 100644 index 00000000000..8b3b0388cea --- /dev/null +++ b/docs/docsite/rst/community/contributor_path.rst @@ -0,0 +1,104 @@ +**************** +Contributor path +**************** + +This section describes the contributor journey from the beginning to becoming a leader who helps shape the future of Ansible. You can use this path as a roadmap for your long-term participation. + +Any contribution to the project, even a small one, is very welcome and valuable. Any contribution counts, whether it's feedback on an issue, a pull request, a topic or documentation change, or a coding contribution. When you contribute regularly, your proficiency and judgment in the related area increase and, along with this, the importance of your presence in the project. + +.. contents:: + :local: + + + +Determine your area of interest +================================= + +First, determine areas that are interesting to you. Consider your current experience and what you'd like to gain. For example, if you use a specific collection, have a look there. See :ref:`how_can_i_help` for more ideas on how to help. + +Find the corresponding project +==================================== + +These are multiple community projects in the Ansible ecosystem you could contribute to: + +- `Ansible Core `_ +- `Collections `_ +- `AWX `_ +- `Galaxy `_ +- `ansible-lint `_ +- `Molecule `_ + +Learn +===== + +The required skillset depends on the area of interest and the project you'll be working on. Remember that the best way to learn is by doing. + +Specific knowledge for code developers +---------------------------------------- + +Code development requires the most technical knowledge. Let's sort out what an Ansible developer should learn. + + +You should understand at least *basics* of the following tools: + +- `Python programming language `_ +- `Git `_ +- `GitHub collaborative development model through forks and pull requests `_ + +You can learn these tools more in depth when working on your first contributions. + + +Each Ansible project has its own set of contributor guidelines. Familarize yourself with these as you prepare your first contributions. + +* :ref:`Ansible Core development `. +* :ref:`Ansible collectoin development ` and the collection-level contributor guidelines in the collection repository. + + +Making your first contribution +============================== + +You can find some ideas on how you can contribute in :ref:`how_can_i_help` and the `collection repository `_ ``README`` and ``CONTRIBUTING`` files. To make your first experience as smooth as possible, read the repository documentation carefully, then ask the repository maintainers for guidance if you have any questions. + +You can also look for GitHub issues labeled with the ``easyfix``, ``good_first_issue``, and ``docs`` labels. Add a comment on the GitHub issue to say you are looking at it and to ask for help if you need it. + +Continue to contribute +====================== + +We don't expect everybody to know everything. Start small, think big. When you contribute regularly, your proficiency and judgment in the related area will improve quickly and, along with this, the importance of your presence in the project. + +See :ref:`communication` for ways to communicate and engage with the Ansible community, including working group meetings, accessing the Bullhorn news bulletin, and upcoming contributor summits. + + +Teach others +============ + +Share your experience with other contributors through `improving documentation `, answering question from other contributors and users on `Matrix/Libera.Chat IRC `, giving advice in issues and pull requests, and discussing the `Community Topics `_. + +Become a collection maintainer +=============================== + +If you are a code contributor to a collection, you can get extended permissions in the repository and become a maintainer. A collection maintainer is a contributor trusted by the community who makes significant and regular contributions to the project and showed themselves as a specialist in the related area. See :ref:`maintainers` for details. + +For some collections that use the `collection bot `_ , such as `community.general `_ and `community.network `_, you can have different levels of access and permissions. + +* `module_maintainers` - The stage prior to becoming a collection maintainer. The file is usually a module or plugin. File maintainers have indirect commit rights. +* supershipit permissions - Similar to being a file maintainer but the scope where a maintainer has the indirect commit is the whole repository. +* ``triage`` - Access to the repository that allows contributors manage issues and pull requests. +* ``write`` access to the repository also known as ``commit``. In other words, become a committer. This access level allows contributors to merge pull requests to the development branch as well as perform all the other activities listed in the :ref:`maintainers`. + +For information about permission levels, see the `GitHub official documentation `_. + +Become a steering committee member +================================== + +.. note:: + + You do NOT have to be a programmer to become a steering committee member. + +The `Steering Committee ` member status reflects the highest level of trust which allows contributors to lead the project through making very important `decisions `_ for the Ansible project. The Committee members are the community leaders who shape the project's future and the future of automation in the IT world in general. + +To reach the status, as the current Committee members did before getting it, along with the things mentioned in this document, you should: + +* Subscribe to, comment on, and vote on the `Community Topics `_. +* Propose your topics. +* If time permits, join the `Community meetings `_ Note this is **NOT** a requirement. \ No newline at end of file diff --git a/docs/docsite/rst/community/how_can_I_help.rst b/docs/docsite/rst/community/how_can_I_help.rst index cf0a64c28ca..ceeea05f467 100644 --- a/docs/docsite/rst/community/how_can_I_help.rst +++ b/docs/docsite/rst/community/how_can_I_help.rst @@ -48,7 +48,10 @@ If there is no meetup near you, we are happy to help you `start one `. +All software has bugs, and Ansible is no exception. When you find a bug, you can help tremendously by telling us about it: + +* Filing :ref:`issues for ansible-core `. +* Filing :ref:`issues for collections `. If the bug you found already exists in an issue, you can help by verifying the behavior of the reported bug with a comment in that issue, or by reporting any additional information. @@ -56,16 +59,16 @@ If the bug you found already exists in an issue, you can help by verifying the b Review and submit pull requests =============================== -As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you have a fix for a bug in Ansible, or if you have a new feature that you would like to share with millions of Ansible users, read all about the :ref:`Ansible development process ` and and :ref:`how to contribute to collections ` to learn how to get your code accepted into Ansible. +As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you have a fix for a bug in Ansible, or if you have a new feature that you would like to share with millions of Ansible users, read all about the :ref:`development process ` to learn how to get your code accepted into Ansible. -Another good way to help is to review pull requests that other Ansible users have submitted. The Ansible community keeps a full list of `open pull requests by file `_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. +Another good way to help is to review pull requests that other Ansible users have submitted. Ansible core keeps a full list of `open pull requests by file `_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Alternately, you can review the pull requests for any collections that interest you. Click :guilabel:`Issue tracker` on the collection documentation page to find the issues and PRs for that collection. Become a collection maintainer ============================== Once you have learned about the development process and have contributed code to a collection, we encourage you to become a maintainer of that collection. There are hundreds of modules in dozens of Ansible collections, and the vast majority of them are written and maintained entirely by members of the Ansible community. -To learn more about the responsibilities of being an Ansible module maintainer, please read our :ref:`collection maintainer guidelines `. + See :ref:`collection maintainer guidelines ` to learn more about the responsibilities of being an Ansible collection maintainer. .. _community_working_groups: diff --git a/docs/docsite/rst/community/index.rst b/docs/docsite/rst/community/index.rst index 81d394f2dea..e8ae75708bf 100644 --- a/docs/docsite/rst/community/index.rst +++ b/docs/docsite/rst/community/index.rst @@ -21,3 +21,4 @@ The purpose of this guide is to teach you everything you need to know about bein :maxdepth: 2 getting_started + contributor_path diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index c6843e79fa0..7a51de24f90 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -108,7 +108,16 @@ Promote active contributors satisfying :ref:`requirements`_ and during the next Contributor Summit congratulating and thanking them for the work done. You can mention all the people promoted since the previous summit. Remember to invite the other maintainers to the Summit in advance. - +Some other general guidelines to encourage contributors: + +* Welcome the author and thank them for the issue or pull request. +* If there is a non-crucial easy-fix bug reported, politely ask the author to fix it themselves providing a link to :ref:`collection_quickstart`. +* When suggesting changes, try to use questions, not statements. +* When suggesting mandatory changes, do it as politely as possible providing documentation references. +* If your suggestion is optional or a matter of personal preferences, please say it explicitly. +* When asking for adding tests or for complex code refactoring, say that the author is welcome to ask for clarifications and help if they need. +* If somebody suggests a good idea, mention it or put a thumbs up. +* After merging, thank the author and reviewers for their time and effort. .. _maintainer_documentation: diff --git a/docs/docsite/rst/community/reporting_bugs_and_features.rst b/docs/docsite/rst/community/reporting_bugs_and_features.rst index 49ba8ed595a..a972603af36 100644 --- a/docs/docsite/rst/community/reporting_bugs_and_features.rst +++ b/docs/docsite/rst/community/reporting_bugs_and_features.rst @@ -16,7 +16,7 @@ Reporting a bug Security bugs ------------- -Ansible practices responsible disclosure - for security-related bugs, email `security@ansible.com `_ to receive a prompt response. Do not submit a ticket or post to any public groups. +Ansible practices responsible disclosure. To report security-related bugs, send an email to `security@ansible.com `_ for an immediate response. Do not submit a ticket or post to any public groups. Bugs in ansible-core -------------------- @@ -39,14 +39,15 @@ If you find a bug, open an issue using the `issue template `_ when sharing YAML in playbooks. For multiple-file content, use gist.github.com, which is more durable than pastebin content. +When sharing YAML in playbooks, ensure that you preserve formatting using `code blocks `_. For multiple-file content, use gist.github.com, more durable than Pastebin content. .. _request_features: diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index 6fc220ee2e0..2c933b0ea16 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -53,6 +53,8 @@ The following table lists the current Steering Committee members. See :ref:`stee +------------------+---------------+-------------+ | John Barker | gundalow | 2021 | +------------------+---------------+-------------+ + | Mario Lenz | mariolenz | 2022 | + +------------------+---------------+-------------+ | Markus Bergholz | markuman | 2022 | +------------------+---------------+-------------+ | Sorin Sbarnea | ssbarnea | 2021 | diff --git a/docs/docsite/rst/dev_guide/developing_collections_shared.rst b/docs/docsite/rst/dev_guide/developing_collections_shared.rst index 6a2f5251df9..bddb94c9e61 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_shared.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_shared.rst @@ -70,7 +70,7 @@ The optional import behavior also applies to module_utils imported from collecti Listing collection dependencies =============================== -We recommend that collections work as standalone, independent units, depending only on ansible-core. However, if your collection must depend on features and functionality from another collection, list the other collection or collections under ``dependencies`` in your collection's :file:`galaxy.yml` file. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`. +We recommend that collections work as standalone, independent units, depending only on ansible-core. However, if your collection must depend on features and functionality from another collection, list the other collection or collections under ``dependencies`` in your collection's :file:`galaxy.yml` file. Use the :file:`meta/runtime.yml` file to set the ansible-core version that your collection depends on. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`. You can use git repositories for collection dependencies during local development and testing. For example: diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 0c3f7392f15..585087a4c88 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -198,8 +198,8 @@ When reading the :ref:`developing_testing` documentation, there will be content .. _meta_runtime_yml: -meta directory --------------- +meta directory and runtime.yml +------------------------------ A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys: diff --git a/docs/docsite/rst/dev_guide/developing_python_3.rst b/docs/docsite/rst/dev_guide/developing_python_3.rst index 23b94767ad8..43221b0342e 100644 --- a/docs/docsite/rst/dev_guide/developing_python_3.rst +++ b/docs/docsite/rst/dev_guide/developing_python_3.rst @@ -4,47 +4,31 @@ Ansible and Python 3 ******************** -The ``ansible-core`` code runs on both Python 2 and Python 3 because we want Ansible to be able to manage a wide -variety of machines. Contributors to ansible-core and to Ansible Collections should be aware of the tips in this document so that they can write code that will run on the same versions of Python as the rest of Ansible. +The ``ansible-core`` code runs Python 3 (for specific versions check `Control Node Requirements <:ref:control-node-requirements>`_. +Contributors to ``ansible-core`` and to Ansible Collections should be aware of the tips in this document so that they can write code +that will run on the same versions of Python as the rest of Ansible. .. contents:: :local: -To ensure that your code runs on Python 3 as well as on Python 2, learn the tips and tricks and idioms -described here. Most of these considerations apply to all three types of Ansible code: +We do have some considerations depending on the types of Ansible code: -1. controller-side code - code that runs on the machine where you invoke :command:`/usr/bin/ansible` -2. modules - the code which Ansible transmits to and invokes on the managed machine. -3. shared ``module_utils`` code - the common code that's used by modules to perform tasks and sometimes used by controller-side code as well +1. controller-side code - code that runs on the machine where you invoke :command:`/usr/bin/ansible`, only needs to support the controller's Python versions. +2. modules - the code which Ansible transmits to and invokes on the managed machine. Modules need to support the 'managed node' Python versions, with some exceptions. +3. shared ``module_utils`` code - the common code that is used by modules to perform tasks and sometimes used by controller-side code as well. Shared ``module_utils`` code needs to support the same range of Python as the modules. However, the three types of code do not use the same string strategy. If you're developing a module or some ``module_utils`` code, be sure to read the section on string strategy carefully. +.. note: + - While modules can be written in any language, the above applies to code contributed to the core project, which only supports specific Python versions and Powershell for Windows. + Minimum version of Python 3.x and Python 2.x ============================================ -On the controller we support Python 3.5 or greater and Python 2.7 or greater. Module-side, we -support Python 3.5 or greater and Python 2.6 or greater. - -Python 3.5 was chosen as a minimum because it is the earliest Python 3 version adopted as the -default Python by a Long Term Support (LTS) Linux distribution (in this case, Ubuntu-16.04). -Previous LTS Linux distributions shipped with a Python 2 version which users can rely upon instead -of the Python 3 version. - -For Python 2, the default is for modules to run on at least Python 2.6. This allows -users with older distributions that are stuck on Python 2.6 to manage their -machines. Modules are allowed to drop support for Python 2.6 when one of -their dependent libraries requires a higher version of Python. This is not an -invitation to add unnecessary dependent libraries in order to force your -module to be usable only with a newer version of Python; instead it is an -acknowledgment that some libraries (for instance, boto3 and docker-py) will -only function with a newer version of Python. - -.. note:: Python 2.4 Module-side Support: +See `Control Node Requirements <:ref:control-node-requirements>`_ and `Managed Node Requirements <:ref:managed-node-requirements>`_ for the +specific versions supported. - Support for Python 2.4 and Python 2.5 was dropped in Ansible-2.4. RHEL-5 - (and its rebuilds like CentOS-5) were supported until April of 2017. - Ansible-2.3 was released in April of 2017 and was the last Ansible release - to support Python 2.4 on the module-side. +Your custom modules can support any version of Python (or other languages) you want, but the above are the requirements for the code contributed to the Ansible project. Developing Ansible code that supports Python 2 and Python 3 =========================================================== @@ -90,7 +74,7 @@ Ansible uses different strategies for working with strings in controller-side co Controller string strategy: the Unicode Sandwich ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In controller-side code we use a strategy known as the Unicode Sandwich (named +Until recently ``ansible-core`` supported Python 2.x and followed this strategy, known as the Unicode Sandwich (named after Python 2's :func:`unicode ` text type). For Unicode Sandwich we know that at the border of our code and the outside world (for example, file and network IO, environment variables, and some library calls) we are going to receive bytes. @@ -100,6 +84,13 @@ the outside world we first convert the text back into bytes. To visualize this, imagine a 'sandwich' consisting of a top and bottom layer of bytes, a layer of conversion between, and all text type in the center. +For compatibility reasons you will see a bunch of custom functions we developed (``to_text``/``to_bytes``/``to_native``) +and while Python 2 is not a concern anymore we will continue to use them as they apply for other cases that make +dealing with unicode problematic. + +While we will not be using it most of it anymore, the documentation below is still useful for those developing modules +that still need to support both Python 2 and 3 simultaneouslly. + Unicode Sandwich common borders: places to convert bytes to text in controller code ----------------------------------------------------------------------------------- @@ -400,8 +391,3 @@ does have support for the older, percent-formatting. Python documentation on `percent formatting `_ .. _testing_modules_python_3: - -Testing modules on Python 3 -=================================== - -Ansible modules are slightly harder to code to support Python 3 than normal code from other projects. A lot of mocking has to go into unit testing an Ansible module, so it's harder to test that your changes have fixed everything or to to make sure that later commits haven't regressed the Python 3 support. Review our :ref:`testing ` pages for more information. diff --git a/docs/docsite/rst/porting_guides/porting_guide_6.rst b/docs/docsite/rst/porting_guides/porting_guide_6.rst new file mode 100644 index 00000000000..418f64ca654 --- /dev/null +++ b/docs/docsite/rst/porting_guides/porting_guide_6.rst @@ -0,0 +1,484 @@ +.. + THIS DOCUMENT IS AUTOMATICALLY GENERATED BY ANTSIBULL! PLEASE DO NOT EDIT MANUALLY! (YOU PROBABLY WANT TO EDIT porting_guide_core_2.13.rst) + +.. _porting_6_guide: + +======================= +Ansible 6 Porting Guide +======================= + +.. contents:: + :local: + :depth: 2 + + +Ansible 6 is based on Ansible-core 2.13. + + +We suggest you read this page along with the `Ansible 6 Changelog `_ to understand what updates you may need to make. + + +Playbook +======== + +* Templating - You can no longer perform arithmetic and concatenation operations outside of the jinja template. The following statement will need to be rewritten to produce ``[1, 2]``: + + .. code-block:: yaml + + - name: Prior to 2.13 + debug: + msg: '[1] + {{ [2] }}' + + - name: 2.13 and forward + debug: + msg: '{{ [1] + [2] }}' + +* The return value of the ``__repr__`` method of an undefined variable represented by the ``AnsibleUndefined`` object changed. ``{{ '%r'|format(undefined_variable) }}`` returns ``AnsibleUndefined(hint=None, obj=missing, name='undefined_variable')`` in 2.13 as opposed to just ``AnsibleUndefined`` in versions 2.12 and prior. + +* The ``finalize`` method is no longer exposed in the globals for use in templating. To convert ``None`` to an empty string the following expression can be used: ``{{ value if value is not none }}``. + + +Command Line +============ + +No notable changes + + +Deprecated +========== + +No notable changes + + +Modules +======= + +* To use ansible-core 2.13 for module execution, you must use Python 2 version 2.7 or Python 3 version 3.5 or newer. Any code utilizing ``ansible.module_utils.basic`` will not function with lower Python versions. + + +Modules removed +--------------- + +The following modules no longer exist: + +* No notable changes + + +Deprecation notices +------------------- + +No notable changes + + +Noteworthy module changes +------------------------- + +No notable changes + + +Breaking Changes +---------------- + +* ``ansible.module_utils.urls.fetch_url`` will now return the captured ``HTTPError`` exception as ``r``. ``HTTPError`` is a response like object that can offer more information to module authors. Modules should rely on ``info['status'] >= 400`` to determine if there was a failure, instead of using ``r is None`` or catching ``AttributeError`` when attempting ``r.read()``. + + +Plugins +======= + +No notable changes + + +Porting custom scripts +====================== + +No notable changes + + +Networking +========== + +No notable changes + +Porting Guide for v6.0.0a1 +========================== + +Added Collections +----------------- + +- community.sap (version 1.0.0) + +Known Issues +------------ + +Ansible-core +~~~~~~~~~~~~ + +- get_url - document ``check_mode`` correctly with unreliable changed status (https://github.com/ansible/ansible/issues/65687). + +community.general +~~~~~~~~~~~~~~~~~ + +- pacman - ``update_cache`` cannot differentiate between up to date and outdated package lists and will report ``changed`` in both situations (https://github.com/ansible-collections/community.general/pull/4318). +- pacman - binaries specified in the ``executable`` parameter must support ``--print-format`` in order to be used by this module. In particular, AUR helper ``yay`` is known not to currently support it (https://github.com/ansible-collections/community.general/pull/4312). + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- 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_smtp - Issue(212310) - The module does not provide a proper error message if the destination_address is more than 255 characters. +- 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_application_console_preferences - Issue(224690) - The module does not display a proper error message when an unsupported value is provided for the parameters report_row_limit, email_sender_settings, and metric_collection_settings, and the value is applied on OpenManage Enterprise. +- ome_device_local_access_configuration - Issue(215035) - The module reports ``Successfully updated the local access setting`` if an unsupported value is provided for the parameter timeout_limit. However, this value is not actually applied on OpenManage Enterprise Modular. +- ome_device_local_access_configuration - Issue(217865) - The module does not display a proper error message if an unsupported value is provided for the user_defined and lcd_language parameters. +- 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_device_power_settings - Issue(212679) - The module errors out with 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_device_power_settings - Issue(212679) - The module errors out with 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_device_quick_deploy - Issue(216352) - The module does not display a proper error message if an unsupported value is provided for the ipv6_prefix_length and vlan_id parameters. +- 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. + +purestorage.flasharray +~~~~~~~~~~~~~~~~~~~~~~ + +- purefa_admin - Once `max_login` and `lockout` have been set there is currently no way to rest these to zero except through the FlashArray GUI + +Breaking Changes +---------------- + +Ansible-core +~~~~~~~~~~~~ + +- Module Python Dependency - Drop support for Python 2.6 in module execution. +- Templating - it is no longer allowed to perform arithmetic and concatenation operations outside of the jinja template (https://github.com/ansible/ansible/pull/75587) +- The ``finalize`` method is no longer exposed in the globals for use in templating. + +amazon.aws +~~~~~~~~~~ + +- aws_caller_facts - Remove deprecated ``aws_caller_facts`` alias. Please use ``aws_caller_info`` instead. +- cloudformation_facts - Remove deprecated ``cloudformation_facts`` alias. Please use ``cloudformation_info`` instead. +- ec2_ami_facts - Remove deprecated ``ec2_ami_facts`` alias. Please use ``ec2_ami_info`` instead. +- ec2_eni_facts - Remove deprecated ``ec2_eni_facts`` alias. Please use ``ec2_eni_info`` instead. +- ec2_group_facts - Remove deprecated ``ec2_group_facts`` alias. Please use ``ec2_group_info`` instead. +- ec2_instance_facts - Remove deprecated ``ec2_instance_facts`` alias. Please use ``ec2_instance_info`` instead. +- ec2_snapshot_facts - Remove deprecated ``ec2_snapshot_facts`` alias. Please use ``ec2_snapshot_info`` instead. +- ec2_vol_facts - Remove deprecated ``ec2_vol_facts`` alias. Please use ``ec2_vol_info`` instead. +- ec2_vpc_dhcp_option_facts - Remove deprecated ``ec2_vpc_dhcp_option_facts`` alias. Please use ``ec2_vpc_dhcp_option_info`` instead. +- ec2_vpc_endpoint_facts - Remove deprecated ``ec2_vpc_endpoint_facts`` alias. Please use ``ec2_vpc_endpoint_info`` instead. +- ec2_vpc_igw_facts - Remove deprecated ``ec2_vpc_igw_facts`` alias. Please use ``ec2_vpc_igw_info`` instead. +- ec2_vpc_nat_gateway_facts - Remove deprecated ``ec2_vpc_nat_gateway_facts`` alias. Please use ``ec2_vpc_nat_gateway_info`` instead. +- ec2_vpc_net_facts - Remove deprecated ``ec2_vpc_net_facts`` alias. Please use ``ec2_vpc_net_info`` instead. +- ec2_vpc_route_table_facts - Remove deprecated ``ec2_vpc_route_table_facts`` alias. Please use ``ec2_vpc_route_table_info`` instead. +- ec2_vpc_subnet_facts - Remove deprecated ``ec2_vpc_subnet_facts`` alias. Please use ``ec2_vpc_subnet_info`` instead. + +arista.eos +~~~~~~~~~~ + +- eos_command - new suboption ``version`` of parameter ``command``, which controls the JSON response version. Previously the value was assumed to be "latest" for network_cli and "1" for httpapi, but the default will now be "latest" for both connections. This option is also available for use in modules making their own device requests with ``plugins.module_utils.network.eos.eos.run_commands()`` with the same new default behavior. (https://github.com/ansible-collections/arista.eos/pull/258). + +community.aws +~~~~~~~~~~~~~ + +- aws_acm_facts - Remove deprecated alias ``aws_acm_facts``. Please use ``aws_acm_info`` instead. +- aws_kms_facts - Remove deprecated alias ``aws_kms_facts``. Please use ``aws_kms_info`` instead. +- aws_kms_info - Deprecated ``keys_attr`` field is now ignored (https://github.com/ansible-collections/community.aws/pull/838). +- aws_region_facts - Remove deprecated alias ``aws_region_facts``. Please use ``aws_region_info`` instead. +- aws_s3_bucket_facts - Remove deprecated alias ``aws_s3_bucket_facts``. Please use ``aws_s3_bucket_info`` instead. +- aws_sgw_facts - Remove deprecated alias ``aws_sgw_facts``. Please use ``aws_sgw_info`` instead. +- aws_waf_facts - Remove deprecated alias ``aws_waf_facts``. Please use ``aws_waf_info`` instead. +- cloudfront_facts - Remove deprecated alias ``cloudfront_facts``. Please use ``cloudfront_info`` instead. +- cloudwatchlogs_log_group_facts - Remove deprecated alias ``cloudwatchlogs_log_group_facts``. Please use ``cloudwatchlogs_log_group_info`` instead. +- dynamodb_table - deprecated updates currently ignored for primary keys and global_all indexes will now result in a failure. (https://github.com/ansible-collections/community.aws/pull/837). +- ec2_asg_facts - Remove deprecated alias ``ec2_asg_facts``. Please use ``ec2_asg_info`` instead. +- ec2_customer_gateway_facts - Remove deprecated alias ``ec2_customer_gateway_facts``. Please use ``ec2_customer_gateway_info`` instead. +- ec2_eip_facts - Remove deprecated alias ``ec2_eip_facts``. Please use ``ec2_eip_info`` instead. +- ec2_elb_facts - Remove deprecated alias ``ec2_elb_facts``. Please use ``ec2_elb_info`` instead. +- ec2_elb_info - The ``ec2_elb_info`` module has been removed. Please use ``the ``elb_classic_lb_info`` module. +- ec2_lc_facts - Remove deprecated alias ``ec2_lc_facts``. Please use ``ec2_lc_info`` instead. +- ec2_placement_group_facts - Remove deprecated alias ``ec2_placement_group_facts``. Please use ``ec2_placement_group_info`` instead. +- ec2_vpc_nacl_facts - Remove deprecated alias ``ec2_vpc_nacl_facts``. Please use ``ec2_vpc_nacl_info`` instead. +- ec2_vpc_peering_facts - Remove deprecated alias ``ec2_vpc_peering_facts``. Please use ``ec2_vpc_peering_info`` instead. +- ec2_vpc_route_table_facts - Remove deprecated alias ``ec2_vpc_route_table_facts``. Please use ``ec2_vpc_route_table_info`` instead. +- ec2_vpc_vgw_facts - Remove deprecated alias ``ec2_vpc_vgw_facts``. Please use ``ec2_vpc_vgw_info`` instead. +- ec2_vpc_vpn_facts - Remove deprecated alias ``ec2_vpc_vpn_facts``. Please use ``ec2_vpc_vpn_info`` instead. +- ecs_service_facts - Remove deprecated alias ``ecs_service_facts``. Please use ``ecs_service_info`` instead. +- ecs_taskdefinition_facts - Remove deprecated alias ``ecs_taskdefinition_facts``. Please use ``ecs_taskdefinition_info`` instead. +- efs_facts - Remove deprecated alias ``efs_facts``. Please use ``efs_info`` instead. +- elasticache_facts - Remove deprecated alias ``elasticache_facts``. Please use ``elasticache_info`` instead. +- elb_application_lb_facts - Remove deprecated alias ``elb_application_lb_facts``. Please use ``elb_application_lb_info`` instead. +- elb_classic_lb_facts - Remove deprecated alias ``elb_classic_lb_facts``. Please use ``elb_classic_lb_info`` instead. +- elb_target_facts - Remove deprecated alias ``elb_target_facts``. Please use ``elb_target_info`` instead. +- elb_target_group_facts - Remove deprecated alias ``elb_target_group_facts``. Please use ``elb_target_group_info`` instead. +- iam - Removed deprecated ``community.aws.iam`` module. Please use ``community.aws.iam_user``, ``community.aws.iam_access_key`` or ``community.aws.iam_group`` (https://github.com/ansible-collections/community.aws/pull/839). +- iam_cert_facts - Remove deprecated alias ``iam_cert_facts``. Please use ``iam_cert_info`` instead. +- iam_mfa_device_facts - Remove deprecated alias ``iam_mfa_device_facts``. Please use ``iam_mfa_device_info`` instead. +- iam_role_facts - Remove deprecated alias ``iam_role_facts``. Please use ``iam_role_info`` instead. +- iam_server_certificate_facts - Remove deprecated alias ``iam_server_certificate_facts``. Please use ``iam_server_certificate_info`` instead. +- lambda_facts - Remove deprecated module lambda_facts``. Please use ``lambda_info`` instead. +- rds - Removed deprecated ``community.aws.rds`` module. Please use ``community.aws.rds_instance`` (https://github.com/ansible-collections/community.aws/pull/839). +- rds_instance_facts - Remove deprecated alias ``rds_instance_facts``. Please use ``rds_instance_info`` instead. +- rds_snapshot_facts - Remove deprecated alias ``rds_snapshot_facts``. Please use ``rds_snapshot_info`` instead. +- redshift_facts - Remove deprecated alias ``redshift_facts``. Please use ``redshift_info`` instead. +- route53_facts - Remove deprecated alias ``route53_facts``. Please use ``route53_info`` instead. + +community.mysql +~~~~~~~~~~~~~~~ + +- mysql_replication - remove ``Is_Slave`` and ``Is_Master`` return values (were replaced with ``Is_Primary`` and ``Is_Replica`` (https://github.com/ansible-collections /community.mysql/issues/145). +- mysql_replication - remove the mode options values containing ``master``/``slave`` and the master_use_gtid option ``slave_pos`` (were replaced with corresponding ``primary``/``replica`` values) (https://github.com/ansible-collections/community.mysql/issues/145). +- mysql_user - remove support for the `REQUIRESSL` special privilege as it has ben superseded by the `tls_requires` option (https://github.com/ansible-collections/community.mysql/discussions/121). +- mysql_user - validate privileges using database engine directly (https://github.com/ansible-collections/community.mysql/issues/234 https://github.com/ansible-collections/community.mysql/pull/243). Do not validate privileges in this module anymore. + +community.vmware +~~~~~~~~~~~~~~~~ + +- The collection now requires at least ansible-core 2.11.0. Ansible 3 and before, and ansible-base versions are no longer supported. +- vmware_cluster_drs - The default for ``enable`` has been changed from ``false`` to ``true``. +- vmware_cluster_drs - The parameter alias ``enable_drs`` has been removed, use ``enable`` instead. +- vmware_cluster_ha - The default for ``enable`` has been changed from ``false`` to ``true``. +- vmware_cluster_ha - The parameter alias ``enable_ha`` has been removed, use ``enable`` instead. +- vmware_cluster_vsan - The default for ``enable`` has been changed from ``false`` to ``true``. +- vmware_cluster_vsan - The parameter alias ``enable_vsan`` has been removed, use ``enable`` instead. +- vmware_guest - Virtualization Based Security has some requirements (``nested_virt``, ``secure_boot`` and ``iommu``) that the module silently enabled. They have to be enabled explicitly now. + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- HTTPS SSL certificate validation is a **breaking change** and will require modification in the existing playbooks. Please refer to `SSL Certificate Validation `_ section in the `README.md `_ for modification to existing playbooks. + +theforeman.foreman +~~~~~~~~~~~~~~~~~~ + +- Set use_reports_api default value to true for the inventory plugin +- Support for Ansible 2.8 is removed + +Major Changes +------------- + +Ansible-core +~~~~~~~~~~~~ + +- Jinja2 Controller Requirement - Jinja2 3.0.0 or newer is required for the control node (the machine that runs Ansible) (https://github.com/ansible/ansible/pull/75881) +- Templating - remove ``safe_eval`` in favor of using ``NativeEnvironment`` but utilizing ``literal_eval`` only in cases when ``safe_eval`` was used (https://github.com/ansible/ansible/pull/75587) + +amazon.aws +~~~~~~~~~~ + +- amazon.aws collection - The amazon.aws collection has dropped support for ``botocore<1.19.0`` and ``boto3<1.16.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/amazon.aws/pull/574). + +chocolatey.chocolatey +~~~~~~~~~~~~~~~~~~~~~ + +- win_chocolatey - Added choco_args option to pass additional arguments directly to Chocolatey. + +cisco.ise +~~~~~~~~~ + +- Update ciscoisesdk requirement to 1.2.0 +- anc_endpoint_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- anc_policy_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- backup_last_status_info - change return value, it returns response content. +- device_administration_authentication_rules - deletes parameter identitySourceId. +- device_administration_authentication_rules_info - change return value, it returns response content. +- device_administration_authorization_rules_info - change return value, it returns response content. +- device_administration_conditions - deletes parameter attributeId. +- device_administration_conditions_for_authentication_rule_info - change return value, it returns response content. +- device_administration_conditions_for_authorization_rule_info - change return value, it returns response content. +- device_administration_conditions_for_policy_set_info - change return value, it returns response content. +- device_administration_conditions_info - change return value, it returns response content. +- device_administration_dictionary_attributes_authentication_info - change return value, it returns response content. +- device_administration_dictionary_attributes_authorization_info - change return value, it returns response content. +- device_administration_dictionary_attributes_policy_set_info - change return value, it returns response content. +- device_administration_global_exception_rules_info - change return value, it returns response content. +- device_administration_network_conditions_info - change return value, it returns response content. +- device_administration_time_date_conditions - deletes parameter attributeId. +- device_administration_time_date_conditions_info - change return value, it returns response content. +- egress_matrix_cell_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- network_access_authentication_rules - deletes parameter identitySourceId. +- network_access_conditions - deletes parameter attributeId. +- network_access_time_date_conditions - deletes parameter attributeId. +- node_deployment - update parameters. +- node_deployment_info - add filter and filterType parameters. +- node_group - fixes response recollection. +- node_group_info - fixes response recollection. +- repository_files_info - change return value, it returns response content. +- repository_info - change return value, it returns response content. +- sg_acl_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- sg_mapping_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- sg_mapping_group_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- sg_mapping_group_info - change return value, it returns BulkStatus content. +- sg_to_vn_to_vlan_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- sgt - change generationId type from int to str. +- sgt_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- sxp_connections_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- sxp_local_bindings_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- sxp_vpns_bulk_monitor_status_info - change return value, it returns BulkStatus content. +- system_certificate - new parameters portalTagTransferForSameSubject and roleTransferForSameSubject. +- system_certificate - portalTagTransferForSameSubject parameter renamed to allowPortalTagTransferForSameSubject. +- system_certificate - roleTransferForSameSubject parameter renamed to allowRoleTransferForSameSubject. +- system_certificate_import - new parameters portalTagTransferForSameSubject and roleTransferForSameSubject. +- system_certificate_import - portalTagTransferForSameSubject parameter renamed to allowPortalTagTransferForSameSubject. +- system_certificate_import - roleTransferForSameSubject parameter renamed to allowRoleTransferForSameSubject. +- trustsec_nbar_app_info - change type from str to list. +- trustsec_vn_info - change type from str to list. + +cisco.meraki +~~~~~~~~~~~~ + +- meraki_mr_radio - New module + +community.aws +~~~~~~~~~~~~~ + +- community.aws collection - The community.aws collection has dropped support for ``botocore<1.19.0`` and ``boto3<1.16.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/community.aws/pull/809). +- s3_bucket_notifications - refactor module to support SNS / SQS targets as well as the existing support for Lambda functions (https://github.com/ansible-collections/community.aws/issues/140). + +community.postgresql +~~~~~~~~~~~~~~~~~~~~ + +- postgresql_privs - the ``usage_on_types`` feature have been deprecated and will be removed in ``community.postgresql 3.0.0``. Please use the ``type`` option with the ``type`` value to explicitly grant/revoke privileges on types (https://github.com/ansible-collections/community.postgresql/issues/207). +- postgresql_query - the ``path_to_script`` and ``as_single_query`` options as well as the ``query_list`` and ``query_all_results`` return values have been deprecated and will be removed in ``community.postgresql 3.0.0``. Please use the ``community.postgresql.postgresql_script`` module to execute statements from scripts (https://github.com/ansible-collections/community.postgresql/issues/189). +- postgresql_query - the default value of the ``as_single_query`` option changes to ``yes``. If the related behavior of your tasks where the module is involved changes, please adjust the parameter's value correspondingly (https://github.com/ansible-collections/community.postgresql/issues/85). +- postgresql_user - the ``priv`` argument has been deprecated and will be removed in ``community.postgresql 3.0.0``. Please use the ``postgresql_privs`` module to grant/revoke privileges instead (https://github.com/ansible-collections/community.postgresql/issues/212). + +containers.podman +~~~~~~~~~~~~~~~~~ + +- Add podman_tag module +- Add secrets driver and driver opts support + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- All modules can read custom or organizational CA signed certificate from the environment variables. Please refer to `SSL Certificate Validation `_ section in the `README.md `_ for modification to existing playbooks or setting environment variable. +- All modules now support SSL over HTTPS and socket level timeout. + +f5networks.f5_modules +~~~~~~~~~~~~~~~~~~~~~ + +- bigip_device_info - pagination logic has also been added to help with api stability. +- bigip_device_info - the module no longer gathers information from all partitions on device. This change will stabalize the module by gathering resources only from the given partition and prevent the module from gathering way too much information that might result in crashing. + +ovirt.ovirt +~~~~~~~~~~~ + +- manageiq - role removed (https://github.com/oVirt/ovirt-ansible-collection/pull/375). + +vyos.vyos +~~~~~~~~~ + +- Add 'pool' as value to server key in ntp_global. + +Removed Features +---------------- + +Ansible-core +~~~~~~~~~~~~ + +- Remove deprecated ``Templar.set_available_variables()`` method (https://github.com/ansible/ansible/issues/75828) +- cli - remove deprecated ability to set verbosity before the sub-command (https://github.com/ansible/ansible/issues/75823) +- copy - remove deprecated ``thirsty`` alias (https://github.com/ansible/ansible/issues/75824) +- psrp - Removed fallback on ``put_file`` with older ``pypsrp`` versions. Users must have at least ``pypsrp>=0.4.0``. +- url_argument_spec - remove deprecated ``thirsty`` alias for ``get_url`` and ``uri`` modules (https://github.com/ansible/ansible/issues/75825, https://github.com/ansible/ansible/issues/75826) + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- the "legacy" integration test setup has been removed; this does not affect end users and is only relevant to contributors (https://github.com/ansible-collections/community.hashi_vault/pull/191). + +community.vmware +~~~~~~~~~~~~~~~~ + +- vcenter_extension_facts - The deprecated module ``vcenter_extension_facts`` has been removed, use ``vcenter_extension_info`` instead. +- vmware_about_facts - The deprecated module ``vmware_about_facts`` has been removed, use ``vmware_about_info`` instead. +- vmware_category_facts - The deprecated module ``vmware_category_facts`` has been removed, use ``vmware_category_info`` instead. +- vmware_cluster - Remove DRS configuration in favour of module ``vmware_cluster_drs``. +- vmware_cluster - Remove HA configuration in favour of module ``vmware_cluster_ha``. +- vmware_cluster - Remove VSAN configuration in favour of module ``vmware_cluster_vsan``. +- vmware_cluster_facts - The deprecated module ``vmware_cluster_facts`` has been removed, use ``vmware_cluster_info`` instead. +- vmware_datastore_facts - The deprecated module ``vmware_datastore_facts`` has been removed, use ``vmware_datastore_info`` instead. +- vmware_drs_group_facts - The deprecated module ``vmware_drs_group_facts`` has been removed, use ``vmware_drs_group_info`` instead. +- vmware_drs_rule_facts - The deprecated module ``vmware_drs_rule_facts`` has been removed, use ``vmware_drs_rule_info`` instead. +- vmware_dvs_portgroup - The deprecated parameter ``portgroup_type`` has been removed, use ``port_binding`` instead. +- vmware_dvs_portgroup_facts - The deprecated module ``vmware_dvs_portgroup_facts`` has been removed, use ``vmware_dvs_portgroup_info`` instead. +- vmware_guest_boot_facts - The deprecated module ``vmware_guest_boot_facts`` has been removed, use ``vmware_guest_boot_info`` instead. +- vmware_guest_customization_facts - The deprecated module ``vmware_guest_customization_facts`` has been removed, use ``vmware_guest_customization_info`` instead. +- vmware_guest_disk_facts - The deprecated module ``vmware_guest_disk_facts`` has been removed, use ``vmware_guest_disk_info`` instead. +- vmware_guest_facts - The deprecated module ``vmware_guest_facts`` has been removed, use ``vmware_guest_info`` instead. +- vmware_guest_snapshot_facts - The deprecated module ``vmware_guest_snapshot_facts`` has been removed, use ``vmware_guest_snapshot_info`` instead. +- vmware_host_capability_facts - The deprecated module ``vmware_host_capability_facts`` has been removed, use ``vmware_host_capability_info`` instead. +- vmware_host_config_facts - The deprecated module ``vmware_host_config_facts`` has been removed, use ``vmware_host_config_info`` instead. +- vmware_host_dns_facts - The deprecated module ``vmware_host_dns_facts`` has been removed, use ``vmware_host_dns_info`` instead. +- vmware_host_feature_facts - The deprecated module ``vmware_host_feature_facts`` has been removed, use ``vmware_host_feature_info`` instead. +- vmware_host_firewall_facts - The deprecated module ``vmware_host_firewall_facts`` has been removed, use ``vmware_host_firewall_info`` instead. +- vmware_host_ntp_facts - The deprecated module ``vmware_host_ntp_facts`` has been removed, use ``vmware_host_ntp_info`` instead. +- vmware_host_package_facts - The deprecated module ``vmware_host_package_facts`` has been removed, use ``vmware_host_package_info`` instead. +- vmware_host_service_facts - The deprecated module ``vmware_host_service_facts`` has been removed, use ``vmware_host_service_info`` instead. +- vmware_host_ssl_facts - The deprecated module ``vmware_host_ssl_facts`` has been removed, use ``vmware_host_ssl_info`` instead. +- vmware_host_vmhba_facts - The deprecated module ``vmware_host_vmhba_facts`` has been removed, use ``vmware_host_vmhba_info`` instead. +- vmware_host_vmnic_facts - The deprecated module ``vmware_host_vmnic_facts`` has been removed, use ``vmware_host_vmnic_info`` instead. +- vmware_local_role_facts - The deprecated module ``vmware_local_role_facts`` has been removed, use ``vmware_local_role_info`` instead. +- vmware_local_user_facts - The deprecated module ``vmware_local_user_facts`` has been removed, use ``vmware_local_user_info`` instead. +- vmware_portgroup_facts - The deprecated module ``vmware_portgroup_facts`` has been removed, use ``vmware_portgroup_info`` instead. +- vmware_resource_pool_facts - The deprecated module ``vmware_resource_pool_facts`` has been removed, use ``vmware_resource_pool_info`` instead. +- vmware_tag_facts - The deprecated module ``vmware_tag_facts`` has been removed, use ``vmware_tag_info`` instead. +- vmware_target_canonical_facts - The deprecated module ``vmware_target_canonical_facts`` has been removed, use ``vmware_target_canonical_info`` instead. +- vmware_vm_facts - The deprecated module ``vmware_vm_facts`` has been removed, use ``vmware_vm_info`` instead. +- vmware_vmkernel_facts - The deprecated module ``vmware_vmkernel_facts`` has been removed, use ``vmware_vmkernel_info`` instead. +- vmware_vmkernel_ip_config - The deprecated module ``vmware_vmkernel_ip_config`` has been removed, use ``vmware_vmkernel`` instead. +- vmware_vswitch_facts - The deprecated module ``vmware_vswitch_facts`` has been removed, use ``vmware_vswitch_info`` instead. + +Deprecated Features +------------------- + +Ansible-core +~~~~~~~~~~~~ + +- ansible-core - Remove support for Python 2.6. +- ansible-test - Remove support for Python 2.6. +- ssh connection plugin option scp_if_ssh in favor of ssh_transfer_method. + +amazon.aws +~~~~~~~~~~ + +- ec2_instance - The default value for ```instance_type``` has been deprecated, in the future release you must set an instance_type or a launch_template (https://github.com/ansible-collections/amazon.aws/pull/587). +- module_utils - support for the original AWS SDK `boto` has been deprecated in favour of the `boto3`/`botocore` SDK. All `boto` based modules have either been deprecated or migrated to `botocore`, and the remaining support code in module_utils will be removed in release 4.0.0 of the amazon.aws collection. Any modules outside of the amazon.aws and community.aws collections based on the `boto` library will need to be migrated to the `boto3`/`botocore` libraries (https://github.com/ansible-collections/amazon.aws/pull/575). + +cisco.ios +~~~~~~~~~ + +- Deprecates lldp module. +- `ios_acls` - Deprecated fragment attribute added boolean alternate as enable_fragment. + +cisco.nxos +~~~~~~~~~~ + +- Deprecated nxos_snmp_community module. +- Deprecated nxos_snmp_contact module. +- Deprecated nxos_snmp_host module. +- Deprecated nxos_snmp_location module. +- Deprecated nxos_snmp_traps module. +- Deprecated nxos_snmp_user module. + +community.general +~~~~~~~~~~~~~~~~~ + +- mail callback plugin - not specifying ``sender`` is deprecated and will be disallowed in community.general 6.0.0 (https://github.com/ansible-collections/community.general/pull/4140). +- module_helper module utils - deprecated the attribute ``ModuleHelper.VarDict`` (https://github.com/ansible-collections/community.general/pull/3801). +- pacman - from community.general 5.0.0 on, the ``changed`` status of ``update_cache`` will no longer be ignored if ``name`` or ``upgrade`` is specified. To keep the old behavior, add something like ``register: result`` and ``changed_when: result.packages | length > 0`` to your task (https://github.com/ansible-collections/community.general/pull/4329). + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- Support for Ansible 2.9 and ansible-base 2.10 is deprecated, and will be removed in the next major release (community.hashi_vault 3.0.0) next spring (https://github.com/ansible-community/community-topics/issues/50, https://github.com/ansible-collections/community.hashi_vault/issues/189). +- aws_iam_login auth method - the ``aws_iam_login`` method has been renamed to ``aws_iam``. The old name will be removed in collection version ``3.0.0``. Until then both names will work, and a warning will be displayed when using the old name (https://github.com/ansible-collections/community.hashi_vault/pull/193). + +junipernetworks.junos +~~~~~~~~~~~~~~~~~~~~~ + +- 'router_id' options is deprecated from junos_ospf_interfaces, junos_ospfv2 and junos_ospfv3 resuorce module. + +purestorage.flasharray +~~~~~~~~~~~~~~~~~~~~~~ + +- purefa_sso - Deprecated in favor of M(purefa_admin). Will be removed in Collection 2.0 diff --git a/docs/docsite/rst/porting_guides/porting_guides.rst b/docs/docsite/rst/porting_guides/porting_guides.rst index 7798fbf4969..562ae57f6e2 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_6 porting_guide_5 porting_guide_4 porting_guide_3 diff --git a/docs/docsite/rst/user_guide/vault.rst b/docs/docsite/rst/user_guide/vault.rst index a6bf6a7e611..b196f6125eb 100644 --- a/docs/docsite/rst/user_guide/vault.rst +++ b/docs/docsite/rst/user_guide/vault.rst @@ -101,7 +101,7 @@ To create a vault password client script: * Within the script itself: * Print the passwords to standard output * Accept a ``--vault-id`` option - * If the script prompts for data (for example, a database password), send the prompts to standard error + * If the script prompts for data (for example, a database password), display the prompts to the TTY. When you run a playbook that uses vault passwords stored in a third-party tool, specify the script as the source within the ``--vault-id`` flag. For example: diff --git a/docs/docsite/rst/user_guide/windows_dsc.rst b/docs/docsite/rst/user_guide/windows_dsc.rst index 0dd53dea21c..0588149f068 100644 --- a/docs/docsite/rst/user_guide/windows_dsc.rst +++ b/docs/docsite/rst/user_guide/windows_dsc.rst @@ -12,7 +12,7 @@ is the same as Ansible, it is just executed in a different manner. Since Ansible 2.4, the ``win_dsc`` module has been added and can be used to take advantage of existing DSC resources when interacting with a Windows host. -More details on DSC can be viewed at `DSC Overview `_. +More details on DSC can be viewed at `DSC Overview `_. Host Requirements ````````````````` @@ -33,7 +33,7 @@ on the scenario. Reasons for using an Ansible module over a DSC resource: * The host does not support PowerShell v5.0, or it cannot easily be upgraded -* The DSC resource does not offer a feature present in an Ansible module. For example +* The DSC resource does not offer a feature present in an Ansible module. For example, win_regedit can manage the ``REG_NONE`` property type, while the DSC ``Registry`` resource cannot * DSC resources have limited check mode support, while some Ansible modules have @@ -57,7 +57,7 @@ and it does the job, just use DSC for that task. How to Use DSC? ``````````````` The ``win_dsc`` module takes in a free-form of options so that it changes -according to the resource it is managing. A list of built in resources can be +according to the resource it is managing. A list of built-in resources can be found at `resources `_. Using the `Registry `_ @@ -78,7 +78,7 @@ resource as an example, this is the DSC definition as documented by Microsoft: } When defining the task, ``resource_name`` must be set to the DSC resource being -used - in this case the ``resource_name`` should be set to ``Registry``. The +used - in this case, the ``resource_name`` should be set to ``Registry``. The ``module_version`` can refer to a specific version of the DSC resource installed; if left blank it will default to the latest version. The other options are parameters that are used to define the resource, such as ``Key`` and @@ -154,10 +154,10 @@ invocation output for the above ``Registry`` task: } The ``invocation.module_args`` key shows the actual values that were set as -well as other possible values that were not set. Unfortunately this will not +well as other possible values that were not set. Unfortunately, this will not show the default value for a DSC property, only what was set from the Ansible task. Any ``*_password`` option will be masked in the output for security -reasons, if there are any other sensitive module options, set ``no_log: True`` +reasons; if there are any other sensitive module options, set ``no_log: True`` on the task to stop all task output from being logged. @@ -165,8 +165,8 @@ Property Types -------------- Each DSC resource property has a type that is associated with it. Ansible will try to convert the defined options to the correct type during execution. -For simple types like ``[string]`` and ``[bool]`` this is a simple operation, -but complex types like ``[PSCredential]`` or arrays (like ``[string[]]``) this +For simple types like ``[string]`` and ``[bool]``, this is a simple operation, +but complex types like ``[PSCredential]`` or arrays (like ``[string[]]``) require certain rules. PSCredential @@ -174,7 +174,7 @@ PSCredential A ``[PSCredential]`` object is used to store credentials in a secure way, but Ansible has no way to serialize this over JSON. To set a DSC PSCredential property, the definition of that parameter should have two entries that are suffixed with -``_username`` and ``_password`` for the username and password respectively. +``_username`` and ``_password`` for the username and password, respectively. For example: .. code-block:: yaml+jinja @@ -219,14 +219,14 @@ class definition is typically located in the ``.schema.mof``. HashTable Type ++++++++++++++ A ``[HashTable]`` object is also a dictionary but does not have a strict set of -keys that can/need to be defined. Like a ``[CimInstance]``, define it like a +keys that can/need to be defined. Like a ``[CimInstance]``, define it as a normal dictionary value in YAML. A ``[HashTable]]`` is defined with ``EmbeddedInstance("MSFT_KeyValuePair")`` in a DSC resource MOF definition. Arrays ++++++ Simple type arrays like ``[string[]]`` or ``[UInt32[]]`` are defined as a list -or as a comma separated string which are then cast to their type. Using a list +or as a comma-separated string which is then cast to their type. Using a list is recommended because the values are not manually parsed by the ``win_dsc`` module before being passed to the DSC engine. For example, to define a simple type array in Ansible: @@ -264,7 +264,7 @@ like this example: Port: 80 IPAddress: '*' -The above example, is an array with two values of the class `MSFT_xWebBindingInformation `_. +The above example is an array with two values of the class `MSFT_xWebBindingInformation `_. When defining a ``[CimInstance[]]``, be sure to read the resource documentation to find out what keys to use in the definition. @@ -293,10 +293,10 @@ All the values above are equal to a UTC date time of February 22nd 2019 at Run As Another User ------------------- By default, DSC runs each resource as the SYSTEM account and not the account -that Ansible use to run the module. This means that resources that are dynamically +that Ansible uses to run the module. This means that resources that are dynamically loaded based on a user profile, like the ``HKEY_CURRENT_USER`` registry hive, will be loaded under the ``SYSTEM`` profile. The parameter -``PsDscRunAsCredential`` is a parameter that can be set for every DSC resource +``PsDscRunAsCredential`` is a parameter that can be set for every DSC resource, and force the DSC engine to run under a different account. As ``PsDscRunAsCredential`` has a type of ``PSCredential``, it is defined with the ``_username`` and ``_password`` suffix. @@ -337,7 +337,7 @@ The ``Find-DscResource`` cmdlet can also be used to find custom resources. For e # Find all DSC resources that relate to SQL Find-DscResource -ModuleName "*sql*" -.. Note:: DSC resources developed by Microsoft that start with ``x``, means the +.. Note:: DSC resources developed by Microsoft that start with ``x`` means the resource is experimental and comes with no support. Installing a Custom Resource @@ -346,9 +346,9 @@ There are three ways that a DSC resource can be installed on a host: * Manually with the ``Install-Module`` cmdlet * Using the ``win_psmodule`` Ansible module -* Saving the module manually and copying it another host +* Saving the module manually and copying it to another host -This is an example of installing the ``xWebAdministration`` resources using +The following is an example of installing the ``xWebAdministration`` resources using ``win_psmodule``: .. code-block:: yaml+jinja @@ -371,10 +371,10 @@ can be run: Save-Module -Name xWebAdministration -Path C:\temp -This will create a folder called ``xWebAdministration`` in ``C:\temp`` which +This will create a folder called ``xWebAdministration`` in ``C:\temp``, which can be copied to any host. For PowerShell to see this offline resource, it must be copied to a directory set in the ``PSModulePath`` environment variable. -In most cases the path ``C:\Program Files\WindowsPowerShell\Module`` is set +In most cases, the path ``C:\Program Files\WindowsPowerShell\Module`` is set through this variable, but the ``win_path`` module can be used to add different paths. diff --git a/lib/ansible/modules/pip.py b/lib/ansible/modules/pip.py index 21327bc7b54..c71a857b2ed 100644 --- a/lib/ansible/modules/pip.py +++ b/lib/ansible/modules/pip.py @@ -159,12 +159,11 @@ EXAMPLES = ''' - bottle>0.10,<0.20,!=0.11 - name: Install python package using a proxy - # Pip doesn't use the standard environment variables, please use the CAPITALIZED ones below ansible.builtin.pip: name: six environment: - HTTP_PROXY: '127.0.0.1:8080' - HTTPS_PROXY: '127.0.0.1:8080' + http_proxy: 'http://127.0.0.1:8080' + https_proxy: 'https://127.0.0.1:8080' # You do not have to supply '-e' option in extra_args - name: Install MyApp using one of the remote protocols (bzr+,hg+,git+,svn+) diff --git a/lib/ansible/modules/setup.py b/lib/ansible/modules/setup.py index 715ba13d9dc..ecad1a8f562 100644 --- a/lib/ansible/modules/setup.py +++ b/lib/ansible/modules/setup.py @@ -114,13 +114,13 @@ EXAMPLES = """ # ansible all -m ansible.builtin.setup -a 'filter=facter_*' # Collect only facts returned by facter. -# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,!any,facter' +# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,facter' - name: Collect only facts returned by facter ansible.builtin.setup: gather_subset: - '!all' - - '!any' + - '!' - facter - name: Collect only selected facts @@ -137,7 +137,7 @@ EXAMPLES = """ # ansible all -m ansible.builtin.setup -a 'gather_subset=network,virtual' # Collect only network and virtual (excludes default minimum facts) -# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,!any,network,virtual' +# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,network,virtual' # Do not call puppet facter or ohai even if present. # ansible all -m ansible.builtin.setup -a 'gather_subset=!facter,!ohai'