oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-tf-infra/resources/cost-optimization.md

@@ -0,0 +1,574 @@
+# Cost Optimization Examples
+
+Terraform patterns for optimizing cloud infrastructure costs across AWS, GCP, and Azure.
+
+## Environment-Based Resource Sizing
+
+Dynamically size resources based on environment to reduce non-production costs.
+
+```hcl
+# locals.tf
+locals {
+  # Instance sizing by environment
+  instance_sizes = {
+    production  = "t3.large"
+    staging     = "t3.medium"
+    development = "t3.micro"
+  }
+
+  # Database sizing by environment  
+  db_instance_classes = {
+    production  = "db.r5.xlarge"
+    staging     = "db.t3.medium"
+    development = "db.t3.micro"
+  }
+
+  # Enable HA only in production
+  enable_multi_az = var.environment == "production" ? true : false
+  enable_backups  = var.environment == "production" ? true : false
+}
+
+# Compute resource with environment-based sizing
+resource "aws_instance" "app" {
+  instance_type = local.instance_sizes[var.environment]
+  # ...
+}
+
+# Database with environment-based sizing
+resource "aws_db_instance" "main" {
+  instance_class = local.db_instance_classes[var.environment]
+  multi_az       = local.enable_multi_az
+  # ...
+}
+```
+
+## Reserved Instances & Savings Plans
+
+### AWS Reserved Instances
+
+```hcl
+# Note: Reserved Instances are purchased via Console or API, not Terraform
+# Use tags to track RI-eligible resources
+resource "aws_instance" "app" {
+  instance_type = "t3.medium"
+  
+  tags = {
+    Name        = "app-server"
+    RIEligible  = "true"
+    Environment = "production"
+  }
+}
+```
+
+### GCP Committed Use Discounts (CUDs)
+
+```hcl
+# Resource-based CUDs can be purchased directly via Terraform.
+# WARNING: commitments are binding contracts — they cannot be updated
+# or deleted once created. Review amounts carefully before apply.
+resource "google_compute_region_commitment" "cud" {
+  name   = "app-cud"
+  region = var.region
+  plan   = "TWELVE_MONTH" # or THIRTY_SIX_MONTH
+
+  resources {
+    type   = "VCPU"
+    amount = "4"
+  }
+  resources {
+    type   = "MEMORY"
+    amount = "16"
+  }
+}
+
+# Tag commitment-covered resources for cost tracking
+resource "google_compute_instance" "app" {
+  machine_type = "n2-standard-4"
+
+  labels = {
+    cud_covered = "true"
+  }
+}
+```
+
+### Azure Reserved VM Instances
+
+```hcl
+# Note: Reserved Instances are purchased separately
+# Tag resources for RI tracking
+resource "azurerm_linux_virtual_machine" "app" {
+  size = "Standard_D4s_v3"
+  
+  tags = {
+    RIEligible = "true"
+  }
+}
+```
+
+## Spot/Preemptible Instances
+
+For fault-tolerant workloads, use spot instances for up to 90% savings.
+
+### AWS Spot Instances
+
+```hcl
+resource "aws_launch_template" "spot" {
+  name_prefix   = "spot-"
+  image_id      = data.aws_ami.amazon_linux.id
+  instance_type = "t3.medium"
+
+  # Mixed policy controls On-Demand/Spot distribution; omit InstanceMarketOptions.
+}
+
+resource "aws_autoscaling_group" "spot" {
+  name                = "spot-asg"
+  vpc_zone_identifier = var.private_subnets
+  target_group_arns   = [aws_lb_target_group.app.arn]
+  health_check_type   = "ELB"
+
+  min_size         = 1
+  max_size         = 10
+  desired_capacity = 3
+
+  # Mixed instances policy for spot diversification
+  mixed_instances_policy {
+    launch_template {
+      launch_template_specification {
+        launch_template_id = aws_launch_template.spot.id
+      }
+
+      override {
+        instance_type = "t3.medium"
+      }
+      override {
+        instance_type = "t3a.medium"
+      }
+      override {
+        instance_type = "m5.large"
+      }
+    }
+
+    instances_distribution {
+      on_demand_base_capacity                  = 1
+      on_demand_percentage_above_base_capacity = 0
+      spot_allocation_strategy                 = "capacity-optimized"
+    }
+  }
+}
+```
+
+### GCP Spot VMs
+
+```hcl
+# Spot VMs are the recommended successor to preemptible VMs (no 24h limit).
+# `preemptible = true` alone creates a legacy preemptible VM;
+# `provisioning_model = "SPOT"` is what makes it a Spot VM.
+resource "google_compute_instance" "worker" {
+  name         = "worker"
+  machine_type = "n2-standard-4"
+  zone         = var.zone
+
+  scheduling {
+    preemptible                 = true
+    automatic_restart           = false
+    provisioning_model          = "SPOT"
+    instance_termination_action = "STOP"
+  }
+}
+
+# Separate cost lever: start/stop schedule for dev/test VMs (off-hours shutdown)
+resource "google_compute_resource_policy" "business_hours" {
+  name   = "business-hours-schedule"
+  region = var.region
+
+  instance_schedule_policy {
+    vm_start_schedule {
+      schedule = "0 8 * * MON-FRI"
+    }
+    vm_stop_schedule {
+      schedule = "0 20 * * MON-FRI"
+    }
+    time_zone = "America/New_York"
+  }
+}
+```
+
+### Azure Spot VMs
+
+```hcl
+resource "azurerm_linux_virtual_machine" "spot" {
+  name                = "spot-vm"
+  resource_group_name = var.resource_group_name
+  location            = var.location
+  size                = "Standard_D4s_v3"
+  priority            = "Spot"
+  eviction_policy     = "Deallocate"  # or "Delete"
+
+  # Only create if spot price is acceptable
+  max_bid_price = "0.1"
+}
+```
+
+## Autoscaling Schedules
+
+Scale down during non-business hours to reduce costs.
+
+### AWS Autoscaling Schedule
+
+```hcl
+# Scale down in the evening
+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-THU"  # Friday is handled by weekend_shutdown
+  autoscaling_group_name = aws_autoscaling_group.app.name
+}
+
+# Scale up in the morning
+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"   # 7 AM weekdays
+  autoscaling_group_name = aws_autoscaling_group.app.name
+}
+
+# Weekend shutdown
+resource "aws_autoscaling_schedule" "weekend_shutdown" {
+  scheduled_action_name  = "weekend-shutdown"
+  min_size               = 0
+  max_size               = 0
+  desired_capacity       = 0
+  recurrence             = "0 18 * * FRI"      # 6 PM Friday
+  autoscaling_group_name = aws_autoscaling_group.app.name
+}
+```
+
+### GCP Autoscaler Schedules
+
+```hcl
+resource "google_compute_autoscaler" "app" {
+  name   = "app-autoscaler"
+  zone   = var.zone
+  target = google_compute_instance_group_manager.app.id
+
+  autoscaling_policy {
+    min_replicas    = 1
+    max_replicas    = 10
+    cooldown_period = 60
+
+    cpu_utilization {
+      target = 0.6
+    }
+
+    scaling_schedules {
+      name               = "scale-down-evening"
+      description        = "Scale down in the evening"
+      min_required_replicas = 1
+      schedule           = "0 20 * * 1-5"  # 8 PM weekdays
+      time_zone          = "America/New_York"
+      duration_sec       = 39600  # 11 hours
+    }
+
+    scaling_schedules {
+      name               = "scale-up-morning"
+      description        = "Scale up in the morning"
+      min_required_replicas = 3
+      schedule           = "0 7 * * 1-5"   # 7 AM weekdays
+      time_zone          = "America/New_York"
+      duration_sec       = 46800  # 13 hours
+    }
+  }
+}
+```
+
+## Storage Lifecycle Rules
+
+Transition data to cheaper storage classes based on age.
+
+### AWS S3 Lifecycle Rules
+
+```hcl
+resource "aws_s3_bucket_lifecycle_configuration" "data" {
+  bucket = aws_s3_bucket.data.id
+
+  rule {
+    id     = "transition-to-ia"
+    status = "Enabled"
+
+    filter {
+      prefix = "logs/"
+    }
+
+    # Transition to Infrequent Access after 30 days
+    transition {
+      days          = 30
+      storage_class = "STANDARD_IA"
+    }
+
+    # Transition to Glacier after 90 days
+    transition {
+      days          = 90
+      storage_class = "GLACIER"
+    }
+
+    # Delete after 1 year
+    expiration {
+      days = 365
+    }
+
+    # Clean up incomplete multipart uploads
+    abort_incomplete_multipart_upload {
+      days_after_initiation = 7
+    }
+  }
+
+  # Rule for temporary data
+  rule {
+    id     = "delete-temp-data"
+    status = "Enabled"
+
+    filter {
+      prefix = "temp/"
+    }
+
+    expiration {
+      days = 7
+    }
+  }
+}
+
+# Enable Intelligent-Tiering for automatic cost optimization
+resource "aws_s3_bucket_intelligent_tiering_configuration" "data" {
+  bucket = aws_s3_bucket.data.id
+  name   = "EntireBucket"
+
+  tiering {
+    access_tier = "ARCHIVE_ACCESS"
+    days        = 90
+  }
+
+  tiering {
+    access_tier = "DEEP_ARCHIVE_ACCESS"
+    days        = 180
+  }
+}
+```
+
+### GCP Storage Lifecycle Rules
+
+```hcl
+resource "google_storage_bucket" "data" {
+  name          = "${var.project_id}-data"
+  location      = var.region
+  storage_class = "STANDARD"
+
+  lifecycle_rule {
+    condition {
+      age = 30
+    }
+    action {
+      type          = "SetStorageClass"
+      storage_class = "NEARLINE"
+    }
+  }
+
+  lifecycle_rule {
+    condition {
+      age = 90
+    }
+    action {
+      type          = "SetStorageClass"
+      storage_class = "COLDLINE"
+    }
+  }
+
+  lifecycle_rule {
+    condition {
+      age = 365
+    }
+    action {
+      type = "Delete"
+    }
+  }
+}
+```
+
+### Azure Blob Storage Lifecycle
+
+```hcl
+resource "azurerm_storage_management_policy" "data" {
+  storage_account_id = azurerm_storage_account.data.id
+
+  rule {
+    name    = "transition-to-cool"
+    enabled = true
+    filters {
+      prefix_match = ["logs/"]
+      blob_types   = ["blockBlob"]
+    }
+    actions {
+      base_blob {
+        tier_to_cool_after_days_since_modification_greater_than    = 30
+        tier_to_archive_after_days_since_modification_greater_than = 90
+        delete_after_days_since_modification_greater_than          = 365
+      }
+      snapshot {
+        delete_after_days_since_creation_greater_than = 30
+      }
+    }
+  }
+}
+```
+
+## Cost Allocation Tags
+
+Tag all resources for cost tracking and chargeback.
+
+### AWS Cost Allocation Tags
+
+```hcl
+locals {
+  common_tags = {
+    Environment     = var.environment
+    Project         = var.project_name
+    Owner           = var.team_email
+    CostCenter      = var.cost_center
+    ManagedBy       = "terraform"
+  }
+}
+
+# Apply tags to all resources
+resource "aws_instance" "app" {
+  ami           = data.aws_ami.amazon_linux.id
+  instance_type = "t3.medium"
+
+  tags = local.common_tags
+}
+
+resource "aws_db_instance" "main" {
+  identifier     = "${var.project_name}-db"
+  instance_class = "db.t3.medium"
+
+  tags = local.common_tags
+}
+
+# Activate cost allocation tags (run once per account)
+resource "aws_ce_cost_allocation_tag" "environment" {
+  tag_key = "Environment"
+  status  = "Active"
+}
+
+resource "aws_ce_cost_allocation_tag" "project" {
+  tag_key = "Project"
+  status  = "Active"
+}
+```
+
+### GCP Labels
+
+```hcl
+locals {
+  common_labels = {
+    environment = var.environment
+    project     = var.project_name
+    owner       = var.team_label # validated lowercase label ID, not an email
+    cost-center = var.cost_center
+    managed-by  = "terraform"
+  }
+}
+
+resource "google_compute_instance" "app" {
+  name         = "app-server"
+  machine_type = "n2-standard-4"
+
+  labels = local.common_labels
+}
+
+# Budget alerts (configure BigQuery billing export separately)
+resource "google_billing_budget" "monthly" {
+  billing_account = var.billing_account
+  display_name    = "Monthly Budget"
+
+  amount {
+    specified_amount {
+      currency_code = "USD"
+      units         = "1000"
+    }
+  }
+
+  threshold_rules {
+    threshold_percent = 0.5
+  }
+  threshold_rules {
+    threshold_percent = 0.9
+  }
+}
+```
+
+### Azure Tags
+
+```hcl
+locals {
+  common_tags = {
+    Environment = var.environment
+    Project     = var.project_name
+    Owner       = var.team_email
+    CostCenter  = var.cost_center
+    ManagedBy   = "terraform"
+  }
+}
+
+resource "azurerm_linux_virtual_machine" "app" {
+  name                = "app-vm"
+  resource_group_name = var.resource_group_name
+  location            = var.location
+  size                = "Standard_D4s_v3"
+
+  tags = local.common_tags
+}
+
+# Cost Management Budget
+resource "azurerm_consumption_budget_resource_group" "monthly" {
+  name              = "monthly-budget"
+  resource_group_id = var.resource_group_id
+  amount            = 1000
+  time_grain        = "Monthly"
+
+  time_period {
+    start_date = "2024-01-01T00:00:00Z"
+    end_date   = "2024-12-31T00:00:00Z"
+  }
+
+  notification {
+    enabled        = true
+    threshold      = 90
+    operator       = "GreaterThan"
+    contact_emails = [var.team_email]
+  }
+}
+```
+
+## Cost Estimation Before Apply
+
+Use Infracost to turn `terraform plan` into a monthly cost estimate, locally or as a CI diff comment:
+
+```bash
+infracost breakdown --path .          # cost of current config
+infracost diff --path . --compare-to infracost-base.json  # cost delta for a change
+```
+
+## Best Practices Summary
+
+1. **Use environment-based sizing** - Smaller instances for dev/staging
+2. **Reserved capacity for production** - 1-3 year commitments for predictable workloads
+3. **Spot instances for fault-tolerant workloads** - Up to 90% savings
+4. **Scheduled scaling** - Scale down during off-hours
+5. **Storage lifecycle policies** - Automate transitions to cheaper tiers
+6. **Cost allocation tags** - Track and optimize spending
+7. **Right-sizing** - Use the smallest instance that meets performance needs
+8. **Auto-shutdown** - Stop dev/test resources when not in use
+9. **Estimate before apply** - Run Infracost (or provider pricing calculators) on every plan that adds resources

