ECS (Elastic Container Service)¶
This page contains information about the ECS service supported in Handel. This Handel service provisions your application code as an ECS Service, with included supporting infrastructure such as load balancers and auto-scaling groups.
Service Limitations¶
One service per cluster¶
This service uses a model of one ECS service per ECS cluster. It does not support the model of one large cluster with multiple services running on it.
Unsupported ECS task features¶
This service currently does not support the following ECS task features:
- User-specified volumes from the EC2 host. You can specify services such as EFS that will mount a volume in your container for you, however.
- Extra networking items such as manually specifying DNS Servers, DNS Search Domains, and extra hosts in the /etc/hosts file
- Task definition options such as specifying an entry point, command, or working directory. These options are available in your Dockerfile and can be specified there.
Important
This service only offers limited tagging support. ECS resources will not be tagged, but any load balancers, EC2 instances, and the Cloudformation stack used to create them will be. See Tagging Unsupported Resources.
Parameters¶
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
type | string | Yes | This must always be ecs for this service type. | |
containers | Containers | Yes | This section allows you to configure one or more containers that will make up your service. | |
auto_scaling | AutoScaling | Yes | This section contains information about scaling your tasks up and down. | |
cluster | Cluster | No | This section contains items used to configure your ECS cluster of EC2 instances. | |
load_balancer | LoadBalancer | No | If your task needs routing from a load balancer, this section can be used to configure the load balancer’s options. | |
logging | string | No | enabled | Turns CloudWatch logging on or off. Must be either “enabled” or “disabled”. See Logging for more. |
log_retention_in_days | number | No | 0 | Configures the log retention duration for CloudWatch logs. If set to 0, logs are kept indefinitely. |
tags | Resource Tags | No | This section allows you to specify any tags you wish to apply to your ECS service. |
Containers¶
The containers section is defined by the following schema:
containers:
- name: <string> # Required
image_name: <string> # Optional
port_mappings: # Optional, required if you specify 'routing'
- <integer>
max_mb: <integer> # Optional. Default: 128
cpu_units: <integer> # Optional. Default: 100
links: # Optional
- <string> # Each value in the list should be the "name" field of another container in your containers list
routing: # Optional
base_path: <string> # Required
health_check_path: <string> # Optional. Default: /
environment_variables: # Optional
<string>: <string>
Note
You may currently only specify the routing section in a single container. Attempting to add routing to multiple containers in a single service will result in an error. This is due to a current limitation in the integration between Application Load Balancers (ALB) and ECS that only allows you to attach an ALB to a single container in your task.
Container Image Names¶
In each container, you may specify an optional image_name. If you want to pull a public image from somewhere like DockerHub, just reference the image name:
dsw88/my-cool-image
If you want to reference an image in your AWS account’s EC2 Container Registry (ECR), reference it like this:
# The <account> piece will be replaced with your account's long ECR repository name
<account>/my-cool-image
If you don’t specify an image_name, Handel will automatically choose an image name for you based on your Handel naming information. It will use the following image naming pattern:
<appName>-<serviceName>-<containerName>:<environmentName>
For example, if you don’t specify an image_name in the below Example Handel Files, the two images ECS looks for would be named the following:
my-ecs-app-webapp-mywebapp:dev
my-ecs-app-webapp-myothercontainer:dev
AutoScaling¶
The auto_scaling section is defined by the following schema:
auto_scaling:
min_tasks: <integer> # Required
max_tasks: <integer> # Required
scaling_policies: # Optional
- type: <up|down> # Required
adjustment: # Required
value: <number> # Required
type: <string> # Optional. Default: 'ChangeInCapacity'. See http://docs.aws.amazon.com/ApplicationAutoScaling/latest/APIReference/API_StepScalingPolicyConfiguration.html for allowed values
cooldown: <number> # Optional. Default: 300.
alarm: # Required
metric_name: <string> # Required
comparison_operator: <string> # Required. See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cw-alarm.html#cfn-cloudwatch-alarms-comparisonoperator for allowed values.
threshold: <number> # Required
namespace: <string> # Optional. Default: 'AWS/ECS'
dimensions: # Optional. Default: Your ECS service dimensions
<string>: <string>
period: <number> # Optional. Default: 300
evaluation_periods: <number> # Optional. Default: 5
Tip
Auto-scaling in AWS is based off the CloudWatch service. Configuring auto-scaling can be a bit daunting at first if you haven’t used CloudWatch metrics or alarms.
See the below Example Handel Files section for some examples of configuring auto-scaling.
Note
If you don’t wish to configure auto scaling for your containers, just set min_tasks = max_tasks and don’t configure any scaling_policies.
Cluster¶
The cluster section is defined by the following schema:
cluster:
key_name: <string> # Optional. The name of the EC2 keypair to use for SSH access. Default: none
instance_type: <string> # Optional. The type of EC2 instances to use in the cluster. Default: t2.micro
LoadBalancer¶
The load_balancer section is defined by the following schema:
load_balancer:
type: <string> # Required. Allowed values: `http`, `https`.
timeout: <integer> # Optional. The connection timeout on the load balancer
https_certificate: <string> # Required if type=https. The ID of the ACM certificate to use on the load balancer.
dns_names:
- <string> # Optional.
health_check_grace_period: <integer> # Optional. Default: 15. The period of time, in seconds, that the Amazon ECS service scheduler ignores unhealthy Elastic Load Balancing target health checks after a task has first started.
The dns_names section creates one or more dns names that point to this load balancer. See DNS Records for more.
Logging¶
If logging is enabled, a CloudWatch log group will be created, with a name like ecs/<appName>-<environmentName>-<serviceName>. Each container in the container configuration will have a log prefix matching its name. The retention time for the log group is set with log_retention_in_days, and defaults to keeping the logs indefinitely.
Example Handel Files¶
Simplest Possible ECS Service¶
This Handel file shows an ECS service with only the required parameters:
version: 1
name: my-ecs-app
environments:
dev:
webapp:
type: ecs
auto_scaling:
min_tasks: 1
max_tasks: 1
containers:
- name: mywebapp
Web Service¶
This Handel file shows an ECS service configured with HTTP routing to it via a load balancer:
version: 1
name: my-ecs-app
environments:
dev:
webapp:
type: ecs
auto_scaling:
min_tasks: 1
max_tasks: 1
load_balancer:
type: http
containers:
- name: mywebapp
port_mappings:
- 5000
routing:
base_path: /mypath
health_check_path: /
Multiple Containers¶
This Handel file shows an ECS service with two containers being configured:
version: 1
name: my-ecs-app
environments:
dev:
webapp:
type: ecs
cluster:
key_name: mykey
auto_scaling:
min_tasks: 1
max_tasks: 1
load_balancer:
type: http
timeout: 120
tags:
mytag: myvalue
containers:
- name: mywebapp
port_mappings:
- 5000
max_mb: 256
cpu_units: 200
environment_variables:
MY_VAR: myvalue
routing:
base_path: /mypath
health_check_path: /
- name: myothercontainer
max_mb: 256
Auto-Scaling On Service CPU Utilization¶
This Handel file shows an ECS service auto-scaling on its own CPU Utilization metric. Note that in the alarm section you can leave off things like namespace and dimensions and it will default to your ECS service for those values:
version: 1
name: my-ecs-app
environments:
dev:
webapp:
type: ecs
auto_scaling:
min_tasks: 1
max_tasks: 11
scaling_policies:
- type: up
adjustment:
value: 5
alarm:
metric_name: CPUUtilization
comparison_operator: GreaterThanThreshold
threshold: 70
- type: down
adjustment:
value: 5
alarm:
metric_name: CPUUtilization
comparison_operator: LessThanThreshold
threshold: 30
load_balancer:
type: http
containers:
- name: ecstest
port_mappings:
- 5000
routing:
base_path: /mypath
Auto-Scaling On Queue Size¶
This Handel file shows an ECS service scaling off the size of a queue it consumes:
version: 1
name: my-ecs-app
environments:
dev:
webapp:
type: ecs
auto_scaling:
min_tasks: 1
max_tasks: 11
scaling_policies:
- type: up
adjustment:
value: 5
alarm:
namespace: AWS/SQS
dimensions:
QueueName: my-ecs-app-dev-queue-sqs
metric_name: ApproximateNumberOfMessagesVisible
comparison_operator: GreaterThanThreshold
threshold: 2000
- type: down
adjustment:
value: 5
alarm:
namespace: AWS/SQS
dimensions:
QueueName: my-ecs-app-dev-queue-sqs
metric_name: ApproximateNumberOfMessagesVisible
comparison_operator: LessThanThreshold
threshold: 100
load_balancer:
type: http
containers:
- name: ecstest
port_mappings:
- 5000
routing:
base_path: /mypath
dependencies:
- queue
queue:
type: sqs
Depending on this service¶
The ECS service cannot be referenced as a dependency for another Handel service
Events produced by this service¶
The ECS service does not produce events for other Handel services to consume.
Events consumed by this service¶
The ECS service does not consume events from other Handel services.