Advanced

package main
 
import (
 "github.com/hashicorp/terraform-plugin-sdk/v2/plugin"
 "github.com/example/terraform-provider-example/provider"
)
 
func main() {
 plugin.Serve(&plugin.ServeOpts{
 ProviderFunc: provider.New, // => Provider factory function
 // => Configure ProviderFunc: provider.New, //
 })
 // => Provider served as gRPC plugin
}
 
 

package provider
 
import (
 "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
 // => schema package provides Terraform resource schema types
)
 
func New() *schema.Provider {
 // => New() returns provider instance with schema and configuration
 return &schema.Provider{
 // => Schema defines provider configuration arguments
 Schema: map[string]*schema.Schema{
 "api_url": {
 // => api_url argument configuration
 Type: schema.TypeString, // => Expects string value
 // => Configure Type: schema.TypeString, //
 Required: true, // => Must be provided
 // => Configure Required: true, //
 DefaultFunc: schema.EnvDefaultFunc("EXAMPLE_API_URL", nil),
 // => Reads from EXAMPLE_API_URL env var if not set in config
 Description: "API URL for provider", // => Shown in docs
 // => Configure Description: "API URL for provider", //
 },
 "api_key": {
 // => api_key argument for authentication
 Type: schema.TypeString, // => Expects string value
 // => Configure Type: schema.TypeString, //
 Required: true, // => Must be provided
 // => Configure Required: true, //
 Sensitive: true, // => Hidden in logs and plan output
 // => Configure Sensitive: true, //
 DefaultFunc: schema.EnvDefaultFunc("EXAMPLE_API_KEY", nil),
 // => Reads from EXAMPLE_API_KEY env var if not set
 Description: "API key for authentication",// => Documentation string
 // => Configure Description: "API key for authentication",//
 },
 },
 
 ResourcesMap: map[string]*schema.Resource{
 // => ResourcesMap registers available resource types
 "example_server": resourceServer(), // => Register example_server resource
 // => Users can now use resource "example_server" "name" { .. }
 },
 
 DataSourcesMap: map[string]*schema.Resource{
 // => DataSourcesMap registers available data sources
 "example_info": dataSourceInfo(), // => Register example_info data source
 // => Users can now use data "example_info" "name" { .. }
 },
 
 ConfigureContextFunc: configureProvider, // => Provider initialization function
 // => Called once at provider startup to create API client
 }
}
 
func configureProvider(ctx context.Context, d *schema.ResourceData) (interface{}, diag.Diagnostics) {
 // => configureProvider initializes API client with provider config
 // => d contains provider arguments (api_url, api_key)
 apiURL := d.Get("api_url").(string) // => Read api_url from config
 // => Type assertion to string (Terraform stores as interface{})
 apiKey := d.Get("api_key").(string) // => Read api_key from config
 // => Both values guaranteed present due to Required: true
 
 // Initialize API client
 client := NewAPIClient(apiURL, apiKey) // => Create API client
 // => client used by all resource CRUD operations
 // => Returned as meta interface{} to resource functions
 
 return client, nil // => Return client, no errors
 // => nil diag.Diagnostics means success
}
 
 

package provider
 
import (
 "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
 // => schema package provides resource schema and CRUD function types
)
 
func resourceServer() *schema.Resource {
 // => resourceServer defines example_server resource schema and operations
 return &schema.Resource{
 // => CRUD function mapping (Terraform calls these during lifecycle)
 CreateContext: resourceServerCreate, // => Called on resource creation
 // => Configure CreateContext: resourceServerCreate, //
 ReadContext: resourceServerRead, // => Called on refresh/plan/apply
 // => Configure ReadContext: resourceServerRead, //
 UpdateContext: resourceServerUpdate, // => Called when attributes change
 // => Configure UpdateContext: resourceServerUpdate, //
 DeleteContext: resourceServerDelete, // => Called on resource destruction
 // => Configure DeleteContext: resourceServerDelete, //
 
 // => Schema defines resource arguments and attributes
 Schema: map[string]*schema.Schema{
 "name": {
 // => name attribute (user-provided)
 Type: schema.TypeString, // => Expects string value
 // => Configure Type: schema.TypeString, //
 Required: true, // => Must be provided in config
 // => Configure Required: true, //
 Description: "Server name", // => Documentation
 // => Configure Description: "Server name", //
 },
 "instance_type": {
 // => instance_type attribute (user-provided)
 Type: schema.TypeString, // => Expects string value
 // => Configure Type: schema.TypeString, //
 Required: true, // => Must be provided in config
 // => Configure Required: true, //
 Description: "Instance type", // => Documentation
 // => Configure Description: "Instance type", //
 },
 "status": {
 // => status attribute (API-provided)
 Type: schema.TypeString, // => Expects string value
 // => Configure Type: schema.TypeString, //
 Computed: true, // => Set by provider, not user
 // => Configure Computed: true, //
 Description: "Server status", // => Documentation
 // => Computed values come from API responses
 },
 },
 }
}
 
// CRUD operations
func resourceServerCreate(ctx context.Context, d *schema.ResourceData, meta interface{}) diag.Diagnostics {
 // => resourceServerCreate handles resource creation
 // => d contains resource config (name, instance_type)
 // => meta contains API client from configureProvider
 client := meta.(*APIClient) // => Type assert to APIClient
 // => client has CreateServer, GetServer, UpdateServer, DeleteServer methods
 
 name := d.Get("name").(string) // => Read name from config
 // => d.Get() returns interface{}, type assert to string
 instanceType := d.Get("instance_type").(string) // => Read instance_type from config
 // => Both guaranteed present due to Required: true
 
 // Call external API to create resource
 server, err := client.CreateServer(name, instanceType)
 // => POST /servers with {"name": "..", "instance_type": ".."}
 // => Returns server object with ID and status
 if err != nil {
 return diag.FromErr(err) // => Return error as diagnostic
 // => Terraform shows error, doesn't create state entry
 }
 
 // Set resource ID (required)
 d.SetId(server.ID) // => Set resource ID in state
 // => ID identifies resource for future operations (read, update, delete)
 // => Example: d.SetId("srv-abc123")
 
 // Set computed attributes
 d.Set("status", server.Status) // => Set status in state
 // => Example: server.Status might be "creating" or "running"
 // => Terraform tracks this in state file
 
 return nil // => Success, no diagnostics
 // => Resource created, state saved with ID and attributes
}
 
func resourceServerRead(ctx context.Context, d *schema.ResourceData, meta interface{}) diag.Diagnostics {
 // => resourceServerRead fetches current resource state from API
 // => Called during refresh, plan, and apply to sync state
 client := meta.(*APIClient) // => Type assert to APIClient
 // => Configure client :
 
 server, err := client.GetServer(d.Id()) // => GET /servers/{id}
 // => d.Id() returns resource ID from state (set in Create)
 if err != nil {
 if isNotFound(err) {
 d.SetId("") // => Resource deleted externally (drift detected)
 // => Empty ID signals Terraform to remove from state
 // => Next plan will show resource needs recreation
 return nil // => Not an error, resource just doesn't exist
 // => Configure return nil //
 }
 return diag.FromErr(err) // => API error (network, auth, etc.)
 // => Configure return diag.FromErr(err) //
 }
 
 // Update state with API values
 d.Set("name", server.Name) // => Sync name from API
 // => Configure d.Set("name", server.Name) //
 d.Set("instance_type", server.InstanceType) // => Sync instance_type from API
 // => Configure d.Set("instance_type", server.InstanceType) //
 d.Set("status", server.Status) // => Sync status from API
 // => If API values differ from state, Terraform detects drift
 // => Example: Manual console changes show in plan
 
 return nil // => Success, state updated
 // => Configure return nil //
}
 
func resourceServerUpdate(ctx context.Context, d *schema.ResourceData, meta interface{}) diag.Diagnostics {
 // => resourceServerUpdate handles in-place resource updates
 // => Only called when attributes change (not all changes supported)
 client := meta.(*APIClient) // => Type assert to APIClient
 // => Configure client :
 
 if d.HasChange("instance_type") { // => Check if instance_type changed
 // => d.HasChange() compares config to state
 newType := d.Get("instance_type").(string) // => Read new value from config
 // => Example: changing "small" to "large"
 err := client.UpdateServer(d.Id(), newType)
 // => PATCH /servers/{id} with {"instance_type": "large"}
 // => API performs in-place update
 if err != nil {
 return diag.FromErr(err) // => Update failed
 // => Terraform shows error, state unchanged
 }
 }
 // => name changes would require ForceNew: true (recreate resource)
 
 return resourceServerRead(ctx, d, meta) // => Refresh state after update
 // => Ensures state matches updated resource
}
 
func resourceServerDelete(ctx context.Context, d *schema.ResourceData, meta interface{}) diag.Diagnostics {
 // => resourceServerDelete handles resource destruction
 // => Called during terraform destroy or resource removal
 client := meta.(*APIClient) // => Type assert to APIClient
 // => Configure client :
 
 err := client.DeleteServer(d.Id()) // => DELETE /servers/{id}
 // => API destroys resource
 if err != nil {
 return diag.FromErr(err) // => Delete failed
 // => Terraform keeps resource in state, can retry
 }
 // => No need to d.SetId("") - Terraform removes from state automatically
 
 return nil // => Success, resource destroyed
 // => Terraform removes resource from state file
}
 
 

terraform {
 required_providers {
 example = { # => Map/object definition
 source = "example.com/custom/example" # => Custom provider source
 # => Format: hostname/namespace/name
 # => For private registry or local development
 version = "~> 1.0" # => Accept 1.x versions
 # => ~> 1.0 allows 1.0.0, 1.1.0, but not 2.0.0
 }
 }
}
 
provider "example" {
 # => Provider configuration block
 # => Calls configureProvider() with these arguments
 api_url = "https://api.example.com" # => Sets api_url argument
 # => Could use env var: EXAMPLE_API_URL instead
 api_key = var.api_key # => Sets api_key from variable
 # => Marked sensitive in provider schema, hidden in logs
 # => Calls configureProvider() which returns API client
 # => Client used by all resource operations
}
 
resource "example_server" "web" {
 # => Creates example_server resource named "web"
 # => Calls resourceServerCreate() during apply
 name = "web-server" # => Sets name argument
 # => Passed to CreateServer API call
 instance_type = "large" # => Sets instance_type argument
 # => Determines server capacity/pricing
 # => terraform plan shows: +example_server.web will be created
 # => terraform apply calls client.CreateServer("web-server", "large")
 # => State stores: ID, name, instance_type, status
}
 
