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