[stable-2.10] Update the porting guide for ansible-2.10.0b1 (#71583). (#71584)

(cherry picked from commit 1882c60b04)

Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>

docs/docsite/rst/porting_guides/porting_guide_2.10.rst

@@ -27,11 +27,12 @@ The :ref:`porting_2.10_guide_base` is included in this porting guide. The comple
   :local:
   :depth: 2
 
+
 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`.
+  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).
@@ -56,47 +57,9 @@ Modules
 
 	Links on this page may not point to the most recent versions of modules. We will update them when we can.
 
-Deprecation notices
+* Version 2.10.0 of ansible-base changed the default mode of file-based tasks to ``0o600 & ~umask`` when the user did not specify a ``mode`` parameter on file-based tasks. This was in response to a CVE report which we have reconsidered. As a result, the mode change has been reverted in 2.10.1, and mode will now default to ``0o666 & ~umask`` as in previous versions of Ansible.
--------------------
+* If you changed any tasks to specify less restrictive permissions while using 2.10.0, those changes will be unnecessary (but will do no harm) in 2.10.1.
-
+* To avoid the issue raised in CVE-2020-1736, specify a ``mode`` parameter in all file-based tasks that accept it.
-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``.
-
-
-Code Audit
-~~~~~~~~~~
-
-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
@@ -130,6 +93,124 @@ Porting custom scripts
 
 No notable changes
 
+Porting Guide for v2.10.0b1
+===========================
+
+Breaking Changes
+----------------
+
+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 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
+- win_user - Change idempotency checks for ``description`` to be case sensitive
+- win_user - Change idempotency checks for ``fullname`` to be case sensitive
+
+cisco.meraki
+~~~~~~~~~~~~
+
+- meraki_device - Changed tags from string to list
+- meraki_device - Removed serial_lldp_cdp parameter
+- meraki_device - Removed serial_uplink parameter
+- meraki_intrusion_prevention - Rename whitedlisted_rules to allowed_rules
+- meraki_mx_l3_firewall - Rule responses are now in a `rules` list
+- meraki_mx_l7_firewall - Rename blacklisted_countries to blocked_countries
+- meraki_mx_l7_firewall - Rename whitelisted_countries to allowed_countries
+- meraki_network - Local and remote status page settings cannot be set during network creation
+- meraki_network - `disableRemoteStatusPage` response is now `remote_status_page_enabled`
+- meraki_network - `disable_my_meraki_com` response is now `local_status_page_enabled`
+- meraki_network - `disable_my_meraki` has been deprecated
+- meraki_network - `enable_my_meraki` is now called `local_status_page_enabled`
+- meraki_network - `enable_remote_status_page` is now called `remote_status_page_enabled`
+- meraki_network - `enabled` response for VLAN status is now `vlans_enabled`
+- meraki_network - `tags` and `type` now return a list
+- meraki_snmp - peer_ips is now a list
+- meraki_switchport - `access_policy_number` is now an int and not a string
+- meraki_switchport - `tags` is now a list and not a string
+- meraki_webhook - Querying test status now uses state of query.
+
+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.
+
+community.zabbix
+~~~~~~~~~~~~~~~~
+
+- zabbix_javagateway - options ``javagateway_pidfile``, ``javagateway_listenip``, ``javagateway_listenport`` and ``javagateway_startpollers`` renamed to ``zabbix_javagateway_xyz`` (see `UPGRADE.md <https://github.com/ansible-collections/community.zabbix/blob/main/docs/UPGRADE.md>`_).
+
+Major Changes
+-------------
+
+cisco.meraki
+~~~~~~~~~~~~
+
+- Rewrite requests method for version 1.0 API and improved readability
+- meraki_mr_rf_profile - Configure wireless RF profiles.
+- meraki_mr_settings - Configure network settings for wireless.
+- meraki_ms_l3_interface - New module
+- meraki_ms_ospf - Configure OSPF.
+
+community.grafana
+~~~~~~~~~~~~~~~~~
+
+- Add changelog management for ansible 2.10 (#112)
+- grafana_datasource ; adding additional_json_data param
+
+community.libvirt
+~~~~~~~~~~~~~~~~~
+
+- added generic libvirt inventory plugin
+- removed libvirt_lxc inventory script
+
+Removed Collections
+-------------------
+
+- skydive.skydive (previously included version: 0.0.1-dev7)
+
+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
+-------------------
+
+amazon.aws
+~~~~~~~~~~
+
+- All AWS Modules - ``aws_access_key``, ``aws_secret_key`` and ``security_token`` will be made mutually exclusive with ``profile`` after 2022-06-01.
+
+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.
+- 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``.
+- 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``.
+- 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.vmware
+~~~~~~~~~~~~~~~~
+
+- vmware_guest - deprecate specifying CDROM configuration as a dict, instead use a list.
+
+openstack.cloud
+~~~~~~~~~~~~~~~
+
+- foo - The bar option has been deprecated. Use the username option instead.
+- send_request - The quic option has been deprecated. Use the protocol option instead.
+
 Porting Guide for v2.10.0a9
 ===========================
 
@@ -149,6 +230,19 @@ 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.
 
+gluster.gluster
+~~~~~~~~~~~~~~~
+
+- geo_rep - Added the independent module of geo rep with other gluster modules (https://github.com/gluster/gluster-ansible-collection/pull/2).
+
+ovirt.ovirt
+~~~~~~~~~~~
+
+- ovirt_disk - Add backup (https://github.com/oVirt/ovirt-ansible-collection/pull/57).
+- ovirt_disk - Support direct upload/download (https://github.com/oVirt/ovirt-ansible-collection/pull/35).
+- ovirt_host - Add ssh_port (https://github.com/oVirt/ovirt-ansible-collection/pull/60).
+- ovirt_vm_os_info - Creation of module (https://github.com/oVirt/ovirt-ansible-collection/pull/26).
+
 purestorage.flasharray
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -206,7 +300,7 @@ 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.
 - 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.
 - ec2_lc - The ``associate_public_ip_address`` option had no effect and will be removed after 2022-06-01
-- ec2_tag - deprecate the `list` option in favor of ec2_tag_info
+- ec2_tag - deprecate the ``list`` option in favor of ec2_tag_info
 - 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.
 
 community.aws
@@ -353,6 +447,43 @@ 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.0a3
+===========================
+
+Breaking Changes
+----------------
+
+netbox.netbox
+~~~~~~~~~~~~~
+
+- To pass in integers via Ansible Jinja filters for a key in ``data`` that
+  requires querying an endpoint is now done by making it a dictionary with
+  an ``id`` key. The previous behavior was to just pass in an integer and
+  it was converted when normalizing the data, but some people may have names
+  that are all integers and those were being converted erroneously so we made
+  the decision to change the method to convert to an integer for the NetBox
+  API.
+
+  ::
+
+    tasks:
+      - name: Create device within NetBox with only required information
+        netbox_device:
+          netbox_url: http://netbox-demo.org:32768
+          netbox_token: 0123456789abcdef0123456789abcdef01234567
+          data:
+            name: Test66
+            device_type:
+              id: "{{ some_jinja_variable }}"
+            device_role: Core Switch
+            site: Test Site
+            status: Staged
+          state: present
+- ``pynetbox`` changed to using ``requests.Session()`` to manage the HTTP session
+  which broke passing in ``ssl_verify`` when building the NetBox API client.
+  This PR makes ``pynetbox 5.0.4+`` the new required version of `pynetbox` for
+  the Ansible modules and lookup plugin. (https://github.com/netbox-community/ansible_modules/pull/269)
+
 Porting Guide for v2.10.0a2
 ===========================
 
@@ -375,6 +506,20 @@ 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).
 
+theforeman.foreman
+~~~~~~~~~~~~~~~~~~
+
+- All modules were renamed to drop the ``foreman_`` and ``katello_`` prefixes.
+  Additionally to the prefix removal, the following modules were further ranamed:
+
+  * katello_upload to content_upload
+  * katello_sync to repository_sync
+  * katello_manifest to subscription_manifest
+  * foreman_search_facts to resource_info
+  * foreman_ptable to partition_table
+  * foreman_model to hardware_model
+  * foreman_environment to puppet_environment
+
 Major Changes
 -------------
 
@@ -395,7 +540,6 @@ 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
 ~~~~~~~~~~~~~~~~~~~~
@@ -477,7 +621,6 @@ community.general
 - 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.
-- 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
 ~~~~~~~~~~~~~~~~
@@ -490,15 +633,23 @@ Porting Guide for v2.10.0a1
 Breaking Changes
 ----------------
 
-- 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.grafana.grafana_dashboard - the parameter ``message`` is renamed to ``commit_message`` since ``message`` is used by Ansible Core engine internally.
-- 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``.
 
+netbox.netbox
+~~~~~~~~~~~~~
+
+- Change ``ip-addresses`` key in netbox inventory plugin to ``ip_addresses`` (https://github.com/netbox-community/ansible_modules/issues/139)
+- Changed ``group`` to ``tenant_group`` in ``netbox_tenant.py`` (https://github.com/netbox-community/ansible_modules/issues/9)
+- Changed ``role`` to ``prefix_role`` in ``netbox_prefix.py`` (https://github.com/netbox-community/ansible_modules/issues/9)
+- Module failures when required fields arent provided (https://github.com/netbox-community/ansible_modules/issues/24)
+- Renamed ``netbox_interface`` to ``netbox_device_interface`` (https://github.com/netbox-community/ansible_modules/issues/9)
+- This version has a few breaking changes due to new namespace and collection name. I felt it necessary to change the name of the lookup plugin and inventory plugin just not to have a non descriptive namespace call to use them. Below is an example:
+  ``netbox.netbox.netbox`` would be used for both inventory plugin and lookup plugin, but in different contexts so no collision will arise, but confusion will.
+  I renamed the lookup plugin to ``nb_lookup`` so it will be used with the FQCN ``netbox.netbox.nb_lookup``.
+  The inventory plugin will now be called within an inventory file by ``netbox.netbox.nb_inventory``
+
 Major Changes
 -------------
 
@@ -521,17 +672,12 @@ community.kubernetes
 - 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 vyos.vyos.vyos_static_route module has been deprecated and will be removed in a later release; use vyos.vyos.vyos_static_routes instead.
-- 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``.
+community.zabbix
-- 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.
+
+- zabbix_proxy (module) - 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.