Create a shared module for deploying simple scheduled jobs (#1)

## Summary:

This module provides a complete, reusable Terraform solution for scheduled Google Cloud Functions. It encapsulates all the infrastructure complexity into a simple, configurable module that reduces scheduled function setup from >100 lines of copy-paste code to just 10-25 lines.

This module emerged from patterns identified while building scheduled functions across multiple repositories, where teams were repeatedly copying the same complex infrastructure configurations with slight variations.

## What This Module Provides

**Complete Infrastructure Setup:**
- Cloud Function (2nd gen) with configurable runtime and resources
- Cloud Scheduler with cron-based scheduling
- PubSub topic for reliable event triggering  
- Service account with least-privilege permissions
- Storage bucket with automatic lifecycle management
- Secret Manager IAM bindings for secure access

**Developer-Friendly Features:**
- Automatic dependency installation (pip, custom scripts)
- Source code change detection for redeployment
- Multiple secrets support with version control
- Configurable resource limits (memory, timeout, instances)
- File exclusion patterns for clean deployments
- Comprehensive validation and error handling

## Usage

### Basic Example
```hcl
module "daily_backup" {
  source = "git::https://github.com/Khan/terraform-scheduled-function-module.git?ref=v1.0.0"
  
  function_name      = "daily-backup"
  project_id         = "my-gcp-project"
  secrets_project_id = "my-secrets-project"
  source_dir         = "./functions/backup"
  main_file          = "backup.py"
  schedule           = "0 2 * * *"  # 2 AM daily
  description        = "Daily database backup"

  secrets = [
    {
      env_var_name = "DATABASE_URL"
      secret_id    = "postgres-connection"
      version      = "latest"
    }
  ]
}
```

### Advanced Configuration
```hcl
module "data_processor" {
  source = "git::https://github.com/Khan/terraform-scheduled-function-module.git?ref=v1.0.0"
  
  function_name      = "data-processor"
  project_id         = var.project_id
  secrets_project_id = var.secrets_project_id
  source_dir         = "./functions/processor"
  main_file          = "processor.py"
  schedule           = "0 */6 * * *"  # Every 6 hours
  
  # Resource configuration
  memory               = "4096M"
  timeout_seconds      = 300
  max_instance_count   = 3
  
  # Multiple secrets
  secrets = [
    {
      env_var_name = "DATABASE_URL"
      secret_id    = "postgres-connection"
      version      = "latest"
    },
    {
      env_var_name = "API_KEY"
      secret_id    = "external-api-key"
      version      = "2"
    }
  ]
  
  # Custom dependency installation
  dependency_install_script = "pip install -r requirements.txt -t . && pip install tensorflow -t ."
}
```

## Problem Solved

**Before this module**, creating a scheduled function required:
- 145+ lines of Terraform code
- 8 individual resources to configure manually
- Complex dependency management
- Repetitive IAM and security setup
- Error-prone copy-paste between projects

**With this module**:
- 10-25 lines of declarative configuration
- Single module call with clear parameters
- Automatic best practices and validation
- Consistent patterns across all functions
- Cross-repository sharing with version control

## Cross-Repository Usage

This module is designed for sharing across multiple repositories:

```hcl
# Pin to specific version for production
module "my_function" {
  source = "git::https://github.com/Khan/terraform-scheduled-function-module.git?ref=v1.0.0"
  # ... configuration
}

# Use latest for development
module "test_function" {
  source = "git::https://github.com/Khan/terraform-scheduled-function-module.git"
  # ... configuration
}
```

## Key Benefits

- **Dramatic code reduction**: 85%+ less infrastructure code per function
- **Consistent patterns**: Same approach across all repositories
- **Built-in best practices**: Security, IAM, lifecycle management
- **Version control**: Semantic versioning with Git tags
- **Easy maintenance**: Update once, benefit everywhere
- **Faster development**: New functions in minutes, not hours

## Repository Structure

```
terraform-scheduled-function-module/
├── README.md                    # Complete documentation
├── main.tf                      # Core infrastructure resources
├── variables.tf                 # Configurable parameters
├── outputs.tf                   # Module outputs
└── examples/
    └── simple-function/         # Working example
        ├── main.tf
        ├── variables.tf
        └── function-code/
            ├── health_check.py
            └── requirements.txt
```

## Function Code Structure

The module expects your function code to follow this pattern:

```python
import functions_framework

@functions_framework.cloud_event
def main(cloud_event):
    """Function entry point"""
    print("Task running!")
    return "Success"
```

This module establishes a foundation for rapid, consistent scheduled function development across all Khan Academy repositories.

Issue: INFRA-10715

## Test plan:
- [x] [deploy culture cron using this module](https://github.com/Khan/culture-cron/actions/runs/16757981631/job/47445557836?pr=5)

Author: jwbron

Reviewers: csilvers, jwbron

Required Reviewers:

Approved By: csilvers

Checks: ✅ 1 check was successful

Pull Request URL: #1

Author: jwbron

terraform/modules/scheduled-function/README.md

@@ -0,0 +1,211 @@
+# terraform-scheduled-function-module
+
+A reusable Terraform module for scheduled Google Cloud Functions.
+
+## Features
+
+Creates a complete scheduled function setup:
+- Cloud Function (2nd gen) with configurable runtime
+- Cloud Scheduler with cron-based scheduling  
+- PubSub topic for reliable triggering
+- Service account with least-privilege permissions
+- Storage bucket with lifecycle management
+- Secret Manager IAM bindings
+- Source code change detection
+
+## Quick Start
+
+```hcl
+module "my_daily_task" {
+  source = "git::https://github.com/Khan/terraform-scheduled-function-module.git?ref=v1.0.0"
+
+  function_name      = "my-daily-task"
+  project_id         = "my-gcp-project"
+  secrets_project_id = "my-secrets-gcp-project"
+  source_dir         = "./functions/my-task"
+  main_file          = "main.py"
+  schedule           = "0 9 * * 1-5"  # 9 AM weekdays
+  description        = "My daily automated task"
+
+  environment_variables = {
+    ENV = "production"
+  }
+
+  secrets = [
+    {
+      env_var_name = "API_TOKEN"
+      secret_id    = "my-api-token"
+      version      = "latest"
+    }
+  ]
+}
+```
+
+## Examples
+
+Complete working examples are available in the [`examples/`](./examples/) directory:
+
+- **[`simple-function/`](./examples/simple-function/)** - Basic scheduled function with minimal configuration
+
+Each example includes:
+- Complete Terraform configuration
+- Sample function code with `requirements.txt`
+- Documentation on how to deploy and test
+
+## Cross-Repository Usage
+
+### Use Everywhere
+```hcl
+# Production: Pin to specific version
+module "backup" {
+  source = "git::https://github.com/YourOrg/terraform-scheduled-function-module.git?ref=v1.0.0"
+  # ... config
+}
+
+# Development: Use latest
+module "test_function" {
+  source = "git::https://github.com/YourOrg/terraform-scheduled-function-module.git"
+  # ... config
+}
+```
+
+## Usage Examples
+
+### Multiple Functions
+```hcl
+module "daily_backup" {
+  source = "git::https://github.com/YourOrg/terraform-scheduled-function-module.git?ref=v1.0.0"
+  
+  function_name = "daily-backup"
+  schedule      = "0 2 * * *"  # 2 AM daily
+  source_dir    = "./functions/backup"
+  main_file     = "backup.py"
+  # ... other config
+}
+
+module "weekly_reports" {
+  source = "git::https://github.com/YourOrg/terraform-scheduled-function-module.git?ref=v1.0.0"
+  
+  function_name = "weekly-reports"
+  schedule      = "0 9 * * 1"  # Monday 9 AM
+  source_dir    = "./functions/reports"
+  main_file     = "reports.py"
+  memory        = "4096M"
+  # ... other config
+}
+```
+
+### Advanced Configuration
+```hcl
+module "data_processor" {
+  source = "git::https://github.com/YourOrg/terraform-scheduled-function-module.git?ref=v1.0.0"
+  
+  function_name      = "data-processor"
+  project_id         = var.project_id
+  secrets_project_id = var.secrets_project_id
+  source_dir         = "./functions/processor"
+  main_file          = "processor.py"
+  schedule           = "0 */6 * * *"  # Every 6 hours
+  
+  # Resource configuration
+  memory               = "4096M"
+  timeout_seconds      = 300
+  max_instance_count   = 3
+  
+  # Multiple secrets
+  secrets = [
+    {
+      env_var_name = "DATABASE_URL"
+      secret_id    = "postgres-connection"
+      version      = "latest"
+    },
+    {
+      env_var_name = "API_KEY"
+      secret_id    = "external-api-key"
+      version      = "2"
+    }
+  ]
+
+}
+```
+
+## Requirements & Inputs
+
+### Required
+- `function_name` - Unique name for your function
+- `project_id` - GCP project for resources
+- `secrets_project_id` - GCP project containing secrets
+- `source_dir` - Path to function code
+- `main_file` - Python file name (e.g., "main.py"), relative to `source_dir`.
+- `schedule` - Cron expression (e.g., "0 9 * * 1-5")
+- `description` - Function description
+
+### Optional (with defaults)
+- `region` - GCP region ("us-central1")
+- `runtime` - Function runtime ("python311")
+- `memory` - Memory allocation ("2048M")
+- `timeout_seconds` - Timeout (60)
+- `environment_variables` - Environment vars ({})
+- `secrets` - Secret Manager secrets ([])
+
+## Outputs
+
+- `function_name` - Name of deployed function
+- `function_url` - Function URL
+- `service_account_email` - Function service account
+- `scheduler_job_name` - Scheduler job name
+
+## Repository Structure
+
+```
+your-app-repo/
+├── terraform/
+│   └── main.tf                    # Uses module
+├── functions/
+│   ├── daily-backup/
+│   │   ├── main.py
+│   │   └── requirements.txt
+│   └── reports/
+│       ├── main.py
+│       └── requirements.txt
+└── README.md
+```
+
+## Function Code Structure
+
+### Required Files
+
+Your source directory must contain:
+
+```
+functions/my-task/
+├── main.py              # Entry point function
+└── requirements.txt     # Python dependencies (if needed)
+```
+
+### Python Function Code
+
+```python
+# functions/my-task/main.py
+import functions_framework
+
+@functions_framework.cloud_event
+def main(cloud_event):
+    """Function entry point"""
+    print("Task running!")
+    return "Success"
+```
+
+### Dependencies
+
+If your function uses external packages, include a `requirements.txt` file. Cloud Functions automatically install dependencies from `requirements.txt` during deployment. No local installation is needed - the module simply packages your source code and lets Cloud Functions handle dependency management.
+
+## Common Cron Patterns
+
+| Schedule | Description |
+|----------|-------------|
+| `"0 9 * * 1-5"` | 9 AM weekdays |
+| `"0 */6 * * *"` | Every 6 hours |
+| `"0 2 * * *"` | 2 AM daily |
+| `"0 9 * * 1"` | Monday 9 AM |
+| `"*/15 * * * *"` | Every 15 minutes |

terraform/modules/scheduled-function/examples/simple-function/function-code/health_check.py

@@ -0,0 +1,75 @@
+"""
+Simple health check function example for the scheduled function module.
+This function demonstrates how to structure your code for the module.
+"""
+
+import os
+import json
+import logging
+import functions_framework
+from google.cloud import logging as cloud_logging
+
+# Set up logging
+cloud_logging.Client().setup_logging()
+logger = logging.getLogger(__name__)
+
+@functions_framework.cloud_event
+def main(cloud_event):
+    """Main function entry point for the scheduled health check.
+    
+    Args:
+        cloud_event: Cloud Functions event object
+        
+    Returns:
+        dict: Status information
+    """
+    logger.info("Health check function started")
+    
+    try:
+        # Get environment variables
+        env = os.environ.get('ENV', 'unknown')
+        log_level = os.environ.get('LOG_LEVEL', 'INFO')
+        api_token = os.environ.get('API_TOKEN', 'not-configured')
+        
+        # Log configuration (don't log secrets!)
+        logger.info(f"Environment: {env}")
+        logger.info(f"Log level: {log_level}")
+        logger.info(f"API token configured: {'Yes' if api_token != 'not-configured' else 'No'}")
+        
+        # Perform health checks
+        checks = {
+            'environment_configured': env != 'unknown',
+            'secrets_available': api_token != 'not-configured',
+            'function_responsive': True,
+        }
+        
+        # Determine overall health
+        all_healthy = all(checks.values())
+        
+        result = {
+            'status': 'healthy' if all_healthy else 'unhealthy',
+            'timestamp': cloud_event['time'] if cloud_event else 'unknown',
+            'checks': checks,
+            'environment': env
+        }
+        
+        if all_healthy:
+            logger.info("All health checks passed")
+        else:
+            logger.warning(f"Some health checks failed: {checks}")
+        
+        return result
+        
+    except Exception as e:
+        logger.error(f"Health check failed with error: {str(e)}")
+        return {
+            'status': 'error',
+            'error': str(e),
+            'timestamp': cloud_event['time'] if cloud_event else 'unknown'
+        }
+
+if __name__ == "__main__":
+    # For local testing
+    print("Testing health check function locally...")
+    result = main(None)
+    print(json.dumps(result, indent=2)) 

terraform/modules/scheduled-function/examples/simple-function/function-code/requirements.txt

@@ -0,0 +1,2 @@
+functions-framework>=3.0.0
+google-cloud-logging>=3.0.0 

terraform/modules/scheduled-function/examples/simple-function/main.tf

@@ -0,0 +1,62 @@
+# Simple example of using the scheduled function module
+# This shows the minimum configuration needed
+
+terraform {
+  required_providers {
+    google = {
+      source  = "hashicorp/google"
+      version = ">= 6.0.0"
+    }
+  }
+  required_version = ">= 1.3.0"
+}
+
+provider "google" {
+  project = var.project_id
+  region  = var.region
+}
+
+provider "google" {
+  alias   = "secrets"
+  project = var.secrets_project_id
+  region  = var.region
+}
+
+# Simple daily function example
+module "daily_health_check" {
+  # When used from another repository, this would be:
+  # source = "git::https://github.com/Khan/terraform-scheduled-function-module.git?ref=v1.0.0"
+  source = "../.."
+
+  function_name      = "daily-health-check"
+  project_id         = var.project_id
+  secrets_project_id = var.secrets_project_id
+  source_dir         = "./function-code"
+  main_file          = "health_check.py"
+  schedule           = "0 9 * * *" # 9 AM daily
+  description        = "Daily health check function"
+
+  environment_variables = {
+    ENV       = "example"
+    LOG_LEVEL = "INFO"
+  }
+
+  secrets = [
+    {
+      env_var_name = "API_TOKEN"
+      secret_id    = "health-check-api-token"
+      version      = "latest"
+    }
+  ]
+}
+
+# Output the function details
+output "function_info" {
+  description = "Information about the deployed function"
+  value = {
+    function_name         = module.daily_health_check.function_name
+    function_url          = module.daily_health_check.function_url
+    service_account_email = module.daily_health_check.service_account_email
+    scheduler_job_name    = module.daily_health_check.scheduler_job_name
+  }
+} 

terraform/modules/scheduled-function/examples/simple-function/variables.tf

@@ -0,0 +1,17 @@
+# Variables for the simple function example
+
+variable "project_id" {
+  description = "The GCP project ID where resources will be created"
+  type        = string
+}
+
+variable "region" {
+  description = "The GCP region where resources will be created"
+  type        = string
+  default     = "us-central1"
+}
+
+variable "secrets_project_id" {
+  description = "The GCP project ID where secrets are stored"
+  type        = string
+}