Skip to main content
Service Catalog Version 0.108.7Last updated in version 0.107.6

Amazon ECS Service

View SourceRelease Notes

Overview

This service contains Terraform code to deploy a production-grade ECS service on AWS using Elastic Container Service(ECS).

ECS architectureECS architecture

Features

  • Deploy an ECS Service onto an existing ECS cluster
  • Define arbitrary tasks via JSON
  • Optionally deploy a canary task for testing release candidates
  • Configure and deploy load balancing and optional DNS records
  • Auto scaling of ECS tasks
  • Cloudwatch metrics and alerts

Learn

note

This repo is a part of the Gruntwork Service Catalog, a collection of reusable, battle-tested, production ready infrastructure code. If you’ve never used the Service Catalog before, make sure to read How to use the Gruntwork Service Catalog!

Under the hood, this is all implemented using Terraform modules from the Gruntwork terraform-aws-ecs repo. If you are a subscriber and don’t have access to this repo, email support@gruntwork.io.

Core concepts

To understand core concepts like what is ECS, the different cluster types, how to authenticate to Kubernetes, and more, see the documentation in the terraform-aws-ecs repo.

Repo organization

  • modules: the main implementation code for this repo, broken down into multiple standalone, orthogonal submodules.
  • examples: This folder contains working examples of how to use the submodules.
  • test: Automated tests for the modules and examples.

Deploy

Non-production deployment (quick start for learning)

If you just want to try this repo out for experimenting and learning, check out the following resources:

  • examples/for-learning-and-testing folder: The examples/for-learning-and-testing folder contains standalone sample code optimized for learning, experimenting, and testing (but not direct production usage).

Production deployment

If you want to deploy this repo in production, check out the following resources:

Manage

For information on how to manage your ECS service, see the documentation in the module ecs repo.

Sample Usage

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S ECS-SERVICE MODULE
# ------------------------------------------------------------------------------------------------------

