[docs][backport] Docs backports week 4-18-22 (#77557)

* Update reporting_bugs_and_features.rst (#77518)

(cherry picked from commit fa7c5d9b10)

* docs: Add porting guide for Ansible 6.0.0a1 (#77526)

(cherry picked from commit 0d9a580f24)

* Steering Committee: add new member (#77529)

(cherry picked from commit 553a226da5)

* Update pip example with standard lowercase http[s]_proxy env vars (#77515)

(cherry picked from commit 2ba39fcf8c)

* Update docs to recommend the TTY for prompts over stderr (#77533)

(cherry picked from commit 789d29e895)

* update python devel docs (#77499)

* update python devel docs

Co-authored-by: Sandra McCann <samccann@redhat.com>
(cherry picked from commit 2fc73a9dc3)

* setup: remove 'any' as seemingly valid option (#77532)

fixes #59783

(cherry picked from commit 762d97f1b8)

* 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 eef0a1cef9)

* Update developing_collections_structure.rst (#77496)

(cherry picked from commit 538a19b748)

* Fix a broken link and some grammatical errors (#77531)

(cherry picked from commit 0c1cb0e9d4)

* Add contributor path page (#77494)

Co-authored-by: Emmanuel Ugwu <32464178+ugwutotheeshoes@users.noreply.github.com>
(cherry picked from commit 3b0d74c145)

Co-authored-by: Iheanacho Amarachi Sharon <58210919+Iheanacho-ai@users.noreply.github.com>
Co-authored-by: David Moreau Simard <moi@dmsimard.com>
Co-authored-by: Andrew Klychkov <aklychko@redhat.com>
Co-authored-by: Junegunn Choi <junegunn.c@gmail.com>
Co-authored-by: Matt Martz <matt@sivel.net>
Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>
Co-authored-by: Emmanuel Ugwu <32464178+ugwutotheeshoes@users.noreply.github.com>
Co-authored-by: Kajsa Gauza <nimrod7@gmail.com>
pull/77611/head
Sandra McCann 3 years ago committed by GitHub
parent 91fb18bf31
commit e03069a444
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -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 <https://docs.ansible.com/ansible-core/devel/index.html>`_
- `Collections <https://docs.ansible.com/ansible/latest/user_guide/collections_using.html>`_
- `AWX <https://github.com/ansible/awx>`_
- `Galaxy <https://galaxy.ansible.com/>`_
- `ansible-lint <https://ansible-lint.readthedocs.io/en/latest/>`_
- `Molecule <https://molecule.readthedocs.io/en/latest/>`_
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 <https://docs.python.org/3/tutorial/>`_
- `Git <https://git-scm.com/docs/gittutorial>`_
- `GitHub collaborative development model through forks and pull requests <https://docs.github.com/en/github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models>`_
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 <developer_guide>`.
* :ref:`Ansible collectoin development <developing_collections>` 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 <https://github.com/ansible-collections/>`_ ``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 <ommunity_documentation_contributions>`, answering question from other contributors and users on `Matrix/Libera.Chat IRC <communicate>`, giving advice in issues and pull requests, and discussing the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_.
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 <https://github.com/ansible-community/collection_bot>`_ , such as `community.general <https://github.com/ansible-collections/community.general>`_ and `community.network <https://github.com/ansible-collections/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 <https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization>`_.
Become a steering committee member
==================================
.. note::
You do NOT have to be a programmer to become a steering committee member.
The `Steering Committee <community_steering_committee>` member status reflects the highest level of trust which allows contributors to lead the project through making very important `decisions <https://github.com/ansible-community/community-topics/issues>`_ 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 <https://github.com/ansible-community/community-topics/issues>`_.
* Propose your topics.
* If time permits, join the `Community meetings <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_ Note this is **NOT** a requirement.

@ -48,7 +48,10 @@ If there is no meetup near you, we are happy to help you `start one <https://www
File and verify issues File and verify issues
====================== ======================
All software has bugs, and Ansible is no exception. When you find a bug, you can help tremendously by :ref:`telling us about it <reporting_bugs_and_features>`. 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 <reporting_bugs_and_features>`.
* Filing :ref:`issues for collections <reporting_bugs_in_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. 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 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 <community_development_process>` and and :ref:`how to contribute to collections <contributing_maintained_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 <community_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 <https://ansible.sivel.net/pr/byfile.html>`_, 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 <https://ansible.sivel.net/pr/byfile.html>`_, 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 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. 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 <maintainers>`. See :ref:`collection maintainer guidelines <maintainers>` to learn more about the responsibilities of being an Ansible collection maintainer.
.. _community_working_groups: .. _community_working_groups:

@ -21,3 +21,4 @@ The purpose of this guide is to teach you everything you need to know about bein
:maxdepth: 2 :maxdepth: 2
getting_started getting_started
contributor_path

@ -108,7 +108,16 @@ Promote active contributors satisfying :ref:`requirements<maintainer_requirement
If your collection found new maintainers, announce that fact in the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ 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. If your collection found new maintainers, announce that fact in the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ 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: .. _maintainer_documentation:

@ -16,7 +16,7 @@ Reporting a bug
Security bugs Security bugs
------------- -------------
Ansible practices responsible disclosure - for security-related bugs, email `security@ansible.com <mailto: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 <mailto:security@ansible.com>`_ for an immediate response. Do not submit a ticket or post to any public groups.
Bugs in ansible-core Bugs in ansible-core
-------------------- --------------------
@ -39,14 +39,15 @@ If you find a bug, open an issue using the `issue template <https://github.com/a
Fill out the issue template as completely and as accurately as possible. Include: Fill out the issue template as completely and as accurately as possible. Include:
* your Ansible version * your Ansible version
* the expected behavior and what you've tried (including the exact commands you were using or tasks you are running) * the expected behavior and what you've tried, including the exact commands you were using or tasks you are running.
* the current behavior and why you think it is a bug * the current behavior and why you think it is a bug
* the steps to reproduce the bug * the steps to reproduce the bug
* a minimal reproducible example and comments describing examples * a minimal reproducible example and comments describing examples
* any relevant configurations and the components you used * any relevant configurations and the components you used
* any relevant output plus ``ansible -vvvv`` (debugging) output * any relevant output plus ``ansible -vvvv`` (debugging) output
* add the output of ``ansible-test-env --show`` when filing bug reports involving ``ansible-test``.
Make sure to preserve formatting using `code blocks <https://help.github.com/articles/creating-and-highlighting-code-blocks/>`_ 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 <https://help.github.com/articles/creating-and-highlighting-code-blocks/>`_. For multiple-file content, use gist.github.com, more durable than Pastebin content.
.. _request_features: .. _request_features:

@ -53,6 +53,8 @@ The following table lists the current Steering Committee members. See :ref:`stee
+------------------+---------------+-------------+ +------------------+---------------+-------------+
| John Barker | gundalow | 2021 | | John Barker | gundalow | 2021 |
+------------------+---------------+-------------+ +------------------+---------------+-------------+
| Mario Lenz | mariolenz | 2022 |
+------------------+---------------+-------------+
| Markus Bergholz | markuman | 2022 | | Markus Bergholz | markuman | 2022 |
+------------------+---------------+-------------+ +------------------+---------------+-------------+
| Sorin Sbarnea | ssbarnea | 2021 | | Sorin Sbarnea | ssbarnea | 2021 |

@ -70,7 +70,7 @@ The optional import behavior also applies to module_utils imported from collecti
Listing collection dependencies 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: You can use git repositories for collection dependencies during local development and testing. For example:

@ -198,8 +198,8 @@ When reading the :ref:`developing_testing` documentation, there will be content
.. _meta_runtime_yml: .. _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: 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:

@ -4,47 +4,31 @@
Ansible and Python 3 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 The ``ansible-core`` code runs Python 3 (for specific versions check `Control Node Requirements <:ref:control-node-requirements>`_.
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. 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:: .. contents::
:local: :local:
To ensure that your code runs on Python 3 as well as on Python 2, learn the tips and tricks and idioms We do have some considerations depending on the types of Ansible code:
described here. Most of these considerations apply to all three types of Ansible code:
1. controller-side code - code that runs on the machine where you invoke :command:`/usr/bin/ansible` 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. 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's used by modules to perform tasks and sometimes used by controller-side code as well 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. 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 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 See `Control Node Requirements <:ref:control-node-requirements>`_ and `Managed Node Requirements <:ref:managed-node-requirements>`_ for the
support Python 3.5 or greater and Python 2.6 or greater. specific versions supported.
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:
Support for Python 2.4 and Python 2.5 was dropped in Ansible-2.4. RHEL-5 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.
(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.
Developing Ansible code that supports Python 2 and Python 3 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 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 <python:unicode>` text type). For Unicode Sandwich we know that after Python 2's :func:`unicode <python: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, 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. 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 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. 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 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 <https://docs.python.org/3/library/stdtypes.html#string-formatting>`_ Python documentation on `percent formatting <https://docs.python.org/3/library/stdtypes.html#string-formatting>`_
.. _testing_modules_python_3: .. _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 <developing_testing>` pages for more information.

@ -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 <https://github.com/ansible-community/ansible-build-data/blob/main/6/CHANGELOG-v6.rst>`_ 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 <https://github.com/dell/dellemc-openmanage-ansible-modules#ssl-certificate-validation>`_ section in the `README.md <https://github.com/dell/dellemc-openmanage-ansible-modules/blob/collections/README.md#SSL-Certificate-Validation>`_ 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 <https://github.com/dell/dellemc-openmanage-ansible-modules#ssl-certificate-validation>`_ section in the `README.md <https://github.com/dell/dellemc-openmanage-ansible-modules/blob/collections/README.md#SSL-Certificate-Validation>`_ 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

@ -10,6 +10,7 @@ This section lists porting guides that can help you in updating playbooks, plugi
:maxdepth: 1 :maxdepth: 1
:glob: :glob:
porting_guide_6
porting_guide_5 porting_guide_5
porting_guide_4 porting_guide_4
porting_guide_3 porting_guide_3

@ -101,7 +101,7 @@ To create a vault password client script:
* Within the script itself: * Within the script itself:
* Print the passwords to standard output * Print the passwords to standard output
* Accept a ``--vault-id`` option * 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: 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:

@ -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 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. existing DSC resources when interacting with a Windows host.
More details on DSC can be viewed at `DSC Overview <https://docs.microsoft.com/en-us/powershell/scripting/dsc/overview/overview>`_. More details on DSC can be viewed at `DSC Overview <https://docs.microsoft.com/en-us/powershell/scripting/dsc/overview?view=powershell-7.2>`_.
Host Requirements Host Requirements
````````````````` `````````````````
@ -33,7 +33,7 @@ on the scenario.
Reasons for using an Ansible module over a DSC resource: 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 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 win_regedit can manage the ``REG_NONE`` property type, while the DSC
``Registry`` resource cannot ``Registry`` resource cannot
* DSC resources have limited check mode support, while some Ansible modules have * 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? How to Use DSC?
``````````````` ```````````````
The ``win_dsc`` module takes in a free-form of options so that it changes 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 <https://docs.microsoft.com/en-us/powershell/scripting/dsc/resources/resources>`_. found at `resources <https://docs.microsoft.com/en-us/powershell/scripting/dsc/resources/resources>`_.
Using the `Registry <https://docs.microsoft.com/en-us/powershell/scripting/dsc/reference/resources/windows/registryresource>`_ Using the `Registry <https://docs.microsoft.com/en-us/powershell/scripting/dsc/reference/resources/windows/registryresource>`_
@ -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 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 ``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 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 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 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 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 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. 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 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. 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, For simple types like ``[string]`` and ``[bool]``, this is a simple operation,
but complex types like ``[PSCredential]`` or arrays (like ``[string[]]``) this but complex types like ``[PSCredential]`` or arrays (like ``[string[]]``)
require certain rules. require certain rules.
PSCredential PSCredential
@ -174,7 +174,7 @@ PSCredential
A ``[PSCredential]`` object is used to store credentials in a secure way, but 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, 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 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: For example:
.. code-block:: yaml+jinja .. code-block:: yaml+jinja
@ -219,14 +219,14 @@ class definition is typically located in the ``<resource name>.schema.mof``.
HashTable Type HashTable Type
++++++++++++++ ++++++++++++++
A ``[HashTable]`` object is also a dictionary but does not have a strict set of 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 normal dictionary value in YAML. A ``[HashTable]]`` is defined with
``EmbeddedInstance("MSFT_KeyValuePair")`` in a DSC resource MOF definition. ``EmbeddedInstance("MSFT_KeyValuePair")`` in a DSC resource MOF definition.
Arrays Arrays
++++++ ++++++
Simple type arrays like ``[string[]]`` or ``[UInt32[]]`` are defined as a list 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`` 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 module before being passed to the DSC engine. For example, to define a simple
type array in Ansible: type array in Ansible:
@ -264,7 +264,7 @@ like this example:
Port: 80 Port: 80
IPAddress: '*' IPAddress: '*'
The above example, is an array with two values of the class `MSFT_xWebBindingInformation <https://github.com/dsccommunity/xWebAdministration/blob/master/source/DSCResources/MSFT_xWebSite/MSFT_xWebSite.schema.mof>`_. The above example is an array with two values of the class `MSFT_xWebBindingInformation <https://github.com/dsccommunity/xWebAdministration/blob/master/source/DSCResources/MSFT_xWebSite/MSFT_xWebSite.schema.mof>`_.
When defining a ``[CimInstance[]]``, be sure to read the resource documentation When defining a ``[CimInstance[]]``, be sure to read the resource documentation
to find out what keys to use in the definition. 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 Run As Another User
------------------- -------------------
By default, DSC runs each resource as the SYSTEM account and not the account 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, loaded based on a user profile, like the ``HKEY_CURRENT_USER`` registry hive,
will be loaded under the ``SYSTEM`` profile. The parameter 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 force the DSC engine to run under a different account. As
``PsDscRunAsCredential`` has a type of ``PSCredential``, it is defined with the ``PsDscRunAsCredential`` has a type of ``PSCredential``, it is defined with the
``_username`` and ``_password`` suffix. ``_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 all DSC resources that relate to SQL
Find-DscResource -ModuleName "*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. resource is experimental and comes with no support.
Installing a Custom Resource 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 * Manually with the ``Install-Module`` cmdlet
* Using the ``win_psmodule`` Ansible module * 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``: ``win_psmodule``:
.. code-block:: yaml+jinja .. code-block:: yaml+jinja
@ -371,10 +371,10 @@ can be run:
Save-Module -Name xWebAdministration -Path C:\temp 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 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. 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 through this variable, but the ``win_path`` module can be used to add different
paths. paths.

@ -159,12 +159,11 @@ EXAMPLES = '''
- bottle>0.10,<0.20,!=0.11 - bottle>0.10,<0.20,!=0.11
- name: Install python package using a proxy - name: Install python package using a proxy
# Pip doesn't use the standard environment variables, please use the CAPITALIZED ones below
ansible.builtin.pip: ansible.builtin.pip:
name: six name: six
environment: environment:
HTTP_PROXY: '127.0.0.1:8080' http_proxy: 'http://127.0.0.1:8080'
HTTPS_PROXY: '127.0.0.1:8080' https_proxy: 'https://127.0.0.1:8080'
# You do not have to supply '-e' option in extra_args # You do not have to supply '-e' option in extra_args
- name: Install MyApp using one of the remote protocols (bzr+,hg+,git+,svn+) - name: Install MyApp using one of the remote protocols (bzr+,hg+,git+,svn+)

@ -114,13 +114,13 @@ EXAMPLES = """
# ansible all -m ansible.builtin.setup -a 'filter=facter_*' # ansible all -m ansible.builtin.setup -a 'filter=facter_*'
# Collect only facts returned by 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 - name: Collect only facts returned by facter
ansible.builtin.setup: ansible.builtin.setup:
gather_subset: gather_subset:
- '!all' - '!all'
- '!any' - '!<any valid subset>'
- facter - facter
- name: Collect only selected facts - name: Collect only selected facts
@ -137,7 +137,7 @@ EXAMPLES = """
# ansible all -m ansible.builtin.setup -a 'gather_subset=network,virtual' # ansible all -m ansible.builtin.setup -a 'gather_subset=network,virtual'
# Collect only network and virtual (excludes default minimum facts) # 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. # Do not call puppet facter or ohai even if present.
# ansible all -m ansible.builtin.setup -a 'gather_subset=!facter,!ohai' # ansible all -m ansible.builtin.setup -a 'gather_subset=!facter,!ohai'

Loading…
Cancel
Save