Ansible File Structure, destructured

The big question, Is there a recommended way to structure Ansible projects?

Well, Ansible doesn’t have enforce patterns on how you put files into folders. But there are a few common approaches popular in the ecosystem you may want to consider. This guides walks you through.

Keeping it simple 😉

A pattern recommended though is to keep things as simple as you can, do things simply. Use advanced features only when necessary, if it begins to feel complex for the task, then it's probably complex. The documentation asks you to take the time to look for a simpler solution.

Look no further, one solution is to start with the minimum pattern that is easy to build upon when you need to, and that is what this article is all about.

A typical Ansible file-structure

Keep your files organized in your working Ansible project directory like this:

...
ansible
    ├── ansible.cfg
    ├── first_playbook.yml
    ├── inventory
    ├── group_vars
    │   ├── vyos.yml
    │   └── eos.yml
    ├── roles
    │   ├── static_route
    │   └── system
    ├── second_playbook.yml
    └── third_playbook.yml

With this you can expand your inventory and create and run more network playbooks, let's destructure all these and what goes into them.

Ansible.cfg

This is the ansible config file, commonly referred to as the brain and the heart of Ansible. It is file that defines Ansible config, and is responsible for how all processes in Ansible functions.

By default Ansible reads its configuration file in /etc/ansible/ansible.cfg, however this behavior can be altered. The recommended practice is either to have an ansible.cfg in your current project working directory or to set it as an environment variable.

Playbooks

Ansible Playbooks are way to automate deployment tasks by using a repeatable, re-usable, simple configuration management and multi-platform deployment system.

Each playbook contains one or more plays and each play defines the managed nodes to target and runs one or tasks on it. Each task calls an Ansible module. When you run a playbook, the plays are executed sequentially, play by play and each play also executes it's tasks sequentially from top to bottom.

Ansible lets you define more than one playbook with each paybook focused on one function, you can have one playbook to create your deployment and another one to destroy it. Our example structure show first_playbook.yml, second_playbook.yml and third_playbook.yml.

Inventory

The Ansible inventory file defines the groups of hosts, commands, modules, and tasks a playbook can operate on. It functions as a list of managed nodes. An inventory can specify information like IP address for each managed node, you can designate different servers into groups like webservers, or databases

Group_vars

Ansible uses a combination of a hosts file and a group_vars directory to pull variables per host group and run Ansible plays/tasks against hosts. group_vars/all is used to set variables that will be used for every host that Ansible is ran against.

The group_vars in Ansible are a convenient way to apply variables to multiple hosts at once, they also provide a pattern for the reusability of group variables, saving you efforts to sort the hosts and also enhance the flexibility in your code.

Roles

Roles allows to easily reuse your grouped content, One way to use roles is with the roles option for a play, then ansible follow your file structure and the order listed below to execute the role and replace the play task with its values.

• Any pre_tasks defined in the play.
• Any handlers triggered by pre_tasks.
• Each role listed in roles:, in the order listed. Any role dependencies defined in the role’s meta/main.yml run first, subject to tag filtering and conditionals.
• Any tasks defined in the play.
• Any handlers triggered by the roles or tasks.
• Any post_tasks defined in the play.
• Any handlers triggered by post_tasks.

Time for an example

In addition to the above recommendations, i also recommend that you practalize your knowledge, Rafael has written an amazing article on how to automate the setup of a Kubernetes cluster on GCP following a similar structure.

This is the format he implemented

...
└── ansible                    # Ansible top-level folder
    ├── ansible.cfg            # Ansible config file
    ├── create-k8s.yml         # Ansible playbook to provision env
    ├── destroy-k8s.yml        # Ansible playbook to destroy env
    ├── inventory             
    │   └── gcp.yml            # Ansible inventory file
    └── roles
        ├── destroy_k8s        # Ansible role to remove k8s cluster        
        │   └── tasks
        │       └── main.yml
        ├── destroy_network    # Ansible role to remove VPC
        │   └── tasks
        │       └── main.yml
        ├── k8s                # Ansible role to create k8s cluster
        │   └── tasks
        │       └── main.yml
        └── network            # Ansible role to create VPC
            └── tasks
                └── main.yml

Conclusion

Ansible makes deploying your infrastructure easier and it's best when used as intended, Don't over complicate it, start simple and with time you would discover what structure works best for your organization.

Thank you for reading, I hope you learned a lot already. I'm Azeez Lukman and here's a developer's journey building something awesome every day. Please let's meet on Twitter, LinkedIn, GitHub and anywhere else @robogeeek95