Root Module Inputs

The root module creates both an ECS cluster and one or more services together. Use this when you want to manage the cluster and its services as a single Terraform unit.

module "ecs" {
  source  = "terraform-aws-modules/ecs/aws"
  version = "~> 7.0"

  cluster_name = "my-cluster"
  # ...
}

Resource Creation Controls

create

bool

Determines whether resources will be created (affects all resources). Default: true.

Cluster Configuration

cluster_name

string

Name of the ECS cluster (up to 255 letters, numbers, hyphens, and underscores). Default: "".

cluster_configuration

object

The execute command configuration for the cluster.

Show properties

execute_command_configuration

object

Configuration for ECS Exec.

Show properties

kms_key_id

string

Optional KMS key for encrypting exec data.

logging

string

Logging mode: DEFAULT, OVERRIDE, or NONE. Default: OVERRIDE.

log_configuration

object

CloudWatch/S3 log configuration for exec sessions.

managed_storage_configuration

object

KMS key configuration for Fargate ephemeral storage encryption.

Default: { execute_command_configuration = { log_configuration = { cloud_watch_log_group_name = "placeholder" } } }

cluster_service_connect_defaults

object

Configures a default Service Connect namespace for the cluster.

Show properties

namespace

string

required

The ARN or name of the Cloud Map namespace.

Default: null.

cluster_setting

list(object)

List of configuration blocks with cluster settings. Used to enable CloudWatch Container Insights. Default: [{ name = "containerInsights", value = "enabled" }].

cluster_tags

map(string)

A map of additional tags to add to the cluster. Default: {}.

Capacity Providers

cluster_capacity_providers

list(string)

List of capacity provider names to associate with the ECS cluster. Note: any capacity providers created by this module will be automatically added. Default: [].

default_capacity_provider_strategy

map(object)

Map of default capacity provider strategy definitions to use for the cluster.

Show properties

base

number

Minimum number of tasks to run on this provider.

name

string

Provider name. Falls back to map key if not set.

weight

number

Relative percentage of tasks to run on this provider.

Default: null.

capacity_providers

map(object)

Map of capacity provider definitions to create for the cluster.

Show properties

auto_scaling_group_provider

object

EC2 Auto Scaling Group provider configuration.

managed_instances_provider

object

ECS Managed Instances provider configuration.

Default: {}.

Services

services

map(object)

Map of service definitions to create. Each key is the service name. All attributes of the service module are supported within each service object.

services = {
  my-service = {
    cpu    = 1024
    memory = 2048
    container_definitions = {
      app = {
        image = "nginx:latest"
        portMappings = [{ containerPort = 80 }]
      }
    }
    subnet_ids = ["subnet-abc123"]
  }
}

Default: {}.

CloudWatch Logging

create_cloudwatch_log_group

bool

Determines whether a log group is created by this module for cluster logs. Default: true.

cloudwatch_log_group_name

string

Custom name of CloudWatch Log Group for ECS cluster. Default: null.

cloudwatch_log_group_retention_in_days

number

Number of days to retain log events. Default: 90.

cloudwatch_log_group_kms_key_id

string

KMS Key ARN for encrypting the log group. Default: null.

cloudwatch_log_group_class

string

Log class of the log group. Possible values: STANDARD or INFREQUENT_ACCESS. Default: null.

cloudwatch_log_group_tags

map(string)

Additional tags to add to the log group. Default: {}.

IAM — Infrastructure Role

create_infrastructure_iam_role

bool

Determines whether the ECS infrastructure IAM role should be created. Default: true.

infrastructure_iam_role_name

string

Name to use on the infrastructure IAM role. Default: null.

infrastructure_iam_role_use_name_prefix

bool

Use the role name as a prefix. Default: true.

infrastructure_iam_role_path

string

IAM role path. Default: null.

infrastructure_iam_role_description

string

Description of the infrastructure IAM role. Default: null.

infrastructure_iam_role_permissions_boundary

string

ARN of the permissions boundary policy. Default: null.

infrastructure_iam_role_source_policy_documents

list(string)

IAM policy documents merged into the role policy. Statements must have unique sids. Default: [].

infrastructure_iam_role_override_policy_documents

list(string)

IAM policy documents merged into the role policy. Statements with non-blank sids override matching statements. Default: [].

infrastructure_iam_role_statements

