Interface | Description |
---|---|
AddAutoScalingGroupCapacityOptions |
The properties for adding an AutoScalingGroup.
|
AddCapacityOptions |
The properties for adding instance capacity to an AutoScalingGroup.
|
AppMeshProxyConfigurationConfigProps |
The configuration to use when setting an App Mesh proxy configuration.
|
AppMeshProxyConfigurationProps |
Interface for setting the properties of proxy configuration.
|
AsgCapacityProviderProps |
The options for creating an Auto Scaling Group Capacity Provider.
|
AssetImageProps |
The properties for building an AssetImage.
|
AssociateCloudMapServiceOptions |
The options for using a cloudmap service.
|
AuthorizationConfig |
The authorization configuration details for the Amazon EFS file system.
|
AwsLogDriverProps |
Specifies the awslogs log driver configuration options.
|
BaseLogDriverProps |
Example:
|
BaseServiceOptions |
The properties for the base Ec2Service or FargateService service.
|
BaseServiceProps |
Complete base service properties that are required to be supplied by the implementation of the BaseService class.
|
BottleRocketImageProps |
Properties for BottleRocketImage.
|
CapacityProviderStrategy |
A Capacity Provider strategy to use for the service.
|
CfnCapacityProvider.AutoScalingGroupProviderProperty |
The `AutoScalingGroupProvider` property specifies the details of the Auto Scaling group for the capacity provider.
|
CfnCapacityProvider.ManagedScalingProperty |
The `ManagedScaling` property specifies the settings for the Auto Scaling group capacity provider.
|
CfnCapacityProviderProps |
Properties for defining a `CfnCapacityProvider`.
|
CfnCluster.CapacityProviderStrategyItemProperty |
The `CapacityProviderStrategyItem` property specifies the details of the default capacity provider strategy for the cluster.
|
CfnCluster.ClusterConfigurationProperty |
The execute command configuration for the cluster.
|
CfnCluster.ClusterSettingsProperty |
The settings to use when creating a cluster.
|
CfnCluster.ExecuteCommandConfigurationProperty |
The details of the execute command configuration.
|
CfnCluster.ExecuteCommandLogConfigurationProperty |
The log configuration for the results of the execute command actions.
|
CfnCluster.ServiceConnectDefaultsProperty |
Use this parameter to set a default Service Connect namespace.
|
CfnClusterCapacityProviderAssociations.CapacityProviderStrategyProperty |
The `CapacityProviderStrategy` property specifies the details of the default capacity provider strategy for the cluster.
|
CfnClusterCapacityProviderAssociationsProps |
Properties for defining a `CfnClusterCapacityProviderAssociations`.
|
CfnClusterProps |
Properties for defining a `CfnCluster`.
|
CfnPrimaryTaskSetProps |
Properties for defining a `CfnPrimaryTaskSet`.
|
CfnService.AwsVpcConfigurationProperty |
An object representing the networking details for a task or service.
|
CfnService.CapacityProviderStrategyItemProperty |
The details of a capacity provider strategy.
|
CfnService.DeploymentAlarmsProperty |
One of the methods which provide a way for you to quickly identify when a deployment has failed, and then to optionally roll back the failure to the last working deployment.
|
CfnService.DeploymentCircuitBreakerProperty |
> The deployment circuit breaker can only be used for services using the rolling update ( `ECS` ) deployment type.
|
CfnService.DeploymentConfigurationProperty |
The `DeploymentConfiguration` property specifies optional deployment parameters that control how many tasks run during the deployment and the ordering of stopping and starting tasks.
|
CfnService.DeploymentControllerProperty |
The deployment controller to use for the service.
|
CfnService.LoadBalancerProperty |
The `LoadBalancer` property specifies details on a load balancer that is used with a service.
|
CfnService.LogConfigurationProperty |
The log configuration for the container.
|
CfnService.NetworkConfigurationProperty |
The `NetworkConfiguration` property specifies an object representing the network configuration for a task or service.
|
CfnService.PlacementConstraintProperty |
The `PlacementConstraint` property specifies an object representing a constraint on task placement in the task definition.
|
CfnService.PlacementStrategyProperty |
The `PlacementStrategy` property specifies the task placement strategy for a task or service.
|
CfnService.SecretProperty |
An object representing the secret to expose to your container.
|
CfnService.ServiceConnectClientAliasProperty |
Each alias ("endpoint") is a fully-qualified name and port number that other tasks ("clients") can use to connect to this service.
|
CfnService.ServiceConnectConfigurationProperty |
The Service Connect configuration of your Amazon ECS service.
|
CfnService.ServiceConnectServiceProperty |
The Service Connect service object configuration.
|
CfnService.ServiceRegistryProperty |
The `ServiceRegistry` property specifies details of the service registry.
|
CfnServiceProps |
Properties for defining a `CfnService`.
|
CfnTaskDefinition.AuthorizationConfigProperty |
The authorization configuration details for the Amazon EFS file system.
|
CfnTaskDefinition.ContainerDefinitionProperty |
The `ContainerDefinition` property specifies a container definition.
|
CfnTaskDefinition.ContainerDependencyProperty |
The `ContainerDependency` property specifies the dependencies defined for container startup and shutdown.
|
CfnTaskDefinition.DeviceProperty |
The `Device` property specifies an object representing a container instance host device.
|
CfnTaskDefinition.DockerVolumeConfigurationProperty |
The `DockerVolumeConfiguration` property specifies a Docker volume configuration and is used when you use Docker volumes.
|
CfnTaskDefinition.EFSVolumeConfigurationProperty |
This parameter is specified when you're using an Amazon Elastic File System file system for task storage.
|
CfnTaskDefinition.EnvironmentFileProperty |
A list of files containing the environment variables to pass to a container.
|
CfnTaskDefinition.EphemeralStorageProperty |
The amount of ephemeral storage to allocate for the task.
|
CfnTaskDefinition.FirelensConfigurationProperty |
The FireLens configuration for the container.
|
CfnTaskDefinition.HealthCheckProperty |
The `HealthCheck` property specifies an object representing a container health check.
|
CfnTaskDefinition.HostEntryProperty |
The `HostEntry` property specifies a hostname and an IP address that are added to the `/etc/hosts` file of a container through the `extraHosts` parameter of its `ContainerDefinition` resource.
|
CfnTaskDefinition.HostVolumePropertiesProperty |
The `HostVolumeProperties` property specifies details on a container instance bind mount host volume.
|
CfnTaskDefinition.InferenceAcceleratorProperty |
Details on an Elastic Inference accelerator.
|
CfnTaskDefinition.KernelCapabilitiesProperty |
The `KernelCapabilities` property specifies the Linux capabilities for the container that are added to or dropped from the default configuration that is provided by Docker.
|
CfnTaskDefinition.KeyValuePairProperty |
The `KeyValuePair` property specifies a key-value pair object.
|
CfnTaskDefinition.LinuxParametersProperty |
The `LinuxParameters` property specifies Linux-specific options that are applied to the container, such as Linux [KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities.html) .
|
CfnTaskDefinition.LogConfigurationProperty |
The `LogConfiguration` property specifies log configuration options to send to a custom log driver for the container.
|
CfnTaskDefinition.MountPointProperty |
The `MountPoint` property specifies details on a volume mount point that is used in a container definition.
|
CfnTaskDefinition.PortMappingProperty |
The `PortMapping` property specifies a port mapping.
|
CfnTaskDefinition.ProxyConfigurationProperty |
The `ProxyConfiguration` property specifies the details for the App Mesh proxy.
|
CfnTaskDefinition.RepositoryCredentialsProperty |
The `RepositoryCredentials` property specifies the repository credentials for private registry authentication.
|
CfnTaskDefinition.ResourceRequirementProperty |
The `ResourceRequirement` property specifies the type and amount of a resource to assign to a container.
|
CfnTaskDefinition.RuntimePlatformProperty |
Information about the platform for the Amazon ECS service or task.
|
CfnTaskDefinition.SecretProperty |
The `Secret` property specifies an object representing the secret to expose to your container.
|
CfnTaskDefinition.SystemControlProperty |
A list of namespaced kernel parameters to set in the container.
|
CfnTaskDefinition.TaskDefinitionPlacementConstraintProperty |
The `TaskDefinitionPlacementConstraint` property specifies an object representing a constraint on task placement in the task definition.
|
CfnTaskDefinition.TmpfsProperty |
The `Tmpfs` property specifies the container path, mount options, and size of the tmpfs mount.
|
CfnTaskDefinition.UlimitProperty |
The `Ulimit` property specifies the `ulimit` settings to pass to the container.
|
CfnTaskDefinition.VolumeFromProperty |
The `VolumeFrom` property specifies details on a data volume from another container in the same task definition.
|
CfnTaskDefinition.VolumeProperty |
The `Volume` property specifies a data volume used in a task definition.
|
CfnTaskDefinitionProps |
Properties for defining a `CfnTaskDefinition`.
|
CfnTaskSet.AwsVpcConfigurationProperty |
The networking details for a task.
|
CfnTaskSet.LoadBalancerProperty |
Details on the load balancer or load balancers to use with a task set.
|
CfnTaskSet.NetworkConfigurationProperty |
The network configuration for a task.
|
CfnTaskSet.ScaleProperty |
A floating-point percentage of the desired number of tasks to place and keep running in the task set.
|
CfnTaskSet.ServiceRegistryProperty |
The details for the service registry.
|
CfnTaskSetProps |
Properties for defining a `CfnTaskSet`.
|
CloudMapNamespaceOptions |
The options for creating an AWS Cloud Map namespace.
|
CloudMapOptions |
The options to enabling AWS Cloud Map for an Amazon ECS service.
|
ClusterAttributes |
The properties to import from the ECS cluster.
|
ClusterProps |
The properties used to define an ECS cluster.
|
CommonTaskDefinitionAttributes |
The common task definition attributes used across all types of task definitions.
|
CommonTaskDefinitionProps |
The common properties for all task definitions.
|
ContainerDefinitionOptions |
Example:
|
ContainerDefinitionProps |
The properties in a container definition.
|
ContainerDependency |
The details of a dependency on another container in the task definition.
|
ContainerImageConfig |
The configuration for creating a container image.
|
CpuUtilizationScalingProps |
The properties for enabling scaling based on CPU utilization.
|
DeploymentCircuitBreaker |
The deployment circuit breaker to use for the service.
|
DeploymentController |
The deployment controller to use for the service.
|
Device |
A container instance host device.
|
DockerVolumeConfiguration |
The configuration for a Docker volume.
|
Ec2ServiceAttributes |
The properties to import from the service using the EC2 launch type.
|
Ec2ServiceProps |
The properties for defining a service using the EC2 launch type.
|
Ec2TaskDefinitionAttributes |
Attributes used to import an existing EC2 task definition.
|
Ec2TaskDefinitionProps |
The properties for a task definition run on an EC2 cluster.
|
EcsOptimizedAmiProps | Deprecated |
EcsOptimizedImageOptions |
Additional configuration properties for EcsOptimizedImage factory functions.
|
EcsTarget |
Example:
|
EfsVolumeConfiguration |
The configuration for an Elastic FileSystem volume.
|
EnvironmentFileConfig |
Configuration for the environment file.
|
ExecuteCommandConfiguration |
The details of the execute command configuration.
|
ExecuteCommandLogConfiguration |
The log configuration for the results of the execute command actions.
|
ExternalServiceAttributes |
The properties to import from the service using the External launch type.
|
ExternalServiceProps |
The properties for defining a service using the External launch type.
|
ExternalTaskDefinitionAttributes |
Attributes used to import an existing External task definition.
|
ExternalTaskDefinitionProps |
The properties for a task definition run on an External cluster.
|
FargateServiceAttributes |
The properties to import from the service using the Fargate launch type.
|
FargateServiceProps |
The properties for defining a service using the Fargate launch type.
|
FargateTaskDefinitionAttributes |
Attributes used to import an existing Fargate task definition.
|
FargateTaskDefinitionProps |
The properties for a task definition.
|
FirelensConfig |
Firelens Configuration https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_firelens.html#firelens-taskdef.
|
FireLensLogDriverProps |
Specifies the firelens log driver configuration options.
|
FirelensLogRouterDefinitionOptions |
The options for creating a firelens log router.
|
FirelensLogRouterProps |
The properties in a firelens log router.
|
FirelensOptions |
The options for firelens log router https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_firelens.html#firelens-taskdef-customconfig.
|
FluentdLogDriverProps |
Specifies the fluentd log driver configuration options.
|
GelfLogDriverProps |
Specifies the journald log driver configuration options.
|
GenericLogDriverProps |
The configuration to use when creating a log driver.
|
HealthCheck |
The health check command and associated configuration parameters for the container.
|
Host |
The details on a container instance bind mount host volume.
|
IBaseService |
The interface for BaseService.
|
IBaseService.Jsii$Default |
Internal default implementation for
IBaseService . |
ICluster |
A regional grouping of one or more container instances on which you can run tasks and services.
|
ICluster.Jsii$Default |
Internal default implementation for
ICluster . |
IEc2Service |
The interface for a service using the EC2 launch type on an ECS cluster.
|
IEc2Service.Jsii$Default |
Internal default implementation for
IEc2Service . |
IEc2TaskDefinition |
The interface of a task definition run on an EC2 cluster.
|
IEc2TaskDefinition.Jsii$Default |
Internal default implementation for
IEc2TaskDefinition . |
IEcsLoadBalancerTarget |
Interface for ECS load balancer target.
|
IEcsLoadBalancerTarget.Jsii$Default |
Internal default implementation for
IEcsLoadBalancerTarget . |
IExternalService |
The interface for a service using the External launch type on an ECS cluster.
|
IExternalService.Jsii$Default |
Internal default implementation for
IExternalService . |
IExternalTaskDefinition |
The interface of a task definition run on an External cluster.
|
IExternalTaskDefinition.Jsii$Default |
Internal default implementation for
IExternalTaskDefinition . |
IFargateService |
The interface for a service using the Fargate launch type on an ECS cluster.
|
IFargateService.Jsii$Default |
Internal default implementation for
IFargateService . |
IFargateTaskDefinition |
The interface of a task definition run on a Fargate cluster.
|
IFargateTaskDefinition.Jsii$Default |
Internal default implementation for
IFargateTaskDefinition . |
InferenceAccelerator |
Elastic Inference Accelerator.
|
IService |
The interface for a service.
|
IService.Jsii$Default |
Internal default implementation for
IService . |
ITaskDefinition |
The interface for all task definitions.
|
ITaskDefinition.Jsii$Default |
Internal default implementation for
ITaskDefinition . |
ITaskDefinitionExtension |
An extension for Task Definitions.
|
ITaskDefinitionExtension.Jsii$Default |
Internal default implementation for
ITaskDefinitionExtension . |
JournaldLogDriverProps |
Specifies the journald log driver configuration options.
|
JsonFileLogDriverProps |
Specifies the json-file log driver configuration options.
|
LinuxParametersProps |
The properties for defining Linux-specific options that are applied to the container.
|
LoadBalancerTargetOptions |
Properties for defining an ECS target.
|
LogDriverConfig |
The configuration to use when creating a log driver.
|
MemoryUtilizationScalingProps |
The properties for enabling scaling based on memory utilization.
|
MountPoint |
The details of data volume mount points for a container.
|
PortMapping |
Port mappings allow containers to access ports on the host container instance to send or receive traffic.
|
RepositoryImageProps |
The properties for an image hosted in a public or private repository.
|
RequestCountScalingProps |
The properties for enabling scaling based on Application Load Balancer (ALB) request counts.
|
RuntimePlatform |
The interface for Runtime Platform.
|
ScalableTaskCountProps |
The properties of a scalable attribute representing task count.
|
ScratchSpace |
The temporary disk space mounted to the container.
|
SecretVersionInfo |
Specify the secret's version id or version stage.
|
SplunkLogDriverProps |
Specifies the splunk log driver configuration options.
|
SyslogLogDriverProps |
Specifies the syslog log driver configuration options.
|
SystemControl |
Kernel parameters to set in the container.
|
TaskDefinitionAttributes |
A reference to an existing task definition.
|
TaskDefinitionProps |
The properties for task definitions.
|
Tmpfs |
The details of a tmpfs mount for a container.
|
TrackCustomMetricProps |
The properties for enabling target tracking scaling based on a custom CloudWatch metric.
|
Ulimit |
The ulimit settings to pass to the container.
|
Volume |
A data volume used in a task definition.
|
VolumeFrom |
The details on a data volume from another container in the same task definition.
|
Enum | Description |
---|---|
AmiHardwareType |
The ECS-optimized AMI variant to use.
|
AwsLogDriverMode |
awslogs provides two modes for delivering messages from the container to the log driver.
|
BinPackResource |
Instance resource used for bin packing.
|
BottlerocketEcsVariant |
Amazon ECS variant.
|
Capability |
A Linux capability.
|
Compatibility |
The task launch type compatibility requirement.
|
ContainerDependencyCondition | |
DeploymentControllerType |
The deployment controller type to use for the service.
|
DevicePermission |
Permissions for device access.
|
EnvironmentFileType |
Type of environment file to be included in the container definition.
|
ExecuteCommandLogging |
The log settings to use to for logging the execute command session.
|
FargatePlatformVersion |
The platform version on which to run your service.
|
FirelensConfigFileType |
Firelens configuration file type, s3 or file path.
|
FirelensLogRouterType |
Firelens log router type, fluentbit or fluentd.
|
GelfCompressionType |
The type of compression the GELF driver uses to compress each log message.
|
IpcMode |
The IPC resource namespace to use for the containers in the task.
|
LaunchType |
The launch type of an ECS service.
|
MachineImageType |
The machine image type.
|
NetworkMode |
The networking mode to use for the containers in the task.
|
PidMode |
The process namespace to use for the containers in the task.
|
PropagatedTagSource |
Propagate tags from either service or task definition.
|
Protocol |
Network protocol.
|
Scope |
The scope for the Docker volume that determines its lifecycle.
|
SplunkLogFormat |
Log Message Format.
|
TmpfsMountOption |
The supported options for a tmpfs mount for a container.
|
UlimitName |
Type of resource to set a limit on.
|
WindowsOptimizedVersion |
ECS-optimized Windows version list.
|
---
This package contains constructs for working with Amazon Elastic Container Service (Amazon ECS).
Amazon Elastic Container Service (Amazon ECS) is a fully managed container orchestration service.
For further information on Amazon ECS, see the Amazon ECS documentation
The following example creates an Amazon ECS cluster, adds capacity to it, and runs a service on it:
Vpc vpc; // Create an ECS cluster Cluster cluster = Cluster.Builder.create(this, "Cluster") .vpc(vpc) .build(); // Add capacity to it cluster.addCapacity("DefaultAutoScalingGroupCapacity", AddCapacityOptions.builder() .instanceType(new InstanceType("t2.xlarge")) .desiredCapacity(3) .build()); Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("DefaultContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .memoryLimitMiB(512) .build()); // Instantiate an Amazon ECS Service Ec2Service ecsService = Ec2Service.Builder.create(this, "Service") .cluster(cluster) .taskDefinition(taskDefinition) .build();
For a set of constructs defining common ECS architectural patterns, see the @aws-cdk/aws-ecs-patterns
package.
There are two sets of constructs in this library; one to run tasks on Amazon EC2 and one to run tasks on AWS Fargate.
Ec2TaskDefinition
and Ec2Service
constructs to run tasks on Amazon EC2 instances running in your account.FargateTaskDefinition
and FargateService
constructs to run tasks on
instances that are managed for you by AWS.ExternalTaskDefinition
and ExternalService
constructs to run AWS ECS Anywhere tasks on self-managed infrastructure.Here are the main differences:
For more information on Amazon EC2 vs AWS Fargate, networking and ECS Anywhere see the AWS Documentation: AWS Fargate, Task Networking, ECS Anywhere
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:
Vpc vpc; Cluster cluster = Cluster.Builder.create(this, "Cluster") .vpc(vpc) .build();
The following code imports an existing cluster using the ARN which can be used to import an Amazon ECS service either EC2 or Fargate.
String clusterArn = "arn:aws:ecs:us-east-1:012345678910:cluster/clusterName"; ICluster cluster = Cluster.fromClusterArn(this, "Cluster", clusterArn);
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:
Vpc vpc; Cluster cluster = Cluster.Builder.create(this, "Cluster") .vpc(vpc) .build(); // Either add default capacity cluster.addCapacity("DefaultAutoScalingGroupCapacity", AddCapacityOptions.builder() .instanceType(new InstanceType("t2.xlarge")) .desiredCapacity(3) .build()); // Or add customized capacity. Be sure to start the Amazon ECS-optimized AMI. AutoScalingGroup autoScalingGroup = AutoScalingGroup.Builder.create(this, "ASG") .vpc(vpc) .instanceType(new InstanceType("t2.xlarge")) .machineImage(EcsOptimizedImage.amazonLinux()) // Or use Amazon ECS-Optimized Amazon Linux 2 AMI // machineImage: EcsOptimizedImage.amazonLinux2(), .desiredCapacity(3) .build(); AsgCapacityProvider capacityProvider = AsgCapacityProvider.Builder.create(this, "AsgCapacityProvider") .autoScalingGroup(autoScalingGroup) .build(); cluster.addAsgCapacityProvider(capacityProvider);
If you omit the property vpc
, the construct will create a new VPC with two AZs.
By default, all machine images will auto-update to the latest version on each deployment, causing a replacement of the instances in your AutoScalingGroup if the AMI has been updated since the last deployment.
If task draining is enabled, ECS will transparently reschedule tasks on to the new
instances before terminating your old instances. If you have disabled task draining,
the tasks will be terminated along with the instance. To prevent that, you
can pick a non-updating AMI by passing cacheInContext: true
, but be sure
to periodically update to the latest AMI manually by using the CDK CLI
context management commands:
Vpc vpc; AutoScalingGroup autoScalingGroup = AutoScalingGroup.Builder.create(this, "ASG") .machineImage(EcsOptimizedImage.amazonLinux(EcsOptimizedImageOptions.builder().cachedInContext(true).build())) .vpc(vpc) .instanceType(new InstanceType("t2.micro")) .build();
Bottlerocket is a Linux-based open source operating system that is purpose-built by AWS for running containers. You can launch Amazon ECS container instances with the Bottlerocket AMI.
The following example will create a capacity with self-managed Amazon EC2 capacity of 2 c5.large
Linux instances running with Bottlerocket
AMI.
The following example adds Bottlerocket capacity to the cluster:
Cluster cluster; cluster.addCapacity("bottlerocket-asg", AddCapacityOptions.builder() .minCapacity(2) .instanceType(new InstanceType("c5.large")) .machineImage(new BottleRocketImage()) .build());
To launch instances with ARM64 hardware, you can use the Amazon ECS-optimized Amazon Linux 2 (arm64) AMI. Based on Amazon Linux 2, this AMI is recommended for use when launching your EC2 instances that are powered by Arm-based AWS Graviton Processors.
Cluster cluster; cluster.addCapacity("graviton-cluster", AddCapacityOptions.builder() .minCapacity(2) .instanceType(new InstanceType("c6g.large")) .machineImage(EcsOptimizedImage.amazonLinux2(AmiHardwareType.ARM)) .build());
Bottlerocket is also supported:
Cluster cluster; cluster.addCapacity("graviton-cluster", AddCapacityOptions.builder() .minCapacity(2) .instanceType(new InstanceType("c6g.large")) .machineImageType(MachineImageType.BOTTLEROCKET) .build());
To add spot instances into the cluster, you must specify the spotPrice
in the ecs.AddCapacityOptions
and optionally enable the spotInstanceDraining
property.
Cluster cluster; // Add an AutoScalingGroup with spot instances to the existing cluster cluster.addCapacity("AsgSpot", AddCapacityOptions.builder() .maxCapacity(2) .minCapacity(2) .desiredCapacity(2) .instanceType(new InstanceType("c5.xlarge")) .spotPrice("0.0735") // Enable the Automated Spot Draining support for Amazon ECS .spotInstanceDraining(true) .build());
When the ecs.AddCapacityOptions
that you provide has a non-zero taskDrainTime
(the default) then an SNS topic and Lambda are created to ensure that the
cluster's instances have been properly drained of tasks before terminating. The SNS Topic is sent the instance-terminating lifecycle event from the AutoScalingGroup,
and the Lambda acts on that event. If you wish to engage server-side encryption for this SNS Topic
then you may do so by providing a KMS key for the topicEncryptionKey
property of ecs.AddCapacityOptions
.
// Given Cluster cluster; Key key; // Then, use that key to encrypt the lifecycle-event SNS Topic. cluster.addCapacity("ASGEncryptedSNS", AddCapacityOptions.builder() .instanceType(new InstanceType("t2.xlarge")) .desiredCapacity(3) .topicEncryptionKey(key) .build());
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
. For AWS ECS Anywhere use the ExternalTaskDefinition
. These classes
provide simplified APIs that only contain properties relevant for each specific launch type.
For a FargateTaskDefinition
, specify the task size (memoryLimitMiB
and cpu
):
FargateTaskDefinition fargateTaskDefinition = FargateTaskDefinition.Builder.create(this, "TaskDef") .memoryLimitMiB(512) .cpu(256) .build();
On Fargate Platform Version 1.4.0 or later, you may specify up to 200GiB of ephemeral storage:
FargateTaskDefinition fargateTaskDefinition = FargateTaskDefinition.Builder.create(this, "TaskDef") .memoryLimitMiB(512) .cpu(256) .ephemeralStorageGiB(100) .build();
To add containers to a task definition, call addContainer()
:
FargateTaskDefinition fargateTaskDefinition = FargateTaskDefinition.Builder.create(this, "TaskDef") .memoryLimitMiB(512) .cpu(256) .build(); ContainerDefinition container = fargateTaskDefinition.addContainer("WebContainer", ContainerDefinitionOptions.builder() // Use an image from DockerHub .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .build());
For a Ec2TaskDefinition
:
Ec2TaskDefinition ec2TaskDefinition = Ec2TaskDefinition.Builder.create(this, "TaskDef") .networkMode(NetworkMode.BRIDGE) .build(); ContainerDefinition container = ec2TaskDefinition.addContainer("WebContainer", ContainerDefinitionOptions.builder() // Use an image from DockerHub .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .memoryLimitMiB(1024) .build());
For an ExternalTaskDefinition
:
ExternalTaskDefinition externalTaskDefinition = new ExternalTaskDefinition(this, "TaskDef"); ContainerDefinition container = externalTaskDefinition.addContainer("WebContainer", ContainerDefinitionOptions.builder() // Use an image from DockerHub .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .memoryLimitMiB(1024) .build());
You can specify container properties when you add them to the task definition, or with various methods, e.g.:
To add a port mapping when adding a container to the task definition, specify the portMappings
option:
TaskDefinition taskDefinition; taskDefinition.addContainer("WebContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .memoryLimitMiB(1024) .portMappings(List.of(PortMapping.builder().containerPort(3000).build())) .build());
To add port mappings directly to a container definition, call addPortMappings()
:
ContainerDefinition container; container.addPortMappings(PortMapping.builder() .containerPort(3000) .build());
To add data volumes to a task definition, call addVolume()
:
FargateTaskDefinition fargateTaskDefinition = FargateTaskDefinition.Builder.create(this, "TaskDef") .memoryLimitMiB(512) .cpu(256) .build(); Map<String, Object> volume = Map.of( // Use an Elastic FileSystem "name", "mydatavolume", "efsVolumeConfiguration", Map.of( "fileSystemId", "EFS")); void container = fargateTaskDefinition.addVolume(volume);
Note: ECS Anywhere doesn't support volume attachments in the task definition.
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:
TaskDefinition taskDefinition = TaskDefinition.Builder.create(this, "TaskDef") .memoryMiB("512") .cpu("256") .networkMode(NetworkMode.AWS_VPC) .compatibility(Compatibility.EC2_AND_FARGATE) .build();
Images supply the software that runs inside the container. Images can be obtained from either DockerHub or from ECR repositories, built directly from a local Dockerfile, or use an existing tarball.
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, tagOrDigest)
: use the given ECR repository as the image
to start. If no tag or digest 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.ecs.ContainerImage.fromTarball(file)
: use an existing tarball.new ecs.TagParameterContainerImage(repository)
: use the given ECR repository as the image
but a CloudFormation parameter as the tag.
To pass environment variables to the container, you can use the environment
, environmentFiles
, and secrets
props.
Secret secret; Secret dbSecret; StringParameter parameter; TaskDefinition taskDefinition; Bucket s3Bucket; ContainerDefinition newContainer = taskDefinition.addContainer("container", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .memoryLimitMiB(1024) .environment(Map.of( // clear text, not for sensitive data "STAGE", "prod")) .environmentFiles(List.of(EnvironmentFile.fromAsset("./demo-env-file.env"), EnvironmentFile.fromBucket(s3Bucket, "assets/demo-env-file.env"))) .secrets(Map.of( // Retrieved from AWS Secrets Manager or AWS Systems Manager Parameter Store at container start-up. "SECRET", Secret.fromSecretsManager(secret), "DB_PASSWORD", Secret.fromSecretsManager(dbSecret, "password"), // Reference a specific JSON field, (requires platform version 1.4.0 or later for Fargate tasks) "API_KEY", Secret.fromSecretsManagerVersion(secret, SecretVersionInfo.builder().versionId("12345").build(), "apiKey"), // Reference a specific version of the secret by its version id or version stage (requires platform version 1.4.0 or later for Fargate tasks) "PARAMETER", Secret.fromSsmParameter(parameter))) .build()); newContainer.addEnvironment("QUEUE_NAME", "MyQueue");
The task execution role is automatically granted read permissions on the secrets/parameters. Support for environment files is restricted to the EC2 launch type for files hosted on S3. Further details provided in the AWS documentation about specifying environment variables.
To set system controls (kernel parameters) on the container, use the systemControls
prop:
TaskDefinition taskDefinition; taskDefinition.addContainer("container", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .memoryLimitMiB(1024) .systemControls(List.of(SystemControl.builder() .namespace("net") .value("ipv4.tcp_tw_recycle") .build())) .build());
AWS Fargate supports Amazon ECS Windows containers. For more details, please see this blog post
// Create a Task Definition for the Windows container to start FargateTaskDefinition taskDefinition = FargateTaskDefinition.Builder.create(this, "TaskDef") .runtimePlatform(RuntimePlatform.builder() .operatingSystemFamily(OperatingSystemFamily.WINDOWS_SERVER_2019_CORE) .cpuArchitecture(CpuArchitecture.X86_64) .build()) .cpu(1024) .memoryLimitMiB(2048) .build(); taskDefinition.addContainer("windowsservercore", ContainerDefinitionOptions.builder() .logging(LogDriver.awsLogs(AwsLogDriverProps.builder().streamPrefix("win-iis-on-fargate").build())) .portMappings(List.of(PortMapping.builder().containerPort(80).build())) .image(ContainerImage.fromRegistry("mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019")) .build());
AWS Graviton2 supports AWS Fargate. For more details, please see this blog post
// Create a Task Definition for running container on Graviton Runtime. FargateTaskDefinition taskDefinition = FargateTaskDefinition.Builder.create(this, "TaskDef") .runtimePlatform(RuntimePlatform.builder() .operatingSystemFamily(OperatingSystemFamily.LINUX) .cpuArchitecture(CpuArchitecture.ARM64) .build()) .cpu(1024) .memoryLimitMiB(2048) .build(); taskDefinition.addContainer("webarm64", ContainerDefinitionOptions.builder() .logging(LogDriver.awsLogs(AwsLogDriverProps.builder().streamPrefix("graviton2-on-fargate").build())) .portMappings(List.of(PortMapping.builder().containerPort(80).build())) .image(ContainerImage.fromRegistry("public.ecr.aws/nginx/nginx:latest-arm64v8")) .build());
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.
Cluster cluster; TaskDefinition taskDefinition; FargateService service = FargateService.Builder.create(this, "Service") .cluster(cluster) .taskDefinition(taskDefinition) .desiredCount(5) .build();
ECS Anywhere service definition looks like:
Cluster cluster; TaskDefinition taskDefinition; ExternalService service = ExternalService.Builder.create(this, "Service") .cluster(cluster) .taskDefinition(taskDefinition) .desiredCount(5) .build();
Services
by default will create a security group if not provided.
If you'd like to specify which security groups to use you can override the securityGroups
property.
Amazon ECS deployment circuit breaker
automatically rolls back unhealthy service deployments without the need for manual intervention. Use circuitBreaker
to enable
deployment circuit breaker and optionally enable rollback
for automatic rollback. See Using the deployment circuit breaker
for more details.
Cluster cluster; TaskDefinition taskDefinition; FargateService service = FargateService.Builder.create(this, "Service") .cluster(cluster) .taskDefinition(taskDefinition) .circuitBreaker(DeploymentCircuitBreaker.builder().rollback(true).build()) .build();
Note: ECS Anywhere doesn't support deployment circuit breakers and rollback.
Services
are load balancing targets and can be added to a target group, which will be attached to an application/network load balancers:
Vpc vpc; Cluster cluster; TaskDefinition taskDefinition; FargateService service = FargateService.Builder.create(this, "Service").cluster(cluster).taskDefinition(taskDefinition).build(); ApplicationLoadBalancer lb = ApplicationLoadBalancer.Builder.create(this, "LB").vpc(vpc).internetFacing(true).build(); ApplicationListener listener = lb.addListener("Listener", BaseApplicationListenerProps.builder().port(80).build()); ApplicationTargetGroup targetGroup1 = listener.addTargets("ECS1", AddApplicationTargetsProps.builder() .port(80) .targets(List.of(service)) .build()); ApplicationTargetGroup targetGroup2 = listener.addTargets("ECS2", AddApplicationTargetsProps.builder() .port(80) .targets(List.of(service.loadBalancerTarget(LoadBalancerTargetOptions.builder() .containerName("MyContainer") .containerPort(8080) .build()))) .build());
Note: ECS Anywhere doesn't support application/network load balancers.
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.
Cluster cluster; TaskDefinition taskDefinition; Vpc vpc; FargateService service = FargateService.Builder.create(this, "Service").cluster(cluster).taskDefinition(taskDefinition).build(); ApplicationLoadBalancer lb = ApplicationLoadBalancer.Builder.create(this, "LB").vpc(vpc).internetFacing(true).build(); ApplicationListener listener = lb.addListener("Listener", BaseApplicationListenerProps.builder().port(80).build()); service.registerLoadBalancerTargets(EcsTarget.builder() .containerName("web") .containerPort(80) .newTargetGroupId("ECS") .listener(ListenerConfig.applicationListener(listener, AddApplicationTargetsProps.builder() .protocol(ApplicationProtocol.HTTPS) .build())) .build());
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.
Services
can also be directly attached to a classic load balancer as targets:
Cluster cluster; TaskDefinition taskDefinition; Vpc vpc; Ec2Service service = Ec2Service.Builder.create(this, "Service").cluster(cluster).taskDefinition(taskDefinition).build(); LoadBalancer lb = LoadBalancer.Builder.create(this, "LB").vpc(vpc).build(); lb.addListener(LoadBalancerListener.builder().externalPort(80).build()); lb.addTarget(service);
Similarly, if you want to have more control over load balancer targeting:
Cluster cluster; TaskDefinition taskDefinition; Vpc vpc; Ec2Service service = Ec2Service.Builder.create(this, "Service").cluster(cluster).taskDefinition(taskDefinition).build(); LoadBalancer lb = LoadBalancer.Builder.create(this, "LB").vpc(vpc).build(); lb.addListener(LoadBalancerListener.builder().externalPort(80).build()); lb.addTarget(service.loadBalancerTarget(LoadBalancerTargetOptions.builder() .containerName("MyContainer") .containerPort(80) .build()));
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
You can configure the task count of a service to match demand. Task auto-scaling is
configured by calling autoScaleTaskCount()
:
ApplicationTargetGroup target; BaseService service; ScalableTaskCount scaling = service.autoScaleTaskCount(EnableScalingProps.builder().maxCapacity(10).build()); scaling.scaleOnCpuUtilization("CpuScaling", CpuUtilizationScalingProps.builder() .targetUtilizationPercent(50) .build()); scaling.scaleOnRequestCount("RequestScaling", RequestCountScalingProps.builder() .requestsPerTarget(10000) .targetGroup(target) .build());
Task auto-scaling is powered by Application Auto-Scaling. See that section for details.
To start an Amazon ECS task on an Amazon EC2-backed Cluster, instantiate an
@aws-cdk/aws-events-targets.EcsTask
instead of an Ec2Service
:
Cluster cluster; // Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromAsset(resolve(__dirname, "..", "eventhandler-image"))) .memoryLimitMiB(256) .logging(AwsLogDriver.Builder.create().streamPrefix("EventDemo").mode(AwsLogDriverMode.NON_BLOCKING).build()) .build()); // An Rule that describes the event trigger (in this case a scheduled run) Rule rule = Rule.Builder.create(this, "Rule") .schedule(Schedule.expression("rate(1 min)")) .build(); // Pass an environment variable to the container 'TheContainer' in the task rule.addTarget(EcsTask.Builder.create() .cluster(cluster) .taskDefinition(taskDefinition) .taskCount(1) .containerOverrides(List.of(ContainerOverride.builder() .containerName("TheContainer") .environment(List.of(TaskEnvironmentVariable.builder() .name("I_WAS_TRIGGERED") .value("From CloudWatch Events") .build())) .build())) .build());
Currently Supported Log Drivers:
// Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(LogDrivers.awsLogs(AwsLogDriverProps.builder().streamPrefix("EventDemo").build())) .build());
// Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(LogDrivers.fluentd()) .build());
// Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(LogDrivers.gelf(GelfLogDriverProps.builder().address("my-gelf-address").build())) .build());
// Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(LogDrivers.journald()) .build());
// Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(LogDrivers.jsonFile()) .build());
// Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(LogDrivers.splunk(SplunkLogDriverProps.builder() .token(SecretValue.secretsManager("my-splunk-token")) .url("my-splunk-url") .build())) .build());
// Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(LogDrivers.syslog()) .build());
// Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(LogDrivers.firelens(FireLensLogDriverProps.builder() .options(Map.of( "Name", "firehose", "region", "us-west-2", "delivery_stream", "my-stream")) .build())) .build());
To pass secrets to the log configuration, use the secretOptions
property of the log configuration. The task execution role is automatically granted read permissions on the secrets/parameters.
Secret secret; StringParameter parameter; Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(LogDrivers.firelens(FireLensLogDriverProps.builder() .options(Map.of()) .secretOptions(Map.of( // Retrieved from AWS Secrets Manager or AWS Systems Manager Parameter Store "apikey", Secret.fromSecretsManager(secret), "host", Secret.fromSsmParameter(parameter))) .build())) .build());
A generic log driver object exists to provide a lower level abstraction of the log driver configuration.
// Create a Task Definition for the container to start Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("TheContainer", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("example-image")) .memoryLimitMiB(256) .logging(GenericLogDriver.Builder.create() .logDriver("fluentd") .options(Map.of( "tag", "example-tag")) .build()) .build());
To register your ECS service with a CloudMap Service Registry, you may add the
cloudMapOptions
property to your service:
TaskDefinition taskDefinition; Cluster cluster; Ec2Service service = Ec2Service.Builder.create(this, "Service") .cluster(cluster) .taskDefinition(taskDefinition) .cloudMapOptions(CloudMapOptions.builder() // Create A records - useful for AWSVPC network mode. .dnsRecordType(DnsRecordType.A) .build()) .build();
With bridge
or host
network modes, only SRV
DNS record types are supported.
By default, SRV
DNS record types will target the default container and default
port. However, you may target a different container and port on the same ECS task:
TaskDefinition taskDefinition; Cluster cluster; // Add a container to the task definition ContainerDefinition specificContainer = taskDefinition.addContainer("Container", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("/aws/aws-example-app")) .memoryLimitMiB(2048) .build()); // Add a port mapping specificContainer.addPortMappings(PortMapping.builder() .containerPort(7600) .protocol(Protocol.TCP) .build()); Ec2Service.Builder.create(this, "Service") .cluster(cluster) .taskDefinition(taskDefinition) .cloudMapOptions(CloudMapOptions.builder() // Create SRV records - useful for bridge networking .dnsRecordType(DnsRecordType.SRV) // Targets port TCP port 7600 `specificContainer` .container(specificContainer) .containerPort(7600) .build()) .build();
You may associate an ECS service with a specific CloudMap service. To do
this, use the service's associateCloudMapService
method:
Service cloudMapService; FargateService ecsService; ecsService.associateCloudMapService(AssociateCloudMapServiceOptions.builder() .service(cloudMapService) .build());
There are two major families of Capacity Providers: AWS Fargate (including Fargate Spot) and EC2 Auto Scaling Group Capacity Providers. Both are supported.
To enable Fargate capacity providers, you can either set
enableFargateCapacityProviders
to true
when creating your cluster, or by
invoking the enableFargateCapacityProviders()
method after creating your
cluster. This will add both FARGATE
and FARGATE_SPOT
as available capacity
providers on your cluster.
Vpc vpc; Cluster cluster = Cluster.Builder.create(this, "FargateCPCluster") .vpc(vpc) .enableFargateCapacityProviders(true) .build(); FargateTaskDefinition taskDefinition = new FargateTaskDefinition(this, "TaskDef"); taskDefinition.addContainer("web", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .build()); FargateService.Builder.create(this, "FargateService") .cluster(cluster) .taskDefinition(taskDefinition) .capacityProviderStrategies(List.of(CapacityProviderStrategy.builder() .capacityProvider("FARGATE_SPOT") .weight(2) .build(), CapacityProviderStrategy.builder() .capacityProvider("FARGATE") .weight(1) .build())) .build();
To add an Auto Scaling Group Capacity Provider, first create an EC2 Auto Scaling
Group. Then, create an AsgCapacityProvider
and pass the Auto Scaling Group to
it in the constructor. Then add the Capacity Provider to the cluster. Finally,
you can refer to the Provider by its name in your service's or task's Capacity
Provider strategy.
By default, an Auto Scaling Group Capacity Provider will manage the Auto Scaling
Group's size for you. It will also enable managed termination protection, in
order to prevent EC2 Auto Scaling from terminating EC2 instances that have tasks
running on them. If you want to disable this behavior, set both
enableManagedScaling
to and enableManagedTerminationProtection
to false
.
Vpc vpc; Cluster cluster = Cluster.Builder.create(this, "Cluster") .vpc(vpc) .build(); AutoScalingGroup autoScalingGroup = AutoScalingGroup.Builder.create(this, "ASG") .vpc(vpc) .instanceType(new InstanceType("t2.micro")) .machineImage(EcsOptimizedImage.amazonLinux2()) .minCapacity(0) .maxCapacity(100) .build(); AsgCapacityProvider capacityProvider = AsgCapacityProvider.Builder.create(this, "AsgCapacityProvider") .autoScalingGroup(autoScalingGroup) .build(); cluster.addAsgCapacityProvider(capacityProvider); Ec2TaskDefinition taskDefinition = new Ec2TaskDefinition(this, "TaskDef"); taskDefinition.addContainer("web", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .memoryReservationMiB(256) .build()); Ec2Service.Builder.create(this, "EC2Service") .cluster(cluster) .taskDefinition(taskDefinition) .capacityProviderStrategies(List.of(CapacityProviderStrategy.builder() .capacityProvider(capacityProvider.getCapacityProviderName()) .weight(1) .build())) .build();
Currently, this feature is only supported for services with EC2 launch types.
To add elastic inference accelerators to your EC2 instance, first add
inferenceAccelerators
field to the Ec2TaskDefinition and set the deviceName
and deviceType
properties.
Map<String, String>[] inferenceAccelerators = List.of(Map.of( "deviceName", "device1", "deviceType", "eia2.medium")); Ec2TaskDefinition taskDefinition = Ec2TaskDefinition.Builder.create(this, "Ec2TaskDef") .inferenceAccelerators(inferenceAccelerators) .build();
To enable using the inference accelerators in the containers, add inferenceAcceleratorResources
field and set it to a list of device names used for the inference accelerators. Each value in the
list should match a DeviceName
for an InferenceAccelerator
specified in the task definition.
TaskDefinition taskDefinition; String[] inferenceAcceleratorResources = List.of("device1"); taskDefinition.addContainer("cont", ContainerDefinitionOptions.builder() .image(ContainerImage.fromRegistry("test")) .memoryLimitMiB(1024) .inferenceAcceleratorResources(inferenceAcceleratorResources) .build());
Please note, ECS Exec leverages AWS Systems Manager (SSM). So as a prerequisite for the exec command to work, you need to have the SSM plugin for the AWS CLI installed locally. For more information, see Install Session Manager plugin for AWS CLI.
To enable the ECS Exec feature for your containers, set the boolean flag enableExecuteCommand
to true
in
your Ec2Service
or FargateService
.
Cluster cluster; TaskDefinition taskDefinition; Ec2Service service = Ec2Service.Builder.create(this, "Service") .cluster(cluster) .taskDefinition(taskDefinition) .enableExecuteCommand(true) .build();
You can enable sending logs of your execute session commands to a CloudWatch log group or S3 bucket by configuring
the executeCommandConfiguration
property for your cluster. The default configuration will send the
logs to the CloudWatch Logs using the awslogs
log driver that is configured in your task definition. Please note,
when using your own logConfiguration
the log group or S3 Bucket specified must already be created.
To encrypt data using your own KMS Customer Key (CMK), you must create a CMK and provide the key in the kmsKey
field
of the executeCommandConfiguration
. To use this key for encrypting CloudWatch log data or S3 bucket, make sure to associate the key
to these resources on creation.
Vpc vpc; Key kmsKey = new Key(this, "KmsKey"); // Pass the KMS key in the `encryptionKey` field to associate the key to the log group LogGroup logGroup = LogGroup.Builder.create(this, "LogGroup") .encryptionKey(kmsKey) .build(); // Pass the KMS key in the `encryptionKey` field to associate the key to the S3 bucket Bucket execBucket = Bucket.Builder.create(this, "EcsExecBucket") .encryptionKey(kmsKey) .build(); Cluster cluster = Cluster.Builder.create(this, "Cluster") .vpc(vpc) .executeCommandConfiguration(ExecuteCommandConfiguration.builder() .kmsKey(kmsKey) .logConfiguration(ExecuteCommandLogConfiguration.builder() .cloudWatchLogGroup(logGroup) .cloudWatchEncryptionEnabled(true) .s3Bucket(execBucket) .s3EncryptionEnabled(true) .s3KeyPrefix("exec-command-output") .build()) .logging(ExecuteCommandLogging.OVERRIDE) .build()) .build();