Skip to main content

Quickstart

Deploy your first ECS cluster in minutes with a working example.

Architecture Overview

Understand the module structure, sub-modules, and design decisions.

Module Reference

Complete input and output variable reference for all modules.

Examples

Real-world example configurations for common deployment patterns.

What is this module?

The terraform-aws-modules/terraform-aws-ecs module provides a set of Terraform resources for creating and managing AWS Elastic Container Service (ECS) infrastructure. It supports all major ECS capacity provider types and handles the complexity of IAM roles, security groups, CloudWatch logging, and autoscaling.
module "ecs" {
  source = "terraform-aws-modules/ecs/aws"

  cluster_name = "my-cluster"

  cluster_capacity_providers = ["FARGATE", "FARGATE_SPOT"]

  default_capacity_provider_strategy = {
    FARGATE = {
      weight = 50
      base   = 20
    }
    FARGATE_SPOT = {
      weight = 50
    }
  }

  services = {
    my-service = {
      cpu    = 1024
      memory = 2048

      container_definitions = {
        app = {
          cpu       = 512
          memory    = 1024
          essential = true
          image     = "public.ecr.aws/aws-containers/ecsdemo-frontend:776fd50"
          portMappings = [
            {
              containerPort = 80
              protocol      = "tcp"
            }
          ]
        }
      }

      subnet_ids = ["subnet-abcde012", "subnet-bcde012a"]
    }
  }

  tags = {
    Environment = "production"
    Terraform   = "true"
  }
}

Available modules

Root Module

Integrated module that creates both cluster and services together. Best for simple deployments managed as a single unit.

Cluster Module

Standalone cluster sub-module. Create the cluster independently and attach services separately.

Service Module

Standalone service sub-module. Deploy services onto an existing cluster with full task definition control.

Container Definition Module

Building block for container definitions used within task definitions, with CloudWatch log group management.

Express Service Module

Simplified service module with opinionated defaults for rapid deployment.

Key features

Fargate Support

Deploy serverless containers with Fargate on-demand and Fargate Spot capacity providers.

EC2 Auto Scaling

Attach EC2 Auto Scaling Groups as capacity providers for full control over compute.

Managed Instances

Use ECS Managed Instances for simplified fleet management without managing ASGs.

Auto Scaling

Target tracking and scheduled scaling policies built in by default.

IAM Management

Task execution, task runtime, and service IAM roles automatically created and configured.

Service Connect

Native ECS Service Connect and AWS Cloud Map service discovery support.

Blue/Green Deploys

CodeDeploy blue/green deployment integration with load balancer traffic shifting.

FireLens Logging

Integrated CloudWatch and FireLens log forwarding configuration.

Security Groups

Automatic security group creation and management for services and instances.

Requirements

RequirementVersion
Terraform>= 1.5.7
AWS Provider>= 6.34

License

Apache 2.0 — maintained by Anton Babenko and contributors.

Build docs developers (and LLMs) love