@@ -1,23 +1,31 @@

+..

+   THIS DOCUMENT IS AUTOMATICALLY GENERATED BY ANTSIBULL! PLEASE DO NOT EDIT MANUALLY! (YOU PROBABLY WANT TO EDIT porting_guide_base_2.10.rst)

 .. _porting_2.10_guide:

-**************************

+==========================

 Ansible 2.10 Porting Guide

-**************************

+==========================

 .. warning::

-	Links on this page may not point to the most recent versions of modules. In preparation for the release of 2.10, many plugins and modules have migrated to Collections on  `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/general/blob/master/README.rst>`_. We expect the 2.10 Porting Guide to change frequently up to the 2.10 release. Follow the conversations about collections on our various :ref:`communication` channels for the latest information on the status of the ``devel`` branch.

+         In preparation for the release of 2.10, many plugins and modules have migrated to Collections on  `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/master/README.rst>`_. We expect the 2.10 Porting Guide to change frequently up to the 2.10 release. Follow the conversations about collections on our various :ref:`communication` channels for the latest information on the status of the ``devel`` branch.

 This section discusses the behavioral changes between Ansible 2.9 and Ansible 2.10.

 It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible.

-We suggest you read this page along with `Ansible Changelog for 2.10 <https://github.com/ansible/ansible/blob/stable-2.10/changelogs/CHANGELOG-v2.10.rst>`_ to understand what updates you may need to make.

+We suggest you read this page along with the `Ansible Changelog for 2.10 <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/CHANGELOG-v2.10.rst>`_ to understand what updates you may need to make.

-This document is part of a collection on porting. The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.

+Since 2.10, ansible consists of two parts:

+* ansible-base, which are the ansible command line tools with a very small selection of plugins and modules, and

+* a `set of collections <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/acd.in>`_.

-.. contents:: Topics

+The :ref:`porting_2.10_guide_base` is included in this porting guide. The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.

+

+.. contents::

+  :local:

+  :depth: 2

 Playbook

@@ -40,8 +48,6 @@ Deprecated

 ==========

 * Windows Server 2008 and 2008 R2 will no longer be supported or tested in the next Ansible release, see :ref:`windows_faq_server2008`.

-* The :ref:`win_stat <win_stat_module>` module has removed the deprecated ``get_md55`` option and ``md5`` return value.

-* The :ref:`win_psexec <win_psexec_module>` module has removed the deprecated ``extra_opts`` option.

 Modules

@@ -67,7 +73,7 @@ The following modules call ``atomic_move()`` but do not call ``set_fs_attributes

 Code Audit

-++++++++++

+~~~~~~~~~~

 The code was audited for modules that use ``atomic_move()`` but **do not** later call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()``. Modules that provide no means for specifying the ``mode`` will not display a warning message since there is no way for the playbook author to remove the warning. The behavior of each module with regards to the default permissions of temporary files and the permissions of newly created files is explained below.

@@ -121,70 +127,11 @@ The M(sysctl) module uses ``atomic_move()`` to operate on ``/etc/sysctl.conf`` o

 	Links on this page may not point to the most recent versions of modules. We will update them when we can.

-Deprecation notices

-

-The following modules will be removed in Ansible 2.14. Please update your playbooks accordingly.

-

-* ldap_attr use ldap_attrs instead.

-* vyos_static_route use vyos_static_routes instead.

-

-The following functionality will be removed in Ansible 2.14. Please update update your playbooks accordingly.

-

-* :ref:`iam_managed_policy <iam_managed_policy_module>`: the ``fail_on_delete`` option will be removed.  It has always been ignored by the module.

-* :ref:`s3_lifecycle <s3_lifecycle_module>`: the ``requester_pays`` option will be removed. It has always been ignored by the module.

-* :ref:`s3_sync <s3_sync_module>`: the ``retries`` option will be removed. It has always been ignored by the module.

-* :ref:`cloudformation <cloudformation_module>`: the ``template_format`` option will be removed. It has been ignored by the module since Ansible 2.3.

-* :ref:`data_pipeline <data_pipeline_module>`: the ``version`` option will be removed. It has always been ignored by the module.

-* :ref:`ec2_eip <ec2_eip_module>`: the ``wait_timeout`` option will be removed. It has had no effect since Ansible 2.3.

-* :ref:`ec2_key <ec2_key_module>`: the ``wait`` option will be removed. It has had no effect since Ansible 2.5.

-* :ref:`ec2_key <ec2_key_module>`: the ``wait_timeout`` option will be removed. It has had no effect since Ansible 2.5.

-* :ref:`ec2_lc <ec2_lc_module>`: the ``associate_public_ip_address`` option will be removed. It has always been ignored by the module.

-* :ref:`ec2_tag <ec2_tag_module>`: Support for ``list`` as a state has been deprecated.  The ``ec2_tag_info`` can be used to fetch the tags on an EC2 resource.

