Ansible 13 Porting Guide

Ansible 13 is based on Ansible-core 2.20.

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

Introduction

No notable changes

Playbook

Removed quote stripping in PowerShell operations

The PowerShell module utilities no longer attempt to remove quotes from paths when performing Windows operations like copying and fetching files. This should not affect normal playbooks unless a value is quoted too many times. If you have playbooks that rely on this automatic quote removal, you will need to adjust your path formatting.

Engine

No notable changes

Plugin API

Removed Features

The following previously deprecated features have been removed:

  • The DEFAULT_TRANSPORT configuration option no longer supports the smart value that selected the default transport as either ssh or paramiko based on the underlying platform configuration.

  • The vault and unvault filters no longer accept the deprecated vaultid parameter.

  • The ansible-galaxy command no longer supports the v2 Galaxy server API. Galaxy servers hosting collections must support v3.

  • The dnf and dnf5 modules no longer support the deprecated install_repoquery option.

  • The encrypt module utility no longer includes the deprecated passlib_or_crypt API.

  • The paramiko connection plugin no longer supports the PARAMIKO_HOST_KEY_AUTO_ADD and PARAMIKO_LOOK_FOR_KEYS configuration keys, which were previously deprecated.

  • The py3compat.environ call has been removed.

  • Vars plugins that do not inherit from BaseVarsPlugin and define a get_vars method can no longer use the deprecated get_host_vars or get_group_vars fallback.

  • The yum_repository module no longer supports the deprecated keepcache option.

Behavioral Changes

  • The DataLoader.get_basedir method now returns an absolute path instead of a relative path. Plugin code that relies on relative paths may need adjustment.

  • Argument spec validation now treats None values as empty strings for the str type for better consistency with pre-2.19 templating conversions.

  • When using failed_when to suppress an error, the exception key in the result is now renamed to failed_when_suppressed_exception. This prevents the error from being displayed by callbacks after being suppressed. If you have playbooks that check for the exception in the result, update them as follows:

# Before
- command: /bin/false
  register: result
  failed_when: false

- debug:
    msg: "Exception was: {{ result.exception }}"
  when: result.exception is defined

# After
- command: /bin/false
  register: result
  failed_when: false

- debug:
    msg: "Exception was: {{ result.failed_when_suppressed_exception }}"
  when: result.failed_when_suppressed_exception is defined

Command Line

  • Python 3.11 is no longer a supported control node version. Python 3.12+ is now required for running Ansible.

  • Python 3.8 is no longer a supported remote version. Python 3.9+ is now required for target execution.

Deprecated

INJECT_FACTS_AS_VARS

The INJECT_FACTS_AS_VARS configuration currently defaults to True, but this is now deprecated and it will switch to False in Ansible 2.24.

When enabled, facts are available both inside the ansible_facts dictionary and as individual variables in the main namespace. In the ansible_facts dictionary, the ansible_ prefix is removed from fact names.

You will receive deprecation warnings if you are accessing ‘injected’ facts. To prepare for the future default:

Update your playbooks to use the ansible_facts dictionary:

# Deprecated - will stop working in 2.24
- debug:
    msg: "OS: {{ ansible_os_distribution }}"

# Recommended - works in all versions
- debug:
    msg: "OS: {{ ansible_facts['distribution'] }}"
    # Note: 'ansible_' prefix is removed inside ansible_facts

Or explicitly enable the current behavior in your configuration:

In your ansible.cfg file:

[defaults]
inject_facts_as_vars = True

By exporting an environment variable:

export ANSIBLE_INJECT_FACT_VARS=True

Other Deprecations

  • The vars internal variable cache will be removed in 2.24. This cache, once used internally, exposes variables in inconsistent states. The vars and varnames lookups should be used instead.

  • Specifying ignore_files as a string in the include_vars module is deprecated. Use a list instead:

# Deprecated
- include_vars:
    dir: vars/
    ignore_files: ".gitkeep"