module "ecs_service" {

source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/services/ecs-service?ref=v0.108.7"

# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------

# List of container definitions to use for the ECS task. Each entry
# corresponds to a different ECS container definition.
container_definitions = <any>

# A map of all the listeners on the load balancer. The keys should be the port
# numbers and the values should be the ARN of the listener for that port.
default_listener_arns = <map(string)>

# The default port numbers on the load balancer to attach listener rules to.
# You can override this default on a rule-by-rule basis by setting the
# listener_ports parameter in each rule. The port numbers specified in this
# variable and the listener_ports parameter must exist in var.listener_arns.
default_listener_ports = <list(string)>

# The ARN of the cluster to which the ecs service should be deployed.
ecs_cluster_arn = <string>

# The name of the ecs cluster to deploy the ecs service onto.
ecs_cluster_name = <string>

# The name of the ECS service (e.g. my-service-stage)
service_name = <string>

# ----------------------------------------------------------------------------------------------------
# OPTIONAL VARIABLES
# ----------------------------------------------------------------------------------------------------

# A list of ARNs of the SNS topic(s) to write alarm events to
alarm_sns_topic_arns = []

# A list of SNS topic ARNs to notify when the route53 health check changes to
# ALARM, OK, or INSUFFICIENT_DATA state. Note: these SNS topics MUST be in
# us-east-1! This is because Route 53 only sends CloudWatch metrics to
# us-east-1, so we must create the alarm in that region, and therefore, can
# only notify SNS topics in that region
alarm_sns_topic_arns_us_east_1 = []

# The time period, in seconds, during which requests from a client should be
# routed to the same Target. After this time period expires, the load
# balancer-generated cookie is considered stale. The acceptable range is 1
# second to 1 week (604800 seconds). The default value is 1 day (86400
# seconds). Only used if var.elb_target_groups is set.
alb_sticky_session_cookie_duration = 86400

# The type of Sticky Sessions to use. See https://goo.gl/MNwqNu for possible
# values. Only used if var.elb_target_groups is set.
alb_sticky_session_type = "lb_cookie"

# List of container definitions to use for the canary ECS task. Each entry
# corresponds to a different ECS container definition.
canary_container_definitions = []

# Which version of the ECS Service Docker container to deploy as a canary
# (e.g. 0.57)
canary_version = null

# The capacity provider strategy to use for the service. Note that the
# capacity providers have to be present on the ECS cluster before deploying
# the ECS service. When provided, var.launch_type is ignored.
capacity_provider_strategy = []

# The name of the container, as it appears in the var.task_arn Task
# definition, to associate with a CLB. Currently, ECS can only associate a CLB
# with a single container per service. Only used if clb_name is set.
clb_container_name = null

# The port on the container in var.clb_container_name to associate with an
# CLB. Currently, ECS can only associate a CLB with a single container per
# service. Only used if clb_name is set.
clb_container_port = null

# The name of a Classic Load Balancer (CLB) to associate with this service.
# Containers in the service will automatically register with the CLB when
# booting up. Set to null if using ELBv2.
clb_name = null

# The ARN of a KMS CMK to use for encrypting log events in the CloudWatch
# Logs. Set to null to disable encryption. Only used if
# var.create_cloudwatch_log_group is true.
cloudwatch_log_group_kms_key_id = null

# The name for the Cloudwatch logs that will be generated by the ecs service.
# Only used (and required) if var.create_cloudwatch_log_group is true.
cloudwatch_log_group_name = null

# Number of days to retain log events. Possible values are: 1, 3, 5, 7, 14,
# 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 3653, and 0. Select 0
# to never expire. Only used if var.create_cloudwatch_log_group is true.
cloudwatch_log_group_retention = null

# A map of tags to apply to the Cloudwatch log group. Each item in this list
# should be a map with the parameters key and value. Only used if
# var.create_cloudwatch_log_group is true.
cloudwatch_log_group_tags = {}

# The number of CPU units to allocate to the ECS Service.
cpu = 1

# When true, create and manage the CloudWatch Log Group in the Terraform
# module instead of relying on ECS. This is useful for configuring options
# that are not available in the ECS native feature of managing the Log Group
# (e.g., encryption support).
create_cloudwatch_log_group = false

# Set to true if you want a DNS record automatically created and pointed at
# the the load balancer for the ECS service
create_route53_entry = false

# If var.use_custom_docker_run_command is set to true, set this variable to
# the custom docker run command you want to provide
custom_docker_command = null

# The name to use for the ECS Service IAM role, which is used to grant
# permissions to the ECS service to register the task IPs to ELBs.
custom_ecs_service_role_name = null

# Prefix for name of the custom IAM policies created by this module (those
# resulting from var.iam_policy and var.secrets_access). If omitted, defaults
# to var.service_name.
custom_iam_policy_prefix = null

# Prefix for name of the IAM role used by the ECS task.
custom_iam_role_name_prefix = null

# Prefix for name of task execution IAM role and policy that grants access to
# CloudWatch and ECR.
custom_task_execution_iam_role_name_prefix = null

# Create a dependency between the resources in this module to the interpolated
# values in this list (and thus the source resources). In other words, the
# resources in this module will now depend on the resources backing the values
# in this list such that those resources need to be created before the
# resources in this module, and the resources in this module need to be
# destroyed before the resources in the list.
dependencies = []

# Set the logging level of the deployment check script. You can set this to
# `error`, `warn`, or `info`, in increasing verbosity.
deployment_check_loglevel = "info"

# Seconds to wait before timing out each check for verifying ECS service
# deployment. See ecs_deploy_check_binaries for more details.
deployment_check_timeout_seconds = 600

# Set to 'true' to prevent the task from attempting to continuously redeploy
# after a failed health check.
deployment_circuit_breaker_enabled = false

# Set to 'true' to also automatically roll back to the last successful
# deployment. deploy_circuit_breaker_enabled must also be true to enable this
# behavior.
deployment_circuit_breaker_rollback = false

# The upper limit, as a percentage of var.desired_number_of_tasks, of the
# number of running tasks that can be running in a service during a
# deployment. Setting this to more than 100 means that during deployment, ECS
# will deploy new instances of a Task before undeploying the old ones.
deployment_maximum_percent = 200

# The lower limit, as a percentage of var.desired_number_of_tasks, of the
# number of running tasks that must remain running and healthy in a service
# during a deployment. Setting this to less than 100 means that during
# deployment, ECS may undeploy old instances of a Task before deploying new
# ones.
deployment_minimum_healthy_percent = 100

# How many instances of the ECS Service to run across the ECS cluster for a
# canary deployment. Typically, only 0 or 1 should be used.
desired_number_of_canary_tasks = 0

# How many instances of the ECS Service to run across the ECS cluster
desired_number_of_tasks = 1

# The domain name to create a route 53 record for. This DNS record will point
# to the load balancer for the ECS service
domain_name = null

# The ID of the security group that should be applied to ecs service instances
ecs_instance_security_group_id = null

# A map of ports to be opened via security groups applied to the EC2 instances
# that back the ECS cluster, when not using fargate. The key should be the
# container port and the value should be what host port to map it to.
ecs_node_port_mappings = {}

# (Optional) A map of EFS volumes that containers in your task may use. Each
# item in the list should be a map compatible with
# https://www.terraform.io/docs/providers/aws/r/ecs_task_definition.html#efs-volume-configuration-arguments.
efs_volumes = {}

# The amount time for targets to warm up before the load balancer sends them a
# full share of requests. The range is 30-900 seconds or 0 to disable. The
# default value is 0 seconds. Only used if var.elb_target_groups is set.
elb_slow_start = 0

# The amount of time for Elastic Load Balancing to wait before changing the
# state of a deregistering target from draining to unused. The range is 0-3600
# seconds. Only used if var.elb_target_groups is set.
elb_target_group_deregistration_delay = 300

# The ID of the VPC in which to create the target group. Only used if
# var.elb_target_groups is set.
elb_target_group_vpc_id = null

# Configurations for ELB target groups for ALBs and NLBs that should be
# associated with the ECS Tasks. Each entry corresponds to a separate target
# group. Set to the empty object ({}) if you are not using an ALB or NLB.
elb_target_groups = {}

# Set to true to enable Cloudwatch alarms on the ecs service instances
enable_cloudwatch_alarms = true

# Whether or not to enable the ECS deployment check binary to make terraform
# wait for the task to be deployed. See ecs_deploy_check_binaries for more
# details. You must install the companion binary before the check can be used.
# Refer to the README for more details.
enable_ecs_deployment_check = true

# Specifies whether to enable Amazon ECS Exec for the tasks within the
# service.
enable_execute_command = false

# Set this to true to create a route 53 health check and Cloudwatch alarm that
# will alert if your domain becomes unreachable
enable_route53_health_check = false

# Set this to true to allow the ecs service to be accessed by other ecs nodes
expose_ecs_service_to_other_ecs_nodes = false

fixed_response_rules = {}

forward_rules = {}

# If true, enable health checks on the target group. Only applies to ELBv2.
# For CLBs, health checks are not configurable.
health_check_enabled = true

# Seconds to ignore failing load balancer health checks on newly instantiated
# tasks to prevent premature shutdown, up to 2,147,483,647. Only valid for
# services configured to use load balancers.
health_check_grace_period_seconds = 0

# The number of consecutive successful health checks required before
# considering an unhealthy Target healthy. The acceptable range is 2 to 10.
health_check_healthy_threshold = 5

# The approximate amount of time, in seconds, between health checks of an
# individual Target. Minimum value 5 seconds, Maximum value 300 seconds.
health_check_interval = 30

# The HTTP codes to use when checking for a successful response from a Target.
# You can specify multiple values (e.g. '200,202') or a range of values (e.g.
# '200-299'). Required when using ALBs.
health_check_matcher = "200"

# The ping path that is the destination on the Targets for health checks.
# Required when using ALBs.
health_check_path = "/"

# The port the ELB uses when performing health checks on Targets. The default
# is to use the port on which each target receives traffic from the load
# balancer, indicated by the value 'traffic-port'.
health_check_port = "traffic-port"

# The amount of time, in seconds, during which no response from a Target means
# a failed health check. The acceptable range is 2 to 60 seconds.
health_check_timeout = 5

# The number of consecutive failed health checks required before considering a
# target unhealthy. The acceptable range is 2 to 10. For NLBs, this value must
# be the same as the health_check_healthy_threshold.
health_check_unhealthy_threshold = 2

# The period, in seconds, over which to measure the CPU utilization percentage
high_cpu_utilization_period = 300

# Trigger an alarm if the ECS Service has a CPU utilization percentage above
# this threshold
high_cpu_utilization_threshold = 90

# Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Must
# be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
high_cpu_utilization_treat_missing_data = "missing"

# The period, in seconds, over which to measure the memory utilization
# percentage
high_memory_utilization_period = 300

# Trigger an alarm if the ECS Service has a memory utilization percentage
# above this threshold
high_memory_utilization_threshold = 90

# Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Must
# be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
high_memory_utilization_treat_missing_data = "missing"

# The ID of the Route 53 hosted zone into which the Route 53 DNS record should
# be written
hosted_zone_id = null

# An object defining the policy to attach to the ECS task. Accepts a map of
# objects, where the map keys are sids for IAM policy statements, and the
# object fields are the resources, actions, and the effect ("Allow" or "Deny")
# of the statement.
iam_policy = null

# The launch type of the ECS service. Must be one of EC2 or FARGATE. When
# using FARGATE, you must set the network mode to awsvpc and configure it.
# When using EC2, you can configure the placement strategy using the variables
# var.placement_strategy_type, var.placement_strategy_field,
# var.placement_constraint_type, var.placement_constraint_expression. This
# variable is ignored if var.capacity_provider_strategy is provided.
launch_type = "EC2"

# The ID of the Route 53 Hosted Zone in which to create a DNS A record pointed
# to the ECS service's load balancer
lb_hosted_zone_id = null

# A map of tags to apply to the elb target group. Each item in this list
# should be a map with the parameters key and value.
lb_target_group_tags = {}

# The maximum number of instances of the ECS Service to run. Auto scaling will
# never scale out above this number.
max_number_of_tasks = 3

# How much memory, in MB, to give the ECS Service.
memory = 500

# The minimum number of instances of the ECS Service to run. Auto scaling will
# never scale in below this number.
min_number_of_tasks = 1

# The configuration to use when setting up the VPC network mode. Required and
# only used if network_mode is awsvpc.
network_configuration = null

# The Docker networking mode to use for the containers in the task. The valid
# values are none, bridge, awsvpc, and host. If the network_mode is set to
# awsvpc, you must configure var.network_configuration.
network_mode = "bridge"

# Service level strategy rules that are taken into consideration during task
# placement. List from top to bottom in order of precedence. Updates to this
# configuration will take effect next task deployment unless
# force_new_deployment is enabled. The maximum number of
# ordered_placement_strategy blocks is 5.
ordered_placement_strategy = [{"field":"cpu","type":"binpack"}]

# The DNS name that was assigned by AWS to the load balancer upon creation
original_lb_dns_name = null

# Cluster Query Language expression to apply to the constraint for matching.
# Does not need to be specified for the distinctInstance constraint type.
placement_constraint_expression = "attribute:ecs.ami-id != 'ami-fake'"

# The type of constraint to apply for container instance placement. The only
# valid values at this time are memberOf and distinctInstance.
placement_constraint_type = "memberOf"

# Whether tags should be propogated to the tasks from the service or from the
# task definition. Valid values are SERVICE and TASK_DEFINITION. Defaults to
# SERVICE. If set to null, no tags are created for tasks.
propagate_tags = "SERVICE"

# Use the name of the Envoy proxy container from `container_definitions` as
# the container name.
proxy_configuration_container_name = null

# A map of network configuration parameters to provide the Container Network
# Interface (CNI) plugin.
proxy_configuration_properties = null

redirect_rules = {}

# The path, without any leading slash, that can be used as a health check
# (e.g. healthcheck) by Route 53. Should return a 200 OK when the service is
# up and running.
route53_health_check_path = "/"

# The port to use for Route 53 health checks. This should be the port for the
# service that is available at the publicly accessible domain name
# (var.domain_name).
route53_health_check_port = 80

# The protocol to use for Route 53 health checks. Should be one of HTTP,
# HTTPS.
route53_health_check_protocol = "HTTP"

# The optional external_id to be used in the us-east-1 provider block defined
# in the route53-health-check-alarms module. This module configures its own
# AWS provider to ensure resources are created in us-east-1.
route53_health_check_provider_external_id = null

# The optional AWS profile to be used in the us-east-1 provider block defined
# in the route53-health-check-alarms module. This module configures its own
# AWS provider to ensure resources are created in us-east-1.
route53_health_check_provider_profile = null

# The optional role_arn to be used in the us-east-1 provider block defined in
# the route53-health-check-alarms module. This module configures its own AWS
# provider to ensure resources are created in us-east-1.
route53_health_check_provider_role_arn = null

# The optional session_name to be used in the us-east-1 provider block defined
# in the route53-health-check-alarms module. This module configures its own
# AWS provider to ensure resources are created in us-east-1.
route53_health_check_provider_session_name = null

# The optional path to a credentials file used in the us-east-1 provider block
# defined in the route53-health-check-alarms module. This module configures
# its own AWS provider to ensure resources are created in us-east-1.
route53_health_check_provider_shared_credentials_file = null

# Define runtime platform options
runtime_platform = null

# A list of ARNs of Secrets Manager secrets that the task should have
# permissions to read. The IAM role for the task will be granted
# `secretsmanager:GetSecretValue` for each secret in the list. The ARN can be
# either the complete ARN, including the randomly generated suffix, or the ARN
# without the suffix. If the latter, the module will look up the full ARN
# automatically. This is helpful in cases where you don't yet know the
# randomly generated suffix because the rest of the ARN is a predictable
# value.
secrets_access = []

# A list of ARNs for Secrets Manager secrets that the ECS execution IAM policy
# should be granted access to read. Note that this is different from the ECS
# task IAM policy. The execution policy is concerned with permissions required
# to run the ECS task. The ARN can be either the complete ARN, including the
# randomly generated suffix, or the ARN without the suffix. If the latter, the
# module will look up the full ARN automatically. This is helpful in cases
# where you don't yet know the randomly generated suffix because the rest of
# the ARN is a predictable value.
secrets_manager_arns = []

# The ARN of the kms key associated with secrets manager
secrets_manager_kms_key_arn = null

# The name of the aws_security_group that gets created if var.network_mode is
# awsvpc and custom rules are specified for the ECS Fargate worker via
# var.network_configuration.security_group_rules. Defaults to var.service_name
# if not specified.
service_security_group_name = null

# A map of tags to apply to the ECS service. Each item in this list should be
# a map with the parameters key and value.
service_tags = {}

# The CPU units for the instances that Fargate will spin up. Options here:
# https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html#fargate-tasks-size.
# Required when using FARGATE launch type.
task_cpu = null

# A map of tags to apply to the task definition. Each item in this list should
# be a map with the parameters key and value.
task_definition_tags = {}

# Ephemeral storage size for Fargate tasks. See:
# https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#task_definition_ephemeralStorage
task_ephemeral_storage = null

# The memory units for the instances that Fargate will spin up. Options here:
# https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html#fargate-tasks-size.
# Required when using FARGATE launch type.
task_memory = null

# If true, the ALB will use use Sticky Sessions as described at
# https://goo.gl/VLcNbk. Only used if var.elb_target_groups is set. Note that
# this can only be true when associating with an ALB. This cannot be used with
# CLBs or NLBs.
use_alb_sticky_sessions = false

# Whether or not to enable auto scaling for the ecs service
use_auto_scaling = true

# Set this to true if you want to pass a custom docker run command. If you set
# this to true, you must supply var.custom_docker_command
use_custom_docker_run_command = false

# (Optional) A map of volume blocks that containers in your task may use. The
# key should be the name of the volume and the value should be a map
# compatible with
# https://www.terraform.io/docs/providers/aws/r/ecs_task_definition.html#volume-block-arguments,
# but not including the name parameter.
volumes = {}

}


