infra/ansible/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is an Ansible infrastructure management repository that manages a mixed environment including network services, monitoring, VPN infrastructure, and web applications. The codebase supports multiple operating systems (Debian, Ubuntu, AlmaLinux) and uses a role-based architecture for modularity.

Note: Flatcar Container Linux VMs are provisioned by OpenTofu and configured via Butane/Ignition — they are NOT managed by Ansible.

Common Commands

Bootstrap New Hosts

# Initial bootstrap (requires password)
make bootstrap-init HOSTNAME=hostname ANSIBLE_HOST=ip_address

# Full bootstrap with network config and reboot
make bootstrap HOSTNAME=hostname ANSIBLE_HOST=ip_address

Run playbooks

# Run main playbook
./run.sh

# Run all plays on specific host
ansible-playbook -l hostname playbook.yml

# Run specific tags
ansible-playbook -t caddy playbook.yml

Development Tasks

# Gather facts from all hosts
ansible -m setup all

# Test changes on specific host
ansible-playbook -l hostname playbook.yml

# Check syntax
ansible-playbook --syntax-check playbook.yml

# Dry run
ansible-playbook --check playbook.yml

Architecture

Playbook Structure

• playbook.yml - Main playbook for all configuration (common, firewall, DNS, Caddy, general, monitoring, PostgreSQL, prometheus stack, etc.)
• bootstrap.yml - Initial host preparation
• netbox.yml - Standalone NetBox deployment

Role Organization

Roles follow a standard structure with:

• tasks/main.yml - Main task list
• handlers/main.yml - Service restart handlers
• templates/ - Jinja2 templates for config files
• vars/ - Role-specific variables
• defaults/ - Default variable values

Key Roles

• base - Combined base configuration (users, SSH, sudo, packages)
• general - General system configurations (motd, network, syslog, NFS, K3s)
• caddy - Web server and reverse proxy
• firewall - UFW/firewalld rule management
• ns - BIND9 nameserver configuration
• tailscale - Tailscale VPN setup
• monitor - Icinga2 monitoring master
• prometheus / alertmanager / loki / grafana / node_exporter - Prometheus monitoring stack
• netbox - NetBox IPAM/DCIM
• pgbouncer - PostgreSQL connection pooler
• librenms - LibreNMS network monitoring
• mailcow - Mailcow email server
• dokku - Dokku PaaS
• aprsc - APRS-IS server
• uisp - Ubiquiti UISP
• syncthing - Syncthing file sync

Variable Precedence

1. Host-specific vars in host_vars/
2. Group vars in group_vars/
3. Role defaults in roles/*/defaults/
4. Base variables in vars/

Service Dependencies

• SSH configuration managed by base role
• Firewall rules (UFW/firewalld) applied before service configs
• Handlers ensure services restart when configs change
• Tailscale VPN requires TAILSCALE_AUTHKEY (or TAILSCALE_KEY) environment variable
• SSH key path defaults to ~/.ssh/ansible; override via ANSIBLE_SSH_PRIVATE_KEY_FILE env var

Key Patterns

User Management

• Ansible user (UID 10001) created on all hosts
• SSH keys fetched from GitHub for authentication
• Passwordless sudo configured for automation

Network Services

• DNS resolvers are Flatcar VMs managed via OpenTofu + Butane (see ../tofu/)
• Nameservers configured via ns role
• Caddy serves as reverse proxy for web services
• Tailscale provides VPN connectivity

Configuration Management

• Templates use host-specific variables
• Handlers manage service restarts
• Fact caching improves performance
• Collections required: ansible.posix, community.general, kubernetes.core, community.postgresql, community.proxmox, community.mysql

Memories

Playbook Defaults

• The default ansible playbook is playbook.yml