aigroup-workflow 2.1.2 → 2.2.1

package/skills/infra/terraform-engineer/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: terraform-engineer
+description: Use when implementing infrastructure as code with Terraform across AWS, Azure, or GCP. Invoke for module development (create reusable modules, manage module versioning), state management (migrate backends, import existing resources, resolve state conflicts), provider configuration, multi-environment workflows, and infrastructure testing.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: infrastructure
+  triggers: Terraform, infrastructure as code, IaC, terraform module, terraform state, AWS provider, Azure provider, GCP provider, terraform plan, terraform apply
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: cloud-architect, devops-engineer, kubernetes-specialist
+---
+
+# Terraform Engineer
+
+Senior Terraform engineer specializing in infrastructure as code across AWS, Azure, and GCP with expertise in modular design, state management, and production-grade patterns.
+
+## Core Workflow
+
+1. **Analyze infrastructure** — Review requirements, existing code, cloud platforms
+2. **Design modules** — Create composable, validated modules with clear interfaces
+3. **Implement state** — Configure remote backends with locking and encryption
+4. **Secure infrastructure** — Apply security policies, least privilege, encryption
+5. **Validate** — Run `terraform fmt` and `terraform validate`, then `tflint`; if any errors are reported, fix them and re-run until all checks pass cleanly before proceeding
+6. **Plan and apply** — Run `terraform plan -out=tfplan`, review output carefully, then `terraform apply tfplan`; if the plan fails, see error recovery below
+
+### Error Recovery
+
+**Validation failures (step 5):** Fix reported errors → re-run `terraform validate` → repeat until clean. For `tflint` warnings, address rule violations before proceeding.
+
+**Plan failures (step 6):**
+- *State drift* — Run `terraform refresh` to reconcile state with real resources, or use `terraform state rm` / `terraform import` to realign specific resources, then re-plan.
+- *Provider auth errors* — Verify credentials, environment variables, and provider configuration blocks; re-run `terraform init` if provider plugins are stale, then re-plan.
+- *Dependency / ordering errors* — Add explicit `depends_on` references or restructure module outputs to resolve unknown values, then re-plan.
+
+After any fix, return to step 5 to re-validate before re-running the plan.
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Modules | `references/module-patterns.md` | Creating modules, inputs/outputs, versioning |
+| State | `references/state-management.md` | Remote backends, locking, workspaces, migrations |
+| Providers | `references/providers.md` | AWS/Azure/GCP configuration, authentication |
+| Testing | `references/testing.md` | terraform plan, terratest, policy as code |
+| Best Practices | `references/best-practices.md` | DRY patterns, naming, security, cost tracking |
+
+## Constraints
+
+### MUST DO
+- Use semantic versioning and pin provider versions
+- Enable remote state with locking and encryption
+- Validate inputs with validation blocks
+- Use consistent naming conventions and tag all resources
+- Document module interfaces
+- Run `terraform fmt` and `terraform validate`
+
+### MUST NOT DO
+- Store secrets in plain text or hardcode environment-specific values
+- Use local state for production or skip state locking
+- Mix provider versions without constraints
+- Create circular module dependencies or skip input validation
+- Commit `.terraform` directories
+
+## Code Examples
+
+### Minimal Module Structure
+
+**`main.tf`**
+```hcl
+resource "aws_s3_bucket" "this" {
+  bucket = var.bucket_name
+  tags   = var.tags
+}
+```
+
+**`variables.tf`**
+```hcl
+variable "bucket_name" {
+  description = "Name of the S3 bucket"
+  type        = string
+
+  validation {
+    condition     = length(var.bucket_name) > 3
+    error_message = "bucket_name must be longer than 3 characters."
+  }
+}
+
+variable "tags" {
+  description = "Tags to apply to all resources"
+  type        = map(string)
+  default     = {}
+}
+```
+
+**`outputs.tf`**
+```hcl
+output "bucket_id" {
+  description = "ID of the created S3 bucket"
+  value       = aws_s3_bucket.this.id
+}
+```
+
+### Remote Backend Configuration (S3 + DynamoDB)
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket         = "my-tf-state"
+    key            = "env/prod/terraform.tfstate"
+    region         = "us-east-1"
+    encrypt        = true
+    dynamodb_table = "terraform-lock"
+  }
+}
+```
+
+### Provider Version Pinning
+
+```hcl
+terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+    azurerm = {
+      source  = "hashicorp/azurerm"
+      version = "~> 3.0"
+    }
+  }
+}
+```
+
+## Output Format
+
+When implementing Terraform solutions, provide: module structure (`main.tf`, `variables.tf`, `outputs.tf`), backend and provider configuration, example usage with tfvars, and a brief explanation of design decisions.

package/skills/infra/terraform-engineer/references/best-practices.md

@@ -0,0 +1,583 @@
+# Terraform Best Practices
+
+## DRY Principles
+
+**Use Modules for Reusability**
+```hcl
+# Bad - Repeated code
+resource "aws_vpc" "app1" {
+  cidr_block = "10.0.0.0/16"
+  enable_dns_hostnames = true
+  tags = { Name = "app1-vpc", Environment = "prod" }
+}
+
+resource "aws_vpc" "app2" {
+  cidr_block = "10.1.0.0/16"
+  enable_dns_hostnames = true
+  tags = { Name = "app2-vpc", Environment = "prod" }
+}
+
+# Good - Use module
+module "vpc_app1" {
+  source = "./modules/vpc"
+
+  name       = "app1"
+  cidr_block = "10.0.0.0/16"
+  environment = "prod"
+}
+
+module "vpc_app2" {
+  source = "./modules/vpc"
+
+  name       = "app2"
+  cidr_block = "10.1.0.0/16"
+  environment = "prod"
+}
+```
+
+**Use Locals for Repeated Values**
+```hcl
+locals {
+  common_tags = {
+    Environment = var.environment
+    ManagedBy   = "Terraform"
+    Project     = var.project_name
+    CostCenter  = var.cost_center
+  }
+
+  name_prefix = "${var.project_name}-${var.environment}"
+
+  # Computed locals
+  vpc_cidr = var.environment == "production" ? "10.0.0.0/16" : "10.1.0.0/16"
+
+  # Complex data structures
+  availability_zones = slice(data.aws_availability_zones.available.names, 0, var.az_count)
+}
+
+resource "aws_vpc" "main" {
+  cidr_block = local.vpc_cidr
+  tags       = merge(local.common_tags, { Name = "${local.name_prefix}-vpc" })
+}
+```
+
+**Use Data Sources Instead of Hardcoding**
+```hcl
+# Bad - Hardcoded AMI
+resource "aws_instance" "web" {
+  ami           = "ami-0c55b159cbfafe1f0"
+  instance_type = "t3.micro"
+}
+
+# Good - Dynamic AMI lookup
+data "aws_ami" "amazon_linux_2" {
+  most_recent = true
+  owners      = ["amazon"]
+
+  filter {
+    name   = "name"
+    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
+  }
+
+  filter {
+    name   = "virtualization-type"
+    values = ["hvm"]
+  }
+}
+
+resource "aws_instance" "web" {
+  ami           = data.aws_ami.amazon_linux_2.id
+  instance_type = "t3.micro"
+}
+```
+
+**Use for_each for Multiple Similar Resources**
+```hcl
+# Bad - Duplicated resources
+resource "aws_subnet" "private_1" {
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = "10.0.1.0/24"
+  availability_zone = "us-east-1a"
+}
+
+resource "aws_subnet" "private_2" {
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = "10.0.2.0/24"
+  availability_zone = "us-east-1b"
+}
+
+# Good - Use for_each
+variable "private_subnets" {
+  type = map(object({
+    cidr_block = string
+    az         = string
+  }))
+  default = {
+    subnet1 = { cidr_block = "10.0.1.0/24", az = "us-east-1a" }
+    subnet2 = { cidr_block = "10.0.2.0/24", az = "us-east-1b" }
+  }
+}
+
+resource "aws_subnet" "private" {
+  for_each = var.private_subnets
+
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = each.value.cidr_block
+  availability_zone = each.value.az
+
+  tags = {
+    Name = "${var.name}-private-${each.key}"
+  }
+}
+```
+
+## Naming Conventions
+
+**Resource Naming**
+```hcl
+# Pattern: {resource_type}_{descriptive_name}
+
+# Good examples
+resource "aws_vpc" "main" {}
+resource "aws_subnet" "private" {}
+resource "aws_security_group" "web" {}
+resource "aws_instance" "app" {}
+
+# Avoid generic names
+resource "aws_vpc" "vpc" {}          # Bad
+resource "aws_subnet" "subnet" {}    # Bad
+resource "aws_vpc" "this" {}         # Use in modules only
+```
+
+**AWS Resource Name Tags**
+```hcl
+locals {
+  # Pattern: {project}-{environment}-{resource}-{identifier}
+  name_prefix = "${var.project_name}-${var.environment}"
+}
+
+resource "aws_vpc" "main" {
+  cidr_block = var.cidr_block
+
+  tags = merge(local.common_tags, {
+    Name = "${local.name_prefix}-vpc"
+  })
+}
+
+resource "aws_subnet" "private" {
+  for_each = var.private_subnets
+
+  vpc_id     = aws_vpc.main.id
+  cidr_block = each.value.cidr_block
+
+  tags = merge(local.common_tags, {
+    Name = "${local.name_prefix}-private-${each.key}"
+    Type = "private"
+  })
+}
+
+resource "aws_security_group" "web" {
+  name   = "${local.name_prefix}-web-sg"
+  vpc_id = aws_vpc.main.id
+
+  tags = merge(local.common_tags, {
+    Name = "${local.name_prefix}-web-sg"
+  })
+}
+```
+
+**Variable Naming**
+```hcl
+# Use snake_case for all names
+variable "instance_type" {}      # Good
+variable "instanceType" {}       # Bad
+variable "InstanceType" {}       # Bad
+
+# Be descriptive
+variable "vpc_cidr_block" {}     # Good
+variable "cidr" {}               # Too vague
+
+# Boolean variables should be questions
+variable "enable_nat_gateway" {} # Good
+variable "nat_gateway" {}        # Ambiguous
+
+# Plural for lists/maps
+variable "availability_zones" {} # Good
+variable "private_subnets" {}    # Good
+```
+
+**File Naming**
+```
+# Standard structure
+main.tf           # Primary resource definitions
+variables.tf      # Input variables
+outputs.tf        # Output values
+versions.tf       # Terraform and provider versions
+backend.tf        # Backend configuration (optional)
+locals.tf         # Local values (optional)
+data.tf           # Data sources (optional)
+
+# Resource-specific files for complex modules
+vpc.tf
+subnets.tf
+security_groups.tf
+route_tables.tf
+```
+
+## Security Best Practices
+
+**Secret Management**
+```hcl
+# Bad - Secrets in plain text
+variable "db_password" {
+  default = "SuperSecret123!"  # NEVER DO THIS
+}
+
+# Good - Use sensitive variables
+variable "db_password" {
+  description = "Database password"
+  type        = string
+  sensitive   = true
+  # No default - must be provided
+}
+
+# Better - Use secrets manager
+data "aws_secretsmanager_secret_version" "db_password" {
+  secret_id = "prod/db/password"
+}
+
+resource "aws_db_instance" "main" {
+  password = data.aws_secretsmanager_secret_version.db_password.secret_string
+}
+```
+
+**Encryption at Rest**
+```hcl
+# S3 bucket with encryption
+resource "aws_s3_bucket" "data" {
+  bucket = "my-data-bucket"
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "data" {
+  bucket = aws_s3_bucket.data.id
+
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm     = "aws:kms"
+      kms_master_key_id = aws_kms_key.s3.arn
+    }
+    bucket_key_enabled = true
+  }
+}
+
+# EBS volume encryption
+resource "aws_ebs_volume" "data" {
+  availability_zone = "us-east-1a"
+  size              = 100
+  encrypted         = true
+  kms_key_id        = aws_kms_key.ebs.arn
+}
+
+# RDS encryption
+resource "aws_db_instance" "main" {
+  storage_encrypted   = true
+  kms_key_id          = aws_kms_key.rds.arn
+}
+```
+
+**Least Privilege IAM**
+```hcl
+# Bad - Overly permissive
+data "aws_iam_policy_document" "bad" {
+  statement {
+    effect    = "Allow"
+    actions   = ["*"]
+    resources = ["*"]
+  }
+}
+
+# Good - Specific permissions
+data "aws_iam_policy_document" "good" {
+  statement {
+    effect = "Allow"
+    actions = [
+      "s3:GetObject",
+      "s3:PutObject"
+    ]
+    resources = [
+      "${aws_s3_bucket.data.arn}/*"
+    ]
+  }
+
+  statement {
+    effect = "Allow"
+    actions = [
+      "s3:ListBucket"
+    ]
+    resources = [
+      aws_s3_bucket.data.arn
+    ]
+  }
+}
+```
+
+**Network Security**
+```hcl
+# Security group with restricted access
+resource "aws_security_group" "web" {
+  name        = "${var.name}-web-sg"
+  description = "Security group for web servers"
+  vpc_id      = aws_vpc.main.id
+
+  # Bad - Too permissive
+  # ingress {
+  #   from_port   = 0
+  #   to_port     = 65535
+  #   protocol    = "tcp"
+  #   cidr_blocks = ["0.0.0.0/0"]
+  # }
+
+  # Good - Specific rules
+  ingress {
+    description = "HTTPS from internet"
+    from_port   = 443
+    to_port     = 443
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  ingress {
+    description     = "HTTP from ALB"
+    from_port       = 80
+    to_port         = 80
+    protocol        = "tcp"
+    security_groups = [aws_security_group.alb.id]
+  }
+
+  egress {
+    description = "All outbound"
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}
+```
+
+## Resource Tagging
+
+**Consistent Tagging Strategy**
+```hcl
+locals {
+  # Required tags for all resources
+  required_tags = {
+    Environment = var.environment
+    ManagedBy   = "Terraform"
+    Project     = var.project_name
+    CostCenter  = var.cost_center
+    Owner       = var.owner_email
+  }
+
+  # Optional tags
+  optional_tags = {
+    Repository = "github.com/org/repo"
+    Terraform  = "true"
+  }
+
+  # Merge all tags
+  common_tags = merge(local.required_tags, local.optional_tags, var.additional_tags)
+}
+
+# Use provider default tags
+provider "aws" {
+  region = var.aws_region
+
+  default_tags {
+    tags = local.common_tags
+  }
+}
+
+# Resource-specific tags
+resource "aws_instance" "app" {
+  ami           = data.aws_ami.amazon_linux_2.id
+  instance_type = var.instance_type
+
+  tags = merge(local.common_tags, {
+    Name = "${var.name}-app"
+    Role = "application"
+    Backup = "daily"
+  })
+}
+```
+
+## Cost Optimization
+
+**Cost-Aware Resource Sizing**
+```hcl
+variable "environment" {
+  type = string
+}
+
+locals {
+  # Environment-based sizing
+  instance_type = {
+    production  = "t3.large"
+    staging     = "t3.medium"
+    development = "t3.micro"
+  }
+
+  rds_instance_class = {
+    production  = "db.r5.xlarge"
+    staging     = "db.t3.medium"
+    development = "db.t3.micro"
+  }
+
+  enable_multi_az = var.environment == "production" ? true : false
+}
+
+resource "aws_instance" "app" {
+  instance_type = local.instance_type[var.environment]
+}
+
+resource "aws_db_instance" "main" {
+  instance_class = local.rds_instance_class[var.environment]
+  multi_az       = local.enable_multi_az
+}
+```
+
+**Lifecycle Management**
+```hcl
+resource "aws_instance" "app" {
+  ami           = data.aws_ami.amazon_linux_2.id
+  instance_type = var.instance_type
+
+  lifecycle {
+    create_before_destroy = true
+    prevent_destroy       = var.environment == "production"
+    ignore_changes        = [ami, user_data]
+  }
+}
+
+# S3 lifecycle rules for cost savings
+resource "aws_s3_bucket_lifecycle_configuration" "data" {
+  bucket = aws_s3_bucket.data.id
+
+  rule {
+    id     = "transition-to-ia"
+    status = "Enabled"
+
+    transition {
+      days          = 30
+      storage_class = "STANDARD_IA"
+    }
+
+    transition {
+      days          = 90
+      storage_class = "GLACIER"
+    }
+
+    expiration {
+      days = 365
+    }
+  }
+}
+```
+
+**Resource Scheduling**
+```hcl
+# Auto-scaling schedule for cost savings
+resource "aws_autoscaling_schedule" "scale_down_evening" {
+  scheduled_action_name  = "scale-down-evening"
+  min_size               = 1
+  max_size               = 1
+  desired_capacity       = 1
+  recurrence             = "0 20 * * MON-FRI"
+  autoscaling_group_name = aws_autoscaling_group.app.name
+}
+
+resource "aws_autoscaling_schedule" "scale_up_morning" {
+  scheduled_action_name  = "scale-up-morning"
+  min_size               = 3
+  max_size               = 10
+  desired_capacity       = 3
+  recurrence             = "0 7 * * MON-FRI"
+  autoscaling_group_name = aws_autoscaling_group.app.name
+}
+```
+
+## Code Organization
+
+**Directory Structure**
+```
+terraform/
+├── environments/
+│   ├── production/
+│   │   ├── main.tf
+│   │   ├── variables.tf
+│   │   ├── terraform.tfvars
+│   │   └── backend.tf
+│   ├── staging/
+│   └── development/
+├── modules/
+│   ├── vpc/
+│   ├── eks/
+│   └── rds/
+├── global/
+│   ├── iam/
+│   └── route53/
+└── README.md
+```
+
+**Module Best Practices**
+```hcl
+# Keep modules small and focused
+# modules/vpc/main.tf - Does ONE thing well
+
+# Clear input/output contracts
+# modules/vpc/variables.tf
+variable "cidr_block" {
+  description = "CIDR block for VPC"
+  type        = string
+  validation { ... }
+}
+
+# modules/vpc/outputs.tf
+output "vpc_id" {
+  description = "ID of the VPC"
+  value       = aws_vpc.this.id
+}
+
+# Version all modules
+# modules/vpc/versions.tf
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+```
+
+## Best Practices Checklist
+
+- [ ] Use remote state with locking
+- [ ] Pin Terraform and provider versions
+- [ ] Validate all input variables
+- [ ] Use consistent naming conventions
+- [ ] Tag all resources for cost tracking
+- [ ] Encrypt sensitive data at rest and in transit
+- [ ] Implement least privilege IAM policies
+- [ ] Use modules for reusable components
+- [ ] Document module interfaces
+- [ ] Run terraform fmt before commit
+- [ ] Run terraform validate in CI/CD
+- [ ] Review plan output before apply
+- [ ] Use data sources instead of hardcoding
+- [ ] Implement automated testing
+- [ ] Use for_each instead of count
+- [ ] Avoid hardcoded secrets
+- [ ] Enable logging and monitoring
+- [ ] Implement cost optimization strategies
+- [ ] Use lifecycle rules appropriately
+- [ ] Keep modules focused and single-purpose