Instruction file imported from aghyara/GitHubCopilot_Customized (.github/instructions/terraform.instructions.md). Copyright stays with the author.

Terraform Standards

Core Principles

• Keep infrastructure declarative, reproducible, and environment-agnostic
• Prefer small, composable modules over one large root configuration
• Do not hardcode secrets, tokens, or connection strings
• Use remote state with locking for collaborative workflows

File Layout

• Keep root modules focused on orchestration
• Use a predictable structure:

# Example
# modules/
#   network/
#   app_service/
# envs/
#   dev/
#   prod/

• Split files by concern when configurations grow:
  • providers.tf
  • versions.tf
  • variables.tf
  • main.tf
  • outputs.tf

Versioning

• Pin Terraform and provider versions with explicit constraints
• Use pessimistic constraints for providers unless stricter pinning is required

terraform {
  required_version = ">= 1.8.0, < 2.0.0"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

Variables and Outputs

• Declare types for all variables
• Provide descriptions for variables and outputs
• Avoid complex variable objects unless they improve maintainability
• Mark sensitive values as sensitive = true

variable "resource_group_name" {
  type        = string
  description = "Resource group name for shared resources"
}

variable "admin_password" {
  type        = string
  description = "Administrator password"
  sensitive   = true
}

Naming and Tags

• Use consistent snake_case for Terraform identifiers
• Follow a deterministic naming strategy for cloud resources
• Apply required tags/labels to all supported resources
• Centralize common tags in locals

locals {
  common_tags = {
    environment = var.environment
    managed_by  = "terraform"
    project     = var.project_name
  }
}

Security

• Never store secrets in .tf, .tfvars, or state comments
• Use secret managers and data sources for sensitive runtime values
• Enable encryption at rest and in transit where applicable
• Restrict public network exposure unless explicitly required
• Apply least privilege for identities and IAM/RBAC assignments

State Management

• Use remote state backends for shared environments
• Enable state locking (for example, blob lease/DynamoDB lock)
• Keep one state per environment/workload boundary
• Never manually edit state files unless performing controlled recovery

Modules

• Keep module interfaces small and explicit
• Expose only necessary outputs
• Avoid business logic in module naming or structure
• Prefer module version pinning when using external registries

Quality Gates

• Run terraform fmt -check before committing
• Run terraform validate for syntax and schema checks
• Run terraform plan and review changes before apply
• Use static analysis/security scanning (for example tflint, tfsec, or checkov) in CI

PR Review Checklist

• Version constraints are explicit and appropriate
• Variables and outputs are typed and documented
• Sensitive values are not hardcoded or exposed
• Required tags/labels are applied
• Plan output is reviewed for destructive changes
• New resources follow naming conventions