Ansible 3 Porting Guide

Ansible 3 is based on Ansible-Base 2.10, which is the same major release as Ansible 2.10. Therefore, there is no section on ansible-base in this porting guide. If you are upgrading from Ansible 2.9, please first consult the Ansible 2.10 porting guide before continuing with the Ansible 3 porting guide.

We suggest you read this page along with the Ansible Changelog for 3.0 to understand what updates you may need to make.

Note

Due to a scheduling conflict, the latest version of Ansible 2.10 (2.10.7) has a few collections which are newer than Ansible 3.0.0. Ansible 3.1.0 will contain updated versions of those collections.

Porting Guide for v3.0.0

Breaking Changes

Ansible-base

ansible.utils

  • If added custom sub plugins in your collection move from old location plugins/<sub-plugin-name> to the new location plugins/sub_plugins/<sub-plugin-name> and update the imports as required
  • Move sub plugins cli_parsers, fact_diff and validate to plugins/sub_plugins folder
  • The cli_parsers sub plugins folder name is changed to cli_parse to have consistent naming convention, that is all the cli_parse subplugins will now be in plugins/sub_plugins/cli_parse folder

cloudscale_ch.cloud

  • floating_ip - name is required for assigning a new floating IP.

community.general

  • If you use Ansible 2.9 and the Google cloud plugins or modules from this collection, community.general 2.0.0 results in errors when trying to use the Google cloud content by FQCN, like community.general.gce_img. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (community.google.gce_img for the previous example) and to make sure that you have community.google installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install the community.google or google.cloud collections if you are using any of the Google cloud plugins or modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (such as community.google) must be installed for them to work.

  • If you use Ansible 2.9 and the Kubevirt plugins or modules from this collection, community.general 2.0.0 results in errors when trying to use the Kubevirt content by FQCN, like community.general.kubevirt_vm. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (community.kubevirt.kubevirt_vm for the previous example) and to make sure that you have community.kubevirt installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install the community.kubevirt collection if you are using any of the Kubevirt plugins or modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (such as community.google) must be installed for them to work.

  • If you use Ansible 2.9 and the docker plugins or modules from this collections, community.general 2.0.0 results in errors when trying to use the docker content by FQCN, like community.general.docker_container. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (community.docker.docker_container for the previous example) and to make sure that you have community.docker installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install community.docker if you are using any of the docker plugins or modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.docker) must be installed for them to work.

  • If you use Ansible 2.9 and the hashi_vault lookup plugin from this collections, community.general 2.0.0 results in errors when trying to use the Hashi Vault content by FQCN, like community.general.hashi_vault. Since Ansible 2.9 is not able to use redirections, you will have to adjust your inventories, variable files, playbooks and roles manually to use the new FQCN (community.hashi_vault.hashi_vault) and to make sure that you have community.hashi_vault installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install community.hashi_vault if you are using the hashi_vault plugin. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.hashi_vault) must be installed for them to work.

  • If you use Ansible 2.9 and the hetzner modules from this collections, community.general 2.0.0 results in errors when trying to use the hetzner content by FQCN, like community.general.hetzner_firewall. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (community.hrobot.firewall for the previous example) and to make sure that you have community.hrobot installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install community.hrobot if you are using any of the hetzner modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.hrobot) must be installed for them to work.

  • If you use Ansible 2.9 and the oc connection plugin from this collections, community.general 2.0.0 results in errors when trying to use the oc content by FQCN, like community.general.oc. Since Ansible 2.9 is not able to use redirections, you will have to adjust your inventories, variable files, playbooks and roles manually to use the new FQCN (community.okd.oc) and to make sure that you have community.okd installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install community.okd if you are using the oc plugin. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.okd) must be installed for them to work.

  • If you use Ansible 2.9 and the postgresql modules from this collections, community.general 2.0.0 results in errors when trying to use the postgresql content by FQCN, like community.general.postgresql_info. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (community.postgresql.postgresql_info for the previous example) and to make sure that you have community.postgresql installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.general manually, you need to make sure to also install community.postgresql if you are using any of the postgresql modules. While ansible-base 2.10 or newer can use the redirects that community.general 2.0.0 adds, the collection they point to (community.postgresql) must be installed for them to work.

  • The Google cloud inventory script gce.py has been migrated to the community.google collection. Install the community.google collection in order to continue using it.
  • archive - remove path folder itself when remove paramater is true (https://github.com/ansible-collections/community.general/issues/1041).
  • log_plays callback - add missing information to the logs generated by the callback plugin. This changes the log message format (https://github.com/ansible-collections/community.general/pull/442).
  • passwordstore lookup plugin - now parsing a password store entry as YAML if possible, skipping the first line (which by convention only contains the password and nothing else). If it cannot be parsed as YAML, the old key: value parser will be used to process the entry. Can break backwards compatibility if YAML formatted code was parsed in a non-YAML interpreted way, e.g. foo: [bar, baz] will become a list with two elements in the new version, but a string '[bar, baz]' in the old (https://github.com/ansible-collections/community.general/issues/1673).
  • pkgng - passing name: * with state: absent will no longer remove every installed package from the system. It is now a noop. (https://github.com/ansible-collections/community.general/pull/569).
  • pkgng - passing name: * with state: latest or state: present will no longer install every package from the configured package repositories. Instead, name: *, state: latest will upgrade all already-installed packages, and name: *, state: present is a noop. (https://github.com/ansible-collections/community.general/pull/569).
  • proxmox_kvm - recognize force=yes in conjunction with state=absent to forcibly remove a running VM (https://github.com/ansible-collections/community.general/pull/849).
  • utm_proxy_auth_profile - the frontend_cookie_secret return value now contains a placeholder string instead of the module’s frontend_cookie_secret parameter (https://github.com/ansible-collections/community.general/pull/1736).

community.hashi_vault

community.hrobot

community.network

  • If you use Ansible 2.9 and the FortiOS modules from this collection, community.network 2.0.0 results in errors when trying to use the FortiOS content by FQCN, like community.network.fmgr_device. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (community.fortios.fmgr_device for the previous example) and to make sure that you have community.fortios installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install community.fortios if you are using any of the FortiOS modules. While ansible-base 2.10 or newer can use the redirects that community.network 2.0.0 adds, the collection they point to (community.fortios) must be installed for them to work.

  • If you use Ansible 2.9 and the cp_publish module from this collection, community.network 2.0.0 results in errors when trying to use the module by FQCN, i.e. community.network.cp_publish. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (check_point.mgmt.cp_mgmt_publish) and to make sure that you have check_point.mgmt installed. If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install check_point.mgmt if you are using the cp_publish module. While ansible-base 2.10 or newer can use the redirects that community.network 2.0.0 adds, the collection they point to (check_point.mgmt) must be installed for them to work.

  • If you use Ansible 2.9 and the fortimanager httpapi plugin from this collection, community.network 2.0.0 results in errors when trying to use it by FQCN (community.network.fortimanager). Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCN fortinet.fortimanager.fortimanager and to make sure that you have fortinet.fortimanager installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install fortinet.fortimanager if you are using the fortimanager httpapi plugin. While ansible-base 2.10 or newer can use the redirect that community.network 2.0.0 adds, the collection they point to (fortinet.fortimanager) must be installed for it to work.

  • If you use Ansible 2.9 and the nso modules from this collection, community.network 2.0.0 results in errors when trying to use the nso content by FQCN, like community.network.nso_config. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (cisco.nso.nso_config for the previous example) and to make sure that you have cisco.nso installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install cisco.nso if you are using any of the nso modules. While ansible-base 2.10 or newer can use the redirects that community.network 2.0.0 adds, the collection they point to (cisco.nso) must be installed for them to work.

  • If you use Ansible 2.9 and the routeros plugins or modules from this collections, community.network 2.0.0 results in errors when trying to use the routeros content by FQCN, like community.network.routeros_command. Since Ansible 2.9 is not able to use redirections, you will have to adjust your playbooks and roles manually to use the new FQCNs (community.routeros.command for the previous example) and to make sure that you have community.routeros installed.

    If you use ansible-base 2.10 or newer and did not install Ansible 3.0.0, but installed (and/or upgraded) community.network manually, you need to make sure to also install community.routeros if you are using any of the routeros plugins or modules. While ansible-base 2.10 or newer can use the redirects that community.network 2.0.0 adds, the collection they point to (community.routeros) must be installed for them to work.

  • cnos_static_route - move ipaddress import from ansible.netcommon to builtin or package before ipaddress is removed from ansible.netcommon. You need to make sure to have the ipaddress package installed if you are using this module on Python 2.7 (https://github.com/ansible-collections/community.network/pull/129).

dellemc.os10

  • os10_bgp - Changed “subnet” key as list format instead of dictionary format under “listen” key to support multiple neighbor prefix for listen command
  • os10_bgp - Changed “vrf” key as list format instead of dictionary format to supprot multiple VRF in router BGP and changed the “vrf” key name to “vrfs”

ngine_io.cloudstack

  • Authentication option using INI files e.g. cloudstack.ini has been removed. The only supported option to authenticate is by using the module params with fallback to the ENV variables.
  • default zone deprecation - The zone param default value, across multiple modules, has been deprecated due to unreliable API (https://github.com/ngine-io/ansible-collection-cloudstack/pull/62).

Major Changes

cisco.aci

  • Change certificate_name to name in aci_aaa_user_certificate module for query operation

community.general

  • For community.general 3.0.0, the ome_device_info, idrac_firmware and idrac_server_config_profile modules will be moved to the dellemc.openmanage collection. A redirection will be inserted so that users using ansible-base 2.10 or newer do not have to change anything.

    If you use Ansible 2.9 and explicitly use the DellEMC modules mentioned above from this collection, you will need to adjust your playbooks and roles to use FQCNs starting with dellemc.openmanage. instead of community.general., for example replace community.general.ome_device_info in a task by dellemc.openmanage.ome_device_info.

    If you use ansible-base and installed community.general manually and rely on the DellEMC modules mentioned above, you have to make sure to install the dellemc.openmanage collection as well. If you are using FQCNs, for example community.general.ome_device_info instead of ome_device_info, it will continue working, but we still recommend to adjust the FQCNs as well.

  • The community.general collection no longer depends on the ansible.netcommon collection (https://github.com/ansible-collections/community.general/pull/1561).
  • The community.general collection no longer depends on the ansible.posix collection (https://github.com/ansible-collections/community.general/pull/1157).

community.kubernetes

community.okd

dellemc.os10

  • os10_bgp - Enhanced router bgp keyword support for non-default vrf which are supported for default vrf and additional keyword to support both default and non-default vrf
  • os10_snmp role - Added support for snmp V3 features in community, group, host, engineID

f5networks.f5_modules

  • Add phone home Teem integration into all modules, functionality can be disabled by setting up F5_TEEM environment variable or no_f5_teem provider parameter
  • Added async_timeout parameter to bigip_ucs_fetch module to allow customization of module wait for async interface
  • Changed bigip_ucs_fetch module to use asynchronous interface when generating UCS files

kubernetes.core

netbox.netbox

  • nb_inventory - Add dns_name option that adds dns_name to the host when True and device has a primary IP address. (#394)
  • nb_inventory - Add status as a group_by option. (398)
  • nb_inventory - Move around extracted_primary_ip to allow for config_context or custom_field to overwite. (#377)
  • nb_inventory - Services are now a list of integers due to NetBox 2.10 changes. (#396)
  • nb_lookup - Allow ID to be passed in and use .get instead of .filter. (#376)
  • nb_lookup - Allow api_endpoint and token to be found via env. (#391)

ovirt.ovirt

servicenow.servicenow

  • add new tests (find with no result, search many)
  • add related tests
  • add support for ServiceNOW table api display_value exclude_reference_link and suppress_pagination_header
  • use new API for pysnow >=0.6.0

Removed Features

community.docker

community.general

community.network

  • All FortiOS modules and plugins have been removed from this collection. They have been migrated to the community.fortios collection. If you use ansible-base 2.10 or newer, redirections have been provided.

    If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (community.network.fmgr_device → community.fortios.fmgr_device) and make sure to install the community.fortios collection.

  • All nso modules have been removed from this collection. They have been migrated to the cisco.nso collection. If you use ansible-base 2.10 or newer, redirections have been provided.

    If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (community.network.nso_config → cisco.nso.nso_config) and make sure to install the cisco.nso collection.

  • All routeros modules and plugins have been removed from this collection. They have been migrated to the community.routeros collection. If you use ansible-base 2.10 or newer, redirections have been provided.

    If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (community.network.routeros_command → community.routeros.command) and make sure to install the community.routeros collection.

  • The cp_publish module has been removed from this collection. It was a duplicate of check_point.mgmt.cp_mgmt_publish in the check_point.mgmt collection. If you use ansible-base 2.10 or newer, redirections have been provided. If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (community.network.cp_publish → check_point.mgmt.cp_mgmt_publish) and make sure to install the check_point.mgmt collection.

  • The fortimanager httpapi plugin has been removed from this collection. It was a duplicate of the one in the fortinet.fortimanager collection. If you use ansible-base 2.10 or newer, a redirection has been provided.

    If you use Ansible 2.9 and installed this collection, you need to adjust the FQCNs (community.network.fortimanager → fortinet.fortimanager.fortimanager) and make sure to install the fortinet.fortimanager collection.

  • The dependency on the check_point.mgmt collection has been removed. If you depend on that installing community.network also installs check_point.mgmt, you have to make sure to install check_point.mgmt explicitly.
  • The deprecated Pluribus Networks modules pn_cluster, pn_ospf, pn_ospfarea, pn_show, pn_trunk, pn_vlag, pn_vlan, pn_vrouter, pn_vrouterbgp, pn_vrouterif, pn_vrouterlbif have been removed (https://github.com/ansible-collections/community.network/pull/176).
  • The deprecated modules panos_admin, panos_admpwd, panos_cert_gen_ssh, panos_check, panos_commit, panos_dag, panos_dag_tags, panos_import, panos_interface, panos_lic, panos_loadcfg, panos_match_rule, panos_mgtconfig, panos_nat_rule, panos_object, panos_op, panos_pg, panos_query_rules, panos_restart, panos_sag, panos_security_rule, panos_set have been removed. Use modules from the paloaltonetworks.panos collection instead (https://github.com/ansible-collections/community.network/pull/176).
  • The redirect to the mellanox.onyx collection was removed for: the onyx cliconf plugin, terminal plugin, module_utils, action plugin, doc fragment, and the following modules: onyx_aaa, onyx_bfd, onyx_bgp, onyx_buffer_pool, onyx_command, onyx_config, onyx_facts, onyx_igmp, onyx_igmp_interface, onyx_igmp_vlan, onyx_interface, onyx_l2_interface, onyx_l3_interface, onyx_linkagg, onyx_lldp, onyx_lldp_interface, onyx_magp, onyx_mlag_ipl, onyx_mlag_vip, onyx_ntp, onyx_ntp_servers_peers, onyx_ospf, onyx_pfc_interface, onyx_protocol, onyx_ptp_global, onyx_ptp_interface, onyx_qos, onyx_snmp, onyx_snmp_hosts, onyx_snmp_users, onyx_syslog_files, onyx_syslog_remote, onyx_traffic_class, onyx_username, onyx_vlan, onyx_vxlan, onyx_wjh (https://github.com/ansible-collections/community.network/pull/175).
  • onyx - all onyx modules and plugins have been moved to the mellanox.onyx collection. Redirects have been added that will be removed in community.network 2.0.0 (https://github.com/ansible-collections/community.network/pull/83).

f5networks.f5_modules

  • Removed arp_state parameter from the bigip_virtual_address module

Deprecated Features

cisco.nxos

  • Deprecated nxos_bgp and nxos_bgp_neighbor modules in favor of nxos_bgp_global resource module.
  • Deprecated nxos_interface_ospf in favor of nxos_ospf_interfaces Resource Module.
  • Deprecated nxos_smu in favour of nxos_rpm module.
  • The nxos_ospf_vrf module is deprecated by nxos_ospfv2 and nxos_ospfv3 Resource Modules.

community.aws

community.docker

community.general

community.hashi_vault

community.network

community.vmware

  • vmware_host_firewall_manager - the creation of new rule with no allowed_ip entry in the allowed_hosts dictionary won’t be allowed after 2.0.0 release.

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/porting_guides/porting_guide_3.html