aws-cdk-lib.aws_ecs.TaskDefinitionProps

TaskDefinitionProps Struct

The properties for task definitions.

TaskDefinitionProps

extends

• CommonTaskDefinitionProps

used as props by

• TaskDefinition

Source

aws-ecs/lib/base/task-definition.ts

Type last changed

v2.178.0 · 6 Feb 2025

Example

const vpc = ec2.Vpc.fromLookup(this, 'Vpc', {
  isDefault: true,
});

const cluster = new ecs.Cluster(this, 'FargateCluster', { vpc });

const taskDefinition = new ecs.TaskDefinition(this, 'TD', {
  memoryMiB: '512',
  cpu: '256',
  compatibility: ecs.Compatibility.FARGATE,
});

// Use custom() option - specify custom capacity provider strategy
const runTaskWithCustom = new tasks.EcsRunTask(this, 'RunTaskWithCustom', {
  cluster,
  taskDefinition,
  launchTarget: new tasks.EcsFargateLaunchTarget({
    platformVersion: ecs.FargatePlatformVersion.VERSION1_4,
    capacityProviderOptions: tasks.CapacityProviderOptions.custom([
      { capacityProvider: 'FARGATE_SPOT', weight: 2, base: 1 },
      { capacityProvider: 'FARGATE', weight: 1 },
    ]),
  }),
});

// Use default() option - uses cluster's default capacity provider strategy
const runTaskWithDefault = new tasks.EcsRunTask(this, 'RunTaskWithDefault', {
  cluster,
  taskDefinition,
  launchTarget: new tasks.EcsFargateLaunchTarget({
    platformVersion: ecs.FargatePlatformVersion.VERSION1_4,
    capacityProviderOptions: tasks.CapacityProviderOptions.default(),
  }),
});

vpc = ec2.Vpc.from_lookup(self, "Vpc",
    is_default=True
)

cluster = ecs.Cluster(self, "FargateCluster", vpc=vpc)

task_definition = ecs.TaskDefinition(self, "TD",
    memory_mi_b="512",
    cpu="256",
    compatibility=ecs.Compatibility.FARGATE
)

# Use custom() option - specify custom capacity provider strategy
run_task_with_custom = tasks.EcsRunTask(self, "RunTaskWithCustom",
    cluster=cluster,
    task_definition=task_definition,
    launch_target=tasks.EcsFargateLaunchTarget(
        platform_version=ecs.FargatePlatformVersion.VERSION1_4,
        capacity_provider_options=tasks.CapacityProviderOptions.custom([capacity_provider="FARGATE_SPOT", weight=2, base=1, capacity_provider="FARGATE", weight=1
        ])
    )
)

# Use default() option - uses cluster's default capacity provider strategy
run_task_with_default = tasks.EcsRunTask(self, "RunTaskWithDefault",
    cluster=cluster,
    task_definition=task_definition,
    launch_target=tasks.EcsFargateLaunchTarget(
        platform_version=ecs.FargatePlatformVersion.VERSION1_4,
        capacity_provider_options=tasks.CapacityProviderOptions.default()
    )
)

IVpc vpc = Vpc.fromLookup(this, "Vpc", VpcLookupOptions.builder()
        .isDefault(true)
        .build());

Cluster cluster = Cluster.Builder.create(this, "FargateCluster").vpc(vpc).build();

TaskDefinition taskDefinition = TaskDefinition.Builder.create(this, "TD")
        .memoryMiB("512")
        .cpu("256")
        .compatibility(Compatibility.FARGATE)
        .build();

// Use custom() option - specify custom capacity provider strategy
EcsRunTask runTaskWithCustom = EcsRunTask.Builder.create(this, "RunTaskWithCustom")
        .cluster(cluster)
        .taskDefinition(taskDefinition)
        .launchTarget(EcsFargateLaunchTarget.Builder.create()
                .platformVersion(FargatePlatformVersion.VERSION1_4)
                .capacityProviderOptions(CapacityProviderOptions.custom(List.of(CapacityProviderStrategy.builder().capacityProvider("FARGATE_SPOT").weight(2).base(1).build(), CapacityProviderStrategy.builder().capacityProvider("FARGATE").weight(1).build())))
                .build())
        .build();

