# Terraform LXC Deployment for Iron Legion — PRD

**Status:** Draft | **Author:** Artemis | **Date:** 2026-06-04

## 1. Objective

Deploy Proxmox LXC containers via Terraform using the `bpg/proxmox` provider, running inside a custom Docker container (lazy automator pattern). Support runtime parameterization for bulk LXC creation with auto-incrementing VMID, IPv4, and naming.

## 2. Architecture

### 2.1 Docker Image

**Base:** Custom Dockerfile extending `hashicorp/terraform:latest`
**Provider:** `bpg/proxmox` pre-installed via `terraform init` at build time
**Pattern:** Matches thelazyautomator's guide — local workspace mounted into container

```dockerfile
FROM hashicorp/terraform:latest
# Pre-install bpg/proxmox provider cache
COPY providers.tf /tmp/providers.tf
RUN cd /tmp && terraform init -upgrade && rm -f providers.tf
WORKDIR /workspace
ENTRYPOINT ["terraform"]
```

### 2.2 Credential Model

Proxmox API token stored in `.env` / `terraform.tfvars`, referenced as variables:

```hcl
variable "pm_api_url" {
  default = "https://192.168.7.33:8006/api2/json"
}

variable "pm_api_token_id" {
  default = "root@pam!terraform"
}

variable "pm_api_token_secret" {
  default = "terraform"
}
```

Token to be created on MK33: `pveum user token add root@pam terraform --comment "Terraform automation" --privsep 0`

### 2.3 Runtime Parameterization

| Parameter | Example | Effect |
|-----------|---------|--------|
| `count` | `4` | Number of LXCs to create |
| `vmid_base` | `5050` | Starting VMID |

Auto-derived per LXC (index `i` from 0 to `count-1`):
- **VMID:** `vmid_base + i`
- **Name:** `lxc-${vmid}`
- **IPv4:** `192.168.${first2digits(vmid)}.${last2digits(vmid)}/18`
  - Example: vmid 5050 → `192.168.50.50/18`
  - Example: vmid 5051 → `192.168.50.51/18`

### 2.4 LXC Configuration (Static)

- **OS:** Debian 13 (or Debian 12 if 13 unavailable)
- **CPU:** 1 vCPU, 2 cores
- **RAM:** 2048 MB
- **Storage:** 8GB rootfs on local disk (test), migrate to NFS after validation
- **Network:** Static IPv4 with gateway `192.168.0.1`

### 2.5 User / SSH (Option A First)

Bake `jarvis` user + SSH key into LXC via `initialization` block:

```hcl
initialization {
  user_account {
    username = "jarvis"
    keys     = [file("~/.ssh/artemis_key.pub")]
  }
}
```

**Fallback (B):** If initialization fails after 3 attempts, set root password to `ubuntu` via `root_password` and let Ansible configure post-build.

## 3. Phase Breakdown

### Phase 1 — Single LXC (Plan/Build/Destroy)

**Goal:** Prove the pipeline works end-to-end with one manual LXC.

**Deliverables:**
- `Dockerfile` for custom Terraform image
- `docker-compose.yml` for local execution
- `main.tf` — single LXC resource with hardcoded VMID
- `providers.tf` — bpg/proxmox provider config
- `variables.tf` — API credentials and defaults
- `run.sh` — wrapper script for plan/apply/destroy

**Test:**
```bash
./run.sh plan    # Validate config
./run.sh apply   # Build lxc-5050
./run.sh destroy # Clean up
```

### Phase 2 — Modular + Bulk Creation

**Goal:** Add `count`, `vmid_base`, and auto-derived naming/IP.

**Deliverables:**
- `modules/lxc/` — reusable LXC module
- `locals.tf` — VMID/IP/name calculation logic
- `main.tf` — uses module with `count = var.lxc_count`
- Step-counter for sequential VMID assignment

**Example execution:**
```bash
TF_VAR_lxc_count=4 TF_VAR_vmid_base=5050 ./run.sh apply
# Creates: lxc-5050, lxc-5051, lxc-5052, lxc-5053
```

## 4. File Structure

```
~/docker/terraform-pve/
├── Dockerfile
├── docker-compose.yml
├── run.sh
├── terraform/
│   ├── providers.tf
│   ├── variables.tf
│   ├── main.tf
│   ├── locals.tf
│   └── modules/
│       └── lxc/
│           ├── main.tf
│           ├── variables.tf
│           └── outputs.tf
```

## 5. Open Questions

1. **Debian version:** Is Debian 13 available on your PVE nodes as a template, or should we use Debian 12?
2. **Gateway IP:** Confirm `192.168.0.1` is the correct gateway for `192.168.0.0/18` subnet?
3. **DNS servers:** Use Technitium (`192.168.7.7`) for LXC `/etc/resolv.conf`?
4. **SSH key:** Use `~/.ssh/artemis_key.pub` for jarvis user, or a dedicated terraform key?

## 6. Decision Points

| Decision | Option A | Option B |
|----------|----------|----------|
| Debian template | 13 (if available) | 12 (fallback) |
| DNS | Technitium (192.168.7.7) | Router default (192.168.18.1) |
| SSH key | artemis_key.pub | New dedicated terraform key |

---

**Awaiting Commander Bobby approval before Phase 1 build.**