feat: Add professional hierarchical documentation

- Created comprehensive README.md with Mermaid diagrams, badges, and TOC - Added docs/ directory with 7 sections and 14 markdown files - Included architecture diagrams, flowcharts, and sequence diagrams - All documentation is fully interlinked with cross-references - Added ISO storage location on Proxmox development server - Included troubleshooting guide and evaluation management docs - All config files (Packer, Terraform, Ansible, Forgejo) documented - Added icons and visual elements throughout documentation
2026-02-06 14:47:15 +00:00 · 2026-02-06 14:47:15 +00:00 · e4f03427b7
commit e4f03427b7
parent faf04d69f8
24 changed files with 3844 additions and 2 deletions
--- a/docs/04-terraform/main.tf.md
+++ b/docs/04-terraform/main.tf.md
@ -0,0 +1,223 @@
+# 🏗️ OpenTofu Resources
+
+[![OpenTofu](https://img.shields.io/badge/OpenTofu-Latest-green?style=flat&logo=opentofu)](https://opentofu.org/)
+[![Proxmox](https://img.shields.io/badge/Proxmox-VE-orange?style=flat&logo=proxmox)](https://www.proxmox.com/)
+
+## Overview
+
+OpenTofu provisions ephemeral Windows VMs from the Packer-built template. This document details the Terraform/OpenTofu configuration in [`terraform/main.tf`](../../terraform/main.tf).
+
+---
+
+## Configuration Structure
+
+```mermaid
+graph TD
+    subgraph OpenTofu["OpenTofu Configuration"]
+        direction TB
+        Provider[Provider Config] --> Resources[VM Resource] --> Clone[Clone Strategy] --> Output[VM IP Output]
+    end
+    
+    subgraph ResourceParts["VM Resource Parts"]
+        Basic[Basic Settings] --> Hardware[CPU/Memory] --> Network[Network Config] --> Init[Cloud-Init/IP]
+    end
+    
+    Provider --> Resources
+    Resources --> ResourceParts
+    
+    style OpenTofu fill:#e3f2fd
+    style ResourceParts fill:#e8f5e9
+```
+
+---
+
+## Full Configuration
+
+```hcl
+terraform {
+  required_providers {
+    proxmox = {
+      source = "bpg/proxmox"
+      version = "0.46.1"
+    }
+  }
+}
+
+provider "proxmox" {
+  endpoint = "https://proxmox-host:8006/"
+  # Credentials injected via Environment Variables in Forgejo
+  # PM_API_TOKEN_ID and PM_API_TOKEN_SECRET
+}
+
+resource "proxmox_virtual_environment_vm" "build_agent" {
+  name      = "ci-win-build-${var.build_id}"
+  node_name = "la-vmh-07"
+  
+  clone {
+    # Packer template VM ID
+    vm_id      = var.template_vm_id
+    full_clone = false
+  }
+
+  cpu {
+    cores = 4
+    type  = "host"
+  }
+  
+  memory {
+    dedicated = 8192
+  }
+  
+  network_device {
+    bridge = "vmbr0"
+  }
+
+  initialization {
+    ip_config {
+      ipv4 {
+        address = "dhcp"
+      }
+    }
+  }
+}
+
+output "vm_ip" {
+  value = proxmox_virtual_environment_vm.build_agent.ipv4_addresses[1][0]
+  description = "IP address of the provisioned VM"
+}
+```
+
+---
+
+## Variables
+
+### Input Variables
+
+**File:** [`terraform/variables.tf`](../../terraform/variables.tf)
+
+```hcl
+variable "build_id" {
+  description = "Unique identifier for the build"
+  type        = string
+}
+
+variable "template_vm_id" {
+  description = "VM ID of the Packer-built template"
+  type        = number
+  default     = 9000
+}
+```
+
+### Usage
+
+```bash
+export TF_VAR_build_id="123"
+export TF_VAR_template_vm_id="9000"
+tofu apply -auto-approve
+```
+
+---
+
+## Section Details
+
+### Provider Configuration
+
+| Setting | Value | Description |
+|---------|-------|-------------|
+| `endpoint` | `https://proxmox-host:8006/` | Proxmox API URL |
+| `source` | `bpg/proxmox` | Proxmox provider |
+| `version` | `0.46.1` | Provider version |
+
+### VM Clone Configuration
+
+| Setting | Value | Description |
+|---------|-------|-------------|
+| `vm_id` | `var.template_vm_id` | Template VM ID to clone |
+| `full_clone` | `false` | Fast linked clone |
+| `node_name` | `la-vmh-07` | Target Proxmox node |
+
+### Hardware Configuration
+
+| Setting | Value | Notes |
+|---------|-------|-------|
+| `cores` | 4 | CPU cores |
+| `type` | `host` | Host-passthrough CPU |
+| `dedicated` | 8192 | 8 GB dedicated RAM |
+
+### Network Configuration
+
+| Setting | Value | Notes |
+|---------|-------|-------|
+| `bridge` | `vmbr0` | Default Proxmox bridge |
+| `ip_config` | DHCP | Automatic IP assignment |
+
+---
+
+## Provisioning Process
+
+```mermaid
+flowchart LR
+    subgraph Process["OpenTofu Process"]
+        direction TB
+        Init[tofu init] --> Plan[tofu plan] --> Apply[tofu apply] --> Clone[Clone VM] --> Start[Start VM] --> IP[Get VM IP]
+    end
+    
+    subgraph Template["Template"]
+        T[Template VM] --> |Clone| V[New VM]
+    end
+    
+    Apply --> Template
+    V --> Start
+    
+    style Process fill:#e3f2fd
+    style Template fill:#e8f5e9
+```
+
+---
+
+## Output
+
+```hcl
+output "vm_ip" {
+  value = proxmox_virtual_environment_vm.build_agent.ipv4_addresses[1][0]
+}
+```
+
+**Usage in pipeline:**
+```bash
+VM_IP=$(tofu output -raw vm_ip)
+echo "VM_IP=$VM_IP" >> $GITHUB_ENV
+```
+
+---
+
+## Environment Variables
+
+| Secret | Env Var | Purpose |
+|--------|---------|---------|
+| Proxmox Token ID | `PM_API_TOKEN_ID` | Authentication |
+| Proxmox Token Secret | `PM_API_TOKEN_SECRET` | Authentication |
+
+---
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Clone failed | Wrong VM ID | Check template VM ID in Proxmox |
+| No IP assigned | DHCP not working | Check network bridge |
+| Permission denied | Token lacks privileges | Add VM.Admin to token |
+
+---
+
+## Next Steps
+
+| Goal | Next Document |
+|------|---------------|
+| View variables | [Terraform Variables](variables.md) |
+| Run Ansible | [Ansible Pipeline](../05-ansible/pipeline.md) |
+| Run full pipeline | [Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) |
+
+---
+
+[← Documentation Index](../index.md) | [→ Variables](variables.md) | [← Packer Autounattend](../03-packer/autounattend.md)