Initial commit

skills/assets/templates/MODULE_TEMPLATE.md

@@ -0,0 +1,386 @@
+# Terraform Module Template
+
+This directory contains templates for creating well-structured Terraform modules.
+
+## Module Structure
+
+```
+module-name/
+├── main.tf           # Primary resource definitions
+├── variables.tf      # Input variables
+├── outputs.tf        # Output values
+├── versions.tf       # Version constraints
+├── README.md         # Module documentation
+└── examples/         # Usage examples
+    └── complete/
+        ├── main.tf
+        ├── variables.tf
+        └── outputs.tf
+```
+
+## Template Files
+
+### main.tf
+```hcl
+# Main resource definitions
+terraform {
+  # No backend configuration in modules
+}
+
+# Example: VPC Module
+resource "aws_vpc" "main" {
+  cidr_block           = var.vpc_cidr
+  enable_dns_hostnames = var.enable_dns_hostnames
+  enable_dns_support   = var.enable_dns_support
+  
+  tags = merge(
+    var.tags,
+    {
+      Name = var.name
+    }
+  )
+}
+
+# Use locals for computed values
+locals {
+  availability_zones = slice(data.aws_availability_zones.available.names, 0, var.az_count)
+}
+```
+
+### variables.tf
+```hcl
+variable "name" {
+  description = "Name to be used on all resources as prefix"
+  type        = string
+}
+
+variable "vpc_cidr" {
+  description = "CIDR block for VPC"
+  type        = string
+  
+  validation {
+    condition     = can(cidrhost(var.vpc_cidr, 0))
+    error_message = "Must be a valid IPv4 CIDR block."
+  }
+}
+
+variable "enable_dns_hostnames" {
+  description = "Enable DNS hostnames in the VPC"
+  type        = bool
+  default     = true
+}
+
+variable "tags" {
+  description = "A map of tags to add to all resources"
+  type        = map(string)
+  default     = {}
+}
+
+# For sensitive values
+variable "database_password" {
+  description = "Master password for the database"
+  type        = string
+  sensitive   = true
+}
+
+# With validation
+variable "environment" {
+  description = "Environment name"
+  type        = string
+  
+  validation {
+    condition     = contains(["dev", "staging", "prod"], var.environment)
+    error_message = "Environment must be one of: dev, staging, prod."
+  }
+}
+
+# Complex types
+variable "subnets" {
+  description = "Map of subnet configurations"
+  type = map(object({
+    cidr_block        = string
+    availability_zone = string
+    public            = bool
+  }))
+  default = {}
+}
+```
+
+### outputs.tf
+```hcl
+output "vpc_id" {
+  description = "The ID of the VPC"
+  value       = aws_vpc.main.id
+}
+
+output "vpc_cidr" {
+  description = "The CIDR block of the VPC"
+  value       = aws_vpc.main.cidr_block
+}
+
+output "private_subnet_ids" {
+  description = "List of IDs of private subnets"
+  value       = aws_subnet.private[*].id
+}
+
+# Sensitive outputs
+output "database_endpoint" {
+  description = "Database connection endpoint"
+  value       = aws_db_instance.main.endpoint
+  sensitive   = true
+}
+
+# Complex outputs
+output "subnet_details" {
+  description = "Detailed information about all subnets"
+  value = {
+    for subnet in aws_subnet.main :
+    subnet.id => {
+      cidr_block        = subnet.cidr_block
+      availability_zone = subnet.availability_zone
+      public            = subnet.map_public_ip_on_launch
+    }
+  }
+}
+```
+
+### versions.tf
+```hcl
+terraform {
+  required_version = ">= 1.3.0"
+  
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.0.0"
+    }
+  }
+}
+```
+
+### README.md Template
+```markdown
+# Module Name
+
+Brief description of what this module does.
+
+## Usage
+
+\`\`\`hcl
+module "example" {
+  source = "./modules/module-name"
+  
+  name             = "my-resource"
+  vpc_cidr         = "10.0.0.0/16"
+  environment      = "prod"
+  
+  tags = {
+    Environment = "prod"
+    Project     = "example"
+  }
+}
+\`\`\`
+
+## Examples
+
+- [Complete](./examples/complete) - Full example with all options
+
+## Requirements
+
+| Name | Version |
+|------|---------|
+| terraform | >= 1.3.0 |
+| aws | >= 5.0.0 |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| name | Resource name | `string` | n/a | yes |
+| vpc_cidr | VPC CIDR block | `string` | n/a | yes |
+| environment | Environment name | `string` | n/a | yes |
+| tags | Common tags | `map(string)` | `{}` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| vpc_id | VPC identifier |
+| private_subnet_ids | List of private subnet IDs |
+
+## Authors
+
+Module is maintained by [Your Team].
+
+## License
+
+Apache 2 Licensed. See LICENSE for full details.
+\`\`\`
+
+## Example: Complete Usage Example
+
+### examples/complete/main.tf
+```hcl
+module "vpc" {
+  source = "../../"
+  
+  name                 = "example-vpc"
+  vpc_cidr            = "10.0.0.0/16"
+  environment         = "dev"
+  enable_dns_hostnames = true
+  
+  tags = {
+    Environment = "dev"
+    Project     = "example"
+    ManagedBy   = "Terraform"
+  }
+}
+```
+
+### examples/complete/outputs.tf
+```hcl
+output "vpc_id" {
+  description = "The ID of the VPC"
+  value       = module.vpc.vpc_id
+}
+```
+
+### examples/complete/variables.tf
+```hcl
+variable "region" {
+  description = "AWS region"
+  type        = string
+  default     = "us-east-1"
+}
+```
+
+## Terragrunt Configuration Template
+
+### terragrunt.hcl (root)
+```hcl
+# Root terragrunt.hcl
+locals {
+  # Load account-level variables
+  account_vars = read_terragrunt_config(find_in_parent_folders("account.hcl"))
+  
+  # Load region-level variables  
+  region_vars = read_terragrunt_config(find_in_parent_folders("region.hcl"))
+  
+  # Load environment variables
+  environment_vars = read_terragrunt_config(find_in_parent_folders("env.hcl"))
+  
+  # Extract commonly used variables
+  account_name = local.account_vars.locals.account_name
+  account_id   = local.account_vars.locals.account_id
+  aws_region   = local.region_vars.locals.aws_region
+  environment  = local.environment_vars.locals.environment
+}
+
+# Generate provider configuration
+generate "provider" {
+  path      = "provider.tf"
+  if_exists = "overwrite_terragrunt"
+  contents  = <<EOF
+provider "aws" {
+  region = "${local.aws_region}"
+  
+  assume_role {
+    role_arn = "arn:aws:iam::${local.account_id}:role/TerraformRole"
+  }
+  
+  default_tags {
+    tags = {
+      Environment = "${local.environment}"
+      ManagedBy   = "Terragrunt"
+      Account     = "${local.account_name}"
+    }
+  }
+}
+EOF
+}
+
+# Configure S3 backend
+remote_state {
+  backend = "s3"
+  
+  generate = {
+    path      = "backend.tf"
+    if_exists = "overwrite_terragrunt"
+  }
+  
+  config = {
+    bucket         = "${local.account_name}-terraform-state"
+    key            = "${path_relative_to_include()}/terraform.tfstate"
+    region         = local.aws_region
+    encrypt        = true
+    dynamodb_table = "${local.account_name}-terraform-lock"
+    
+    s3_bucket_tags = {
+      Name        = "Terraform State"
+      Environment = local.environment
+    }
+    
+    dynamodb_table_tags = {
+      Name        = "Terraform Lock"
+      Environment = local.environment
+    }
+  }
+}
+
+# Global inputs for all modules
+inputs = {
+  account_name = local.account_name
+  account_id   = local.account_id
+  aws_region   = local.aws_region
+  environment  = local.environment
+}
+```
+
+### terragrunt.hcl (module level)
+```hcl
+# Include root configuration
+include "root" {
+  path = find_in_parent_folders()
+}
+
+# Define terraform source
+terraform {
+  source = "git::https://github.com/company/terraform-modules.git//vpc?ref=v1.0.0"
+}
+
+# Dependencies on other modules
+dependency "iam" {
+  config_path = "../iam"
+  
+  mock_outputs = {
+    role_arn = "arn:aws:iam::123456789012:role/mock"
+  }
+  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
+}
+
+# Module-specific inputs
+inputs = {
+  name     = "my-vpc"
+  vpc_cidr = "10.0.0.0/16"
+  
+  # Use dependency outputs
+  iam_role_arn = dependency.iam.outputs.role_arn
+  
+  # Module-specific tags
+  tags = {
+    Component = "networking"
+    Module    = "vpc"
+  }
+}
+```
+
+## Best Practices
+
+1. **Always include descriptions** for variables and outputs
+2. **Use validation blocks** for important variables
+3. **Mark sensitive values** as sensitive
+4. **Provide sensible defaults** where appropriate
+5. **Document everything** in README
+6. **Include usage examples** in examples/ directory
+7. **Version your modules** using Git tags
+8. **Test modules** before tagging new versions