Skip to main content

Module: ecs-alb-service-task

Terraform module to create an ECS Service for a web app (task), and an ALB target group to route requests.

Usage

For a complete example, see examples/complete.

For automated test of the complete example using bats and Terratest, see test.

provider "aws" {
region = var.region
}

module "label" {
source = "git::https://github.com/cloudposse/terraform-null-label.git?ref=tags/0.15.0"
namespace = var.namespace
name = var.name
stage = var.stage
delimiter = var.delimiter
attributes = var.attributes
tags = var.tags
}

module "vpc" {
source = "git::https://github.com/cloudposse/terraform-aws-vpc.git?ref=tags/0.8.1"
namespace = var.namespace
stage = var.stage
name = var.name
delimiter = var.delimiter
attributes = var.attributes
cidr_block = var.vpc_cidr_block
tags = var.tags
}

module "subnets" {
source = "git::https://github.com/cloudposse/terraform-aws-dynamic-subnets.git?ref=tags/0.16.1"
availability_zones = var.availability_zones
namespace = var.namespace
stage = var.stage
name = var.name
attributes = var.attributes
delimiter = var.delimiter
vpc_id = module.vpc.vpc_id
igw_id = module.vpc.igw_id
cidr_block = module.vpc.vpc_cidr_block
nat_gateway_enabled = true
nat_instance_enabled = false
tags = var.tags
}

resource "aws_ecs_cluster" "default" {
name = module.label.id
tags = module.label.tags
}

module "container_definition" {
source = "git::https://github.com/cloudposse/terraform-aws-ecs-container-definition.git?ref=tags/0.21.0"
container_name = var.container_name
container_image = var.container_image
container_memory = var.container_memory
container_memory_reservation = var.container_memory_reservation
container_cpu = var.container_cpu
essential = var.container_essential
readonly_root_filesystem = var.container_readonly_root_filesystem
environment = var.container_environment
port_mappings = var.container_port_mappings
log_configuration = var.container_log_configuration
}

module "ecs_alb_service_task" {
source = "cloudposse/ecs-alb-service-task/aws"
# Cloud Posse recommends pinning every module to a specific version
# version = "x.x.x"
namespace = var.namespace
stage = var.stage
name = var.name
attributes = var.attributes
delimiter = var.delimiter
alb_security_group = module.vpc.vpc_default_security_group_id
container_definition_json = module.container_definition.json
ecs_cluster_arn = aws_ecs_cluster.default.arn
launch_type = var.ecs_launch_type
vpc_id = module.vpc.vpc_id
security_group_ids = [module.vpc.vpc_default_security_group_id]
subnet_ids = module.subnets.public_subnet_ids
tags = var.tags
ignore_changes_task_definition = var.ignore_changes_task_definition
network_mode = var.network_mode
assign_public_ip = var.assign_public_ip
propagate_tags = var.propagate_tags
health_check_grace_period_seconds = var.health_check_grace_period_seconds
deployment_minimum_healthy_percent = var.deployment_minimum_healthy_percent
deployment_maximum_percent = var.deployment_maximum_percent
deployment_controller_type = var.deployment_controller_type
desired_count = var.desired_count
task_memory = var.task_memory
task_cpu = var.task_cpu
}

The container_image in the container_definition module is the Docker image used to start a container.

The container_definition is a string of JSON-encoded container definitions. Normally, you would place only one container definition here as the example above demonstrates. However, there might be situations where more than one container per task is more appropriate such as optionally in Fargate or in other cases where sidecars may be required. With cloudposse/terraform-aws-ecs-container-definition multi-container task definitions can be created using:

module "ecs_alb_service_task" {
...
container_definition_json = jsonencode([
module.first_container.json_map_object,
module.second_container.json_map_object,
])
...
}

Refer to the multiple definitions example in cloudposse/terraform-aws-ecs-container-definition for details on defining multiple definitions.

