Skip to main content
Service Catalog Version 0.85.1Last updated in version 0.85.0

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.

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.

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 listener_arns.

list(string)
ecs_cluster_arnstring(required)

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

ecs_cluster_namestring(required)

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

service_namestring(required)

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

Optional​

alarm_sns_topic_arnslist(optional)

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

list(string)
[]

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

list(string)
[]

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
alb_sticky_session_typestring(optional)

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.

[]
canary_versionstring(optional)

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

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, launch_type is ignored.

list(object({
    capacity_provider = string
    weight            = number
    base              = number
  }))
[]
clb_container_namestring(optional)

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_portnumber(optional)

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_namestring(optional)

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
cpunumber(optional)

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
create_route53_entrybool(optional)

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_commandstring(optional)

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
custom_iam_policy_prefixstring(optional)

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(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.

list(string)
[]

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
desired_number_of_tasksnumber(optional)

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

1
domain_namestring(optional)

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

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.

map(number)
{}
efs_volumesmap(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_startnumber(optional)

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
elb_target_group_vpc_idstring(optional)

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

null
elb_target_groupsany(optional)

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.

{}

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
map(any)
{}
forward_rulesany(optional)
{}
health_check_enabledbool(optional)

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_intervalnumber(optional)

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_matcherstring(optional)

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_pathstring(optional)

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

/
health_check_portstring(optional)

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_timeoutnumber(optional)

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

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
hosted_zone_idstring(optional)

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

null
iam_policymap(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_typestring(optional)

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_idstring(optional)

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
max_number_of_tasksnumber(optional)

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

3
memorynumber(optional)

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

500
min_number_of_tasksnumber(optional)

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_modestring(optional)

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_namestring(optional)

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
placement_strategy_fieldstring(optional)

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
placement_strategy_typestring(optional)

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

binpack
propagate_tagsstring(optional)

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.

map(string)
null
redirect_rulesmap(optional)
map(any)
{}

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(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.

list(string)
[]
secrets_manager_arnslist(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.

list(string)
[]

The ARN of the kms key associated with secrets manager

null
service_tagsmap(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.

map(string)
{}
task_cpunumber(optional)

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

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.

map(string)
{}
task_memorynumber(optional)

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_scalingbool(optional)

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
volumesany(optional)

(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.

{}