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

bool

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

Cluster Configuration

string

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

object

The execute command configuration for the cluster.

Show properties

object

Configuration for ECS Exec.

Show properties

string

Optional KMS key for encrypting exec data.

string

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

object

CloudWatch/S3 log configuration for exec sessions.

object

KMS key configuration for Fargate ephemeral storage encryption.

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

object

Configures a default Service Connect namespace for the cluster.

Show properties

string

required

The ARN or name of the Cloud Map namespace.

Default: null.

list(object)

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

map(string)

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

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: [].

map(object)

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

Show properties

number

Minimum number of tasks to run on this provider.

string

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

number

Relative percentage of tasks to run on this provider.

Default: null.

map(object)

Map of capacity provider definitions to create for the cluster.

Show properties

object

EC2 Auto Scaling Group provider configuration.

object

ECS Managed Instances provider configuration.

Default: {}.

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

bool

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

string

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

number

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

string

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

string

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

map(string)

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

IAM — Infrastructure Role

bool

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

string

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

bool

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

string

IAM role path. Default: null.

string

Description of the infrastructure IAM role. Default: null.

string

ARN of the permissions boundary policy. Default: null.

list(string)

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

list(string)

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

map(object)

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

map(string)

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

IAM — Task Execution 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.

string

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

bool

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

string

IAM role path. Default: null.

string

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

string

ARN of the permissions boundary policy. Default: null.

map(string)

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

map(string)

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

bool

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

list(string)

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

list(string)

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

map(object)

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

IAM — Node Role (Managed Instances)

bool

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

string

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

bool

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

string

IAM role/instance profile path. Default: null.

string

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

string

ARN of the permissions boundary policy. Default: null.

map(string)

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

list(string)

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

list(string)

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

map(object)

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

map(string)

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

Security Group

bool

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

string

Name for the security group. Default: null.

bool

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

string

Description of the security group. Default: null.

map(object)

Security group ingress rules. Default: {}.

map(object)

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

map(string)

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

string

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

Misc

string

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

map(string)

Map of tags to add to all resources. Default: {}.

bool

Deprecated — will be removed in v8.0. Disables the default postfix added to resource names and descriptions in v7.0. Default: false.

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

​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

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