# Ansible usage in CentOS infra

## Contributing to Ansible infra (playbooks or roles)
When you want to contribute to playbooks or roles, you should always open a merge request (PR) against `staging` branch and not `master` branch.
One reviewer from the correct org will then get notification and will discuss/review your PR and eventually guide you.
Ideally just look at the common way roles are organised, to reuse other roles and convention.
Always have default variables for *Everything*, with safe default values (of course never the ones deployed for staging/prod)
When proposing a change in the behaviour, always make that change a opt-in, that defaults to "no" (safest) so that only that change would be applied on other nodes *if* variable used to include that task would be turned on. Of course we can have on real needs a default to `True` if we know that such change would need to be replicated by default on all nodes controlled by Ansible and using that role.

##  Naming convention
### Roles (regular playbooks used at regular interval)
The playbooks that will be played for roles will start with `role-<role_name>`
A all-in-one roles-all.yml will just include all the role-<role_name>.yml when we want to just ensure the whole infra is configured the way it should.
Each playbook for a role target a group called `hostgroup-role-<role_name>`. 

There a small exceptions where some role-<role_name> playbooks will be small variants of a role, so also with other tasks to call specific tasks for an existing role (so when for example a vhost for httpd is a variant of the httpd role)

#### "pre-flight" check
For each playbook configuring a role, there is an option (in case of) to end the play if we have to.
Basically touching /etc/no-ansible on a managed node would ensure that the playbook is ended. That permits to have (in emergency for example) someone having a look at a node and ensuring that ansible doesn't modify the node at the same time. After each role configuration, a file is also created (monitored by Zabbix) to ensure that nodes are always configured as they have to


### Deploy (on demand/triggered)
Deploy playbooks (can combine also other playbooks) can be named `deploy-<function>`


### Ad-Hoc tasks (on demand/triggered)
Simple ad-hoc playbooks can just be named/start with `adhoc-<function>`.
Those specific playbooks can need some tasks/vars/handlers, so for those special ones (as each role has it own set) we'll include those in the same repository, but it's up to the process deploying those for the ansible-host role to setup correctly the needed symlinks for the normal hierarchy.

## Complete needed structure (needed on ansible mgmt node)
The "on-disk" ansible directory should then look like this :

```
.
├── ansible.cfg
├── files -> playbooks/files
├── handlers -> playbooks/handlers
├── filestore
├── inventory
├── pkistore
├── playbooks
│   ├── files
│   ├── handlers
│   ├── requirements.yml
│   └── vars
│   └── templates
├── roles
│   ├── <role-name>
└── templates -> playbooks/templates
└── vars -> playbooks/vars

```

## Ansible roles setup
All roles will be deployed for a list of individual git repositories, each one being its own role.
A requirements.yml file will be used to declare which roles (and from where to get them) and so downloaded on the ansible host through ansible-galaxy

## Inventory and encrypted files
Inventory is itself a different git repository, git-crypted and that will be checked-out on the ansible host
Same for the two following git (crypted) repositories:

 * pkistore (holding some PKI key/certs)
 * filestore (holding some other files/secrets that aren't templates but that should be crypted/non public, so not in roles either)

!!! note
    This paragraph is a note and shouldn't be read
    Seriously, try something else

!!! warning
    This is a warning
    And you should be careful about it

This is the **end**