Ansible 2.4 Porting Guide¶

Initial playbook relative group_vars and host_vars¶

In Ansible versions prior to 2.4, the inventory system would maintain the context of the initial playbook that was executed. This allowed successively included playbooks from other directories to inherit group_vars and host_vars placed relative to the top level playbook file.

Due to some behavioral inconsistencies, this functionality will not be included in the new inventory system starting with Ansible version 2.4.

Similar functionality can still be achieved by using vars_files, include_vars, or group_vars and host_vars placed relative to the inventory file.

Specifying Inventory sources¶

Use of --inventory-file on the command line is now deprecated. Use --inventory or -i. The associated ini configuration key, hostfile, and environment variable, ANSIBLE_HOSTS, are also deprecated. Replace them with the configuration key inventory and environment variable ANSIBLE_INVENTORY.

Use of multiple tags¶

Specifying --tags (or --skip-tags) multiple times on the command line currently leads to the last one overriding all the previous ones. This behavior is deprecated. In the future, if you specify –tags multiple times the tags will be merged together. From now on, using --tags multiple times on one command line will emit a deprecation warning. Setting the merge_multiple_cli_tags option to True in the ansible.cfg file will enable the new behavior.

In 2.4, the default has change to merge the tags. You can enable the old overwriting behavior via the config option.

In 2.5, multiple --tags options will be merged with no way to go back to the old behavior.

Other caveats¶

No major changes in this version.

Modules removed¶

The following modules no longer exist:

• None

Deprecation notices¶

The following modules will be removed in Ansible 2.8. Please update your playbooks accordingly.

• azure, use azure_rm_virtualmachine, which uses the new Resource Manager SDK.
• win_msi, use win_package instead

Noteworthy module changes¶

• The win_get_url module has the dictionary win_get_url in its results deprecated, its content is now also available directly in the resulting output, like other modules. This dictionary will be removed in Ansible 2.8.
• The win_unzip module no longer includes the dictionary win_unzip in its results; the contents are now included directly in the resulting output, like other modules.
• The win_package module return values exit_code and restart_required have been deprecated in favour of rc and reboot_required respectively. The deprecated return values will be removed in Ansible 2.6.

Vars plugin changes¶

There have been many changes to the implementation of vars plugins, but both users and developers should not need to change anything to keep current setups working. Developers should consider changing their plugins take advantage of new features.

The most notable difference to users is that vars plugins now get invoked on demand instead of at inventory build time. This should make them more efficient for large inventories, especially when using a subset of the hosts.

Inventory plugins¶

Developers should start migrating from hardcoded inventory with dynamic inventory scripts to the new Inventory Plugins. The scripts will still work via the script inventory plugin but Ansible development efforts will now concentrate on writing plugins rather than enhancing existing scripts.

Both users and developers should look into the new plugins because they are intended to alleviate the need for many of the hacks and workarounds found in the dynamic inventory scripts.

Callback plugins¶

Users:

• Callbacks are now using the new configuration system. Users should not need to change anything as the old system still works, but you might see a deprecation notice if any callbacks used are not inheriting from the built in classes. Developers need to update them as stated below.

Developers:

• If your callback does not inherit from CallbackBase (directly or indirectly via another callback), it will still work, but issue a deprecation notice. To avoid this and ensure it works in the future change it to inherit from CallbackBase so it has the new options handling methods and properties. You can also implement the new options handling methods and properties but that won’t automatically inherit changes added in the future. You can look at CallbackBase itself and/or AnsiblePlugin for details.
• Any callbacks inheriting from other callbacks might need to also be updated to contain the same documented options as the parent or the options won’t be available. This is noted in the developer guide.

Template lookup plugin: Escaping Strings¶

Prior to Ansible 2.4, backslashes in strings passed to the template lookup plugin would be escaped automatically. In 2.4, users are responsible for escaping backslashes themselves. This change brings the template lookup plugin inline with the template module so that the same backslash escaping rules apply to both.

If you have a template lookup like this:

- debug:
    msg: '{{ lookup("template", "template.j2") }}'

OLD In Ansible 2.3 (and earlier) template.j2 would look like this:

{{ "name surname" | regex_replace("^[^\s]+\s+(.*)", "\1") }}

NEW In Ansible 2.4 it should be changed to look like this:

{{ "name surname" | regex_replace("^[^\\s]+\\s+(.*)", "\\1") }}

Tests succeeded/failed¶

Prior to Ansible version 2.4, a task return code of rc would override a return code of failed. In version 2.4, both rc and failed are used to calculate the state of the task. Because of this, test plugins succeeded/failed` have also been changed. This means that overriding a task failure with failed_when: no will result in succeeded/failed returning True/False. For example:

- command: /bin/false
  register: result
  failed_when: no

- debug:
    msg: 'This is printed on 2.3'
  when: result|failed

- debug:
    msg: 'This is printed on 2.4'
  when: result|succeeded

- debug:
    msg: 'This is always printed'
  when: result.rc != 0

As we can see from the example above, in Ansible 2.3 succeeded/failed only checked the value of rc.

Persistent Connection¶

The configuration variables connection_retries and connect_interval which were added in Ansible 2.3 are now deprecated. For Ansible 2.4 and later use connection_retry_timeout.

To control timeouts use command_timeout rather than the previous top level timeout variable under [default]

See Ansible Network debug guide for more information.