This string is passed directly to the Docker daemon. Images in the Docker Hub registry are available by default. Other repositories are specified with either repository-url/image:tag or repository-url/image@digest. Up to 255 letters (uppercase and lowercase), numbers, hyphens, underscores, colons, periods, forward slashes, and number signs are allowed. This parameter maps to Image in the Create a container section of the Docker Remote API and the IMAGE parameter of docker run.

When a new task starts, the Amazon ECS container agent pulls the latest version of the specified image and tag for the container to use. However, subsequent updates to a repository image are not propagated to already running tasks.

Images in Amazon ECR repositories can be specified by either using the full registry/repository:tag or registry/repository@digest. For example, 012345678910.dkr.ecr.<region-name>.amazonaws.com/<repository-name>:latest or 012345678910.dkr.ecr.<region-name>.amazonaws.com/<repository-name>@sha256:94afd1f2e64d908bc90dbca0035a5b567EXAMPLE.

Images in official repositories on Docker Hub use a single name (for example, ubuntu or mongo).

Images in other repositories on Docker Hub are qualified with an organization name (for example, amazon/amazon-ecs-agent).

Images in other online repositories are qualified further by a domain name (for example, quay.io/assemblyline/ubuntu).

For more info, see Container Definition.

Variables

Required Variables

container_definition_json (string) required

A string containing a JSON-encoded array of container definitions
("[{ "name": "container1", ... }, { "name": "container2", ... }]").
See API_ContainerDefinition,
cloudposse/terraform-aws-ecs-container-definition, or
ecs_task_definition#container_definitions


ecs_cluster_arn (string) required

The ARN of the ECS cluster where service will be provisioned

vpc_id (string) required

The VPC ID where resources are created

Optional Variables

alb_security_group (string) optional

Security group of the ALB


Default value: ""

assign_public_ip (bool) optional

Assign a public IP address to the ENI (Fargate launch type only). Valid values are true or false. Default false


Default value: false

availability_zone_rebalancing (string) optional

ECS automatically redistributes tasks within a service across Availability Zones (AZs) to mitigate the risk of impaired application availability due to underlying infrastructure failures and task lifecycle activities. The valid values are ENABLED and DISABLED.


Default value: "DISABLED"

bind_mount_volumes (list(any)) optional

Task bind mount volume definitions as list of configuration objects. You can define multiple bind mount volumes on the same task definition. Requires name and optionally host_path


Default value: [ ]

capacity_provider_strategies optional

The capacity provider strategies to use for the service. See capacity_provider_strategy configuration block: https://www.terraform.io/docs/providers/aws/r/ecs_service.html#capacity_provider_strategy


Type:

list(object({
capacity_provider = string
weight = number
base = number
}))

Default value: [ ]

circuit_breaker_deployment_enabled (bool) optional

If true, enable the deployment circuit breaker logic for the service. If using CODE_DEPLOY for deployment_controller_type, this value will be ignored


Default value: false

circuit_breaker_rollback_enabled (bool) optional

If true, Amazon ECS will roll back the service if a service deployment fails. If using CODE_DEPLOY for deployment_controller_type, this value will be ignored


Default value: false

container_port (number) optional

The port on the container to allow traffic from the ALB security group


Default value: 80

deployment_controller_type (string) optional

Type of deployment controller. Valid values are CODE_DEPLOY and ECS


Default value: "ECS"

deployment_maximum_percent (number) optional

The upper limit of the number of tasks (as a percentage of desired_count) that can be running in a service during a deployment


Default value: 200

deployment_minimum_healthy_percent (number) optional

The lower limit (as a percentage of desired_count) of the number of tasks that must remain running and healthy in a service during a deployment


Default value: 100

desired_count (number) optional

The number of instances of the task definition to place and keep running


Default value: 1

docker_volumes optional

Task docker volume definitions as list of configuration objects. You can define multiple Docker volumes on the same task definition, but a single volume can only have one docker_volume_configuration.


Type:

