Ansible 2.7 Porting Guide

It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible.

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

This document is part of a collection on porting. The complete list of porting guides can be found at porting guides.

If you specify or —skip-tags multiple times on the command line, Ansible will merge the specifiedtags together. In previous versions of Ansible, you could set merge_multiple_cli_tags to Falseif you wanted to keep only the last-specified —tags. This configoption existed for backwards compatibility. The overwriting behavior was deprecated in 2.3 andthe default behavior was changed in 2.4. Ansible-2.7 removes the config option; multiple—tags are now always merged.

If you have a shell script that depends on setting merge_multiple_cli_tags to False, please upgrade your scriptso it only adds the —tags you actually want before upgrading to Ansible-2.7.

Python Compatibility

Ansible has dropped compatibility with Python-2.6 on the controller (The host where /usr/bin/ansibleor /usr/bin/ansible-playbook is run). Modules shipped with Ansible can still be used tomanage hosts which only have Python-2.6. You just need to have a host with Python-2.7 or Python-3.5or greater to manage those hosts from.

One thing that this does affect is the ability to use /usr/bin/ansible-pull to managea host which has Python-2.6. ansible-pull runs on the host being managed but it is a controllerscript, not a module so it will need an updated Python. Actively developed Linux distros which shipwith Python-2.6 have some means to install newer Python versions (For instance, you can installPython-2.7 via an SCL on RHEL-6) but you may need to also install Python bindings for many commonmodules to work (For RHEL-6, for instance, selinux bindings and yum would have to be installed forthe updated Python install).

The decision to drop Python-2.6 support on the controller was made because many dependent librariesare becoming unavailable there. In particular, python-cryptography is no longer available for Python-2.6and the last release of pycrypto (the alternative to python-cryptography) has known security bugswhich will never be fixed.

Ansible 2.7 makes a small change to variable precedence when loading roles, resolving a bug, ensuring that role loading matches .

Before Ansible 2.7, when loading a role, the variables defined in the role’s vars/main.yml and defaults/main.yml were not available when parsing the role’s tasks/main.yml file. This prevented the role from utilizing these variables when being parsed. The problem manifested when import_tasks or import_role was used with a variable defined in the role’s vars or defaults.

In Ansible 2.7, role vars and defaults are now parsed before tasks/main.yml. This can cause a change in behavior if the same variable is defined at the play level and the role level with different values, and leveraged in import_tasks or import_role to define the role or file to import.

include_role and import_role variable exposure

In Ansible 2.7 a new module argument named public was added to the include_role module that dictates whether or not the role’s defaults and vars will be exposed outside of the role, allowing those variables to be used by later tasks. This value defaults to public: False, matching current behavior.

There is an important difference in the way that includerole (dynamic) will expose the role’s variables, as opposed to import_role (static). import_role is a pre-processor, and the defaults and vars are evaluated at playbook parsing, making the variables available to tasks and roles listed at any point in the play. include_role is a conditional task, and the and vars are evaluated at execution time, making the variables available to tasks and roles listed _after the include_role task.

include_tasks/import_tasks inline variables

As of Ansible 2.7, include_tasks and import_tasks can no longer accept inline variables. Instead of using inline variables, tasks should supply variables under the vars keyword.

OLD In Ansible 2.6 (and earlier) the following was valid syntax for specifying variables:

NEW In Ansible 2.7 the task should be changed to use the vars keyword:

  vars:
    variable: value

vars_prompt now throws an error if the hash algorithm specified in encrypt is not supported bythe controller. This increases the safety of vars_prompt as it previously returned None if thealgorithm was unknown. Some modules, notably the user module, treated a password of None asa request not to set a password. If your playbook starts erroring because of this, change thehashing algorithm being used with this filter.

Deprecated

Expedited Deprecation: Use of file in AnsibleModule

Note

The use of the file variable is deprecated in Ansible 2.7 and will be eliminated in Ansible 2.8. This is much quicker than our usual 4-release deprecation cycle.