output "server_status" {
 # => Exposes computed status attribute
 value = example_server.web.status # => Read from state
 # => status is Computed: true, set by API in Create/Read
 # => Example output: server_status = "running"
 # => Shown after terraform apply completes
}

// provider/data_source_info.go
package provider
 
import (
 "context"
 "github.com/hashicorp/terraform-plugin-sdk/v2/diag"
 "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
 // => schema package provides data source schema types
)
 
func dataSourceInfo() *schema.Resource {
 // => dataSourceInfo defines example_info data source schema
 // => Data sources query existing resources without managing them
 return &schema.Resource{
 ReadContext: dataSourceInfoRead,
 // => Data sources only have Read operation (no Create/Update/Delete)
 // => Called during terraform plan to fetch latest data
 // => Re-runs every plan to ensure fresh data
 
 Schema: map[string]*schema.Schema{
 // => Schema defines data source arguments and attributes
 "region": {
 // => region argument (user-provided input)
 Type: schema.TypeString, // => Expects string value
 // => Configure Type: schema.TypeString, //
 Required: true, // => Must be provided
 // => Configure Required: true, //
 Description: "Region to query", // => Documentation
 // => User specifies which region to query
 },
 // => Input parameter - users provide this in config
 
 "endpoint": {
 // => endpoint attribute (provider-computed output)
 Type: schema.TypeString, // => Returns string value
 // => Configure Type: schema.TypeString, //
 Computed: true, // => Set by provider, not user
 // => Configure Computed: true, //
 Description: "API endpoint for region", // => Documentation
 // => Computed: true means read-only, provider sets value
 },
 // => Computed: output only (provider calculates value from API)
 
 "availability_zones": {
 // => availability_zones attribute (list output)
 Type: schema.TypeList, // => Returns list of values
 // => Configure Type: schema.TypeList, //
 Computed: true, // => Provider-computed
 // => Configure Computed: true, //
 Elem: &schema.Schema{Type: schema.TypeString},
 // => Elem defines list element type (strings)
 Description: "List of availability zones",// => Documentation
 // => Example: ["us-west-2a", "us-west-2b", "us-west-2c"]
 },
 // => TypeList with string elements - array of availability zones
 
 "metadata": {
 // => metadata attribute (map output)
 Type: schema.TypeMap, // => Returns key-value map
 // => Configure Type: schema.TypeMap, //
 Computed: true, // => Provider-computed
 // => Configure Computed: true, //
 Elem: &schema.Schema{Type: schema.TypeString},
 // => Elem defines map value type (string values)
 Description: "Region metadata", // => Documentation
 // => Example: {"tier": "standard", "compliance": "hipaa"}
 },
 // => TypeMap for key-value pairs - flexible metadata storage
 },
 }
}
 
func dataSourceInfoRead(ctx context.Context, d *schema.ResourceData, meta interface{}) diag.Diagnostics {
 // => dataSourceInfoRead fetches region information from API
 // => Called during terraform plan, runs every plan (not cached in state)
 // => d contains data source config (region argument)
 client := meta.(*APIClient) // => Type assert to APIClient
 // => client from provider configuration
 region := d.Get("region").(string) // => Read region from config
 // => Example: region = "us-west-2"
 // => Get input parameter from user configuration
 
 // Query external API
 info, err := client.GetRegionInfo(region) // => GET /regions/us-west-2
 // => Fetches endpoint, availability zones, metadata from API
 // => Returns RegionInfo struct with all computed values
 if err != nil {
 return diag.FromErr(err) // => API error (not found, auth, etc.)
 // => Terraform shows error, plan fails
 }
 // => info contains: Endpoint, AvailabilityZones, Metadata
 
 // Set computed values
 d.SetId(region) // => Set data source ID
 // => Data sources need ID for state tracking
 // => Use region as unique identifier
 // => Example: ID = "us-west-2"
 d.Set("endpoint", info.Endpoint) // => Set computed endpoint
 // => Set computed string value from API response
 // => Example: endpoint = "https://api.us-west-2.example.com"
 d.Set("availability_zones", info.AvailabilityZones)
 // => Set computed list value from API response
 // => Example: ["us-west-2a", "us-west-2b", "us-west-2c"]
 d.Set("metadata", info.Metadata) // => Set computed map
 // => Set map value from API response
 // => Example: {"tier": "standard", "compliance": "hipaa"}
 
 return nil // => Success, values set
 // => Data available for use in configuration
}
 

terraform {
 # => Terraform configuration block
 required_providers {
 # => Provider requirements
 example = { # => Map/object definition
 # => example provider configuration
 source = "example.com/custom/example" # => Custom provider source
 # => Matches provider registration from Example 57
 # => Format: hostname/namespace/name
 }
 }
}
 
provider "example" {
 # => Provider configuration (calls configureProvider)
 api_url = "https://api.example.com" # => API base URL
 api_key = var.api_key # => Authentication key
 # => Initializes API client for data source queries
}
 
# Query region information via data source
data "example_info" "us_west" {
 # => Declares data source of type example_info named "us_west"
 # => Calls dataSourceInfoRead during terraform plan
 region = "us-west-2" # => Input parameter (Required: true)
 # => Passed to client.GetRegionInfo("us-west-2")
 # => Data source executes on EVERY plan (not cached)
 # => Returns: endpoint, availability_zones, metadata
}
# => terraform plan queries API and displays computed values
# => Example output:
# => endpoint = "https://api.us-west-2.example.com"
# => availability_zones = ["us-west-2a", "us-west-2b", "us-west-2c"]
# => metadata = {"tier": "standard", "compliance": "hipaa"}
 
# Use data source outputs in resources
resource "local_file" "config" {
 # => Create configuration file from data source outputs
 filename = "region-config.txt" # => Output file path
 content = <<-EOT
 Endpoint: ${data.example_info.us_west.endpoint}
 AZs: ${jsonencode(data.example_info.us_west.availability_zones)}
 Metadata: ${jsonencode(data.example_info.us_west.metadata)}
 EOT
 # => data.example_info.us_west.* accesses computed values
 # => References: data.TYPE.NAME.ATTRIBUTE
 # => jsonencode converts list/map to JSON string
 # => Creates dependency: resource waits for data source query
}
# => terraform apply creates file:
# => Endpoint: https://api.us-west-2.example.com
# => AZs: ["us-west-2a","us-west-2b","us-west-2c"]
# => Metadata: {"compliance":"hipaa","tier":"standard"}
 
output "region_endpoint" {
 # => Expose endpoint for use by other configurations
 value = data.example_info.us_west.endpoint # => Read from data source
 # => Example: region_endpoint = "https://api.us-west-2.example.com"
 # => Shown after terraform apply completes
}

// provider/resource_server_test.go
package provider
// => Test package for provider acceptance tests
 
import (
 "testing" // => Go testing framework
 "github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource"
 // => resource package provides acceptance test framework
)
 
func TestAccResourceServer_basic(t *testing.T) {
 // => TestAccResourceServer_basic tests full resource lifecycle
 // => Function name pattern: TestAcc* for acceptance tests
 // => Requires TF_ACC=1 environment variable to run
 resource.Test(t, resource.TestCase{
 // => resource.Test runs acceptance test suite
 // => Manages test lifecycle: apply, verify, destroy
 PreCheck: func() { testAccPreCheck(t) },
 // => PreCheck validates environment (API keys, endpoints) before test
 // => Runs once before all test steps
 // => Fails fast if environment not ready
 Providers: testAccProviders,
 // => Providers is map of providers to test
 // => testAccProviders defined in provider_test.go setup
 // => Maps provider name to provider instance
 CheckDestroy: testAccCheckServerDestroy,
 // => CheckDestroy verifies resources cleaned up after test
 // => Runs after all steps complete
 // => Ensures no orphaned resources remain
 
 Steps: []resource.TestStep{
 // => Steps is sequence of configurations to apply
 // => Each step: apply config → run checks → proceed
 // => Tests full lifecycle: create → update → import
 {
 // => Step 1: Create resource with basic configuration
 Config: testAccResourceServerConfig_basic(),
 // => Step 1: Apply basic configuration
 // => Calls terraform apply with HCL from testAccResourceServerConfig_basic
 // => Creates example_server.test resource
 Check: resource.ComposeTestCheckFunc(
 // => ComposeTestCheckFunc runs multiple checks sequentially
 // => If any check fails, test fails immediately
 testAccCheckServerExists("example_server.test"),
 // => Verify resource was created
 // => Custom check: queries API to confirm resource exists
 // => Validates Terraform state matches reality
 resource.TestCheckResourceAttr("example_server.test", "name", "test-server"),
 // => Verify name attribute
 // => Checks state: example_server.test.name == "test-server"
 // => Validates Create operation set correct value
 resource.TestCheckResourceAttr("example_server.test", "instance_type", "small"),
 // => Verify instance_type attribute
 // => Checks state: example_server.test.instance_type == "small"
 // => Confirms config value persisted to state
 resource.TestCheckResourceAttrSet("example_server.test", "status"),
 // => Verify status is set (don't check exact value)
 // => Validates computed attribute exists
 // => Doesn't validate exact value (API-dependent)
 ),
 },
 {
 // => Step 2: Update resource to test Update operation
 Config: testAccResourceServerConfig_updated(),
 // => Step 2: Apply updated configuration
 // => Calls terraform apply with instance_type changed to "large"
 // => Tests in-place update (not recreate)
 Check: resource.ComposeTestCheckFunc(
 resource.TestCheckResourceAttr("example_server.test", "instance_type", "large"),
 // => Verify update worked
 // => Confirms instance_type changed from "small" to "large"
 // => Validates Update operation worked
 ),
 },
 {
 // => Step 3: Test import functionality
 ResourceName: "example_server.test",
 // => Name of resource to import
 // => Must match resource from previous steps
 ImportState: true,
 // => Enable import test
 // => Runs terraform import for this resource
 ImportStateVerify: true,
 // => Step 3: Test import (verify exported state matches)
 // => Validates imported state matches expected state
 // => Ensures import implementation correct
 },
 },
 })
}
 
