Skip to main content
The terraform-aws-modules/terraform-aws-ecs module creates and manages AWS Elastic Container Service (ECS) infrastructure. It handles the full complexity of ECS cluster and service setup — capacity providers, IAM roles, security groups, CloudWatch log groups, autoscaling, and container definitions — so you can focus on your application. You can use the module in two ways: as an integrated root module that creates both the cluster and its services together, or as separate sub-modules that you compose independently.

​
Sub-modules

Root module

Creates a cluster and one or more services in a single module call. Best for deployments managed as a unit by one team.

Cluster module

Creates an ECS cluster in isolation. Use this when you want to manage the cluster separately from the services that run on it.

Service module

Creates an ECS service with its task definition and all associated resources. Attach it to any existing cluster ARN.

Container definition module

A building block for container definitions inside task definitions. Manages CloudWatch log groups and supports FireLens configuration.

Express service module

A simplified service module with opinionated defaults for getting a service running quickly.

​
When to use each sub-module

Root module (integrated) — use this when a single team owns both the cluster and its services, or when you want everything provisioned together in one Terraform module call. The root module passes the cluster ARN to each service automatically. Cluster + service sub-modules (standalone) — use these when different teams or Terraform states manage the cluster and services separately. You create the cluster first, then pass its ARN to one or more service module calls.
The cluster module supports two task execution IAM role patterns: one shared role created at the cluster level (common when one team owns the cluster), or one role per service created at the service level (common when multiple teams share a cluster and need scoped secret access).

​
Key features

Fargate and EC2 capacity providers — support for Fargate on-demand, Fargate Spot, EC2 Auto Scaling Groups, and ECS Managed Instances. You cannot mix EC2-based and Fargate capacity providers on the same cluster. IAM role management — the module creates and configures the task execution role (used by ECS during task startup to pull images and retrieve secrets) and the tasks IAM role (used by containers at runtime to access AWS services). A separate service IAM role is created when a load balancer is attached. Security groups — security groups are created automatically for services and, when applicable, for EC2 instances. Ingress and egress rules are configurable per service. CloudWatch logging — the module creates CloudWatch log groups for the cluster and for container definitions by default, so log groups are fully managed by Terraform (tagged, retention-controlled, and destroyed with the resources). FireLens log forwarding — container definitions support FireLens configuration with a FluentBit sidecar for forwarding logs to third-party destinations. Application autoscaling — target tracking and scheduled scaling policies are built in. The service module always ignores desired_count in Terraform to avoid conflicts with application autoscaling. Service Connect and Cloud Map — native ECS Service Connect and AWS Cloud Map namespace configuration for service-to-service discovery. Blue/green deployments — ignore_task_definition_changes = true on the service module enables CodeDeploy blue/green deployment workflows where an external process manages task definition updates. Continuous delivery support — when ignore_task_definition_changes is enabled, Terraform ignores the task_definition and load_balancer arguments on the service, allowing an external CD pipeline (such as the amazon-ecs-deploy-task-definition GitHub Action) to manage deployments without conflicting with Terraform.

​
Requirements

RequirementVersion
Terraform>= 1.5.7
AWS provider>= 6.34

​
Source

The module is published on the Terraform Registry and maintained by Anton Babenko with help from contributors. 
module "ecs" {
  source  = "terraform-aws-modules/ecs/aws"
  version = "~> 7.0"
}
For individual sub-modules, use the double-slash path syntax: 
module "cluster" {
  source  = "terraform-aws-modules/ecs/aws//modules/cluster"
  version = "~> 7.0"
}

module "service" {
  source  = "terraform-aws-modules/ecs/aws//modules/service"
  version = "~> 7.0"
}
The module source on the Terraform Registry is terraform-aws-modules/ecs/aws. The GitHub repository is terraform-aws-modules/terraform-aws-ecs.

Build docs developers (and LLMs) love

Get started for freeTalk to us