vn-ansible/README.md

# Verdnatura Ansible playbooks

Collection of Ansible playbooks used in the Verdnatura server farm.

## Setup Ansible

### Debian

Install Ansible package.
```
apt install ansible
```

### Python

Create a Python virtual environment.
```
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip ansible==10.1.0 ansible-builder==3.1.0
```

Before running any Python dependent command, activate the virtual environment.
```
source venv/bin/activate
```

Once you are done, deactivate the virtual environment.
```
deactivate
```

### All platforms

Install dependencies.
```
pip install -r requirements.txt
ansible-galaxy collection install -r collections/requirements.yml
```

## Run playbook

Before merging changes into protected branches, playbooks should be tested 
locally to ensure they work properly. The *inventories/local* inventory is not 
uploaded to the repository and can be used for local testing. In any case, it 
is advisable to use a different repository to store inventories.

Run playbook on inventory host.
```
ansible-playbook -i inventories/local -l <host> [-t tag1,tag2...] playbooks/ping.yml
```

Run playbook on the fly on a host not declared in the inventory.
```
ansible-playbook -i <ip_or_hostname>, playbooks/ping.yml
```

*Note the comma at the end of the hostname or IP.*

List available tags for playbook.
```
ansible-playbook playbooks/<playbook_name>.yml --list-tags
```

## Manage secrets

Secrets can be managed by using Ansible vault or an external keystore, Passbolt 
is used in this case. It is recommended to use an external keystore to avoid 
publicly exposing the secrets, even if they are encrypted.

When running playbooks that use any of the keystores mentioned above, the 
*run-playbook.sh* script can be used, it is an ovelay over the original 
*ansible-playbook* command which injects the necessary parameters.

### Passbolt

Add the necessary environment variables to the *.passbolt.yml* file, the 
template file *.passbolt.tpl.yml* is included as a reference:

* https://galaxy.ansible.com/ui/repo/published/anatomicjc/passbolt/docs/

### Ansible vault

To manage Ansible vault place the encryption password into *.vault-pass* file.

Manage the vault.
```
ansible-vault {view,edit,create} --vault-pass-file .vault-pass .vault.yml
```

> The files used for the vault must only be used locally and 
> under **no** circumstances can they be uploaded to the repository.

## Build execution environment for AWX

Create an image with *ansible-builder* and upload it to registry.
```
ansible-builder build --tag awx-ee:vn1
```

## Common playbooks

* **facts.yml**: Collect and display facts from a host
* **ping.yml**: Check that a host is alive and reachable
* **awx.yml**: Create and configure AWX user
* **debian.yml**: Setup base Debian server

## Documentation

* https://docs.ansible.com/ansible/latest/reference_appendices/config.html
* https://docs.ansible.com/ansible/latest/collections/ansible/builtin/gather_facts_module.html
* https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_vars_facts.html
* https://ansible.readthedocs.io/projects/builder/en/latest/
* https://www.ansible.com/blog/introduction-to-ansible-builder/
* https://github.com/ansible/awx-ee/
* https://www.passbolt.com/blog/managing-secrets-in-ansible-using-passbolt