# Correct
- include_vars:
    dir: vars/
    ignore_files: [".gitkeep"]

Modules

Modules removed

The following modules no longer exist:

  • No notable changes

Deprecation notices

No notable changes

Noteworthy module changes

  • The include_vars module now raises an error if the extensions parameter is not specified as a list. Previously, non-list values were silently accepted.

  • The include_vars module now raises an error if the ignore_files parameter is not specified as a list. Previously, string values were accepted but are now deprecated.

  • The replace module now reads and writes files in text-mode as unicode characters instead of as bytes, and switches regex matching to unicode characters instead of bytes. This may affect playbooks that rely on byte-level operations.

Plugins

Noteworthy plugin changes

No notable changes

Porting custom scripts

No notable changes

Networking

No notable changes

Porting Guide for v13.0.0

Added Collections

  • hitachivantara.vspone_object (version 1.0.0)

  • ravendb.ravendb (version 1.0.4)

Known Issues

Ansible-core

  • templating - Exceptions raised in a Jinja set or with block which are not accessed by the template are ignored in the same manner as undefined values.

  • templating - Passing a container created in a Jinja set or with block to a method results in a copy of that container. Mutations to that container which are not returned by the method will be discarded.

community.sops

  • When using the community.sops.load_vars with ansible-core 2.20, note that the deprecation of INJECT_FACTS_AS_VARS causes deprecation warnings to be shown every time a variable loaded with community.sops.load_vars is used. This is due to ansible-core deprecating INJECT_FACTS_AS_VARS without providing an alternative for modules like community.sops.load_vars to use. If you do not like these deprecation warnings, you have to explicitly set INJECT_FACTS_AS_VARS to true. DO NOT change the use of SOPS encrypted variables to ansible_facts. The situation will hopefully improve in ansible-core 2.21 through the promised API that allows action plugins to set variables; community.sops will adapt to use it, which will make the warning go away. (The API was originally promised for ansible-core 2.20, but then delayed.)

dellemc.openmanage

  • Formal qualification of module ome_smart_fabric_info for Ansible Core version 2.19 is still pending.

  • idrac_attributes - The module accepts both the string as well as integer value for the field “SNMP.1.AgentCommunity” for iDRAC10.

  • idrac_diagnostics - This module does not support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy.

  • idrac_license - Due to API limitation, proxy parameters are ignored during the import operation.

  • idrac_license - The module will fail to export license to NFS Share.

  • idrac_license - The module will give different error messages for iDRAC9 and iDRAC10 when user imports license with invalid share name.

  • idrac_os_deployment - The module continues to return a 200 response and marks the job as completed, even when an outdated date is supplied in the Expose duration.

  • idrac_redfish_storage_controller - PatrolReadRatePercent attribute cannot be set in iDRAC10.

  • idrac_server_config_profile - When attempting to revert iDRAC settings using a previously exported SCP file, the import operation will complete with errors if a new user was created after the export (Instead of restoring the system to its previous state, including the removal of newly added users).

  • idrac_system_info - The module will show empty video list despite having Embedded VIDEO controller.

  • ome_smart_fabric_uplink - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified.

  • redfish_storage_volume - Encryption type and block_io_size bytes will be read only property in iDRAC 9 and iDRAC 10 and hence the module ignores these parameters.

  • redfish_storage_volume - Encryption type and block_io_size bytes will be read only property in iDRAC9 and iDRAC10 and hence the module ignores these parameters.

Breaking Changes

Ansible-core

  • powershell - Removed code that tried to remote quotes from paths when performing Windows operations like copying and fetching file. This should not affect normal playbooks unless a value is quoted too many times.

community.docker

community.general

community.mysql

community.vmware

hetzner.hcloud

  • Drop support for Python 3.9

  • Drop support for ansible-core 2.17

ibm.storage_virtualize

  • ibm_sv_manage_flashsystem_grid - The flashsystem grid module now uses newer FlashSystem REST APIs to perform tasks.

