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

### Official Recommended Flow
1. **Find an IP:** `infra ip next-free`
2. **Create Database:** `infra db provision "my-project"`
3. **Provision LXC:** `infra proxmox create-lxc debian-13 "my-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 "my-host"`
5. **Update SSL:** `infra cert renew`
6. **Expose Ingress:** `infra ingress add "my-project.loopaware.com" 10.32.70.x 80`

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

## 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.

## Pro-Tips for Developers

### Environment Selection
- **Staging:** Use `--node la-vmh-07` for experiments.
- **Public Production:** Use `--node la-vmh-12`.
- **Private Production:** Use `--node la-vmh-13`.

### Programmatic Integration
The CLI is designed to be consumed by other scripts. Use the `--config` flag or `INFRA_CONFIG` environment variable to point to your configuration.

```bash
# Get just the IP for scripting
NEW_IP=$(infra ip next-free)
```

## Development

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