93 lines
4.2 KiB
Markdown
93 lines
4.2 KiB
Markdown
# Ansible
|
|
|
|
Bootstraps, syncs, and starts/stops the Docker Compose stacks in `../services/`
|
|
on the three servers OpenTofu provisions (see `../infra/`). OpenTofu still owns
|
|
the actual cloud resources (servers, network, firewalls, DNS);
|
|
everything downstream of "the server exists" - installing Docker, creating the
|
|
`deploy` user, hardening SSH, copying `services/<host>/`, rendering `.env` /
|
|
the Gitea runner compose file, and running `spinup.sh`/`spindown.sh` - lives
|
|
here instead. Persistent service data lives in named Docker volumes backed up
|
|
to S3, not on a Hetzner volume - see `../readme.md`.
|
|
|
|
## Contents
|
|
|
|
- `inventory/hcloud.yml` - dynamic inventory, queries the Hetzner Cloud API
|
|
directly (not Terraform state) and groups servers by their `role` label
|
|
(`role_dev`, `role_prod`, `role_vpn` - set in `infra/modules/<host>/main.tf`).
|
|
- `roles/bootstrap/` - Docker install, `deploy` user creation, SSH hardening,
|
|
unattended-upgrades. Replaces `infra/scripts/bootstrap.sh.tftpl`.
|
|
- `roles/deploy/` - copies `services/<host>/` to the server and renders `.env`
|
|
(S3 backup credentials, see `../readme.md`) and, for `dev`,
|
|
`Runners/docker-compose.yml`.
|
|
- `playbooks/` - `bootstrap.yml`, `deploy.yml`, `spinup.yml`, `spindown.yml`,
|
|
`site.yml` (all three in order), and `group_vars/` (`all.yml` - shared:
|
|
`deploy_user`, SSH key path, `backup_s3_*` S3 backup credentials;
|
|
`role_dev.yml` / `role_prod.yml` / `role_vpn.yml` - per-role vars, e.g.
|
|
`service_group`). `group_vars/` lives here rather than at the `ansible/`
|
|
root because Ansible only auto-loads `group_vars/`/`host_vars/` from
|
|
directories adjacent to the playbook file or the inventory source - not
|
|
from an arbitrary sibling directory.
|
|
|
|
## Prerequisites
|
|
|
|
```sh
|
|
cd ansible
|
|
ansible-galaxy collection install -r requirements.yml
|
|
export HCLOUD_TOKEN=your-hetzner-api-token # never commit this
|
|
export BACKUP_S3_BUCKET=your-bucket-name
|
|
export BACKUP_S3_ACCESS_KEY_ID=your-access-key-id
|
|
export BACKUP_S3_SECRET_ACCESS_KEY=your-secret-access-key
|
|
export BACKUP_S3_ENDPOINT=your-s3-endpoint # omit for real AWS S3
|
|
```
|
|
|
|
`../control.sh`'s **Set variables** menu does the same thing interactively and
|
|
persists your answers to `../.control.env` (gitignored) so you don't have to
|
|
re-export them every session.
|
|
|
|
`deploy_user` (see `playbooks/group_vars/all.yml`) defaults to `deploy` - override with
|
|
the `DEPLOY_USER` env var if you want a different non-root user created on each
|
|
host. `ansible_ssh_private_key_file` (same file) defaults to
|
|
`~/.ssh/id_ed25519` - override with `ANSIBLE_SSH_PRIVATE_KEY_FILE` if you use a
|
|
different key. It must match one of the SSH keys OpenTofu installed on the
|
|
servers (`var.ssh_key_names`).
|
|
|
|
## Usage
|
|
|
|
Same chicken-and-egg as OpenTofu's own first-apply ordering (see
|
|
`../readme.md`): `dev`/`prod`'s firewalls only accept SSH from `vpn`'s own
|
|
public IP, so you must bring `vpn` up and connect to it before `dev`/`prod`
|
|
are reachable at all.
|
|
|
|
```sh
|
|
# 1. vpn first - its firewall accepts SSH from var.allowed_ssh_source_ips directly
|
|
ansible-playbook playbooks/bootstrap.yml -l role_vpn
|
|
ansible-playbook playbooks/deploy.yml -l role_vpn
|
|
ansible-playbook playbooks/spinup.yml -l role_vpn
|
|
|
|
# 2. connect to the VPN you just started with an OpenVPN client - now dev/prod
|
|
# are reachable, since your egress IP matches their firewall rule
|
|
ansible-playbook playbooks/bootstrap.yml -l role_dev,role_prod
|
|
ansible-playbook playbooks/deploy.yml -l role_dev,role_prod
|
|
ansible-playbook playbooks/spinup.yml -l role_dev,role_prod
|
|
|
|
# ...or once already bootstrapped and connected, do everything in one go:
|
|
ansible-playbook playbooks/site.yml -l role_dev,role_prod
|
|
```
|
|
|
|
Re-run `deploy.yml` + `spinup.yml` any time a compose file changes - `spinup.sh`
|
|
only starts/updates what's changed, same as before. `dev` always runs three
|
|
Gitea Actions runners (fixed in
|
|
`roles/deploy/templates/runners-docker-compose.yml.j2`).
|
|
|
|
`spindown.yml` runs `spindown.sh`, which does a full `docker system/volume
|
|
prune -a` on the host - it prompts for a `yes` confirmation before running,
|
|
since the dynamic inventory makes it trivial to target multiple hosts at once
|
|
(`-l role_dev,role_prod`).
|
|
|
|
Inspect what the dynamic inventory currently sees:
|
|
|
|
```sh
|
|
ansible-inventory --graph
|
|
ansible-inventory --list
|
|
```
|