Ansible Projects

On this page we are going to discuss exactly how Edmonds Commrce creates and manages Ansible projects.

Coding Standards

Here are the coding standars for Edmonds Commerce Ansible projects

Folders and Filenames

If the ansible project is a sub folder of another project, the folder name should be ansible-project

If the ansible project is a standalone project with it's own repository, the root of the repo is the ansible project root

Inventory

Inventory should be managed with a folder per environment that then contains multiple files.

The directory name should be inventory.{envirnoment-name}

Inventory files should be in ini format and have the .ini extension

Example Directory Structure

1
2
3
4
5
6
.
├── group_vars
├── host_vars
├── inventory.local
├── inventory.production
└── roles

Playbooks

Playbook files should be in the root of the project

The file name should be in the format playbook-{playbook-name}.yml

Playbooks should not contain any actual tasks, they should only include roles. Your tasks should be in roles

Whilst it is possible to have sub playbooks that are imported into the main playbook, it is preferable to keep as much as possible in roles and to only have the main playbook.

Main Playbook

Each project should have a single "main" playbook that builds everything

Our main playbook must be called playbook-main.yml

The best practices refer to this file as site.yml, however I do not think this is explicit enough.

Managing Project Dependencies

Coming from the PHP world that now enjoys the wonderful features of Composer you might hope that Ansible has something similar. It doesn't

However we can get pretty close by following these rules:

Warning

Whilst following these rules get's something like Composer. It is no where near as fully featured or good. Main differences include: * ansible-galaxy will not create git repos in the roles folder, they will just be files

Ignore the Roles Folder in Git

Add the roles folder to your .gitignore file. This then becomes the equivalent of vendor in the composer world.

If you want to work on custom roles, you can, you simply need to add an exclusion to your .gitignore file, such as:

1
2
roles/*
!roles/my-custom-role

Track Dependencies in a Text File

ansible-galaxy allows us install multiple roles as listed in a file.

We can use this to provide us with rudimentary project level depenedency management

In your project root, create a file called requirements.yml, and in this file list all of your roles.

For example:

1
2
- src: edmondscommerce.lxc
- src: edmondscommerce.akeneo

Always Use the File Based Install to Update Roles

To install roles, get in the habit of always using the mulitple roles file based approach

1
2
3
4
5
6
7
8
# go to the ansible project root
cd ansible-project

# ensure the roles directory exists
mkdir -p roles

# install all dependencies
ansible-galaxy install -r requirements.yml --roles-path=roles

Create Ansible Playbook to Install Roles

To make this easier, you might want to create this ansible playbook in your Ansible project root:

Eg the file playbook-install-roles.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
- hosts: localhost

  tasks:
    - name: Remove any none git folders from the roles directory. We assume that if it is a git repo, its being developed on locally and should not be removed.
      local_action:
        command find roles -mindepth 1 -maxdepth 1 -type d '!' -exec test -e "{}/.git" ';' -print | xargs rm -rf

    - name: Install Galaxy Roles in the requirements.yml file
      local_action:
        command ansible-galaxy install -r requirements.yml --roles-path roles

    - name: Make sure the roles directory is being git ignore
      lineinfile:
        dest:   .gitignore
        regexp: '^\/roles$'
        line:   '/roles'
        state:  present

Warning - thi

Warning - this playbook will totally delete your roles folder It's good in a purist sense because it forces you to