func testAccResourceServerConfig_basic() string {
 // => testAccResourceServerConfig_basic returns HCL for initial resource
 return `
resource "example_server" "test" {
 # => Defines example_server.test resource
 name = "test-server"
 instance_type = "small"
}
`
 // => HCL configuration for test
 // => Creates small instance for testing
 // => Used in Step 1
}
 
func testAccResourceServerConfig_updated() string {
 // => testAccResourceServerConfig_updated returns HCL for update test
 return `
resource "example_server" "test" {
 # => Defines example_server.test resource
 name = "test-server"
 instance_type = "large"
}
`
 // => Updated configuration (tests Update operation)
 // => Changes instance_type: "small" → "large"
 // => Used in Step 2 to test in-place updates
}
 
func testAccCheckServerExists(resourceName string) resource.TestCheckFunc {
 // => testAccCheckServerExists verifies resource exists in external system
 // => Returns TestCheckFunc that queries API
 // => resourceName: "example_server.test"
 return func(s *terraform.State) error {
 // => Returned function receives Terraform state
 // => s contains all resources from apply
 rs, ok := s.RootModule().Resources[resourceName]
 // => rs is resource state for example_server.test
 // => ok is false if resource not in state
 if !ok {
 return fmt.Errorf("Resource not found: %s", resourceName)
 // => Test fails: resource missing from state
 }
 
 client := testAccProvider.Meta().(*APIClient)
 // => Get API client from provider metadata
 // => client used to query external API
 _, err := client.GetServer(rs.Primary.ID)
 // => Query API with resource ID from state
 // => rs.Primary.ID is the d.SetId value from Create
 return err
 // => Verify resource exists in external system
 // => err != nil means resource not found (test fails)
 // => err == nil means resource exists (test passes)
 }
}
 
func testAccCheckServerDestroy(s *terraform.State) error {
 // => testAccCheckServerDestroy runs after all test steps complete
 // => Verifies all resources were destroyed
 // => s contains final state before cleanup
 client := testAccProvider.Meta().(*APIClient)
 // => Get API client to query external system
 
 for _, rs := range s.RootModule().Resources {
 // => Iterate all resources in state
 // => rs is each resource entry
 if rs.Type != "example_server" {
 continue
 // => Skip non-example_server resources
 // => Only validate our resource type
 }
 
 _, err := client.GetServer(rs.Primary.ID)
 // => Query API: does resource still exist?
 // => rs.Primary.ID is resource ID
 if err == nil {
 return fmt.Errorf("Server still exists: %s", rs.Primary.ID)
 // => Test fails: resource not destroyed
 // => Indicates CheckDestroy failed (orphaned resource)
 }
 // => Verify resource was destroyed
 // => err != nil means resource deleted (good)
 }
 
 return nil
 // => All resources destroyed successfully
 // => Test cleanup validated
}

# $ TF_ACC=1 go test -v ./provider/
# => TF_ACC=1 enables acceptance tests (creates real resources)
# => -v verbose output
# => Runs all Test* functions in provider/ directory
 
# Output:
# === RUN TestAccResourceServer_basic
# --- PASS: TestAccResourceServer_basic (15.32s)
# PASS

terraform {
# => Terraform configuration block
 required_version = ">= 1.0" # => String value
 # => Sets required_version
}
 
provider "local" {}
# => Provider configuration
 
# Intentional errors for validation demonstration
resource "local_file" "example" {
# => Resource definition
 filename = "test.txt" # => String value
 # => Sets filename
 content = "Test content" # => String value
 # => Sets content
}
 
# Missing required argument (will fail validation)
resource "local_file" "invalid" {
# => Resource definition
 filename = "invalid.txt" # => String value
 # content missing (required argument)
}
 
 
 
 
 

# Format check (shows formatting issues)
# $ terraform fmt -check
# => example.tf (formatting issues detected)
# => Exit code: 3 (some files need formatting)
 
# Format automatically
# $ terraform fmt
# => example.tf (formatted)
# => Fixes indentation, spacing, alignment
 
# Recursive format all .tf files
# $ terraform fmt -recursive
# => Formats all Terraform files in directory tree
 
# Validate configuration
# $ terraform validate
# => Error: Missing required argument
# => on example.tf line 10:
# => resource "local_file" "invalid" {
# => The argument "content" is required, but no definition was found.
 
# After fixing:
# $ terraform validate
# => Success! The configuration is valid.
 
# Validate with JSON output (for CI/CD)
# $ terraform validate -json
# => {"valid":false,"error_count":1,"errors":[..]}
 
 

#!/bin/bash
# .git/hooks/pre-commit
 
terraform fmt -check -recursive
# => Terraform configuration
if [ $? -ne 0 ]; then
# => Terraform configuration
 echo "Terraform files need formatting. Run: terraform fmt -recursive"
 # => Terraform configuration
 exit 1
 # => Terraform configuration
fi
# => Terraform configuration
 
terraform validate
# => Terraform configuration
if [ $? -ne 0 ]; then
# => Terraform configuration
 echo "Terraform validation failed"
 # => Terraform configuration
 exit 1
 # => Terraform configuration
fi
# => Terraform configuration
 
echo "Terraform validation passed"
# => Terraform configuration
 
 
 
 

config {
 # => TFLint global configuration
 module = true # => Boolean value
 # => Enable linting of module calls
 # => Validates modules called from root configuration
}
 
plugin "terraform" {
 # => Core Terraform plugin for basic linting
 enabled = true # => Boolean value
 # => Core Terraform linting rules
 # => Activates terraform-specific rule checks
 preset = "recommended" # => String value
 # => Use recommended rule set (opinionated defaults)
}
 
plugin "aws" {
 # => AWS provider plugin for cloud-specific rules
 enabled = true # => Boolean value
 # => Activate AWS linting rules
 version = "0.27.0" # => String value
 # => Plugin version to use
 source = "github.com/terraform-linters/tflint-ruleset-aws" # => String value
 # => AWS-specific rules (instance types, regions, deprecated resources)
 # => GitHub repository for AWS ruleset
}
 
rule "terraform_unused_declarations" {
 # => Rule for detecting unused declarations
 enabled = true # => Boolean value
 # => Detect unused variables, outputs, locals
 # => Helps clean up configuration clutter
}
 
rule "terraform_deprecated_syntax" {
 # => Rule for deprecated HCL syntax
 enabled = true # => Boolean value
 # => Warn about deprecated HCL syntax
 # => Catches old patterns that should be updated
}
 
rule "terraform_naming_convention" {
 # => Rule for consistent naming patterns
 enabled = true # => Boolean value
 # => Activate naming convention checks
 format = "snake_case" # => String value
 # => Enforce snake_case naming
 # => Variables, resources, modules must use underscores not camelCase
}

terraform {
 # => Terraform configuration
 required_version = ">= 1.0" # => String value
 # => Minimum version requirement
}
 
provider "local" {}
# => Local provider for file operations
 
variable "unused_var" {
 # => Variable declared but never used
 type = string
 # => String type
 default = "never referenced" # => String value
 # => Default value provided
 # => TFLint warning: unused variable
 # => No resource or output references this
}
 
variable "ProdInstanceType" {
 # => Variable with camelCase naming (violation)
 type = string
 # => String type
 # => TFLint warning: variable should use snake_case
 # => Correct name would be: prod_instance_type
}
 
resource "local_file" "example" {
 # => Local file resource
 filename = "test.txt" # => String value
 # => Output filename
 content = var.ProdInstanceType
 # => References camelCase variable
 # => References variable with naming violation
}
 
# Deprecated syntax
locals {
 # => Local values block
 list_example = "${list("a", "b", "c")}" # => String interpolation
 # => TFLint warning: use ["a", "b", "c"] instead of list() function
 # => list() function deprecated in Terraform 0.12+
 # => Modern syntax: ["a", "b", "c"] (no function needed)
}

# Install TFLint
# $ brew install tflint (macOS)
# $ curl -s https://raw.githubusercontent.com/terraform-linters/tflint/master/install_linux.sh | bash (Linux)
 
# Initialize plugins
# $ tflint --init
# => Downloading plugin "terraform"
# => Downloading plugin "aws"
 
# Run linting
# $ tflint
# => Warning: variable "unused_var" is declared but not used (terraform_unused_declarations)
# => Warning: variable name "ProdInstanceType" should use snake_case (terraform_naming_convention)
# => Warning: Deprecated interpolation syntax (terraform_deprecated_interpolation)
 
# Output formats
# $ tflint --format json
# => JSON output for CI/CD parsing
 
# $ tflint --format compact
# => Compact one-line-per-issue format
 
# Fail on warnings (for CI enforcement)
# $ tflint --minimum-failure-severity=warning
# => Exit code 2 if any warnings found

# .github/workflows/terraform-lint.yml
name: Terraform Lint
on: [pull_request]
 
jobs:
 tflint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - uses: terraform-linters/setup-tflint@v3
 with:
 tflint_version: latest
 
 - name: Init TFLint
 run: tflint --init
 
 - name: Run TFLint
 run: tflint --format compact --minimum-failure-severity=warning
 # => Configure run: tflint --format compact --minimum-failure-severity

module github.com/example/terraform-tests
// => Module declaration: Go module path (used as package import prefix)
 
go 1.21
// => Minimum Go version required for this module
 
require (
 // => require block: external dependencies with pinned versions
 github.com/gruntwork-io/terratest v0.46.0
 // => Terratest: Go library for infrastructure testing
 // => Provides terraform.InitAndApply, terraform.Destroy, terraform.Output
 github.com/stretchr/testify v1.8.4
 // => Testify: assertion library (assert.Equal, assert.NoError)
 // => Standard Go testing assertions
)

terraform {
 # => terraform block configures provider requirements
 required_version = ">= 1.0" # => Ensures compatible Terraform version
 # => Prevents running tests with incompatible older versions
}
 
provider "local" {}
# => Local provider: no credentials required
# => Manages files on local filesystem - perfect for unit-style tests
 
variable "filename" {
 # => Input variable: filename for created file
 type    = string # => Type constraint: string only
 # => Terratest will pass this via Vars map
 default = "test-output.txt" # => Default used if no override provided
 # => Overridden in tests via terraformOptions.Vars
}
 
variable "content" {
 # => Input variable: content for created file
 type = string  # => Required string (no default)
 # => Terratest passes "Hello from Terratest!" via Vars map
}
 