-* :ref:`iam_policy <iam_policy_module>`: the ``policy_document`` option will be removed. To maintain the existing behavior use the ``policy_json`` option and read the file with the ``lookup`` plugin.

-* :ref:`win_domain_controller <win_domain_controller_module>`: the ``log_path`` option will be removed. This was undocumented and only related to debugging information for module development.

-* :ref:`win_package <win_package_module>`: the ``username`` and ``password`` options will be removed. The same functionality can be done by using ``become: yes`` and ``become_flags: logon_type=new_credentials logon_flags=netcredentials_only`` on the task.

-* :ref:`win_package <win_package_module>`: the ``ensure`` alias for the ``state`` option will be removed. Please use ``state`` instead of ``ensure``.

-* :ref:`win_package <win_package_module>`: the ``productid`` alias for the ``product_id`` option will be removed. Please use ``product_id`` instead of ``productid``.

-

-

-

-The following functionality will change in Ansible 2.14. Please update update your playbooks accordingly.

-

-* :ref:`ec2 <ec2_module>`: the ``group`` and ``group_id`` options will become mutually exclusive.  Currently ``group_id`` is ignored if you pass both.

-* :ref:`iam_policy <iam_policy_module>`: the default value for the ``skip_duplicates`` option will change from ``true`` to ``false``.  To maintain the existing behavior explicitly set it to ``true``.

-* :ref:`iam_role <iam_role_module>`: the ``purge_policies`` option (also know as ``purge_policy``) default value will change from ``true`` to ``false``

-* :ref:`elb_network_lb <elb_network_lb_module>`: the default behaviour for the ``state`` option will change from ``absent`` to ``present``.  To maintain the existing behavior explicitly set state to ``absent``.

-* :ref:`vmware_tag_info <vmware_tag_info_module>`: the module will not return ``tag_facts`` since it does not return multiple tags with the same name and different category id. To maintain the existing behavior use ``tag_info`` which is a list of tag metadata.

-

-The following modules will be removed in Ansible 2.14. Please update your playbooks accordingly.

-

-* ``vmware_dns_config`` use vmware_host_dns instead.

-

 Noteworthy module changes

 -------------------------

-* The ``datacenter`` option has been removed from :ref:`vmware_guest_find <vmware_guest_find_module>`

-* The options ``ip_address`` and ``subnet_mask`` have been removed from :ref:`vmware_vmkernel <vmware_vmkernel_module>`; use the suboptions ``ip_address`` and ``subnet_mask`` of the ``network`` option instead.

 * Ansible modules created with ``add_file_common_args=True`` added a number of undocumented arguments which were mostly there to ease implementing certain action plugins. The undocumented arguments ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``, ``delimiter``, and ``directory_mode`` are now no longer added. Modules relying on these options to be added need to specify them by themselves.

-* The ``AWSRetry`` decorator no longer catches ``NotFound`` exceptions by default.  ``NotFound`` exceptions need to be explicitly added using ``catch_extra_error_codes``.  Some AWS modules may see an increase in transient failures due to AWS's eventual consistency model.

-* :ref:`vmware_datastore_maintenancemode <vmware_datastore_maintenancemode_module>` now returns ``datastore_status`` instead of Ansible internal key ``results``.

-* :ref:`vmware_host_kernel_manager <vmware_host_kernel_manager_module>` now returns ``host_kernel_status`` instead of Ansible internal key ``results``.

-* :ref:`vmware_host_ntp <vmware_host_ntp_module>` now returns ``host_ntp_status`` instead of Ansible internal key ``results``.

-* :ref:`vmware_host_service_manager <vmware_host_service_manager_module>` now returns ``host_service_status`` instead of Ansible internal key ``results``.

-* :ref:`vmware_tag <vmware_tag_module>` now returns ``tag_status`` instead of Ansible internal key ``results``.

-* The deprecated ``recurse`` option in :ref:`pacman <pacman_module>` module has been removed, you should use ``extra_args=--recursive`` instead.

-* :ref:`vmware_guest_custom_attributes <vmware_guest_custom_attributes_module>` module does not require VM name which was a required parameter for releases prior to Ansible 2.10.

-* :ref:`win_pester <win_pester_module>` no longer runs all ``*.ps1`` file in the directory specified due to it executing potentially unknown scripts. It will follow the default behaviour of only running tests for files that are like ``*.tests.ps1`` which is built into Pester itself

-* :ref:`win_find <win_find_module>` has been refactored to better match the behaviour of the ``find`` module. Here is what has changed:

-    * When the directory specified by ``paths`` does not exist or is a file, it will no longer fail and will just warn the user

-    * Junction points are no longer reported as ``islnk``, use ``isjunction`` to properly report these files. This behaviour matches the :ref:`win_stat <win_stat_module>`

-    * Directories no longer return a ``size``, this matches the ``stat`` and ``find`` behaviour and has been removed due to the difficulties in correctly reporting the size of a directory