Reference

Required

List of container definitions to use for the ECS task. Each entry corresponds to a different ECS container definition.

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
Example
   container_definitions = [{
name = "nginx"
image = "nginx:1.21"
}]

Details

Ideally we can use a concrete type here, but container definitions have many optional fields which Terraform does
not yet have good support for.

default_listener_arnsmap(string)required

A map of all the listeners on the load balancer. The keys should be the port numbers and the values should be the ARN of the listener for that port.

default_listener_portslist(string)required

The default port numbers on the load balancer to attach listener rules to. You can override this default on a rule-by-rule basis by setting the listener_ports parameter in each rule. The port numbers specified in this variable and the listener_ports parameter must exist in listener_arns.

ecs_cluster_arnstringrequired

The ARN of the cluster to which the ecs service should be deployed.

ecs_cluster_namestringrequired

The name of the ecs cluster to deploy the ecs service onto.

service_namestringrequired

The name of the ECS service (e.g. my-service-stage)

Optional

alarm_sns_topic_arnslist(string)optional

A list of ARNs of the SNS topic(s) to write alarm events to

[]
alarm_sns_topic_arns_us_east_1list(string)optional

A list of SNS topic ARNs to notify when the route53 health check changes to ALARM, OK, or INSUFFICIENT_DATA state. Note: these SNS topics MUST be in us-east-1! This is because Route 53 only sends CloudWatch metrics to us-east-1, so we must create the alarm in that region, and therefore, can only notify SNS topics in that region

