Ansible-core 2.11 Porting Guide

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

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.

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