We are deprecating the use of the file variable to refer to the file containing the currently-running code. This common Python technique for finding a filesystem path does not always work (even in vanilla Python). Sometimes a Python module can be imported from a virtual location (like inside of a zip file). When this happens, the file variable will reference a virtual location pointing to inside of the zip file. This can cause problems if, for instance, the code was trying to use file to find the directory containing the python module to write some temporary information.

Before the introduction of AnsiBallZ in Ansible 2.1, using file worked in AnsibleModule sometimes, but any module that used it would fail when pipelining was turned on (because the module would be piped into the python interpreter’s standard input, so file wouldn’t contain a file path). AnsiBallZ unintentionally made using file work, by always creating a temporary file for AnsibleModule to reside in.

Ansible 2.8 will no longer create a temporary file for AnsibleModule; instead it will read the file out of a zip file. This change should speed up module execution, but it does mean that starting with Ansible 2.8, referencing file will always fail in AnsibleModule.

If you are the author of a third-party module which uses file with AnsibleModule, please update your module(s) now, while the use of file is deprecated but still available. The most common use of file is to find a directory to write a temporary file. In Ansible 2.5 and above, you can use the tmpdir attribute on an AnsibleModule instance instead, as shown in this code from the apt module:

Using a loop on a package module via squash_actions

The use of squash_actions to invoke a package module, such as “yum”, to only invoke the module once is deprecated, and will be removed in Ansible 2.11.

OLD In Ansible 2.6 (and earlier) the following task would invoke the “yum” module only 1 time to install multiple packages

- name: Install packages
  yum:
    name: "{{ item }}"
    state: present
  with_items: "{{ packages }}"

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

Major changes in popular modules are detailed here

• The configuration option tells Ansible modules to use a specificsyslog facility when logging information on allmanaged machines. Due to a bug with older Ansible versions, this setting did not affect machinesusing journald with the systemd Python bindings installed. On those machines, Ansible logmessages were sent to /var/log/messages, even if you set .Ansible 2.7 fixes this bug, routing all Ansible log messages according to the value set forDEFAULT_SYSLOG_FACILITY. If you have configured, thelocation of remote logs on systems which use journald may change.

The following modules no longer exist:

Deprecation notices

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

• na_cdot_aggregate use na_ontap_aggregate instead.
• na_cdot_license use instead.
• na_cdot_lun use na_ontap_lun instead.
• na_cdot_qtree use instead.
• na_cdot_svm use na_ontap_svm instead.
• na_cdot_user use instead.
• na_cdot_user_role use na_ontap_user_role instead.
• na_cdot_volume use instead.
• sf_account_manager use na_elementsw_account instead.
• sf_snapshot_schedule_manager use instead.
• sf_volume_access_group_manager use na_elementsw_access_group instead.
• sf_volume_manager use instead.

Noteworthy module changes

• Check mode is now supported in the command and shell modules. However, only when creates or removes isspecified. If either of these are specified, the module will check for existence of the file and report the correctchanged status, if they are not included the module will skip like it had done previously.

• The win_chocolatey module originally required the proxy_username and proxy_password toescape any double quotes in the value. This is no longer required and the escaping may cause furtherissues.

• The win_uri module has removed the deprecated option use_basic_parsing, since Ansible 2.5 this option didnothing

• The win_scheduled_task module has removed the following deprecated options:

  • executable, use path in an actions entry instead
  • argument, use arguments in an actions entry instead
  • store_password, set logon_type: password instead
  • days_of_week, use monthlydow in a triggers entry instead
  • frequency, use type, in a triggers entry instead
  • time, use start_boundary in a triggers entry instead

• The interface_name module option for na_ontap_net_vlan has been removed and should be removed from your playbooks

• The win_disk_image module has deprecated the return value mount_path, use mount_paths[0] instead. This willbe removed in Ansible 2.11.

• include_role and include_tasks can now be used directly from ansible (adhoc) and ansible-console:

#> ansible -m include_role -a 'name=myrole' all

Plugins

• The hash_password filter now throws an error if the hash algorithm specified is not supported bythe controller. This increases the safety of the filter as it previously returned None if thealgorithm was unknown. Some modules, notably the user module, treated a password of None asa request not to set a password. If your playbook starts erroring because of this, change thehashing algorithm being used with this filter.

Networking

No notable changes.