From 7d8b6dc779e1fc639203e29a241e3d10834b417d Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Tue, 1 Sep 2020 15:58:18 -0700 Subject: [PATCH] [stable-2.10] Update the porting guide for ansible-2.10.0b1 (#71583). (#71584) (cherry picked from commit 1882c60b04c96abd58dc7c40de65b73ed06fd6de) Co-authored-by: Toshio Kuratomi --- .../rst/porting_guides/porting_guide_2.10.rst | 266 ++++++++++++++---- 1 file changed, 206 insertions(+), 60 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst index 5c361477bb4..2eb411ed80f 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst +++ b/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 -------------------- - -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 `: the ``fail_on_delete`` option will be removed. It has always been ignored by the module. -* :ref:`s3_lifecycle `: the ``requester_pays`` option will be removed. It has always been ignored by the module. -* :ref:`s3_sync `: the ``retries`` option will be removed. It has always been ignored by the module. -* :ref:`cloudformation `: the ``template_format`` option will be removed. It has been ignored by the module since Ansible 2.3. -* :ref:`data_pipeline `: the ``version`` option will be removed. It has always been ignored by the module. -* :ref:`ec2_eip `: the ``wait_timeout`` option will be removed. It has had no effect since Ansible 2.3. -* :ref:`ec2_key `: the ``wait`` option will be removed. It has had no effect since Ansible 2.5. -* :ref:`ec2_key `: the ``wait_timeout`` option will be removed. It has had no effect since Ansible 2.5. -* :ref:`ec2_lc `: the ``associate_public_ip_address`` option will be removed. It has always been ignored by the module. -* :ref:`ec2_tag `: 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 `: 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 `: the ``log_path`` option will be removed. This was undocumented and only related to debugging information for module development. -* :ref:`win_package `: 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 `: the ``ensure`` alias for the ``state`` option will be removed. Please use ``state`` instead of ``ensure``. -* :ref:`win_package `: 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 `: the ``group`` and ``group_id`` options will become mutually exclusive. Currently ``group_id`` is ignored if you pass both. -* :ref:`iam_policy `: 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 `: the ``purge_policies`` option (also know as ``purge_policy``) default value will change from ``true`` to ``false`` -* :ref:`elb_network_lb `: 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 `: 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 `_). + +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.