Major Changes

Ansible-core

  • ansible - Add support for Python 3.14.

  • ansible - Drop support for Python 3.11 on the controller.

  • ansible - Drop support for Python 3.8 on targets.

community.vmware

containers.podman

  • Add inventory plugins for buildah and podman

  • Add podman system connection modules

dellemc.openmanage

  • The OpenManage Enterprise, OpenManage Enterprise Modular and OpenManage Enterprise Integration for VMware vCenter modules are now compatible with Ansible Core version 2.19.

  • idrac_certificate - This role is enhanced to support iDRAC10.

  • idrac_export_server_config_profile - This role is enhanced to support iDRAC10.

  • idrac_firmware - This role is enhanced to support iDRAC10.

  • idrac_import_server_config_profile - This role is enhanced to support iDRAC10.

  • idrac_license - This module is enhanced to support iDRAC10.

  • idrac_os_deployment - This module is enhanced to support iDRAC10.

  • idrac_os_deployment - This role is enhanced to support iDRAC10.

  • idrac_redfish_storage_controller - This module is enhanced to support iDRAC10.

  • idrac_server_config_profile - This module is enhanced to support iDRAC10.

  • idrac_storage_controller - This role is enhanced to support iDRAC10.

  • idrac_storage_volume - This module is enhanced to support iDRAC10.

  • redfish_firmware - This role is enhanced to support iDRAC10.

  • redfish_firmware_rollback - This module is enhanced to support iDRAC10.

  • redfish_storage_volume - This module is enhanced to support iDRAC10.

  • redfish_storage_volume - This role is enhanced to support iDRAC10.

fortinet.fortios

  • Supported default_group feature for the all of the modules.

  • Supported new versions 7.6.3 and 7.6.4.

  • Supported the authentication method when using username and password in v7.6.4.

grafana.grafana

