Ansible 4 Porting Guide

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

Playbook

  • The jinja2_native setting now does not affect the template module which implicitly returns strings. For the template lookup there is a new argument jinja2_native (off by default) to control that functionality. The rest of the Jinja2 expressions still operate based on the jinja2_native setting.

Command Line

  • The ansible-galaxy login command has been removed, as the underlying API it used for GitHub auth has been shut down. Publishing roles or collections to Galaxy with ansible-galaxy now requires that a Galaxy API token be passed to the CLI using a token file (default location ~/.ansible/galaxy_token) or (insecurely) with the --token argument to ansible-galaxy.

Deprecated

The constant ansible.module_utils.basic._CHECK_ARGUMENT_TYPES_DISPATCHER is deprecated. Use ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS instead.

Breaking Changes

Changes to AnsibleModule

With the move to ArgumentSpecValidator for performing argument spec validation, the following private methods in AnsibleModule have been removed:

Modules or plugins using these private methods should use the public functions in ansible.module_utils.common.validation or ArgumentSpecValidator.validate() if no public function was listed above.

Changes to ansible.module_utils.common.parameters

The following functions in ansible.module_utils.common.parameters are now private and should not be used directly. Use ArgumentSpecValidator.validate() instead.

  • list_no_log_values

  • list_deprecations

  • handle_aliases

Other

  • Upgrading: If upgrading from ansible < 2.10 or from ansible-base and using pip, you must pip uninstall ansible or pip uninstall ansible-base before installing ansible-core to avoid conflicts.

  • Python 3.8 on the controller node is a soft requirement for this release. ansible-core 2.11 still works with the same versions of Python that ansible-base 2.10 worked with, however 2.11 emits a warning when running on a controller node with a Python version less than 3.8. This warning can be disabled by setting ANSIBLE_CONTROLLER_PYTHON_WARNING=False in your environment. ansible-core 2.12 will require Python 3.8 or greater.

  • The configuration system now validates the choices field, so any settings that violate it and were ignored in 2.10 cause an error in 2.11. For example, ANSIBLE_COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH=0 now causes an error (valid choices are ignore, warn or error).

  • The ansible-galaxy command now uses resolvelib for resolving dependencies. In most cases this should not make a user-facing difference beyond being more performant, but we note it here for posterity and completeness.

  • If you import Python module_utils into any modules you maintain, you may now mark the import as optional during the module payload build by wrapping the import statement in a try or if block. This allows modules to use module_utils that may not be present in all versions of Ansible or a collection, and to perform arbitrary recovery or fallback actions during module runtime.

Modules

  • The apt_key module has explicitly defined file as mutually exclusive with data, keyserver and url. They cannot be used together anymore.

  • The meta module now supports tags for user-defined tasks. Set the task’s tags to ‘always’ to maintain the previous behavior. Internal meta tasks continue to always run.

Modules removed

The following modules no longer exist:

  • No notable changes

Deprecation notices

No notable changes

Noteworthy module changes

  • facts - On NetBSD, ansible_virtualization_type now tries to report a more accurate result than xen when virtualized and not running on Xen.

  • facts - Virtualization facts now include virtualization_tech_guest and virtualization_tech_host keys. These are lists of virtualization technologies that a guest is a part of, or that a host provides, respectively. As an example, if you set up a host to provide both KVM and VirtualBox, both values are included in virtualization_tech_host. Similarly, a podman container running on a VM powered by KVM has a virtualization_tech_guest of ["kvm", "podman", "container"].

  • The parameter filter type is changed from string to list in the setup module in order to use more than one filter. Previous behavior (using a string) still remains and works as a single filter.

Plugins

  • inventory plugins - CachePluginAdjudicator.flush() now calls the underlying cache plugin’s flush() instead of only deleting keys that it knows about. Inventory plugins should use delete() to remove any specific keys. As a user, this means that when an inventory plugin calls its clear_cache() method, facts could also be flushed from the cache. To work around this, users can configure inventory plugins to use a cache backend that is independent of the facts cache.

  • callback plugins - meta task execution is now sent to v2_playbook_on_task_start like any other task. By default, only explicit meta tasks are sent there. Callback plugins can opt-in to receiving internal, implicitly created tasks to act on those as well, as noted in the plugin development documentation.

  • The choices are now validated, so plugins that were using incorrect or incomplete choices issue an error in 2.11 if the value provided does not match. This has a simple fix: update the entries in choices to match reality.

Porting custom scripts

No notable changes

Porting Guide for v4.10.0

Major Changes

containers.podman

  • Add podman_tag module

  • Add secrets driver and driver opts support

Deprecated Features

