Blame docs/ansible/index.md

12bb45
# Ansible usage in CentOS infra
12bb45
12bb45
## Contributing to Ansible infra (playbooks or roles)
12bb45
When you want to contribute to playbooks or roles, you should always open a merge request (PR) against `staging` branch and not `master` branch.
12bb45
One reviewer from the correct org will then get notification and will discuss/review your PR and eventually guide you.
12bb45
Ideally just look at the common way roles are organised, to reuse other roles and convention.
12bb45
Always have default variables for *Everything*, with safe default values (of course never the ones deployed for staging/prod)
12bb45
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.
12bb45
12bb45
##  Naming convention
12bb45
### Roles (regular playbooks used at regular interval)
12bb45
The playbooks that will be played for roles will start with `role-<role_name>`
12bb45
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.
12bb45
Each playbook for a role target a group called `hostgroup-role-<role_name>`. 
12bb45
12bb45
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)
12bb45
12bb45
#### "pre-flight" check
12bb45
For each playbook configuring a role, there is an option (in case of) to end the play if we have to.
12bb45
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
12bb45
12bb45
12bb45
### Deploy (on demand/triggered)
12bb45
Deploy playbooks (can combine also other playbooks) can be named `deploy-<function>`
12bb45
12bb45
12bb45
### Ad-Hoc tasks (on demand/triggered)
12bb45
Simple ad-hoc playbooks can just be named/start with `adhoc-<function>`.
12bb45
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.
12bb45
12bb45
## Complete needed structure (needed on ansible mgmt node)
12bb45
The "on-disk" ansible directory should then look like this :
12bb45
12bb45
```
12bb45
.
12bb45
├── ansible.cfg
12bb45
├── files -> playbooks/files
12bb45
├── handlers -> playbooks/handlers
12bb45
├── filestore
12bb45
├── inventory
12bb45
├── pkistore
12bb45
├── playbooks
12bb45
│   ├── files
12bb45
│   ├── handlers
12bb45
│   ├── requirements.yml
12bb45
│   └── vars
12bb45
│   └── templates
12bb45
├── roles
12bb45
│   ├── <role-name>
12bb45
└── templates -> playbooks/templates
12bb45
└── vars -> playbooks/vars
12bb45
12bb45
```
12bb45
12bb45
## Ansible roles setup
12bb45
All roles will be deployed for a list of individual git repositories, each one being its own role.
12bb45
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
12bb45
12bb45
## Inventory and encrypted files
12bb45
Inventory is itself a different git repository, git-crypted and that will be checked-out on the ansible host
12bb45
Same for the two following git (crypted) repositories:
12bb45
12bb45
 * pkistore (holding some PKI key/certs)
12bb45
 * filestore (holding some other files/secrets that aren't templates but that should be crypted/non public, so not in roles either)
12bb45
12bb45
!!! note
12bb45
    This paragraph is a note and shouldn't be read
12bb45
    Seriously, try something else
12bb45
12bb45
!!! warning
12bb45
    This is a warning
12bb45
    And you should be careful about it
12bb45
12bb45
This is the **end**