map(object)

Map of IAM policy statements for custom permission usage. Default: null.

infrastructure_iam_role_tags

map(string)

Additional tags for the infrastructure IAM role. Default: {}.

IAM — Task Execution Role

create_task_exec_iam_role

bool

Determines whether the ECS task execution IAM role should be created at the cluster level. Default: false.

Set to true when you want a single shared task execution role across all services in the cluster. The service module creates its own by default.

task_exec_iam_role_name

string

Name for the task execution IAM role. Default: null.

task_exec_iam_role_use_name_prefix

bool

Use the role name as a prefix. Default: true.

task_exec_iam_role_path

string

IAM role path. Default: null.

task_exec_iam_role_description

string

Description of the task execution IAM role. Default: null.

task_exec_iam_role_permissions_boundary

string

ARN of the permissions boundary policy. Default: null.

task_exec_iam_role_policies

map(string)

Map of IAM role policy ARNs to attach to the role. Default: {}.

task_exec_iam_role_tags

map(string)

Additional tags for the task execution IAM role. Default: {}.

create_task_exec_policy

bool

Determines whether the task execution IAM policy should be created. Includes AmazonECSTaskExecutionRolePolicy permissions plus Secrets Manager and SSM access. Default: true.

task_exec_secret_arns

list(string)

List of SecretsManager secret ARNs the task execution role can read. Default: [].

task_exec_ssm_param_arns

list(string)

List of SSM parameter ARNs the task execution role can read. Default: [].

task_exec_iam_statements

map(object)

Map of IAM policy statements for custom task execution role permissions. Default: null.

IAM — Node Role (Managed Instances)

create_node_iam_instance_profile

bool

Determines whether an IAM instance profile is created. Default: true.

node_iam_role_name

string

Name for the node IAM role/instance profile. Default: null.

node_iam_role_use_name_prefix

bool

Use the role name as a prefix. Default: true.

node_iam_role_path

string

IAM role/instance profile path. Default: null.

node_iam_role_description

string

Description of the node IAM role. Default: "ECS Managed Instances node IAM role".

node_iam_role_permissions_boundary

string

ARN of the permissions boundary policy. Default: null.

node_iam_role_additional_policies

map(string)

Additional policies to attach to the node IAM role. Default: {}.

node_iam_role_source_policy_documents

list(string)

IAM policy documents merged into the node role policy. Default: [].

node_iam_role_override_policy_documents

list(string)

IAM policy documents that override matching statements. Default: [].

node_iam_role_statements

map(object)

Map of IAM policy statements for the node role. Default: null.

node_iam_role_tags

map(string)

Additional tags for the node IAM role. Default: {}.

Security Group

create_security_group

bool

Determines if a security group is created. Default: true.

security_group_name

string

Name for the security group. Default: null.

security_group_use_name_prefix

bool

Use the security group name as a prefix. Default: true.

security_group_description

string

Description of the security group. Default: null.

security_group_ingress_rules

map(object)

Security group ingress rules. Default: {}.

security_group_egress_rules

map(object)

Security group egress rules. Default includes allow-all IPv4 and IPv6 egress.

security_group_tags

map(string)

Additional tags for the security group. Default: {}.

vpc_id

string

VPC ID where the security group will be created. Default: null.

Misc

region

string

AWS region where resources will be managed. Defaults to the provider region. Default: null.

Root Module

Cluster Module

Service Module

Container Definition Module

Express Service Module

Resource Creation Controls

Cluster Configuration

Capacity Providers

Services

CloudWatch Logging

IAM — Infrastructure Role

IAM — Task Execution Role

IAM — Node Role (Managed Instances)

Security Group

Misc

Build docs developers (and LLMs) love

Root Module

Cluster Module

Service Module

Container Definition Module

Express Service Module

​Resource Creation Controls

​Cluster Configuration

​Capacity Providers

​Services

​CloudWatch Logging

​IAM — Infrastructure Role

​IAM — Task Execution Role

​IAM — Node Role (Managed Instances)

​Security Group

​Misc

Build docs developers (and LLMs) love

Resource Creation Controls

Cluster Configuration

Capacity Providers

Services

CloudWatch Logging

IAM — Infrastructure Role

IAM — Task Execution Role

IAM — Node Role (Managed Instances)

Security Group

Misc