Ansible Structure¶

Directory tree¶

ansible/
  playbook.yml
  inventory.ini
  requirements.yml
  secrets.yml        # encrypted with ansible-vault
  roles/
    caddy/
      defaults/
        main.yml
      tasks/
        main.yml
      templates/
        caddy.container.j2
        Caddyfile.j2
    grafana/
      dashboards/
        sensors.json
        defaults/
          main.yml
        tasks/
          main.yml
        vars/
          main.yml  
    influxdb/
      defaults/
        main.yml
      tasks/
        main.yml
    mosquitto/
      defaults/
        main.yml
      files/
        mosquitto.conf
      tasks/
        main.yml    
      templates/
        mosquitto.container.j2
    telegraf/
      defaults/
        main.yml
      tasks/
        main.yml
      templates/
        telegraf.conf.j2
        telegraf.container.j2
    vaultwarden/
      defaults/
          main.yml
        tasks/
          main.yml
        vars/
          main.yml  
    tandoor/
      defaults/
        main.yml
      tasks/
        main.yml
      templates/
        .evn.j2
        tandoor-db.container.j2
        tandoor-web.container.j2

Playbook¶

This is the entrypoint for Ansible. It defines the tasks, lists variable files, invites roles and applies templates.
Running it enforces the desired (what you specify in your playbook) state across your inventory.

Inventory¶

This file contains the target machines address and corresponding login details (but that's not stored here).

Requirements¶

It lists external collections needed for this playbook to run, and can be installed with:

ansible-galaxy collection install -r requirements.yml

Currently used collections:

Collection	Version
`containers.podman`	Latest
`grafana.grafana`	6.0.6

Secrets¶

You store your sensitive data here, such as passwords and API tokens, then use these variables to access the contents elsewhere. Currently used secrets:

Variable	Description
`ssh_user`	Username Ansible logs in with
`ssh_password`	Corresponding SSH password
`username`	Local user that should own (some) service files
`group`	Group the user is assigned to
`root_password`	Sudo/root password
`cloudflare_install_token`	Cloudflared service installation token
`cloudflare_api_token`	Cloudflare API token
`influx_admin_user`	InfluxDB admin username
`influx_admin_password`	InfluxDB admin password
`grafana_pass`	Grafana admin password

Variables¶

Here, you store every other variable that is not sensitive, such as ports, directories, docker images and so on.
Their precedence is the following from lowest to highest (only contains relevant items):

Role defaults (roles/{role}/defaults/main.yml)
Vars files (vars.yml and vaults)
Role vars (roles/{role}/vars/main.yml)
Registered vars and set_facts

Templates¶

Templates are Jinja2 files that Ansible renders into real configuration files using variables from the global variable file, vault, role defaults and role variables during playbook execution.
Global templates live in templates/, while role specific templates reside in roles/{role}/templates/

Caddyfile.j2

The .j2 snippet

{{ vaultwarden_domain }} {
    reverse_proxy vaultwarden:{{ vaultwarden_port }}
}

becomes:

subdomain.domain.tld {
    reverse_proxy vaultwarden:1111
}

Roles¶

Reusable task collections that manage a service from start to end live under roles/.
Each role includes its own tasks/ and may have additional vars/, templates/, defaults/ or other directories.