infra/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 a multi-environment infrastructure-as-code repository managing:

• Ansible: Configuration management for servers across multiple environments (VNTX, home, app servers)
• Terraform: DNS infrastructure management across DNSimple, Porkbun, and PowerDNS
• Kubernetes: K3s cluster deployments on Proxmox with Flatcar/Debian
• Home Lab: K3s configurations with Tailscale integration

Common Commands

Ansible Operations

# Run main playbook
cd ansible && ./run.sh

# Bootstrap new host
make bootstrap-init HOSTNAME=hostname ANSIBLE_HOST=ip_address

# Run specific playbook
ansible-playbook general.yml

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

# Gather facts from all hosts
make facts

Terraform Operations

cd terraform
terraform init
terraform plan
terraform apply

# Format terraform files before committing
terraform fmt

K3s Cluster Deployment (VNTX)

cd clusters/vntx
export TF_VAR_proxmox_password="your-password"
./deploy.sh

# Manual steps if needed:
cd terraform && tofu apply
cd ../ansible && ansible-playbook -i inventory.yml k3s-install.yml
export KUBECONFIG=./kubeconfig
kubectl get nodes

Architecture

Directory Structure

• ansible/ - Ansible playbooks and roles for server configuration

  • roles/ - Reusable roles (base, caddy, docker, k3s, resolvers, etc.)
  • group_vars/ - Group-specific variables
  • host_vars/ - Host-specific variables
  • Main playbooks: playbook.yml, general.yml, bootstrap.yml

• terraform/ - DNS infrastructure management

  • Manages domains: w5isp.com, vntx.net/org, manero.org, mcintire.me, gridmap.org
  • Providers: DNSimple, Porkbun, PowerDNS (reverse DNS)

• clusters/vntx/ - K3s cluster on Proxmox

  • terraform/ - VM provisioning on Proxmox
  • ansible/ - K3s installation and configuration
  • infrastructure/ - Services like Icinga2, FreeRADIUS, Unbound
  • system/ - Core services: MetalLB, Longhorn, cert-manager

• home/ - Home lab K3s configurations

  • k3s/ - K3s service definitions with Tailscale integration
  • cluster/ - Application deployments (Forgejo, Node-RED, etc.)

Key Infrastructure Services

Monitoring: Icinga2 with MariaDB backend DNS: Unbound resolvers, PowerDNS for reverse zones VPN: Tailscale integration across environments Web Proxy: Caddy for reverse proxy and SSL termination Storage: Longhorn distributed storage for K3s Load Balancing: MetalLB for bare-metal K3s

Security Notes

• Ansible user (UID 10001) with passwordless sudo
• SSH keys fetched from GitHub for authentication
• Tailscale requires TAILSCALE_KEY environment variable
• Terraform credentials should use environment variables (TF_VAR_*)

Development Workflow

Adding New Hosts

1. Add host to ansible/hosts inventory
2. Create host_vars file if needed
3. Run bootstrap: make bootstrap-init HOSTNAME=x ANSIBLE_HOST=y
4. Apply configuration: ansible-playbook -l hostname general.yml

DNS Changes

1. Edit appropriate terraform/dns_*.tf file
2. Run terraform fmt to format
3. Review with terraform plan
4. Apply with terraform apply

K3s Service Deployment

1. Create namespace if needed
2. Deploy storage (PVC) if stateful
3. Create ConfigMaps/Secrets
4. Deploy application
5. Configure Service/Ingress for access

Testing

Ansible

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

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

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

Terraform

terraform validate
terraform plan

Kubernetes

kubectl apply --dry-run=client -f manifest.yaml
kubectl diff -f manifest.yaml