// Use default() option - uses cluster's default capacity provider strategy
EcsRunTask runTaskWithDefault = EcsRunTask.Builder.create(this, "RunTaskWithDefault")
        .cluster(cluster)
        .taskDefinition(taskDefinition)
        .launchTarget(EcsFargateLaunchTarget.Builder.create()
                .platformVersion(FargatePlatformVersion.VERSION1_4)
                .capacityProviderOptions(CapacityProviderOptions.default())
                .build())
        .build();

// Install: dotnet add package Amazon.CDK.Lib
var vpc = Vpc.FromLookup(this, "Vpc", new VpcLookupOptions {
    IsDefault = true
});

var cluster = new Cluster(this, "FargateCluster", new ClusterProps { Vpc = vpc });

var taskDefinition = new TaskDefinition(this, "TD", new TaskDefinitionProps {
    MemoryMiB = "512",
    Cpu = "256",
    Compatibility = Compatibility.FARGATE
});

// Use custom() option - specify custom capacity provider strategy
var runTaskWithCustom = new EcsRunTask(this, "RunTaskWithCustom", new EcsRunTaskProps {
    Cluster = cluster,
    TaskDefinition = taskDefinition,
    LaunchTarget = new EcsFargateLaunchTarget(new EcsFargateLaunchTargetOptions {
        PlatformVersion = FargatePlatformVersion.VERSION1_4,
        CapacityProviderOptions = CapacityProviderOptions.Custom(new [] { new CapacityProviderStrategy { CapacityProvider = "FARGATE_SPOT", Weight = 2, Base = 1 }, new CapacityProviderStrategy { CapacityProvider = "FARGATE", Weight = 1 } })
    })
});

// Use default() option - uses cluster's default capacity provider strategy
var runTaskWithDefault = new EcsRunTask(this, "RunTaskWithDefault", new EcsRunTaskProps {
    Cluster = cluster,
    TaskDefinition = taskDefinition,
    LaunchTarget = new EcsFargateLaunchTarget(new EcsFargateLaunchTargetOptions {
        PlatformVersion = FargatePlatformVersion.VERSION1_4,
        CapacityProviderOptions = CapacityProviderOptions.Default()
    })
});

// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
vpc := ec2.Vpc_FromLookup(this, jsii.String("Vpc"), &VpcLookupOptions{
	IsDefault: jsii.Boolean(true),
})

cluster := ecs.NewCluster(this, jsii.String("FargateCluster"), &ClusterProps{
	Vpc: Vpc,
})

taskDefinition := ecs.NewTaskDefinition(this, jsii.String("TD"), &TaskDefinitionProps{
	MemoryMiB: jsii.String("512"),
	Cpu: jsii.String("256"),
	Compatibility: ecs.Compatibility_FARGATE,
})

// Use custom() option - specify custom capacity provider strategy
runTaskWithCustom := tasks.NewEcsRunTask(this, jsii.String("RunTaskWithCustom"), &EcsRunTaskProps{
	Cluster: Cluster,
	TaskDefinition: TaskDefinition,
	LaunchTarget: tasks.NewEcsFargateLaunchTarget(&EcsFargateLaunchTargetOptions{
		PlatformVersion: ecs.FargatePlatformVersion_VERSION1_4,
		CapacityProviderOptions: tasks.CapacityProviderOptions_Custom([]CapacityProviderStrategy{
			&CapacityProviderStrategy{
				CapacityProvider: jsii.String("FARGATE_SPOT"),
				Weight: jsii.Number(2),
				Base: jsii.Number(1),
			},
			&CapacityProviderStrategy{
				CapacityProvider: jsii.String("FARGATE"),
				Weight: jsii.Number(1),
			},
		}),
	}),
})

// Use default() option - uses cluster's default capacity provider strategy
runTaskWithDefault := tasks.NewEcsRunTask(this, jsii.String("RunTaskWithDefault"), &EcsRunTaskProps{
	Cluster: Cluster,
	TaskDefinition: TaskDefinition,
	LaunchTarget: tasks.NewEcsFargateLaunchTarget(&EcsFargateLaunchTargetOptions{
		PlatformVersion: ecs.FargatePlatformVersion_VERSION1_4,
		CapacityProviderOptions: tasks.CapacityProviderOptions_Default(),
	}),
})