resource "local_file" "test" {
 # => Creates file on local filesystem for testing
 filename = var.filename  # => Uses filename variable
 # => Resolves to "terratest-output.txt" in test
 content  = var.content   # => Uses content variable
 # => Resolves to "Hello from Terratest!" in test
}
 
output "filename" {
 # => Exposes filename so Terratest can read it with terraform.Output
 value = local_file.test.filename
 # => terraform.Output(t, opts, "filename") returns this value
 # => Used in assertions: assert.Equal(t, "terratest-output.txt", outputFilename)
}
 
output "content" {
 # => Exposes content for verification
 value = local_file.test.content
 # => terraform.Output(t, opts, "content") returns this value
}

package test
// => Package declaration: "test" is conventional for Terratest packages
 
import (
 "os"       // => Standard library: os.ReadFile for file content validation
 "testing"  // => Standard library: *testing.T test context
 
 "github.com/gruntwork-io/terratest/modules/terraform" // => Terratest Terraform helper
 "github.com/stretchr/testify/assert"                  // => Assertion library
)
 
func TestTerraformBasicExample(t *testing.T) {
 // => Function name must start with "Test" to be picked up by `go test`
 t.Parallel()
 // => t.Parallel(): allows multiple tests to run concurrently
 // => Critical for speed: 10 parallel tests = 1/10 total time
 
 terraformOptions := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
 // => terraform.WithDefaultRetryableErrors: wraps options with standard retry logic
 // => Retries on transient AWS API errors (throttling, eventual consistency)
 TerraformDir: "./examples/basic",
 // => TerraformDir: path to Terraform configuration to test
 // => Relative to test/ directory where go test runs
 
 Vars: map[string]interface{}{
 // => Vars: passed as -var flags to terraform apply
 "filename": "terratest-output.txt",
 // => Overrides variable "filename" in Terraform config
 "content": "Hello from Terratest!",
 // => Overrides variable "content" in Terraform config
 },
 
 NoColor: true,
 // => NoColor: removes ANSI escape codes from Terraform output
 // => Makes CI/CD log output readable without color rendering
 })
 
 defer terraform.Destroy(t, terraformOptions)
 // => defer: schedules Destroy to run when test function exits
 // => Guarantees cleanup even if test panics or fails mid-execution
 // => Without defer: test failure leaves orphaned resources ($$$)
 
 terraform.InitAndApply(t, terraformOptions)
 // => InitAndApply: runs `terraform init` then `terraform apply -auto-approve`
 // => Blocks until apply completes or fails (fails the test on error)
 // => After this line: real file exists on disk
 
 // Validate outputs match expected values
 outputFilename := terraform.Output(t, terraformOptions, "filename")
 // => terraform.Output: reads output value from terraform state
 // => outputFilename = "terratest-output.txt" (from Vars above)
 outputContent := terraform.Output(t, terraformOptions, "content")
 // => outputContent = "Hello from Terratest!" (from Vars above)
 
 assert.Equal(t, "terratest-output.txt", outputFilename)
 // => Fails test if outputFilename != "terratest-output.txt"
 assert.Equal(t, "Hello from Terratest!", outputContent)
 // => Fails test if outputContent != "Hello from Terratest!"
 
 // Validate actual infrastructure state (not just Terraform outputs)
 fileContent, err := os.ReadFile("./examples/basic/terratest-output.txt")
 // => os.ReadFile: reads actual file from disk
 // => This validates infrastructure EXISTS, not just that Terraform tracks it
 assert.NoError(t, err)
 // => Fails test if file doesn't exist or can't be read
 assert.Equal(t, "Hello from Terratest!", string(fileContent))
 // => Converts []byte to string for comparison
 // => Verifies actual file content matches expected
}
 
func TestTerraformIdempotence(t *testing.T) {
 // => Idempotence test: second apply should make zero changes
 terraformOptions := &terraform.Options{
 TerraformDir: "./examples/basic",
 Vars: map[string]interface{}{
 "filename": "idempotence-test.txt",
 "content": "Test",
 },
 }
 
 defer terraform.Destroy(t, terraformOptions)
 // => Cleanup: always run terraform destroy after test
 
 // First apply: create resources
 terraform.InitAndApply(t, terraformOptions)
 // => First apply creates the file
 
 // Second apply should show no changes (infrastructure already matches config)
 planOutput := terraform.Plan(t, terraformOptions)
 // => terraform.Plan: runs terraform plan, returns output as string
 // => Idempotent config: second plan shows no changes
 assert.NotContains(t, planOutput, "will be created")
 // => Fails if second plan wants to create anything (non-idempotent)
 assert.NotContains(t, planOutput, "will be updated")
 // => Fails if second plan wants to update anything (drift)
 assert.NotContains(t, planOutput, "will be destroyed")
 // => Fails if second plan wants to destroy anything (unexpected behavior)
}

# Run all tests
# $ cd test
# $ go test -v -timeout 30m
# => -v: verbose output
# => -timeout: prevent hanging tests (infrastructure provisioning can be slow)
 
# Run specific test
# $ go test -v -run TestTerraformBasicExample
 
# Run tests in parallel
# $ go test -v -parallel 10
# => Runs up to 10 tests concurrently

import "tfplan/v2" as tfplan
# => tfplan/v2 provides access to Terraform plan data
 
# Find all resources
all_resources = filter tfplan.resource_changes as _, rc {
 # => filter expression iterates resource_changes
 rc.mode is "managed"
 # => "managed" = regular resources; excludes data sources
}
# => Filters to managed resources (not data sources)
 
# Check for required tags
required_tags = ["Environment", "Owner", "CostCenter"]
# => List of tag keys that must be present on every resource
 
# Validation function
mandatory_tags = rule {
 # => rule block defines a named policy rule (returns bool)
 all all_resources as _, resource {
 # => all quantifier: every resource must pass
 all required_tags as tag {
 # => inner all: every tag in required_tags must be present
 resource.change.after.tags contains tag
 # => .change.after = resource state after apply
 }
 }
}
# => Rule: ALL resources must have ALL required tags
 
# Main policy
main = rule {
# => Terraform configuration
 mandatory_tags
 # => Sentinel enforces this rule before allowing apply
}
# => Policy fails if mandatory_tags rule fails
 
 

package terraform.policies
# => package: OPA namespace for policy rules
 
import input as tfplan
# => import input: binds the JSON input document (tfplan.json) to "tfplan"
 
# Deny resources without required tags
deny[msg] {
 # => deny[msg]: partial set rule - adds msg to deny set for each violation
 resource := tfplan.resource_changes[_]
 # => resource_changes[_]: iterates over all resource changes (wildcard index)
 resource.mode == "managed"
 # => Check managed resources only (exclude data sources with mode "data")
 
 required_tags := {"Environment", "Owner", "CostCenter"}
 # => Set literal: the three mandatory tag keys
 existing_tags := {tag | resource.change.after.tags[tag]}
 # => Set comprehension: builds set of all tag keys on this resource
 # => resource.change.after = planned state after apply
 
 missing_tags := required_tags - existing_tags
 # => Set difference: tags required but not present on resource
 count(missing_tags) > 0
 # => count(): number of missing tags; > 0 means violations exist
 
 msg := sprintf(
 # => sprintf: format string with resource address and missing tags
 "Resource %s is missing required tags: %v",
 # => Terraform configuration
 [resource.address, missing_tags]
 # => resource.address: e.g. "local_file.non_compliant"
 )
}
# => deny set contains violation messages; empty set = policy passes
 
 

terraform {
# => Terraform configuration block
 required_version = ">= 1.0" # => String value
 # => Sets required_version
}
 
provider "local" {}
# => Provider configuration
 
# Compliant resource (has all required tags)
resource "local_file" "compliant" {
# => Resource definition
 filename = "compliant.txt" # => String value
 # => Sets filename
 content = "Valid" # => String value
 # => Sets content
 
 # Simulated tags using local_file
 # (real clouds use tags = {..})
}
 
# Non-compliant resource (missing tags)
resource "local_file" "non_compliant" {
# => Resource definition
 filename = "non-compliant.txt" # => String value
 # => Sets filename
 content = "Invalid" # => String value
 # => Missing Environment, Owner, CostCenter tags
}
 
 
 

# Sentinel (Terraform Cloud/Enterprise)
# $ terraform plan
# => Generates plan
# => Sentinel runs automatically in Terraform Cloud
# => Policy Check: require-tags.sentinel
# => Result: FAIL
# => Resource "local_file.non_compliant" missing required tags: ["Environment", "Owner", "CostCenter"]
# => Apply blocked until policy passes
 
# OPA (open source)
# $ terraform plan -out=tfplan.binary
# $ terraform show -json tfplan.binary > tfplan.json
# => Convert plan to JSON
 
# $ opa eval -i tfplan.json -d require_tags.rego "data.terraform.policies.deny"
# => [
# => "Resource local_file.non_compliant is missing required tags: {Environment, Owner, CostCenter}"
# => ]
# => Exit code 1 (policy violation)
 
# Fix violations
# $ terraform apply
# => Error: policy check failed (apply blocked)
 
 

# .github/workflows/terraform-policy.yml
name: Terraform Policy Check
# => Workflow/job name: Terraform Policy Check
on: [pull_request]          # => Runs on every pull request (checks before merge)
 
jobs:
# => Workflow jobs definition
 policy:
 # => policy configuration
 runs-on: ubuntu-latest
 # => GitHub Actions runner type
 steps:
 # => Sequential steps for job
 - uses: actions/checkout@v3  # => Clone repository with Terraform configs
 
 - name: Terraform Plan
 # => Step name: Terraform Plan
 run: |
 # => Shell command to execute
 terraform init              # => Download providers and modules
 terraform plan -out=tfplan.binary
 # => -out=: saves plan as binary file for JSON conversion
 terraform show -json tfplan.binary > tfplan.json
 # => terraform show -json: converts binary plan to JSON
 # => tfplan.json: OPA input document for policy evaluation
 
 - name: Install OPA
 # => Step name: Install OPA
 run: |
 # => Shell command to execute
 curl -L -o opa https://openpolicyagent.org/downloads/latest/opa_linux_amd64
 # => Download OPA binary (open-source policy engine)
 chmod +x opa
 # => Make OPA executable
 
 - name: Run Policy Check
 # => Step name: Run Policy Check
 run: |
 # => Shell command to execute
 ./opa eval -i tfplan.json -d policies/ "data.terraform.policies.deny"
 # => -i: input file (tfplan.json)
 # => -d: policy directory (all .rego files)
 # => "data.terraform.policies.deny": query the deny set
 if [ $? -ne 0 ]; then
 # => $?: exit code from opa eval (non-zero = violations found)
 echo "Policy violations detected!"
 # => Terraform configuration
 exit 1                      # => Fail CI/CD pipeline, block merge
 fi
 # => Terraform configuration
 
 

