Here are some best practices to consider while writing the Ansible playbooks. This article should be particularly useful for anyone starting with Ansible.
While writing the playbooks in YAML, consider them as the documentation of the automation that you are bringing into the environment. Anyone with knowledge of Ansible should be able to read the playbooks and easily be able to decipher what those are expected to do.
- Version Control. Treat the playbooks just like other software development code. It is necessary to keep them in a repository like Git and use the code development approach to version control them and release them to production. Use pull requests and code reviews to progress a code through the development, test, production stages. Code reviews may not be a typical process for sysadmin teams, however this is one of the practices of software development that is essential to be adopted, especially before using the playbooks in production.
- Start simple and then build on it. While starting to write a play book it would be easiest to document the thought process in a single play and then fine tune and break it up from there. Consider breaking the playbooks into multiple logical playbooks and roles and then stitching them together from a main playbook.
- Treat the code as documentation. A well written playbook is the documentation of the automation workflow. Strive to keep the workflow simple and easily readable. Anyone reading this playbook should easily understand what is going on in the workflow. This should be part of the acceptance criteria when accepting pull requests. Few simple guidelines are:
- Use self explanatory name of playbooks and roles
- Include meaningful
nameto the tasks
- Give meaningful and unique names to the
variables. Consider grouping the variables together in the playbook rather than having them all over the playbook.
- Include meaningful
debugstatements. Can someone new to the environment understand what exactly is going on when a playbook is executed? Also consider if a debug message is really necessary rather than overusing them. The key messages should be covered. Also consider the right verbosity level.
- Use meaningful hostnames rather than IP addresses and cryptic hostnames.
- Modules first. Always use modules over shell commands. Check the available modules with
- Roles. Use
ansible-galaxy initcommand to create the role directory structure. Remove the unused directories from the role directory structure to simplify and improve readability.
- No point reinventing the wheel. Before writing a playbook from scratch research what may already be available in the repositories. A similar code may already have been written by someone in another part of the organisation. Use that as a starting point and fine tune it for your environment.
I would recommend you to listen to the talk by Timothy Appnel, Principal Product Manger of Ansible.