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

create

bool

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

create_service

bool

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

create_task_definition

bool

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

create_iam_role

bool

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

create_task_exec_iam_role

bool

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

create_task_exec_policy

bool

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

create_tasks_iam_role

bool

Create the tasks runtime IAM role. Default: true.

create_security_group

bool

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

create_infrastructure_iam_role

bool

Create the infrastructure IAM role. Default: true.

Service

name

string

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

cluster_arn

string

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

launch_type

string

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

scheduling_strategy

string

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

desired_count

number

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

ignore_task_definition_changes

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.

availability_zone_rebalancing

string

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

enable_ecs_managed_tags

bool

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

enable_execute_command

bool

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

enable_fault_injection

bool

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

force_new_deployment

bool

Force a new task deployment. Default: true.

force_delete

bool

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

health_check_grace_period_seconds

number

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

propagate_tags

string

Propagate tags from SERVICE or TASK_DEFINITION. Default: null.

wait_for_steady_state

bool

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

sigint_rollback

bool

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

triggers

map(string)

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

timeouts

object

Create, update, and delete timeout configurations.

Show properties

create

string

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

update

string

Update timeout.

delete

string

Deletion timeout.

Default: null.

service_tags

map(string)

Additional tags for the service. Default: {}.

Deployment

deployment_controller

object

Deployment controller type.

Show properties

type

string

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

Default: null.

deployment_circuit_breaker

object

Deployment circuit breaker configuration.

Show properties

enable

bool

required

Enable the circuit breaker.

rollback

bool

required

Roll back on failure.

Default: null.

deployment_configuration

object

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

Show properties

strategy

string

ROLLING_UPDATE, CANARY, or LINEAR.

bake_time_in_minutes

string

Wait time after deployment completes.

canary_configuration

object

Canary percent and bake time.

linear_configuration

object

Step percent and step bake time.

lifecycle_hook

map(object)

Lifecycle hook configuration.

Default: null.

deployment_maximum_percent

number

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

deployment_minimum_healthy_percent

number

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

alarms

object

CloudWatch alarms configuration for deployment monitoring.

Show properties

alarm_names

list(string)

required

CloudWatch alarm names.

enable

bool

Enable alarms. Default: true.

rollback

bool

Roll back on alarm. Default: true.

Default: null.

capacity_provider_strategy

map(object)

Capacity provider strategy overrides for the service.

Show properties

capacity_provider

string

required

Capacity provider name.

base

number

Minimum tasks on this provider.

weight

number

Relative weight.

Default: null.

placement_constraints

map(object)

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

ordered_placement_strategy

list(object)

Ordered task placement strategies. Default: null.

Load Balancer

load_balancer

map(object)

Load balancer configuration.

Show properties

container_name

string

required

Name of the container to route traffic to.

container_port

number

required

Port on the container.

target_group_arn

string

ALB/NLB target group ARN.

elb_name

string

Classic ELB name.

advanced_configuration

object

Blue/green ALB configuration with alternate target group.

Default: null.

VPC Lattice

vpc_lattice_configurations

object

VPC Lattice configuration for cross-account service connectivity.

Show properties

role_arn

string

required

IAM role ARN.

target_group_arn

string

required

VPC Lattice target group ARN.

port_name

string

required

Port mapping name.

Default: null.

Service Connect

service_connect_configuration

object

ECS Service Connect configuration for service discovery.

Show properties

enabled

bool

Enable Service Connect. Default: true.

namespace

string

Cloud Map namespace ARN or name.

service

list(object)

Service Connect endpoints to expose.

log_configuration

object

Log driver for Service Connect proxy.

Default: null.

service_registries

object

Service discovery registries (Cloud Map).

Show properties

registry_arn

string

required

Cloud Map service registry ARN.

port

number

Port for SRV records.

container_name

string

Container name for A/AAAA records.

container_port

number

Container port for SRV records.

Default: null.

Task Definition

cpu

number

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

memory

number

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

family

string

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

network_mode

string

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

requires_compatibilities

list(string)

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

runtime_platform

object

CPU architecture and OS family.

Show properties

cpu_architecture

string

Default: "X86_64". Also supports ARM64.

operating_system_family

string

Default: "LINUX". Also supports WINDOWS_SERVER_*.

task_definition_arn

string

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

task_definition_placement_constraints

map(object)

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

track_latest

bool

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

skip_destroy

bool

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

ipc_mode

string

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

pid_mode

string

PID namespace: host or task. Default: null.

proxy_configuration

object

App Mesh proxy configuration. Default: null.

ephemeral_storage

object

Additional ephemeral storage beyond default (Fargate only).

Show properties

size_in_gib

number

required

Storage size (21–200 GiB).

Default: null.