list(object({
host_path = string
name = string
docker_volume_configuration = list(object({
autoprovision = bool
driver = string
driver_opts = map(string)
labels = map(string)
scope = string
}))
}))

Default value: [ ]

ecs_load_balancers optional

A list of load balancer config objects for the ECS service; see ecs_service#load_balancer docs


Type:

list(object({
container_name = string
container_port = number
elb_name = optional(string)
target_group_arn = string
}))

Default value: [ ]

ecs_service_enabled (bool) optional

Whether or not to create the aws_ecs_service resource


Default value: true

efs_volumes optional

Task EFS volume definitions as list of configuration objects. You can define multiple EFS volumes on the same task definition, but a single volume can only have one efs_volume_configuration.


Type:

list(object({
host_path = string
name = string
efs_volume_configuration = list(object({
file_system_id = string
root_directory = string
transit_encryption = string
transit_encryption_port = string
authorization_config = list(object({
access_point_id = string
iam = string
}))
}))
}))

Default value: [ ]

enable_all_egress_rule (bool) optional

A flag to enable/disable adding the all ports egress rule to the service security group


Default value: true

enable_ecs_managed_tags (bool) optional

Specifies whether to enable Amazon ECS managed tags for the tasks within the service


Default value: false

enable_icmp_rule (bool) optional

Specifies whether to enable ICMP on the service security group


Default value: false

ephemeral_storage_size (number) optional

The number of GBs to provision for ephemeral storage on Fargate tasks. Must be greater than or equal to 21 and less than or equal to 200


Default value: 0

exec_enabled (bool) optional

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


Default value: false

force_new_deployment (bool) optional

Enable to force a new task deployment of the service.


Default value: false

fsx_volumes optional

Task FSx volume definitions as list of configuration objects. You can define multiple FSx volumes on the same task definition, but a single volume can only have one fsx_windows_file_server_volume_configuration.


Type:

list(object({
host_path = string
name = string
fsx_windows_file_server_volume_configuration = list(object({
file_system_id = string
root_directory = string
authorization_config = list(object({
credentials_parameter = string
domain = string
}))
}))
}))

Default value: [ ]

health_check_grace_period_seconds (number) optional

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


Default value: 0

ignore_changes_desired_count (bool) optional

Whether to ignore changes for desired count in the ECS service


Default value: false

ignore_changes_task_definition (bool) optional

Whether to ignore changes in container definition and task definition in the ECS service


Default value: true

ipc_mode (string) optional

The IPC resource namespace to be used for the containers in the task.
The valid values are host, task, and none. If host is specified,
then all containers within the tasks that specified the host IPC mode on
the same container instance share the same IPC resources with the host
Amazon EC2 instance. If task is specified, all containers within the
specified task share the same IPC resources. If none is specified, then
IPC resources within the containers of a task are private and not shared
with other containers in a task or on the container instance. If no value
is specified, then the IPC resource namespace sharing depends on the
Docker daemon setting on the container instance. For more information, see
IPC settings in the Docker documentation."



Default value: null

launch_type (string) optional

The launch type on which to run your service. Valid values are EC2 and FARGATE


Default value: "FARGATE"

network_mode (string) optional

The network mode to use for the task. This is required to be awsvpc for FARGATE launch_type or null for EC2 launch_type


Default value: "awsvpc"

nlb_cidr_blocks (list(string)) optional

A list of CIDR blocks to add to the ingress rule for the NLB container port


Default value: [ ]

nlb_container_port (number) optional

The port on the container to allow traffic from the NLB


Default value: 80

ordered_placement_strategy optional

Service level strategy rules that are taken into consideration during task placement.
List from top to bottom in order of precedence. The maximum number of ordered_placement_strategy blocks is 5.
See ordered_placement_strategy



Type:

list(object({
type = string
field = string
}))

Default value: [ ]

permissions_boundary (string) optional

A permissions boundary ARN to apply to the 3 roles that are created.


Default value: ""

pid_mode (string) optional

