Service Module Inputs

The service sub-module creates an ECS service with task definition, container definitions, IAM roles, security group, and optional autoscaling.

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

  name        = "my-service"
  cluster_arn = module.ecs_cluster.arn

  cpu    = 1024
  memory = 2048

  container_definitions = {
    app = {
      image = "nginx:latest"
      portMappings = [{ containerPort = 80 }]
    }
  }

  subnet_ids = ["subnet-abc123"]
}

Resource Creation Controls

bool

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

bool

Determines whether the ECS service resource will be created. Set to false to create only the task definition. Default: true.

bool

Determines whether to create a task definition or use an existing one. Default: true.

bool

Determines whether the ECS service IAM role should be created (for load balancer management). Default: true.

bool

Create a service-level task execution IAM role. Default: true.

bool

Create the task execution IAM policy with ECR, CloudWatch, Secrets Manager, and SSM permissions. Default: true.

bool

Create the tasks runtime IAM role. Default: true.

bool

Create a security group for the service. Default: true.

bool

Create the infrastructure IAM role. Default: true.

Service

string

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

string

ARN of the ECS cluster where the service will be provisioned. Default: "".

string

Launch type for the service: EC2, FARGATE, or EXTERNAL. Default: "FARGATE".

string

Scheduling strategy: REPLICA or DAEMON. Default: null (REPLICA).

number

Number of task instances to run. Note: this value is always ignored after initial creation — autoscaling manages the count. Default: 1.

bool

Whether changes to task definition, and load_balancer should be ignored. Set to true for CodeDeploy blue/green deployments.

Changing this after service creation forces the service to be re-created.

Default: false.

string

Enable ECS automatic task rebalancing across AZs: ENABLED or DISABLED. Default: null.

bool

Enable Amazon ECS managed tags for tasks. Default: true.

bool

Enable Amazon ECS Exec for interactive debugging. Default: false.

bool

Enable fault injection requests from task containers. Default: null.

bool

Force a new task deployment. Default: true.

bool

Delete service even if not scaled to zero (REPLICA strategy only). Default: null.

number

Seconds to ignore failing load balancer health checks on new tasks. Default: null.

string

Propagate tags from SERVICE or TASK_DEFINITION. Default: null.

bool

Wait for the service to reach steady state before completing. Default: null.

bool

Enable graceful termination using SIGINT signals (requires wait_for_steady_state = true). Default: null.

map(string)

Map of values that trigger in-place redeployments when changed. Useful with timestamp(). Default: null.

object

Create, update, and delete timeout configurations.

Show properties

string

Creation timeout (e.g., "10m").

string

Update timeout.

string

Deletion timeout.

Default: null.

map(string)

Additional tags for the service. Default: {}.

Deployment

object

Deployment controller type.

Show properties

string

ECS (rolling), CODE_DEPLOY (blue/green), or EXTERNAL.

Default: null.

object

Deployment circuit breaker configuration.

Show properties

bool

required

Enable the circuit breaker.

bool

required

Roll back on failure.

Default: null.

object

Advanced deployment configuration (rolling, canary, linear strategies).

Show properties

string

ROLLING_UPDATE, CANARY, or LINEAR.

string

Wait time after deployment completes.

object

Canary percent and bake time.

object

Step percent and step bake time.

map(object)

Lifecycle hook configuration.

Default: null.

number

Upper limit of running tasks during deployment (as % of desired count). Default: 200.

number

Lower limit of healthy tasks during deployment (as % of desired count). Default: 66.

object

CloudWatch alarms configuration for deployment monitoring.

Show properties

list(string)

required

CloudWatch alarm names.

bool

Enable alarms. Default: true.

bool

Roll back on alarm. Default: true.

Default: null.

map(object)

Capacity provider strategy overrides for the service.

Show properties

string

required

Capacity provider name.

number

Minimum tasks on this provider.

number

Relative weight.

Default: null.

map(object)

Task placement constraints (up to 10). Default: null.

list(object)

Ordered task placement strategies. Default: null.

Load Balancer

map(object)

Load balancer configuration.

Show properties

string

required

Name of the container to route traffic to.

number

required

Port on the container.

string

ALB/NLB target group ARN.

string

Classic ELB name.

object

Blue/green ALB configuration with alternate target group.

Default: null.

VPC Lattice

object

VPC Lattice configuration for cross-account service connectivity.

Show properties

string

required

IAM role ARN.

string

required

VPC Lattice target group ARN.

string

required

Port mapping name.

Default: null.

Service Connect

object

ECS Service Connect configuration for service discovery.

Show properties

bool

Enable Service Connect. Default: true.

string

Cloud Map namespace ARN or name.

list(object)

Service Connect endpoints to expose.

object

Log driver for Service Connect proxy.

Default: null.

object

Service discovery registries (Cloud Map).

Show properties

string

required

Cloud Map service registry ARN.

number

Port for SRV records.

string

Container name for A/AAAA records.

number

Container port for SRV records.

Default: null.

Task Definition

number

CPU units for the task (required for FARGATE). Default: 1024.

number

Memory in MiB for the task (required for FARGATE). Default: 2048.

string

Unique name for the task definition family. Default: null (uses service name).

string

Docker networking mode: none, bridge, awsvpc, or host. Default: "awsvpc".

list(string)

Launch types required: EC2, FARGATE, EXTERNAL, MANAGED_INSTANCES. Default: ["FARGATE"].

object

CPU architecture and OS family.

Show properties

string

Default: "X86_64". Also supports ARM64.

string

Default: "LINUX". Also supports WINDOWS_SERVER_*.

string

Existing task definition ARN. Required when create_task_definition = false. Default: null.

map(object)

Task-level placement constraints (up to 10). Default: null.

bool

