dynamic-infra-tooling/README.md

# LoopAware Infrastructure CLI

A professional Python-based CLI for programmatically managing the LoopAware flat network (`10.32.0.0/16`).

## Features

- **DNS/DHCP:** Manage `dnsmasq` reservations and records on `la-dnsmasq-01`.
- **Ingress:** Dynamic HAProxy routing for subdomains.
- **Router:** Manage OpenWrt firewall DNAT rules (TCP/UDP).
- **Proxmox:** Provision and manage LXC containers across physical nodes (`vmh-07` to `vmh-13`).
- **Samba:** Automated User and Group management for Active Directory.

## Installation

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

## Configuration

The CLI requires a `config.yaml` file. A template is provided in `config.yaml.example`.

```bash
cp config.yaml.example config.yaml
# Update the nodes, IPs, and SSH key paths
```

### Environment Variables
- `ROUTER_PASS`: Required for router operations (if SSH keys are not deployed).
- `INFRA_CONFIG`: Optional path to a custom config file.

## Usage Guide

### 1. Identity & Access (Samba)
```bash
# List all users
infra samba list-users

# Create a new user
infra samba add-user "jdoe" "SecurePass123!"

# Grant XMPP access
infra samba add-to-group "xmpp-users" "jdoe"
```

### 2. Compute (Proxmox)
```bash
# List containers on a specific node
infra proxmox list-lxcs --node la-vmh-12

# Create a new container
infra proxmox create-lxc 12150 local:vztmpl/debian-13-standard "new-app" "10.32.70.100/16" "10.32.0.1" --node la-vmh-12
```

### 3. Networking (IP, DNS & DHCP)
Assign a static identity to your new machine. The CLI helps you find free addresses in the dedicated agent pool (`10.32.70.0/16` through `10.32.80.0/16`).

```bash
# Find the next available IP for your project
infra ip next-free

# List top 5 available IPs
infra ip list-free --count 5

# Register the machine in DHCP
infra dns add-host "aa:bb:cc:dd:ee:ff" "10.32.70.100" "new-app"
```

### 4. Cloudflare DDNS
The list of domains to update is managed dynamically on the server.

```bash
# Add a domain to the update list
infra cloudflare add-ddns "my-new-domain.com"

# List all domains being updated
infra cloudflare list-ddns

# Run the update (usually via cron)
infra cloudflare update-ddns
```

## Advanced Workflows for AI Agents

For detailed automation workflows, see [Workflow Documentation](../../docs/guides/dynamic-infrastructure-workflow.md).

## Development and Testing

Run the integration test suite:
```bash
export ROUTER_PASS="..."
pytest tests/test_cli.py -s
```