# Oshun ECS Services Module

This Terraform module creates ECS services with task definitions, ALB target
groups, Service Connect integration, and auto-scaling.

## Features

- **Task Definitions**: Fargate-compatible task definitions with health checks
- **ALB Integration**: Target groups and listener rules for path/host routing
- **Service Connect**: Internal service mesh via AWS Cloud Map
- **Auto-Scaling**: CPU and memory-based target tracking policies
- **Logging**: CloudWatch log groups per service
- **Secrets**: Integration with Secrets Manager and SSM Parameter Store
- **Circuit Breaker**: Deployment protection with automatic rollback

## Usage

```hcl
module "ecs_services" {
  source = "../ecs-services"

  environment = "production"
  region      = "us-east-1"
  name_prefix = "oshun"

  # From ECS cluster module
  cluster_arn  = module.ecs.cluster_arn
  cluster_name = module.ecs.cluster_name

  # From VPC module
  vpc_id             = module.vpc.vpc_id
  private_subnet_ids = module.vpc.private_subnet_ids
  security_group_ids = [module.ecs.security_group_id]

  # From ALB module
  alb_listener_arn = module.alb.https_listener_arn
  alb_dns_name     = module.alb.dns_name

  # From ECS cluster module
  service_discovery_namespace_id   = module.ecs.service_discovery_namespace_id
  service_discovery_namespace_name = module.ecs.service_discovery_namespace_name

  # From ECS IAM module
  task_execution_role_arn = module.ecs.task_execution_role_arn
  task_role_arns = {
    "isis-generation-api" = module.ecs_roles.service_task_role_arns["isis-generation-api"]
  }

  # ECR
  ecr_registry_url = module.ecr.registry_url

  # Service definitions
  services = {
    isis-generation-api = {
      domain         = "isis"
      description    = "Isis Generation API"
      image_name     = "isis/generation-api"
      container_port = 3000
      cpu            = 512
      memory         = 1024
      desired_count  = 2

      enable_load_balancer = true
      alb_path_pattern     = ["/api/isis/generation/*"]
      alb_priority         = 100

      secrets = [
        {
          name      = "DATABASE_URL"
          valueFrom = "arn:aws:secretsmanager:..."
        }
      ]
    }
  }
}
```

## Service Configuration Options

### Basic Configuration

```hcl
services = {
  my-service = {
    # Required
    domain      = "isis"
    description = "My service description"
    image_name  = "isis/my-service"

    # Optional (with defaults)
    enabled        = true
    image_tag      = "latest"
    container_port = 3000
    protocol       = "HTTP"  # HTTP, HTTPS, or gRPC
  }
}
```

### Resource Allocation

```hcl
services = {
  my-service = {
    # CPU (256 = 0.25 vCPU, 512 = 0.5 vCPU, 1024 = 1 vCPU, etc.)
    cpu    = 512
    memory = 1024  # MB

    # Ephemeral storage (default 21 GB)
    ephemeral_storage = 50  # GB, for services that need more scratch space
  }
}
```

### Scaling Configuration

```hcl
services = {
  my-service = {
    desired_count = 2
    min_count     = 1
    max_count     = 10

    # Auto-scaling
    enable_autoscaling        = true
    autoscaling_cpu_target    = 70   # Scale when avg CPU > 70%
    autoscaling_memory_target = 80   # Scale when avg memory > 80%
    scale_in_cooldown         = 300  # seconds
    scale_out_cooldown        = 60   # seconds
  }
}
```

### Capacity Provider Strategy

```hcl
services = {
  my-service = {
    # Custom capacity provider strategy (overrides default)
    capacity_provider_strategy = [
      {
        capacity_provider = "FARGATE"
        weight            = 100
        base              = 1
      }
    ]
  }
}
```

For Spot instances:

```hcl
services = {
  batch-worker = {
    capacity_provider_strategy = [
      {
        capacity_provider = "FARGATE_SPOT"
        weight            = 100
        base              = 0
      }
    ]
  }
}
```

### Health Check Configuration

```hcl
services = {
  my-service = {
    health_check_path     = "/health"
    health_check_interval = 30  # seconds
    health_check_timeout  = 5   # seconds
    health_check_retries  = 3
  }
}
```