[]

The time period, in seconds, during which requests from a client should be routed to the same Target. After this time period expires, the load balancer-generated cookie is considered stale. The acceptable range is 1 second to 1 week (604800 seconds). The default value is 1 day (86400 seconds). Only used if elb_target_groups is set.

86400

The type of Sticky Sessions to use. See https://goo.gl/MNwqNu for possible values. Only used if elb_target_groups is set.

"lb_cookie"

List of container definitions to use for the canary ECS task. Each entry corresponds to a different ECS container definition.

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
[]
Example
   container_definitions = [{
name = "nginx"
image = "nginx:1.21"
}]

Details

Ideally we can use a concrete type here, but container definitions have many optional fields which Terraform does
not yet have good support for.

canary_versionstringoptional

Which version of the ECS Service Docker container to deploy as a canary (e.g. 0.57)

null
capacity_provider_strategylist(object(…))optional

The capacity provider strategy to use for the service. Note that the capacity providers have to be present on the ECS cluster before deploying the ECS service. When provided, launch_type is ignored.

list(object({
capacity_provider = string
weight = number
base = number
}))
[]
Example
   capacity_provider_strategy = [
{
capacity_provider = "FARGATE"
weight = 1
base = 2
},
{
capacity_provider = "FARGATE_SPOT"
weight = 2
base = null
},
]

clb_container_namestringoptional

The name of the container, as it appears in the task_arn Task definition, to associate with a CLB. Currently, ECS can only associate a CLB with a single container per service. Only used if clb_name is set.

null
clb_container_portnumberoptional

The port on the container in clb_container_name to associate with an CLB. Currently, ECS can only associate a CLB with a single container per service. Only used if clb_name is set.

null
clb_namestringoptional

The name of a Classic Load Balancer (CLB) to associate with this service. Containers in the service will automatically register with the CLB when booting up. Set to null if using ELBv2.

null

The ARN of a KMS CMK to use for encrypting log events in the CloudWatch Logs. Set to null to disable encryption. Only used if create_cloudwatch_log_group is true.

null

The name for the Cloudwatch logs that will be generated by the ecs service. Only used (and required) if create_cloudwatch_log_group is true.

null

Number of days to retain log events. Possible values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 3653, and 0. Select 0 to never expire. Only used if create_cloudwatch_log_group is true.

null
cloudwatch_log_group_tagsmap(string)optional

