specweave 0.21.2 → 0.22.0

package/plugins/specweave/iac-templates/gcp-cloud-functions/README.md.hbs

@@ -0,0 +1,330 @@
+# {{projectName}} - GCP Cloud Functions Infrastructure
+
+🚀 Generated by **SpecWeave Serverless Intelligence**
+
+## Overview
+
+This Terraform configuration deploys a serverless application on GCP Cloud Functions Gen2 with the following components:
+
+- **Cloud Function Gen2**: `{{functionName}}` ({{#if runtime}}{{runtime}}{{else}}Node.js 20{{/if}})
+- **Service Account**: Least-privilege IAM permissions{{#if databaseName}}
+- **Firestore**: Native NoSQL database with indexing{{/if}}
+- **Cloud Storage**: Source code and logs storage
+- **Cloud Logging**: Centralized logging and monitoring
+
+## Architecture
+
+```
+{{#if databaseName}}
+Internet → Cloud Function Gen2 → Firestore
+                ↓
+         Cloud Logging
+{{else}}
+Internet → Cloud Function Gen2
+                ↓
+         Cloud Logging
+{{/if}}
+```
+
+## Prerequisites
+
+1. **GCP Account** with billing enabled
+2. **gcloud CLI** installed and authenticated
+3. **Terraform** >= 1.0 installed
+4. **Function deployment package**: `{{functionName}}.zip` with your code
+
+## Quick Start
+
+### 1. Authenticate with GCP
+
+```bash
+gcloud auth application-default login
+gcloud config set project YOUR_PROJECT_ID
+```
+
+### 2. Enable Required APIs
+
+```bash
+gcloud services enable cloudfunctions.googleapis.com
+gcloud services enable cloudbuild.googleapis.com
+gcloud services enable cloudscheduler.googleapis.com
+{{#if databaseName}}
+gcloud services enable firestore.googleapis.com
+{{/if}}
+gcloud services enable logging.googleapis.com
+gcloud services enable storage.googleapis.com
+```
+
+### 3. Initialize Terraform
+
+```bash
+terraform init
+```
+
+### 4. Review Plan
+
+```bash
+terraform plan -var="project_id=YOUR_PROJECT_ID"
+```
+
+### 5. Deploy
+
+```bash
+terraform apply -var="project_id=YOUR_PROJECT_ID"
+```
+
+### 6. Upload Function Code
+
+```bash
+# Get bucket name
+BUCKET=$(terraform output -raw source_bucket_name)
+
+# Upload function code
+gcloud storage cp {{functionName}}.zip gs://$BUCKET/
+```
+
+### 7. Test Deployment
+
+```bash
+# Get function URL
+FUNCTION_URL=$(terraform output -raw function_url)
+
+# Test function
+curl $FUNCTION_URL
+```
+
+## Configuration
+
+### Variables
+
+Edit `terraform.tfvars` to customize:
+
+```hcl
+project_id         = "your-gcp-project-id"
+project_name       = "{{projectName}}"
+environment        = "{{environment}}"
+function_name      = "{{functionName}}"
+region             = "{{#if region}}{{region}}{{else}}us-central1{{/if}}"
+runtime            = "{{#if runtime}}{{runtime}}{{else}}nodejs20{{/if}}"
+memory             = "{{#if memory}}{{memory}}{{else}}256M{{/if}}"
+timeout            = {{#if timeout}}{{timeout}}{{else}}60{{/if}}
+{{#if databaseName}}
+database_name      = "{{databaseName}}"
+firestore_location = "us-central"
+{{/if}}
+```
+
+### Environment Variables
+
+The Cloud Function has these environment variables:
+
+- `ENVIRONMENT`: `{{environment}}`{{#if databaseName}}
+- `FIRESTORE_PROJECT`: GCP project ID
+- `FIRESTORE_DATABASE`: Firestore database name{{/if}}
+
+## Outputs
+
+After deployment, Terraform provides these outputs:
+
+- `function_name`: Cloud Function name
+- `function_url`: HTTPS endpoint
+- `function_service_account_email`: Service account email{{#if databaseName}}
+- `firestore_database_name`: Firestore database name{{/if}}
+
+## Resource Details
+
+### Cloud Function Gen2
+
+- **Runtime**: {{#if runtime}}{{runtime}}{{else}}Node.js 20{{/if}}
+- **Memory**: {{#if memory}}{{memory}}{{else}}256M{{/if}}
+- **Timeout**: {{#if timeout}}{{timeout}}{{else}}60{{/if}} seconds
+- **Entry Point**: {{#if entryPoint}}{{entryPoint}}{{else}}handler{{/if}}
+- **Min Instances**: {{#if (eq environment "prod")}}1 (always warm){{else}}0 (cold starts){{/if}}
+- **Max Instances**: {{#if (eq environment "prod")}}100{{else if (eq environment "staging")}}10{{else}}5{{/if}}
+- **Ingress**: {{#if (eq environment "prod")}}Internal + Load Balancer{{else}}Allow all{{/if}}
+
+{{#if databaseName}}
+### Firestore
+
+- **Name**: `{{databaseName}}-{{environment}}`
+- **Type**: FIRESTORE_NATIVE
+- **Location**: {{#if firestoreLocation}}{{firestoreLocation}}{{else}}us-central{{/if}}
+- **Concurrency**: {{#if (eq environment "prod")}}Optimistic (higher throughput){{else}}Pessimistic (simpler){{/if}}
+- **Point-in-Time Recovery**: {{#if (eq environment "prod")}}Enabled{{else}}Disabled{{/if}}
+- **Delete Protection**: {{#if (eq environment "prod")}}Enabled{{else}}Disabled{{/if}}
+
+**Cost Optimization**: Firestore has a generous free tier (50K reads, 20K writes, 1GB storage per day).
+{{/if}}
+
+### Cloud Storage
+
+- **Source Bucket**: Stores function deployment packages
+- **Logs Bucket**: Stores function logs
+- **Versioning**: {{#if (eq environment "prod")}}Enabled (3 versions){{else}}Disabled{{/if}}
+- **Lifecycle**: Logs deleted after {{#if (eq environment "prod")}}90{{else}}30{{/if}} days
+
+## Security Best Practices
+
+✅ **Implemented**:
+- Dedicated service account (least privilege)
+- Uniform bucket-level access
+- HTTPS-only endpoints{{#if (eq environment "prod")}}
+- Internal ingress (+ Load Balancer only)
+- Point-in-time recovery for Firestore
+- Delete protection for Firestore{{/if}}
+
+⚠️ **TODO**:
+- Add VPC Connector for private networking
+- Enable Secret Manager for sensitive data
+- Implement Cloud Armor for DDoS protection
+- Add Cloud CDN for global distribution
+- Enable Binary Authorization for container signing
+
+## Cost Estimation
+
+### Free Tier (Always Free)
+
+GCP offers a generous always-free tier:
+- **Cloud Functions**: 2M invocations/month, 400K GB-seconds, 200K GHz-seconds
+- **Firestore**: 50K reads/day, 20K writes/day, 1GB storage, 10GB network egress/month
+- **Cloud Storage**: 5 GB standard storage
+- **Cloud Logging**: 50 GB logs/month
+
+### Estimated Monthly Cost (After Free Tier)
+
+**Development**:
+- Cloud Functions (10K requests): $0.00 (within free tier)
+- Firestore (minimal usage): $0.00 (within free tier)
+- Cloud Storage: $0.10
+- **Total**: ~$0.10/month
+
+**Staging**:
+- Cloud Functions (100K requests): ~$0.50
+- Firestore (moderate usage): ~$1.00
+- Cloud Storage: $0.20
+- **Total**: ~$1.70/month
+
+**Production**:
+- Cloud Functions (1M requests + min instances): ~$15.00
+- Firestore (high usage): ~$5.00
+- Cloud Storage: $0.50
+- **Total**: ~$20.50/month
+
+💡 **Tip**: Use GCP Cost Management and set up budget alerts.
+
+## Monitoring
+
+### Cloud Logging Metrics
+
+- **Invocation Count**: Total function executions
+- **Execution Time**: P50, P95, P99 latency
+- **Error Rate**: Function errors and exceptions
+- **Instance Count**: Active instances{{#if databaseName}}
+- **Firestore Operations**: Read/write counts{{/if}}
+
+### Log Explorer
+
+View logs in Cloud Console:
+```
+resource.type="cloud_function"
+resource.labels.function_name="{{functionName}}-{{environment}}"
+```
+
+### Recommended Alerts
+
+```hcl
+# Add to your Terraform:
+resource "google_monitoring_alert_policy" "function_errors" {
+  display_name = "{{functionName}} - High Error Rate"
+  combiner     = "OR"
+
+  conditions {
+    display_name = "Error rate > 5%"
+
+    condition_threshold {
+      filter          = "resource.type = \"cloud_function\" AND resource.labels.function_name = \"{{functionName}}-{{environment}}\" AND metric.type = \"cloudfunctions.googleapis.com/function/execution_count\" AND metric.labels.status = \"error\""
+      duration        = "60s"
+      comparison      = "COMPARISON_GT"
+      threshold_value = 5
+      aggregations {
+        alignment_period   = "60s"
+        per_series_aligner = "ALIGN_RATE"
+      }
+    }
+  }
+
+  notification_channels = [google_monitoring_notification_channel.email.id]
+}
+```
+
+## Deployment Workflow
+
+### Development
+
+```bash
+terraform workspace new dev
+terraform workspace select dev
+terraform apply -var="environment=dev"
+```
+
+### Staging
+
+```bash
+terraform workspace new staging
+terraform workspace select staging
+terraform apply -var="environment=staging"
+```
+
+### Production
+
+```bash
+terraform workspace new prod
+terraform workspace select prod
+terraform apply -var="environment=prod"
+```
+
+## Cleanup
+
+To destroy all resources:
+
+```bash
+terraform destroy
+```
+
+⚠️ **Warning**: This will permanently delete all data in Firestore!
+
+## Troubleshooting
+
+**Function deployment fails?**
+1. Check Cloud Build logs in GCP Console
+2. Verify source code is uploaded to bucket
+3. Review IAM permissions
+
+**Permission denied errors?**
+1. Verify service account has required roles
+2. Check project-level IAM bindings
+3. Enable required APIs
+
+**Firestore connection issues?**
+1. Verify Firestore database is created
+2. Check service account has `datastore.user` role
+3. Review Firestore security rules
+
+## Next Steps
+
+1. **Add VPC Integration**: Secure private networking
+2. **Enable Secret Manager**: Manage API keys and secrets
+3. **Implement CI/CD**: Use Cloud Build or GitHub Actions
+4. **Add Monitoring**: Set up alerts and dashboards
+5. **Optimize Costs**: Review Cloud Functions instance settings
+
+## Resources
+
+- [Cloud Functions Documentation](https://cloud.google.com/functions/docs)
+- [Firestore Documentation](https://cloud.google.com/firestore/docs)
+- [Cloud Logging Documentation](https://cloud.google.com/logging/docs)
+- [Terraform Google Provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
+
+---
+
+**Generated by SpecWeave** | [Learn More](https://spec-weave.com)

package/plugins/specweave/iac-templates/gcp-cloud-functions/defaults.json

@@ -0,0 +1,69 @@
+{
+  "platform": "gcp-cloud-functions",
+  "region": "us-central1",
+  "firestoreLocation": "us-central",
+  "runtime": "nodejs20",
+  "memory": "256M",
+  "timeout": 60,
+  "instances": {
+    "dev": {
+      "min": 0,
+      "max": 5
+    },
+    "staging": {
+      "min": 0,
+      "max": 10
+    },
+    "prod": {
+      "min": 1,
+      "max": 100
+    }
+  },
+  "ingress": {
+    "dev": "ALLOW_ALL",
+    "staging": "ALLOW_ALL",
+    "prod": "ALLOW_INTERNAL_AND_GCLB"
+  },
+  "storage": {
+    "versioning": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    },
+    "lifecycleDays": {
+      "dev": 30,
+      "staging": 30,
+      "prod": 90
+    },
+    "forceDestroy": {
+      "dev": true,
+      "staging": true,
+      "prod": false
+    }
+  },
+  "firestore": {
+    "type": "FIRESTORE_NATIVE",
+    "concurrencyMode": {
+      "dev": "PESSIMISTIC",
+      "staging": "OPTIMISTIC",
+      "prod": "OPTIMISTIC"
+    },
+    "pointInTimeRecovery": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    },
+    "deleteProtection": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    }
+  },
+  "iam": {
+    "publicInvoker": {
+      "dev": true,
+      "staging": true,
+      "prod": false
+    }
+  }
+}

package/plugins/specweave/iac-templates/gcp-cloud-functions/environments/dev.defaults.json

@@ -0,0 +1,33 @@
+{
+  "environment": "dev",
+  "region": "us-central1",
+  "firestoreLocation": "us-central",
+  "memory": "256M",
+  "timeout": 60,
+  "instances": {
+    "min": 0,
+    "max": 5
+  },
+  "ingress": "ALLOW_ALL",
+  "publicInvoker": true,
+  "storage": {
+    "versioning": false,
+    "lifecycleDays": 30,
+    "forceDestroy": true
+  },
+  "firestore": {
+    "concurrencyMode": "PESSIMISTIC",
+    "pointInTimeRecovery": false,
+    "deleteProtection": false
+  },
+  "costOptimization": {
+    "description": "Free tier optimized - 0 min instances, cold starts acceptable",
+    "estimatedMonthlyCost": "$0-1",
+    "freeTierEligible": true,
+    "notes": [
+      "2M invocations/month free",
+      "50K Firestore reads/day free",
+      "Cold starts expected (0 min instances)"
+    ]
+  }
+}

package/plugins/specweave/iac-templates/gcp-cloud-functions/environments/prod.defaults.json

@@ -0,0 +1,40 @@
+{
+  "environment": "prod",
+  "region": "us-central1",
+  "firestoreLocation": "us-central",
+  "memory": "512M",
+  "timeout": 120,
+  "instances": {
+    "min": 1,
+    "max": 100
+  },
+  "ingress": "ALLOW_INTERNAL_AND_GCLB",
+  "publicInvoker": false,
+  "storage": {
+    "versioning": true,
+    "versionRetention": 3,
+    "lifecycleDays": 90,
+    "forceDestroy": false
+  },
+  "firestore": {
+    "concurrencyMode": "OPTIMISTIC",
+    "pointInTimeRecovery": true,
+    "deleteProtection": true
+  },
+  "security": {
+    "vpcConnectorRequired": false,
+    "internalIngressOnly": true,
+    "serviceAccountMinimalPrivileges": true
+  },
+  "costOptimization": {
+    "description": "Production-ready - Always-on, restricted ingress, PITR enabled",
+    "estimatedMonthlyCost": "$20-50",
+    "freeTierEligible": false,
+    "notes": [
+      "1 min instance = always warm (no cold starts)",
+      "Point-in-time recovery for Firestore",
+      "Restricted ingress for security",
+      "Delete protection enabled"
+    ]
+  }
+}

package/plugins/specweave/iac-templates/gcp-cloud-functions/environments/staging.defaults.json

@@ -0,0 +1,33 @@
+{
+  "environment": "staging",
+  "region": "us-central1",
+  "firestoreLocation": "us-central",
+  "memory": "512M",
+  "timeout": 120,
+  "instances": {
+    "min": 0,
+    "max": 10
+  },
+  "ingress": "ALLOW_ALL",
+  "publicInvoker": true,
+  "storage": {
+    "versioning": false,
+    "lifecycleDays": 30,
+    "forceDestroy": true
+  },
+  "firestore": {
+    "concurrencyMode": "OPTIMISTIC",
+    "pointInTimeRecovery": false,
+    "deleteProtection": false
+  },
+  "costOptimization": {
+    "description": "Cost-effective for testing - Higher memory, no min instances",
+    "estimatedMonthlyCost": "$1-5",
+    "freeTierEligible": false,
+    "notes": [
+      "512M memory for realistic testing",
+      "No always-on instances",
+      "Optimistic concurrency for performance"
+    ]
+  }
+}

package/plugins/specweave/iac-templates/gcp-cloud-functions/iam.tf.hbs

@@ -0,0 +1,54 @@
+# IAM Roles and Permissions for GCP Cloud Functions
+# Project: {{projectName}}
+
+###############################
+# Service Account Permissions
+###############################
+
+{{#if databaseName}}
+# Grant Cloud Function service account access to Firestore
+resource "google_project_iam_member" "{{snakeCase functionName}}_firestore" {
+  project = var.project_id
+  role    = "roles/datastore.user"
+  member  = "serviceAccount:${google_service_account.{{snakeCase functionName}}.email}"
+}
+{{/if}}
+
+# Grant Cloud Function service account access to Cloud Logging
+resource "google_project_iam_member" "{{snakeCase functionName}}_logging" {
+  project = var.project_id
+  role    = "roles/logging.logWriter"
+  member  = "serviceAccount:${google_service_account.{{snakeCase functionName}}.email}"
+}
+
+# Grant Cloud Function service account access to Cloud Monitoring
+resource "google_project_iam_member" "{{snakeCase functionName}}_monitoring" {
+  project = var.project_id
+  role    = "roles/monitoring.metricWriter"
+  member  = "serviceAccount:${google_service_account.{{snakeCase functionName}}.email}"
+}
+
+# Grant service account access to read from source bucket
+resource "google_storage_bucket_iam_member" "{{snakeCase functionName}}_source_reader" {
+  bucket = google_storage_bucket.{{snakeCase functionName}}_source.name
+  role   = "roles/storage.objectViewer"
+  member = "serviceAccount:${google_service_account.{{snakeCase functionName}}.email}"
+}
+
+###############################
+# Additional IAM Bindings (Optional)
+###############################
+
+# For Secret Manager integration (uncomment if needed):
+# resource "google_project_iam_member" "function_secret_accessor" {
+#   project = var.project_id
+#   role    = "roles/secretmanager.secretAccessor"
+#   member  = "serviceAccount:${google_service_account.{{snakeCase functionName}}.email}"
+# }
+
+# For Cloud Storage access (uncomment if needed):
+# resource "google_project_iam_member" "function_storage_admin" {
+#   project = var.project_id
+#   role    = "roles/storage.objectAdmin"
+#   member  = "serviceAccount:${google_service_account.{{snakeCase functionName}}.email}"
+# }