### Load Balancer Configuration

```hcl
services = {
  my-service = {
    enable_load_balancer = true

    # Path-based routing
    alb_path_pattern = ["/api/my-service/*"]

    # Or host-based routing
    alb_host_header = ["api.example.com"]

    # Priority (lower = higher priority)
    alb_priority = 100

    # Sticky sessions
    stickiness_enabled  = true
    stickiness_duration = 86400  # seconds
  }
}
```

### Service Connect (Internal Service Mesh)

```hcl
services = {
  my-service = {
    enable_service_connect = true
    service_connect_port   = 3000  # 0 = use container_port

    # Service will be discoverable as:
    # my-service.oshun.local:3000
  }
}
```

### Environment Variables and Secrets

```hcl
services = {
  my-service = {
    # Plain environment variables
    environment = [
      {
        name  = "LOG_LEVEL"
        value = "info"
      }
    ]

    # Secrets from Secrets Manager
    secrets = [
      {
        name      = "DATABASE_URL"
        valueFrom = "arn:aws:secretsmanager:...:secret:my-secret:connection_string::"
      }
    ]

    # Secrets from SSM Parameter Store
    secrets = [
      {
        name      = "API_KEY"
        valueFrom = "arn:aws:ssm:...:parameter/my-param"
      }
    ]
  }
}
```

### Deployment Configuration

```hcl
services = {
  my-service = {
    deployment_minimum_healthy_percent = 50   # Allow 50% to be unavailable during deploy
    deployment_maximum_percent         = 200  # Allow 2x tasks during deploy

    enable_circuit_breaker = true   # Auto-rollback on failures
    enable_execute_command = true   # Enable ECS Exec for debugging
  }
}
```

### Volume Mounts

```hcl
services = {
  my-service = {
    volumes = [
      {
        name = "data"
        efs_config = {
          file_system_id = "fs-12345678"
          root_directory = "/data"
        }
      }
    ]

    mount_points = [
      {
        source_volume  = "data"
        container_path = "/app/data"
        read_only      = false
      }
    ]
  }
}
```

## Accessing Services

### Via ALB (External)

Services with `enable_load_balancer = true` are accessible via the ALB:

```
https://alb-dns-name/api/isis/generation/...
```

### Via Service Connect (Internal)

Services with `enable_service_connect = true` are discoverable internally:

```
http://isis-generation-api.oshun.local:3000
```

### ECS Exec (Debugging)

For services with `enable_execute_command = true`:

```bash
aws ecs execute-command \
  --cluster oshun-production \
  --task <task-id> \
  --container isis-generation-api \
  --interactive \
  --command "/bin/sh"
```

## Outputs

| Name                      | Description                        |
| ------------------------- | ---------------------------------- |
| task_definition_arns      | Map of service → task def ARN      |
| service_names             | Map of service → ECS service name  |
| target_group_arns         | Map of service → ALB target group  |
| log_group_names           | Map of service → CloudWatch log    |
| service_connect_endpoints | Map of service → internal DNS      |
| service_urls              | Map of service → external/internal |
| services_summary          | Summary of all deployed services   |

## Domain Configuration Files

This module supports domain-specific configuration files:

- `isis.tf` - Isis (Generative Factory) services
- `sophia.tf` - Sophia (Research & Knowledge) services
- `hathor.tf` - Hathor (Worldbuilding) services
- `bellona.tf` - Bellona (Build Engine) services
- `yemaya.tf` - Yemaya (Creative Studio) services
- `lilith.tf` - Lilith (Consciousness) services
- `common.tf` - Common services (API Gateway, Auth, etc.)

Each file defines domain-specific service configurations that get merged into
the main services variable.

## Best Practices

1. **Resource Right-Sizing**: Start with 256 CPU / 512 MB and scale up as needed
2. **Health Checks**: Use specific health check endpoints that verify
   dependencies
3. **Secrets**: Never put secrets in environment variables, use Secrets Manager
4. **Auto-Scaling**: Set appropriate min/max based on expected traffic patterns
5. **Spot Instances**: Use FARGATE_SPOT for batch workers, not APIs
6. **Service Connect**: Enable for all services that need internal communication
7. **Circuit Breaker**: Keep enabled for automatic rollback on failed
   deployments