variable "server_name" {
# => Input variable
 type = string
 # => Variable type constraint
 # => Sets type
 description = "Server name" # => String value
 # => Sets description
 
 validation {
 # => Validation rule enforces constraints
 condition = length( # => Returns collection size
var.server_name) > 0
 # => Sets condition
 error_message = "server_name cannot be empty" # => String value
 # => Sets error_message
 }
}
 
variable "instance_type" {
# => Input variable
 type = string
 # => Variable type constraint
 # => Sets type
 default = "small" # => String value
 # => Sets default
}
 
output "server_id" {
# => Output value
 value = local_file.server.id
 # => Output value
 # => Sets value: contract tests assert this output is non-empty string
}
 
output "server_name" {
# => Output value
 value = var.server_name
 # => Output value
 # => Sets value
}
 
resource "local_file" "server" {
# => Resource definition
 filename = "${var.server_name}-server.txt" # => String interpolation
 # => Sets filename
 content = "Instance type: ${var.instance_type}" # => String value
 # => Sets content
}
 
 
 
 
 

package test
# => Package declaration
// => Contract test package for web-server module
 
import (
# => Import statement
 "testing" // => Go testing framework
 // => Configure testing" //
 "github.com/gruntwork-io/terratest/modules/terraform" // => Terratest Terraform helpers
 // => Configure github.com/gruntwork-io/terratest/modules/terraform" //
 "github.com/stretchr/testify/assert" // => Assertion library
 // => Configure github.com/stretchr/testify/assert" //
)
 
// Contract Test 1: Module accepts valid inputs
func TestModuleAcceptsValidInputs(t *testing.T) {
# => Function declaration
 // => Verify module applies successfully with valid inputs
 // => Contract: module must accept documented input combinations
 terraformOptions := &terraform.Options{
 // => Terraform configuration for test
 TerraformDir: "./modules/web-server",
 // => Path to module under test
 Vars: map[string]interface{}{
 // => Input variables (valid values)
 "server_name": "web-01",
 // => Valid server_name (non-empty string)
 "instance_type": "large",
 // => Valid instance_type (overrides default)
 },
 }
 
 defer terraform.Destroy(t, terraformOptions)
 # => Deferred cleanup (runs when function exits)
 // => Cleanup: destroy resources after test completes
 terraform.InitAndApply(t, terraformOptions)
 // => terraform init && terraform apply -auto-approve
 // => Test passes if apply succeeds
 // => Contract: module accepts valid inputs without error
 // => No assertions needed (failure = exception)
}
 
// Contract Test 2: Module rejects invalid inputs
func TestModuleRejectsInvalidInputs(t *testing.T) {
# => Function declaration
 // => Verify module validation catches invalid inputs
 // => Contract: module must reject invalid inputs with clear errors
 terraformOptions := &terraform.Options{
 # => Short variable declaration: terraformOptions
 TerraformDir: "./modules/web-server",
 # => Terraform configuration
 Vars: map[string]interface{}{
 # => Terraform configuration
 "server_name": "", // Empty (invalid)
 // => Invalid input: empty string (validation should fail)
 },
 }
 
 _, err := terraform.InitAndApplyE(t, terraformOptions)
 // => InitAndApplyE returns error instead of failing test
 // => Allows testing expected failures
 assert.Error(t, err)
 # => Test assertion
 // => Verify apply failed (error is not nil)
 assert.Contains(t, err.Error(), "server_name cannot be empty")
 # => Test assertion
 // => Verify error message matches validation error
 // => Contract: module rejects invalid inputs with clear error
 // => Error message must help user fix issue
}
 
// Contract Test 3: Module produces required outputs
func TestModuleProducesRequiredOutputs(t *testing.T) {
# => Function declaration
 // => Verify module exposes documented outputs
 // => Contract: module must output server_id and server_name
 terraformOptions := &terraform.Options{
 # => Short variable declaration: terraformOptions
 TerraformDir: "./modules/web-server",
 # => Terraform configuration
 Vars: map[string]interface{}{
 # => Terraform configuration
 "server_name": "web-02",
 // => Valid input for test
 },
 }
 
 defer terraform.Destroy(t, terraformOptions)
 # => Deferred cleanup (runs when function exits)
 terraform.InitAndApply(t, terraformOptions)
 // => Apply module configuration
 
 // Verify output exists
 serverID := terraform.Output(t, terraformOptions, "server_id")
 // => Read server_id output from state
 // => terraform output server_id
 serverName := terraform.Output(t, terraformOptions, "server_name")
 // => Read server_name output from state
 
 assert.NotEmpty(t, serverID)
 # => Test assertion
 // => Verify server_id is not empty string
 // => Contract: server_id must have value
 assert.Equal(t, "web-02", serverName)
 # => Test assertion
 // => Verify server_name matches input
 // => Contract: module outputs server_id and server_name
 // => Consumers can depend on these outputs existing
}
 
// Contract Test 4: Module is idempotent
func TestModuleIdempotence(t *testing.T) {
# => Function declaration
 // => Verify second apply produces no changes
 // => Contract: module is idempotent (apply twice = apply once)
 terraformOptions := &terraform.Options{
 # => Short variable declaration: terraformOptions
 TerraformDir: "./modules/web-server",
 # => Terraform configuration
 Vars: map[string]interface{}{
 # => Terraform configuration
 "server_name": "web-03",
 # => Terraform configuration
 },
 }
 
 defer terraform.Destroy(t, terraformOptions)
 # => Deferred cleanup (runs when function exits)
 terraform.InitAndApply(t, terraformOptions)
 // => First apply creates infrastructure
 
 // Second apply
 planOutput := terraform.Plan(t, terraformOptions)
 // => terraform plan (should show no changes)
 // => Returns plan output as string
 assert.Contains(t, planOutput, "No changes")
 # => Test assertion
 // => Verify plan shows "No changes. Your infrastructure matches.."
 // => Contract: module is idempotent (second apply changes nothing)
 // => Prevents resource recreation on every apply
}
 
