ansible/project-docs/architecture.md

Architecture

High-level map (modules and relationships)

• Inventory: inventories/production/

  • hosts: groups like dev, desktop, services, qa, ansible, tailscale, local
  • group_vars/all/main.yml: shared configuration (including app_projects)
  • group_vars/all/vault.yml: encrypted secrets (Ansible Vault)
  • host_vars/*: per-host overrides (some encrypted)

• Playbooks: playbooks/

  • playbooks/site.yml: dispatcher (imports other playbooks)
  • playbooks/servers.yml: baseline for servers (services:qa:ansible:tailscale)
  • playbooks/workstations.yml: baseline for dev:desktop:local + desktop apps for desktop group only
  • playbooks/development.yml: dev machines baseline (no desktop apps)
  • playbooks/local.yml: localhost baseline (no desktop apps)
  • playbooks/app/*: Proxmox app-project provisioning/configuration suite

• Roles: roles/*

  • Baseline/security: base, user, ssh
  • Dev tooling: development, datascience, docker
  • Shell: shell (minimal aliases-only)
  • Monitoring split:
    • monitoring_server (fail2ban + sysstat)
    • monitoring_desktop (desktop-oriented monitoring tooling)
  • Proxmox guests: proxmox_vm
  • App guest configuration: base_os, app_setup, pote

Proxmox “app projects” flow (data model + execution)

• Data model: app_projects in inventories/production/group_vars/all/main.yml

  • Defines projects and per-env (dev/qa/prod) guest parameters (ip, branch, vmid, etc.)

• Provision: playbooks/app/provision_vms.yml

  • Loops app_projects → envs → calls role: proxmox_vm to create LXC guests
  • Adds dynamic inventory groups:
    • app_all
    • app_<project>_all
    • app_<project>_<env>

• Configure: playbooks/app/configure_app.yml

  • Builds a dynamic inventory from app_projects (so it can run standalone)
  • Applies:
    • role: base_os (baseline OS for app guests)
    • role: app_setup (deploy + systemd) or role: pote for the POTE project

Boundaries

• Inventory/vars define desired state and credentials.
• Playbooks define “what path to run” (role ordering, target groups, tags).
• Roles implement actual host configuration (idempotent tasks, handlers).

External dependencies

• Ansible collections: collections/requirements.yml
• Ansible Vault: inventories/production/group_vars/all/vault.yml
• Proxmox API: used by community.proxmox.* modules in provisioning

References

• Playbook execution graphs and tags: docs/reference/playbooks-and-tags.md
• Legacy pointer (do not update): docs/reference/architecture.md → project-docs/architecture.md