dynamic-infra-tooling/README.md

# LoopAware Infrastructure CLI

A robust Python-based CLI designed for automated management of the LoopAware infrastructure. Built for developers and AI agents to provision and manage resources on a flat `10.32.0.0/16` network.

## Core Modules

| Module | Command | Description |
|--------|---------|-------------|
| **Identity** | `infra samba` | Manage Active Directory users and groups. |
| **Compute** | `infra proxmox` | Provision and destroy LXC containers across nodes. |
| **Database**| `infra db` | Provision PostgreSQL databases and users. |
| **Network** | `infra dns` | Manage static DHCP leases and DNS records. |
| **IP AM**   | `infra ip` | Automatic discovery of free IPs in the agent pool. |
| **Ingress** | `infra ingress` | Manage HAProxy subdomains and routing. |
| **Certificates**| `infra cert` | Manage SSL/TLS certificates (Let's Encrypt). |
| **External**| `infra cloudflare`| Manage Cloudflare DNS and Dynamic DNS updates. |

## Installation

```bash
cd external/dynamic-infra-tooling
pip install -e .
```

## Configuration

The CLI looks for a config file at `~/.config/loopaware/infra-cli.yaml` or the path specified in the `INFRA_CONFIG` environment variable.

```bash
# Set up your local config
cp config.yaml.example config.yaml
export INFRA_CONFIG=$(pwd)/config.yaml
```

## Common Workflows

### Provisioning a New Service
1. **Find an IP:** `infra ip next-free`
2. **Create Database:** `infra db provision "project-name"`
3. **Provision LXC:** `infra proxmox create-lxc 12345 debian-13 "project-host" "10.32.70.x/16" "10.32.0.1" --node la-vmh-12`
4. **Setup DNS:** `infra dns add-host <MAC> 10.32.70.x "project-host"`
5. **Expose Ingress:** `infra ingress add "project.loopaware.com" 10.32.70.x 80`

### Full Decommission
Clean up every trace of a service in one command:
```bash
infra decommission --domain project.loopaware.com --mac <MAC> --vmid 12345 --node la-vmh-12 --port-name project_udp
```

### 4. Certificates (Let's Encrypt)
The infrastructure uses a consolidated SAN (Subject Alternative Name) strategy to optimize Let's Encrypt rate limits.

- **`loopaware.com.pem`**: Wildcard cert for all public services.
- **`la-infra-san.pem`**: Consolidated SAN cert for all internal `*.fe.loopaware.com` hosts.

The system automatically discovers new internal hosts and adds them to the SAN certificate nightly at 3:00 AM.

```bash
# List all active certificates in shared storage
infra cert list

# Check expiry date of the main wildcard cert
infra cert status

# Manually trigger discovery and renewal (Rate-limit safe)
infra cert renew
```

### 5. Cloudflare DDNS

## Safety & Validation
- **Template Resolution:** The `debian-13` alias automatically finds the latest template on the target Proxmox node.
- **Input Validation:** All IPs, MACs, and Ports are validated before execution.
- **Pre-flight Checks:** The CLI verifies SSH connectivity to nodes before attempting changes.

## Development

### Running Tests
```bash
export ROUTER_PASS="..."
pytest tests/test_cli.py -v
```