Skip to main content
Service Catalog Version 0.96.9Last updated in version 0.96.1

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.

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.
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.
[]
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
  }))
[]
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
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
  }))
{}
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.
{}

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

false

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.
{}
forward_rulesanyoptional
Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}

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
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
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"
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"

The field to apply the placement strategy against. For the spread placement strategy, valid values are instanceId (or host, which has the same effect), or any platform or custom attribute that is applied to a container instance, such as attribute:ecs.availability-zone. For the binpack placement strategy, valid values are cpu and memory. For the random placement strategy, this field is not used.

"cpu"

The strategy to use when placing ECS tasks on EC2 instances. Can be binpack (default), random, or spread.

"binpack"
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
redirect_rulesmap(any)optional
Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}

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
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 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.
{}