101 lines
3.0 KiB
Markdown
101 lines
3.0 KiB
Markdown
# The Ansible Edda
|
|
|
|
Ansible playbooks for provisioning **The Nine Worlds**.
|
|
|
|
## Running the playbooks
|
|
|
|
The main entrypoint for **The Nine Worlds** is [`main.yml`](main.yml).
|
|
|
|
### Keyring integration
|
|
|
|
Keyring integration requires `python3-keyring` to be installed.
|
|
|
|
To set the keyring password run:
|
|
|
|
``` sh
|
|
./vault-keyring-client.py --set [--vault-id <vault-id>]
|
|
```
|
|
|
|
If `--vault-id` is not specified, the password will be stored under `ansible`.
|
|
|
|
To use the password from the keyring invoke playbooks with:
|
|
|
|
``` sh
|
|
ansible-playbook --vault-id @vault-keyring-client.py ...
|
|
```
|
|
|
|
### Production and testing
|
|
|
|
The inventory files are split into [`inventory/production`](inventory/production) and
|
|
[`inventory/testing`](inventory/testing).
|
|
|
|
To run the `main.yml` playbook on production hosts:
|
|
``` sh
|
|
ansible-playbook -i inventory/production main.yml
|
|
```
|
|
|
|
To run the `main.yml` playbook on testing hosts:
|
|
``` sh
|
|
ansible-playbook -i inventory/testing main.yml
|
|
```
|
|
|
|
### Playbooks
|
|
|
|
The Ansible Edda playbook is composed of smaller [`playbooks`](playbooks). To run a single playbook,
|
|
invoke the relevant playbook directly from the playbook directory. For example, to run the
|
|
[`playbooks/system.yml`](playbooks/system.yml) playbook, run:
|
|
|
|
``` sh
|
|
ansible-playbook playbooks/system.yml
|
|
```
|
|
|
|
Alternatively you can use its tag as well:
|
|
|
|
``` sh
|
|
ansible-playbook main.yml --tags "system"
|
|
```
|
|
|
|
### Roles
|
|
|
|
Playbooks are composed of roles defined in the
|
|
[`roles`](http://git.thenineworlds.net/the-nine-worlds/ansible-roles) submodule and
|
|
[`playbooks/roles`](playbooks/roles).
|
|
|
|
To play a specific role, e.g., `system/base/sshd` in the playbook `system`, run:
|
|
``` sh
|
|
ansible-playbook playbooks/system.yml --tags "system:base:sshd"
|
|
```
|
|
|
|
To play all roles from a specific group, e.g., `system/base` in the playbook `system`, run:
|
|
``` sh
|
|
ansible-playbook playbooks/system.yml --tags "system:base"
|
|
```
|
|
|
|
Some roles, e.g., `services/setup/user`, have sub-tasks which can also be invoked individually. To
|
|
find the relevant tag, see the role's `tasks/main.yml`.
|
|
|
|
In all cases, the roles can be also invoked from the main playbook:
|
|
``` sh
|
|
ansible-playbook main.yml --tags "system:base:sshd"
|
|
ansible-playbook main.yml --tags "system:base"
|
|
```
|
|
|
|
## Testing virtual machines
|
|
|
|
The scripts for starting, stopping, and reverting the testing virtual machines is located in
|
|
[`scripts/testing/vmgr.py`](scripts/testing/vmgr.py).
|
|
|
|
## Managing backup buckets
|
|
|
|
The [`scripts/restic/restic.py`](scripts/restic/restic.py) script provides a wrapper around restic
|
|
to manage the backup buckets. The script collects the credentials from the OS keyring and constructs
|
|
the restic command with the correct endpoint. It allows the user to focus on the actual command to
|
|
be executed rather than authentication and bucket URLs.
|
|
|
|
The `scripts/restic/restic.py` requires the following entries in the keyring:
|
|
- `scaleway`: `access_key` (Scaleway project ID),
|
|
- `scaleway`: `secret_key` (Scaleway secret key),
|
|
- `restic`: `password`.
|
|
|
|
The easiest way to set these values is with Python's `keyring.set_password`.
|