The process namespace to use for the containers in the task. The valid
values are host and task. If host is specified, then all containers
within the tasks that specified the host PID mode on the same container
instance share the same process namespace with the host Amazon EC2 instanc
. If task is specified, all containers within the specified task share
the same process namespace. If no value is specified, then the process
namespace sharing depends on the Docker daemon setting on the container
instance. For more information, see PID settings in the Docker documentation.



Default value: null

platform_version (string) optional

The platform version on which to run your service. Only applicable for launch_type set to FARGATE.
More information about Fargate platform versions can be found in the AWS ECS User Guide.



Default value: "LATEST"

propagate_tags (string) optional

Specifies whether to propagate the tags from the task definition or the service to the tasks. The valid values are SERVICE and TASK_DEFINITION


Default value: null

proxy_configuration optional

The proxy configuration details for the App Mesh proxy. See proxy_configuration docs https://www.terraform.io/docs/providers/aws/r/ecs_task_definition.html#proxy-configuration-arguments


Type:

object({
type = string
container_name = string
properties = map(string)
})

Default value: null

redeploy_on_apply (bool) optional

Updates the service to the latest task definition on each apply


Default value: false

role_tags_enabled (bool) optional

Whether or not to create tags on ECS roles


Default value: true

runtime_platform (list(map(string))) optional

Zero or one runtime platform configurations that containers in your task may use.
Map of strings with optional keys operating_system_family and cpu_architecture.
See runtime_platform docs https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition#runtime_platform



Default value: [ ]

scheduling_strategy (string) optional

The scheduling strategy to use for the service. The valid values are REPLICA and DAEMON.
Note that Fargate tasks do not support the DAEMON scheduling strategy.



Default value: "REPLICA"

security_group_description (string) optional

The description to assign to the service security group.
Warning: Changing the description causes the security group to be replaced.



Default value: "Allow ALL egress from ECS service"

security_group_enabled (bool) optional

Whether to create a security group for the service.


Default value: true

security_group_ids (list(string)) optional

Security group IDs to allow in Service network_configuration if var.network_mode = "awsvpc"


Default value: [ ]

service_connect_configurations optional

The list of Service Connect configurations.
See service_connect_configuration docs https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service#service_connect_configuration



Type:

list(object({
enabled = bool
namespace = optional(string, null)
log_configuration = optional(object({
log_driver = string
options = optional(map(string), null)
secret_option = optional(list(object({
name = string
value_from = string
})), [])
}), null)
service = optional(list(object({
client_alias = list(object({
dns_name = string
port = number
}))
timeout = optional(list(object({
idle_timeout_seconds = optional(number, null)
per_request_timeout_seconds = optional(number, null)
})), [])
tls = optional(list(object({
kms_key = optional(string, null)
role_arn = optional(string, null)
issuer_cert_authority = object({
aws_pca_authority_arn = string
})
})), [])
discovery_name = optional(string, null)
ingress_port_override = optional(number, null)
port_name = string
})), [])
}))

Default value: [ ]

service_placement_constraints optional

The rules that are taken into consideration during task placement. Maximum number of placement_constraints is 10. See placement_constraints docs


Type:

list(object({
type = string
expression = string
}))

Default value: [ ]

service_registries (list(any)) optional

Zero or one service discovery registries for the service.
The currently supported service registry is Amazon Route 53 Auto Naming Service - aws_service_discovery_service;
see service_registries docs https://www.terraform.io/docs/providers/aws/r/ecs_service.html#service_registries-1"
Service registry is object with required key registry_arn = string and optional keys
port = number
container_name = string
container_port = number



Default value: [ ]

service_role_arn (string) optional

ARN of the IAM role that allows Amazon ECS to make calls to your load balancer on your behalf. This parameter is required if you are using a load balancer with your service, but only if your task definition does not use the awsvpc network mode. If using awsvpc network mode, do not specify this role. If your account has already created the Amazon ECS service-linked role, that role is used by default for your service unless you specify a role here.


