Terraform Tasks

<!-- Progressive Disclosure References:

• references/aws-provider-6.md - AWS Provider 6.0 breaking changes and migration
• references/azurerm-4.md - AzureRM 4.x features and migration
• references/ephemeral-values.md - Terraform 1.10+ ephemeral values for secrets
• references/terraform-stacks.md - Terraform Stacks (GA 2025) reference

-->

Terraform Tasks Skill

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

This skill enables autonomous execution of complex Terraform tasks with comprehensive provider knowledge and platform awareness.

Capabilities

1. Infrastructure Code Generation

Generate complete, production-ready Terraform code for any cloud provider:

Process: 1. Determine provider and version from user context 2. Research latest provider documentation if needed 3. Generate complete configurations with:

• Provider version constraints
• Resource configurations
• Variables with validation
• Outputs
• Security best practices
• Platform-specific considerations

Example Tasks:

• "Create Azure Storage Account with private endpoints and customer-managed keys"
• "Generate AWS VPC with 3-tier architecture and NAT gateways"
• "Build GCP GKE cluster with Workload Identity and node pools"

2. Version Management

Handle Terraform and provider version upgrades:

Process: 1. Check current versions 2. Research changelogs and breaking changes 3. Propose upgrade path 4. Generate migration code 5. Provide testing strategy

Example Tasks:

• "Upgrade from AzureRM provider 2.x to 3.x"
• "Migrate Terraform 0.12 code to 1.x"
• "Update all providers to latest compatible versions"

3. Debugging and Troubleshooting

Diagnose and fix Terraform issues:

Process: 1. Gather diagnostic information 2. Analyze error messages and logs 3. Identify root cause 4. Provide platform-specific solution 5. Suggest preventive measures

Example Tasks:

• "Debug state lock timeout on Windows"
• "Fix provider authentication failure in Azure DevOps pipeline"
• "Resolve circular dependency in module structure"

4. Security Scanning and Remediation

Scan and fix security issues:

Process: 1. Run security scanners (tfsec, Checkov) 2. Analyze findings 3. Prioritize issues 4. Generate fixes 5. Explain security implications

Example Tasks:

• "Run tfsec and fix all HIGH severity issues"
• "Ensure all S3 buckets have encryption enabled"
• "Implement Azure storage account with all security best practices"

5. Architecture Review

Review and improve Terraform architecture:

Process: 1. Analyze current structure 2. Identify anti-patterns 3. Propose improvements 4. Generate refactoring plan 5. Document decisions (ADRs)

Example Tasks:

• "Review state management strategy for 500+ resources"
• "Design multi-region architecture for high availability"
• "Refactor monolithic state into layered approach"

6. CI/CD Pipeline Generation

Create complete CI/CD pipelines:

Process: 1. Determine CI/CD platform 2. Understand environment strategy 3. Generate pipeline configuration 4. Include security scanning 5. Add approval gates 6. Implement drift detection

Example Tasks:

• "Create Azure DevOps pipeline with multi-stage deployment"
• "Generate GitHub Actions workflow with OIDC authentication"
• "Build GitLab CI pipeline with Terraform Cloud backend"

7. Module Development

Create reusable Terraform modules:

Process: 1. Design module interface 2. Implement with best practices 3. Add variable validation 4. Generate documentation 5. Create examples 6. Set up testing

Example Tasks:

• "Create Azure networking module with hub-spoke pattern"
• "Build AWS ECS module with auto-scaling and ALB"
• "Develop GCP Cloud Run module with custom domains"

8. Migration Tasks

Migrate infrastructure to Terraform:

Process: 1. Inventory existing resources 2. Generate import commands 3. Create matching Terraform code 4. Validate configurations 5. Test import process 6. Plan cutover strategy

Example Tasks:

• "Import existing Azure resources into Terraform"
• "Migrate from CloudFormation to Terraform"
• "Convert ARM templates to Terraform HCL"

Autonomous Behavior

This skill operates autonomously with minimal user intervention:

Information Gathering

• Automatically detect Terraform and provider versions
• Identify platform (Windows/Linux/macOS)
• Detect CI/CD environment
• Check for existing configurations

Research

