Best practices for sharing Ansible Roles across multiple projects
Ansible is a great tool with a lot of flexibility. It’s generally the easiest configuration management tool for new users to start with due to the batteries-included philosophy, straightforward DSL, and daemonless push model.
However, as your infrastructure goals become more complex, the flexibility means it’s less obvious how things should be structured.
For example, it’s very common to reuse the same role across multiple projects, and I’ve talked with many people who handle this by copy/pasting the role in each project. Anytime they make a change to the role, they have to remember to manually update all the projects that have copies of that role, which is tedious and error-prone.
There is a better way.™ A couple of little-known Ansible features can be combined to easily share a single role across multiple projects without duplicating code.
To do this, I stick all my shared roles in a single master folder that gets shared across all my projects. This avoids the tediousness of manual copy/pasting and updating multiple copies of the same role. If you want more granularity, this technique also supports organizing groups of roles into dedicated folders–perhaps one for roles used in work projects and one for person projects.
Than I modify each project’s ansible.cfg to tell Ansible to look for roles in that master folder in addition to the local project folder.
Sample ansible.cfg:
|
1 2 |
[defaults] roles_path = ~/Code/ansible_roles |
Ansible first searches the local project for a role, then searches the roles_path. You can specify multiple paths by separating them with colons.
By default, ansible-galaxy install username.rolename will install the role to the roles_path configured in ansible.cfg, so that’s pretty much all you need to do.
Occasionally I want to install the role into the specific project and not the master folder. For example, to avoid version conflicts when two roles have role dependencies that require different versions of the same role. In that case, you can use the -p ROLES_PATH or --roles-path=ROLES_PATH option:
|
1 |
ansible-galaxy install username.rolename -p ~/Code/project_deploy/ansible/roles/ |
Alternatively, in your project’s requirements.yml, you can manually specify where you want a role to be installed:
|
1 2 3 4 5 6 |
# from galaxy - src: jeffwidman.elasticsearch # from private github repo, installing to a relative path - src: https://github.com/jeffwidman/private_ansible_role path: vagrant/roles/ |
If you want to customize things further, there’s currently some discussion about Ansible 2.0 adding support for multiple ansible.cfg files which would let you easily set roles_path at varying levels of specificity. Ansible will read ANSIBLE_CONFIG, ansible.cfg in the current working directory, .ansible.cfg in the home directory or /etc/ansible/ansible.cfg, whichever it finds first.
If you want to see more examples of how I use Ansible, check out my roles on Ansible Galaxy.
I found that ~/Code/ansible_roles needed in my case to be ~/Code/ansible/roles
but your article is a top find and has enabled me to clean up my roles and better structure ansible code
many thanks!
That was incredibly useful. In my case, this post was a hook to learning about galaxy collections. Now I can have a shared collection across several ansible projects.
I create an ansible collection by defining a galaxy.yaml and the roles I want to share across the projects.
Then, in each project, I referenced the collection in the requirements.yaml. Something like
# requirements.yaml
collections:
- name: git+https://bitbucket.org/company/ansible.wordpress.git
type: git
version: stable
To download and install the collection in the requirements, I did
$ ansible-galaxy collection install -r requirements.yaml -p collections
Finally, in the playbook yaml I did
---
- name: Basic settings for server
hosts:
- all
collections:
- company.wordpress
roles:
- { role: company.wordpress.common }
- { role: company.wordpress.nginx }
- { role: company.wordpress.php }
- { role: company.wordpress.letsencrypt }