Sanitized mirror from private repository - 2026-04-20 01:24:42 UTC

docs/advanced/terraform.md

@@ -0,0 +1,59 @@
+# 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.