package/skills/oma-tf-infra/resources/error-playbook.md

@@ -0,0 +1,68 @@
+# TF Infra Agent: Error Recovery Playbook
+
+## State Lock Error
+**Symptom:** `Error acquiring the state lock`
+**Recovery:**
+1. Read the lock owner, operation, timestamp and ID from the original lock error.
+2. Confirm the owning local/remote job has stopped; do not assume a missing local process means a remote apply ended.
+3. Only for a confirmed stale lock, use `terraform force-unlock <LOCK_ID>`. This removes a lock; it does not inspect ownership.
+
+## Resource Already Exists
+**Symptom:** `Error: already exists` on create
+**Recovery:**
+1. Import the existing resource. On Terraform >= 1.5, prefer a config-driven `import` block (plannable and reviewable):
+   ```hcl
+   import {
+     to = aws_s3_bucket.assets
+     id = "my-existing-bucket"
+   }
+   ```
+   On older versions, use the CLI: `terraform import <resource_type>.<name> <id>`
+2. Verify imported state matches config: `terraform plan`
+3. Adjust config if drift exists
+4. For refactors, use `moved` blocks (rename/move without recreate) and `removed` blocks (TF >= 1.7, drop from state without destroying)
+
+## Permission Denied
+**Symptom:** `AccessDenied`, `403 Forbidden`, `insufficient permissions`
+**Recovery:**
+1. Check current identity:
+   - AWS: `aws sts get-caller-identity`
+   - GCP: `gcloud auth list`
+   - Azure: `az account show`
+   - OCI: `oci iam region list`
+2. Verify IAM policies attached to the identity
+3. Add missing permissions following least privilege
+
+## Provider Version Conflict
+**Symptom:** `Incompatible provider version` or `Could not retrieve the list of available versions`
+**Recovery:**
+1. Update version constraint in `versions.tf`
+2. Run `terraform init -upgrade`
+3. Review changelog for breaking changes
+
+## Drift Detected
+**Symptom:** `terraform plan` shows unexpected changes on existing resources
+**Recovery:**
+1. Run `terraform plan -refresh-only` to review drift (the standalone `terraform refresh` command is deprecated — it updates state without confirmation)
+2. If the detected changes are correct, sync state with `terraform apply -refresh-only`
+3. If manual changes exist, decide: import to state or revert manual change
+
+## Wrong Provider Configuration
+**Symptom:** Resources targeting wrong region/project/subscription
+**Recovery:**
+1. Check `provider.tf` for region/project/subscription settings
+2. Check `backend.tf` for state configuration
+3. Use provider aliases for multi-region setups
+
+## Module Source Error
+**Symptom:** `Module not found` or `Failed to download module`
+**Recovery:**
+1. Check module source path (local) or registry URL (remote)
+2. For git sources, verify access credentials
+3. Run `terraform init` to re-download modules
+
+## General Principles
+- After 3 consecutive failures on the same issue, try a fundamentally different approach
+- Check cloud provider status pages for service outages
+- Never modify `terraform.tfstate` manually; use `terraform state mv` / `terraform state rm` for state surgery
+- Always backup state before destructive operations: `terraform state pull > backup.tfstate`

