## ROLES ANATOMY

Ansible Terminal

     tree example_role/

    example_role/
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    │   └── main.yml
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    ├── templates
    ├── tests
    │   ├── inventory
    │   └── test.yml
    └── vars
        └── main.yml

Let's take a moment to look at the anatomy of a role and discuss the various directories and files we see in a newly created role.

## MAIN ROLE DIRECTORY

Ansible Terminal

     tree example_role/

    example_role/
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    │   └── main.yml
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    ├── templates
    ├── tests
    │   ├── inventory
    │   └── test.yml
    └── vars
        └── main.yml

The role, by default, creates a directory with its own name, then subdirectories below that. When you call this role within an Ansible playbook, you use this directory name as the name of the role to include.

## DEFAULTS AND VARIABLES

Ansible Terminal

     tree example_role/

    example_role/
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    │   └── main.yml
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    ├── templates
    ├── tests
    │   ├── inventory
    │   └── test.yml
    └── vars
        └── main.yml

The VARIABLES and DEFAULTS in a role are essentially the same type of information. But remember in the variable order of precedence, once is the highest and one is the lowest.

For example, any variables we put in the DEFAULTS main.yml file will be overwritten anywhere else they are defined. This is because DEFAULTS is the lowest order of precedence for variables. We put in default values here, knowing they can and possibly will be overwritten at some point.

On the other hand, the VARS are the highest level of precedence, aside from extra variables fed into the role at run-time. These can only be overridden by passing variables at the command line or Tower "extra vars" or, by re-declaring them with different values in the playbook itself.

A real-world example might be a role with predefined defaults but a user who wants to overwrite their stored version of the role by adding new variables into vars/main.yml. These new variables will override the role defaults without having to delete or edit that file.

## FILES DIRECTORY

Ansible Terminal

     tree example_role/

    example_role/
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    │   └── main.yml
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    ├── templates
    ├── tests
    │   ├── inventory
    │   └── test.yml
    └── vars
        └── main.yml

This directory commonly contains files intended to copy to a remote system or an entire directory structure to sync remotely. In the playbook, we can refer to these source files simply as the relative path files/filename (files slash filename)

## HANDLERS DIRECTORY

Ansible Terminal

     tree example_role/

    example_role/
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    │   └── main.yml
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    ├── templates
    ├── tests
    │   ├── inventory
    │   └── test.yml
    └── vars
        └── main.yml

Handlers run once the tasks are complete. Instead of putting handlers in-line in your playbook, we put them in this special location, to be evaluated once the tasks are complete.

## METADATA AND README

Ansible Terminal

     tree example_role/

    example_role/
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    │   └── main.yml
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    ├── templates
    ├── tests
    │   ├── inventory
    │   └── test.yml
    └── vars
        └── main.yml

This is mostly important for GIT communication and publishing to galaxy. The metadata is crucial for ansible galaxy to be able to search and filter on the metadata you include. The README is helpful for users who want to pull your code from a public git source. The README commonly includes examples of a playbook to run your role or specific variables that can / should be overwitten.

## TASKS DIRECTORY

Ansible Terminal

     tree example_role/

    example_role/
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    │   └── main.yml
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    ├── templates
    ├── tests
    │   ├── inventory
    │   └── test.yml
    └── vars
        └── main.yml

TASKS is possibly the most important location. Ansible looks inside tasks/main.yml first to determine what to do in a role. You can have all of your role's tasks in-line or your main.yml can conditionally (or statically) include additional files to separate and extend your tasks for organizational purposes.

## TEMPLATES DIRECTORY

Ansible Terminal

     tree example_role/

    example_role/
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    │   └── main.yml
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    ├── templates
    ├── tests
    │   ├── inventory
    │   └── test.yml
    └── vars
        └── main.yml

Similar to files, this is a directory where your templates are stored. Unlike files, templates likely include a jinja2 syntax or variables inside them to make them dynamically change as they're copyied by Ansible.

## TESTS DIRECTORY

Ansible Terminal

     tree example_role/

    example_role/
    ├── defaults
    │   └── main.yml
    ├── files
    ├── handlers
    │   └── main.yml
    ├── meta
    │   └── main.yml
    ├── README.md
    ├── tasks
    │   └── main.yml
    ├── templates
    ├── tests
    │   ├── inventory
    │   └── test.yml
    └── vars
        └── main.yml

This directory is used for defining unit testing and validation of the role to confirm it ran the way you wanted it to run and that systems are responding as expected.