volume

map(object)

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

volume_configuration

object

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

task_tags

map(string)

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

Container Definitions

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

external_id

string

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

scale

object

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

wait_until_stable

bool

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

Autoscaling

enable_autoscaling

bool

Enable autoscaling for the service. Default: true.

autoscaling_min_capacity

number

Minimum number of tasks. Default: 1.

autoscaling_max_capacity

number

Maximum number of tasks. Default: 10.

autoscaling_policies

map(object)

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

autoscaling_scheduled_actions

map(object)

Map of scheduled scaling actions.

Show properties

min_capacity

number

required

Minimum capacity at schedule time.

max_capacity

number

required

Maximum capacity at schedule time.

schedule

string

required

Schedule expression (cron/rate/at).

start_time

string

Schedule start time (RFC3339).

end_time

string

Schedule end time (RFC3339).

timezone

string

Timezone for the schedule.

Default: null.

autoscaling_suspended_state

object

Suspend scaling activities.

Show properties

dynamic_scaling_in_suspended

bool

Default: false.

dynamic_scaling_out_suspended

bool

Default: false.

scheduled_scaling_suspended

bool

Default: false.

Default: null.

Networking

subnet_ids

list(string)

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

assign_public_ip

bool

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

security_group_ids

list(string)

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

security_group_name

string

Security group name. Default: null.

security_group_use_name_prefix

bool

Use security group name as prefix. Default: true.

security_group_description

string

Security group description. Default: null.

security_group_ingress_rules

map(object)

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

security_group_egress_rules

map(object)

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

security_group_tags

map(string)

Additional security group tags. Default: {}.

vpc_id

string

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

IAM — Service Role

iam_role_arn

string

Existing service IAM role ARN. Default: null.

iam_role_name

string

Service IAM role name. Default: null.

iam_role_use_name_prefix

bool

Use role name as prefix. Default: true.

iam_role_path

string

IAM role path. Default: null.

iam_role_description

string

Role description. Default: null.

iam_role_permissions_boundary

string

Permissions boundary ARN. Default: null.

iam_role_statements

list(object)

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

iam_role_tags

map(string)

Additional tags. Default: {}.

IAM — Task Execution Role

task_exec_iam_role_arn

string

Existing task execution IAM role ARN. Default: null.

task_exec_iam_role_name

string

Task execution IAM role name. Default: null.

task_exec_iam_role_use_name_prefix

bool

Use name as prefix. Default: true.

task_exec_iam_role_path

string

IAM role path. Default: null.

task_exec_iam_role_description

string

Role description. Default: null.

task_exec_iam_role_permissions_boundary

string

Permissions boundary ARN. Default: null.

task_exec_iam_role_policies

map(string)

Policy ARNs to attach. Default: {}.

task_exec_iam_role_tags

map(string)

Additional tags. Default: {}.

task_exec_iam_role_max_session_duration

number

Maximum session duration in seconds. Default: null.

task_exec_iam_policy_path

string

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

task_exec_secret_arns

list(string)

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

task_exec_ssm_param_arns

list(string)

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

task_exec_iam_statements

list(object)

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

IAM — Tasks Role (Runtime)

tasks_iam_role_arn

string

Existing tasks IAM role ARN. Default: null.

tasks_iam_role_name

string

Tasks IAM role name. Default: null.

tasks_iam_role_use_name_prefix

bool

Use name as prefix. Default: true.

tasks_iam_role_path

string

IAM role path. Default: null.

tasks_iam_role_description

string

Role description. Default: null.

tasks_iam_role_permissions_boundary

string

Permissions boundary ARN. Default: null.

tasks_iam_role_policies

map(string)

Additional policy ARNs to attach. Default: {}.

tasks_iam_role_statements

list(object)

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

tasks_iam_role_tags

map(string)

Additional tags. Default: {}.

tasks_iam_role_max_session_duration

number

Maximum session duration in seconds. Default: null.

IAM — Infrastructure Role

create_infrastructure_iam_role

bool

Create the infrastructure IAM role. Default: true.

infrastructure_iam_role_arn

string

Existing infrastructure IAM role ARN. Default: null.

infrastructure_iam_role_name

string

Infrastructure IAM role name. Default: null.

infrastructure_iam_role_use_name_prefix

bool

Use name as prefix. Default: true.

infrastructure_iam_role_path

string

IAM role path. Default: null.

infrastructure_iam_role_description

string

Role description. Default: null.

infrastructure_iam_role_permissions_boundary

string

Permissions boundary ARN. Default: null.

infrastructure_iam_role_tags

map(string)

Additional tags. Default: {}.

Misc

region

string

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

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

Build docs developers (and LLMs) love

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

Build docs developers (and LLMs) love

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