cisco.nxos

  • Deprecated nxos_snmp_community module.

  • Deprecated nxos_snmp_contact module.

  • Deprecated nxos_snmp_host module.

  • Deprecated nxos_snmp_location module.

  • Deprecated nxos_snmp_traps module.

  • Deprecated nxos_snmp_user module.

junipernetworks.junos

  • ‘router_id’ options is deprecated from junos_ospf_interfaces, junos_ospfv2 and junos_ospfv3 resource module.

Porting Guide for v4.9.0

Known Issues

purestorage.flashblade

  • purefb_lag - The mac_address field in the response is not populated. This will be fixed in a future FlashBlade update.

Major Changes

fortinet.fortios

  • Add real-world use cases in the example section for some configuration modules.

  • Collect the current configurations of the modules and convert them into playbooks.

  • Support FortiOS 7.0.1.

  • Support member operation (delete/add extra members) on an object that has a list of members in it.

  • Support selectors feature in fortios_monitor_fact and fortios_log_fact.

Porting Guide for v4.8.0

Breaking Changes

community.zabbix

  • all roles now reference other roles and modules through their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (see issue 477).

Deprecated Features

community.azure

community.hashi_vault

Porting Guide for v4.7.0

Major Changes

openvswitch.openvswitch

  • By mistake we tagged the repo to 2.0.0 and as it wasn’t intended and cannot be reverted we’re releasing 2.0.1 to make the community aware of the major version update.

Deprecated Features

cisco.ios

  • Deprecated ios_ntp modules.

cisco.nxos

  • Deprecated nxos_ntp, nxos_ntp_options, nxos_ntp_auth modules.

community.vmware

junipernetworks.junos

  • Deprecated router_id from ospfv2 resource module.

Porting Guide for v4.6.0

Major Changes

containers.podman

  • Add systemd generation for pods

  • Generate systemd service files for containers

gluster.gluster

Deprecated Features

community.grafana

  • grafana_dashboard lookup - Providing a mangled version of the API key is no longer preferred.

Porting Guide for v4.5.0

Major Changes

hetzner.hcloud

  • Introduction of placement groups

ovirt.ovirt

Deprecated Features