Properties

compatibilityCompatibilitycompatibilityCompatibilitycompatibilityCompatibilityCompatibilityCompatibilityCompatibilityCompatibilityrequired#

The task launch type compatibility requirement.

cpu?optionalstringcpu?optionalstrcpu?optionalStringCpu?optionalstringCpu?optional*string#

The number of cpu units used by the task.

Default: CPU units are not specified.

notes

If you are using the EC2 launch type, this field is optional and any value can be used. If you are using the Fargate launch type, this field is required and you must use one of the following values, which determines your range of valid values for the memory parameter:

256 (.25 vCPU) - Available memory values: 512 (0.5 GB), 1024 (1 GB), 2048 (2 GB)

512 (.5 vCPU) - Available memory values: 1024 (1 GB), 2048 (2 GB), 3072 (3 GB), 4096 (4 GB)

1024 (1 vCPU) - Available memory values: 2048 (2 GB), 3072 (3 GB), 4096 (4 GB), 5120 (5 GB), 6144 (6 GB), 7168 (7 GB), 8192 (8 GB)

2048 (2 vCPU) - Available memory values: Between 4096 (4 GB) and 16384 (16 GB) in increments of 1024 (1 GB)

4096 (4 vCPU) - Available memory values: Between 8192 (8 GB) and 30720 (30 GB) in increments of 1024 (1 GB)

8192 (8 vCPU) - Available memory values: Between 16384 (16 GB) and 61440 (60 GB) in increments of 4096 (4 GB)

16384 (16 vCPU) - Available memory values: Between 32768 (32 GB) and 122880 (120 GB) in increments of 8192 (8 GB)

enableFaultInjection?optionalbooleanenable_fault_injection?optionalboolenableFaultInjection?optionalBooleanEnableFaultInjection?optionalboolEnableFaultInjection?optional*bool#

Enables fault injection and allows for fault injection requests to be accepted from the task's containers.

Default: undefined - ECS default setting is false

Fault injection only works with tasks using the {@link NetworkMode.AWS_VPC} or {@link NetworkMode.HOST} network modes.

ephemeralStorageGiB?optionalnumberephemeral_storage_gi_b?optionalint | floatephemeralStorageGiB?optionalNumberEphemeralStorageGiB?optionaldoubleEphemeralStorageGiB?optional*float64#

The amount (in GiB) of ephemeral storage to be allocated to the task.

Default: Undefined, in which case, the task will receive 20GiB ephemeral storage.

Only supported in Fargate platform version 1.4.0 or later for Linux tasks, and platform version 1.0.0 or later for Windows tasks.

executionRole?optionalIRoleexecution_role?optionalIRoleexecutionRole?optionalIRoleExecutionRole?optionalIRoleExecutionRole?optionalIRole#

The name of the IAM task execution role that grants the ECS agent permission to call AWS APIs on your behalf.

Default: An execution role will be automatically created if you use ECR images in your task definition.

The role will be used to retrieve container images from ECR and create CloudWatch log groups.

family?optionalstringfamily?optionalstrfamily?optionalStringFamily?optionalstringFamily?optional*string#

The name of a family that this task definition is registered to.

Default: Automatically generated name.

A family groups multiple versions of a task definition.

inferenceAccelerators?optionalInferenceAccelerator[]inference_accelerators?optionaltyping.List[InferenceAccelerator]inferenceAccelerators?optionalList<InferenceAccelerator>InferenceAccelerators?optionalInferenceAccelerator[]InferenceAccelerators?optional*[]InferenceAcceleratordeprecated#

ECS TaskDefinition's inferenceAccelerator is EOL since April 2024

Default: No inference accelerators.

Not supported in Fargate.

ipcMode?optionalIpcModeipc_mode?optionalIpcModeipcMode?optionalIpcModeIpcMode?optionalIpcModeIpcMode?optionalIpcMode#

The IPC resource namespace to use for the containers in the task.

Default: IpcMode used by the task is not specified

Not supported in Fargate and Windows containers.

