# Oshun ECS Cluster Terraform Module

This Terraform module creates an Amazon ECS cluster with comprehensive
infrastructure for running containerized workloads.

## Features

- **ECS Cluster** with CloudWatch Container Insights
- **Capacity Providers**: Fargate, Fargate Spot, and EC2 (with Spot support)
- **Service Discovery**: AWS Cloud Map integration for internal DNS
- **IAM Roles**: Task execution role, task role, and instance role
- **Security Groups**: Pre-configured for container-to-container communication
- **CloudWatch Logging**: Log groups for cluster, ECS Exec, and Container
  Insights
- **Auto Scaling Group**: Mixed instances policy with On-Demand + Spot

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        ECS Cluster                               │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Capacity Providers                        │ │
│  │  ┌──────────┐  ┌───────────────┐  ┌───────────────────────┐ │ │
│  │  │ FARGATE  │  │ FARGATE_SPOT  │  │   EC2 (ASG + Spot)    │ │ │
│  │  └──────────┘  └───────────────┘  └───────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                     Supporting Services                      │ │
│  │  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐  │ │
│  │  │ Cloud Map   │  │ CloudWatch   │  │   Security Groups  │  │ │
│  │  │ (Service    │  │ Container    │  │   (Container-to-   │  │ │
│  │  │  Discovery) │  │ Insights     │  │    Container)      │  │ │
│  │  └─────────────┘  └──────────────┘  └────────────────────┘  │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Prerequisites

- Terraform >= 1.6.0
- AWS Provider ~> 5.0
- VPC with private subnets configured
- (Optional) S3 bucket and DynamoDB table for remote state

## Usage

### Basic Usage (Fargate Only)

```hcl
module "ecs_cluster" {
  source = "./infra/terraform/ecs"

  environment        = "development"
  region             = "us-east-1"
  vpc_id             = "vpc-xxxxxxxxx"
  private_subnet_ids = ["subnet-xxx", "subnet-yyy"]

  enable_fargate      = true
  enable_fargate_spot = true
  enable_ec2          = false

  tags = {
    Project = "oshun"
  }
}
```

### Production Usage (Mixed Capacity)

```hcl
module "ecs_cluster" {
  source = "./infra/terraform/ecs"

  environment        = "production"
  region             = "us-east-1"
  vpc_id             = "vpc-xxxxxxxxx"
  private_subnet_ids = ["subnet-xxx", "subnet-yyy", "subnet-zzz"]

  enable_fargate      = true
  enable_fargate_spot = true
  enable_ec2          = true
  enable_ec2_spot     = true

  ec2_instance_types = ["m6i.large", "m6i.xlarge", "m5.large"]
  ec2_min_size       = 2
  ec2_max_size       = 20
  ec2_desired_size   = 4

  default_capacity_provider_strategy = [
    {
      capacity_provider = "FARGATE"
      weight            = 60
      base              = 3
    },
    {
      capacity_provider = "FARGATE_SPOT"
      weight            = 40
      base              = 0
    }
  ]

  tags = {
    Project     = "oshun"
    Environment = "production"
  }
}
```

## Initialization

```bash
# Initialize with remote state backend
terraform init \
  -backend-config="bucket=oshun-terraform-state" \
  -backend-config="key=ecs/cluster/${ENV}/terraform.tfstate" \
  -backend-config="region=us-east-1" \
  -backend-config="dynamodb_table=oshun-terraform-locks" \
  -backend-config="encrypt=true"

# Plan with environment-specific variables
terraform plan -var-file="environments/${ENV}.tfvars"

# Apply
terraform apply -var-file="environments/${ENV}.tfvars"
```

## Inputs

| Name                      | Description               | Type           | Default       | Required |
| ------------------------- | ------------------------- | -------------- | ------------- | :------: |
| environment               | Deployment environment    | `string`       | n/a           |   yes    |
| vpc_id                    | VPC ID                    | `string`       | n/a           |   yes    |
| private_subnet_ids        | Private subnet IDs        | `list(string)` | n/a           |   yes    |
| region                    | AWS region                | `string`       | `"us-east-1"` |    no    |
| name_prefix               | Resource name prefix      | `string`       | `"oshun"`     |    no    |
| enable_fargate            | Enable Fargate capacity   | `bool`         | `true`        |    no    |
| enable_fargate_spot       | Enable Fargate Spot       | `bool`         | `true`        |    no    |
| enable_ec2                | Enable EC2 capacity       | `bool`         | `false`       |    no    |
| enable_ec2_spot           | Enable EC2 Spot           | `bool`         | `false`       |    no    |
| enable_container_insights | Enable Container Insights | `bool`         | `true`        |    no    |
| log_retention_days        | Log retention period      | `number`       | `30`          |    no    |

See `variables.tf` for the complete list of inputs.

## Outputs

| Name                           | Description                            |
| ------------------------------ | -------------------------------------- |
| cluster_arn                    | ECS cluster ARN                        |
| cluster_name                   | ECS cluster name                       |
| security_group_id              | Security group ID for ECS tasks        |
| task_execution_role_arn        | Task execution role ARN                |
| task_role_arn                  | Task role ARN                          |
| service_discovery_namespace_id | Cloud Map namespace ID                 |
| cluster_summary                | Complete cluster configuration summary |

See `outputs.tf` for the complete list of outputs.

## Creating ECS Services

After deploying the cluster, create ECS services using the outputs:

```hcl
resource "aws_ecs_service" "example" {
  name            = "example-service"
  cluster         = module.ecs_cluster.cluster_arn
  task_definition = aws_ecs_task_definition.example.arn
  desired_count   = 2

  capacity_provider_strategy {
    capacity_provider = "FARGATE"
    weight            = 1
    base              = 1
  }

  network_configuration {
    subnets          = module.ecs_cluster.default_network_configuration.subnets
    security_groups  = module.ecs_cluster.default_network_configuration.security_groups
    assign_public_ip = false
  }

  service_registries {
    registry_arn = aws_service_discovery_service.example.arn
  }

  enable_execute_command = true
}
```

## Cost Optimization

The module supports several cost optimization strategies:

1. **Fargate Spot**: Use for non-critical or fault-tolerant workloads
2. **EC2 Spot**: Mixed instances policy with On-Demand base capacity
3. **Capacity Provider Strategy**: Balance between reliability and cost
4. **Container Insights**: Monitor resource utilization for right-sizing

## Security Considerations

- IMDSv2 required for EC2 instances
- EBS volumes encrypted by default
- Security groups restrict traffic to within cluster
- IAM roles follow least-privilege principle
- ECS Exec requires explicit enablement

## Troubleshooting

### ECS Exec not working

1. Ensure `enable_execute_command = true`
2. Verify task role has SSM permissions
3. Check that the service has ECS Exec enabled

### Tasks not starting

1. Check CloudWatch logs in `/ecs/${cluster_name}/cluster`
2. Verify security group allows required traffic
3. Ensure task execution role can pull images

### High costs

1. Review Container Insights for over-provisioned tasks
2. Consider increasing Spot capacity percentage
3. Enable Fargate Spot for development/staging
