-
Interface Summary Interface Description ApplicationListenerProps Properties to define an application listener.ApplicationLoadBalancedEc2ServiceProps The properties for the ApplicationLoadBalancedEc2Service service.ApplicationLoadBalancedFargateServiceProps The properties for the ApplicationLoadBalancedFargateService service.ApplicationLoadBalancedServiceBaseProps The properties for the base ApplicationLoadBalancedEc2Service or ApplicationLoadBalancedFargateService service.ApplicationLoadBalancedTaskImageOptions ApplicationLoadBalancedTaskImageProps Options for configuring a new container.ApplicationLoadBalancerProps Properties to define an application load balancer.ApplicationMultipleTargetGroupsEc2ServiceProps The properties for the ApplicationMultipleTargetGroupsEc2Service service.ApplicationMultipleTargetGroupsFargateServiceProps The properties for the ApplicationMultipleTargetGroupsFargateService service.ApplicationMultipleTargetGroupsServiceBaseProps The properties for the base ApplicationMultipleTargetGroupsEc2Service or ApplicationMultipleTargetGroupsFargateService service.ApplicationTargetProps Properties to define an application target group.NetworkListenerProps Properties to define an network listener.NetworkLoadBalancedEc2ServiceProps The properties for the NetworkLoadBalancedEc2Service service.NetworkLoadBalancedFargateServiceProps The properties for the NetworkLoadBalancedFargateService service.NetworkLoadBalancedServiceBaseProps The properties for the base NetworkLoadBalancedEc2Service or NetworkLoadBalancedFargateService service.NetworkLoadBalancedTaskImageOptions NetworkLoadBalancedTaskImageProps Options for configuring a new container.NetworkLoadBalancerProps Properties to define an network load balancer.NetworkMultipleTargetGroupsEc2ServiceProps The properties for the NetworkMultipleTargetGroupsEc2Service service.NetworkMultipleTargetGroupsFargateServiceProps The properties for the NetworkMultipleTargetGroupsFargateService service.NetworkMultipleTargetGroupsServiceBaseProps The properties for the base NetworkMultipleTargetGroupsEc2Service or NetworkMultipleTargetGroupsFargateService service.NetworkTargetProps Properties to define a network load balancer target group.QueueProcessingEc2ServiceProps The properties for the QueueProcessingEc2Service service.QueueProcessingFargateServiceProps The properties for the QueueProcessingFargateService service.QueueProcessingServiceBaseProps The properties for the base QueueProcessingEc2Service or QueueProcessingFargateService service.ScheduledEc2TaskDefinitionOptions The properties for the ScheduledEc2Task using a task definition.ScheduledEc2TaskImageOptions The properties for the ScheduledEc2Task using an image.ScheduledEc2TaskProps The properties for the ScheduledEc2Task task.ScheduledFargateTaskDefinitionOptions The properties for the ScheduledFargateTask using a task definition.ScheduledFargateTaskImageOptions The properties for the ScheduledFargateTask using an image.ScheduledFargateTaskProps The properties for the ScheduledFargateTask task.ScheduledTaskBaseProps The properties for the base ScheduledEc2Task or ScheduledFargateTask task.ScheduledTaskImageProps
Package software.amazon.awscdk.services.ecs.patterns Description
CDK Construct library for higher-level ECS Constructs
---
This library provides higher-level Amazon ECS constructs which follow common architectural patterns. It contains:
- Application Load Balanced Services
- Network Load Balanced Services
- Queue Processing Services
- Scheduled Tasks (cron jobs)
- Additional Examples
Application Load Balanced Services
To define an Amazon ECS service that is behind an application load balancer, instantiate one of the following:
ApplicationLoadBalancedEc2Service
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var loadBalancedEcsService = ApplicationLoadBalancedEc2Service.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(1024)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("test"),
"environment", Map.of(
"TEST_ENVIRONMENT_VARIABLE1", "test environment variable 1 value",
"TEST_ENVIRONMENT_VARIABLE2", "test environment variable 2 value")))
.desiredCount(2)
.build();
ApplicationLoadBalancedFargateService
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var loadBalancedFargateService = ApplicationLoadBalancedFargateService.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(1024)
.cpu(512)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample")))
.build();
loadBalancedFargateService.targetGroup.configureHealthCheck(Map.of(
"path", "/custom-health-path"));
Instead of providing a cluster you can specify a VPC and CDK will create a new ECS cluster. If you deploy multiple services CDK will only create one cluster per VPC.
You can omit cluster and vpc to let CDK create a new VPC with two AZs and create a cluster inside this VPC.
You can customize the health check for your target group; otherwise it defaults to HTTP over port 80 hitting path /.
Fargate services will use the LATEST platform version by default, but you can override by providing a value for the platformVersion property in the constructor.
Additionally, if more than one application target group are needed, instantiate one of the following:
ApplicationMultipleTargetGroupsEc2Service
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
// One application load balancer with one listener and two target groups.
var loadBalancedEc2Service = ApplicationMultipleTargetGroupsEc2Service.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(256)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample")))
.targetGroups(asList(Map.of(
"containerPort", 80), Map.of(
"containerPort", 90,
"pathPattern", "a/b/c",
"priority", 10)))
.build();
ApplicationMultipleTargetGroupsFargateService
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
// One application load balancer with one listener and two target groups.
var loadBalancedFargateService = ApplicationMultipleTargetGroupsFargateService.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(1024)
.cpu(512)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample")))
.targetGroups(asList(Map.of(
"containerPort", 80), Map.of(
"containerPort", 90,
"pathPattern", "a/b/c",
"priority", 10)))
.build();
Network Load Balanced Services
To define an Amazon ECS service that is behind a network load balancer, instantiate one of the following:
NetworkLoadBalancedEc2Service
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var loadBalancedEcsService = NetworkLoadBalancedEc2Service.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(1024)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("test"),
"environment", Map.of(
"TEST_ENVIRONMENT_VARIABLE1", "test environment variable 1 value",
"TEST_ENVIRONMENT_VARIABLE2", "test environment variable 2 value")))
.desiredCount(2)
.build();
NetworkLoadBalancedFargateService
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var loadBalancedFargateService = NetworkLoadBalancedFargateService.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(1024)
.cpu(512)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample")))
.build();
The CDK will create a new Amazon ECS cluster if you specify a VPC and omit cluster. If you deploy multiple services the CDK will only create one cluster per VPC.
If cluster and vpc are omitted, the CDK creates a new VPC with subnets in two Availability Zones and a cluster within this VPC.
Additionally, if more than one network target group is needed, instantiate one of the following:
- NetworkMultipleTargetGroupsEc2Service
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
// Two network load balancers, each with their own listener and target group.
var loadBalancedEc2Service = NetworkMultipleTargetGroupsEc2Service.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(256)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample")))
.loadBalancers(asList(Map.of(
"name", "lb1",
"listeners", asList(Map.of(
"name", "listener1"))), Map.of(
"name", "lb2",
"listeners", asList(Map.of(
"name", "listener2")))))
.targetGroups(asList(Map.of(
"containerPort", 80,
"listener", "listener1"), Map.of(
"containerPort", 90,
"listener", "listener2")))
.build();
- NetworkMultipleTargetGroupsFargateService
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
// Two network load balancers, each with their own listener and target group.
var loadBalancedFargateService = NetworkMultipleTargetGroupsFargateService.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(512)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample")))
.loadBalancers(asList(Map.of(
"name", "lb1",
"listeners", asList(Map.of(
"name", "listener1"))), Map.of(
"name", "lb2",
"listeners", asList(Map.of(
"name", "listener2")))))
.targetGroups(asList(Map.of(
"containerPort", 80,
"listener", "listener1"), Map.of(
"containerPort", 90,
"listener", "listener2")))
.build();
Queue Processing Services
To define a service that creates a queue and reads from that queue, instantiate one of the following:
QueueProcessingEc2Service
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var queueProcessingEc2Service = QueueProcessingEc2Service.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(1024)
.image(ecs.ContainerImage.fromRegistry("test"))
.command(asList("-c", "4", "amazon.com"))
.enableLogging(false)
.desiredTaskCount(2)
.environment(Map.of(
"TEST_ENVIRONMENT_VARIABLE1", "test environment variable 1 value",
"TEST_ENVIRONMENT_VARIABLE2", "test environment variable 2 value"))
.queue(queue)
.maxScalingCapacity(5)
.build();
QueueProcessingFargateService
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var queueProcessingFargateService = QueueProcessingFargateService.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(512)
.image(ecs.ContainerImage.fromRegistry("test"))
.command(asList("-c", "4", "amazon.com"))
.enableLogging(false)
.desiredTaskCount(2)
.environment(Map.of(
"TEST_ENVIRONMENT_VARIABLE1", "test environment variable 1 value",
"TEST_ENVIRONMENT_VARIABLE2", "test environment variable 2 value"))
.queue(queue)
.maxScalingCapacity(5)
.build();
when queue not provided by user, CDK will create a primary queue and a dead letter queue with default redrive policy and attach permission to the task to be able to access the primary queue.
Scheduled Tasks
To define a task that runs periodically, instantiate an ScheduledEc2Task:
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
// Instantiate an Amazon EC2 Task to run at a scheduled interval
var ecsScheduledTask = ScheduledEc2Task.Builder.create(stack, "ScheduledTask")
.cluster(cluster)
.scheduledEc2TaskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample"),
"memoryLimitMiB", 256,
"environment", Map.of("name", "TRIGGER", "value", "CloudWatch Events")))
.schedule(events.Schedule.expression("rate(1 minute)"))
.build();
Additional Examples
In addition to using the constructs, users can also add logic to customize these constructs:
Add Schedule-Based Auto-Scaling to an ApplicationLoadBalancedFargateService
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import software.amazon.awscdk.services.applicationautoscaling.Schedule;
import application.load.balanced.fargate.service.ApplicationLoadBalancedFargateService;
import application.load.balanced.fargate.service.ApplicationLoadBalancedFargateServiceProps;
var loadBalancedFargateService = ApplicationLoadBalancedFargateService.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(1024)
.desiredCount(1)
.cpu(512)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample")))
.build();
var scalableTarget = loadBalancedFargateService.service.autoScaleTaskCount(Map.of(
"minCapacity", 5,
"maxCapacity", 20));
scalableTarget.scaleOnSchedule("DaytimeScaleDown", Map.of(
"schedule", Schedule.cron(new CronOptions().hour("8").minute("0")),
"minCapacity", 1));
scalableTarget.scaleOnSchedule("EveningRushScaleUp", Map.of(
"schedule", Schedule.cron(new CronOptions().hour("20").minute("0")),
"minCapacity", 10));
Add Metric-Based Auto-Scaling to an ApplicationLoadBalancedFargateService
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import application.load.balanced.fargate.service.ApplicationLoadBalancedFargateService;
var loadBalancedFargateService = ApplicationLoadBalancedFargateService.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(1024)
.desiredCount(1)
.cpu(512)
.taskImageOptions(Map.of(
"image", ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample")))
.build();
var scalableTarget = loadBalancedFargateService.service.autoScaleTaskCount(Map.of(
"minCapacity", 1,
"maxCapacity", 20));
scalableTarget.scaleOnCpuUtilization("CpuScaling", Map.of(
"targetUtilizationPercent", 50));
scalableTarget.scaleOnMemoryUtilization("MemoryScaling", Map.of(
"targetUtilizationPercent", 50));
Set deployment configuration on QueueProcessingService
// Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
var queueProcessingFargateService = QueueProcessingFargateService.Builder.create(stack, "Service")
.cluster(cluster)
.memoryLimitMiB(512)
.image(ecs.ContainerImage.fromRegistry("test"))
.command(asList("-c", "4", "amazon.com"))
.enableLogging(false)
.desiredTaskCount(2)
.environment(Map.of())
.queue(queue)
.maxScalingCapacity(5)
.maxHealthyPercent(200)
.minHealthPercent(66)
.build();