What are some of your best tips and tricks when developing your Ansible roles?

[Razique]

When creating roles for your playbooks, what are some of the tips and tricks you are applying yourself to make your roles more robust or resilient? 

How do you write your unit tests?

[Rik_NL]

tbh, my main trick is to stay away from roles ... until you are very very comfortable with Ansible and it serves a clear goal to use a role/roles for your given situation. I see to many students on day 2 start asking about roles when they are not even ready to automate a simple httpd install.

And when you start thinking about some type of automated testing, work with TDD or Test Driven Development. Describe what it is you want to achieve, describe how you would prove you achieved said goal and then start writing your playbooks.

Personally, i first write on a piece of paper whatever i would have done in bash. Then create ad-hoc oneliners, compile them into plays and playbooks and then rewrite it into a role whenever i think it will serve a purpose when the playbooks are available as a role. By then the code is pretty stable.

[JorgeAndrade]

Interested also about unit testing !

What do you use for that ?

[DanK · Accepted solution]

Unit testing is a great idea for roles.  If you write and use roles, its important to incorporate testing.    There's a lot out there about how best to "test" a role.  I hope others will share what they do.

At a minimum, I use the "tests" directory of a role as a smoke test.  So, my "tests" directory looks a lot like a playbook directory.  I have an ansible.cfg file, an inventory file, a requirements.yml file, a roles directory (if the role has dependencies), a site.yml file, a group_vars and host_vars directory (if needed).  This means that I can clone a role, modify the inventory file, and run the site.yml playbook.  I try to make sure that my roles work on their own.

[Razique]

Thanks Dan. Those are helpful tips.

I also been finding myself enjoying using the setup module beforehand to see which facts and variables the host gives me and the JSON structure, that helps me to better parse the output and get what I need.

[littlebigfab]

Hi Razique! :)

Here are my top tips & tricks ;)

1. use the 'ansible galaxy init' command to create the folders' tree, because it also generates yaml files with fancy comments ; delete the unnecessary directories of the role at the end, if any
   
   
2.  store the role in a dedicated gitlab project, so that it can easily be used by a roles/requirements.yml file with the scm=git directive
   
   
3.  insert a link to the role's gitlab project in meta/main.yml (galaxy_info.description)
   
   
4.  declare all variables exposed to users in defaults/main.yml, even though they do not have a default value (in such a case, use 'null' instead), so that users know in a glance what variables they can use ; use comments to specify which ones are mandatory / optional
   
   
5.  use the debug module as the first task of tasks/main.yml to display the value of all role variables ; I always build and display a 'role_parameters' dictionary made up with 2 keys, 'mandatory' and 'optional', each of them containing corresponding variables as key/value pairs
   
   
6.  use the assert module as the second task of tasks/main.yml to perform sanity and consistency checks of all variables ; in case of failure, the user will be able to refer to the preceding task to check the variables in use
   
   
7.  always add the |bool filter when manipulating a boolean variables, to convert boolean-style strings user inputs to real booleans
   
   
8.  be idempotent: avoid the 'command' and 'shell' modules ; favor jinja2 templates over commands that alter existing files ; use the 'changed_when' and 'failed_when' attributes to improve the execution log's accuracy
   
   
9.  be secure: use no_log=true for tasks that would otherwise expose passwords or sensitive data
   
   
10.  be readable: use '>' to split one line into several lines, for example to introduce a complex 'when' statement
    
    
11. be handy: use explicit names for role's files and templates ; I always add prefixes such as 'crontab__', 'logrotate__', 'systemd__', 'sudoers__', etc... so that users navigating in the corresponding role's folders immediately identify files and templates

[Razique]

Amazing tips and feedback @littlebigfab. Point 10 is a great one. I also use it when I write multi-lines text.

Point 7 is a great reminder that I should get into the habit of doing it as well :)