Track the latest ACTIVE task definition revision on AWS. Default: true.

bool

Don’t delete the task definition when the service is deleted. Default: null.

string

IPC namespace: host, task, or none. Default: null.

string

PID namespace: host or task. Default: null.

object

App Mesh proxy configuration. Default: null.

object

Additional ephemeral storage beyond default (Fargate only).

Show properties

number

required

Storage size (21–200 GiB).

Default: null.

map(object)

Volume configurations for the task (EFS, Docker, FSx, host bind mounts). Default: null.

object

EBS volume configuration for volumes attached at launch time. Default: null.

map(string)

Additional tags for the task definition/set. Default: {}.

Container Definitions

map(object)

Map of container definitions. Each key is the container name. Supports all ECS container definition parameters.Key module-specific additions:

enable_cloudwatch_logging (bool) — creates a CloudWatch log group. Default: true
cloudwatch_log_group_name — custom log group name
cloudwatch_log_group_retention_in_days — log retention days
create_cloudwatch_log_group — whether the module manages the log group

Default: {}.

Task Set

string

External ID associated with the task set. Default: null.

object

Desired percentage of tasks to run in the task set (always ignored after creation). Default: null.

bool

Wait until the task set reaches STEADY_STATE. Default: null.

Autoscaling

bool

Enable autoscaling for the service. Default: true.

number

Minimum number of tasks. Default: 1.

number

Maximum number of tasks. Default: 10.

map(object)

Map of autoscaling policies. Supports TargetTrackingScaling and StepScaling policy types. Default includes CPU and Memory target tracking policies.

map(object)

Map of scheduled scaling actions.

Show properties

number

required

Minimum capacity at schedule time.

number

required

Maximum capacity at schedule time.

string

required

Schedule expression (cron/rate/at).

string

Schedule start time (RFC3339).

string

Schedule end time (RFC3339).

string

Timezone for the schedule.

Default: null.

object

Suspend scaling activities.

Show properties

bool

Default: false.

bool

Default: false.

bool

Default: false.

Default: null.

Networking

list(string)

Subnets to associate with the task or service. Default: [].

bool

Assign a public IP to the task ENI (Fargate only). Default: false.

list(string)

Additional security groups to associate with the task. Default: [].

string

Security group name. Default: null.

bool

Use security group name as prefix. Default: true.

string

Security group description. Default: null.

map(object)

Ingress rules for the service security group. Default: {}.

map(object)

Egress rules for the service security group. Default: {}.

map(string)

Additional security group tags. Default: {}.

string

VPC ID for the service. Derived from subnets if not provided. Default: null.

IAM — Service Role

string

Existing service IAM role ARN. Default: null.

string

Service IAM role name. Default: null.

bool

Use role name as prefix. Default: true.

string

IAM role path. Default: null.

string

Role description. Default: null.

string

Permissions boundary ARN. Default: null.

list(object)

Custom IAM statements for the service role. Default: null.

map(string)

Additional tags. Default: {}.

IAM — Task Execution Role

string

Existing task execution IAM role ARN. Default: null.

string

Task execution IAM role name. Default: null.

bool

Use name as prefix. Default: true.

string

IAM role path. Default: null.

string

Role description. Default: null.

string

Permissions boundary ARN. Default: null.

map(string)

Policy ARNs to attach. Default: {}.

map(string)

Additional tags. Default: {}.

number

Maximum session duration in seconds. Default: null.

string

Path for the task execution IAM policy. Default: null.

list(string)

Secrets Manager ARNs the execution role can read. Default: [].

list(string)

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

list(object)

Custom IAM statements for the execution role. Default: null.

IAM — Tasks Role (Runtime)

string

Existing tasks IAM role ARN. Default: null.

string

Tasks IAM role name. Default: null.

bool

Use name as prefix. Default: true.

string

IAM role path. Default: null.

string

Role description. Default: null.

string

Permissions boundary ARN. Default: null.

map(string)

Additional policy ARNs to attach. Default: {}.

list(object)

Custom IAM statements for the tasks role. Default: null.

map(string)

Additional tags. Default: {}.

number

Maximum session duration in seconds. Default: null.

IAM — Infrastructure Role

bool

Create the infrastructure IAM role. Default: true.

string

Existing infrastructure IAM role ARN. Default: null.

string

Infrastructure IAM role name. Default: null.

bool

Use name as prefix. Default: true.

string

IAM role path. Default: null.

string

Role description. Default: null.

string

Permissions boundary ARN. Default: null.

map(string)

Additional tags. Default: {}.

Misc

string

AWS region. Defaults to provider region. Default: null.

map(string)

Tags for all resources. Default: {}.

bool

Deprecated — will be removed in v8.0. Disables v7.0 name/description postfixes. Default: false.

Root Module

Cluster Module

Service Module

Container Definition Module

Express Service Module

Resource Creation Controls

Service

Deployment

Load Balancer

VPC Lattice

Service Connect

Task Definition

Container Definitions

Task Set

Autoscaling

Networking

IAM — Service Role

IAM — Task Execution Role

IAM — Tasks Role (Runtime)

IAM — Infrastructure Role

Misc

​Resource Creation Controls

​Service

​Deployment

​Load Balancer

​VPC Lattice

​Service Connect

​Task Definition

​Container Definitions

​Task Set

​Autoscaling

​Networking

​IAM — Service Role

​IAM — Task Execution Role

​IAM — Tasks Role (Runtime)

​IAM — Infrastructure Role

​Misc

Resource Creation Controls

Service

Deployment

Load Balancer

VPC Lattice

Service Connect

Task Definition

Container Definitions

Task Set

Autoscaling

Networking

IAM — Service Role

IAM — Task Execution Role

IAM — Tasks Role (Runtime)

IAM — Infrastructure Role

Misc