Amazon ECS Service
Overview
This service contains Terraform code to deploy a production-grade ECS service on AWS using Elastic Container Service(ECS).
ECS 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
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:
- examples/for-production folder: The
examples/for-production
folder contains sample code optimized for direct usage in production. This is code from the Gruntwork Reference Architecture, and it shows you how we build an end-to-end, integrated tech stack on top of the Gruntwork Service Catalog.
Manage
For information on how to manage your ECS service, see the documentation in the module ecs repo.
Sample Usage
- Terraform
- Terragrunt
# ------------------------------------------------------------------------------------------------------
# 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.118.2"
# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------
# List of container definitions to use for the ECS task. Each entry
# corresponds to a different ECS container definition.
container_definitions = <any>
# 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
# 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 = {}
# 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 = []
# 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 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
# CloudWatch alarms which triggers deployment rollback if failure.
deployment_cloudwatch_alarms = null
# Type of deployment controller, possible values: CODE_DEPLOY, ECS, EXTERNAL
deployment_controller = null
# 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
# 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
# Whether or not to ignore changes to the target groups in the listener
# forwarding rule. Can be used with AWS CodeDeploy to allow changes to target
# group mapping outside of Terraform.
ignore_changes_to_target_groups = false
# 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 = {}
# Listener rules list required first to be provisioned before creation of ECS
# cluster.
listener_rule_ids = []
# 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
# Process namespace to use for the containers in the task. The valid values
# are host and task.
pid_mode = 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"
# The platform version on which to run your service. Only applicable for
# launch_type set to FARGATE. Defaults to LATEST.
platform_version = null
# 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
# Use this variable to adjust the default timeout of 20m for create and update
# operations the the ECS service. Adjusting the value can be particularly
# useful when using 'wait_for_steady_state'.
service_create_update_timeout = "20m"
# 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 = {}
# If true, Terraform will wait for the service to reach a steady state — as
# in, the ECS tasks you wanted are actually deployed — before 'apply' is
# considered complete.
wait_for_steady_state = true
}
# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S ECS-SERVICE MODULE
# ------------------------------------------------------------------------------------------------------
terraform {
source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/services/ecs-service?ref=v0.118.2"
}
inputs = {
# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------
# List of container definitions to use for the ECS task. Each entry
# corresponds to a different ECS container definition.
container_definitions = <any>
# 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
# 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 = {}
# 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 = []
# 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 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
# CloudWatch alarms which triggers deployment rollback if failure.
deployment_cloudwatch_alarms = null
# Type of deployment controller, possible values: CODE_DEPLOY, ECS, EXTERNAL
deployment_controller = null
# 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
# 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
# Whether or not to ignore changes to the target groups in the listener
# forwarding rule. Can be used with AWS CodeDeploy to allow changes to target
# group mapping outside of Terraform.
ignore_changes_to_target_groups = false
# 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 = {}
# Listener rules list required first to be provisioned before creation of ECS
# cluster.
listener_rule_ids = []
# 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
# Process namespace to use for the containers in the task. The valid values
# are host and task.
pid_mode = 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"
# The platform version on which to run your service. Only applicable for
# launch_type set to FARGATE. Defaults to LATEST.
platform_version = null
# 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
# Use this variable to adjust the default timeout of 20m for create and update
# operations the the ECS service. Adjusting the value can be particularly
# useful when using 'wait_for_steady_state'.
service_create_update_timeout = "20m"
# 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 = {}
# If true, Terraform will wait for the service to reach a steady state — as
# in, the ECS tasks you wanted are actually deployed — before 'apply' is
# considered complete.
wait_for_steady_state = true
}
Reference
- Inputs
- Outputs
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.
ecs_cluster_arn
stringThe ARN of the cluster to which the ecs service should be deployed.
ecs_cluster_name
stringThe name of the ecs cluster to deploy the ecs service onto.
service_name
stringThe name of the ECS service (e.g. my-service-stage)
Optional
alarm_sns_topic_arns
list(string)A list of ARNs of the SNS topic(s) to write alarm events to
[]
alarm_sns_topic_arns_us_east_1
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
[]
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_type
stringThe 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_version
stringWhich version of the ECS Service Docker container to deploy as a canary (e.g. 0.57)
null
capacity_provider_strategy
list(object(…))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_name
stringThe 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_port
numberThe 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_name
stringThe 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_tags
map(string)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.
{}
cpu
numberThe 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_command
stringIf 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_prefix
stringPrefix 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
default_listener_arns
map(string)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_ports
list(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
.
[]
dependencies
list(string)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 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
deployment_cloudwatch_alarms
object(…)CloudWatch alarms which triggers deployment rollback if failure.
object({
cloudwatch_alarms = list(string)
enable = bool
rollback = bool
})
null
deployment_controller
stringType of deployment controller, possible values: CODE_DEPLOY, ECS, EXTERNAL
null
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_tasks
numberHow many instances of the ECS Service to run across the ECS cluster
1
domain_name
stringThe 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_mappings
map(number)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_volumes
map(object(…))(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_start
numberThe 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_id
stringThe 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
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_rules
map(any)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.
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_interval
numberThe approximate amount of time, in seconds, between health checks of an individual Target. Minimum value 5 seconds, Maximum value 300 seconds.
30
health_check_matcher
stringThe 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_path
stringThe ping path that is the destination on the Targets for health checks. Required when using ALBs.
"/"
health_check_port
stringThe 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_timeout
numberThe 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_id
stringThe ID of the Route 53 hosted zone into which the Route 53 DNS record should be written
null
iam_policy
map(object(…))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"
}
}
Whether or not to ignore changes to the target groups in the listener forwarding rule. Can be used with AWS CodeDeploy to allow changes to target group mapping outside of Terraform.
false
launch_type
stringThe 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_id
stringThe 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_tags
map(string)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.
{}
listener_rule_ids
list(string)Listener rules list required first to be provisioned before creation of ECS cluster.
[]
max_number_of_tasks
numberThe maximum number of instances of the ECS Service to run. Auto scaling will never scale out above this number.
3
memory
numberHow much memory, in MB, to give the ECS Service.
500
min_number_of_tasks
numberThe minimum number of instances of the ECS Service to run. Auto scaling will never scale in below this number.
1
network_configuration
object(…)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_mode
stringThe 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_strategy
list(object(…))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_name
stringThe DNS name that was assigned by AWS to the load balancer upon creation
null
pid_mode
stringProcess namespace to use for the containers in the task. The valid values are host and task.
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"
platform_version
stringThe platform version on which to run your service. Only applicable for launch_type set to FARGATE. Defaults to LATEST.
null
propagate_tags
stringWhether 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
proxy_configuration_properties
map(string)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_rules
map(any)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_platform
object(…)Define runtime platform options
object({
operating_system_family = string
cpu_architecture = string
})
null
secrets_access
list(string)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_arns
list(string)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
Use this variable to adjust the default timeout of 20m for create and update operations the the ECS service. Adjusting the value can be particularly useful when using 'wait_for_steady_state'.
"20m"
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_tags
map(string)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_cpu
numberThe 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_tags
map(string)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_ephemeral_storage
numberEphemeral storage size for Fargate tasks. See: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#task_definition_ephemeralStorage
null
task_memory
numberThe 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_scaling
boolWhether 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
volumes
any(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"
}
}
}
If true, Terraform will wait for the service to reach a steady state — as in, the ECS tasks you wanted are actually deployed — before 'apply' is considered complete.
true
A list of all the CloudWatch Dashboard metric widgets available in this module.
The ARN of the ECS task definition
The ARN of the canary ECS task definition
The ARN of the canary service. Canary services are optional and can be helpful when you're attempting to verify a release candidate
The capacity provider strategy determines how infrastructure (such as EC2 instances or Fargate) that backs your ECS service is managed. See https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cluster-capacity-providers.html for more information
A map representing the instance host and container ports that should be opened
The ARN of the ECS task's IAM role
The name of the ECS task execution IAM role. The execution role is used by the ECS container agent to make calls to the ECS API, pull container images from ECR, use the logs driver, etc
The ARN of the IAM role associated with the ECS task
The name of the IAM role granting permissions to the running ECS task itself. Note this role is separate from the execution role which is assumed by the ECS container agent
The metric widget for the ECS service's CPU usage
The metric widget for the ECS service's memory usage
The domain name of the optional route53 record, which points at the load balancer for the ECS service
The ARN of the app autoscaling target
The resource ID of the autoscaling target
The ARN of the ECS service
The ARN of the service role associated with the ELB of the ECS service
The name of the service role associated with the ELB of the ECS service
The ARNs of the ECS service's load balancer's target groups
The names of the ECS service's load balancer's target groups