vn-ansible/README.md

# Verdnatura Ansible playbooks

Collection of Ansible playbooks used in the Verdnatura server farm.

## Install Ansible

Instal Ansible on Debian.
```
apt install ansible
```

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

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

## Run playbook

Before merging changes into protected branches, playbooks should be tested 
locally to ensure they work properly.

Launch playbook on the fly on a host not declared in the inventory.
```
ansible-playbook -i <ip_or_hostname>, [-t tag1,tag2] playbooks/test.yml
```

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

## Manage vault

To manage Ansible vault place the password into *.vaultpass* file.

View or edit the vault file.
```
ansible-vault {view,edit} --vault-pass-file .vaultpass vault.yml
```

When running playbooks that use the vault the *vault-playbook.sh* script can 
be used, it is ovelay over the original *ansible-playbook* command.

## Create execution environment

Create an image with *ansible-builder* and upload it to registry.
```
ansible-builder build --tag ansible-runner: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://www.passbolt.com/blog/managing-secrets-in-ansible-using-passbolt
* https://galaxy.ansible.com/ui/repo/published/anatomicjc/passbolt/
* https://www.ansible.com/blog/introduction-to-ansible-builder/