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.

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 playbooks on specific host
make run-all HOSTNAME=hostname ANSIBLE_HOST=ip_address

# Run general playbook
ansible-playbook general.yml

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

Development Tasks

# Gather facts from all hosts
make facts

# 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 common configuration, DNS, Tailscale, Caddy
general.yml - General system setup including SNMP, K3s, Docker, syslog
bootstrap.yml - Initial host preparation

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)
caddy - Web server and reverse proxy
ns - Nameserver configuration
resolvers - DNS resolver setup (Unbound)
docker - Docker installation (stub)
k3s_servers - Kubernetes K3s setup (stub)
snmp_clients - SNMP client configuration (stub)

Variable Precedence

Host-specific vars in host_vars/
Group vars in group_vars/
Role defaults in roles/*/defaults/
Base variables in vars/

Service Dependencies

SSH configuration managed by common role
Firewall rules (firewalld) applied before service configs
Handlers ensure services restart when configs change
Tailscale VPN requires TAILSCALE_KEY environment variable

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 use Unbound
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, netbox.netbox

3 KiB Raw Blame History