ECS Cluster#

This module provisions a flexible and production-ready AWS ECS cluster. It supports both Fargate and EC2 launch types, and allows you to:

Configure the cluster name, tags, and advanced ECS settings
Optionally enable Fargate and/or EC2 capacity providers
Automatically create and manage an EC2 Auto Scaling Group and Launch Template for EC2-backed clusters
Attach a managed scaling policy to the EC2 capacity provider for dynamic scaling
Assign custom user data, security groups, subnets, and other EC2/ASG parameters
Automatically create a default ECS instance IAM role with recommended policies for EC2 instances
Output all key resource identifiers for integration with other modules

Usage#

module "ecs_cluster" {
  source = "./modules/ecs/cluster"
  name = "my-ecs-cluster"

  tags = {
    Environment = "dev"
    Project = "example"
  }

  settings = [
    {
      name = "containerInsights"
      value = "enabled"
    }
  ]

  fargate_enabled = true
  fargate_capacity_providers = ["FARGATE", "FARGATE_SPOT"]
  with_ec2_capacity_provider = true

  ec2_managed_scaling = {
    maximum_scaling_step_size = 10
    minimum_scaling_step_size = 1
    target_capacity = 100
    status = "ENABLED"
  }

  ami_id = module.test_cluster.default_ami_id
  instance_type = "t3.micro"
  key_name = "my-key"
  security_group_ids = ["sg-xxxxxxx"]
  subnet_ids = ["subnet-xxxxxxx"]

  max_size = 10
  min_size = 0
  desired_capacity = 1

  health_check_type = "EC2"
  health_check_grace_period = 300
  termination_policies = ["Default"]
  target_group_arns = []
  enabled_metrics = []
}

Variables#

Name	Description	Type	Default
name	The name of the ECS cluster	string	n/a
tags	A map of tags to assign to the ECS cluster	map(string)	{}
settings	A list of maps for ECS cluster settings (e.g., name and value)	list(object)	[]
fargate_enabled	Whether to enable Fargate capacity providers for the ECS cluster	bool	true
fargate_capacity_providers	List of Fargate capacity providers to associate	list(string)	[“FARGATE”, “FARGATE_SPOT”]
with_ec2_capacity_provider	Whether to enable EC2 capacity provider for the ECS cluster	bool	false
ec2_managed_scaling	Managed scaling configuration for the EC2 capacity provider	object	See below
ami_id	AMI ID for EC2 instances	string	n/a
instance_type	EC2 instance type	string	“t3.micro”
key_name	Key pair name for SSH access	string	null
security_group_ids	List of security group IDs	list(string)	n/a
health_check_type	Type of health check (EC2 or ELB)	string	“EC2”
health_check_grace_period	Time (in seconds) for health check grace period	number	300
termination_policies	List of termination policies for the ASG	list(string)	[“Default”]
target_group_arns	List of target group ARNs for load balancing	list(string)	[]
enabled_metrics	List of enabled ASG metrics	list(string)	[]
subnet_ids	List of subnet IDs for the ASG	list(string)	n/a
max_size	Maximum number of instances in the ASG	number	10
min_size	Minimum number of instances in the ASG	number	0
desired_capacity	Desired number of instances in the ASG	number	0

Default for ec2_managed_scaling#

{
  maximum_scaling_step_size = 10
  minimum_scaling_step_size = 1
  target_capacity = 100
  status = "ENABLED"
}

Outputs#

Name	Description
id	The ID of the ECS cluster
name	The name of the ECS cluster
arn	The ARN of the ECS cluster
user_data	The rendered user data script for EC2 instances
default_ami_id	The default Amazon Linux 2023 ECS-optimized AMI ID
fargate_capacity_providers	The Fargate capacity providers associated with the ECS cluster
capacity_providers	The capacity providers associated with the ECS cluster
ec2_capacity_provider_name	The name of the EC2 capacity provider, if enabled
ecs_instance_role_name	The name of the ECS Instance role (for EC2 instances)
ecs_instance_role_arn	The ARN of the ECS Instance role (for EC2 instances)
ecs_task_execution_role_name	The name of the ECS Task Execution role (for task execution)
ecs_task_execution_role_arn	The ARN of the ECS Task Execution role (for task execution)
autoscaling_group_name	Name of the Auto Scaling Group
autoscaling_group_arn	ARN of the Auto Scaling Group
launch_template_id	ID of the Launch Template

IAM Roles#

This module automatically creates two IAM roles:

ECS Instance Role#

Name: ${var.name}-EcsInstanceRole

Purpose: For EC2 instances in the ECS cluster

Trust: ec2.amazonaws.com

Attached Policies:

service-role/AmazonEC2ContainerServiceforEC2Role - Allows EC2 instances to register with ECS
AmazonSSMManagedInstanceCore - Enables SSM Session Manager access
CloudWatchAgentServerPolicy - Allows CloudWatch metrics/logs

Security: Includes aws:SourceAccount condition to prevent confused deputy attacks

ECS Task Execution Role#

Name: ${var.name}-EcsTaskExecutionRole

Purpose: For ECS service to execute tasks (pull images, write logs)

Trust: ecs-tasks.amazonaws.com