windows-iac-vm-tooling/docs/04-terraform/variables.md

# 📊 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)