How to upgrade your Ansible Playbook in 20 minutes instead of 2 hours

If you’re reading this, you know the feeling of putting off upgrading your Ansible Playbooks for as long as possible because you know it will take time, effort, and patience to do it. But it doesn’t have to be this way. Not when we have tools to do the grunt work for us, such as Ansible Lint and Steampunk Spotter.

Ansible Lint validates Ansible syntax to catch misconfigurations and enforce best practices in Ansible content, whereas Steampunk Spotter goes beyond syntax checks when analyzing your playbooks - and especially shines when it comes to Ansible upgrades. It scans your content and takes into account your environment to identify all the things you need to resolve when performing your upgrade. Many of provided hints, warnings and errors such as the use of FQCNs and generating requirements file with correct collection requirement versions can be applied automatically (automagically :P). For the other, more tricky issues, the suggestions are equipped by links to module documentation of a specific version.

Ok, but … how much time can a tool actually save?

You need some numbers, we know. Just some flashy words won’t do. Agreed! Our team, developing Spotter, wanted to check first hand. You gotta practice what you preach, right?

So, we did some testing and simulated Ansible upgrade from version 2.4 to 2.14. We took the playbooks and roles used in our step-by-step Ansible Upgrades webinar and fixed everything manually, which took 2 hours (and remember, our Steampunks knew exactly where to look for the documentation they needed, otherwise it would have taken even longer), but using Ansible Lint and Steampunk Spotter, all it took was 20 minutes.

Check out a detailed walkthrough of upgrading Ansible Playbooks in this step by step guide .

The experiment: manually vs. using Spotter

So, here’s what you have to go through if you want to do a manual upgrade and ensure that your Ansible content will be runnable after upgrading to Ansible 2.14:

First noticeable thing is that Ansible 2.4 required Python 2.9 and Ansible 2.14 requires Python 3.8, which means that you can abandon all hopes that a playbook written for 2.4 will run successfully on 2.14. We turned a blind eye and tried and of course, it failed and ERROR! ‘sudo’ is not a valid attribute for a Play showed up. As this error is quite common you can google it and you’ll probably find an answer on StackOverflow or GitHub Gist saying that sudo playbook keyword has been replaced by become.

This was easy but try running again and ERROR! couldn’t resolve module/action ‘sysctl’ could be a little harder to figure out. Since Ansible 2.4 and 2.14 are five years apart many things happened and Ansible kept just the core functionalities and other related plugins and modules separated into Ansible Collections. After searching the web for ‘sysctl’ Ansible module, you’ll find that this module is now part of ansible.posix collection and identified by ansible.posix.sysctl. Apart from replacing the name, you will also have to install the collection with ansible-galaxy collection install. There will be many more FQCNs to handle and searching through Ansible documentation can make you dizzy as time passes by. We’d rather not mention that you may have to reopen all closed tabs from the browser when you find out that the parameter names and values changed too.

Also, when searching for the right Ansible documentation, it could happen that you even end up in documentation for the wrong version. In our case, when we stopped by openssl_certificate module, we found ourselves in Ansible 2.7 documentation and needed some time to figure out we were at the wrong place before finally we discovered the correct replacement called community.crypto.x509_certificate. The trick here is that you have to dig into the module examples to find out that the assertonly parameter had been surprisingly replaced by a new module called community.crypto.x509_certificate_info.

There will be many cases where you can notice that module parameter names have changed and then you have to figure out which new ones to use to reach the same behavior. For instance, the force parameter in the old docker_image module (now called community.docker.docker_image), has been replaced by force_source. Not just parameter names, but also the values have changed, for example in the aforementioned module, the build is no longer a valid value for the state parameter and you will have to replace it with state: present and source: build. Also, here the documentation was nice and had many examples, but for some of the other modules, this wasn’t the case.

This and a lot more work will await if you decide to go this way. As said, it took us about an hour to correct the most crucial errors, and another hour to fix other minor mistakes that could lead to not-so-minor problems.

But luckily there is Steampunk Spotter that helps you do the same in 20 minutes. How? We fixed all FQCNs in a flash using the Spotter CLI’s rewrite feature that automatically applies given suggestions. The same goes for generating requirements.yml file with all the collections we need to install. Suddenly, all the errors were gone and other issues (hints and warnings) have been resolved by hand, but easily this time because Spotter gave us just the right tips.

The truth is that when upgrading without Spotter, we even forgot about some of these tiny things that make our playbooks by following best practices. For instance, that “yes” parameter values now default to true for some modules, that with_items is discouraged and should be replaced with loop or that mode parameter should be set explicitly for that ansible.builtin.template. For the other issues, Spotter saved us time searching the web and provided direct links to documentation of a specific module version.

See how in this video and try out Spotter yourself: