# Roles

## 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:

<div id="bkmrk-defaults-%3A-contains-">- <div>**defaults** : contains default values for the role. These are the available variables you'll be able to set in your host_vars/ or group_vars/ to configure the service</div>
- <div>**tasks** : contains the action to run to configure the role</div>
- <div>**templates**: contains [jinja2](https://jinja.palletsprojects.com/ "https://jinja.palletsprojects.com/") templates which will be deployed on the host</div>
- <div>**files**: contains files which will be deployed (as-is, no template processing)</div>
- <div>**vars**: contains variables used by the role. Usualy, variables which you should change are defined in defaults. In vars are defined variables used by the role which you shouldn't have to change</div>
- <div>**handlers** : containers handlers (eg, how to restart services when a configuration file changed)</div>

</div>### defaults &amp; 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)

```YAML
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) }}"
```

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**

```YAML
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
```

### 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 :

```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
```

<div id="bkmrk-please%2C-read-ansible"><div>Please, read ansible documentation if you need more detailed information on this</div></div>Now, you can create the files

<div id="bkmrk-group_vars%2Ffws%2Fvars.">- <div>**group\_vars/fws/vars.yml** : all the variables defined here will be inherited by **proxyin.fws.fr**, **docker1.fws.fr** and **docker2.fws.fr**</div>
- <div>**group\_vars/fws\_docker/vars.yml** : all the variables defined here will be inherited by **docker1.fws.fr** and **docker2.fws.fr**</div>

<div>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**.</div></div>### 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](https://docs.ansible.com/ansible/latest/user_guide/vault.htmlansible-vault "https://docs.ansible.com/ansible/latest/user_guide/vault.htmlansible-vault") utility.

<div id="bkmrk-ansible-vault-create">```shell
`ansible-vault create group_vars/fws/vault.ym`
```

</div>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 :

<div id="bkmrk-ansible-vault-edit-g"><div>```
ansible-vault edit group_vars<span class="sy0">/</span>fws<span class="sy0">/</span>vault.yml
```

</div></div>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