# Terraform Implementation Guide

This guide gives a quick template for provisioning the same infrastructure that’s managed by the homelab repository, but using Terraform as the IaC tool.

> ⚠️ **NOTE**: These are *example* configurations. In production, ensure you manage secrets with Vault or an equivalent system.

## 1. Prerequisites

- Terraform >= 1.5
- `terraform-provider-external` for custom scripts
- `oci` or `proxmox-ve` provider for hypervisor configuration

## 2. Terragrunt Directory Layout

```text
infra/
├── terragrunt.hcl          # Root provider config
├── nodes/
│   ├── atlas/terragrunt.hcl   # Synology Atlas
│   ├── concord/terragrunt.hcl # Intel NUC
│   └── pi5/terragrunt.hcl    # Raspberry Pi 5
└── services/
    ├── nginx/terragrunt.hcl
    ├── prometheus/terragrunt.hcl
    └── ...
```

## 3. Example Module: Synology NAS

```hcl
# modules/synology-nas/main.tf
resource "garden_nas" "atlas" {
  hostname = "atlantis.vish.local"
  username = var.special_user
  password = "REDACTED_PASSWORD"
  tags     = ["primary", "nas"]
}
```

## 4. Deployment Steps

```bash
# Install terragrunt
curl -L https://github.com/gruntwork-io/terragrunt/releases/download/v0.50.0/terragrunt_linux_amd64 -o /usr/local/bin/terragrunt && chmod +x /usr/local/bin/terragrunt

# Bootstrap provider
terraform init

# Apply infra plan
terragrunt run-all apply
```

## 5. Maintaining State

Use a remote backend such as Vault, Consul or an S3 bucket to avoid state drift.

---

For reference: the homelab repo uses **git‑ops**. The Terraform guide is a *parallel* fabric.  Keep both in sync via CI tags.