A map of tags to apply to the Cloudwatch log group. Each item in this list should be a map with the parameters key and value. Only used if create_cloudwatch_log_group is true.

{}
cpunumberoptional

The number of CPU units to allocate to the ECS Service.

1

When true, create and manage the CloudWatch Log Group in the Terraform module instead of relying on ECS. This is useful for configuring options that are not available in the ECS native feature of managing the Log Group (e.g., encryption support).

false

Set to true if you want a DNS record automatically created and pointed at the the load balancer for the ECS service

false
custom_docker_commandstringoptional

If use_custom_docker_run_command is set to true, set this variable to the custom docker run command you want to provide

null

The name to use for the ECS Service IAM role, which is used to grant permissions to the ECS service to register the task IPs to ELBs.

null

Prefix for name of the custom IAM policies created by this module (those resulting from iam_policy and secrets_access). If omitted, defaults to service_name.

null

Prefix for name of the IAM role used by the ECS task.

null

Prefix for name of task execution IAM role and policy that grants access to CloudWatch and ECR.

null
dependencieslist(string)optional

Create a dependency between the resources in this module to the interpolated values in this list (and thus the source resources). In other words, the resources in this module will now depend on the resources backing the values in this list such that those resources need to be created before the resources in this module, and the resources in this module need to be destroyed before the resources in the list.

[]

Set the logging level of the deployment check script. You can set this to error, warn, or info, in increasing verbosity.

"info"

Seconds to wait before timing out each check for verifying ECS service deployment. See ecs_deploy_check_binaries for more details.

600

Set to 'true' to prevent the task from attempting to continuously redeploy after a failed health check.

false

Set to 'true' to also automatically roll back to the last successful deployment. deploy_circuit_breaker_enabled must also be true to enable this behavior.

false

The upper limit, as a percentage of desired_number_of_tasks, of the number of running tasks that can be running in a service during a deployment. Setting this to more than 100 means that during deployment, ECS will deploy new instances of a Task before undeploying the old ones.

200

The lower limit, as a percentage of desired_number_of_tasks, of the number of running tasks that must remain running and healthy in a service during a deployment. Setting this to less than 100 means that during deployment, ECS may undeploy old instances of a Task before deploying new ones.

100

How many instances of the ECS Service to run across the ECS cluster for a canary deployment. Typically, only 0 or 1 should be used.

0

How many instances of the ECS Service to run across the ECS cluster

1
domain_namestringoptional

The domain name to create a route 53 record for. This DNS record will point to the load balancer for the ECS service

null

The ID of the security group that should be applied to ecs service instances

null
ecs_node_port_mappingsmap(number)optional

A map of ports to be opened via security groups applied to the EC2 instances that back the ECS cluster, when not using fargate. The key should be the container port and the value should be what host port to map it to.

{}
efs_volumesmap(object(…))optional

(Optional) A map of EFS volumes that containers in your task may use. Each item in the list should be a map compatible with https://www.terraform.io/docs/providers/aws/r/ecs_task_definition.html#efs-volume-configuration-arguments.

map(object({
file_system_id = string # required
container_path = string # required
root_directory = string
transit_encryption = string
transit_encryption_port = number
access_point_id = string
iam = string
}))
{}
Example
   efs_volumes = {
jenkins = {
file_system_id = "fs-a1bc234d"
container_path = "/efs"
root_directory = "/jenkins"
transit_encryption = "ENABLED"
transit_encryption_port = 2999
access_point_id = "fsap-123a4b5c5d7891234"
iam = "ENABLED"
}
}

elb_slow_startnumberoptional

The amount time for targets to warm up before the load balancer sends them a full share of requests. The range is 30-900 seconds or 0 to disable. The default value is 0 seconds. Only used if elb_target_groups is set.

0

The amount of time for Elastic Load Balancing to wait before changing the state of a deregistering target from draining to unused. The range is 0-3600 seconds. Only used if elb_target_groups is set.

300

The ID of the VPC in which to create the target group. Only used if elb_target_groups is set.

null

Configurations for ELB target groups for ALBs and NLBs that should be associated with the ECS Tasks. Each entry corresponds to a separate target group. Set to the empty object ({}) if you are not using an ALB or NLB.

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Details

`elb_target_groups` should be set to a map of keys to objects with one mapping per desired target group. The keys
in the map can be any arbitrary name and are used to link the outputs with the inputs. The values of the map are an
object containing these attributes:

Set to true to enable Cloudwatch alarms on the ecs service instances

true

Whether or not to enable the ECS deployment check binary to make terraform wait for the task to be deployed. See ecs_deploy_check_binaries for more details. You must install the companion binary before the check can be used. Refer to the README for more details.

true

Specifies whether to enable Amazon ECS Exec for the tasks within the service.

false

Set this to true to create a route 53 health check and Cloudwatch alarm that will alert if your domain becomes unreachable

false

Set this to true to allow the ecs service to be accessed by other ecs nodes

false
fixed_response_rulesmap(any)optional
Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Example
    {
"health-path" = {
priority = 130

content_type = "text/plain"
message_body = "HEALTHY"
status_code = "200"

Conditions:
You need to provide *at least ONE* per set of rules. It should contain one of the following:
host_headers = ["foo.com", "www.foo.com"]
path_patterns = ["/health"]
source_ips = ["127.0.0.1"]
http_request_methods = ["GET"]
query_strings = [
{
key = "foo" Key is optional, this can be ommited.
value = "bar"
}, {
value = "hello"
}
]
}
}

Details

Each entry in the map supports the following attributes:

REQUIRED
- content_type [string]: The content type. Valid values are `text/plain`, `text/css`, `text/html`, `application/javascript`
and `application/json`.

OPTIONAL (defaults to value of corresponding module input):
- priority [number] : A value between 1 and 50000. Leaving it unset will automatically set the rule with the next
available priority after currently existing highest rule. This value must be unique for each
listener.
- listener_arns [list(string)]: A list of listener ARNs to override `var.default_listener_arns`
- message_body [string] : The message body.
- status_code [string] : The HTTP response code. Valid values are `2XX`, `4XX`, or `5XX`.