Default value: null

subnet_ids (list(string)) optional

Subnet IDs used in Service network_configuration if var.network_mode = "awsvpc"


Default value: null

task_cpu (number) optional

The number of CPU units used by the task. If using FARGATE launch type task_cpu must match supported memory values


Default value: 256

task_definition (any) optional

A list(string) of zero or one ARNs of task definitions, to reuse
reuse an existing task definition family and revision for the ecs
service instead of creating one
DEPRECATED: you can also pass a string with the ARN, but that
string must be known a "plan" time.



Default value: [ ]

task_exec_policy_arns (list(string)) optional

A list of IAM Policy ARNs to attach to the generated task execution role.
Changes to the list will have ripple effects, so use task_exec_policy_arns_map if possible.



Default value: [ ]

task_exec_policy_arns_map (map(string)) optional

A map of name to IAM Policy ARNs to attach to the generated task execution role.
The names are arbitrary, but must be known at plan time. The purpose of the name
is so that changes to one ARN do not cause a ripple effect on the other ARNs.
If you cannot provide unique names known at plan time, use task_exec_policy_arns instead.



Default value: { }

task_exec_role_arn (any) optional

A list(string) of zero or one ARNs of IAM roles that allows the
ECS/Fargate agent to make calls to the ECS API on your behalf.
If the list is empty, a role will be created for you.
DEPRECATED: you can also pass a string with the ARN, but that
string must be known a "plan" time.



Default value: [ ]

task_memory (number) optional

The amount of memory (in MiB) used by the task. If using Fargate launch type task_memory must match supported cpu value


Default value: 512

task_placement_constraints optional

A set of placement constraints rules that are taken into consideration during task placement.
Maximum number of placement_constraints is 10. See placement_constraints



Type:

list(object({
type = string
expression = string
}))

Default value: [ ]

task_policy_arns (list(string)) optional

A list of IAM Policy ARNs to attach to the generated task role.
Changes to the list will have ripple effects, so use task_policy_arns_map if possible.



Default value: [ ]

task_policy_arns_map (map(string)) optional

A map of name to IAM Policy ARNs to attach to the generated task role.
The names are arbitrary, but must be known at plan time. The purpose of the name
is so that changes to one ARN do not cause a ripple effect on the other ARNs.
If you cannot provide unique names known at plan time, use task_policy_arns instead.



Default value: { }

task_role_arn (any) optional

A list(string) of zero or one ARNs of IAM roles that allows
your Amazon ECS container task to make calls to other AWS services.
If the list is empty, a role will be created for you.
DEPRECATED: you can also pass a string with the ARN, but that
string must be known a "plan" time.



Default value: [ ]

track_latest (bool) optional

Whether should track latest task definition or the one created with the resource.


Default value: false

use_alb_security_group (bool) optional

A flag to enable/disable allowing traffic from the ALB security group to the service security group


Default value: false

use_nlb_cidr_blocks (bool) optional

A flag to enable/disable adding the NLB ingress rule to the service security group


Default value: false

use_old_arn (bool) optional

A flag to enable/disable tagging the ecs resources that require the new arn format


Default value: false

wait_for_steady_state (bool) optional

If true, it will wait for the service to reach a steady state (like aws ecs wait services-stable) before continuing


Default value: false

Context Variables

The following variables are defined in the context.tf file of this module and part of the terraform-null-label pattern.

additional_tag_map (map(string)) optional

Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.


Required: No

Default value: { }

attributes (list(string)) optional

ID element. Additional attributes (e.g. workers or cluster) to add to id,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the delimiter
and treated as a single ID element.


Required: No

Default value: [ ]

context (any) optional

Single object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as null to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.


Required: No

Default value:

{
"additional_tag_map": {},
"attributes": [],
"delimiter": null,
"descriptor_formats": {},
"enabled": true,
"environment": null,
"id_length_limit": null,
"label_key_case": null,
"label_order": [],
"label_value_case": null,
"labels_as_tags": [
"unset"
],
"name": null,
"namespace": null,
"regex_replace_chars": null,
"stage": null,
"tags": {},
"tenant": null
}
delimiter (string) optional

Delimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.


Required: No

Default value: null

descriptor_formats (any) optional

Describe additional descriptors to be output in the descriptors output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
\{<br/> format = string<br/> labels = list(string)<br/> \}
(Type is any so the map values can later be enhanced to provide additional options.)
format is a Terraform format string to be passed to the format() function.
labels is a list of labels, in order, to pass to format() function.
Label values will be normalized before being passed to format() so they will be
identical to how they appear in id.
Default is {} (descriptors output will be empty).


Required: No

Default value: { }

enabled (bool) optional

Set to false to prevent the module from creating any resources
Required: No

Default value: null

environment (string) optional

ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'
Required: No

Default value: null

id_length_limit (number) optional

Limit id to this many characters (minimum 6).
Set to 0 for unlimited length.
Set to null for keep the existing setting, which defaults to 0.
Does not affect id_full.


Required: No

Default value: null

label_key_case (string) optional

Controls the letter case of the tags keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the tags input.
Possible values: lower, title, upper.
Default value: title.


Required: No

Default value: null

label_order (list(string)) optional

The order in which the labels (ID elements) appear in the id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.


Required: No

Default value: null

label_value_case (string) optional

Controls the letter case of ID elements (labels) as included in id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the tags input.
Possible values: lower, title, upper and none (no transformation).
Set this to title and set delimiter to "" to yield Pascal Case IDs.
Default value: lower.


Required: No

Default value: null

labels_as_tags (set(string)) optional

Set of labels (ID elements) to include as tags in the tags output.
Default is to include all labels.
Tags with empty values will not be included in the tags output.
Set to [] to suppress all generated tags.
Notes:
The value of the name tag, if included, will be the id, not the name.
Unlike other null-label inputs, the initial setting of labels_as_tags cannot be
changed in later chained modules. Attempts to change it will be silently ignored.


Required: No

Default value:

[
"default"
]
name (string) optional

ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a tag.
The "name" tag is set to the full id string. There is no tag with the value of the name input.


Required: No

Default value: null

namespace (string) optional

ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique
Required: No

Default value: null

regex_replace_chars (string) optional

Terraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.


Required: No

Default value: null

stage (string) optional

ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'
Required: No

Default value: null

tags (map(string)) optional

Additional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.


Required: No

Default value: { }

tenant (string) optional

ID element (Rarely used, not included by default). A customer identifier, indicating who this instance of a resource is for
Required: No

Default value: null

Outputs

ecs_exec_role_policy_id

The ECS service role policy ID, in the form of role_name:role_policy_name

ecs_exec_role_policy_name

ECS service role name

service_arn

ECS Service ARN

service_name

ECS Service name

service_role_arn

ECS Service role ARN

service_security_group_id

Security Group ID of the ECS task

task_definition_arn

ECS task definition ARN

task_definition_arn_without_revision

ECS task definition ARN without revision

task_definition_family

ECS task definition family

task_definition_revision

ECS task definition revision

task_exec_role_arn

ECS Task exec role ARN

task_exec_role_id

ECS Task exec role id

task_exec_role_name

ECS Task role name

task_role_arn

ECS Task role ARN

task_role_id

ECS Task role id

task_role_name

ECS Task role name

Dependencies

Requirements

  • terraform, version: >= 0.14.0
  • aws, version: >= 5.77

Providers

  • aws, version: >= 5.77

Modules

NameVersionSourceDescription
exec_label0.25.0cloudposse/label/nulln/a
service_connect_label0.25.0cloudposse/label/nulln/a
service_label0.25.0cloudposse/label/nulln/a
task_label0.25.0cloudposse/label/nulln/a
this0.25.0cloudposse/label/nulln/a

Resources

The following resources are used by this module:

Data Sources

The following data sources are used by this module: