Set minimum Ansible version in project
Ansible is one of the most popular open-source configuration management tools used now a days. It is a common scenario that all the users of an Ansible project runs playbook from their localhost. This means that same Ansible playbook is run using different Ansible version depending on the Ansible version installed on a particular user’s work station. However, Ansible module’s feature changes from version to version. However, when an Ansible playbook is configured using the updated module feature, this playbook may not behave as expected when an user has old version of Ansible installed in his/her system. Considering this condition, it is a good practice to set a minimum Ansible version in a project. This will ensure that a minimum Ansible version is always used to run the playbook in a project.
There are several ways to set the minimum Ansible version for a project. Among all of the options I found that the most suitable option to set Ansible version in a project is using a callback plugin. Every time a playbook is run in the project, Ansible loads this callback plugin to check that the user’s Ansible version satisfies the requirement of Ansible version for this project or not.
To set minimum Ansible version using callback plugin, copy the following plugin code in a file named ansible_version_check.py. Update the value of required_version in the following code based on your requirement.
#!/usr/bin/python
# -*- encoding:utf-8 -*-
from __future__ import (absolute_import, division, print_function, unicode_literals)
__metaclass__ = type
import sys
from ansible.plugins.callback import CallbackBase
from ansible import __version__ as ansible_version
from ansible.utils.version import SemanticVersion
def print_red_bold(text):
print('\x1b[31;1m' + text + '\x1b[0m')
class CallbackModule(CallbackBase):
CALLBACK_VERSION = 2.0
CALLBACK_TYPE = 'stdout'
def __init__(self):
minimal_version = SemanticVersion('2.9.0')
current = SemanticVersion(ansible_version)
if current < minimal_version:
print_red_bold(
f"Restriction: only Ansible >={minimal_version.vstring} is supported. Your current version is {current.vstring}."
f"\n\nInstall a supported version with:\n\n"
f"\tpip install ansible=={minimal_version.major}.{minimal_version.minor}.*"
)
sys.exit(1)
ansible = CallbackModule()There are some magic directories from where Ansible automatically loads plugins (more details can be found here). Now create a directory named callback_plugins in the root of your project. The magic directories for plugins did not work as expected for project level plugins for me. So we will update Ansible configuration to let Ansible know where it can find the plugin. To know more details about Ansible configuration file settings check here. In our case we will put the configuration in a file named ansible.cfg in the root of our project. Add the following content to the ansible.cfg file.
[defaults]
callback_plugins = callback_pluginsWith this Ansible configuration, every time we run a playbook, Ansible will first check the directory callback_plugins and load all the plugins located in that directory.
According to the above plugin code, now if we run any playbook in our project, Ansible will check if the version is 2.9 or not. If Ansible version is less than 2.9, the playbook will fail with the following message.
Restriction: only Ansible =2.9.X is supported. You should install it with:pip install ansible==2.9.*
If user’s Ansible version is 2.9.X then this will satisfy the version restriction and the playbook will run as expected. However, if we want to configure Ansible version check for only a particular playbook, we just need to put the directory callback_plugins inside the playbook’s root directory.
The above plugin code is a very simple version of the implementation. However, this can be updated with more advance checking. For example- check if Ansible version higher than or equal to a expected minimum version or not.
I hope this simplest version of the plugin will also be helpful to set a minimum Ansible version in your project. Please feel free to share if you have any suggestions or feedback about the process explained above.