Package software.amazon.awscdk.services.ecs

Class TaskDefinition

java.lang.Object
software.amazon.jsii.JsiiObject
software.constructs.Construct
software.amazon.awscdk.Resource
software.amazon.awscdk.services.ecs.TaskDefinition
All Implemented Interfaces:
IResource, ITaskDefinition, software.amazon.jsii.JsiiSerializable, software.constructs.IConstruct, software.constructs.IDependable
Direct Known Subclasses:
Ec2TaskDefinition, ExternalTaskDefinition, FargateTaskDefinition
@Generated(value="jsii-pacmak/1.116.0 (build 0eddcff)", date="2025-10-29T11:15:39.283Z") @Stability(Stable) public class TaskDefinition extends Resource implements ITaskDefinition
The base class for all task definitions.

Example: 

 import software.amazon.awscdk.services.cloudwatch.*;
 Cluster cluster;
 TaskDefinition taskDefinition;
 Alarm elbAlarm;
 FargateService service = FargateService.Builder.create(this, "Service")
         .cluster(cluster)
         .taskDefinition(taskDefinition)
         .minHealthyPercent(100)
         .deploymentAlarms(DeploymentAlarmConfig.builder()
                 .alarmNames(List.of(elbAlarm.getAlarmName()))
                 .behavior(AlarmBehavior.ROLLBACK_ON_ALARM)
                 .build())
         .build();
 // Defining a deployment alarm after the service has been created
 String cpuAlarmName = "MyCpuMetricAlarm";
 Alarm.Builder.create(this, "CPUAlarm")
         .alarmName(cpuAlarmName)
         .metric(service.metricCpuUtilization())
         .evaluationPeriods(2)
         .threshold(80)
         .build();
 service.enableDeploymentAlarms(List.of(cpuAlarmName), DeploymentAlarmOptions.builder()
         .behavior(AlarmBehavior.FAIL_ON_ALARM)
         .build());

  • Field Details

    • PROPERTY_INJECTION_ID

      @Stability(Stable) public static final String PROPERTY_INJECTION_ID
      Uniquely identifies this class.

  • Constructor Details

    • TaskDefinition

      protected TaskDefinition(software.amazon.jsii.JsiiObjectRef objRef)

    • TaskDefinition

      protected TaskDefinition(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)

    • TaskDefinition

      @Stability(Stable) public TaskDefinition(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull TaskDefinitionProps props)
      Constructs a new instance of the TaskDefinition class.

      Parameters:
      scope - This parameter is required.
      id - This parameter is required.
      props - This parameter is required.

  • Method Details

    • fromTaskDefinitionArn

      @Stability(Stable) @NotNull public static ITaskDefinition fromTaskDefinitionArn(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String taskDefinitionArn)
      Imports a task definition from the specified task definition ARN.

      The task will have a compatibility of EC2+Fargate.

      Parameters:
      scope - This parameter is required.
      id - This parameter is required.
      taskDefinitionArn - This parameter is required.

    • fromTaskDefinitionAttributes

      @Stability(Stable) @NotNull public static ITaskDefinition fromTaskDefinitionAttributes(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull TaskDefinitionAttributes attrs)
      Create a task definition from a task definition reference.

      Parameters:
      scope - This parameter is required.
      id - This parameter is required.
      attrs - This parameter is required.

    • addContainer

      @Stability(Stable) @NotNull public ContainerDefinition addContainer(@NotNull String id, @NotNull ContainerDefinitionOptions props)
      Adds a new container to the task definition.

      Parameters:
      id - This parameter is required.
      props - This parameter is required.

    • addExtension

      @Stability(Stable) public void addExtension(@NotNull ITaskDefinitionExtension extension)
      Adds the specified extension to the task definition.

      Extension can be used to apply a packaged modification to a task definition.

      Parameters:
      extension - This parameter is required.

    • addFirelensLogRouter

      @Stability(Stable) @NotNull public FirelensLogRouter addFirelensLogRouter(@NotNull String id, @NotNull FirelensLogRouterDefinitionOptions props)
      Adds a firelens log router to the task definition.

      Parameters:
      id - This parameter is required.
      props - This parameter is required.

    • addInferenceAccelerator

      @Stability(Deprecated) @Deprecated public void addInferenceAccelerator(@NotNull InferenceAccelerator inferenceAccelerator)
      Deprecated.
      ECS TaskDefinition's inferenceAccelerator is EOL since April 2024
      (deprecated) Adds an inference accelerator to the task definition.

      Parameters:
      inferenceAccelerator - This parameter is required.

    • addPlacementConstraint

      @Stability(Stable) public void addPlacementConstraint(@NotNull PlacementConstraint constraint)
      Adds the specified placement constraint to the task definition.

      Parameters:
      constraint - This parameter is required.

    • addToExecutionRolePolicy

      @Stability(Stable) public void addToExecutionRolePolicy(@NotNull PolicyStatement statement)
      Adds a policy statement to the task execution IAM role.

      Parameters:
      statement - This parameter is required.

    • addToTaskRolePolicy

      @Stability(Stable) public void addToTaskRolePolicy(@NotNull PolicyStatement statement)
      Adds a policy statement to the task IAM role.

      Parameters:
      statement - This parameter is required.

    • addVolume

      @Stability(Stable) public void addVolume(@NotNull Volume volume)
      Adds a volume to the task definition.

      Parameters:
      volume - This parameter is required.

    • findContainer

      @Stability(Stable) @Nullable public ContainerDefinition findContainer(@NotNull String containerName)
      Returns the container that match the provided containerName.

      Parameters:
      containerName - This parameter is required.

    • findPortMappingByName

      @Stability(Stable) @Nullable public PortMapping findPortMappingByName(@NotNull String name)
      Determine the existing port mapping for the provided name.

      Parameters:
      name - : port mapping name. This parameter is required.
      Returns:
      PortMapping for the provided name, if it exists.

    • grantRun

      @Stability(Stable) @NotNull public Grant grantRun(@NotNull IGrantable grantee)
      Grants permissions to run this task definition.

      This will grant the following permissions:

      • ecs:RunTask
      • iam:PassRole

      Parameters:
      grantee - Principal to grant consume rights to. This parameter is required.

    • obtainExecutionRole

      @Stability(Stable) @NotNull public IRole obtainExecutionRole()
      Creates the task execution IAM role if it doesn't already exist.

    • getCompatibility

      @Stability(Stable) @NotNull public Compatibility getCompatibility()
      The task launch type compatibility requirement.
      Specified by:
      getCompatibility in interface ITaskDefinition

    • getContainers

      @Stability(Stable) @NotNull protected List<ContainerDefinition> getContainers()
      The container definitions.

    • getFamily

      @Stability(Stable) @NotNull public String getFamily()
      The name of a family that this task definition is registered to.

      A family groups multiple versions of a task definition.

    • getInferenceAccelerators

      @Stability(Stable) @NotNull public List<InferenceAccelerator> getInferenceAccelerators()
      Public getter method to access list of inference accelerators attached to the instance.

    • getIsEc2Compatible

      @Stability(Stable) @NotNull public Boolean getIsEc2Compatible()
      Return true if the task definition can be run on an EC2 cluster.
      Specified by:
      getIsEc2Compatible in interface ITaskDefinition

    • getIsExternalCompatible

      @Stability(Stable) @NotNull public Boolean getIsExternalCompatible()
      Return true if the task definition can be run on a ECS anywhere cluster.
      Specified by:
      getIsExternalCompatible in interface ITaskDefinition

    • getIsFargateCompatible

      @Stability(Stable) @NotNull public Boolean getIsFargateCompatible()
      Return true if the task definition can be run on a Fargate cluster.
      Specified by:
      getIsFargateCompatible in interface ITaskDefinition

    • getIsManagedInstancesCompatible

      @Stability(Stable) @NotNull public Boolean getIsManagedInstancesCompatible()
      Return true if the task definition can be run on Managed Instances.
      Specified by:
      getIsManagedInstancesCompatible in interface ITaskDefinition

    • getNetworkMode

      @Stability(Stable) @NotNull public NetworkMode getNetworkMode()
      The networking mode to use for the containers in the task.
      Specified by:
      getNetworkMode in interface ITaskDefinition

    • getTaskDefinitionArn

      @Stability(Stable) @NotNull public String getTaskDefinitionArn()
      The full Amazon Resource Name (ARN) of the task definition.
      Specified by:
      getTaskDefinitionArn in interface ITaskDefinition

    • getTaskRole

      @Stability(Stable) @NotNull public IRole getTaskRole()
      The name of the IAM role that grants containers in the task permission to call AWS APIs on your behalf.
      Specified by:
      getTaskRole in interface ITaskDefinition

    • getEphemeralStorageGiB

      @Stability(Stable) @Nullable public Number getEphemeralStorageGiB()
      The amount (in GiB) of ephemeral storage to be allocated to the task.

      Only supported in Fargate platform version 1.4.0 or later.

    • getExecutionRole

      @Stability(Stable) @Nullable public IRole getExecutionRole()
      Execution role for this task definition.
      Specified by:
      getExecutionRole in interface ITaskDefinition

    • getPidMode

      @Stability(Stable) @Nullable public PidMode getPidMode()
      The process namespace to use for the containers in the task.

      Only supported for tasks that are hosted on AWS Fargate if the tasks are using platform version 1.4.0 or later (Linux). 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.

    • getReferencesSecretJsonField

      @Stability(Stable) @Nullable public Boolean getReferencesSecretJsonField()
      Whether this task definition has at least a container that references a specific JSON field of a secret stored in Secrets Manager.

    • getDefaultContainer

      @Stability(Stable) @Nullable public ContainerDefinition getDefaultContainer()
      Default container for this task.

      Load balancers will send traffic to this container. The first essential container that is added to this task will become the default container.

    • setDefaultContainer

      @Stability(Stable) public void setDefaultContainer(@Nullable ContainerDefinition value)
      Default container for this task.

      Load balancers will send traffic to this container. The first essential container that is added to this task will become the default container.