ieisystem.inmanage

  • The edit_m6_log_setting.py module has added the ‘server_status’ attribute; The edit_network_bond.py module modifies the attribute descriptions; The edit_snmp.py and edit_snmp_trap.py module modifies the allowable value ranges for the auth_protocol and priv_protocol attributes. (https://github.com/ieisystem/ieisystem.inmanage/pull/30).

ngine_io.cloudstack

Removed Collections

  • community.digitalocean (previously included version: 1.27.0)

  • ibm.qradar (previously included version: 4.0.0)

You can still install a removed collection manually with ansible-galaxy collection install <name-of-collection>.

Removed Features

Ansible-core

  • Removed the option to set the DEFAULT_TRANSPORT configuration to smart that selects the default transport as either ssh or paramiko based on the underlying platform configuraton.

  • vault/unvault filters - remove the deprecated vaultid parameter.

  • ansible-doc - role entrypoint attributes are no longer shown

  • ansible-galaxy - remove support for resolvelib >= 0.5.3, < 0.8.0.

  • ansible-galaxy - removed the v2 Galaxy server API. Galaxy servers hosting collections must support v3.

  • dnf/dnf5 - remove deprecated install_repoquery option.

  • encrypt - remove deprecated passlib_or_crypt API.

  • paramiko - Removed the PARAMIKO_HOST_KEY_AUTO_ADD and PARAMIKO_LOOK_FOR_KEYS configuration keys, which were previously deprecated.

  • py3compat - remove deprecated py3compat.environ call.

  • vars plugins - removed the deprecated get_host_vars or get_group_vars fallback for vars plugins that do not inherit from BaseVarsPlugin and define a get_vars method.

  • yum_repository - remove deprecated keepcache option.

community.docker

community.general

community.vmware

Deprecated Features

Ansible-core

  • Deprecated the shell plugin’s wrap_for_exec function. This API is not used in Ansible or any known collection and is being removed to simplify the plugin API. Plugin authors should wrap their command to execute within an explicit shell or other known executable.

  • INJECT_FACTS_AS_VARS configuration currently defaults to True, this is now deprecated and it will switch to False by Ansible 2.24. You will only get notified if you are accessing ‘injected’ facts (for example, ansible_os_distribution vs ansible_facts[‘os_distribution’]).

  • hash_params function in roles/__init__ is being deprecated as it is not in use.

  • include_vars - Specifying ‘ignore_files’ as a string is deprecated.

  • vars, the internal variable cache will be removed in 2.24. This cache, once used internally exposes variables in inconsistent states, the ‘vars’ and ‘varnames’ lookups should be used instead.

community.general

community.hrobot

  • storagebox* modules - membership in the community.hrobot.robot action group (module defaults group) is deprecated; the modules will be removed from the group in community.hrobot 3.0.0. Use community.hrobot.api instead (https://github.com/ansible-collections/community.hrobot/pull/178).

  • storagebox* modules - the hetzner_token option for these modules will be required from community.hrobot 3.0.0 on (https://github.com/ansible-collections/community.hrobot/pull/178).

  • storagebox* modules - the hetzner_user and hetzner_pass options for these modules are deprecated; support will be removed in community.hrobot 3.0.0. Use hetzner_token instead (https://github.com/ansible-collections/community.hrobot/pull/178).

  • storagebox_info - the storageboxes[].login, storageboxes[].disk_quota, storageboxes[].disk_usage, storageboxes[].disk_usage_data, storageboxes[].disk_usage_snapshot, storageboxes[].webdav, storageboxes[].samba, storageboxes[].ssh, storageboxes[].external_reachability, and storageboxes[].zfs return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API (https://github.com/ansible-collections/community.hrobot/pull/178).

  • storagebox_snapshot_info - the snapshots[].timestamp, snapshots[].size, snapshots[].filesystem_size, snapshots[].automatic, and snapshots[].comment return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API (https://github.com/ansible-collections/community.hrobot/pull/178).

  • storagebox_snapshot_plan - the plans[].month return value is deprecated, since it only returns null with the new API and cannot be set to any other value (https://github.com/ansible-collections/community.hrobot/pull/178).

  • storagebox_snapshot_plan_info - the plans[].month return value is deprecated, since it only returns null with the new API and cannot be set to any other value (https://github.com/ansible-collections/community.hrobot/pull/178).

  • storagebox_subaccount - password_mode=set-to-random is deprecated and will be removed from community.hrobot 3.0.0. Hetzner’s new API does not support this anyway, it can only be used with the legacy API (https://github.com/ansible-collections/community.hrobot/pull/183).

  • storagebox_subaccount - the subaccount.homedirectory, subaccount.samba, subaccount.ssh, subaccount.external_reachability, subaccount.webdav, subaccount.readonly, subaccount.createtime, and subaccount.comment return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API (https://github.com/ansible-collections/community.hrobot/pull/178).

  • storagebox_subaccount_info - the subaccounts[].accountid, subaccounts[].homedirectory, subaccounts[].samba, subaccounts[].ssh, subaccounts[].external_reachability, subaccounts[].webdav, subaccounts[].readonly, subaccounts[].createtime, and subaccounts[].comment return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API (https://github.com/ansible-collections/community.hrobot/pull/178).

community.vmware

community.zabbix

  • zabbix_maintenance module - Depreicated minutes argument for time_periods

dellemc.powerflex

  • The device, info, protection_domain, snapshot, storagepool and volume modules are supported only on PowerFlex Gen1. They are replaced by v2 modules on PowerFlex Gen2.

  • The fault_set, replication_consistency_group, replication_pair, resource_group and sds modules are not supported on PowerFlex Gen2.

hetzner.hcloud

  • server_type_info - Deprecate Server Type deprecation property.

purestorage.flasharray

  • purefa_volume_tags - Deprecated due to removal of REST 1.x support. Will be removed in Collection 2.0.0