// Contract Test 5: Module handles updates correctly
func TestModuleHandlesUpdates(t *testing.T) {
# => Function declaration
 // => Verify module handles variable updates without unnecessary recreation
 // => Contract: changing instance_type doesn't destroy/recreate server
 terraformOptions := &terraform.Options{
 # => Short variable declaration: terraformOptions
 TerraformDir: "./modules/web-server",
 # => Terraform configuration
 Vars: map[string]interface{}{
 # => Terraform configuration
 "server_name": "web-04",
 // => Server name (should not change)
 "instance_type": "small",
 // => Initial instance type
 },
 }
 
 defer terraform.Destroy(t, terraformOptions)
 # => Deferred cleanup (runs when function exits)
 terraform.InitAndApply(t, terraformOptions)
 // => First apply with instance_type = "small"
 
 // Update instance_type
 terraformOptions.Vars["instance_type"] = "large"
 // => Change variable value
 // => Simulates config update
 terraform.Apply(t, terraformOptions)
 // => Second apply with instance_type = "large"
 // => Should update in-place (not recreate)
 
 // Verify output unchanged (module handles in-place update)
 serverName := terraform.Output(t, terraformOptions, "server_name")
 // => Read server_name output after update
 assert.Equal(t, "web-04", serverName)
 # => Test assertion
 // => Verify server_name unchanged
 // => Contract: module updates without replacing resources unnecessarily
 // => In-place updates preferred over destroy/create
 
 
 
 

terraform {
# => Terraform configuration block
 required_version = ">= 1.0" # => String value
 # => Sets required_version
 
 backend "s3" {
 # => Backend type for state storage
 # Production state in separate S3 bucket
 bucket = "company-terraform-prod-state" # => String value
 # => Sets bucket
 key = "app/terraform.tfstate" # => String value
 # => Sets key
 region = "us-east-1" # => String value
 # => Sets region
 encrypt = true # => Boolean value
 # => Sets encrypt
 dynamodb_table = "terraform-prod-locks" # => String value
 # => Sets dynamodb_table
 }
 
 required_providers {
 # => Provider configuration
 aws = { # => Map/object definition
 source = "hashicorp/aws" # => String value
 # => Provider source location
 version = "~> 5.0" # => String value
 # => Sets version
 }
 }
}
 
provider "aws" {
# => Provider configuration
 region = var.aws_region
 # => AWS/cloud region
 # => Sets region
 
 # Production uses separate AWS account
 assume_role {
 # => Terraform configuration
 role_arn = "arn:aws:iam::111111111111:role/TerraformProd" # => String value
 # => Sets role_arn
 }
 # => Different IAM role than dev/staging
 # => Prevents cross-environment accidents
}
 
module "app" {
# => Module call
# => Module configuration
 source = "././modules/app" # => String value
 # => Sets source
 
 environment = "production" # => String value
 # => Sets environment
 instance_count = 10
 # => Sets instance_count
 instance_type = "m5.large"
 # => Production-specific configuration
}
 
output "app_url" {
# => Output value
 value = module.app.url
 # => Output value
 # => Sets value
}
 
 
 
 
 

terraform {
# => Terraform configuration block
 required_version = ">= 1.0" # => String value
 # => Sets required_version
 
 backend "s3" {
 # => Backend type for state storage
 # Dev state in separate S3 bucket
 bucket = "company-terraform-dev-state" # => String value
 # => Sets bucket
 key = "app/terraform.tfstate" # => String value
 # => Sets key
 region = "us-west-2" # => String value
 # => Sets region
 encrypt = true # => Boolean value
 # => Sets encrypt
 dynamodb_table = "terraform-dev-locks" # => String value
 # => Sets dynamodb_table
 }
}
 
provider "aws" {
# => Provider configuration
 region = var.aws_region
 # => AWS/cloud region
 # => Sets region
 
 # Dev uses separate AWS account
 assume_role {
 # => Terraform configuration
 role_arn = "arn:aws:iam::222222222222:role/TerraformDev" # => String value
 # => Sets role_arn
 }
}
 
module "app" {
# => Module call
# => Module configuration
 source = "././modules/app" # => String value
 # => Sets source
 
 environment = "development" # => String value
 # => Sets environment
 instance_count = 1 # => Numeric value
 # => Sets instance_count
 instance_type = "t3.micro" # => String value
 # => Dev-specific configuration
}
 
 
 
 
 

terraform {
# => Terraform configuration block
 required_version = ">= 1.0" # => String value
 # => Sets required_version
 
 required_providers {
 # => Provider configuration
 aws = { # => Map/object definition
 source = "hashicorp/aws" # => String value
 # => Provider source location
 version = "~> 5.0" # => String value
 # => Sets version
 }
 }
}
 
# Primary region provider
provider "aws" {
# => Provider configuration
 alias = "primary" # => String value
 # => Sets alias
 region = "us-east-1" # => String value
 # => Primary region: main traffic
}
 
# Secondary region provider
provider "aws" {
# => Provider configuration
 alias = "secondary" # => String value
 # => Sets alias
 region = "us-west-2" # => String value
 # => Secondary region: failover
}
 
# Tertiary region provider (global distribution)
provider "aws" {
# => Provider configuration
 alias = "tertiary" # => String value
 # => Sets alias
 region = "eu-west-1" # => String value
 # => Tertiary region: Europe traffic
}
 
# Primary region resources
module "app_primary" {
# => Module call
# => Module configuration
 source = "./modules/app" # => String value
 # => Sets source
 
 providers = { # => Map/object definition
 aws = aws.primary
 # => aws.primary refers to provider with alias = "primary"
 }
 # => Pass specific provider to module
 
 region = "us-east-1"
 # => AWS/cloud region
 # => Sets region
 environment = "production"
 # => Sets environment
 instance_count = 10
 # => Primary: handles main traffic load
}
 
# Secondary region resources (disaster recovery)
module "app_secondary" {
# => Module call
# => Module configuration
 source = "./modules/app"
 # => Provider/module source location
 # => Sets source
 
 providers = {
 # => Terraform configuration
 aws = aws.secondary
 # => Directs module resources to us-west-2 provider
 }
 
 region = "us-west-2"
 # => AWS/cloud region
 # => Sets region
 environment = "production"
 # => Sets environment
 instance_count = 5
 # => Smaller capacity for failover: 50% of primary
}
 
# Tertiary region resources (global distribution)
module "app_tertiary" {
# => Module call
# => Module configuration
 source = "./modules/app"
 # => Provider/module source location
 # => Sets source
 
 providers = {
 # => Terraform configuration
 aws = aws.tertiary
 # => Sets aws
 }
 
 region = "eu-west-1"
 # => AWS/cloud region
 # => Sets region
 environment = "production"
 # => Sets environment
 instance_count = 7
 # => Sets instance_count
}
 
# Global resources (region-agnostic)
# Created in primary region
resource "aws_route53_zone" "main" {
# => Resource definition
 provider = aws.primary # => Overrides default provider
 # => Sets provider
 
 name = "example.com"
 # => Resource name
 # => Route53 zone is global (serves all regions)
}
 
# Multi-region DNS routing (latency-based)
resource "aws_route53_record" "app" {
# => Resource definition
 provider = aws.primary # => Overrides default provider
 # => Sets provider
 
 zone_id = aws_route53_zone.main.zone_id
 # => Sets zone_id
 name = "app.example.com"
 # => Resource name
 # => Sets name
 type = "A"
 # => Variable type constraint
 # => Sets type
 set_identifier = "primary"
 # => Sets set_identifier
 
 latency_routing_policy {
 # => Terraform configuration
 region = "us-east-1"
 # => AWS/cloud region
 # => Route53 routes requests to nearest healthy endpoint
 }
 # => Latency routing: Route53 directs users to lowest-latency region
 
 alias {
 # => Terraform configuration
 name = module.app_primary.load_balancer_dns
 # => Resource name
 # => Sets name
 zone_id = module.app_primary.load_balancer_zone_id
 # => Sets zone_id
 evaluate_target_health = true
 # => Sets evaluate_target_health
 }
}
 
resource "aws_route53_record" "app_secondary" {
# => Resource definition
 provider = aws.primary # => Overrides default provider
 # => Sets provider
 
 zone_id = aws_route53_zone.main.zone_id
 # => Sets zone_id
 name = "app.example.com"
 # => Resource name
 # => Sets name
 type = "A"
 # => Variable type constraint
 # => Sets type
 set_identifier = "secondary"
 # => Sets set_identifier
 
 latency_routing_policy {
 # => Terraform configuration
 region = "us-west-2"
 # => AWS/cloud region
 # => Sets region
 }
 
 alias {
 # => Terraform configuration
 name = module.app_secondary.load_balancer_dns
 # => Resource name
 # => Sets name
 zone_id = module.app_secondary.load_balancer_zone_id
 # => Sets zone_id
 evaluate_target_health = true
 # => Sets evaluate_target_health
 }
}
 
# Cross-region data replication
resource "aws_s3_bucket_replication_configuration" "primary_to_secondary" {
# => Resource definition
 provider = aws.primary # => Overrides default provider
 # => Sets provider
 
 bucket = module.app_primary.s3_bucket_id
 # => S3 bucket name
 # => Sets bucket
 role = aws_iam_role.replication.arn
 # => Sets role
 
 rule {
 # => Terraform configuration
 id = "replicate_all"
 # => Sets id
 status = "Enabled"
 # => Sets status
 
 destination {
 # => Terraform configuration
 bucket = module.app_secondary.s3_bucket_arn
 # => S3 bucket name
 # => Sets bucket
 storage_class = "STANDARD_IA"
 # => STANDARD_IA: infrequent access tier (cheaper for DR copies)
 # => Replicate to secondary region for disaster recovery
 }
 }
}
 
output "endpoints" {
# => Output value
 value = {
 # => Output value
 primary = module.app_primary.endpoint
 # => Sets primary
 secondary = module.app_secondary.endpoint
 # => Sets secondary
 tertiary = module.app_tertiary.endpoint
 # => Sets tertiary
 global = "app.example.com"
 # => Sets global
 }
}
 
 
 
 
 

terraform {
# => Terraform configuration block
 required_version = ">= 1.0" # => String value
 # => Sets required_version
}
 
provider "local" {}
# => Provider configuration
 
variable "active_environment" {
# => Input variable
 type = string
 # => Variable type constraint
 # => Sets type
 description = "Active environment: blue or green" # => String value
 # => Sets description
 default = "blue" # => String value
 # => Sets default
 
 validation {
 # => Validation rule enforces constraints
 condition = contains( # => Checks list membership
["blue", "green"], var.active_environment)
 # => Sets condition
 error_message = "active_environment must be blue or green" # => String value
 # => Sets error_message
 }
}
 
variable "app_version" {
# => Input variable
 type = map(string)
 # => Variable type constraint
 # => Sets type
 default = { # => Map/object definition
 blue = "v1.0" # => String value
 # => Sets blue
 green = "v2.0" # => String value
 # => Sets green
 }
}
 
# Blue environment
resource "local_file" "blue_app" {
# => Resource definition
 filename = "blue-app.txt" # => String value
 # => Sets filename
 content = "App version: ${var.app_version["blue"]}\nStatus: ${var.active_environment == "blue" ? "ACTIVE" : "STANDBY"}"
 # => File/resource content
 # => Ternary: active_environment == "blue" → "ACTIVE" else "STANDBY"
}
 
# Green environment
resource "local_file" "green_app" {
# => Resource definition
 filename = "green-app.txt"
 # => Output file path
 # => Sets filename
 content = "App version: ${var.app_version["green"]}\nStatus: ${var.active_environment == "green" ? "ACTIVE" : "STANDBY"}"
 # => File/resource content
 # => Mirror of blue: only one environment is ACTIVE at any time
}
 
# Load balancer (simulated with file showing routing)
resource "local_file" "load_balancer" {
# => Resource definition
 filename = "load-balancer-config.txt"
 # => Output file path
 # => Sets filename
 content = <<-EOT
 # => File/resource content
 Active Environment: ${var.active_environment}
 # => Shows which environment (blue/green) is receiving traffic
 Traffic Routing: 100% -> ${var.active_environment}-app.txt
 # => 100% traffic directed to active environment
 App Version: ${var.app_version[var.active_environment]}
 # => var.app_version[var.active_environment]: map lookup with variable key
 EOT
 # => Routes all traffic to active environment—switch by changing active_environment
}
 
output "active_environment" {
# => Output value
 value = var.active_environment
 # => Output value
 # => Sets value
}
 
output "active_version" {
# => Output value
 value = var.app_version[var.active_environment]
 # => Output value
 # => Sets value
}
 
output "deployment_status" {
# => Output value
 value = {
 # => Output value
 blue = {
 # => Terraform configuration
 version = var.app_version["blue"]
 # => Blue environment's deployed version
 status = var.active_environment == "blue" ? "ACTIVE (100% traffic)" : "STANDBY (0% traffic)"
 # => Status depends on which environment is active
 }
 green = {
 # => Terraform configuration
 version = var.app_version["green"]
 # => Green environment's deployed version
 status = var.active_environment == "green" ? "ACTIVE (100% traffic)" : "STANDBY (0% traffic)"
 # => Only one environment is ACTIVE (100% traffic) at any given time
 }
 }
}
 
 
 
 
 

# Initial state: Blue active with v1.0
# $ terraform apply -var="active_environment=blue"
# => Blue: v1.0 ACTIVE (100% traffic)
# => Green: v2.0 STANDBY (0% traffic)
 
# Step 1: Deploy new version to green (standby)
# $ terraform apply \
# -var="active_environment=blue" \
# -var='app_version={"blue":"v1.0","green":"v2.0"}'
# => Green updated to v2.0 (no traffic yet)
 
# Step 2: Test green environment
# $ curl https://green.example.com/health
# => Validate v2.0 works correctly
 
# Step 3: Switch traffic to green (zero-downtime cutover)
# $ terraform apply -var="active_environment=green"
# => Traffic switches: Blue (0%) → Green (100%)
# => Instant switchover (DNS/load balancer update)
 
# Step 4: Verify green serving traffic
# $ curl https://app.example.com
# => App version: v2.0
 
# Step 5 (if issues): Instant rollback to blue
# $ terraform apply -var="active_environment=blue"
# => Traffic switches back: Green (0%) → Blue (100%)
# => Rollback in seconds (no redeployment needed)
 
# Step 6 (if successful): Update blue with next version
# $ terraform apply \
# -var="active_environment=green" \
# -var='app_version={"blue":"v3.0","green":"v2.0"}'
# => Blue becomes new standby with v3.0
 
 

terraform {
# => Terraform configuration block
 required_version = ">= 1.0" # => String value
 # => Sets required_version
}
 
provider "local" {}
# => Provider configuration
 
variable "new_feature_enabled" {
# => Input variable
 type = bool
 # => Variable type constraint
 # => Sets type
 description = "Enable new feature" # => String value
 # => Sets description
 default = false # => Boolean value
 # => Sets default
}
 
variable "new_feature_rollout_percentage" {
# => Input variable
 type = number
 # => Variable type constraint
 # => Sets type
 description = "Percentage of traffic to new feature (0-100)" # => String value
 # => Sets description
 default = 0 # => Numeric value
 # => Sets default
 
 validation {
 # => Validation rule enforces constraints
 condition = var.new_feature_rollout_percentage >= 0 && var.new_feature_rollout_percentage <= 100 # => Numeric value
 # => Sets condition
 error_message = "Rollout percentage must be 0-100" # => String value
 # => Sets error_message
 }
}
 
# Old feature (stable)
resource "local_file" "feature_v1" {
# => Resource definition
 filename = "feature-v1.txt" # => String value
 # => Sets filename
 content = "Feature Version: 1.0 (Stable)\nTraffic: ${100 - var.new_feature_rollout_percentage}%" # => String value
 # => v1 receives remaining percentage: 100 - rollout_percentage
}
 
# New feature (experimental)
resource "local_file" "feature_v2" {
# => Resource definition
 count = var.new_feature_enabled ? 1 : 0
 # => Number of resource instances
 # => Creates v2 only when enabled flag is true
 
 filename = "feature-v2.txt"
 # => Output file path
 # => Sets filename
 content = "Feature Version: 2.0 (Experimental)\nTraffic: ${var.new_feature_rollout_percentage}%"
 # => File/resource content
 # => Shows what percentage of traffic routes to the new feature
}
 
# Load balancer configuration (weighted routing)
resource "local_file" "load_balancer_weights" {
# => Resource definition
 filename = "traffic-split.txt"
 # => Output file path
 # => Sets filename
 content = <<-EOT
 # => File/resource content
 # => Sets content
 Traffic Split Configuration:
 # => Terraform configuration
 - Feature V1: ${100 - var.new_feature_rollout_percentage}% (${100 - var.new_feature_rollout_percentage} out of 100 requests)
 # => Terraform configuration
 - Feature V2: ${var.new_feature_rollout_percentage}% (${var.new_feature_rollout_percentage} out of 100 requests)
 # => Terraform configuration
 
 Status: ${var.new_feature_enabled ? "ROLLOUT IN PROGRESS" : "STABLE (V1 ONLY)"}
 # => Terraform configuration
 EOT
 # => Terraform configuration
}
 
output "rollout_status" {
# => Output value
 value = {
 # => Output value
 new_feature_enabled = var.new_feature_enabled
 # => Sets new_feature_enabled
 v1_traffic_pct = 100 - var.new_feature_rollout_percentage
 # => Sets v1_traffic_pct
 v2_traffic_pct = var.new_feature_rollout_percentage
 # => Sets v2_traffic_pct
 stage = var.new_feature_rollout_percentage == 0 ? "Not started" : (
 # => Nested ternary: 0% → Not started, 100% → Complete, else → In progress
 var.new_feature_rollout_percentage == 100 ? "Complete" : "In progress"
 # => Terraform configuration
 )
 }
}
 
 
 
 
 

# Stage 1: Deploy new feature (0% traffic)
# $ terraform apply \
# -var="new_feature_enabled=true" \
# -var="new_feature_rollout_percentage=0"
# => Feature V2 deployed but receives no traffic
# => Test internally before exposing to users
 
# Stage 2: Canary deployment (1% traffic)
# $ terraform apply \
# -var="new_feature_enabled=true" \
# -var="new_feature_rollout_percentage=1"
# => 1 in 100 requests go to V2
# => Monitor error rates, latency, metrics
 
# Stage 3: Increase to 10% (validation successful)
# $ terraform apply \
# -var="new_feature_enabled=true" \
# -var="new_feature_rollout_percentage=10"
# => 10 in 100 requests go to V2
 
# Stage 4: Increase to 50%
# $ terraform apply -var="new_feature_rollout_percentage=50"
# => Half of traffic on new feature
 
# Stage 5: Full rollout (100%)
# $ terraform apply -var="new_feature_rollout_percentage=100"
# => All traffic on V2
# => V1 remains deployed for instant rollback
 
# Rollback (if issues discovered)
# $ terraform apply -var="new_feature_rollout_percentage=0"
# => Instant rollback to V1 (100% traffic)
 
# Stage 6: Remove old feature (after stability confirmed)
# $ terraform apply \
# -var="new_feature_enabled=true" \
# -var="new_feature_rollout_percentage=100"
# => Can remove V1 resources in future apply
 
 

# ❌ NEVER hardcode secrets
variable "database_password" {
# => Input variable
 default = "SuperSecret123!" # EXPOSED IN CODE
 # => Default value if not specified
 # => Sets default
}
 
# ❌ NEVER use sensitive data in resources directly
resource "local_file" "config" {
# => Resource definition
 filename = "config.txt" # => String value
 # => Sets filename
 content = "DB_PASSWORD=SuperSecret123!" # => String value
 # => Secrets appear in state file (plain text)
 # => Secrets appear in plan output
 # => Secrets leak in logs
}
 
 
 

terraform {
# => Terraform configuration block
 required_version = ">= 1.0" # => String value
 # => Sets required_version
 
 required_providers {
 # => Provider configuration
 aws = { # => Map/object definition
 source = "hashicorp/aws" # => String value
 # => Provider source location
 version = "~> 5.0" # => String value
 # => Sets version
 }
 }
}
 
provider "aws" {
# => Provider configuration
 region = "us-west-2" # => String value
 # => Sets region
}
 
# Store secret in Secrets Manager (one-time manual creation)
# $ aws secretsmanager create-secret \
# --name prod/database/password \
# --secret-string "SuperSecret123!"
 
# Reference secret from Secrets Manager (not stored in Terraform)
data "aws_secretsmanager_secret" "db_password" {
# => Data source
 name = "prod/database/password" # => String value
 # => Fetch secret metadata (not value)
}
 
data "aws_secretsmanager_secret_version" "db_password" {
# => Data source
 secret_id = data.aws_secretsmanager_secret.db_password.id
 # => Fetch current secret value
 # => ⚠️ Value still appears in state (state encryption required)
}
 
# Use secret in resource (marked sensitive)
resource "aws_db_instance" "main" {
# => Resource definition
 allocated_storage = 20 # => Numeric value
 # => Sets allocated_storage
 engine = "postgres" # => String value
 # => Sets engine
 instance_class = "db.t3.micro" # => String value
 # => Sets instance_class
 username = "admin"
 # => Sets username
 password = data.aws_secretsmanager_secret_version.db_password.secret_string
 # => Secret value from Secrets Manager
 # => Never hardcoded in .tf files
 
 # Other configurations..
}
 
# Output secrets safely (marked sensitive)
output "db_endpoint" {
# => Output value
 value = aws_db_instance.main.endpoint
 # => Output value
 # => Sets value
}
 
output "db_password_arn" {
# => Output value
 value = data.aws_secretsmanager_secret.db_password.arn
 # => Output value
 # => Output secret ARN (safe), not password value
}
 
# ❌ NEVER output secret values
# output "db_password" {
# value = data.aws_secretsmanager_secret_version.db_password.secret_string
# # => Exposes secret in terraform output
# }
 
# ✅ If must output (for debugging), mark sensitive
output "db_password_debug" {
# => Output value
 value = data.aws_secretsmanager_secret_version.db_password.secret_string
 # => Output value
 # => Sets value
 sensitive = true
 # => Mark as sensitive (hide from output)
 # => sensitive = true hides value in plan/apply output
 # => Still visible in state file
}
 
 
 

terraform {
# => Terraform configuration block
 required_providers {
 # => Provider configuration
 vault = { # => Map/object definition
 source = "hashicorp/vault" # => String value
 # => Provider source location
 version = "~> 3.0" # => String value
 # => Sets version
 }
 }
}
 
provider "vault" {
# => Provider configuration
 address = "https://vault.example.com" # => String value
 # Authenticate via VAULT_TOKEN environment variable
}
 
# Read secret from Vault
data "vault_generic_secret" "db_password" {
# => Data source
 path = "secret/prod/database" # => String value
 # => Fetch secret from Vault KV store
}
 
resource "local_file" "config" {
# => Resource definition
 filename = "app-config.txt" # => String value
 # => Sets filename
 content = <<-EOT
 # => File/resource content
 # => Sets content
 DB_HOST=db.example.com
 # => Sets DB_HOST
 DB_USER=admin
 # => Sets DB_USER
 DB_PASSWORD=${data.vault_generic_secret.db_password.data["password"]}
 # => Sets DB_PASSWORD
 EOT
 # => Secret value from Vault
 # => Not hardcoded in Terraform
}
 
 
 
 
 

# Terraform execution role (assumed by CI/CD)
resource "aws_iam_role" "terraform_apply" {
# => Terraform configuration block
 # => IAM role for terraform apply operations
 # => Assumed by GitHub Actions on main branch
 name = "TerraformApply" # => String value
 # => Role name (visible in AWS console)
 
 assume_role_policy = jsonencode( # => Converts value to JSON string
 
 
 {
 # => Trust policy defines who can assume this role
 # => jsonencode converts map to JSON string
 Version = "2012-10-17"
 # => IAM policy language version
 Statement = [{
 # => List of policy statements (trust relationship)
 Effect = "Allow"
 # => Grant permission to assume role
 Principal = {
 # => Who can assume this role
 Federated = "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
 # => GitHub OIDC provider (configured in AWS)
 # => Enables keyless authentication from GitHub Actions
 }
 Action = "sts:AssumeRoleWithWebIdentity"
 # => STS action for OIDC-based role assumption
 # => Uses GitHub's OIDC token for authentication
 Condition = {
 # => Additional constraints on role assumption
 StringEquals = {
 # => Exact string match condition
 "token.actions.githubusercontent.com:sub" = "repo:my-org/infrastructure:ref:refs/heads/main"
 # => Only GitHub Actions from main branch can assume this role
 # => :sub claim identifies repository and branch
 # => Prevents PRs or other branches from assuming write role
 }
 }
 }]
 # => Terraform configuration
 })
 # => Terraform configuration
}
 
# Terraform apply policy (write permissions)
resource "aws_iam_role_policy" "terraform_apply" {
# => Terraform configuration block
 # => Inline policy attached to terraform_apply role
 # => Grants permissions for infrastructure changes
 name = "TerraformApplyPolicy" # => String value
 # => Policy name
 role = aws_iam_role.terraform_apply.id
 # => Attach to terraform_apply role
 
 policy = jsonencode( # => Converts value to JSON string
 
 
 {
 # => Permissions policy (what role can do)
 Version = "2012-10-17"
 # => Sets Version
 Statement = [
 # => Sets Statement
 {
 # => Statement 1: Resource management permissions
 Effect = "Allow"
 # => Grant permissions
 Action = [
 # => AWS API actions allowed
 "ec2:*",
 # => All EC2 actions (instances, VPCs, subnets, etc.)
 # => Wildcard grants full EC2 control
 "s3:*",
 # => All S3 actions (buckets, objects, policies)
 "rds:*",
 # => All RDS actions (databases, snapshots, etc.)
 "iam:GetRole",
 # => Read IAM role details
 "iam:GetRolePolicy",
 # => Read role policy details
 # => Minimal permissions for managed resources
 # => IAM limited to read-only (no role creation/deletion)
 ]
 Resource = "*"
 # => Apply to all resources (no restrictions)
 # => Production should scope to specific resources
 },
 {
 # => Statement 2: State file access
 Effect = "Allow"
 # => Sets Effect
 Action = [
 # => S3 actions for state operations
 "s3:GetObject",
 # => Read state file
 "s3:PutObject",
 # => Write state file (after apply)
 "s3:DeleteObject"
 # => Delete old state versions
 ]
 Resource = "arn:aws:s3:::terraform-state-bucket/*"
 # => State file access
 # => Scoped to terraform-state-bucket only
 # => /* allows access to all objects in bucket
 },
 {
 # => Statement 3: State locking
 Effect = "Allow"
 # => Sets Effect
 Action = [
 # => DynamoDB actions for state locks
 "dynamodb:GetItem",
 # => Check lock status
 "dynamodb:PutItem",
 # => Acquire lock (start apply)
 "dynamodb:DeleteItem"
 # => Release lock (end apply)
 ]
 Resource = "arn:aws:dynamodb:us-west-2:ACCOUNT_ID:table/terraform-locks"
 # => State locking
 # => Scoped to terraform-locks table only
 # => Prevents concurrent applies
 }
 ]
 })
 # => Terraform configuration
}
 
# Terraform plan role (read-only permissions)
resource "aws_iam_role" "terraform_plan" {
# => Terraform configuration block
 # => IAM role for terraform plan operations
 # => Assumed by GitHub Actions from pull requests
 name = "TerraformPlan"
 # => Resource name
 # => Role name (read-only variant)
 
 assume_role_policy = jsonencode( # => Converts value to JSON string
 
 
 {
 # => Trust policy for plan role
 Version = "2012-10-17"
 # => Sets Version
 Statement = [{
 # => Terraform configuration
 Effect = "Allow"
 # => Sets Effect
 Principal = {
 # => Terraform configuration
 Federated = "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
 # => Same OIDC provider as apply role
 }
 Action = "sts:AssumeRoleWithWebIdentity"
 # => OIDC-based role assumption
 Condition = {
 # => Terraform configuration
 StringEquals = {
 # => Terraform configuration
 "token.actions.githubusercontent.com:sub" = "repo:my-org/infrastructure:pull_request"
 # => GitHub Actions from pull requests use read-only role
 # => :pull_request allows any PR in repository
 # => Different condition from apply role (main branch only)
 }
 }
 }]
 # => Terraform configuration
 })
 # => Terraform configuration
}
 
# Terraform plan policy (read-only)
resource "aws_iam_role_policy" "terraform_plan" {
# => Terraform configuration block
 # => Read-only policy for plan operations
 # => Allows terraform plan but blocks apply
 name = "TerraformPlanPolicy"
 # => Resource name
 # => Sets name
 role = aws_iam_role.terraform_plan.id
 # => Attach to plan role
 
 policy = jsonencode( # => Converts value to JSON string
 
 
 {
 Version = "2012-10-17"
 # => Sets Version
 Statement = [
 # => Sets Statement
 {
 # => Statement 1: Read-only AWS resource access
 Effect = "Allow"
 # => Sets Effect
 Action = [
 # => Read-only API actions
 "ec2:Describe*",
 # => All EC2 Describe actions (no Create/Update/Delete)
 "s3:List*",
 # => List S3 buckets and objects
 "s3:Get*",
 # => Read S3 object content and metadata
 "rds:Describe*",
 # => Read RDS database details
 "iam:Get*",
 # => Read IAM role/policy details
 "iam:List*",
 # => List IAM entities
 # => Read-only permissions for plan
 # => Wildcards allow all read operations, no write
 ]
 Resource = "*"
 # => Apply to all resources
 },
 {
 # => Statement 2: State file read access
 Effect = "Allow"
 # => Sets Effect
 Action = [
 # => Sets Action
 "s3:GetObject"
 # => Read state file only
 # => No PutObject (can't modify state)
 # => No DeleteObject (can't delete state)
 ]
 Resource = "arn:aws:s3:::terraform-state-bucket/*"
 # => Read state (no write)
 # => Plan needs state to compare current vs desired
 }
 # => Note: No DynamoDB permissions (plan doesn't lock state)
 ]
 })
 # => Terraform configuration
}
 
 
 

# Terraform configuration assumes appropriate role
terraform {
 # => Terraform configuration block
 required_version = ">= 1.0" # => String value
 # => Minimum Terraform version
 
 backend "s3" {
 # => Backend type for state storage
 # => S3 backend for state storage
 bucket = "terraform-state-bucket" # => String value
 # => S3 bucket name for state file
 key = "prod/terraform.tfstate" # => String value
 # => State file path within bucket
 # => Organizes state by environment (prod/)
 region = "us-west-2" # => String value
 # => AWS region for S3 bucket
 role_arn = "arn:aws:iam::ACCOUNT_ID:role/TerraformApply" # => String value
 # => Backend uses apply role (write access)
 # => Role must have S3 GetObject/PutObject/DeleteObject permissions
 # => Also needs DynamoDB permissions for state locking
 }
}
 
provider "aws" {
 # => AWS provider configuration
 region = "us-west-2" # => String value
 # => All resources created in us-west-2
 
 assume_role {
 # => Assume IAM role for resource operations
 role_arn = "arn:aws:iam::ACCOUNT_ID:role/TerraformApply" # => String value
 # => Provider assumes role with appropriate permissions
 # => Role has permissions for EC2, S3, RDS operations
 # => CI/CD authenticates via OIDC, then assumes this role
 }
}
 
 

# .github/workflows/terraform.yml
name: Terraform
# => Workflow name in GitHub Actions UI
on:
 # => Trigger conditions
 pull_request:
 # => Run on pull requests
 branches: [main]
 # => Only PRs targeting main branch
 push:
 # => Run on direct pushes
 branches: [main]
 # => Only pushes to main branch (after PR merge)
 
jobs:
 # => Job definitions
 plan:
 # => Plan job for pull requests
 if: github.event_name == 'pull_request'
 # => Conditional execution expression
 # => Only run on PRs (not pushes)
 runs-on: ubuntu-latest
 # => GitHub Actions runner type
 # => GitHub-hosted Ubuntu runner
 permissions:
 # => GitHub token permissions
 id-token: write # Required for OIDC
 # => Write permission to generate OIDC tokens
 # => Needed for AWS OIDC authentication
 contents: read
 # => Read permission for repository checkout
 steps:
 # => Sequential steps
 - uses: actions/checkout@v3
 # => Check out repository code
 - uses: hashicorp/setup-terraform@v2
 # => Install Terraform CLI
 
 - name: Configure AWS credentials
 # => Authenticate to AWS using OIDC
 uses: aws-actions/configure-aws-credentials@v2
 # => Reusable action from marketplace
 with:
 # => Input parameters for action
 role-to-assume: arn:aws:iam::ACCOUNT_ID:role/TerraformPlan
 # => PR uses read-only plan role
 # => TerraformPlan role has Describe/List/Get permissions only
 aws-region: us-west-2
 # => AWS region for API calls
 
 - name: Terraform Plan
 # => Generate execution plan
 run: terraform plan
 # => Shell command to execute
 # => Plan shows what changes would be made
 # => Read-only operation (no infrastructure changes)
 
 apply:
 # => Apply job for main branch
 if: github.event_name == 'push'
 # => Conditional execution expression
 # => Only run on push to main (after PR merge)
 runs-on: ubuntu-latest
 # => GitHub Actions runner type
 permissions:
 # => permissions configuration
 id-token: write
 # => OIDC token generation
 contents: read
 # => Repository read access
 steps:
 # => Sequential steps for job
 - uses: actions/checkout@v3
 # => Check out merged code
 - uses: hashicorp/setup-terraform@v2
 # => Install Terraform
 
 - name: Configure AWS credentials
 # => Authenticate with elevated permissions
 uses: aws-actions/configure-aws-credentials@v2
 # => Reusable action from marketplace
 with:
 # => Input parameters for action
 role-to-assume: arn:aws:iam::ACCOUNT_ID:role/TerraformApply
 # => Main branch uses write apply role
 # => TerraformApply role has Create/Update/Delete permissions
 # => Different role than plan (least privilege)
 aws-region: us-west-2
 # => Sets aws-region
 
 - name: Terraform Apply
 # => Apply infrastructure changes
 run: terraform apply -auto-approve
 # => Shell command to execute
 # => -auto-approve: no interactive prompt (CI environment)
 # => Creates/updates/deletes resources