-* :ref:`purefb_fs <purefb_fs_module>` no longer supports the deprecated ``nfs`` option. This has been superceeded by ``nfsv3``.

-* :ref:`nxos_igmp_interface <nxos_igmp_interface_module>` no longer supports the deprecated ``oif_prefix`` and ``oif_source`` options. These have been superceeded by ``oif_ps``.

-* :ref:`aws_s3 <aws_s3_module>` can now delete versioned buckets even when they are not empty - set mode to delete to delete a versioned bucket and everything in it.

-* The parameter ``message`` in :ref:`grafana_dashboard <grafana_dashboard_module>` module is renamed to ``commit_message`` since ``message`` is used by Ansible Core engine internally.

 * Ansible no longer looks for Python modules in the current working directory (typically the ``remote_user``'s home directory) when an Ansible module is run. This is to fix becoming an unprivileged user on OpenBSD and to mitigate any attack vector if the current working directory is writable by a malicious user. Install any Python modules needed to run the Ansible modules on the managed node in a system-wide location or in another directory which is in the ``remote_user``'s ``$PYTHONPATH`` and readable by the ``become_user``.

@@ -217,3 +164,254 @@ Networking

 ==========

 No notable changes

+

+Porting Guide for v2.10.0a7

+===========================

+

+Major Changes

+-------------

+

+community.kubernetes

+~~~~~~~~~~~~~~~~~~~~

+

+- helm_plugin - new module to manage Helm plugins (https://github.com/ansible-collections/community.kubernetes/pull/154).

+- helm_plugin_info - new modules to gather information about Helm plugins (https://github.com/ansible-collections/community.kubernetes/pull/154).

+- k8s_exec - Return rc for the command executed (https://github.com/ansible-collections/community.kubernetes/pull/158).

+

+Porting Guide for v2.10.0a5

+===========================

+

+Removed Collections

+-------------------

+

+- dellemc_networking.os10 (previously included version: 1.0.2)

+

+Porting Guide for v2.10.0a4

+===========================

+

+Breaking Changes

+----------------

+

+ansible.windows

+~~~~~~~~~~~~~~~

+

+- setup - Make sure ``ansible_date_time.epoch`` is seconds since EPOCH in UTC to mirror the POSIX facts. The ``ansible_date_time.epoch_local`` contains seconds since EPOCH in the local timezone for backwards compatibility

+- setup - Will now add the IPv6 scope on link local addresses for ``ansible_ip_addresses``

+- setup - ``ansible_processor`` will now return the index before the other values to match the POSIX fact behaviour

+- win_find - No longer filters by size on directories, this feature had a lot of bugs, slowed down the module, and not a supported scenario with the ``find`` module.

+

+Removed Features

+----------------

+

+community.windows

+~~~~~~~~~~~~~~~~~

+

+- win_disk_image - removed the deprecated return value ``mount_path`` in favour of ``mount_paths``.

+

+Deprecated Features

+-------------------

+

+ansible.windows

+~~~~~~~~~~~~~~~

+

+- win_domain_computer - Deprecated the undocumented ``log_path`` option. This option will be removed in a major release after ``2022-07-01``.

+- win_regedit - Deprecated using forward slashes as a path separator, use backslashes to avoid ambiguity between a forward slash in the key name or a forward slash as a path separator. This feature will be removed in a major release after ``2021-07-01``.

+

+Porting Guide for v2.10.0a2

+===========================

+

+Breaking Changes

+----------------

+

+community.general

+~~~~~~~~~~~~~~~~~

+

+- The environment variable for the auth context for the oc.py connection plugin has been corrected (K8S_CONTEXT).  It was using an initial lowercase k by mistake. (https://github.com/ansible-collections/community.general/pull/377).

+- bigpanda - the parameter ``message`` was renamed to ``deployment_message`` since ``message`` is used by Ansible Core engine internally.

+- cisco_spark - the module option ``message`` was renamed to ``msg``, as ``message`` is used internally in Ansible Core engine (https://github.com/ansible/ansible/issues/39295)

+- datadog - the parameter ``message`` was renamed to ``notification_message`` since ``message`` is used by Ansible Core engine internally.

+- docker_container - no longer passes information on non-anonymous volumes or binds as ``Volumes`` to the Docker daemon. This increases compatibility with the ``docker`` CLI program. Note that if you specify ``volumes: strict`` in ``comparisons``, this could cause existing containers created with docker_container from Ansible 2.9 or earlier to restart.

+- docker_container - support for port ranges was adjusted to be more compatible to the ``docker`` command line utility: a one-port container range combined with a multiple-port host range will no longer result in only the first host port be used, but the whole range being passed to Docker so that a free port in that range will be used.

+- hashi_vault lookup - now returns the latest version when using the KV v2 secrets engine. Previously, it returned all versions of the secret which required additional steps to extract and filter the desired version.

+

+community.network

+~~~~~~~~~~~~~~~~~

+

+- routeros_facts - allow multiple addresses and neighbors per interface. This makes ``ansible_net_neighbors`` a list instead of a dict (https://github.com/ansible-collections/community.network/pull/6).

+

+Major Changes

+-------------

+

+Ansible-base

+~~~~~~~~~~~~

+

+- Both ansible-doc and ansible-console's help command will error for modules and plugins whose return documentation cannot be parsed as YAML. All modules and plugins passing ``ansible-test sanity --test yamllint`` will not be affected by this.

+- Collections may declare a list of supported/tested Ansible versions for the collection. A warning is issued if a collection does not support the Ansible version that loads it (can also be configured as silent or a fatal error). Collections that do not declare supported Ansible versions do not issue a warning/error.

+- Plugin routing allows collections to declare deprecation, redirection targets, and removals for all plugin types.

+- Plugins that import module_utils and other ansible namespaces that have moved to collections should continue to work unmodified.

+- Routing data built into Ansible 2.10 ensures that 2.9 content should work unmodified on 2.10. Formerly included modules and plugins that were moved to collections are still accessible by their original unqualified names, so long as their destination collections are installed.

+- When deprecations are done in code, they to specify a ``collection_name`` so that deprecation warnings can mention which collection - or ansible-base - is deprecating a feature. This affects all ``Display.deprecated()`` or ``AnsibleModule.deprecate()`` or ``Ansible.Basic.Deprecate()`` calls, and ``removed_in_version``/``removed_at_date`` or ``deprecated_aliases`` in module argument specs.

+- ansible-test now uses a different ``default`` test container for Ansible Collections

+

+community.general

+~~~~~~~~~~~~~~~~~

+

+- docker_container - the ``network_mode`` option will be set by default to the name of the first network in ``networks`` if at least one network is given and ``networks_cli_compatible`` is ``true`` (will be default from community.general 2.0.0 on). Set to an explicit value to avoid deprecation warnings if you specify networks and set ``networks_cli_compatible`` to ``true``. The current default (not specifying it) is equivalent to the value ``default``.

+- docker_container - the module has a new option, ``container_default_behavior``, whose default value will change from ``compatibility`` to ``no_defaults``. Set to an explicit value to avoid deprecation warnings.

+- gitlab_user - no longer requires ``name``, ``email`` and ``password`` arguments when ``state=absent``.

+- zabbix_action - no longer requires ``esc_period`` and ``event_source`` arguments when ``state=absent``.

+

+community.kubernetes

+~~~~~~~~~~~~~~~~~~~~

+

+- Add changelog and fragments and document changelog process (https://github.com/ansible-collections/community.kubernetes/pull/131).

+

+Removed Features

+----------------

+

+Ansible-base

+~~~~~~~~~~~~

+

+- core - remove support for ``check_invalid_arguments`` in ``AnsibleModule``, ``AzureModule`` and ``UTMModule``.

+

+community.crypto

+~~~~~~~~~~~~~~~~

+

+- The ``letsencrypt`` module has been removed. Use ``acme_certificate`` instead.

+

+community.general

+~~~~~~~~~~~~~~~~~

+

+- core - remove support for ``check_invalid_arguments`` in ``UTMModule``.

+- logicmonitor - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541).

+- logicmonitor_facts - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541).

+- pacman - Removed deprecated ``recurse`` option, use ``extra_args=--recursive`` instead

+

+community.vmware

+~~~~~~~~~~~~~~~~

+

+- vmware_guest_find - Removed deprecated ``datacenter`` option

+- vmware_vmkernel - Removed deprecated ``ip_address`` option; use sub-option ip_address in the network option instead

+- vmware_vmkernel - Removed deprecated ``subnet_mask`` option; use sub-option subnet_mask in the network option instead

+

+Deprecated Features

+-------------------

+

+Ansible-base

+~~~~~~~~~~~~

+

+- Using the DefaultCallback without the correspodning doc_fragment or copying the documentation.

+- hash_behaviour - Deprecate ``hash_behaviour`` for future removal.

+- script inventory plugin - The 'cache' option is deprecated and will be removed in 2.12. Its use has been removed from the plugin since it has never had any effect.

+

+community.crypto

+~~~~~~~~~~~~~~~~

+

+- openssl_csr - all values for the ``version`` option except ``1`` are deprecated. The value 1 denotes the current only standardized CSR version.

+

+community.general

+~~~~~~~~~~~~~~~~~

+

+- airbrake_deployment - Add deprecation notice for ``token`` parameter and v2 api deploys. This feature will be removed in community.general 3.0.0.

+- clc_aa_policy - The ``wait`` option had no effect and will be removed in community.general 3.0.0.

+- clc_aa_policy - the ``wait`` parameter will be removed. It has always been ignored by the module.

+- docker_container - the ``trust_image_content`` option is now deprecated and will be removed in community.general 3.0.0. It has never been used by the module.

+- docker_container - the ``trust_image_content`` option will be removed. It has always been ignored by the module.

+- docker_container - the default of ``container_default_behavior`` will change from ``compatibility`` to ``no_defaults`` in community.general 3.0.0. Set the option to an explicit value to avoid a deprecation warning.

+- docker_container - the default value for ``network_mode`` will change in community.general 3.0.0, provided at least one network is specified and ``networks_cli_compatible`` is ``true``. See porting guide, module documentation or deprecation warning for more details.

+- docker_stack - Return values ``out`` and ``err`` have been deprecated and will be removed in community.general 3.0.0. Use ``stdout`` and ``stderr`` instead.

+- docker_stack - the return values ``err`` and ``out`` have been deprecated. Use ``stdout`` and ``stderr`` from now on instead.

+- helm - Put ``helm`` module to deprecated. New implementation is available in community.kubernetes collection.

+- redfish_config - Deprecate ``bios_attribute_name`` and ``bios_attribute_value`` in favor of new `bios_attributes`` option.

+- redfish_config - the ``bios_attribute_name`` and ``bios_attribute_value`` options will be removed. To maintain the existing behavior use the ``bios_attributes`` option instead.

+- redfish_config and redfish_command - the behavior to select the first System, Manager, or Chassis resource to modify when multiple are present will be removed. Use the new ``resource_id`` option to specify target resource to modify.

+- redfish_config, redfish_command - Behavior to modify the first System, Mananger, or Chassis resource when multiple are present is deprecated. Use the new ``resource_id`` option to specify target resource to modify.

+- xbps - the ``force`` option never had any effect. It is now deprecated, and will be removed in 3.0.0 (https://github.com/ansible-collections/community.general/pull/568).

+- zabbix_proxy - deprecates ``interface`` sub-options ``type`` and ``main`` when proxy type is set to passive via ``status=passive``. Make sure these suboptions are removed from your playbook as they were never supported by Zabbix in the first place.

+

+community.vmware

+~~~~~~~~~~~~~~~~

+

+- vmware_dns_config - Deprecate in favour of new module vmware_host_dns.

+

+Porting Guide for v2.10.0a1

+===========================

+

+Breaking Changes

+----------------

+

+- amazon.aws.aws_s3 - can now delete versioned buckets even when they are not empty - set mode to delete to delete a versioned bucket and everything in it.

+- ansible.windows.win_find - module has been refactored to better match the behaviour of the ``find`` module. Here is what has changed:

+    * When the directory specified by ``paths`` does not exist or is a file, it will no longer fail and will just warn the user

+    * Junction points are no longer reported as ``islnk``, use ``isjunction`` to properly report these files. This behaviour matches the ansible.windows.win_stat module

+    * Directories no longer return a ``size``, this matches the ``stat`` and ``find`` behaviour and has been removed due to the difficulties in correctly reporting the size of a directory

+- cisco.nxos.nxos_igmp_interface - no longer supports the deprecated ``oif_prefix`` and ``oif_source`` options. These have been superceeded by ``oif_ps``.

+- community.general.pacman - the deprecated ``recurse`` option has been removed, you should use ``extra_args=--recursive`` instead.

+- community.grafana.grafana_dashboard - the parameter ``message`` is renamed to ``commit_message`` since ``message`` is used by Ansible Core engine internally.

+- community.vmware.vmware_datastore_maintenancemode - now returns ``datastore_status`` instead of Ansible internal key ``results``.

+- community.vmware.vmware_guest_custom_attributes - does not require VM name which was a required parameter for releases prior to Ansible 2.10.

+- community.vmware.vmware_guest_find - the ``datacenter`` option has been removed.

+- community.vmware.vmware_host_kernel_manager - now returns ``host_kernel_status`` instead of Ansible internal key ``results``.

+- community.vmware.vmware_host_ntp - now returns ``host_ntp_status`` instead of Ansible internal key ``results``.

+- community.vmware.vmware_host_service_manager - now returns ``host_service_status`` instead of Ansible internal key ``results``.

+- community.vmware.vmware_tag - now returns ``tag_status`` instead of Ansible internal key ``results``.

+- community.vmware.vmware_vmkernel - the options ``ip_address`` and ``subnet_mask`` have been removed; use the suboptions ``ip_address`` and ``subnet_mask`` of the ``network`` option instead.

+- community.windows.win_pester - no longer runs all ``*.ps1`` file in the directory specified due to it executing potentially unknown scripts. It will follow the default behaviour of only running tests for files that are like ``*.tests.ps1`` which is built into Pester itself.

+- purestorage.flashblade.purefb_fs - no longer supports the deprecated ``nfs`` option. This has been superceeded by ``nfsv3``.

+

+Major Changes

+-------------

+

+- amazon.aws.ec2 module_utils: The ``AWSRetry`` decorator no longer catches ``NotFound`` exceptions by default.  ``NotFound`` exceptions need to be explicitly added using ``catch_extra_error_codes``.  Some AWS modules may see an increase in transient failures due to AWS's eventual consistency model.

+

+community.kubernetes

+~~~~~~~~~~~~~~~~~~~~

+

+- helm - New module for managing Helm charts (https://github.com/ansible-collections/community.kubernetes/pull/61).

+- helm_info - New module for retrieving Helm chart information (https://github.com/ansible-collections/community.kubernetes/pull/61).

+- helm_repository - New module for managing Helm repositories (https://github.com/ansible-collections/community.kubernetes/pull/61).

+- k8s - Inventory source migrated from Ansible 2.9 to Kubernetes collection.

+- k8s - Lookup plugin migrated from Ansible 2.9 to Kubernetes collection.

+- k8s - Module migrated from Ansible 2.9 to Kubernetes collection.

+- k8s_auth - Module migrated from Ansible 2.9 to Kubernetes collection.

+- k8s_config_resource_name - Filter plugin migrated from Ansible 2.9 to Kubernetes collection.

+- k8s_exec - New module for executing commands on pods via Kubernetes API (https://github.com/ansible-collections/community.kubernetes/pull/14).

+- k8s_info - Module migrated from Ansible 2.9 to Kubernetes collection.

+- k8s_log - New module for retrieving pod logs (https://github.com/ansible-collections/community.kubernetes/pull/16).

+- k8s_scale - Module migrated from Ansible 2.9 to Kubernetes collection.

+- k8s_service - Module migrated from Ansible 2.9 to Kubernetes collection.

+- kubectl - Connection plugin migrated from Ansible 2.9 to Kubernetes collection.

+- openshift - Inventory source migrated from Ansible 2.9 to Kubernetes collection.

+

+Removed Features

+----------------

+

+- ansible.windows.win_stat - removed the deprecated ``get_md55`` option and ``md5`` return value.

+- community.windows.win_psexec - removed the deprecated ``extra_opts`` option.

+

+Deprecated Features

+-------------------

+

+- The community.general.ldap_attr module has been deprecated and will be removed in a later release; use community.general.ldap_attrs instead.

+- The community.vmware.vmware_dns_config module has been deprecated and will be removed in a later release; use community.vmware.vmware_host_dns instead.

+- The vyos.vyos.vyos_static_route module has been deprecated and will be removed in a later release; use vyos.vyos.vyos_static_routes instead.

+- amazon.aws.cloudformation - the ``template_format`` option has been deprecated and will be removed in a later release. It has been ignored by the module since Ansible 2.3.

+- amazon.aws.ec2 - in a later release, the ``group`` and ``group_id`` options will become mutually exclusive.  Currently ``group_id`` is ignored if you pass both.

+- amazon.aws.ec2_key - the ``wait_timeout`` option has been deprecated and will be removed in a later release. It has had no effect since Ansible 2.5.

+- amazon.aws.ec2_key - the ``wait`` option has been deprecated and will be removed in a later release. It has had no effect since Ansible 2.5.

+- amazon.aws.ec2_tag - support for ``list`` as a state has been deprecated and will be removed in a later release.  The ``ec2_tag_info`` can be used to fetch the tags on an EC2 resource.

+- ansible.windows.win_domain_controller - the ``log_path`` option has been deprecated and will be removed in a later release. This was undocumented and only related to debugging information for module development.

+- ansible.windows.win_package - the ``ensure`` alias for the ``state`` option has been deprecated and will be removed in a later release. Please use ``state`` instead of ``ensure``.

+- ansible.windows.win_package - the ``productid`` alias for the ``product_id`` option has been deprecated and will be removed in a later release. Please use ``product_id`` instead of ``productid``.

+- ansible.windows.win_package - the ``username`` and ``password`` options has been deprecated and will be removed in a later release. The same functionality can be done by using ``become: yes`` and ``become_flags: logon_type=new_credentials logon_flags=netcredentials_only`` on the task.

+- community.aws.data_pipeline - the ``version`` option has been deprecated and will be removed in a later release. It has always been ignored by the module.

+- community.aws.ec2_eip - the ``wait_timeout`` option has been deprecated and will be removed in a later release. It has had no effect since Ansible 2.3.

+- community.aws.ec2_lc - the ``associate_public_ip_address`` option has been deprecated and will be removed in a later release. It has always been ignored by the module.

+- community.aws.elb_network_lb - in a later release, the default behaviour for the ``state`` option will change from ``absent`` to ``present``.  To maintain the existing behavior explicitly set state to ``absent``.

+- community.aws.iam_managed_policy - the ``fail_on_delete`` option has been deprecated and will be removed in a later release.  It has always been ignored by the module.

+- community.aws.iam_policy - in a later release, the default value for the ``skip_duplicates`` option will change from ``true`` to ``false``.  To maintain the existing behavior explicitly set it to ``true``.

+- community.aws.iam_policy - the ``policy_document`` option has been deprecated and will be removed in a later release. To maintain the existing behavior use the ``policy_json`` option and read the file with the ``lookup`` plugin.

+- community.aws.iam_role - in a later release, the ``purge_policies`` option (also know as ``purge_policy``) default value will change from ``true`` to ``false``

+- community.aws.s3_lifecycle - the ``requester_pays`` option has been deprecated and will be removed in a later release. It has always been ignored by the module.

+- community.aws.s3_sync - the ``retries`` option has been deprecated and will be removed in a later release. It has always been ignored by the module.

+- community.vmware.vmware_tag_info - in a later release, the module will not return ``tag_facts`` since it does not return multiple tags with the same name and different category id. To maintain the existing behavior use ``tag_info`` which is a list of tag metadata.

new file mode 100644

@@ -0,0 +1,160 @@

+

+.. _porting_2.10_guide_base:

+

+*******************************

+Ansible-base 2.10 Porting Guide

+*******************************

+

+.. warning::

+

+	In preparation for the release of 2.10, many plugins and modules have migrated to Collections on  `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/master/README.rst>`_. We expect the 2.10 Porting Guide to change frequently up to the 2.10 release. Follow the conversations about collections on our various :ref:`communication` channels for the latest information on the status of the ``devel`` branch.

+

+This section discusses the behavioral changes between Ansible 2.9 and Ansible-base 2.10.

+

+It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible-base.

+

+We suggest you read this page along with the `Ansible-base Changelog for 2.10 <https://github.com/ansible/ansible/blob/stable-2.10/changelogs/CHANGELOG-v2.10.rst>`_ to understand what updates you may need to make.

+

+Ansible-base is mainly of interest for developers and users who only want to use a small, controlled subset of the available collections. Regular users should install ansible.

+

+The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.

+

+.. contents::

+

+

+Playbook

+========

+

+* Fixed a bug on boolean keywords that made random strings return 'False', now they should return an error if they are not a proper boolean

+  Example: `diff: yes-` was returning `False`.

+* A new fact, ``ansible_processor_nproc`` reflects the number of vcpus

+  available to processes (falls back to the number of vcpus available to

+  the scheduler).

+

+

+Command Line

+============

+

+No notable changes

+

+

+Deprecated

+==========

+

+* Windows Server 2008 and 2008 R2 will no longer be supported or tested in the next Ansible release, see :ref:`windows_faq_server2008`.

+

+

+Modules

+=======

+

+Change to Default File Permissions

+----------------------------------

+

+To address CVE-2020-1736, the default permissions for certain files created by Ansible using ``atomic_move()`` were changed from ``0o666`` to ``0o600``. The default permissions value was only used for the temporary file before it was moved into its place or newly created files. If the file existed when the new temporary file was moved into place, Ansible would use the permissions of the existing file. If there was no existing file, Ansible would retain the default file permissions, combined with the system ``umask``, of the temporary file.

+

+Most modules that call ``atomic_move()`` also call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()``, which will set the permissions of the file to what is specified in the task.

+

+A new warning will be displayed when all of the following conditions are true:

+

+    - The file at the final destination, not the temporary file, does not exist

+    - A module supports setting ``mode`` but it was not specified for the task

+    - The module calls ``atomic_move()`` but does not later call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()`` with a ``mode`` specified

+

+The following modules call ``atomic_move()`` but do not call ``set_fs_attributes_if_different()``  or ``set_mode_if_different()`` and do not support setting ``mode``. This means for files they create, the default permissions have changed and there is no indication:

+

+    - M(known_hosts)

+    - M(service)

+

+

+Code Audit

+~~~~~~~~~~

+

+The code was audited for modules that use ``atomic_move()`` but **do not** later call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()``. Modules that provide no means for specifying the ``mode`` will not display a warning message since there is no way for the playbook author to remove the warning. The behavior of each module with regards to the default permissions of temporary files and the permissions of newly created files is explained below.

+

+known_hosts

+^^^^^^^^^^^

+

+The M(known_hosts) module uses ``atomic_move()`` to operate on the ``known_hosts`` file specified by the ``path`` parameter in the module. It creates a temporary file using ``tempfile.NamedTemporaryFile()`` which creates a temporary file that is readable and writable only by the creating user ID.

+

+service

+^^^^^^^

+

+The M(service) module uses ``atomic_move()`` to operate on the default rc file, which is the first found of ``/etc/rc.conf``,  ``/etc/rc.conf.local``, and ``/usr/local/etc/rc.conf``. Since these files almost always exist on the target system, they will not be created and the existing permissions of the file will be used.

+

+**The following modules were included in Ansible <= 2.9. They have moved to collections but are documented here for completeness.**

+

+authorized_key

+^^^^^^^^^^^^^^

+

+The M(authorized_key) module uses ``atomic_move()`` to operate on the the ``authorized_key`` file. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. The M(authorized_key) module manages the permissions of the the ``.ssh`` direcotry and ``authorized_keys`` files if ``managed_dirs`` is set to ``True``, which is the default. The module sets the ``ssh`` directory owner and group to the ``uid`` and ``gid`` of the user specified in the ``user`` parameter and directory permissions to ``700``. The module sets the ``authorized_key`` file owner and group to the ``uid`` and ``gid`` of the user specified in the ``user`` parameter and file permissions to ``600``. These values cannot be controlled by module parameters.

+

+interfaces_file

+^^^^^^^^^^^^^^^

+The M(interfaces_file) module uses ``atomic_move()`` to operate on ``/etc/network/serivces`` or the ``dest`` specified by the module. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. If the file specified by ``path`` does not exist it will retain the permissions of the temporary file once moved into place.

+

+pam_limits

+^^^^^^^^^^

+

+The M(pam_limits) module uses ``atomic_move()`` to operate on ``/etc/security/limits.conf`` or the value of ``dest``. A temporary file is created using ``tempfile.NamedTemporaryFile()``, which is only readable and writable by the creating user ID. The temporary file will inherit the permissions of the file specified by ``dest``, or it will retain the permissions that only allow the creating user ID to read and write the file.

+

+pamd

+^^^^

+

+The M(pamd) module uses ``atomic_move()`` to operate on a file in ``/etc/pam.d``. The path and the file can be specified by setting the ``path`` and ``name`` parameters. A temporary file is created using ``tempfile.NamedTemporaryFile()``, which is only readable and writable by the creating user ID. The temporary file will inherit the permissions of the file located at ``[dest]/[name]``, or it will retain the permissions of the temporary file that only allow the creating user ID to read and write the file.

+

+redhat_subscription

+^^^^^^^^^^^^^^^^^^^

+

+The M(redhat_subscription) module uses ``atomic_move()`` to operate on ``/etc/yum/pluginconf.d/rhnplugin.conf`` and ``/etc/yum/pluginconf.d/subscription-manager.conf``. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID and the temporary file will inherit the permissions of the existing file once it is moved in to place.

+

+selinux

+^^^^^^^

+

+The M(selinux) module uses ``atomic_move()`` to operate on ``/etc/selinux/config`` on the value specified by ``configfile``. The module will fail if ``configfile`` does not exist before any temporary data is written to disk. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. Since the file specified by ``configfile`` must exist, the temporary file will inherit the permissions of that file once it is moved in to place.

+

+sysctl

+^^^^^^

+

+The M(sysctl) module uses ``atomic_move()`` to operate on ``/etc/sysctl.conf`` or the value specified by ``sysctl_file``. The module will fail if ``sysctl_file`` does not exist before any temporary data is written to disk. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. Since the file specified by ``sysctl_file`` must exist, the temporary file will inherit the permissions of that file once it is moved in to place.

+

+.. warning::

+

+	Links on this page may not point to the most recent versions of modules. We will update them when we can.

+

+

+Noteworthy module changes

+-------------------------

+

+* Ansible modules created with ``add_file_common_args=True`` added a number of undocumented arguments which were mostly there to ease implementing certain action plugins. The undocumented arguments ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``, ``delimiter``, and ``directory_mode`` are now no longer added. Modules relying on these options to be added need to specify them by themselves.

+* Ansible no longer looks for Python modules in the current working directory (typically the ``remote_user``'s home directory) when an Ansible module is run. This is to fix becoming an unprivileged user on OpenBSD and to mitigate any attack vector if the current working directory is writable by a malicious user. Install any Python modules needed to run the Ansible modules on the managed node in a system-wide location or in another directory which is in the ``remote_user``'s ``$PYTHONPATH`` and readable by the ``become_user``.

+

+

+Plugins

+=======

+

+Lookup plugin names case-sensitivity

+------------------------------------

+

+* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked via ``with_<lookup_name>``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive.

+

+Noteworthy plugin changes

+-------------------------

+

+* Cache plugins in collections can be used to cache data from inventory plugins. Previously, cache plugins in collections could only be used for fact caching.

+* Some undocumented arguments from ``FILE_COMMON_ARGUMENTS`` have been removed; plugins using these, in particular action plugins, need to be adjusted. The undocumented arguments which were removed are ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``, ``delimiter``, and ``directory_mode``.

+

+Action plugins which execute modules should use fully-qualified module names

+----------------------------------------------------------------------------

+

+* Action plugins that call modules should pass explicit, fully-qualified module names to ``_execute_module()`` whenever possible (eg, ``ansible.builtin.file`` rather than ``file``). This ensures that the task's collection search order is not consulted to resolve the module. Otherwise, a module from a collection earlier in the search path could be used when not intended.

+

+Porting custom scripts

+======================

+

+No notable changes

+

+

+Networking

+==========

+

+No notable changes

@@ -13,6 +13,7 @@ Please note that this is not a complete list. If you believe any extra informati

    :glob:

    porting_guide_2.10

+   porting_guide_base_2.10

    porting_guide_2.9

    porting_guide_2.8

    porting_guide_2.7