Amazon ECS Construct Library
This package contains constructs for working with Amazon Elastic Container
Service (Amazon ECS).
Amazon ECS is a highly scalable, fast, container management service
that makes it easy to run, stop,
and manage Docker containers on a cluster of Amazon EC2 instances.
For further information on Amazon ECS,
see the Amazon ECS documentation
The following example creates an Amazon ECS cluster,
adds capacity to it,
and instantiates the Amazon ECS Service with an automatic load balancer.
import ecs = require('@aws-cdk/aws-ecs');
const cluster = new ecs.Cluster(this, 'Cluster', {
vpc,
});
cluster.addCapacity('DefaultAutoScalingGroupCapacity', {
instanceType: new ec2.InstanceType("t2.xlarge"),
desiredCapacity: 3,
});
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('DefaultContainer', {
image: ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample"),
memoryLimitMiB: 512,
});
const ecsService = new ecs.Ec2Service(this, 'Service', {
cluster,
taskDefinition,
});
For a set of constructs defining common ECS architectural patterns, see the @aws-cdk/aws-ecs-patterns
package.
Launch Types: AWS Fargate vs Amazon EC2
There are two sets of constructs in this library; one to run tasks on Amazon EC2 and
one to run tasks on AWS Fargate.
- Use the
Ec2TaskDefinition
and Ec2Service
constructs to run tasks on Amazon EC2 instances running in your account. - Use the
FargateTaskDefinition
and FargateService
constructs to run tasks on
instances that are managed for you by AWS.
Here are the main differences:
- Amazon EC2: instances are under your control. Complete control of task to host
allocation. Required to specify at least a memory reseration or limit for
every container. Can use Host, Bridge and AwsVpc networking modes. Can attach
Classic Load Balancer. Can share volumes between container and host.
- AWS Fargate: tasks run on AWS-managed instances, AWS manages task to host
allocation for you. Requires specification of memory and cpu sizes at the
taskdefinition level. Only supports AwsVpc networking modes and
Application/Network Load Balancers. Only the AWS log driver is supported.
Many host features are not supported such as adding kernel capabilities
and mounting host devices/volumes inside the container.
For more information on Amazon EC2 vs AWS Fargate and networking see the AWS Documentation:
AWS Fargate and
Task Networking.
Clusters
A Cluster
defines the infrastructure to run your
tasks on. You can run many tasks on a single cluster.
The following code creates a cluster that can run AWS Fargate tasks:
const cluster = new ecs.Cluster(this, 'Cluster', {
vpc: vpc
});
To use tasks with Amazon EC2 launch-type, you have to add capacity to
the cluster in order for tasks to be scheduled on your instances. Typically,
you add an AutoScalingGroup with instances running the latest
Amazon ECS-optimized AMI to the cluster. There is a method to build and add such an
AutoScalingGroup automatically, or you can supply a customized AutoScalingGroup
that you construct yourself. It's possible to add multiple AutoScalingGroups
with various instance types.
The following example creates an Amazon ECS cluster and adds capacity to it:
const cluster = new ecs.Cluster(this, 'Cluster', {
vpc: vpc
});
cluster.addCapacity('DefaultAutoScalingGroupCapacity', {
instanceType: new ec2.InstanceType("t2.xlarge"),
desiredCapacity: 3,
});
const autoScalingGroup = new autoscaling.AutoScalingGroup(this, 'ASG', {
vpc,
instanceType: new ec2.InstanceType('t2.xlarge'),
machineImage: EcsOptimizedImage.amazonLinux(),
desiredCapacity: 3,
});
cluster.addAutoScalingGroup(autoScalingGroup);
If you omit the property vpc
, the construct will create a new VPC with two AZs.
Spot Instances
To add spot instances into the cluster, you must specify the spotPrice
in the ecs.AddCapacityOptions
and optionally enable the spotInstanceDraining
property.
cluster.addCapacity('AsgSpot', {
maxCapacity: 2,
minCapacity: 2,
desiredCapacity: 2,
instanceType: new ec2.InstanceType('c5.xlarge'),
spotPrice: '0.0735',
spotInstanceDraining: true,
});
Task definitions
A task Definition describes what a single copy of a task should look like.
A task definition has one or more containers; typically, it has one
main container (the default container is the first one that's added
to the task definition, and it is marked essential) and optionally
some supporting containers which are used to support the main container,
doings things like upload logs or metrics to monitoring services.
To run a task or service with Amazon EC2 launch type, use the Ec2TaskDefinition
. For AWS Fargate tasks/services, use the
FargateTaskDefinition
. These classes provide a simplified API that only contain
properties relevant for that specific launch type.
For a FargateTaskDefinition
, specify the task size (memoryLimitMiB
and cpu
):
const fargateTaskDefinition = new ecs.FargateTaskDefinition(this, 'TaskDef', {
memoryLimitMiB: 512,
cpu: 256
});
To add containers to a task definition, call addContainer()
:
const container = fargateTaskDefinition.addContainer("WebContainer", {
image: ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample"),
});
For a Ec2TaskDefinition
:
const ec2TaskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef', {
networkMode: NetworkMode.BRIDGE
});
const container = ec2TaskDefinition.addContainer("WebContainer", {
image: ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample"),
memoryLimitMiB: 1024
});
You can specify container properties when you add them to the task definition, or with various methods, e.g.:
container.addPortMappings({
containerPort: 3000
})
To use a TaskDefinition that can be used with either Amazon EC2 or
AWS Fargate launch types, use the TaskDefinition
construct.
When creating a task definition you have to specify what kind of
tasks you intend to run: Amazon EC2, AWS Fargate, or both.
The following example uses both:
const taskDefinition = new ecs.TaskDefinition(this, 'TaskDef', {
memoryMiB: '512',
cpu: '256',
networkMode: NetworkMode.AWS_VPC,
compatibility: ecs.Compatibility.EC2_AND_FARGATE,
});
Images
Images supply the software that runs inside the container. Images can be
obtained from either DockerHub or from ECR repositories, or built directly from a local Dockerfile.
ecs.ContainerImage.fromRegistry(imageName)
: use a public image.ecs.ContainerImage.fromRegistry(imageName, { credentials: mySecret })
: use a private image that requires credentials.ecs.ContainerImage.fromEcrRepository(repo, tag)
: use the given ECR repository as the image
to start. If no tag is provided, "latest" is assumed.ecs.ContainerImage.fromAsset('./image')
: build and upload an
image directly from a Dockerfile
in your source directory.ecs.ContainerImage.fromDockerImageAsset(asset)
: uses an existing
@aws-cdk/aws-ecr-assets.DockerImageAsset
as a container image.
Environment variables
To pass environment variables to the container, use the environment
and secrets
props.
taskDefinition.addContainer('container', {
image: ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample"),
memoryLimitMiB: 1024,
environment: {
STAGE: 'prod',
},
secrets: {
SECRET: ecs.Secret.fromSecretsManager(secret),
PARAMETER: ecs.Secret.fromSsmParameter(parameter),
}
});
The task execution role is automatically granted read permissions on the secrets/parameters.
Service
A Service
instantiates a TaskDefinition
on a Cluster
a given number of
times, optionally associating them with a load balancer.
If a task fails,
Amazon ECS automatically restarts the task.
const taskDefinition;
const service = new ecs.FargateService(this, 'Service', {
cluster,
taskDefinition,
desiredCount: 5
});
Include an application/network load balancer
Services
are load balancing targets and can be added to a target group, which will be attached to an application/network load balancers:
import elbv2 = require('@aws-cdk/aws-elasticloadbalancingv2');
const service = new ecs.FargateService(this, 'Service', { });
const lb = new elbv2.ApplicationLoadBalancer(this, 'LB', { vpc, internetFacing: true });
const listener = lb.addListener('Listener', { port: 80 });
const targetGroup1 = listener.addTargets('ECS1', {
port: 80,
targets: [service]
});
const targetGroup2 = listener.addTargets('ECS2', {
port: 80,
targets: [service.loadBalancerTarget({
containerName: 'MyContainer',
containerPort: 8080
})]
});
Note that in the example above, the default service
only allows you to register the first essential container or the first mapped port on the container as a target and add it to a new target group. To have more control over which container and port to register as targets, you can use service.loadBalancerTarget()
to return a load balancing target for a specific container and port.
Alternatively, you can also create all load balancer targets to be registered in this service, add them to target groups, and attach target groups to listeners accordingly.
import elbv2 = require('@aws-cdk/aws-elasticloadbalancingv2');
const service = new ecs.FargateService(this, 'Service', { });
const lb = new elbv2.ApplicationLoadBalancer(this, 'LB', { vpc, internetFacing: true });
const listener = lb.addListener('Listener', { port: 80 });
service.registerLoadBalancerTargets(
{
containerName: 'web',
containerPort: 80,
newTargetGroupId: 'ECS',
listener: ecs.ListenerConfig.applicationListener(listener, {
protocol: elbv2.ApplicationProtocol.HTTPS
}),
},
);
Using a Load Balancer from a different Stack
If you want to put your Load Balancer and the Service it is load balancing to in
different stacks, you may not be able to use the convenience methods
loadBalancer.addListener()
and listener.addTargets()
.
The reason is that these methods will create resources in the same Stack as the
object they're called on, which may lead to cyclic references between stacks.
Instead, you will have to create an ApplicationListener
in the service stack,
or an empty TargetGroup
in the load balancer stack that you attach your
service to.
See the ecs/cross-stack-load-balancer example
for the alternatives.
Include a classic load balancer
Services
can also be directly attached to a classic load balancer as targets:
import elb = require('@aws-cdk/aws-elasticloadbalancing');
const service = new ecs.Ec2Service(this, 'Service', { });
const lb = new elb.LoadBalancer(stack, 'LB', { vpc });
lb.addListener({ externalPort: 80 });
lb.addTarget(service);
Similarly, if you want to have more control over load balancer targeting:
import elb = require('@aws-cdk/aws-elasticloadbalancing');
const service = new ecs.Ec2Service(this, 'Service', { });
const lb = new elb.LoadBalancer(stack, 'LB', { vpc });
lb.addListener({ externalPort: 80 });
lb.addTarget(service.loadBalancerTarget{
containerName: 'MyContainer',
containerPort: 80
});
There are two higher-level constructs available which include a load balancer for you that can be found in the aws-ecs-patterns module:
LoadBalancedFargateService
LoadBalancedEc2Service
Task Auto-Scaling
You can configure the task count of a service to match demand. Task auto-scaling is
configured by calling autoScaleTaskCount()
:
const scaling = service.autoScaleTaskCount({ maxCapacity: 10 });
scaling.scaleOnCpuUtilization('CpuScaling', {
targetUtilizationPercent: 50
});
scaling.scaleOnRequestCount('RequestScaling', {
requestsPerTarget: 10000,
targetGroup: target
})
Task auto-scaling is powered by Application Auto-Scaling.
See that section for details.
Instance Auto-Scaling
If you're running on AWS Fargate, AWS manages the physical machines that your
containers are running on for you. If you're running an Amazon ECS cluster however,
your Amazon EC2 instances might fill up as your number of Tasks goes up.
To avoid placement errors, configure auto-scaling for your
Amazon EC2 instance group so that your instance count scales with demand. To keep
your Amazon EC2 instances halfway loaded, scaling up to a maximum of 30 instances
if required:
const autoScalingGroup = cluster.addCapacity('DefaultAutoScalingGroup', {
instanceType: new ec2.InstanceType("t2.xlarge"),
minCapacity: 3,
maxCapacity: 30,
desiredCapacity: 3,
taskDrainTime: Duration.seconds(300)
});
autoScalingGroup.scaleOnCpuUtilization('KeepCpuHalfwayLoaded', {
targetUtilizationPercent: 50
});
See the @aws-cdk/aws-autoscaling
library for more autoscaling options
you can configure on your instances.
Integration with CloudWatch Events
To start an Amazon ECS task on an Amazon EC2-backed Cluster, instantiate an
@aws-cdk/aws-events-targets.EcsTask
instead of an Ec2Service
:
import targets = require('@aws-cdk/aws-events-targets');
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromAsset(path.resolve(__dirname, '..', 'eventhandler-image')),
memoryLimitMiB: 256,
logging: new ecs.AwsLogDriver({ streamPrefix: 'EventDemo' })
});
const rule = new events.Rule(this, 'Rule', {
schedule: events.Schedule.expression('rate(1 min)')
});
rule.addTarget(new targets.EcsTask({
cluster,
taskDefinition,
taskCount: 1,
containerOverrides: [{
containerName: 'TheContainer',
environment: [{
name: 'I_WAS_TRIGGERED',
value: 'From CloudWatch Events'
}]
}]
}));
Log Drivers
Currently Supported Log Drivers:
- awslogs
- fluentd
- gelf
- journald
- json-file
- splunk
- syslog
- awsfirelens
awslogs Log Driver
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: ecs.LogDrivers.awslogs({ streamPrefix: 'EventDemo' })
});
fluentd Log Driver
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: ecs.LogDrivers.fluentd()
});
gelf Log Driver
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: ecs.LogDrivers.gelf({ address: 'my-gelf-address' })
});
journald Log Driver
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: ecs.LogDrivers.journald()
});
json-file Log Driver
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: ecs.LogDrivers.jsonFile()
});
splunk Log Driver
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: ecs.LogDrivers.splunk({
token: cdk.SecretValue.secretsManager('my-splunk-token'),
url: 'my-splunk-url'
})
});
syslog Log Driver
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: ecs.LogDrivers.syslog()
});
firelens Log Driver
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: ecs.LogDrivers.firelens({
options: {
Name: 'firehose',
region: 'us-west-2',
delivery_stream: 'my-stream',
}
})
});
Generic Log Driver
A generic log driver object exists to provide a lower level abstraction of the log driver configuration.
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: new ecs.GenericLogDriver({
logDriver: 'fluentd',
options: {
tag: 'example-tag'
}
})
});