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#
text
┌─────────────────────────────────────────────────────────────────┐
│ 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:
- Fargate Spot: Use for non-critical or fault-tolerant workloads
- EC2 Spot: Mixed instances policy with On-Demand base capacity
- Capacity Provider Strategy: Balance between reliability and cost
- 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#
- Ensure
enable_execute_command = true - Verify task role has SSM permissions
- Check that the service has ECS Exec enabled
Tasks not starting#
- Check CloudWatch logs in
/ecs/${cluster_name}/cluster - Verify security group allows required traffic
- Ensure task execution role can pull images
High costs#
- Review Container Insights for over-provisioned tasks
- Consider increasing Spot capacity percentage
- Enable Fargate Spot for development/staging