Wildcard characters:
* - matches 0 or more characters
? - matches exactly 1 character
To search for a literal '*' or '?' character in a query string, escape the character with a backslash (\).

Conditions (need to specify at least one):
- path_patterns [list(string)] : A list of paths to match (note that "/foo" is different than "/foo/").
Comparison is case sensitive. Wildcard characters supported: * and ?.
It is compared to the path of the URL, not it's query string. To compare
against query string, use the `query_strings` condition.
- host_headers [list(string)] : A list of host header patterns to match. Comparison is case insensitive.
Wildcard characters supported: * and ?.
- source_ips [list(string)] : A list of IP CIDR notations to match. You can use both IPv4 and IPv6
addresses. Wildcards are not supported. Condition is not satisfied by the
addresses in the `X-Forwarded-For` header, use `http_headers` condition instead.
- query_strings [list(map(string))]: Query string pairs or values to match. Comparison is case insensitive.
Wildcard characters supported: * and ?. Only one pair needs to match for
the condition to be satisfied.
- http_request_methods [list(string)] : A list of HTTP request methods or verbs to match. Only allowed characters are
A-Z, hyphen (-) and underscore (_). Comparison is case sensitive. Wildcards
are not supported. AWS recommends that GET and HEAD requests are routed in the
same way because the response to a HEAD request may be cached.