package/skills/oma-tf-infra/resources/examples.md

@@ -0,0 +1,38 @@
+# TF Infra Agent: Examples
+
+## Example 1: GCP Cloud Run Service with Cloud SQL
+
+**Input:** "Deploy an API service on Cloud Run and connect it to Cloud SQL PostgreSQL"
+
+**Output:**
+- Files created: `compute.tf`, `database.tf`, `networking.tf`, `iam.tf`, `outputs.tf`
+- Cloud provider: GCP (detected from existing `provider "google"`)
+- Resources: Cloud Run service, Cloud SQL PostgreSQL, VPC connector, service account
+- Key decisions:
+  - VPC connector for private Cloud SQL access
+  - Dedicated service account with minimal permissions
+  - Cloud SQL Auth Proxy sidecar for secure connection
+  - Environment-based sizing: `db-f1-micro` (dev) vs `db-custom-4-16384` (prod)
+
+## Example 2: AWS ECS Fargate with GitHub OIDC
+
+**Input:** "Set up OIDC so GitHub Actions can deploy to ECS Fargate"
+
+**Output:**
+- Files created: `cicd-auth.tf`, `iam.tf`
+- Cloud provider: AWS (detected from existing `aws_*` resources)
+- Resources: OIDC provider, IAM role with trust policy, ECR/ECS permissions
+- Key decisions:
+  - Trust policy scoped to specific repo and branch
+  - Permissions limited to ECR push + ECS task update only
+  - No long-lived access keys
+
+## Example 3: Terraform Plan Review
+
+**Input:** "Review this terraform plan output"
+
+**Output:**
+- Summary: 3 to add, 1 to change, 1 to destroy
+- Risk: HIGH; `aws_db_instance` will be destroyed and recreated (engine version change)
+- Recommendation: Use `lifecycle { prevent_destroy = true }` or manual migration
+- Checklist: backup verified, maintenance window set, rollback plan documented