diff options
Diffstat (limited to 'ansible/README.md')
| -rw-r--r-- | ansible/README.md | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/ansible/README.md b/ansible/README.md new file mode 100644 index 0000000..f693916 --- /dev/null +++ b/ansible/README.md @@ -0,0 +1,82 @@ +This part of the repo is responsible for provisioning our +home-lab services using Ansible on top of the infrastructure already +created via Terraform. + +The basic pattern is to confiure the service, and then add the upstream host +to our reverse proxy (Caddy) configuration. + + + +# TODOs (in-progress) +1. reverse-proxy init +1. minio user,bucket init +1. static sites using minio bucket + +# Done +1. Adding service to reverse-proxy (Caddy) via api +1. Media Downloader with Transmission, and `*arr` services +1. Plex +1. Password Manager +1. Nextcloud +1. Metrics monitoring + +--- + +# Pre-reqs +* `pip`3 - `sudo apt install python3 python3-pip` +* `ansible` - `pip install --user ansible` + +# Execution +1. (First Time Only) Fork this repo, if you haven't already. +1. (FTO) Make sure that your [`hosts`](./hosts) have been created in the [Terraform](../terraform) section. +1. (FTO) Edit `group_vars/all/vault.example` to your liking. +```bash +echo "YourSecretPassword" > vaultkey +ansible-vault encrypt --output group_vars/all/vault --encrypt-vault-id vaultkey group_vars/all/vault.example +git checkout group_vars/all/vault.example +``` +1. View/edit your encrypted vault: +```bash +ansible-vault view/edit --vault-id vaultkey group_vars/all/vault +``` +1. (FTO) Run the `init.yaml` playbook to install a service +```bash +ansible-playbook -u youruser -i hosts --vault-id vaultkey playbooks/init.yaml --tags=[app name] +``` +1. Use another playbook to modify a service (not yet implemented but planned) +```bash +ansible-playbook -u youruser -i hosts --vault-id vaultkey playbooks/... --tags=[...] +``` + +# Ansible Roles +You can think of each Role being an "app". + +Each Role has a `setup.yaml` task file responsible for installing the app. +It may or may not have other task files depending on what other functionality this Role +supports for this app. + +The `main.yaml` file in the Role determines the flow logic for which task files +are getting run based on Tags for other functionalities (see Tags section below). + + +# Artifacts +The directory `playbooks/artifacts/` is a place where we save the output for some of the roles. + +This not only serves the purpose to tracking important state info for our configurations, +but it also allows us to use some of this info in other parts of Ansible for cleaner automation. + +> Never commit this dir to git. It contains sensitive info! Its already configured to +be ignored by git. + + +# Ansible Tags +Setting up the app is normally done using the Role's name as the tag, +i.e. `--tags <role name>`. + +Any subsequent tasks required beyond setting up the app, will have a different +tag associated for those tasks (along with a different playbook to trigger them). +For example, the MinIO Role will support adding a new user+bucket under the tag `add_minio_user`: + +```bash +ansible-playbook ... playbooks/add_user.yaml --tags add_minio_user +``` |