• Use WebSearch to find current documentation
• Check provider changelogs for breaking changes
• Research best practices
• Find platform-specific solutions

Code Generation

• Generate complete, working code
• Include all necessary files (main.tf, variables.tf, outputs.tf, etc.)
• Add comprehensive comments
• Follow naming conventions
• Apply security best practices

Validation

• Run terraform fmt on generated code
• Validate syntax
• Check for security issues
• Test configurations when possible

Documentation

• Explain architectural decisions
• Document usage examples
• Note version compatibility
• Include troubleshooting tips

Error Handling

When encountering issues:

1. Gather Context: Collect all relevant information 2. Research: Look up error messages and solutions 3. Platform Awareness: Consider OS-specific issues 4. Multiple Solutions: Provide alternatives when available 5. Prevention: Suggest how to avoid similar issues

Platform-Specific Considerations

Windows

• PowerShell syntax for commands
• Path handling (backslashes)
• Line ending considerations
• Execution policy issues
• Credential management

Linux/macOS

• Bash syntax for commands
• File permissions
• Package managers
• Environment variables

CI/CD Environments

• Pipeline-specific syntax
• Agent capabilities
• Authentication methods
• Artifact handling

Quality Standards

All generated Terraform code must:

• Be properly formatted (terraform fmt)
• Pass validation (terraform validate)
• Include security best practices
• Have comprehensive variable validation
• Include meaningful descriptions
• Follow naming conventions
• Be version-compatible
• Include usage examples
• Have proper output definitions

Provider Expertise

Azure (AzureRM)

• All resource types
• AzAPI for preview features
• Service endpoints and private endpoints
• Managed identities
• RBAC and policies

AWS

• All services
• IAM roles and policies
• VPC networking
• S3 backend configuration
• Cross-account deployments

Google Cloud

• All GCP services
• IAM and service accounts
• VPC and networking
• GCS backend configuration
• Organization and folder policies

Community Providers

• Kubernetes and Helm
• Datadog, PagerDuty
• GitHub, GitLab
• HashiCorp Vault
• And more...

Examples

Example 1: Generate Azure Storage Account

User Request: "Create an Azure Storage Account with all security best practices"

Skill Actions: 1. Detect/ask for AzureRM provider version 2. Research latest security requirements 3. Generate complete configuration:

• Storage account with secure settings
• Private endpoint
• Diagnostic settings
• Customer-managed encryption keys
• Network rules
• Variables with validation
• Outputs

4. Include usage examples 5. Add security scanner ignore comments where appropriate with explanations

Example 2: Debug Plan Failure

User Request: "My terraform plan is failing with authentication error on Windows"

Skill Actions: 1. Ask for error details 2. Identify it's Azure CLI authentication 3. Provide Windows-specific solution:

• PowerShell commands to check authentication
• How to refresh credentials
• Environment variable configuration
• Alternative authentication methods

4. Explain root cause 5. Suggest prevention

Example 3: Architecture Review

User Request: "Review my Terraform structure, I have 1000+ resources in one state file"

Skill Actions: 1. Analyze current structure 2. Identify issues:

• Large state file
• Slow operations
• Large blast radius

3. Propose layered architecture:

• Split into foundation/platform/apps
• Separate state files
• Remote state data sources

4. Generate migration plan 5. Create ADR documenting decision 6. Provide implementation steps

Integration with terraform-expert Agent

This skill works in tandem with the terraform-expert agent:

• Agent provides strategic guidance
• Skill executes tactical tasks
• Agent validates skill outputs
• Skill reports back to agent

Use this skill when you need to autonomously execute Terraform tasks with comprehensive provider knowledge and platform awareness.

AWS Provider 6.0 GA Reference (2025)

Breaking Changes

Multi-Region Support

• Enhanced region attribute support for S3 resources
• bucket_region attribute now available on aws_s3_bucket
• Can specify region per-resource without multiple provider configurations

Deprecated Services (Removed)

• Amazon Chime: Use aws_chime_voice_connector alternatives
• Amazon Evidently: Migrate to CloudWatch RUM
• AWS MediaStore: Use S3 with CloudFront

Resource Renames

# Old (5.x)
resource "aws_s3_bucket_acl" "example" { ... }

