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)
--- a/docs/04-terraform/variables.md
+++ b/docs/04-terraform/variables.md
@ -0,0 +1,158 @@
+# 📊 Terraform Variables
+
+[![Terraform](https://img.shields.io/badge/Terraform-OpenTofu-green?style=flat&logo=terraform)](https://opentofu.org/)
+
+## Overview
+
+This document details all input variables for the OpenTofu configuration.
+
+---
+
+## Variables File
+
+**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
+}
+```
+
+---
+
+## Variable Details
+
+### build_id
+
+| Property | Value |
+|----------|-------|
+| Description | Unique identifier for the build |
+| Type | String |
+| Required | Yes |
+| Example | `"2024-02-06-001"` |
+
+**Purpose:** Creates unique VM names for each pipeline run, enabling parallel builds and preventing naming conflicts.
+
+```hcl
+# Generated VM name
+name = "ci-win-build-${var.build_id}"
+# Example: ci-win-build-2024-02-06-001
+```
+
+### template_vm_id
+
+| Property | Value |
+|----------|-------|
+| Description | VM ID of the Packer-built template |
+| Type | Number |
+| Default | `9000` |
+| Required | No |
+
+**Purpose:** Specifies which template to clone when provisioning VMs.
+
+```hcl
+# Default value
+vm_id = 9000
+
+# Custom value
+vm_id = var.template_vm_id
+```
+
+---
+
+## Setting Variables
+
+### Method 1: Environment Variables
+
+```bash
+export TF_VAR_build_id="123"
+export TF_VAR_template_vm_id="9000"
+tofu plan
+```
+
+### Method 2: tfvars File
+
+Create `terraform/terraform.tfvars`:
+
+```hcl
+build_id       = "2024-02-06-001"
+template_vm_id = 9000
+```
+
+### Method 3: Command Line
+
+```bash
+tofu apply -var="build_id=123" -var="template_vm_id=9000"
+```
+
+---
+
+## Sensitive Variables
+
+| Variable | Sensitive | Reason |
+|----------|-----------|--------|
+| `build_id` | No | Public identifier |
+| `template_vm_id` | No | Configuration value |
+
+**Note:** Proxmox credentials are passed via environment variables, not variables file:
+- `PM_API_TOKEN_ID`
+- `PM_API_TOKEN_SECRET`
+
+---
+
+## Variable Validation
+
+```hcl
+variable "build_id" {
+  description = "Unique identifier for the build"
+  type        = string
+  
+  validation {
+    condition     = can(regex("^[a-zA-Z0-9-_]+$", var.build_id))
+    error_message = "build_id must contain only alphanumeric characters, hyphens, and underscores."
+  }
+}
+
+variable "template_vm_id" {
+  description = "VM ID of the Packer-built template"
+  type        = number
+  
+  validation {
+    condition     = var.template_vm_id >= 100 && var.template_vm_id <= 999999
+    error_message = "template_vm_id must be a valid VM ID (100-999999)."
+  }
+}
+```
+
+---
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| ✅ Use descriptive names | `build_id` vs `id` |
+| ✅ Set defaults | Provide safe defaults where possible |
+| ✅ Add validation | Prevent invalid configurations |
+| ✅ Document all variables | Clear description for each |
+| ✅ Use type constraints | Enforce correct data types |
+
+---
+
+## Next Steps
+
+| Goal | Next Document |
+|------|---------------|
+| View main.tf | [OpenTofu Resources](main.tf.md) |
+| Run provisioning | Apply Terraform configuration |
+| View Ansible | [Ansible Pipeline](../05-ansible/pipeline.md) |
+
+---
+
+[← Documentation Index](../index.md) | [← OpenTofu Resources](main.tf.md) | [→ Ansible Pipeline](../05-ansible/pipeline.md)