====== Roles and their configuration ======

===== Role directories =====

A role is a set of instruction which describe how to install or update a functionnality. Roles are under the roles directory (no joke ;-) ). Each role have several sub directories:
  * defaults : contains default values for the role. This is the available variables you'll be able to set in your host_vars/ or group_vars/ to configure the service
  * tasks : contains the action to run to configure the role
  * templates: contains [[https://jinja.palletsprojects.com/|jinja2]] templates which will be deployed on the host
  * files: contains files which will be deployed (as-is, no template processing)
  * vars: contains variables used by the role. Usually, variable which you should change are defined in defaults. In vars are defined variables used by the role which you shouldn't have to change
  * handlers : containers handlers (eg, how to restart services when a configuration file changed)

===== defaults & variables =====

**defaults** is really the most important part of a role. Check the file defaults/main.yml of a role to see which variables you can tune. For example, for the role docker (which can install docker daemon on a host)

<file yaml main.yml>
docker_data_dir: /opt/docker
docker_log_driver: journald

docker_base_conf:
  data-root: /opt/docker
  log-driver: journald
  storage-driver: overlay2
  storage-opts:
    - 'overlay2.override_kernel_check=true'
docker_extra_conf: {}
# docker_extra_conf:
#   log-opts:
#     max-size: 100m
#     max-file: 5

docker_conf: "{{ docker_base_conf | combine(docker_extra_conf, recursive=True) }}"
</file>

This is all the variable you can set to modify how Docker will be configured. You do not have to configure everything, just set the variables for which the default value doesn't fit your need.

===== hosts variables =====

For example, if you deploy docker on the host docker.fws.fr, just create **host_vars/docker.fws.fr/vars.yml**

<file yaml vars.yml>
docker_extra_conf:
  data-root: '/data'
  log-driver: 'json-file'
  log-opts:
    max-size: '100m'
    max-file: '5'
  iptables: False
  group: dockeradmins
  userns-remap: default
  live-restore: True
  dns:
    - 10.118.1.1
</file>

===== groups variables =====
For some settings, you'll want to share them with a group of hosts (eg, the AD domain to join, or the Docker settings above, if you deploy several Docker hosts). In this case, you can create a group of host in your inventory file, for example :

<code ini>
[fws]
proxyin.fws.fr
docker1.fws.fr
docker2.fws.fr

[fws_docker:vars]
ansible_group_priority=2

[fws_docker]
docker1.fws.fr
docker2.fws.fr
</code>

<note tip>Please, read ansible documentation if you need more detailed information on this</note>

Now, you can create the files
  * group_vars/fws/vars.yml : all the variables defined here will be inherited by proxyin.fws.fr, docker1.fws.fr and docker2.fws.fr
  * group_vars/fws_docker/vars.yml : all the variables defined here will be inherited by docker1.fws.fr and docker2.fws.fr

<note tip>With the above ansible_group_priority, if a variable is defined in both fws and fws_docker, the one from fws_docker will be used for docker1.fws.fr and docker2.fws.fr</note>

===== encrypted variables =====
You might need to set secret values in variables, like passwords. In this case, you do not want to store them as cleartext. Then, just use the [[https://docs.ansible.com/ansible/latest/user_guide/vault.htmlansible-vault]] utility.

<code bash>
ansible-vault create group_vars/fws/vault.yml
</code>

You'll be prompted for a password to encrypt the file. The syntaxe is the same as a normal file. If you want to edit an existing vault, use instead :
<code bash>
ansible-vault edit group_vars/fws/vault.yml
</code>

When you run the ansible playbook, if a host requires access to variables in a vault, you'll be prompted to enter the vault password