cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

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

Browse source 
(cherry picked from commit 1882c60b04)

Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
This commit is contained in:
Toshio Kuratomi 2020-09-01 15:58:18 -07:00 committed by GitHub
parent 6aaef596d6
commit 7d8b6dc779
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 206 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

266
docs/docsite/rst/porting_guides/porting_guide_2.10.rst
View file

@ -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
-------------------
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.
* 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.
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``.
- 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.zabbix
~~~~~~~~~~~~~~~~
- 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.