# New (6.0) - Same but ACLs deprecated
resource "aws_s3_bucket" "example" {
  bucket = "my-bucket"
  # Object ownership enforces bucket owner
  object_ownership = "BucketOwnerEnforced"
}

Migration Guide

Step 1: Check Provider Version

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }
}

Step 2: Update Deprecated Resources

# Find deprecated resources
grep -r "aws_chime\|aws_evidently\|aws_mediastore" *.tf

Step 3: Update S3 Configurations

# Modern S3 bucket (6.0+)
resource "aws_s3_bucket" "main" {
  bucket = "my-bucket"

  tags = {
    Environment = "production"
  }
}

resource "aws_s3_bucket_versioning" "main" {
  bucket = aws_s3_bucket.main.id
  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "main" {
  bucket = aws_s3_bucket.main.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "aws:kms"
    }
    bucket_key_enabled = true
  }
}

resource "aws_s3_bucket_public_access_block" "main" {
  bucket = aws_s3_bucket.main.id

  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

New Features

Enhanced Region Support

# Multi-region bucket replication without multiple providers
resource "aws_s3_bucket" "source" {
  bucket = "source-bucket"
}

resource "aws_s3_bucket" "destination" {
  bucket = "destination-bucket"
  # Can now specify region directly
}

New Resources (6.0)

• aws_bedrockagent_* - Bedrock Agent resources
• aws_sagemaker_* - Additional SageMaker resources
• Enhanced Lambda resources
• VPC Lattice improvements

Compatibility Matrix

AzureRM Provider 4.x Reference (2025)

Overview

• 1,101+ resources
• 360+ data sources
• Provider-defined functions
• Improved resource provider registration

Key Features

Provider-Defined Functions

# Use provider functions directly
locals {
  # Normalize Azure location names
  location = provider::azurerm::normalize_location("East US 2")

  # Parse resource IDs
  parsed = provider::azurerm::parse_resource_id(azurerm_resource_group.main.id)
}

AKS Enhancements

resource "azurerm_kubernetes_cluster" "main" {
  name                = "my-aks"
  location            = azurerm_resource_group.main.location
  resource_group_name = azurerm_resource_group.main.name
  dns_prefix          = "my-aks"

  default_node_pool {
    name       = "default"
    node_count = 3
    vm_size    = "Standard_D4s_v3"

    # AzureRM 4.x: AzureLinux OS support
    os_sku = "AzureLinux"

    # AzureRM 4.x: Node provisioning profile
    upgrade_settings {
      max_surge = "33%"
    }
  }

  # AzureRM 4.x: AI toolchain operator
  ai_toolchain_operator_enabled = true

  # AzureRM 4.x: Workload identity
  oidc_issuer_enabled       = true
  workload_identity_enabled = true

  identity {
    type = "SystemAssigned"
  }
}

Azure OpenAI

resource "azurerm_cognitive_account" "openai" {
  name                = "my-openai"
  location            = azurerm_resource_group.main.location
  resource_group_name = azurerm_resource_group.main.name
  kind                = "OpenAI"
  sku_name            = "S0"

  # AzureRM 4.x: Enhanced network configuration
  network_acls {
    default_action = "Deny"
    ip_rules       = ["1.2.3.4/32"]
  }
}

resource "azurerm_cognitive_deployment" "gpt4" {
  name                 = "gpt-4"
  cognitive_account_id = azurerm_cognitive_account.openai.id

  model {
    format  = "OpenAI"
    name    = "gpt-4"
    version = "turbo-2024-04-09"
  }

  sku {
    name     = "Standard"
    capacity = 120
  }
}

Migration from 3.x to 4.x

Breaking Changes

# 3.x - Some properties renamed
resource "azurerm_storage_account" "old" {
  allow_blob_public_access = false  # Deprecated
}

# 4.x - Updated property names
resource "azurerm_storage_account" "new" {
  allow_nested_items_to_be_public = false
  shared_access_key_enabled       = true
}

Resource Provider Registration

provider "azurerm" {
  features {}

  # AzureRM 4.x: Improved provider registration
  resource_provider_registrations = "core"  # Or "none", "all", "extended"
}

New Resources (4.x)

AI & ML

• azurerm_machine_learning_workspace
• azurerm_cognitive_account (OpenAI)
• azurerm_cognitive_deployment

Kubernetes

• azurerm_kubernetes_cluster_node_pool
• azurerm_kubernetes_fleet_manager

Networking

• azurerm_virtual_network_gateway_nat_rule
• azurerm_express_route_port_authorization

Best Practices

Version Pinning

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

Features Block

provider "azurerm" {
  features {
    key_vault {
      purge_soft_delete_on_destroy    = false
      recover_soft_deleted_key_vaults = true
    }

    resource_group {
      prevent_deletion_if_contains_resources = false
    }

    virtual_machine {
      delete_os_disk_on_deletion     = true
      graceful_shutdown              = false
      skip_shutdown_and_force_delete = false
    }
  }
}

Ephemeral Values Reference (Terraform 1.10+)

Overview

Ephemeral values are a security feature introduced in Terraform 1.10 that allows secrets to be used without persisting them in state or plan files.

Ephemeral Input Variables

variable "db_password" {
  description = "Database password - never stored in state"
  type        = string
  sensitive   = true
  ephemeral   = true  # Key: Never persisted
}

variable "api_key" {
  description = "External API key"
  type        = string
  sensitive   = true
  ephemeral   = true
}

Ephemeral Resources

AWS Secrets Manager

ephemeral "aws_secretsmanager_secret_version" "db_creds" {
  secret_id = "prod/database/credentials"
}

resource "aws_db_instance" "main" {
  identifier     = "mydb"
  engine         = "postgres"
  engine_version = "15.4"
  instance_class = "db.t3.micro"

  username = "admin"
  password = ephemeral.aws_secretsmanager_secret_version.db_creds.secret_string
}

AWS SSM Parameter

ephemeral "aws_ssm_parameter" "api_key" {
  name = "/prod/api-key"
}

resource "aws_lambda_function" "main" {
  function_name = "my-function"
  role          = aws_iam_role.lambda.arn
  handler       = "index.handler"
  runtime       = "nodejs18.x"

  environment {
    variables = {
      API_KEY = ephemeral.aws_ssm_parameter.api_key.value
    }
  }
}

Azure Key Vault

ephemeral "azurerm_key_vault_secret" "db_password" {
  name         = "database-password"
  key_vault_id = azurerm_key_vault.main.id
}

resource "azurerm_postgresql_flexible_server" "main" {
  name                = "mypostgres"
  resource_group_name = azurerm_resource_group.main.name
  location            = azurerm_resource_group.main.location

  administrator_login    = "psqladmin"
  administrator_password = ephemeral.azurerm_key_vault_secret.db_password.value
}

Google Secret Manager

ephemeral "google_secret_manager_secret_version" "db_password" {
  secret = "projects/my-project/secrets/db-password"
}

resource "google_sql_database_instance" "main" {
  name             = "myinstance"
  database_version = "POSTGRES_15"
  region           = "us-central1"

  root_password = ephemeral.google_secret_manager_secret_version.db_password.secret_data
}

Write-Only Arguments (1.11+)

# Arguments marked as write-only accept ephemeral values
# and are never stored in state
resource "aws_db_instance" "main" {
  identifier     = "mydb"
  engine         = "postgres"
  instance_class = "db.t3.micro"

  # Write-only argument - accepts ephemeral value
  password = var.db_password
}

Ephemeral Outputs

output "db_connection_string" {
  description = "Database connection string"
  value       = "postgres://admin:${var.db_password}@${aws_db_instance.main.endpoint}/mydb"
  sensitive   = true
  ephemeral   = true  # Never stored in state
}

How Ephemeral Values Work

1. Fresh on every run: Retrieved during plan/apply, not stored 2. No state persistence: Never written to terraform.tfstate 3. No plan persistence: Never written to plan files 4. Re-evaluation: Fetched again during apply if needed 5. Garbage collection: Cleaned up after use

Provider Support (2025)

Migration from Data Sources

# OLD (1.9 and earlier) - Secrets in state!
data "aws_secretsmanager_secret_version" "db_creds" {
  secret_id = "prod/database/credentials"
}

# NEW (1.10+) - Secrets NOT in state
ephemeral "aws_secretsmanager_secret_version" "db_creds" {
  secret_id = "prod/database/credentials"
}

Requirements

• Terraform >= 1.10 for ephemeral variables
• Terraform >= 1.11 for write-only arguments
• Provider support for ephemeral resource types

Terraform Stacks Reference (GA 2025)

Overview

Terraform Stacks enable deploying consistent infrastructure across multiple deployments (environments, regions, accounts) with a single action.

Key Concepts

Stack Definition

# stack.tfstack - Infrastructure template
stack {
  name        = "multi-region-app"
  description = "Production application infrastructure"
}

# Component definitions
component "networking" {
  source = "./modules/networking"

  inputs = {
    environment = var.environment
    region      = var.region
    cidr_block  = var.vpc_cidr
  }
}

component "compute" {
  source = "./modules/compute"

  inputs = {
    environment   = var.environment
    subnet_ids    = component.networking.private_subnet_ids
    instance_type = var.instance_type
  }
}

component "database" {
  source = "./modules/database"

  inputs = {
    environment = var.environment
    subnet_ids  = component.networking.database_subnet_ids
    vpc_id      = component.networking.vpc_id
  }
}

Deployment Configuration

# deployments.tfdeploy.hcl - Multiple deployments

deployment "prod-us-east" {
  inputs = {
    environment   = "production"
    region        = "us-east-1"
    vpc_cidr      = "10.0.0.0/16"
    instance_type = "m5.xlarge"
  }
}

deployment "prod-us-west" {
  inputs = {
    environment   = "production"
    region        = "us-west-2"
    vpc_cidr      = "10.1.0.0/16"
    instance_type = "m5.xlarge"
  }
}

deployment "prod-eu-west" {
  inputs = {
    environment   = "production"
    region        = "eu-west-1"
    vpc_cidr      = "10.2.0.0/16"
    instance_type = "m5.large"
  }
}

deployment "staging" {
  inputs = {
    environment   = "staging"
    region        = "us-east-1"
    vpc_cidr      = "10.100.0.0/16"
    instance_type = "t3.medium"
  }
}

Linked Stacks (2025)

Cross-stack dependency management with automatic triggers:

# platform-stack.tfstack
stack {
  name = "platform"
}

component "shared-services" {
  source = "./modules/shared"
}

output "vpc_id" {
  value = component.shared-services.vpc_id
}

# application-stack.tfstack
stack {
  name = "application"

  # Link to platform stack
  depends_on = [stack.platform]
}

component "app" {
  source = "./modules/app"

  inputs = {
    vpc_id = stack.platform.outputs.vpc_id
  }
}

2025 Features

Self-Hosted Agents

Execute stacks behind firewalls or in air-gapped environments.

Custom Deployment Groups

Auto-approve checks for HCP Terraform Premium:

deployment "auto-deploy" {
  auto_approve = true  # Requires Premium

  inputs = {
    environment = "dev"
  }
}

Deferred Changes

Partial plans when too many unknown values:

# Stack handles deferred changes automatically
component "app" {
  source = "./modules/app"

  # Even with unknown values, stack can create partial plan
  inputs = {
    config = component.config.output  # May be unknown
  }
}

VCS Support

• GitHub
• GitLab
• Azure DevOps
• Bitbucket

Limits

• Maximum 20 deployments per stack
• Available in HCP Terraform only
• Requires Terraform 1.9+ for CLI compatibility

Use Cases

Multi-Region Deployment

Deploy same infrastructure pattern across multiple AWS regions.

Multi-Account Architecture

Deploy to multiple AWS accounts (dev, staging, prod) from single definition.

Multi-Tenant SaaS

Deploy isolated environments for each customer.

Disaster Recovery

Maintain synchronized infrastructure across primary and DR regions.

CLI Commands

# Initialize stack
terraform stack init

# Plan all deployments
terraform stack plan

# Apply specific deployment
terraform stack apply -target=deployment.prod-us-east

# Apply all deployments
terraform stack apply

Best Practices

1. Keep components modular: Each component should be self-contained 2. Use variables for differences: Environment-specific values through inputs 3. Test with staging first: Include staging deployment for validation 4. Monitor deployment order: Use depends_on for ordering 5. Limit deployment count: Stay within 20 deployment limit