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.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 via 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 2.2.0. replaced with inspur.sm.ad_group.

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

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

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

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

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

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

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

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

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

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

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

Porting Guide for v4.0.0

Known Issues

Ansible-core

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

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.

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 paramater 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