# 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
```bash
# 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
```bash
cd terraform
terraform init
terraform plan
terraform apply

# Format terraform files before committing
terraform fmt
```

### K3s Cluster Deployment (VNTX)
```bash
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
```bash
# 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
```bash
terraform validate
terraform plan
```

### Kubernetes
```bash
kubectl apply --dry-run=client -f manifest.yaml
kubectl diff -f manifest.yaml
```