k.renner
c13b5819d1
git-subtree-dir: ansible git-subtree-mainline:2d82d3bd67git-subtree-split:693bc3fc87
4.9 KiB
Ansible Repository Documentation
This repository houses the Ansible configurations used for managing the infrastructure, including configuration management, software deployment, and system updates for Virtual Machines (VMs) and LXC containers.
Table of Contents
Project Structure
The project is organized efficiently to separate data, logic, and execution:
ansible.cfg: The main configuration file defining defaults for the Ansible executable.inventory/: Contains thehosts.ymlfile which defines the infrastructure hierarchy, host groups, and host-specific variables.plays/: Task-oriented playbooks. These are the entry points for executing changes on the infrastructure.roles/: Reusable units of configuration and logic. Roles abstract complex tasks into simple, reusable components.vars/: Directory for storing global variable files (currently empty).
Configuration
The Ansible environment is configured via ansible.cfg with the following key defaults:
- Inventory Source:
~/.ansible/inventory(and/etc/ansible/hosts) - Roles Path:
~/.ansible/roles - Authentication: Uses the private key at
~/.ssh/id_ed25519 - Host Key Checking: Disabled (
False) for easier automation in dynamic environments.
Inventory
The inventory is defined in YAML format in inventory/hosts.yml. It categorizes hosts into groups for targeted automation.
Note: Specific host parameters such as proxmox_node and proxmox_vmid are defined here for integration with Proxmox tasks.
Roles
Roles are self-contained logical units used to deploy specific services or configurations.
Infrastructure & Base
common: Applies baseline configurations (users, packages, settings) common to all hosts.certificates: Manages SSL/TLS certificates.qemu-guest-agent: Installs and checks QEMU guest agent status.rustfs: Sets up RustFS (likely a custom filesystem or storage solution).
Service Deployment
audiobookshelf: Deploys Audiobookshelf (self-hosted audiobook server).caddy-ha: Sets up Caddy in a High Availability configuration.cloudflared: Deploys Cloudflare Tunnel daemon for securing exposed services.cloudflared-lxc: Specialized Cloudflared setup for LXC containers.gitea: Deploys Gitea (Git service).gitea-lxc: Gitea setup optimized for LXC.gitea-runner: Sets up Gitea Actions runners.ollama: Deploys Ollama for local LLM inference.wazuh: Deploys Wazuh agents for security monitoring.
Maintenance & Updates
docker-install: Installs Docker engine and compose.docker-update: Updates Docker containers and images.pve-update: Updates Proxmox VE nodes.vm-update: General update tasks for VMs.authentik-update: Specific routines for updating Authentik.
Playbooks
Playbooks in the plays/ directory orchestrate the roles and tasks.
Setup & Installation
These playbooks are used to provision new services or nodes.
install-gitea.yml: Full installation of Gitea.install-rustfs.yml: Deploys RustFS.setup-caddy-ha.yml: Configures Caddy H/A.setup-cloudflared.yml: Sets up Cloudflare tunnels.setup-gitea-proxy.yml: Configures a proxy for Gitea.setup-gitea-runner.yml: Provisions a build runner for Gitea.create-ha-dev-vm.yml: Creates a High Availability development VM.create-template.yml: Creates a VM template.create-tfstate-bucket.yml: Sets up storage for Terraform/OpenTofu state.
Updates & Maintenance
Routines for keeping the infrastructure up-to-date.
update.yml/update_all_software.yml: General update execution.dist-upgrade.yml: Performs distribution-level upgrades (e.g., viaapt dist-upgrade).check-dist-upgrade.yml: Checks if a distribution upgrade is available.docker-update.yml: Updates running Docker containers.lxc-update.yml: Specialized update routine for LXC containers.pve-rolling-update.yml: Performs a rolling update on Proxmox VE nodes.vm-update.yml: Updates standard VMs.authentik-update.yml: Updates the Authentik identity provider.
Migration & Cleanup
Helper scripts for transitions and housekeeping.
paperless-migration.yml: Tasks for migrating Paperless-ngx instances.cleanup-gitea-mess.yml: Remediation script for Gitea issues.destroy-ha-dev-vm.yml: Tears down the HA dev environment.install-error-page.yml: Deploys custom error pages (likely for the proxy/load balancer).