Eve library

Oshun ECS Cluster Terraform Module

Other

Revision 1

On this page

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:

  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