After installing ansible package I start with listing all the available roles:

ansible-galaxy list

I am immediately greeted with two warnings:

# /home/peterbabic/.ansible/roles
[WARNING]: - the configured path /usr/share/ansible/roles does not exist.
[WARNING]: - the configured path /etc/ansible/roles does not exist.

Roles path

The reason for this is the default roles_path setting in ansible. It is uncommented in the /etc/ansible/ansible.cfg, but it gives the hint on the default values:

[defaults]
#roles_path = ~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles

The easiest way to get rid of the errors would either be to uncomment and change the value of the roles_path to contain only ~/.ansible/roles or to create the missing directories, but there is a better solution. I like to keep the dotfiles versioned using yadm as a git repository. Fortunately, ansible following administrator conventions is well suited for this. Ansible looks for configuration files in a following order and uses the first one it encounters:

  1. ansible.cfg in the current directory
  2. .ansible.cfg in the home directory
  3. /etc/ansible/ansible.cfg in the filesystem

Naturally, the 2nd option is the most suited for the dotfiles management. To remove the warnings, create the file ~/.ansible.cfg:

[defaults]
roles_path = ~/.ansible/roles

Now the warnings complaining the path does not exist will disappear.

Default inventory file

The next thing is to customize the default inventory file. Peeking back into the /etc/ansible/ansible.cfg one can find the following:

[defaults]
#inventory = /etc/ansible/hosts

Similarly, the file /etc/ansible/hosts is also not very suitable for a version control. This can be changed to a local files inside the ~/.ansible.cfg setting:

[defaults]
inventory  = ~/.ansible_hosts

Depending on the preference, it is possible to use any arbitrary path for the inventory file inside the home directory, for instance ~/.ansible/hosts. I decided against locating the inventory file inside ~/.ansible/ directory due to following reasons:

  1. There are currently only auto-generated files inside the ~/.ansible/ directory
  2. The ansible.cfg and hosts file reside side by side in /etc/ansible/ by default

Putting ~/.ansible.cfg and ~/.ansible_hosts side by side into a home folder currently feels the most natural to me.

Vim settings

I am using vim for my editing, ansible is no exception. Installing ansible-vim plugin by any preferred method enables syntax highlighting among other things. The highlighting also works for ansible inventory files, but only files named hosts are considered. Our file is called .ansible_hosts not hosts, so the right filetype will not be picked up and thus highlighting will not work by default.

There are at least two ways to fix this:

  1. Add an autocmd setting into the .vimrc file
  2. Add a modeline into the inventory file

The first option is documented elsewhere, for instance in the plugin README. I find vimrc solution inferior because it adds unnecessary lines into my vim config and only for one single file. I also need to make sure I update .vimrc should I change the ~/.ansible_hosts location in addition to updating the ~/.ansible.cfg. I see the process prone to errors.

The better approach I believe is to include the information about the filetype in the inventory file itself for vim to pick up. This information is called modeline. It is usually used to set the right indentation style for the file, but can help here equally well. Here's how the modeline in the end of the file looks with the plugin installed:

# vim: set ft=ansible_hosts:

Or, this if YAML is preferred, both works:

# vim: set ft=yaml.ansible:

Equally, even without ansible-vim installed, this modeline will make syntax highlighting work as it was .ini file:

# vim: set ft=dosini:

As a note of interest, I am used to the notion that hosts file represent /etc/hosts, which is something different entirely. The plugin is smart enough to not highlight this file, but still, I find the ansible way for naming it's inventory files the same to be confusing. Not including the file extension, because they tried to make sure multiple formats are supported is also not that common to me.

Note on dotfiles management

Do not forget to add both files into the dotfiles manager. I have seen fellow users promoting chezmoi lately, but I use yadm and I am happy about it so far.

yadm add ~/.ansible.cfg
yadm add ~/.ansible_hosts
yadm commit
yadm push

As a security note, I think an inventory file should not be public in an exposed dotfiles repository and different approach should be considered, for example the hosts file in a private repository.

Summary

After following these steps, it is possible to use ansible roles without unnecessary warnings, having the syntax highlighting enabled and not loosing track of the changes in the files. The steps in order:

  1. Configure ansible-galaxy roles location
  2. Use an inventory file stored in a home directory
  3. Set-up syntax highlighting with ansible-vim
  4. Track the files in the dotfiles repository

For the completeness, an example of with a vim modeline ~/.ansible_hosts:

[webserver]
example.com

# vim: set ft=ansible_hosts:

And the local ansible configuration file ~/.ansible.cfg:

[defaults]
roles_path = ~/.ansible/roles
inventory  = ~/.ansible_hosts

Note that the roles_path represents a directory while the inventory represents a file.

This is a 24th post of #100daystooffload.