plan-forge terraform.instructions.md

Terraform on Azure Best Practices

File Structure

infra/
├── main.tf               ← resource definitions
├── variables.tf          ← input variable declarations
├── outputs.tf            ← output value declarations
├── providers.tf          ← provider configuration
├── versions.tf           ← required_providers with version locks
├── locals.tf             ← computed/derived values
├── terraform.tfvars      ← variable values (dev — never commit prod secrets)
└── modules/
    ├── networking/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    └── compute/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

Provider Configuration

# versions.tf — always lock provider versions
terraform {
  required_version = ">= 1.7.0"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"   # pin to minor; review major bumps
    }
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"   # for preview/new resources not in azurerm
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }

  # ✅ Remote state in Azure Blob Storage — never local state in CI
  backend "azurerm" {
    resource_group_name  = "rg-tfstate-prod"
    storage_account_name = "sttfstateprod"
    container_name       = "tfstate"
    key                  = "myapp.prod.tfstate"
  }
}

# providers.tf — use Managed Identity (no client_secret in code)
provider "azurerm" {
  features {}
  use_oidc = true   # workload identity federation in CI
}

Variable Declarations

# variables.tf
variable "environment_name" {
  description = "The environment name (dev, test, staging, prod)."
  type        = string
  validation {
    condition     = contains(["dev", "test", "staging", "prod"], var.environment_name)
    error_message = "environment_name must be one of: dev, test, staging, prod."
  }
}

variable "workload_name" {
  description = "Short workload name used in resource naming (2-8 chars)."
  type        = string
  validation {
    condition     = length(var.workload_name) >= 2 && length(var.workload_name) <= 8
    error_message = "workload_name must be between 2 and 8 characters."
  }
}

# ✅ sensitive = true on all secret variables
variable "db_admin_password" {
  description = "Admin password for the database."
  type        = string
  sensitive   = true
}