memoryMiB?optionalstringmemory_mi_b?optionalstrmemoryMiB?optionalStringMemoryMiB?optionalstringMemoryMiB?optional*string#

The amount (in MiB) of memory used by the task.

Default: Memory used by task is not specified.

notes

If using the EC2 launch type, this field is optional and any value can be used. If using the Fargate launch type, this field is required and you must use one of the following values, which determines your range of valid values for the cpu parameter:

512 (0.5 GB), 1024 (1 GB), 2048 (2 GB) - Available cpu values: 256 (.25 vCPU)

1024 (1 GB), 2048 (2 GB), 3072 (3 GB), 4096 (4 GB) - Available cpu values: 512 (.5 vCPU)

2048 (2 GB), 3072 (3 GB), 4096 (4 GB), 5120 (5 GB), 6144 (6 GB), 7168 (7 GB), 8192 (8 GB) - Available cpu values: 1024 (1 vCPU)

Between 4096 (4 GB) and 16384 (16 GB) in increments of 1024 (1 GB) - Available cpu values: 2048 (2 vCPU)

Between 8192 (8 GB) and 30720 (30 GB) in increments of 1024 (1 GB) - Available cpu values: 4096 (4 vCPU)

Between 16384 (16 GB) and 61440 (60 GB) in increments of 4096 (4 GB) - Available cpu values: 8192 (8 vCPU)

Between 32768 (32 GB) and 122880 (120 GB) in increments of 8192 (8 GB) - Available cpu values: 16384 (16 vCPU)

networkMode?optionalNetworkModenetwork_mode?optionalNetworkModenetworkMode?optionalNetworkModeNetworkMode?optionalNetworkModeNetworkMode?optionalNetworkMode#

The networking mode to use for the containers in the task.

Default: NetworkMode.Bridge for EC2 & External tasks, AwsVpc for Fargate tasks.

On Fargate, the only supported networking mode is AwsVpc.

pidMode?optionalPidModepid_mode?optionalPidModepidMode?optionalPidModePidMode?optionalPidModePidMode?optionalPidMode#

The process namespace to use for the containers in the task.

Default: PidMode used by the task is not specified

notes

Only supported for tasks that are hosted on AWS Fargate if the tasks are using platform version 1.4.0 or later (Linux). Only the TASK option is supported for Linux-based Fargate containers. Not supported in Windows containers. If pidMode is specified for a Fargate task, then runtimePlatform.operatingSystemFamily must also be specified. For more information, see Task Definition Parameters.

placementConstraints?optionalPlacementConstraint[]placement_constraints?optionaltyping.List[PlacementConstraint]placementConstraints?optionalList<PlacementConstraint>PlacementConstraints?optionalPlacementConstraint[]PlacementConstraints?optional*[]PlacementConstraint#

The placement constraints to use for tasks in the service.

Default: No placement constraints.

You can specify a maximum of 10 constraints per task (this limit includes constraints in the task definition and those specified at run time).

Not supported in Fargate.

proxyConfiguration?optionalProxyConfigurationproxy_configuration?optionalProxyConfigurationproxyConfiguration?optionalProxyConfigurationProxyConfiguration?optionalProxyConfigurationProxyConfiguration?optionalProxyConfiguration#

The configuration details for the App Mesh proxy.

Default: No proxy configuration.

runtimePlatform?optionalRuntimePlatformruntime_platform?optionalRuntimePlatformruntimePlatform?optionalRuntimePlatformRuntimePlatform?optionalRuntimePlatformRuntimePlatform?optionalRuntimePlatform= Undefined.#

The operating system that your task definitions are running on.

A runtimePlatform is supported only for tasks using the Fargate launch type.

taskRole?optionalIRoletask_role?optionalIRoletaskRole?optionalIRoleTaskRole?optionalIRoleTaskRole?optionalIRole#

The name of the IAM role that grants containers in the task permission to call AWS APIs on your behalf.

Default: A task role is automatically created for you.

volumes?optionalVolume[]volumes?optionaltyping.List[Volume]volumes?optionalList<Volume>Volumes?optionalVolume[]Volumes?optional*[]Volume#

The list of volume definitions for the task.

Default: No volumes are passed to the Docker daemon on a container instance.

For more information, see Task Definition Parameter Volumes.