forward_rulesanyoptional
Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Example
    {
"foo" = {
priority = 120

host_headers = ["www.foo.com", "*.foo.com"]
path_patterns = ["/foo/*"]
source_ips = ["127.0.0.1/32"]
http_request_methods = ["GET"]
query_strings = [
{
key = "foo" Key is optional, this can be ommited.
value = "bar"
}, {
value = "hello"
}
]
},
"auth" = {
priority = 128
listener_ports = ["443"]

host_headers = ["intern.example.com]
path_patterns = ["/admin", "/admin/*]
authenticate_oidc = {
authorization_endpoint = "https://myaccount.oktapreview.com/oauth2/v1/authorize"
client_id = "0123456789aBcDeFgHiJ"
client_secret = "clientsecret"
issuer = "https://myaccount.oktapreview.com"
token_endpoint = "https://myaccount.oktapreview.com/oauth2/v1/token"
user_info_endpoint = "https://myaccount.oktapreview.com/oauth2/v1/userinfo"
}
}

Details

Each entry in the map supports the following attributes:

OPTIONAL (defaults to value of corresponding module input):
- priority [number] : A value between 1 and 50000. Leaving it unset will automatically set
the rule with the next available priority after currently existing highest
rule. This value must be unique for each listener.
- listener_arns [list(string)] : A list of listener ARNs to override `var.default_listener_arns`
- stickiness [map(object[Stickiness])] : Target group stickiness for the rule. Only applies if more than one
target_group_arn is defined.
- authenticate_oidc map(object) : OIDC authentication configuration. Only applies, if not null.


Details

Wildcard characters:
* - matches 0 or more characters
? - matches exactly 1 character
To search for a literal '*' or '?' character in a query string, escape the character with a backslash (\).

Details

Conditions (need to specify at least one):
- path_patterns [list(string)] : A list of paths to match (note that "/foo" is different than "/foo/").
Comparison is case sensitive. Wildcard characters supported: * and ?.
It is compared to the path of the URL, not it's query string. To compare
against query string, use the `query_strings` condition.
- host_headers [list(string)] : A list of host header patterns to match. Comparison is case insensitive.
Wildcard characters supported: * and ?.
- source_ips [list(string)] : A list of IP CIDR notations to match. You can use both IPv4 and IPv6
addresses. Wildcards are not supported. Condition is not satisfied by the
addresses in the `X-Forwarded-For` header, use `http_headers` condition instead.
- query_strings [list(map(string))]: Query string pairs or values to match. Comparison is case insensitive.
Wildcard characters supported: * and ?. Only one pair needs to match for
the condition to be satisfied.
- http_request_methods [list(string)] : A list of HTTP request methods or verbs to match. Only allowed characters are
A-Z, hyphen (-) and underscore (_). Comparison is case sensitive. Wildcards
are not supported. AWS recommends that GET and HEAD requests are routed in the
same way because the response to a HEAD request may be cached.

Details

Authenticate OIDC Blocks:
authenticate_oidc:
- authorization_endpoint string : (Required) The authorization endpoint of the IdP.
- client_id string : (Required) The OAuth 2.0 client identifier.
- client_secret string : (Required) The OAuth 2.0 client secret.
- issuer string : (Required) The OIDC issuer identifier of the IdP.
- token_endpoint string : (Required) The token endpoint of the IdP.
- user_info_endpoint string : (Required) The user info endpoint of the IdP.
- authentication_request_extra_params map(string): (Optional) The query parameters to include in the redirect request to the authorization endpoint. Max: 10.
- on_unauthenticated_request string : (Optional) The behavior if the user is not authenticated. Valid values: deny, allow and authenticate
- scope string : (Optional) The set of user claims to be requested from the IdP.
- session_cookie_name string : (Optional) The name of the cookie used to maintain session information.
- session_timeout int : (Optional) The maximum duration of the authentication session, in seconds.

If true, enable health checks on the target group. Only applies to ELBv2. For CLBs, health checks are not configurable.

true

Seconds to ignore failing load balancer health checks on newly instantiated tasks to prevent premature shutdown, up to 2,147,483,647. Only valid for services configured to use load balancers.

0

The number of consecutive successful health checks required before considering an unhealthy Target healthy. The acceptable range is 2 to 10.

5
health_check_intervalnumberoptional

The approximate amount of time, in seconds, between health checks of an individual Target. Minimum value 5 seconds, Maximum value 300 seconds.

30
health_check_matcherstringoptional

The HTTP codes to use when checking for a successful response from a Target. You can specify multiple values (e.g. '200,202') or a range of values (e.g. '200-299'). Required when using ALBs.

"200"
health_check_pathstringoptional

The ping path that is the destination on the Targets for health checks. Required when using ALBs.

"/"
health_check_portstringoptional

The port the ELB uses when performing health checks on Targets. The default is to use the port on which each target receives traffic from the load balancer, indicated by the value 'traffic-port'.

"traffic-port"
health_check_timeoutnumberoptional

The amount of time, in seconds, during which no response from a Target means a failed health check. The acceptable range is 2 to 60 seconds.

5

The number of consecutive failed health checks required before considering a target unhealthy. The acceptable range is 2 to 10. For NLBs, this value must be the same as the health_check_healthy_threshold.

2

The period, in seconds, over which to measure the CPU utilization percentage

300

Trigger an alarm if the ECS Service has a CPU utilization percentage above this threshold

90

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"

The period, in seconds, over which to measure the memory utilization percentage

300

Trigger an alarm if the ECS Service has a memory utilization percentage above this threshold

90

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"
hosted_zone_idstringoptional

The ID of the Route 53 hosted zone into which the Route 53 DNS record should be written

null
iam_policymap(object(…))optional

An object defining the policy to attach to the ECS task. Accepts a map of objects, where the map keys are sids for IAM policy statements, and the object fields are the resources, actions, and the effect ('Allow' or 'Deny') of the statement.

map(object({
resources = list(string)
actions = list(string)
effect = string
}))
null
Example
   iam_policy = {
S3Access = {
actions = ["s3:*"]
resources = ["arn:aws:s3:::mybucket"]
effect = "Allow"
},
SecretsManagerAccess = {
actions = ["secretsmanager:GetSecretValue"],
resources = ["arn:aws:secretsmanager:us-east-1:0123456789012:secret:mysecert"]
effect = "Allow"
}
}

launch_typestringoptional

The launch type of the ECS service. Must be one of EC2 or FARGATE. When using FARGATE, you must set the network mode to awsvpc and configure it. When using EC2, you can configure the placement strategy using the variables placement_strategy_type, placement_strategy_field, placement_constraint_type, placement_constraint_expression. This variable is ignored if capacity_provider_strategy is provided.

"EC2"
lb_hosted_zone_idstringoptional

The ID of the Route 53 Hosted Zone in which to create a DNS A record pointed to the ECS service's load balancer

null
lb_target_group_tagsmap(string)optional

A map of tags to apply to the elb target group. Each item in this list should be a map with the parameters key and value.

{}
max_number_of_tasksnumberoptional

The maximum number of instances of the ECS Service to run. Auto scaling will never scale out above this number.

3
memorynumberoptional

How much memory, in MB, to give the ECS Service.

500
min_number_of_tasksnumberoptional

The minimum number of instances of the ECS Service to run. Auto scaling will never scale in below this number.

1
network_configurationobject(…)optional

The configuration to use when setting up the VPC network mode. Required and only used if network_mode is awsvpc.

object({
# IDs of VPC Subnets to allocate fargate worker network from.
subnets = list(string)

# The ID of the VPC used for the Fargate worker network. Must be non-null when security_group_rules are provided.
vpc_id = string

# Security Group Rules to apply to the ECS Fargate worker. This module will create a new security group for the
# worker and attach these rules. Each entry accepts the same attributes as the aws_security_group_rule resource,
# except for security_group_id which will be set to the security group created within the module.
# Each entry corresponds to a rule. The key is a unique, user provided, arbitrary value that can be used by
# Terraform to know which rules to update across changes.
security_group_rules = map(object({
type = string
from_port = number
to_port = number
protocol = string
source_security_group_id = string
cidr_blocks = list(string)
}))

# Additional existing Security Groups that should be bound to the ECS Fargate worker.
additional_security_group_ids = list(string)

# Whether or not the ECS Fargate worker should get a public IP address.
assign_public_ip = bool
})
null
Details

The ID of the VPC used for the Fargate worker network. Must be non-null when security_group_rules are provided.

Details

Security Group Rules to apply to the ECS Fargate worker. This module will create a new security group for the
worker and attach these rules. Each entry accepts the same attributes as the aws_security_group_rule resource,
except for security_group_id which will be set to the security group created within the module.
Each entry corresponds to a rule. The key is a unique, user provided, arbitrary value that can be used by
Terraform to know which rules to update across changes.

Details

Additional existing Security Groups that should be bound to the ECS Fargate worker.

Details

Whether or not the ECS Fargate worker should get a public IP address.

network_modestringoptional

The Docker networking mode to use for the containers in the task. The valid values are none, bridge, awsvpc, and host. If the network_mode is set to awsvpc, you must configure network_configuration.

"bridge"
ordered_placement_strategylist(object(…))optional

Service level strategy rules that are taken into consideration during task placement. List from top to bottom in order of precedence. Updates to this configuration will take effect next task deployment unless force_new_deployment is enabled. The maximum number of ordered_placement_strategy blocks is 5.

list(object({
type = string
field = string
}))
[
{
field = "cpu",
type = "binpack"
}
]
original_lb_dns_namestringoptional

The DNS name that was assigned by AWS to the load balancer upon creation

null

Cluster Query Language expression to apply to the constraint for matching. Does not need to be specified for the distinctInstance constraint type.

"attribute:ecs.ami-id != 'ami-fake'"

The type of constraint to apply for container instance placement. The only valid values at this time are memberOf and distinctInstance.

"memberOf"
propagate_tagsstringoptional

Whether tags should be propogated to the tasks from the service or from the task definition. Valid values are SERVICE and TASK_DEFINITION. Defaults to SERVICE. If set to null, no tags are created for tasks.

"SERVICE"

Use the name of the Envoy proxy container from container_definitions as the container name.

null

A map of network configuration parameters to provide the Container Network Interface (CNI) plugin.

null
Example
   properties = {
AppPorts = "8080"
EgressIgnoredIPs = "169.254.170.2,169.254.169.254"
IgnoredUID = "1337"
ProxyEgressPort = 15001
ProxyIngressPort = 15000
}

redirect_rulesmap(any)optional
Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Example
    {
"old-website" = {
priority = 120
port = 443
protocol = "HTTPS"

status_code = "HTTP_301"
host = "gruntwork.in"
path = "/signup"
query = "foo"

Conditions:
host_headers = ["foo.com", "www.foo.com"]
path_patterns = ["/health"]
source_ips = ["127.0.0.1"]
http_request_methods = ["GET"]
query_strings = [
{
key = "foo" Key is optional, this can be ommited.
value = "bar"
}, {
value = "hello"
}
]
}
}

Details

Each entry in the map supports the following attributes:

OPTIONAL (defaults to value of corresponding module input):
- priority [number]: A value between 1 and 50000. Leaving it unset will automatically set the rule with the next
available priority after currently existing highest rule. This value must be unique for each
listener.
- listener_arns [list(string)]: A list of listener ARNs to override `var.default_listener_arns`
- status_code [string]: The HTTP redirect code. The redirect is either permanent `HTTP_301` or temporary `HTTP_302`.

The URI consists of the following components: `protocol://hostname:port/path?query`. You must modify at least one of
the following components to avoid a redirect loop: protocol, hostname, port, or path. Any components that you do not
modify retain their original values.
- host [string]: The hostname. The hostname can contain {host}.
- path [string]: The absolute path, starting with the leading "/". The path can contain `host`, `path`, and `port`.
- port [string]: The port. Specify a value from 1 to 65525.
- protocol [string]: The protocol. Valid values are `HTTP` and `HTTPS`. You cannot redirect HTTPS to HTTP.
- query [string]: The query params. Do not include the leading "?".

Wildcard characters:
* - matches 0 or more characters
? - matches exactly 1 character
To search for a literal '*' or '?' character in a query string, escape the character with a backslash (\).

Conditions (need to specify at least one):
- path_patterns [list(string)] : A list of paths to match (note that "/foo" is different than "/foo/").
Comparison is case sensitive. Wildcard characters supported: * and ?.
It is compared to the path of the URL, not it's query string. To compare
against query string, use the `query_strings` condition.
- host_headers [list(string)] : A list of host header patterns to match. Comparison is case insensitive.
Wildcard characters supported: * and ?.
- source_ips [list(string)] : A list of IP CIDR notations to match. You can use both IPv4 and IPv6
addresses. Wildcards are not supported. Condition is not satisfied by the
addresses in the `X-Forwarded-For` header, use `http_headers` condition instead.
- query_strings [list(map(string))]: Query string pairs or values to match. Comparison is case insensitive.
Wildcard characters supported: * and ?. Only one pair needs to match for
the condition to be satisfied.
- http_request_methods [list(string)] : A list of HTTP request methods or verbs to match. Only allowed characters are
A-Z, hyphen (-) and underscore (_). Comparison is case sensitive. Wildcards
are not supported. AWS recommends that GET and HEAD requests are routed in the
same way because the response to a HEAD request may be cached.

The path, without any leading slash, that can be used as a health check (e.g. healthcheck) by Route 53. Should return a 200 OK when the service is up and running.

"/"

The port to use for Route 53 health checks. This should be the port for the service that is available at the publicly accessible domain name (domain_name).

80

The protocol to use for Route 53 health checks. Should be one of HTTP, HTTPS.

"HTTP"

The optional external_id to be used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null

The optional AWS profile to be used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null

The optional role_arn to be used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null

The optional session_name to be used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null

The optional path to a credentials file used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null
runtime_platformobject(…)optional

Define runtime platform options

object({
operating_system_family = string
cpu_architecture = string
})
null
secrets_accesslist(string)optional

A list of ARNs of Secrets Manager secrets that the task should have permissions to read. The IAM role for the task will be granted secretsmanager:GetSecretValue for each secret in the list. The ARN can be either the complete ARN, including the randomly generated suffix, or the ARN without the suffix. If the latter, the module will look up the full ARN automatically. This is helpful in cases where you don't yet know the randomly generated suffix because the rest of the ARN is a predictable value.

[]
secrets_manager_arnslist(string)optional

A list of ARNs for Secrets Manager secrets that the ECS execution IAM policy should be granted access to read. Note that this is different from the ECS task IAM policy. The execution policy is concerned with permissions required to run the ECS task. The ARN can be either the complete ARN, including the randomly generated suffix, or the ARN without the suffix. If the latter, the module will look up the full ARN automatically. This is helpful in cases where you don't yet know the randomly generated suffix because the rest of the ARN is a predictable value.

[]

The ARN of the kms key associated with secrets manager

null

The name of the aws_security_group that gets created if network_mode is awsvpc and custom rules are specified for the ECS Fargate worker via network_configuration.security_group_rules. Defaults to service_name if not specified.

null
service_tagsmap(string)optional

A map of tags to apply to the ECS service. Each item in this list should be a map with the parameters key and value.

{}
task_cpunumberoptional

The CPU units for the instances that Fargate will spin up. Options here: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html#fargate-tasks-size. Required when using FARGATE launch type.

null
task_definition_tagsmap(string)optional

A map of tags to apply to the task definition. Each item in this list should be a map with the parameters key and value.

{}
task_memorynumberoptional

The memory units for the instances that Fargate will spin up. Options here: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html#fargate-tasks-size. Required when using FARGATE launch type.

null

If true, the ALB will use use Sticky Sessions as described at https://goo.gl/VLcNbk. Only used if elb_target_groups is set. Note that this can only be true when associating with an ALB. This cannot be used with CLBs or NLBs.

false
use_auto_scalingbooloptional

Whether or not to enable auto scaling for the ecs service

true

Set this to true if you want to pass a custom docker run command. If you set this to true, you must supply custom_docker_command

false
volumesanyoptional

(Optional) A map of volume blocks that containers in your task may use. The key should be the name of the volume and the value should be a map compatible with https://www.terraform.io/docs/providers/aws/r/ecs_task_definition.html#volume-block-arguments, but not including the name parameter.

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Example
   volumes = {
datadog = {
host_path = "/var/run/datadog"
}

logs = {
host_path = "/var/log"
docker_volume_configuration = {
scope = "shared"
autoprovision = true
driver = "local"
}
}
}