140 lines
No EOL
3.8 KiB
Markdown
140 lines
No EOL
3.8 KiB
Markdown
# 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
|
|
``` |