ansible.netcommon

  • network_cli - The paramiko_ssh setting look_for_keys was set automatically based on the values of the password and private_key_file options passed to network_cli. This option can now be set explicitly, and the automatic setting of look_for_keys will be removed after 2024-01-01 (https://github.com/ansible-collections/ansible.netcommon/pull/271).

cisco.ios

  • Deprecated ios_bgp in favor of ios_bgp_global and ios_bgp_address_family.

  • Remove testing with provider for ansible-test integration jobs. This helps prepare us to move to network-ee integration tests.

junipernetworks.junos

  • Deprecated router_id from ospfv3 resource module.

Porting Guide for v4.4.0

Known Issues

dellemc.openmanage

  • idrac_user - Issue(192043) Module may error out with the message unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress. Wait for the job to complete and run the task again.

Deprecated Features

cisco.iosxr

  • The iosxr_logging module has been deprecated in favor of the new iosxr_logging_global resource module and will be removed in a release after ‘2023-08-01’.

cisco.nxos

  • The nxos_logging module has been deprecated in favor of the new nxos_logging_global resource module and will be removed in a release after ‘2023-08-01’.

community.docker

  • docker_container - the new command_handling’s default value, compatibility, is deprecated and will change to correct in community.docker 3.0.0. A deprecation warning is emitted by the module in cases where the behavior will change. Please note that ansible-core will output a deprecation warning only once, so if it is shown for an earlier task, there could be more tasks with this warning where it is not shown (https://github.com/ansible-collections/community.docker/pull/186).

junipernetworks.junos

  • The junos_logging module has been deprecated in favor of the new junos_logging_global resource module and will be removed in a release after ‘2023-08-01’.

vyos.vyos

  • The vyos_logging module has been deprecated in favor of the new vyos_logging_global resource module and will be removed in a release after “2023-08-01”.

Porting Guide for v4.3.0

Major Changes

netapp.cloudmanager

  • Adding stage environment to all modules in cloudmanager

Deprecated Features

community.hashi_vault

Porting Guide for v4.2.0

Known Issues

dellemc.openmanage

  • idrac_user - Issue(192043) Module may error out with the message unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress. Wait for the job to complete and run the task again.

  • ome_smart_fabric_uplink - Issue(186024) ome_smart_fabric_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified.

Major Changes

community.vmware

dellemc.openmanage

  • idrac_server_config_profile - Added support for exporting and importing Server Configuration Profile through HTTP/HTTPS share.

  • ome_device_group - Added support for adding devices to a group using the IP addresses of the devices and group ID.

fortinet.fortios

  • New module fortios_monitor_fact.

  • Support Fortios 7.0.

  • Support Log APIs.

Deprecated Features

  • The community.kubernetes collection is being renamed to kubernetes.core. In Ansible 5, community.kubernetes will be replaced by an empty collection which has deprecated redirects for all the current content to kubernetes.core. If you are using FQCNs starting with community.kubernetes., please update them to kubernetes.core. now. Note that kubernetes.core has been included in Ansible since Ansible 3.0.0 (https://github.com/ansible-community/community-topics/issues/22).

ansible.windows

  • win_updates - Deprecated the filtered_reason return value for each filtered up in favour of filtered_reasons. This has been done to show all the reasons why an update was filtered and not just the first reason.

  • win_updates - Deprecated the use_scheduled_task option as it is no longer used.

  • win_updates - Deprecated the whitelist and blacklist options in favour of accept_list and reject_list respectively to conform to the new standards used in Ansible for these types of options.

community.general

community.hashi_vault

Porting Guide for v4.1.0

Known Issues

dellemc.openmanage

  • idrac_user - Issue(192043) Module may error out with the message unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress. Wait for the job to complete and run the task again.

  • ome_smart_fabric_uplink - Issue(186024) ome_smart_fabric_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified.

Major Changes

cloudscale_ch.cloud

  • Add custom_image module

community.postgresql

dellemc.openmanage

  • ome_firmware_baseline - Module supports check mode, and allows the modification and deletion of firmware baselines.

  • ome_firmware_catalog - Module supports check mode, and allows the modification and deletion of firmware catalogs.

fortinet.fortios

  • Improve fortios_configuration_fact to use multiple selectors concurrently.

  • Support check_mode in all cofigurationAPI-based modules.

  • Support filtering for fact gathering modules fortios_configuration_fact and fortios_monitor_fact.

  • Support moving policy in firewall_central_snat_map.

  • Unify schemas for monitor API.

netbox.netbox

  • packages is now a required Python package and gets installed through Ansible 2.10+.

Removed Features

ansible.windows

  • win_reboot - Removed shutdown_timeout and shutdown_timeout_sec which has not done anything since Ansible 2.5.

Deprecated Features

ansible.windows

community.docker

  • docker_* modules and plugins, except docker_swarm connection plugin and docker_compose and docker_stack*` modules - the current default ``localhost for tls_hostname is deprecated. In community.docker 2.0.0 it will be computed from docker_host instead (https://github.com/ansible-collections/community.docker/pull/134).

community.general

inspur.sm

  • add_ad_group - This feature will be removed in inspur.sm.add_ad_group 3.0.0. replaced with inspur.sm.ad_group.

  • add_ldap_group - This feature will be removed in inspur.sm.add_ldap_group 3.0.0. replaced with inspur.sm.ldap_group.

  • add_user - This feature will be removed in inspur.sm.add_user 3.0.0. replaced with inspur.sm.user.

  • add_user_group - This feature will be removed in inspur.sm.add_user_group 3.0.0. replaced with inspur.sm.user_group.

  • del_ad_group - This feature will be removed in inspur.sm.del_ad_group 3.0.0. replaced with inspur.sm.ad_group.

  • del_ldap_group - This feature will be removed in inspur.sm.del_ldap_group 3.0.0. replaced with inspur.sm.ldap_group.

  • del_user - This feature will be removed in inspur.sm.del_user 3.0.0. replaced with inspur.sm.user.

  • del_user_group - This feature will be removed in inspur.sm.del_user_group 3.0.0. replaced with inspur.sm.user_group.

  • edit_ad_group - This feature will be removed in inspur.sm.edit_ad_group 3.0.0. replaced with inspur.sm.ad_group.

  • edit_ldap_group - This feature will be removed in inspur.sm.edit_ldap_group 3.0.0. replaced with inspur.sm.ldap_group.

  • edit_user - This feature will be removed in inspur.sm.edit_user 3.0.0. replaced with inspur.sm.user.

  • edit_user_group - This feature will be removed in inspur.sm.edit_user_group 3.0.0. replaced with inspur.sm.user_group.

Porting Guide for v4.0.0

Known Issues

Ansible-core

  • ansible-test - The pylint sanity test no longer correctly detects “bad” variable names for non-constants. See issue 3701 for additional details.

dellemc.openmanage

  • idrac_user - Issue(192043) Module may error out with the message unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress. Wait for the job to complete and run the task again.

  • ome_configuration_compliance_info - Issue(195592) Module may error out with the message unable to process the request because an error occurred. If the issue persists, report it to the system administrator.

  • ome_smart_fabric - Issue(185322) Only three design types are supported by OpenManage Enterprise Modular but the module successfully creates a fabric when the design type is not supported.

  • ome_smart_fabric_uplink - Issue(186024) ome_smart_fabric_uplink module does not allow the creation of multiple uplinks of the same name even though this is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified.

fortinet.fortios

  • Modules for monitor API are not versioned yet.

Breaking Changes

Ansible-core

  • Made SCM collections be reinstalled regardless of --force being present.

  • NetBSD virtualization facts (specifically ansible_virtualization_type) now returns a more accurate value by checking the value of the machdep.hypervisor sysctl key. This change is breaking because in some cases previously, we would erroneously report xen even when the target is not running on Xen. This prevents that behavior in most cases. (https://github.com/ansible/ansible/issues/69352)

  • Replaced the in-tree dependency resolver with an external implementation that pip >= 20.3 uses now by default — resolvelib. (https://github.com/ansible/ansible/issues/71784)

  • The meta module now supports tags for user-defined tasks. Internal meta tasks continue to always run. (https://github.com/ansible/ansible/issues/64558)

  • ansible-galaxy login command has been removed (see issue 71560)

ansible.netcommon

community.docker

  • docker_swarm - if join_token is specified, a returned join token with the same value will be replaced by VALUE_SPECIFIED_IN_NO_LOG_PARAMETER. Make sure that you do not blindly use the join tokens from the return value of this module when the module is invoked with join_token specified! This breaking change appears in a minor release since it is necessary to fix a security issue (https://github.com/ansible-collections/community.docker/pull/103).

community.general

  • If you use Ansible 2.9 and these plugins or modules from this collection, community.general 3.0.0 results in errors when trying to use the DellEMC content by FQCN, like community.general.idrac_firmware. 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 (dellemc.openmanage.idrac_firmware for the previous example) and to make sure that you have dellemc.openmanage installed.

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

  • gitlab_deploy_key - if for an already existing key title a different public key was given as parameter nothing happened, now this changed so that the public key is updated to the new value (https://github.com/ansible-collections/community.general/pull/1661).

  • java_keystore - instead of failing, now overwrites keystore if the alias (name) is changed. This was originally the intended behavior, but did not work due to a logic error. Make sure that your playbooks and roles do not depend on the old behavior of failing instead of overwriting (https://github.com/ansible-collections/community.general/issues/1671).

  • java_keystore - instead of failing, now overwrites keystore if the passphrase is changed. Make sure that your playbooks and roles do not depend on the old behavior of failing instead of overwriting (https://github.com/ansible-collections/community.general/issues/1671).

  • one_image - use pyone instead of python-oca (https://github.com/ansible-collections/community.general/pull/2032).

  • 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).

fortinet.fortios

  • Generic FortiOS Module - FOS module to issue generic request with Ansible.

  • Support for FOS Monitor API - several modules are new for monitor API.

  • Unified Collection - The fortios collection itself will be adapting any FOS platforms.

servicenow.servicenow

  • auth field now required for anything other than Basic authentication

theforeman.foreman

  • All role variables are now prefixed with foreman_ to avoid clashes with similarly named variables from roles outside this collection.

Major Changes

Ansible-core

  • A collection can be reinstalled with new version requirements without using the --force flag. The collection’s dependencies will also be updated if necessary with the new requirements. Use --upgrade to force transitive dependency updates.

  • AnsibleModule - use ArgumentSpecValidator class for validating argument spec and remove private methods related to argument spec validation. Any modules using private methods should now use the ArgumentSpecValidator class or the appropriate validation function.

  • Declared resolvelib >= 0.5.3, < 0.6.0 a direct dependency of ansible-core. Refs: - https://github.com/sarugaku/resolvelib - https://pypi.org/p/resolvelib - https://pradyunsg.me/blog/2020/03/27/pip-resolver-testing

  • It became possible to install Ansible Collections from local folders and namespaces folder similar to SCM structure with multiple collections.

  • It became possible to upgrade Ansible collections from Galaxy servers using the --upgrade option with ansible-galaxy collection install.

  • Support for role argument specification validation at role execution time. When a role contains an argument spec, an implicit validation task is inserted at the start of role execution.

  • add ArgumentSpecValidator class for validating parameters against an argument spec outside of AnsibleModule (https://github.com/ansible/ansible/pull/73335)

  • ansible-test - Tests run with the centos6 and default test containers now use a PyPI proxy container to access PyPI when Python 2.6 is used. This allows tests running under Python 2.6 to continue functioning even though PyPI is discontinuing support for non-SNI capable clients.

ansible.netcommon

  • Remove deprecated connection arguments from netconf_config

arista.eos

  • Requires ansible.netcommon v2.0.0+ to support ansible_network_single_user_mode and ansible_network_import_modules - Please refer to ansible.netcommon changelog for more details.

cisco.asa

  • Please refer to ansible.netcommon changelog <https://github.com/ansible-collections/ansible.netcommon/blob/main/changelogs/CHANGELOG.rst#ansible-netcommon-collection-release-notes> for more details.

  • Requires ansible.netcommon v2.0.0+ to support ansible_network_single_user_mode and ansible_network_import_modules.

cisco.ios

  • Please refer to ansible.netcommon changelog for more details.

  • Requires ansible.netcommon v2.0.0+ to support ansible_network_single_user_mode and ansible_network_import_modules.

cisco.iosxr

  • Please refer to ansible.netcommon changelog for more details.

  • Requires ansible.netcommon v2.0.0+ to support ansible_network_single_user_mode and ansible_network_import_modules.

  • ipaddress is no longer in ansible.netcommon. For Python versions without ipaddress (< 3.0), the ipaddress package is now required.

cisco.nxos

  • Please refer to ansible.netcommon changelog for more details.

  • Requires ansible.netcommon v2.0.0+ to support ansible_network_single_user_mode and ansible_network_import_modules.

community.grafana

  • introduce “skip_version_check” parameter in grafana_teams and grafana_folder modules (#147)

community.mysql

fortinet.fortios

  • New module fortios_configuration_fact

  • New module fortios_json_generic

  • New module fortios_monitor

  • New module fortios_monitor_fact

junipernetworks.junos

  • Please refer to ansible.netcommon changelog for more details.

  • Requires ansible.netcommon v2.0.0+ to support ansible_network_single_user_mode and ansible_network_import_modules.

netapp.ontap

  • na_ontap_autosupport - Added REST support to the module.

openvswitch.openvswitch

  • There is no major changes for this particular release and it was tagged by mistake and cannot be reverted.

servicenow.servicenow

  • refactored client to inherit from AnsibleModule

  • supports OpenID Connect authentication protocol

  • supports bearer tokens for authentication

vyos.vyos

  • Please refer to ansible.netcommon changelog for more details.

  • Requires ansible.netcommon v2.0.0+ to support ansible_network_single_user_mode and ansible_network_import_modules

  • ipaddress is no longer in ansible.netcommon. For Python versions without ipaddress (< 3.0), the ipaddress package is now required.

Removed Features

Ansible-core

  • Removed SharedPluginLoaderObj class from ansible.plugins.strategy. It was deprecated in favor of using the standard plugin loader.

  • Removed _get_item() alias from callback plugin base class which had been deprecated in favor of _get_item_label().

  • The “user” parameter was previously deprecated and is now removed in favor of “scope”

  • The deprecated ansible.constants.BECOME_METHODS has been removed.

  • The deprecated ansible.constants.get_config() has been removed.

  • The deprecated ansible.constants.mk_boolean() has been removed.

  • with_* loops are no longer optimized for modules whose name parameters can take lists (mostly package managers). Use name instead of looping over individual names with with_items and friends.

community.general

community.network

f5networks.f5_modules

fortinet.fortios

  • Removed module fortios_facts

  • Removed module fortios_registration_forticare

  • Removed module fortios_registration_vdom

  • Removed module fortios_system_config_backup_restore

  • Removed module fortios_system_vmlicense

Deprecated Features

Ansible-core

  • Starting in 2.14, shell and command modules will no longer have the option to warn and suggest modules in lieu of commands. The warn parameter to these modules is now deprecated and defaults to False. Similarly, the COMMAND_WARNINGS configuration option is also deprecated and defaults to False. These will be removed and their presence will become an error in 2.14.

  • apt_key - the parameter key does not have any effect, has been deprecated and will be removed in ansible-core version 2.14 (https://github.com/ansible/ansible/pull/70319).

  • psrp - Set the minimum version of pypsrp to 0.4.0.

ansible.netcommon

cisco.nxos

  • Deprecated nxos_bgp_af in favour of nxos_bgp_address_family resource module.

  • Deprecated nxos_bgp_neighbor_af in favour of nxos_bgp_neighbor_address_family resource module.

cloudscale_ch.cloud

  • The aliases server_uuids and server_uuid of the servers parameter in the volume module will be removed in version 3.0.0.

community.aws

community.crypto

community.general

community.vmware

f5networks.f5_modules

  • Support for Python versions earlier than 3.5 is being deprecated